@shadowforge0/aquifer-memory 1.5.12 → 1.7.0

package/consumers/cli.js

@@ -11,10 +11,13 @@
  *   aquifer backfill [options]          Enrich pending sessions
  *   aquifer stats [options]             Show database statistics
  *   aquifer export [options]            Export sessions
+ *   aquifer operator ...                Run operator-safe consolidation jobs
  *   aquifer mcp                         Start MCP server
  */
 
+const fs = require('fs');
 const { createAquiferFromConfig } = require('./shared/factory');
+const { formatRecallResults } = require('./shared/recall-format');
 
 function formatDate(value, fallback) {
   if (!value) return fallback;
@@ -36,6 +39,130 @@ function parsePositiveInt(value, fallback) {
   return Math.max(1, parsed);
 }
 
+function parseScopePath(value) {
+  if (!value) return undefined;
+  const parts = String(value).split(',').map(s => s.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : undefined;
+}
+
+function parseCsvList(value) {
+  if (!value) return undefined;
+  const parts = String(value).split(',').map(s => s.trim()).filter(Boolean);
+  return parts.length > 0 ? parts : undefined;
+}
+
+function readJsonFlagValue(value, label) {
+  if (!value || value === true) {
+    throw new Error(`${label} requires a JSON value`);
+  }
+  try {
+    return JSON.parse(String(value));
+  } catch (err) {
+    throw new Error(`${label} must be valid JSON: ${err.message}`);
+  }
+}
+
+function readJsonFlagFile(filePath, label) {
+  if (!filePath || filePath === true) {
+    throw new Error(`${label} requires a file path`);
+  }
+  try {
+    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
+  } catch (err) {
+    throw new Error(`${label} must point to valid JSON: ${err.message}`);
+  }
+}
+
+function readSynthesisSummaryFromFlags(flags = {}) {
+  if (flags['synthesis-summary-file']) {
+    return readJsonFlagFile(flags['synthesis-summary-file'], '--synthesis-summary-file');
+  }
+  if (flags['synthesis-summary']) {
+    return readJsonFlagValue(flags['synthesis-summary'], '--synthesis-summary');
+  }
+  return undefined;
+}
+
+function hasQuickstartEmbedConfig(env) {
+  return !!(
+    env.EMBED_PROVIDER
+    || (env.AQUIFER_EMBED_BASE_URL && env.AQUIFER_EMBED_MODEL)
+  );
+}
+
+function printQuickstartFailure(title, detailLines = []) {
+  console.error(`     FAIL — ${title}`);
+  for (const line of detailLines) {
+    if (line) console.error(`     ${line}`);
+  }
+}
+
+function buildQuickstartSetupHints(env, detected, err) {
+  const hints = [];
+  const message = err && err.message ? err.message : String(err || 'Unknown error');
+  const hasDb = !!(env.DATABASE_URL || env.AQUIFER_DB_URL || detected.DATABASE_URL);
+  const hasEmbed = hasQuickstartEmbedConfig(env)
+    || !!detected.EMBED_PROVIDER;
+
+  if (/Database URL is required/i.test(message)) {
+    hints.push('Quickstart could not find a PostgreSQL connection.');
+    if (!hasDb) {
+      hints.push('If you expect local defaults, make sure PostgreSQL is running on localhost:5432.');
+      hints.push('Otherwise set DATABASE_URL or AQUIFER_DB_URL explicitly and run quickstart again.');
+    }
+    return hints;
+  }
+
+  if (/OPENAI_API_KEY/i.test(message)) {
+    hints.push('OpenAI embeddings were selected, but OPENAI_API_KEY is not set.');
+    hints.push('Export OPENAI_API_KEY or switch EMBED_PROVIDER back to ollama for local quickstart.');
+    return hints;
+  }
+
+  if (!hasDb || !hasEmbed) {
+    hints.push('Quickstart is missing part of the local setup.');
+    if (!hasDb) hints.push('PostgreSQL was not autodetected and no DATABASE_URL is set.');
+    if (!hasEmbed) hints.push('No embedding provider was autodetected and no embed env is set.');
+    hints.push('Try `docker compose up -d`, then run `npx aquifer quickstart` again.');
+  }
+
+  hints.push(`Raw error: ${message}`);
+  return hints;
+}
+
+function buildQuickstartRecallHints(err) {
+  const message = err && err.message ? err.message : String(err || 'Unknown error');
+
+  if (/requires config\.embed\.fn|EMBED_PROVIDER/i.test(message)) {
+    return [
+      'Quickstart reached recall, but embeddings are not configured.',
+      'Set EMBED_PROVIDER=ollama for local Ollama, or EMBED_PROVIDER=openai with OPENAI_API_KEY.',
+      `Raw error: ${message}`,
+    ];
+  }
+
+  if (/OPENAI_API_KEY/i.test(message)) {
+    return [
+      'Recall is configured to use OpenAI embeddings, but OPENAI_API_KEY is missing.',
+      'Export OPENAI_API_KEY and rerun quickstart.',
+      `Raw error: ${message}`,
+    ];
+  }
+
+  if (/ECONNREFUSED|ENOTFOUND|fetch failed|connect/i.test(message)) {
+    return [
+      'Aquifer could not reach the embedding service during recall.',
+      'If you expect local Ollama, make sure it is running and the model is available.',
+      `Raw error: ${message}`,
+    ];
+  }
+
+  return [
+    'Aquifer could not recall the quickstart test session.',
+    `Raw error: ${message}`,
+  ];
+}
+
 // ---------------------------------------------------------------------------
 // Argument parser (minimal, no deps)
 // ---------------------------------------------------------------------------
@@ -43,7 +170,15 @@ function parsePositiveInt(value, fallback) {
 function parseArgs(argv) {
   const args = { _: [], flags: {} };
   // Flags that take a value (not boolean)
-  const VALUE_FLAGS = new Set(['limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status', 'concurrency', 'entities', 'entity-mode', 'session-id', 'verdict', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars', 'out']);
+  const VALUE_FLAGS = new Set([
+    'limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status',
+    'concurrency', 'entities', 'entity-mode', 'mode', 'session-id', 'memory-id', 'canonical-key',
+    'verdict', 'feedback-type', 'note', 'db', 'since', 'min-messages', 'lookback-days', 'max-chars',
+    'out', 'active-scope-key', 'active-scope-path', 'cadence', 'period-start', 'period-end',
+    'policy-version', 'worker-id', 'apply-token', 'claim-lease-seconds', 'snapshot-as-of',
+    'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
+    'synthesis-summary', 'synthesis-summary-file',
+  ]);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
     if (argv[i].startsWith('--')) {
@@ -76,13 +211,13 @@ async function cmdRecall(aquifer, args) {
     process.exit(1);
   }
 
-  const recallOpts = {
-    limit: parsePositiveInt(args.flags.limit, 5),
-    agentId: args.flags['agent-id'] || undefined,
-    source: args.flags.source || undefined,
-    dateFrom: args.flags['date-from'] || undefined,
-    dateTo: args.flags['date-to'] || undefined,
-  };
+  const recallOpts = { limit: parsePositiveInt(args.flags.limit, 5) };
+  if (args.flags['agent-id']) recallOpts.agentId = args.flags['agent-id'];
+  if (args.flags.source) recallOpts.source = args.flags.source;
+  if (args.flags['date-from']) recallOpts.dateFrom = args.flags['date-from'];
+  if (args.flags['date-to']) recallOpts.dateTo = args.flags['date-to'];
+  if (args.flags['active-scope-key']) recallOpts.activeScopeKey = args.flags['active-scope-key'];
+  if (args.flags['active-scope-path']) recallOpts.activeScopePath = parseScopePath(args.flags['active-scope-path']);
   if (args.flags.entities) {
     recallOpts.entities = args.flags.entities.split(',').map(s => s.trim()).filter(Boolean);
     recallOpts.entityMode = args.flags['entity-mode'] || 'any';
@@ -94,39 +229,20 @@ async function cmdRecall(aquifer, args) {
     return;
   }
 
-  if (results.length === 0) {
-    console.log('No results found.');
-    return;
-  }
-
-  const showExplain = !!args.flags.explain;
-  for (let i = 0; i < results.length; i++) {
-    const r = results[i];
-    const ss = r.structuredSummary || {};
-    const title = ss.title || r.summaryText?.slice(0, 60) || '(untitled)';
-    const date = formatDate(r.startedAt, '?');
-    console.log(`${i + 1}. [${r.score?.toFixed(3)}] ${title} (${date}, ${r.agentId})`);
-    if (ss.overview) console.log(`   ${ss.overview.slice(0, 200)}`);
-    if (r.matchedTurnText) console.log(`   > ${r.matchedTurnText.slice(0, 150)}`);
-    if (showExplain && r._debug) {
-      const d = r._debug;
-      const f = (v) => typeof v === 'number' ? v.toFixed(3) : '?';
-      const parts = [
-        `rrf=${f(d.rrf)}`, `td=${f(d.timeDecay)}`, `access=${f(d.access)}`,
-        `entity=${f(d.entityScore)}`, `trust=${f(d.trustScore)}(\u00d7${f(d.trustMultiplier)})`,
-        `ol=${f(d.openLoopBoost)}`, `\u2192 hybrid=${f(d.hybridScore)}`,
-      ];
-      if (d.rerankApplied) parts.push(`rerank=${f(d.rerankScore)}(${d.rerankReason || '?'})`);
-      else parts.push(`[rerank: off (${d.rerankReason || '?'})]`);
-      console.log(`   ${parts.join(' ')}`);
-    }
-    console.log();
-  }
+  console.log(formatRecallResults(results, {
+    query,
+    showScore: true,
+    showExplain: !!args.flags.explain,
+  }));
 }
 
 async function cmdFeedback(aquifer, args) {
   const sessionId = args.flags['session-id'] || args._[1];
   const verdict = args.flags.verdict;
+  if (args.flags['memory-id'] || args.flags['canonical-key'] || args.flags['feedback-type']) {
+    console.error('Use `aquifer memory-feedback` for curated memory feedback.');
+    process.exit(1);
+  }
 
   if (!sessionId || !verdict) {
     console.error('Usage: aquifer feedback --session-id ID --verdict helpful|unhelpful [--note TEXT] [--agent-id ID]');
@@ -146,6 +262,66 @@ async function cmdFeedback(aquifer, args) {
   }
 }
 
+async function cmdMemoryFeedback(aquifer, args) {
+  const memoryId = args.flags['memory-id'];
+  const canonicalKey = args.flags['canonical-key'];
+  const feedbackType = args.flags['feedback-type'];
+
+  if ((!memoryId && !canonicalKey) || !feedbackType) {
+    console.error('Usage: aquifer memory-feedback (--memory-id ID | --canonical-key KEY) --feedback-type helpful|confirm|irrelevant|scope_mismatch|stale|incorrect [--note TEXT] [--agent-id ID]');
+    process.exit(1);
+  }
+
+  const result = await aquifer.memoryFeedback({
+    memoryId: memoryId || undefined,
+    canonicalKey: canonicalKey || undefined,
+  }, {
+    feedbackType,
+    agentId: args.flags['agent-id'] || undefined,
+    note: args.flags.note || undefined,
+  });
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+  } else {
+    const target = result.canonicalKey || result.memoryId;
+    console.log(`Memory feedback: ${result.feedbackType} (${target})`);
+  }
+}
+
+async function cmdEvidenceRecall(aquifer, args) {
+  const query = args._.slice(1).join(' ');
+  if (!query) {
+    console.error('Usage: aquifer evidence-recall <query> [--limit N] [--agent-id ID] [--allow-unsafe-debug] [--json]');
+    process.exit(1);
+  }
+
+  const recallOpts = { limit: parsePositiveInt(args.flags.limit, 5) };
+  if (args.flags['agent-id']) recallOpts.agentId = args.flags['agent-id'];
+  if (args.flags.source) recallOpts.source = args.flags.source;
+  if (args.flags['date-from']) recallOpts.dateFrom = args.flags['date-from'];
+  if (args.flags['date-to']) recallOpts.dateTo = args.flags['date-to'];
+  if (args.flags.entities) {
+    recallOpts.entities = args.flags.entities.split(',').map(s => s.trim()).filter(Boolean);
+    recallOpts.entityMode = args.flags['entity-mode'] || 'any';
+  }
+  if (args.flags.mode) recallOpts.mode = args.flags.mode;
+  if (args.flags['allow-unsafe-debug']) recallOpts.allowUnsafeDebug = true;
+
+  const results = await aquifer.evidenceRecall(query, recallOpts);
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(results, null, 2));
+    return;
+  }
+
+  console.log(formatRecallResults(results, {
+    query,
+    showScore: true,
+    showExplain: !!args.flags.explain,
+  }));
+}
+
 async function cmdFeedbackStats(aquifer, args) {
   const stats = await aquifer.feedbackStats({
     agentId: args.flags['agent-id'] || undefined,
@@ -238,13 +414,39 @@ async function cmdQuickstart(aquifer) {
     skipSummary: true,
     skipEntities: true,
   });
+  if (Array.isArray(enrichResult.warnings) && enrichResult.warnings.length > 0) {
+    printQuickstartFailure('embedding step returned warnings.', [
+      'Quickstart expects turn embeddings to succeed cleanly.',
+      ...enrichResult.warnings.map(w => `Warning: ${w}`),
+    ]);
+    process.exitCode = 1;
+    return;
+  }
+  if (!Number.isFinite(enrichResult.turnsEmbedded) || enrichResult.turnsEmbedded <= 0) {
+    printQuickstartFailure('0 turns were embedded.', [
+      'The quickstart test session contains user turns, so this usually means the embedding setup is not working.',
+      'Check EMBED_PROVIDER / AQUIFER_EMBED_* settings, or make sure Ollama/OpenAI is reachable.',
+    ]);
+    process.exitCode = 1;
+    return;
+  }
   console.log(`     OK — ${enrichResult.turnsEmbedded} turns embedded\n`);
 
   // 4. Recall
   console.log('4/5  Recalling "PostgreSQL memory store"...');
-  const results = await aquifer.recall('PostgreSQL memory store', { limit: 3 });
+  let results;
+  try {
+    results = await aquifer.recall('PostgreSQL memory store', { limit: 3 });
+  } catch (err) {
+    printQuickstartFailure('recall step failed.', buildQuickstartRecallHints(err));
+    process.exitCode = 1;
+    return;
+  }
   if (results.length === 0) {
-    console.error('     FAIL — no results returned. Check your embedding config.');
+    printQuickstartFailure('quickstart could not recall its own test session.', [
+      'The write step succeeded, but the test query returned no matches.',
+      'This usually means the embedding path is misconfigured or the embed service is not reachable.',
+    ]);
     process.exitCode = 1;
     return;
   }
@@ -282,14 +484,17 @@ async function cmdQuickstart(aquifer) {
 }
 
 async function cmdBootstrap(aquifer, args) {
-  const result = await aquifer.bootstrap({
-    agentId: args.flags['agent-id'] || undefined,
-    source: args.flags.source || undefined,
+  const bootstrapOpts = {
     limit: parsePositiveInt(args.flags.limit, 5),
-    lookbackDays: parsePositiveInt(args.flags['lookback-days'], 14),
     maxChars: parsePositiveInt(args.flags['max-chars'], 4000),
     format: args.flags.json ? 'structured' : 'text',
-  });
+  };
+  if (args.flags['agent-id']) bootstrapOpts.agentId = args.flags['agent-id'];
+  if (args.flags.source) bootstrapOpts.source = args.flags.source;
+  if (args.flags['lookback-days']) bootstrapOpts.lookbackDays = parsePositiveInt(args.flags['lookback-days'], 14);
+  if (args.flags['active-scope-key']) bootstrapOpts.activeScopeKey = args.flags['active-scope-key'];
+  if (args.flags['active-scope-path']) bootstrapOpts.activeScopePath = parseScopePath(args.flags['active-scope-path']);
+  const result = await aquifer.bootstrap(bootstrapOpts);
 
   if (args.flags.json) {
     console.log(JSON.stringify(result, null, 2));
@@ -305,6 +510,102 @@ async function cmdBootstrap(aquifer, args) {
   }
 }
 
+async function cmdOperator(aquifer, args) {
+  const operatorVerb = args._[1] || 'compaction';
+  const cadenceVerbs = new Set(['manual', 'daily', 'weekly', 'monthly']);
+
+  if (operatorVerb === 'archive-distill') {
+    const inputPath = args.flags.input || args._[2];
+    if (!inputPath) {
+      console.error('Usage: aquifer operator archive-distill --input /path/to/archive.json [--authority verified_summary] [--json]');
+      process.exit(1);
+    }
+    const archiveSnapshot = JSON.parse(fs.readFileSync(inputPath, 'utf8'));
+    const result = await aquifer.memory.consolidation.runJob({
+      job: 'archive-distill',
+      archiveSnapshot,
+      authority: args.flags.authority || undefined,
+      scopeKind: args.flags['scope-kind'] || undefined,
+      scopeKey: args.flags['scope-key'] || undefined,
+      contextKey: args.flags['context-key'] || undefined,
+      topicKey: args.flags['topic-key'] || undefined,
+    });
+
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+
+    const sessionCount = Array.isArray(archiveSnapshot.sessions) ? archiveSnapshot.sessions.length : 0;
+    console.log(`Archive distill planned from ${sessionCount} sessions.`);
+    console.log(`Candidates: ${result.candidates.length}`);
+    console.log('Visibility: recall/bootstrap hidden until a separate promotion step.');
+    return;
+  }
+
+  if (operatorVerb !== 'compaction' && operatorVerb !== 'compact' && !cadenceVerbs.has(operatorVerb)) {
+    console.error('Usage: aquifer operator <compaction|archive-distill> [...]');
+    process.exit(1);
+  }
+
+  const cadence = args.flags.cadence
+    || (cadenceVerbs.has(operatorVerb) ? operatorVerb : args._[2])
+    || 'manual';
+  const synthesisSummary = readSynthesisSummaryFromFlags(args.flags);
+  const result = await aquifer.memory.consolidation.runJob({
+    job: 'compaction',
+    cadence,
+    periodStart: args.flags['period-start'] || undefined,
+    periodEnd: args.flags['period-end'] || undefined,
+    policyVersion: args.flags['policy-version'] || undefined,
+    workerId: args.flags['worker-id'] || undefined,
+    applyToken: args.flags['apply-token'] || undefined,
+    claimLeaseSeconds: args.flags['claim-lease-seconds']
+      ? parsePositiveInt(args.flags['claim-lease-seconds'], undefined)
+      : undefined,
+    snapshotAsOf: args.flags['snapshot-as-of'] || undefined,
+    scopeKeys: parseCsvList(args.flags['scope-keys'] || args.flags['scope-key']),
+    scopeKind: args.flags['scope-kind'] || undefined,
+    scopeKey: args.flags['scope-key'] || undefined,
+    contextKey: args.flags['context-key'] || undefined,
+    topicKey: args.flags['topic-key'] || undefined,
+    activeScopeKey: args.flags['active-scope-key'] || undefined,
+    activeScopePath: parseScopePath(args.flags['active-scope-path']),
+    limit: parsePositiveInt(args.flags.limit, 1000),
+    apply: args.flags.apply === true,
+    promoteCandidates: args.flags['promote-candidates'] === true,
+    includeSynthesisPrompt: args.flags['include-synthesis-prompt'] === true,
+    synthesisSummary,
+  });
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+
+  console.log(`${result.dryRun ? 'Planned' : 'Executed'} ${result.cadence} compaction window ${result.periodStart} -> ${result.periodEnd}`);
+  console.log(`Snapshot: ${result.snapshotCount} active rows${result.snapshotTruncated ? ' (snapshot limit reached)' : ''}`);
+  console.log(`Plan: ${result.plan.statusUpdates.length} lifecycle updates, ${result.plan.candidates.length} candidates`);
+  if (result.synthesisPrompt) {
+    console.log('\nSynthesis prompt:\n');
+    console.log(result.synthesisPrompt);
+  }
+  if (result.promotionReview) {
+    console.log(`\n${result.promotionReview}`);
+  }
+  if (result.dryRun) {
+    console.log('Mode: dry-run only. Re-run with --apply to write compaction_runs and lifecycle changes.');
+    return;
+  }
+  if (result.run) {
+    console.log(`Run: #${result.run.id} status=${result.run.status}`);
+  } else if (result.existingRun) {
+    console.log(`Existing run: #${result.existingRun.id} status=${result.existingRun.status} reason=${result.skipReason || 'claim_not_acquired'}`);
+  } else {
+    console.log(`No run claimed: ${result.skipReason || 'claim_not_acquired'}`);
+  }
+}
+
 async function cmdExport(aquifer, args) {
   const output = args.flags.output || null;
   const limit = parsePositiveInt(args.flags.limit, 1000);
@@ -333,6 +634,10 @@ async function cmdExport(aquifer, args) {
   }
 }
 
+async function cmdCompact(aquifer, args) {
+  return cmdOperator(aquifer, { ...args, _: ['operator', 'compaction', ...args._.slice(1)] });
+}
+
 // ---------------------------------------------------------------------------
 // Main
 // ---------------------------------------------------------------------------
@@ -343,17 +648,22 @@ async function main() {
     console.log(`Usage: aquifer <command> [options]
 
 Commands:
-  quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
-  migrate                     Run database migrations
+   quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
+   migrate                     Run database migrations
   recall <query>              Search sessions (requires embed config)
+  evidence-recall <query>     Search legacy session/evidence plane explicitly
   feedback                    Record trust feedback on a session
+  memory-feedback             Record curated memory feedback
   feedback-stats              Show trust feedback statistics and coverage
   backfill                    Enrich pending sessions
+  operator ...                Run operator-safe consolidation jobs
+  compact                     Plan or apply curated memory compaction
   stats                       Show database statistics
   export                      Export sessions as JSONL
   bootstrap                   Show recent session context (for new session start)
-  ingest-opencode             Import sessions from OpenCode's local SQLite DB
-  mcp                         Start MCP server
+  codex-recovery ...          Inspect or run Codex SessionStart recovery flow
+   ingest-opencode             Import sessions from OpenCode's local SQLite DB
+   mcp                         Start MCP server
 
 Options:
   --limit N                   Limit results
@@ -364,23 +674,55 @@ Options:
   --entities A,B,C            Entity names (comma-separated, recall)
   --entity-mode any|all       Entity match mode (recall, default: any)
   --session-id ID             Session ID (feedback)
+  --memory-id ID              Curated memory record ID (memory-feedback)
+  --canonical-key KEY         Active curated memory canonical key (memory-feedback)
   --verdict helpful|unhelpful Feedback verdict (feedback)
+  --feedback-type TYPE        Curated memory feedback type
   --note TEXT                 Feedback note (feedback)
   --explain                    Show score breakdown per result (recall)
+  --allow-unsafe-debug        Allow broad evidence-recall without audit boundary
   --json                      JSON output
   --dry-run                   Preview only (backfill)
   --output PATH               Output file (export)
   --config PATH               Config file path
   --lookback-days N           How far back in days (bootstrap, default: 14)
   --max-chars N               Max output characters (bootstrap, default: 4000)
+  --active-scope-key KEY      Active curated memory scope key
+  --active-scope-path A,B     Ordered curated scope path
+  --cadence manual|daily|weekly|monthly
+  --period-start ISO          Compaction window start
+  --period-end ISO            Compaction window end
+  --apply                     Apply compaction; default is dry-run
+  --promote-candidates        Promote compaction/synthesis candidates when applying
+  --include-synthesis-prompt  Include timer synthesis prompt in operator output
+  --synthesis-summary JSON    Timer synthesis summary JSON to attach to a compaction plan
+  --synthesis-summary-file P  Read timer synthesis summary JSON from file
+  --scope-key A,B             Limit compaction snapshot to specific scope keys
+  --scope-kind KIND           Explicit synthesis target scope kind
+  --snapshot-as-of ISO        Read active snapshot as of a specific instant
+  --claim-lease-seconds N     Override compaction apply lease
+  --input PATH                Archive distill input JSON path
   --db PATH                   OpenCode SQLite path (ingest-opencode)
   --since YYYY-MM-DD          Only ingest sessions after date (ingest-opencode)
-  --min-messages N            Min user messages to ingest (ingest-opencode, default: 3)`);
+  --min-messages N            Min user messages to ingest (ingest-opencode, default: 3)
+
+Operator examples:
+  aquifer operator compaction daily --json
+  aquifer operator compaction daily --include-synthesis-prompt --json
+  aquifer operator compaction manual --period-start 2026-04-27T00:00:00Z --period-end 2026-04-28T00:00:00Z --apply
+  aquifer operator compaction daily --synthesis-summary-file /tmp/timer-summary.json --apply --promote-candidates --json
+  aquifer operator archive-distill --input /tmp/archive-snapshot.json --json`);
     process.exit(0);
   }
 
   const command = argv[0];
   const args = parseArgs(argv);
+  let quickstartDetected = {};
+
+  if (command === 'codex-recovery') {
+    await require('../scripts/codex-recovery').main(argv.slice(1));
+    return;
+  }
 
   // MCP: delegate to mcp.js
   if (command === 'mcp') {
@@ -414,10 +756,10 @@ Options:
   // the operator to have set env explicitly.
   if (command === 'quickstart') {
     const { autodetectForQuickstart } = require('./shared/autodetect');
-    const detected = await autodetectForQuickstart(process.env);
-    if (Object.keys(detected).length > 0) {
+    quickstartDetected = await autodetectForQuickstart(process.env);
+    if (Object.keys(quickstartDetected).length > 0) {
       console.log('Autodetected localhost services (env not set):');
-      for (const [k, v] of Object.entries(detected)) {
+      for (const [k, v] of Object.entries(quickstartDetected)) {
         console.log(`  ${k}=${v}`);
         process.env[k] = v;
       }
@@ -425,7 +767,17 @@ Options:
     }
   }
 
-  const aquifer = createAquiferFromConfig(configOverrides);
+  let aquifer;
+  try {
+    aquifer = createAquiferFromConfig(configOverrides);
+  } catch (err) {
+    if (command === 'quickstart') {
+      printQuickstartFailure('setup check failed before quickstart could start.', buildQuickstartSetupHints(process.env, quickstartDetected, err));
+      process.exit(1);
+      return;
+    }
+    throw err;
+  }
 
   try {
     switch (command) {
@@ -438,15 +790,27 @@ Options:
       case 'recall':
         await cmdRecall(aquifer, args);
         break;
+      case 'evidence-recall':
+        await cmdEvidenceRecall(aquifer, args);
+        break;
       case 'feedback':
         await cmdFeedback(aquifer, args);
         break;
+      case 'memory-feedback':
+        await cmdMemoryFeedback(aquifer, args);
+        break;
       case 'feedback-stats':
         await cmdFeedbackStats(aquifer, args);
         break;
       case 'backfill':
         await cmdBackfill(aquifer, args);
         break;
+      case 'operator':
+        await cmdOperator(aquifer, args);
+        break;
+      case 'compact':
+        await cmdCompact(aquifer, args);
+        break;
       case 'stats':
         await cmdStats(aquifer, args);
         break;
@@ -471,7 +835,11 @@ Options:
 }
 
 // Export for testing; execute only when run directly
-module.exports = { parseArgs };
+module.exports = {
+  parseArgs,
+  cmdOperator,
+  readSynthesisSummaryFromFlags,
+};
 
 if (require.main === module) {
   main().catch(err => {