hippo-memory 1.69.0 → 1.71.0

package/dist/cli/session-hooks.js

@@ -8,103 +8,70 @@ import { resolveJsonHookPaths } from '../hooks/json-hooks.js';
 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 '../session-digest.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { captureToolFailure } from '../capture-error.js';
-import { estimateTokens, isSubagentPayload, readApiCalls, recordRereads, recordTokenUse, } from '../token-ledger.js';
+import { readSessionScan, recordSessionDigest } from '../capture/session-digest.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 '../project-identity.js';
-import { getGlobalRoot } from '../shared.js';
+import { resolveProjectIdentity } from '../core/project-identity.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';
-import { collectHandoffEvidence } from '../handoff-evidence.js';
-import { resolveLastSessionTranscript } from '../capture/transcript.js';
+import { collectHandoffEvidence } from '../capture/handoff-evidence.js';
 import { copilotTranscriptFor, SESSION_ID_RE } from '../capture/copilot-transcript.js';
 import { loadTurnPosition, runSessionWorker, saveTurnPosition, turnsAfter } from '../capture/session-worker.js';
-import { isStringValue, readVscodeStop } from '../capture-contract.js';
-import { loadConfig } from '../config.js';
-import { countCreatedSinceLastSleep } from '../store/index-and-stats.js';
-import { truncateCodePointSafe } from '../transcript-tail.js';
-import { COMPACTION_DB_WAIT_MS } from '../compaction-record.js';
-import { COMPACT_RESUME_EVENT_CONTENT_CAP, COMPACT_RESUME_MAX_AGE_MS, compactResumeText } from '../context-render.js';
-import { normaliseHookPayload, readHookStdin, readStdinBounded } from '../stdin.js';
-import { resolveTenantId } from '../tenant.js';
-import { errorMessage, log } from '../log.js';
-import { withLedgerDb } from '../ledger-db.js';
+import { isStringValue, readSessionEnd, readVscodeStop } from '../core/capture-contract.js';
+import { loadConfig } from '../core/config.js';
+import { autoSleepDue } from '../api/auto-sleep.js';
+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 { errorMessage, log } from '../util/log.js';
+import { bookLedgerTurn } from '../api/ledger-db.js';
+import { flushDeliveryRecorder } from '../api/prompt-hook.js';
 import { printError } from './output.js';
 import { cmdLastSleep } from './last-sleep.js';
-import { logSessionEndImport, appendSessionEndCloseLog, resetHookInjection, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, } from './shared.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 { readCompactResumePayload } from './compact-resume-payload.js';
+import { boolFlag, flagIsTrue, stringFlag } from './flag-values.js';
+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);
-        }
-        // The matcher is an optimization, not a dependency: older Claude Code
-        // that ignores `matcher: 'compact'` would run this on every SessionStart,
-        // so we also gate on payload.source here. A payload that parses but
-        // carries a different source (e.g. 'startup') means the matcher-based
-        // gate failed to apply — stay silent rather than print stale state.
-        const nonEmptyStdin = !!stdinText && stdinText.trim() !== '';
-        // Without a payload session_id the cross-restore guard below can
-        // never fire, so a timed-out empty read must not reach the print path.
-        let suppressOutput = stdinTimedOut && !nonEmptyStdin;
-        let payloadSessionId = null;
-        if (nonEmptyStdin) {
-            let payload = null;
-            try {
-                payload = JSON.parse(stdinText.trim());
-            }
-            catch {
-                // Malformed JSON is handled as a null payload by the fail-closed check below.
-                payload = null;
-            }
-            if (!payload || typeof payload !== 'object') {
-                // Fail closed on malformed non-empty stdin; only a TTY/no-stdin manual run, which never reaches here, prints.
-                suppressOutput = true;
-            }
-            else {
-                // Fail closed on structurally incomplete payloads too ({}, [], source missing/non-string): real
-                // SessionStart payloads always carry source, so a parsed one must say 'compact' to print.
-                // A sub-agent's payload carries its parent's session id, so the mismatch guard would pass and restore the parent's snapshot into it.
-                if (payload.source !== 'compact' || isSubagentPayload(stdinText)) {
-                    suppressOutput = true;
-                }
-                if (typeof payload.session_id === 'string') {
-                    payloadSessionId = payload.session_id;
-                }
-            }
+            throw new CliExit(0);
         }
+        const payloadState = readCompactResumePayload(stdinText, stdinTimedOut);
+        let suppressOutput = payloadState.suppressOutput;
+        const payloadSessionId = payloadState.payloadSessionId;
+        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);
+            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: ${err instanceof Error ? err.message : String(err)}`);
+        log.warn(`hippo compact-resume: skipped: ${errorMessage(err)}`);
     }
-    process.exit(0);
+    // A no-op when the token ledger's handle already wrote the row; exit would drop it otherwise.
+    flushDeliveryRecorder(rec);
+    throw new CliExit(0);
 }
-function restoreCompactSnapshot(hippoRoot, payloadSessionId) {
-    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.
@@ -125,101 +92,115 @@ function restoreCompactSnapshot(hippoRoot, payloadSessionId) {
         }
     }
     catch (err) {
-        log.warn(`hippo compact-resume: trail skipped: ${err instanceof Error ? err.message : String(err)}`);
+        log.warn(`hippo compact-resume: trail skipped: ${errorMessage(err)}`);
     }
     // Printed in one write so the ledger books exactly the text the model is handed.
     const text = compactResumeText(snapshot, events);
     console.log(text);
-    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
-        tenantId, sessionId: payloadSessionId, surface: 'compact_resume', event: 'inject', items: 1, tokens: estimateTokens(text),
-    }));
+    rec?.delivered({ state: 'sent', emittedText: `${text}\n` });
+    bookLedgerTurn(hippoRoot, {
+        uses: [{
+                tenantId, sessionId: payloadSessionId, surface: 'compact_resume', event: 'inject', items: 1, tokens: estimateTokens(text),
+            }],
+        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 = flags['turn'] === true;
+    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.
-    const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : runtime === 'copilot' ? resolveJsonHookPaths('copilot').logFile : null;
+    const logFile = stringFlag(flags, 'log-file') ?? (runtime === 'copilot' ? resolveJsonHookPaths('copilot').logFile : null);
     // Bounded read: extracts transcript_path + session_id for the detached worker's argv.
-    let sessionId = null;
     const raw = await readStdinBounded();
     // Read before normalising: the Copilot CLI's agentStop shares this hook line, and camelCase keys would pass as VS Code's.
-    if (turn && !isVscodeStopPayload(raw))
+    const stop = turn ? vscodeStopInput(raw) : null;
+    if (turn && !stop)
         return;
     const stdinText = normaliseHookPayload(raw.text);
     // Before the spawn, since the worker finds its store from the folder it inherits.
     const root = payloadCwdRoot(hippoRoot, stdinText, runtime);
-    try {
-        if (stdinText && stdinText.trim().startsWith('{')) {
-            const payload = JSON.parse(stdinText);
-            if (typeof payload.session_id === 'string') {
-                sessionId = payload.session_id;
-            }
-        }
-    }
-    catch {
-        // No stdin, not JSON, or read failure: the snapshot close below will no-op.
-    }
+    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.
-    const transcriptPath = resolveLastSessionTranscript(undefined, stdinText, { mayScan: false })
+    const named = input?.transcriptPath ?? null;
+    const transcriptPath = (named !== null && fs.existsSync(named) ? named : null)
         ?? (runtime === 'copilot' && sessionId ? copilotTranscriptFor(sessionId) : null);
-    const workerArgs = [process.argv[1], '__session-end-worker'];
-    if (logFile)
-        workerArgs.push('--log-file', logFile);
-    if (transcriptPath)
-        workerArgs.push('--transcript', transcriptPath);
-    if (sessionId)
-        workerArgs.push('--session-id', sessionId);
-    if (turn)
-        workerArgs.push('--turn');
     try {
-        const child = spawn(process.execPath, workerArgs, {
-            detached: true,
-            stdio: 'ignore',
-            windowsHide: true,
-        });
-        // An async spawn failure arrives as an 'error' event, which with no listener is an uncaught exception.
-        child.on('error', (err) => log.warn(`hippo session-end: the worker did not start: ${errorMessage(err)}`));
-        child.unref();
+        spawnSessionEndWorker(sessionEndWorkerArgs(logFile, transcriptPath, sessionId, turn));
     }
-    catch {
-        // If spawn fails, run inline as a last resort, handed what the child's argv would have carried.
+    catch (err) {
+        log.debug(`session-end: the worker did not spawn, running inline: ${errorMessage(err)}`);
+        // Inline is the last resort, handed what the child's argv would have carried.
         if (logFile)
             flags['log-file'] = logFile;
         if (transcriptPath)
             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) {
+    const receipt = readSessionEnd(stdinText, timedOut, runtime);
+    if (receipt.status === 'received')
+        return receipt.input;
+    log.debug(`session-end: ${receipt.reason}`);
+    return null;
+}
+function sessionEndWorkerArgs(logFile, transcriptPath, sessionId, turn) {
+    const workerArgs = [process.argv[1], '__session-end-worker'];
+    if (logFile)
+        workerArgs.push('--log-file', logFile);
+    if (transcriptPath)
+        workerArgs.push('--transcript', transcriptPath);
+    if (sessionId)
+        workerArgs.push('--session-id', sessionId);
+    if (turn)
+        workerArgs.push('--turn');
+    return workerArgs;
 }
-/** A VS Code Stop payload with a session id that can name the lock file; anything else makes turn mode a silent no-op. */
-function isVscodeStopPayload(raw) {
+function spawnSessionEndWorker(workerArgs) {
+    const child = spawn(process.execPath, workerArgs, {
+        detached: true,
+        stdio: 'ignore',
+        windowsHide: true,
+    });
+    // An async spawn failure arrives as an 'error' event, which with no listener is an uncaught exception.
+    child.on('error', (err) => log.warn(`hippo session-end: the worker did not start: ${errorMessage(err)}`));
+    child.unref();
+}
+/** The input of a VS Code Stop payload with a session id that can name the lock file; null makes turn mode a silent no-op. */
+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);
+    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, flags['turn'] === true ? 'turn' : 'full', (mode) => sessionEndWork(hippoRoot, flags, mode));
-}
-async function sessionEndWork(hippoRoot, flags, mode) {
-    const transcriptPath = typeof flags['transcript'] === 'string' ? flags['transcript'] : undefined;
-    const closeLogFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : null;
-    const closeSessionId = typeof flags['session-id'] === 'string' ? flags['session-id'] : null;
-    const rereadLog = await bookSessionRereads(hippoRoot, transcriptPath, closeSessionId)
-        .catch((err) => [`re-read count failed: ${err instanceof Error ? err.message : String(err)}`]);
+    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, 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, 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))
         appendSessionEndCloseLog(closeLogFile, line); };
@@ -232,35 +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, tenantId, 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 {
@@ -268,18 +251,18 @@ async function sessionEndWork(hippoRoot, flags, mode) {
         }
     }
     catch (err) {
-        appendSessionEndCloseLog(closeLogFile, `snapshot close failed: ${err.message}`);
+        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 {
-            // sleep errors are already tee'd to the log file via cmdSleep's
-            // `[hippo] sleep failed: ...` line. Continue to capture regardless.
+        catch (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 {
@@ -288,19 +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, threshold } = loadConfig(hippoRoot).autoSleep;
-        const count = enabled ? countCreatedSinceLastSleep(hippoRoot, resolveTenantId({})) : 0;
-        if (!enabled || count < threshold) {
+        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) {
@@ -322,9 +304,9 @@ 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 = typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined;
+        const logFile = stringFlag(flags, 'log-file');
         // With no stdin of its own, capture would read this as a manual run and scan every project.
         if (!transcriptPath) {
             appendSessionEndCloseLog(logFile ?? null, 'skip capture: no transcript for this session');
@@ -336,21 +318,20 @@ 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,
         });
         return true;
     }
-    catch {
-        // Same treatment — the failure line is already in the log.
+    catch (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
@@ -367,11 +348,11 @@ function writeEndHandoff(store, closeSessionId, transcriptPath, closeLogFile, in
     }
     catch (err) {
         // SAFETY: catch clauses bind unknown, but Node/V8 always throws an Error here.
-        appendSessionEndCloseLog(closeLogFile, `handoff write failed: ${err.message}`);
+        appendSessionEndCloseLog(closeLogFile, `handoff write failed: ${errorMessage(err)}`);
     }
 }
 /** 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;
@@ -379,23 +360,17 @@ async function bookSessionRereads(hippoRoot, transcriptPath, sessionId) {
         read = await readApiCalls(transcriptPath);
     }
     catch (err) {
-        return [`skip re-read count: cannot read the transcript: ${err instanceof Error ? err.message : String(err)}`];
+        return [`skip re-read count: cannot read the transcript: ${errorMessage(err)}`];
     }
     const roots = new Set([hippoRoot, getGlobalRoot()].filter((root) => isInitialized(root)).map((root) => path.resolve(root)));
     const lines = [];
     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: ${err instanceof Error ? err.message : String(err)}`);
+            lines.push(`re-read count failed: ${errorMessage(err)}`);
         }
     }
     const skipped = read.malformed > 0 ? `, ${read.malformed} unparsable transcript lines skipped` : '';
@@ -407,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. */
@@ -433,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.
@@ -442,8 +418,8 @@ export function cmdCodexRun(hippoRoot, args) {
     try {
         cmdLastSleep(hippoRoot, { path: metadata.logFile }, 'terminal');
     }
-    catch {
-        // best-effort only
+    catch (err) {
+        log.debug(`codex run: the last sleep summary was not shown: ${errorMessage(err)}`);
     }
     const child = spawnRealCodex(metadata.realCodexPath, args, process.cwd());
     child.on('error', (err) => {
@@ -451,85 +427,106 @@ export function cmdCodexRun(hippoRoot, args) {
         process.exit(1);
     });
     child.on('exit', async (code, signal) => {
-        const workerArgs = [
-            process.argv[1],
-            '__codex-session-end-worker',
-            '--codex-home',
-            path.dirname(historyPath),
-            '--history-path',
-            historyPath,
-            '--start-offset',
-            String(startOffsetBytes),
-            '--started-at',
-            String(startedAtMs),
-            '--log-file',
-            metadata.logFile,
-        ];
+        await launchCodexSessionEndWorker(hippoRoot, tenantId, historyPath, startOffsetBytes, startedAtMs, metadata.logFile);
+        exitLikeChild(code, signal);
+    });
+}
+async function launchCodexSessionEndWorker(hippoRoot, tenantId, historyPath, startOffsetBytes, startedAtMs, logFile) {
+    const workerArgs = [
+        process.argv[1],
+        '__codex-session-end-worker',
+        '--codex-home',
+        path.dirname(historyPath),
+        '--history-path',
+        historyPath,
+        '--start-offset',
+        String(startOffsetBytes),
+        '--started-at',
+        String(startedAtMs),
+        '--log-file',
+        logFile,
+    ];
+    if (await detachedWorkerStarted(workerArgs))
+        return;
+    // Awaited so the sleep write can't be killed by the exit calls below.
+    try {
+        await cmdCodexSessionEndWorker(hippoRoot, tenantId, {
+            'codex-home': path.dirname(historyPath),
+            'history-path': historyPath,
+            'start-offset': String(startOffsetBytes),
+            'started-at': String(startedAtMs),
+            'log-file': logFile,
+        });
+    }
+    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 {
-            const worker = spawn(process.execPath, workerArgs, {
-                detached: true,
-                stdio: 'ignore',
-                windowsHide: true,
-            });
+            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 {
-            // Fall back to the inline path if the detached worker cannot be created.
-            // Awaited so the sleep write can't be killed by the exit calls below.
-            try {
-                await cmdCodexSessionEndWorker(hippoRoot, {
-                    'codex-home': path.dirname(historyPath),
-                    'history-path': historyPath,
-                    'start-offset': String(startOffsetBytes),
-                    'started-at': String(startedAtMs),
-                    'log-file': metadata.logFile,
-                });
-            }
-            catch {
-                // cmdCodexSessionEndWorker already fail-softs internally; this is belt-and-braces.
-            }
-        }
-        if (signal) {
-            try {
-                process.kill(process.pid, signal);
-            }
-            catch {
-                // Cannot re-raise the child's signal on this platform; a non-zero exit still reports the failure.
-                process.exit(1);
-            }
-            return;
+        catch (err) {
+            failed(errorMessage(err));
         }
-        process.exit(code ?? 0);
     });
 }
-export async function cmdCodexSessionEndWorker(hippoRoot, flags) {
-    const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined;
+function exitLikeChild(code, signal) {
+    if (signal) {
+        try {
+            process.kill(process.pid, signal);
+        }
+        catch {
+            // Cannot re-raise the child's signal on this platform; a non-zero exit still reports the failure.
+            process.exit(1);
+        }
+        return;
+    }
+    process.exit(code ?? 0);
+}
+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);
     if (!isInitialized(store)) {
         appendSessionEndCloseLog(logFile ?? null, 'skip: no hippo store for this folder or globally', { startFresh: true });
         return;
     }
+    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, 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 {
-            // sleep errors are already written via cmdSleep
+        catch (err) {
+            reportSessionEndFailure(logFile ?? null, 'codex session-end: sleep', err);
         }
     }
     else {
         appendSessionEndCloseLog(logFile ?? null, 'skip sleep: this folder has no store of its own', { startFresh: true });
         logSessionEndImport(logFile ?? null, undefined);
     }
+}
+function captureCodexTranscript(hippoRoot, tenantId, store, flags, logFile) {
     try {
-        const codexHome = typeof flags['codex-home'] === 'string'
-            ? flags['codex-home']
-            : resolveCodexWrapperPaths().codexHome;
-        const historyPath = typeof flags['history-path'] === 'string'
-            ? flags['history-path']
-            : path.join(codexHome, 'history.jsonl');
+        const codexHome = stringFlag(flags, 'codex-home') ?? resolveCodexWrapperPaths().codexHome;
+        const historyPath = stringFlag(flags, 'history-path') ?? path.join(codexHome, 'history.jsonl');
         const startOffsetBytes = parseInt(String(flags['start-offset'] ?? '0'), 10) || 0;
         const startedAtMs = parseInt(String(flags['started-at'] ?? Date.now()), 10) || Date.now();
         const transcriptPath = resolveCodexSessionTranscript({
@@ -551,21 +548,21 @@ export async function cmdCodexSessionEndWorker(hippoRoot, flags) {
             logFile,
             dryRun: false,
             global: false,
-            tenantId: resolveTenantId({}),
+            tenantId,
             originProject: store === hippoRoot ? undefined : resolveProjectIdentity(process.cwd()),
             sessionTurns: scan?.turns,
         };
         try {
             cmdCapture(store, captureOpts);
         }
-        catch {
-            // capture path logs its own failures
+        catch (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 {
-        // capture path logs its own failures
+    catch (err) {
+        reportSessionEndFailure(logFile ?? null, 'codex session-end: transcript scan or digest', err);
     }
 }
 export async function handlePreCompact({ hippoRoot, flags }) {
@@ -574,24 +571,31 @@ export async function handlePreCompact({ hippoRoot, flags }) {
     const runtime = hookRuntime(flags);
     const root = payloadCwdRoot(hippoRoot, stdinText, runtime);
     await runHookWithStores(async () => {
+        // Started before any store wait, so two fires of one hook carry timestamps close enough to match as duplicates.
+        const rec = startDeliveryRecorder(hookStoreRoot(root), stdinText, runtime, 'pre-compact');
         resetHookInjection(root, stdinText, null);
         await cmdPreCompact(hookStoreRoot(root), {
             stdinText,
             stdinTimedOut,
-            logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
+            logFile: stringFlag(flags, 'log-file'),
             runtime,
+            onBoundary: (printed) => {
+                rec?.delivered(printed === null ? { state: 'empty' } : { state: 'sent', emittedText: printed });
+                flushDeliveryRecorder(rec);
+            },
         });
     });
 }
 export async function handlePostCompact({ hippoRoot, flags }) {
     // PostCompact hook: saves the compaction summary and its memories, then prints one plain line, because Claude Code shows this hook's stdout as-is. Always exits 0.
-    const { text } = await readHookStdin();
+    const { text, timedOut } = await readHookStdin();
     const logFlag = flags['log-file'];
     const store = hookStoreRoot(hippoRoot);
     const line = await runHookWithStores(() => cmdPostCompact(store, {
         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);
@@ -604,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();
@@ -614,21 +618,22 @@ 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 {
-        // A malformed payload or store error must never fail the agent's tool call.
+    catch (err) {
+        // A malformed payload or store error must never fail the agent's tool call, so it is reported and dropped.
+        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;
@@ -649,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 };
@@ -662,10 +667,10 @@ export async function handleCapture({ hippoRoot, flags }) {
         transcriptPath,
         stdinText: bounded.text,
         stdinTimedOut: bounded.timedOut,
-        logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
-        dryRun: Boolean(flags['dry-run']),
-        global: Boolean(flags['global']),
-        tenantId: resolveTenantId({}),
+        logFile: stringFlag(flags, 'log-file'),
+        dryRun: boolFlag(flags, 'dry-run'),
+        global: boolFlag(flags, 'global'),
+        tenantId,
     });
 }
 //# sourceMappingURL=session-hooks.js.map