hippo-memory 1.57.0 → 1.59.0

package/dist/server.js

@@ -1,5 +1,5 @@
 import { createServer } from 'node:http';
-import { createHash } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
 import { dirname, resolve } from 'node:path';
 import { resolveProjectIdentity } from './project-identity.js';
 import { assembleCost, contextCost, drillCost } from './context-render.js';
@@ -8,7 +8,7 @@ import { resolveTenantId } from './tenant.js';
 import { openHippoDb, closeHippoDb } from './db.js';
 import { updateStats } from './store.js';
 import { buildSessionKey, getOrCreateRing, appendRecall, snapshotRing, hashQueryText, biasHintEnabled, } from './recall-history.js';
-import { appendAuditEvent, auditQueryFields, AUDIT_OPS } from './audit.js';
+import { appendAuditEvent, auditQueryFields, auditWriteFailureCount, AUDIT_OPS } from './audit.js';
 // v0.33 / J1 — Module-level per-(tenant, session) recall-history ring map
 // for the HTTP pipeline. Separate from CLI/MCP rings per plan v3 (per-
 // pipeline rings; no IPC). HTTP is the only caller that threads its
@@ -21,9 +21,10 @@ export function __resetSessionRecallHistoryHttp() {
     sessionRecallHistoryHttp.clear();
 }
 import { PACKAGE_VERSION } from './version.js';
+import { log } from './log.js';
 import { API_KEY_PREFIX, validateApiKey } from './auth.js';
 import { createRateLimiter } from './rate-limit.js';
-import { remember, retrieve, RecallContractError, ForbiddenError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, recordTokens, quarantineList, quarantineApprove, quarantineReject, } from './api.js';
+import { remember, retrieve, RecallContractError, drillDown, assemble, forget, promote, supersede, archiveRaw, authCreate, authList, authRevoke, auditList, outcome, outcomeForLastRecall, getContext, sleep, recordTokens, quarantineList, quarantineApprove, quarantineReject, } 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';
@@ -37,7 +38,10 @@ import { saveCustomerNote, closeCustomerNote, loadCustomerNoteById, loadCustomer
 import { handleMcpRequest } from './mcp/server.js';
 import { handleSlackEventsWebhook } from './connectors/slack/webhook.js';
 import { handleGitHubEventsWebhook } from './connectors/github/webhook.js';
-import { HttpError, JSON_HEADERS, BodyTooLargeError, isHeaderString, isJsonObjectRecord, readBody, sendJson, } from './http-util.js';
+import { HttpError, JSON_HEADERS, BodyTooLargeError, isHeaderString, isJsonObjectRecord, mapApiError, readBody, sendJson, } from './http-util.js';
+import { ForbiddenError, NotFoundError } from './api-errors.js';
+// Add-on packages revoke keys through these without importing the whole api surface.
+export { authRevoke, ForbiddenError };
 // Review patch #2: explicit allow-list for unauthenticated /v1/* routes.
 // New unauth routes MUST be added here AND get a corresponding entry in
 // tests/server-bearer-lockdown.test.ts. Do not gate auth elsewhere by
@@ -156,6 +160,22 @@ const VALID_KINDS = new Set([
 // v1.3.1: source from src/version.ts so /health no longer reports stale 0.39.0.
 const VERSION = PACKAGE_VERSION;
 const LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
+// The caller's id lands in a response header and in logs, so only a short plain token is echoed back.
+const REQUEST_ID_RE = /^[A-Za-z0-9._:-]{1,128}$/;
+/** The caller's `X-Request-Id` when it is a short plain token, else a fresh UUID. */
+function resolveRequestId(header) {
+    const value = Array.isArray(header) ? undefined : header;
+    return value && REQUEST_ID_RE.test(value) ? value : randomUUID();
+}
+/** One line per failed request; 4xx is the caller's mistake, so it stays below the default level. */
+function logRequestFailure(req, err, requestId, status) {
+    const message = err instanceof Error ? err.message : String(err);
+    const line = `${req.method ?? 'GET'} ${(req.url ?? '/').split('?')[0]} failed: ${message}`;
+    if (status >= 500)
+        log.error(line, { requestId, status });
+    else
+        log.info(line, { requestId, status });
+}
 function sendError(res, status, message) {
     sendJson(res, status, { error: message });
 }
@@ -176,35 +196,17 @@ async function parseJsonBody(req) {
         throw new HttpError(400, 'invalid JSON body');
     }
 }
-/**
- * Map an error thrown by an api.* function into an HTTP status + message.
- * api.* uses plain Error, so we discriminate by message pattern. Stable
- * patterns we rely on:
- *   - /not found/i  → 404 (forget on unknown id, supersede on unknown old id, etc.)
- *   - /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)
- * 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 };
-    }
-    if (/already superseded/.test(lower)) {
-        return { status: 409, message };
+function parseRequest(req) {
+    let url;
+    try {
+        url = new URL(req.url ?? '/', 'http://placeholder');
     }
-    if (/requires admin role/.test(lower)) {
-        return { status: 403, message };
+    catch (e) {
+        // A request target the URL parser rejects is the caller's fault, not a server failure.
+        if (e instanceof TypeError)
+            throw new HttpError(400, e.message);
+        throw e;
     }
-    return { status: 400, message };
-}
-function parseRequest(req) {
-    const url = new URL(req.url ?? '/', 'http://placeholder');
     return {
         method: req.method ?? 'GET',
         path: url.pathname,
@@ -219,6 +221,16 @@ function parseRequest(req) {
  * mapping each :param name to its value. Path segments are exact-matched
  * except for parameter slots.
  */
+function decodePathSegment(segment) {
+    try {
+        return decodeURIComponent(segment);
+    }
+    catch (e) {
+        if (e instanceof URIError)
+            throw new HttpError(400, e.message);
+        throw e;
+    }
+}
 function matchPath(pattern, path) {
     const patternParts = pattern.split('/');
     const pathParts = path.split('/');
@@ -231,7 +243,7 @@ function matchPath(pattern, path) {
         if (pp.startsWith(':')) {
             if (ap.length === 0)
                 return null;
-            params[pp.slice(1)] = decodeURIComponent(ap);
+            params[pp.slice(1)] = decodePathSegment(ap);
         }
         else if (pp !== ap) {
             return null;
@@ -265,10 +277,22 @@ export function isCrossSite(req) {
     const origin = req.headers.origin;
     return origin !== undefined && origin !== `http://${req.headers.host}`;
 }
+// A proxy on this host (nginx, Caddy, cloudflared) connects from loopback, so these headers mean the caller is not local.
+const PROXY_HEADERS = [
+    'forwarded', 'x-forwarded-for', 'x-forwarded-host', 'x-forwarded-proto', 'x-real-ip', 'cf-connecting-ip', 'true-client-ip',
+];
+// The auth helpers only see the request, so its id rides here for their log lines.
+const requestIds = new WeakMap();
 // 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 proxyHeader = PROXY_HEADERS.find((name) => req.headers[name] !== undefined);
+    if (proxyHeader !== undefined) {
+        log.warn(`proxied loopback request refused: it carries ${proxyHeader}, so the no-key local fallback does not apply. ` +
+            'Send an API key (hippo auth create, then Authorization: Bearer hk_...).', { requestId: requestIds.get(req) });
+        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');
@@ -342,6 +366,11 @@ export function clientIpForRateLimit(req) {
 const RESERVED_ACTOR_NAMES = [
     'api_key', 'localhost', 'cli', 'system', 'mcp', 'connector', 'sleep', 'post-compact', 'recall', 'agent-memories',
 ];
+/** Add-ons call this to refuse a subject that would collide with a built-in actor. */
+export function isReservedActor(subject) {
+    const lower = subject.toLowerCase();
+    return RESERVED_ACTOR_NAMES.some((n) => lower === n || lower.startsWith(`${n}:`));
+}
 function hasControlChar(s) {
     for (let i = 0; i < s.length; i++) {
         const c = s.charCodeAt(i);
@@ -366,8 +395,7 @@ function sanitiseResolved(r) {
     // Padding would let "system " pass the reserved-name check yet read as `system` in an audit log.
     if (hasControlChar(subject) || subject !== subject.trim())
         return null;
-    const lower = subject.toLowerCase();
-    if (RESERVED_ACTOR_NAMES.some((n) => lower === n || lower.startsWith(`${n}:`)))
+    if (isReservedActor(subject))
         return null;
     const clean = { tenantId: tenant, subject, role: role === 'admin' ? 'admin' : 'member' };
     if (Array.isArray(scopes))
@@ -452,9 +480,8 @@ async function buildContextWithAuth(req, opts) {
             actor.viaAuthResolver = true;
         return { hippoRoot: opts.hippoRoot, tenantId: id.tenantId, actor };
     }
-    // No Authorization header. Loopback-only fallback, unless explicitly
-    // disabled via HIPPO_REQUIRE_AUTH=1 (used by the bearer-lockdown test
-    // and by deployments that want to forbid the local-CLI escape hatch).
+    // No Authorization header. Loopback-only fallback for a direct local caller (no proxy headers),
+    // unless HIPPO_REQUIRE_AUTH=1 forbids the local-CLI escape hatch.
     if (process.env.HIPPO_REQUIRE_AUTH === '1') {
         throw new HttpError(401, 'auth required');
     }
@@ -1117,36 +1144,16 @@ async function handleListQuarantine({ req, res, opts, query }) {
 async function handleApproveQuarantine({ req, res, opts }, quarantineApproveMatch) {
     validateIdSegment(quarantineApproveMatch.id, 'memory id');
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        quarantineApprove(ctx, quarantineApproveMatch.id);
-        sendJson(res, 200, { approved: quarantineApproveMatch.id });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not quarantined'))
-            throw new HttpError(404, msg);
-        if (msg.includes('is already') || msg.includes('scope changed'))
-            throw new HttpError(409, msg);
-        throw e;
-    }
+    quarantineApprove(ctx, quarantineApproveMatch.id);
+    sendJson(res, 200, { approved: quarantineApproveMatch.id });
     return;
 }
 // POST /v1/quarantine/:id/reject: admin only; ForbiddenError falls through to mapApiError's 403.
 async function handleRejectQuarantine({ req, res, opts }, quarantineRejectMatch) {
     validateIdSegment(quarantineRejectMatch.id, 'memory id');
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        quarantineReject(ctx, quarantineRejectMatch.id);
-        sendJson(res, 200, { rejected: quarantineRejectMatch.id });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not quarantined'))
-            throw new HttpError(404, msg);
-        if (msg.includes('is already'))
-            throw new HttpError(409, msg);
-        throw e;
-    }
+    quarantineReject(ctx, quarantineRejectMatch.id);
+    sendJson(res, 200, { rejected: quarantineRejectMatch.id });
     return;
 }
 // GET /v1/audit?op=&since=&limit= — read audit events. All three filters
@@ -1335,21 +1342,12 @@ async function handleClosePrediction({ req, res, opts }, predictionCloseMatch) {
         closureNote = note;
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const prediction = closePrediction(opts.hippoRoot, ctx.tenantId, id, {
-            closureState: state,
-            actualValue,
-            closureNote,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { prediction });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        throw e;
-    }
+    const prediction = closePrediction(opts.hippoRoot, ctx.tenantId, id, {
+        closureState: state,
+        actualValue,
+        closureNote,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { prediction });
     return;
 }
 // ── decisions (E2 first-class object) ──
@@ -1400,10 +1398,9 @@ async function handleCreateDecision({ req, res, opts }) {
         sendJson(res, 201, { decision });
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found') || msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
+        // A missing referenced row is a conflict with the create, not a missing target.
+        if (e instanceof NotFoundError)
+            throw new HttpError(409, e.message);
         throw e;
     }
     return;
@@ -1450,43 +1447,19 @@ async function handleSupersedeDecision({ req, res, opts }, decisionSupersedeMatc
         context = contextRaw;
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
-            decisionText: text,
-            context,
-            supersedesDecisionId: oldId,
-        }, ctx.actor.subject);
-        sendJson(res, 201, { decision });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const decision = saveDecision(opts.hippoRoot, ctx.tenantId, {
+        decisionText: text,
+        context,
+        supersedesDecisionId: oldId,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { decision });
     return;
 }
 async function handleCloseDecision({ req, res, opts }, decisionCloseMatch) {
     const id = parseInt(decisionCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const decision = closeDecision(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { decision });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const decision = closeDecision(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { decision });
     return;
 }
 async function handleGetDecision({ req, res, opts }, decisionByIdMatch) {
@@ -1555,10 +1528,9 @@ async function handleCreateIncident({ req, res, opts }) {
         sendJson(res, 201, { incident });
     }
     catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(409, msg);
-        }
+        // A missing referenced row is a conflict with the create, not a missing target.
+        if (e instanceof NotFoundError)
+            throw new HttpError(409, e.message);
         throw e;
     }
     return;
@@ -1594,39 +1566,15 @@ async function handleResolveIncident({ req, res, opts }, incidentResolveMatch) {
         throw new HttpError(400, 'resolutionText exceeds 4096-character cap');
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const incident = resolveIncident(opts.hippoRoot, ctx.tenantId, id, resolutionText, ctx.actor.subject);
-        sendJson(res, 200, { incident });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not open')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const incident = resolveIncident(opts.hippoRoot, ctx.tenantId, id, resolutionText, ctx.actor.subject);
+    sendJson(res, 200, { incident });
     return;
 }
 async function handleCloseIncident({ req, res, opts }, incidentCloseMatch) {
     const id = parseInt(incidentCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const incident = closeIncident(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { incident });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('already closed')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const incident = closeIncident(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { incident });
     return;
 }
 async function handleGetIncident({ req, res, opts }, incidentByIdMatch) {
@@ -1737,45 +1685,21 @@ async function handleSupersedeProcess({ req, res, opts }, processSupersedeMatch)
     if (!existing) {
         throw new HttpError(404, `process ${id} not found`);
     }
-    try {
-        const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
-            processName: existing.processName,
-            steps,
-            description,
-            changeSummary,
-            supersedesProcessId: id,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { process });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const process = saveProcess(opts.hippoRoot, ctx.tenantId, {
+        processName: existing.processName,
+        steps,
+        description,
+        changeSummary,
+        supersedesProcessId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { process });
     return;
 }
 async function handleCloseProcess({ req, res, opts }, processCloseMatch) {
     const id = parseInt(processCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const process = closeProcess(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { process });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const process = closeProcess(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { process });
     return;
 }
 async function handleGetProcess({ req, res, opts }, processByIdMatch) {
@@ -1816,19 +1740,13 @@ async function handleCreatePolicy({ req, res, opts }) {
     const validFrom = optionalDateField(body['validFrom'], 'validFrom');
     const validTo = optionalDateField(body['validTo'], 'validTo');
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
-            policyName,
-            policyText,
-            validFrom,
-            validTo,
-        }, ctx.actor.subject);
-        sendJson(res, 201, { policy });
-    }
-    catch (e) {
-        // savePolicy throws on invalid/inverted dates (validation) -> 400.
-        throw new HttpError(400, e instanceof Error ? e.message : String(e));
-    }
+    const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+        policyName,
+        policyText,
+        validFrom,
+        validTo,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { policy });
     return;
 }
 async function handleListPolicies({ req, res, opts, query }) {
@@ -1860,13 +1778,8 @@ async function handlePoliciesAsOf({ req, res, opts, query }) {
     }
     const name = query.get('name') ?? undefined;
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const policies = loadPoliciesAsOf(opts.hippoRoot, ctx.tenantId, date, { name });
-        sendJson(res, 200, { policies });
-    }
-    catch (e) {
-        throw new HttpError(400, e instanceof Error ? e.message : String(e));
-    }
+    const policies = loadPoliciesAsOf(opts.hippoRoot, ctx.tenantId, date, { name });
+    sendJson(res, 200, { policies });
     return;
 }
 async function handleSupersedePolicy({ req, res, opts }, policySupersedeMatch) {
@@ -1897,47 +1810,22 @@ async function handleSupersedePolicy({ req, res, opts }, policySupersedeMatch) {
     if (!existing) {
         throw new HttpError(404, `policy ${id} not found`);
     }
-    try {
-        const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
-            policyName: existing.policyName,
-            policyText,
-            validFrom,
-            validTo,
-            changeSummary,
-            supersedesPolicyId: id,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { policy });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        // invalid/inverted date or missing field -> validation.
-        throw new HttpError(400, msg);
-    }
+    const policy = savePolicy(opts.hippoRoot, ctx.tenantId, {
+        policyName: existing.policyName,
+        policyText,
+        validFrom,
+        validTo,
+        changeSummary,
+        supersedesPolicyId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { policy });
     return;
 }
 async function handleClosePolicy({ req, res, opts }, policyCloseMatch) {
     const id = parseInt(policyCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const policy = closePolicy(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { policy });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const policy = closePolicy(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { policy });
     return;
 }
 async function handleGetPolicy({ req, res, opts }, policyByIdMatch) {
@@ -1990,18 +1878,12 @@ async function handleCreateSkill({ req, res, opts }) {
         trigger = triggerRaw;
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
-            skillName,
-            instructions,
-            trigger,
-        }, ctx.actor.subject);
-        sendJson(res, 201, { skill });
-    }
-    catch (e) {
-        // saveSkill throws on validation (single-line name etc.) -> 400.
-        throw new HttpError(400, e instanceof Error ? e.message : String(e));
-    }
+    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+        skillName,
+        instructions,
+        trigger,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { skill });
     return;
 }
 async function handleListSkills({ req, res, opts, query }) {
@@ -2069,45 +1951,21 @@ async function handleSupersedeSkill({ req, res, opts }, skillSupersedeMatch) {
     if (!existing) {
         throw new HttpError(404, `skill ${id} not found`);
     }
-    try {
-        const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
-            skillName: existing.skillName,
-            instructions,
-            trigger,
-            changeSummary,
-            supersedesSkillId: id,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { skill });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        throw new HttpError(400, msg);
-    }
+    const skill = saveSkill(opts.hippoRoot, ctx.tenantId, {
+        skillName: existing.skillName,
+        instructions,
+        trigger,
+        changeSummary,
+        supersedesSkillId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { skill });
     return;
 }
 async function handleCloseSkill({ req, res, opts }, skillCloseMatch) {
     const id = parseInt(skillCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { skill });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const skill = closeSkill(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { skill });
     return;
 }
 async function handleGetSkill({ req, res, opts }, skillByIdMatch) {
@@ -2147,17 +2005,11 @@ async function handleCreateProjectBrief({ req, res, opts }) {
         throw new HttpError(400, 'summary exceeds 8192-character cap');
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
-            repo,
-            summary,
-        }, ctx.actor.subject);
-        sendJson(res, 201, { brief });
-    }
-    catch (e) {
-        // saveProjectBrief throws on validation (single-line repo etc.) -> 400.
-        throw new HttpError(400, e instanceof Error ? e.message : String(e));
-    }
+    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+        repo,
+        summary,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { brief });
     return;
 }
 async function handleListProjectBriefs({ req, res, opts, query }) {
@@ -2192,29 +2044,13 @@ async function handleRefreshProjectBrief({ req, res, opts }) {
     }
     const dryRun = body['dryRun'] === true;
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        if (dryRun) {
-            const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
-            sendJson(res, 200, { markdown, receiptCount });
-            return;
-        }
-        const brief = refreshBrief(opts.hippoRoot, ctx.tenantId, repo, ctx.actor.subject);
-        sendJson(res, 200, { brief });
-    }
-    catch (e) {
-        // A refresh race (the active brief is closed/superseded between
-        // loadActiveBriefForRepo and the supersede CAS) is a state conflict, not a
-        // validation error — map it to 409 like the explicit supersede route
-        // (codex-review 2026-05-30, P3).
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        throw new HttpError(400, msg);
+    if (dryRun) {
+        const { markdown, receiptCount } = assembleBriefFromReceipts(opts.hippoRoot, ctx.tenantId, repo);
+        sendJson(res, 200, { markdown, receiptCount });
+        return;
     }
+    const brief = refreshBrief(opts.hippoRoot, ctx.tenantId, repo, ctx.actor.subject);
+    sendJson(res, 200, { brief });
     return;
 }
 async function handleSupersedeProjectBrief({ req, res, opts }, briefSupersedeMatch) {
@@ -2243,44 +2079,20 @@ async function handleSupersedeProjectBrief({ req, res, opts }, briefSupersedeMat
     if (!existing) {
         throw new HttpError(404, `project brief ${id} not found`);
     }
-    try {
-        const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
-            repo: existing.repo,
-            summary,
-            changeSummary,
-            supersedesBriefId: id,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { brief });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        throw new HttpError(400, msg);
-    }
+    const brief = saveProjectBrief(opts.hippoRoot, ctx.tenantId, {
+        repo: existing.repo,
+        summary,
+        changeSummary,
+        supersedesBriefId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { brief });
     return;
 }
 async function handleCloseProjectBrief({ req, res, opts }, briefCloseMatch) {
     const id = parseInt(briefCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { brief });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const brief = closeProjectBrief(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { brief });
     return;
 }
 async function handleGetProjectBrief({ req, res, opts }, briefByIdMatch) {
@@ -2318,17 +2130,11 @@ async function handleCreateCustomerNote({ req, res, opts }) {
         throw new HttpError(400, 'note exceeds 8192-character cap');
     }
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
-            customer,
-            note,
-        }, ctx.actor.subject);
-        sendJson(res, 201, { note: customerNote });
-    }
-    catch (e) {
-        // saveCustomerNote throws on validation (single-line customer etc.) -> 400.
-        throw new HttpError(400, e instanceof Error ? e.message : String(e));
-    }
+    const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
+        customer,
+        note,
+    }, ctx.actor.subject);
+    sendJson(res, 201, { note: customerNote });
     return;
 }
 async function handleListCustomerNotes({ req, res, opts, query }) {
@@ -2376,44 +2182,20 @@ async function handleSupersedeCustomerNote({ req, res, opts }, noteSupersedeMatc
     if (!existing) {
         throw new HttpError(404, `customer note ${id} not found`);
     }
-    try {
-        const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
-            customer: existing.customer,
-            note,
-            changeSummary,
-            supersedesNoteId: id,
-        }, ctx.actor.subject);
-        sendJson(res, 200, { note: customerNote });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active') || msg.includes('could not be superseded')) {
-            throw new HttpError(409, msg);
-        }
-        throw new HttpError(400, msg);
-    }
+    const customerNote = saveCustomerNote(opts.hippoRoot, ctx.tenantId, {
+        customer: existing.customer,
+        note,
+        changeSummary,
+        supersedesNoteId: id,
+    }, ctx.actor.subject);
+    sendJson(res, 200, { note: customerNote });
     return;
 }
 async function handleCloseCustomerNote({ req, res, opts }, noteCloseMatch) {
     const id = parseInt(noteCloseMatch[1], 10);
     const ctx = await buildContextWithAuth(req, opts);
-    try {
-        const customerNote = closeCustomerNote(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
-        sendJson(res, 200, { note: customerNote });
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        if (msg.includes('not found')) {
-            throw new HttpError(404, msg);
-        }
-        if (msg.includes('not active')) {
-            throw new HttpError(409, msg);
-        }
-        throw e;
-    }
+    const customerNote = closeCustomerNote(opts.hippoRoot, ctx.tenantId, id, ctx.actor.subject);
+    sendJson(res, 200, { note: customerNote });
     return;
 }
 async function handleGetCustomerNote({ req, res, opts }, noteByIdMatch) {
@@ -2536,6 +2318,7 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
                 version: VERSION,
                 started_at: startedAt,
                 pid: process.pid,
+                audit_write_failures: auditWriteFailureCount(),
             });
         }
         else {
@@ -2738,7 +2521,9 @@ async function handleRequest(req, res, opts, startedAt, limiter) {
  * 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
@@ -2777,7 +2562,12 @@ export async function serve(opts) {
         ? createRateLimiter({ ratePerSec: v1Rps, burst: v1Rps * 2, idleEvictMs: 60000, maxKeys: 10000 })
         : undefined;
     const server = createServer((req, res) => {
+        const requestId = resolveRequestId(req.headers['x-request-id']);
+        requestIds.set(req, requestId);
+        res.setHeader('X-Request-Id', requestId);
         handleRequest(req, res, opts, startedAt, limiter).catch((err) => {
+            const mapped = mapApiError(err);
+            logRequestFailure(req, err, requestId, mapped.status);
             if (res.headersSent) {
                 try {
                     res.end();
@@ -2785,33 +2575,20 @@ export async function serve(opts) {
                 catch { /* socket already gone */ }
                 return;
             }
-            if (err instanceof BodyTooLargeError) {
-                sendError(res, 413, err.message);
-                // M3: readBody hit the 1 MB cap mid-stream, so the request body is
-                // only partially consumed. Destroy the socket rather than let the
-                // client's remaining (unbounded) bytes drain into an exchange we have
-                // already answered.
-                req.destroy();
-                return;
-            }
-            if (err instanceof HttpError) {
-                sendError(res, err.status, err.message);
+            if (mapped.status === 500) {
+                // The id lets an operator find the logged cause without the client seeing internal text.
+                sendJson(res, 500, { error: mapped.message, requestId });
                 return;
             }
-            // F5 (v1.6.5) + v1.7.0 api-contract review: RecallContractError lands
-            // at 400 with {error: <message>, code: <code>}. The `error` field
-            // matches `sendError`'s shape (human message, used by HttpError /
-            // BodyTooLargeError / mapApiError). The `code` field is the typed
-            // discriminator — clients can branch on `body.code` without parsing
-            // prose. Earlier draft used {error: code, message: text} but that
-            // diverged from the rest of v1/* and forced clients to special-case
-            // the error path.
+            // RecallContractError keeps the shared {error} shape and adds `code` so clients branch without parsing prose.
             if (err instanceof RecallContractError) {
                 sendJson(res, 400, { error: err.message, code: err.code });
                 return;
             }
-            const mapped = mapApiError(err);
             sendError(res, mapped.status, mapped.message);
+            // M3: readBody hit the 1 MB cap mid-stream, so drop the socket rather than drain unbounded bytes.
+            if (err instanceof BodyTooLargeError)
+                req.destroy();
         });
     });
     // T3b capture (v1.26.2): tests/server-concurrency.test.ts's ECONNRESET flake