hippo-memory 1.69.0 → 1.70.0

package/dist/cli/init.js

@@ -1,21 +1,25 @@
 // `hippo init`: create a store and wire the detected agents' instruction files, hooks and daily runner.
-import { envSkipAutoIntegrations } from '../env.js';
+import { envSkipAutoIntegrations } from '../util/env.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import * as os from 'os';
 import { installJsonHooks } from '../hooks/json-hooks.js';
+import { writeFileAtomic } from '../util/atomic-write.js';
 import { isCodexPresent } from '../hooks/shared.js';
 import { isCodexWrapperInstalled } from '../hooks/codex-wrapper.js';
 import { installOpencodePlugin } from '../hooks/opencode.js';
 import { isInitialized, initStore } from '../store/open.js';
 import { loadAllEntries } from '../store/entry-reads.js';
-import { isGitRepo } from '../autolearn.js';
+import { isGitRepo } from '../learn/autolearn.js';
 import { currentMachine, importForStore, importProjectMemories, importUserMemories } from '../agent-memories/sync.js';
 import { emptyReport, mergeReports } from '../agent-memories/report.js';
-import { getGlobalRoot, initGlobal } from '../shared.js';
-import { registerWorkspace } from '../scheduler.js';
-import { printAgentImport, installCodexMemoryHooks, setupDailySchedule, learnFromRepo, skipLearnOnSharedStore, warnClaudeSettingsUnusable } from './shared.js';
-import { HOOK_MARKERS, HOOKS, hippoBlock } from './hook-blocks.js';
+import { getGlobalRoot, initGlobal } from '../sharing/shared.js';
+import { registerWorkspace } from './scheduler.js';
+import { stringFlag } from './flag-values.js';
+import { printAgentImport } from './print.js';
+import { installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable } from './install-steps.js';
+import { learnFromRepo, skipLearnOnSharedStore } from './shared.js';
+import { HOOK_MARKERS, HOOKS, hippoBlock } from '../hooks/hook-blocks.js';
 function scanForGitRepos(rootDir, maxDepth = 2) {
     const repos = [];
     function walk(dir, depth) {
@@ -44,6 +48,51 @@ function scanForGitRepos(rootDir, maxDepth = 2) {
     walk(rootDir, 0);
     return repos;
 }
+/** Creates the repo's store when absent and registers it; returns whether it already existed. */
+function initScannedRepo(repo, globalRoot) {
+    const repoHippo = path.join(repo, '.hippo');
+    const alreadyExists = isInitialized(repoHippo);
+    if (!alreadyExists) {
+        initStore(repoHippo);
+    }
+    registerWorkspace(globalRoot, repo);
+    return alreadyExists;
+}
+/** Seeds one scanned repo from git history and its agents' notes, unless --no-learn. */
+function learnScannedRepo(repo, seedDays, learn, machine, agentImport) {
+    const repoHippo = path.join(repo, '.hippo');
+    let added = 0;
+    let lowInfo = 0;
+    if (learn && isGitRepo(repo)) {
+        const result = learnFromRepo(repoHippo, repo, seedDays, path.basename(repo));
+        added = result.added;
+        lowInfo = result.lowInfo;
+    }
+    if (learn)
+        mergeReports(agentImport, importProjectMemories(repoHippo, { machine }));
+    return { added, lowInfo };
+}
+function installScanHooks(repos) {
+    // User-level hooks only: a hippo block in each repo's CLAUDE.md or AGENTS.md would leave a diff in every repo.
+    const agents = detectAgentHooks(repos);
+    if (agents.length === 0) {
+        console.log('   No agent config found in these repositories. Run `hippo setup` to add hooks for the agents on this machine.');
+    }
+    installUserLevelHooks(agents, true);
+}
+function initGlobalFirst() {
+    const globalRoot = getGlobalRoot();
+    if (!isInitialized(globalRoot)) {
+        initGlobal();
+        console.log(`Initialized global store at ${globalRoot}\n`);
+    }
+    return globalRoot;
+}
+function printScanSummary(repoCount, totalLessons, totalLowInfo) {
+    console.log(`\n${repoCount} repositories, ${totalLessons} new lessons learned` +
+        (totalLowInfo > 0 ? `, ${totalLowInfo} low-information subject(s) dropped` : '') +
+        '.');
+}
 function cmdInitScan(scanDir, flags) {
     const resolved = path.resolve(scanDir);
     console.log(`Scanning ${resolved} for git repositories...\n`);
@@ -53,12 +102,7 @@ function cmdInitScan(scanDir, flags) {
         return;
     }
     console.log(`Found ${repos.length} repositories:\n`);
-    // Init global store first
-    const globalRoot = getGlobalRoot();
-    if (!isInitialized(globalRoot)) {
-        initGlobal();
-        console.log(`Initialized global store at ${globalRoot}\n`);
-    }
+    const globalRoot = initGlobalFirst();
     let totalLessons = 0;
     // Rolled up so the cross-repo summary reports the gate too. Each repo
     // already prints its own count inside learnFromRepo, but the aggregate
@@ -68,67 +112,63 @@ function cmdInitScan(scanDir, flags) {
     const seedDays = parseInt(String(flags['days'] ?? '365'), 10);
     const machine = currentMachine();
     const agentImport = emptyReport();
+    const learn = !flags['no-learn'];
     for (const repo of repos) {
-        const name = path.basename(repo);
-        const repoHippo = path.join(repo, '.hippo');
-        const alreadyExists = isInitialized(repoHippo);
-        if (!alreadyExists) {
-            initStore(repoHippo);
-        }
-        registerWorkspace(globalRoot, repo);
-        // Learn from git history
-        let added = 0;
-        if (!flags['no-learn'] && isGitRepo(repo)) {
-            const result = learnFromRepo(repoHippo, repo, seedDays, name);
-            added = result.added;
-            totalLessons += added;
-            totalLowInfo += result.lowInfo;
-        }
-        if (!flags['no-learn'])
-            mergeReports(agentImport, importProjectMemories(repoHippo, { machine }));
+        const alreadyExists = initScannedRepo(repo, globalRoot);
+        const { added, lowInfo } = learnScannedRepo(repo, seedDays, learn, machine, agentImport);
+        totalLessons += added;
+        totalLowInfo += lowInfo;
         const status = alreadyExists ? 'existing' : 'new';
-        const entries = loadAllEntries(repoHippo);
-        console.log(`  ${name.padEnd(25)} ${status.padEnd(10)} ${entries.length} memories${added > 0 ? ` (+${added} from git)` : ''}`);
+        const entries = loadAllEntries(path.join(repo, '.hippo'));
+        console.log(`  ${path.basename(repo).padEnd(25)} ${status.padEnd(10)} ${entries.length} memories${added > 0 ? ` (+${added} from git)` : ''}`);
     }
-    console.log(`\n${repos.length} repositories, ${totalLessons} new lessons learned` +
-        (totalLowInfo > 0 ? `, ${totalLowInfo} low-information subject(s) dropped` : '') +
-        '.');
-    if (!flags['no-learn']) {
+    printScanSummary(repos.length, totalLessons, totalLowInfo);
+    if (learn) {
         mergeReports(agentImport, importUserMemories(globalRoot, { machine }));
         printAgentImport(agentImport, '');
     }
     console.log(`Global store: ${globalRoot}`);
-    if (initInstallsIntegrations(flags)) {
-        // User-level hooks only: a hippo block in each repo's CLAUDE.md or AGENTS.md would leave a diff in every repo.
-        const agents = detectAgentHooks(repos);
-        if (agents.length === 0) {
-            console.log('   No agent config found in these repositories. Run `hippo setup` to add hooks for the agents on this machine.');
-        }
-        installUserLevelHooks(agents, true);
-    }
+    if (initInstallsIntegrations(flags))
+        installScanHooks(repos);
     if (!flags['no-schedule']) {
         setupDailySchedule(globalRoot);
     }
     console.log(`\nRun \`hippo sleep\` in any project to consolidate and auto-share to global.`);
 }
+function initGlobalOnly(flags) {
+    const globalRoot = getGlobalRoot();
+    if (isInitialized(globalRoot)) {
+        console.log('Already initialized global store at', globalRoot);
+    }
+    else {
+        initGlobal();
+        console.log('Initialized global Hippo store at', globalRoot);
+    }
+    if (!flags['no-learn'])
+        printAgentImport(importUserMemories(globalRoot, { machine: currentMachine() }));
+}
+function seedFromGitHistory(hippoRoot) {
+    if (!isGitRepo(process.cwd()))
+        return;
+    const seedDays = 30;
+    console.log(`\n   Seeding memories from last ${seedDays} days of git history...`);
+    const { added, skipped } = learnFromRepo(hippoRoot, process.cwd(), seedDays);
+    if (added > 0) {
+        console.log(`   Learned ${added} lessons from git (${skipped} duplicates skipped).`);
+    }
+    else {
+        console.log(`   No matching commits found in git history.`);
+    }
+}
 export function cmdInit(hippoRoot, flags) {
     // Handle --scan mode
     if (flags['scan']) {
-        const scanDir = typeof flags['scan'] === 'string' ? flags['scan'] : os.homedir();
+        const scanDir = stringFlag(flags, 'scan') ?? os.homedir();
         cmdInitScan(scanDir, flags);
         return;
     }
     if (flags['global']) {
-        const globalRoot = getGlobalRoot();
-        if (isInitialized(globalRoot)) {
-            console.log('Already initialized global store at', globalRoot);
-        }
-        else {
-            initGlobal();
-            console.log('Initialized global Hippo store at', globalRoot);
-        }
-        if (!flags['no-learn'])
-            printAgentImport(importUserMemories(globalRoot, { machine: currentMachine() }));
+        initGlobalOnly(flags);
         return;
     }
     const alreadyExists = isInitialized(hippoRoot);
@@ -152,19 +192,8 @@ export function cmdInit(hippoRoot, flags) {
     }
     const learn = !flags['no-learn'] && !skipLearnOnSharedStore(hippoRoot);
     // Seed with git history on first init (unless --no-learn)
-    if (!alreadyExists && learn && !flags['global']) {
-        if (isGitRepo(process.cwd())) {
-            const seedDays = 30;
-            console.log(`\n   Seeding memories from last ${seedDays} days of git history...`);
-            const { added, skipped } = learnFromRepo(hippoRoot, process.cwd(), seedDays);
-            if (added > 0) {
-                console.log(`   Learned ${added} lessons from git (${skipped} duplicates skipped).`);
-            }
-            else {
-                console.log(`   No matching commits found in git history.`);
-            }
-        }
-    }
+    if (!alreadyExists && learn && !flags['global'])
+        seedFromGitHistory(hippoRoot);
     // Every run, not only the first: an agent's notes change between inits.
     if (learn)
         printAgentImport(importForStore(hippoRoot, { machine: currentMachine() }));
@@ -222,7 +251,7 @@ function patchInstructionFiles(dir, agents) {
         }
         const block = `${HOOK_MARKERS.start}\n${hookDef.content}\n${HOOK_MARKERS.end}`;
         const sep = existing.endsWith('\n') ? '\n' : '\n\n';
-        fs.writeFileSync(targetPath, existing + sep + block + '\n', 'utf8');
+        writeFileAtomic(targetPath, existing + sep + block + '\n');
         console.log(`   Auto-installed ${hook} hook in ${hookDef.file}`);
     }
 }
@@ -237,9 +266,58 @@ function refreshShippedBlock(filePath, text, hook) {
         console.log(`   Left the edited hippo block in ${name} as is; \`hippo hook install ${hook}\` replaces it.`);
         return;
     }
-    fs.writeFileSync(filePath, `${text.slice(0, start)}${eol}${HOOKS[owner].content.replace(/\n/g, eol)}${eol}${text.slice(end)}`, 'utf8');
+    writeFileAtomic(filePath, `${text.slice(0, start)}${eol}${HOOKS[owner].content.replace(/\n/g, eol)}${eol}${text.slice(end)}`);
     console.log(`   Refreshed the ${owner} hippo block in ${name}`);
 }
+function installClaudeCodeSettingsHooks(hook) {
+    const result = installJsonHooks(hook);
+    warnClaudeSettingsUnusable(result, '   ');
+    if (result.installedSessionEnd) {
+        console.log(`   Auto-installed hippo session-end SessionEnd hook in ${hook} settings`);
+    }
+    if (result.installedSessionStart) {
+        console.log(`   Auto-installed hippo last-sleep SessionStart hook in ${hook} settings`);
+    }
+    if (result.installedUserPromptSubmit) {
+        console.log(`   Auto-installed hippo pinned-inject UserPromptSubmit hook in ${hook} settings`);
+    }
+    if (result.installedPreCompact) {
+        console.log(`   Auto-installed hippo pre-compact PreCompact hook in ${hook} settings`);
+    }
+    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)`);
+    }
+    if (result.migratedSplitSessionEnd) {
+        console.log(`   Migrated split sleep+capture SessionEnd entries → single detached hippo session-end`);
+    }
+    else if (result.migratedLegacySessionEnd) {
+        console.log(`   Migrated legacy SessionEnd entry to the new detached form`);
+    }
+}
+function installOpencodeUserPlugin() {
+    // opencode uses a TS plugin, not Claude Code's JSON-hook schema.
+    // See OPENCODE_PLUGIN_SOURCE in src/hooks.ts for the plugin file
+    // content + design rationale.
+    const result = installOpencodePlugin();
+    if (result.installed) {
+        console.log(`   Auto-installed hippo opencode plugin -> ${result.pluginPath}`);
+    }
+    if (result.migratedLegacyHooks) {
+        console.log(`   Removed legacy Claude Code-style hooks block from opencode.json — opencode can now launch`);
+    }
+    if (result.jsonRepairFailed) {
+        console.log(`   WARNING: opencode.json is unparseable; legacy hooks block could not be auto-removed. Fix the file manually.`);
+    }
+}
 /** Claude Code settings hooks, Codex's hooks.json and the OpenCode plugin, under the home directory; idempotent, so re-running init adds newer hooks. */
 function installUserLevelHooks(agents, codexHint) {
     for (const hook of agents) {
@@ -253,55 +331,10 @@ function installUserLevelHooks(agents, codexHint) {
         // For Claude Code, also install SessionEnd+SessionStart entries in its
         // settings.json. Keeps `hippo init` in lockstep with `hippo hook install
         // claude-code` and `hippo setup`.
-        if (hook === 'claude-code') {
-            const result = installJsonHooks(hook);
-            warnClaudeSettingsUnusable(result, '   ');
-            if (result.installedSessionEnd) {
-                console.log(`   Auto-installed hippo session-end SessionEnd hook in ${hook} settings`);
-            }
-            if (result.installedSessionStart) {
-                console.log(`   Auto-installed hippo last-sleep SessionStart hook in ${hook} settings`);
-            }
-            if (result.installedUserPromptSubmit) {
-                console.log(`   Auto-installed hippo pinned-inject UserPromptSubmit hook in ${hook} settings`);
-            }
-            if (result.installedPreCompact) {
-                console.log(`   Auto-installed hippo pre-compact PreCompact hook in ${hook} settings`);
-            }
-            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)`);
-            }
-            if (result.migratedSplitSessionEnd) {
-                console.log(`   Migrated split sleep+capture SessionEnd entries → single detached hippo session-end`);
-            }
-            else if (result.migratedLegacySessionEnd) {
-                console.log(`   Migrated legacy SessionEnd entry to the new detached form`);
-            }
-        }
-        else if (hook === 'opencode') {
-            // opencode uses a TS plugin, not Claude Code's JSON-hook schema.
-            // See OPENCODE_PLUGIN_SOURCE in src/hooks.ts for the plugin file
-            // content + design rationale.
-            const result = installOpencodePlugin();
-            if (result.installed) {
-                console.log(`   Auto-installed hippo opencode plugin -> ${result.pluginPath}`);
-            }
-            if (result.migratedLegacyHooks) {
-                console.log(`   Removed legacy Claude Code-style hooks block from opencode.json — opencode can now launch`);
-            }
-            if (result.jsonRepairFailed) {
-                console.log(`   WARNING: opencode.json is unparseable; legacy hooks block could not be auto-removed. Fix the file manually.`);
-            }
-        }
+        if (hook === 'claude-code')
+            installClaudeCodeSettingsHooks(hook);
+        else if (hook === 'opencode')
+            installOpencodeUserPlugin();
     }
 }
 //# sourceMappingURL=init.js.map

package/dist/cli/install-steps.d.ts

@@ -0,0 +1,7 @@
+import { type InstallResult } from '../hooks/json-hooks.js';
+/** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
+export declare function installCodexMemoryHooks(indent: string): void;
+/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was left unchanged; true when it printed. */
+export declare function warnClaudeSettingsUnusable(result: Pick<InstallResult, 'settingsPath' | 'invalidJson'>, indent: string, action?: 'install' | 'uninstall'): boolean;
+export declare function setupDailySchedule(globalRoot: string): void;
+//# sourceMappingURL=install-steps.d.ts.map

package/dist/cli/install-steps.js

@@ -0,0 +1,110 @@
+// The init and setup steps that touch the machine: Codex hooks, the settings.json warning and the daily schedule.
+import * as path from 'path';
+import { execFileSync, execSync } from 'child_process';
+import { installJsonHooks } from '../hooks/json-hooks.js';
+import { CODEX_TRUST_LINE } from '../hooks/shared.js';
+import { DAILY_TASK_NAME, buildDailyRunnerCommand, buildSchtasksCreateArgs, buildWindowsTaskRun, quoteInsideWindowsArg } from './scheduler.js';
+/** Adds hippo's two Codex hooks and says what changed; each install ends on the trust reminder, since Codex skips an untrusted hook. */
+export function installCodexMemoryHooks(indent) {
+    const result = installJsonHooks('codex');
+    if (result.invalidJson) {
+        console.log(`${indent}WARNING: ${result.settingsPath} is not a hooks file hippo can merge into; fix it, then run \`hippo hook install codex\`.`);
+        return;
+    }
+    const added = [
+        result.installedUserPromptSubmit ? 'UserPromptSubmit' : '',
+        result.installedCompactResume ? 'SessionStart(compact)' : '',
+    ].filter(Boolean);
+    console.log(added.length > 0
+        ? `${indent}Installed hippo's Codex memory hooks (${added.join(', ')}) in ${result.settingsPath}`
+        : `${indent}hippo's Codex memory hooks already in ${result.settingsPath}`);
+    console.log(`${indent}${CODEX_TRUST_LINE}`);
+}
+/** The one line init, hook install, hook uninstall and setup print when Claude Code's settings.json is not JSON hippo can edit and so was left unchanged; true when it printed. */
+export function warnClaudeSettingsUnusable(result, indent, action = 'install') {
+    if (!result.invalidJson)
+        return false;
+    console.log(`${indent}WARNING: ${result.settingsPath} is not a JSON object hippo can merge into, so it was left unchanged; fix it, then run \`hippo hook ${action} claude-code\`.`);
+    return true;
+}
+/**
+ * Set up a machine-level daily runner that sweeps all registered Hippo
+ * workspaces.
+ * Linux/macOS: writes to user crontab.
+ * Windows: creates a scheduled task.
+ * Skips if already installed.
+ */
+/** Bound on each schtasks and crontab call, so a scheduler that never answers cannot hang `hippo init` or `hippo setup`. */
+const SCHEDULER_CALL_TIMEOUT_MS = 30_000;
+/** Node kills a child at its timeout and reports ETIMEDOUT; every other failure here means the scheduler refused or is missing. */
+function schedulerTimedOut(err) {
+    return err instanceof Error && 'code' in err && err.code === 'ETIMEDOUT';
+}
+function warnSchedulerTimedOut(command) {
+    console.log(`   ${command} did not answer within ${SCHEDULER_CALL_TIMEOUT_MS / 1000} s and was stopped, so the daily runner is not scheduled.`);
+}
+export function setupDailySchedule(globalRoot) {
+    const runnerDir = path.resolve(globalRoot);
+    // Reject paths with characters that could break shell/crontab quoting
+    // (backslash is normal on Windows, only dangerous in Unix shell/crontab)
+    const unsafeChars = process.platform === 'win32' ? /["`$%\n\r]/ : /["`$\n\r\\]/;
+    if (unsafeChars.test(runnerDir)) {
+        console.log(`   Skipping schedule: runner path contains unsafe characters.`);
+        return;
+    }
+    const isWindows = process.platform === 'win32';
+    const taskName = DAILY_TASK_NAME;
+    const cmd = buildDailyRunnerCommand(runnerDir);
+    if (isWindows)
+        scheduleOnWindows(taskName, cmd);
+    else
+        scheduleOnCrontab(taskName, cmd);
+}
+function scheduleOnWindows(taskName, cmd) {
+    // Check if task already exists
+    try {
+        const existing = execSync(`schtasks /query /tn "${taskName}" 2>nul`, { encoding: 'utf-8', windowsHide: true, timeout: SCHEDULER_CALL_TIMEOUT_MS });
+        if (existing.includes(taskName)) {
+            return; // already scheduled
+        }
+    }
+    catch (err) {
+        // A non-zero exit means the task does not exist yet, so it is created below.
+        if (schedulerTimedOut(err))
+            warnSchedulerTimedOut('schtasks /query');
+    }
+    try {
+        execFileSync('schtasks', buildSchtasksCreateArgs(taskName, cmd), { stdio: 'pipe', windowsHide: true, timeout: SCHEDULER_CALL_TIMEOUT_MS });
+        console.log(`   Scheduled machine-level daily runner (6:15am) via Task Scheduler: ${taskName}`);
+    }
+    catch (err) {
+        if (schedulerTimedOut(err))
+            warnSchedulerTimedOut('schtasks /create');
+        // No admin rights or schtasks unavailable, fall back to printing instructions
+        console.log(`   To schedule the machine-level daily runner, run:`);
+        console.log(`   schtasks /create /tn "${taskName}" /tr "${quoteInsideWindowsArg(buildWindowsTaskRun(cmd))}" /sc daily /st 06:15`);
+    }
+}
+function scheduleOnCrontab(taskName, cmd) {
+    // Unix: check crontab for existing entry
+    const marker = `# hippo:${taskName}`;
+    try {
+        const existing = execSync('crontab -l 2>/dev/null', { encoding: 'utf-8', windowsHide: true, timeout: SCHEDULER_CALL_TIMEOUT_MS });
+        if (existing.includes(marker)) {
+            return; // already scheduled
+        }
+        const cronLine = `15 6 * * * ${cmd} ${marker}`;
+        const newCrontab = existing.trimEnd() + '\n' + cronLine + '\n';
+        execSync('crontab -', { input: newCrontab, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true, timeout: SCHEDULER_CALL_TIMEOUT_MS });
+        console.log(`   Scheduled machine-level daily runner (6:15am) via crontab`);
+    }
+    catch (err) {
+        if (schedulerTimedOut(err))
+            warnSchedulerTimedOut('crontab');
+        // No crontab or no permission: print the line for the user to add by hand.
+        const cronLine = `15 6 * * * ${cmd}`;
+        console.log(`   To schedule the machine-level daily runner, add to crontab (crontab -e):`);
+        console.log(`   ${cronLine}`);
+    }
+}
+//# sourceMappingURL=install-steps.js.map

package/dist/cli/last-sleep.d.ts

@@ -1,6 +1,7 @@
+import { type CliFlags } from './flag-values.js';
 /** The line the user sees when the last sleep failed, a spool step hit an unexpected error, or the spool holds `.bad` files; null when none did. */
 export declare function sleepProblems(logText: string, bad: number): string | null;
 /** Prints the SessionEnd sleep log on stderr, then clears it. In a hook, stdout carries only `systemMessage`,
  *  because Claude Code shows that to the user and adds any other SessionStart stdout to the model's context. */
-export declare function cmdLastSleep(hippoRoot: string, flags: Record<string, string | boolean | string[]>, out?: 'hook' | 'terminal'): void;
+export declare function cmdLastSleep(hippoRoot: string, flags: CliFlags, out?: 'hook' | 'terminal'): void;
 //# sourceMappingURL=last-sleep.d.ts.map

package/dist/cli/last-sleep.js

@@ -1,13 +1,13 @@
 // `hippo last-sleep`: the previous session's sleep log for the debug log, and one problems line for the user.
 import * as fs from 'fs';
-import { isStringValue } from '../capture-contract.js';
-import { REPLAY_AFTER_MS } from '../compaction-record.js';
-import { SPOOL_PROBLEM, spoolCounts } from '../compaction-spool.js';
+import { isStringValue } from '../core/capture-contract.js';
+import { REPLAY_AFTER_MS } from '../capture/compaction-record.js';
+import { SPOOL_PROBLEM, spoolCounts } from '../capture/compaction-spool.js';
 import { defaultSleepLogPath } from '../hooks/shared.js';
-import { errorMessage } from '../log.js';
-import { truncateCodePointSafe } from '../transcript-tail.js';
+import { errorMessage, log } from '../util/log.js';
+import { truncateCodePointSafe } from '../util/transcript-tail.js';
 import { printError } from './output.js';
-import { hookStoreRoot } from './shared.js';
+import { hookStoreRoot } from './hook-runtime.js';
 const SLEEP_FAILED = '[hippo] sleep failed: ';
 const FAILURE_CHARS = 120;
 /** The line the user sees when the last sleep failed, a spool step hit an unexpected error, or the spool holds `.bad` files; null when none did. */
@@ -62,7 +62,9 @@ export function cmdLastSleep(hippoRoot, flags, out = process.stdout.isTTY ? 'ter
         try {
             fs.unlinkSync(logPath);
         }
-        catch { /* non-fatal */ }
+        catch (err) {
+            log.debug(`last-sleep log not removed, it shows again next session: ${errorMessage(err)}`);
+        }
     }
 }
 //# sourceMappingURL=last-sleep.js.map

package/dist/cli/maintenance.d.ts

@@ -1,5 +1,6 @@
-import { type EmbeddingProvider } from '../embedding-provider.js';
-export declare function cmdRefine(hippoRoot: string, flags: Record<string, string | boolean | string[]>): Promise<void>;
-export declare function cmdDedup(hippoRoot: string, flags: Record<string, string | boolean | string[]>): void;
-export declare function cmdEmbed(hippoRoot: string, flags: Record<string, string | boolean | string[]>, given?: EmbeddingProvider): Promise<void>;
+import { type EmbeddingProvider } from '../store/embeddings/provider.js';
+import { type CliFlags } from './flag-values.js';
+export declare function cmdRefine(hippoRoot: string, flags: CliFlags): Promise<void>;
+export declare function cmdDedup(hippoRoot: string, flags: CliFlags): void;
+export declare function cmdEmbed(hippoRoot: string, flags: CliFlags, given?: EmbeddingProvider): Promise<void>;
 //# sourceMappingURL=maintenance.d.ts.map

package/dist/cli/maintenance.js

@@ -1,16 +1,20 @@
 // Store upkeep verbs: `hippo refine`, `hippo dedup` and `hippo embed`.
-import { envAnthropicApiKey } from '../env.js';
+import { envAnthropicApiKey } from '../util/env.js';
 import { loadAllEntries } from '../store/entry-reads.js';
-import { deduplicateStore } from '../dedupe.js';
-import { embedAll, loadEmbeddingIndex } from '../embeddings.js';
-import { resolveEmbeddingProvider } from '../embedding-provider.js';
-import { resetAllPhysicsState } from '../physics-state.js';
-import { loadConfig } from '../config.js';
-import { openHippoDb, closeHippoDb } from '../db.js';
-import { resolveTenantId } from '../tenant.js';
-import { refineStore } from '../refine-llm.js';
+import { deduplicateStore } from '../consolidate/dedupe.js';
+import { embedAll, loadEmbeddingIndex } from '../store/embeddings/index.js';
+import { resolveEmbeddingProvider } from '../store/embeddings/provider.js';
+import { resetStoredParticles } from '../store/vector-writes.js';
+import { loadConfig } from '../core/config.js';
+import { resolveTenantId } from '../store/tenant.js';
+import { refineStore } from './refine-llm.js';
 import { printError } from './output.js';
+import { boolFlag } from './flag-values.js';
 import { requireInit, resolveAuthRoot } from './shared.js';
+import { errorMessage } from '../util/log.js';
+const MAX_FAILED_SHOWN = 5;
+const MAX_PAIRS_SHOWN = 15;
+const PAIR_PREVIEW_CHARS = 90;
 export async function cmdRefine(hippoRoot, flags) {
     requireInit(hippoRoot);
     const apiKey = envAnthropicApiKey();
@@ -18,11 +22,11 @@ export async function cmdRefine(hippoRoot, flags) {
         printError('hippo refine needs ANTHROPIC_API_KEY in the environment.');
         process.exit(1);
     }
-    const dryRun = Boolean(flags['dry-run']);
-    const all = Boolean(flags['all']);
+    const dryRun = boolFlag(flags, 'dry-run');
+    const all = boolFlag(flags, 'all');
     const limit = flags['limit'] !== undefined ? parseInt(String(flags['limit']), 10) : undefined;
     const model = flags['model'] ? String(flags['model']) : undefined;
-    const asJson = Boolean(flags['json']);
+    const asJson = boolFlag(flags, 'json');
     const result = await refineStore(hippoRoot, {
         apiKey,
         model,
@@ -41,14 +45,14 @@ export async function cmdRefine(hippoRoot, flags) {
     console.log(`Failed:   ${result.failed}`);
     if (result.failed > 0) {
         console.log('\nFailures:');
-        for (const d of result.details.filter((x) => x.status === 'failed').slice(0, 5)) {
+        for (const d of result.details.filter((x) => x.status === 'failed').slice(0, MAX_FAILED_SHOWN)) {
             console.log(`  ${d.id}: ${d.reason}`);
         }
     }
 }
 export function cmdDedup(hippoRoot, flags) {
     requireInit(hippoRoot);
-    const dryRun = Boolean(flags['dry-run']);
+    const dryRun = boolFlag(flags, 'dry-run');
     if (flags['threshold'] !== undefined) {
         printError('hippo dedup: --threshold is ignored; a duplicate is the same text apart from spacing.');
     }
@@ -59,6 +63,10 @@ export function cmdDedup(hippoRoot, flags) {
         console.log('No duplicates found.');
         return;
     }
+    printDedupGroups(result, dryRun);
+    printDedupPairs(result, dryRun);
+}
+function printDedupGroups(result, dryRun) {
     // Group by reason
     const sameLayerSem = result.pairs.filter(p => p.keptLayer === 'semantic' && p.removedLayer === 'semantic');
     const sameLayerEpi = result.pairs.filter(p => p.keptLayer === 'episodic' && p.removedLayer === 'episodic');
@@ -73,16 +81,18 @@ export function cmdDedup(hippoRoot, flags) {
     if (crossLayer.length > 0) {
         console.log(`  ${crossLayer.length} cross-layer duplicates (episodic content already consolidated into semantic)`);
     }
+}
+function printDedupPairs(result, dryRun) {
     // Show detailed pairs
     console.log('');
-    const shown = result.pairs.slice(0, 15);
+    const shown = result.pairs.slice(0, MAX_PAIRS_SHOWN);
     for (const pair of shown) {
         const simPct = (pair.similarity * 100).toFixed(0);
         const action = dryRun ? 'Would remove' : 'Removed';
         console.log(`  ${simPct}% similar | kept [${pair.keptLayer}] strength=${pair.keptStrength.toFixed(2)}`);
-        console.log(`    ${pair.keptContent.slice(0, 90)}`);
+        console.log(`    ${pair.keptContent.slice(0, PAIR_PREVIEW_CHARS)}`);
         console.log(`  ${action} [${pair.removedLayer}] strength=${pair.removedStrength.toFixed(2)}`);
-        console.log(`    ${pair.removedContent.slice(0, 90)}`);
+        console.log(`    ${pair.removedContent.slice(0, PAIR_PREVIEW_CHARS)}`);
         console.log('');
     }
     if (result.pairs.length > 15) {
@@ -117,7 +127,7 @@ export async function cmdEmbed(hippoRoot, flags, given) {
         count = await embedAll(root, undefined, provider);
     }
     catch (err) {
-        printError(`Embedding failed: ${err instanceof Error ? err.message : String(err)}`);
+        printError(`Embedding failed: ${errorMessage(err)}`);
         const partial = loadEmbeddingIndex(root);
         printError(`Partial progress saved: ${Object.keys(partial).length} embeddings on disk. Re-run \`hippo embed\` to resume.`);
         process.exitCode = 1;
@@ -135,14 +145,8 @@ export async function cmdEmbed(hippoRoot, flags, given) {
 function resetPhysics(root) {
     const entries = loadAllEntries(root);
     const embIndex = loadEmbeddingIndex(root);
-    const db = openHippoDb(root);
-    try {
-        const count = resetAllPhysicsState(db, entries, embIndex);
-        console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
-    }
-    finally {
-        closeHippoDb(db);
-    }
+    const count = resetStoredParticles(root, entries, embIndex);
+    console.log(`Reset physics state: ${count} particles re-initialized from embeddings.`);
 }
 function printEmbedStatus(root) {
     const entries = loadAllEntries(root);
@@ -167,7 +171,7 @@ function readyEmbedProvider(root, given) {
             return resolveEmbeddingProvider(root);
         }
         catch (err) {
-            printError(err instanceof Error ? err.message : String(err));
+            printError(errorMessage(err));
             return null;
         }
     })();