@ijfw/memory-server 1.5.0 → 1.5.3

package/src/cross-orchestrator-cli.js

@@ -62,6 +62,8 @@ import {
 } from './swarm/worktree.js';
 import { renderSwarmDispatchPrompt } from './swarm/dispatch-prompt.js';
 import { syncCodexAgents } from './codex-agents.js';
+// v1.5.1 W2.H — memory benchmark harness (T22). Surfaced via `ijfw metrics --benchmark`.
+import { runBenchmark } from './memory/benchmark.js';
 import {
   DESIGN_ACTIONS,
   auditDesignText,
@@ -69,6 +71,12 @@ import {
   initialDesignMarkdown,
   loadDesignContext,
 } from './design-intelligence.js';
+// v1.5.1 W3.A.4 — registry-driven usage + alias help.
+// SINGLE SOURCE OF TRUTH lives at installer/src/command-registry.js;
+// import sibling-package style, matching extension-installer.js precedent.
+import {
+  COMMAND_REGISTRY,
+} from '../../installer/src/command-registry.js';
 
 // ---------------------------------------------------------------------------
 // Auditor error translator (1.2.5)
@@ -219,68 +227,19 @@ function parseArgs(argv) {
   return out;
 }
 
-const COMMAND_ALIAS_HELP = {
-  workflow: {
-    title: 'IJFW workflow',
-    usage: 'Use the ijfw-workflow skill in agents. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare.',
-  },
-  handoff: {
-    title: 'IJFW handoff',
-    usage: 'Use the ijfw-handoff skill in agents, or record swarm handoff text with: ijfw blackboard handoff --message "<summary>".',
-  },
-  compress: {
-    title: 'IJFW compress',
-    usage: 'Use the ijfw-compress skill in agents. Terminal context compression is host-specific and should preserve exact paths, commands, versions, and decisions.',
-  },
-  consolidate: {
-    title: 'IJFW consolidate',
-    usage: 'Use the ijfw-handoff or ijfw-memory-audit skill to consolidate decisions into memory. For swarm state, run: ijfw memory checkpoint <label>.',
-  },
-  'ijfw-audit': {
-    title: 'IJFW audit',
-    usage: 'Run verification with: ijfw preflight. For multi-model review, run: ijfw cross audit <target>.',
-  },
-  'ijfw-execute': {
-    title: 'IJFW execute',
-    usage: 'Use ijfw-workflow in agents, then terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare, ijfw swarm start <task-id>.',
-  },
-  'ijfw-help': {
-    title: 'IJFW help',
-    usage: 'Run: ijfw help. Add --browser for the rendered local guide.',
-  },
-  'ijfw-plan': {
-    title: 'IJFW plan',
-    usage: 'Use ijfw-workflow for planning. Terminal helpers: ijfw team init, ijfw swarm plan, ijfw swarm prepare --reviews.',
-  },
-  'ijfw-ship': {
-    title: 'IJFW ship',
-    usage: 'Run: ijfw preflight. Do not publish or tag until your release gate is explicitly cleared.',
-  },
-  'ijfw-verify': {
-    title: 'IJFW verify',
-    usage: 'Run: ijfw preflight. For focused review, run: ijfw cross audit <target>.',
-  },
-  'memory-audit': {
-    title: 'IJFW memory audit',
-    usage: 'Use the ijfw-memory-audit skill in agents. Terminal safety net: ijfw recover status and ijfw memory checkpoint <label>.',
-  },
-  'memory-consent': {
-    title: 'IJFW memory consent',
-    usage: 'Use IJFW memory tools only for explicit project memory. Terminal checkpoint: ijfw memory checkpoint <label>.',
-  },
-  'memory-why': {
-    title: 'IJFW memory why',
-    usage: 'Use ijfw-recall or ijfw-memory-audit in agents to inspect why memory exists. Terminal recovery state: ijfw recover latest.',
-  },
-  metrics: {
-    title: 'IJFW metrics',
-    usage: 'Open the dashboard with: ijfw dashboard start. Agent-side metrics are available through ijfw_metrics.',
-  },
-  mode: {
-    title: 'IJFW mode',
-    usage: 'Inspect configuration with: ijfw config --audit. Statusline mode helpers: ijfw statusline --status, --compose, or --disable.',
-  },
-};
+// v1.5.1 W3.A.4 — COMMAND_ALIAS_HELP is now derived from the command-registry
+// (entries where tier === 'pointer-stub'). Each entry's deprecatedReason
+// becomes the usage line; title is auto-derived from the canonical name.
+// To change the help text or add a new pointer-stub: edit
+// installer/src/command-registry.js.
+const COMMAND_ALIAS_HELP = Object.freeze(Object.fromEntries(
+  COMMAND_REGISTRY
+    .filter(e => e.tier === 'pointer-stub')
+    .map(e => [e.name, {
+      title: `IJFW ${e.name}`,
+      usage: e.deprecatedReason,
+    }])
+));
 
 function parseCrossAlias(mode, args) {
   let only = null;
@@ -313,6 +272,16 @@ function parseCommandAlias(args) {
     return parseCrossAlias('research', args);
   }
   if (Object.prototype.hasOwnProperty.call(COMMAND_ALIAS_HELP, name)) {
+    // v1.5.1 W2.H — `ijfw metrics` is a deprecated pointer-stub, but
+    // `ijfw metrics --benchmark` surfaces the memory benchmark harness (T22).
+    // Bare `ijfw metrics` still falls through to the deprecation redirect.
+    if (name === 'metrics' && args.includes('--benchmark')) {
+      const opts = { cmd: 'metrics-benchmark', json: args.includes('--json'), write: true };
+      for (let i = 1; i < args.length; i++) {
+        if (args[i] === '--no-write') opts.write = false;
+      }
+      return opts;
+    }
     return { cmd: 'command-alias', alias: name };
   }
   return null;
@@ -441,6 +410,13 @@ function parseArgsInner(args) {
     return { cmd: 'extension', sub: args[1] || 'list', rest: args.slice(2) };
   }
 
+  if (args[0] === 'env') {
+    // v1.5.2 F6: `ijfw env` lists every IJFW_* env var with current value,
+    // default, and one-line description. Closes the configuration-sprawl
+    // discoverability gap surfaced in the v1.5.2 cross-audit.
+    return { cmd: 'env' };
+  }
+
   if (args[0] === 'swarm') {
     return { cmd: 'swarm', sub: args[1] || 'status' };
   }
@@ -449,8 +425,25 @@ function parseArgsInner(args) {
     return { cmd: 'codex', sub: args[1] || 'doctor' };
   }
 
-  if (args[0] === 'memory' && args[1] === 'checkpoint') {
-    return { cmd: 'memory-checkpoint', label: args[2] || 'manual' };
+  if (args[0] === 'memory') {
+    // `ijfw memory` / `ijfw memory --help` / `ijfw memory -h` → namespace help
+    if (args.length === 1 || args[1] === '--help' || args[1] === '-h') {
+      return { cmd: 'memory-help' };
+    }
+    if (args[1] === 'checkpoint') {
+      return { cmd: 'memory-checkpoint', label: args[2] || 'manual' };
+    }
+    if (args[1] === 'reindex') {
+      // `ijfw memory reindex`        -> M1 backfill (free, obsidian indexing)
+      // `ijfw memory reindex --m2`   -> also run M2 A-Mem auto-link backfill
+      //                                 (budget-gated; needs IJFW_AUTOLINK_*)
+      let m2 = false;
+      for (let i = 2; i < args.length; i++) {
+        if (args[i] === '--m2' || args[i] === '--autolink') m2 = true;
+      }
+      return { cmd: 'memory-reindex', m2 };
+    }
+    return { cmd: 'memory-unknown', sub: args[1] };
   }
 
   if (args[0] === 'recover') {
@@ -514,86 +507,67 @@ function parseArgsInner(args) {
 // Commands
 // ---------------------------------------------------------------------------
 
-function printUsage() {
+// v1.5.2 F6: every IJFW_* env var the brain + memory subsystems read at runtime.
+// Order: most-likely-to-set first. `default` is the documented fallback when
+// the var is unset; `description` is one short line for `ijfw env` output.
+const IJFW_ENV_VARS = [
+  // Brain (v1.5.2)
+  { name: 'IJFW_DREAM_BUDGET_USD',     default: '0.50',                                description: 'Per-cycle USD cap for dream-cycle LLM extraction.' },
+  { name: 'IJFW_DREAM_BUDGET_DAY_USD', default: '5.00',                                description: 'Per-day USD cap; cycle stops when reached.' },
+  { name: 'IJFW_BRAIN_LOCAL_URL',      default: '(unset)',                             description: 'Ollama-compatible local LLM endpoint to try first.' },
+  { name: 'IJFW_BRAIN_EXTRACT_MODEL',  default: 'claude-haiku-4-5-20251001',           description: 'Cheap-tier model id for fact extraction.' },
+  { name: 'IJFW_BRAIN_SYNTH_MODEL',    default: 'claude-sonnet-4-6',                   description: 'Mid-tier model id for reconciliation + page synthesis.' },
+  { name: 'IJFW_BRAIN_API_KEY',        default: '(falls back to ANTHROPIC_API_KEY)',   description: 'API key for the synth-tier Anthropic call.' },
+  { name: 'IJFW_BRAIN_INJECT',         default: 'never',                               description: '"auto"|"always" appends top-N wiki pages to handlePrelude.' },
+  // Memory-moat (v1.5.0 — A-Mem auto-linker)
+  { name: 'IJFW_AUTOLINK_OFF',         default: '(unset)',                             description: 'Set to disable the A-Mem auto-linker entirely.' },
+  { name: 'IJFW_AUTOLINK_BUDGET_USD',  default: '(unbounded if unset)',                description: 'Per-write USD cap for auto-linker LLM calls.' },
+  { name: 'IJFW_AUTOLINK_BACKFILL',    default: '(unset)',                             description: 'Set to "1" to opt into M2 backfill during `memory reindex --m2`.' },
+];
+
+export function cmdEnv() {
+  const widthName = Math.max(...IJFW_ENV_VARS.map((v) => v.name.length)) + 2;
+  console.log('IJFW environment variables\n');
+  for (const v of IJFW_ENV_VARS) {
+    const current = process.env[v.name];
+    const shownValue = current !== undefined && current !== '' ? current : '(unset)';
+    const isOverridden = current !== undefined && current !== '';
+    const tag = isOverridden ? ' [SET]' : '';
+    console.log(`  ${v.name.padEnd(widthName)} = ${shownValue}${tag}`);
+    console.log(`  ${' '.repeat(widthName)}   default: ${v.default}`);
+    console.log(`  ${' '.repeat(widthName)}   ${v.description}`);
+    console.log('');
+  }
+  console.log('Tip: variables tagged [SET] override their defaults. Unset values show the documented default in effect.');
+}
+
+function printMemoryHelp() {
   console.log(`
-ijfw -- It Just Fucking Works CLI
-Fire 2-4 AIs at any target. Receipts logged. Cache hits tracked. Memory follows you.
+ijfw memory -- project memory namespace
 
 Usage:
-  ijfw install
-  ijfw uninstall
-  ijfw preflight
-  ijfw dashboard [start|stop|status]
-  ijfw design [start|open|status|stop|push|clear|init|plan|audit|critique|polish|normalize|bolder|quieter|handoff]
-  ijfw blackboard [init|status|claim|release|note|handoff]
-  ijfw team [init|status]
-  ijfw swarm [plan|prepare|tasks|prompt|start|complete|block|ready|status]
-  ijfw swarm worktree [create|list|integrate|cleanup]
-  ijfw codex [doctor|sync-agents]
-  ijfw memory checkpoint <label>
-  ijfw recover [status|latest]
-  ijfw cross <mode> <target> [options]
-  ijfw cross project-audit <rule-file> [--dry-run]
-  ijfw import <tool> [--all] [--dry-run] [--force] [--path <p>]
-  ijfw status
-  ijfw doctor
-  ijfw update
-  ijfw receipt last
-  ijfw --purge-receipts
-  ijfw --help
-
-Commands:
-  install           Install IJFW into your AI coding agents.
-  uninstall         Remove IJFW and revert AI-agent configs. Same as: ijfw off
-  preflight         Run the 11-gate quality pipeline (blocking + advisory).
-  dashboard         Control the dashboard server (start, stop, status).
-  design            Control the live visual design companion.
-  blackboard        Coordinate project-local swarm state and artifact claims.
-  team              Assemble project agents, charter, and workflow manifest.
-  swarm             Plan artifact-aware parallel work from the team manifest.
-  recover           Show the latest checkpoint and next recovery step.
-  demo              30-second live tour of the Trident (fires real auditors).
-  cross             Fire external auditors at a target. Try: ijfw cross audit README.md
-  import            Pull memory in from another tool. Try: ijfw import claude-mem --all
-  status            Show recent cross-audit activity. Try: ijfw status
-  doctor            Probe which CLIs and API keys are reachable. Try: ijfw doctor
-  update            Pull latest IJFW + reinstall merge-safely. Try: ijfw update
-  update --check    Non-invasive check. Exits 0 always; prints "update-available: <ver>" when an update exists (grep-safe).
-  receipt last      Print a redacted, shareable block from the last Trident run.
-  --purge-receipts  Clear the cross-runs receipt log. Try: ijfw --purge-receipts
-
-Modes (for ijfw cross):
-  audit           Adversarial review of a file, module, or path
-  research        Multi-source research on a topic
-  critique        Structured counter-argument generation
-  project-audit   Run the same audit across every registered IJFW project
-                  Usage: ijfw cross project-audit <rule-file> [--dry-run]
-
-Options for ijfw cross:
-  --with <id>   Force a specific auditor (comma-separated for multiple)
-  --confirm     Prompt for confirmation before firing
-  --expand      Include extended swarm when available
-
-Global flags:
-  --json    Emit JSON instead of human output. status and doctor auto-JSON
-            on non-TTY (gh-CLI convention); version stays one-line on pipe
-            and only JSON-ifies with explicit --json. Other commands ignore.
-
-Environment:
-  IJFW_AUDIT_BUDGET_USD   Session spend cap (default $2.00). First call is always
-                          allowed (no cap). Cap enforced from the 2nd call on.
-
-Examples:
-  ijfw demo
-  ijfw cross audit README.md
-  ijfw cross research "vector search approaches"
-  ijfw cross critique HEAD~3..HEAD
-  ijfw cross audit CLAUDE.md --with codex,gemini
-  ijfw status
-  ijfw doctor
+  ijfw memory checkpoint <label>   Snapshot current swarm/memory state under <label>.
+                                   <label> defaults to "manual" if omitted.
+  ijfw memory reindex [--m2]       Backfill M1 obsidian indexing (wikilinks,
+                                   #tags, [k:: v] metadata) over the whole
+                                   memory db. Free + idempotent. Add --m2 to
+                                   also run the A-Mem auto-link backfill --
+                                   budget-gated (set IJFW_AUTOLINK_BUDGET_USD
+                                   and IJFW_AUTOLINK_BACKFILL=1).
+
+Related:
+  ijfw recover [status|latest]     Inspect checkpoints and recovery state.
+  ijfw env                         List every IJFW_* env var, current value, default, description.
+  ijfw --help                      Top-level user-facing commands.
+  ijfw commands                    Full command surface (all verbs).
 `.trim());
 }
 
+function printUnknownCommand(raw) {
+  console.error(`Unknown command: ${raw}`);
+  console.error('Run `ijfw --help` for the user-facing command list, or `ijfw commands` for the full surface.');
+}
+
 function cmdCommandAlias(alias) {
   const info = COMMAND_ALIAS_HELP[alias];
   if (!info) {
@@ -606,6 +580,41 @@ function cmdCommandAlias(alias) {
   process.exit(0);
 }
 
+// v1.5.1 W2.H — `ijfw metrics --benchmark`: run the memory benchmark harness
+// (T22) against IJFW's own 3-tier store and report recall@k, MRR/NDCG-style
+// retrieval quality, throughput, and p50/p95/p99 latency. See
+// docs/MEMORY-BENCHMARK.md for the axes and how to interpret the numbers.
+async function cmdMetricsBenchmark(opts = {}) {
+  const results = await runBenchmark({
+    root: process.cwd(),
+    write: opts.write !== false,
+  });
+
+  if (wantsJson(opts)) {
+    emitJson(results);
+    return;
+  }
+
+  const q = results.axes.query_warm_fts5;
+  const ing = results.axes.ingest;
+  const recallPairs = Object.entries(q.recall || {});
+  console.log('IJFW memory benchmark (T22)');
+  console.log('');
+  console.log(`  corpus            ${results.corpus.docs} docs / ${results.corpus.queries} queries / ${results.corpus.total_query_samples} timed samples`);
+  console.log(`  ingest throughput ${ing.throughput_rps} rows/s`);
+  console.log(`  ingest latency    p50 ${ing.latency_ms.p50}ms  p95 ${ing.latency_ms.p95}ms  p99 ${ing.latency_ms.p99}ms`);
+  console.log(`  query latency     p50 ${q.latency_ms.p50}ms  p95 ${q.latency_ms.p95}ms  p99 ${q.latency_ms.p99}ms`);
+  console.log(`  recall            ${recallPairs.map(([k, v]) => `${k}=${v.toFixed(3)}`).join('  ')}`);
+  console.log(`  storage           ${results.axes.storage.bytes_per_memory} bytes/memory (${results.axes.storage.rows_indexed} rows)`);
+  console.log(`  cold tier         ${results.axes.query_cold_vector.available ? 'available' : 'reserved (no embedding model)'}`);
+  if (results.artifact_path) {
+    console.log('');
+    console.log(`  artifact          ${results.artifact_path}`);
+  }
+  console.log('');
+  console.log('Axes explained: docs/MEMORY-BENCHMARK.md');
+}
+
 async function cmdStatus(projectDir, opts = {}) {
   const receipts = readReceipts(projectDir);
   const last = receipts[receipts.length - 1];
@@ -696,8 +705,6 @@ async function cmdDemo() {
 
   let result;
   try {
-    // TODO post-merge: perAuditorTimeoutSec, minResponses, quiet are added by Item 2 agent.
-    // Passed through here; current orchestrator silently ignores unknown params.
     result = await runCrossOp({
       mode: 'audit',
       target,
@@ -1072,7 +1079,7 @@ async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
       const chunks = buildChunkedTargets(absPath, rawTarget);
       console.log('');
       console.log(`--chunk: splitting ${rawTarget} into ${chunks.length} chunks (≈${(CHUNKER_DEFAULTS.chunkSize / 1024).toFixed(0)} KB each, ${(CHUNKER_DEFAULTS.overlap / 1024).toFixed(0)} KB overlap).`);
-      console.log(`Trident dispatches: ${chunks.length} × per-chunk audit. Cost scales linearly.`);
+      console.log(`Trident dispatches: ${chunks.length} x per-chunk audit. Cost scales linearly.`);
 
       const perChunkResults = [];
       const auditorIds = new Set();
@@ -1107,7 +1114,7 @@ async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
       }
       for (const f of merged) {
         const sev = (f.severity || 'note').toUpperCase();
-        const cluster = f.clusterSize > 1 ? ` [×${f.clusterSize}]` : '';
+        const cluster = f.clusterSize > 1 ? ` [x${f.clusterSize}]` : '';
         const tgt = f.target ? ` ${f.target} —` : '';
         // v1.5.0 wire-W4: widen field fallback to cover description/issue/
         // detail/note/summary keys auditors emit. Closes the r19 "(no detail)"
@@ -2353,10 +2360,25 @@ if (isMainModule) {
   }
 
   if (parsed.cmd === 'help') {
-    printUsage();
+    // v1.5.1 W1.D+E: orchestrator-side help is handled by the installer
+    // (`ijfw --help` for the primary surface, `ijfw commands` for full).
+    // Print a pointer instead of the old stale Usage block.
+    console.log('Run `ijfw --help` for the user-facing command list, or `ijfw commands` for the full surface.');
     process.exit(0);
   }
 
+  if (parsed.cmd === 'memory-help') {
+    printMemoryHelp();
+    process.exit(0);
+  }
+
+  if (parsed.cmd === 'memory-unknown') {
+    console.error(`Unknown memory subcommand: ${parsed.sub}`);
+    console.error('');
+    printMemoryHelp();
+    process.exit(1);
+  }
+
   if (parsed.cmd === 'status') {
     cmdStatus(process.cwd(), parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'demo') {
@@ -2367,6 +2389,8 @@ if (isMainModule) {
     cmdCrossProjectAudit(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'command-alias') {
     cmdCommandAlias(parsed.alias);
+  } else if (parsed.cmd === 'metrics-benchmark') {
+    cmdMetricsBenchmark(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'import') {
     cmdImport(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'doctor') {
@@ -2411,11 +2435,15 @@ if (isMainModule) {
     cmdCodex(parsed.sub);
   } else if (parsed.cmd === 'memory-checkpoint') {
     cmdMemoryCheckpoint(parsed.label);
+  } else if (parsed.cmd === 'memory-reindex') {
+    cmdMemoryReindex(parsed).catch(err => { console.error(err.message); process.exit(1); });
+  } else if (parsed.cmd === 'env') {
+    cmdEnv();
   } else if (parsed.cmd === 'recover') {
     cmdRecover(parsed.sub);
   } else {
-    console.error(`Unknown command: ${parsed.raw}`);
-    printUsage();
+    // v1.5.1 W1.D+E: clean unknown-command message; no stale usage dump.
+    printUnknownCommand(parsed.raw);
     process.exit(1);
   }
 }
@@ -2433,10 +2461,19 @@ function repoRootFromCli() {
   return join(here, '..', '..');
 }
 function findCliAsset(...rel) {
+  // F-C-4 (Lens 3): probe XDG_DATA_HOME and XDG_CONFIG_HOME in addition to
+  // ~/.ijfw and IJFW_HOME. Users who installed via a distro-aware packager
+  // (e.g. dotfiles repo, nix, distro RPM, or any wrapper that honours XDG
+  // base-dir spec) land their ijfw tree under $XDG_DATA_HOME/ijfw rather
+  // than ~/.ijfw, and were silently invisible to the doctor fallback.
+  const xdgData = process.env.XDG_DATA_HOME;
+  const xdgConfig = process.env.XDG_CONFIG_HOME;
   const candidates = [
     join(repoRootFromCli(), ...rel),
     process.env.IJFW_HOME ? join(process.env.IJFW_HOME, ...rel) : null,
     join(homedir(), '.ijfw', ...rel),
+    xdgData ? join(xdgData, 'ijfw', ...rel) : null,
+    xdgConfig ? join(xdgConfig, 'ijfw', ...rel) : null,
   ].filter(Boolean);
   return candidates.find(p => existsSync(p)) || null;
 }
@@ -2935,6 +2972,42 @@ function cmdCodex(sub) {
   process.exit(1);
 }
 
+// F4.1/F4.2: resolve the canonical IJFW version with explicit source labelling
+// and a corrupt-vs-missing distinction. Exported so the codex-doctor tests can
+// exercise the fallback matrix without spawning the CLI against synthetic
+// repo trees. Inputs are absolute paths (or null) so callers can stub them.
+//
+// Returns: { canonicalVersion, canonicalSource, canonicalParseError } where
+//   canonicalVersion : string | null  (first source whose JSON parses)
+//   canonicalSource  : 'installer' | 'mcp-server' | null
+//   canonicalParseError : string | null  (only set if installer pkg corrupt)
+export function resolveCanonicalVersion({ installerPkg, selfPkg } = {}) {
+  let canonicalVersion = null;
+  let canonicalSource = null;
+  let canonicalParseError = null;
+  for (const [src, p] of [['installer', installerPkg], ['mcp-server', selfPkg]]) {
+    if (!p || !existsSync(p)) continue;
+    let raw;
+    try {
+      raw = readFileSync(p, 'utf8');
+    } catch { continue; }
+    try {
+      canonicalVersion = JSON.parse(raw).version;
+      canonicalSource = src;
+      break;
+    } catch (e) {
+      // F-C-2 (Lens 3): capture parse error from whichever source was attempted
+      // and label the source. Previously only installer parse errors surfaced,
+      // so a corrupt mcp-server/package.json (e.g. partial pnpm install) caused
+      // the doctor to render misleading "install @ijfw/install" fix text.
+      if (canonicalParseError == null) {
+        canonicalParseError = `${src}: ${e.message}`;
+      }
+    }
+  }
+  return { canonicalVersion, canonicalSource, canonicalParseError };
+}
+
 function codexDoctor(projectRoot) {
   const root = resolve(projectRoot);
   const checks = [];
@@ -2962,12 +3035,50 @@ function codexDoctor(projectRoot) {
   const agentsMd = join(root, 'AGENTS.md');
 
   const plugin = readJsonFile(pluginPath);
+  // v1.5.2.1: read the canonical version dynamically from
+  // installer/package.json instead of comparing against a hardcoded literal.
+  // The previous hardcoded '1.3.2' check drifted out of sync on every
+  // release (latest observed: project at 1.5.1, doctor still expecting
+  // 1.3.2 → false-positive failures on every fresh install). Reading from
+  // installer/package.json keeps the doctor honest as long as that file
+  // and the codex plugin.json are bumped together at ship-gate.
+  //
+  // F4.1: standalone @ijfw/memory-server installs do not ship installer/.
+  // F4.3: regressing against the established findCliAsset() convention. Reuse it.
+  // F4.2: differentiate ENOENT (missing) from SyntaxError (corrupt).
+  const { canonicalVersion, canonicalSource, canonicalParseError } =
+    resolveCanonicalVersion({
+      installerPkg: findCliAsset('installer', 'package.json'),
+      // F-C-1 (Lens 3): IJFW_HOME fallback was previously installer-only; make
+      // mcp-server resolution symmetric so a custom-checkout user with IJFW_HOME
+      // pointed at a partial tree also gets a working fallback.
+      selfPkg: findCliAsset('mcp-server', 'package.json')
+        ?? join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json'),
+    });
   checks.push({
     name: 'plugin metadata',
-    ok: plugin?.version === '1.3.2',
+    ok: !!plugin && !!canonicalVersion && plugin.version === canonicalVersion,
     required: true,
-    message: plugin ? `version ${plugin.version}` : 'missing plugin.json',
-    fix: 'update codex/.codex-plugin/plugin.json',
+    message: plugin
+      ? (canonicalVersion
+          ? `version ${plugin.version}${plugin.version === canonicalVersion ? '' : ` (expected ${canonicalVersion} per ${canonicalSource}/package.json)`}`
+          : canonicalParseError
+            ? `version ${plugin.version} (canonical source corrupt: ${canonicalParseError})`
+            : `version ${plugin.version} (canonical version unreadable -- install @ijfw/install or set IJFW_HOME)`)
+      : 'missing plugin.json',
+    // F-C-9 (Lens 3): if plugin.json itself is missing, the fix text needs
+    // to point at restoring plugin.json, NOT at the canonical-version dance.
+    // canonicalParseError is now source-labelled by F-C-2 ("installer: ..."
+    // or "mcp-server: ..."), so derive the specific package.json to restore.
+    fix: !plugin
+      ? `restore codex/.codex-plugin/plugin.json (try \`git checkout codex/.codex-plugin/plugin.json\`)`
+      : canonicalVersion
+        ? (plugin.version !== canonicalVersion
+            ? `update codex/.codex-plugin/plugin.json version to ${canonicalVersion}`
+            : null)
+        : canonicalParseError
+          ? `restore canonical source (try \`git checkout ${canonicalParseError.split(':')[0]}/package.json\`)`
+          : `install @ijfw/install (npm i -g @ijfw/install), or set IJFW_HOME=<ijfw-repo-checkout>`,
   });
 
   const hooks = readJsonFile(hooksPath);
@@ -2981,11 +3092,23 @@ function codexDoctor(projectRoot) {
     fix: 'restore codex/.codex/hooks.json and hook scripts',
   });
 
+  // C11 — the message MUST track the same condition `ok` does. Previously the
+  // message said "ijfw-memory configured" whenever config.toml merely existed,
+  // so a config.toml present-but-missing-the-ijfw-memory-block printed the
+  // [ !! ] failure glyph (ok=false) next to success text. Branch all three
+  // states: file absent, file present-but-unconfigured, file configured.
+  const _codexConfigExists = existsSync(configPath);
+  const _codexMemoryConfigured =
+    _codexConfigExists && readFileSync(configPath, 'utf8').includes('ijfw-memory');
   checks.push({
     name: 'MCP config',
-    ok: existsSync(configPath) && readFileSync(configPath, 'utf8').includes('ijfw-memory'),
+    ok: _codexMemoryConfigured,
     required: true,
-    message: existsSync(configPath) ? 'ijfw-memory configured' : 'missing config.toml',
+    message: _codexMemoryConfigured
+      ? 'ijfw-memory configured'
+      : _codexConfigExists
+        ? 'config.toml present but ijfw-memory not configured'
+        : 'missing config.toml',
     fix: 'run ijfw install or restore codex/.codex/config.toml',
   });
 
@@ -3355,6 +3478,69 @@ function cmdMemoryCheckpoint(label) {
   process.exit(0);
 }
 
+// v1.5.1 R5-1.2 -- `ijfw memory reindex [--m2]`. Closes Trident r5 finding
+// 1.2: memory written during v1.5.0 (before Round-4 Fix-1 wired M1/M2 into
+// the production write path) has empty memory_links / memory_tags /
+// memory_meta. Migration 009 already backfills M1 once on upgrade; this verb
+// is the manual re-run path AND the only way to opt into the M2 (A-Mem
+// auto-link) backfill, which is budget-gated because it makes one LLM call
+// per row.
+async function cmdMemoryReindex(parsed) {
+  const projectRoot = process.cwd();
+  // Lazy import: better-sqlite3 is heavy; only pay for it on this verb.
+  const { openDb, closeDb, dbPathFor } = await import('./memory/fts5.js');
+  const { backfillObsidianIndex } = await import('./memory/obsidian-parser.js');
+  const { backfillAutoLink } = await import('./memory/auto-linker.js');
+
+  let db;
+  try {
+    db = await openDb(projectRoot);
+  } catch (e) {
+    console.error(`Memory db unavailable: ${e.message}`);
+    process.exit(1);
+  }
+
+  try {
+    console.log(`Reindexing memory at ${dbPathFor(projectRoot)}`);
+    // M1 -- always. Free + idempotent obsidian indexing.
+    const m1 = backfillObsidianIndex(db);
+    console.log(
+      `M1 obsidian-index backfill: ${m1.rows} entries re-indexed ` +
+      `(${m1.links} links, ${m1.tags} tags, ${m1.meta} meta` +
+      `${m1.errors ? `, ${m1.errors} errors` : ''}).`,
+    );
+
+    // M2 -- opt-in via --m2. Budget-gated; backfillAutoLink internally
+    // forces past the IJFW_AUTOLINK_BACKFILL opt-in (the --m2 flag IS the
+    // explicit opt-in) but still honours IJFW_AUTOLINK_OFF, the budget cap,
+    // and the API-key requirement.
+    if (parsed.m2) {
+      const m2 = await backfillAutoLink(db, { force: true });
+      if (m2.skipped) {
+        console.log(
+          `M2 auto-link backfill skipped (${m2.reason}). ` +
+          `M2 backfill needs a positive IJFW_AUTOLINK_BUDGET_USD cap and an ` +
+          `API key (IJFW_AUTOLINK_API_KEY or ANTHROPIC_API_KEY).`,
+        );
+      } else {
+        console.log(
+          `M2 auto-link backfill: ${m2.linked}/${m2.rows} entries linked ` +
+          `(${m2.links_added} links, ${m2.neighbor_tags_added} neighbor tags)` +
+          `${m2.stopped_early ? ' -- stopped early (budget / kill switch)' : ''}.`,
+        );
+      }
+    } else {
+      console.log(
+        'M2 auto-link backfill not run. Re-run with --m2 (budget-gated) to ' +
+        'auto-link old entries via the A-Mem LLM pass.',
+      );
+    }
+  } finally {
+    closeDb(db);
+  }
+  process.exit(0);
+}
+
 function cmdRecover(sub) {
   if (sub === 'latest') {
     const latest = latestCheckpoint(process.cwd());