hippo-memory 1.70.0 → 1.71.0

package/dist/cli/serve.js

@@ -1,18 +1,20 @@
 // Long-running verbs: `hippo dashboard`, `hippo mcp` and `hippo serve`.
 import { installCrashHandlers } from '../util/crash-handlers.js';
-import { envPort, envRequireAuth, envTlsCert, envTlsKey } from '../util/env.js';
+import { envAllowKeylessLocal, envPort, envRequireAuth, envTlsCert, envTlsKey } from '../util/env.js';
 import * as fs from 'fs';
 import * as path from 'path';
 import { printError } from './output.js';
 import { stringFlagOrExit, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { errorMessage } from '../util/log.js';
+import { CliExit } from './exit.js';
+import { DEFAULT_SERVER_HOST, DEFAULT_SERVER_PORT } from '../server/defaults.js';
 export async function handleDashboard({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     const port = parseInt(String(flags['port'] ?? '3333'), 10);
     const { serveDashboard } = await import('../dashboard/dashboard.js');
-    serveDashboard(hippoRoot, port);
-    // A busy port or a later throw ends in one log line and exit 1, as it does for serve and mcp.
+    serveDashboard(hippoRoot, port, undefined, { handleSignals: true });
+    // A later throw ends in one log line and exit 1, as it does for serve and mcp; a busy port is reported by the dashboard itself.
     installCrashHandlers('dashboard');
     await new Promise(() => { }); // run until Ctrl+C
 }
@@ -35,33 +37,40 @@ function readTlsFiles(flags) {
         return undefined;
     if (certPath === undefined || keyPath === undefined) {
         printError('hippo serve: TLS needs both a certificate and a key: --tls-cert and --tls-key, or HIPPO_TLS_CERT and HIPPO_TLS_KEY.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     try {
         return { cert: fs.readFileSync(certPath), key: fs.readFileSync(keyPath) };
     }
     catch (err) {
         printError(`hippo serve: cannot read the TLS files: ${errorMessage(err)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
 }
+/** Said at every start, so the key rule is a choice an operator sees, and an upgrade that changed it explains itself. */
+function keyRuleLine() {
+    if (envRequireAuth())
+        return 'every request needs an API key (HIPPO_REQUIRE_AUTH=1)';
+    if (envAllowKeylessLocal()) {
+        return 'requests from this machine need no API key and act as host admin (HIPPO_ALLOW_KEYLESS_LOCAL=1); unset it to require a key on every request';
+    }
+    return 'every request needs an API key: mint one with `hippo auth create` and send it as "Authorization: Bearer <key>" ' +
+        '(the hippo CLI reads HIPPO_API_KEY). To let requests from this machine in without a key, start with HIPPO_ALLOW_KEYLESS_LOCAL=1';
+}
 export async function handleServe({ hippoRoot, flags }) {
     requireInit(hippoRoot);
-    const portRaw = flags['port'] ?? envPort() ?? '6789';
+    const portRaw = flags['port'] ?? envPort() ?? DEFAULT_SERVER_PORT;
     const port = Number(portRaw);
     if (!Number.isFinite(port) || port < 0) {
         printError(`Invalid --port: ${String(portRaw)}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const host = stringFlag(flags, 'host') ?? '127.0.0.1';
+    const host = stringFlag(flags, 'host') ?? DEFAULT_SERVER_HOST;
     const tls = readTlsFiles(flags);
     const { serve } = await import('../server.js');
     const handle = await serve({ hippoRoot, port, host, handleSignals: true, tls });
     console.log(`hippo serve listening on ${handle.url} (pid ${process.pid})`);
-    // Said at every start: the no-key local fallback is a default an operator should choose, not discover.
-    if (!envRequireAuth()) {
-        console.log('local requests need no API key and act as host admin; set HIPPO_REQUIRE_AUTH=1 to require a key on every request');
-    }
+    console.log(keyRuleLine());
     console.log(`pidfile: ${path.join(hippoRoot, 'server.pid')}`);
     console.log('press Ctrl+C to stop');
     // The SIGINT/SIGTERM handlers stop the server and exit. Hang until then.

package/dist/cli/session-hooks.d.ts

@@ -1,26 +1,18 @@
 import { type CliFlags, type CommandContext } from './flag-values.js';
-/**
- * SessionEnd entry point. Claude Code / OpenCode fire this on /exit while
- * tearing down the TUI, which kills any child that is still running when
- * the parent returns. Running sleep + capture synchronously here means both
- * get SIGTERM'd mid-consolidation.
- *
- * So we do the minimum inline (read stdin for transcript_path), then spawn
- * a fully detached Node child that runs sleep → capture and exit the parent
- * immediately. The child writes to the log file and survives TUI teardown;
- * the next SessionStart reads the log via `hippo last-sleep`.
- */
-export declare function cmdSessionEnd(hippoRoot: string, flags: CliFlags): Promise<void>;
-export declare function cmdSessionEndWorker(hippoRoot: string, flags: CliFlags): Promise<void>;
+/** SessionEnd entry: TUI teardown kills children still running, so read stdin inline, spawn a detached child that runs sleep then capture, and exit.
+ * The child logs to a file that the next SessionStart reads via `hippo last-sleep`. */
+export declare function handleSessionEnd({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
+export declare function handleSessionEndWorker({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 /** Quotes one cmd.exe argument; each `%` leaves the quotes as `^%`, so no %NAME% pair can expand. */
 export declare function quoteCmdArg(arg: string): string;
 /** cmd.exe arguments that run a .cmd or .bat shim with every forwarded argument delivered verbatim. */
 export declare function cmdShimArgs(shimPath: string, forwardArgs: readonly string[]): string[];
-export declare function cmdCodexRun(hippoRoot: string, args: string[]): void;
-export declare function cmdCodexSessionEndWorker(hippoRoot: string, flags: CliFlags): Promise<void>;
+export declare function handleCodexRun({ hippoRoot, tenantId, args }: CommandContext): void;
+export declare function cmdCodexSessionEndWorker(hippoRoot: string, tenantId: string, flags: CliFlags): Promise<void>;
+export declare function handleCodexSessionEndWorker({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 export declare function handlePreCompact({ hippoRoot, flags }: CommandContext): Promise<void>;
 export declare function handlePostCompact({ hippoRoot, flags }: CommandContext): Promise<void>;
-export declare function handleCaptureError({ hippoRoot, flags }: CommandContext): Promise<void>;
-export declare function handleCompactResume({ hippoRoot }: CommandContext): Promise<void>;
-export declare function handleCapture({ hippoRoot, flags }: CommandContext): Promise<void>;
+export declare function handleCaptureError({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
+export declare function handleCompactResume({ hippoRoot, tenantId }: CommandContext): Promise<void>;
+export declare function handleCapture({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=session-hooks.d.ts.map

package/dist/cli/session-hooks.js

@@ -9,14 +9,13 @@ import { isInitialized } from '../store/open.js';
 import { loadActiveTaskSnapshot, loadFreshActiveTaskSnapshot, closeTaskSnapshotsForSession, listSessionEvents, } from '../store/sessions.js';
 import { writeSessionEndHandoff } from '../store/handoffs.js';
 import { readSessionScan, recordSessionDigest } from '../capture/session-digest.js';
-import { openHippoDb, closeHippoDb } from '../db/index.js';
 import { captureToolFailure } from '../capture/capture-error.js';
 import { readApiCalls, recordRereads, } from '../store/token-ledger.js';
 import { estimateTokens } from '../util/token-text.js';
 import { currentMachine, importSessionFolder } from '../agent-memories/sync.js';
 import { summaryLine } from '../agent-memories/report.js';
 import { resolveProjectIdentity } from '../core/project-identity.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { cmdCapture } from '../capture/command.js';
 import { cmdPreCompact, cmdPostCompact } from '../capture/compact.js';
 import { transcriptWorkingState } from '../capture/working-state.js';
@@ -30,7 +29,6 @@ import { truncateCodePointSafe } from '../util/transcript-tail.js';
 import { COMPACTION_DB_WAIT_MS } from '../capture/compaction-record.js';
 import { COMPACT_RESUME_EVENT_CONTENT_CAP, COMPACT_RESUME_MAX_AGE_MS, compactResumeText } from '../api/context-render.js';
 import { normaliseHookPayload, readHookStdin, readStdinBounded } from './stdin.js';
-import { resolveTenantId } from '../store/tenant.js';
 import { errorMessage, log } from '../util/log.js';
 import { bookLedgerTurn } from '../api/ledger-db.js';
 import { flushDeliveryRecorder } from '../api/prompt-hook.js';
@@ -38,26 +36,17 @@ import { printError } from './output.js';
 import { cmdLastSleep } from './last-sleep.js';
 import { readCompactResumePayload } from './compact-resume-payload.js';
 import { boolFlag, flagIsTrue, stringFlag } from './flag-values.js';
-import { logSessionEndImport, appendSessionEndCloseLog, resetHookInjection, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, startDeliveryRecorder } from './hook-runtime.js';
-/**
- * SessionStart(compact) injector. Prints the active task snapshot + recent
- * session trail so working state that would otherwise be lost to
- * compaction summarisation survives into the new context window. No pinned
- * memories here — the UserPromptSubmit hook already re-injects those every
- * turn, so duplicating them here would double token cost for nothing.
- *
- * Same exit-0/crash-safety contract as `hippo pre-compact`: every path
- * exits 0. A malformed payload or a store read failure
- * degrades to empty stdout, never a thrown error — a failing SessionStart
- * hook must not pollute session startup.
- */
-function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
+import { logSessionEndImport, appendSessionEndCloseLog, reportSessionEndFailure, resetHookInjection, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, startDeliveryRecorder, } from './hook-runtime.js';
+import { CliExit } from './exit.js';
+/** SessionStart(compact) injector: prints the task snapshot and session trail lost to compaction; no pinned memories (UserPromptSubmit re-injects them).
+ * Every path exits 0: a malformed payload or store read failure degrades to empty stdout, never a throw. */
+function cmdCompactResume(hippoRoot, tenantId, stdinText, stdinTimedOut) {
     let rec = null;
     try {
         // Gate on the non-exiting isInitialized check first: the store reads below call initStore, which would
         // silently create a store in a project that never ran `hippo init`, and this hook fires globally.
         if (!isInitialized(hippoRoot)) {
-            process.exit(0);
+            throw new CliExit(0);
         }
         const payloadState = readCompactResumePayload(stdinText, stdinTimedOut);
         let suppressOutput = payloadState.suppressOutput;
@@ -65,23 +54,24 @@ function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
         if (payloadState.boundary)
             rec = startDeliveryRecorder(hippoRoot, stdinText, 'claude-code', 'compact-resume');
         // A compaction follows a prompt or SessionStart that booked the arm, so this only reads it.
-        if (!suppressOutput && payloadSessionId !== null && inPilotHoldout(hippoRoot, resolveTenantId({}), payloadSessionId, false)) {
+        if (!suppressOutput && payloadSessionId !== null && inPilotHoldout(hippoRoot, tenantId, payloadSessionId, false)) {
             suppressOutput = true;
             rec?.disabled();
         }
         if (!suppressOutput)
-            restoreCompactSnapshot(hippoRoot, payloadSessionId, rec);
+            restoreCompactSnapshot(hippoRoot, tenantId, payloadSessionId, rec);
     }
     catch (err) {
+        if (err instanceof CliExit)
+            throw err;
         // Empty stdout on any store error, never a crashed SessionStart; the reason goes to stderr, which the model never sees.
         log.warn(`hippo compact-resume: skipped: ${errorMessage(err)}`);
     }
     // A no-op when the token ledger's handle already wrote the row; exit would drop it otherwise.
     flushDeliveryRecorder(rec);
-    process.exit(0);
+    throw new CliExit(0);
 }
-function restoreCompactSnapshot(hippoRoot, payloadSessionId, rec) {
-    const tenantId = resolveTenantId({});
+function restoreCompactSnapshot(hippoRoot, tenantId, payloadSessionId, rec) {
     const snapshot = loadFreshActiveTaskSnapshot(hippoRoot, tenantId, { maxAgeMs: COMPACT_RESUME_MAX_AGE_MS });
     // Concurrent sessions must not cross-restore. Only suppress when BOTH ids are present and differ;
     // either side missing, or a manual invocation with no payload session_id, still prints.
@@ -115,18 +105,9 @@ function restoreCompactSnapshot(hippoRoot, payloadSessionId, rec) {
         delivery: (write) => flushDeliveryRecorder(rec, write),
     });
 }
-/**
- * SessionEnd entry point. Claude Code / OpenCode fire this on /exit while
- * tearing down the TUI, which kills any child that is still running when
- * the parent returns. Running sleep + capture synchronously here means both
- * get SIGTERM'd mid-consolidation.
- *
- * So we do the minimum inline (read stdin for transcript_path), then spawn
- * a fully detached Node child that runs sleep → capture and exit the parent
- * immediately. The child writes to the log file and survives TUI teardown;
- * the next SessionStart reads the log via `hippo last-sleep`.
- */
-export async function cmdSessionEnd(hippoRoot, flags) {
+/** SessionEnd entry: TUI teardown kills children still running, so read stdin inline, spawn a detached child that runs sleep then capture, and exit.
+ * The child logs to a file that the next SessionStart reads via `hippo last-sleep`. */
+export async function handleSessionEnd({ hippoRoot, tenantId, flags }) {
     const runtime = hookRuntime(flags);
     const turn = flagIsTrue(flags, 'turn');
     // Copilot's hook command carries no path, since one quoted into it would need escaping for each shell; the log goes where the hook table used to point.
@@ -141,6 +122,8 @@ export async function cmdSessionEnd(hippoRoot, flags) {
     // Before the spawn, since the worker finds its store from the folder it inherits.
     const root = payloadCwdRoot(hippoRoot, stdinText, runtime);
     const input = stop ?? sessionEndInput(stdinText, raw.timedOut, runtime);
+    // Only a host payload ends a session: a manual run and a reply's end (turn mode) are not boundaries.
+    const rec = !turn && input !== null && !input.manual ? startDeliveryRecorder(hookStoreRoot(root), stdinText, runtime, 'session-end') : null;
     const sessionId = input?.sessionId ?? null;
     // Resolved here because only this process saw the payload; the worker captures just the path it is handed.
     // Always a hook, so never scan: an empty stdin here is not a manual run. The Copilot CLI's sessionEnd names no transcript, so its log is found by id.
@@ -159,9 +142,16 @@ export async function cmdSessionEnd(hippoRoot, flags) {
             flags['transcript'] = transcriptPath;
         if (sessionId)
             flags['session-id'] = sessionId;
-        await cmdSessionEndWorker(root, flags);
+        try {
+            await cmdSessionEndWorker(root, tenantId, flags);
+        }
+        finally {
+            await runHookWithStores(() => flushDeliveryRecorder(rec));
+        }
         return;
     }
+    // After the spawn, so a locked store delays only the row; the hook's short lock wait bounds it.
+    await runHookWithStores(() => flushDeliveryRecorder(rec));
 }
 /** What the session-end payload named; null for one hippo refuses or one that never arrived, and the worker then runs with neither value. */
 function sessionEndInput(stdinText, timedOut, runtime) {
@@ -198,15 +188,18 @@ function vscodeStopInput(raw) {
     const receipt = readVscodeStop(raw.text, raw.timedOut);
     return receipt.status === 'received' && receipt.input.sessionId !== null && SESSION_ID_RE.test(receipt.input.sessionId) ? receipt.input : null;
 }
-export async function cmdSessionEndWorker(hippoRoot, flags) {
+async function cmdSessionEndWorker(hippoRoot, tenantId, flags) {
     const sessionId = flags['session-id'];
-    await runSessionWorker(isStringValue(sessionId) ? sessionId : null, flagIsTrue(flags, 'turn') ? 'turn' : 'full', (mode) => sessionEndWork(hippoRoot, flags, mode));
+    await runSessionWorker(isStringValue(sessionId) ? sessionId : null, flagIsTrue(flags, 'turn') ? 'turn' : 'full', (mode) => sessionEndWork(hippoRoot, tenantId, flags, mode));
+}
+export function handleSessionEndWorker({ hippoRoot, tenantId, flags }) {
+    return cmdSessionEndWorker(hippoRoot, tenantId, flags);
 }
-async function sessionEndWork(hippoRoot, flags, mode) {
+async function sessionEndWork(hippoRoot, tenantId, flags, mode) {
     const transcriptPath = stringFlag(flags, 'transcript');
     const closeLogFile = stringFlag(flags, 'log-file') ?? null;
     const closeSessionId = stringFlag(flags, 'session-id') ?? null;
-    const rereadLog = await bookSessionRereads(hippoRoot, transcriptPath, closeSessionId)
+    const rereadLog = await bookSessionRereads(hippoRoot, tenantId, transcriptPath, closeSessionId)
         .catch((err) => [`re-read count failed: ${errorMessage(err)}`]);
     // Sleep starts the log file afresh, so the lines go in after it; on exit too, in case sleep exits the process.
     const flushRereadLog = () => { for (const line of rereadLog.splice(0))
@@ -220,38 +213,37 @@ async function sessionEndWork(hippoRoot, flags, mode) {
         return;
     }
     if (mode === 'turn' && closeSessionId)
-        await sleepIfDue(hippoRoot, flags, closeLogFile, transcriptPath, closeSessionId);
+        await sleepIfDue(hippoRoot, tenantId, flags, closeLogFile, transcriptPath, closeSessionId);
     else
-        await sleepProjectStore(hippoRoot, flags, closeLogFile, transcriptPath);
+        await sleepProjectStore(hippoRoot, tenantId, flags, closeLogFile, transcriptPath);
     flushRereadLog();
     const digestLog = (message) => appendSessionEndCloseLog(closeLogFile, message);
     const scan = transcriptPath ? readSessionScan(transcriptPath, digestLog) : null;
-    const capture = (turns) => captureEndedSession(hippoRoot, store, flags, transcriptPath, turns);
+    const capture = (turns) => captureEndedSession(hippoRoot, tenantId, store, flags, transcriptPath, turns);
     if (mode === 'turn')
         captureNewTurns(transcriptPath, closeSessionId, scan, capture, digestLog);
     else
         capture(scan?.turns);
     recordSessionDigest(hippoRoot, scan, {
         key: closeSessionId || path.basename(transcriptPath ?? '', '.jsonl'),
-        tenantId: resolveTenantId({}),
+        tenantId,
         log: digestLog,
     });
-    // Close only this session's snapshot, after sleep+capture: no snapshot producer runs in session-end, and since
-    // session-end may never fire (crash, kill -9) the freshness bound in loadFreshActiveTaskSnapshot is the backstop.
-    // The handoff is written first, while the snapshot writeSessionEndHandoff reads is still active.
+    // Close only this session's snapshot, after sleep+capture; if session-end never fires (crash, kill -9) the freshness bound in
+    // loadFreshActiveTaskSnapshot is the backstop. The handoff is written first, while the snapshot writeSessionEndHandoff reads is active.
     if (closeSessionId)
-        writeEndHandoff(store, closeSessionId, transcriptPath, closeLogFile, mode === 'turn');
+        writeEndHandoff(store, tenantId, closeSessionId, transcriptPath, closeLogFile, mode === 'turn');
     if (mode === 'turn') {
         // The chat goes on after a reply, so its snapshot stays for the next compaction to restore.
         appendSessionEndCloseLog(closeLogFile, 'skip snapshot close: turn mode');
         return;
     }
-    closeEndedSessionSnapshot(store, closeSessionId, closeLogFile);
+    closeEndedSessionSnapshot(store, tenantId, closeSessionId, closeLogFile);
 }
-function closeEndedSessionSnapshot(store, closeSessionId, closeLogFile) {
+function closeEndedSessionSnapshot(store, tenantId, closeSessionId, closeLogFile) {
     try {
         if (closeSessionId) {
-            const closed = closeTaskSnapshotsForSession(store, resolveTenantId({}), closeSessionId);
+            const closed = closeTaskSnapshotsForSession(store, tenantId, closeSessionId);
             appendSessionEndCloseLog(closeLogFile, `closed ${closed} active snapshot(s) for session ${closeSessionId}`);
         }
         else {
@@ -262,15 +254,15 @@ function closeEndedSessionSnapshot(store, closeSessionId, closeLogFile) {
         appendSessionEndCloseLog(closeLogFile, `snapshot close failed: ${errorMessage(err)}`);
     }
 }
-async function sleepProjectStore(hippoRoot, flags, closeLogFile, transcriptPath) {
+async function sleepProjectStore(hippoRoot, tenantId, flags, closeLogFile, transcriptPath) {
     // Sleeping the global store from here would learn this folder's git commits into it; it has its own daily sleep.
     if (isInitialized(hippoRoot)) {
         try {
-            await (await import('./sleep.js')).cmdSleep(hippoRoot, flags);
+            await (await import('./sleep.js')).cmdSleep(hippoRoot, tenantId, flags);
         }
         catch (err) {
-            // cmdSleep writes its failure line only when it has a log file, and capture runs regardless.
-            log.debug(`session-end: sleep failed: ${errorMessage(err)}`);
+            // cmdSleep writes its own failure line only once its log tee is open, and capture runs regardless.
+            reportSessionEndFailure(closeLogFile, 'session-end: sleep', err);
         }
     }
     else {
@@ -279,18 +271,18 @@ async function sleepProjectStore(hippoRoot, flags, closeLogFile, transcriptPath)
     }
 }
 /** A close after every reply sleeps only at the MCP server's auto-sleep threshold; each line starts the log afresh, as a sleep does. */
-async function sleepIfDue(hippoRoot, flags, closeLogFile, transcriptPath, sessionId) {
+async function sleepIfDue(hippoRoot, tenantId, flags, closeLogFile, transcriptPath, sessionId) {
     if (!isInitialized(hippoRoot))
-        return sleepProjectStore(hippoRoot, flags, closeLogFile, transcriptPath);
+        return sleepProjectStore(hippoRoot, tenantId, flags, closeLogFile, transcriptPath);
     const prefix = `turn close, session ${sessionId}`;
     try {
-        const { enabled, count, threshold, due } = autoSleepDue(hippoRoot, resolveTenantId({}), loadConfig(hippoRoot).autoSleep);
+        const { enabled, count, threshold, due } = autoSleepDue(hippoRoot, tenantId, loadConfig(hippoRoot).autoSleep);
         if (!due) {
             const why = enabled ? `${count} new memories, threshold ${threshold}` : 'auto-sleep is off';
             appendSessionEndCloseLog(closeLogFile, `${prefix}: skip sleep, ${why}`, { startFresh: true });
             return;
         }
-        await sleepProjectStore(hippoRoot, flags, closeLogFile, transcriptPath);
+        await sleepProjectStore(hippoRoot, tenantId, flags, closeLogFile, transcriptPath);
         appendSessionEndCloseLog(closeLogFile, `${prefix}: ran sleep at ${count} new memories (threshold ${threshold})`);
     }
     catch (err) {
@@ -312,7 +304,7 @@ function captureNewTurns(transcriptPath, sessionId, scan, capture, log) {
         saveTurnPosition(sessionId, transcriptPath, scan.turns, log);
 }
 /** True when capture ran to the end, so a turn close may move its cursor past these turns. */
-function captureEndedSession(hippoRoot, store, flags, transcriptPath, turns) {
+function captureEndedSession(hippoRoot, tenantId, store, flags, transcriptPath, turns) {
     try {
         const logFile = stringFlag(flags, 'log-file');
         // With no stdin of its own, capture would read this as a manual run and scan every project.
@@ -326,7 +318,7 @@ function captureEndedSession(hippoRoot, store, flags, transcriptPath, turns) {
             logFile,
             dryRun: false,
             global: false,
-            tenantId: resolveTenantId({}),
+            tenantId,
             // In the global store, rows would otherwise read as user-global and show up in every project.
             originProject: store === hippoRoot ? undefined : resolveProjectIdentity(process.cwd()),
             sessionTurns: turns,
@@ -334,13 +326,12 @@ function captureEndedSession(hippoRoot, store, flags, transcriptPath, turns) {
         return true;
     }
     catch (err) {
-        log.debug(`session-end: capture failed: ${errorMessage(err)}`);
+        reportSessionEndFailure(stringFlag(flags, 'log-file') ?? null, 'session-end: capture', err);
         return false;
     }
 }
-function writeEndHandoff(store, closeSessionId, transcriptPath, closeLogFile, inPlace = false) {
+function writeEndHandoff(store, tenantId, closeSessionId, transcriptPath, closeLogFile, inPlace = false) {
     try {
-        const tenantId = resolveTenantId({});
         const ownSnapshot = loadActiveTaskSnapshot(store, tenantId)?.session_id === closeSessionId;
         // A never-compacted session has no snapshot; read even when it has one, as another session's PreCompact can take the slot before the write.
         const derived = transcriptPath
@@ -361,7 +352,7 @@ function writeEndHandoff(store, closeSessionId, transcriptPath, closeLogFile, in
     }
 }
 /** Books the ending session's re-reads in each store its ledger rows can land in (project and global); returns the log lines. */
-async function bookSessionRereads(hippoRoot, transcriptPath, sessionId) {
+async function bookSessionRereads(hippoRoot, tenantId, transcriptPath, sessionId) {
     if (!transcriptPath || !sessionId)
         return [];
     let read;
@@ -376,13 +367,7 @@ async function bookSessionRereads(hippoRoot, transcriptPath, sessionId) {
     let tokens = 0;
     for (const root of roots) {
         try {
-            const db = openHippoDb(root);
-            try {
-                tokens += recordRereads(db, resolveTenantId({}), sessionId, read.calls);
-            }
-            finally {
-                closeHippoDb(db);
-            }
+            tokens += recordRereads(root, tenantId, sessionId, read.calls);
         }
         catch (err) {
             lines.push(`re-read count failed: ${errorMessage(err)}`);
@@ -397,6 +382,7 @@ function loadCodexWrapperMetadata() {
     if (!fs.existsSync(metadataPath)) {
         throw new Error('Codex wrapper is not installed. Run `hippo hook install codex` first.');
     }
+    // SAFETY: the file is the one installCodexWrapper wrote; handleCodexRun reads only logFile and realCodexPath from it.
     return JSON.parse(fs.readFileSync(metadataPath, 'utf8'));
 }
 /** Quotes one cmd.exe argument; each `%` leaves the quotes as `^%`, so no %NAME% pair can expand. */
@@ -423,7 +409,7 @@ function spawnRealCodex(realCodexPath, forwardArgs, cwd) {
     }
     return spawn(realCodexPath, forwardArgs, { cwd, stdio: 'inherit', windowsHide: false });
 }
-export function cmdCodexRun(hippoRoot, args) {
+export function handleCodexRun({ hippoRoot, tenantId, args }) {
     const metadata = loadCodexWrapperMetadata();
     const startedAtMs = Date.now();
     // Codex reads CODEX_HOME at each launch, so resolve it now, not from the install-time metadata.
@@ -441,11 +427,11 @@ export function cmdCodexRun(hippoRoot, args) {
         process.exit(1);
     });
     child.on('exit', async (code, signal) => {
-        await launchCodexSessionEndWorker(hippoRoot, historyPath, startOffsetBytes, startedAtMs, metadata.logFile);
+        await launchCodexSessionEndWorker(hippoRoot, tenantId, historyPath, startOffsetBytes, startedAtMs, metadata.logFile);
         exitLikeChild(code, signal);
     });
 }
-async function launchCodexSessionEndWorker(hippoRoot, historyPath, startOffsetBytes, startedAtMs, logFile) {
+async function launchCodexSessionEndWorker(hippoRoot, tenantId, historyPath, startOffsetBytes, startedAtMs, logFile) {
     const workerArgs = [
         process.argv[1],
         '__codex-session-end-worker',
@@ -460,30 +446,40 @@ async function launchCodexSessionEndWorker(hippoRoot, historyPath, startOffsetBy
         '--log-file',
         logFile,
     ];
+    if (await detachedWorkerStarted(workerArgs))
+        return;
+    // Awaited so the sleep write can't be killed by the exit calls below.
     try {
-        const worker = spawn(process.execPath, workerArgs, {
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: true,
+        await cmdCodexSessionEndWorker(hippoRoot, tenantId, {
+            'codex-home': path.dirname(historyPath),
+            'history-path': historyPath,
+            'start-offset': String(startOffsetBytes),
+            'started-at': String(startedAtMs),
+            'log-file': logFile,
         });
-        worker.unref();
     }
-    catch (err) {
-        log.debug(`codex run: the session-end worker did not spawn, running inline: ${errorMessage(err)}`);
-        // Awaited so the sleep write can't be killed by the exit calls below.
+    catch (inlineErr) {
+        log.debug(`codex run: the inline session-end failed: ${errorMessage(inlineErr)}`);
+    }
+}
+/** Resolves true once the detached worker is running, false when the spawn fails, whether it throws or reports later. */
+function detachedWorkerStarted(workerArgs) {
+    return new Promise((resolve) => {
+        const failed = (reason) => {
+            log.debug(`codex run: the session-end worker did not spawn, running inline: ${reason}`);
+            resolve(false);
+        };
         try {
-            await cmdCodexSessionEndWorker(hippoRoot, {
-                'codex-home': path.dirname(historyPath),
-                'history-path': historyPath,
-                'start-offset': String(startOffsetBytes),
-                'started-at': String(startedAtMs),
-                'log-file': logFile,
-            });
+            const worker = spawn(process.execPath, workerArgs, { detached: true, stdio: 'ignore', windowsHide: true });
+            // An async spawn failure (ENOENT, EAGAIN) arrives as an 'error' event, which a try cannot catch.
+            worker.on('error', (err) => failed(err.message));
+            worker.once('spawn', () => resolve(true));
+            worker.unref();
         }
-        catch (inlineErr) {
-            log.debug(`codex run: the inline session-end failed: ${errorMessage(inlineErr)}`);
+        catch (err) {
+            failed(errorMessage(err));
         }
-    }
+    });
 }
 function exitLikeChild(code, signal) {
     if (signal) {
@@ -498,7 +494,7 @@ function exitLikeChild(code, signal) {
     }
     process.exit(code ?? 0);
 }
-export async function cmdCodexSessionEndWorker(hippoRoot, flags) {
+export async function cmdCodexSessionEndWorker(hippoRoot, tenantId, flags) {
     const logFile = stringFlag(flags, 'log-file');
     // Like the other hooks: project store, else global; a folder with neither must not get one made.
     const store = hookStoreRoot(hippoRoot);
@@ -506,17 +502,20 @@ export async function cmdCodexSessionEndWorker(hippoRoot, flags) {
         appendSessionEndCloseLog(logFile ?? null, 'skip: no hippo store for this folder or globally', { startFresh: true });
         return;
     }
-    await sleepCodexProjectStore(hippoRoot, logFile);
-    captureCodexTranscript(hippoRoot, store, flags, logFile);
+    await sleepCodexProjectStore(hippoRoot, tenantId, logFile);
+    captureCodexTranscript(hippoRoot, tenantId, store, flags, logFile);
+}
+export function handleCodexSessionEndWorker({ hippoRoot, tenantId, flags }) {
+    return cmdCodexSessionEndWorker(hippoRoot, tenantId, flags);
 }
-async function sleepCodexProjectStore(hippoRoot, logFile) {
+async function sleepCodexProjectStore(hippoRoot, tenantId, logFile) {
     // Sleeping the global store from here would learn this folder's git commits into it; it has its own daily sleep.
     if (isInitialized(hippoRoot)) {
         try {
-            await (await import('./sleep.js')).cmdSleep(hippoRoot, logFile ? { 'log-file': logFile } : {});
+            await (await import('./sleep.js')).cmdSleep(hippoRoot, tenantId, logFile ? { 'log-file': logFile } : {});
         }
         catch (err) {
-            log.debug(`codex session-end: sleep failed: ${errorMessage(err)}`);
+            reportSessionEndFailure(logFile ?? null, 'codex session-end: sleep', err);
         }
     }
     else {
@@ -524,7 +523,7 @@ async function sleepCodexProjectStore(hippoRoot, logFile) {
         logSessionEndImport(logFile ?? null, undefined);
     }
 }
-function captureCodexTranscript(hippoRoot, store, flags, logFile) {
+function captureCodexTranscript(hippoRoot, tenantId, store, flags, logFile) {
     try {
         const codexHome = stringFlag(flags, 'codex-home') ?? resolveCodexWrapperPaths().codexHome;
         const historyPath = stringFlag(flags, 'history-path') ?? path.join(codexHome, 'history.jsonl');
@@ -549,7 +548,7 @@ function captureCodexTranscript(hippoRoot, store, flags, logFile) {
             logFile,
             dryRun: false,
             global: false,
-            tenantId: resolveTenantId({}),
+            tenantId,
             originProject: store === hippoRoot ? undefined : resolveProjectIdentity(process.cwd()),
             sessionTurns: scan?.turns,
         };
@@ -557,13 +556,13 @@ function captureCodexTranscript(hippoRoot, store, flags, logFile) {
             cmdCapture(store, captureOpts);
         }
         catch (err) {
-            log.debug(`codex session-end: capture failed: ${errorMessage(err)}`);
+            reportSessionEndFailure(logFile ?? null, 'codex session-end: capture', err);
         }
         // The Codex wrapper passes no session id, so the rollout file names the session.
-        recordSessionDigest(hippoRoot, scan, { key: path.basename(transcriptPath, '.jsonl'), tenantId: resolveTenantId({}), log: digestLog });
+        recordSessionDigest(hippoRoot, scan, { key: path.basename(transcriptPath, '.jsonl'), tenantId, log: digestLog });
     }
     catch (err) {
-        log.debug(`codex session-end: transcript scan or digest failed: ${errorMessage(err)}`);
+        reportSessionEndFailure(logFile ?? null, 'codex session-end: transcript scan or digest', err);
     }
 }
 export async function handlePreCompact({ hippoRoot, flags }) {
@@ -596,7 +595,7 @@ export async function handlePostCompact({ hippoRoot, flags }) {
         stdinText: text,
         stdinTimedOut: timedOut,
         logFile: logFlag === true || logFlag === false || Array.isArray(logFlag) ? undefined : logFlag,
-        // Passed in, since capture.ts importing the sync would close an import cycle.
+        // Passed in, since src/capture/ importing the sync would close an import cycle.
         afterSave: (transcriptPath, cwd, log) => {
             const report = importSessionFolder(store, transcriptPath, cwd, { machine: currentMachine(), busyWaitMs: COMPACTION_DB_WAIT_MS });
             const summary = summaryLine(report);
@@ -609,7 +608,7 @@ export async function handlePostCompact({ hippoRoot, flags }) {
     if (line !== null && line !== undefined)
         console.log(line);
 }
-export async function handleCaptureError({ hippoRoot, flags }) {
+export async function handleCaptureError({ hippoRoot, tenantId, flags }) {
     // PostToolUseFailure hook: every path exits 0, and nothing is created
     // when no store exists (the hook fires in every directory).
     const { text } = await readHookStdin();
@@ -619,7 +618,7 @@ export async function handleCaptureError({ hippoRoot, flags }) {
         if (isInitialized(root) && payload) {
             // SAFETY: JSON.parse returns a JSON value by definition.
             const failure = JSON.parse(payload);
-            await runHookWithStores(() => captureToolFailure(root, resolveTenantId({}), failure));
+            await runHookWithStores(() => captureToolFailure(root, tenantId, failure));
         }
     }
     catch (err) {
@@ -627,14 +626,14 @@ export async function handleCaptureError({ hippoRoot, flags }) {
         log.warn(`failure capture skipped: ${errorMessage(err)}`);
     }
 }
-export async function handleCompactResume({ hippoRoot }) {
+export async function handleCompactResume({ hippoRoot, tenantId }) {
     const { text: stdinText, timedOut: stdinTimedOut } = await readHookStdin();
     await runHookWithStores(() => {
         resetHookInjection(hippoRoot, stdinText, 'compact');
-        cmdCompactResume(hookStoreRoot(hippoRoot), stdinText, stdinTimedOut);
+        cmdCompactResume(hookStoreRoot(hippoRoot), tenantId, stdinText, stdinTimedOut);
     });
 }
-export async function handleCapture({ hippoRoot, flags }) {
+export async function handleCapture({ hippoRoot, tenantId, flags }) {
     let captureSource = null;
     let captureFile;
     let transcriptPath;
@@ -655,10 +654,10 @@ export async function handleCapture({ hippoRoot, flags }) {
     }
     if (!captureSource) {
         printError('Usage: hippo capture --stdin|--file <path>|--last-session [--transcript <path>] [--log-file <path>] [--dry-run] [--global]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Bounded, and only when last-session has no explicit path: the
-    // --stdin source keeps its own blocking read in capture.ts by design.
+    // --stdin source keeps its own blocking read in src/capture/ by design.
     const bounded = captureSource === 'last-session' && !transcriptPath
         ? await readHookStdin()
         : { text: undefined, timedOut: false };
@@ -671,7 +670,7 @@ export async function handleCapture({ hippoRoot, flags }) {
         logFile: stringFlag(flags, 'log-file'),
         dryRun: boolFlag(flags, 'dry-run'),
         global: boolFlag(flags, 'global'),
-        tenantId: resolveTenantId({}),
+        tenantId,
     });
 }
 //# sourceMappingURL=session-hooks.js.map