hippo-memory 1.69.0 → 1.70.0

package/dist/cli.js

@@ -33,7 +33,7 @@
  *   hippo decide "<decision>" [--context "<why>"] [--supersedes <id>]
  *   hippo wm <push|read|clear|flush>
  */
-import { envSkipAutoIntegrations } from './env.js';
+import { envSkipAutoIntegrations } from './util/env.js';
 import * as path from 'path';
 import * as fs from 'fs';
 import { fileURLToPath } from 'node:url';
@@ -41,41 +41,14 @@ 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 { errorFields, errorMessage, isLevelEnabled, log } from './util/log.js';
 import { isStoreBusy, STORE_BUSY_MESSAGE } from './db/busy.js';
+import { boolFlag, flagIsTrue } from './cli/flag-values.js';
 import { VERB_USAGE, USAGE_HEADER, USAGE_EXAMPLES, printAuditPruneUsage, printSlackBackfillUsage, printSlackWorkspacesUsage } from './cli/usage.js';
+import { VERB_FLAGS, flagKind, isKnownFlag, undeclaredFlags } from './cli/flags.js';
 // ---------------------------------------------------------------------------
 // Helpers
 // ---------------------------------------------------------------------------
-// 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([
-    'agents', 'all', 'all-tenants', 'apply', 'archive', 'auto', 'bad', 'bootstrap', 'classic', 'churn', 'continuity',
-    'cross-project', 'dry-run', 'equal-sources', 'error', 'evc-adaptive', 'extract',
-    'filter-conflicts', 'fix', 'force', 'forget', 'git', 'global', 'good', 'graph-stream',
-    'help', 'include-logs', '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', 'turn', 'value-aware', 'verified', 'version', 'why',
-]);
-// Every flag some command reads. Anything else is a typo that no command would act on.
-export const KNOWN_FLAGS = new Set([
-    ...BOOLEAN_FLAGS,
-    'actual', 'artifact', 'artifact-ref', 'as-of', 'author', 'baseline', 'body', 'budget', 'card-id',
-    'change', 'channel', 'chatgpt', 'class', 'claude', 'codex-home', 'compare', 'constraint', 'content',
-    'context', 'contract', 'cursor', 'customer', 'days', 'depends-on', 'depth', 'description',
-    'embedding-weight', 'entity', 'estimate', 'file', 'format', 'framing', 'fresh-tail', 'from', 'goal',
-    'graph-hops', 'graph-seeds', 'history-path', 'hops', 'host', 'id', 'importance', 'include-recent',
-    'instructions', 'keep', 'kind', 'label', 'layer', 'level', 'limit', 'link', 'local-bump', 'log-file',
-    'markdown', 'max', 'max-cases', 'max-neighbors', 'min-mrr', 'min-results', 'min-score', 'mmr-lambda',
-    'model', 'name', 'next', 'next-step', 'note', 'older-than', 'op', 'out', 'outcome', 'owner', 'parent',
-    'path', 'policy', 'port', 'reason', 'repo', 'repos', 'reranker', 'reranker-top-k', 'resolution',
-    'role', 'run', 'runtime', 'salience-threshold', 'scan', 'scope', 'session', 'session-id', 'since',
-    'source', 'start-offset', 'started-at', 'state', 'status', 'step', 'steps', 'success', 'summary',
-    'supersedes', 'tag', 'target', 'target-runtime', 'task', 'team', 'tenant', 'tenant-id', 'tests',
-    'text', 'threshold', 'title', 'to', 'transcript', 'trigger', 'type', 'unit', 'value', 'vault',
-]);
 // Commands that delete or hide memories: an unknown flag here stops the run instead of being ignored.
 const DESTRUCTIVE_COMMANDS = new Set([
     'audit', 'dedup', 'forget', 'invalidate', 'projects', 'reject', 'resolve', 'sleep', 'supersede',
@@ -88,17 +61,13 @@ const DRY_RUN_COMMANDS = new Set([
 function dryRunRefusal(command, args, flags) {
     const isBrief = command === 'brief' || command === 'project-brief';
     const onlyForm = command === 'share' ? 'share --auto' : isBrief ? `${command} refresh` : null;
-    const honoured = command === 'share' ? args[0] === '--auto' || Boolean(flags['auto'])
+    const honoured = command === 'share' ? args[0] === '--auto' || boolFlag(flags, 'auto')
         : isBrief ? args[0] === 'refresh' : DRY_RUN_COMMANDS.has(command);
     if (honoured)
         return null;
     const where = onlyForm ? ` outside \`hippo ${onlyForm}\`` : '';
     return `hippo ${command} has no --dry-run${where}, so it would run for real. Nothing was changed.`;
 }
-// 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.
@@ -108,10 +77,43 @@ function pushRepeatableFlag(flags, key, value) {
         flags[key] = [value];
     }
 }
+function setGluedFlag(flags, key, value, kind) {
+    // Glued form has no following token to swallow, so a switch gets its
+    // own branch here instead of the swallow-avoidance short-circuit in setSeparatedFlag.
+    if (kind === 'switch') {
+        flags[key] = value;
+    }
+    else if (kind === 'list') {
+        if (value !== '')
+            pushRepeatableFlag(flags, key, value);
+    }
+    else {
+        flags[key] = value === '' ? true : value;
+    }
+}
+/** Returns how many tokens the flag consumed: its own, plus `next` when that is its value. */
+function setSeparatedFlag(flags, key, next, kind) {
+    if (kind === 'switch' && (next === 'true' || next === 'false')) {
+        // Kept as a value so main() rejects it, instead of `--pin true` pinning the text "... true".
+        flags[key] = next;
+        return 2;
+    }
+    if (!next || next.startsWith('--') || kind === 'switch') {
+        // Boolean flag
+        flags[key] = true;
+        return 1;
+    }
+    if (kind === 'list')
+        pushRepeatableFlag(flags, key, next);
+    else
+        flags[key] = next;
+    return 2;
+}
 export function parseArgs(argv) {
     const [, , command = '', ...rest] = argv;
     const args = [];
     const flags = {};
+    const declared = COMMAND_INDEX.get(command)?.flags;
     let i = 0;
     while (i < rest.length) {
         const part = rest[i];
@@ -121,43 +123,13 @@ export function parseArgs(argv) {
         }
         if (part.startsWith('--')) {
             const eqIdx = part.indexOf('=');
+            const key = part.slice(2, eqIdx > 2 ? eqIdx : undefined);
             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 (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;
+                setGluedFlag(flags, key, part.slice(eqIdx + 1), flagKind(declared, key));
                 i++;
             }
-            else if (isRepeatableFlag(key)) {
-                pushRepeatableFlag(flags, key, next);
-                i += 2;
-            }
             else {
-                flags[key] = next;
-                i += 2;
+                i += setSeparatedFlag(flags, key, rest[i + 1], flagKind(declared, key));
             }
         }
         else if (part === '-h') {
@@ -178,7 +150,7 @@ export function shouldAutoRepairCodexWrapper(currentCommand, flags) {
     if (!['context', 'remember', 'recall', 'sleep', 'capture', 'outcome', 'status', 'init'].includes(currentCommand)) {
         return false;
     }
-    if (currentCommand === 'init' && flags['no-hooks'] === true)
+    if (currentCommand === 'init' && flagIsTrue(flags, 'no-hooks'))
         return false;
     return true;
 }
@@ -193,8 +165,8 @@ function maybeRepairCodexWrapper(currentCommand, flags) {
     try {
         repairCodexWrapperIfInstalled();
     }
-    catch {
-        // best-effort only
+    catch (err) {
+        log.debug(`codex wrapper not repaired: ${errorMessage(err)}`);
     }
 }
 /** Every verb main() dispatches, keyed by name, with its handler, aliases and help blocks. */
@@ -202,332 +174,410 @@ export const COMMANDS = {
     init: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/init.js')).cmdInit(hippoRoot, flags); },
         usage: VERB_USAGE.init,
+        flags: VERB_FLAGS.init,
     },
     remember: {
         run: async (c) => { await (await import('./cli/remember.js')).handleRemember(c); },
         usage: VERB_USAGE.remember,
+        flags: VERB_FLAGS.remember,
     },
     recall: {
         run: async (c) => { await (await import('./cli/recall.js')).handleRecall(c); },
         scoped: true,
         usage: VERB_USAGE.recall,
+        flags: VERB_FLAGS.recall,
     },
     drill: {
         run: async (c) => { await (await import('./cli/dag.js')).handleDrill(c); },
         scoped: true,
         usage: VERB_USAGE.drill,
+        flags: VERB_FLAGS.drill,
     },
     assemble: {
         run: async (c) => { await (await import('./cli/dag.js')).handleAssemble(c); },
         scoped: true,
         usage: VERB_USAGE.assemble,
+        flags: VERB_FLAGS.assemble,
     },
     supersede: {
         run: async (c) => { await (await import('./cli/remember.js')).handleSupersede(c); },
         usage: VERB_USAGE.supersede,
+        flags: VERB_FLAGS.supersede,
     },
     explain: {
         run: async (c) => { await (await import('./cli/explain.js')).handleExplain(c); },
         scoped: true,
         usage: VERB_USAGE.explain,
+        flags: VERB_FLAGS.explain,
     },
     eval: {
         run: async (c) => { await (await import('./cli/eval.js')).handleEval(c); },
         usage: VERB_USAGE.eval,
+        flags: VERB_FLAGS.eval,
     },
     trace: {
         run: async (c) => { await (await import('./cli/remember.js')).handleTrace(c); },
         usage: VERB_USAGE.trace,
+        flags: VERB_FLAGS.trace,
     },
     refine: {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/maintenance.js')).cmdRefine(hippoRoot, flags); },
         usage: VERB_USAGE.refine,
+        flags: VERB_FLAGS.refine,
     },
     sleep: {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/sleep.js')).cmdSleep(hippoRoot, flags); },
         scoped: true,
         usage: VERB_USAGE.sleep,
+        flags: VERB_FLAGS.sleep,
     },
     'last-sleep': {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/last-sleep.js')).cmdLastSleep(hippoRoot, flags); },
         usage: VERB_USAGE['last-sleep'],
+        flags: VERB_FLAGS['last-sleep'],
     },
     'session-end': {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/session-hooks.js')).cmdSessionEnd(hippoRoot, flags); },
         usage: VERB_USAGE['session-end'],
+        flags: VERB_FLAGS['session-end'],
     },
     '__session-end-worker': {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/session-hooks.js')).cmdSessionEndWorker(hippoRoot, flags); },
         usage: [],
+        flags: VERB_FLAGS['__session-end-worker'],
     },
     'pre-compact': {
         run: async (c) => { await (await import('./cli/session-hooks.js')).handlePreCompact(c); },
         usage: VERB_USAGE['pre-compact'],
+        flags: VERB_FLAGS['pre-compact'],
     },
     'post-compact': {
         run: async (c) => { await (await import('./cli/session-hooks.js')).handlePostCompact(c); },
         usage: VERB_USAGE['post-compact'],
+        flags: VERB_FLAGS['post-compact'],
     },
     'capture-error': {
         run: async (c) => { await (await import('./cli/session-hooks.js')).handleCaptureError(c); },
         usage: VERB_USAGE['capture-error'],
+        flags: VERB_FLAGS['capture-error'],
     },
     'compact-resume': {
         run: async (c) => { await (await import('./cli/session-hooks.js')).handleCompactResume(c); },
         usage: VERB_USAGE['compact-resume'],
+        flags: VERB_FLAGS['compact-resume'],
     },
     'codex-run': {
         run: async ({ hippoRoot, args }) => { (await import('./cli/session-hooks.js')).cmdCodexRun(hippoRoot, args); },
         usage: VERB_USAGE['codex-run'],
+        flags: VERB_FLAGS['codex-run'],
     },
     '__codex-session-end-worker': {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/session-hooks.js')).cmdCodexSessionEndWorker(hippoRoot, flags); },
         usage: [],
+        flags: VERB_FLAGS['__codex-session-end-worker'],
     },
     dedup: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/maintenance.js')).cmdDedup(hippoRoot, flags); },
         usage: VERB_USAGE.dedup,
+        flags: VERB_FLAGS.dedup,
     },
     dag: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/dag.js')).cmdDag(hippoRoot, flags); },
         usage: VERB_USAGE.dag,
+        flags: VERB_FLAGS.dag,
     },
     auth: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/auth.js')).cmdAuth(hippoRoot, args, flags); },
         scoped: true,
         usage: VERB_USAGE.auth,
+        flags: VERB_FLAGS.auth,
     },
     goal: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/goals.js')).cmdGoal(hippoRoot, args, flags); },
         scoped: true,
         usage: VERB_USAGE.goal,
+        flags: VERB_FLAGS.goal,
     },
     slack: {
-        run: async ({ hippoRoot, args, flags }) => { (await import('./cli/slack.js')).cmdSlack(hippoRoot, args, flags); },
+        run: async ({ hippoRoot, args, flags }) => { await (await import('./cli/slack.js')).cmdSlack(hippoRoot, args, flags); },
         usage: VERB_USAGE.slack,
+        flags: VERB_FLAGS.slack,
     },
     github: {
         run: async ({ hippoRoot, args, flags }) => { await cmdGithub(hippoRoot, args, flags); },
         usage: VERB_USAGE.github,
+        flags: VERB_FLAGS.github,
     },
     audit: {
         run: async (c) => { await (await import('./cli/audit.js')).handleAudit(c); },
         scoped: true,
         usage: VERB_USAGE.audit,
+        flags: VERB_FLAGS.audit,
     },
     'correction-latency': {
         run: async (c) => { await (await import('./cli/status.js')).handleCorrectionLatency(c); },
         usage: VERB_USAGE['correction-latency'],
+        flags: VERB_FLAGS['correction-latency'],
     },
     provenance: {
         run: async (c) => { await (await import('./cli/status.js')).handleProvenance(c); },
         usage: VERB_USAGE.provenance,
+        flags: VERB_FLAGS.provenance,
     },
     status: {
         run: async ({ hippoRoot }) => { (await import('./cli/status.js')).cmdStatus(hippoRoot); },
         usage: VERB_USAGE.status,
+        flags: VERB_FLAGS.status,
     },
     outcome: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/curate.js')).cmdOutcome(hippoRoot, flags); },
         scoped: true,
         usage: VERB_USAGE.outcome,
+        flags: VERB_FLAGS.outcome,
     },
     conflicts: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/curate.js')).cmdConflicts(hippoRoot, flags); },
         usage: VERB_USAGE.conflicts,
+        flags: VERB_FLAGS.conflicts,
     },
     resolve: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdResolve(hippoRoot, args, flags); },
         usage: VERB_USAGE.resolve,
+        flags: VERB_FLAGS.resolve,
     },
     reject: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdReject(hippoRoot, args, flags); },
         usage: VERB_USAGE.reject,
+        flags: VERB_FLAGS.reject,
     },
     rejections: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/curate.js')).cmdRejections(hippoRoot, flags); },
         usage: VERB_USAGE.rejections,
+        flags: VERB_FLAGS.rejections,
     },
     unreject: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdUnreject(hippoRoot, args, flags); },
         usage: VERB_USAGE.unreject,
+        flags: VERB_FLAGS.unreject,
     },
     dormant: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdDormant(hippoRoot, args, flags); },
         scoped: true,
         usage: VERB_USAGE.dormant,
+        flags: VERB_FLAGS.dormant,
     },
     projects: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/projects.js')).cmdProjects(hippoRoot, args, flags); },
         usage: VERB_USAGE.projects,
+        flags: VERB_FLAGS.projects,
     },
     quarantine: {
-        run: async ({ hippoRoot, args, flags }) => { (await import('./cli/curate.js')).cmdQuarantine(hippoRoot, args, flags); },
+        run: async ({ hippoRoot, args, flags }) => { await (await import('./cli/curate.js')).cmdQuarantine(hippoRoot, args, flags); },
         scoped: true,
         usage: VERB_USAGE.quarantine,
+        flags: VERB_FLAGS.quarantine,
     },
     tokens: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/status.js')).cmdTokens(hippoRoot, flags); },
         scoped: true,
         usage: VERB_USAGE.tokens,
+        flags: VERB_FLAGS.tokens,
     },
     failures: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/status.js')).cmdFailures(hippoRoot, flags); },
         scoped: true,
         usage: VERB_USAGE.failures,
+        flags: VERB_FLAGS.failures,
     },
     doctor: {
         run: async (c) => { await (await import('./cli/status.js')).handleDoctor(c); },
         usage: VERB_USAGE.doctor,
+        flags: VERB_FLAGS.doctor,
     },
     'support-bundle': {
         run: async (c) => { await (await import('./cli/status.js')).handleSupportBundle(c); },
         usage: VERB_USAGE['support-bundle'],
+        flags: VERB_FLAGS['support-bundle'],
     },
     snapshot: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/continuity.js')).cmdSnapshot(hippoRoot, args, flags); },
         usage: VERB_USAGE.snapshot,
+        flags: VERB_FLAGS.snapshot,
     },
     session: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/continuity.js')).cmdSession(hippoRoot, args, flags); },
         usage: VERB_USAGE.session,
+        flags: VERB_FLAGS.session,
     },
     handoff: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/continuity.js')).cmdHandoff(hippoRoot, args, flags); },
         usage: VERB_USAGE.handoff,
+        flags: VERB_FLAGS.handoff,
     },
     card: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/card.js')).cmdCard(hippoRoot, args, flags); },
         usage: VERB_USAGE.card,
+        flags: VERB_FLAGS.card,
     },
     predict: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/decisions.js')).cmdPredict(hippoRoot, args, flags); },
         usage: VERB_USAGE.predict,
+        flags: VERB_FLAGS.predict,
     },
     current: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/continuity.js')).cmdCurrent(hippoRoot, args, flags); },
         usage: VERB_USAGE.current,
+        flags: VERB_FLAGS.current,
     },
     forget: {
         run: async (c) => { await (await import('./cli/curate.js')).handleForget(c); },
         scoped: true,
         usage: VERB_USAGE.forget,
+        flags: VERB_FLAGS.forget,
     },
     inspect: {
         run: async (c) => { await (await import('./cli/status.js')).handleInspect(c); },
         usage: VERB_USAGE.inspect,
+        flags: VERB_FLAGS.inspect,
     },
     context: {
         run: async (c) => { await (await import('./cli/context.js')).handleContext(c); },
         usage: VERB_USAGE.context,
+        flags: VERB_FLAGS.context,
     },
     hook: {
         run: async ({ args }) => { (await import('./cli/setup.js')).cmdHook(args); },
         usage: VERB_USAGE.hook,
+        flags: VERB_FLAGS.hook,
     },
     setup: {
         run: async ({ flags }) => { (await import('./cli/setup.js')).cmdSetup(flags); },
         usage: VERB_USAGE.setup,
+        flags: VERB_FLAGS.setup,
     },
     'daily-runner': {
         run: async () => { (await import('./cli/setup.js')).cmdDailyRunner(); },
         usage: VERB_USAGE['daily-runner'],
+        flags: VERB_FLAGS['daily-runner'],
     },
     embed: {
         run: async ({ hippoRoot, flags }) => { await (await import('./cli/maintenance.js')).cmdEmbed(hippoRoot, flags); },
         usage: VERB_USAGE.embed,
+        flags: VERB_FLAGS.embed,
     },
     watch: {
         run: async (c) => { await (await import('./cli/transfer.js')).handleWatch(c); },
         usage: VERB_USAGE.watch,
+        flags: VERB_FLAGS.watch,
     },
     learn: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/transfer.js')).cmdLearn(hippoRoot, flags); },
         scoped: true,
         usage: VERB_USAGE.learn,
+        flags: VERB_FLAGS.learn,
     },
     promote: {
         run: async (c) => { await (await import('./cli/transfer.js')).handlePromote(c); },
         scoped: true,
         usage: VERB_USAGE.promote,
+        flags: VERB_FLAGS.promote,
     },
     sync: {
         run: async ({ hippoRoot, flags }) => { (await import('./cli/transfer.js')).cmdSync(hippoRoot, flags); },
         usage: VERB_USAGE.sync,
+        flags: VERB_FLAGS.sync,
     },
     share: {
         run: async (c) => { await (await import('./cli/transfer.js')).handleShare(c); },
         usage: VERB_USAGE.share,
+        flags: VERB_FLAGS.share,
     },
     peers: {
         run: async (c) => { await (await import('./cli/transfer.js')).handlePeers(c); },
         usage: VERB_USAGE.peers,
+        flags: VERB_FLAGS.peers,
     },
     import: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/transfer.js')).cmdImport(hippoRoot, args, flags); },
         usage: VERB_USAGE.import,
+        flags: VERB_FLAGS.import,
     },
     export: {
         run: async (c) => { await (await import('./cli/transfer.js')).handleExport(c); },
         usage: VERB_USAGE.export,
+        flags: VERB_FLAGS.export,
     },
     capture: {
         run: async (c) => { await (await import('./cli/session-hooks.js')).handleCapture(c); },
         usage: VERB_USAGE.capture,
+        flags: VERB_FLAGS.capture,
     },
     dashboard: {
         run: async (c) => { await (await import('./cli/serve.js')).handleDashboard(c); },
         usage: VERB_USAGE.dashboard,
+        flags: VERB_FLAGS.dashboard,
     },
     wm: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/continuity.js')).cmdWm(hippoRoot, args, flags); },
         usage: VERB_USAGE.wm,
+        flags: VERB_FLAGS.wm,
     },
     mcp: {
         run: async () => { await (await import('./cli/serve.js')).handleMcp(); },
         usage: VERB_USAGE.mcp,
+        flags: VERB_FLAGS.mcp,
     },
     serve: {
         run: async (c) => { await (await import('./cli/serve.js')).handleServe(c); },
         usage: VERB_USAGE.serve,
+        flags: VERB_FLAGS.serve,
     },
     invalidate: {
         run: async (c) => { await (await import('./cli/curate.js')).handleInvalidate(c); },
         usage: VERB_USAGE.invalidate,
+        flags: VERB_FLAGS.invalidate,
     },
     decide: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/decisions.js')).cmdDecide(hippoRoot, args, flags); },
         usage: VERB_USAGE.decide,
+        flags: VERB_FLAGS.decide,
     },
     incident: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/decisions.js')).cmdIncident(hippoRoot, args, flags); },
         usage: VERB_USAGE.incident,
+        flags: VERB_FLAGS.incident,
     },
     process: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/playbooks.js')).cmdProcess(hippoRoot, args, flags); },
         usage: VERB_USAGE.process,
+        flags: VERB_FLAGS.process,
     },
     policy: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/playbooks.js')).cmdPolicy(hippoRoot, args, flags); },
         usage: VERB_USAGE.policy,
+        flags: VERB_FLAGS.policy,
     },
     skill: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/playbooks.js')).cmdSkill(hippoRoot, args, flags); },
         usage: VERB_USAGE.skill,
+        flags: VERB_FLAGS.skill,
     },
     brief: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/briefs.js')).cmdProjectBrief(hippoRoot, args, flags); },
         aliases: ['project-brief'],
         usage: VERB_USAGE.brief,
+        flags: VERB_FLAGS.brief,
     },
     note: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/briefs.js')).cmdCustomerNote(hippoRoot, args, flags); },
         aliases: ['customer-note'],
         usage: VERB_USAGE.note,
+        flags: VERB_FLAGS.note,
     },
     graph: {
         run: async ({ hippoRoot, args, flags }) => { (await import('./cli/briefs.js')).cmdGraph(hippoRoot, args, flags); },
         usage: VERB_USAGE.graph,
+        flags: VERB_FLAGS.graph,
     },
 };
 const COMMAND_INDEX = new Map(Object.entries(COMMANDS).flatMap(([verb, spec]) => [verb, ...(spec.aliases ?? [])].map((name) => [name, spec])));
@@ -577,70 +627,82 @@ function printHelp(command, args) {
 // ---------------------------------------------------------------------------
 // Entry point
 // ---------------------------------------------------------------------------
-async function main(command, args, flags, hippoRoot) {
-    if (command === '--version' || command === '-v' || flags['version']) {
-        const __filename_local = fileURLToPath(import.meta.url);
-        const __dirname_local = path.dirname(__filename_local);
-        const pkgJson = fs.readFileSync(path.join(__dirname_local, '..', 'package.json'), 'utf-8');
-        const { version } = JSON.parse(pkgJson);
-        console.log(version);
-        process.exit(0);
-    }
-    if (command === '' || command === 'help' || command === '--help' || command === '-h') {
-        printUsage();
-        return;
-    }
-    // Before every other step, so help never opens a store, installs a hook or starts a server.
-    if (Object.hasOwn(flags, 'help')) {
-        printHelp(command, args);
-        return;
-    }
-    maybeRepairCodexWrapper(command, flags);
-    /** A value-less --scope parses as boolean true, which consumers coerced to the scope 'true' or dropped;
-     *  reject it once here so every command, thin-client relays included, sees only a non-empty string. */
+function printVersion() {
+    const __filename_local = fileURLToPath(import.meta.url);
+    const __dirname_local = path.dirname(__filename_local);
+    const pkgJson = fs.readFileSync(path.join(__dirname_local, '..', 'package.json'), 'utf-8');
+    const { version } = JSON.parse(pkgJson);
+    console.log(version);
+    process.exit(0);
+}
+/** A value-less --scope parses as boolean true, which consumers coerced to the scope 'true' or dropped;
+ *  reject it once here so every command, thin-client relays included, sees only a non-empty string. */
+function rejectEmptyScope(flags) {
     if ('scope' in flags && (typeof flags['scope'] !== 'string' || !flags['scope'].trim())) {
         printError('--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)
+}
+// parseArgs stores a value-less flag as boolean true, and NaN then survives every
+// downstream guard because each comparison against it is false.
+function rejectNonNumericFlags(flags, declared) {
+    for (const [key, raw] of Object.entries(flags)) {
+        if (flagKind(declared, key) !== 'number')
             continue;
         if (typeof raw !== 'string' || !raw.trim() || !Number.isFinite(Number(raw))) {
             printError(`--${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') {
+}
+// 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.
+function rejectValuedSwitches(flags, declared) {
+    for (const [key, raw] of Object.entries(flags)) {
+        if (flagKind(declared, key) === 'switch' && typeof raw !== 'boolean') {
             printError(`--${key} takes no value`);
             process.exit(1);
         }
     }
+}
+function checkUnknownFlags(command, flags, declared) {
     // card checks its flags per subcommand, with a stricter message.
-    const unknownFlags = command === 'card' ? [] : Object.keys(flags).filter((key) => !KNOWN_FLAGS.has(key));
-    if (unknownFlags.length > 0) {
-        const names = unknownFlags.map((key) => `--${key}`).join(', ');
-        if (DESTRUCTIVE_COMMANDS.has(command)) {
-            printError(`Unknown flag ${names} for hippo ${command}. Nothing was changed.`);
-            process.exit(2);
-        }
-        printError(`hippo: ignoring unknown flag ${names}. A later release will reject it.`);
+    if (command === 'card')
+        return;
+    const flagNames = (keys) => keys.map((key) => `--${key}`).join(', ');
+    const unknown = Object.keys(flags).filter((key) => !isKnownFlag(key));
+    if (unknown.length > 0 && DESTRUCTIVE_COMMANDS.has(command)) {
+        printError(`Unknown flag ${flagNames(unknown)} for hippo ${command}. Nothing was changed.`);
+        process.exit(2);
     }
+    // main() refuses --dry-run by name on a verb without one, so that flag is not also called ignored.
+    const ignored = declared ? undeclaredFlags(declared, Object.keys(flags)).filter((key) => key !== 'dry-run') : unknown;
+    if (ignored.length > 0)
+        printError(`hippo: ignoring unknown flag ${flagNames(ignored)}. A later release will reject it.`);
+}
+async function main(command, args, flags, hippoRoot) {
+    if (command === '--version' || command === '-v' || flags['version'])
+        printVersion();
+    if (command === '' || command === 'help' || command === '--help' || command === '-h') {
+        printUsage();
+        return;
+    }
+    // Before every other step, so help never opens a store, installs a hook or starts a server.
+    if (Object.hasOwn(flags, 'help')) {
+        printHelp(command, args);
+        return;
+    }
+    const spec = COMMAND_INDEX.get(command);
+    maybeRepairCodexWrapper(command, flags);
+    rejectEmptyScope(flags);
+    rejectNonNumericFlags(flags, spec?.flags);
+    rejectValuedSwitches(flags, spec?.flags);
+    checkUnknownFlags(command, flags, spec?.flags);
     const refusal = Object.hasOwn(flags, 'dry-run') ? dryRunRefusal(command, args, flags) : null;
     if (refusal) {
         printError(refusal);
         process.exit(2);
     }
-    const spec = COMMAND_INDEX.get(command);
     if (!spec) {
         printError(`Unknown command: ${command}`);
         printUsage();
@@ -656,6 +718,11 @@ export async function runCli(argv = process.argv) {
     }
     catch (err) {
         printError('Error:', isStoreBusy(err) ? STORE_BUSY_MESSAGE : err instanceof Error ? err.message : err);
+        // The message alone rarely says where it came from; debug is the level that asks for the rest.
+        if (isLevelEnabled('debug')) {
+            const { errorClass, stack } = errorFields(err);
+            printError(`  thrown as ${errorClass}${stack ? `\n${stack}` : ''}`);
+        }
         process.exit(1);
     }
 }