hippo-memory 1.72.0 → 2.1.0

package/dist/capture/transcript.d.ts

@@ -1,4 +1,7 @@
-/** Transcript-line flags isNonHumanUserLine reads (any may be absent); `promptSource: 'system'` marks Claude Code's own notices. */
+/**
+ * Transcript-line flags isNonHumanUserLine reads (any may be absent); `promptSource: 'system'` marks Claude Code's own
+ * notices.
+ */
 interface TranscriptLineFlags {
     type?: unknown;
     isMeta?: unknown;
@@ -9,7 +12,9 @@ interface TranscriptLineFlags {
 interface TranscriptMessage {
     content?: unknown;
 }
-/** The human's words on a Claude Code user line, '' when none; VS Code stores prompts as text blocks, beside its own open-file, selection
+/**
+ * The human's words on a Claude Code user line, '' when none; VS Code stores prompts as text blocks, beside its own
+ * open-file, selection
  * and interrupt blocks. */
 export declare function humanUserText(entry: TranscriptLineFlags, message: TranscriptMessage): string;
 export interface SessionTurn {
@@ -29,8 +34,12 @@ export declare function sessionTail(turns: readonly SessionTurn[]): {
     assistants: string[];
 };
 export declare function summariseSessionTurns(turns: readonly SessionTurn[]): string;
-/** Resolve a transcript path for `--last-session`: `transcriptPath`, then the stdin JSON payload, then the newest `.jsonl` in the Claude config dir.
- *  The scan runs only with `mayScan` (it spans every project on the box); returns null when nothing resolves, never throws. */
+/**
+ * Resolve a transcript path for `--last-session`: `transcriptPath`, then the stdin JSON payload, then the newest
+ * `.jsonl` in the Claude config dir.
+ * The scan runs only with `mayScan` (it spans every project on the box); returns null when nothing resolves, never
+ * throws.
+ */
 export declare function resolveLastSessionTranscript(explicit: string | undefined, stdinText: string | undefined, opts: {
     mayScan: boolean;
 }): string | null;

package/dist/capture/transcript.js

@@ -6,18 +6,26 @@ import { isObjectLike, isStringValue, readSessionEnd } from '../core/capture-con
 import { copilotTurn } from './copilot-transcript.js';
 const RECENT_USER_TURNS = 20;
 const RECENT_ASSISTANT_TURNS = 10;
-/** Build a compact text summary from a Claude Code / OpenCode / Copilot JSONL transcript: plain user messages and the final assistant text chunk,
+/**
+ * Build a compact text summary from a Claude Code / OpenCode / Copilot JSONL transcript: plain user messages and the
+ * final assistant text chunk,
  *  without thinking, tool_use and tool_result noise. Exported for tests. */
 /** Leading markers of the command lines Claude Code writes with type 'user'. */
 const CLAUDE_CODE_COMMAND_PREFIXES = ['<local-command-', '<command-name>', '<command-message>', '<command-args>'];
 function isNonHumanUserLine(entry, content) {
-    if (entry.isMeta === true || entry.isSidechain === true || entry.isCompactSummary === true || entry.promptSource === 'system')
+    if (entry.isMeta === true ||
+        entry.isSidechain === true ||
+        entry.isCompactSummary === true ||
+        entry.promptSource === 'system') {
         return true;
+    }
     const head = content.trimStart();
     return CLAUDE_CODE_COMMAND_PREFIXES.some((p) => head.startsWith(p));
 }
 const NON_HUMAN_BLOCK_PREFIXES = ['<ide_', '[Request interrupted by user'];
-/** The human's words on a Claude Code user line, '' when none; VS Code stores prompts as text blocks, beside its own open-file, selection
+/**
+ * The human's words on a Claude Code user line, '' when none; VS Code stores prompts as text blocks, beside its own
+ * open-file, selection
  * and interrupt blocks. */
 export function humanUserText(entry, message) {
     const content = message.content;
@@ -25,12 +33,14 @@ export function humanUserText(entry, message) {
     if (isStringValue(content)) {
         text = content;
     }
-    else if (Array.isArray(content) && !content.some((b) => isObjectLike(b) && 'type' in b && b.type === 'tool_result')) {
+    else if (Array.isArray(content) &&
+        !content.some((b) => isObjectLike(b) && 'type' in b && b.type === 'tool_result')) {
         const parts = [];
         for (const block of content) {
             const blockText = isObjectLike(block) && 'type' in block && block.type === 'text' && 'text' in block ? block.text : undefined;
-            if (isStringValue(blockText) && !NON_HUMAN_BLOCK_PREFIXES.some((p) => blockText.trimStart().startsWith(p)))
+            if (isStringValue(blockText) && !NON_HUMAN_BLOCK_PREFIXES.some((p) => blockText.trimStart().startsWith(p))) {
                 parts.push(blockText);
+            }
         }
         text = parts.join('\n');
     }
@@ -57,7 +67,10 @@ export function collectSessionTurns(jsonl, visit) {
     }
     return turns;
 }
-/** The turn a Claude Code `user` or `assistant` line carries; null for any other line or one with no human or reply text. */
+/**
+ * The turn a Claude Code `user` or `assistant` line carries; null for any other line or one with no human or reply
+ * text.
+ */
 function claudeCodeTurn(entry) {
     if (entry.type !== 'user' && entry.type !== 'assistant')
         return null;
@@ -83,7 +96,8 @@ function claudeCodeTurn(entry) {
     }
     return chunks.length > 0 ? { role: 'assistant', text: chunks.join('\n') } : null;
 }
-// Codex stores its own context as user messages: the AGENTS.md text, and one tagged block each for the environment and app state.
+// Codex stores its own context as user messages: the AGENTS.md text, and one tagged block each for the environment and
+// app state.
 const CODEX_INJECTED_USER_TEXT = /^(?:# AGENTS\.md instructions\b|<([A-Za-z][\w-]*)(?:\s[^>]*)?>[\s\S]*<\/\1>$)/;
 // Codex rollout transcript shape: response_item -> payload.message
 function codexTurn(entry) {
@@ -102,7 +116,11 @@ function codexTurn(entry) {
             continue;
         const blockType = 'type' in block ? block.type : undefined;
         const blockText = 'text' in block ? block.text : undefined;
-        if (role === 'user' && blockType === 'input_text' && isStringValue(blockText) && blockText.trim() && !CODEX_INJECTED_USER_TEXT.test(blockText.trim())) {
+        if (role === 'user' &&
+            blockType === 'input_text' &&
+            isStringValue(blockText) &&
+            blockText.trim() &&
+            !CODEX_INJECTED_USER_TEXT.test(blockText.trim())) {
             chunks.push(blockText.trim());
         }
         if (role === 'assistant' && blockType === 'output_text' && isStringValue(blockText) && blockText.trim()) {
@@ -142,8 +160,12 @@ export function summariseSessionTurns(turns) {
         tailAssistants.join('\n\n'),
     ].join('\n');
 }
-/** Resolve a transcript path for `--last-session`: `transcriptPath`, then the stdin JSON payload, then the newest `.jsonl` in the Claude config dir.
- *  The scan runs only with `mayScan` (it spans every project on the box); returns null when nothing resolves, never throws. */
+/**
+ * Resolve a transcript path for `--last-session`: `transcriptPath`, then the stdin JSON payload, then the newest
+ * `.jsonl` in the Claude config dir.
+ * The scan runs only with `mayScan` (it spans every project on the box); returns null when nothing resolves, never
+ * throws.
+ */
 export function resolveLastSessionTranscript(explicit, stdinText, opts) {
     if (explicit)
         return fs.existsSync(explicit) ? explicit : null;

package/dist/capture/working-state.d.ts

@@ -1,5 +1,8 @@
 import type { TaskSnapshot } from '../store/rows.js';
-/** The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these instead of copying them. */
+/**
+ * The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these
+ * instead of copying them.
+ */
 export declare const WORKING_STATE_CAPS: {
     readonly task: 200;
     readonly summary: number;
@@ -8,13 +11,19 @@ export declare const WORKING_STATE_CAPS: {
 export type WorkingState = Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'>;
 /** Cuts each field to {@link WORKING_STATE_CAPS}, for after a scrub, as a mask can run longer than what it hides. */
 export declare function fitWorkingState(state: WorkingState): WorkingState;
-/** Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so blanks never replace a snapshot.
+/**
+ * Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so
+ * blanks never replace a snapshot.
  *  Never across sessions: another session's task saved under this id would pass compact-resume's session check. */
 export declare function mergeWorkingState(derived: WorkingState, existing: TaskSnapshot | null, sessionId: string | null): WorkingState | null;
-/** Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a head cap would drop
+/**
+ * Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a
+ * head cap would drop
  * the newest working state. */
 export declare function truncateKeepNewest(text: string, maxChars: number): string;
-/** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged
+/**
+ * A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null
+ * with a logged
  * reason when nothing is derivable. */
 export declare function transcriptWorkingState(transcriptPath: string, log: (message: string) => void): Pick<TaskSnapshot, 'task' | 'summary' | 'next_step'> | null;
 //# sourceMappingURL=working-state.d.ts.map

package/dist/capture/working-state.js

@@ -1,4 +1,5 @@
-// A session's working state read from its transcript tail, with no store in the imports, so a hook with no store can derive it.
+// A session's working state read from its transcript tail, with no store in the imports, so a hook with no store can
+// derive it.
 import * as fs from 'fs';
 import { maskEmails, redactSecretsStrict } from '../util/secret-detect.js';
 import { isObjectLike, isStringValue } from '../core/capture-contract.js';
@@ -10,7 +11,10 @@ const PRE_COMPACT_TASK_CAP = 200;
 const PRE_COMPACT_SUMMARY_CAP = 2000;
 const PRE_COMPACT_NEXT_STEP_CAP = 500;
 const TRIM_MARKER = '[...earlier turns trimmed]\n';
-/** The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these instead of copying them. */
+/**
+ * The longest each field of {@link transcriptWorkingState} can be, so a check of a sent working state imports these
+ * instead of copying them.
+ */
 export const WORKING_STATE_CAPS = {
     task: PRE_COMPACT_TASK_CAP,
     summary: PRE_COMPACT_SUMMARY_CAP + TRIM_MARKER.length,
@@ -20,15 +24,22 @@ export const WORKING_STATE_CAPS = {
 export function fitWorkingState(state) {
     return {
         task: truncateCodePointSafe(state.task, WORKING_STATE_CAPS.task),
-        // Only past the cap, since re-trimming a summary that fits would drop its head again; the cut keeps the newest turns.
-        summary: state.summary.length > WORKING_STATE_CAPS.summary ? truncateKeepNewest(state.summary, PRE_COMPACT_SUMMARY_CAP) : state.summary,
+        // Only past the cap, since re-trimming a summary that fits would drop its head again; the cut keeps the newest
+        // turns.
+        summary: state.summary.length > WORKING_STATE_CAPS.summary
+            ? truncateKeepNewest(state.summary, PRE_COMPACT_SUMMARY_CAP)
+            : state.summary,
         next_step: truncateCodePointSafe(state.next_step, WORKING_STATE_CAPS.next_step),
     };
 }
-/** Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so blanks never replace a snapshot.
+/**
+ * Each empty field falls back to `existing`'s, since a tool-heavy tail derives no task; null when all are empty, so
+ * blanks never replace a snapshot.
  *  Never across sessions: another session's task saved under this id would pass compact-resume's session check. */
 export function mergeWorkingState(derived, existing, sessionId) {
-    const fallback = existing !== null && (existing.session_id === null || sessionId === null || existing.session_id === sessionId) ? existing : null;
+    const fallback = existing !== null && (existing.session_id === null || sessionId === null || existing.session_id === sessionId)
+        ? existing
+        : null;
     const merged = {
         task: derived.task || (fallback?.task ?? ''),
         summary: derived.summary || (fallback?.summary ?? ''),
@@ -36,7 +47,9 @@ export function mergeWorkingState(derived, existing, sessionId) {
     };
     return merged.task || merged.summary || merged.next_step ? merged : null;
 }
-/** Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a head cap would drop
+/**
+ * Keeps the LAST maxChars behind a trim marker, aligned to a nearby line start: the summary runs oldest first, so a
+ * head cap would drop
  * the newest working state. */
 export function truncateKeepNewest(text, maxChars) {
     if (text.length <= maxChars)
@@ -50,8 +63,11 @@ export function truncateKeepNewest(text, maxChars) {
         start = nl + 1;
     return TRIM_MARKER + text.slice(start);
 }
-/** Most recent plain-text user message in a JSONL tail, from a Claude Code or a Copilot transcript. */
-function lastPlainUserMessage(jsonl) {
+/**
+ * Newest main-agent `role` turn in a JSONL tail, from a Claude Code or a Copilot transcript; `textOf` reads a Claude
+ * Code line, '' when it has no text.
+ */
+function lastTurnText(jsonl, role, textOf) {
     const lines = jsonl.split('\n').filter((l) => l.trim());
     for (let i = lines.length - 1; i >= 0; i--) {
         let entry;
@@ -66,65 +82,42 @@ function lastPlainUserMessage(jsonl) {
         if (!('type' in entry))
             continue;
         const copilot = copilotTurn(entry);
-        if (copilot?.role === 'user')
+        if (copilot?.role === role)
             return copilot.text;
-        if (entry.type !== 'user')
+        if (entry.type !== role)
             continue;
-        // An isMeta user line holds an earlier compact summary and an isSidechain one is a sub-agent turn; neither is the human's task.
-        if (('isMeta' in entry && entry.isMeta === true) || ('isSidechain' in entry && entry.isSidechain === true))
+        // An isMeta line holds an earlier compact summary and an isSidechain one is a sub-agent turn; neither is this
+        // session's own.
+        if (('isMeta' in entry && entry.isMeta === true) || ('isSidechain' in entry && entry.isSidechain === true)) {
             continue;
+        }
         const message = 'message' in entry && isObjectLike(entry.message) ? entry.message : undefined;
         if (!message)
             continue;
-        const text = humanUserText(entry, message);
+        const text = textOf(entry, message);
         if (text)
             return text;
     }
     return '';
 }
-/** Last assistant text block in a JSONL tail (skips thinking + tool_use, same as summariseTranscript). */
-function lastAssistantTextBlock(jsonl) {
-    const lines = jsonl.split('\n').filter((l) => l.trim());
-    for (let i = lines.length - 1; i >= 0; i--) {
-        let entry;
-        try {
-            entry = JSON.parse(lines[i]);
-        }
-        catch {
-            continue; // the tail read can start mid-line; skip the torn fragment
-        }
-        if (!isObjectLike(entry))
-            continue;
-        if (!('type' in entry))
-            continue;
-        const copilot = copilotTurn(entry);
-        if (copilot?.role === 'assistant')
-            return copilot.text;
-        if (entry.type !== 'assistant')
-            continue;
-        // Same meta/sidechain guard as lastPlainUserMessage: sub-agent turns
-        // (isSidechain) are not this session's next step.
-        if (('isMeta' in entry && entry.isMeta === true) || ('isSidechain' in entry && entry.isSidechain === true))
-            continue;
-        const message = 'message' in entry && isObjectLike(entry.message) ? entry.message : undefined;
-        if (!message)
-            continue;
-        const content = 'content' in message ? message.content : undefined;
-        if (!Array.isArray(content))
+/** The last text block of an assistant message, skipping thinking and tool_use blocks (as summariseTranscript does). */
+function lastTextBlock(_entry, message) {
+    const content = message.content;
+    if (!Array.isArray(content))
+        return '';
+    for (let j = content.length - 1; j >= 0; j--) {
+        const block = content[j];
+        if (!isObjectLike(block))
             continue;
-        for (let j = content.length - 1; j >= 0; j--) {
-            const block = content[j];
-            if (isObjectLike(block)) {
-                const blockText = 'type' in block && block.type === 'text' && 'text' in block ? block.text : undefined;
-                if (isStringValue(blockText) && blockText.trim()) {
-                    return blockText.trim();
-                }
-            }
-        }
+        const blockText = 'type' in block && block.type === 'text' && 'text' in block ? block.text : undefined;
+        if (isStringValue(blockText) && blockText.trim())
+            return blockText.trim();
     }
     return '';
 }
-/** A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null with a logged
+/**
+ * A session's task, summary and next step from its transcript tail, secrets scrubbed and capped, '' where none; null
+ * with a logged
  * reason when nothing is derivable. */
 export function transcriptWorkingState(transcriptPath, log) {
     let tail = '';
@@ -135,11 +128,12 @@ export function transcriptWorkingState(transcriptPath, log) {
         // megabytes back: grow the window a bounded number of times until both turns are in it.
         const size = fs.statSync(transcriptPath).size;
         for (const cap of [PRE_COMPACT_TAIL_BYTES, PRE_COMPACT_TAIL_BYTES * 4, PRE_COMPACT_TAIL_BYTES * 16]) {
-            if (cap > PRE_COMPACT_TAIL_BYTES)
+            if (cap > PRE_COMPACT_TAIL_BYTES) {
                 log(`tail window grown to ${cap} bytes (last ${rawTask ? 'assistant' : 'user'} turn is further back)`);
+            }
             tail = readTranscriptTail(transcriptPath, cap);
-            rawTask = lastPlainUserMessage(tail);
-            rawNextStep = lastAssistantTextBlock(tail);
+            rawTask = lastTurnText(tail, 'user', humanUserText);
+            rawNextStep = lastTurnText(tail, 'assistant', lastTextBlock);
             if ((rawTask && rawNextStep) || size <= cap)
                 break;
         }

package/dist/cli/api-context.d.ts

@@ -1,3 +1,15 @@
-import { type HippoDbContext } from '../api/index.js';
-export declare function cliApiContext(hippoRoot: string, tenantId: string): HippoDbContext;
+import { type ContextWith } from '../api/index.js';
+import { type LedgerReach } from '../api/ledger-db.js';
+import type { McpHost } from '../mcp/protocol.js';
+import type { StoreGroup } from '../store/index.js';
+import type { LocalFiles } from '../store/port.js';
+/** The folder's hippo.db for a verb that runs a sleep pass by itself. */
+export declare function cliLocalFiles(hippoRoot: string): LocalFiles;
+/** The request scope a scoped CLI verb and the stdio MCP server run in; named here so no other surface opens one. */
+export declare function cliRequest<T>(run: () => T | Promise<T>): Promise<T>;
+export declare function cliApiContext(hippoRoot: string, tenantId: string): ContextWith<StoreGroup>;
+/** Where a hook on `hippoRoot` books its ledger rows: the folder's store, else the global one, probed once here. */
+export declare function cliLedgerReach(hippoRoot: string): LedgerReach;
+/** Stdio is the operator's own process: host admin, the folder's hippo.db, and an auto-sleep that runs in process. */
+export declare const cliStdioHost: McpHost;
 //# sourceMappingURL=api-context.d.ts.map

package/dist/cli/api-context.js

@@ -1,6 +1,49 @@
 import { adminActor } from '../api/index.js';
-// The one place the CLI names its audit actor; root is a parameter because some verbs target the global store.
+import { ledgerReachOf } from '../api/ledger-db.js';
+import { loadConfig } from '../core/config.js';
+import { runConsolidation } from '../consolidate/sleep.js';
+import { runDetachedSqliteRequest, runSqliteRequest, sqliteReach, sqliteStore, sqliteSyncStore, } from '../store/sqlite/store.js';
+/** The store the CLI and the stdio MCP server open; the adapter is named here so src/mcp never imports it. */
+function cliStore(hippoRoot) {
+    return sqliteStore(hippoRoot);
+}
+/** The folder's hippo.db for a verb that runs a sleep pass by itself. */
+export function cliLocalFiles(hippoRoot) {
+    return sqliteSyncStore(hippoRoot).localFiles;
+}
+/** The request scope a scoped CLI verb and the stdio MCP server run in; named here so no other surface opens one. */
+export function cliRequest(run) {
+    return runSqliteRequest(run, 'cli');
+}
+// The one place the CLI names its audit actor and builds its store;
+// root is a parameter because some verbs target the global store.
 export function cliApiContext(hippoRoot, tenantId) {
-    return { hippoRoot, tenantId, actor: adminActor('cli') };
+    const store = cliStore(hippoRoot);
+    // Read here, once per command, so a long-lived caller of this function never pins a stale config.
+    const config = loadConfig(hippoRoot);
+    return { hippoRoot, tenantId, actor: adminActor('cli'), store, reach: sqliteReach(hippoRoot, store), config };
+}
+/** Where a hook on `hippoRoot` books its ledger rows: the folder's store, else the global one, probed once here. */
+export function cliLedgerReach(hippoRoot) {
+    const store = cliStore(hippoRoot);
+    return ledgerReachOf({ reach: sqliteReach(hippoRoot, store), store });
 }
+/** Stdio is the operator's own process: host admin, the folder's hippo.db, and an auto-sleep that runs in process. */
+export const cliStdioHost = {
+    contextFor(hippoRoot, tenantId) {
+        const store = cliStore(hippoRoot);
+        return {
+            hippoRoot,
+            tenantId,
+            actor: 'mcp',
+            role: 'admin',
+            hostAdmin: true,
+            stdio: true,
+            store,
+            reach: sqliteReach(hippoRoot, store),
+            autoSleepRunner: (root) => runDetachedSqliteRequest(() => runConsolidation(cliLocalFiles(root))).then(() => { }),
+        };
+    },
+    runRequest: cliRequest,
+};
 //# sourceMappingURL=api-context.js.map

package/dist/cli/audit.js

@@ -4,13 +4,12 @@ import { DEFAULT_LIST_LIMIT } from '../util/limits.js';
 import { AUDIT_OPS } from '../store/audit.js';
 import * as api from '../api/index.js';
 import { parseOlderThanFlag } from './audit-prune.js';
-import { printError } from './output.js';
 import { cliApiContext } from './api-context.js';
 import { boolFlag, flagIsTrue, isBooleanFlag, stringFlag } from './flag-values.js';
 import { requireInit, resolveAuthRoot } from './shared.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 // Audit log subcommands (`hippo audit list`)
 const VALID_AUDIT_OPS = new Set(AUDIT_OPS);
 function formatAuditRow(ev) {
@@ -24,10 +23,10 @@ function readAuditOp(flags) {
     if (opFlag && !VALID_AUDIT_OPS.has(opFlag)) {
         // Built from the Set so the message cannot drift from the valid ops.
         const expected = Array.from(VALID_AUDIT_OPS).join(' | ');
-        printError(`Unknown --op value: ${opFlag}. Expected one of: ${expected}.`);
-        throw new CliExit(1);
+        fail(`Unknown --op value: ${opFlag}. Expected one of: ${expected}.`);
     }
-    // SAFETY: the exit above rejects every non-empty opFlag outside VALID_AUDIT_OPS, and an empty one is returned as given.
+    // SAFETY: the exit above rejects every non-empty opFlag outside VALID_AUDIT_OPS, and an empty one is returned as
+    // given.
     return opFlag;
 }
 function readAuditLimit(flags) {
@@ -36,14 +35,12 @@ function readAuditLimit(flags) {
     if (limitRaw !== undefined && !isBooleanFlag(limitRaw)) {
         const parsed = parseInt(String(limitRaw), 10);
         if (!Number.isFinite(parsed)) {
-            printError(`Invalid --limit value: ${String(limitRaw)} (expected a positive integer).`);
-            throw new CliExit(1);
+            fail(`Invalid --limit value: ${String(limitRaw)} (expected a positive integer).`);
         }
         limit = parsed;
     }
     if (limit < 1 || limit > 10000) {
-        printError(`--limit must be between 1 and 10000 (got ${limit}).`);
-        throw new CliExit(1);
+        fail(`--limit must be between 1 and 10000 (got ${limit}).`);
     }
     return limit;
 }
@@ -53,11 +50,13 @@ async function cmdAuditList(hippoRoot, tenantId, flags) {
     const op = readAuditOp(flags);
     const since = stringFlag(flags, 'since');
     if (since !== undefined && !Number.isFinite(new Date(since).getTime())) {
-        printError(`Invalid --since: ${since} (expected an ISO timestamp like 2026-04-22 or 2026-04-22T12:00:00Z).`);
-        throw new CliExit(1);
+        fail(`Invalid --since: ${since} (expected an ISO timestamp like 2026-04-22 or 2026-04-22T12:00:00Z).`);
     }
     const limit = readAuditLimit(flags);
-    const ctx = { hippoRoot: root, tenantId, actor: { subject: 'cli', role: 'admin' } };
+    const ctx = {
+        ...cliApiContext(root, tenantId),
+        actor: { subject: 'cli', role: 'admin' },
+    };
     const events = await api.auditList(ctx, { op, since, limit });
     if (asJson) {
         console.log(JSON.stringify(events));
@@ -72,24 +71,22 @@ async function cmdAuditList(hippoRoot, tenantId, flags) {
         console.log(formatAuditRow(ev));
     }
 }
-function cmdAuditPrune(hippoRoot, ctxTenantId, flags) {
+async function cmdAuditPrune(hippoRoot, ctxTenantId, flags) {
     const olderThanRaw = stringFlag(flags, 'older-than') ?? '';
     if (!olderThanRaw) {
-        printError('Usage: hippo audit prune --older-than <Nd> [--dry-run] [--tenant <t>]');
-        throw new CliExit(1);
+        fail('Usage: hippo audit prune --older-than <Nd> [--dry-run] [--tenant <t>]');
     }
     let olderThanDays;
     try {
         olderThanDays = parseOlderThanFlag(olderThanRaw);
     }
     catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
+        fail(errorMessage(e));
     }
     const tenantId = stringFlag(flags, 'tenant')?.trim() || ctxTenantId;
     const dryRun = flagIsTrue(flags, 'dry-run');
     const asJson = boolFlag(flags, 'json');
-    const result = api.pruneAuditLog(cliApiContext(hippoRoot, tenantId), { olderThanDays, dryRun });
+    const result = await api.pruneAuditLog(cliApiContext(hippoRoot, tenantId), { olderThanDays, dryRun });
     if (asJson) {
         console.log(JSON.stringify(result));
         return;
@@ -107,45 +104,47 @@ async function cmdAuditLog(hippoRoot, tenantId, args, flags) {
         return;
     }
     if (sub === 'prune') {
-        cmdAuditPrune(hippoRoot, tenantId, flags);
+        await cmdAuditPrune(hippoRoot, tenantId, flags);
         return;
     }
-    printError(`Unknown audit subcommand: ${sub}. Expected: list | prune.`);
-    throw new CliExit(1);
+    fail(`Unknown audit subcommand: ${sub}. Expected: list | prune.`);
 }
-function auditRepair(hippoRoot, tenantId, flags) {
+async function auditRepair(hippoRoot, tenantId, flags) {
     const apply = flagIsTrue(flags, 'apply') && flags['dry-run'] !== true;
-    const result = api.repairMemoryQuality(cliApiContext(flags['global'] ? getGlobalRoot() : hippoRoot, tenantId), apply);
+    const result = await api.repairMemoryQuality(cliApiContext(flags['global'] ? getGlobalRoot() : hippoRoot, tenantId), apply);
     if (flags['json']) {
         console.log(JSON.stringify(result));
         return;
     }
     console.log(`Quality repair ${apply ? 'apply' : 'preview'}: ${result.issues.length} issue(s) across ${result.total} memories.`);
-    for (const issue of result.issues)
+    for (const issue of result.issues) {
         console.log(`  [${issue.disposition}] ${issue.id}: ${issue.reason}${issue.protection ? ` (${issue.protection})` : ''}`);
+    }
     for (const blocker of result.blockers) {
         console.log(`  Blocked: ${blocker}. Repair never upgrades a store; ` +
             'any other hippo command does, then run repair again.');
     }
     const restore = `hippo dormant restore <id>${flags['global'] ? ' --global' : ''}`;
-    if (result.backup)
+    if (result.backup) {
         console.log(`Backup: ${result.backup}\nMoved ${result.appliedIds.length} memories to dormant storage. Recovery: ${restore}.`);
+    }
     else if (apply && result.supported)
         console.log('Nothing moved: no unprotected memory has a certain defect.');
     for (const warning of result.warnings)
         console.log(`Warning: ${warning}`);
-    if (!apply)
+    if (!apply) {
         console.log('Preview only. Add --apply to move set-aside memories to dormant storage. Pin a review memory to keep it.');
+    }
 }
-function fixAuditErrors(hippoRoot, tenantId, result, flags) {
-    const errors = result.issues.filter(i => i.severity === 'error');
+async function fixAuditErrors(hippoRoot, tenantId, result, flags) {
+    const errors = result.issues.filter((i) => i.severity === 'error');
     if (errors.length > 0 && flagIsTrue(flags, 'dry-run')) {
         console.log(`\nWould remove ${errors.length} error-severity memories (dry run, nothing deleted).`);
         console.log(`${result.issues.length - errors.length} warnings would remain (review manually).`);
     }
     else if (errors.length > 0) {
         const ctx = cliApiContext(hippoRoot, tenantId);
-        const removedCount = api.removeAuditErrors(ctx, 'audit --fix', errors).length;
+        const removedCount = (await api.removeAuditErrors(ctx, 'audit --fix', errors)).length;
         console.log(`\nRemoved ${removedCount} error-severity memories.`);
         console.log(`${result.issues.length - errors.length} warnings remain (review manually).`);
     }
@@ -155,16 +154,17 @@ function fixAuditErrors(hippoRoot, tenantId, result, flags) {
 }
 export async function handleAudit({ hippoRoot, tenantId, args, flags }) {
     if (args[0] === 'repair') {
-        auditRepair(hippoRoot, tenantId, flags);
+        await auditRepair(hippoRoot, tenantId, flags);
         return;
     }
-    // `audit list` and `audit prune` are the audit-log subcommands; other forms (no sub, --fix) keep the memory-quality auditor.
+    // `audit list` and `audit prune` are the audit-log subcommands;
+    // other forms (no sub, --fix) keep the memory-quality auditor.
     if (args[0] === 'list' || args[0] === 'prune') {
         await cmdAuditLog(hippoRoot, tenantId, args, flags);
         return;
     }
     requireInit(hippoRoot);
-    const result = api.auditMemoryQuality(cliApiContext(hippoRoot, tenantId));
+    const result = await api.auditMemoryQuality(cliApiContext(hippoRoot, tenantId));
     const shouldFix = boolFlag(flags, 'fix');
     if (result.issues.length === 0) {
         console.log(`All ${result.total} memories passed quality checks.`);
@@ -177,7 +177,7 @@ export async function handleAudit({ hippoRoot, tenantId, args, flags }) {
             console.log(`         "${truncateWithEllipsis(issue.content, 80)}"`);
         }
         if (shouldFix) {
-            fixAuditErrors(hippoRoot, tenantId, result, flags);
+            await fixAuditErrors(hippoRoot, tenantId, result, flags);
         }
         else {
             console.log(`\nRun with --fix to auto-remove error-severity issues.`);