hippo-memory 1.72.0 → 2.1.0

package/dist/cli/eval.js

@@ -1,34 +1,35 @@
 // The `hippo eval` verb; main() loads it lazily from the command table.
 import * as path from 'path';
 import * as fs from 'fs';
-import { listMemories } from '../api/memories.js';
+import { listMemories } from '../api/memories/memories.js';
 import { cliApiContext } from './api-context.js';
 import { loadConfig } from '../core/config.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import { runEval, bootstrapCorpus, compareSummaries } from '../eval/eval.js';
-import { runFeatureEval, formatResult, resultToBaseline, detectRegressions } from '../eval/eval-suite.js';
+import { runFeatureEval, formatResult, resultToBaseline, detectRegressions, } from '../eval/eval-suite.js';
 import { PACKAGE_VERSION } from '../util/version.js';
 import { printError } from './output.js';
 import { requireInit } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag, numberFlag } from './flag-values.js';
+import { boolFlag, numberFlag, stringFlagOrExit } from './flag-values.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
 const HIT_TOP_K = 10;
 const MAX_FAILING_SHOWN = 10;
 const TOP_IDS_SHOWN = 3;
 const MAX_MISSED_SHOWN = 4;
 const QUERY_PREVIEW_CHARS = 60;
 const MAX_DELTAS_SHOWN = 5;
-/** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus file. */
+/** Runs `hippo eval`: --bootstrap writes a corpus, --suite runs the built-in feature eval, else it scores a corpus
+ * file. */
 async function cmdEval(hippoRoot, tenantId, corpusPath, flags) {
     const asJson = boolFlag(flags, 'json');
     const minMrr = numberFlag(flags, 'min-mrr') ?? null;
-    const comparePath = flags['compare'] ? String(flags['compare']) : null;
+    const comparePath = stringFlagOrExit(flags, 'compare') || null;
     // Suite mode doesn't need an initialized store
     if (!flags['suite'])
         requireInit(hippoRoot);
-    const entries = flags['suite'] ? [] : listMemories(cliApiContext(hippoRoot, tenantId), { everyTenant: true });
+    const entries = flags['suite'] ? [] : await listMemories(cliApiContext(hippoRoot, tenantId), { everyTenant: true });
     if (flags['bootstrap']) {
         writeBootstrapCorpus(entries, flags);
         return;
@@ -45,8 +46,7 @@ async function cmdEval(hippoRoot, tenantId, corpusPath, flags) {
         printEvalSummary(summary, boolFlag(flags, 'show-cases'));
     }
     if (minMrr !== null && summary.meanMrr < minMrr) {
-        printError(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
-        throw new CliExit(1);
+        fail(`MRR ${fmt(summary.meanMrr, 4)} below threshold ${minMrr}`);
     }
     if (comparePath)
         printEvalCompare(summary, comparePath, asJson);
@@ -68,7 +68,7 @@ async function runCorpusEval(hippoRoot, corpusPath, entries, flags) {
 }
 /** Bootstrap mode: emit a synthetic corpus built from the store's own memories. */
 function writeBootstrapCorpus(entries, flags) {
-    const outPath = flags['out'] ? String(flags['out']) : null;
+    const outPath = stringFlagOrExit(flags, 'out') || null;
     const max = numberFlag(flags, 'max-cases') ?? 50;
     const corpus = bootstrapCorpus(entries, max);
     const payload = JSON.stringify({ cases: corpus }, null, 2);
@@ -83,7 +83,7 @@ function writeBootstrapCorpus(entries, flags) {
 }
 /** Suite mode: run the built-in feature eval (no corpus file needed, no init needed). */
 async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
-    const baselinePath = flags['baseline'] ? String(flags['baseline']) : path.join(hippoRoot, 'eval-baseline.json');
+    const baselinePath = stringFlagOrExit(flags, 'baseline') || path.join(hippoRoot, 'eval-baseline.json');
     let baseline;
     try {
         baseline = JSON.parse(fs.readFileSync(baselinePath, 'utf8'));
@@ -117,12 +117,10 @@ async function runEvalSuite(hippoRoot, flags, asJson, minMrr) {
 /** Loads the corpus file, exiting with the usage line or the read error when there is none to score. */
 function readCorpus(corpusPath) {
     if (!corpusPath) {
-        printError('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
-        throw new CliExit(1);
+        fail('Usage: hippo eval <corpus.json>  OR  hippo eval --suite [--save-baseline]  OR  hippo eval --bootstrap');
     }
     if (!fs.existsSync(corpusPath)) {
-        printError(`Corpus file not found: ${corpusPath}`);
-        throw new CliExit(1);
+        fail(`Corpus file not found: ${corpusPath}`);
     }
     let cases;
     try {
@@ -132,8 +130,7 @@ function readCorpus(corpusPath) {
             throw new Error('Corpus JSON must be an array or { cases: [...] }');
     }
     catch (err) {
-        printError(`Failed to read corpus: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Failed to read corpus: ${errorMessage(err)}`);
     }
     return cases;
 }
@@ -176,16 +173,14 @@ function printEvalSummary(summary, showCases) {
 }
 function printEvalCompare(summary, comparePath, asJson) {
     if (!fs.existsSync(comparePath)) {
-        printError(`Baseline file not found: ${comparePath}`);
-        throw new CliExit(1);
+        fail(`Baseline file not found: ${comparePath}`);
     }
     let baseline;
     try {
         baseline = JSON.parse(fs.readFileSync(comparePath, 'utf8'));
     }
     catch (err) {
-        printError(`Failed to parse baseline: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Failed to parse baseline: ${errorMessage(err)}`);
     }
     const cmp = compareSummaries(baseline, summary);
     if (asJson) {

package/dist/cli/exit.d.ts

@@ -1,6 +1,9 @@
-/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to
+ * print. */
 export declare class CliExit extends Error {
     readonly code: number;
     constructor(code: number);
 }
+/** Stops the verb with a message the user must act on: one call, so the text and the exit code 1 cannot drift apart. */
+export declare function fail(...args: unknown[]): never;
 //# sourceMappingURL=exit.d.ts.map

package/dist/cli/exit.js

@@ -1,5 +1,8 @@
-// The one error a CLI verb throws to stop its command; runCli is the one place that turns it into the process exit code.
-/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to print. */
+// The one error a CLI verb throws to stop its command; runCli is the one place that turns it into the process exit
+// code.
+import { printError } from './output.js';
+/** Thrown after the verb has printed its own message, so it carries the exit code and nothing for the entry to
+ * print. */
 export class CliExit extends Error {
     code;
     constructor(code) {
@@ -8,4 +11,9 @@ export class CliExit extends Error {
         this.code = code;
     }
 }
+/** Stops the verb with a message the user must act on: one call, so the text and the exit code 1 cannot drift apart. */
+export function fail(...args) {
+    printError(...args);
+    throw new CliExit(1);
+}
 //# sourceMappingURL=exit.js.map

package/dist/cli/explain.js

@@ -6,14 +6,14 @@ import { dropHeldCopies } from '../util/same-text.js';
 import { detectScope } from '../core/active-scope.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import * as api from '../api/index.js';
-import { cliRecallOrigin, scopeHiddenCount } from '../api/recall-cli.js';
+import { cliRecallOrigin, scopeHiddenCount } from '../api/recall/rows.js';
 import { cliApiContext } from './api-context.js';
 import { printedTokens } from '../api/context-render.js';
 import { printError } from './output.js';
-import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag } from './flag-values.js';
+import { parseLimitFlag, parseBudgetFlag, parseAsOfFlag, engineFlags, boolFlag, stringFlagOrExit, } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { fmt, recallEntryText, recallHeading } from './print.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 const EXPLAIN_PREVIEW_CHARS = 48;
 /** The SQL predicate drops denied rows before the window, so an unscoped probe counts what the policy hides. */
 function noteScopeHidden(ctx, globalRoot, query, requested) {
@@ -32,7 +32,7 @@ async function cmdExplain(hippoRoot, tenantId, query, flags) {
     const globalRoot = getGlobalRoot();
     const ctx = cliApiContext(hippoRoot, tenantId);
     // Explain shows what recall would see, so it applies the same scope rule.
-    const explicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
+    const explicitScope = stringFlagOrExit(flags, 'scope') ?? null;
     const activeScope = explicitScope || detectScope();
     // Unlike recall, explain reads the global store whenever it exists, even when it is the local root.
     const origin = cliRecallOrigin(ctx, { globalRoot, primaryIsGlobal: false, activeScope });
@@ -52,7 +52,7 @@ async function cmdExplain(hippoRoot, tenantId, query, flags) {
                 explicitScope, activeScope,
                 search: { ...engine, multihop: false, explain: true },
             },
-            sources: { globalRoot: explainGlobalOn ? globalRoot : undefined },
+            sources: explainGlobalOn ? { globalRoot, globalStore: cliApiContext(globalRoot, tenantId).store } : undefined,
             inspect: (ranking) => { slot.rank = ranking; },
         },
     });
@@ -112,8 +112,8 @@ function printExplainTable(results, query, modeUsed, candidates) {
         const b = r.breakdown;
         const preview = r.entry.content.replace(/\s+/g, ' ').slice(0, EXPLAIN_PREVIEW_CHARS);
         const ageStr = b ? `${b.ageDays}d` : '?';
-        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ${ageStr.padEnd(6)} ` +
-            `${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
+        console.log(`${String(i + 1).padEnd(5)} ${fmt(r.score, 3).padEnd(7)} ${fmt(r.entry.strength).padEnd(9)} ` +
+            `${ageStr.padEnd(6)} ${r.entry.layer.padEnd(10)} ${r.entry.id.padEnd(17)} ${preview}`);
     }
     console.log();
 }
@@ -140,8 +140,9 @@ function printExplainBreakdown(r, i) {
         console.log(`    recency:   x${fmt(b.recencyMultiplier, 3)}  (age=${b.ageDays}d)`);
         if (b.decisionBoost !== 1)
             console.log(`    decision:  x${fmt(b.decisionBoost, 2)}  (tagged 'decision')`);
-        if (b.scopeBoost !== 1)
+        if (b.scopeBoost !== 1) {
             console.log(`    scope:     x${fmt(b.scopeBoost, 2)}  (scope tag ${b.scopeBoost > 1 ? 'match' : 'mismatch'})`);
+        }
         if (b.pathBoost !== 1)
             console.log(`    path:      x${fmt(b.pathBoost, 3)}  (cwd path tag overlap)`);
         if (b.sourceBump !== 1)
@@ -150,8 +151,9 @@ function printExplainBreakdown(r, i) {
             console.log(`    outcome:   x${fmt(b.outcomeBoost, 3)}  ` +
                 `(user feedback: pos-neg = ${(r.entry.outcome_positive ?? 0) - (r.entry.outcome_negative ?? 0)})`);
         }
-        if (b.churnStaleMultiplier !== 1)
+        if (b.churnStaleMultiplier !== 1) {
             console.log(`    churn:     x${fmt(b.churnStaleMultiplier, 2)}  (tagged 'churn-stale')`);
+        }
         if (b.preMmrRank !== undefined && b.postMmrRank !== undefined && b.preMmrRank !== b.postMmrRank) {
             const arrow = b.postMmrRank < b.preMmrRank ? 'up' : 'down';
             console.log(`    mmr:       rank ${b.preMmrRank} -> ${b.postMmrRank}  (diversity ${arrow})`);
@@ -163,8 +165,7 @@ function printExplainBreakdown(r, i) {
 export async function handleExplain({ hippoRoot, tenantId, args, flags }) {
     const query = args.join(' ').trim();
     if (!query) {
-        printError('Please provide a search query.');
-        throw new CliExit(1);
+        fail('Please provide a search query.');
     }
     await cmdExplain(hippoRoot, tenantId, query, flags);
 }

package/dist/cli/flag-values.d.ts

@@ -1,4 +1,4 @@
-import type { RecallSearchOpts } from '../api/recall-pipeline.js';
+import type { RecallSearchOpts } from '../api/recall/pipeline.js';
 import type { HippoConfig } from '../core/config.js';
 export declare function isBooleanFlag(value: string | boolean | string[] | undefined): value is boolean;
 export declare function isStringFlag(value: string | boolean | string[] | undefined): value is string;

package/dist/cli/flag-values.js

@@ -1,7 +1,6 @@
 // Readers that turn parsed CLI flags into typed values, and the flag types they share.
 import { resolveListLimit } from '../util/limits.js';
-import { printError } from './output.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 export function isBooleanFlag(value) {
     return typeof value === 'boolean';
 }
@@ -25,14 +24,12 @@ export function parseBudgetFlag(value, fallback) {
         return fallback;
     // A value-less flag and a junk value are different typos; the --hops guard already splits them.
     if (!isStringFlag(value)) {
-        printError('--budget requires an integer value (e.g. --budget 1500).');
-        throw new CliExit(1);
+        fail('--budget requires an integer value (e.g. --budget 1500).');
     }
     // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
     const parsed = Number(value);
     if (!Number.isInteger(parsed) || parsed < 0) {
-        printError(`Invalid --budget: "${value}". Must be a non-negative integer.`);
-        throw new CliExit(1);
+        fail(`Invalid --budget: "${value}". Must be a non-negative integer.`);
     }
     return parsed;
 }
@@ -42,8 +39,7 @@ export function parsePositiveId(idRaw, label) {
     const s = String(idRaw ?? '').trim();
     const id = parseInt(s, 10);
     if (!/^\d+$/.test(s) || id <= 0 || !Number.isSafeInteger(id)) {
-        printError(`Invalid ${label} id: "${idRaw}" (expected a positive integer).`);
-        throw new CliExit(1);
+        fail(`Invalid ${label} id: "${idRaw}" (expected a positive integer).`);
     }
     return id;
 }
@@ -51,8 +47,7 @@ export function parseListLimit(flags) {
     const limitRaw = flags['limit'];
     const limit = resolveListLimit(limitRaw !== undefined ? parseInt(String(limitRaw), 10) : undefined);
     if (limit === undefined) {
-        printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        throw new CliExit(1);
+        fail(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
     }
     return limit;
 }
@@ -82,8 +77,7 @@ export function numberFlag(flags, name) {
         return undefined;
     const parsed = Number(v);
     if (v.trim() === '' || !Number.isFinite(parsed)) {
-        printError(`Invalid --${name}: "${v}". Must be a number.`);
-        throw new CliExit(1);
+        fail(`Invalid --${name}: "${v}". Must be a number.`);
     }
     return parsed;
 }
@@ -98,8 +92,7 @@ export function flagIsTrue(flags, name) {
 export function parseAsOfFlag(flags) {
     const asOf = stringFlag(flags, 'as-of');
     if (asOf !== undefined && Number.isNaN(new Date(asOf).getTime())) {
-        printError(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
-        throw new CliExit(1);
+        fail(`Error: --as-of value "${asOf}" is not a valid ISO date (e.g. 2026-04-22 or 2026-04-22T12:00:00Z).`);
     }
     return asOf;
 }
@@ -121,10 +114,8 @@ export function stringFlagOrExit(flags, key) {
     const v = flags[key];
     if (v === undefined)
         return undefined;
-    if (v === true || v === false || Array.isArray(v)) {
-        printError(`--${key} requires a value`);
-        throw new CliExit(1);
-    }
+    if (v === true || v === false || Array.isArray(v))
+        fail(`--${key} requires a value`);
     return v.trim();
 }
 //# sourceMappingURL=flag-values.js.map

package/dist/cli/github.d.ts

@@ -1,6 +1,7 @@
 /** `hippo github` subcommands, split out of cli.ts so tests can import them without triggering main().
  * The dispatcher in cli.ts re-exports handleGitHub. */
 import { type GitHubFetcher } from '../connectors/github/octokit-client.js';
+import type { JsonValue } from '../util/json.js';
 import type { CommandContext } from './flag-values.js';
 type FlagValue = string | boolean | string[];
 type Flags = Record<string, FlagValue>;
@@ -8,6 +9,11 @@ export declare function printGitHubBackfillUsage(): void;
 /** `hippo github backfill`; the fetcher is injectable so tests avoid the network (default `realGitHubFetcher`). */
 export declare function cmdGitHubBackfill(hippoRoot: string, tenantId: string, flags: Flags, fetcher?: GitHubFetcher): Promise<void>;
 export declare function cmdGitHubDlqList(hippoRoot: string, tenantId: string, _flags: Flags): void;
+/** A parked payload that is not JSON, naming the command and the start of the text so the operator can find the row. */
+export declare class GitHubPayloadParseError extends Error {
+    constructor(command: string, rawPayload: string, cause: unknown);
+}
+export declare function parseParkedPayload(rawPayload: string): JsonValue;
 export declare function cmdGitHubDlqReplay(hippoRoot: string, tenantId: string, args: string[], flags: Flags): Promise<void>;
 export declare function handleGitHub({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export {};

package/dist/cli/github.js

@@ -10,19 +10,22 @@ import { ingestEvent } from '../connectors/github/ingest.js';
 import { handleCommentDeleted } from '../connectors/github/deletion.js';
 import { computeDeletionKey } from '../connectors/github/signature.js';
 import { isGitHubIssueEvent, isGitHubIssueCommentEvent, isGitHubPullRequestEvent, isGitHubPullRequestReviewCommentEvent, } from '../connectors/github/types.js';
+import { cliApiContext } from './api-context.js';
 import { CliExit } from './exit.js';
 import { errorMessage } from '../util/log.js';
 function isFlagString(value) {
     return typeof value === 'string';
 }
-// FlagValue never includes `number`, so a `value is number` predicate on it would not type-check; the generic wrapper narrows any type T instead.
+// FlagValue never includes `number`, so a `value is number` predicate on it would not type-check; the generic wrapper
+// narrows any type T instead.
 function isNumberLike(value) {
     return typeof value === 'number';
 }
 function isFlagValueNumberLike(value) {
     return isNumberLike(value);
 }
-/** Map a parsed envelope + eventName header to an IngestEvent; null for unknown event types or shapes failing the type guards. */
+/** Map a parsed envelope + eventName header to an IngestEvent;
+ * null for unknown event types or shapes failing the type guards. */
 function parsedToIngestEvent(parsed, eventName) {
     if (eventName === 'issues' && isGitHubIssueEvent(parsed, eventName)) {
         return { eventName: 'issues', payload: parsed };
@@ -72,11 +75,7 @@ export async function cmdGitHubBackfill(hippoRoot, tenantId, flags, fetcher = re
     const maxPerStream = maxPerStreamFlag(flags['max']);
     const sinceFlag = flags['since'];
     const sinceIso = isFlagString(sinceFlag) ? sinceFlag : undefined;
-    const ctx = {
-        hippoRoot,
-        tenantId,
-        actor: adminActor('cli:github-backfill'),
-    };
+    const ctx = { ...cliApiContext(hippoRoot, tenantId), actor: adminActor('cli:github-backfill') };
     try {
         const result = await backfillRepo(ctx, {
             repoFullName: repo,
@@ -102,8 +101,25 @@ export function cmdGitHubDlqList(hippoRoot, tenantId, _flags) {
         console.log(`${it.id}\t${it.bucket}\t${it.tenantId}\t${it.eventName ?? '-'}\t${it.receivedAt}\t${it.error}`);
     }
 }
+const PAYLOAD_PREVIEW_CHARS = 200;
+/** A parked payload that is not JSON, naming the command and the start of the text so the operator can find the row. */
+export class GitHubPayloadParseError extends Error {
+    constructor(command, rawPayload, cause) {
+        const start = JSON.stringify(rawPayload.slice(0, PAYLOAD_PREVIEW_CHARS));
+        super(`${command}: payload is not valid JSON (${errorMessage(cause)}); starts with ${start}`, { cause });
+        this.name = 'GitHubPayloadParseError';
+    }
+}
+export function parseParkedPayload(rawPayload) {
+    try {
+        return JSON.parse(rawPayload);
+    }
+    catch (err) {
+        throw new GitHubPayloadParseError('hippo github dlq replay', rawPayload, err);
+    }
+}
 const reingestParkedDelivery = async (innerCtx, args) => {
-    const parsed = JSON.parse(args.rawPayload);
+    const parsed = parseParkedPayload(args.rawPayload);
     const event = parsedToIngestEvent(parsed, args.eventName);
     if (!event) {
         return { memoryId: null };
@@ -146,11 +162,7 @@ export async function cmdGitHubDlqReplay(hippoRoot, tenantId, args, flags) {
         throw new CliExit(1);
     }
     const force = flags['force'] === true;
-    const ctx = {
-        hippoRoot,
-        tenantId,
-        actor: adminActor('cli:github-dlq-replay'),
-    };
+    const ctx = { ...cliApiContext(hippoRoot, tenantId), actor: adminActor('cli:github-dlq-replay') };
     // Without an ingestHook replay only bumps retry_count while printing "replay ok"; the real hook re-runs ingest.
     const result = await replayDlqEntry(ctx, id, {
         force,

package/dist/cli/goals.d.ts

@@ -1,3 +1,3 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleGoal({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleGoal({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=goals.d.ts.map

package/dist/cli/goals.js

@@ -3,8 +3,8 @@ import { DEFAULT_TENANT_ID, envHippoSessionId } from '../util/env.js';
 import * as api from '../api/index.js';
 import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
-import { boolFlag, flagIsTrue, isStringFlag, stringFlag } from './flag-values.js';
-import { CliExit } from './exit.js';
+import { boolFlag, flagIsTrue, isStringFlag, stringFlag, stringFlagOrExit, } from './flag-values.js';
+import { fail } from './exit.js';
 // `hippo goal <push|list|complete|suspend|resume>`
 const GOAL_POLICY_TYPES = [
     'schema-fit-biased',
@@ -20,52 +20,42 @@ function sanitizeGoalName(s) {
     return s.replace(/[^\x20-\x7e\u0080-\uffff]/g, '?');
 }
 function resolveGoalSession(flags, defaultTenantId) {
-    const sessionId = (flags['session-id'] !== undefined
-        ? String(flags['session-id'])
-        : envHippoSessionId() ?? '').trim();
+    const sessionId = (stringFlagOrExit(flags, 'session-id') ?? envHippoSessionId() ?? '').trim();
     if (!sessionId) {
-        printError('session id required (set HIPPO_SESSION_ID or pass --session-id)');
-        throw new CliExit(1);
+        fail('session id required (set HIPPO_SESSION_ID or pass --session-id)');
     }
-    const tenantId = (flags['tenant-id'] !== undefined
-        ? String(flags['tenant-id'])
-        : defaultTenantId).trim() || DEFAULT_TENANT_ID;
+    const tenantId = (stringFlagOrExit(flags, 'tenant-id') ?? defaultTenantId).trim() || DEFAULT_TENANT_ID;
     return { sessionId, tenantId };
 }
 function readGoalPolicy(flags) {
     const policyRaw = flags['policy'];
     if (policyRaw === true) {
-        printError('--policy requires a value (e.g., --policy error-prioritized)');
-        throw new CliExit(1);
+        fail('--policy requires a value (e.g., --policy error-prioritized)');
     }
     if (!isStringFlag(policyRaw))
         return undefined;
     if (!isGoalPolicyType(policyRaw)) {
-        printError(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
-        throw new CliExit(1);
+        fail(`Unknown --policy '${policyRaw}'. Expected one of: ${GOAL_POLICY_TYPES.join(' | ')}.`);
     }
     return { policyType: policyRaw };
 }
 function readGoalLevel(flags) {
     const levelRaw = flags['level'];
     if (levelRaw === true) {
-        printError('--level requires a value (e.g., --level 1)');
-        throw new CliExit(1);
+        fail('--level requires a value (e.g., --level 1)');
     }
     if (levelRaw === undefined)
         return undefined;
     const parsed = Number(levelRaw);
     if (!Number.isFinite(parsed) || parsed < 0 || parsed > 2 || !Number.isInteger(parsed)) {
-        printError('--level must be an integer in [0, 2]');
-        throw new CliExit(1);
+        fail('--level must be an integer in [0, 2]');
     }
     return parsed;
 }
-function cmdGoalPush(hippoRoot, defaultTenantId, args, flags) {
+async function cmdGoalPush(hippoRoot, defaultTenantId, args, flags) {
     const rawName = args.join(' ').trim();
     if (!rawName) {
-        printError('Usage: hippo goal push <name> [--policy <type>] [--success "<condition>"] [--level N] [--parent <goalId>]');
-        throw new CliExit(1);
+        fail('Usage: hippo goal push <name> [--policy <type>] [--success "<condition>"] [--level N] [--parent <goalId>]');
     }
     // Sanitize at WRITE time so corrupt names never enter the DB.
     const name = sanitizeGoalName(rawName);
@@ -76,18 +66,16 @@ function cmdGoalPush(hippoRoot, defaultTenantId, args, flags) {
     const policy = readGoalPolicy(flags);
     const successRaw = flags['success'];
     if (successRaw === true) {
-        printError('--success requires a value (e.g., --success "<condition>")');
-        throw new CliExit(1);
+        fail('--success requires a value (e.g., --success "<condition>")');
     }
     const successCondition = stringFlag(flags, 'success');
     const level = readGoalLevel(flags);
     const parentRaw = flags['parent'];
     if (parentRaw === true) {
-        printError('--parent requires a value (e.g., --parent <goalId>)');
-        throw new CliExit(1);
+        fail('--parent requires a value (e.g., --parent <goalId>)');
     }
     const parentGoalId = stringFlag(flags, 'parent');
-    const goal = api.goalPush(cliApiContext(hippoRoot, tenantId), {
+    const goal = await api.goalPush(cliApiContext(hippoRoot, tenantId), {
         sessionId,
         goalName: name,
         level,
@@ -97,10 +85,10 @@ function cmdGoalPush(hippoRoot, defaultTenantId, args, flags) {
     });
     console.log(goal.id);
 }
-function cmdGoalList(hippoRoot, defaultTenantId, flags) {
+async function cmdGoalList(hippoRoot, defaultTenantId, flags) {
     const { sessionId, tenantId } = resolveGoalSession(flags, defaultTenantId);
     const showAll = boolFlag(flags, 'all');
-    const goals = api.goalList(cliApiContext(hippoRoot, tenantId), { sessionId, all: showAll });
+    const goals = await api.goalList(cliApiContext(hippoRoot, tenantId), { sessionId, all: showAll });
     if (goals.length === 0) {
         console.log('(no goals)');
         return;
@@ -119,79 +107,74 @@ function cmdGoalList(hippoRoot, defaultTenantId, flags) {
         outcome: Math.max(7, ...rows.map(r => r.outcome.length)),
     };
     const pad = (s, w) => s + ' '.repeat(Math.max(0, w - s.length));
-    console.log(`${pad('id', widths.id)}  ${pad('status', widths.status)}  ${pad('name', widths.name)}  ${pad('outcome', widths.outcome)}`);
+    console.log(`${pad('id', widths.id)}  ${pad('status', widths.status)}  ${pad('name', widths.name)}  ` +
+        pad('outcome', widths.outcome));
     for (const r of rows) {
-        console.log(`${pad(r.id, widths.id)}  ${pad(r.status, widths.status)}  ${pad(r.name, widths.name)}  ${pad(r.outcome, widths.outcome)}`);
+        console.log(`${pad(r.id, widths.id)}  ${pad(r.status, widths.status)}  ${pad(r.name, widths.name)}  ` +
+            pad(r.outcome, widths.outcome));
     }
 }
-function cmdGoalComplete(hippoRoot, tenantId, args, flags) {
+async function cmdGoalComplete(hippoRoot, tenantId, args, flags) {
     const id = args[0];
     if (!id) {
-        printError('Usage: hippo goal complete <id> [--outcome <0..1>] [--no-propagate]');
-        throw new CliExit(1);
+        fail('Usage: hippo goal complete <id> [--outcome <0..1>] [--no-propagate]');
     }
     let outcomeScore;
     const outcomeRaw = flags['outcome'];
     if (outcomeRaw === true) {
-        printError('--outcome requires a value (e.g., --outcome 0.9)');
-        throw new CliExit(1);
+        fail('--outcome requires a value (e.g., --outcome 0.9)');
     }
     if (outcomeRaw !== undefined) {
         const parsed = Number(outcomeRaw);
         if (!Number.isFinite(parsed) || parsed < 0 || parsed > 1) {
-            printError('--outcome must be a number in [0, 1]');
-            throw new CliExit(1);
+            fail('--outcome must be a number in [0, 1]');
         }
         outcomeScore = parsed;
     }
     const noPropagate = flagIsTrue(flags, 'no-propagate');
-    api.goalComplete(cliApiContext(hippoRoot, tenantId), id, { outcomeScore, noPropagate });
+    await api.goalComplete(cliApiContext(hippoRoot, tenantId), id, { outcomeScore, noPropagate });
     console.log('ok');
 }
-function cmdGoalSuspend(hippoRoot, tenantId, args) {
+async function cmdGoalSuspend(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
-        printError('Usage: hippo goal suspend <id>');
-        throw new CliExit(1);
+        fail('Usage: hippo goal suspend <id>');
     }
-    api.goalSuspend(cliApiContext(hippoRoot, tenantId), id);
+    await api.goalSuspend(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-function cmdGoalResume(hippoRoot, tenantId, args) {
+async function cmdGoalResume(hippoRoot, tenantId, args) {
     const id = args[0];
     if (!id) {
-        printError('Usage: hippo goal resume <id>');
-        throw new CliExit(1);
+        fail('Usage: hippo goal resume <id>');
     }
-    api.goalResume(cliApiContext(hippoRoot, tenantId), id);
+    await api.goalResume(cliApiContext(hippoRoot, tenantId), id);
     console.log('ok');
 }
-export function handleGoal({ hippoRoot, tenantId, args, flags }) {
+export async function handleGoal({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (!sub) {
-        printError('Usage: hippo goal <push|list|complete|suspend|resume> [args]');
-        throw new CliExit(1);
+        fail('Usage: hippo goal <push|list|complete|suspend|resume> [args]');
     }
     const subArgs = args.slice(1);
     switch (sub) {
         case 'push':
-            cmdGoalPush(hippoRoot, tenantId, subArgs, flags);
+            await cmdGoalPush(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'list':
-            cmdGoalList(hippoRoot, tenantId, flags);
+            await cmdGoalList(hippoRoot, tenantId, flags);
             return;
         case 'complete':
-            cmdGoalComplete(hippoRoot, tenantId, subArgs, flags);
+            await cmdGoalComplete(hippoRoot, tenantId, subArgs, flags);
             return;
         case 'suspend':
-            cmdGoalSuspend(hippoRoot, tenantId, subArgs);
+            await cmdGoalSuspend(hippoRoot, tenantId, subArgs);
             return;
         case 'resume':
-            cmdGoalResume(hippoRoot, tenantId, subArgs);
+            await cmdGoalResume(hippoRoot, tenantId, subArgs);
             return;
         default:
-            printError(`Unknown goal subcommand: ${sub}. Expected: push | list | complete | suspend | resume.`);
-            throw new CliExit(1);
+            fail(`Unknown goal subcommand: ${sub}. Expected: push | list | complete | suspend | resume.`);
     }
 }
 //# sourceMappingURL=goals.js.map

package/dist/cli/graph.d.ts

@@ -1,3 +1,3 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleGraph({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleGraph({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=graph.d.ts.map