hippo-memory 1.61.0 → 1.63.0

package/dist/server/routes/recall.js

@@ -7,11 +7,11 @@ import { updateStats } from '../../store/index-and-stats.js';
 import { appendRecall, biasHintEnabled, buildSessionKey, getOrCreateRing, hashQueryText, snapshotRing } from '../../recall-history.js';
 import { appendAuditEvent, auditQueryFields } from '../../audit.js';
 import { assemble, drillDown, getContext, recordTokens, retrieve } from '../../api.js';
-import { HttpError, sendJson } from '../../http-util.js';
+import { HttpError, MAX_ID_LEN, sendJson } from '../../http-util.js';
 import { buildContextWithAuth } from '../auth.js';
 import { parseListLimit, validateIdSegment } from '../validation.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-
+// Module-level per-(tenant, session) recall-history ring map
+// for the HTTP pipeline. Separate from CLI/MCP rings (per-
 // pipeline rings; no IPC). HTTP is the only caller that threads its
 // snapshot through opts.recallHistory to api.recall — api.recall's
 // anchoringHint on the returned RecallResult IS the user-visible hint
@@ -21,8 +21,40 @@ const sessionRecallHistoryHttp = new Map();
 export function __resetSessionRecallHistoryHttp() {
     sessionRecallHistoryHttp.clear();
 }
-// GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
-export async function handleRecallMemories({ req, res, opts, query }) {
+function parseFreshTail(query) {
+    // Surface the fresh-tail RecallOpts to HTTP callers so session-scoped
+    // fresh-tail and summary substitution are not JS-only.
+    const freshTailCountRaw = query.get('fresh_tail_count');
+    const freshTailCount = freshTailCountRaw === null ? undefined : Number(freshTailCountRaw);
+    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
+        throw new HttpError(400, 'fresh_tail_count must be a non-negative number');
+    }
+    // Cap session_id length consistent with the
+    // rest of the API. Untrimmed strings round-trip through the SQL layer
+    // and through any downstream metric/log; 256 is generous for a session
+    // id and matches the rest of this file's id-shaped param parsers.
+    const freshTailSessionIdRaw = query.get('fresh_tail_session_id');
+    if (freshTailSessionIdRaw !== null && freshTailSessionIdRaw.length > MAX_ID_LEN) {
+        throw new HttpError(400, `fresh_tail_session_id exceeds ${MAX_ID_LEN}-character cap`);
+    }
+    const freshTailSessionId = freshTailSessionIdRaw && freshTailSessionIdRaw.length > 0
+        ? freshTailSessionIdRaw
+        : undefined;
+    return { freshTailCount, freshTailSessionId };
+}
+function parseSessionId(query) {
+    // session_id for the dlPFC goal-stack boost. 256-char cap mirrors
+    // fresh_tail_session_id (above). Trim then drop if empty so api.recall
+    // sees undefined when the param is omitted or whitespace-only.
+    const sessionIdRaw = query.get('session_id');
+    if (sessionIdRaw !== null && sessionIdRaw.length > MAX_ID_LEN) {
+        throw new HttpError(400, `session_id exceeds ${MAX_ID_LEN}-character cap`);
+    }
+    return sessionIdRaw && sessionIdRaw.trim().length > 0
+        ? sessionIdRaw.trim()
+        : undefined;
+}
+function parseRecallQuery(query) {
     const q = query.get('q');
     if (!q) {
         throw new HttpError(400, 'q is required');
@@ -37,29 +69,9 @@ export async function handleRecallMemories({ req, res, opts, query }) {
     const includeContinuityRaw = query.get('include_continuity');
     const includeContinuity = includeContinuityRaw === '1'
         || includeContinuityRaw === 'true';
-    // v1.6.2: surface the v1.5.0/v1.5.2 RecallOpts additions to HTTP
-    // callers. Pre-v1.6.2 the route silently ignored these so the
-    // session-scoped fresh-tail and summary substitution were JS-only.
-    const freshTailCountRaw = query.get('fresh_tail_count');
-    const freshTailCount = freshTailCountRaw === null ? undefined : Number(freshTailCountRaw);
-    if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
-        throw new HttpError(400, 'fresh_tail_count must be a non-negative number');
-    }
-    // v1.6.3 senior-review P1-3: cap session_id length consistent with the
-    // rest of the API. Untrimmed strings round-trip through the SQL layer
-    // and through any downstream metric/log; 256 is generous for a session
-    // id and matches the rest of this file's id-shaped param parsers.
-    const freshTailSessionIdRaw = query.get('fresh_tail_session_id');
-    if (freshTailSessionIdRaw !== null && freshTailSessionIdRaw.length > 256) {
-        throw new HttpError(400, 'fresh_tail_session_id exceeds 256-character cap');
-    }
-    const freshTailSessionId = freshTailSessionIdRaw && freshTailSessionIdRaw.length > 0
-        ? freshTailSessionIdRaw
-        : undefined;
-    // v1.6.3 senior-review P1-4: tighten parser to match the includeContinuity
-    // convention. Pre-v1.6.3 accepted any non-'0'/'false' value as `true`,
-    // so `?summarize_overflow=banana` and `?summarize_overflow=` both
-    // turned it on. Surface convention drift fixed.
+    const { freshTailCount, freshTailSessionId } = parseFreshTail(query);
+    // Strict parse matching the includeContinuity convention, so values
+    // like `?summarize_overflow=banana` or an empty value do not turn it on.
     const summarizeOverflowRaw = query.get('summarize_overflow');
     const summarizeOverflow = summarizeOverflowRaw === null
         ? undefined
@@ -70,40 +82,29 @@ export async function handleRecallMemories({ req, res, opts, query }) {
     if (scorerWindow !== undefined && scorerWindow > 1000) {
         throw new HttpError(400, 'scorer_window must be <= 1000');
     }
-    // v1.7.4: session_id for the dlPFC goal-stack boost. 256-char cap mirrors
-    // fresh_tail_session_id (above). Trim then drop if empty so api.recall
-    // sees undefined when the param is omitted or whitespace-only.
-    const sessionIdRaw = query.get('session_id');
-    if (sessionIdRaw !== null && sessionIdRaw.length > 256) {
-        throw new HttpError(400, 'session_id exceeds 256-character cap');
-    }
-    const sessionId = sessionIdRaw && sessionIdRaw.trim().length > 0
-        ? sessionIdRaw.trim()
-        : undefined;
-    // A7 recall-trace: opt-in explain flag. When set, api.recall attaches the
+    const sessionId = parseSessionId(query);
+    // Recall-trace: opt-in explain flag. When set, api.recall attaches the
     // lifecycle re-ranking trace (goal-boost step on the api pipeline) +
     // rerankPipeline:'api' to each result item; the field then rides on the
     // serialized RecallResult. Mirrors the include_continuity convention.
     const explainRaw = query.get('explain');
     const explain = explainRaw === '1' || explainRaw === 'true';
-    const ctx = await buildContextWithAuth(req, opts);
-    // v0.33 / J1 — HTTP per-pipeline anchoring detector. HTTP threads its
-    // ring snapshot via opts.recallHistory so api.recall's own
-    // anchoringHint compute path activates. Unlike CLI (which computes
-    // its own hint separately because cmdRecall runs its own physics/
-    // hybrid pipeline outside api.recall), HTTP's /v1/memories response
-    // body IS api.recall's result directly. So the api.recall-computed
-    // hint flows through. HIPPO_ANCHORING=off short-circuits.
+    return { q, limit, mode, scope, includeContinuity, freshTailCount, freshTailSessionId, summarizeOverflow, scorerWindow, sessionId, explain };
+}
+// HTTP per-pipeline anchoring detector. HTTP threads its
+// ring snapshot via opts.recallHistory so api.recall's own
+// anchoringHint compute path activates. Unlike CLI (which computes
+// its own hint separately because cmdRecall runs its own physics/
+// hybrid pipeline outside api.recall), HTTP's /v1/memories response
+// body IS api.recall's result directly. So the api.recall-computed
+// hint flows through. HIPPO_ANCHORING=off short-circuits.
+function snapshotSessionRing(ctx, hippoRoot, q, sessionId) {
     let httpRecallHistory;
     let httpRingKey;
     if (biasHintEnabled('anchoring')) {
         if (sessionId) {
-            // Codex round-5 P2 catch: do NOT mutate sessionRecallHistoryHttp
-            // before recall() preflight runs. A request with an invalid
-            // scorer_window / fresh_tail_count would create-or-touch the
-            // session ring (LRU-evicting valid sessions) even though recall
-            // throws 400. Snapshot the EXISTING ring if present; only
-            // create-or-touch after the recall returns successfully.
+            // Do NOT mutate sessionRecallHistoryHttp before recall() preflight: a request
+            // that 400s would otherwise create-or-touch a ring and LRU-evict valid sessions.
             httpRingKey = buildSessionKey(ctx.tenantId, sessionId);
             const existingRing = sessionRecallHistoryHttp.get(httpRingKey);
             httpRecallHistory = existingRing ? snapshotRing(existingRing) : [];
@@ -113,12 +114,9 @@ export async function handleRecallMemories({ req, res, opts, query }) {
             // Per the normal recall-audit convention (api.ts:854 stores
             // SHA-256/16 hash of the query, NOT raw text), avoid retaining
             // prompts in audit_log here too — query content can contain
-            // secrets, PII, or RTBF-restricted material. Codex round-2 P2
-            // catch: hashQueryText is a 32-bit FNV-1a designed for recall
-            // matching, NOT a privacy hash; brute-force trivial for low-
-            // entropy queries. Use the same SHA-256/16 truncation as the
-            // canonical recall audit.
-            const dbForAudit = openHippoDb(opts.hippoRoot);
+            // secrets, PII, or RTBF-restricted material. hashQueryText is a 32-bit
+            // FNV-1a, NOT a privacy hash, so use the recall audit's SHA-256/16 truncation.
+            const dbForAudit = openHippoDb(hippoRoot);
             try {
                 appendAuditEvent(dbForAudit, {
                     tenantId: ctx.tenantId,
@@ -133,36 +131,42 @@ export async function handleRecallMemories({ req, res, opts, query }) {
             }
         }
     }
+    return { httpRecallHistory, httpRingKey };
+}
+function recallExtraOpts(parsed, httpRecallHistory) {
     const recallExtra = {};
-    if (freshTailCount !== undefined)
-        recallExtra.freshTailCount = freshTailCount;
-    if (freshTailSessionId !== undefined)
-        recallExtra.freshTailSessionId = freshTailSessionId;
-    if (summarizeOverflow !== undefined)
-        recallExtra.summarizeOverflow = summarizeOverflow;
-    if (scorerWindow !== undefined)
-        recallExtra.scorerWindow = scorerWindow;
-    if (sessionId !== undefined)
-        recallExtra.sessionId = sessionId;
+    if (parsed.freshTailCount !== undefined)
+        recallExtra.freshTailCount = parsed.freshTailCount;
+    if (parsed.freshTailSessionId !== undefined)
+        recallExtra.freshTailSessionId = parsed.freshTailSessionId;
+    if (parsed.summarizeOverflow !== undefined)
+        recallExtra.summarizeOverflow = parsed.summarizeOverflow;
+    if (parsed.scorerWindow !== undefined)
+        recallExtra.scorerWindow = parsed.scorerWindow;
+    if (parsed.sessionId !== undefined)
+        recallExtra.sessionId = parsed.sessionId;
     if (httpRecallHistory !== undefined)
         recallExtra.recallHistory = httpRecallHistory;
-    if (explain)
-        recallExtra.explain = explain;
+    if (parsed.explain)
+        recallExtra.explain = parsed.explain;
+    return recallExtra;
+}
+// GET /v1/memories?q=...&limit=...&mode=...&scope=...&include_continuity=1
+export async function handleRecallMemories({ req, res, opts, query }) {
+    const parsed = parseRecallQuery(query);
+    const { q, includeContinuity, sessionId } = parsed;
+    const ctx = await buildContextWithAuth(req, opts);
+    const { httpRecallHistory, httpRingKey } = snapshotSessionRing(ctx, opts.hippoRoot, q, sessionId);
     const result = await retrieve(ctx, {
         query: q,
-        limit,
-        mode: mode ?? undefined,
-        scope: scope ?? undefined,
+        limit: parsed.limit,
+        mode: parsed.mode ?? undefined,
+        scope: parsed.scope ?? undefined,
         includeContinuity,
-        ...recallExtra,
+        ...recallExtraOpts(parsed, httpRecallHistory),
     });
-    // v0.33 / J1 — append AFTER recall completes (snapshot was taken before
-    // recall() ran). anchoredOn carries the memoryId of any hint that fired
-    // (api.recall computed it from the same snapshot we passed in), feeding
-    // the cooldown logic for the NEXT recall on this session.
-    // Codex round-5 P2 fix: create-or-touch the ring ONLY HERE, after recall
-    // returns successfully. Invalid requests that throw 400 in recall()
-    // never reach this point, so they cannot LRU-evict valid sessions.
+    // Append only after recall succeeds, so a 400 cannot LRU-evict valid sessions;
+    // anchoredOn feeds the cooldown logic for the NEXT recall on this session.
     if (httpRingKey) {
         const httpRing = getOrCreateRing(sessionRecallHistoryHttp, httpRingKey);
         const topId = result.results[0]?.id ?? null;
@@ -196,10 +200,8 @@ export async function handleAssembleSession({ req, res, opts, query }, assembleM
     if (freshTailCount !== undefined && (!Number.isFinite(freshTailCount) || freshTailCount < 0)) {
         throw new HttpError(400, 'freshTail must be a non-negative number');
     }
-    // v1.6.3 senior review P1: same strict-parse convention as the v1.6.3
-    // summarize_overflow tighten on /v1/memories. Pre-v1.6.3 accepted any
-    // non-'0'/'false' as true; ?summarizeOlder=banana now correctly returns
-    // false (matches includeContinuity convention).
+    // Same strict-parse convention as summarize_overflow on /v1/memories:
+    // ?summarizeOlder=banana is false (matches includeContinuity convention).
     const sumOlderRaw = query.get('summarizeOlder');
     const summarizeOlder = sumOlderRaw === null
         ? undefined
@@ -239,12 +241,12 @@ export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
     if (budget !== undefined && (!Number.isFinite(budget) || budget <= 0)) {
         throw new HttpError(400, 'budget must be a positive number');
     }
-    // v0.30 / E5: depth query param walks N levels (default 1, hard cap 10).
+    // depth query param walks N levels (default 1, hard cap 10).
     const depthRaw = query.get('depth');
     let depth;
     if (depthRaw !== null) {
         const parsed = Number(depthRaw);
-        // L4 fold: reject out-of-range explicitly (no silent clamp).
+        // Reject out-of-range explicitly (no silent clamp).
         if (!Number.isInteger(parsed) || parsed < 1 || parsed > 10) {
             throw new HttpError(400, 'depth must be a positive integer between 1 and 10');
         }
@@ -260,7 +262,7 @@ export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
         drillExtra.depth = depth;
     const result = drillDown(ctx, drillMatch.id, { ...drillExtra, cost: drillCost });
     if ('failure' in result) {
-        // v1.6.4: leaf id maps to 422 (caller-actionable). Other cases stay
+        // Leaf id maps to 422 (caller-actionable). Other cases stay
         // as 404 to avoid leaking cross-tenant existence or scope grants.
         if (result.failure === 'not_drillable') {
             throw new HttpError(422, 'Id is a leaf row, not a level-2+ summary; nothing to drill into');
@@ -277,7 +279,7 @@ export async function handleDrillRecall({ req, res, opts, query }, drillMatch) {
 // (matches cmdContext); real-query hybrid search emits one 'recall' row.
 export async function handleGetContext({ req, res, opts, query }) {
     const q = query.get('q') ?? undefined;
-    // v1.11.5: DoS cap on q-param length. 1024 covers real multi-clause queries
+    // DoS cap on q-param length. 1024 covers real multi-clause queries
     // (pasted error messages, multi-stem searches) while bounding BM25
     // tokenisation cost (~150 tokens worst case at 1024 chars).
     if (q !== undefined && q.length > 1024) {
@@ -302,8 +304,8 @@ export async function handleGetContext({ req, res, opts, query }) {
     const pinnedOnlyRaw = query.get('pinned_only');
     const pinnedOnly = pinnedOnlyRaw === '1' || pinnedOnlyRaw === 'true';
     const scopeRaw = query.get('scope');
-    if (scopeRaw !== null && scopeRaw.length > 256) {
-        throw new HttpError(400, 'scope exceeds 256-character cap');
+    if (scopeRaw !== null && scopeRaw.length > MAX_ID_LEN) {
+        throw new HttpError(400, `scope exceeds ${MAX_ID_LEN}-character cap`);
     }
     const scope = scopeRaw === null ? undefined : scopeRaw;
     const includeRecentRaw = query.get('include_recent');
@@ -330,7 +332,7 @@ export async function handleGetContext({ req, res, opts, query }) {
         scope,
         includeRecent,
         crossProject,
-        currentProject: resolveProjectIdentity(dirname(resolve(opts.hippoRoot))).name,
+        currentProject: resolveProjectIdentity(dirname(resolve(opts.hippoRoot))),
         cost: contextCost('markdown', 'observe'), // clients render; the budget prices the block `hippo context` would print
     });
     recordTokens(ctx, 'http_context', { items: result.entries.length, tokens: result.tokens });

package/dist/server/routes/skills.js

@@ -1,10 +1,11 @@
 // /v1/skills routes.
-import { closeSkill, exportSkills, loadSkillById, loadSkills, saveSkill, VALID_SKILL_STATES } from '../../skills.js';
+import { closeSkill, exportSkills, loadSkillById, loadSkills, MAX_SKILL_NAME_LEN, saveSkill, VALID_SKILL_STATES } from '../../skills.js';
 import { HttpError, sendJson } from '../../http-util.js';
 import { buildContextWithAuth } from '../auth.js';
 import { byCreatedAt, pageOf, parseCursor } from '../cursor.js';
-import { isJsonString, isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
-// ── skills (E2 first-class object, executable/exportable) ──
+import { isSetMember, parseJsonBody, parseListLimit } from '../validation.js';
+import { isJsonString } from '../../json.js';
+// ── skills (first-class object, executable/exportable) ──
 //
 // 6 routes: POST /v1/skills (new; body skillName + instructions + trigger?),
 // GET /v1/skills (list, status filter; shared parseListLimit), GET
@@ -23,8 +24,8 @@ export async function handleCreateSkill({ req, res, opts }) {
     if (!isJsonString(skillName) || skillName.trim().length === 0) {
         throw new HttpError(400, 'skillName is required (non-empty string)');
     }
-    if (skillName.length > 256) {
-        throw new HttpError(400, 'skillName exceeds 256-character cap');
+    if (skillName.length > MAX_SKILL_NAME_LEN) {
+        throw new HttpError(400, `skillName exceeds ${MAX_SKILL_NAME_LEN}-character cap`);
     }
     const instructions = body['instructions'];
     if (!isJsonString(instructions) || instructions.trim().length === 0) {

package/dist/server/types.d.ts

@@ -3,7 +3,7 @@ export interface ServerHandle {
     port: number;
     url: string;
     stop: () => Promise<void>;
-    /** Introspection-only (v1.26.2): the underlying node:http Server, exposed so
+    /** Introspection-only: the underlying node:http Server, exposed so
      *  tests can assert keep-alive/headers timeout hardening without reaching
      *  into serve()'s closure. Additive field — do not depend on it for control
      *  flow outside tests. */

package/dist/server/validation.d.ts

@@ -1,7 +1,6 @@
 import type { IncomingMessage } from 'node:http';
 import type { Context } from '../api.js';
-import { type JsonValue } from '../http-util.js';
-export declare function isJsonString(value: JsonValue | undefined): value is string;
+import { type JsonValue } from '../json.js';
 export declare function isJsonNumber(value: JsonValue | undefined): value is number;
 export declare function isJsonBoolean(value: JsonValue | undefined): value is boolean;
 export declare function isSetMember<T extends string>(set: ReadonlySet<T>, value: string): value is T;

package/dist/server/validation.js

@@ -1,7 +1,5 @@
-import { HttpError, isJsonObjectRecord, readBody } from '../http-util.js';
-export function isJsonString(value) {
-    return typeof value === 'string';
-}
+import { HttpError, isJsonObjectRecord, MAX_ID_LEN, readBody } from '../http-util.js';
+import { isJsonString } from '../json.js';
 export function isJsonNumber(value) {
     return typeof value === 'number';
 }
@@ -21,13 +19,8 @@ export function isSetMember(set, value) {
     // performs the actual narrowing for callers.
     return set.has(value);
 }
-// Parse a `?limit=` query param for the E2 list routes. Defaults to 100; requires
-// a positive INTEGER <= 1000. Number.isInteger rejects fractional values like
-// "1.5" that Number.isFinite would pass but SQLite `LIMIT ?` rejects with a
-// datatype mismatch (a 500). Shared across the decision/incident/process/policy
-// list routes so the guard cannot drift (codex review 2026-05-30 P2: fractional
-// limit reached SQLite on the policy route; the same latent hole existed in the
-// sibling routes this was copied from).
+// Number.isInteger, not isFinite: SQLite `LIMIT ?` rejects "1.5" with a 500.
+// Shared by every first-class-object list route so the guard cannot drift.
 export function parseListLimit(limitRaw, defaultLimit = 100, maxLimit = 1000) {
     if (limitRaw === null)
         return defaultLimit;
@@ -68,7 +61,7 @@ export function getStringArray(obj, key) {
     return v;
 }
 /**
- * v1.6.4: charset + length validation for `:id` route captures. Routes call
+ * Charset + length validation for `:id` route captures. Routes call
  * this immediately after `matchPath` to reject empty / overlong / illegal
  * ids with a useful 400 instead of silently falling through to "not found".
  *
@@ -82,8 +75,8 @@ const ID_SEGMENT_RE = /^[A-Za-z0-9_:.\-]+$/;
 export function validateIdSegment(id, fieldName) {
     if (id.length === 0)
         throw new HttpError(400, `${fieldName} is required`);
-    if (id.length > 256)
-        throw new HttpError(400, `${fieldName} exceeds 256-character cap`);
+    if (id.length > MAX_ID_LEN)
+        throw new HttpError(400, `${fieldName} exceeds ${MAX_ID_LEN}-character cap`);
     if (!ID_SEGMENT_RE.test(id)) {
         throw new HttpError(400, `${fieldName} contains invalid characters; allowed: A-Z a-z 0-9 _ : . -`);
     }

package/dist/server-detect.js

@@ -23,33 +23,8 @@ const HEALTH_BODY_MAX_BYTES = 64 * 1024;
  * with any other host is malformed or forged and must not be probed.
  */
 const PIDFILE_LOOPBACK_HOSTS = new Set(['127.0.0.1', '::1', 'localhost']);
-/**
- * Read .hippo/server.pid and return the embedded ServerInfo if a live hippo
- * server is genuinely answering on the recorded url. Returns null on missing,
- * malformed, or stale pidfiles, and best-effort unlinks the file in the
- * stale/malformed cases.
- *
- * Liveness is proven in two steps. `process.kill(pid, 0)` rules out dead
- * pids. But a pid can be reused by an unrelated process, so a GET /health
- * then confirms the process that answers is *this* hippo server: its
- * `started_at` must equal the pidfile's. A mismatch, non-200, malformed
- * body, or timeout all mean the pidfile is stale.
- *
- * The /health probe runs only when a pidfile exists and the pid is live, so
- * the common no-server path stays a single fast file existence check.
- */
-export async function detectServer(hippoRoot) {
-    const path = join(hippoRoot, PIDFILE);
-    if (!existsSync(path))
-        return null;
-    let info;
-    try {
-        info = JSON.parse(readFileSync(path, 'utf8'));
-    }
-    catch {
-        removePidfile(hippoRoot);
-        return null;
-    }
+/** False when the pidfile's pid is dead or its url could not be one serve() wrote. */
+function isLiveLoopbackTarget(info) {
     // Probe the process. Sending signal 0 throws if the pid is dead or owned
     // by another user we cannot signal. Either way, treat as stale.
     // Node's process.kill(pid, 0) is implemented on Windows via OpenProcess +
@@ -58,8 +33,7 @@ export async function detectServer(hippoRoot) {
         process.kill(info.pid, 0);
     }
     catch {
-        removePidfile(hippoRoot);
-        return null;
+        return false;
     }
     // The pid is live, but it may have been reused by an unrelated process, and
     // the recorded url is read from a file anyone could forge. serve() only ever
@@ -71,15 +45,37 @@ export async function detectServer(hippoRoot) {
         probeUrl = new URL(info.url);
     }
     catch {
-        removePidfile(hippoRoot);
-        return null;
+        return false;
     }
-    if (probeUrl.protocol !== 'http:' ||
-        !PIDFILE_LOOPBACK_HOSTS.has(probeUrl.hostname) ||
-        probeUrl.port !== String(info.port)) {
-        removePidfile(hippoRoot);
-        return null;
+    return (probeUrl.protocol === 'http:' &&
+        PIDFILE_LOOPBACK_HOSTS.has(probeUrl.hostname.replace(/^\[(.*)\]$/, '$1')) &&
+        probeUrl.port === String(info.port));
+}
+/** The whole body as text, or null once it passes HEALTH_BODY_MAX_BYTES (the stream is then cancelled). */
+async function readCappedBody(body) {
+    // Read the body under a hard byte cap. The process answering on info.url
+    // may not be hippo (pid reuse is the case this probe guards against), so
+    // its response is untrusted: never hand an unbounded stream to a parser.
+    const reader = body.getReader();
+    const decoder = new TextDecoder();
+    let raw = '';
+    let received = 0;
+    for (;;) {
+        const { done, value } = await reader.read();
+        if (done)
+            break;
+        received += value.byteLength;
+        if (received > HEALTH_BODY_MAX_BYTES) {
+            await reader.cancel();
+            return null;
+        }
+        raw += decoder.decode(value, { stream: true });
     }
+    raw += decoder.decode();
+    return raw;
+}
+/** True when /health on info.url reports the pidfile's started_at; unlinks the pidfile on any definitive mismatch. */
+async function healthMatchesPidfile(hippoRoot, info) {
     // Confirm the process answering on info.url is this hippo server by matching
     // the /health `started_at` against the pidfile. A connection refusal, a
     // non-200, or a malformed body unlink the pidfile as stale. A probe timeout
@@ -92,33 +88,19 @@ export async function detectServer(hippoRoot) {
         });
         if (!res.ok || !res.body) {
             removePidfile(hippoRoot);
-            return null;
+            return false;
         }
-        // Read the body under a hard byte cap. The process answering on info.url
-        // may not be hippo (pid reuse is the case this probe guards against), so
-        // its response is untrusted: never hand an unbounded stream to a parser.
-        const reader = res.body.getReader();
-        const decoder = new TextDecoder();
-        let raw = '';
-        let received = 0;
-        for (;;) {
-            const { done, value } = await reader.read();
-            if (done)
-                break;
-            received += value.byteLength;
-            if (received > HEALTH_BODY_MAX_BYTES) {
-                await reader.cancel();
-                removePidfile(hippoRoot);
-                return null;
-            }
-            raw += decoder.decode(value, { stream: true });
+        const raw = await readCappedBody(res.body);
+        if (raw === null) {
+            removePidfile(hippoRoot);
+            return false;
         }
-        raw += decoder.decode();
         const body = JSON.parse(raw);
         if (body.started_at !== info.started_at) {
             removePidfile(hippoRoot);
-            return null;
+            return false;
         }
+        return true;
     }
     catch (err) {
         // A timeout is ambiguous (the server may be alive but busy), so keep the
@@ -129,9 +111,41 @@ export async function detectServer(hippoRoot) {
         if (err?.name !== 'TimeoutError') {
             removePidfile(hippoRoot);
         }
+        return false;
+    }
+}
+/**
+ * Read .hippo/server.pid and return the embedded ServerInfo if a live hippo
+ * server is genuinely answering on the recorded url. Returns null on missing,
+ * malformed, or stale pidfiles, and best-effort unlinks the file in the
+ * stale/malformed cases.
+ *
+ * Liveness is proven in two steps. `process.kill(pid, 0)` rules out dead
+ * pids. But a pid can be reused by an unrelated process, so a GET /health
+ * then confirms the process that answers is *this* hippo server: its
+ * `started_at` must equal the pidfile's. A mismatch, non-200, malformed
+ * body, or timeout all mean the pidfile is stale.
+ *
+ * The /health probe runs only when a pidfile exists and the pid is live, so
+ * the common no-server path stays a single fast file existence check.
+ */
+export async function detectServer(hippoRoot) {
+    const path = join(hippoRoot, PIDFILE);
+    if (!existsSync(path))
+        return null;
+    let info;
+    try {
+        info = JSON.parse(readFileSync(path, 'utf8'));
+    }
+    catch {
+        removePidfile(hippoRoot);
+        return null;
+    }
+    if (!isLiveLoopbackTarget(info)) {
+        removePidfile(hippoRoot);
         return null;
     }
-    return info;
+    return (await healthMatchesPidfile(hippoRoot, info)) ? info : null;
 }
 /**
  * Atomically write the pidfile. Writes to a process-scoped temp file then

package/dist/server.d.ts

@@ -10,8 +10,8 @@ export type { AuthResolver, ResolvedBearer, ServeOpts, ServerHandle } from './se
 /**
  * Boot the HTTP daemon on host:port and write the pidfile under hippoRoot.
  *
- * Refuses non-loopback hosts at boot (Footgun #3 from the A1 plan) unless
- * HIPPO_REQUIRE_AUTH=1 is set. The A5 v2 auth middleware (buildContextWithAuth /
+ * Refuses non-loopback hosts at boot unless
+ * HIPPO_REQUIRE_AUTH=1 is set. The auth middleware (buildContextWithAuth /
  * requireAuth) has shipped and every route checks it except GET /health
  * (public by design for platform health checks) and the two connector
  * webhooks in PUBLIC_ROUTES, which are HMAC-gated by their own signing