hippo-memory 2.0.0 → 2.1.0

package/dist/cli/context.js

@@ -3,22 +3,26 @@ import { isSubagentPayload } from '../util/hook-payload.js';
 import { estimateTokens } from '../util/token-text.js';
 import { autoDetectContext } from '../api/context-auto.js';
 import { detectScope } from '../core/active-scope.js';
-import { bookLedgerTurn } from '../api/ledger-db.js';
+import { bookLedgerTurn, ledgerReachOf } from '../api/ledger-db.js';
 import { readHookStdin } from './stdin.js';
 import { isJsonObject, isJsonString } from '../util/json.js';
 import * as api from '../api/index.js';
-import { DEFAULT_CONTEXT_BUDGET } from '../api/context.js';
+import { DEFAULT_CONTEXT_BUDGET, NO_QUERY } from '../api/context.js';
 import { cliApiContext } from './api-context.js';
 import { renderAmbientSummary } from '../core/ambient.js';
 import { contextBlockLines, contextCost, crossProjectLines, settleTokens } from '../api/context-render.js';
 import { additionalContextOutput, flushDeliveryRecorder, hasContextData, startDeliveryRecorder, sessionStartEnvelope, toRenderItems, } from '../api/prompt-hook.js';
-import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue } from './flag-values.js';
+import { parseLimitFlag, parseCountFlag, parseBudgetFlag, flagIsTrue, stringFlagOrExit, } from './flag-values.js';
 import { requireInit } from './shared.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { printActiveTaskSnapshot, printSessionEvents, printHandoff, captureConsole } from './print.js';
-import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout } from './hook-runtime.js';
+import { hostSessionId, hookStoreRoot, hookRuntime, payloadCwdRoot, runHookWithStores, inPilotHoldout, } from './hook-runtime.js';
 async function cmdContext(hippoRoot, tenantId, args, flags, stdinText) {
     const rec = startDeliveryRecorder(cliApiContext(hippoRoot, tenantId), {
-        stdinText, runtime: hookRuntime(flags), eventType: flagIsTrue(flags, 'pinned-only') ? undefined : 'context', envSessionId: hostSessionId(),
+        stdinText,
+        runtime: hookRuntime(flags),
+        eventType: flagIsTrue(flags, 'pinned-only') ? undefined : 'context',
+        envSessionId: hostSessionId(),
     });
     // No try/finally: a render throw keeps its own exit code and writes no event.
     await renderContext(hippoRoot, tenantId, args, flags, stdinText, rec);
@@ -38,13 +42,15 @@ function readHookPayload(stdinText) {
             if (isJsonString(raw))
                 prompt = raw;
         }
-        catch {
+        catch (err) {
             // Malformed/non-JSON stdin: fall through to the env fallback below.
+            log.debug(`context: hook payload is not JSON: ${errorMessage(err)}`, errorFields(err));
         }
     }
     return { sessionId, prompt };
 }
-async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText, rec) {
+/** Null when this call renders nothing: the pilot holdout arm, or a budget of zero. */
+function contextGate(hippoRoot, resolvedTenant, flags, stdinText, rec) {
     // --pinned-only fires on every prompt, even where no local .hippo exists, so it skips requireInit
     // and api.getContext falls back to global-only.
     const pinnedOnly = flagIsTrue(flags, 'pinned-only');
@@ -52,22 +58,30 @@ async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText,
         requireInit(hippoRoot);
     }
     const session = resolveContextSession(stdinText);
-    const { currentSessionId, ledgerSessionId, payloadSessionId } = session;
+    const { currentSessionId, payloadSessionId } = session;
     // The pilot arm is booked at the first hook call whatever the flags, so the holdout sees no budget or content branch.
     if (inPilotHoldout(hippoRoot, resolvedTenant, currentSessionId, { write: payloadSessionId !== undefined })) {
         rec?.disabled();
-        return;
+        return null;
     }
     const budget = parseBudgetFlag(flags['budget'], DEFAULT_CONTEXT_BUDGET);
     if (budget <= 0) {
         rec?.disabled();
-        return;
+        return null;
     }
+    return { pinnedOnly, session, budget };
+}
+async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText, rec) {
+    const gate = contextGate(hippoRoot, resolvedTenant, flags, stdinText, rec);
+    if (gate === null)
+        return;
+    const { pinnedOnly, session, budget } = gate;
+    const { ledgerSessionId, payloadSessionId } = session;
     // --auto shells out to git, so it stays CLI-side; api.getContext stays host-agnostic and falls back to '*'.
     const query = contextQuery(args, flags);
     const ctx = cliApiContext(hippoRoot, resolvedTenant);
-    const format = String(flags['format'] ?? 'markdown');
-    const framing = String(flags['framing'] ?? 'observe');
+    const format = stringFlagOrExit(flags, 'format') ?? 'markdown';
+    const framing = stringFlagOrExit(flags, 'framing') ?? 'observe';
     const opts = buildContextOpts(flags, { query, budget, pinnedOnly, format, framing, session, rec });
     const result = await api.getContext(ctx, opts);
     if (!hasContextData(result)) {
@@ -75,7 +89,18 @@ async function renderContext(hippoRoot, resolvedTenant, args, flags, stdinText,
         return;
     }
     const envelope = format === 'copilot' ? sessionStartEnvelope(stdinText) : undefined;
-    const view = { hippoRoot, tenantId: ctx.tenantId, ledgerSessionId, payloadSessionId, pinnedOnly, framing, rec, result, envelope };
+    const view = {
+        hippoRoot,
+        tenantId: ctx.tenantId,
+        ledgerSessionId,
+        payloadSessionId,
+        pinnedOnly,
+        framing,
+        rec,
+        result,
+        reach: ledgerReachOf(ctx),
+        envelope,
+    };
     renderContextView(view, format, query);
 }
 function contextQuery(args, flags) {
@@ -110,7 +135,7 @@ function resolveContextSession(stdinText) {
 }
 function buildContextOpts(flags, input) {
     // Scope detection uses cwd, so it is resolved here and passed in via opts.scope.
-    const ctxExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const ctxExplicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const ctxActiveScope = ctxExplicitScope || detectScope();
     // --cross-project re-includes other-project memories, rendered under their own section.
     const crossProject = flagIsTrue(flags, 'cross-project');
@@ -143,7 +168,7 @@ function renderContextJson(view, query) {
         category: r.category ?? null,
     }));
     const jsonText = JSON.stringify({
-        query: query || '*',
+        query: query || NO_QUERY,
         activeSnapshot: result.activeSnapshot ?? null,
         sessionHandoff: result.sessionHandoff ?? null,
         recentSessionEvents: result.recentEvents ?? [],
@@ -158,7 +183,7 @@ function renderContextJson(view, query) {
                 event: 'inject', items: output.length, tokens: estimateTokens(jsonText),
             }],
         delivery: (write) => flushDeliveryRecorder(rec, write),
-    });
+    }, view.reach);
 }
 /** The default format; the header figure counts the whole block, sections included, as the ledger does. */
 function renderContextMarkdown(view) {
@@ -193,7 +218,7 @@ function renderContextMarkdown(view) {
                 event: 'inject', items: renderItems.length, tokens: estimateTokens(text),
             }],
         delivery: (write) => flushDeliveryRecorder(rec, write),
-    });
+    }, view.reach);
 }
 function printCrossProjectSection(items) {
     for (const line of crossProjectLines(items))

package/dist/cli/continuity.d.ts

@@ -1,7 +1,7 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleSnapshot({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleSession({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleHandoff({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleCurrent({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-export declare function handleWm({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleSnapshot({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleSession({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleHandoff({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleCurrent({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+export declare function handleWm({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=continuity.d.ts.map

package/dist/cli/continuity.js

@@ -3,26 +3,25 @@ import { snapshotSave as apiSnapshotSave, snapshotClear as apiSnapshotClear, sna
 import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from '../core/handoff.js';
 import { collectHandoffEvidence } from '../capture/handoff-evidence.js';
-import { printError } from './output.js';
 import { requireInit } from './shared.js';
 import { printActiveTaskSnapshot, printSessionEvents, printHandoff } from './print.js';
-import { boolFlag, isStringFlag, numberFlag } from './flag-values.js';
-import { CliExit } from './exit.js';
+import { boolFlag, isStringFlag, numberFlag, stringFlagOrExit, } from './flag-values.js';
+import { fail } from './exit.js';
 const ISO_DATETIME_CHARS = 19;
-function snapshotSave(hippoRoot, tenantId, flags) {
-    const task = String(flags['task'] ?? '').trim();
-    const summary = String(flags['summary'] ?? '').trim();
-    const nextStep = String(flags['next-step'] ?? '').trim();
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim();
+async function snapshotSave(hippoRoot, tenantId, flags) {
+    const task = stringFlagOrExit(flags, 'task') ?? '';
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
+    const nextStep = stringFlagOrExit(flags, 'next-step') ?? '';
+    const sessionId = stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '';
     if (!task || !summary || !nextStep) {
-        printError('Usage: hippo snapshot save --task <task> --summary <summary> --next-step <step> [--source <source>] [--session <session-id>]');
-        throw new CliExit(1);
+        fail('Usage: hippo snapshot save --task <task> --summary <summary> --next-step <step> ' +
+            '[--source <source>] [--session <session-id>]');
     }
-    const snapshot = apiSnapshotSave(cliApiContext(hippoRoot, tenantId), {
+    const snapshot = await apiSnapshotSave(cliApiContext(hippoRoot, tenantId), {
         task,
         summary,
         next_step: nextStep,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
         session_id: sessionId || null,
     });
     console.log(`Saved active task snapshot #${snapshot.id}`);
@@ -32,16 +31,17 @@ function snapshotSave(hippoRoot, tenantId, flags) {
         console.log(`   Session: ${snapshot.session_id}`);
     }
 }
-function snapshotClear(hippoRoot, tenantId, flags) {
-    const cleared = apiSnapshotClear(cliApiContext(hippoRoot, tenantId), String(flags['status'] ?? 'cleared'));
+async function snapshotClear(hippoRoot, tenantId, flags) {
+    const status = stringFlagOrExit(flags, 'status') ?? 'cleared';
+    const cleared = await apiSnapshotClear(cliApiContext(hippoRoot, tenantId), status);
     if (!cleared) {
         console.log('No active task snapshot to clear.');
         return;
     }
     console.log('Cleared active task snapshot.');
 }
-function snapshotShow(hippoRoot, tenantId, flags) {
-    const snapshot = snapshotLoad(cliApiContext(hippoRoot, tenantId));
+async function snapshotShow(hippoRoot, tenantId, flags) {
+    const snapshot = await snapshotLoad(cliApiContext(hippoRoot, tenantId));
     if (!snapshot) {
         if (flags['json']) {
             console.log(JSON.stringify({ snapshot: null }));
@@ -57,7 +57,7 @@ function snapshotShow(hippoRoot, tenantId, flags) {
     }
     printActiveTaskSnapshot(snapshot);
 }
-export function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
+export async function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'save')
@@ -66,30 +66,29 @@ export function handleSnapshot({ hippoRoot, tenantId, args, flags }) {
         return snapshotClear(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
         return snapshotShow(hippoRoot, tenantId, flags);
-    printError('Usage: hippo snapshot <save|show|clear>');
-    throw new CliExit(1);
+    fail('Usage: hippo snapshot <save|show|clear>');
 }
-function sessionLog(hippoRoot, tenantId, s, flags) {
-    const eventType = String(flags['type'] ?? 'note').trim();
-    const content = String(flags['content'] ?? '').trim();
+async function sessionLog(hippoRoot, tenantId, s, flags) {
+    const eventType = stringFlagOrExit(flags, 'type') ?? 'note';
+    const content = stringFlagOrExit(flags, 'content') ?? '';
     if (!s.sessionId || !content) {
-        printError('Usage: hippo session log --id <session-id> --content <text> [--type <type>] [--task <task>] [--source <source>]');
-        throw new CliExit(1);
+        fail('Usage: hippo session log --id <session-id> --content <text> [--type <type>] [--task <task>] ' +
+            '[--source <source>]');
     }
-    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
+    const event = await sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: s.sessionId,
         task: s.task || null,
         event_type: eventType || 'note',
         content,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
     });
     console.log(`Logged session event #${event.id}`);
     console.log(`   Session: ${event.session_id}`);
     console.log(`   Type: ${event.event_type}`);
 }
-function sessionShow(hippoRoot, tenantId, s, flags) {
-    const events = sessionEventList(cliApiContext(hippoRoot, tenantId), {
-        session_id: s.sessionId || undefined,
+async function sessionShow(hippoRoot, tenantId, s, flags) {
+    const events = await sessionEventList(cliApiContext(hippoRoot, tenantId), {
+        sessionId: s.sessionId || undefined,
         task: s.task || undefined,
         limit: s.limit,
     });
@@ -99,8 +98,8 @@ function sessionShow(hippoRoot, tenantId, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionLatest(hippoRoot, tenantId, s, flags) {
-    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), {
+async function sessionLatest(hippoRoot, tenantId, s, flags) {
+    const { snapshot, events } = await continuityLatest(cliApiContext(hippoRoot, tenantId), {
         sessionId: s.sessionId,
         limit: s.limit,
     });
@@ -117,41 +116,39 @@ function sessionLatest(hippoRoot, tenantId, s, flags) {
     }
     printSessionEvents(events);
 }
-function sessionComplete(hippoRoot, tenantId, s, flags) {
+async function sessionComplete(hippoRoot, tenantId, s, flags) {
     const { sessionId, task } = s;
-    const outcomeRaw = String(flags['outcome'] ?? '').trim();
-    const summary = String(flags['summary'] ?? '').trim();
+    const outcomeRaw = stringFlagOrExit(flags, 'outcome') ?? '';
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
     if (!sessionId) {
-        printError('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
-        throw new CliExit(1);
+        fail('Usage: hippo session complete --session <session-id> --outcome <success|failure|partial> [--summary "..."]');
     }
     if (!isHandoffOutcome(outcomeRaw)) {
-        printError(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
-        throw new CliExit(1);
+        fail(`Invalid outcome: "${outcomeRaw}". Must be one of: success, failure, partial.`);
     }
     const outcome = outcomeRaw;
     const metadata = { ended_at: new Date().toISOString() };
     if (summary)
         metadata.summary = summary;
-    const event = sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
+    const event = await sessionEventAppend(cliApiContext(hippoRoot, tenantId), {
         session_id: sessionId,
         task: task || null,
         event_type: 'session_complete',
         content: outcome,
-        source: String(flags['source'] ?? 'cli'),
+        source: stringFlagOrExit(flags, 'source') ?? 'cli',
         metadata,
     });
     console.log(`Completed session ${event.session_id} with outcome=${outcome} (event #${event.id})`);
-    const stamped = handoffStampOutcome(cliApiContext(hippoRoot, tenantId), sessionId, outcome);
+    const stamped = await handoffStampOutcome(cliApiContext(hippoRoot, tenantId), sessionId, outcome);
     if (stamped > 0) {
         console.log(`Stamped outcome on handoff for session ${sessionId}`);
     }
 }
-export function handleSession({ hippoRoot, tenantId, args, flags }) {
+export async function handleSession({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
-    const sessionId = String(flags['id'] ?? flags['session'] ?? '').trim();
-    const task = String(flags['task'] ?? '').trim();
+    const sessionId = stringFlagOrExit(flags, 'id') ?? stringFlagOrExit(flags, 'session') ?? '';
+    const task = stringFlagOrExit(flags, 'task') ?? '';
     const limit = Math.max(1, numberFlag(flags, 'limit') || 8);
     const s = { sessionId, task, limit };
     if (subcommand === 'log')
@@ -164,11 +161,10 @@ export function handleSession({ hippoRoot, tenantId, args, flags }) {
         return sessionComplete(hippoRoot, tenantId, s, flags);
     if (subcommand === 'resume')
         return sessionResume(hippoRoot, tenantId, sessionId);
-    printError('Usage: hippo session <log|show|latest|resume|complete>');
-    throw new CliExit(1);
+    fail('Usage: hippo session <log|show|latest|resume|complete>');
 }
-function sessionResume(hippoRoot, tenantId, sessionId) {
-    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId || undefined);
+async function sessionResume(hippoRoot, tenantId, sessionId) {
+    const handoff = await apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId || undefined);
     if (!handoff) {
         console.log('No handoff to resume from.');
         return;
@@ -215,37 +211,30 @@ function sessionResume(hippoRoot, tenantId, sessionId) {
 function flagList(value) {
     return Array.isArray(value) ? value : (isStringFlag(value) ? [value] : []);
 }
-const HANDOFF_CREATE_USAGE = 'Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] [--task <id>] [--artifact <path>...] ' +
+const HANDOFF_CREATE_USAGE = 'Usage: hippo handoff create --summary "..." [--next "..."] [--session <id>] ' +
+    '[--task <id>] [--artifact <path>...] ' +
     '[--constraint <text>...] [--outcome <success|failure|partial>] [--target-runtime <name>] [--card-id <id>] ' +
     '[--tests <pass|fail|unknown>]';
-function handoffCreate(hippoRoot, tenantId, flags) {
-    const summary = String(flags['summary'] ?? '').trim();
+async function handoffCreate(hippoRoot, tenantId, flags) {
+    const summary = stringFlagOrExit(flags, 'summary') ?? '';
     if (!summary) {
-        printError(HANDOFF_CREATE_USAGE);
-        throw new CliExit(1);
+        fail(HANDOFF_CREATE_USAGE);
     }
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw !== undefined && !isHandoffOutcome(outcomeRaw)) {
-        printError(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
-        throw new CliExit(1);
+        fail(`Invalid outcome: "${String(outcomeRaw)}". Must be one of: success, failure, partial.`);
     }
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || `fallback-${Date.now()}-${process.pid}`;
-    const nextAction = String(flags['next'] ?? '').trim() || undefined;
-    const taskId = String(flags['task'] ?? '').trim() || undefined;
+    const sessionId = (stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '') ||
+        `fallback-${Date.now()}-${process.pid}`;
+    const nextAction = stringFlagOrExit(flags, 'next') || undefined;
+    const taskId = stringFlagOrExit(flags, 'task') || undefined;
     const artifacts = flagList(flags['artifact']);
     const constraints = flagList(flags['constraint']);
-    for (const name of ['target-runtime', 'card-id']) {
-        // parseArgs turns a value-less flag into `true`; refuse rather than store "true".
-        if (flags[name] === true) {
-            printError(`--${name} needs a value`);
-            throw new CliExit(1);
-        }
-    }
-    const targetRuntime = String(flags['target-runtime'] ?? '').trim() || undefined;
-    const cardId = String(flags['card-id'] ?? '').trim() || undefined;
-    const testStatus = String(flags['tests'] ?? '').trim();
+    const targetRuntime = stringFlagOrExit(flags, 'target-runtime') || undefined;
+    const cardId = stringFlagOrExit(flags, 'card-id') || undefined;
+    const testStatus = stringFlagOrExit(flags, 'tests') ?? '';
     const evidence = collectHandoffEvidence(process.cwd(), testStatus === 'pass' || testStatus === 'fail' ? testStatus : 'unknown');
-    const handoff = handoffSave(cliApiContext(hippoRoot, tenantId), {
+    const handoff = await handoffSave(cliApiContext(hippoRoot, tenantId), {
         version: 1,
         sessionId,
         repoRoot: process.cwd(),
@@ -282,9 +271,9 @@ function printCreatedHandoff(handoff) {
     if (handoff.evidence)
         console.log(`   Evidence: ${formatHandoffEvidenceLine(handoff.evidence)}`);
 }
-function handoffLatest(hippoRoot, tenantId, flags) {
-    const sessionId = String(flags['session'] ?? flags['id'] ?? '').trim() || undefined;
-    const handoff = apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId);
+async function handoffLatest(hippoRoot, tenantId, flags) {
+    const sessionId = (stringFlagOrExit(flags, 'session') ?? stringFlagOrExit(flags, 'id') ?? '') || undefined;
+    const handoff = await apiHandoffLatest(cliApiContext(hippoRoot, tenantId), sessionId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -300,18 +289,16 @@ function handoffLatest(hippoRoot, tenantId, flags) {
     }
     printHandoff(handoff);
 }
-function handoffShow(hippoRoot, tenantId, args, flags) {
+async function handoffShow(hippoRoot, tenantId, args, flags) {
     const idArg = args[1];
     if (!idArg) {
-        printError('Usage: hippo handoff show <id> [--json]');
-        throw new CliExit(1);
+        fail('Usage: hippo handoff show <id> [--json]');
     }
     const handoffId = parseInt(idArg, 10);
     if (!Number.isFinite(handoffId) || handoffId <= 0) {
-        printError(`Invalid handoff ID: ${idArg}`);
-        throw new CliExit(1);
+        fail(`Invalid handoff ID: ${idArg}`);
     }
-    const handoff = handoffById(cliApiContext(hippoRoot, tenantId), handoffId);
+    const handoff = await handoffById(cliApiContext(hippoRoot, tenantId), handoffId);
     if (!handoff) {
         if (flags['json']) {
             console.log(JSON.stringify({ handoff: null }));
@@ -327,7 +314,7 @@ function handoffShow(hippoRoot, tenantId, args, flags) {
     }
     printHandoff(handoff);
 }
-export function handleHandoff({ hippoRoot, tenantId, args, flags }) {
+export async function handleHandoff({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'latest';
     if (subcommand === 'create')
@@ -336,8 +323,7 @@ export function handleHandoff({ hippoRoot, tenantId, args, flags }) {
         return handoffLatest(hippoRoot, tenantId, flags);
     if (subcommand === 'show')
         return handoffShow(hippoRoot, tenantId, args, flags);
-    printError('Usage: hippo handoff <create|latest|show>');
-    throw new CliExit(1);
+    fail('Usage: hippo handoff <create|latest|show>');
 }
 function printCurrentState(snapshot, events) {
     console.log('# Current State\n');
@@ -362,9 +348,9 @@ function printCurrentState(snapshot, events) {
         }
     }
 }
-function currentShow(hippoRoot, tenantId, flags) {
+async function currentShow(hippoRoot, tenantId, flags) {
     const asJson = boolFlag(flags, 'json');
-    const { snapshot, events } = continuityLatest(cliApiContext(hippoRoot, tenantId), { limit: 5 });
+    const { snapshot, events } = await continuityLatest(cliApiContext(hippoRoot, tenantId), { limit: 5 });
     if (asJson) {
         console.log(JSON.stringify({
             snapshot: snapshot ?? null,
@@ -384,16 +370,15 @@ function currentShow(hippoRoot, tenantId, flags) {
     }
     printCurrentState(snapshot, events);
 }
-export function handleCurrent({ hippoRoot, tenantId, args, flags }) {
+export async function handleCurrent({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
     if (subcommand === 'show')
         return currentShow(hippoRoot, tenantId, flags);
-    printError('Usage: hippo current <show>');
-    throw new CliExit(1);
+    fail('Usage: hippo current <show>');
 }
 // Working Memory
-export function handleWm({ hippoRoot, tenantId, args, flags }) {
+export async function handleWm({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? '';
     if (subcommand === 'push')
@@ -401,34 +386,32 @@ export function handleWm({ hippoRoot, tenantId, args, flags }) {
     if (subcommand === 'read')
         return wmReadCmd(hippoRoot, tenantId, flags);
     if (subcommand === 'clear') {
-        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-        const count = workingMemoryClear(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
+        const scope = stringFlagOrExit(flags, 'scope') || undefined;
+        const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+        const count = await workingMemoryClear(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
         console.log(`Cleared ${count} working memory entries.`);
         return;
     }
     if (subcommand === 'flush') {
-        const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-        const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-        const count = workingMemoryFlush(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
+        const scope = stringFlagOrExit(flags, 'scope') || undefined;
+        const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+        const count = await workingMemoryFlush(cliApiContext(hippoRoot, tenantId), { scope, sessionId });
         console.log(`Flushed ${count} working memory entries.`);
         return;
     }
-    printError('Usage: hippo wm <push|read|clear|flush>');
-    throw new CliExit(1);
+    fail('Usage: hippo wm <push|read|clear|flush>');
 }
 const WM_DEFAULT_IMPORTANCE = 0.5;
-function wmPushCmd(hippoRoot, tenantId, flags) {
-    const scope = String(flags['scope'] ?? 'default').trim();
-    const content = String(flags['content'] ?? '').trim();
+async function wmPushCmd(hippoRoot, tenantId, flags) {
+    const scope = stringFlagOrExit(flags, 'scope') ?? 'default';
+    const content = stringFlagOrExit(flags, 'content') ?? '';
     const importance = numberFlag(flags, 'importance') ?? WM_DEFAULT_IMPORTANCE;
-    const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
-    const taskId = flags['task'] ? String(flags['task']).trim() : undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
+    const taskId = stringFlagOrExit(flags, 'task') || undefined;
     if (!content) {
-        printError('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
-        throw new CliExit(1);
+        fail('Usage: hippo wm push --scope <scope> --content "..." [--importance 0.8] [--session <id>] [--task <id>]');
     }
-    const id = workingMemoryPush(cliApiContext(hippoRoot, tenantId), {
+    const id = await workingMemoryPush(cliApiContext(hippoRoot, tenantId), {
         scope,
         content,
         importance,
@@ -437,11 +420,11 @@ function wmPushCmd(hippoRoot, tenantId, flags) {
     });
     console.log(`Pushed working memory #${id} (scope=${scope}, importance=${importance})`);
 }
-function wmReadCmd(hippoRoot, tenantId, flags) {
-    const scope = flags['scope'] ? String(flags['scope']).trim() : undefined;
-    const sessionId = flags['session'] ? String(flags['session']).trim() : undefined;
+async function wmReadCmd(hippoRoot, tenantId, flags) {
+    const scope = stringFlagOrExit(flags, 'scope') || undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     const limit = numberFlag(flags, 'limit') || 20;
-    const items = workingMemoryRead(cliApiContext(hippoRoot, tenantId), { scope, sessionId, limit });
+    const items = await workingMemoryRead(cliApiContext(hippoRoot, tenantId), { scope, sessionId, limit });
     if (flags['json']) {
         console.log(JSON.stringify({ items }, null, 2));
         return;

package/dist/cli/curate.d.ts

@@ -1,14 +1,15 @@
 import { type CommandContext } from './flag-values.js';
 export declare function handleOutcome({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
-export declare function handleConflicts({ hippoRoot, tenantId, flags }: CommandContext): void;
+export declare function handleConflicts({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 export declare function handleResolve({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleReject({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 export declare function handleRejections({ hippoRoot, tenantId, flags }: CommandContext): void;
 export declare function handleUnreject({ hippoRoot, tenantId, args, flags }: CommandContext): void;
 /** `hippo dormant [list|restore <id>|forget <id>]`: dormant memories are what sleep keeps instead of deleting
  * (on by default; `"dormant": { "enabled": false }` in .hippo/config.json deletes instead). */
-export declare function handleDormant({ hippoRoot, tenantId, args, flags }: CommandContext): void;
-/** `hippo quarantine [list] [--all] [--json] [--global]`, `quarantine approve <id>`, `quarantine reject <id>` (poisoning defence). */
+export declare function handleDormant({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
+/** `hippo quarantine [list] [--all] [--json] [--global]`,
+ * `quarantine approve <id>`, `quarantine reject <id>` (poisoning defence). */
 export declare function handleQuarantine({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleForget({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleInvalidate({ hippoRoot, tenantId, args, flags }: CommandContext): void;