hippo-memory 1.43.2 → 1.44.0

package/dist/cli.js

@@ -65,7 +65,8 @@ import { detectScope } from './scope.js';
 import { getGlobalRoot, initGlobal, shareMemory, listPeers, autoShare, transferScore, searchBothHybrid, syncGlobalToLocal, } from './shared.js';
 import { DAILY_TASK_NAME, buildDailyRunnerCommand, listRegisteredWorkspaces, registerWorkspace, runDailyMaintenance, } from './scheduler.js';
 import { importChatGPT, importClaude, importCursor, importGenericFile, importMarkdown, importVault, } from './importers.js';
-import { cmdCapture, cmdPreCompact, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
+import { cmdCapture, cmdPreCompact, resolveLastSessionTranscript, truncateCodePointSafe, sanitizeLogMessage } from './capture.js';
+import { readStdinBounded } from './stdin.js';
 import { auditMemories, appendAuditEvent, } from './audit.js';
 import { listApiKeys, revokeApiKey } from './auth.js';
 import { buildProvenanceCoverage } from './provenance-coverage.js';
@@ -143,6 +144,22 @@ function parseCountFlag(value) {
     const parsed = parseInt(String(value), 10);
     return Number.isFinite(parsed) && parsed >= 1 ? parsed : 0;
 }
+function parseBudgetFlag(value, fallback) {
+    if (value === undefined)
+        return fallback;
+    // A value-less flag and a junk value are different typos; the --hops guard already splits them.
+    if (typeof value !== 'string') {
+        console.error('--budget requires an integer value (e.g. --budget 1500).');
+        process.exit(1);
+    }
+    // Number(), like the --hops guard: parseInt('12abc') is 12, silently accepting what this message rejects.
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0) {
+        console.error(`Invalid --budget: "${value}". Must be a non-negative integer.`);
+        process.exit(1);
+    }
+    return parsed;
+}
 /**
  * Emit an audit event against `hippoRoot`'s db. Opens its own short-lived
  * connection so callers don't have to thread a db handle. Swallows all errors
@@ -233,10 +250,32 @@ async function runViaServerIfAvailable(hippoRoot, httpFn) {
         throw err;
     }
 }
-// Flags that NEVER take a value. Without this, a positional following the
-// flag is silently swallowed as its value (`invalidate --dry-run "X"` would
-// eat the pattern). Every existing --dry-run consumer reads it as boolean.
-const BOOLEAN_FLAGS = new Set(['dry-run']);
+// Every switch the CLI reads. A value on one reads as on under Boolean() (`--fix=false` would fix)
+// and as off under === true (`--pin=true` would not pin), so parseArgs and main() refuse one.
+// tests/cli-parse-flag-equals.test.ts fails when a switch read is missing from this set.
+export const BOOLEAN_FLAGS = new Set([
+    'all', 'all-tenants', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'continuity',
+    'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
+    'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
+    'help', 'include-superseded', 'inferred', 'json', 'last-session', 'multihop', 'no-hooks',
+    'no-learn', 'no-mmr', 'no-propagate', 'no-schedule', 'no-share', 'no-summarize-older',
+    'observed', 'open', 'physics', 'pin', 'pinned-only', 'reject-loser', 'rerank-utility',
+    'reset-physics', 'save-baseline', 'show-cases', 'stats', 'stdin',
+    'strict', 'suite', 'value-aware', 'verified', 'version', 'why',
+]);
+// Shared by both the separated and glued (`=`) forms so the list can't drift.
+function isRepeatableFlag(key) {
+    return key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on';
+}
+function pushRepeatableFlag(flags, key, value) {
+    if (Array.isArray(flags[key])) {
+        // SAFETY: Array.isArray just confirmed flags[key] is an array; the union has no other array member.
+        flags[key].push(value);
+    }
+    else {
+        flags[key] = [value];
+    }
+}
 export function parseArgs(argv) {
     const [, , command = '', ...rest] = argv;
     const args = [];
@@ -249,26 +288,43 @@ export function parseArgs(argv) {
             break;
         }
         if (part.startsWith('--')) {
+            const eqIdx = part.indexOf('=');
+            if (eqIdx > 2) {
+                // Glued form has no following token to swallow, so BOOLEAN_FLAGS gets its
+                // own branch here instead of the swallow-avoidance short-circuit below.
+                const key = part.slice(2, eqIdx);
+                const value = part.slice(eqIdx + 1);
+                if (BOOLEAN_FLAGS.has(key)) {
+                    flags[key] = value;
+                }
+                else if (isRepeatableFlag(key)) {
+                    if (value !== '')
+                        pushRepeatableFlag(flags, key, value);
+                }
+                else {
+                    flags[key] = value === '' ? true : value;
+                }
+                i++;
+                continue;
+            }
             const key = part.slice(2);
             const next = rest[i + 1];
-            if (!next || next.startsWith('--') || BOOLEAN_FLAGS.has(key)) {
+            if (BOOLEAN_FLAGS.has(key) && (next === 'true' || next === 'false')) {
+                // Kept as a value so main() rejects it, instead of `--pin true` pinning the text "... true".
+                flags[key] = next;
+                i += 2;
+            }
+            else if (!next || next.startsWith('--') || BOOLEAN_FLAGS.has(key)) {
                 // Boolean flag
                 flags[key] = true;
                 i++;
             }
+            else if (isRepeatableFlag(key)) {
+                pushRepeatableFlag(flags, key, next);
+                i += 2;
+            }
             else {
-                // Check if it's a repeatable flag (tag, artifact, link, step, constraint, depends-on)
-                if (key === 'tag' || key === 'artifact' || key === 'link' || key === 'step' || key === 'constraint' || key === 'depends-on') {
-                    if (Array.isArray(flags[key])) {
-                        flags[key].push(next);
-                    }
-                    else {
-                        flags[key] = [next];
-                    }
-                }
-                else {
-                    flags[key] = next;
-                }
+                flags[key] = next;
                 i += 2;
             }
         }
@@ -768,7 +824,7 @@ function cmdSupersede(hippoRoot, oldId, newContent, flags) {
 }
 async function cmdRecall(hippoRoot, query, flags) {
     requireInit(hippoRoot);
-    const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 4000);
     const limit = parseLimitFlag(flags['limit']);
     const asJson = Boolean(flags['json']);
     const showWhy = Boolean(flags['why']);
@@ -1895,7 +1951,7 @@ async function cmdRecall(hippoRoot, query, flags) {
 }
 async function cmdExplain(hippoRoot, query, flags) {
     requireInit(hippoRoot);
-    const budget = parseInt(String(flags['budget'] ?? '4000'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 4000);
     const limit = parseLimitFlag(flags['limit']);
     const asJson = Boolean(flags['json']);
     const forcePhysics = Boolean(flags['physics']);
@@ -2776,7 +2832,7 @@ function cmdLastSleep(flags) {
 // X8: session-event content is capped at print time only — the shared
 // printSessionEvents stays untouched for every other caller.
 const COMPACT_RESUME_EVENT_CONTENT_CAP = 400;
-function cmdCompactResume(hippoRoot, stdinText) {
+function cmdCompactResume(hippoRoot, stdinText, stdinTimedOut) {
     try {
         // X3: gate on the non-exiting isInitialized check before any
         // store-opening call (loadActiveTaskSnapshot/listSessionEvents both
@@ -2791,7 +2847,9 @@ function cmdCompactResume(hippoRoot, stdinText) {
         // carries a different source (e.g. 'startup') means the matcher-based
         // gate failed to apply — stay silent rather than print stale state.
         const nonEmptyStdin = !!stdinText && stdinText.trim() !== '';
-        let suppressOutput = false;
+        // Without a payload session_id the X5 cross-restore guard below can
+        // never fire, so a timed-out empty read must not reach the print path.
+        let suppressOutput = stdinTimedOut && !nonEmptyStdin;
         let payloadSessionId = null;
         if (nonEmptyStdin) {
             let payload = null;
@@ -2872,30 +2930,23 @@ function cmdCompactResume(hippoRoot, stdinText) {
  */
 async function cmdSessionEnd(hippoRoot, flags) {
     const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : null;
-    // Read stdin synchronously. The SessionEnd hook payload carries
-    // `transcript_path` as JSON; we extract it here and pass it to the worker
-    // via argv so the detached child doesn't need to inherit stdin.
-    // DF1 T3 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md): `session_id`
-    // is extracted the same way, so the worker can close the ending session's
-    // own active task snapshot after sleep+capture finish.
-    let transcriptPath = null;
+    // Bounded read (DF1 T3, docs/plans/2026-08-23-df1-snapshot-lifecycle.md):
+    // extracts transcript_path + session_id for the detached worker's argv.
     let sessionId = null;
+    const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
     try {
-        const stdinText = fs.readFileSync(0, 'utf8');
         if (stdinText && stdinText.trim().startsWith('{')) {
             const payload = JSON.parse(stdinText);
-            if (typeof payload.transcript_path === 'string') {
-                transcriptPath = payload.transcript_path;
-            }
             if (typeof payload.session_id === 'string') {
                 sessionId = payload.session_id;
             }
         }
     }
     catch {
-        // No stdin, not JSON, or read failure — capture will fall back to
-        // transcript auto-discovery; the snapshot close below will no-op.
+        // No stdin, not JSON, or read failure: the snapshot close below will no-op.
     }
+    // Resolved here because only this process saw the payload; the worker captures just the path it is handed.
+    const transcriptPath = resolveLastSessionTranscript(undefined, stdinText, stdinTimedOut);
     const workerArgs = [process.argv[1], '__session-end-worker'];
     if (logFile)
         workerArgs.push('--log-file', logFile);
@@ -2912,11 +2963,11 @@ async function cmdSessionEnd(hippoRoot, flags) {
         child.unref();
     }
     catch (err) {
-        // If spawn fails, run inline as a last resort — better late output than
-        // no consolidation at all. NOTE: `flags` carries neither --transcript nor
-        // --session-id (both are stdin-derived, argv-only for the child), so in
-        // this fallback capture auto-discovers the transcript and the DF1
-        // snapshot close no-ops — the ambient freshness bound is the backstop.
+        // If spawn fails, run inline as a last resort, handed what the child's argv would have carried.
+        if (transcriptPath)
+            flags['transcript'] = transcriptPath;
+        if (sessionId)
+            flags['session-id'] = sessionId;
         await cmdSessionEndWorker(hippoRoot, flags);
         return;
     }
@@ -2959,19 +3010,22 @@ async function cmdSessionEndWorker(hippoRoot, flags) {
         // `[hippo] sleep failed: ...` line. Continue to capture regardless.
     }
     try {
-        const captureOpts = {
-            source: 'last-session',
-            transcriptPath: typeof flags['transcript'] === 'string'
-                ? flags['transcript']
-                : undefined,
-            logFile: typeof flags['log-file'] === 'string'
-                ? flags['log-file']
-                : undefined,
-            dryRun: false,
-            global: false,
-            tenantId: resolveTenantId({}),
-        };
-        cmdCapture(hippoRoot, captureOpts);
+        const logFile = typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined;
+        const transcriptPath = typeof flags['transcript'] === 'string' ? flags['transcript'] : undefined;
+        // With no stdin of its own, capture would read this as a manual run and scan every project.
+        if (!transcriptPath) {
+            appendSessionEndCloseLog(logFile ?? null, 'skip capture: no transcript for this session');
+        }
+        else {
+            cmdCapture(hippoRoot, {
+                source: 'last-session',
+                transcriptPath,
+                logFile,
+                dryRun: false,
+                global: false,
+                tenantId: resolveTenantId({}),
+            });
+        }
     }
     catch {
         // Same treatment — the failure line is already in the log.
@@ -3154,6 +3208,11 @@ async function cmdCodexSessionEndWorker(hippoRoot, flags) {
             startOffsetBytes,
             startedAtMs,
         }) ?? undefined;
+        // No Codex transcript must not fall through to the scan of Claude Code projects.
+        if (!transcriptPath) {
+            appendSessionEndCloseLog(logFile ?? null, 'skip capture: no Codex transcript for this session');
+            return;
+        }
         const captureOpts = {
             source: 'last-session',
             transcriptPath,
@@ -4122,10 +4181,8 @@ function cmdCard(hippoRoot, args, flags) {
         const allowedFlags = CARD_SUBCOMMAND_FLAGS[subcommand];
         for (const key of Object.keys(flags)) {
             if (!allowedFlags.includes(key)) {
-                // --flag=value never splits on '=' (see parseArgs), so it lands here as one long key.
-                const hint = key.includes('=') ? ` Use --${key.slice(0, key.indexOf('='))} <value>, not --${key}.` : '';
                 const valid = allowedFlags.length > 0 ? allowedFlags.map((f) => `--${f}`).join(', ') : '(none)';
-                console.error(`Unknown flag --${key} for hippo card ${subcommand}.${hint} Valid flags: ${valid}`);
+                console.error(`Unknown flag --${key} for hippo card ${subcommand}. Valid flags: ${valid}`);
                 process.exit(1);
             }
         }
@@ -5915,7 +5972,7 @@ async function cmdContext(hippoRoot, args, flags, stdinText) {
     if (!pinnedOnly) {
         requireInit(hippoRoot);
     }
-    const budget = parseInt(String(flags['budget'] ?? '1500'), 10);
+    const budget = parseBudgetFlag(flags['budget'], 1500);
     if (budget <= 0)
         return;
     // Resolve query: explicit args, --auto (git diff via CLI-side helper), or
@@ -7242,7 +7299,8 @@ function cmdDag(hippoRoot, flags) {
 }
 function cmdAssemble(hippoRoot, sessionId, flags) {
     requireInit(hippoRoot);
-    const budget = typeof flags['budget'] === 'string' ? Number(flags['budget']) : undefined;
+    // Absent stays undefined so the api default applies; the 0 fallback is unreachable.
+    const budget = flags['budget'] === undefined ? undefined : parseBudgetFlag(flags['budget'], 0);
     const freshTailCount = typeof flags['fresh-tail'] === 'string' ? Number(flags['fresh-tail']) : undefined;
     const summarizeOlder = flags['no-summarize-older'] !== true;
     const scope = typeof flags['scope'] === 'string' && flags['scope'].length > 0
@@ -7273,7 +7331,8 @@ function cmdAssemble(hippoRoot, sessionId, flags) {
 function cmdDrillDown(hippoRoot, summaryId, flags) {
     requireInit(hippoRoot);
     const limit = typeof flags['limit'] === 'string' ? Number(flags['limit']) : undefined;
-    const budget = typeof flags['budget'] === 'string' ? Number(flags['budget']) : undefined;
+    // Absent stays undefined so the api default applies; the 0 fallback is unreachable.
+    const budget = flags['budget'] === undefined ? undefined : parseBudgetFlag(flags['budget'], 0);
     // v0.30 / E5: --depth N walks N levels down (default 1, hard cap 10).
     // L4 fold: reject out-of-range explicitly (no silent clamp).
     const rawDepth = typeof flags['depth'] === 'string' ? Number(flags['depth']) : undefined;
@@ -8603,6 +8662,29 @@ async function main() {
         console.error('--scope requires a non-empty value (e.g. --scope slack:private:C1).');
         process.exit(1);
     }
+    // parseArgs stores a value-less flag as boolean true, and NaN then survives every
+    // downstream guard because each comparison against it is false.
+    const NUMERIC_FLAGS = [
+        'days', 'threshold', 'min-score', 'port', 'limit', 'mmr-lambda', 'local-bump',
+        'min-results', 'reranker-top-k', 'min-mrr', 'embedding-weight', 'max-cases',
+    ];
+    for (const key of NUMERIC_FLAGS) {
+        const raw = flags[key];
+        if (raw === undefined)
+            continue;
+        if (typeof raw !== 'string' || !raw.trim() || !Number.isFinite(Number(raw))) {
+            console.error(`--${key} requires a numeric value.`);
+            process.exit(1);
+        }
+    }
+    // Reject rather than coerce: consumers read --dry-run both as Boolean() and === true,
+    // so no single coercion of an inline value would be correct for every one of them.
+    for (const key of BOOLEAN_FLAGS) {
+        if (Object.hasOwn(flags, key) && typeof flags[key] !== 'boolean') {
+            console.error(`--${key} takes no value`);
+            process.exit(1);
+        }
+    }
     switch (command) {
         case 'init':
             cmdInit(hippoRoot, flags);
@@ -8747,34 +8829,18 @@ async function main() {
             await cmdSessionEndWorker(hippoRoot, flags);
             break;
         case 'pre-compact': {
-            // Same TTY guard as `capture --last-session`: skip reading stdin when
-            // it's an interactive terminal so a manual invocation never hangs.
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
+            // Bounded wait, not a TTY guard: an idle non-TTY pipe must not hang.
+            const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
             await cmdPreCompact(hippoRoot, {
                 stdinText,
+                stdinTimedOut,
                 logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
             });
             break;
         }
         case 'compact-resume': {
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
-            cmdCompactResume(hippoRoot, stdinText);
+            const { text: stdinText, timedOut: stdinTimedOut } = await readStdinBounded();
+            cmdCompactResume(hippoRoot, stdinText, stdinTimedOut);
             break;
         }
         case 'codex-run':
@@ -8987,23 +9053,9 @@ async function main() {
             break;
         }
         case 'context': {
-            // DF1 T2 (docs/plans/2026-08-23-df1-snapshot-lifecycle.md): same TTY
-            // guard as `pre-compact` / `compact-resume` above — skip reading stdin
-            // when it's an interactive terminal so a manual invocation never
-            // hangs. `hippo context` is both the hot UserPromptSubmit path
-            // (non-TTY, stdin carries the hook JSON with `session_id`) and a
-            // manually-invocable command (TTY, no payload) — the guardless read in
-            // cmdSessionEnd is the wrong sibling to copy here; it only runs under
-            // a hook that always supplies stdin.
-            let stdinText;
-            if (!process.stdin.isTTY) {
-                try {
-                    stdinText = fs.readFileSync(0, 'utf8');
-                }
-                catch {
-                    stdinText = undefined;
-                }
-            }
+            // Bounded, not a TTY guard (DF1 T2, docs/plans/2026-08-23-df1-snapshot-lifecycle.md):
+            // the hot stdin path and a manual run share this one command.
+            const { text: stdinText } = await readStdinBounded();
             await cmdContext(hippoRoot, args, flags, stdinText);
             break;
         }
@@ -9180,10 +9232,17 @@ async function main() {
                 console.error('Usage: hippo capture --stdin|--file <path>|--last-session [--transcript <path>] [--log-file <path>] [--dry-run] [--global]');
                 process.exit(1);
             }
+            // Bounded, and only when last-session has no explicit path: the
+            // --stdin source keeps its own blocking read in capture.ts by design.
+            const bounded = captureSource === 'last-session' && !transcriptPath
+                ? await readStdinBounded()
+                : { text: undefined, timedOut: false };
             cmdCapture(hippoRoot, {
                 source: captureSource,
                 filePath: captureFile,
                 transcriptPath,
+                stdinText: bounded.text,
+                stdinTimedOut: bounded.timedOut,
                 logFile: typeof flags['log-file'] === 'string' ? flags['log-file'] : undefined,
                 dryRun: Boolean(flags['dry-run']),
                 global: Boolean(flags['global']),
@@ -9242,8 +9301,8 @@ async function main() {
             }
             const onlyId = typeof flags['id'] === 'string' ? flags['id'] : undefined;
             if (typeof flags['dry-run'] === 'string') {
-                // Unreachable via argv (dry-run is in BOOLEAN_FLAGS); guards
-                // programmatically-built flags objects.
+                // Dead: the earlier global BOOLEAN_FLAGS guard now exits first on any --dry-run=<v>.
+                // Kept as defence in depth on a destructive command.
                 console.error('--dry-run takes no value');
                 process.exit(1);
             }