hippo-memory 1.72.0 → 2.1.0

package/dist/cli/auth.js

@@ -5,7 +5,7 @@ import { printError } from './output.js';
 import { boolFlag, stringFlag } from './flag-values.js';
 import { resolveAuthRoot } from './shared.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 // ---------------------------------------------------------------------------
 // Auth subcommands
 // ---------------------------------------------------------------------------
@@ -13,8 +13,7 @@ import { CliExit } from './exit.js';
 function roleFlagOrExit(flags) {
     const roleFlag = stringFlag(flags, 'role');
     if (roleFlag !== undefined && roleFlag !== 'admin' && roleFlag !== 'member') {
-        printError(`Invalid --role value: '${roleFlag}'. Use 'admin' or 'member'.`);
-        throw new CliExit(1);
+        fail(`Invalid --role value: '${roleFlag}'. Use 'admin' or 'member'.`);
     }
     return roleFlag;
 }
@@ -28,7 +27,7 @@ function noteMintDefaults(roleGiven, expiryGiven) {
     if (notes.length > 0)
         printError(`hippo auth create: ${notes.join('; ')}.`);
 }
-function cmdAuthCreate(hippoRoot, defaultTenantId, flags) {
+async function cmdAuthCreate(hippoRoot, defaultTenantId, flags) {
     const root = resolveAuthRoot(hippoRoot, flags);
     const tenantFlag = stringFlag(flags, 'tenant');
     const labelFlag = stringFlag(flags, 'label');
@@ -37,21 +36,20 @@ function cmdAuthCreate(hippoRoot, defaultTenantId, flags) {
     const ttlFlag = stringFlag(flags, 'ttl-days');
     const ttlDays = ttlFlag === undefined ? undefined : Number(ttlFlag);
     const noExpiry = boolFlag(flags, 'no-expiry');
-    // The CLI's --tenant flag is the only legitimate cross-tenant override
-    // (admin minting a key for another tenant from the local machine). It
-    // flows through ctx.tenantId, NOT through opts — authCreate's opts no
-    // longer accepts a tenantId field, so the HTTP layer cannot smuggle a
-    // body.tenantId across.
+    // The CLI's --tenant flag is the only legitimate cross-tenant
+    // override (admin minting a key for another tenant from the
+    // local machine). It flows through ctx.tenantId, NOT through
+    // opts — authCreate's opts no longer accepts a tenantId field,
+    // so the HTTP layer cannot smuggle a body.tenantId across.
     const ctx = cliApiContext(root, tenantFlag ?? defaultTenantId);
     let result;
     try {
-        result = api.authCreate(ctx, { label: labelFlag, role, ttlDays, noExpiry: noExpiry || undefined });
+        result = await api.authCreate(ctx, { label: labelFlag, role, ttlDays, noExpiry: noExpiry || undefined });
     }
     catch (err) {
         if (!(err instanceof api.BadRequestError))
             throw err;
-        printError(`hippo auth create: ${err.message} (--ttl-days, --no-expiry).`);
-        throw new CliExit(1);
+        fail(`hippo auth create: ${err.message} (--ttl-days, --no-expiry).`);
     }
     noteMintDefaults(role !== undefined, ttlFlag !== undefined || noExpiry);
     if (asJson) {
@@ -103,8 +101,7 @@ async function keyContext(root, tenantId, keyId) {
     const hostCtx = cliApiContext(root, tenantId);
     const keyTenant = await api.authKeyTenant(hostCtx, keyId);
     if (keyTenant === undefined) {
-        printError(`Unknown key_id: ${keyId}`);
-        throw new CliExit(1);
+        fail(`Unknown key_id: ${keyId}`);
     }
     return { ...hostCtx, tenantId: keyTenant };
 }
@@ -112,11 +109,10 @@ async function cmdAuthRevoke(hippoRoot, tenantId, keyId, flags) {
     const ctx = await keyContext(resolveAuthRoot(hippoRoot, flags), tenantId, keyId);
     let revokedAt;
     try {
-        revokedAt = api.authRevoke(ctx, keyId).revokedAt;
+        revokedAt = (await api.authRevoke(ctx, keyId)).revokedAt;
     }
     catch (err) {
-        printError(`Error: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Error: ${errorMessage(err)}`);
     }
     if (flags['json']) {
         console.log(JSON.stringify({ keyId, revokedAt }));
@@ -124,18 +120,18 @@ async function cmdAuthRevoke(hippoRoot, tenantId, keyId, flags) {
     }
     console.log(`Revoked ${keyId} at ${revokedAt}`);
 }
-/** `hippo auth grant|ungrant <key_id> <scope>`, routed through api so the tenant, restricted-scope and audit checks live in one place. */
+/** `hippo auth grant|ungrant <key_id> <scope>`, routed through api so the tenant, restricted-scope and audit checks
+ * live in one place. */
 async function cmdAuthScopeGrant(hippoRoot, tenantId, keyId, scope, grant, flags) {
     const ctx = await keyContext(resolveAuthRoot(hippoRoot, flags), tenantId, keyId);
     try {
         if (grant)
-            api.authGrant(ctx, keyId, scope);
+            await api.authGrant(ctx, keyId, scope);
         else
-            api.authUngrant(ctx, keyId, scope);
+            await api.authUngrant(ctx, keyId, scope);
     }
     catch (err) {
-        printError(`Error: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Error: ${errorMessage(err)}`);
     }
     if (flags['json']) {
         console.log(JSON.stringify({ keyId, scope, granted: grant }));
@@ -146,13 +142,12 @@ async function cmdAuthScopeGrant(hippoRoot, tenantId, keyId, scope, grant, flags
 export async function handleAuth({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (!sub) {
-        printError('Usage: hippo auth <create|list|revoke|grant|ungrant> [options]');
-        throw new CliExit(1);
+        fail('Usage: hippo auth <create|list|revoke|grant|ungrant> [options]');
     }
     const subArgs = args.slice(1);
     switch (sub) {
         case 'create':
-            cmdAuthCreate(hippoRoot, tenantId, flags);
+            await cmdAuthCreate(hippoRoot, tenantId, flags);
             return;
         case 'list':
             cmdAuthList(hippoRoot, tenantId, flags);
@@ -160,8 +155,7 @@ export async function handleAuth({ hippoRoot, tenantId, args, flags }) {
         case 'revoke': {
             const keyId = subArgs[0];
             if (!keyId) {
-                printError('Usage: hippo auth revoke <key_id>');
-                throw new CliExit(1);
+                fail('Usage: hippo auth revoke <key_id>');
             }
             await cmdAuthRevoke(hippoRoot, tenantId, keyId, flags);
             return;
@@ -170,15 +164,13 @@ export async function handleAuth({ hippoRoot, tenantId, args, flags }) {
         case 'ungrant': {
             const [keyId, scope] = subArgs;
             if (!keyId || !scope) {
-                printError(`Usage: hippo auth ${sub} <key_id> <scope>`);
-                throw new CliExit(1);
+                fail(`Usage: hippo auth ${sub} <key_id> <scope>`);
             }
             await cmdAuthScopeGrant(hippoRoot, tenantId, keyId, scope, sub === 'grant', flags);
             return;
         }
         default:
-            printError(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke | grant | ungrant.`);
-            throw new CliExit(1);
+            fail(`Unknown auth subcommand: ${sub}. Expected: create | list | revoke | grant | ungrant.`);
     }
 }
 //# sourceMappingURL=auth.js.map

package/dist/cli/briefs.d.ts

@@ -1,2 +1,2 @@
-export declare const handleProjectBrief: (ctx: import("./flag-values.js").CommandContext) => void;
+export declare const handleProjectBrief: (ctx: import("./flag-values.js").CommandContext) => Promise<void>;
 //# sourceMappingURL=briefs.d.ts.map

package/dist/cli/briefs.js

@@ -3,28 +3,27 @@ import * as briefsModule from '../objects/project-briefs.js';
 import { errorMessage } from '../util/log.js';
 import { printError } from './output.js';
 import { boolFlag, stringFlag } from './flag-values.js';
-import { CliExit } from './exit.js';
+import { fail } from './exit.js';
 import { requiredText, versionedVerbs } from './versioned-verbs.js';
 function printBriefRow(b) {
     console.log(`#${b.id} [${b.status}] v${b.version} repo="${b.repo}" memory=${b.memoryId ?? '-'}`);
     if (b.changeSummary)
         console.log(`    change: ${b.changeSummary}`);
 }
-function briefRefresh(hippoRoot, tenantId, args, flags) {
+async function briefRefresh(objects, hippoRoot, tenantId, args, flags) {
     const repoRaw = args[1];
     if (!repoRaw) {
-        printError('Usage: hippo brief refresh "<repo>" [--dry-run]');
-        throw new CliExit(1);
+        fail('Usage: hippo brief refresh "<repo>" [--dry-run]');
     }
     const dryRun = boolFlag(flags, 'dry-run');
     try {
         if (dryRun) {
-            const { markdown, receiptCount } = briefsModule.assembleBriefFromReceipts(hippoRoot, tenantId, repoRaw);
+            const { markdown, receiptCount } = await briefsModule.briefFromReceipts(objects, tenantId, repoRaw);
             printError(`(dry-run: assembled from ${receiptCount} receipt(s); brief NOT written)`);
             console.log(markdown);
             return;
         }
-        const created = briefsModule.refreshBrief(hippoRoot, tenantId, repoRaw, 'cli');
+        const created = await briefsModule.refreshedBrief(objects, { hippoRoot, tenantId, actor: 'cli' }, repoRaw);
         console.log(`Project brief #${created.id} recorded (v${created.version}) for repo "${created.repo}".`);
         if (created.changeSummary)
             console.log(`  change: ${created.changeSummary}`);
@@ -32,11 +31,10 @@ function briefRefresh(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
+        fail(errorMessage(e));
     }
 }
-const briefKind = (hippoRoot, tenantId) => ({
+const briefKind = (objects, hippoRoot, tenantId) => ({
     names: { cmd: 'brief', noun: 'Project brief', idLabel: 'brief' },
     plural: 'project briefs',
     states: briefsModule.VALID_BRIEF_STATES,
@@ -52,13 +50,20 @@ const briefKind = (hippoRoot, tenantId) => ({
     bodyRequired: '--summary "<text>"',
     body: (flags) => requiredText(flags, 'summary'),
     keyOf: (b) => b.repo,
-    save: (repo, summary, extraTags, from) => briefsModule.saveProjectBrief(hippoRoot, tenantId, {
-        repo, summary, extraTags, changeSummary: from?.changeSummary, supersedesBriefId: from?.id,
+    save: (repo, summary, extraTags, from) => briefsModule.saveProjectBrief(objects, hippoRoot, tenantId, {
+        repo,
+        summary,
+        extraTags,
+        changeSummary: from?.changeSummary,
+        supersedesBriefId: from?.id,
     }),
     recorded: (b) => `Project brief recorded: #${b.id} (v${b.version}) for repo "${b.repo}"`,
-    list: (opts, flags) => briefsModule.loadProjectBriefs(hippoRoot, tenantId, { ...opts, repo: stringFlag(flags, 'repo')?.trim() || undefined }),
-    loadById: (id) => briefsModule.loadProjectBriefById(hippoRoot, tenantId, id),
-    close: (id) => briefsModule.closeProjectBrief(hippoRoot, tenantId, id),
+    list: (opts, flags) => briefsModule.loadProjectBriefs(objects, tenantId, {
+        ...opts,
+        repo: stringFlag(flags, 'repo')?.trim() || undefined,
+    }),
+    loadById: (id) => briefsModule.loadProjectBriefById(objects, tenantId, id),
+    close: (id) => briefsModule.closeProjectBrief(objects, tenantId, id),
     printRow: printBriefRow,
     printDetail: (b) => {
         console.log(`  repo: ${b.repo}`);
@@ -66,7 +71,7 @@ const briefKind = (hippoRoot, tenantId) => ({
         console.log(`  version: ${b.version}`);
         console.log(`  summary: ${b.summary}`);
     },
-    extra: { sub: 'refresh', run: (args, flags) => briefRefresh(hippoRoot, tenantId, args, flags) },
+    extra: { sub: 'refresh', run: (args, flags) => briefRefresh(objects, hippoRoot, tenantId, args, flags) },
 });
 export const handleProjectBrief = versionedVerbs(briefKind);
 //# sourceMappingURL=briefs.js.map

package/dist/cli/card.d.ts

@@ -1,4 +1,4 @@
 import { type CommandContext } from './flag-values.js';
 /** Runs `hippo card <subcommand>`: rejects flags the subcommand never reads, then hands off to its handler. */
-export declare function handleCard({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleCard({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=card.d.ts.map

package/dist/cli/card.js

@@ -1,5 +1,5 @@
 // The `hippo card` verb (the agent work board); main() loads it lazily from the command table.
-import * as cardsApi from '../api/cards.js';
+import * as cardsApi from '../api/objects/cards.js';
 import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome } from '../core/handoff.js';
 import { isCardStatus } from '../core/card.js';
@@ -7,7 +7,7 @@ import { printError } from './output.js';
 import { stringFlagOrExit } from './flag-values.js';
 import { requireInit } from './shared.js';
 import { errorMessage } from '../util/log.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
 // Each subcommand's usage line, written once so the repeated checks cannot drift.
 const CARD_USAGE = {
     create: 'hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]',
@@ -50,7 +50,8 @@ function printCard(detail) {
     if (runs.length > 0) {
         console.log('\n### Runs');
         for (const run of runs) {
-            console.log(`- run ${run.id}: ${run.runtime} started ${run.started}${run.ended ? ` ended ${run.ended} (${run.outcome})` : ' (open)'}`);
+            const ended = run.ended ? ` ended ${run.ended} (${run.outcome})` : ' (open)';
+            console.log(`- run ${run.id}: ${run.runtime} started ${run.started}${ended}`);
         }
     }
     if (comments.length > 0) {
@@ -73,16 +74,15 @@ function cardRunFlag(flags) {
         return undefined;
     const n = Number(raw);
     if (!/^\d+$/.test(raw) || !Number.isSafeInteger(n) || n <= 0) {
-        printError(`Invalid --run: "${raw}" (expected a positive integer).`);
-        throw new CliExit(1);
+        fail(`Invalid --run: "${raw}" (expected a positive integer).`);
     }
     return n;
 }
 // Reads after the store already refused, so this only explains the refusal, never changes it.
-function cardRefusal(hippoRoot, tenantId, id) {
+async function cardRefusal(hippoRoot, tenantId, id) {
     const ctx = cliApiContext(hippoRoot, tenantId);
-    const card = cardsApi.cardLoad(ctx, id);
-    const liveRun = cardsApi.cardRuns(ctx, id).find((r) => !r.ended);
+    const card = await cardsApi.cardLoad(ctx, id);
+    const liveRun = (await cardsApi.cardRuns(ctx, id)).find((r) => !r.ended);
     return `status ${card?.status ?? 'unknown'}, live run ${liveRun?.id ?? 'none'}`;
 }
 const CARD_SUBCOMMAND_FLAGS = {
@@ -102,8 +102,7 @@ export function handleCard({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? '';
     if (!Object.hasOwn(CARD_SUBCOMMAND_FLAGS, subcommand)) {
-        printError('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
-        throw new CliExit(1);
+        fail('Usage: hippo card <create|show|list|claim|heartbeat|block|review|complete|reclaim|comment>');
     }
     // SAFETY: hasOwn, unlike `in`, skips inherited keys such as constructor, so subcommand is a real key.
     const known = subcommand;
@@ -111,13 +110,12 @@ export function handleCard({ hippoRoot, tenantId, args, flags }) {
     for (const key of Object.keys(flags)) {
         if (!allowedFlags.includes(key)) {
             const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
-            printError(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
-            throw new CliExit(1);
+            fail(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
         }
     }
-    CARD_HANDLERS[known](hippoRoot, tenantId, args, flags);
+    return CARD_HANDLERS[known](hippoRoot, tenantId, args, flags);
 }
-function cardCreate(hippoRoot, tenantId, _args, flags) {
+async function cardCreate(hippoRoot, tenantId, _args, flags) {
     const title = stringFlagOrExit(flags, 'title') ?? '';
     if (!title) {
         throw usageError('create');
@@ -128,36 +126,32 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
     let budget;
     if (budgetRaw !== undefined) {
         if (!/^\d+$/.test(budgetRaw)) {
-            printError(`Invalid budget: "${budgetRaw}" (expected a positive integer)`);
-            throw new CliExit(1);
+            fail(`Invalid budget: "${budgetRaw}" (expected a positive integer)`);
         }
         budget = Number(budgetRaw);
     }
     const dependsOnFlag = flags['depends-on'];
     if (dependsOnFlag === true) {
-        printError('--depends-on requires a value');
-        throw new CliExit(1);
+        fail('--depends-on requires a value');
     }
     const dependsOn = Array.isArray(dependsOnFlag) ? dependsOnFlag : [];
     let card;
     try {
-        card = cardsApi.cardCreate(cliApiContext(hippoRoot, tenantId), { title, repo, contract, budget, dependsOn });
+        card = await cardsApi.cardCreate(cliApiContext(hippoRoot, tenantId), { title, repo, contract, budget, dependsOn });
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     console.log(`Created card ${card.id} (status: ${card.status})`);
 }
-function cardShow(hippoRoot, tenantId, args, flags) {
+async function cardShow(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         throw usageError('show');
     }
-    const detail = cardsApi.cardDetail(cliApiContext(hippoRoot, tenantId), id);
+    const detail = await cardsApi.cardDetail(cliApiContext(hippoRoot, tenantId), id);
     if (!detail) {
-        printError(`No card found with id ${id}.`);
-        throw new CliExit(1);
+        fail(`No card found with id ${id}.`);
     }
     if (flags['json']) {
         console.log(JSON.stringify(detail, null, 2));
@@ -165,13 +159,12 @@ function cardShow(hippoRoot, tenantId, args, flags) {
     }
     printCard(detail);
 }
-function cardList(hippoRoot, tenantId, _args, flags) {
+async function cardList(hippoRoot, tenantId, _args, flags) {
     const status = stringFlagOrExit(flags, 'status');
     if (status !== undefined && !isCardStatus(status)) {
-        printError(`Invalid status: "${status}".`);
-        throw new CliExit(1);
+        fail(`Invalid status: "${status}".`);
     }
-    const cards = cardsApi.cardList(cliApiContext(hippoRoot, tenantId), { status });
+    const cards = await cardsApi.cardList(cliApiContext(hippoRoot, tenantId), { status });
     if (flags['json']) {
         console.log(JSON.stringify({ cards }, null, 2));
         return;
@@ -181,10 +174,11 @@ function cardList(hippoRoot, tenantId, _args, flags) {
         return;
     }
     for (const card of cards) {
-        console.log(`${card.id}\t${card.status}\t${card.title}${card.assigneeRuntime ? `\t(${card.assigneeRuntime})` : ''}`);
+        const assignee = card.assigneeRuntime ? `\t(${card.assigneeRuntime})` : '';
+        console.log(`${card.id}\t${card.status}\t${card.title}${assignee}`);
     }
 }
-function cardClaim(hippoRoot, tenantId, args, flags) {
+async function cardClaim(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runtime = stringFlagOrExit(flags, 'runtime') ?? '';
     if (!id || !runtime) {
@@ -193,19 +187,17 @@ function cardClaim(hippoRoot, tenantId, args, flags) {
     const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     let card;
     try {
-        card = cardsApi.cardClaim(cliApiContext(hippoRoot, tenantId), id, runtime, sessionId);
+        card = await cardsApi.cardClaim(cliApiContext(hippoRoot, tenantId), id, runtime, sessionId);
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     if (!card) {
-        printError(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
-        throw new CliExit(1);
+        fail(`Could not claim card ${id} (not ready/blocked, or already claimed).`);
     }
     console.log(`Claimed card ${card.id} for ${runtime} (run ${card.runId}, lease until ${card.leaseUntil})`);
 }
-function cardHeartbeat(hippoRoot, tenantId, args, flags) {
+async function cardHeartbeat(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runId = cardRunFlag(flags);
     if (!id || runId === undefined) {
@@ -213,42 +205,37 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
     }
     let card;
     try {
-        card = cardsApi.cardHeartbeat(cliApiContext(hippoRoot, tenantId), id, runId);
+        card = await cardsApi.cardHeartbeat(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     if (!card) {
-        printError(`Could not heartbeat card ${id} (${cardRefusal(hippoRoot, tenantId, id)}).`);
-        throw new CliExit(1);
+        fail(`Could not heartbeat card ${id} (${await cardRefusal(hippoRoot, tenantId, id)}).`);
     }
     console.log(`Heartbeat card ${card.id}: lease until ${card.leaseUntil}`);
 }
-function cardBlock(hippoRoot, tenantId, args, flags) {
+async function cardBlock(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const reason = stringFlagOrExit(flags, 'reason') ?? '';
     if (!id || !reason) {
-        printError(CARD_BLOCK_REASON_REQUIRED);
-        throw new CliExit(1);
+        fail(CARD_BLOCK_REASON_REQUIRED);
     }
     const runId = cardRunFlag(flags);
     let card;
     try {
-        card = cardsApi.cardBlock(cliApiContext(hippoRoot, tenantId), id, reason, runId);
+        card = await cardsApi.cardBlock(cliApiContext(hippoRoot, tenantId), id, reason, runId);
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     if (!card) {
-        const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
-        printError(`Could not block card ${id} (${why}).`);
-        throw new CliExit(1);
+        const why = runId === undefined ? 'not running' : await cardRefusal(hippoRoot, tenantId, id);
+        fail(`Could not block card ${id} (${why}).`);
     }
     console.log(`Blocked card ${card.id}`);
 }
-function cardReview(hippoRoot, tenantId, args, flags) {
+async function cardReview(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         throw usageError('review');
@@ -256,20 +243,18 @@ function cardReview(hippoRoot, tenantId, args, flags) {
     const runId = cardRunFlag(flags);
     let card;
     try {
-        card = cardsApi.cardReview(cliApiContext(hippoRoot, tenantId), id, runId);
+        card = await cardsApi.cardReview(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     if (!card) {
-        const why = runId === undefined ? 'not running' : cardRefusal(hippoRoot, tenantId, id);
-        printError(`Could not move card ${id} to review (${why}).`);
-        throw new CliExit(1);
+        const why = runId === undefined ? 'not running' : await cardRefusal(hippoRoot, tenantId, id);
+        fail(`Could not move card ${id} to review (${why}).`);
     }
     console.log(`Card ${card.id} moved to review`);
 }
-function cardComplete(hippoRoot, tenantId, args, flags) {
+async function cardComplete(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const outcomeRaw = flags['outcome'];
     if (!id || !isHandoffOutcome(outcomeRaw)) {
@@ -278,27 +263,25 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
     const runId = cardRunFlag(flags);
     let result;
     try {
-        result = cardsApi.cardComplete(cliApiContext(hippoRoot, tenantId), id, outcomeRaw, runId);
+        result = await cardsApi.cardComplete(cliApiContext(hippoRoot, tenantId), id, outcomeRaw, runId);
     }
     catch (error) {
-        printError(errorMessage(error));
-        throw new CliExit(1);
+        fail(errorMessage(error));
     }
     if (!result) {
-        const why = runId === undefined ? 'not in review' : cardRefusal(hippoRoot, tenantId, id);
-        printError(`Could not complete card ${id} (${why}).`);
-        throw new CliExit(1);
+        const why = runId === undefined ? 'not in review' : await cardRefusal(hippoRoot, tenantId, id);
+        fail(`Could not complete card ${id} (${why}).`);
     }
     console.log(`Completed card ${result.card.id} (status: ${result.card.status})`);
     if (result.promotedChildren.length > 0) {
         console.log(`Promoted to ready: ${result.promotedChildren.join(', ')}`);
     }
 }
-function cardReclaim(hippoRoot, tenantId, args) {
+async function cardReclaim(hippoRoot, tenantId, args) {
     if (args.length > 1) {
         throw usageError('reclaim');
     }
-    const ids = cardsApi.cardReclaimExpired(cliApiContext(hippoRoot, tenantId));
+    const ids = await cardsApi.cardReclaimExpired(cliApiContext(hippoRoot, tenantId));
     if (ids.length === 0) {
         console.log('No expired leases.');
         return;
@@ -307,24 +290,24 @@ function cardReclaim(hippoRoot, tenantId, args) {
         console.log(`Reclaimed card ${id} (now ready)`);
     }
 }
-function cardComment(hippoRoot, tenantId, args, flags) {
+async function cardComment(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
         throw usageError('comment');
     }
-    // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store instead.
+    // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store
+    // instead.
     const ctx = cliApiContext(hippoRoot, tenantId);
-    const card = cardsApi.cardLoad(ctx, id);
+    const card = await cardsApi.cardLoad(ctx, id);
     if (!card) {
-        printError(`No card found with id ${id}.`);
-        throw new CliExit(1);
+        fail(`No card found with id ${id}.`);
     }
     const body = stringFlagOrExit(flags, 'body') ?? '';
     if (!body) {
         throw usageError('comment');
     }
     const author = stringFlagOrExit(flags, 'author') || 'cli';
-    const comment = cardsApi.cardComment(ctx, id, author, body);
+    const comment = await cardsApi.cardComment(ctx, id, author, body);
     console.log(`Added comment ${comment.id} to card ${id}`);
 }
 const CARD_HANDLERS = {

package/dist/cli/client.d.ts

@@ -1,8 +1,13 @@
-/** HTTP client wrapper for `hippo serve`: only the routed writes (remember, forget, archive, promote); every other command opens the store directly.
- * Server errors rethrow with the message verbatim so CLI substring matches still work; network errors propagate as the native fetch failure. */
+/**
+ * HTTP client wrapper for `hippo serve`: only the routed writes (remember, forget, archive, promote); every other
+ * command opens the store directly.
+ * Server errors rethrow with the message verbatim so CLI substring matches still work; network errors propagate as the
+ * native fetch failure.
+ */
 import type { RememberOpts, RememberResult } from '../api/index.js';
-/** An error the server answered with, not one the transport raised: the refused-connection classifier sniffs message text,
- *  and a server message quotes the caller's own id or content back verbatim. */
+/**
+ * An error the server answered with, not one the transport raised, so the transport classifier can skip it by class.
+ */
 export declare class HttpResponseError extends Error {
     readonly status: number;
     constructor(message: string, status: number);
@@ -26,7 +31,9 @@ export declare function archiveRaw(serverUrl: string, apiKey: string | undefined
     ok: true;
     archivedAt: string;
 }>;
-/** 'never-sent': connection never opened, safe to replay locally. 'delivery-unknown': the request was on the wire and may have
+/**
+ * 'never-sent': connection never opened, safe to replay locally. 'delivery-unknown': the request was on the wire and
+ * may have
  * committed, so never replay a write. 'none': not a transport failure. */
 export type TransportFailure = 'none' | 'never-sent' | 'delivery-unknown';
 export declare function classifyTransportFailure(err: Error): TransportFailure;