mindforge-cc 11.9.2 → 11.9.3

package/bin/learning/instinct-cli.js

@@ -23,6 +23,7 @@ const fs = require('fs');
 const path = require('path');
 
 const guard = require('./lib/ssrf-guard');
+const { redactSecrets } = require('../utils/redact-secrets');
 const { detectProject } = require('../hooks/lib/detect-project');
 const { withFileLock } = require('../utils/file-lock');
 
@@ -197,7 +198,13 @@ async function cmdImport(args, cfg) {
   for (const e of incoming) {
     if (!e || !guard.validateInstinctId(e.id || '')) { process.stderr.write(`skipping entry with invalid id: ${e && e.id}\n`); continue; }
     if ((Number(e.confidence) || 0) < minC) continue;
+    // Import is the store's second ingress and it accepts an https:// source, so incoming text is
+    // untrusted twice over: it may carry a credential from whoever exported it. Redacting here
+    // rather than at every egress means export, promote, list and the LLM promotion path into a
+    // published SKILL.md all inherit already-clean data — one choke point instead of five.
     valid.push(Object.assign({}, e, {
+      observation: redactSecrets(e.observation),
+      behavior: redactSecrets(e.behavior),
       project: projectName, project_id: scopeId, source: 'imported',
       imported_from: source, created_at: now, updated_at: now,
     }));

package/bin/memory/vector-hub.js

@@ -8,6 +8,7 @@
 const crypto = require('crypto');
 const path = require('path');
 const fs = require('fs');
+const { withFileLock } = require('../utils/file-lock');
 
 // ── FTS retrieval (FTS-01) ───────────────────────────────────────────────────
 // A MATCH argument is an FTS *query expression*, not a literal. Wrapping the
@@ -167,6 +168,9 @@ class VectorHub {
     // deliberately bias toward flushing.
     this._pendingSaves = 0;
     this._exitGuardInstalled = false;
+    // null until a file is loaded or written. null means "no expectation", so a first write into a
+    // fresh directory is never treated as a conflict.
+    this._diskFingerprint = null;
   }
 
   _installExitGuard() {
@@ -174,10 +178,59 @@ class VectorHub {
     this._exitGuardInstalled = true;
     // 'exit' handlers can only run synchronous code — saveSync() fits exactly.
     process.once('exit', () => {
-      if (this._db && this._pendingSaves > 0) this.saveSync();
+      if (!this._db) return;
+      // _pendingSaves === 0 means every scheduled save already ran commitDb, which consumes
+      // its tmp file by renaming it. So there is nothing outstanding and the in-memory DB is
+      // durable — the reap below is safe without a further write.
+      const durable = this._pendingSaves > 0 ? this.saveSync() : true;
+      if (durable) this._reapAbandonedExport();
     });
   }
 
+  /**
+   * Delete THIS process's abandoned tmp export.
+   *
+   * THE LEAK. save() is a two-step chain: writeTmpDurable() writes and fsyncs
+   * `<db>.tmp.<pid>.async`, then commitDb() renames it into place. A 'exit' handler can only
+   * run synchronous code, so a process that exits with a save in flight abandons the pending
+   * .then() — the microtask never runs, commitDb never renames, and the tmp file stays on disk
+   * forever. Nothing anywhere deleted it. Measured in this repository: 176 orphaned
+   * `celestial.db.tmp.<pid>.async` files totalling 1.8 GB, against a live database of 10.6 MB.
+   * Each orphan is a complete copy of the database, so the directory grew by ~11 MB per exit.
+   *
+   * Reproduced with a control arm: three runs that call process.exit() without close() leave
+   * three orphans, one per pid; three runs that await close() leave zero. Orphan size records
+   * how far the chain got — 0 bytes if the process died inside fs.open, a full export if the
+   * write landed and only the rename was lost.
+   *
+   * The trigger is ordinary, not exotic. nexus-tracer.js is the framework-wide tracing
+   * singleton, so any command that traces and then exits hits this window;
+   * bin/migrations/v9-unified-memory.js calls process.exit() and never calls close() at all.
+   *
+   * WHY THIS IS SAFE, AND WHY IT IS GATED. An earlier snapshot from the SAME process is a
+   * subset of what saveSync() just exported: saveSync() serialises the entire current
+   * in-memory database, which already contains every row the abandoned export held. So once
+   * persistence is confirmed the orphan is provably redundant.
+   *
+   * It is confirmed, not assumed. When saveSync() fails — commitDb throws, or the conflict
+   * sidecar could not be written — the abandoned export may be the only copy of those rows on
+   * disk, and deleting it would be exactly the silent data destruction commitDb refuses to
+   * commit. In that case the caller does NOT reap, and the file is deliberately left behind for
+   * a human. Accumulating a file on a failed write is the correct trade against destroying the
+   * last copy of it. Measured: zero `.sync` orphans exist in this repository, so that path does
+   * not fire in practice — the accumulation was entirely the async one.
+   *
+   * Both suffixes are swept because saveSync()'s own tmp leaks by the same argument if
+   * commitDb throws after the write; that arm is currently unobserved but not impossible.
+   */
+  _reapAbandonedExport() {
+    for (const suffix of ['async', 'sync']) {
+      try {
+        fs.unlinkSync(`${this.dbPath}.tmp.${process.pid}.${suffix}`);
+      } catch { /* not present — the normal case, since commitDb usually consumes it */ }
+    }
+  }
+
   _ensureDir() {
     const dir = path.dirname(this.dbPath);
     if (!fs.existsSync(dir)) {
@@ -220,6 +273,9 @@ class VectorHub {
     if (fs.existsSync(this.dbPath)) {
       const buffer = fs.readFileSync(this.dbPath);
       this._db = new SQL.Database(buffer);
+      // What the file looked like when this process took its copy. Every later write compares
+      // against it, so a rewrite by another process is detected instead of silently clobbered.
+      this._diskFingerprint = dbFingerprint(this.dbPath);
     } else {
       this._db = new SQL.Database();
     }
@@ -513,11 +569,24 @@ class VectorHub {
     // COMPLETED (success or failure). The exit guard fires saveSync() while any
     // scheduled save is still outstanding — see _installExitGuard().
     this._pendingSaves++;
-    this._saveChain = this._saveChain.then(() => writeDbDurable(dbPath, buffer))
+    this._saveChain = this._saveChain
+      // Write the tmp asynchronously, then commit it under the lock. The commit MUST be the last
+      // step — see commitDb's note on the check-then-write gap that made this guard bypassable.
+      .then(() => writeTmpDurable(dbPath, buffer))
+      .then((tmpPath) => {
+        const res = commitDb(dbPath, this._diskFingerprint, buffer, tmpPath);
+        if (res.ok) {
+          this._diskFingerprint = res.fingerprint;
+          this._pendingSaves--;         // decrement ONLY on a durable write; see below
+        }
+      })
       .catch((err) => {
+        // Left deliberately outstanding. _pendingSaves gates the exit guard, so decrementing after a
+        // FAILED save would make the guard skip its last-resort saveSync() and drop this batch — the
+        // exact loss the counter exists to prevent. withFileLock throws when it cannot acquire, so
+        // lock contention lands here, and leaving the count high is what makes the retry happen.
         console.warn(`[VectorHub] Failed to save database: ${err.message}`);
-      })
-      .then(() => { this._pendingSaves--; });
+      });
     return this._saveChain;
   }
 
@@ -525,13 +594,18 @@ class VectorHub {
    * Synchronous, crash-safe persistence — used only on shutdown to GUARANTEE
    * no acknowledged write is lost if the process exits before the async save
    * chain drains. Correctness over non-blocking here.
+   *
+   * @returns {boolean} true when the in-memory database is durably on disk — either committed
+   *   over the live file or preserved in a conflict sidecar. false when it is NOT, which is the
+   *   signal _reapAbandonedExport() needs: on false, an abandoned tmp export may hold the only
+   *   copy of those rows and must be left alone.
    */
   saveSync() {
-    if (!this._db) return;
+    if (!this._db) return false;
     try {
       this._ensureDir();
       const buffer = Buffer.from(this._db.export());
-      const tmpPath = `${this.dbPath}.tmp.${process.pid}`;
+      const tmpPath = `${this.dbPath}.tmp.${process.pid}.sync`;
       const fd = fs.openSync(tmpPath, 'w');
       try {
         fs.writeSync(fd, buffer);
@@ -539,13 +613,26 @@ class VectorHub {
       } finally {
         fs.closeSync(fd);
       }
-      fs.renameSync(tmpPath, this.dbPath);
+      // Commit under the lock. Worst case this blocks the exit handler for withFileLock's bounded
+      // retry ceiling (~1-2s) and then throws into the catch below — bounded, logged, and far better
+      // than writing over a file another process just changed.
+      const res = commitDb(this.dbPath, this._diskFingerprint, buffer, tmpPath);
+      if (!res.ok) {
+        this._pendingSaves = 0;   // the data is in the sidecar; retrying would clobber again
+        // A written sidecar IS durable persistence — the bytes are on disk under a name nothing
+        // else will touch. A NULL sidecar is not: commitDb unlinked the tmp and wrote nothing,
+        // so this export exists only in memory and is about to be lost with the process.
+        return res.sidecar !== null && res.sidecar !== undefined;
+      }
+      this._diskFingerprint = res.fingerprint;
       // A sync export captures the full in-memory DB — a superset of anything the
       // outstanding async saves would have written — so the pending work is now
       // durably satisfied. Clearing the counter prevents a redundant second flush.
       this._pendingSaves = 0;
+      return true;
     } catch (err) {
       console.warn(`[VectorHub] Failed to save database (sync): ${err.message}`);
+      return false;
     }
   }
 
@@ -840,9 +927,108 @@ class VectorHub {
 // ── Durable async DB file write (UC-09) ───────────────────────────────────────
 // Crash-safe: write to a tmp file, fsync, then atomically rename over the target.
 // A crash mid-write leaves the previous good .db intact (rename is atomic on POSIX).
-function writeDbDurable(dbPath, buffer) {
+/**
+ * A cheap identity for the on-disk database: size plus mtime in ms.
+ *
+ * Not a digest — this runs before every save, and hashing a 10MB+ file on each write would be a real
+ * cost for a check whose only job is "did somebody else touch this?". size+mtimeMs changes on any
+ * rewrite by another process, which is exactly the event being detected.
+ */
+function dbFingerprint(dbPath) {
+  try {
+    const st = fs.statSync(dbPath);
+    return `${st.size}:${st.mtimeMs}`;
+  } catch {
+    return null;   // absent is a legitimate state, not an error
+  }
+}
+
+/**
+ * Refuse to silently overwrite another process's writes.
+ *
+ * sql.js holds the whole database in memory and persists by exporting the ENTIRE file and renaming it
+ * over the path. Two processes each hold their own copy and each rewrite the whole file, so the last
+ * writer wins and the other's rows are gone. Measured: two concurrent writers, 15 acknowledged
+ * recordTrace() calls each, 30 expected — 15 on disk, ALL from writer A. Writer B's 15 acknowledged
+ * writes vanished, with no error on either side.
+ *
+ * A caveat on the corroborating evidence, because it was overstated. `.mindforge/` does carry
+ * orphaned `celestial.db.tmp.<pid>` files, and one IS a valid database with skills rows absent from
+ * the live file — but those rows are not lost user data. Audited all 171 non-empty orphans against
+ * the live database: 161 are strict subsets, 9 exceed it only on `traces_search_segdir` (an FTS5
+ * segment-directory count, an index-merge artifact rather than rows), and exactly one
+ * (`celestial.db.tmp.4027`, 63.5 MB, pre-dating the `.async`/`.sync` suffixes) holds 1,373 skill
+ * names the live file lacks — every one of them a `Synthesized Skill (mf-*) - ev_<hash>` row, the
+ * generated filler already slated for deletion. So the orphans corroborate that the clobber window
+ * was ENTERED; they are not evidence that anything worth keeping was destroyed.
+ *
+ * The cross-process loss itself is proven by the two-writer measurement above, which does not
+ * depend on this. Recorded because "there is a database on disk holding rows the live file lacks"
+ * reads as recoverable data loss, and here it is not.
+ *
+ * Making sql.js genuinely multi-process safe means replacing the driver — the whole-file export IS the
+ * problem, and locking alone does not fix it, because both processes loaded a stale copy before either
+ * saved. What is fixable now is the SILENCE. On a detected clobber the export goes to a
+ * `.conflict.<pid>` sidecar and the caller is told, so the data still exists and somebody knows.
+ * Refusing loudly beats destroying quietly — the same choice as auto-runner refusing to record a
+ * completion it cannot substantiate.
+ *
+ * WHY CHECK AND RENAME ARE ONE CRITICAL SECTION. A first version checked the fingerprint and then
+ * handed the buffer to an ASYNC writer. Measured with a deterministic stage — parent writes 3, spawns a
+ * child that writes 5 and exits, parent then closes:
+ *
+ *     [parent] GUARD ...898 == ...898      <- check passes
+ *     === child writes and saves ===       <- file is now ...249
+ *     [parent] ASYNC-WROTE new=...309      <- writes its PRE-CHILD snapshot anyway
+ *     live rows: P0,P1,P2,seed             <- the child's 5 rows destroyed, silently
+ *
+ * spawnSync blocked the event loop, so the child fit entirely inside the gap between the check and the
+ * write. A check followed by a later write is not a guard — it is the same clobber with extra steps.
+ * So the fingerprint comparison and the atomic rename now happen together, synchronously, under the
+ * shared fail-closed lock. withFileLock rejects a thenable outright, which makes reintroducing that gap
+ * a loud TypeError rather than silent data loss.
+ *
+ * The expensive part (writing and fsyncing the tmp file) stays OUTSIDE the lock and may still be async:
+ * the tmp path is pid-scoped, so no other process can observe or touch it.
+ *
+ * @param {string} tmpPath  a fully-written, fsynced tmp file to rename into place
+ * @returns {{ok: boolean, fingerprint?: string, sidecar?: string}}
+ */
+function commitDb(dbPath, expected, buffer, tmpPath) {
+  return withFileLock(dbPath, () => {
+    const actual = dbFingerprint(dbPath);
+    if (expected === null || actual === null || actual === expected) {
+      fs.renameSync(tmpPath, dbPath);
+      return { ok: true, fingerprint: dbFingerprint(dbPath) };
+    }
+
+    // Conflict. Keep this process's bytes and leave the other process's file untouched.
+    const sidecar = `${dbPath}.conflict.${process.pid}.${buffer.length}`;
+    try {
+      fs.renameSync(tmpPath, sidecar);   // already fsynced; a rename beats a second full write
+    } catch (err) {
+      console.error(`[VectorHub] CONFLICT and the sidecar could not be written: ${err.message}`);
+      try { fs.unlinkSync(tmpPath); } catch { /* nothing further to do */ }
+      return { ok: false, sidecar: null };
+    }
+    console.error(
+      `[VectorHub] REFUSING TO OVERWRITE ${dbPath}: another process changed it since this one loaded it `
+      + `(expected ${expected}, found ${actual}). sql.js rewrites the whole file, so continuing would `
+      + `discard that process's rows. This process's data went to ${sidecar} instead — nothing is lost, `
+      + 'but the two databases must be reconciled by hand.');
+    return { ok: false, sidecar };
+  }, { label: 'vector-hub-db' });
+}
+
+/**
+ * Write and fsync the pid-scoped tmp file, resolving to its path. Does NOT rename it into place —
+ * that is commitDb's job, because the rename has to share a critical section with the staleness check.
+ * Staying async here is the point: fsync of a multi-megabyte export is the expensive part, and the tmp
+ * path cannot be observed by another process.
+ */
+function writeTmpDurable(dbPath, buffer) {
   return new Promise((resolve, reject) => {
-    const tmpPath = `${dbPath}.tmp.${process.pid}`;
+    const tmpPath = `${dbPath}.tmp.${process.pid}.async`;
     const fail = (err) => { fs.unlink(tmpPath, () => reject(err)); };
     fs.open(tmpPath, 'w', (openErr, fd) => {
       if (openErr) return reject(openErr);
@@ -852,10 +1038,7 @@ function writeDbDurable(dbPath, buffer) {
           fs.close(fd, (closeErr) => {
             if (syncErr) return fail(syncErr);
             if (closeErr) return fail(closeErr);
-            fs.rename(tmpPath, dbPath, (renameErr) => {
-              if (renameErr) return fail(renameErr);
-              resolve();
-            });
+            resolve(tmpPath);
           });
         });
       });

package/bin/migrations/0.6.0-to-1.0.0.js

@@ -3,18 +3,19 @@
  *
  * Changes:
  * 1. HANDOFF.json: add `plugin_api_version` field
- * 2. AUDIT.jsonl: backfill `session_id` for entries missing it
+ * 2. AUDIT.jsonl: append a migration record — existing entries are NEVER rewritten (see step 2)
  * 3. MINDFORGE.md: convert VERIFY_PASS_RATE_WARNING_THRESHOLD if in old 0-100 format
  * 4. STATE.md: add v1.0.0 compatibility note if it doesn't already have one
  */
 'use strict';
 
 const fs = require('fs');
+const { appendAuditEntrySync } = require('../autonomous/audit-writer');
 
 module.exports = {
   fromVersion: '0.6.0',
   toVersion:   '1.0.0',
-  description: 'Add plugin_api_version; backfill session_id; normalise MINDFORGE.md thresholds',
+  description: 'Add plugin_api_version; record the migration in the audit log; normalise MINDFORGE.md thresholds',
 
   async run(paths) {
     // ── 1. HANDOFF.json ───────────────────────────────────────────────────────
@@ -36,31 +37,35 @@ module.exports = {
     }
 
     // ── 2. AUDIT.jsonl ────────────────────────────────────────────────────────
+    //
+    // APPEND-ONLY. This step used to rewrite every entry to backfill `session_id`, which BROKE the
+    // hash chain and then reported success. Measured on a 50-entry chain written by the real writer:
+    //
+    //     before  ->  audit chain valid: 50 entries          exit 0
+    //     after   ->  audit chain BROKEN at entry 0: hash mismatch (entry mutated)   exit 1
+    //
+    // 50 of 50 entries mutated, integrity destroyed at the very first entry, and the migration printed
+    // "backfilled session_id in 50 of 50 entries" and carried on to report "All migrations complete".
+    // bin/governance/audit-hash.js hashes {...entry, previous_hash} with JSON.stringify, so ANY added
+    // key changes the material — a back-linked log cannot be edited in place, only appended to. No file
+    // in this directory referenced the canonical hasher.
+    //
+    // AND THE BACKFILL BOUGHT NOTHING. The only consumer of `session_id` on an audit entry is
+    // bin/dashboard/metrics-aggregator.js:253,286, which reads
+    // `entry.authored_by || entry.session_id || 'unknown'`. So the rewrite swapped the placeholder
+    // 'unknown' for the placeholder 'migrated-from-pre-1.0' — no consumer distinguishes them — at the
+    // cost of every integrity guarantee in the file. Deleting it loses nothing.
+    //
+    // What IS worth recording is that a migration touched this project, so one entry is APPENDED
+    // through the canonical writer. An append extends the chain instead of invalidating it.
     if (fs.existsSync(paths.audit)) {
-      const raw   = fs.readFileSync(paths.audit, 'utf8');
-      const lines = raw.split('\n').filter(Boolean);
-      let modified = 0;
-
-      const updated = lines.map(line => {
-        try {
-          const entry = JSON.parse(line);
-          if (!entry.session_id) {
-            entry.session_id = 'migrated-from-pre-1.0';
-            modified++;
-            return JSON.stringify(entry);
-          }
-          return line;
-        } catch {
-          return line;  // Preserve unparseable lines exactly as-is (quarantine pattern)
-        }
+      appendAuditEntrySync(paths.audit, {
+        event:       'schema_migrated',
+        target_id:   'AUDIT.jsonl',
+        description: 'schema 0.6.0 -> 1.0.0; existing entries left byte-identical (append-only log)',
+        agent:       'migrate',
       });
-
-      if (modified > 0) {
-        fs.writeFileSync(paths.audit, updated.join('\n') + '\n');
-        console.log(`    • AUDIT.jsonl: backfilled session_id in ${modified} of ${lines.length} entries`);
-      } else {
-        console.log('    • AUDIT.jsonl: all entries already have session_id');
-      }
+      console.log('    • AUDIT.jsonl: recorded the migration as a new entry; existing entries untouched');
     }
 
     // ── 3. MINDFORGE.md ───────────────────────────────────────────────────────

package/bin/migrations/1.0.0-to-2.0.0.js

@@ -11,11 +11,12 @@
 
 const fs = require('fs');
 const path = require('path');
+const { appendAuditEntrySync } = require('../autonomous/audit-writer');
 
 module.exports = {
   fromVersion: '1.0.0',
   toVersion:   '2.0.0',
-  description: 'Additive schema upgrade: backfill runtime/agent_id in audit; model_group in tokens',
+  description: 'Additive schema upgrade: record the migration in the audit log; model_group in tokens',
 
   async run(paths) {
     const backupDir = path.join(path.dirname(paths.handoff), '.backups', `v1-to-v2-${Date.now()}`);
@@ -65,29 +66,27 @@ module.exports = {
     });
 
     // ── 2. AUDIT.jsonl ────────────────────────────────────────────────────────
-    safeMigrate(paths.audit, (raw) => {
-      const lines = raw.split('\n').filter(Boolean);
-      let modified = 0;
-      
-      const updated = lines.map(line => {
-        try {
-          const entry = JSON.parse(line);
-          let changed = false;
-          if (!entry.runtime) { entry.runtime = 'unknown'; changed = true; }
-          if (!entry.agent_id) { entry.agent_id = 'migrated-v1'; changed = true; }
-          
-          if (changed) {
-            modified++;
-            return JSON.stringify(entry);
-          }
-          return line;
-        } catch {
-          return line;
-        }
+    //
+    // APPEND-ONLY, for the same reason as 0.6.0-to-1.0.0.js step 2: this rewrote every entry to add
+    // `runtime` and `agent_id`, and bin/governance/audit-hash.js hashes {...entry, previous_hash}, so
+    // any added key changes the hash material and the chain breaks at the first entry while the
+    // migration reports success.
+    //
+    // Worse than its sibling, because here the backfill had NO consumer at all: `git grep agent_id`
+    // and `git grep model_group` outside bin/migrations/ return zero readers in bin/. The chain was
+    // being destroyed to populate fields nothing reads.
+    //
+    // Note safeMigrate() cannot express this — it takes raw content and returns replacement content,
+    // which is a rewrite by construction. An append goes through the canonical writer instead.
+    if (fs.existsSync(paths.audit)) {
+      appendAuditEntrySync(paths.audit, {
+        event:       'schema_migrated',
+        target_id:   'AUDIT.jsonl',
+        description: 'schema 1.0.0 -> 2.0.0; existing entries left byte-identical (append-only log)',
+        agent:       'migrate',
       });
-      
-      return modified > 0 ? updated.join('\n') + '\n' : raw;
-    });
+      console.log('    • AUDIT.jsonl: recorded the migration as a new entry; existing entries untouched');
+    }
 
     // ── 3. token-usage.jsonl ──────────────────────────────────────────────────
     const tokensFile = path.join(path.dirname(paths.handoff), 'token-usage.jsonl');

package/bin/mindforge-cli.js

@@ -167,6 +167,17 @@ const COMMANDS = {
 };
 
 // ── Workflow subcommand (non-script, handled inline) ─────────────────────────
+//
+// Routable but NOT a COMMANDS key, because it dispatches to a module rather than spawning a script.
+// That made the CLI lie about itself: `workflow` is the most-documented verb in the project (126
+// references across the docs) and it works, yet it appeared in neither `--help` nor the
+// "Available commands" list, so a user who mistyped it was told it does not exist. Declared here, next
+// to the handler that makes it real, and consumed by both self-report sites below — one source, so the
+// two cannot drift.
+const INLINE_COMMANDS = ['workflow'];
+/** Every verb the router will actually dispatch: table-driven plus inline. */
+const ROUTABLE = [...Object.keys(COMMANDS), ...INLINE_COMMANDS].sort();
+
 if (COMMAND === 'workflow') {
   const workflowRunner = require('./workflows/workflow-runner');
   workflowRunner.run(COMMAND_ARGS[0], COMMAND_ARGS.slice(1));
@@ -174,8 +185,18 @@ if (COMMAND === 'workflow') {
 }
 
 if (ARGS.includes('--version') || ARGS.includes('-V')) {
-  console.log(require('../package.json').version);
-  process.exit(0);
+  // Resolve by package NAME. In an install this file lands at <project>/bin/mindforge-cli.js, so
+  // '../package.json' is the CONSUMER's manifest and `--version` confidently printed THEIR app's
+  // version as MindForge's — measured: 1.0.0 for a host app at 1.0.0, while MindForge was 11.9.2.
+  // Exit non-zero on an unresolvable version rather than guessing: the whole point of this command
+  // is to be trusted, and a plausible wrong answer is worse than an honest failure.
+  try {
+    console.log(require('./utils/mindforge-version').resolveMindforgeVersion().version);
+    process.exit(0);
+  } catch (err) {
+    console.error(err.message);
+    process.exit(1);
+  }
 }
 
 if (!COMMAND || ARGS.includes('--help') || ARGS.includes('-h')) {
@@ -187,8 +208,10 @@ const target = COMMANDS[COMMAND];
 if (!target) {
   console.error(`Unknown command: ${COMMAND}`);
 
-  // Suggest similar commands using Levenshtein distance
-  const suggestions = Object.keys(COMMANDS)
+  // Suggest similar commands using Levenshtein distance. ROUTABLE, not Object.keys(COMMANDS): a
+  // near-miss on `workflow` (`worklow`, `wokflow`) previously produced no suggestion at all, because
+  // the only verb it resembles was absent from the pool.
+  const suggestions = ROUTABLE
     .map(cmd => ({ cmd, dist: levenshtein(COMMAND, cmd) }))
     .filter(s => s.dist <= 3)
     .sort((a, b) => a.dist - b.dist)
@@ -197,7 +220,7 @@ if (!target) {
   if (suggestions.length > 0) {
     console.error(`\nDid you mean: ${suggestions.map(s => s.cmd).join(', ')}?`);
   } else {
-    console.error('Available commands: ' + Object.keys(COMMANDS).join(', '));
+    console.error('Available commands: ' + ROUTABLE.join(', '));
   }
   process.exit(1);
 }
@@ -213,8 +236,42 @@ const finalArgs = [...(target.defaultArgs || []), ...COMMAND_ARGS];
 
 console.log(`🚀 Executing: ${COMMAND} (${target.description})`);
 
+// The child runs in the USER'S project, not in MindForge's install directory.
+//
+// This was `cwd: ROOT`, which made every routed command operate on the framework's own tree
+// instead of the caller's. The worst case was `security-scan`, the command the protocol mandates
+// pre-commit for any Auth/Payment/PII change: measured against a fixture project whose
+// MINDFORGE.md declared 4 settings including `[MIN_SOUL_SCORE] = 99` (schema maximum is 10) and
+// `[COST_HARD_LIMIT_USD] = not-a-number`, it printed
+//
+//     ✅ MINDFORGE.md valid — 43 settings configured
+//
+// and exited 0. 43 is MindForge's OWN setting count. Two different fixture configs produced
+// byte-identical output, which is the proof it read neither: a security gate that cannot fail,
+// because it never sees the input it claims to check.
+//
+// MEASURED BLAST RADIUS before changing it — all 27 routed commands run under both values against
+// the same fixture. 7 differ, every one of them moving from the vendor's tree to the caller's, and
+// NONE regressed from success to failure:
+//
+//   security-scan                validated MindForge's config      -> reads the caller's
+//   classify                     TIER=2 from MindForge's git diff  -> diffs the caller's repo
+//   pr-review, cross-review      loaded MindForge's ConfigManager  -> looks in the caller's project
+//   learning, record-learning    reported MindForge's state        -> reports the caller's
+//   test-memory                  same ConfigManager shift
+//
+// `classify` deserves its own note: for every consumer it was classifying MindForge's changes.
+//
+// CI is unaffected, checked rather than assumed. control-plane.yml:80 runs `security-scan` as the
+// required ⚖️ Governance Enforcement check and mindforge-ci.yml:46 runs validate-config.js
+// directly; both execute with the repo root as cwd, so ROOT and process.cwd() are the same path
+// there and behaviour is byte-identical.
+//
+// A script that needs the FRAMEWORK's own assets must resolve them from __dirname, which is
+// independent of cwd — see the SCHEMA_PATH note in bin/validate-config.js. Anchoring vendor assets
+// to the process's working directory is what coupled these two unrelated things in the first place.
 const result = spawnSync('node', [scriptPath, ...finalArgs], {
-  cwd: ROOT,
+  cwd: process.cwd(),
   stdio: 'inherit',
   env: { ...process.env, MINDFORGE_CLI: 'true' }
 });
@@ -252,8 +309,12 @@ function printUsage() {
   for (const [name, cfg] of Object.entries(COMMANDS)) {
     console.log(`  ${name.padEnd(15)} ${cfg.description}`);
   }
+  // Listed separately because it dispatches to a module rather than spawning a script, so it has no
+  // COMMANDS entry to carry a description. Omitting it made --help contradict the router.
+  console.log(`  ${'workflow'.padEnd(15)} Run a registered dynamic workflow (see \`workflow list\`)`);
   console.log('\nExamples:');
   console.log('  node bin/mindforge-cli.js security-scan');
   console.log('  node bin/mindforge-cli.js headless --phase 1');
+  console.log('  node bin/mindforge-cli.js workflow list');
   console.log('\n');
 }