hippo-memory 1.72.0 → 2.1.0

package/dist/cli/status.js

@@ -15,10 +15,10 @@ import { PACKAGE_VERSION } from '../util/version.js';
 import { FAILURE_LOG_RETENTION_DAYS } from '../store/failure-log.js';
 import { getGlobalRoot } from '../sharing/global-store.js';
 import * as api from '../api/index.js';
-import { getMemory } from '../api/memories.js';
+import { getMemory } from '../api/memories/memories.js';
 import { correctionLatencyReport, embeddingReindexNeeded, provenanceCoverageReport, storeStatus, storedParticles, vectorSummary, } from '../api/status.js';
 import { cliApiContext } from './api-context.js';
-import { errorMessage, log } from '../util/log.js';
+import { errorMessage, log, errorFields } from '../util/log.js';
 import { printError } from './output.js';
 import { parseCountFlag, stringFlagOrExit, flagIsTrue } from './flag-values.js';
 import { requireInit, resolveAuthRoot } from './shared.js';
@@ -26,11 +26,12 @@ import { fmt } from './print.js';
 import { isJsonObject } from '../util/json.js';
 import { hookStoreRoot } from './hook-runtime.js';
 import { DAY_MS, HOUR_MS, MINUTE_MS } from '../util/time.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
+const AT_RISK_BELOW = 0.2;
 export function handleStatus({ hippoRoot, tenantId }) {
     requireInit(hippoRoot);
     const ctx = cliApiContext(hippoRoot, tenantId);
-    const { stats, counts } = storeStatus(ctx, evalNow(), 0.2);
+    const { stats, counts } = storeStatus(ctx, evalNow(), AT_RISK_BELOW);
     const { byLayer, byConfidence, pinned, atRisk, agedOut, avgStrength } = counts;
     console.log('Hippo Status');
     console.log('---------------------------');
@@ -40,7 +41,7 @@ export function handleStatus({ hippoRoot, tenantId }) {
     console.log(`  Semantic:        ${byLayer[Layer.Semantic]}`);
     console.log(`  Trace:           ${byLayer[Layer.Trace]}`);
     console.log(`Pinned:            ${pinned}`);
-    console.log(`At risk (<0.2):    ${atRisk}`);
+    console.log(`At risk (<${AT_RISK_BELOW}):    ${atRisk}`);
     console.log(`Open conflicts:    ${counts.openConflicts}`);
     console.log(`Avg strength:      ${fmt(avgStrength)}`);
     console.log('');
@@ -130,7 +131,7 @@ function printPhysicsStatus(ctx) {
     }
     catch (err) {
         // The physics table may not exist yet, so status prints without that line.
-        log.debug(`physics status skipped: ${errorMessage(err)}`);
+        log.debug(`physics status skipped: ${errorMessage(err)}`, errorFields(err));
     }
 }
 export function physicsEnergyText(particles, gMemory) {
@@ -143,8 +144,7 @@ async function cmdInspect(hippoRoot, tenantId, id) {
     requireInit(hippoRoot);
     const entry = await getMemory(cliApiContext(hippoRoot, tenantId), id);
     if (!entry) {
-        printError(`Memory not found: ${id}`);
-        throw new CliExit(1);
+        fail(`Memory not found: ${id}`);
     }
     const now = evalNow();
     const currentStrength = calculateStrength(entry, now, { ablation: strengthAblation() });
@@ -156,7 +156,8 @@ async function cmdInspect(hippoRoot, tenantId, id) {
     console.log(`Memory: ${entry.id}`);
     console.log('---------------------------');
     console.log(`Layer:            ${entry.layer}`);
-    console.log(`Confidence:       ${entry.confidence}${effectiveConfidence !== entry.confidence ? ` (effective: ${effectiveConfidence})` : ''}`);
+    const effective = effectiveConfidence !== entry.confidence ? ` (effective: ${effectiveConfidence})` : '';
+    console.log(`Confidence:       ${entry.confidence}${effective}`);
     console.log(`Created:          ${entry.created} (${fmt(ageDays, 1)}d ago)`);
     console.log(`Last retrieved:   ${entry.last_retrieved} (${fmt(daysSince, 1)}d ago)`);
     console.log(`Retrieval count:  ${entry.retrieval_count}`);
@@ -181,13 +182,13 @@ async function cmdInspect(hippoRoot, tenantId, id) {
     console.log('-'.repeat(40));
     console.log(entry.content);
 }
-/** `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 function handleTokens({ hippoRoot, tenantId, flags }) {
+/** `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 async function handleTokens({ hippoRoot, tenantId, flags }) {
     const root = resolveAuthRoot(hippoRoot, flags);
     const ctx = cliApiContext(root, tenantId);
     const days = parseCountFlag(flags['days']);
-    const summary = api.tokenSummary(ctx, { days: days > 0 ? days : undefined });
+    const summary = await api.tokenSummary(ctx, { days: days > 0 ? days : undefined });
     if (flags['json']) {
         console.log(JSON.stringify(summary, null, 2));
         return;
@@ -198,11 +199,13 @@ export function handleTokens({ hippoRoot, tenantId, flags }) {
         return;
     }
     console.log(`Memory text handed to agents, last ${windowDays} days (estimated tokens, characters / 4)\n`);
-    console.log(`  ${'surface'.padEnd(14)}${'sent'.padStart(8)}${'tokens'.padStart(12)}${'skipped'.padStart(10)}${'saved'.padStart(12)}`
+    console.log(`  ${'surface'.padEnd(14)}${'sent'.padStart(8)}${'tokens'.padStart(12)}${'skipped'.padStart(10)}` +
+        `${'saved'.padStart(12)}`
         + `${'re-read'.padStart(12)}`);
     for (const row of summary.surfaces) {
         console.log(`  ${row.surface.padEnd(14)}${String(row.injected).padStart(8)}${String(row.tokens).padStart(12)}`
-            + `${String(row.skipped).padStart(10)}${String(row.tokensAvoided).padStart(12)}${String(row.tokensReread).padStart(12)}`);
+            + `${String(row.skipped).padStart(10)}${String(row.tokensAvoided).padStart(12)}`
+            + `${String(row.tokensReread).padStart(12)}`);
     }
     console.log('');
     console.log(`  Total sent: ${summary.totalTokens} tokens. Saved by skipping unchanged blocks: ${summary.totalTokensAvoided}.`);
@@ -211,17 +214,18 @@ export function handleTokens({ hippoRoot, tenantId, flags }) {
     if (summary.meanTokensPerSession > 0) {
         console.log(`  Mean per session (rows with a session id): ${summary.meanTokensPerSession} tokens.`);
     }
-    console.log('  Re-reads are counted for hook and compact-resume blocks when a session ends; other surfaces, and open or crashed sessions, show sent only.');
+    console.log('  Re-reads are counted for hook and compact-resume blocks when a session ends; ' +
+        'other surfaces, and open or crashed sessions, show sent only.');
     console.log("  Re-reads usually bill at the provider's cached-input rate, a fraction of the full input price.");
 }
 /** `hippo failures [--days <n>] [--json] [--global]`: failed tool calls by outcome, and repeats across sessions. */
-export function handleFailures({ hippoRoot, tenantId, flags }) {
+export async function handleFailures({ hippoRoot, tenantId, flags }) {
     // The store the capture-error hook writes to; a report never creates one.
     const root = flags['global'] ? getGlobalRoot() : hookStoreRoot(hippoRoot);
     requireInit(root);
     const ctx = cliApiContext(root, tenantId);
     const days = parseCountFlag(flags['days']);
-    const summary = api.failureSummary(ctx, { days: days > 0 ? days : undefined });
+    const summary = await api.failureSummary(ctx, { days: days > 0 ? days : undefined });
     if (flags['json']) {
         console.log(JSON.stringify(summary, null, 2));
         return;
@@ -305,8 +309,9 @@ export function handleProvenance({ hippoRoot, tenantId, flags }) {
     }
 }
 export function handleDoctor({ flags }) {
+    const pkgPath = path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json');
     // SAFETY: package.json always carries a string "version" (checked at release by check-manifest-versions).
-    const pkg = JSON.parse(fs.readFileSync(path.join(path.dirname(fileURLToPath(import.meta.url)), '..', '..', 'package.json'), 'utf-8'));
+    const pkg = JSON.parse(fs.readFileSync(pkgPath, 'utf-8'));
     const report = runDoctor({ version: pkg.version });
     console.log(flags['json'] ? JSON.stringify(report, null, 2) : formatDoctor(report));
     if (!report.ok)
@@ -315,8 +320,7 @@ export function handleDoctor({ flags }) {
 export function handleSupportBundle({ flags }) {
     const outFlag = stringFlagOrExit(flags, 'out');
     if (outFlag === '') {
-        printError('--out requires a file path.');
-        throw new CliExit(1);
+        fail('--out requires a file path.');
     }
     const includeLogs = flagIsTrue(flags, 'include-logs');
     const home = envHomeDir() || os.homedir();
@@ -340,16 +344,17 @@ export function handleSupportBundle({ flags }) {
     const kb = Math.round(Buffer.byteLength(json) / 1024);
     console.log(`Wrote ${file} (${kb} KB).`);
     console.log(includeLogs
-        ? `It holds versions, doctor checks, config with secrets removed, store counts, and the last ${TAIL_MAX_LINES} lines of ` +
-            'each hippo log with known secret shapes removed. Those log lines can quote memory text. Read it before you attach it to a ticket.'
-        : 'It holds versions, doctor checks, config with secrets removed, store counts and log file names. It never holds memory text. Read it before you ' +
-            'attach it to a ticket.');
+        ? `It holds versions, doctor checks, config with secrets removed, store counts, ` +
+            `and the last ${TAIL_MAX_LINES} lines of ` +
+            'each hippo log with known secret shapes removed. Those log lines can quote memory text. ' +
+            'Read it before you attach it to a ticket.'
+        : 'It holds versions, doctor checks, config with secrets removed, store counts and log file names. ' +
+            'It never holds memory text. Read it before you attach it to a ticket.');
 }
 export async function handleInspect({ hippoRoot, tenantId, args }) {
     const id = args[0];
     if (!id) {
-        printError('Please provide a memory ID.');
-        throw new CliExit(1);
+        fail('Please provide a memory ID.');
     }
     await cmdInspect(hippoRoot, tenantId, id);
 }

package/dist/cli/stdin.d.ts

@@ -1,15 +1,22 @@
-/** `timedOut` means the window closed with stdin still open, so absent `text` is "unknown", not "none", and present `text` may be truncated;
+/**
+ * `timedOut` means the window closed with stdin still open, so absent `text` is "unknown", not "none", and present
+ * `text` may be truncated;
  * treating absence as a manual run is only safe when it is false. */
 export interface BoundedStdin {
     text?: string;
     timedOut: boolean;
 }
-/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`),
+/**
+ * Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or
+ * `HIPPO_STDIN_WAIT_MS`),
  * refreshed on each chunk so a slow real write is not cut off, capped at `waitMs * 10`. */
 export declare function readStdinBounded(waitMs?: number): Promise<BoundedStdin>;
 /** A hook payload with Copilot's camelCase fields copied to the snake_case keys hippo reads. The camelCase keys stay,
  * so the sessionStart reply can follow the sender's casing; text that needs no change comes back exactly as sent. */
 export declare function normaliseHookPayload(text: string | undefined): string | undefined;
-/** The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link normaliseHookPayload}. */
+/**
+ * The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link
+ * normaliseHookPayload}.
+ */
 export declare function readHookStdin(waitMs?: number): Promise<BoundedStdin>;
 //# sourceMappingURL=stdin.d.ts.map

package/dist/cli/stdin.js

@@ -4,7 +4,9 @@ const DEFAULT_STDIN_WAIT_MS = 1000;
 function defaultWaitMs() {
     return envStdinWaitMs() ?? DEFAULT_STDIN_WAIT_MS;
 }
-/** Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or `HIPPO_STDIN_WAIT_MS`),
+/**
+ * Never blocks: a TTY resolves at once, otherwise waits up to `waitMs` of idle (default 1000ms, or
+ * `HIPPO_STDIN_WAIT_MS`),
  * refreshed on each chunk so a slow real write is not cut off, capped at `waitMs * 10`. */
 export function readStdinBounded(waitMs = defaultWaitMs()) {
     let stdin;
@@ -48,7 +50,9 @@ const CAMEL_TO_SNAKE = [
     ['hookEventName', 'hook_event_name'],
     ['customInstructions', 'custom_instructions'],
 ];
-/** Copilot sends `toolArgs` as the model's raw JSON string; Claude Code and VS Code send `tool_input` already parsed. */
+/**
+ * Copilot sends `toolArgs` as the model's raw JSON string; Claude Code and VS Code send `tool_input` already parsed.
+ */
 function parsedToolArgs(value) {
     if (!isJsonString(value))
         return value;
@@ -95,7 +99,10 @@ export function normaliseHookPayload(text) {
     const added = snakeCaseFields(payload);
     return Object.keys(added).length === 0 ? text : JSON.stringify({ ...payload, ...added });
 }
-/** The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link normaliseHookPayload}. */
+/**
+ * The stdin read every hook verb uses: {@link readStdinBounded}, with the payload passed through {@link
+ * normaliseHookPayload}.
+ */
 export async function readHookStdin(waitMs) {
     const read = await readStdinBounded(waitMs);
     return { text: normaliseHookPayload(read.text), timedOut: read.timedOut };

package/dist/cli/transfer.d.ts

@@ -1,10 +1,10 @@
 import { type CommandContext } from './flag-values.js';
-export declare function handleLearn({ hippoRoot, tenantId, flags }: CommandContext): void;
-export declare function handleImport({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleLearn({ hippoRoot, tenantId, flags }: CommandContext): Promise<void>;
+export declare function handleImport({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handleSync({ hippoRoot, flags }: CommandContext): void;
-export declare function handleWatch({ hippoRoot, tenantId, args }: CommandContext): Promise<void>;
+export declare function handleWatch({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handlePromote({ hippoRoot, tenantId, args }: CommandContext): Promise<void>;
 export declare function handleShare({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 export declare function handlePeers({ tenantId, flags }: CommandContext): void;
-export declare function handleExport({ hippoRoot, tenantId, args, flags }: CommandContext): void;
+export declare function handleExport({ hippoRoot, tenantId, args, flags }: CommandContext): Promise<void>;
 //# sourceMappingURL=transfer.d.ts.map

package/dist/cli/transfer.js

@@ -4,7 +4,7 @@ import * as fs from 'fs';
 import { isInitialized } from '../core/project-identity.js';
 import { RejectedValueError } from '../core/api-errors.js';
 import { embedCoverage, embedMissingMemories } from '../api/embeddings.js';
-import { captureError, runWatched } from '../learn/autolearn.js';
+import { captureError, runWatched, runWatchedLine } from '../learn/autolearn.js';
 import { currentMachine, importAtSessionEnd, importForStore } from '../agent-memories/sync.js';
 import { detailLines } from '../agent-memories/report.js';
 import { getGlobalRoot, initGlobal } from '../sharing/global-store.js';
@@ -14,25 +14,44 @@ import { importChatGPT, importClaude, importCursor, importGenericFile, } from '.
 import { importMarkdown } from '../importers/markdown.js';
 import { importVault } from '../importers/vault.js';
 import * as api from '../api/index.js';
-import { getMemory, listMemories } from '../api/memories.js';
+import { getMemory, listMemories } from '../api/memories/memories.js';
 import * as client from './client.js';
 import { cliApiContext } from './api-context.js';
 import { printError } from './output.js';
 import { errorMessage, log } from '../util/log.js';
 import { requireInit, runViaServerIfAvailable, learnFromRepo } from './shared.js';
 import { fmt } from './print.js';
-import { boolFlag, flagIsTrue, isStringFlag, nonEmptyStringFlag, numberFlag } from './flag-values.js';
+import { boolFlag, flagIsTrue, isStringFlag, nonEmptyStringFlag, numberFlag, stringFlagOrExit, stringListFlag, } from './flag-values.js';
 import { CONTENT_PREVIEW_CHARS, DATE_PREFIX_CHARS } from '../util/token-text.js';
-import { CliExit } from './exit.js';
+import { CliExit, fail } from './exit.js';
 const STDERR_PREVIEW_CHARS = 80;
 const MAX_ENTRIES_SHOWN = 10;
 // Watch command
-async function cmdWatch(command, hippoRoot, tenantId) {
-    if (!command) {
-        printError('Usage: hippo watch "<command>"');
-        throw new CliExit(1);
+const WATCH_USAGE = 'Usage: hippo watch -- <command> [args...], or hippo watch --shell "<command line>"';
+/** The argv to run and whether a shell parses it: `--shell` takes one command line, anything else is argv as given. */
+function watchedCommand(args, flags) {
+    if (flags['shell'] !== undefined) {
+        const line = nonEmptyStringFlag(flags, 'shell');
+        if (line === undefined) {
+            fail(WATCH_USAGE);
+        }
+        // The shell is the feature here: the user's own command line, pipes and && included, opted into by name; argv runs
+        // with no shell.
+        return { argv: [line], shell: true };
+    }
+    if (args.length === 0) {
+        fail(WATCH_USAGE);
+    }
+    // A quoted 1.x command line would now run as one program name, so it is refused rather than guessed at.
+    if (args.length === 1 && /\s/.test(args[0])) {
+        fail(`hippo watch: "${args[0]}" is one argument with spaces. Use \`hippo watch -- cmd args\` ` +
+            `or \`hippo watch --shell "<command line>"\`.`);
     }
-    const { exitCode, stderr } = await runWatched(command);
+    return { argv: [...args], shell: false };
+}
+async function cmdWatch(argv, shell, hippoRoot, tenantId) {
+    const command = argv.join(' ');
+    const { exitCode, stderr } = await (shell ? runWatchedLine(argv[0]) : runWatched(argv));
     if (exitCode === 0) {
         // Success: no noise
         return;
@@ -46,7 +65,7 @@ async function cmdWatch(command, hippoRoot, tenantId) {
     // A rejection-guard refusal of a failed command's output must not crash the watcher:
     // skip with the message below and still exit with the wrapped command's real exit code.
     try {
-        api.rememberLocally(cliApiContext(hippoRoot, tenantId), {
+        await api.rememberLocally(cliApiContext(hippoRoot, tenantId), {
             content: failure.content,
             tags: failure.tags,
             layer: failure.layer,
@@ -69,11 +88,10 @@ async function cmdWatch(command, hippoRoot, tenantId) {
     throw new CliExit(exitCode);
 }
 // Learn command
-export function handleLearn({ hippoRoot, tenantId, flags }) {
+export async function handleLearn({ hippoRoot, tenantId, flags }) {
     requireInit(hippoRoot);
     if (!flags['git']) {
-        printError('Usage: hippo learn --git [--days <n>] [--repos <paths>]');
-        throw new CliExit(1);
+        fail('Usage: hippo learn --git [--days <n>] [--repos <paths>]');
     }
     const days = numberFlag(flags, 'days') ?? 7;
     console.log(`Scanning git log for the last ${days} days...`);
@@ -84,19 +102,21 @@ export function handleLearn({ hippoRoot, tenantId, flags }) {
         let totalSkipped = 0;
         for (const repo of repos) {
             const label = path.basename(repo);
-            const { added, skipped } = learnFromRepo(hippoRoot, tenantId, repo, days, label);
+            const { added, skipped } = await learnFromRepo(hippoRoot, tenantId, repo, days, label);
             totalAdded += added;
             totalSkipped += skipped;
         }
-        console.log(`Git learn complete: ${totalAdded} new lessons added, ${totalSkipped} duplicates skipped across ${repos.length} repos.`);
+        console.log(`Git learn complete: ${totalAdded} new lessons added, ` +
+            `${totalSkipped} duplicates skipped across ${repos.length} repos.`);
     }
     else {
-        const { added, skipped } = learnFromRepo(hippoRoot, tenantId, process.cwd(), days);
+        const { added, skipped } = await learnFromRepo(hippoRoot, tenantId, process.cwd(), days);
         console.log(`Git learn complete: ${added} new lessons added, ${skipped} duplicates skipped.`);
     }
 }
 // Import command
-/** The rows are saved either way; a failed backfill only delays vectors, so it warns with how many wait and the command that finishes them. */
+/** The rows are saved either way; a failed backfill only delays vectors, so it warns with how many wait and the command
+ * that finishes them. */
 function warnBackfillFailed(ctx, embedCommand, err) {
     let waiting;
     try {
@@ -107,25 +127,24 @@ function warnBackfillFailed(ctx, embedCommand, err) {
     catch (countErr) {
         waiting = `an unknown number of (count failed: ${errorMessage(countErr)})`;
     }
-    log.warn(`import: embedding backfill failed (${errorMessage(err)}); ${waiting} rows have no vector; run '${embedCommand}' to backfill`);
+    log.warn(`import: embedding backfill failed (${errorMessage(err)}); ${waiting} rows have no vector; ` +
+        `run '${embedCommand}' to backfill`);
 }
-/** Batch-embed freshly imported rows. The floating promise is deliberate: libuv keeps the process alive until it settles, and awaiting
- *  would block the CLI on model load; `hippo embed` is the backstop if interrupted. */
+/** Batch-embed freshly imported rows. The floating promise is deliberate: libuv keeps the process alive until it
+ * settles, and awaiting would block the CLI on model load; `hippo embed` is the backstop if interrupted. */
 function backfillVectors(ctx, embedCommand) {
     void embedMissingMemories(ctx).catch((err) => warnBackfillFailed(ctx, embedCommand, err));
 }
 function warnRedacted(count) {
-    if (count)
-        printError(`Warning: secret-shaped text was redacted from ${count} imported ${count === 1 ? 'entry' : 'entries'} before storing`);
+    if (count) {
+        const noun = count === 1 ? 'entry' : 'entries';
+        printError(`Warning: secret-shaped text was redacted from ${count} imported ${noun} before storing`);
+    }
 }
-export function handleImport({ hippoRoot, tenantId, args, flags }) {
+export async function handleImport({ hippoRoot, tenantId, args, flags }) {
     const useGlobal = boolFlag(flags, 'global');
     const dryRun = boolFlag(flags, 'dry-run');
-    const extraTags = Array.isArray(flags['tag'])
-        ? flags['tag']
-        : flags['tag']
-            ? [String(flags['tag'])]
-            : [];
+    const extraTags = stringListFlag(flags, 'tag') ?? [];
     const targetRoot = useGlobal ? getGlobalRoot() : hippoRoot;
     if (flags['agents'])
         return importAgentMemories(hippoRoot, useGlobal, dryRun);
@@ -141,24 +160,31 @@ export function handleImport({ hippoRoot, tenantId, args, flags }) {
         extraTags,
         hippoRoot,
     };
-    // Vault import is a FOLDER importer that dispatches apart from the single-file slot below; it writes through tenant-scoped api calls,
-    // so the tenant is resolved and passed through. --global is unsupported (the connector raw-archive path is tenant-local).
-    if (flags['vault'])
-        return importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun);
+    // Vault import is a FOLDER importer that dispatches apart from the single-file slot below; it writes through
+    // tenant-scoped api calls, so the tenant is resolved and passed through. --global is unsupported (the connector
+    // raw-archive path is tenant-local).
+    const vault = stringFlagOrExit(flags, 'vault');
+    if (vault)
+        return await importVaultFolder(hippoRoot, tenantId, vault, flags, importOptions, useGlobal, dryRun);
     importFromFile(targetRoot, args, flags, { importOptions, useGlobal, dryRun, tenantId });
 }
 // Determine which importer to use based on flag
 function pickImporter(args, flags) {
-    if (flags['chatgpt'])
-        return { filePath: String(flags['chatgpt']), importer: importChatGPT, importerName: 'ChatGPT' };
-    if (flags['claude'])
-        return { filePath: String(flags['claude']), importer: importClaude, importerName: 'Claude' };
-    if (flags['cursor'])
-        return { filePath: String(flags['cursor']), importer: importCursor, importerName: 'Cursor' };
-    if (flags['file'])
-        return { filePath: String(flags['file']), importer: importGenericFile, importerName: 'File' };
-    if (flags['markdown'])
-        return { filePath: String(flags['markdown']), importer: importMarkdown, importerName: 'Markdown' };
+    if (flags['chatgpt']) {
+        return { filePath: stringFlagOrExit(flags, 'chatgpt'), importer: importChatGPT, importerName: 'ChatGPT' };
+    }
+    if (flags['claude']) {
+        return { filePath: stringFlagOrExit(flags, 'claude'), importer: importClaude, importerName: 'Claude' };
+    }
+    if (flags['cursor']) {
+        return { filePath: stringFlagOrExit(flags, 'cursor'), importer: importCursor, importerName: 'Cursor' };
+    }
+    if (flags['file']) {
+        return { filePath: stringFlagOrExit(flags, 'file'), importer: importGenericFile, importerName: 'File' };
+    }
+    if (flags['markdown']) {
+        return { filePath: stringFlagOrExit(flags, 'markdown'), importer: importMarkdown, importerName: 'Markdown' };
+    }
     // Positional: try to auto-detect from extension
     if (args[0])
         return { filePath: args[0], importer: importGenericFile, importerName: 'File' };
@@ -168,12 +194,11 @@ function importFromFile(targetRoot, args, flags, options) {
     const { importOptions, useGlobal, dryRun, tenantId } = options;
     const { filePath, importer, importerName } = pickImporter(args, flags);
     if (!filePath || !importer) {
-        printError('Usage: hippo import <--chatgpt|--claude|--cursor|--file|--markdown|--vault> <path>, or hippo import --agents [--dry-run]');
-        throw new CliExit(1);
+        fail('Usage: hippo import <--chatgpt|--claude|--cursor|--file|--markdown|--vault> <path>, ' +
+            'or hippo import --agents [--dry-run]');
     }
     if (!fs.existsSync(filePath)) {
-        printError(`File not found: ${filePath}`);
-        throw new CliExit(1);
+        fail(`File not found: ${filePath}`);
     }
     const result = importer(filePath, importOptions);
     // The importers' writeEntry sites don't embed, so the new rows are embedded here in one pass.
@@ -219,38 +244,33 @@ function importAgentMemories(hippoRoot, useGlobal, dryRun) {
     for (const warning of report.warnings)
         printError(`hippo: agent memories: ${warning}`);
 }
-function importVaultFolder(hippoRoot, tenantId, flags, importOptions, useGlobal, dryRun) {
-    const folderPath = String(flags['vault']);
+async function importVaultFolder(hippoRoot, tenantId, folderPath, flags, importOptions, useGlobal, dryRun) {
     checkVaultArgs(folderPath, flags, useGlobal);
     const vaultOptions = {
         ...importOptions,
         tenantId,
-        name: flags['name'] ? String(flags['name']) : undefined,
-        scope: flags['scope'] ? String(flags['scope']) : undefined,
+        name: nonEmptyStringFlag(flags, 'name'),
+        scope: nonEmptyStringFlag(flags, 'scope'),
     };
-    const vaultResult = importVault(folderPath, vaultOptions);
+    const vaultResult = await importVault(folderPath, vaultOptions);
     printVaultSummary(vaultResult, folderPath, cliApiContext(hippoRoot, tenantId), dryRun);
 }
 function checkVaultArgs(folderPath, flags, useGlobal) {
     if (!fs.existsSync(folderPath) || !fs.statSync(folderPath).isDirectory()) {
-        printError(`Vault folder not found (or not a directory): ${folderPath}`);
-        throw new CliExit(1);
+        fail(`Vault folder not found (or not a directory): ${folderPath}`);
     }
     if (useGlobal) {
-        printError('hippo import --vault does not support --global (raw rows are tenant-local).');
-        throw new CliExit(1);
+        fail('hippo import --vault does not support --global (raw rows are tenant-local).');
     }
     if (!isStringFlag(flags['name']) || !flags['name'].trim()) {
         // --name keys the destructive source-deletion sync; a folder-basename default lets same-basename vaults clobber
         // each other, and a valueless `--name` (boolean true) would silently import under vault:true:*.
-        printError('hippo import --vault requires --name <vault> (a non-empty identity key for source-deletion sync).');
-        throw new CliExit(1);
+        fail('hippo import --vault requires --name <vault> (a non-empty identity key for source-deletion sync).');
     }
     if (flags['scope'] !== undefined && (!isStringFlag(flags['scope']) || !flags['scope'].trim())) {
-        // Same valueless-flag trap: a bare `--scope` must not become scope "true". The example uses the source-prefixed private form,
-        // since a bare `private` scope is not treated as private by recall and importVault rejects it.
-        printError('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
-        throw new CliExit(1);
+        // Same valueless-flag trap: a bare `--scope` must not become scope "true". The example uses the source-prefixed
+        // private form, since a bare `private` scope is not treated as private by recall and importVault rejects it.
+        fail('hippo import --vault: --scope requires a value (e.g. --scope vault:private:notes).');
     }
 }
 function printVaultSummary(vaultResult, folderPath, ctx, dryRun) {
@@ -272,8 +292,7 @@ function printVaultSummary(vaultResult, folderPath, ctx, dryRun) {
 function cmdPromote(hippoRoot, tenantId, id) {
     requireInit(hippoRoot);
     if (!id) {
-        printError('Usage: hippo promote <id>');
-        throw new CliExit(1);
+        fail('Usage: hippo promote <id>');
     }
     const ctx = cliApiContext(hippoRoot, tenantId);
     try {
@@ -282,8 +301,7 @@ function cmdPromote(hippoRoot, tenantId, id) {
         console.log(`   Global store: ${getGlobalRoot()}`);
     }
     catch (err) {
-        printError(`Failed to promote: ${errorMessage(err)}`);
-        throw new CliExit(1);
+        fail(`Failed to promote: ${errorMessage(err)}`);
     }
 }
 // Sync command
@@ -297,18 +315,17 @@ export function handleSync({ hippoRoot, flags }) {
     // v39: other-project rows are skipped by default; secrets always are.
     const includeCrossProject = flagIsTrue(flags, 'cross-project');
     const count = syncGlobalToLocal(hippoRoot, globalRoot, { includeCrossProject });
-    console.log(`Synced ${count} global memories into local project.${includeCrossProject ? '' : ' (other-project rows skipped; use --cross-project to ' +
-        'include them)'}`);
+    const skipNote = includeCrossProject ? '' : ' (other-project rows skipped; use --cross-project to include them)';
+    console.log(`Synced ${count} global memories into local project.${skipNote}`);
 }
-export async function handleWatch({ hippoRoot, tenantId, args }) {
-    const watchCmd = args.join(' ').trim();
-    await cmdWatch(watchCmd, hippoRoot, tenantId);
+export async function handleWatch({ hippoRoot, tenantId, args, flags }) {
+    const { argv, shell } = watchedCommand(args, flags);
+    await cmdWatch(argv, shell, hippoRoot, tenantId);
 }
 export async function handlePromote({ hippoRoot, tenantId, args }) {
     const id = args[0];
     if (!id) {
-        printError('Please provide a memory ID.');
-        throw new CliExit(1);
+        fail('Please provide a memory ID.');
     }
     const promoted = await runViaServerIfAvailable(hippoRoot, async (info, apiKey) => {
         try {
@@ -316,8 +333,7 @@ export async function handlePromote({ hippoRoot, tenantId, args }) {
             console.log(`Promoted ${id} to global store as ${result.globalId}`);
         }
         catch (err) {
-            printError(`Failed to promote: ${errorMessage(err)}`);
-            throw new CliExit(1);
+            fail(`Failed to promote: ${errorMessage(err)}`);
         }
     });
     if (promoted)
@@ -365,14 +381,12 @@ export async function handleShare({ hippoRoot, tenantId, args, flags }) {
                 console.log('Use --force to share anyway.');
             }
             else {
-                printError(`Memory not found: ${shareId}`);
-                throw new CliExit(1);
+                fail(`Memory not found: ${shareId}`);
             }
         }
     }
     else {
-        printError('Usage: hippo share <memory_id> [--force] or hippo share --auto [--dry-run]');
-        throw new CliExit(1);
+        fail('Usage: hippo share <memory_id> [--force] or hippo share --auto [--dry-run]');
     }
 }
 export function handlePeers({ tenantId, flags }) {
@@ -387,15 +401,16 @@ export function handlePeers({ tenantId, flags }) {
         const scopeLabel = allTenants ? 'global store (all tenants)' : `global store (tenant "${tenantScope}")`;
         console.log(`${peers.length} project${peers.length === 1 ? '' : 's'} contributing to ${scopeLabel}:\n`);
         for (const p of peers) {
-            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  (latest: ${p.latest.slice(0, DATE_PREFIX_CHARS)})`);
+            console.log(`  ${p.project.padEnd(25)} ${String(p.count).padStart(4)} memories  ` +
+                `(latest: ${p.latest.slice(0, DATE_PREFIX_CHARS)})`);
         }
     }
 }
-export function handleExport({ hippoRoot, tenantId, args, flags }) {
+export async function handleExport({ hippoRoot, tenantId, args, flags }) {
     requireInit(hippoRoot);
-    const format = String(flags['format'] || 'json');
+    const format = stringFlagOrExit(flags, 'format') || 'json';
     const outputPath = args[0] || null;
-    const entries = listMemories(cliApiContext(hippoRoot, tenantId));
+    const entries = await listMemories(cliApiContext(hippoRoot, tenantId));
     let output;
     if (format === 'markdown' || format === 'md') {
         output = entries.map(e => {

package/dist/cli/usage.d.ts

@@ -2,5 +2,5 @@ export declare function printAuditPruneUsage(): void;
 export declare function printSlackBackfillUsage(): void;
 export declare function printSlackWorkspacesUsage(): void;
 export declare const USAGE_HEADER = "\nHippo - Make your agent's memory work like a brain. Hippo is long-term memory for coding agents.\n\nUsage: hippo <command> [options]\n\nCommands:";
-export declare const USAGE_EXAMPLES = "\n\nExamples:\n  hippo init\n  hippo remember \"FRED cache can silently drop series\" --tag error\n  hippo recall \"data pipeline issues\" --budget 2000\n  hippo context --auto --budget 1500\n  hippo conflicts\n  hippo reject mem_abc123 --reason \"leaked credential\"\n  hippo reject --value \"never store my key again\" --reason \"secret\"\n  hippo rejections\n  hippo unreject a1b2c3d4e5f6\n  hippo dormant \"staging hostname\"\n  hippo dormant restore mem_abc123\n  hippo tokens --days 7\n  hippo session log --id sess_123 --task \"Ship feature\" --type progress --content \"Build is green, next step is docs\"\n  hippo session latest --json\n  hippo session resume\n  hippo snapshot save --task \"Ship feature\" --summary \"Tests are green\" --next-step \"Open the PR\" --session sess_123\n  hippo handoff create --summary \"PR is open, tests green\" --next \"Merge after review\" --session sess_123 --artifact src/foo.ts\n  hippo handoff create --summary s --constraint a --constraint b --outcome partial --target-runtime codex --card-id c1 --tests pass\n  hippo card create --title \"Add cards table\" --repo hippo --depends-on card_abc\n  hippo card claim card_abc --runtime codex\n  hippo card complete card_abc --outcome success\n  hippo card heartbeat card_abc --run 7\n  hippo card reclaim\n  hippo embed --status\n  hippo watch \"npm run build\"\n  hippo learn --git --days 30\n  hippo promote mem_abc123\n  hippo sync\n  hippo setup\n  hippo hook install claude-code\n  hippo decide \"Use PostgreSQL for new services\" --context \"JSONB support\"\n  hippo incident \"Prod outage: DB connection pool exhausted\" --context \"spike at 14:00\"\n  hippo process new \"Release\" --step \"run tests\" --step \"bump version\" --step \"publish\"\n  hippo policy new \"Data retention\" --text \"Delete logs after 90 days\" --from 2026-01-01\n  hippo policy asof 2026-03-01 --name \"Data retention\"\n  hippo skill new \"Run tests\" --instructions \"npm test before every commit\" --trigger \"before commit\"\n  hippo skill export\n  hippo brief new \"hippo\" --summary \"Agent-memory library; E2 first-class objects in progress\"\n  hippo brief refresh \"hippo\"\n  hippo note new \"Acme Corp\" --text \"Renewal call: wants SSO before Q3; champion is the VP Eng\"\n  hippo note list --customer \"Acme Corp\" --status active\n  hippo graph extract\n  hippo invalidate \"REST API\" --dry-run\n  hippo invalidate \"REST API\" --reason \"migrated to GraphQL\"\n  hippo invalidate --id mem_a1b2c3d4e5f6 --reason \"superseded by new policy\"\n  hippo invalidate --churn --dry-run\n  hippo export memories.json\n  hippo export --format markdown memories.md\n  hippo sleep --dry-run\n  hippo outcome --good\n  hippo status\n";
+export declare const USAGE_EXAMPLES = "\n\nExamples:\n  hippo init\n  hippo remember \"FRED cache can silently drop series\" --tag error\n  hippo recall \"data pipeline issues\" --budget 2000\n  hippo context --auto --budget 1500\n  hippo conflicts\n  hippo reject mem_abc123 --reason \"leaked credential\"\n  hippo reject --value \"never store my key again\" --reason \"secret\"\n  hippo rejections\n  hippo unreject a1b2c3d4e5f6\n  hippo dormant \"staging hostname\"\n  hippo dormant restore mem_abc123\n  hippo tokens --days 7\n  hippo session log --id sess_123 --task \"Ship feature\" --type progress --content \"Build is green, next step is docs\"\n  hippo session latest --json\n  hippo session resume\n  hippo snapshot save --task \"Ship feature\" --summary \"Tests are green\" --next-step \"Open the PR\" --session sess_123\n  hippo handoff create --summary \"PR is open, tests green\" --next \"Merge after review\" --session sess_123 --artifact src/foo.ts\n  hippo handoff create --summary s --constraint a --constraint b --outcome partial --target-runtime codex --card-id c1 --tests pass\n  hippo card create --title \"Add cards table\" --repo hippo --depends-on card_abc\n  hippo card claim card_abc --runtime codex\n  hippo card complete card_abc --outcome success\n  hippo card heartbeat card_abc --run 7\n  hippo card reclaim\n  hippo embed --status\n  hippo watch -- npm run build\n  hippo learn --git --days 30\n  hippo promote mem_abc123\n  hippo sync\n  hippo setup\n  hippo hook install claude-code\n  hippo decide \"Use PostgreSQL for new services\" --context \"JSONB support\"\n  hippo incident \"Prod outage: DB connection pool exhausted\" --context \"spike at 14:00\"\n  hippo process new \"Release\" --step \"run tests\" --step \"bump version\" --step \"publish\"\n  hippo policy new \"Data retention\" --text \"Delete logs after 90 days\" --from 2026-01-01\n  hippo policy asof 2026-03-01 --name \"Data retention\"\n  hippo skill new \"Run tests\" --instructions \"npm test before every commit\" --trigger \"before commit\"\n  hippo skill export\n  hippo brief new \"hippo\" --summary \"Agent-memory library; E2 first-class objects in progress\"\n  hippo brief refresh \"hippo\"\n  hippo note new \"Acme Corp\" --text \"Renewal call: wants SSO before Q3; champion is the VP Eng\"\n  hippo note list --customer \"Acme Corp\" --status active\n  hippo graph extract\n  hippo invalidate \"REST API\" --dry-run\n  hippo invalidate \"REST API\" --reason \"migrated to GraphQL\"\n  hippo invalidate --id mem_a1b2c3d4e5f6 --reason \"superseded by new policy\"\n  hippo invalidate --churn --dry-run\n  hippo export memories.json\n  hippo export --format markdown memories.md\n  hippo sleep --dry-run\n  hippo outcome --good\n  hippo status\n";
 //# sourceMappingURL=usage.d.ts.map

package/dist/cli/usage.js

@@ -50,7 +50,7 @@ Examples:
   hippo card heartbeat card_abc --run 7
   hippo card reclaim
   hippo embed --status
-  hippo watch "npm run build"
+  hippo watch -- npm run build
   hippo learn --git --days 30
   hippo promote mem_abc123
   hippo sync

package/dist/cli/verb-row.d.ts

@@ -18,6 +18,8 @@ export interface VerbRow {
     readonly aliases?: readonly string[];
     /** Runs in a request scope, opening each store once; set on api-backed verbs, as hook verbs open their own. */
     readonly scoped?: true;
+    /** Routine verbs after which a previously installed codex wrapper is repaired (never first-installed). */
+    readonly repairsCodexWrapper?: true;
     /** Deletes or hides memories: an unknown flag stops the run instead of being ignored. */
     readonly destructive?: true;
     /** Unset: --dry-run is honoured exactly when the verb declares it; `false` refuses it even so. */