hippo-memory 1.68.0 → 1.70.0

package/dist/cli/briefs.js

@@ -1,23 +1,19 @@
 // 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 '../path-context.js';
-import * as briefsModule from '../project-briefs.js';
-import * as customerNotesModule from '../customer-notes.js';
-import { extractGraph } from '../graph-extract.js';
-import { buildGraphModel, renderGraphHtml, renderGraphCanvas, DEFAULT_VIEW_LIMIT } from '../graph-view.js';
-import { resolveTenantId } from '../tenant.js';
+import { extractPathTags } from '../search/path-context.js';
+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 { resolveTenantId } from '../store/tenant.js';
+import { errorMessage, log } from '../util/log.js';
 import { printError } from './output.js';
+import { nonEmptyStringFlag, boolFlag, stringFlag } from './flag-values.js';
 import { requireInit } from './shared.js';
-function parsePositiveBriefId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid brief id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
-    }
-    return id;
-}
+import { closeObject, foundOrExit, idArgOrExit, listObjects, printLifecycleTail } from './object-verbs.js';
+const BRIEF = { cmd: 'brief', noun: 'Project brief', idLabel: 'brief' };
+const NOTE = { cmd: 'note', noun: 'Customer note', idLabel: 'note' };
 function printBriefRow(b) {
     console.log(`#${b.id} [${b.status}] v${b.version} repo="${b.repo}" memory=${b.memoryId ?? '-'}`);
     if (b.changeSummary)
@@ -31,38 +27,14 @@ function briefUsage() {
     printError('       hippo brief close <id>');
     printError('       hippo brief refresh "<repo>" [--dry-run]   (auto-assemble the brief from the repo\'s receipts)');
 }
-function parseListLimit(flags) {
-    const limitRaw = flags['limit'];
-    const limit = limitRaw !== undefined ? parseInt(String(limitRaw), 10) : 100;
-    if (!Number.isFinite(limit) || limit <= 0) {
-        printError(`Invalid --limit: "${limitRaw}". Must be a positive integer.`);
-        process.exit(1);
-    }
-    return limit;
-}
 function briefList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const repoRaw = flags['repo'];
-    const repo = typeof repoRaw === 'string' && repoRaw.trim() ? repoRaw.trim() : undefined;
-    const limit = parseListLimit(flags);
-    const opts = { limit, repo };
-    if (status !== 'all') {
-        if (!briefsModule.VALID_BRIEF_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        opts.status = status;
-    }
-    const results = briefsModule.loadProjectBriefs(hippoRoot, tenantId, opts);
-    if (results.length === 0) {
-        console.log('No project briefs.');
-        return;
-    }
-    console.log(`Found ${results.length} project briefs:
-`);
-    for (const b of results)
-        printBriefRow(b);
+    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];
@@ -70,7 +42,7 @@ function briefRefresh(hippoRoot, tenantId, args, flags) {
         printError('Usage: hippo brief refresh "<repo>" [--dry-run]');
         process.exit(1);
     }
-    const dryRun = Boolean(flags['dry-run']);
+    const dryRun = boolFlag(flags, 'dry-run');
     try {
         if (dryRun) {
             const { markdown, receiptCount } = briefsModule.assembleBriefFromReceipts(hippoRoot, tenantId, repoRaw);
@@ -86,62 +58,33 @@ function briefRefresh(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
 function briefGet(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo brief get <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveBriefId(idRaw);
-    const b = briefsModule.loadProjectBriefById(hippoRoot, tenantId, id);
-    if (!b) {
-        printError(`Project brief ${id} not found.`);
-        process.exit(1);
-    }
+    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}`);
-    if (b.changeSummary)
-        console.log(`  change_summary: ${b.changeSummary}`);
-    if (b.supersededBy !== null)
-        console.log(`  superseded_by: #${b.supersededBy}`);
-    if (b.supersededAt)
-        console.log(`  superseded_at: ${b.supersededAt}`);
-    if (b.closedAt)
-        console.log(`  closed_at: ${b.closedAt}`);
-    if (b.memoryId)
-        console.log(`  memory: ${b.memoryId}`);
-    console.log(`  created: ${b.createdAt}`);
+    printLifecycleTail(b);
 }
 function briefSupersede(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo brief supersede <id> --summary "<text>" [--change "<summary>"]');
-        process.exit(1);
-    }
-    const id = parsePositiveBriefId(idRaw);
-    const summaryRaw = flags['summary'];
-    if (typeof summaryRaw !== 'string' || !summaryRaw.trim()) {
+    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.');
         process.exit(1);
     }
-    const existing = briefsModule.loadProjectBriefById(hippoRoot, tenantId, id);
-    if (!existing) {
-        printError(`Project brief ${id} not found.`);
-        process.exit(1);
-    }
-    const changeRaw = flags['change'];
+    const existing = foundOrExit(briefsModule.loadProjectBriefById(hippoRoot, tenantId, id), BRIEF.noun, id);
     try {
         const created = briefsModule.saveProjectBrief(hippoRoot, tenantId, {
             repo: existing.repo,
             summary: summaryRaw,
-            changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+            changeSummary: nonEmptyStringFlag(flags, 'change'),
             supersedesBriefId: id,
             extraTags: extractPathTags(process.cwd()),
         });
@@ -150,27 +93,20 @@ function briefSupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
 function briefClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo brief close <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveBriefId(idRaw);
-    const closed = briefsModule.closeProjectBrief(hippoRoot, tenantId, id);
-    console.log(`Project brief #${closed.id} closed.`);
+    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 = flags['summary'];
-    if (!repo || typeof summaryRaw !== 'string' || !summaryRaw.trim()) {
+    const summaryRaw = stringFlag(flags, 'summary');
+    if (!repo || !summaryRaw?.trim()) {
         briefUsage();
         process.exit(1);
     }
@@ -185,7 +121,7 @@ function briefCreate(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
@@ -205,15 +141,6 @@ export function cmdProjectBrief(hippoRoot, args, flags) {
         return briefClose(hippoRoot, tenantId, args);
     briefCreate(hippoRoot, tenantId, args, flags);
 }
-function parsePositiveNoteId(idRaw) {
-    const s = String(idRaw ?? '').trim();
-    const id = parseInt(s, 10);
-    if (!/^\d+$/.test(s) || id <= 0) {
-        printError(`Invalid note id: "${idRaw}" (expected a positive integer).`);
-        process.exit(1);
-    }
-    return id;
-}
 function printNoteRow(n) {
     console.log(`#${n.id} [${n.status}] v${n.version} customer="${n.customer}" memory=${n.memoryId ?? '-'}`);
     if (n.changeSummary)
@@ -282,12 +209,13 @@ function openInBrowser(out) {
         child.on('error', () => { });
         child.unref();
     }
-    catch {
-        /* ignore — the file is written; the path is printed above */
+    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 = typeof flags['format'] === 'string' ? flags['format'] : 'html';
+    const format = stringFlag(flags, 'format') ?? 'html';
     if (format !== 'html' && format !== 'canvas') {
         printError("graph view: --format must be 'html' or 'canvas'");
         process.exit(1);
@@ -295,7 +223,7 @@ function graphView(hippoRoot, tenantId, entity, flags) {
     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 = typeof flags['out'] === 'string' ? flags['out'] : defaultOut;
+    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')
@@ -307,7 +235,7 @@ export function cmdGraph(hippoRoot, args, flags) {
     const subcommand = args[0] ?? '';
     if (subcommand === 'extract')
         return graphExtract(hippoRoot, tenantId);
-    const entity = typeof flags['entity'] === 'string' ? flags['entity'] : undefined;
+    const entity = stringFlag(flags, 'entity');
     if (subcommand === 'show')
         return graphShow(hippoRoot, tenantId, entity, flags);
     if (subcommand === 'view')
@@ -319,80 +247,37 @@ export function cmdGraph(hippoRoot, args, flags) {
     process.exit(1);
 }
 function noteList(hippoRoot, tenantId, flags) {
-    const statusRaw = flags['status'];
-    const status = typeof statusRaw === 'string' ? statusRaw.trim() : 'all';
-    const customerRaw = flags['customer'];
-    const customer = typeof customerRaw === 'string' && customerRaw.trim() ? customerRaw.trim() : undefined;
-    const limit = parseListLimit(flags);
-    const opts = { limit, customer };
-    if (status !== 'all') {
-        if (!customerNotesModule.VALID_NOTE_STATES.has(status)) {
-            printError(`Invalid --status: "${status}". Must be one of: active | superseded | closed | all.`);
-            process.exit(1);
-        }
-        opts.status = status;
-    }
-    const results = customerNotesModule.loadCustomerNotes(hippoRoot, tenantId, opts);
-    if (results.length === 0) {
-        console.log('No customer notes.');
-        return;
-    }
-    console.log(`Found ${results.length} customer notes:\n`);
-    for (const n of results)
-        printNoteRow(n);
+    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 idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo note get <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveNoteId(idRaw);
-    const n = customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id);
-    if (!n) {
-        printError(`Customer note ${id} not found.`);
-        process.exit(1);
-    }
+    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}`);
-    if (n.changeSummary)
-        console.log(`  change_summary: ${n.changeSummary}`);
-    if (n.supersededBy !== null)
-        console.log(`  superseded_by: #${n.supersededBy}`);
-    if (n.supersededAt)
-        console.log(`  superseded_at: ${n.supersededAt}`);
-    if (n.closedAt)
-        console.log(`  closed_at: ${n.closedAt}`);
-    if (n.memoryId)
-        console.log(`  memory: ${n.memoryId}`);
-    console.log(`  created: ${n.createdAt}`);
+    printLifecycleTail(n);
 }
 function noteSupersede(hippoRoot, tenantId, args, flags) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo note supersede <id> --text "<note>" [--change "<summary>"]');
-        process.exit(1);
-    }
-    const id = parsePositiveNoteId(idRaw);
-    const textRaw = flags['text'];
-    if (typeof textRaw !== 'string' || !textRaw.trim()) {
+    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.');
         process.exit(1);
     }
-    const existing = customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id);
-    if (!existing) {
-        printError(`Customer note ${id} not found.`);
-        process.exit(1);
-    }
-    const changeRaw = flags['change'];
+    const existing = foundOrExit(customerNotesModule.loadCustomerNoteById(hippoRoot, tenantId, id), NOTE.noun, id);
     try {
         const created = customerNotesModule.saveCustomerNote(hippoRoot, tenantId, {
             customer: existing.customer,
             note: textRaw,
-            changeSummary: typeof changeRaw === 'string' && changeRaw ? changeRaw : undefined,
+            changeSummary: nonEmptyStringFlag(flags, 'change'),
             supersedesNoteId: id,
             extraTags: extractPathTags(process.cwd()),
         });
@@ -401,19 +286,12 @@ function noteSupersede(hippoRoot, tenantId, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }
 function noteClose(hippoRoot, tenantId, args) {
-    const idRaw = args[1];
-    if (!idRaw) {
-        printError('Usage: hippo note close <id>');
-        process.exit(1);
-    }
-    const id = parsePositiveNoteId(idRaw);
-    const closed = customerNotesModule.closeCustomerNote(hippoRoot, tenantId, id);
-    console.log(`Customer note #${closed.id} closed.`);
+    closeObject(args, NOTE, (id) => customerNotesModule.closeCustomerNote(hippoRoot, tenantId, id));
 }
 export function cmdCustomerNote(hippoRoot, args, flags) {
     requireInit(hippoRoot);
@@ -430,8 +308,8 @@ export function cmdCustomerNote(hippoRoot, args, flags) {
     // 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 = flags['text'];
-    if (!customer || typeof textRaw !== 'string' || !textRaw.trim()) {
+    const textRaw = stringFlag(flags, 'text');
+    if (!customer || !textRaw?.trim()) {
         noteUsage();
         process.exit(1);
     }
@@ -446,7 +324,7 @@ export function cmdCustomerNote(hippoRoot, args, flags) {
             console.log(`  memory: ${created.memoryId}`);
     }
     catch (e) {
-        printError(e.message);
+        printError(errorMessage(e));
         process.exit(1);
     }
 }

package/dist/cli/card.d.ts

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

package/dist/cli/card.js

@@ -1,11 +1,13 @@
 // 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 { isHandoffOutcome } from '../handoff.js';
-import { isCardStatus } from '../card.js';
-import { loadCardDetail } from '../card-detail.js';
-import { resolveTenantId } from '../tenant.js';
+import { createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from '../store/cards.js';
+import { isHandoffOutcome } from '../core/handoff.js';
+import { isCardStatus } from '../core/card.js';
+import { loadCardDetail } from '../store/card-detail.js';
+import { resolveTenantId } from '../store/tenant.js';
 import { printError } from './output.js';
-import { requireInit, cardStringFlag } from './shared.js';
+import { stringFlagOrExit } from './flag-values.js';
+import { requireInit } from './shared.js';
+import { errorMessage } from '../util/log.js';
 // 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) {
@@ -51,7 +53,7 @@ function printCard(detail) {
 }
 // A too-large --run would silently round to a different id (mirrors parsePositiveIncidentId).
 function cardRunFlag(flags) {
-    const raw = cardStringFlag(flags, 'run');
+    const raw = stringFlagOrExit(flags, 'run');
     if (raw === undefined)
         return undefined;
     const n = Number(raw);
@@ -101,14 +103,14 @@ export function cmdCard(hippoRoot, args, flags) {
     CARD_HANDLERS[known](hippoRoot, tenantId, args, flags);
 }
 function cardCreate(hippoRoot, tenantId, _args, flags) {
-    const title = cardStringFlag(flags, 'title') ?? '';
+    const title = stringFlagOrExit(flags, 'title') ?? '';
     if (!title) {
         printError('Usage: hippo card create --title "..." [--repo <name>] [--contract <text>] [--budget <n>] [--depends-on <id>...]');
         process.exit(1);
     }
-    const repo = cardStringFlag(flags, 'repo') || undefined;
-    const contract = cardStringFlag(flags, 'contract') || undefined;
-    const budgetRaw = cardStringFlag(flags, 'budget');
+    const repo = stringFlagOrExit(flags, 'repo') || undefined;
+    const contract = stringFlagOrExit(flags, 'contract') || undefined;
+    const budgetRaw = stringFlagOrExit(flags, 'budget');
     let budget;
     if (budgetRaw !== undefined) {
         if (!/^\d+$/.test(budgetRaw)) {
@@ -128,7 +130,7 @@ function cardCreate(hippoRoot, tenantId, _args, flags) {
         card = createCard(hippoRoot, tenantId, { title, repo, contract, budget, dependsOn });
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     console.log(`Created card ${card.id} (status: ${card.status})`);
@@ -151,7 +153,7 @@ function cardShow(hippoRoot, tenantId, args, flags) {
     printCard(detail);
 }
 function cardList(hippoRoot, tenantId, _args, flags) {
-    const status = cardStringFlag(flags, 'status');
+    const status = stringFlagOrExit(flags, 'status');
     if (status !== undefined && !isCardStatus(status)) {
         printError(`Invalid status: "${status}".`);
         process.exit(1);
@@ -171,18 +173,18 @@ function cardList(hippoRoot, tenantId, _args, flags) {
 }
 function cardClaim(hippoRoot, tenantId, args, flags) {
     const id = args[1];
-    const runtime = cardStringFlag(flags, 'runtime') ?? '';
+    const runtime = stringFlagOrExit(flags, 'runtime') ?? '';
     if (!id || !runtime) {
         printError('Usage: hippo card claim <id> --runtime <name> [--session <id>]');
         process.exit(1);
     }
-    const sessionId = cardStringFlag(flags, 'session') || undefined;
+    const sessionId = stringFlagOrExit(flags, 'session') || undefined;
     let card;
     try {
         card = claimCard(hippoRoot, tenantId, id, runtime, sessionId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     if (!card) {
@@ -203,7 +205,7 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
         card = heartbeatCard(hippoRoot, tenantId, id, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     if (!card) {
@@ -214,7 +216,7 @@ function cardHeartbeat(hippoRoot, tenantId, args, flags) {
 }
 function cardBlock(hippoRoot, tenantId, args, flags) {
     const id = args[1];
-    const reason = cardStringFlag(flags, 'reason') ?? '';
+    const reason = stringFlagOrExit(flags, 'reason') ?? '';
     if (!id || !reason) {
         printError(CARD_BLOCK_REASON_REQUIRED);
         process.exit(1);
@@ -225,7 +227,7 @@ function cardBlock(hippoRoot, tenantId, args, flags) {
         card = blockCard(hippoRoot, tenantId, id, reason, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     if (!card) {
@@ -247,7 +249,7 @@ function cardReview(hippoRoot, tenantId, args, flags) {
         card = reviewCard(hippoRoot, tenantId, id, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     if (!card) {
@@ -270,7 +272,7 @@ function cardComplete(hippoRoot, tenantId, args, flags) {
         result = completeCard(hippoRoot, tenantId, id, outcomeRaw, runId);
     }
     catch (error) {
-        printError(error instanceof Error ? error.message : String(error));
+        printError(errorMessage(error));
         process.exit(1);
     }
     if (!result) {
@@ -309,12 +311,12 @@ function cardComment(hippoRoot, tenantId, args, flags) {
         printError(`No card found with id ${id}.`);
         process.exit(1);
     }
-    const body = cardStringFlag(flags, 'body') ?? '';
+    const body = stringFlagOrExit(flags, 'body') ?? '';
     if (!body) {
         printError('Usage: hippo card comment <id> --body "..." [--author <name>]');
         process.exit(1);
     }
-    const author = cardStringFlag(flags, 'author') || 'cli';
+    const author = stringFlagOrExit(flags, 'author') || 'cli';
     const comment = addCardComment(hippoRoot, tenantId, id, author, body);
     console.log(`Added comment ${comment.id} to card ${id}`);
 }

package/dist/{client.d.ts → cli/client.d.ts}

@@ -13,7 +13,7 @@
  * Network errors (ECONNREFUSED on a stale pidfile, etc.) propagate as the
  * native fetch failure so the caller can detect them and self-heal.
  */
-import type { RememberOpts, RememberResult } from './api.js';
+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. */

package/dist/{client.js → cli/client.js}

@@ -13,7 +13,7 @@
  * Network errors (ECONNREFUSED on a stale pidfile, etc.) propagate as the
  * native fetch failure so the caller can detect them and self-heal.
  */
-import { fetchWithRetry } from './http-retry.js';
+import { fetchWithRetry } from '../util/http-retry.js';
 /** A write the local server has not answered in this long is stuck; the caller treats it as delivery-unknown. */
 const SERVER_TIMEOUT_MS = 30_000;
 /** Five tries at the server's 1 s Retry-After keeps the roughly 5 s wait the CLI had before the server answered busy with 503. */

package/dist/cli/compact-resume-payload.d.ts

@@ -0,0 +1,8 @@
+export interface CompactResumePayload {
+    suppressOutput: boolean;
+    payloadSessionId: string | null;
+    boundary: boolean;
+}
+/** Fail-closed read of the SessionStart payload: only a manual run or a main-session `source: 'compact'` payload may print. */
+export declare function readCompactResumePayload(stdinText: string | undefined, stdinTimedOut: boolean): CompactResumePayload;
+//# sourceMappingURL=compact-resume-payload.d.ts.map

package/dist/cli/compact-resume-payload.js

@@ -0,0 +1,39 @@
+// The payload gate for `hippo compact-resume`.
+import { isSubagentPayload } from '../store/token-ledger.js';
+/** Fail-closed read of the SessionStart payload: only a manual run or a main-session `source: 'compact'` payload may print. */
+export function readCompactResumePayload(stdinText, stdinTimedOut) {
+    // An older Claude Code that ignores `matcher: 'compact'` runs this on every SessionStart, so a parsed payload with any other source stays silent.
+    const nonEmptyStdin = !!stdinText && stdinText.trim() !== '';
+    // Without a payload session_id the cross-restore guard can never fire, so a timed-out empty read must not reach the print path.
+    let suppressOutput = stdinTimedOut && !nonEmptyStdin;
+    let payloadSessionId = null;
+    // A boundary is a manual run or a payload that says it follows a compaction; anything else is not one.
+    let boundary = !nonEmptyStdin && !stdinTimedOut;
+    if (nonEmptyStdin) {
+        let payload = null;
+        try {
+            payload = JSON.parse(stdinText.trim());
+        }
+        catch {
+            // Malformed JSON is handled as a null payload by the fail-closed check below.
+            payload = null;
+        }
+        if (!payload || typeof payload !== 'object') {
+            // Fail closed on malformed non-empty stdin; only a TTY/no-stdin manual run, which never reaches here, prints.
+            suppressOutput = true;
+        }
+        else {
+            // Fail closed on structurally incomplete payloads too ({}, [], source missing/non-string): a real SessionStart payload always carries source.
+            // A sub-agent's payload carries its parent's session id, so the mismatch guard would pass and restore the parent's snapshot into it.
+            boundary = payload.source === 'compact';
+            if (payload.source !== 'compact' || isSubagentPayload(stdinText)) {
+                suppressOutput = true;
+            }
+            if (typeof payload.session_id === 'string') {
+                payloadSessionId = payload.session_id;
+            }
+        }
+    }
+    return { suppressOutput, payloadSessionId, boundary };
+}
+//# sourceMappingURL=compact-resume-payload.js.map

package/dist/cli/context.d.ts

@@ -1,15 +1,4 @@
-import { MemoryEntry } from '../memory.js';
-import { type CommandContext } from './shared.js';
-export declare function cmdContext(hippoRoot: string, args: string[], flags: Record<string, string | boolean | string[]>, stdinText?: string): Promise<void>;
-/** @internal Exported for the render snapshot test; not a stable public API. */
-export declare function printContextMarkdown(items: Array<{
-    entry: MemoryEntry;
-    score: number;
-    tokens: number;
-    isGlobal: boolean;
-}>, totalTokens: number, framing?: string, opts?: {
-    showStrength?: boolean;
-    heading?: string;
-}): void;
+import { type CliFlags, type CommandContext } from './flag-values.js';
+export declare function cmdContext(hippoRoot: string, args: string[], flags: CliFlags, stdinText?: string): Promise<void>;
 export declare function handleContext({ hippoRoot, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=context.d.ts.map