hippo-memory 1.70.0 → 1.71.0

package/dist/cli/setup.d.ts

@@ -1,5 +1,5 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdHook(args: string[]): void;
-export declare function cmdSetup(flags: CliFlags): void;
-export declare function cmdDailyRunner(): void;
+import { type CommandContext } from './flag-values.js';
+export declare function handleHook({ args }: CommandContext): void;
+export declare function handleSetup({ flags }: CommandContext): void;
+export declare function handleDailyRunner(_ctx: CommandContext): void;
 //# sourceMappingURL=setup.d.ts.map

package/dist/cli/setup.js

@@ -9,10 +9,10 @@ import { installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPa
 import { COPILOT_CLI_MCP, VSCODE_MCP, copilotMcpSnippet, copilotPaths, installCopilot, isCopilotCliPresent, isMcpFailure, uninstallCopilot, } from '../hooks/copilot.js';
 import { isInitialized } from '../store/open.js';
 import { currentMachine, importUserMemories } from '../agent-memories/sync.js';
-import { getGlobalRoot } from '../sharing/shared.js';
+import { getGlobalRoot } from '../sharing/global-store.js';
 import { listRegisteredWorkspaces, runDailyMaintenance } from './scheduler.js';
 import { replayCompactionsAt } from '../capture/compaction-record.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorFields, errorMessage, log } from '../util/log.js';
 import { envDailyStepTimeoutMs } from '../util/env.js';
 import { writeFileAtomic } from '../util/atomic-write.js';
 import { printError } from './output.js';
@@ -22,10 +22,9 @@ import { installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable
 import { repairQualityOnceAt } from './quality-repair-once.js';
 import { HOOK_MARKERS, HOOKS, hippoBlock, withoutHookBlock } from '../hooks/hook-blocks.js';
 import { escapeRegex } from '../util/escape.js';
-// ---------------------------------------------------------------------------
+import { CliExit } from './exit.js';
 // Hook install/uninstall
-// ---------------------------------------------------------------------------
-export function cmdHook(args) {
+export function handleHook({ args }) {
     const subcommand = args[0];
     const target = args[1];
     if (subcommand === 'list')
@@ -35,7 +34,7 @@ export function cmdHook(args) {
     if (subcommand === 'uninstall')
         return hookUninstall(target);
     printError('Usage: hippo hook <install|uninstall|list> [target]');
-    process.exit(1);
+    throw new CliExit(1);
 }
 // Cursor has no init row, so the AGENTS.md block is usually another agent's, and Cursor reads that one as it is.
 function othersBlock(target, text) {
@@ -57,7 +56,7 @@ function hookInstall(target) {
     if (!target || !HOOKS[target]) {
         printError(`Unknown hook target: ${target ?? '(none)'}`);
         printError(`   Available: ${[...Object.keys(HOOKS), 'copilot'].join(', ')}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const hook = HOOKS[target];
     patchAgentFile(hook, target);
@@ -103,9 +102,8 @@ function patchAgentFile(hook, target) {
         }
     }
     else {
-        // Do not create a new agent-instructions file (CLAUDE.md, AGENTS.md, etc.) in directories that don't already have one —
-        // avoids polluting cwd with files the user didn't ask for. The settings.json hook below is still installed for
-        // claude-code, so the consolidation hook still runs.
+        // Do not create an agent-instructions file (CLAUDE.md, AGENTS.md, etc.) in directories without one, to avoid polluting cwd;
+        // the settings.json hook below is still installed for claude-code.
         console.log(`${hook.file} not found in ${process.cwd()} — skipping agent-instructions patch.`);
         console.log(`   Create ${hook.file} and re-run \`hippo hook install ${target}\` if you want the agent prompt.`);
     }
@@ -144,7 +142,7 @@ function printClaudeHookInstall(result) {
     }
 }
 function installOpencodeHook() {
-    // opencode uses a TS plugin, not JSON hooks. See src/hooks.ts.
+    // opencode uses a TS plugin, not JSON hooks. See src/hooks/opencode.ts.
     const result = installOpencodePlugin();
     if (result.installed) {
         console.log(`Installed hippo opencode plugin at ${result.pluginPath}`);
@@ -254,7 +252,7 @@ function hookUninstall(target) {
         return printCopilotUninstall(uninstallCopilot());
     if (!target || !HOOKS[target]) {
         printError(`Unknown hook target: ${target ?? '(none)'}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     unpatchAgentFile(HOOKS[target], target);
     // For Claude Code, also strip its SessionEnd/SessionStart entries.
@@ -267,9 +265,7 @@ function hookUninstall(target) {
         }
     }
     else if (target === 'opencode') {
-        // opencode uses a TS plugin; uninstall removes the plugin file AND
-        // also runs the legacy-hooks migration so the downgrade/remove path
-        // leaves opencode launchable.
+        // opencode uses a TS plugin; uninstall removes the plugin file and also runs the legacy-hooks migration, so remove leaves opencode launchable.
         if (uninstallOpencodePlugin()) {
             console.log(`Removed hippo opencode plugin (and any legacy hooks block from opencode.json)`);
         }
@@ -351,8 +347,8 @@ function setupDetectedTools(tools, forceAll, dryRun) {
     }
 }
 // `hippo setup` -- one-shot configuration for every AI coding tool on the box.
-// Detection and install logic live in ./hooks.ts.
-export function cmdSetup(flags) {
+// Detection and install logic live in src/hooks/.
+export function handleSetup({ flags }) {
     const dryRun = boolFlag(flags, 'dry-run');
     const forceAll = boolFlag(flags, 'all');
     const tools = detectInstalledTools();
@@ -389,14 +385,16 @@ function setupCopilot(dryRun) {
 function setupJsonTool(tool, dryRun) {
     if (tool.name === 'copilot')
         return setupCopilot(dryRun);
+    // SAFETY: detectInstalledTools gives kind 'json-hook' only to claude-code and copilot (hooks/shared.ts), and copilot returned above.
+    const target = tool.name;
     if (dryRun) {
         // Resolve the real settings path so the filename is right for each tool
         // (claude-code -> settings.json, opencode -> opencode.json).
-        const { settings } = resolveJsonHookPaths(tool.name);
+        const { settings } = resolveJsonHookPaths(target);
         console.log(`[dry-run] would install hooks in ${settings}`);
         return;
     }
-    const result = installJsonHooks(tool.name);
+    const result = installJsonHooks(target);
     if (warnClaudeSettingsUnusable(result, `  ${tool.name.padEnd(14)} `))
         return;
     const bits = [];
@@ -482,7 +480,7 @@ function dailyStepFailure(err, timeoutMs) {
         return `timed out after ${timeoutMs} ms and was stopped`;
     return errorMessage(err);
 }
-export function cmdDailyRunner() {
+export function handleDailyRunner(_ctx) {
     const globalRoot = getGlobalRoot();
     // No workspace sleep ever opens the global store, yet hooks in folders without a store compact into it.
     if (isInitialized(globalRoot)) {
@@ -515,7 +513,7 @@ export function cmdDailyRunner() {
         catch (err) {
             failed++;
             const action = args.join(' ');
-            log.error(`daily-runner failed in ${cwd} during \`${action}\`: ${dailyStepFailure(err, timeout)}`, { workspace: cwd });
+            log.error(`daily-runner failed in ${cwd} during \`${action}\`: ${dailyStepFailure(err, timeout)}`, { workspace: cwd, ...errorFields(err) });
         }
     });
     console.log(`Daily maintenance complete: ${processed} workspace${processed === 1 ? '' : 's'} processed, ${failed} command failure${failed === 1 ? '' : 's'}.`);

package/dist/cli/shared.d.ts

@@ -1,41 +1,27 @@
 import { type ChurnStaleResult } from '../learn/invalidation.js';
 import { type AuditOp } from '../store/audit.js';
 import { type ServerInfo } from '../server/server-detect.js';
+import type { JsonObject } from '../store/working-memory.js';
 import type { CliFlags } from './flag-values.js';
-/**
- * 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
- * — audit must never crash a CLI command.
- */
-export declare function emitCliAudit(hippoRoot: string, op: AuditOp, targetId?: string, metadata?: Record<string, unknown>): void;
+/** Emit an audit event on its own short-lived connection to `hippoRoot`'s db; swallows all errors, since audit must never crash a CLI command. */
+export declare function emitCliAudit(hippoRoot: string, op: AuditOp, targetId?: string, metadata?: JsonObject): void;
 export declare function requireInit(hippoRoot: string): void;
 /** Runs detectChurnStale against every store this repo's memories can live in. */
 export declare function runChurnStaleForRepo(hippoRoot: string, dryRun: boolean): {
     root: string;
     result: ChurnStaleResult;
 }[];
-/**
- * Run an HTTP-routed command if a `hippo serve` instance is detected for
- * `hippoRoot`. Returns:
- *   - true  if the HTTP path ran (success OR a structured server error that
- *           was already surfaced to stdout/stderr by `httpFn`),
- *   - false if no server was detected, or if the detected pidfile turned out
- *           to be stale (connection refused). On stale, the pidfile is removed
- *           if it still names that dead server (a newer one may have replaced
- *           it) and the caller should fall back to the direct path.
- *
- * Stale pidfiles must self-heal, not crash.
- * When HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
- * returning false, so a missing server fails loudly rather than silently
- * degrading to direct mode.
- */
+/** Run an HTTP-routed command if a `hippo serve` is detected: true if it ran, false on no server or a stale pidfile (removed if it names the dead server).
+ * With HIPPO_REQUIRE_SERVER set both fallbacks throw; a stale pidfile must self-heal, not crash. */
 export declare function runViaServerIfAvailable(hippoRoot: string, httpFn: (info: ServerInfo, apiKey: string | undefined) => Promise<void>): Promise<boolean>;
 /** True, after one line, on a shared store: this account's commits and agent notes are not its members' memories. */
 export declare function skipLearnOnSharedStore(hippoRoot: string): boolean;
-export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): {
+interface LearnFromRepoResult {
     added: number;
     skipped: number;
     lowInfo: number;
-};
+}
+export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): LearnFromRepoResult;
 export declare function resolveAuthRoot(hippoRoot: string, flags: CliFlags): string;
+export {};
 //# sourceMappingURL=shared.d.ts.map

package/dist/cli/shared.js

@@ -6,7 +6,7 @@ import { isSharedStore } from '../core/config.js';
 import { isInitialized } from '../store/open.js';
 import { detectChurnStale } from '../learn/invalidation.js';
 import { resolveProjectIdentity } from '../core/project-identity.js';
-import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
 import { reportAuditWriteFailure } from '../store/audit.js';
 import { sqliteSyncStore } from '../store/sqlite/store.js';
 import * as client from './client.js';
@@ -15,11 +15,7 @@ import { resolveTenantId } from '../store/tenant.js';
 import { adminActor, learn, CLI_LEARN } from '../api/index.js';
 import { errorMessage, log } from '../util/log.js';
 import { printError } from './output.js';
-/**
- * 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
- * — audit must never crash a CLI command.
- */
+/** Emit an audit event on its own short-lived connection to `hippoRoot`'s db; swallows all errors, since audit must never crash a CLI command. */
 export function emitCliAudit(hippoRoot, op, targetId, metadata) {
     try {
         sqliteSyncStore(hippoRoot).appendAuditEvents([{
@@ -59,34 +55,16 @@ export function runChurnStaleForRepo(hippoRoot, dryRun) {
         }
     });
 }
-/**
- * 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 error then. It guards only the routed writes (remember, forget, archive,
- * promote); every other command opens the store directly, knob or not.
- */
+/** With HIPPO_REQUIRE_SERVER set, throw rather than fall back to direct DB mode, which would mask a misconfiguration and discard HIPPO_API_KEY.
+ * Guards only the routed writes (remember, forget, archive, promote). */
 function failIfServerRequired(reason) {
     if (envRequireServer()) {
         throw new Error(`hippo: HIPPO_REQUIRE_SERVER is set but ${reason}. ` +
             `Start \`hippo serve\`, or unset HIPPO_REQUIRE_SERVER to allow direct-mode fallback.`);
     }
 }
-/**
- * Run an HTTP-routed command if a `hippo serve` instance is detected for
- * `hippoRoot`. Returns:
- *   - true  if the HTTP path ran (success OR a structured server error that
- *           was already surfaced to stdout/stderr by `httpFn`),
- *   - false if no server was detected, or if the detected pidfile turned out
- *           to be stale (connection refused). On stale, the pidfile is removed
- *           if it still names that dead server (a newer one may have replaced
- *           it) and the caller should fall back to the direct path.
- *
- * Stale pidfiles must self-heal, not crash.
- * When HIPPO_REQUIRE_SERVER is set, both fallback paths throw instead of
- * returning false, so a missing server fails loudly rather than silently
- * degrading to direct mode.
- */
+/** Run an HTTP-routed command if a `hippo serve` is detected: true if it ran, false on no server or a stale pidfile (removed if it names the dead server).
+ * With HIPPO_REQUIRE_SERVER set both fallbacks throw; a stale pidfile must self-heal, not crash. */
 export async function runViaServerIfAvailable(hippoRoot, httpFn) {
     const info = await detectServer(hippoRoot);
     if (!info) {
@@ -99,7 +77,7 @@ export async function runViaServerIfAvailable(hippoRoot, httpFn) {
         return true;
     }
     catch (err) {
-        const failure = client.classifyTransportFailure(err);
+        const failure = err instanceof Error ? client.classifyTransportFailure(err) : 'none';
         if (failure === 'never-sent') {
             failIfServerRequired('the server pidfile was stale (connection refused)');
             log.warn('stale server pidfile detected, falling back to direct mode');
@@ -109,9 +87,8 @@ export async function runViaServerIfAvailable(hippoRoot, httpFn) {
             return false;
         }
         if (failure === 'delivery-unknown') {
-            // Every caller of this helper is a non-idempotent write, so replaying on
-            // the direct path would store a row the server may already have committed.
-            // Leave the pidfile alone: the next command's connect-phase failure heals it.
+            // Every caller is a non-idempotent write, so replaying on the direct path would store a row the server may already have committed;
+            // leave the pidfile alone: the next command's connect-phase failure heals it.
             printError(`hippo: the connection to ${info.url} dropped or timed out mid-request, so the write may already have been applied. Not retrying locally. Check with \`hippo recall\` before running this again.`);
             process.exit(1);
         }

package/dist/cli/slack.d.ts

@@ -1,3 +1,3 @@
-import { type CliFlags } from './flag-values.js';
-export declare function cmdSlack(hippoRoot: string, args: string[], flags: CliFlags): Promise<void>;
+import { type CommandContext } from './flag-values.js';
+export declare function handleSlack({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=slack.d.ts.map

package/dist/cli/slack.js

@@ -1,7 +1,6 @@
 // `hippo slack`: backfill, dead-letter queue and workspace registry for the Slack connector.
 import { envSlackBotToken, envSlackSigningSecret, envSlackTeamId } from '../util/env.js';
 import * as api from '../api/index.js';
-import { resolveTenantId } from '../store/tenant.js';
 import { listDlq } from '../connectors/dlq.js';
 import { replayDlqEntry, slackDlq } from '../connectors/slack/dlq.js';
 import { backfillChannel } from '../connectors/slack/backfill.js';
@@ -10,30 +9,27 @@ import { addWorkspace as addSlackWorkspace, listWorkspaces as listSlackWorkspace
 import { printError } from './output.js';
 import { printSlackBackfillUsage, printSlackWorkspacesUsage } from './usage.js';
 import { stringFlag } from './flag-values.js';
-// ---------------------------------------------------------------------------
+import { CliExit } from './exit.js';
 // Slack subcommands (`hippo slack backfill` / `hippo slack dlq list`)
-// ---------------------------------------------------------------------------
-function cmdSlackBackfill(hippoRoot, flags) {
+function cmdSlackBackfill(hippoRoot, tenantId, flags) {
     const channel = stringFlag(flags, 'channel');
     if (!channel) {
         printSlackBackfillUsage();
-        process.exit(1);
+        throw new CliExit(1);
     }
     // Real fetcher requires SLACK_BOT_TOKEN with channels:history scope.
     const token = envSlackBotToken();
     if (!token) {
         printError('SLACK_BOT_TOKEN is not set. Backfill requires a Slack bot token with channels:history scope.');
-        process.exit(2);
+        throw new CliExit(2);
     }
-    // --since is advisory in V1: the slack_cursors row drives resume, so the
-    // backfill loop always picks up where it last left off. Honoured-by-cursor
-    // semantics keep idempotency clean.
+    // --since is advisory in V1: the slack_cursors row drives resume, so the backfill loop always continues where it left off (keeps idempotency clean).
     const sinceIso = stringFlag(flags, 'since');
     void sinceIso;
     const fetcher = slackHistoryFetcher(token);
     const ctx = {
         hippoRoot,
-        tenantId: resolveTenantId({}),
+        tenantId,
         actor: api.adminActor('cli:slack-backfill'),
     };
     backfillChannel(ctx, {
@@ -49,8 +45,8 @@ function cmdSlackBackfill(hippoRoot, flags) {
         process.exit(3);
     });
 }
-function cmdSlackDlqList(hippoRoot, _flags) {
-    const items = listDlq(slackDlq, hippoRoot, { tenantId: resolveTenantId({}) });
+function cmdSlackDlqList(hippoRoot, tenantId, _flags) {
+    const items = listDlq(slackDlq, hippoRoot, { tenantId });
     for (const it of items) {
         console.log(`${it.id}\t${it.receivedAt}\t${it.error}`);
     }
@@ -59,12 +55,12 @@ async function cmdSlackDlqReplay(hippoRoot, args, flags) {
     const idArg = args[2];
     if (!idArg) {
         printError('Usage: hippo slack dlq replay <id> [--force]');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const id = Number(idArg);
     if (!Number.isFinite(id) || !Number.isInteger(id) || id < 1) {
         printError(`replay: invalid id ${idArg}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     const force = flags.force === true;
     const result = await replayDlqEntry({ hippoRoot }, id, {
@@ -73,7 +69,7 @@ async function cmdSlackDlqReplay(hippoRoot, args, flags) {
     });
     if (!result.ok) {
         printError(`replay failed: status=${result.status} retry_count=${result.retryCount}${result.reason ? ` reason=${result.reason}` : ''}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`replay ok: status=${result.status} memory_id=${result.memoryId ?? '(none)'} retry_count=${result.retryCount}`);
 }
@@ -82,7 +78,7 @@ function cmdSlackWorkspacesAdd(hippoRoot, flags) {
     const tenantId = (stringFlag(flags, 'tenant') ?? '').trim();
     if (!teamId || !tenantId) {
         printError('Usage: hippo slack workspaces add --team <T> --tenant <t>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const ws = addSlackWorkspace(hippoRoot, { teamId, tenantId });
     console.log(`added: ${ws.teamId} -> ${ws.tenantId} (${ws.addedAt})`);
@@ -101,23 +97,23 @@ function cmdSlackWorkspacesRemove(hippoRoot, flags) {
     const teamId = (stringFlag(flags, 'team') ?? '').trim();
     if (!teamId) {
         printError('Usage: hippo slack workspaces remove --team <T>');
-        process.exit(1);
+        throw new CliExit(1);
     }
     const removed = removeSlackWorkspace(hippoRoot, teamId);
     if (!removed) {
         printError(`no workspace registered for team ${teamId}`);
-        process.exit(1);
+        throw new CliExit(1);
     }
     console.log(`removed: ${teamId}`);
 }
-export async function cmdSlack(hippoRoot, args, flags) {
+export async function handleSlack({ hippoRoot, tenantId, args, flags }) {
     const sub = args[0];
     if (sub === 'backfill') {
-        cmdSlackBackfill(hippoRoot, flags);
+        cmdSlackBackfill(hippoRoot, tenantId, flags);
         return;
     }
     if (sub === 'dlq' && args[1] === 'list') {
-        cmdSlackDlqList(hippoRoot, flags);
+        cmdSlackDlqList(hippoRoot, tenantId, flags);
         return;
     }
     if (sub === 'dlq' && args[1] === 'replay') {
@@ -139,9 +135,9 @@ export async function cmdSlack(hippoRoot, args, flags) {
             return;
         }
         printSlackWorkspacesUsage();
-        process.exit(1);
+        throw new CliExit(1);
     }
     printError('Usage: hippo slack <backfill|dlq list|dlq replay <id> [--force]|workspaces add|workspaces list|workspaces remove> [...]');
-    process.exit(1);
+    throw new CliExit(1);
 }
 //# sourceMappingURL=slack.js.map

package/dist/cli/sleep.d.ts

@@ -1,4 +1,5 @@
-import { type CliFlags } from './flag-values.js';
+import { type CliFlags, type CommandContext } from './flag-values.js';
 /** Runs `hippo sleep`; with `--log-file` it also tees its output to that file. */
-export declare function cmdSleep(hippoRoot: string, flags: CliFlags): Promise<void>;
+export declare function cmdSleep(hippoRoot: string, tenantId: string, flags: CliFlags): Promise<void>;
+export declare function handleSleep({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=sleep.d.ts.map

package/dist/cli/sleep.js

@@ -6,7 +6,7 @@ import { isGitRepo } from '../learn/autolearn.js';
 import { importForStore, currentMachine } from '../agent-memories/sync.js';
 import { replayCompactionsAt } from '../capture/compaction-record.js';
 import * as api from '../api/index.js';
-import { resolveTenantId } from '../store/tenant.js';
+import { cliApiContext } from './api-context.js';
 import { sleepResultLines } from './sleep-render.js';
 import { errorMessage, log } from '../util/log.js';
 import { closeHippoDb, openHippoDb } from '../db/index.js';
@@ -17,10 +17,8 @@ import { printAgentImport } from './print.js';
 import { repairQualityOnceAt } from './quality-repair-once.js';
 import { printError } from './output.js';
 /** Runs `hippo sleep`; with `--log-file` it also tees its output to that file. */
-export async function cmdSleep(hippoRoot, flags) {
-    // Tee stdout/stderr to a log file when --log-file is set. The SessionEnd
-    // hook uses this so the output is captured somewhere the SessionStart hook
-    // can re-display it next time the agent UI starts.
+export async function cmdSleep(hippoRoot, tenantId, flags) {
+    // Tee stdout/stderr to a log file when --log-file is set; the SessionEnd hook uses it so the SessionStart hook can re-display the output.
     const logFile = stringFlag(flags, 'log-file') ?? null;
     let restoreStdout = null;
     if (logFile) {
@@ -31,17 +29,19 @@ export async function cmdSleep(hippoRoot, flags) {
             const origStderrWrite = process.stderr.write.bind(process.stderr);
             const tee = (chunk) => {
                 try {
-                    const buf = typeof chunk === 'string' ? chunk : Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+                    const buf = Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
                     fs.appendFileSync(logFile, buf, 'utf8');
                 }
                 catch {
                     // log failures are non-fatal — still write to the real stream
                 }
             };
+            // SAFETY: the wrapper forwards chunk, enc and cb untouched to the original write, so it keeps write's contract.
             process.stdout.write = ((chunk, enc, cb) => {
                 tee(chunk);
                 return origStdoutWrite(chunk, enc, cb);
             });
+            // SAFETY: the wrapper forwards chunk, enc and cb untouched to the original write, so it keeps write's contract.
             process.stderr.write = ((chunk, enc, cb) => {
                 tee(chunk);
                 return origStderrWrite(chunk, enc, cb);
@@ -56,7 +56,7 @@ export async function cmdSleep(hippoRoot, flags) {
         }
     }
     try {
-        await cmdSleepCore(hippoRoot, flags);
+        await cmdSleepCore(hippoRoot, tenantId, flags);
         if (logFile)
             console.log('[hippo] sleep complete');
     }
@@ -70,16 +70,19 @@ export async function cmdSleep(hippoRoot, flags) {
             restoreStdout();
     }
 }
+export function handleSleep({ hippoRoot, tenantId, flags }) {
+    return cmdSleep(hippoRoot, tenantId, flags);
+}
 function renderSleepResult(result) {
     for (const line of sleepResultLines(result))
         console.log(line);
 }
 /** Fault-isolated: a failed repair warns and runs again next sleep, and never stops the sleep. */
-function repairProjectTagsOnce(hippoRoot) {
+function repairProjectTagsOnce(hippoRoot, tenantId) {
     let db;
     try {
         db = openHippoDb(hippoRoot);
-        const r = repairOnceOnSleep(db, hippoRoot, resolveTenantId({}));
+        const r = repairOnceOnSleep(db, hippoRoot, tenantId);
         if (r === null)
             return;
         const parts = [
@@ -97,7 +100,7 @@ function repairProjectTagsOnce(hippoRoot) {
             closeHippoDb(db);
     }
 }
-async function cmdSleepCore(hippoRoot, flags) {
+async function cmdSleepCore(hippoRoot, tenantId, flags) {
     requireInit(hippoRoot);
     // Phase 1: Auto-learn from git and every coding agent's own memories (CLI-only, uses process.cwd() / os.homedir()).
     // Stays in cli.ts; api.sleep covers Phase 2-6 only.
@@ -128,15 +131,11 @@ async function cmdSleepCore(hippoRoot, flags) {
         const finished = replayCompactionsAt(hippoRoot, (message) => log.warn(`compaction replay: ${message}`));
         if (finished > 0)
             console.log(`Finished saving ${finished} compaction${finished === 1 ? '' : 's'} left over from earlier sessions.`);
-        repairProjectTagsOnce(hippoRoot);
+        repairProjectTagsOnce(hippoRoot, tenantId);
         repairQualityOnceAt(hippoRoot);
     }
     // Phase 2-6: Pure-storage pipeline (consolidate + dedup + audit + share + ambient).
-    const ctx = {
-        hippoRoot,
-        tenantId: resolveTenantId({}),
-        actor: api.adminActor('cli'),
-    };
+    const ctx = cliApiContext(hippoRoot, tenantId);
     const result = await api.sleep(ctx, {
         dryRun: boolFlag(flags, 'dry-run'),
         noShare: boolFlag(flags, 'no-share'),

package/dist/cli/status.d.ts

@@ -1,18 +1,15 @@
-import { type CliFlags, type CommandContext } from './flag-values.js';
-export declare function cmdStatus(hippoRoot: string): void;
-/**
- * `hippo tokens [--days <n>] [--json] [--global]`: the token ledger.
- * Tokens of memory text handed to agents per surface, blocks
- * the per-prompt hook skipped as unchanged and the tokens that saved,
- * and the hook blocks' tokens later model calls re-read, counted when each session ends.
- * Counts are estimates (characters / 4), the same estimate every budget uses.
- */
-export declare function cmdTokens(hippoRoot: string, flags: CliFlags): void;
+import { type PhysicsParticle } from '../core/physics.js';
+import { type CommandContext } from './flag-values.js';
+export declare function handleStatus({ hippoRoot }: CommandContext): void;
+export declare function physicsEnergyText(particles: PhysicsParticle[], gMemory: number): string;
+/** `hippo tokens [--days <n>] [--json] [--global]`: the token ledger per surface, tokens saved by skipped unchanged blocks, and re-read hook tokens.
+ * Counts are estimates (characters / 4), the same estimate every budget uses. */
+export declare function handleTokens({ hippoRoot, tenantId, flags }: CommandContext): void;
 /** `hippo failures [--days <n>] [--json] [--global]`: failed tool calls by outcome, and repeats across sessions. */
-export declare function cmdFailures(hippoRoot: string, flags: CliFlags): void;
+export declare function handleFailures({ hippoRoot, tenantId, flags }: CommandContext): void;
 export declare function handleCorrectionLatency({ hippoRoot, flags }: CommandContext): void;
 export declare function handleProvenance({ hippoRoot, flags }: CommandContext): void;
 export declare function handleDoctor({ flags }: CommandContext): void;
 export declare function handleSupportBundle({ flags }: CommandContext): void;
-export declare function handleInspect({ hippoRoot, args }: CommandContext): void;
+export declare function handleInspect({ hippoRoot, tenantId, args }: CommandContext): Promise<void>;
 //# sourceMappingURL=status.d.ts.map