hippo-memory 1.57.0 → 1.59.0

package/dist/pilot-arm.d.ts

@@ -0,0 +1,9 @@
+import { type DatabaseSyncLike } from './db.js';
+export type PilotArm = 'hippo' | 'holdout';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export declare function hashArm(sessionId: string, rateBp: number): PilotArm;
+/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
+export declare function readPilotArm(db: DatabaseSyncLike, sessionId: string): PilotArm | null;
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+export declare function ensurePilotArm(db: DatabaseSyncLike, tenantId: string, sessionId: string, rateBp: number, now?: string): PilotArm;
+//# sourceMappingURL=pilot-arm.d.ts.map

package/dist/pilot-arm.js

@@ -0,0 +1,47 @@
+// Pilot arm: one token_ledger row per session names its arm, `hippo` or `holdout`, so a pilot can compare them.
+// `items` holds the holdout rate in basis points; readers outside this repo depend on these rows, so their shape is fixed.
+import { createHash } from 'node:crypto';
+import { execWithBusyRetry, HOOK_DB_WAIT_MS } from './db.js';
+import { recordTokenUse } from './token-ledger.js';
+/** Deterministic split: the same session and rate always land in the same arm. */
+export function hashArm(sessionId, rateBp) {
+    const bucket = parseInt(createHash('sha256').update(sessionId).digest('hex').slice(0, 8), 16) % 10000;
+    return bucket < rateBp ? 'holdout' : 'hippo';
+}
+/** The session's first stored arm, or null; never writes. No tenant filter: a session has one arm. */
+export function readPilotArm(db, sessionId) {
+    // SAFETY: the SELECT names exactly this one column.
+    const row = db.prepare(`SELECT block_hash FROM token_ledger WHERE session_id = ? AND surface = 'pilot' AND event = 'arm' ORDER BY id LIMIT 1`).get(sessionId);
+    return row?.block_hash === 'holdout' || row?.block_hash === 'hippo' ? row.block_hash : null;
+}
+/** The stored arm, else the hash arm written once; on any error the hash arm comes back unrecorded. */
+// The hook's lock-wait bound holds only on a handle opened with `busyWaitMs: HOOK_DB_WAIT_MS`, as hook commands are.
+export function ensurePilotArm(db, tenantId, sessionId, rateBp, now) {
+    const hashed = hashArm(sessionId, rateBp);
+    let began = false;
+    try {
+        // A stored row is the common case after the first prompt, so it must not take the write lock.
+        const existing = readPilotArm(db, sessionId);
+        if (existing !== null)
+            return existing;
+        execWithBusyRetry(db, 'BEGIN IMMEDIATE', HOOK_DB_WAIT_MS);
+        began = true;
+        const stored = readPilotArm(db, sessionId);
+        if (stored === null) {
+            recordTokenUse(db, { tenantId, sessionId, surface: 'pilot', event: 'arm', items: rateBp, tokens: 0, hash: hashed, now });
+        }
+        db.exec('COMMIT');
+        return stored ?? hashed;
+    }
+    catch {
+        // A prompt hook must not fail on pilot bookkeeping; concurrent callers still agree on the hash arm.
+        if (began) {
+            try {
+                db.exec('ROLLBACK');
+            }
+            catch { /* keep the hash arm */ }
+        }
+        return hashed;
+    }
+}
+//# sourceMappingURL=pilot-arm.js.map

package/dist/policies.js

@@ -36,6 +36,7 @@
  * Dual-write atomicity: `savePolicy` writes the memory + policies row (and, on
  * supersede, the predecessor's UPDATE) inside writeEntry's SAVEPOINT.
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -62,7 +63,7 @@ export const VALID_POLICY_STATES = new Set([
 export function normalizePolicyDate(input, label = 'date') {
     const d = new Date(input);
     if (Number.isNaN(d.getTime())) {
-        throw new Error(`policy: invalid ${label} "${input}" (expected an ISO-8601 date or datetime)`);
+        throw new BadRequestError(`policy: invalid ${label} "${input}" (expected an ISO-8601 date or datetime)`);
     }
     return d.toISOString();
 }
@@ -76,7 +77,7 @@ export function validatePolicyDates(validFromRaw, validToRaw, nowIso) {
         ? normalizePolicyDate(validToRaw, 'valid_to')
         : null;
     if (validTo !== null && validTo <= validFrom) {
-        throw new Error(`policy: valid_to (${validTo}) must be strictly after valid_from (${validFrom})`);
+        throw new BadRequestError(`policy: valid_to (${validTo}) must be strictly after valid_from (${validFrom})`);
     }
     return { validFrom, validTo };
 }
@@ -123,10 +124,10 @@ function buildPolicyContent(policyName, policyText, validFrom, validTo) {
 export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('savePolicy', tenantId);
     if (!opts.policyName || opts.policyName.trim().length === 0) {
-        throw new Error('savePolicy: policyName is required');
+        throw new BadRequestError('savePolicy: policyName is required');
     }
     if (!opts.policyText || opts.policyText.trim().length === 0) {
-        throw new Error('savePolicy: policyText is required');
+        throw new BadRequestError('savePolicy: policyText is required');
     }
     const now = new Date().toISOString();
     // valid_from defaults to the precise creation instant (the honest effective
@@ -163,10 +164,10 @@ export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
                 // shape for the matching row, or undefined when no policy/tenant pair matches.
                 const pred = db.prepare(`SELECT status, version FROM policies WHERE id = ? AND tenant_id = ?`).get(opts.supersedesPolicyId, tenantId);
                 if (!pred) {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`savePolicy: policy ${opts.supersedesPolicyId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} is not active (status='${pred.status}'); only active policies can be superseded.`);
+                    throw new ConflictError(`savePolicy: policy ${opts.supersedesPolicyId} is not active (status='${pred.status}'); only active policies can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -184,7 +185,7 @@ export function savePolicy(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(policyId, now, opts.supersedesPolicyId, tenantId, policyId);
                 if (sup.changes === 0) {
-                    throw new Error(`savePolicy: policy ${opts.supersedesPolicyId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`savePolicy: policy ${opts.supersedesPolicyId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -248,9 +249,9 @@ export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
                 // shape, or undefined when the id/tenant pair doesn't exist.
                 const existing = db.prepare(`SELECT status FROM policies WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closePolicy: policy ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closePolicy: policy ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closePolicy: policy ${id} is not active (status='${existing.status}'); only active policies can be closed.`);
+                throw new ConflictError(`closePolicy: policy ${id} is not active (status='${existing.status}'); only active policies can be closed.`);
             }
             // SAFETY: SELECT ${POLICY_COLS} projects exactly the PolicyRow columns;
             // .get() returns that row for the just-updated id, or undefined only in an
@@ -258,7 +259,7 @@ export function closePolicy(hippoRoot, tenantId, id, actor = 'cli') {
             const row = db.prepare(`SELECT ${POLICY_COLS} FROM policies WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closePolicy: policy ${id} not found after UPDATE`);
+                throw new NotFoundError(`closePolicy: policy ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -315,7 +316,7 @@ export function loadPolicies(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_POLICY_STATES.has(opts.status)) {
-                throw new Error(`loadPolicies: status must be one of ${Array.from(VALID_POLICY_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadPolicies: status must be one of ${Array.from(VALID_POLICY_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: SELECT ${POLICY_COLS} projects exactly the PolicyRow columns;
             // .all() returns rows in that shape regardless of the status filter applied.

package/dist/predictions.js

@@ -24,6 +24,7 @@
  * (estimate_value, actual_value) at query time. J3 is a follow-up episode;
  * this module ships the data layer.
  */
+import { BadRequestError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -72,9 +73,9 @@ function rowToPrediction(row) {
 export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('savePrediction', tenantId);
     if (!opts.classTag)
-        throw new Error('savePrediction: classTag is required');
+        throw new BadRequestError('savePrediction: classTag is required');
     if (!opts.claimText)
-        throw new Error('savePrediction: claimText is required');
+        throw new BadRequestError('savePrediction: claimText is required');
     const now = new Date().toISOString();
     const mem = createMemory(opts.claimText, {
         tags: ['prediction', opts.classTag],
@@ -143,7 +144,7 @@ export function savePrediction(hippoRoot, tenantId, opts, actor = 'cli') {
 export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
     assertTenantId('closePrediction', tenantId);
     if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
-        throw new Error(`closePrediction: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
+        throw new BadRequestError(`closePrediction: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
     }
     const now = new Date().toISOString();
     const db = openHippoDb(hippoRoot);
@@ -171,9 +172,9 @@ export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
           SELECT closure_state FROM predictions WHERE id = ? AND tenant_id = ?
         `).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closePrediction: prediction ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closePrediction: prediction ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
+                throw new BadRequestError(`closePrediction: prediction ${id} is already closed (state='${existing.closure_state}'); ` +
                     `cannot re-close. Open predictions only.`);
             }
             // SAFETY: row's shape matches the columns named in the SELECT above.
@@ -184,7 +185,7 @@ export function closePrediction(hippoRoot, tenantId, id, opts, actor = 'cli') {
         FROM predictions WHERE id = ? AND tenant_id = ?
       `).get(id, tenantId);
             if (!row) {
-                throw new Error(`closePrediction: prediction ${id} not found after UPDATE`);
+                throw new NotFoundError(`closePrediction: prediction ${id} not found after UPDATE`);
             }
             appendAuditEvent(db, {
                 tenantId,
@@ -239,7 +240,7 @@ export function loadPredictionsByClass(hippoRoot, tenantId, classTag, opts = {})
         let rows;
         if (opts.closureState) {
             if (!VALID_CLOSURE_STATES.has(opts.closureState)) {
-                throw new Error(`loadPredictionsByClass: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
+                throw new BadRequestError(`loadPredictionsByClass: closureState must be one of ${Array.from(VALID_CLOSURE_STATES).join('|')}; got ${opts.closureState}`);
             }
             // SAFETY: rows' shape matches the columns named in the SELECT above.
             rows = db.prepare(`
@@ -296,7 +297,7 @@ export function computePredictionBaserate(hippoRoot, tenantId, classTag, actor =
 emitAudit = true) {
     assertTenantId('computePredictionBaserate', tenantId);
     if (!classTag)
-        throw new Error('computePredictionBaserate: classTag is required');
+        throw new BadRequestError('computePredictionBaserate: classTag is required');
     const db = openHippoDb(hippoRoot);
     try {
         // SAFETY: rows' shape matches the two columns named in the SELECT above.

package/dist/processes.js

@@ -30,6 +30,7 @@
  * 'write_entry' via the afterWrite hook, so a failure in any step rolls all of
  * them back. Pattern matches saveDecision (decisions.ts).
  */
+import { BadRequestError, ConflictError, NotFoundError } from './api-errors.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { writeEntry } from './store.js';
 import { assertTenantId } from './tenant.js';
@@ -58,23 +59,23 @@ export const MAX_PROCESS_STEP_LEN = 2000;
  */
 export function validateProcessSteps(steps) {
     if (!Array.isArray(steps)) {
-        throw new Error('saveProcess: steps must be an array of strings');
+        throw new BadRequestError('saveProcess: steps must be an array of strings');
     }
     if (steps.length > MAX_PROCESS_STEPS) {
-        throw new Error(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
+        throw new BadRequestError(`saveProcess: steps exceeds the ${MAX_PROCESS_STEPS}-step cap (got ${steps.length})`);
     }
     const out = [];
     for (let i = 0; i < steps.length; i++) {
         const raw = steps[i];
         if (!isString(raw)) {
-            throw new Error(`saveProcess: step ${i + 1} is not a string`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} is not a string`);
         }
         const trimmed = raw.trim();
         if (trimmed.length === 0) {
-            throw new Error(`saveProcess: step ${i + 1} is empty`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} is empty`);
         }
         if (trimmed.length > MAX_PROCESS_STEP_LEN) {
-            throw new Error(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
+            throw new BadRequestError(`saveProcess: step ${i + 1} exceeds the ${MAX_PROCESS_STEP_LEN}-char cap`);
         }
         out.push(trimmed);
     }
@@ -143,7 +144,7 @@ function buildProcessContent(processName, steps, description) {
 export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
     assertTenantId('saveProcess', tenantId);
     if (!opts.processName || opts.processName.trim().length === 0) {
-        throw new Error('saveProcess: processName is required');
+        throw new BadRequestError('saveProcess: processName is required');
     }
     const steps = validateProcessSteps(opts.steps);
     const isSupersede = opts.supersedesProcessId !== undefined;
@@ -177,10 +178,10 @@ export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
                 // the two selected columns 1:1.
                 const pred = db.prepare(`SELECT status, version FROM processes WHERE id = ? AND tenant_id = ?`).get(opts.supersedesProcessId, tenantId);
                 if (!pred) {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`saveProcess: process ${opts.supersedesProcessId} to supersede not found for tenant ${tenantId}`);
                 }
                 if (pred.status !== 'active') {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
+                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} is not active (status='${pred.status}'); only active processes can be superseded.`);
                 }
                 version = pred.version + 1;
             }
@@ -198,7 +199,7 @@ export function saveProcess(hippoRoot, tenantId, opts, actor = 'cli') {
           WHERE id = ? AND tenant_id = ? AND status = 'active' AND id != ?
         `).run(processId, now, opts.supersedesProcessId, tenantId, processId);
                 if (sup.changes === 0) {
-                    throw new Error(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
+                    throw new ConflictError(`saveProcess: process ${opts.supersedesProcessId} could not be superseded (no longer active or self-reference).`);
                 }
                 appendAuditEvent(db, {
                     tenantId,
@@ -262,16 +263,16 @@ export function closeProcess(hippoRoot, tenantId, id, actor = 'cli') {
                 // single selected column.
                 const existing = db.prepare(`SELECT status FROM processes WHERE id = ? AND tenant_id = ?`).get(id, tenantId);
                 if (!existing) {
-                    throw new Error(`closeProcess: process ${id} not found for tenant ${tenantId}`);
+                    throw new NotFoundError(`closeProcess: process ${id} not found for tenant ${tenantId}`);
                 }
-                throw new Error(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
+                throw new ConflictError(`closeProcess: process ${id} is not active (status='${existing.status}'); only active processes can be closed.`);
             }
             // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
             // 1:1 (see PROCESS_COLS above).
             const row = db.prepare(`SELECT ${PROCESS_COLS} FROM processes WHERE id = ? AND tenant_id = ?`)
                 .get(id, tenantId);
             if (!row)
-                throw new Error(`closeProcess: process ${id} not found after UPDATE`);
+                throw new NotFoundError(`closeProcess: process ${id} not found after UPDATE`);
             appendAuditEvent(db, {
                 tenantId,
                 actor,
@@ -318,7 +319,7 @@ export function loadProcesses(hippoRoot, tenantId, opts = {}) {
         let rows;
         if (opts.status) {
             if (!VALID_PROCESS_STATES.has(opts.status)) {
-                throw new Error(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
+                throw new BadRequestError(`loadProcesses: status must be one of ${Array.from(VALID_PROCESS_STATES).join('|')}; got ${opts.status}`);
             }
             // SAFETY: SELECT ${PROCESS_COLS} enumerates every ProcessRow field
             // 1:1 (see PROCESS_COLS above).

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

@@ -0,0 +1,52 @@
+import type { DatabaseSyncLike } from './db.js';
+export interface ProjectSummary {
+    /** '' is user-global, null is unknown; neither can be merged. */
+    readonly origin: string | null;
+    readonly live: number;
+    readonly imported: number;
+    readonly newest: string;
+    /** Imported notes whose text another project name also holds: evidence of a duplicate import, never a merge target. */
+    readonly copiesElsewhere: number;
+}
+export interface MergeResult {
+    readonly from: string;
+    readonly into: string;
+    /** Imported note copies moved to dormant storage; the next sync under `into` imports the notes still on disk. */
+    readonly setAside: readonly string[];
+    readonly restamped: readonly string[];
+    readonly dormantRestamped: readonly string[];
+    readonly compactions: number;
+    readonly backup: string | null;
+}
+export interface RepairResult {
+    readonly toProject: ReadonlyArray<{
+        readonly id: string;
+        readonly origin: string;
+    }>;
+    /** Parents in two projects: the merged text blends them, so it goes dormant and the parents re-merge per project. */
+    readonly setAside: readonly string[];
+    /** No parent left to say which project, or pinned: left as they are, since hiding them would rest on no evidence. */
+    readonly untraced: readonly string[];
+    readonly backup: string | null;
+}
+/** Live rows per project name, newest write first, with how many of its imported notes are copies held elsewhere. */
+export declare function listProjects(db: DatabaseSyncLike, tenantId: string): ProjectSummary[];
+/** Copies the database before a repair writes, so the audit ids plus this file are the way back. */
+export declare function backupStore(db: DatabaseSyncLike, hippoRoot: string, label: string, now?: Date): string;
+/** Refuses user-global and unknown: they are not projects, and folding them would leak or hide every row. */
+export declare function validateMergeNames(from: string, into: string): string | null;
+/** Folds project `from` into `into` for one tenant in one transaction; a dry run rolls back and writes nothing, mirrors included. */
+export declare function mergeProjects(db: DatabaseSyncLike, hippoRoot: string, opts: {
+    tenantId: string;
+    from: string;
+    into: string;
+    dryRun: boolean;
+}): MergeResult;
+/** Reads only, so doctor can call it on a read-only handle: what the repair would do to each user-global merged row. */
+export declare function planUserGlobalRepair(db: DatabaseSyncLike, tenantId: string): Omit<RepairResult, 'backup'>;
+/** Re-tags sleep's merged rows saved as user-global before the fix, by the projects of their parents. */
+export declare function repairUserGlobalMerges(db: DatabaseSyncLike, hippoRoot: string, opts: {
+    tenantId: string;
+    dryRun: boolean;
+}): RepairResult;
+//# sourceMappingURL=project-merge.d.ts.map