hippo-memory 1.57.0 → 1.58.0

package/dist/project-briefs.js

@@ -21,6 +21,7 @@
  * Lifecycle: active -> superseded (a newer version replaces it) or active ->
  * closed (retired).
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -56,21 +57,21 @@ export const MAX_RECEIPT_HEADLINE_LEN = 200;
 function validateBriefFields(repo, summary, changeSummary) {
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0)
-        throw new Error('saveProjectBrief: repo is required');
+        throw new BadRequestError('saveProjectBrief: repo is required');
     if (/[\r\n]/.test(normalizedRepo)) {
-        throw new Error('saveProjectBrief: repo must be a single line (no newlines)');
+        throw new BadRequestError('saveProjectBrief: repo must be a single line (no newlines)');
     }
     if (normalizedRepo.length > MAX_REPO_LEN) {
-        throw new Error(`saveProjectBrief: repo exceeds the ${MAX_REPO_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: repo exceeds the ${MAX_REPO_LEN}-char cap`);
     }
     if (!summary || summary.trim().length === 0) {
-        throw new Error('saveProjectBrief: summary is required');
+        throw new BadRequestError('saveProjectBrief: summary is required');
     }
     if (summary.length > MAX_BRIEF_SUMMARY_LEN) {
-        throw new Error(`saveProjectBrief: summary exceeds the ${MAX_BRIEF_SUMMARY_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: summary exceeds the ${MAX_BRIEF_SUMMARY_LEN}-char cap`);
     }
     if (changeSummary !== undefined && changeSummary.length > MAX_CHANGE_SUMMARY_LEN) {
-        throw new Error(`saveProjectBrief: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`);
+        throw new BadRequestError(`saveProjectBrief: changeSummary exceeds the ${MAX_CHANGE_SUMMARY_LEN}-char cap`);
     }
     return { repo: normalizedRepo };
 }
@@ -145,10 +146,10 @@ export function saveProjectBrief(hippoRoot, tenantId, opts, actor = 'cli') {
                 // shape for the matching row, or undefined when no brief/tenant pair matches.
                 const pred = db.prepare(`SELECT status, version FROM project_briefs WHERE id = ? AND tenant_id = ?`).get(opts.supersedesBriefId, tenantId);
                 if (!pred) {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveProjectBrief: brief ${opts.supersedesBriefId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} is not active (status='${pred.status}'); only active briefs can be superseded.`);
+                    throw new ConflictError(`saveProjectBrief: brief ${opts.supersedesBriefId} is not active (status='${pred.status}'); only active briefs can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -166,7 +167,7 @@ export function saveProjectBrief(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(briefId, now, opts.supersedesBriefId, tenantId, briefId);
                 if (sup.changes === 0) {
-                    throw new Error(`saveProjectBrief: brief ${opts.supersedesBriefId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`saveProjectBrief: brief ${opts.supersedesBriefId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -234,9 +235,9 @@ export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
                 // shape, or undefined when the id/tenant pair doesn't exist.
                 const existing = db.prepare(`SELECT status FROM project_briefs WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeProjectBrief: brief ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeProjectBrief: brief ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeProjectBrief: brief ${id} is not active (status='${existing.status}'); only active briefs can be closed.`);
+                throw new ConflictError(`closeProjectBrief: brief ${id} is not active (status='${existing.status}'); only active briefs can be closed.`);
             }
             // SAFETY: SELECT ${BRIEF_COLS} projects exactly the ProjectBriefRow
             // columns; .get() returns that row for the just-updated id, or undefined
@@ -244,7 +245,7 @@ export function closeProjectBrief(hippoRoot, tenantId, id, actor = 'cli') {
             const row = db.prepare(`SELECT ${BRIEF_COLS} FROM project_briefs WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeProjectBrief: brief ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeProjectBrief: brief ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -298,7 +299,7 @@ export function loadProjectBriefs(hippoRoot, tenantId, opts = {}) {
     assertTenantId('loadProjectBriefs', tenantId);
     const limit = opts.limit ?? 100;
     if (opts.status && !VALID_BRIEF_STATES.has(opts.status)) {
-        throw new Error(`loadProjectBriefs: status must be one of ${Array.from(VALID_BRIEF_STATES).join('|')}; got ${opts.status}`);
+        throw new BadRequestError(`loadProjectBriefs: status must be one of ${Array.from(VALID_BRIEF_STATES).join('|')}; got ${opts.status}`);
     }
     const db = openHippoDb(hippoRoot);
     try {
@@ -385,7 +386,7 @@ export function assembleBriefFromReceipts(hippoRoot, tenantId, repo) {
     assertTenantId('assembleBriefFromReceipts', tenantId);
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0) {
-        throw new Error('assembleBriefFromReceipts: repo is required');
+        throw new BadRequestError('assembleBriefFromReceipts: repo is required');
     }
     const tag = `path:${normalizedRepo.toLowerCase()}`;
     const likeParam = `%"${escapeLike(tag)}"%`;
@@ -478,7 +479,7 @@ export function refreshBrief(hippoRoot, tenantId, repo, actor = 'cli') {
     assertTenantId('refreshBrief', tenantId);
     const normalizedRepo = (repo ?? '').trim();
     if (normalizedRepo.length === 0)
-        throw new Error('refreshBrief: repo is required');
+        throw new BadRequestError('refreshBrief: repo is required');
     const { markdown, receiptCount } = assembleBriefFromReceipts(hippoRoot, tenantId, normalizedRepo);
     const active = loadActiveBriefForRepo(hippoRoot, tenantId, normalizedRepo);
     return saveProjectBrief(hippoRoot, tenantId, {

package/dist/project-identity.d.ts

@@ -19,7 +19,7 @@
 export interface ProjectIdentity {
     /** Realpath-resolved root directory of the project (the start dir when not in a project). */
     root: string;
-    /** Lowercased basename of the project root; empty string when not in a project. */
+    /** Lowercased basename of the project root, or of its repo for a linked worktree with no `.hippo` (a store keeps the name its rows carry); '' outside a project. */
     name: string;
     /** True when the directory resolves to the user home working set. */
     isHome: boolean;

package/dist/project-identity.js

@@ -66,7 +66,8 @@ export function resolveProjectIdentity(cwd, opts) {
     let identity;
     const root = hippoRoot ?? gitRoot;
     if (root !== null) {
-        identity = { root, name: path.basename(root).toLowerCase(), isHome: false };
+        const name = (hippoRoot === null ? linkedWorktreeRepoName(root, home) : null) ?? path.basename(root).toLowerCase();
+        identity = { root, name, isHome: false };
     }
     else if (reachedHome || isUnder(start, home)) {
         identity = { root: home, name: '', isHome: true };
@@ -80,6 +81,29 @@ export function resolveProjectIdentity(cwd, opts) {
         identityCache.set(startInput, identity);
     return identity;
 }
+/** The repo name a linked worktree shares with its main checkout (`repo.git` or `repo/.bare` for a bare repo), so one repo is one project; null for any other checkout. */
+function linkedWorktreeRepoName(gitRoot, home) {
+    const marker = path.join(gitRoot, '.git');
+    if (!fs.existsSync(marker) || isDirectoryAt(marker))
+        return null;
+    try {
+        const gitDir = /^gitdir:\s*(.+)$/m.exec(fs.readFileSync(marker, 'utf8'))?.[1]?.trim();
+        if (!gitDir)
+            return null;
+        const linkDir = path.resolve(gitRoot, gitDir);
+        const commondir = path.join(linkDir, 'commondir');
+        if (!fs.existsSync(commondir))
+            return null; // a submodule's or a separate git dir's own checkout
+        const common = realpathOrResolve(path.resolve(linkDir, fs.readFileSync(commondir, 'utf8').trim()));
+        const repo = ['.git', '.bare'].includes(path.basename(common)) ? path.dirname(common) : common;
+        if (samePath(repo, home))
+            return null; // a dotfiles repo at home must not make its worktrees user-global
+        return path.basename(repo).replace(/\.git$/i, '').toLowerCase() || null;
+    }
+    catch {
+        return null; // an unreadable link is still a checkout, named after its own folder
+    }
+}
 /** Climb from start toward the root; home (never a project) and every stop dir end the walk unchecked. */
 function walkProjectMarkers(start, home, stopDirs) {
     let hippoRoot = null;

package/dist/raw-archive.js

@@ -1,5 +1,6 @@
+import { BadRequestError, NotFoundError } from './api-errors.js';
 import { isFtsAvailable } from './db.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { markSummaryDirtyInTx } from './store.js';
 export function archiveRawMemory(db, id, opts) {
     // SAFETY: SELECT * FROM memories returns every column of the memories table; only
@@ -7,9 +8,9 @@ export function archiveRawMemory(db, id, opts) {
     // null) by the memories schema.
     const row = db.prepare(`SELECT * FROM memories WHERE id = ?`).get(id);
     if (!row)
-        throw new Error(`memory not found: ${id}`);
+        throw new NotFoundError(`memory not found: ${id}`);
     if (row.kind !== 'raw') {
-        throw new Error(`memory ${id} is not raw (kind=${String(row.kind)})`);
+        throw new BadRequestError(`memory ${id} is not raw (kind=${String(row.kind)})`);
     }
     // SAVEPOINT (not BEGIN) so this works whether or not we're already inside a
     // transaction. SQLite refuses BEGIN within a transaction; SAVEPOINT nests safely.
@@ -58,9 +59,9 @@ export function archiveRawMemory(db, id, opts) {
                 metadata: { reason: opts.reason },
             });
         }
-        catch {
-            // Audit must not crash the archive. Failures here mean the audit table
-            // is unwritable; the archive itself has already succeeded.
+        catch (error) {
+            // The archive itself has already succeeded; an unwritable audit table must not undo it.
+            reportAuditWriteFailure('archive_raw', String(error), id);
         }
         // v0.30 / E2 — DAG live-coupling: archive of a child under a level-2
         // summary marks parent dirty. Inside the SAVEPOINT so the dirty-mark

package/dist/recall-scope.d.ts

@@ -6,6 +6,7 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+import { ForbiddenError } from './api-errors.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
@@ -83,7 +84,7 @@ export declare function passesCliRecallScopeFilter(scope: string | null, request
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export declare class ScopeForbiddenError extends Error {
+export declare class ScopeForbiddenError extends ForbiddenError {
     readonly scope: string;
     constructor(scope: string);
 }

package/dist/recall-scope.js

@@ -6,6 +6,7 @@
  * these for its own call sites AND re-exports them for back-compat
  * (`api.isPrivateScope`, test imports of `passesScopeFilterForRecall`).
  */
+import { ForbiddenError } from './api-errors.js';
 /**
  * Literal scopes excluded from recall by default-deny when the
  * caller passes no `scope`. The SQL clause in `loadSearchRows` and the JS
@@ -105,7 +106,7 @@ export function passesCliRecallScopeFilter(scope, requested) {
  * Thrown when a caller requests a scope its role may not read. The HTTP layer
  * maps it to 403.
  */
-export class ScopeForbiddenError extends Error {
+export class ScopeForbiddenError extends ForbiddenError {
     scope;
     constructor(scope) {
         super(`scope ${scope} requires admin role`);

package/dist/refine-llm.js

@@ -15,6 +15,7 @@
 import { Layer } from './memory.js';
 import { loadAllEntries, readEntry, writeEntry } from './store.js';
 import { redactSecrets } from './secret-detect.js';
+import { fetchWithRetry, llmTimeoutMs } from './http-retry.js';
 const REFINED_TAG = 'llm-refined';
 const CONSOLIDATED_MARKERS = [
     '[Consolidated from',
@@ -48,7 +49,7 @@ Source memories (up to 8 shown):
 ${sourceBlock}`;
     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',
@@ -60,7 +61,7 @@ ${sourceBlock}`;
                 max_tokens: 800,
                 messages: [{ role: 'user', content: prompt }],
             }),
-        });
+        }, { timeoutMs: llmTimeoutMs(), fetchFn });
     }
     catch {
         return null;

package/dist/reject-flow.js

@@ -12,7 +12,7 @@
  * cli.ts and api.ts, so it introduces no cycle.
  */
 import { closeHippoDb } from './db.js';
-import { appendAuditEvent } from './audit.js';
+import { appendAuditEvent, reportAuditWriteFailure } from './audit.js';
 import { archiveRawMemory } from './raw-archive.js';
 import { deleteDormantRow, listDormantSnapshots, purgeDormantByDigest, replaceDormantEntry } from './dormant.js';
 import { openStore, deleteEntryCore, purgeMirrorBestEffort, selectAllEntries, stampOriginProject, writeEntryDbOnly, writeEntryMirrors, } from './store.js';
@@ -144,12 +144,9 @@ export function rejectValue(opts) {
                     metadata: { digest, removedIds, count: removedIds.length },
                 });
             }
-            catch {
-                // Best-effort — mirrors store.ts's private audit() semantics. This
-                // runs INSIDE the still-open transaction (COMMIT is the next
-                // statement): a swallowed audit failure lets the tombstone +
-                // removals commit without the trail row, rather than rolling the
-                // whole reject back over bookkeeping.
+            catch (error) {
+                // Inside the open transaction: the reject commits without its trail row rather than rolling back over bookkeeping.
+                reportAuditWriteFailure('reject_value', String(error), opts.memoryId);
             }
             db.exec('COMMIT');
         }
@@ -217,8 +214,8 @@ export function unrejectValue(hippoRoot, tenantId, digestOrPrefix, actor) {
                 metadata: { digest: target.digest, reason: target.reason },
             });
         }
-        catch {
-            // Best-effort, same as reject's audit call above.
+        catch (error) {
+            reportAuditWriteFailure('unreject_value', String(error), target.sourceMemoryId);
         }
         return { status: 'ok', digest: target.digest, reason: target.reason };
     }

package/dist/rejection.d.ts

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import type { DatabaseSyncLike } from './db.js';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -33,7 +34,7 @@ export declare function rejectionDigest(content: string): string;
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export declare class RejectedValueError extends Error {
+export declare class RejectedValueError extends BadRequestError {
     readonly digest: string;
     readonly tenantId: string;
     readonly entryId: string;

package/dist/rejection.js

@@ -12,6 +12,7 @@
  * be a cycle.
  */
 import { createHash } from 'node:crypto';
+import { BadRequestError } from './api-errors.js';
 /**
  * Normalize content for rejection-digest comparisons: Unicode NFC →
  * lowercase → collapse whitespace runs to a single space → trim. No
@@ -37,7 +38,7 @@ export function rejectionDigest(content) {
  * blocks (writeEntry, api.supersede) to write a post-rollback
  * `reject_refusal` audit row via `auditRejectionRefusal` (plan §3).
  */
-export class RejectedValueError extends Error {
+export class RejectedValueError extends BadRequestError {
     digest;
     tenantId;
     entryId;

package/dist/search.js

@@ -17,7 +17,13 @@ import { openHippoDb, closeHippoDb } from './db.js';
 import { rrfFuse } from './rrf.js';
 import { graphRankStream, selectGraphSeeds, DEFAULT_GRAPH_SEED_COUNT } from './graph-stream.js';
 import { compareEntryIdentity, compareScoredResults } from './compare.js';
+import { log } from './log.js';
+import { redactSecretsStrict } from './secret-detect.js';
 export const CHURN_STALE_RANK_MULTIPLIER = 0.5; // SHORTCUT: untuned; FE3 measures before any default.
+// Search runs on every hook prompt, so one line per reason per process says why vectors went unused without flooding stderr.
+function warnBm25Fallback(reason, detail) {
+    log.once(`search.bm25-fallback.${reason}`, 'warn', `hybrid search fell back to BM25 only: ${redactSecretsStrict(detail)}`);
+}
 export function churnStaleFactor(entry) {
     return entry.tags.includes(CHURN_STALE_TAG) ? CHURN_STALE_RANK_MULTIPLIER : 1.0;
 }
@@ -267,11 +273,17 @@ export async function hybridSearch(query, entries, options = {}) {
                         embeddingIndex = idx;
                         useEmbeddings = true;
                     }
+                    else {
+                        warnBm25Fallback('empty-query-vector', 'the embedding provider returned no vector for the query');
+                    }
                 }
             }
+            else if (provider.isAvailable()) {
+                warnBm25Fallback('reindex', "the embedding index was built by another model or is being rebuilt; run 'hippo embed'");
+            }
         }
-        catch {
-            // Fall through to BM25-only
+        catch (err) {
+            warnBm25Fallback('error', err instanceof Error ? err.message : String(err));
         }
     }
     // Compute cosine similarities for RRF ranking (need all before scoring)

package/dist/secret-detect.d.ts

@@ -12,7 +12,8 @@
  *    a deliberate act.
  *
  * This is deliberately a thin slice of the A4 lifecycle-compliance item
- * (no write-time scrubbing, no PII detection).
+ * (no PII detection). Write-time scrubbing covers only text no person
+ * typed into hippo; see `vetSecrets`.
  *
  * Leaf module: keep free of imports from store/api/shared so all of them
  * can import it without cycles.
@@ -42,4 +43,15 @@ export declare function redactSecrets(text: string): string;
 export declare function maskEmails(text: string): string;
 /** Stricter redaction for text that leaves the machine: no co-occurrence guard, plus Bearer and Basic auth headers and JWTs. */
 export declare function redactSecretsStrict(text: string): string;
+/** The text a write keeps, plus what to tell its caller about secret material in it. */
+export interface SecretVet {
+    content: string;
+    warnings: string[];
+}
+/** Write-time veto: `scrub` text no person typed gets capture's strict redaction; typed text is a person's own call, so it is kept and flagged. */
+export declare function vetSecrets(content: string, tags: readonly string[], scrub: boolean): SecretVet;
+/** Appended to a dead-letter row's error when `redactPayload` changed its body. */
+export declare const DLQ_REDACTED_NOTE = "secret-shaped text redacted, signature dropped; replay needs --force";
+/** `vetSecrets` redaction for a raw webhook body: JSON stays valid for replay, and an untouched body stays byte-identical so its signature still verifies. */
+export declare function redactPayload(raw: string): string;
 //# sourceMappingURL=secret-detect.d.ts.map

package/dist/secret-detect.js

@@ -12,7 +12,8 @@
  *    a deliberate act.
  *
  * This is deliberately a thin slice of the A4 lifecycle-compliance item
- * (no write-time scrubbing, no PII detection).
+ * (no PII detection). Write-time scrubbing covers only text no person
+ * typed into hippo; see `vetSecrets`.
  *
  * Leaf module: keep free of imports from store/api/shared so all of them
  * can import it without cycles.
@@ -100,6 +101,37 @@ export function maskEmails(text) {
 export function redactSecretsStrict(text) {
     return redactText(text, true);
 }
+/** Write-time veto: `scrub` text no person typed gets capture's strict redaction; typed text is a person's own call, so it is kept and flagged. */
+export function vetSecrets(content, tags, scrub) {
+    const kept = scrub ? redactSecretsStrict(content) : content;
+    const warnings = [];
+    if (kept !== content) {
+        const found = detectSecret({ content, tags: [] }).reason;
+        warnings.push(`secret-shaped text was redacted before storing${found ? ` (${found})` : ''}`);
+    }
+    const left = detectSecret({ content: kept, tags: [...tags] });
+    if (left.flagged) {
+        warnings.push(`content looks like a secret (${left.reason}) and was stored as sent; forget it if it should not be kept`);
+    }
+    return { content: kept, warnings };
+}
+const JSON_STRING = /"(?:[^"\\]|\\.)*"/g;
+/** Appended to a dead-letter row's error when `redactPayload` changed its body. */
+export const DLQ_REDACTED_NOTE = 'secret-shaped text redacted, signature dropped; replay needs --force';
+/** `vetSecrets` redaction for a raw webhook body: JSON stays valid for replay, and an untouched body stays byte-identical so its signature still verifies. */
+export function redactPayload(raw) {
+    try {
+        JSON.parse(raw);
+    }
+    catch {
+        return redactSecretsStrict(raw);
+    }
+    return raw.replace(JSON_STRING, (literal) => {
+        const text = JSON.parse(literal);
+        const kept = redactSecretsStrict(text);
+        return kept === text ? literal : JSON.stringify(kept);
+    });
+}
 function redactText(text, strict) {
     if (!text)
         return text;

package/dist/server.d.ts

@@ -66,7 +66,9 @@ export declare function clientIpForRateLimit(req: IncomingMessage): string;
  * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing
  * secrets and 404 when those secrets are unset. But the loopback
  * no-auth fallback inside buildContextWithAuth still admits unauthenticated
- * requests from a loopback remote address, so binding to a non-loopback host
+ * requests from a loopback remote address (unless they carry Forwarded,
+ * X-Forwarded-For/-Host/-Proto, X-Real-IP, Cf-Connecting-Ip or True-Client-Ip, which mark a same-host proxy and get
+ * a 401 like any keyless remote request), so binding to a non-loopback host
  * is only safe once that fallback is disabled with HIPPO_REQUIRE_AUTH=1,
  * which forces every request (loopback or not) through Bearer-token
  * validation. Without that env var set, a non-loopback bind would expose the