@shadowforge0/aquifer-memory 1.8.1 → 1.9.1

package/consumers/cli.js

@@ -9,8 +9,11 @@
  *   aquifer migrate                     Run database migrations
  *   aquifer recall <query> [options]    Search sessions
  *   aquifer backfill [options]          Enrich pending sessions
- *   aquifer stats [options]             Show database statistics
+ *   aquifer backlog [options]           Explain saved-content preparation work
+ *   aquifer stats [options]             Check memory readiness and diagnostics
  *   aquifer backend-info [--json]       Show selected backend capabilities
+ *   aquifer install-openclaw            Install/update OpenClaw MCP + extension wiring
+ *   aquifer finalization ...            Inspect read-only finalization ledger
  *   aquifer export [options]            Export sessions
  *   aquifer operator ...                Run operator-safe consolidation jobs
  *   aquifer mcp                         Start MCP server
@@ -21,12 +24,13 @@ const { createAquiferFromConfig } = require('./shared/factory');
 const { loadConfig } = require('./shared/config');
 const { formatRecallResults } = require('./shared/recall-format');
 const { backendCapabilities } = require('../core/backends/capabilities');
-
-function formatDate(value, fallback) {
-  if (!value) return fallback;
-  const parsed = new Date(value);
-  return isNaN(parsed.getTime()) ? fallback : parsed.toISOString().slice(0, 10);
-}
+const { summarizeFinalizationListRow } = require('../core/finalization-inspector');
+const {
+  buildBacklogEnvelope,
+  buildStatsEnvelope,
+  formatMemoryStatsInterface,
+  formatPendingWorkInterface,
+} = require('../core/interface');
 
 function quoteIdentifier(identifier) {
   if (!/^[a-zA-Z_]\w{0,62}$/.test(identifier)) {
@@ -42,6 +46,12 @@ function parsePositiveInt(value, fallback) {
   return Math.max(1, parsed);
 }
 
+function printTextBlock(text) {
+  for (const line of String(text).split(/\r?\n/)) {
+    console.log(line);
+  }
+}
+
 function parseScopePath(value) {
   if (!value) return undefined;
   const parts = String(value).split(',').map(s => s.trim()).filter(Boolean);
@@ -177,12 +187,16 @@ function parseArgs(argv) {
   // Flags that take a value (not boolean)
   const VALUE_FLAGS = new Set([
     'limit', 'agent-id', 'source', 'date-from', 'date-to', 'output', 'format', 'config', 'status',
+    'plan', 'action',
     '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-id', 'scope-key', 'scope-keys', 'scope-kind', 'context-key', 'topic-key', 'authority', 'input',
     'synthesis-summary', 'synthesis-summary-file', 'min-finalizations', 'checkpoint-key',
+    'openclaw-home', 'id', 'transcript-hash', 'phase', 'host', 'run-id', 'kind', 'query',
+    'memory-type', 'visibility', 'as-of', 'resolution', 'reason', 'actor-kind', 'actor-id',
+    'defer-until', 'expected-latest-issue-feedback-id', 'expected-latest-issue-feedback-at',
   ]);
   for (let i = 0; i < argv.length; i++) {
     if (argv[i] === '--') { args._.push(...argv.slice(i + 1)); break; }
@@ -402,34 +416,42 @@ async function cmdBackfill(aquifer, args) {
   if (failed > 0) process.exitCode = 2;
 }
 
+async function cmdBacklog(aquifer, args) {
+  const action = args.flags.plan || args.flags.action || 'inspect';
+  const opts = {
+    limit: parsePositiveInt(args.flags.limit, 50),
+    source: args.flags.source || undefined,
+    agentId: args.flags['agent-id'] || undefined,
+    status: args.flags.status || undefined,
+    action,
+  };
+  const report = await aquifer.getPendingWork(opts);
+
+  if (args.flags.json) {
+    console.log(JSON.stringify(buildBacklogEnvelope(report, {
+      diagnostics: args.flags.diagnostics === true,
+      includePlan: true,
+    }), null, 2));
+    return;
+  }
+
+  printTextBlock(formatPendingWorkInterface(report, {
+    diagnostics: args.flags.diagnostics === true,
+    includePlan: true,
+  }));
+}
+
 async function cmdStats(aquifer, args) {
   const stats = await aquifer.getStats();
 
   if (args.flags.json) {
-    console.log(JSON.stringify(stats, null, 2));
+    console.log(JSON.stringify(buildStatsEnvelope(stats, {
+      diagnostics: args.flags.diagnostics === true,
+    }), null, 2));
   } else {
-    console.log(`Backend: ${stats.backendKind || 'unknown'} (${stats.backendProfile || 'unknown'})`);
-    console.log(`Serving mode: ${stats.serving?.mode || 'legacy'}`);
-    console.log(`Active scope: ${stats.serving?.activeScopePath?.join(' > ') || stats.serving?.activeScopeKey || 'none'}`);
-    console.log(`Sessions: ${stats.sessionTotal} (${Object.entries(stats.sessions).map(([k, v]) => `${k}: ${v}`).join(', ')})`);
-    console.log(`Summaries: ${stats.summaries}`);
-    console.log(`Turn embeddings: ${stats.turnEmbeddings}`);
-    console.log(`Entities: ${stats.entities}`);
-    if (stats.memoryRecords) {
-      console.log(`Memory records: ${stats.memoryRecords.total} (${stats.memoryRecords.active} active, ${stats.memoryRecords.visibleInRecall} recall-visible, ${stats.memoryRecords.visibleInBootstrap} bootstrap-visible)`);
-      if (stats.memoryRecords.latest) console.log(`Memory record range: ${formatDate(stats.memoryRecords.earliest, '?')} — ${formatDate(stats.memoryRecords.latest, '?')}`);
-    }
-    if (stats.sessionFinalizations?.available) {
-      const statusText = Object.entries(stats.sessionFinalizations.statuses || {})
-        .map(([status, count]) => `${status}: ${count}`)
-        .join(', ') || 'none';
-      console.log(`Session finalizations: ${stats.sessionFinalizations.total} (${statusText})`);
-      if (stats.sessionFinalizations.latestFinalizedAt) console.log(`Latest finalization: ${formatDate(stats.sessionFinalizations.latestFinalizedAt, '?')}`);
-    }
-    if (stats.earliest) console.log(`Range: ${formatDate(stats.earliest, '?')} — ${formatDate(stats.latest, '?')}`);
-    if ((stats.serving?.mode || 'legacy') !== 'curated') {
-      console.log('Warning: legacy serving returns session/evidence material; configure curated serving with an active scope for current-memory answers.');
-    }
+    printTextBlock(formatMemoryStatsInterface(stats, {
+      diagnostics: args.flags.diagnostics === true,
+    }));
   }
 }
 
@@ -473,6 +495,149 @@ async function cmdBackendInfo(args) {
   }
 }
 
+function formatDoctor(result = {}) {
+  const checks = Array.isArray(result.checks) ? result.checks : [];
+  if (checks.length === 0) return `Doctor: ${result.status || 'unknown'}`;
+  return checks.map(check => {
+    const next = check.nextAction ? ` next=${check.nextAction}` : '';
+    return `${check.status || 'unknown'} ${check.id || 'check'}: ${check.summary || ''}${next}`;
+  }).join('\n');
+}
+
+async function cmdDoctor(aquifer, args) {
+  const result = await aquifer.doctor.run({
+    host: args.flags.host || undefined,
+    openclawHome: args.flags['openclaw-home'] || undefined,
+    limit: parsePositiveInt(args.flags.limit, 20),
+  });
+  if (args.flags.json) {
+    console.log(JSON.stringify(result, null, 2));
+    return;
+  }
+  console.log(formatDoctor(result));
+}
+
+function formatTimestamp(value) {
+  if (!value) return '?';
+  const parsed = new Date(value);
+  return isNaN(parsed.getTime()) ? String(value) : parsed.toISOString();
+}
+
+function shortHash(value) {
+  if (!value) return '?';
+  return String(value).slice(0, 12);
+}
+
+function formatFinalizationList(rows = []) {
+  if (!rows || rows.length === 0) return 'No finalization rows found.';
+  return rows.map(row => {
+    const item = summarizeFinalizationListRow(row);
+    const session = `${item.source}/${item.agentId}/${item.sessionId}`;
+    const phase = item.phase ? ` phase=${item.phase}` : '';
+    const mode = item.mode ? ` mode=${item.mode}` : '';
+    const hash = item.transcriptHashPrefix ? ` hash=${item.transcriptHashPrefix}` : '';
+    return `#${item.id} ${item.status} ${session}${phase}${mode}${hash} updated=${formatTimestamp(item.updatedAt)}`;
+  }).join('\n');
+}
+
+function formatFinalizationInspect(report = {}) {
+  const item = report.finalization || {};
+  const candidateSummary = report.candidateSummary || {};
+  const lineage = report.lineage || {};
+  const envelope = report.candidateEnvelope || {};
+  const memoryResult = report.memoryResult || {};
+  const lines = [
+    `Finalization #${item.id || '?'} ${item.status || 'unknown'}`,
+    `Session: ${item.source || '?'}/${item.agentId || '?'}/${item.sessionId || '?'} phase=${item.phase || '?'} mode=${item.mode || '?'} host=${item.host || '?'}`,
+    `Transcript hash: ${item.transcriptHashPrefix || shortHash(item.transcriptHash)}`,
+    `Updated: ${formatTimestamp(item.updatedAt)} finalized=${formatTimestamp(item.finalizedAt)}`,
+  ];
+
+  if (item.finalizerModel) lines.push(`Finalizer: ${item.finalizerModel}`);
+  if (item.scopeKind || item.scopeKey || item.contextKey || item.topicKey) {
+    lines.push(`Scope: kind=${item.scopeKind || '?'} key=${item.scopeKey || '?'} context=${item.contextKey || '?'} topic=${item.topicKey || '?'}`);
+  }
+  if (item.error) lines.push(`Error: ${item.error}`);
+
+  lines.push(`Memory result: candidates=${memoryResult.candidates || 0} promoted=${memoryResult.promoted || 0} quarantined=${memoryResult.quarantined || 0} skipped=${memoryResult.skipped || 0}`);
+  lines.push(`Candidate envelope: version=${envelope.version || '?'} hash=${shortHash(envelope.hash)} candidates=${envelope.candidateCount || 0}`);
+  lines.push(`Candidate actions: total=${candidateSummary.total || 0} promote=${candidateSummary.promote || 0} quarantine=${candidateSummary.quarantine || 0} skip=${candidateSummary.skip || 0} supersede=${candidateSummary.supersede || 0} error=${candidateSummary.error || 0}`);
+  lines.push(`Lineage: memories=${(lineage.memoryRecordIds || []).join(',') || 'none'} facts=${(lineage.factAssertionIds || []).join(',') || 'none'} evidenceRefs=${lineage.evidenceRefCount || 0} evidenceItems=${lineage.evidenceItemCount || 0}`);
+
+  if (report.review?.humanReviewText) {
+    lines.push('\nHuman review:\n' + report.review.humanReviewText);
+  }
+  if (report.review?.sessionStartText) {
+    lines.push('\nSessionStart:\n' + report.review.sessionStartText);
+  }
+  if (Array.isArray(report.candidates) && report.candidates.length > 0) {
+    lines.push('\nCandidates:');
+    for (const candidate of report.candidates) {
+      lines.push(`  [${candidate.index}] ${candidate.action}${candidate.reason ? `/${candidate.reason}` : ''} ${candidate.memoryType || '?'} ${candidate.canonicalKey || '?'}${candidate.memoryRecordId ? ` memory=${candidate.memoryRecordId}` : ''}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+async function cmdFinalization(aquifer, args) {
+  const verb = args._[1] || 'list';
+
+  if (verb === 'list') {
+    const rows = await aquifer.finalization.list({
+      status: args.flags.status || undefined,
+      agentId: args.flags['agent-id'] || undefined,
+      source: args.flags.source || undefined,
+      host: args.flags.host || undefined,
+      sessionId: args.flags['session-id'] || undefined,
+      transcriptHash: args.flags['transcript-hash'] || undefined,
+      phase: args.flags.phase || undefined,
+      mode: args.flags.mode || undefined,
+      limit: parsePositiveInt(args.flags.limit, 50),
+    });
+
+    if (args.flags.json) {
+      console.log(JSON.stringify({
+        readOnly: true,
+        finalizations: rows.map(summarizeFinalizationListRow),
+      }, null, 2));
+      return;
+    }
+    console.log(formatFinalizationList(rows));
+    return;
+  }
+
+  if (verb === 'inspect') {
+    const id = args.flags.id || args._[2] || undefined;
+    const sessionId = args.flags['session-id'];
+    if (id && (sessionId || args.flags['agent-id'] || args.flags.source || args.flags['transcript-hash'])) {
+      console.error('Usage: --id is mutually exclusive with --session-id/--agent-id/--source/--transcript-hash.');
+      process.exit(1);
+    }
+    if (!id && (!sessionId || !args.flags['agent-id'] || !args.flags.source)) {
+      console.error('Usage: aquifer finalization inspect (--id ID | --session-id ID --agent-id ID --source SOURCE [--transcript-hash HASH]) [--json]');
+      process.exit(1);
+    }
+    const report = await aquifer.finalization.inspect({
+      id,
+      sessionId: sessionId || undefined,
+      agentId: args.flags['agent-id'] || undefined,
+      source: args.flags.source || undefined,
+      transcriptHash: args.flags['transcript-hash'] || undefined,
+      phase: args.flags.phase || undefined,
+    });
+
+    if (args.flags.json) {
+      console.log(JSON.stringify(report, null, 2));
+      return;
+    }
+    console.log(formatFinalizationInspect(report));
+    return;
+  }
+
+  console.error('Usage: aquifer finalization <list|inspect> [options]');
+  process.exit(1);
+}
+
 async function cmdLocalQuickstart(aquifer) {
   const cfg = aquifer.getConfig();
   console.log('Aquifer quickstart — verifying local starter backend.\n');
@@ -644,10 +809,319 @@ async function cmdBootstrap(aquifer, args) {
   }
 }
 
+function formatExplain(result = {}) {
+  const selected = Array.isArray(result.selected) ? result.selected : [];
+  const excluded = Array.isArray(result.excluded) ? result.excluded : [];
+  const lines = [
+    `Explain ${result.lane || 'memory'}: selected=${selected.length} excluded=${excluded.length}`,
+  ];
+  if (selected.length > 0) {
+    lines.push('Selected:');
+    for (const row of selected) {
+      lines.push(`  ${row.memoryId || row.id || '?'} ${row.canonicalKey || '?'} reason=${row.reason || 'selected'}`);
+    }
+  }
+  if (excluded.length > 0) {
+    lines.push('Excluded:');
+    for (const row of excluded) {
+      lines.push(`  ${row.memoryId || row.id || '?'} ${row.canonicalKey || '?'} reason=${row.reason || 'unknown'}`);
+    }
+  }
+  if (result.budget) {
+    lines.push(`Budget: limit=${result.budget.limit || '?'} maxChars=${result.budget.maxChars || '?'} overflow=${result.budget.overflow === true}`);
+  }
+  return lines.join('\n');
+}
+
+function formatFeedbackCounts(counts = {}) {
+  const entries = Object.entries(counts).filter(([, count]) => count > 0);
+  if (entries.length === 0) return 'none';
+  return entries.map(([type, count]) => `${type}=${count}`).join(' ');
+}
+
+function formatReviewResolution(resolution = null) {
+  if (!resolution || !resolution.resolution) return 'none';
+  const at = resolution.resolvedAt ? ` at=${formatTimestamp(resolution.resolvedAt)}` : '';
+  const defer = resolution.deferUntil ? ` deferUntil=${formatTimestamp(resolution.deferUntil)}` : '';
+  return `${resolution.resolution}${at}${defer}`;
+}
+
+function formatReviewQueue(result = {}) {
+  if (result.available === false) {
+    return result.error || 'Memory review queue is unavailable.';
+  }
+  const rows = Array.isArray(result.items) ? result.items : (Array.isArray(result.reviewQueue) ? result.reviewQueue : []);
+  if (rows.length === 0) return 'No memory review items found.';
+  return rows.map(row => {
+    const scope = row.scope?.key ? ` scope=${row.scope.key}` : '';
+    const latest = row.latestFeedbackAt ? ` latest=${formatTimestamp(row.latestFeedbackAt)}` : '';
+    const resolution = row.resolution ? ` resolution=${formatReviewResolution(row.resolution)}` : '';
+    const counts = formatFeedbackCounts(row.feedbackCounts);
+    return `#${row.memoryId} severity=${row.severityScore} issues=${row.issueCount}/${row.feedbackCount} ${row.status || '?'}${scope} ${row.canonicalKey || '?'} feedback=${counts}${latest}${resolution}`;
+  }).join('\n');
+}
+
+function formatReviewInspect(result = {}) {
+  const memory = result.memory || {};
+  const review = result.review || {};
+  const visibility = memory.visibility || {};
+  const lines = [
+    `Memory #${memory.memoryId || '?'} ${memory.status || '?'} ${memory.canonicalKey || '?'}`,
+    `Scope: ${memory.scope?.kind || '?'}/${memory.scope?.key || '?'}`,
+    `Visibility: bootstrap=${visibility.bootstrap === true} recall=${visibility.recall === true}`,
+    `Feedback: issues=${review.issueCount || 0}/${review.feedbackCount || 0} ${formatFeedbackCounts(review.feedbackCounts)}`,
+    `Latest resolution: ${formatReviewResolution(review.latestResolution)}`,
+  ];
+  const events = Array.isArray(review.recentFeedback) ? review.recentFeedback : [];
+  if (events.length > 0) {
+    lines.push('Recent feedback:');
+    for (const event of events) {
+      const actor = event.actorId ? `${event.actorKind || 'actor'}:${event.actorId}` : (event.actorKind || 'actor');
+      lines.push(`  #${event.id} ${event.feedbackType} ${actor} at=${formatTimestamp(event.createdAt)}`);
+    }
+  }
+  return lines.join('\n');
+}
+
+function formatReviewResolve(result = {}) {
+  const resolution = result.resolution || {};
+  const memory = result.memory || {};
+  const issueCount = result.review?.issueFeedbackCount || 0;
+  return [
+    `Review resolution recorded: ${resolution.resolution || '?'} for memory #${memory.memoryId || resolution.memoryId || '?'}`,
+    `Canonical key: ${memory.canonicalKey || resolution.canonicalKey || '?'}`,
+    `Issue feedback covered: ${issueCount} ${formatFeedbackCounts(result.review?.issueFeedbackCounts)}`,
+    `Memory mutated: ${result.memoryMutated === true}`,
+  ].join('\n');
+}
+
+async function cmdReview(aquifer, args) {
+  const verb = args._[1] || 'queue';
+  if (verb === 'queue') {
+    const activeScopePath = parseScopePath(args.flags['active-scope-path']);
+    const activeScopeKey = args.flags['active-scope-key']
+      || args.flags['scope-key']
+      || (activeScopePath ? activeScopePath[activeScopePath.length - 1] : undefined);
+    const result = await aquifer.review.queue({
+      feedbackType: args.flags['feedback-type'] || undefined,
+      memoryType: args.flags['memory-type'] || undefined,
+      visibility: args.flags.visibility || undefined,
+      activeScopeKey,
+      activeScopePath,
+      scopeKey: args.flags['scope-key'] || activeScopeKey,
+      canonicalKey: args.flags['canonical-key'] || undefined,
+      dateFrom: args.flags['date-from'] || undefined,
+      dateTo: args.flags['date-to'] || undefined,
+      asOf: args.flags['as-of'] || args.flags['snapshot-as-of'] || undefined,
+      includeResolved: args.flags['include-resolved'] === true,
+      limit: parsePositiveInt(args.flags.limit, 20),
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatReviewQueue(result));
+    return;
+  }
+
+  if (verb === 'inspect') {
+    const activeScopePath = parseScopePath(args.flags['active-scope-path']);
+    const activeScopeKey = args.flags['active-scope-key']
+      || args.flags['scope-key']
+      || (activeScopePath ? activeScopePath[activeScopePath.length - 1] : undefined);
+    const memoryId = args.flags['memory-id'] || args.flags.id || args._[2] || undefined;
+    const canonicalKey = args.flags['canonical-key'] || undefined;
+    if (memoryId && canonicalKey) {
+      console.error('Usage: --memory-id/--id is mutually exclusive with --canonical-key.');
+      process.exit(1);
+    }
+    if (!memoryId && !canonicalKey) {
+      console.error('Usage: aquifer review inspect (--memory-id ID | --canonical-key KEY) [--json]');
+      process.exit(1);
+    }
+    const result = await aquifer.review.inspect({
+      memoryId,
+      canonicalKey,
+      activeScopeKey,
+      activeScopePath,
+      scopeKey: args.flags['scope-key'] || activeScopeKey,
+      visibility: args.flags.visibility || undefined,
+      feedbackType: args.flags['feedback-type'] || undefined,
+      dateFrom: args.flags['date-from'] || undefined,
+      dateTo: args.flags['date-to'] || undefined,
+      asOf: args.flags['as-of'] || args.flags['snapshot-as-of'] || undefined,
+      limit: parsePositiveInt(args.flags.limit, 20),
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatReviewInspect(result));
+    return;
+  }
+
+  if (verb === 'resolve') {
+    const activeScopePath = parseScopePath(args.flags['active-scope-path']);
+    const activeScopeKey = args.flags['active-scope-key']
+      || args.flags['scope-key']
+      || (activeScopePath ? activeScopePath[activeScopePath.length - 1] : undefined);
+    const memoryId = args.flags['memory-id'] || args.flags.id || undefined;
+    const canonicalKey = args.flags['canonical-key'] || undefined;
+    if (memoryId && canonicalKey) {
+      console.error('Usage: --memory-id/--id is mutually exclusive with --canonical-key.');
+      process.exit(1);
+    }
+    if (!memoryId && !canonicalKey) {
+      console.error('Usage: aquifer review resolve (--memory-id ID | --canonical-key KEY) --resolution resolved|ignored|deferred [--json]');
+      process.exit(1);
+    }
+    if (!args.flags['expected-latest-issue-feedback-id'] && !args.flags['expected-latest-issue-feedback-at']) {
+      console.error('Usage: aquifer review resolve requires --expected-latest-issue-feedback-id or --expected-latest-issue-feedback-at.');
+      process.exit(1);
+    }
+    const result = await aquifer.review.resolve({
+      memoryId,
+      canonicalKey,
+      resolution: args.flags.resolution || undefined,
+      reason: args.flags.reason || args.flags.note || undefined,
+      actorKind: args.flags['actor-kind'] || undefined,
+      actorId: args.flags['actor-id'] || args.flags['agent-id'] || undefined,
+      deferUntil: args.flags['defer-until'] || undefined,
+      expectedLatestIssueFeedbackId: args.flags['expected-latest-issue-feedback-id'] || undefined,
+      expectedLatestIssueFeedbackAt: args.flags['expected-latest-issue-feedback-at'] || undefined,
+      activeScopeKey,
+      activeScopePath,
+      scopeKey: args.flags['scope-key'] || activeScopeKey,
+      visibility: args.flags.visibility || undefined,
+      asOf: args.flags['as-of'] || args.flags['snapshot-as-of'] || undefined,
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatReviewResolve(result));
+    return;
+  }
+
+  console.error('Usage: aquifer review <queue|inspect|resolve> [options]');
+  process.exit(1);
+}
+
+async function cmdExplain(aquifer, args) {
+  const lane = args._[1] || 'bootstrap';
+  if (lane === 'bootstrap') {
+    const result = await aquifer.memory.explainBootstrap({
+      activeScopeKey: args.flags['active-scope-key'] || undefined,
+      activeScopePath: parseScopePath(args.flags['active-scope-path']),
+      limit: parsePositiveInt(args.flags.limit, 5),
+      maxChars: parsePositiveInt(args.flags['max-chars'], 4000),
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatExplain(result));
+    return;
+  }
+  if (lane === 'memory') {
+    const query = args.flags.query || args._.slice(2).join(' ');
+    if (!query) {
+      console.error('Usage: aquifer explain memory --query TEXT --active-scope-key KEY [--limit N] [--json]');
+      process.exit(1);
+    }
+    const result = await aquifer.memory.explainCurrent(query, {
+      activeScopeKey: args.flags['active-scope-key'] || undefined,
+      activeScopePath: parseScopePath(args.flags['active-scope-path']),
+      limit: parsePositiveInt(args.flags.limit, 5),
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatExplain(result));
+    return;
+  }
+  console.error('Usage: aquifer explain <bootstrap|memory> [options]');
+  process.exit(1);
+}
+
+function formatOperatorStatus(result = {}) {
+  const compaction = result.compaction || {};
+  const checkpoint = result.checkpoint || {};
+  const lines = [
+    `Compaction: ${compaction.available === false ? 'unavailable' : 'available'} statuses=${JSON.stringify(compaction.statusCounts || {})}`,
+    `Checkpoint: ${checkpoint.available === false ? 'unavailable' : 'available'} statuses=${JSON.stringify(checkpoint.statusCounts || {})}`,
+  ];
+  if (Array.isArray(compaction.staleClaims) && compaction.staleClaims.length > 0) {
+    lines.push(`Stale compaction claims: ${compaction.staleClaims.map(run => `#${run.id}/${run.cadence}`).join(', ')}`);
+  }
+  if (Array.isArray(compaction.latest) && compaction.latest.length > 0) {
+    lines.push('Latest compaction: ' + compaction.latest.map(run => `#${run.id} ${run.status} ${run.cadence}`).join(', '));
+  }
+  if (Array.isArray(checkpoint.latest) && checkpoint.latest.length > 0) {
+    lines.push('Latest checkpoint: ' + checkpoint.latest.map(run => `#${run.id} ${run.status} sources=${run.sourceCount}`).join(', '));
+  }
+  return lines.join('\n');
+}
+
+function formatOperatorInspect(result = {}) {
+  const run = result.run || {};
+  const lines = [
+    `${run.kind || 'operator'} run #${run.id || '?'} status=${run.status || '?'}`,
+  ];
+  if (run.kind === 'compaction') {
+    lines.push(`Window: ${run.cadence || '?'} ${run.periodStart || '?'} -> ${run.periodEnd || '?'}`);
+    lines.push(`Plan: candidates=${run.candidateCount || 0} statusUpdates=${run.statusUpdateCount || 0}`);
+    if (run.leaseExpiresAt) lines.push(`Claim: worker=${run.workerId || '?'} leaseExpiresAt=${run.leaseExpiresAt}`);
+  } else if (run.kind === 'checkpoint') {
+    lines.push(`Checkpoint: scope=${run.scopeId || '?'} key=${run.checkpointKey || '?'}`);
+    lines.push(`Range: ${run.fromFinalizationIdExclusive || 0} -> ${run.toFinalizationIdInclusive || '?'}`);
+    lines.push(`Sources: ${run.sourceCount || 0}`);
+  }
+  if (run.error) lines.push(`Error: ${run.error}`);
+  if (Array.isArray(result.sources) && result.sources.length > 0) {
+    lines.push('Sources:');
+    for (const source of result.sources) {
+      lines.push(`  [${source.sourceIndex}] finalization=${source.finalizationId} ${source.source || '?'}/${source.agentId || '?'}/${source.sessionId || '?'}`);
+    }
+  }
+  return lines.join('\n');
+}
+
 async function cmdOperator(aquifer, args) {
   const operatorVerb = args._[1] || 'compaction';
   const cadenceVerbs = new Set(['manual', 'daily', 'weekly', 'monthly']);
 
+  if (operatorVerb === 'status') {
+    const result = await aquifer.operator.status({
+      limit: parsePositiveInt(args.flags.limit, 10),
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatOperatorStatus(result));
+    return;
+  }
+
+  if (operatorVerb === 'inspect') {
+    const runId = args.flags['run-id'] || args.flags.id || args._[2];
+    if (!runId) {
+      console.error('Usage: aquifer operator inspect --run-id ID [--kind compaction|checkpoint] [--json]');
+      process.exit(1);
+    }
+    const result = await aquifer.operator.inspect({
+      runId,
+      kind: args.flags.kind || 'compaction',
+    });
+    if (args.flags.json) {
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    console.log(formatOperatorInspect(result));
+    return;
+  }
+
   if (operatorVerb === 'checkpoint') {
     const synthesisSummary = readSynthesisSummaryFromFlags(args.flags);
     const result = await aquifer.checkpoints.runProducer({
@@ -830,15 +1304,21 @@ Commands:
    quickstart                  Verify end-to-end setup (migrate → commit → enrich → recall)
    migrate                     Run database migrations
   backend-info                Show selected backend capabilities without connecting to a database
+  install-openclaw           Install/update OpenClaw MCP + extension wiring
+  doctor                     Run read-only health diagnostics
   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
+  review ...                  Inspect or resolve memory feedback review queue
   backfill                    Enrich pending sessions
+  backlog                     Explain and plan saved-content preparation work
   operator ...                Run operator-safe consolidation jobs
+  finalization ...            Inspect read-only finalization ledger
+  explain ...                 Explain current-memory serving decisions
   compact                     Plan or apply curated memory compaction
-  stats                       Show database statistics
+  stats                       Check memory readiness
   export                      Export sessions as JSONL
   bootstrap                   Show recent session context (for new session start)
   codex-recovery ...          Inspect or run Codex recovery/checkpoint flows
@@ -853,11 +1333,35 @@ Options:
   --date-to YYYY-MM-DD        End date
   --entities A,B,C            Entity names (comma-separated, recall)
   --entity-mode any|all       Entity match mode (recall, default: any)
+  --id ID                     Finalization row id
+  --host HOST                 Finalization host filter
+  --status STATUS             Finalization status filter
+  --plan inspect|backfill|skip
+                              Saved-content dry-run action plan
+  --diagnostics               Include raw counters, buckets, samples, and serving diagnostics
+  --phase PHASE               Finalization phase filter
+  --transcript-hash HASH      Finalization transcript hash filter
+  --run-id ID                 Operator run id
+  --kind KIND                 Operator inspect kind: compaction|checkpoint
+  --query TEXT                Explain memory query
   --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)
+  --memory-id ID              Curated memory record ID (memory-feedback, review inspect/resolve)
+  --canonical-key KEY         Active curated memory canonical key (memory-feedback, review queue/inspect/resolve)
   --verdict helpful|unhelpful Feedback verdict (feedback)
   --feedback-type TYPE        Curated memory feedback type
+  --memory-type TYPE          Curated memory type filter (review queue)
+  --visibility MODE           Review visibility filter: either|both|bootstrap|recall
+  --as-of ISO                 Review queue memory validity instant
+  --include-resolved          Include currently resolved review items in review queue
+  --resolution ACTION         Review resolution: resolved|ignored|deferred
+  --reason TEXT               Operator reason for review resolution
+  --actor-kind KIND           Review resolution actor kind: user|agent|system|curator
+  --actor-id ID               Review resolution actor id
+  --defer-until ISO           Re-open deferred review item after this instant
+  --expected-latest-issue-feedback-id ID
+                              Reject review resolution if newer issue feedback exists
+  --expected-latest-issue-feedback-at ISO
+                              Timestamp guard for review resolution snapshots
   --note TEXT                 Feedback note (feedback)
   --explain                    Show score breakdown per result (recall)
   --allow-unsafe-debug        Allow broad evidence-recall without audit boundary
@@ -865,6 +1369,11 @@ Options:
   --dry-run                   Preview only (backfill)
   --output PATH               Output file (export)
   --config PATH               Config file path
+  --openclaw-home PATH        OpenClaw home path (install-openclaw)
+  --skip-extension            Do not wire the OpenClaw extension/plugin (install-openclaw)
+  --skip-mcp                  Do not update mcp.servers.aquifer (install-openclaw)
+  --force                     Move aside existing extension path if needed (install-openclaw)
+  --link-current-package      Development only: wire the current checkout instead of OpenClaw node_modules
   --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
@@ -890,6 +1399,17 @@ Options:
   --min-messages N            Min user messages to ingest (ingest-opencode, default: 3)
 
 Operator examples:
+  aquifer doctor --json
+  aquifer finalization list --status finalized --json
+  aquifer finalization inspect --id 42 --json
+  aquifer finalization inspect --session-id SESSION --agent-id main --source codex --transcript-hash HASH
+  aquifer explain bootstrap --active-scope-key project:aquifer --json
+  aquifer explain memory --query "serving contract" --active-scope-key project:aquifer --json
+  aquifer review queue --scope-key project:aquifer --feedback-type incorrect --json
+  aquifer review inspect --memory-id 42 --json
+  aquifer review resolve --memory-id 42 --resolution resolved --reason "verified current" --json
+  aquifer operator status --json
+  aquifer operator inspect --run-id 42 --kind compaction --json
   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
@@ -898,7 +1418,9 @@ Operator examples:
   aquifer operator checkpoint --scope-id 7 --synthesis-summary-file /tmp/checkpoint-summary.json --apply --finalize --json
   AQUIFER_BACKEND=local aquifer backend-info --json
   aquifer codex-recovery checkpoint-heartbeat --hook-stdin --scope-key project:aquifer
+  aquifer codex-recovery checkpoint-spool-status --json --limit 10
   aquifer codex-recovery checkpoint-heartbeat-hook --scope-key project:aquifer --hooks-path "$CODEX_HOME/hooks.json" --json
+  aquifer install-openclaw --openclaw-home "$OPENCLAW_HOME"
   aquifer operator archive-distill --input /tmp/archive-snapshot.json --json`);
     process.exit(0);
   }
@@ -939,6 +1461,11 @@ Operator examples:
     return;
   }
 
+  if (command === 'install-openclaw') {
+    await require('./openclaw-install').cmdInstallOpenClaw(args);
+    return;
+  }
+
   // All other commands need an Aquifer instance
   const configOverrides = {};
   if (args.flags.config) {
@@ -986,6 +1513,9 @@ Operator examples:
       case 'migrate':
         await cmdMigrate(aquifer, args);
         break;
+      case 'doctor':
+        await cmdDoctor(aquifer, args);
+        break;
       case 'recall':
         await cmdRecall(aquifer, args);
         break;
@@ -1001,12 +1531,24 @@ Operator examples:
       case 'feedback-stats':
         await cmdFeedbackStats(aquifer, args);
         break;
+      case 'review':
+        await cmdReview(aquifer, args);
+        break;
       case 'backfill':
         await cmdBackfill(aquifer, args);
         break;
+      case 'backlog':
+        await cmdBacklog(aquifer, args);
+        break;
       case 'operator':
         await cmdOperator(aquifer, args);
         break;
+      case 'finalization':
+        await cmdFinalization(aquifer, args);
+        break;
+      case 'explain':
+        await cmdExplain(aquifer, args);
+        break;
       case 'compact':
         await cmdCompact(aquifer, args);
         break;
@@ -1039,8 +1581,20 @@ module.exports = {
   selectedBackendInfo,
   cmdBackendInfo,
   cmdMigrate,
+  cmdDoctor,
   cmdLocalQuickstart,
   cmdOperator,
+  cmdBacklog,
+  cmdFinalization,
+  cmdExplain,
+  cmdReview,
+  formatDoctor,
+  formatFinalizationList,
+  formatFinalizationInspect,
+  formatExplain,
+  formatReviewQueue,
+  formatReviewInspect,
+  cmdInstallOpenClaw: require('./openclaw-install').cmdInstallOpenClaw,
   readSynthesisSummaryFromFlags,
 };