hippo-memory 1.71.0 → 2.0.0

package/dist/cli/briefs.js

@@ -1,41 +1,15 @@
-// First-class object verbs for project briefs and customer notes, plus the entity graph.
-import * as fs from 'fs';
-import { spawn } from 'child_process';
-import { extractPathTags } from '../search/path-context.js';
+// The project brief verbs: one repo's brief, versioned by supersession and refreshable from the repo's receipts.
 import * as briefsModule from '../objects/project-briefs.js';
-import * as customerNotesModule from '../objects/customer-notes.js';
-import { extractGraph } from '../graph/extract.js';
-import { buildGraphModel, renderGraphHtml, renderGraphCanvas, DEFAULT_VIEW_LIMIT } from '../graph/view.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage } from '../util/log.js';
 import { printError } from './output.js';
-import { nonEmptyStringFlag, boolFlag, stringFlag } from './flag-values.js';
-import { requireInit } from './shared.js';
-import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail } from './object-verbs.js';
+import { boolFlag, stringFlag } from './flag-values.js';
 import { CliExit } from './exit.js';
-const BRIEF = { cmd: 'brief', noun: 'Project brief', idLabel: 'brief' };
-const NOTE = { cmd: 'note', noun: 'Customer note', idLabel: 'note' };
+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 briefUsage() {
-    printError('Usage: hippo brief new "<repo>" --summary "<text>"');
-    printError('       hippo brief list [--status active|superseded|closed|all] [--repo "<repo>"] [--limit N]');
-    printError('       hippo brief get <id>');
-    printError('       hippo brief supersede <id> --summary "<text>" [--change "<summary>"]');
-    printError('       hippo brief close <id>');
-    printError('       hippo brief refresh "<repo>" [--dry-run]   (auto-assemble the brief from the repo\'s receipts)');
-}
-function briefList(hippoRoot, tenantId, flags) {
-    const repo = stringFlag(flags, 'repo')?.trim() || undefined;
-    listObjects(flags, {
-        plural: 'project briefs',
-        states: briefsModule.VALID_BRIEF_STATES,
-        load: (opts) => briefsModule.loadProjectBriefs(hippoRoot, tenantId, { ...opts, repo }),
-        printRow: printBriefRow,
-    });
-}
 function briefRefresh(hippoRoot, tenantId, args, flags) {
     const repoRaw = args[1];
     if (!repoRaw) {
@@ -62,266 +36,37 @@ function briefRefresh(hippoRoot, tenantId, args, flags) {
         throw new CliExit(1);
     }
 }
-function briefGet(hippoRoot, tenantId, args) {
-    const id = idArgOrExit(args, 'Usage: hippo brief get <id>', BRIEF.idLabel);
-    const b = foundOrExit(briefsModule.loadProjectBriefById(hippoRoot, tenantId, id), BRIEF.noun, id);
-    console.log(`Project brief #${b.id}`);
-    console.log(`  repo: ${b.repo}`);
-    console.log(`  status: ${b.status}`);
-    console.log(`  version: ${b.version}`);
-    console.log(`  summary: ${b.summary}`);
-    printLifecycleTail(b);
-}
-function briefSupersede(hippoRoot, tenantId, args, flags) {
-    const id = idArgOrExit(args, 'Usage: hippo brief supersede <id> --summary "<text>" [--change "<summary>"]', BRIEF.idLabel);
-    const summaryRaw = stringFlag(flags, 'summary');
-    if (!summaryRaw?.trim()) {
-        printError('hippo brief supersede requires --summary "<text>" for the new version.');
-        throw new CliExit(1);
-    }
-    const existing = foundOrExit(briefsModule.loadProjectBriefById(hippoRoot, tenantId, id), BRIEF.noun, id);
-    try {
-        const created = briefsModule.saveProjectBrief(hippoRoot, tenantId, {
-            repo: existing.repo,
-            summary: summaryRaw,
-            changeSummary: nonEmptyStringFlag(flags, 'change'),
-            supersedesBriefId: id,
-            extraTags: extractPathTags(process.cwd()),
-        });
-        console.log(`Project brief #${created.id} recorded (v${created.version}), superseding #${id}.`);
-        if (created.memoryId)
-            console.log(`  memory: ${created.memoryId}`);
-    }
-    catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
-    }
-}
-function briefClose(hippoRoot, tenantId, args) {
-    closeObject(args, BRIEF, (id) => briefsModule.closeProjectBrief(hippoRoot, tenantId, id));
-}
-function briefCreate(hippoRoot, tenantId, args, flags) {
-    const subcommand = args[0] ?? '';
-    // Default subcommand: new (create). Accept both `brief new "<repo>"` and the
-    // bare `brief "<repo>"` form: for the `new` keyword the repo is args[1].
-    const repo = subcommand === 'new' ? (args[1] ?? '') : subcommand;
-    const summaryRaw = stringFlag(flags, 'summary');
-    if (!repo || !summaryRaw?.trim()) {
-        briefUsage();
-        throw new CliExit(1);
-    }
-    try {
-        const created = briefsModule.saveProjectBrief(hippoRoot, tenantId, {
-            repo,
-            summary: summaryRaw,
-            extraTags: extractPathTags(process.cwd()),
-        });
-        console.log(`Project brief recorded: #${created.id} (v${created.version}) for repo "${created.repo}"`);
-        if (created.memoryId)
-            console.log(`  memory: ${created.memoryId}`);
-    }
-    catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
-    }
-}
-export function handleProjectBrief({ hippoRoot, tenantId, args, flags }) {
-    requireInit(hippoRoot);
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'list')
-        return briefList(hippoRoot, tenantId, flags);
-    if (subcommand === 'refresh')
-        return briefRefresh(hippoRoot, tenantId, args, flags);
-    if (subcommand === 'get')
-        return briefGet(hippoRoot, tenantId, args);
-    if (subcommand === 'supersede')
-        return briefSupersede(hippoRoot, tenantId, args, flags);
-    if (subcommand === 'close')
-        return briefClose(hippoRoot, tenantId, args);
-    briefCreate(hippoRoot, tenantId, args, flags);
-}
-function printNoteRow(n) {
-    console.log(`#${n.id} [${n.status}] v${n.version} customer="${n.customer}" memory=${n.memoryId ?? '-'}`);
-    if (n.changeSummary)
-        console.log(`    change: ${n.changeSummary}`);
-}
-function noteUsage() {
-    printError('Usage: hippo note new "<customer>" --text "<note>"');
-    printError('       hippo note list [--status active|superseded|closed|all] [--customer "<id>"] [--limit N]');
-    printError('       hippo note get <id>');
-    printError('       hippo note supersede <id> --text "<note>" [--change "<summary>"]');
-    printError('       hippo note close <id>');
-}
-function graphExtract(hippoRoot, tenantId) {
-    const result = extractGraph(hippoRoot, tenantId);
-    const byType = Object.entries(result.byType)
-        .map(([t, n]) => `${t} ${n}`)
-        .join(', ');
-    const supersedes = result.relations - result.references;
-    console.log(`Graph extracted: ${result.entities} entities (${byType}) + ${result.relations} relations (${supersedes} supersedes, ${result.references} references).`);
-    if (result.truncated.length > 0) {
-        printError(`WARNING: under-extracted (hit the per-type cap): ${result.truncated.join(', ')}. The graph is incomplete for those types.`);
-    }
-}
-function graphShow(hippoRoot, tenantId, entity, flags) {
-    const model = buildGraphModel(hippoRoot, tenantId, { entity, limit: DEFAULT_VIEW_LIMIT });
-    if (flags['json']) {
-        console.log(JSON.stringify(model, null, 2));
-        return;
-    }
-    if (model.nodes.length === 0) {
-        console.log(entity ? `No entity named "${entity}".` : 'Graph is empty. Run `hippo graph extract` first.');
-        return;
-    }
-    console.log(`Graph: ${model.nodes.length} entities, ${model.edges.length} relations${model.truncated ? ' (truncated)' : ''}`);
-    const byType = new Map();
-    for (const n of model.nodes) {
-        const arr = byType.get(n.type) ?? [];
-        arr.push({ id: n.id, name: n.name });
-        byType.set(n.type, arr);
-    }
-    for (const [type, ns] of byType) {
-        console.log(`\n${type} (${ns.length}):`);
-        for (const n of ns)
-            console.log(`  [${n.id}] ${n.name}`);
-    }
-    if (model.edges.length > 0) {
-        const nameById = new Map(model.nodes.map((n) => [n.id, n.name]));
-        console.log('\nrelations:');
-        for (const e of model.edges) {
-            console.log(`  ${nameById.get(e.from)} --${e.relType}--> ${nameById.get(e.to)}`);
-        }
-    }
-}
-function openInBrowser(out) {
-    // Best-effort browser launch; never fail the command if it doesn't work.
-    try {
-        const [cmd, cmdArgs] = process.platform === 'win32'
-            ? ['cmd', ['/c', 'start', '', out]]
-            : process.platform === 'darwin'
-                ? ['open', [out]]
-                : ['xdg-open', [out]];
-        const child = spawn(cmd, cmdArgs, { detached: true, stdio: 'ignore', windowsHide: true });
-        // A missing launcher (e.g. xdg-open absent) emits 'error' asynchronously; unhandled, it would throw,
-        // so swallow it: the file is already written and its path printed above.
-        child.on('error', () => { });
-        child.unref();
-    }
-    catch (err) {
-        // The file is written and its path printed above, so a browser that will not start costs nothing.
-        log.debug(`browser not opened: ${errorMessage(err)}`);
-    }
-}
-function graphView(hippoRoot, tenantId, entity, flags) {
-    const format = stringFlag(flags, 'format') ?? 'html';
-    if (format !== 'html' && format !== 'canvas') {
-        printError("graph view: --format must be 'html' or 'canvas'");
-        throw new CliExit(1);
-    }
-    const model = buildGraphModel(hippoRoot, tenantId, { entity, limit: DEFAULT_VIEW_LIMIT });
-    const content = format === 'canvas' ? renderGraphCanvas(model) : renderGraphHtml(model);
-    const defaultOut = format === 'canvas' ? 'hippo-graph.canvas' : 'hippo-graph.html';
-    const out = stringFlag(flags, 'out') ?? defaultOut;
-    fs.writeFileSync(out, content, 'utf8');
-    console.log(`Wrote ${model.nodes.length} entities + ${model.edges.length} relations to ${out}${model.truncated ? ' (truncated)' : ''}`);
-    if (flags['open'] && format === 'html')
-        openInBrowser(out);
-}
-export function handleGraph({ hippoRoot, tenantId, args, flags }) {
-    requireInit(hippoRoot);
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'extract')
-        return graphExtract(hippoRoot, tenantId);
-    const entity = stringFlag(flags, 'entity');
-    if (subcommand === 'show')
-        return graphShow(hippoRoot, tenantId, entity, flags);
-    if (subcommand === 'view')
-        return graphView(hippoRoot, tenantId, entity, flags);
-    printError('Usage:\n' +
-        '  hippo graph extract                     Rebuild the entity/relation graph from consolidated objects\n' +
-        '  hippo graph show [--entity NAME] [--json]   Inspect entities + their edges (text or JSON)\n' +
-        '  hippo graph view [--out FILE] [--open] [--format html|canvas] [--entity NAME]   Generate an interactive node-link diagram');
-    throw new CliExit(1);
-}
-function noteList(hippoRoot, tenantId, flags) {
-    const customer = stringFlag(flags, 'customer')?.trim() || undefined;
-    listObjects(flags, {
-        plural: 'customer notes',
-        states: customerNotesModule.VALID_NOTE_STATES,
-        load: (opts) => customerNotesModule.loadCustomerNotes(hippoRoot, tenantId, { ...opts, customer }),
-        printRow: printNoteRow,
-    });
-}
-function noteGet(hippoRoot, tenantId, args) {
-    const id = idArgOrExit(args, 'Usage: hippo note get <id>', NOTE.idLabel);
-    const n = foundOrExit(customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id), NOTE.noun, id);
-    console.log(`Customer note #${n.id}`);
-    console.log(`  customer: ${n.customer}`);
-    console.log(`  status: ${n.status}`);
-    console.log(`  version: ${n.version}`);
-    console.log(`  note: ${n.note}`);
-    printLifecycleTail(n);
-}
-function noteSupersede(hippoRoot, tenantId, args, flags) {
-    const id = idArgOrExit(args, 'Usage: hippo note supersede <id> --text "<note>" [--change "<summary>"]', NOTE.idLabel);
-    const textRaw = stringFlag(flags, 'text');
-    if (!textRaw?.trim()) {
-        printError('hippo note supersede requires --text "<note>" for the new version.');
-        throw new CliExit(1);
-    }
-    const existing = foundOrExit(customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id), NOTE.noun, id);
-    try {
-        const created = customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
-            customer: existing.customer,
-            note: textRaw,
-            changeSummary: nonEmptyStringFlag(flags, 'change'),
-            supersedesNoteId: id,
-            extraTags: extractPathTags(process.cwd()),
-        });
-        console.log(`Customer note #${created.id} recorded (v${created.version}), superseding #${id}.`);
-        if (created.memoryId)
-            console.log(`  memory: ${created.memoryId}`);
-    }
-    catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
-    }
-}
-function noteClose(hippoRoot, tenantId, args) {
-    closeObject(args, NOTE, (id) => customerNotesModule.closeCustomerNote(hippoRoot, tenantId, id));
-}
-export function handleCustomerNote({ hippoRoot, tenantId, args, flags }) {
-    requireInit(hippoRoot);
-    const subcommand = args[0] ?? '';
-    if (subcommand === 'list')
-        return noteList(hippoRoot, tenantId, flags);
-    if (subcommand === 'get')
-        return noteGet(hippoRoot, tenantId, args);
-    if (subcommand === 'supersede')
-        return noteSupersede(hippoRoot, tenantId, args, flags);
-    if (subcommand === 'close')
-        return noteClose(hippoRoot, tenantId, args);
-    // Default subcommand: new (create). Accept both `note new "<customer>"` and the
-    // bare `note "<customer>"` form: for the `new` keyword the customer is args[1].
-    const customer = subcommand === 'new' ? (args[1] ?? '') : subcommand;
-    const textRaw = stringFlag(flags, 'text');
-    if (!customer || !textRaw?.trim()) {
-        noteUsage();
-        throw new CliExit(1);
-    }
-    try {
-        const created = customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
-            customer,
-            note: textRaw,
-            extraTags: extractPathTags(process.cwd()),
-        });
-        console.log(`Customer note recorded: #${created.id} (v${created.version}) for customer "${created.customer}"`);
-        if (created.memoryId)
-            console.log(`  memory: ${created.memoryId}`);
-    }
-    catch (e) {
-        printError(errorMessage(e));
-        throw new CliExit(1);
-    }
-}
+const briefKind = (hippoRoot, tenantId) => ({
+    names: { cmd: 'brief', noun: 'Project brief', idLabel: 'brief' },
+    plural: 'project briefs',
+    states: briefsModule.VALID_BRIEF_STATES,
+    usage: [
+        'Usage: hippo brief new "<repo>" --summary "<text>"',
+        '       hippo brief list [--status active|superseded|closed|all] [--repo "<repo>"] [--limit N]',
+        '       hippo brief get <id>',
+        '       hippo brief supersede <id> --summary "<text>" [--change "<summary>"]',
+        '       hippo brief close <id>',
+        '       hippo brief refresh "<repo>" [--dry-run]   (auto-assemble the brief from the repo\'s receipts)',
+    ],
+    supersedeUsage: 'Usage: hippo brief supersede <id> --summary "<text>" [--change "<summary>"]',
+    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,
+    }),
+    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),
+    printRow: printBriefRow,
+    printDetail: (b) => {
+        console.log(`  repo: ${b.repo}`);
+        console.log(`  status: ${b.status}`);
+        console.log(`  version: ${b.version}`);
+        console.log(`  summary: ${b.summary}`);
+    },
+    extra: { sub: 'refresh', run: (args, flags) => briefRefresh(hippoRoot, tenantId, args, flags) },
+});
+export const handleProjectBrief = versionedVerbs(briefKind);
 //# sourceMappingURL=briefs.js.map

package/dist/cli/card.js

@@ -1,13 +1,28 @@
 // The `hippo card` verb (the agent work board); main() loads it lazily from the command table.
-import { createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from '../store/cards.js';
+import * as cardsApi from '../api/cards.js';
+import { cliApiContext } from './api-context.js';
 import { isHandoffOutcome } from '../core/handoff.js';
 import { isCardStatus } from '../core/card.js';
-import { loadCardDetail } from '../store/card-detail.js';
 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';
+// 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>...]',
+    show: 'hippo card show <id> [--json]',
+    claim: 'hippo card claim <id> --runtime <name> [--session <id>]',
+    heartbeat: 'hippo card heartbeat <id> --run <n>',
+    review: 'hippo card review <id> [--run <n>]',
+    complete: 'hippo card complete <id> --outcome <success|failure|partial> [--run <n>]',
+    reclaim: 'hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)',
+    comment: 'hippo card comment <id> --body "..." [--author <name>]',
+};
+function usageError(sub) {
+    printError(`Usage: ${CARD_USAGE[sub]}`);
+    return new CliExit(1);
+}
 // Mirrors ARCHIVE_REASON_REQUIRED so the block message can't drift from its usage line.
 const CARD_BLOCK_REASON_REQUIRED = 'hippo card block <id> requires --reason "<why>" (recorded as a comment).';
 function printCard(detail) {
@@ -65,8 +80,9 @@ function cardRunFlag(flags) {
 }
 // Reads after the store already refused, so this only explains the refusal, never changes it.
 function cardRefusal(hippoRoot, tenantId, id) {
-    const card = loadCard(hippoRoot, tenantId, id);
-    const liveRun = loadCardRuns(hippoRoot, tenantId, id).find((r) => !r.ended);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const card = cardsApi.cardLoad(ctx, id);
+    const liveRun = cardsApi.cardRuns(ctx, id).find((r) => !r.ended);
     return `status ${card?.status ?? 'unknown'}, live run ${liveRun?.id ?? 'none'}`;
 }
 const CARD_SUBCOMMAND_FLAGS = {
@@ -104,8 +120,7 @@ export function handleCard({ hippoRoot, tenantId, args, flags }) {
 function cardCreate(hippoRoot, tenantId, _args, flags) {
     const title = stringFlagOrExit(flags, 'title') ?? '';
     if (!title) {
-        printError('Usage: hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]');
-        throw new CliExit(1);
+        throw usageError('create');
     }
     const repo = stringFlagOrExit(flags, 'repo') || undefined;
     const contract = stringFlagOrExit(flags, 'contract') || undefined;
@@ -126,7 +141,7 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
     const dependsOn = Array.isArray(dependsOnFlag) ? dependsOnFlag : [];
     let card;
     try {
-        card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
+        card = cardsApi.cardCreate(cliApiContext(hippoRoot, tenantId), { title, repo, contract, budget, dependsOn });
     }
     catch (error) {
         printError(errorMessage(error));
@@ -137,10 +152,9 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
 function cardShow(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
-        printError('Usage: hippo card show <id> [--json]');
-        throw new CliExit(1);
+        throw usageError('show');
     }
-    const detail = loadCardDetail(hippoRoot, tenantId, id);
+    const detail = cardsApi.cardDetail(cliApiContext(hippoRoot, tenantId), id);
     if (!detail) {
         printError(`No card found with id ${id}.`);
         throw new CliExit(1);
@@ -157,7 +171,7 @@ function cardList(hippoRoot, tenantId, _args, flags) {
         printError(`Invalid status: "${status}".`);
         throw new CliExit(1);
     }
-    const cards = listCards(hippoRoot, tenantId, { status });
+    const cards = cardsApi.cardList(cliApiContext(hippoRoot, tenantId), { status });
     if (flags['json']) {
         console.log(JSON.stringify({ cards }, null, 2));
         return;
@@ -174,13 +188,12 @@ function cardClaim(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runtime = stringFlagOrExit(flags, 'runtime') ?? '';
     if (!id || !runtime) {
-        printError('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
-        throw new CliExit(1);
+        throw usageError('claim');
     }
     const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     let card;
     try {
-        card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
+        card = cardsApi.cardClaim(cliApiContext(hippoRoot, tenantId), id, runtime, sessionId);
     }
     catch (error) {
         printError(errorMessage(error));
@@ -196,12 +209,11 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const runId = cardRunFlag(flags);
     if (!id || runId === undefined) {
-        printError('Usage: hippo card heartbeat <id> --run <n>');
-        throw new CliExit(1);
+        throw usageError('heartbeat');
     }
     let card;
     try {
-        card = heartbeatCard(hippoRoot, tenantId, id, runId);
+        card = cardsApi.cardHeartbeat(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
         printError(errorMessage(error));
@@ -223,7 +235,7 @@ function cardBlock(hippoRoot, tenantId, args, flags) {
     const runId = cardRunFlag(flags);
     let card;
     try {
-        card = blockCard(hippoRoot, tenantId, id, reason, runId);
+        card = cardsApi.cardBlock(cliApiContext(hippoRoot, tenantId), id, reason, runId);
     }
     catch (error) {
         printError(errorMessage(error));
@@ -239,13 +251,12 @@ function cardBlock(hippoRoot, tenantId, args, flags) {
 function cardReview(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
-        printError('Usage: hippo card review <id> [--run <n>]');
-        throw new CliExit(1);
+        throw usageError('review');
     }
     const runId = cardRunFlag(flags);
     let card;
     try {
-        card = reviewCard(hippoRoot, tenantId, id, runId);
+        card = cardsApi.cardReview(cliApiContext(hippoRoot, tenantId), id, runId);
     }
     catch (error) {
         printError(errorMessage(error));
@@ -262,13 +273,12 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     const outcomeRaw = flags['outcome'];
     if (!id || !isHandoffOutcome(outcomeRaw)) {
-        printError('Usage: hippo card complete <id> --outcome <success|failure|partial> [--run <n>]');
-        throw new CliExit(1);
+        throw usageError('complete');
     }
     const runId = cardRunFlag(flags);
     let result;
     try {
-        result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
+        result = cardsApi.cardComplete(cliApiContext(hippoRoot, tenantId), id, outcomeRaw, runId);
     }
     catch (error) {
         printError(errorMessage(error));
@@ -286,10 +296,9 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
 }
 function cardReclaim(hippoRoot, tenantId, args) {
     if (args.length > 1) {
-        printError('Usage: hippo card reclaim (sweeps every expired lease; use hippo card block <id> for one card)');
-        throw new CliExit(1);
+        throw usageError('reclaim');
     }
-    const ids = reclaimExpiredCards(hippoRoot, tenantId);
+    const ids = cardsApi.cardReclaimExpired(cliApiContext(hippoRoot, tenantId));
     if (ids.length === 0) {
         console.log('No expired leases.');
         return;
@@ -301,22 +310,21 @@ function cardReclaim(hippoRoot, tenantId, args) {
 function cardComment(hippoRoot, tenantId, args, flags) {
     const id = args[1];
     if (!id) {
-        printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
-        throw new CliExit(1);
+        throw usageError('comment');
     }
     // Only show and comment look the card up directly; claim/heartbeat/block/review/complete throw from the store instead.
-    const card = loadCard(hippoRoot, tenantId, id);
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const card = cardsApi.cardLoad(ctx, id);
     if (!card) {
         printError(`No card found with id ${id}.`);
         throw new CliExit(1);
     }
     const body = stringFlagOrExit(flags, 'body') ?? '';
     if (!body) {
-        printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
-        throw new CliExit(1);
+        throw usageError('comment');
     }
     const author = stringFlagOrExit(flags, 'author') || 'cli';
-    const comment = addCardComment(hippoRoot, tenantId, id, author, body);
+    const comment = 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,12 +1,16 @@
 /** 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);
 }
+/** A 2xx reply that is not the JSON object the route promises: another process may now own the pidfile's port. */
+export declare class MalformedReplyError extends Error {
+    readonly route: string;
+    constructor(route: string, detail: string);
+}
 export declare function remember(serverUrl: string, apiKey: string | undefined, opts: RememberOpts): Promise<RememberResult>;
 export declare function forget(serverUrl: string, apiKey: string | undefined, id: string): Promise<{
     ok: true;