hippo-memory 1.43.3 → 1.45.0

package/dist/cli.js

@@ -29,7 +29,7 @@
  *   hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]
  *   hippo wm <push|read|clear|flush>
  */
-import { evalNow, isRecallBoostAblated } from './ablation.js';
+import { evalNow } from './ablation.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
@@ -38,14 +38,14 @@ import { execFileSync, execSync, spawn } from 'child_process';
 import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths, detectInstalledTools, defaultSleepLogPath, ensureCodexWrapperInstalled, installCodexWrapper, isCodexWrapperInstalled, repairCodexWrapperIfInstalled, uninstallCodexWrapper, resolveCodexSessionTranscript, resolveCodexWrapperPaths, installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath, } from './hooks.js';
 import { createMemory, calculateStrength, calculateRewardFactor, deriveHalfLife, resolveConfidence, confidenceFacets, confidenceLabel, computeSchemaFit, Layer, } from './memory.js';
 import { detectSecret } from './secret-detect.js';
-import { getHippoRoot, isInitialized, initStore, writeEntry, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
+import { getHippoRoot, isInitialized, initStore, writeEntry, strengthenRetrieved, readEntry, deleteEntry, loadAllEntries, loadSearchEntries, loadRecallSearchEntries, loadIndex, saveIndex, loadStats, updateStats, saveActiveTaskSnapshot, loadActiveTaskSnapshot, closeTaskSnapshotsForSession, clearActiveTaskSnapshot, appendSessionEvent, listSessionEvents, listMemoryConflicts, resolveConflict, saveSessionHandoff, loadLatestHandoff, loadHandoffById, stampHandoffOutcome, writeSessionEndHandoff, createCard, loadCard, listCards, loadCardRuns, claimCard, heartbeatCard, blockCard, reviewCard, completeCard, reclaimExpiredCards, addCardComment, } from './store.js';
 import { rejectValue, unrejectValue, listRejectionsForTenant } from './reject-flow.js';
 import { RejectedValueError } from './rejection.js';
 import { isHandoffOutcome, formatHandoffEvidenceLine } from './handoff.js';
 import { isCardStatus } from './card.js';
 import { loadCardDetail } from './card-detail.js';
 import { passesScopeFilterForRecall } from './recall-scope.js';
-import { markRetrieved, hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
+import { hybridSearch, physicsSearch, explainMatch, textOverlap, tokenize as tokenizeQuery } from './search.js';
 import { compareEntryIdentity } from './compare.js';
 import { renderTraceContent, parseSteps } from './trace.js';
 import { writeRecallTraceAtRoot } from './recall-trace.js';
@@ -65,7 +65,8 @@ import { detectScope } from './scope.js';
 import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { DAILY_TASK_NAME, buildDailyRunnerCommand, listRegisteredWorkspaces, registerWorkspace, runDailyMaintenance, } from './scheduler.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, } from './importers.js';
-import { cmdCapture, cmdPreCompact, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
+import { cmdCapture, cmdPreCompact, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
+import { readStdinBounded } from './stdin.js';
 import { auditMemories, appendAuditEvent, } from './audit.js';
 import { listApiKeys, revokeApiKey } from './auth.js';
 import { buildProvenanceCoverage } from './provenance-coverage.js';
@@ -143,6 +144,22 @@ function parseCountFlag(value) {
     const parsed = parseInt(String(value), 10);
     return Number.isFinite(parsed) && parsed >= 1 ? parsed : 0;
 }
+function parseBudgetFlag(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    // A value-less flag and a junk value are different typos; the --hops guard already splits them.
+    if (typeof value !== 'string') {
+        console.error('--budget requires an integer value (e.g. --budget 1500).');
+        process.exit(1);
+    }
+    // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        console.error(`Invalid --budget: "${value}". Must be a non-negative integer.`);
+        process.exit(1);
+    }
+    return parsed;
+}
 /**
  * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
  * connection so callers don't have to thread a db handle. Swallows all errors
@@ -178,8 +195,8 @@ function requireInit(hippoRoot) {
  * H2: when HIPPO_REQUIRE_SERVER is set, the CLI must not silently fall back to
  * direct DB mode — a missing server then masks a real misconfiguration (the
  * configured HIPPO_API_KEY is also silently discarded on fallback). Throws a
- * clear, actionable error in that case; a no-op when the knob is unset, so
- * default behaviour is unchanged.
+ * clear error then. It guards only the routed writes (remember, forget, archive,
+ * promote); every other command opens the store directly, knob or not.
  */
 function failIfServerRequired(reason) {
     if (process.env['HIPPO_REQUIRE_SERVER']) {
@@ -233,10 +250,68 @@ async function runViaServerIfAvailable(hippoRoot, httpFn) {
         throw err;
     }
 }
-// Flags that NEVER take a value. Without this, a positional following the
-// flag is silently swallowed as its value (`invalidate --dry-run "X"` would
-// eat the pattern). Every existing --dry-run consumer reads it as boolean.
-const BOOLEAN_FLAGS = new Set(['dry-run']);
+// Every switch the CLI reads. A value on one reads as on under Boolean() (`--fix=false` would fix)
+// and as off under === true (`--pin=true` would not pin), so parseArgs and main() refuse one.
+// tests/cli-parse-flag-equals.test.ts fails when a switch read is missing from this set.
+export const BOOLEAN_FLAGS = new Set([
+    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
+    'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
+    'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
+    'help', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
+    'no-learn', 'no-mmr', 'no-propagate', 'no-schedule', 'no-share', 'no-summarize-older',
+    'observed', 'open', 'physics', 'pin', 'pinned-only', 'reject-loser', 'rerank-utility',
+    'reset-physics', 'save-baseline', 'show-cases', 'stats', 'stdin',
+    'strict', 'suite', 'value-aware', 'verified', 'version', 'why',
+]);
+// Every flag some command reads. Anything else is a typo that no command would act on.
+export const KNOWN_FLAGS = new Set([
+    ...BOOLEAN_FLAGS,
+    'actual', 'artifact', 'artifact-ref', 'as-of', 'author', 'baseline', 'body', 'budget', 'card-id',
+    'change', 'channel', 'chatgpt', 'class', 'claude', 'codex-home', 'compare', 'constraint', 'content',
+    'context', 'contract', 'cursor', 'customer', 'days', 'depends-on', 'depth', 'description',
+    'embedding-weight', 'entity', 'estimate', 'file', 'format', 'framing', 'fresh-tail', 'from', 'goal',
+    'graph-hops', 'graph-seeds', 'history-path', 'hops', 'host', 'id', 'importance', 'include-recent',
+    'instructions', 'keep', 'kind', 'label', 'layer', 'level', 'limit', 'link', 'local-bump', 'log-file',
+    'markdown', 'max', 'max-cases', 'max-neighbors', 'min-mrr', 'min-results', 'min-score', 'mmr-lambda',
+    'model', 'name', 'next', 'next-step', 'note', 'older-than', 'op', 'out', 'outcome', 'owner', 'parent',
+    'path', 'policy', 'port', 'reason', 'repo', 'repos', 'reranker', 'reranker-top-k', 'resolution',
+    'role', 'run', 'runtime', 'salience-threshold', 'scan', 'scope', 'session', 'session-id', 'since',
+    'source', 'start-offset', 'started-at', 'state', 'status', 'step', 'steps', 'success', 'summary',
+    'supersedes', 'tag', 'target', 'target-runtime', 'task', 'team', 'tenant', 'tenant-id', 'tests',
+    'text', 'threshold', 'title', 'to', 'transcript', 'trigger', 'type', 'unit', 'value', 'vault',
+]);
+// Commands that delete or hide memories: an unknown flag here stops the run instead of being ignored.
+const DESTRUCTIVE_COMMANDS = new Set([
+    'audit', 'dedup', 'forget', 'invalidate', 'reject', 'resolve', 'sleep', 'supersede',
+]);
+// Commands that honour --dry-run. Any other command would ignore it and run for real.
+const DRY_RUN_COMMANDS = new Set([
+    'audit', 'capture', 'dedup', 'forget', 'import', 'invalidate', 'refine', 'setup', 'sleep',
+]);
+// share and brief honour --dry-run in one form only; their other forms write for real.
+function dryRunRefusal(command, args, flags) {
+    const isBrief = command === 'brief' || command === 'project-brief';
+    const onlyForm = command === 'share' ? 'share --auto' : isBrief ? `${command} refresh` : null;
+    const honoured = command === 'share' ? args[0] === '--auto' || Boolean(flags['auto'])
+        : isBrief ? args[0] === 'refresh' : DRY_RUN_COMMANDS.has(command);
+    if (honoured)
+        return null;
+    const where = onlyForm ? ` outside \`hippo ${onlyForm}\`` : '';
+    return `hippo ${command} has no --dry-run${where}, so it would run for real. Nothing was changed.`;
+}
+// Shared by both the separated and glued (`=`) forms so the list can't drift.
+function isRepeatableFlag(key) {
+    return key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on';
+}
+function pushRepeatableFlag(flags, key, value) {
+    if (Array.isArray(flags[key])) {
+        // SAFETY: Array.isArray just confirmed flags[key] is an array; the union has no other array member.
+        flags[key].push(value);
+    }
+    else {
+        flags[key] = [value];
+    }
+}
 export function parseArgs(argv) {
     const [, , command = '', ...rest] = argv;
     const args = [];
@@ -249,26 +324,43 @@ export function parseArgs(argv) {
             break;
         }
         if (part.startsWith('--')) {
+            const eqIdx = part.indexOf('=');
+            if (eqIdx > 2) {
+                // Glued form has no following token to swallow, so BOOLEAN_FLAGS gets its
+                // own branch here instead of the swallow-avoidance short-circuit below.
+                const key = part.slice(2, eqIdx);
+                const value = part.slice(eqIdx + 1);
+                if (BOOLEAN_FLAGS.has(key)) {
+                    flags[key] = value;
+                }
+                else if (isRepeatableFlag(key)) {
+                    if (value !== '')
+                        pushRepeatableFlag(flags, key, value);
+                }
+                else {
+                    flags[key] = value === '' ? true : value;
+                }
+                i++;
+                continue;
+            }
             const key = part.slice(2);
             const next = rest[i + 1];
-            if (!next || next.startsWith('--') || BOOLEAN_FLAGS.has(key)) {
+            if (BOOLEAN_FLAGS.has(key) && (next === 'true' || next === 'false')) {
+                // Kept as a value so main() rejects it, instead of `--pin true` pinning the text "... true".
+                flags[key] = next;
+                i += 2;
+            }
+            else if (!next || next.startsWith('--') || BOOLEAN_FLAGS.has(key)) {
                 // Boolean flag
                 flags[key] = true;
                 i++;
             }
+            else if (isRepeatableFlag(key)) {
+                pushRepeatableFlag(flags, key, next);
+                i += 2;
+            }
             else {
-                // Check if it's a repeatable flag (tag, artifact, link, step, constraint, depends-on)
-                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on') {
-                    if (Array.isArray(flags[key])) {
-                        flags[key].push(next);
-                    }
-                    else {
-                        flags[key] = [next];
-                    }
-                }
-                else {
-                    flags[key] = next;
-                }
+                flags[key] = next;
                 i += 2;
             }
         }
@@ -602,7 +694,7 @@ async function cmdRemember(hippoRoot, text, flags) {
     if (flags['verified'])
         confidence = 'verified';
     // Compute schema fit against existing memories
-    const existing = loadAllEntries(targetRoot);
+    const existing = loadAllEntries(targetRoot, resolveTenantId({}));
     const schemaFit = computeSchemaFit(text, rawTags, existing);
     // A3 envelope flags
     const kindFlagRaw = typeof flags['kind'] === 'string' ? flags['kind'] : undefined;
@@ -632,6 +724,7 @@ async function cmdRemember(hippoRoot, text, flags) {
     // A5 stub auth: stamp tenant_id from env (HIPPO_TENANT) so recall isolation
     // can filter on this row. Default tenant 'default' for unauthenticated CLI.
     const tenantId = resolveTenantId({});
+    const rememberConfig = loadConfig(targetRoot);
     const entry = createMemory(text, {
         layer: Layer.Episodic,
         tags: rawTags,
@@ -644,6 +737,7 @@ async function cmdRemember(hippoRoot, text, flags) {
         owner: ownerFlag,
         artifact_ref: artifactRefFlag,
         tenantId,
+        baseHalfLifeDays: rememberConfig.defaultHalfLifeDays,
     });
     // Auto-tag with path context
     const pathTags = extractPathTags(process.cwd());
@@ -660,7 +754,6 @@ async function cmdRemember(hippoRoot, text, flags) {
             entry.tags.push(scopeTag);
     }
     // Salience gate: decide if this memory is worth storing
-    const rememberConfig = loadConfig(targetRoot);
     if (rememberConfig.salience.enabled && !Boolean(flags['pin']) && !Boolean(flags['force'])) {
         const salienceResult = computeSalience(text, entry.tags, existing, {
             recentWindow: rememberConfig.salience.recentWindow,
@@ -702,14 +795,16 @@ async function cmdRemember(hippoRoot, text, flags) {
             const facts = await extractFacts(entry.content, {
                 apiKey,
                 model: config.extraction.model,
+                onError: (msg) => console.error(`  (extraction failed: ${msg})`),
             });
             if (facts.length > 0) {
                 storeExtractedFacts(targetRoot, entry, facts);
                 console.error(`  extracted ${facts.length} fact(s)`);
             }
         }
-        catch {
-            // Extraction is best-effort — never block remember
+        catch (err) {
+            // Extraction is best-effort: report it, never block remember.
+            console.error(`  (extraction failed: ${err instanceof Error ? err.message : String(err)})`);
         }
     }
     else if (shouldExtract && !apiKey) {
@@ -741,6 +836,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
         pinned,
         source: old.source,
         confidence: 'verified',
+        tenantId: old.tenantId,
     });
     // AT1: write the SUCCESSOR first. The rejection guard fires on the new
     // content — if it refuses, nothing has been mutated yet (the old ordering
@@ -768,7 +864,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
 }
 async function cmdRecall(hippoRoot, query, flags) {
     requireInit(hippoRoot);
-    const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 4000);
     const limit = parseLimitFlag(flags['limit']);
     const asJson = Boolean(flags['json']);
     const showWhy = Boolean(flags['why']);
@@ -798,8 +894,9 @@ async function cmdRecall(hippoRoot, query, flags) {
     // detected-project recalls would change shape.
     const recallExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const requestedScopeForFilter = recallExplicitScope || undefined;
-    let localEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive');
-    let globalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive') : [];
+    const loadSuperseded = includeSuperseded || Boolean(asOf);
+    let localEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive', loadSuperseded);
+    let globalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, requestedScopeForFilter, 'additive', loadSuperseded) : [];
     // v1.12.13 / C5 — WYSIATI counters. Track filter activity per the plan v3
     // Task 3 mapping table. dropped_pre_rank is the SUM of all non-budget
     // filter drops (pre-rank AND post-rank); its meaning is unchanged by C5.
@@ -1669,21 +1766,13 @@ async function cmdRecall(hippoRoot, query, flags) {
         console.log('No memories found for:', query);
         return;
     }
-    // Update retrieval metadata and persist
-    const updated = markRetrieved(results.map((r) => r.entry));
+    const retrievedIds = results.map((r) => r.entry.id);
     const localIndex = loadIndex(hippoRoot);
-    // EVAL-ONLY ablation (see ablation.ts): under the recall flag, markRetrieved
-    // returns unmutated entries (ids preserved for outcome attribution below)
-    // and persistence is skipped - writeEntry on identical rows still refreshes
-    // updated_at, rewrites mirrors, and marks DAG parents dirty.
-    if (!isRecallBoostAblated()) {
-        for (const u of updated) {
-            const targetRoot = localIndex.entries[u.id] ? hippoRoot : (isInitialized(globalRoot) ? globalRoot : hippoRoot);
-            writeEntry(targetRoot, u);
-        }
-    }
+    const strengthenedHere = strengthenRetrieved(hippoRoot, retrievedIds);
+    if (isInitialized(globalRoot))
+        strengthenRetrieved(globalRoot, retrievedIds.filter((id) => !strengthenedHere.has(id)));
     // Track last retrieval IDs for outcome command
-    localIndex.last_retrieval_ids = updated.map((u) => u.id);
+    localIndex.last_retrieval_ids = retrievedIds;
     // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
     // ONE trace at hippoRoot (where last_retrieval_ids and outcome
     // attribution live). Write the trace FIRST, then fold its id into
@@ -1895,7 +1984,7 @@ async function cmdRecall(hippoRoot, query, flags) {
 }
 async function cmdExplain(hippoRoot, query, flags) {
     requireInit(hippoRoot);
-    const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 4000);
     const limit = parseLimitFlag(flags['limit']);
     const asJson = Boolean(flags['json']);
     const forcePhysics = Boolean(flags['physics']);
@@ -1915,8 +2004,9 @@ async function cmdExplain(hippoRoot, query, flags) {
     // command honest for an operator debugging a hidden row.
     const explainExplicitScope = flags['scope'] !== undefined ? String(flags['scope']).trim() : null;
     const explainRequestedScope = explainExplicitScope || undefined;
-    let explainLocalEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, explainRequestedScope, 'additive');
-    let explainGlobalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, explainRequestedScope, 'additive') : [];
+    const explainLoadSuperseded = explainIncludeSuperseded || Boolean(explainAsOf);
+    let explainLocalEntries = loadRecallSearchEntries(hippoRoot, query, undefined, tenantId, explainRequestedScope, 'additive', explainLoadSuperseded);
+    let explainGlobalEntries = isInitialized(globalRoot) ? loadRecallSearchEntries(globalRoot, query, undefined, tenantId, explainRequestedScope, 'additive', explainLoadSuperseded) : [];
     const passesExplainScope = (e) => api.passesCliRecallScopeFilter(e.scope ?? null, explainRequestedScope);
     explainLocalEntries = explainLocalEntries.filter(passesExplainScope);
     explainGlobalEntries = explainGlobalEntries.filter(passesExplainScope);
@@ -2320,6 +2410,7 @@ function cmdTraceRecord(hippoRoot, flags) {
         source: String(flags['source'] ?? 'cli'),
         trace_outcome: outcome,
         source_session_id: sessionId,
+        tenantId: resolveTenantId({}),
     });
     writeEntry(hippoRoot, entry);
     console.log(`Recorded trace ${entry.id} (outcome=${outcome}, ${steps.length} steps)`);
@@ -2484,7 +2575,7 @@ export function learnFromMemoryMd(hippoRoot, homeDir = os.homedir()) {
     }
     if (memoryDirs.length === 0)
         return 0;
-    const existing = loadAllEntries(hippoRoot);
+    const existing = loadAllEntries(hippoRoot, resolveTenantId({}));
     let imported = 0;
     let skippedSecret = 0;
     // AT1 (plan §3 containment): a rejection guard refusal is per-VALUE — one
@@ -2527,6 +2618,7 @@ export function learnFromMemoryMd(hippoRoot, homeDir = os.homedir()) {
                     tags: ['claude-code-memory'],
                     source: `claude-memory:${file}`,
                     confidence: 'observed',
+                    tenantId: resolveTenantId({}),
                 });
                 try {
                     writeEntry(hippoRoot, entry);
@@ -2675,11 +2767,11 @@ export function renderSleepResult(result) {
             parts.push(`${epiDups} duplicate episodic lessons`);
         if (crossDups > 0)
             parts.push(`${crossDups} cross-layer duplicates`);
-        console.log(`\nDeduped ${removed} duplicates (${parts.join(', ')}). Kept stronger copies.`);
+        console.log(`\n${result.dryRun ? 'Would dedupe' : 'Deduped'} ${removed} duplicates (${parts.join(', ')}). ${result.dryRun ? 'Would keep' : 'Kept'} stronger copies.`);
     }
     if (result.audit) {
         if (result.audit.errorsRemoved > 0) {
-            console.log(`\nAudit: removed ${result.audit.errorsRemoved} junk memories (too short/empty).`);
+            console.log(`\nAudit: ${result.dryRun ? 'would remove' : 'removed'} ${result.audit.errorsRemoved} junk memories (too short/empty).`);
         }
         if (result.audit.warningCount > 0) {
             console.log(`Audit: ${result.audit.warningCount} low-quality memories detected (run \`hippo audit\` for details).`);
@@ -2704,7 +2796,10 @@ async function cmdSleepCore(hippoRoot, flags) {
     requireInit(hippoRoot);
     // Phase 1: Auto-learn from git + MEMORY.md (CLI-only, uses process.cwd() / os.homedir()).
     // Stays in cli.ts; api.sleep covers Phase 2-6 only.
-    if (!flags['no-learn']) {
+    if (!flags['no-learn'] && flags['dry-run']) {
+        console.log('Dry run: skipped learning from git commits and MEMORY.md files.');
+    }
+    else if (!flags['no-learn']) {
         const config = loadConfig(hippoRoot);
         if (config.autoLearnOnSleep && isGitRepo(process.cwd())) {
             const { added } = learnFromRepo(hippoRoot, process.cwd(), 1);
@@ -2776,7 +2871,7 @@ function cmdLastSleep(flags) {
 // X8: session-event content is capped at print time only — the shared
 // printSessionEvents stays untouched for every other caller.
 const COMPACT_RESUME_EVENT_CONTENT_CAP = 400;
-function cmdCompactResume(hippoRoot, stdinText) {
+function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
     try {
         // X3: gate on the non-exiting isInitialized check before any
         // store-opening call (loadActiveTaskSnapshot/listSessionEvents both
@@ -2791,7 +2886,9 @@ function cmdCompactResume(hippoRoot, stdinText) {
         // carries a different source (e.g. 'startup') means the matcher-based
         // gate failed to apply — stay silent rather than print stale state.
         const nonEmptyStdin = !!stdinText && stdinText.trim() !== '';
-        let suppressOutput = false;
+        // Without a payload session_id the X5 cross-restore guard below can
+        // never fire, so a timed-out empty read must not reach the print path.
+        let suppressOutput = stdinTimedOut && !nonEmptyStdin;
         let payloadSessionId = null;
         if (nonEmptyStdin) {
             let payload = null;
@@ -2872,30 +2969,23 @@ function cmdCompactResume(hippoRoot, stdinText) {
  */
 async function cmdSessionEnd(hippoRoot, flags) {
     const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : null;
-    // Read stdin synchronously. The SessionEnd hook payload carries
-    // `transcript_path` as JSON; we extract it here and pass it to the worker
-    // via argv so the detached child doesn't need to inherit stdin.
-    // DF1 T3 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md): `session_id`
-    // is extracted the same way, so the worker can close the ending session's
-    // own active task snapshot after sleep+capture finish.
-    let transcriptPath = null;
+    // Bounded read (DF1 T3, docs/plans/2026-08-23-df1-snapshot-lifecycle.md):
+    // extracts transcript_path + session_id for the detached worker's argv.
     let sessionId = null;
+    const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
     try {
-        const stdinText = fs.readFileSync(0, 'utf8');
         if (stdinText && stdinText.trim().startsWith('{')) {
             const payload = JSON.parse(stdinText);
-            if (typeof payload.transcript_path === 'string') {
-                transcriptPath = payload.transcript_path;
-            }
             if (typeof payload.session_id === 'string') {
                 sessionId = payload.session_id;
             }
         }
     }
     catch {
-        // No stdin, not JSON, or read failure — capture will fall back to
-        // transcript auto-discovery; the snapshot close below will no-op.
+        // No stdin, not JSON, or read failure: the snapshot close below will no-op.
     }
+    // Resolved here because only this process saw the payload; the worker captures just the path it is handed.
+    const transcriptPath = resolveLastSessionTranscript(undefined, stdinText, stdinTimedOut);
     const workerArgs = [process.argv[1], '__session-end-worker'];
     if (logFile)
         workerArgs.push('--log-file', logFile);
@@ -2912,11 +3002,11 @@ async function cmdSessionEnd(hippoRoot, flags) {
         child.unref();
     }
     catch (err) {
-        // If spawn fails, run inline as a last resort — better late output than
-        // no consolidation at all. NOTE: `flags` carries neither --transcript nor
-        // --session-id (both are stdin-derived, argv-only for the child), so in
-        // this fallback capture auto-discovers the transcript and the DF1
-        // snapshot close no-ops — the ambient freshness bound is the backstop.
+        // If spawn fails, run inline as a last resort, handed what the child's argv would have carried.
+        if (transcriptPath)
+            flags['transcript'] = transcriptPath;
+        if (sessionId)
+            flags['session-id'] = sessionId;
         await cmdSessionEndWorker(hippoRoot, flags);
         return;
     }
@@ -2959,19 +3049,22 @@ async function cmdSessionEndWorker(hippoRoot, flags) {
         // `[hippo] sleep failed: ...` line. Continue to capture regardless.
     }
     try {
-        const captureOpts = {
-            source: 'last-session',
-            transcriptPath: typeof flags['transcript'] === 'string'
-                ? flags['transcript']
-                : undefined,
-            logFile: typeof flags['log-file'] === 'string'
-                ? flags['log-file']
-                : undefined,
-            dryRun: false,
-            global: false,
-            tenantId: resolveTenantId({}),
-        };
-        cmdCapture(hippoRoot, captureOpts);
+        const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined;
+        const transcriptPath = typeof flags['transcript'] === 'string' ? flags['transcript'] : undefined;
+        // With no stdin of its own, capture would read this as a manual run and scan every project.
+        if (!transcriptPath) {
+            appendSessionEndCloseLog(logFile ?? null, 'skip capture: no transcript for this session');
+        }
+        else {
+            cmdCapture(hippoRoot, {
+                source: 'last-session',
+                transcriptPath,
+                logFile,
+                dryRun: false,
+                global: false,
+                tenantId: resolveTenantId({}),
+            });
+        }
     }
     catch {
         // Same treatment — the failure line is already in the log.
@@ -3154,6 +3247,11 @@ async function cmdCodexSessionEndWorker(hippoRoot, flags) {
             startOffsetBytes,
             startedAtMs,
         }) ?? undefined;
+        // No Codex transcript must not fall through to the scan of Claude Code projects.
+        if (!transcriptPath) {
+            appendSessionEndCloseLog(logFile ?? null, 'skip capture: no Codex transcript for this session');
+            return;
+        }
         const captureOpts = {
             source: 'last-session',
             transcriptPath,
@@ -3168,13 +3266,13 @@ async function cmdCodexSessionEndWorker(hippoRoot, flags) {
         // capture path logs its own failures
     }
 }
-function shouldAutoRepairCodexWrapper(currentCommand, currentArgs) {
+export function shouldAutoRepairCodexWrapper(currentCommand, flags) {
     if (process.env.HIPPO_SKIP_AUTO_INTEGRATIONS === '1')
         return false;
     if (!['context', 'remember', 'recall', 'sleep', 'capture', 'outcome', 'status', 'init'].includes(currentCommand)) {
         return false;
     }
-    if (currentCommand === 'init' && currentArgs.includes('--no-hooks'))
+    if (currentCommand === 'init' && flags['no-hooks'] === true)
         return false;
     return true;
 }
@@ -3183,8 +3281,8 @@ function shouldAutoRepairCodexWrapper(currentCommand, currentArgs) {
 // shim). Never first-installs — silently swapping the codex binary on routine
 // commands is a consent violation and reads as binary hijacking to
 // supply-chain scanners (issue #133).
-function maybeRepairCodexWrapper(currentCommand, currentArgs) {
-    if (!shouldAutoRepairCodexWrapper(currentCommand, currentArgs))
+function maybeRepairCodexWrapper(currentCommand, flags) {
+    if (!shouldAutoRepairCodexWrapper(currentCommand, flags))
         return;
     try {
         repairCodexWrapperIfInstalled();
@@ -3406,8 +3504,7 @@ function cmdForget(hippoRoot, id, flags) {
         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.
-            console.error(`Cannot forget ${id}: it is a raw, append-only memory. ` +
-                `Archive it instead: hippo forget ${id} --archive --reason "<why>"`);
+            console.error(rawForgetRefusal(id));
         }
         else {
             console.error(`Memory not found: ${id}`);
@@ -3415,6 +3512,28 @@ function cmdForget(hippoRoot, id, flags) {
         process.exit(1);
     }
 }
+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) {
+    requireInit(hippoRoot);
+    const entry = readEntry(hippoRoot, id, resolveTenantId({}));
+    if (!entry) {
+        console.error(`Memory not found: ${id}`);
+        process.exit(1);
+    }
+    if (!archive && entry.kind === 'raw') {
+        console.error(rawForgetRefusal(id));
+        process.exit(1);
+    }
+    if (archive && entry.kind !== 'raw') {
+        console.error(`Could not archive ${id}: memory ${id} is not raw (kind=${entry.kind})`);
+        process.exit(1);
+    }
+    const snippet = entry.content.length > 80 ? `${entry.content.slice(0, 80)}...` : entry.content;
+    console.log(`Would ${archive ? 'archive' : 'forget'} ${id} (dry run, nothing changed): "${snippet}"`);
+}
 function cmdInspect(hippoRoot, id) {
     requireInit(hippoRoot);
     const entry = readEntry(hippoRoot, id, resolveTenantId({}));
@@ -4122,10 +4241,8 @@ function cmdCard(hippoRoot, args, flags) {
         const allowedFlags = CARD_SUBCOMMAND_FLAGS[subcommand];
         for (const key of Object.keys(flags)) {
             if (!allowedFlags.includes(key)) {
-                // --flag=value never splits on '=' (see parseArgs), so it lands here as one long key.
-                const hint = key.includes('=') ? ` Use --${key.slice(0, key.indexOf('='))} <value>, not --${key}.` : '';
                 const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
-                console.error(`Unknown flag --${key} for hippo card ${subcommand}.${hint} Valid flags: ${valid}`);
+                console.error(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
                 process.exit(1);
             }
         }
@@ -5915,7 +6032,7 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
     if (!pinnedOnly) {
         requireInit(hippoRoot);
     }
-    const budget = parseInt(String(flags['budget'] ?? '1500'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 1500);
     if (budget <= 0)
         return;
     // Resolve query: explicit args, --auto (git diff via CLI-side helper), or
@@ -6247,9 +6364,9 @@ async function cmdWatch(command, hippoRoot) {
         console.error('Command failed but .hippo not initialized. Run `hippo init` to enable auto-learn.');
         process.exit(exitCode);
     }
-    const entry = captureError(exitCode, stderr, command);
+    const entry = captureError(exitCode, stderr, command, resolveTenantId({}));
     // Compute schema fit against existing memories
-    const existingWatch = loadAllEntries(hippoRoot);
+    const existingWatch = loadAllEntries(hippoRoot, entry.tenantId);
     const watchFit = computeSchemaFit(entry.content, entry.tags, existingWatch);
     entry.schema_fit = watchFit;
     entry.half_life_days = deriveHalfLife(7, entry);
@@ -6335,14 +6452,9 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
     // the existing summary line.
     let rejected = 0;
     const gitLearnTags = ['error', 'git-learned'];
-    const existingForSchema = loadAllEntries(hippoRoot);
+    const existingForSchema = loadAllEntries(hippoRoot, resolveTenantId({}));
     for (const lesson of lessons) {
-        // L9: learnFromRepo's existingForSchema load just above (the
-        // `loadAllEntries(hippoRoot)` call a few lines up) is host-wide and
-        // intentionally out-of-L9-scope per plan §11 (cli.ts is
-        // single-tenant-per-process). The tenantId arg here is a defensive no-op:
-        // deduplicateLesson's array overload ignores it; the parameter exists
-        // only to mirror the canonical caller pattern used elsewhere in cli.ts.
+        // The array overload ignores the tenant arg; existingForSchema is already scoped.
         if (deduplicateLesson(existingForSchema, lesson, 0.7, resolveTenantId({}))) {
             skipped++;
             continue;
@@ -6361,6 +6473,7 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
             source: 'git-learn',
             confidence: 'observed',
             schema_fit: schemaFitVal,
+            tenantId: resolveTenantId({}),
         });
         // Auto-tag with path context from the repo being learned
         const learnPathTags = extractPathTags(repoPath);
@@ -7242,7 +7355,8 @@ function cmdDag(hippoRoot, flags) {
 }
 function cmdAssemble(hippoRoot, sessionId, flags) {
     requireInit(hippoRoot);
-    const budget = typeof flags['budget'] === 'string' ? Number(flags['budget']) : undefined;
+    // Absent stays undefined so the api default applies; the 0 fallback is unreachable.
+    const budget = flags['budget'] === undefined ? undefined : parseBudgetFlag(flags['budget'], 0);
     const freshTailCount = typeof flags['fresh-tail'] === 'string' ? Number(flags['fresh-tail']) : undefined;
     const summarizeOlder = flags['no-summarize-older'] !== true;
     const scope = typeof flags['scope'] === 'string' && flags['scope'].length > 0
@@ -7273,7 +7387,8 @@ function cmdAssemble(hippoRoot, sessionId, flags) {
 function cmdDrillDown(hippoRoot, summaryId, flags) {
     requireInit(hippoRoot);
     const limit = typeof flags['limit'] === 'string' ? Number(flags['limit']) : undefined;
-    const budget = typeof flags['budget'] === 'string' ? Number(flags['budget']) : undefined;
+    // Absent stays undefined so the api default applies; the 0 fallback is unreachable.
+    const budget = flags['budget'] === undefined ? undefined : parseBudgetFlag(flags['budget'], 0);
     // v0.30 / E5: --depth N walks N levels down (default 1, hard cap 10).
     // L4 fold: reject out-of-range explicitly (no silent clamp).
     const rawDepth = typeof flags['depth'] === 'string' ? Number(flags['depth']) : undefined;
@@ -8573,25 +8688,16 @@ Examples:
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-const { command, args, flags } = parseArgs(process.argv);
-const hippoRoot = getHippoRoot(process.cwd());
-async function main() {
+async function main(command, args, flags, hippoRoot) {
     if (command === '--version' || command === '-v' || flags['version']) {
         const __filename_local = fileURLToPath(import.meta.url);
         const __dirname_local = path.dirname(__filename_local);
-        const pkgPath = path.join(__dirname_local, '..', 'package.json');
-        let pkgJson;
-        try {
-            pkgJson = fs.readFileSync(pkgPath, 'utf-8');
-        }
-        catch {
-            pkgJson = fs.readFileSync(path.join(__dirname_local, '..', '..', 'package.json'), 'utf-8');
-        }
+        const pkgJson = fs.readFileSync(path.join(__dirname_local, '..', 'package.json'), 'utf-8');
         const { version } = JSON.parse(pkgJson);
         console.log(version);
         process.exit(0);
     }
-    maybeRepairCodexWrapper(command, args);
+    maybeRepairCodexWrapper(command, flags);
     /** Global --scope well-formedness guard (v1.26.2). parseArgs stores a value-less
      *  flag as boolean true; downstream the 14 consumer sites either coerced that to
      *  the literal scope string 'true' (recall filter/unlock input, wm session scope,
@@ -8603,6 +8709,44 @@ async function main() {
         console.error('--scope requires a non-empty value (e.g. --scope slack:private:C1).');
         process.exit(1);
     }
+    // parseArgs stores a value-less flag as boolean true, and NaN then survives every
+    // downstream guard because each comparison against it is false.
+    const NUMERIC_FLAGS = [
+        'days', 'threshold', 'min-score', 'port', 'limit', 'mmr-lambda', 'local-bump',
+        'min-results', 'reranker-top-k', 'min-mrr', 'embedding-weight', 'max-cases',
+    ];
+    for (const key of NUMERIC_FLAGS) {
+        const raw = flags[key];
+        if (raw === undefined)
+            continue;
+        if (typeof raw !== 'string' || !raw.trim() || !Number.isFinite(Number(raw))) {
+            console.error(`--${key} requires a numeric value.`);
+            process.exit(1);
+        }
+    }
+    // Reject rather than coerce: consumers read --dry-run both as Boolean() and === true,
+    // so no single coercion of an inline value would be correct for every one of them.
+    for (const key of BOOLEAN_FLAGS) {
+        if (Object.hasOwn(flags, key) && typeof flags[key] !== 'boolean') {
+            console.error(`--${key} takes no value`);
+            process.exit(1);
+        }
+    }
+    // card checks its flags per subcommand, with a stricter message.
+    const unknownFlags = command === 'card' ? [] : Object.keys(flags).filter((key) => !KNOWN_FLAGS.has(key));
+    if (unknownFlags.length > 0) {
+        const names = unknownFlags.map((key) => `--${key}`).join(', ');
+        if (DESTRUCTIVE_COMMANDS.has(command)) {
+            console.error(`Unknown flag ${names} for hippo ${command}. Nothing was changed.`);
+            process.exit(2);
+        }
+        console.error(`hippo: ignoring unknown flag ${names}. A later release will reject it.`);
+    }
+    const refusal = Object.hasOwn(flags, 'dry-run') ? dryRunRefusal(command, args, flags) : null;
+    if (refusal) {
+        console.error(refusal);
+        process.exit(2);
+    }
     switch (command) {
         case 'init':
             cmdInit(hippoRoot, flags);
@@ -8747,34 +8891,18 @@ async function main() {
             await cmdSessionEndWorker(hippoRoot, flags);
             break;
         case 'pre-compact': {
-            // Same TTY guard as `capture --last-session`: skip reading stdin when
-            // it's an interactive terminal so a manual invocation never hangs.
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
+            // Bounded wait, not a TTY guard: an idle non-TTY pipe must not hang.
+            const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
             await cmdPreCompact(hippoRoot, {
                 stdinText,
+                stdinTimedOut,
                 logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
             });
             break;
         }
         case 'compact-resume': {
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
-            cmdCompactResume(hippoRoot, stdinText);
+            const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
+            cmdCompactResume(hippoRoot, stdinText, stdinTimedOut);
             break;
         }
         case 'codex-run':
@@ -8810,7 +8938,7 @@ async function main() {
                 break;
             }
             requireInit(hippoRoot);
-            const entries = loadAllEntries(hippoRoot);
+            const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
             const result = auditMemories(entries);
             const shouldFix = Boolean(flags['fix']);
             if (result.issues.length === 0) {
@@ -8824,13 +8952,15 @@ async function main() {
                     console.log(`         "${issue.content.slice(0, 80)}${issue.content.length > 80 ? '...' : ''}"`);
                 }
                 if (shouldFix) {
-                    const errorIds = result.issues.filter(i => i.severity === 'error').map(i => i.memoryId);
-                    if (errorIds.length > 0) {
-                        for (const id of errorIds) {
-                            deleteEntry(hippoRoot, id);
-                        }
-                        console.log(`\nRemoved ${errorIds.length} error-severity memories.`);
-                        console.log(`${result.issues.length - errorIds.length} warnings remain (review manually).`);
+                    const errors = result.issues.filter(i => i.severity === 'error');
+                    if (errors.length > 0 && flags['dry-run'] === true) {
+                        console.log(`\nWould remove ${errors.length} error-severity memories (dry run, nothing deleted).`);
+                        console.log(`${result.issues.length - errors.length} warnings would remain (review manually).`);
+                    }
+                    else if (errors.length > 0) {
+                        const removedCount = errors.filter((issue) => deleteEntry(hippoRoot, issue.memoryId, { reason: `audit --fix: ${issue.reason}`, automatic: true })).length;
+                        console.log(`\nRemoved ${removedCount} error-severity memories.`);
+                        console.log(`${result.issues.length - errors.length} warnings remain (review manually).`);
                     }
                     else {
                         console.log(`\nNo error-severity issues. Warnings require manual review.`);
@@ -8951,6 +9081,10 @@ async function main() {
                 console.error(ARCHIVE_REASON_REQUIRED);
                 process.exit(1);
             }
+            if (flags['dry-run'] === true) {
+                previewForget(hippoRoot, id, archive);
+                break;
+            }
             const routed = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
                 try {
                     if (archive) {
@@ -8987,23 +9121,9 @@ async function main() {
             break;
         }
         case 'context': {
-            // DF1 T2 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md): same TTY
-            // guard as `pre-compact` / `compact-resume` above — skip reading stdin
-            // when it's an interactive terminal so a manual invocation never
-            // hangs. `hippo context` is both the hot UserPromptSubmit path
-            // (non-TTY, stdin carries the hook JSON with `session_id`) and a
-            // manually-invocable command (TTY, no payload) — the guardless read in
-            // cmdSessionEnd is the wrong sibling to copy here; it only runs under
-            // a hook that always supplies stdin.
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
+            // Bounded, not a TTY guard (DF1 T2, docs/plans/2026-08-23-df1-snapshot-lifecycle.md):
+            // the hot stdin path and a manual run share this one command.
+            const { text: stdinText } = await readStdinBounded();
             await cmdContext(hippoRoot, args, flags, stdinText);
             break;
         }
@@ -9130,7 +9250,7 @@ async function main() {
             requireInit(hippoRoot);
             const format = flags['format'] || 'json';
             const outputPath = args[0] || null;
-            const entries = loadAllEntries(hippoRoot);
+            const entries = loadAllEntries(hippoRoot, resolveTenantId({}));
             let output;
             if (format === 'markdown' || format === 'md') {
                 output = entries.map(e => {
@@ -9180,10 +9300,17 @@ async function main() {
                 console.error('Usage: hippo capture --stdin|--file <path>|--last-session [--transcript <path>] [--log-file <path>] [--dry-run] [--global]');
                 process.exit(1);
             }
+            // Bounded, and only when last-session has no explicit path: the
+            // --stdin source keeps its own blocking read in capture.ts by design.
+            const bounded = captureSource === 'last-session' && !transcriptPath
+                ? await readStdinBounded()
+                : { text: undefined, timedOut: false };
             cmdCapture(hippoRoot, {
                 source: captureSource,
                 filePath: captureFile,
                 transcriptPath,
+                stdinText: bounded.text,
+                stdinTimedOut: bounded.timedOut,
                 logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
                 dryRun: Boolean(flags['dry-run']),
                 global: Boolean(flags['global']),
@@ -9223,11 +9350,11 @@ async function main() {
             }
             const host = typeof flags['host'] === 'string' ? flags['host'] : '127.0.0.1';
             const { serve } = await import('./server.js');
-            const handle = await serve({ hippoRoot, port, host });
+            const handle = await serve({ hippoRoot, port, host, handleSignals: true });
             console.log(`hippo serve listening on ${handle.url} (pid ${process.pid})`);
             console.log(`pidfile: ${path.join(hippoRoot, 'server.pid')}`);
             console.log('press Ctrl+C to stop');
-            // SIGINT/SIGTERM handlers wired in server.ts (skipped under VITEST). Hang.
+            // The SIGINT/SIGTERM handlers stop the server and exit. Hang until then.
             await new Promise(() => { });
             break;
         }
@@ -9242,8 +9369,8 @@ async function main() {
             }
             const onlyId = typeof flags['id'] === 'string' ? flags['id'] : undefined;
             if (typeof flags['dry-run'] === 'string') {
-                // Unreachable via argv (dry-run is in BOOLEAN_FLAGS); guards
-                // programmatically-built flags objects.
+                // Dead: the earlier global BOOLEAN_FLAGS guard now exits first on any --dry-run=<v>.
+                // Kept as defence in depth on a destructive command.
                 console.error('--dry-run takes no value');
                 process.exit(1);
             }
@@ -9321,8 +9448,19 @@ async function main() {
             process.exit(1);
     }
 }
-main().catch((err) => {
-    console.error('Error:', err.message ?? err);
-    process.exit(1);
-});
+export async function runCli(argv = process.argv) {
+    const { command, args, flags } = parseArgs(argv);
+    try {
+        await main(command, args, flags, getHippoRoot(process.cwd()));
+    }
+    catch (err) {
+        console.error('Error:', err instanceof Error ? err.message : err);
+        process.exit(1);
+    }
+}
+// bin/hippo.js calls runCli(); this keeps `node dist/cli.js` working while an import runs nothing.
+const entryPath = process.argv[1];
+if (entryPath && fs.existsSync(entryPath) && fs.realpathSync(entryPath) === fileURLToPath(import.meta.url)) {
+    void runCli();
+}
 //# sourceMappingURL=cli.js.map