hippo-memory 1.69.0 → 1.71.0

package/dist/cli/curate.js

@@ -1,31 +1,37 @@
 // Verbs that weaken, suppress or retire memories: outcome, forget, conflicts, reject, dormant, quarantine, invalidate.
 import * as path from 'path';
-import { readEntry } from '../store/entry-reads.js';
 import { listMemoryConflicts, resolveConflict } from '../store/conflicts.js';
-import { rejectValue, unrejectValue, listRejectionsForTenant } from '../reject-flow.js';
-import { RejectedValueError } from '../rejection.js';
-import { loadConfig } from '../config.js';
-import { isGitRepo } from '../autolearn.js';
-import { invalidateMatching } from '../invalidation.js';
-import * as api from '../api.js';
-import * as client from '../client.js';
-import { resolveTenantId } from '../tenant.js';
+import { rejectValue, unrejectValue, listRejectionsForTenant } from '../trust/reject-flow.js';
+import { RejectedValueError } from '../store/rejection.js';
+import { loadConfig } from '../core/config.js';
+import { RawAppendOnlyError } from '../core/raw-append-only.js';
+import { isGitRepo } from '../learn/autolearn.js';
+import { invalidateMatching } from '../learn/invalidation.js';
+import * as api from '../api/index.js';
+import { getMemory } from '../api/memories.js';
+import * as client from './client.js';
+import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
-import { parseCountFlag, requireInit, runChurnStaleForRepo, runViaServerIfAvailable, fmt, resolveAuthRoot, } from './shared.js';
-export function cmdOutcome(hippoRoot, flags) {
+import { parseCountFlag, boolFlag, flagIsTrue, nonEmptyStringFlag, stringFlag } from './flag-values.js';
+import { requireInit, runChurnStaleForRepo, runViaServerIfAvailable, resolveAuthRoot } from './shared.js';
+import { fmt } from './print.js';
+import { errorMessage } from '../util/log.js';
+import { DIGEST_DISPLAY_CHARS, CONTENT_PREVIEW_CHARS, DATE_PREFIX_CHARS } from '../util/token-text.js';
+import { CliExit } from './exit.js';
+const CONFLICT_PREVIEW_CHARS = 120;
+const REJECTED_DIGEST_LIST_CHARS = 16;
+const DORMANT_PREVIEW_CHARS = 100;
+const STRENGTH_DECIMALS = 3;
+export function handleOutcome({ hippoRoot, tenantId, flags }) {
     requireInit(hippoRoot);
-    const good = Boolean(flags['good']);
-    const bad = Boolean(flags['bad']);
+    const good = boolFlag(flags, 'good');
+    const bad = boolFlag(flags, 'bad');
     if (!good && !bad) {
         printError('Specify --good or --bad');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Through api.outcome so every CLI outcome writes one audit_log row per id, as the MCP path does.
-    const ctx = {
-        hippoRoot,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(hippoRoot, tenantId);
     const specificId = flags['id'] ? String(flags['id']) : null;
     let updated;
     if (specificId) {
@@ -43,30 +49,13 @@ export function cmdOutcome(hippoRoot, flags) {
 }
 // Shared between the forget dispatch and cmdForget so the message can't drift.
 const ARCHIVE_REASON_REQUIRED = 'hippo forget --archive requires --reason "<why>" (recorded on the archive).';
-function cmdForget(hippoRoot, id, flags) {
+function cmdForget(hippoRoot, tenantId, id, flags) {
     requireInit(hippoRoot);
-    const ctx = {
-        hippoRoot,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
-    // Raw memories (Slack / GitHub connector ingestion) are append-only: a
-    // BEFORE-DELETE trigger aborts any delete. archiveRaw is the sanctioned
-    // removal path; it records ctx.actor as the archiver for provenance.
-    if (flags['archive'] === true) {
-        const reason = typeof flags['reason'] === 'string' ? flags['reason'] : null;
-        if (!reason) {
-            printError(ARCHIVE_REASON_REQUIRED);
-            process.exit(1);
-        }
-        try {
-            api.archiveRaw(ctx, id, reason);
-            console.log(`Archived ${id}`);
-        }
-        catch (err) {
-            printError(`Could not archive ${id}: ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
-        }
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    // Raw memories (connector ingestion) are append-only: a BEFORE-DELETE trigger aborts any delete,
+    // so archiveRaw is the sanctioned removal path and records ctx.actor as the archiver.
+    if (flagIsTrue(flags, 'archive')) {
+        archiveForgottenRaw(ctx, id, stringFlag(flags, 'reason') ?? null);
         return;
     }
     try {
@@ -74,47 +63,63 @@ function cmdForget(hippoRoot, id, flags) {
         console.log(`Forgot ${id}`);
     }
     catch (err) {
-        const msg = err instanceof Error ? err.message : String(err);
-        if (/append-only/i.test(msg)) {
-            // The delete was refused by the append-only trigger — this is a raw
-            // memory, not a missing one. Point the user at the archive path.
-            printError(rawForgetRefusal(id));
-        }
-        else if (api.isDormant(ctx, id)) {
-            // Sleep moved it to the dormant store: it is not in active memory, so
-            // point at the command that owns it.
-            printError(`${id} is dormant, not in active memory. Delete it for good: hippo dormant forget ${id} ` +
-                `(or bring it back: hippo dormant restore ${id})`);
-        }
-        else {
-            printError(`Memory not found: ${id}`);
-        }
-        process.exit(1);
+        reportForgetFailure(ctx, id, err);
+        throw new CliExit(1);
+    }
+}
+function archiveForgottenRaw(ctx, id, reason) {
+    if (!reason) {
+        printError(ARCHIVE_REASON_REQUIRED);
+        throw new CliExit(1);
+    }
+    try {
+        api.archiveRaw(ctx, id, reason);
+        console.log(`Archived ${id}`);
+    }
+    catch (err) {
+        printError(`Could not archive ${id}: ${errorMessage(err)}`);
+        throw new CliExit(1);
+    }
+}
+function reportForgetFailure(ctx, id, cause) {
+    if (cause instanceof RawAppendOnlyError) {
+        // The delete was refused by the append-only trigger — this is a raw
+        // memory, not a missing one. Point the user at the archive path.
+        printError(rawForgetRefusal(id));
+    }
+    else if (api.isDormant(ctx, id)) {
+        // Sleep moved it to the dormant store: it is not in active memory, so
+        // point at the command that owns it.
+        printError(`${id} is dormant, not in active memory. Delete it for good: hippo dormant forget ${id} ` +
+            `(or bring it back: hippo dormant restore ${id})`);
+    }
+    else {
+        printError(`Memory not found: ${id}`);
     }
 }
 function rawForgetRefusal(id) {
     return `Cannot forget ${id}: it is a raw, append-only memory. Archive it instead: hippo forget ${id} --archive --reason "<why>"`;
 }
 // Refuses exactly where the real run would, so "Would forget" is a promise, not a guess.
-function previewForget(hippoRoot, id, archive) {
+async function previewForget(hippoRoot, tenantId, id, archive) {
     requireInit(hippoRoot);
-    const entry = readEntry(hippoRoot, id, resolveTenantId({}));
+    const entry = await getMemory(cliApiContext(hippoRoot, tenantId), id);
     if (!entry) {
         printError(`Memory not found: ${id}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!archive && entry.kind === 'raw') {
         printError(rawForgetRefusal(id));
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (archive && entry.kind !== 'raw') {
         printError(`Could not archive ${id}: memory ${id} is not raw (kind=${entry.kind})`);
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const snippet = entry.content.length > 80 ? `${entry.content.slice(0, 80)}...` : entry.content;
+    const snippet = entry.content.length > CONTENT_PREVIEW_CHARS ? `${entry.content.slice(0, CONTENT_PREVIEW_CHARS)}...` : entry.content;
     console.log(`Would ${archive ? 'archive' : 'forget'} ${id} (dry run, nothing changed): "${snippet}"`);
 }
-export function cmdConflicts(hippoRoot, flags) {
+export function handleConflicts({ hippoRoot, flags }) {
     requireInit(hippoRoot);
     const conflicts = listMemoryConflicts(hippoRoot, String(flags['status'] ?? 'open'));
     if (flags['json']) {
@@ -133,55 +138,58 @@ export function cmdConflicts(hippoRoot, flags) {
         console.log('');
     }
 }
-export function cmdResolve(hippoRoot, args, flags) {
+/** Shown when --keep is missing, to help the user decide. */
+async function showConflictForResolve(hippoRoot, conflictId, tenantId) {
+    const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId);
+    const conflict = conflicts.find((c) => c.id === conflictId);
+    if (!conflict) {
+        printError(`Conflict ${conflictId} not found or already resolved.`);
+        throw new CliExit(1);
+    }
+    console.log(`Conflict ${conflictId}:`);
+    console.log(`  ${conflict.memory_a_id} <-> ${conflict.memory_b_id}`);
+    console.log(`  Reason: ${conflict.reason}`);
+    console.log('');
+    const ctx = cliApiContext(hippoRoot, tenantId);
+    const entryA = await getMemory(ctx, conflict.memory_a_id);
+    const entryB = await getMemory(ctx, conflict.memory_b_id);
+    if (entryA) {
+        console.log(`  [A] ${conflict.memory_a_id}:`);
+        console.log(`      ${entryA.content.slice(0, CONFLICT_PREVIEW_CHARS)}${entryA.content.length > CONFLICT_PREVIEW_CHARS ? '...' : ''}`);
+    }
+    if (entryB) {
+        console.log(`  [B] ${conflict.memory_b_id}:`);
+        console.log(`      ${entryB.content.slice(0, CONFLICT_PREVIEW_CHARS)}${entryB.content.length > CONFLICT_PREVIEW_CHARS ? '...' : ''}`);
+    }
+    console.log('');
+    console.log(`Resolve with: hippo resolve ${conflictId} --keep <memory_id> [--forget] [--reject-loser [--reason "<why>"]]`);
+}
+export async function handleResolve({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
     const rawId = args[0] ?? '';
     // Accept "42" or "conflict_42"
     const conflictId = parseInt(rawId.replace(/^conflict_/, ''), 10);
     if (isNaN(conflictId)) {
         printError('Usage: hippo resolve <conflict_id> --keep <memory_id> [--forget]');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const tenantId = resolveTenantId({});
     const keepId = String(flags['keep'] ?? '').trim();
     if (!keepId) {
-        // Show the conflict details to help the user decide
-        const conflicts = listMemoryConflicts(hippoRoot, 'open', tenantId);
-        const conflict = conflicts.find((c) => c.id === conflictId);
-        if (!conflict) {
-            printError(`Conflict ${conflictId} not found or already resolved.`);
-            process.exit(1);
-        }
-        console.log(`Conflict ${conflictId}:`);
-        console.log(`  ${conflict.memory_a_id} <-> ${conflict.memory_b_id}`);
-        console.log(`  Reason: ${conflict.reason}`);
-        console.log('');
-        const entryA = readEntry(hippoRoot, conflict.memory_a_id, tenantId);
-        const entryB = readEntry(hippoRoot, conflict.memory_b_id, tenantId);
-        if (entryA) {
-            console.log(`  [A] ${conflict.memory_a_id}:`);
-            console.log(`      ${entryA.content.slice(0, 120)}${entryA.content.length > 120 ? '...' : ''}`);
-        }
-        if (entryB) {
-            console.log(`  [B] ${conflict.memory_b_id}:`);
-            console.log(`      ${entryB.content.slice(0, 120)}${entryB.content.length > 120 ? '...' : ''}`);
-        }
-        console.log('');
-        console.log(`Resolve with: hippo resolve ${conflictId} --keep <memory_id> [--forget] [--reject-loser [--reason "<why>"]]`);
+        await showConflictForResolve(hippoRoot, conflictId, tenantId);
         return;
     }
-    const forgetLoser = Boolean(flags['forget']);
+    const forgetLoser = boolFlag(flags, 'forget');
     // --reject-loser tombstones the loser's digest so it cannot be re-asserted, as well as removing it.
     // --reason is optional here, unlike `hippo reject`: resolve already has the conflict id and keepId.
-    const rejectLoser = Boolean(flags['reject-loser']);
-    const reasonFlag = typeof flags['reason'] === 'string' ? flags['reason'] : undefined;
+    const rejectLoser = boolFlag(flags, 'reject-loser');
+    const reasonFlag = stringFlag(flags, 'reason');
     const result = resolveConflict(hippoRoot, conflictId, keepId, forgetLoser, tenantId, {
         rejectLoserValue: rejectLoser,
         reason: reasonFlag,
     });
     if (!result) {
         printError(`Could not resolve conflict ${conflictId}. Check the ID and --keep value.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const action = rejectLoser
         ? 'rejected (tombstoned) and removed'
@@ -190,31 +198,28 @@ export function cmdResolve(hippoRoot, args, flags) {
             : 'weakened (half-life halved)';
     console.log(`Resolved conflict ${conflictId}: kept ${keepId}, ${action} ${result.loserId}`);
 }
-// ---------------------------------------------------------------------------
 // reject / rejections / unreject
-// ---------------------------------------------------------------------------
-export function cmdReject(hippoRoot, args, flags) {
+export function handleReject({ hippoRoot, tenantId, args, flags }) {
     // Store resolution mirrors `hippo remember`: --global writes to the
     // global store, otherwise the local store (requireInit'd via resolveAuthRoot).
     const root = resolveAuthRoot(hippoRoot, flags);
-    const tenantId = resolveTenantId({});
     // --reason is REQUIRED: the tombstone stores no content, so reason is its only human-readable identity.
-    const reason = typeof flags['reason'] === 'string' ? flags['reason'].trim() : '';
+    const reason = (stringFlag(flags, 'reason') ?? '').trim();
     if (!reason) {
         printError('hippo reject requires --reason "<why>" (the tombstone stores no content; reason is its only identity).');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const valueFlag = typeof flags['value'] === 'string' ? flags['value'] : undefined;
+    const valueFlag = stringFlag(flags, 'value');
     const memoryId = args[0];
     if (!memoryId && valueFlag === undefined) {
         printError('Usage: hippo reject <memory-id> --reason "<why>"');
         printError('   or: hippo reject --value "<text>" --reason "<why>"');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (memoryId && valueFlag !== undefined) {
         // Ambiguous ask: silently preferring one form would ignore the other without feedback.
         printError('hippo reject takes EITHER a memory id OR --value, not both.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     try {
         const result = rejectValue({
@@ -225,31 +230,33 @@ export function cmdReject(hippoRoot, args, flags) {
             memoryId: valueFlag === undefined ? memoryId : undefined,
             value: valueFlag,
         });
-        const digestPrefix = result.digest.slice(0, 12);
-        const preview = result.content.length > 80 ? `${result.content.slice(0, 80)}...` : result.content;
-        console.log(`Rejected [${digestPrefix}...]: "${preview}"`);
-        console.log(`  Reason: ${reason}`);
-        if (result.removedIds.length > 0) {
-            console.log(`  Removed ${result.removedIds.length} matching row(s): ${result.removedIds.join(', ')}`);
-            if (result.successorIds.length > 0) {
-                console.log(`  Merged rows that held it keep their other texts in: ${result.successorIds.join(', ')}`);
-            }
-            if (result.dormantSuccessorIds.length > 0) {
-                console.log(`  Dormant merged rows that held it keep their other texts in: ${result.dormantSuccessorIds.join(', ')}`);
-            }
+        printRejected(result, reason);
+    }
+    catch (err) {
+        printError(`Could not reject: ${errorMessage(err)}`);
+        throw new CliExit(1);
+    }
+}
+function printRejected(result, reason) {
+    const digestPrefix = result.digest.slice(0, DIGEST_DISPLAY_CHARS);
+    const preview = result.content.length > CONTENT_PREVIEW_CHARS ? `${result.content.slice(0, CONTENT_PREVIEW_CHARS)}...` : result.content;
+    console.log(`Rejected [${digestPrefix}...]: "${preview}"`);
+    console.log(`  Reason: ${reason}`);
+    if (result.removedIds.length > 0) {
+        console.log(`  Removed ${result.removedIds.length} matching row(s): ${result.removedIds.join(', ')}`);
+        if (result.successorIds.length > 0) {
+            console.log(`  Merged rows that held it keep their other texts in: ${result.successorIds.join(', ')}`);
         }
-        else {
-            console.log('  No live rows matched (pre-emptive tombstone).');
+        if (result.dormantSuccessorIds.length > 0) {
+            console.log(`  Dormant merged rows that held it keep their other texts in: ${result.dormantSuccessorIds.join(', ')}`);
         }
     }
-    catch (err) {
-        printError(`Could not reject: ${err instanceof Error ? err.message : String(err)}`);
-        process.exit(1);
+    else {
+        console.log('  No live rows matched (pre-emptive tombstone).');
     }
 }
-export function cmdRejections(hippoRoot, flags) {
+export function handleRejections({ hippoRoot, tenantId, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
-    const tenantId = resolveTenantId({});
     const rows = listRejectionsForTenant(root, tenantId);
     if (flags['json']) {
         console.log(JSON.stringify({ rejections: rows }, null, 2));
@@ -261,7 +268,7 @@ export function cmdRejections(hippoRoot, flags) {
     }
     console.log(`${rows.length} rejected value(s):\n`);
     for (const row of rows) {
-        console.log(`--- ${row.digest.slice(0, 12)}...`);
+        console.log(`--- ${row.digest.slice(0, DIGEST_DISPLAY_CHARS)}...`);
         console.log(`    Reason:       ${row.reason ?? 'none given'}`);
         console.log(`    Rejected by:  ${row.rejectedBy ?? 'unknown'}`);
         console.log(`    Rejected at:  ${row.rejectedAt}`);
@@ -272,67 +279,35 @@ export function cmdRejections(hippoRoot, flags) {
         console.log('');
     }
 }
-export function cmdUnreject(hippoRoot, args, flags) {
+export function handleUnreject({ hippoRoot, tenantId, args, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
-    const tenantId = resolveTenantId({});
     const digestOrPrefix = (args[0] ?? '').trim();
     if (!digestOrPrefix) {
         printError('Usage: hippo unreject <digest-or-prefix>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const outcome = unrejectValue(root, tenantId, digestOrPrefix, 'cli');
     if (outcome.status === 'not_found') {
         printError(`No rejected value matches "${digestOrPrefix}". Run \`hippo rejections\` to list tombstones.`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (outcome.status === 'ambiguous') {
         printError(`"${digestOrPrefix}" matches ${outcome.candidates.length} tombstones. Use a longer prefix:`);
         for (const c of outcome.candidates) {
-            printError(`  ${c.digest.slice(0, 16)}...  ${c.reason ?? 'none given'}`);
+            printError(`  ${c.digest.slice(0, REJECTED_DIGEST_LIST_CHARS)}...  ${c.reason ?? 'none given'}`);
         }
-        process.exit(1);
+        throw new CliExit(1);
     }
-    console.log(`Unrejected [${outcome.digest.slice(0, 12)}...] (was: ${outcome.reason ?? 'none given'})`);
+    console.log(`Unrejected [${outcome.digest.slice(0, DIGEST_DISPLAY_CHARS)}...] (was: ${outcome.reason ?? 'none given'})`);
 }
-/**
- * `hippo dormant [list] [<query>...] [--limit <n>] [--json] [--global]`,
- * `hippo dormant restore <id>`, `hippo dormant forget <id>`.
- * Dormant memories are what sleep keeps instead of deleting (on by default;
- * `"dormant": { "enabled": false }` in .hippo/config.json deletes instead).
- */
-export function cmdDormant(hippoRoot, args, flags) {
+/** `hippo dormant [list|restore <id>|forget <id>]`: dormant memories are what sleep keeps instead of deleting
+ * (on by default; `"dormant": { "enabled": false }` in .hippo/config.json deletes instead). */
+export function handleDormant({ hippoRoot, tenantId, args, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
-    const ctx = {
-        hippoRoot: root,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(root, tenantId);
     const sub = args[0];
     if (sub === 'restore' || sub === 'forget') {
-        const id = (args[1] ?? '').trim();
-        if (!id) {
-            printError(`Usage: hippo dormant ${sub} <id>`);
-            process.exit(1);
-        }
-        try {
-            if (sub === 'restore') {
-                api.restoreDormant(ctx, id);
-                console.log(`Restored ${id} to active memory.`);
-            }
-            else {
-                api.forgetDormant(ctx, id);
-                console.log(`Forgot dormant memory ${id} permanently.`);
-            }
-        }
-        catch (err) {
-            if (err instanceof RejectedValueError) {
-                printError(`Cannot restore ${id}: its value was rejected (${err.reason ?? 'no reason given'}). Run \`hippo unreject\` first to allow it.`);
-            }
-            else {
-                printError(`Could not ${sub} ${id}: ${err instanceof Error ? err.message : String(err)}`);
-            }
-            process.exit(1);
-        }
+        changeDormant(ctx, sub, (args[1] ?? '').trim());
         return;
     }
     const queryArgs = sub === 'list' ? args.slice(1) : args;
@@ -345,56 +320,62 @@ export function cmdDormant(hippoRoot, args, flags) {
         console.log(JSON.stringify({ dormant: rows }, null, 2));
         return;
     }
+    printDormantRows(rows, queryArgs.length > 0, root);
+}
+function changeDormant(ctx, sub, id) {
+    if (!id) {
+        printError(`Usage: hippo dormant ${sub} <id>`);
+        throw new CliExit(1);
+    }
+    try {
+        if (sub === 'restore') {
+            api.restoreDormant(ctx, id);
+            console.log(`Restored ${id} to active memory.`);
+        }
+        else {
+            api.forgetDormant(ctx, id);
+            console.log(`Forgot dormant memory ${id} permanently.`);
+        }
+    }
+    catch (err) {
+        if (err instanceof RejectedValueError) {
+            printError(`Cannot restore ${id}: its value was rejected (${err.reason ?? 'no reason given'}). Run \`hippo unreject\` first to allow it.`);
+        }
+        else {
+            printError(`Could not ${sub} ${id}: ${errorMessage(err)}`);
+        }
+        throw new CliExit(1);
+    }
+}
+function printDormantRows(rows, hasQuery, root) {
     if (rows.length === 0) {
-        console.log(queryArgs.length > 0 ? 'No dormant memories match.' : 'No dormant memories.');
+        console.log(hasQuery ? 'No dormant memories match.' : 'No dormant memories.');
         if (!loadConfig(root).dormant.enabled) {
             console.log(`Sleep deletes faded memories. To keep them dormant instead, set "dormant": { "enabled": true } in ${path.join(root, 'config.json')}.`);
         }
         return;
     }
-    console.log(`${rows.length} dormant memor${rows.length === 1 ? 'y' : 'ies'}${queryArgs.length > 0 ? ' matching' : ''} (newest first):\n`);
+    console.log(`${rows.length} dormant memor${rows.length === 1 ? 'y' : 'ies'}${hasQuery ? ' matching' : ''} (newest first):\n`);
     for (const row of rows) {
-        const preview = row.content.length > 100 ? `${row.content.slice(0, 100)}...` : row.content;
+        const preview = row.content.length > DORMANT_PREVIEW_CHARS ? `${row.content.slice(0, DORMANT_PREVIEW_CHARS)}...` : row.content;
         console.log(`--- ${row.id}`);
         console.log(`    ${preview}`);
-        console.log(`    Dormant since ${row.dormantAt.slice(0, 10)} (${row.reason}, strength ${row.strength.toFixed(3)})${row.tags.length > 0 ? `  tags: ${row.tags.join(', ')}` : ''}`);
+        console.log(`    Dormant since ${row.dormantAt.slice(0, DATE_PREFIX_CHARS)} (${row.reason}, strength ${row.strength.toFixed(STRENGTH_DECIMALS)})${row.tags.length > 0 ? `  tags: ${row.tags.join(', ')}` : ''}`);
         console.log('');
     }
     console.log('Bring one back: hippo dormant restore <id>   Delete for good: hippo dormant forget <id>');
 }
 /** `hippo quarantine [list] [--all] [--json] [--global]`, `quarantine approve <id>`, `quarantine reject <id>` (poisoning defence). */
-export function cmdQuarantine(hippoRoot, args, flags) {
+export async function handleQuarantine({ hippoRoot, tenantId, args, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
-    const ctx = {
-        hippoRoot: root,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(root, tenantId);
     const sub = args[0];
     if (sub === 'approve' || sub === 'reject') {
-        const id = (args[1] ?? '').trim();
-        if (!id) {
-            printError(`Usage: hippo quarantine ${sub} <id>`);
-            process.exit(1);
-        }
-        try {
-            if (sub === 'approve') {
-                api.quarantineApprove(ctx, id);
-                console.log(`Approved ${id}: restored to its original scope.`);
-            }
-            else {
-                api.quarantineReject(ctx, id);
-                console.log(`Rejected ${id}: stays quarantined.`);
-            }
-        }
-        catch (err) {
-            printError(`Could not ${sub} ${id}: ${err instanceof Error ? err.message : String(err)}`);
-            process.exit(1);
-        }
+        await decideQuarantined(ctx, sub, (args[1] ?? '').trim());
         return;
     }
     const status = flags['all'] ? 'all' : 'pending';
-    const rows = api.quarantineList(ctx, { status });
+    const rows = await api.quarantineList(ctx, { status });
     if (flags['json']) {
         console.log(JSON.stringify({ quarantine: rows }, null, 2));
         return;
@@ -403,31 +384,54 @@ export function cmdQuarantine(hippoRoot, args, flags) {
         console.log(status === 'all' ? 'No quarantined memories.' : 'No pending quarantined memories.');
         return;
     }
+    printQuarantineRows(rows);
+}
+async function decideQuarantined(ctx, sub, id) {
+    if (!id) {
+        printError(`Usage: hippo quarantine ${sub} <id>`);
+        throw new CliExit(1);
+    }
+    try {
+        if (sub === 'approve') {
+            await api.quarantineApprove(ctx, id);
+            console.log(`Approved ${id}: restored to its original scope.`);
+        }
+        else {
+            await api.quarantineReject(ctx, id);
+            console.log(`Rejected ${id}: stays quarantined.`);
+        }
+    }
+    catch (err) {
+        printError(`Could not ${sub} ${id}: ${errorMessage(err)}`);
+        throw new CliExit(1);
+    }
+}
+function printQuarantineRows(rows) {
     console.log(`${rows.length} quarantined memor${rows.length === 1 ? 'y' : 'ies'} (newest first):\n`);
     for (const row of rows) {
         console.log(`--- ${row.id} [${row.status}]`);
         console.log(`    ${row.contentPreview}`);
-        console.log(`    ${row.reason}, original scope ${row.originalScope ?? '(none)'}, quarantined ${row.quarantinedAt.slice(0, 10)}`);
+        console.log(`    ${row.reason}, original scope ${row.originalScope ?? '(none)'}, quarantined ${row.quarantinedAt.slice(0, DATE_PREFIX_CHARS)}`);
         console.log('');
     }
     console.log('Approve: hippo quarantine approve <id>   Reject: hippo quarantine reject <id>');
 }
-export async function handleForget({ hippoRoot, args, flags }) {
+export async function handleForget({ hippoRoot, tenantId, args, flags }) {
     const id = args[0];
     if (!id) {
         printError('Please provide a memory ID.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Archive has its own HTTP route (POST /v1/memories/:id/archive); route
     // both branches the same way the direct path does.
-    const archive = flags['archive'] === true;
-    const reason = typeof flags['reason'] === 'string' ? flags['reason'] : null;
+    const archive = flagIsTrue(flags, 'archive');
+    const reason = stringFlag(flags, 'reason') ?? null;
     if (archive && !reason) {
         printError(ARCHIVE_REASON_REQUIRED);
-        process.exit(1);
+        throw new CliExit(1);
     }
-    if (flags['dry-run'] === true) {
-        previewForget(hippoRoot, id, archive);
+    if (flagIsTrue(flags, 'dry-run')) {
+        await previewForget(hippoRoot, tenantId, id, archive);
         return;
     }
     const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
@@ -444,28 +448,28 @@ export async function handleForget({ hippoRoot, args, flags }) {
         catch (err) {
             // A server that died after the health probe is the caller's transport
             // fallback to handle, not an error to report to the user.
-            if (client.classifyTransportFailure(err) !== 'none')
+            if (err instanceof Error && client.classifyTransportFailure(err) !== 'none')
                 throw err;
-            const msg = err instanceof Error ? err.message : String(err);
+            const msg = errorMessage(err);
             printError(archive ? `Could not archive ${id}: ${msg}` : msg);
-            process.exit(1);
+            throw new CliExit(1);
         }
     });
     if (routed)
         return;
-    cmdForget(hippoRoot, id, flags);
+    cmdForget(hippoRoot, tenantId, id, flags);
 }
 function invalidateChurn(hippoRoot, args, flags) {
     if (args[0] || flags['id'] !== undefined) {
         printError('Usage: hippo invalidate --churn [--dry-run]');
         printError('--churn takes no pattern or --id.');
-        process.exit(1);
+        throw new CliExit(1);
     }
     if (!isGitRepo(process.cwd())) {
         printError('hippo invalidate --churn must run inside a git repository.');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const churnDryRun = flags['dry-run'] === true;
+    const churnDryRun = flagIsTrue(flags, 'dry-run');
     let churnFailed = false;
     for (const { root, result } of runChurnStaleForRepo(hippoRoot, churnDryRun)) {
         if (result.error) {
@@ -488,34 +492,34 @@ function invalidateChurn(hippoRoot, args, flags) {
         }
     }
     if (churnFailed)
-        process.exit(1);
+        throw new CliExit(1);
 }
-export function handleInvalidate({ hippoRoot, args, flags }) {
+export function handleInvalidate({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    if (flags['churn'] === true)
+    if (flagIsTrue(flags, 'churn'))
         return invalidateChurn(hippoRoot, args, flags);
     const target = args[0];
-    if (flags['id'] === true) {
+    if (flagIsTrue(flags, 'id')) {
         // Value-less --id must never silently fall through to pattern mode
         // (pattern mode writes broadly; an ignored --id reverses user intent).
         printError('--id requires a memory id');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const onlyId = typeof flags['id'] === 'string' ? flags['id'] : undefined;
-    const dryRun = flags['dry-run'] === true;
+    const onlyId = stringFlag(flags, 'id');
+    const dryRun = flagIsTrue(flags, 'dry-run');
     if ((target && onlyId) || (!target && !onlyId)) {
         printError('Usage: hippo invalidate "<old pattern>" [--dry-run] [--reason "<why>"]');
         printError('       hippo invalidate --id <memory-id> [--dry-run] [--reason "<why>"]');
         printError('Pass a pattern OR --id, not both. Tag matching is EXACT: the full pattern must equal a tag.');
-        process.exit(1);
+        throw new CliExit(1);
     }
-    const reason = flags['reason'] || null;
+    const reason = nonEmptyStringFlag(flags, 'reason') ?? null;
     const invTarget = {
         from: target ?? `id:${onlyId}`,
         to: reason,
         type: 'migration',
     };
-    const result = invalidateMatching(hippoRoot, invTarget, resolveTenantId({}), { dryRun, onlyId });
+    const result = invalidateMatching(hippoRoot, invTarget, tenantId, { dryRun, onlyId });
     const label = target ? `"${target}"` : `--id ${onlyId}`;
     if (result.dryRun) {
         if (result.invalidated === 0) {