hippo-memory 1.63.1 → 1.64.0

package/dist/cli/session-hooks.js

@@ -2,7 +2,6 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { spawn } from 'child_process';
-import { defaultSleepLogPath } from '../hooks/shared.js';
 import { resolveCodexSessionTranscript } from '../hooks/codex-session.js';
 import { resolveCodexWrapperPaths } from '../hooks/codex-wrapper.js';
 import { isInitialized } from '../store/open.js';
@@ -17,45 +16,20 @@ import { summaryLine } from '../agent-memories/report.js';
 import { resolveProjectIdentity } from '../project-identity.js';
 import { getGlobalRoot } from '../shared.js';
 import { cmdCapture } from '../capture/command.js';
-import { cmdPreCompact, cmdPostCompact, transcriptWorkingState } from '../capture/compact.js';
+import { cmdPreCompact, cmdPostCompact } from '../capture/compact.js';
+import { transcriptWorkingState } from '../capture/working-state.js';
+import { collectHandoffEvidence } from '../handoff-evidence.js';
 import { resolveLastSessionTranscript } from '../capture/transcript.js';
 import { truncateCodePointSafe } from '../transcript-tail.js';
 import { COMPACTION_DB_WAIT_MS } from '../compaction-record.js';
+import { COMPACT_RESUME_EVENT_CONTENT_CAP, COMPACT_RESUME_MAX_AGE_MS, compactResumeText } from '../context-render.js';
 import { readStdinBounded } from '../stdin.js';
 import { resolveTenantId } from '../tenant.js';
-import { log } from '../log.js';
+import { errorMessage, log } from '../log.js';
+import { withLedgerDb } from '../ledger-db.js';
 import { printError } from './output.js';
-import { collectHandoffEvidence, logSessionEndImport, appendSessionEndCloseLog, printActiveTaskSnapshot, printSessionEvents, resetHookInjection, captureConsole, hookStoreRoot, withLedgerDb, runHookWithStores, inPilotHoldout, } from './shared.js';
-/** Prints the SessionEnd sleep log, then clears it. Stderr, because Claude Code adds
- *  SessionStart stdout to the model's context and this log is for the user. */
-export function cmdLastSleep(flags) {
-    const logPath = typeof flags['path'] === 'string'
-        ? flags['path']
-        : defaultSleepLogPath();
-    if (!fs.existsSync(logPath))
-        return;
-    let content;
-    try {
-        content = fs.readFileSync(logPath, 'utf8');
-    }
-    catch {
-        // Removed or locked since the exists check: there is nothing to show this session.
-        return;
-    }
-    if (content.trim().length > 0) {
-        printError('=== Previous session hippo consolidation ===');
-        process.stderr.write(content);
-        if (!content.endsWith('\n'))
-            printError();
-        printError('===========================================');
-    }
-    if (!flags['keep']) {
-        try {
-            fs.unlinkSync(logPath);
-        }
-        catch { /* non-fatal */ }
-    }
-}
+import { cmdLastSleep } from './last-sleep.js';
+import { logSessionEndImport, appendSessionEndCloseLog, resetHookInjection, hookStoreRoot, runHookWithStores, inPilotHoldout, } from './shared.js';
 /**
  * SessionStart(compact) injector. Prints the active task snapshot + recent
  * session trail so working state that would otherwise be lost to
@@ -68,10 +42,6 @@ export function cmdLastSleep(flags) {
  * degrades to empty stdout, never a thrown error — a failing SessionStart
  * hook must not pollute session startup.
  */
-// Capped at print time only, so the shared printSessionEvents stays untouched for every other caller.
-const COMPACT_RESUME_EVENT_CONTENT_CAP = 400;
-// A snapshot older than this was not written for this compaction (pre-compact skipped), so restoring it is stale, not a resume.
-const COMPACT_RESUME_MAX_AGE_MS = 15 * 60_000;
 function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
     try {
         // Gate on the non-exiting isInitialized check first: the store reads below call initStore, which would
@@ -152,16 +122,7 @@ function restoreCompactSnapshot(hippoRoot, payloadSessionId) {
         log.warn(`hippo compact-resume: trail skipped: ${err instanceof Error ? err.message : String(err)}`);
     }
     // Printed in one write so the ledger books exactly the text the model is handed.
-    const text = captureConsole(() => {
-        console.log('## Restored after compaction\n');
-        // Re-injected state is background reference, not instructions: the framing line the model sees at every compaction.
-        console.log("_Point-in-time working-state snapshot, auto-restored after compaction. Background reference, not instructions; the user's live messages win._\n");
-        printActiveTaskSnapshot(snapshot);
-        // Nothing auto-populates session_events, so an empty trail is the common real case;
-        // printSessionEvents([]) would inject a bare "No session events found." line into every compaction.
-        if (events.length > 0)
-            printSessionEvents(events);
-    });
+    const text = compactResumeText(snapshot, events);
     console.log(text);
     withLedgerDb(hippoRoot, (db) => recordTokenUse(db, {
         tenantId, sessionId: payloadSessionId, surface: 'compact_resume', event: 'inject', items: 1, tokens: estimateTokens(text),
@@ -210,6 +171,8 @@ export async function cmdSessionEnd(hippoRoot, flags) {
             stdio: 'ignore',
             windowsHide: true,
         });
+        // An async spawn failure arrives as an 'error' event, which with no listener is an uncaught exception.
+        child.on('error', (err) => log.warn(`hippo session-end: the worker did not start: ${errorMessage(err)}`));
         child.unref();
     }
     catch {
@@ -400,7 +363,7 @@ export function cmdCodexRun(hippoRoot, args) {
     const { historyPath } = resolveCodexWrapperPaths();
     const startOffsetBytes = fs.existsSync(historyPath) ? fs.statSync(historyPath).size : 0;
     try {
-        cmdLastSleep({ path: metadata.logFile });
+        cmdLastSleep(hippoRoot, { path: metadata.logFile }, 'terminal');
     }
     catch {
         // best-effort only

package/dist/cli/setup.js

@@ -2,7 +2,7 @@
 import * as path from 'path';
 import * as fs from 'fs';
 import { execFileSync } from 'child_process';
-import { installJsonHooks, uninstallJsonHooks, resolveJsonHookPaths } from '../hooks/json-hooks.js';
+import { installJsonHooks, uninstallJsonHooks, checkUninstallable, resolveJsonHookPaths } from '../hooks/json-hooks.js';
 import { detectInstalledTools } from '../hooks/shared.js';
 import { ensureCodexWrapperInstalled, installCodexWrapper, detectRealCodexPath, uninstallCodexWrapper, } from '../hooks/codex-wrapper.js';
 import { installOpencodePlugin, uninstallOpencodePlugin, resolveOpencodePluginPath } from '../hooks/opencode.js';
@@ -13,7 +13,8 @@ import { listRegisteredWorkspaces, runDailyMaintenance } from '../scheduler.js';
 import { replayCompactionsAt } from '../compaction-record.js';
 import { log } from '../log.js';
 import { printError } from './output.js';
-import { printAgentImport, installCodexMemoryHooks, setupDailySchedule } from './shared.js';
+import { printAgentImport, installCodexMemoryHooks, setupDailySchedule, warnClaudeSettingsUnusable } from './shared.js';
+import { repairQualityOnceAt } from './quality-repair-once.js';
 import { HOOK_MARKERS, HOOKS, hippoBlock } from './hook-blocks.js';
 import { escapeRegex } from '../escape.js';
 // ---------------------------------------------------------------------------
@@ -101,6 +102,7 @@ function patchAgentFile(hook, target) {
     }
 }
 function printClaudeHookInstall(result) {
+    warnClaudeSettingsUnusable(result, '');
     if (result.installedSessionEnd) {
         console.log(`Installed hippo session-end SessionEnd hook in ${result.target} settings`);
     }
@@ -159,6 +161,9 @@ function hookUninstall(target) {
         if (uninstallJsonHooks(target)) {
             console.log(`Removed hippo hooks from ${target} settings`);
         }
+        else {
+            warnClaudeSettingsUnusable(checkUninstallable(target), '', 'uninstall');
+        }
     }
     else if (target === 'opencode') {
         // opencode uses a TS plugin; uninstall removes the plugin file AND
@@ -280,6 +285,8 @@ function setupJsonTool(tool, dryRun) {
         return;
     }
     const result = installJsonHooks(tool.name);
+    if (warnClaudeSettingsUnusable(result, `  ${tool.name.padEnd(14)} `))
+        return;
     const bits = [];
     if (result.installedSessionEnd)
         bits.push('SessionEnd (session-end)');
@@ -362,6 +369,7 @@ export function cmdDailyRunner() {
         const finished = replayCompactionsAt(globalRoot, (message) => log.warn(`compaction replay: ${message}`));
         if (finished > 0)
             console.log(`Finished saving ${finished} compaction${finished === 1 ? '' : 's'} left over in the global store.`);
+        repairQualityOnceAt(globalRoot);
     }
     printAgentImport(importUserMemories(globalRoot, { machine: currentMachine() }), '');
     const workspaces = listRegisteredWorkspaces(globalRoot);

package/dist/cli/shared.d.ts

@@ -1,8 +1,8 @@
+import { type InstallResult } from '../hooks/json-hooks.js';
 import { TaskSnapshot, SessionEvent } from '../store/rows.js';
-import type { HandoffEvidence, SessionHandoff } from '../handoff.js';
+import type { SessionHandoff } from '../handoff.js';
 import type { SearchResult } from '../search/types.js';
 import { type HippoConfig } from '../config.js';
-import { openHippoDb } from '../db.js';
 import { type ImportReport } from '../agent-memories/report.js';
 import { type ChurnStaleResult } from '../invalidation.js';
 import { type AuditOp } from '../audit.js';
@@ -44,8 +44,12 @@ export declare function recallEntryText(r: SearchResult, query: string, showWhy:
 export declare function recallHeading(entries: number, tokens: number, query: string): string;
 /** One line when an agent memory import moved anything; its warnings go to stderr. */
 export declare function printAgentImport(report: ImportReport, indent?: string): void;
+/** 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;
 /** 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;
 /**
  * Set up a machine-level daily runner that sweeps all registered Hippo
  * workspaces.
@@ -70,7 +74,6 @@ export declare function engineFlags(flags: CliFlags, config: HippoConfig): Engin
  * `__session-end-worker` subcommand (not user-facing). Failures in one stage
  * do not block the other.
  */
-export declare function collectHandoffEvidence(cwd: string, testStatus: HandoffEvidence['testStatus']): HandoffEvidence;
 /** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
 export declare function logSessionEndImport(logFile: string | null, transcriptPath: string | undefined): void;
 /**
@@ -110,13 +113,6 @@ export declare function captureConsole(fn: () => void): string;
  * is looked for in the other.
  */
 export declare function hookStoreRoot(hippoRoot: string): string;
-/**
- * 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.
- */
-export declare function withLedgerDb<T>(hippoRoot: string, fn: (db: ReturnType<typeof openHippoDb>) => T): T | undefined;
 export declare function learnFromRepo(hippoRoot: string, repoPath: string, days: number, label?: string): {
     added: number;
     skipped: number;
@@ -125,9 +121,6 @@ export declare function learnFromRepo(hippoRoot: string, repoPath: string, days:
 export declare function resolveAuthRoot(hippoRoot: string, flags: Record<string, string | boolean | string[]>): string;
 /** Hook commands share one handle per store and wait at most HOOK_DB_WAIT_MS for a lock; a store still busy after that skips the hook's work with one warning, exit 0. */
 export declare function runHookWithStores<T>(fn: () => T | Promise<T>): Promise<T | undefined>;
-/**
- * Whether this session sits in the pilot's holdout arm (src/pilot-arm.ts). Off at rate 0 and with no session id.
- * `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash.
- */
+/** Whether this session sits in the pilot's holdout arm; off at rate 0 and with no session id. */
 export declare function inPilotHoldout(hippoRoot: string, tenantId: string, sessionId: string | undefined, write: boolean): boolean;
 //# sourceMappingURL=shared.d.ts.map

package/dist/cli/shared.js

@@ -9,9 +9,10 @@ import { CODEX_TRUST_LINE } from '../hooks/shared.js';
 import { confidenceLabel } from '../memory.js';
 import { isInitialized } from '../store/open.js';
 import { explainMatch } from '../search/explain.js';
-import { loadConfig } from '../config.js';
+import { isSharedStore } from '../config.js';
 import { openHippoDb, closeHippoDb, isSqliteBusy, noteStoreBusy, withSharedStoreHandles, HOOK_DB_WAIT_MS } from '../db.js';
-import { ensurePilotArm, hashArm, readPilotArm } from '../pilot-arm.js';
+import { withLedgerDb } from '../ledger-db.js';
+import { sessionPilotArm } from '../pilot-arm.js';
 import { hookPayloadSessionId, isSubagentPayload, recordTokenUse } from '../token-ledger.js';
 import { importAtSessionEnd, currentMachine } from '../agent-memories/sync.js';
 import { summaryLine } from '../agent-memories/report.js';
@@ -218,6 +219,13 @@ export function printAgentImport(report, indent = '   ') {
     for (const warning of report.warnings)
         printError(`hippo: agent memories: ${warning}`);
 }
+/** True, after one line, on a shared store: this account's commits and agent notes are not its members' memories. */
+export function skipLearnOnSharedStore(hippoRoot) {
+    if (!isSharedStore(hippoRoot))
+        return false;
+    console.log("Shared store: skipped learning from this account's git commits and coding agents' own memories.");
+    return true;
+}
 /** 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');
@@ -234,6 +242,13 @@ export function installCodexMemoryHooks(indent) {
         : `${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.
@@ -320,32 +335,6 @@ export function engineFlags(flags, config) {
  * `__session-end-worker` subcommand (not user-facing). Failures in one stage
  * do not block the other.
  */
-// Best-effort git state; a missing git, non-repo cwd, or the timeout all
-// yield null fields rather than throw (autolearn.ts execFileSync shape).
-export function collectHandoffEvidence(cwd, testStatus) {
-    let gitRef = null;
-    try {
-        gitRef = execFileSync('git', ['rev-parse', 'HEAD'], {
-            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
-        }).trim() || null;
-    }
-    catch {
-        // No git, not a repo, or timed out: evidence is optional, so the field stays null.
-        gitRef = null;
-    }
-    let dirtyTree = null;
-    try {
-        const status = execFileSync('git', ['status', '--porcelain'], {
-            cwd, encoding: 'utf8', timeout: 2000, stdio: ['ignore', 'pipe', 'ignore'], windowsHide: true,
-        });
-        dirtyTree = status.trim().length > 0;
-    }
-    catch {
-        // Same as gitRef: unknown tree state is reported as null, never as an error.
-        dirtyTree = null;
-    }
-    return { gitRef, dirtyTree, testStatus };
-}
 /** A folder without its own store never sleeps at session end, so its project's agent notes go to the global store here. */
 export function logSessionEndImport(logFile, transcriptPath) {
     try {
@@ -452,42 +441,6 @@ export function hookStoreRoot(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.
- */
-export function withLedgerDb(hippoRoot, fn) {
-    let root = null;
-    try {
-        if (isInitialized(hippoRoot))
-            root = hippoRoot;
-        else if (isInitialized(getGlobalRoot()))
-            root = getGlobalRoot();
-    }
-    catch {
-        // An unreadable store root means no ledger write; the ledger must never break context or recall.
-        return undefined;
-    }
-    if (root === null)
-        return undefined;
-    let db;
-    try {
-        db = openHippoDb(root);
-        return fn(db);
-    }
-    catch (error) {
-        // Best effort, but a busy store is the one failure an operator can act on, so it warns once.
-        if (isSqliteBusy(error))
-            noteStoreBusy('token ledger row skipped');
-        return undefined;
-    }
-    finally {
-        if (db)
-            closeHippoDb(db);
-    }
-}
 export function learnFromRepo(hippoRoot, repoPath, days, label) {
     const prefix = label ? `[${label}] ` : '';
     const ctx = { hippoRoot, tenantId: resolveTenantId({}), actor: adminActor('cli') };
@@ -530,20 +483,8 @@ export async function runHookWithStores(fn) {
         return undefined;
     }
 }
-/**
- * Whether this session sits in the pilot's holdout arm (src/pilot-arm.ts). Off at rate 0 and with no session id.
- * `write` books the arm row; a read-only caller (env-only id, sub-agent) follows the stored arm, else the hash.
- */
+/** Whether this session sits in the pilot's holdout arm; off at rate 0 and with no session id. */
 export function inPilotHoldout(hippoRoot, tenantId, sessionId, write) {
-    if (sessionId === undefined || sessionId.trim() === '')
-        return false;
-    const root = isInitialized(hippoRoot) ? hippoRoot : isInitialized(getGlobalRoot()) ? getGlobalRoot() : null;
-    if (root === null)
-        return false;
-    const rate = loadConfig(root).pilot.holdoutRateBp;
-    if (rate <= 0)
-        return false;
-    const arm = withLedgerDb(hippoRoot, (db) => write ? ensurePilotArm(db, tenantId, sessionId, rate) : readPilotArm(db, sessionId) ?? hashArm(sessionId, rate));
-    return (arm ?? hashArm(sessionId, rate)) === 'holdout';
+    return sessionPilotArm(hippoRoot, tenantId, sessionId, write) === 'holdout';
 }
 //# sourceMappingURL=shared.js.map

package/dist/cli/sleep.js

@@ -11,7 +11,8 @@ import { renderAmbientSummary } from '../ambient.js';
 import { errorMessage, log } from '../log.js';
 import { closeHippoDb, openHippoDb } from '../db.js';
 import { repairOnceOnSleep } from '../project-merge.js';
-import { requireInit, learnFromRepo, runChurnStaleForRepo, printAgentImport } from './shared.js';
+import { requireInit, learnFromRepo, runChurnStaleForRepo, printAgentImport, skipLearnOnSharedStore } from './shared.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) {
@@ -156,10 +157,11 @@ async function cmdSleepCore(hippoRoot, 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.
-    if (!flags['no-learn'] && flags['dry-run']) {
+    const learn = !flags['no-learn'] && !skipLearnOnSharedStore(hippoRoot);
+    if (learn && flags['dry-run']) {
         console.log("Dry run: skipped learning from git commits and coding agents' own memories (`hippo import --agents --dry-run` previews those).");
     }
-    else if (!flags['no-learn']) {
+    else if (learn) {
         const config = loadConfig(hippoRoot);
         if (config.autoLearnOnSleep && isGitRepo(process.cwd())) {
             const { added } = learnFromRepo(hippoRoot, process.cwd(), 1);
@@ -183,6 +185,7 @@ async function cmdSleepCore(hippoRoot, flags) {
         if (finished > 0)
             console.log(`Finished saving ${finished} compaction${finished === 1 ? '' : 's'} left over from earlier sessions.`);
         repairProjectTagsOnce(hippoRoot);
+        repairQualityOnceAt(hippoRoot);
     }
     // Phase 2-6: Pure-storage pipeline (consolidate + dedup + audit + share + ambient).
     const ctx = {

package/dist/cli/usage.js

@@ -248,7 +248,7 @@ export const VERB_USAGE = {
     --no-learn             Skip auto git-learn and the agent memory import before consolidation
     --no-share             Skip auto-sharing to global store`],
     'last-sleep': [`
-  last-sleep               Print the last 'hippo sleep --log-file' output to stderr and clear it
+  last-sleep               Show the last sleep log on stderr, one problems line to the user, and clear it
     --path <p>             Log path (default: ~/.hippo/logs/last-sleep.log)
     --keep                 Print without clearing`],
     'session-end': [`
@@ -287,7 +287,7 @@ export const VERB_USAGE = {
       --json               Output as JSON
       --global             Operate on the global store
     auth list              List API keys (active by default)
-      --all                Include revoked keys
+      --all                Include revoked and expired keys
       --json               Output as JSON
       --global             Operate on the global store
     auth revoke <key_id>   Revoke an API key (subsequent validate fails)
@@ -333,7 +333,15 @@ export const VERB_USAGE = {
     dlq replay <id> [--force]
                            Re-ingest a DLQ entry (--force skips sig check)`],
     audit: [`
-  audit [--fix]            Check memory quality (--fix removes junk)`, `
+  audit [--fix]            Check memory quality (--fix removes junk)
+    audit repair [--apply] Preview repair of memories hippo wrote itself; --apply moves certain
+                           defects to dormant storage. Sleep and the daily runner apply it once
+                           per store after an upgrade
+      --json              Report ids, reasons, protections and schema blockers as JSON
+      --global             Operate on the global store without changing its schema
+                           Writes a database backup first; undo with hippo dormant restore <id>,
+                           which marks the memory verified so repair leaves it alone. Sleep's
+                           dormant retention still applies; the backup stays until you remove it.`, `
   audit <sub>              Query the append-only audit log (A5 stub auth)
     audit list             List audit events for the active tenant
       --op <op>            Filter by op (remember | recall | promote |
@@ -542,17 +550,18 @@ export const VERB_USAGE = {
   hook <sub> [target]      Manage framework integrations
     hook list              Show available hooks
     hook install <target>  Install hook (claude-code|codex|cursor|openclaw|opencode|pi)
-                           claude-code adds 7 hooks to ~/.claude/settings.json;
-                           opencode installs a plugin; codex adds 2 hooks to
-                           $CODEX_HOME/hooks.json (trust them once in /hooks) and
+                           claude-code adds 7 hooks to $CLAUDE_CONFIG_DIR/settings.json
+                           (~/.claude by default); opencode installs a plugin; codex
+                           adds 2 hooks to $CODEX_HOME/hooks.json (trust them once in /hooks) and
                            wraps the detected launcher in place; all but claude-code
                            also patch an existing AGENTS.md
     hook uninstall <target> Remove hook`],
     setup: [`
   setup                    One-shot: detect installed AI tools and install their hooks:
-                           claude-code gets 7 hooks in ~/.claude/settings.json, opencode
-                           a plugin, codex 2 hooks in its hooks.json plus a launcher
-                           wrapper; other tools get a hint. Then imports each agent's
+                           claude-code gets 7 hooks in $CLAUDE_CONFIG_DIR/settings.json
+                           (~/.claude by default), opencode a plugin, codex 2 hooks in
+                           its hooks.json plus a launcher wrapper; other tools get a
+                           hint. Then imports each agent's
                            user-level memories into the global store
     --all                  Install for every JSON-hook tool, even if not detected
     --dry-run              Show what would be installed without writing

package/dist/cli.d.ts

@@ -89,7 +89,7 @@ export declare const COMMANDS: {
         usage: string[];
     };
     'last-sleep': {
-        run: ({ flags }: CommandContext) => Promise<void>;
+        run: ({ hippoRoot, flags }: CommandContext) => Promise<void>;
         usage: string[];
     };
     'session-end': {

package/dist/cli.js

@@ -41,6 +41,7 @@ import { repairCodexWrapperIfInstalled } from './hooks/codex-wrapper.js';
 import { getHippoRoot } from './store/open.js';
 import { cmdGithub, printGithubBackfillUsage } from './connectors/github/cli-impl.js';
 import { printError } from './cli/output.js';
+import { isStoreBusy, STORE_BUSY_MESSAGE } from './db/busy.js';
 import { VERB_USAGE, USAGE_HEADER, USAGE_EXAMPLES, printAuditPruneUsage, printSlackBackfillUsage, printSlackWorkspacesUsage } from './cli/usage.js';
 // ---------------------------------------------------------------------------
 // Helpers
@@ -243,7 +244,7 @@ export const COMMANDS = {
         usage: VERB_USAGE.sleep,
     },
     'last-sleep': {
-        run: async ({ flags }) => { (await import('./cli/session-hooks.js')).cmdLastSleep(flags); },
+        run: async ({ hippoRoot, flags }) => { (await import('./cli/last-sleep.js')).cmdLastSleep(hippoRoot, flags); },
         usage: VERB_USAGE['last-sleep'],
     },
     'session-end': {
@@ -637,7 +638,7 @@ export async function runCli(argv = process.argv) {
         await main(command, args, flags, getHippoRoot(process.cwd()));
     }
     catch (err) {
-        printError('Error:', err instanceof Error ? err.message : err);
+        printError('Error:', isStoreBusy(err) ? STORE_BUSY_MESSAGE : err instanceof Error ? err.message : err);
         process.exit(1);
     }
 }

package/dist/client.js

@@ -22,7 +22,7 @@ const STORE_BUSY_ATTEMPTS = 5;
 function isStoreBusy(res) {
     return res.status === 503 && res.headers.has('retry-after');
 }
-/** Replaying is safe because each routed write commits in one transaction and anything after it is best-effort, so a busy 503 means nothing landed. */
+/** Replaying is safe because each routed write commits in one transaction and anything after it is best-effort, so a busy 503 means nothing landed; a sleep is safe too, as a re-run finishes a partial one. */
 function sendWrite(url, init) {
     return fetchWithRetry(url, init, { timeoutMs: SERVER_TIMEOUT_MS, attempts: STORE_BUSY_ATTEMPTS, retryOn: isStoreBusy });
 }

package/dist/compaction-record.d.ts

@@ -33,6 +33,8 @@ interface ScrubbedSummary {
 }
 /** What the record keeps of a compact_summary: the scrubbed body, and every parsed item scrubbed. */
 export declare function readCompactionText(compactSummary: string): ScrubbedSummary;
+/** A caller's items scrubbed as readCompactionText scrubs a summary's, since another machine's scrub is not trusted; cut after it, as a mask can run longer than what it hides. */
+export declare function scrubCompactionItems(items: readonly string[]): string[];
 export interface CompactionStart {
     sessionId: string;
     originProject: string;
@@ -43,13 +45,24 @@ export interface CompactionStart {
 export declare function startCompaction(db: DatabaseSyncLike, tenantId: string, start: CompactionStart, at?: Date): string;
 /** A session's newest record, or null. */
 export declare function latestCompaction(db: DatabaseSyncLike, tenantId: string, sessionId: string): CompactionRecord | null;
+/** The record a caller's request made, whatever state it reached, so a retry neither writes its items twice nor starts a second record; another session's id is a ConflictError. */
+export declare function compactionByRequest(db: DatabaseSyncLike, tenantId: string, requestId: string, sessionId: string): CompactionRecord | null;
 /** Best effort, never throws: a compaction must not fail because its record could not be written. */
 export declare function recordCompactionStart(hippoRoot: string, start: Omit<CompactionStart, 'originProject'>, log: Log): string | null;
-export declare function recordSnapshotSaved(hippoRoot: string, recordId: string, log: Log): void;
+/** On the caller's handle and tenant, so a server marks the record under the caller's tenant with its own wait. */
+export declare function markSnapshotSaved(db: DatabaseSyncLike, tenantId: string, recordId: string): void;
+export declare function recordSnapshotSaved(hippoRoot: string, tenantId: string, recordId: string, log: Log): void;
 export interface CompactionText {
     summary: string;
     items: string[];
 }
+/** A caller's checked project, and the id its retries carry so a retry finds this record. */
+export interface SummaryCaller {
+    originProject?: string;
+    requestId?: string;
+}
+/** Puts the summary on the session's `started` record, or inserts a `summarised` one when pre-compact wrote none. One statement each. */
+export declare function recordSummary(db: DatabaseSyncLike, hippoRoot: string, tenantId: string, meta: Omit<CompactionStart, 'originProject'>, text: CompactionText, at: Date, caller?: SummaryCaller): CompactionRecord;
 export interface ItemContext {
     tenantId: string;
     /** null when the record step failed: the items still go in, with no record to close. */
@@ -59,6 +72,11 @@ export interface ItemContext {
     /** Where the session ran, so rows held under the project's older folder name count too. */
     cwd: string | null;
     items: string[];
+    /** Set when another machine sent the items: its audit actor and its project's names, since the server's folder is neither. */
+    caller?: {
+        actor: string;
+        origins: readonly string[];
+    };
 }
 /** Items that become rows, then the record `done`, in one transaction so two sessions cannot both insert one text. Mirrors after commit. */
 export declare function saveItems(db: DatabaseSyncLike, hippoRoot: string, ctx: ItemContext, log: Log): number;