hippo-memory 1.44.0 → 1.46.0

package/dist/cli.js

@@ -19,6 +19,9 @@
  *   hippo reject <id>|--value "<text>" --reason "<why>"
  *   hippo rejections
  *   hippo unreject <digest-prefix>
+ *   hippo dormant [<query>] [--limit <n>] [--json] | restore <id> | forget <id>
+ *   hippo tokens [--days <n>] [--json] [--global]
+ *   hippo doctor [--json]
  *   hippo inspect <id>
  *   hippo embed [--status]
  *   hippo watch "<command>"
@@ -29,7 +32,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 +41,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 { estimateTokens, 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';
@@ -56,6 +59,9 @@ import { loadPhysicsState, resetAllPhysicsState } from './physics-state.js';
 import { computeSystemEnergy, vecNorm } from './physics.js';
 import { loadConfig } from './config.js';
 import { openHippoDb, closeHippoDb } from './db.js';
+import { runDoctor, formatDoctor } from './doctor.js';
+import { captureToolFailure } from './capture-error.js';
+import { blockHash, hookPayloadSessionId, lastSentState, recordTokenUse, shouldSkipUnchanged } from './token-ledger.js';
 import { pushGoal, getActiveGoals, completeGoal, suspendGoal, resumeGoal, applyGoalStackBoost } from './goals.js';
 import { rowToGoal } from './goals.js';
 import { captureError, extractLessons, partitionLessons, deduplicateLesson, runWatched, fetchGitLog, isGitRepo, } from './autolearn.js';
@@ -65,7 +71,7 @@ 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, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
+import { cmdCapture, cmdPreCompact, postCompactMessage, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
 import { readStdinBounded } from './stdin.js';
 import { auditMemories, appendAuditEvent, } from './audit.js';
 import { listApiKeys, revokeApiKey } from './auth.js';
@@ -195,8 +201,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']) {
@@ -263,6 +269,42 @@ export const BOOLEAN_FLAGS = new Set([
     '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';
@@ -506,17 +548,17 @@ function autoInstallHooks(quiet) {
         // Skip if we already installed a hook into this file
         if (installed.has(targetPath))
             continue;
-        // Skip if hook already present
-        if (fs.existsSync(targetPath)) {
-            const content = fs.readFileSync(targetPath, 'utf8');
-            if (content.includes(HOOK_MARKERS.start))
-                continue;
-        }
+        // An instruction block already present is not rewritten, but the JSON
+        // hooks and plugins below still run: they are idempotent, and skipping
+        // them meant a store set up by an older hippo never got hooks added in
+        // later releases (PreCompact, PostToolUseFailure) on a re-run of init.
+        const blockPresent = fs.existsSync(targetPath)
+            && fs.readFileSync(targetPath, 'utf8').includes(HOOK_MARKERS.start);
         // Only patch the agent-instructions file if it already exists.
         // Never create a new CLAUDE.md / AGENTS.md / etc. just because a sibling
         // marker file (.claude/settings.json, .codex, etc.) was detected — that
         // pollutes dirs the user didn't intend to configure.
-        if (fs.existsSync(targetPath)) {
+        if (!blockPresent && fs.existsSync(targetPath)) {
             const block = `${HOOK_MARKERS.start}\n${hookDef.content}\n${HOOK_MARKERS.end}`;
             const existing = fs.readFileSync(targetPath, 'utf8');
             const sep = existing.endsWith('\n') ? '\n' : '\n\n';
@@ -527,7 +569,7 @@ function autoInstallHooks(quiet) {
         // The Codex session-capture wrapper swaps the codex launcher binary, so
         // init never installs it silently — it points at the explicit opt-in
         // command instead (issue #133).
-        if (hook === 'codex' && !isCodexWrapperInstalled()) {
+        if (hook === 'codex' && !blockPresent && !isCodexWrapperInstalled()) {
             console.log('   Codex detected. To capture Codex sessions: hippo hook install codex');
         }
         // For Claude Code, also install SessionEnd+SessionStart entries in its
@@ -550,6 +592,12 @@ function autoInstallHooks(quiet) {
             if (result.installedCompactResume) {
                 console.log(`   Auto-installed hippo compact-resume SessionStart(compact) hook in ${hook} settings`);
             }
+            if (result.installedPostCompact) {
+                console.log(`   Auto-installed hippo post-compact PostCompact hook in ${hook} settings`);
+            }
+            if (result.installedCaptureError) {
+                console.log(`   Auto-installed hippo capture-error PostToolUseFailure hook in ${hook} settings`);
+            }
             if (result.migratedFromStop) {
                 console.log(`   Migrated legacy Stop hook → SessionEnd (no longer runs every turn)`);
             }
@@ -658,7 +706,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;
@@ -688,6 +736,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,
@@ -700,6 +749,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());
@@ -716,7 +766,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,
@@ -758,14 +807,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) {
@@ -797,6 +848,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
@@ -854,8 +906,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.
@@ -1616,7 +1669,7 @@ async function cmdRecall(hippoRoot, query, flags) {
         sessionHandoff =
             rawHandoff && passesScopeFilterForRecall(rowScope(rawHandoff), effectiveScope) ? rawHandoff : null;
         recentSessionEvents = rawEvents.filter((e) => passesScopeFilterForRecall(rowScope(e), effectiveScope));
-        const tokenize = (s) => s ? Math.ceil(s.length / 4) : 0;
+        const tokenize = (s) => s ? estimateTokens(s) : 0;
         continuityTokens =
             tokenize(activeSnapshot?.task) +
                 tokenize(activeSnapshot?.summary) +
@@ -1634,6 +1687,16 @@ async function cmdRecall(hippoRoot, query, flags) {
     const hasContinuity = activeSnapshot !== null
         || sessionHandoff !== null
         || recentSessionEvents.length > 0;
+    // TE0 token ledger: the memory text this recall hands back (results plus
+    // any continuity block), recorded once per query.
+    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+        tenantId,
+        sessionId: hostSessionId() ?? null,
+        surface: 'recall',
+        event: 'inject',
+        items: results.length,
+        tokens: results.reduce((acc, r) => acc + (r.tokens || 0), 0) + continuityTokens,
+    }));
     if (results.length === 0) {
         // LC1 F1 structural fix (docs/plans/2026-08-02-lc1-recall-trace-persistence.md):
         // trace the zero-result recall too (result_count 0, no result rows) so
@@ -1725,21 +1788,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
@@ -1971,8 +2026,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);
@@ -2376,6 +2432,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)`);
@@ -2540,7 +2597,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
@@ -2583,6 +2640,7 @@ export function learnFromMemoryMd(hippoRoot, homeDir = os.homedir()) {
                     tags: ['claude-code-memory'],
                     source: `claude-memory:${file}`,
                     confidence: 'observed',
+                    tenantId: resolveTenantId({}),
                 });
                 try {
                     writeEntry(hippoRoot, entry);
@@ -2712,6 +2770,14 @@ export function renderSleepResult(result) {
     console.log(`\nResults:`);
     console.log(`   Active memories:  ${result.active}`);
     console.log(`   Removed (decayed): ${result.removed}`);
+    // Only when dormant.enabled moved something, so every other render stays
+    // byte-identical (tests/cli-context-render-snapshot.test.ts).
+    if (result.dormant !== undefined && result.dormant > 0) {
+        console.log(`   Kept dormant:      ${result.dormant}  (hippo dormant to list)`);
+    }
+    if (result.dormantExpired !== undefined && result.dormantExpired > 0) {
+        console.log(`   Expired dormant:   ${result.dormantExpired}  (past dormant.retentionDays)`);
+    }
     console.log(`   Merged episodic:   ${result.mergedEpisodic}`);
     console.log(`   New semantic:      ${result.newSemantic}`);
     if (result.details && result.details.length > 0) {
@@ -2731,11 +2797,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).`);
@@ -2760,7 +2826,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);
@@ -3227,13 +3296,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;
 }
@@ -3242,8 +3311,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();
@@ -3465,8 +3534,13 @@ 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 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.
+            console.error(`${id} is dormant, not in active memory. Delete it for good: hippo dormant forget ${id} ` +
+                `(or bring it back: hippo dormant restore ${id})`);
         }
         else {
             console.error(`Memory not found: ${id}`);
@@ -3474,6 +3548,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({}));
@@ -3729,6 +3825,110 @@ function cmdUnreject(hippoRoot, args, flags) {
     }
     console.log(`Unrejected [${outcome.digest.slice(0, 12)}...] (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).
+ */
+function cmdDormant(hippoRoot, args, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: api.adminActor('cli'),
+    };
+    const sub = args[0];
+    if (sub === 'restore' || sub === 'forget') {
+        const id = (args[1] ?? '').trim();
+        if (!id) {
+            console.error(`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) {
+                console.error(`Cannot restore ${id}: its value was rejected (${err.reason ?? 'no reason given'}). Run \`hippo unreject\` first to allow it.`);
+            }
+            else {
+                console.error(`Could not ${sub} ${id}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            process.exit(1);
+        }
+        return;
+    }
+    const queryArgs = sub === 'list' ? args.slice(1) : args;
+    const limit = parseCountFlag(flags['limit']);
+    const rows = api.listDormant(ctx, {
+        query: queryArgs.join(' '),
+        limit: limit > 0 ? limit : undefined,
+    });
+    if (flags['json']) {
+        console.log(JSON.stringify({ dormant: rows }, null, 2));
+        return;
+    }
+    if (rows.length === 0) {
+        console.log(queryArgs.length > 0 ? '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`);
+    for (const row of rows) {
+        const preview = row.content.length > 100 ? `${row.content.slice(0, 100)}...` : 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('');
+    }
+    console.log('Bring one back: hippo dormant restore <id>   Delete for good: hippo dormant forget <id>');
+}
+/**
+ * `hippo tokens [--days <n>] [--json] [--global]`: the token ledger
+ * (ROADMAP TE0). Tokens of memory text handed to agents per surface, blocks
+ * the per-prompt hook skipped as unchanged (TE2) and the tokens that saved.
+ * Counts are estimates (characters / 4), the same estimate every budget uses.
+ */
+function cmdTokens(hippoRoot, flags) {
+    const root = resolveAuthRoot(hippoRoot, flags);
+    const ctx = {
+        hippoRoot: root,
+        tenantId: resolveTenantId({}),
+        actor: api.adminActor('cli'),
+    };
+    const days = parseCountFlag(flags['days']);
+    const summary = api.tokenSummary(ctx, { days: days > 0 ? days : undefined });
+    if (flags['json']) {
+        console.log(JSON.stringify(summary, null, 2));
+        return;
+    }
+    const windowDays = days > 0 ? days : 30;
+    if (summary.surfaces.length === 0) {
+        console.log(`No memory text recorded in the last ${windowDays} days.`);
+        return;
+    }
+    console.log(`Memory text handed to agents, last ${windowDays} days (estimated tokens)\n`);
+    console.log(`  ${'surface'.padEnd(14)}${'sent'.padStart(8)}${'tokens'.padStart(12)}${'skipped'.padStart(10)}${'saved'.padStart(12)}`);
+    for (const row of summary.surfaces) {
+        console.log(`  ${row.surface.padEnd(14)}${String(row.injected).padStart(8)}${String(row.tokens).padStart(12)}`
+            + `${String(row.skipped).padStart(10)}${String(row.tokensAvoided).padStart(12)}`);
+    }
+    console.log('');
+    console.log(`  Total sent: ${summary.totalTokens} tokens. Saved by skipping unchanged blocks: ${summary.totalTokensAvoided}.`);
+    if (summary.meanTokensPerSession > 0) {
+        console.log(`  Mean per session (rows with a session id): ${summary.meanTokensPerSession} tokens.`);
+    }
+}
 function cmdSnapshot(hippoRoot, args, flags) {
     requireInit(hippoRoot);
     const subcommand = args[0] ?? 'show';
@@ -6057,22 +6257,24 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             origin: r.origin ?? null,
             category: r.category ?? null,
         }));
-        console.log(JSON.stringify({
+        const jsonText = JSON.stringify({
             query: query || '*',
             activeSnapshot: result.activeSnapshot ?? null,
             sessionHandoff: result.sessionHandoff ?? null,
             recentSessionEvents: result.recentEvents ?? [],
             memories: output,
             tokens: result.tokens,
+        });
+        console.log(jsonText);
+        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+            tenantId: ctx.tenantId, sessionId: currentSessionId, surface: pinnedOnly ? 'hook' : 'context',
+            event: 'inject', items: output.length, tokens: estimateTokens(jsonText),
         }));
     }
     else if (format === 'additional-context') {
         // Claude Code UserPromptSubmit hook JSON shape. Capture print* helpers'
         // output into a string buffer and wrap as `additionalContext`.
-        const lines = [];
-        const realLog = console.log;
-        console.log = (...parts) => { lines.push(parts.map(String).join(' ')); };
-        try {
+        const textBlock = captureConsole(() => {
             if (result.activeSnapshot)
                 printActiveTaskSnapshot(result.activeSnapshot);
             if (result.sessionHandoff)
@@ -6081,16 +6283,37 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
                 printSessionEvents(result.recentEvents);
             }
             if (renderItems.length > 0) {
-                printContextMarkdown(renderItems, result.tokens, framing);
+                // TE1: no live strength percentage, so an unchanged set of memories
+                // renders byte-identically turn after turn.
+                printContextMarkdown(renderItems, result.tokens, framing, { showStrength: false });
             }
             printCrossProjectSection(crossEntries);
-        }
-        finally {
-            console.log = realLog;
-        }
-        const textBlock = lines.join('\n');
+        });
         if (!textBlock.trim())
             return;
+        const surface = pinnedOnly ? 'hook' : 'context';
+        const hash = blockHash(textBlock);
+        const tokens = estimateTokens(textBlock);
+        // TE2: the per-prompt hook skips a block identical to the one this
+        // session already has, and resends it every refreshTurns skips. Only
+        // with a session id from the hook payload itself: an inherited env id
+        // (a manual run inside an agent's shell) must never suppress output.
+        if (pinnedOnly && payloadSessionId !== undefined) {
+            const injectCfg = loadConfig(hippoRoot).pinnedInject;
+            if (injectCfg.skipUnchanged !== false) {
+                const refreshTurns = Number.isFinite(injectCfg.refreshTurns) && injectCfg.refreshTurns >= 0
+                    ? injectCfg.refreshTurns
+                    : 10;
+                const last = withLedgerDb(hippoRoot, (db) => lastSentState(db, ctx.tenantId, payloadSessionId, surface));
+                if (shouldSkipUnchanged(last ?? null, hash, refreshTurns)) {
+                    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+                        tenantId: ctx.tenantId, sessionId: payloadSessionId, surface, event: 'skip',
+                        items: renderItems.length, tokens, hash,
+                    }));
+                    return;
+                }
+            }
+        }
         const payload = {
             hookSpecificOutput: {
                 hookEventName: 'UserPromptSubmit',
@@ -6098,25 +6321,113 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
             },
         };
         process.stdout.write(JSON.stringify(payload));
+        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+            tenantId: ctx.tenantId, sessionId: currentSessionId, surface, event: 'inject',
+            items: renderItems.length, tokens, hash,
+        }));
     }
     else {
         // markdown (default)
-        if (result.activeSnapshot) {
-            printActiveTaskSnapshot(result.activeSnapshot);
-        }
-        if (result.sessionHandoff) {
-            printHandoff(result.sessionHandoff);
-        }
-        if (result.recentEvents && result.recentEvents.length > 0) {
-            printSessionEvents(result.recentEvents);
-        }
-        if (renderItems.length > 0) {
-            printContextMarkdown(renderItems, result.tokens, framing);
-        }
-        printCrossProjectSection(crossEntries);
-        if (result.ambientState) {
-            console.log(`\n${renderAmbientSummary(result.ambientState)}`);
-        }
+        const text = captureConsole(() => {
+            if (result.activeSnapshot) {
+                printActiveTaskSnapshot(result.activeSnapshot);
+            }
+            if (result.sessionHandoff) {
+                printHandoff(result.sessionHandoff);
+            }
+            if (result.recentEvents && result.recentEvents.length > 0) {
+                printSessionEvents(result.recentEvents);
+            }
+            if (renderItems.length > 0) {
+                printContextMarkdown(renderItems, result.tokens, framing);
+            }
+            printCrossProjectSection(crossEntries);
+            if (result.ambientState) {
+                console.log(`\n${renderAmbientSummary(result.ambientState)}`);
+            }
+        });
+        if (text.length > 0)
+            console.log(text);
+        withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+            tenantId: ctx.tenantId, sessionId: currentSessionId, surface: pinnedOnly ? 'hook' : 'context',
+            event: 'inject', items: renderItems.length, tokens: estimateTokens(text),
+        }));
+    }
+}
+/**
+ * TE2: compaction drops the pinned blocks the per-prompt hook injected
+ * earlier, so record a `reset` for the payload's session and the next prompt
+ * injects again even if nothing changed. `requiredSource` limits it to hook
+ * payloads with that `source` (SessionStart fires for other reasons too).
+ * Best-effort and silent: a malformed payload records nothing.
+ */
+function resetHookInjection(hippoRoot, stdinText, requiredSource) {
+    const sessionId = hookPayloadSessionId(stdinText, requiredSource);
+    if (sessionId === null)
+        return;
+    withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
+        tenantId: resolveTenantId({}), sessionId, surface: 'hook', event: 'reset', items: 0, tokens: 0,
+    }));
+}
+/**
+ * Run `fn` with console.log captured; returns the captured lines joined by
+ * newlines (what the same calls would have printed, minus the final newline).
+ */
+function captureConsole(fn) {
+    const lines = [];
+    const realLog = console.log;
+    console.log = (...parts) => { lines.push(parts.map(String).join(' ')); };
+    try {
+        fn();
+    }
+    finally {
+        console.log = realLog;
+    }
+    return lines.join('\n');
+}
+/**
+ * The store a Claude Code hook writes to: the project store when there is
+ * one, else an existing global store, else the project path (which the hook
+ * then skips, since hooks fire in every directory and must not create one).
+ * Pre-compact and compact-resume must agree, or a snapshot saved to one store
+ * is looked for in the other.
+ */
+function hookStoreRoot(hippoRoot) {
+    if (isInitialized(hippoRoot))
+        return hippoRoot;
+    const globalRoot = getGlobalRoot();
+    return isInitialized(globalRoot) ? globalRoot : hippoRoot;
+}
+/**
+ * Run `fn` against the token ledger's store: the local store when it is
+ * initialized, else the global one (the per-prompt hook runs in directories
+ * without a local store). Best-effort: returns undefined and never throws,
+ * because a ledger failure must not break context or recall.
+ */
+function withLedgerDb(hippoRoot, fn) {
+    let root = null;
+    try {
+        if (isInitialized(hippoRoot))
+            root = hippoRoot;
+        else if (isInitialized(getGlobalRoot()))
+            root = getGlobalRoot();
+    }
+    catch {
+        return undefined;
+    }
+    if (root === null)
+        return undefined;
+    let db;
+    try {
+        db = openHippoDb(root);
+        return fn(db);
+    }
+    catch {
+        return undefined;
+    }
+    finally {
+        if (db)
+            closeHippoDb(db);
     }
 }
 /**
@@ -6135,13 +6446,15 @@ function printCrossProjectSection(items) {
     }
 }
 /** @internal — exported for snapshot tests (tests/cli-context-render-snapshot.test.ts). NOT a stable public API. */
-export function printContextMarkdown(items, totalTokens, framing = 'observe') {
+export function printContextMarkdown(items, totalTokens, framing = 'observe', opts = {}) {
     const now = evalNow();
+    const showStrength = opts.showStrength !== false;
     console.log(`## Project Memory (${items.length} entries, ${totalTokens} tokens)\n`);
     for (const item of items) {
         const e = item.entry;
         const tagStr = e.tags.length > 0 ? ` [${e.tags.join(', ')}]` : '';
         const strengthPct = Math.round(calculateStrength(e) * 100);
+        const strengthStr = showStrength ? ` (${strengthPct}%)` : '';
         const globalPrefix = item.isGlobal ? '[global] ' : '';
         const effectiveConf = confidenceFacets(e, now).tier;
         const label = confidenceLabel(e, now);
@@ -6151,21 +6464,21 @@ export function printContextMarkdown(items, totalTokens, framing = 'observe') {
             const dateStr = new Date(e.created).toISOString().slice(0, 10);
             if (effectiveConf === 'verified') {
                 // Verified: no date prefix, just the rule
-                console.log(`- **${confTag} ${globalPrefix}${e.content}**${tagStr} (${strengthPct}%)`);
+                console.log(`- **${confTag} ${globalPrefix}${e.content}**${tagStr}${strengthStr}`);
             }
             else if (effectiveConf === 'stale') {
-                console.log(`- **${confTag} Previously observed (${dateStr}): ${globalPrefix}${e.content}**${tagStr} (${strengthPct}%)`);
+                console.log(`- **${confTag} Previously observed (${dateStr}): ${globalPrefix}${e.content}**${tagStr}${strengthStr}`);
             }
             else {
-                console.log(`- **${confTag} Previously observed (${dateStr}): ${globalPrefix}${e.content}**${tagStr} (${strengthPct}%)`);
+                console.log(`- **${confTag} Previously observed (${dateStr}): ${globalPrefix}${e.content}**${tagStr}${strengthStr}`);
             }
         }
         else if (framing === 'suggest') {
-            console.log(`- **${confTag} Consider checking: ${globalPrefix}${e.content}**${tagStr} (${strengthPct}%)`);
+            console.log(`- **${confTag} Consider checking: ${globalPrefix}${e.content}**${tagStr}${strengthStr}`);
         }
         else {
             // framing === 'assert': no prefix (bare facts)
-            console.log(`- **${confTag} ${globalPrefix}${e.content}**${tagStr} (${strengthPct}%)`);
+            console.log(`- **${confTag} ${globalPrefix}${e.content}**${tagStr}${strengthStr}`);
         }
     }
 }
@@ -6304,12 +6617,12 @@ 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);
+    entry.half_life_days = deriveHalfLife(loadConfig(hippoRoot).defaultHalfLifeDays, entry);
     entry.strength = calculateStrength(entry);
     // AT1 (plan §3 containment): mechanical content from a failed command — a
     // rejection-guard refusal here must not crash the watcher. Skip silently
@@ -6348,7 +6661,9 @@ function learnFromRepo(hippoRoot, repoPath, days, label) {
         console.log(`${prefix}No fix/revert/bug commits found in the specified period.`);
         return { added: 0, skipped: 0, lowInfo: 0 };
     }
-    const parsedLessons = extractLessons(gitLog);
+    // Same patterns as MCP hippo_learn: config.gitLearnPatterns (whose default
+    // equals extractLessons' built-in list) so a custom list applies everywhere.
+    const parsedLessons = extractLessons(gitLog, loadConfig(hippoRoot).gitLearnPatterns);
     if (parsedLessons.length === 0) {
         console.log(`${prefix}No fix/revert/bug commits found in the specified period.`);
         return { added: 0, skipped: 0, lowInfo: 0 };
@@ -6392,14 +6707,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;
@@ -6418,6 +6728,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);
@@ -6912,6 +7223,12 @@ function cmdHook(args, flags) {
             if (result.installedCompactResume) {
                 console.log(`Installed hippo compact-resume SessionStart(compact) hook in ${result.target} settings`);
             }
+            if (result.installedPostCompact) {
+                console.log(`Installed hippo post-compact PostCompact hook in ${result.target} settings`);
+            }
+            if (result.installedCaptureError) {
+                console.log(`Installed hippo capture-error PostToolUseFailure hook in ${result.target} settings`);
+            }
             if (result.migratedFromStop) {
                 console.log(`Migrated legacy Stop hook → SessionEnd (was running every turn; now fires once on session exit)`);
             }
@@ -7032,6 +7349,10 @@ function cmdSetup(flags) {
             bits.push('PreCompact (pre-compact)');
         if (result.installedCompactResume)
             bits.push('SessionStart(compact) (compact-resume)');
+        if (result.installedPostCompact)
+            bits.push('PostCompact (post-compact)');
+        if (result.installedCaptureError)
+            bits.push('PostToolUseFailure (capture-error)');
         if (result.migratedFromStop)
             bits.push('migrated legacy Stop');
         if (result.migratedSplitSessionEnd)
@@ -7573,6 +7894,8 @@ const VALID_AUDIT_OPS = new Set([
     'reject_refusal', // AT1 — emitted when the rejection guard refuses a write; lockstep
     'unreject_value', // AT1 — emitted by `hippo unreject`; lockstep
     'conflict_resolve', // AT1 — emitted by resolveConflict on every resolution path; lockstep
+    'half_life_migrate', // Decay default change — emitted by migrateDefaultHalfLife; lockstep with AuditOp union
+    'dormant_restore', // Dormant memories — emitted by api.restoreDormant; lockstep with AuditOp union + server.ts VALID_AUDIT_OPS
 ]);
 function formatAuditRow(ev) {
     const target = ev.targetId ?? '-';
@@ -8298,6 +8621,23 @@ Commands:
     --global               Operate on the global store
   unreject <digest-prefix> Delete a tombstone (the only escape hatch)
     --global               Operate on the global store
+  dormant [<query>]        List faded memories sleep kept instead of deleting
+                           (on by default; "dormant": {"enabled": false} deletes instead)
+    --limit <n>            Max rows, newest first (default: 20)
+    --json                 Output as JSON
+    --global               Operate on the global store
+    dormant restore <id>   Bring a dormant memory back to active memory
+    dormant forget <id>    Delete a dormant memory permanently
+  capture-error            Store a failed tool call as an error memory (reads the Claude Code
+                           PostToolUseFailure hook payload on stdin; skips routine failures)
+  doctor                   Check the install: Node, store, schema, sleep, agent hooks
+    --json                 Machine-readable report (exit code 1 on any failure)
+  tokens                   Tokens of memory text hippo handed agents, per surface
+                           (hook, context, recall, MCP, HTTP), and what skipping
+                           unchanged hook blocks saved
+    --days <n>             Window in days (default: 30)
+    --json                 Output as JSON
+    --global               Operate on the global store
   snapshot <sub>           Persist or inspect the current active task
     snapshot save          Save active task state
       --task <task>
@@ -8425,6 +8765,8 @@ Commands:
   pre-compact              PreCompact hook: snapshot + capture the tail before compaction
     --log-file <p>         Diagnostic log path (default: ~/.hippo/logs/pre-compact.log)
   compact-resume           SessionStart(compact) hook: re-print the snapshot + session trail
+  post-compact             PostCompact hook: tell the user what pre-compact saved
+    --log-file <p>         Same log path as pre-compact (default: ~/.hippo/logs/pre-compact.log)
   codex-run [-- ...args]   Launch real Codex behind Hippo's session-end wrapper
   hook <sub> [target]      Manage framework integrations
     hook list              Show available hooks
@@ -8589,6 +8931,9 @@ Examples:
   hippo reject --value "never store my key again" --reason "secret"
   hippo rejections
   hippo unreject a1b2c3d4e5f6
+  hippo dormant "staging hostname"
+  hippo dormant restore mem_abc123
+  hippo tokens --days 7
   hippo session log --id sess_123 --task "Ship feature" --type progress --content "Build is green, next step is docs"
   hippo session latest --json
   hippo session resume
@@ -8632,25 +8977,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,
@@ -8685,6 +9021,21 @@ async function main() {
             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);
@@ -8831,16 +9182,45 @@ async function main() {
         case 'pre-compact': {
             // Bounded wait, not a TTY guard: an idle non-TTY pipe must not hang.
             const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
-            await cmdPreCompact(hippoRoot, {
+            resetHookInjection(hippoRoot, stdinText, null);
+            await cmdPreCompact(hookStoreRoot(hippoRoot), {
                 stdinText,
                 stdinTimedOut,
                 logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
             });
             break;
         }
+        case 'post-compact': {
+            // PostCompact hook: tells the user what pre-compact saved. Plain text,
+            // because Claude Code shows this hook's stdout as-is. Always exits 0.
+            const { text } = await readStdinBounded();
+            const logFlag = flags['log-file'];
+            const message = postCompactMessage(text, logFlag === true || logFlag === false || Array.isArray(logFlag) ? undefined : logFlag);
+            if (message !== null)
+                console.log(message);
+            break;
+        }
+        case 'capture-error': {
+            // PostToolUseFailure hook: every path exits 0, and nothing is created
+            // when no store exists (the hook fires in every directory).
+            const { text } = await readStdinBounded();
+            try {
+                const root = hookStoreRoot(hippoRoot);
+                const payload = (text ?? '').trim();
+                if (isInitialized(root) && payload) {
+                    // SAFETY: JSON.parse returns a JSON value by definition.
+                    captureToolFailure(root, resolveTenantId({}), JSON.parse(payload));
+                }
+            }
+            catch {
+                // A malformed payload or store error must never fail the agent's tool call.
+            }
+            break;
+        }
         case 'compact-resume': {
             const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
-            cmdCompactResume(hippoRoot, stdinText, stdinTimedOut);
+            resetHookInjection(hippoRoot, stdinText, 'compact');
+            cmdCompactResume(hookStoreRoot(hippoRoot), stdinText, stdinTimedOut);
             break;
         }
         case 'codex-run':
@@ -8876,7 +9256,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) {
@@ -8890,13 +9270,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.`);
@@ -8985,6 +9367,21 @@ async function main() {
         case 'unreject':
             cmdUnreject(hippoRoot, args, flags);
             break;
+        case 'dormant':
+            cmdDormant(hippoRoot, args, flags);
+            break;
+        case 'tokens':
+            cmdTokens(hippoRoot, flags);
+            break;
+        case 'doctor': {
+            // SAFETY: package.json always carries a string "version" (checked at release by check-manifest-versions).
+            const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', 'package.json'), 'utf-8'));
+            const report = runDoctor({ version: pkg.version });
+            console.log(flags['json'] ? JSON.stringify(report, null, 2) : formatDoctor(report));
+            if (!report.ok)
+                process.exit(1);
+            break;
+        }
         case 'snapshot':
             cmdSnapshot(hippoRoot, args, flags);
             break;
@@ -9017,6 +9414,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) {
@@ -9182,7 +9583,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 => {
@@ -9282,11 +9683,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;
         }
@@ -9380,8 +9781,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