mindforge-cc 11.9.1 → 11.9.2

package/bin/models/cost-tracker.js

@@ -4,32 +4,34 @@
 'use strict';
 
 const fs = require('fs');
-const path = require('path');
-
-const METRICS_DIR = path.join(process.cwd(), '.mindforge', 'metrics');
-const USAGE_LOG = path.join(METRICS_DIR, 'token-usage.jsonl');
+const { ledgerPath, ledgerDir, buildRecord, entryCost, entryDay } = require('./usage-record');
 
+// Paths are resolved lazily (see usage-record.js) so the suite can exercise the
+// ledger inside a temp cwd instead of appending to the developer's real ledger.
 function ensureDir() {
-  if (!fs.existsSync(METRICS_DIR)) {
-    fs.mkdirSync(METRICS_DIR, { recursive: true });
+  const dir = ledgerDir();
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
   }
 }
 
 let _dailyCache = { value: 0, computed_at: 0 };
 
 function getTodaySpend() {
-  if (!fs.existsSync(USAGE_LOG)) return 0;
-  
+  const usageLog = ledgerPath();
+  if (!fs.existsSync(usageLog)) return 0;
+
   const today = new Date().toISOString().slice(0, 10);
-  const content = fs.readFileSync(USAGE_LOG, 'utf8');
+  const content = fs.readFileSync(usageLog, 'utf8');
   const lines = content.trim().split('\n');
-  
+
   let total = 0;
   for (const line of lines) {
+    if (!line) continue;
     try {
       const entry = JSON.parse(line);
-      if (entry.date === today) {
-        total += entry.cost_usd || 0;
+      if (entryDay(entry) === today) {
+        total += entryCost(entry);
       }
     } catch (e) {
       process.stderr.write('[cost-tracker] Skipped malformed entry\n');
@@ -66,23 +68,20 @@ async function preflight(estimatedCost = 0) {
 
 async function record(entry) {
   ensureDir();
-  const enriched = {
-    ...entry,
-    date: new Date().toISOString().slice(0, 10),
-    timestamp: new Date().toISOString()
-  };
-  fs.appendFileSync(USAGE_LOG, JSON.stringify(enriched) + '\n');
+  const enriched = buildRecord(entry);
+  fs.appendFileSync(ledgerPath(), JSON.stringify(enriched) + '\n');
   _dailyCache.computed_at = 0; // Invalidate cache
 }
 
 function getSummary(params = { days: 7 }) {
-  if (!fs.existsSync(USAGE_LOG)) return { total_usd: 0, by_model: {} };
-  
+  const usageLog = ledgerPath();
+  if (!fs.existsSync(usageLog)) return { total_usd: 0, by_model: {} };
+
   const cutoffDate = new Date();
   cutoffDate.setDate(cutoffDate.getDate() - params.days);
   const cutoffStr = cutoffDate.toISOString().slice(0, 10);
 
-  const content = fs.readFileSync(USAGE_LOG, 'utf8');
+  const content = fs.readFileSync(usageLog, 'utf8');
   const lines = content.trim().split('\n');
   
   const result = {
@@ -95,8 +94,8 @@ function getSummary(params = { days: 7 }) {
   for (const line of lines) {
     try {
       const entry = JSON.parse(line);
-      if (entry.date >= cutoffStr) {
-        const cost = entry.cost_usd || 0;
+      if (entryDay(entry) >= cutoffStr) {
+        const cost = entryCost(entry);
         result.total_usd += cost;
         result.calls++;
         

package/bin/models/model-router.js

@@ -7,11 +7,15 @@
 const fs = require('fs');
 const path = require('path');
 
+// The one bracket-aware MINDFORGE.md reader (see bin/utils/mindforge-params.js).
+const { readParams } = require('../utils/mindforge-params');
+
 // v9: Model topology aligned to Claude 4.x family (2026-04)
 const DEFAULTS = {
   PLANNER_MODEL:          'claude-opus-4-7',
   EXECUTOR_MODEL:         'claude-sonnet-4-6',
   REVIEWER_MODEL:         'claude-sonnet-4-6',
+  VERIFIER_MODEL:         'claude-sonnet-4-6',
   SECURITY_MODEL:         'claude-opus-4-7',
   RESEARCH_MODEL:         'gemini-2.5-pro',
   QA_MODEL:               'claude-sonnet-4-6',
@@ -40,14 +44,31 @@ let _settingsMtime = 0;
 const CACHE_CHECK_INTERVAL_MS = 60000;
 let _lastCacheCheck = 0;
 
+// MINDFORGE.md declares the model topology with SHORT persona keys ([PLANNER]);
+// the router's canonical setting keys are the *_MODEL names in DEFAULTS above,
+// which is what every getAllSettings() consumer reads. Map short -> canonical
+// and keep BOTH in the returned object so nothing reading *_MODEL breaks.
+const KEY_ALIASES = {
+  PLANNER:  'PLANNER_MODEL',
+  EXECUTOR: 'EXECUTOR_MODEL',
+  REVIEWER: 'REVIEWER_MODEL',
+  VERIFIER: 'VERIFIER_MODEL',
+  SECURITY: 'SECURITY_MODEL',
+  RESEARCH: 'RESEARCH_MODEL',
+  QA:       'QA_MODEL',
+  DEBUG:    'DEBUG_MODEL',
+  QUICK:    'QUICK_MODEL',
+};
+
 function parseSettings(filePath) {
-  const content = fs.readFileSync(filePath, 'utf8');
-  const settings = { ...DEFAULTS };
-  const lines = content.split('\n');
-  for (const line of lines) {
-    const match = line.match(/^([A-Z0-9_]+)=(.*)$/);
-    if (match) {
-      settings[match[1]] = match[2].trim();
+  // v11.9.2 matched /^([A-Z0-9_]+)=(.*)$/ here, which matches ZERO lines of a
+  // bracketed MINDFORGE.md — routing silently always used DEFAULTS.
+  const raw = readParams(filePath);
+  const settings = { ...DEFAULTS, ...raw };
+  // An explicit [PLANNER_MODEL] always wins over the short [PLANNER] form.
+  for (const [shortKey, canonicalKey] of Object.entries(KEY_ALIASES)) {
+    if (raw[shortKey] !== undefined && raw[canonicalKey] === undefined) {
+      settings[canonicalKey] = raw[shortKey];
     }
   }
   return settings;

package/bin/models/usage-record.js

@@ -0,0 +1,71 @@
+/**
+ * MindForge — Token-usage ledger record shape.
+ *
+ * SINGLE SOURCE OF TRUTH for `.mindforge/metrics/token-usage.jsonl`.
+ * The writer (bin/models/cost-tracker.js, fed by every provider in
+ * bin/models/*-provider.js) and every reader (bin/models/cost-tracker.js,
+ * bin/dashboard/metrics-aggregator.js) MUST go through this module so the
+ * field names cannot drift apart again.
+ *
+ * Canonical row (all five providers emit exactly this cost field):
+ *   {
+ *     model, input_tokens, output_tokens,
+ *     cache_read_input_tokens?, cache_creation_input_tokens?,
+ *     cost_usd,                       // <- the ONLY cost field. Never total_cost_usd.
+ *     task_name?, session_id?, phase?,
+ *     date,                           // 'YYYY-MM-DD', added by buildRecord()
+ *     timestamp                       // full ISO 8601, added by buildRecord()
+ *   }
+ *
+ * `total_cost_usd` is a DIFFERENT concept that belongs to cross-review reports
+ * (bin/review/cross-review-engine.js:72) and must never appear in this ledger.
+ *
+ * NOTE ON PATHS: resolution stays on process.cwd() (not bin/utils/paths.js
+ * findProjectRoot) to preserve today's behaviour exactly; relocating user state
+ * is deliberately deferred to v12.
+ *
+ * KNOWN STALE SITE, deliberately NOT migrated here: bin/migrations/1.0.0-to-2.0.0.js:93
+ * resolves the ledger to .planning/token-usage.jsonl — a path that has never existed —
+ * so that migration silently no-ops. Repointing it is out of scope for COST-01 because
+ * it would start a migration that has never run against real data. Until then, this
+ * module is the single source of truth for every LIVE reader and writer, not literally
+ * every path-resolution site in the tree.
+ */
+'use strict';
+
+const path = require('path');
+
+// Project-root-relative location of the append-only usage ledger.
+const LEDGER_SEGMENTS = ['.mindforge', 'metrics', 'token-usage.jsonl'];
+
+/** Absolute path to the ledger. Resolved lazily so tests can chdir. */
+function ledgerPath(root = process.cwd()) {
+  return path.join(root, ...LEDGER_SEGMENTS);
+}
+
+/** Directory containing the ledger. */
+function ledgerDir(root = process.cwd()) {
+  return path.join(root, ...LEDGER_SEGMENTS.slice(0, -1));
+}
+
+/** Stamp a provider result into a canonical ledger row. */
+function buildRecord(entry, now = new Date()) {
+  const iso = now.toISOString();
+  return { ...entry, date: iso.slice(0, 10), timestamp: iso };
+}
+
+/** Cost of one row, in USD. Returns 0 for absent/non-finite values. */
+function entryCost(entry) {
+  const v = entry && entry.cost_usd;
+  return typeof v === 'number' && Number.isFinite(v) ? v : 0;
+}
+
+/** 'YYYY-MM-DD' day of one row: prefers `date`, falls back to `timestamp`. */
+function entryDay(entry) {
+  if (!entry) return '';
+  if (typeof entry.date === 'string' && entry.date.length >= 10) return entry.date.slice(0, 10);
+  if (typeof entry.timestamp === 'string' && entry.timestamp.length >= 10) return entry.timestamp.slice(0, 10);
+  return '';
+}
+
+module.exports = { LEDGER_SEGMENTS, ledgerPath, ledgerDir, buildRecord, entryCost, entryDay };

package/bin/utils/file-lock.js

@@ -0,0 +1,106 @@
+'use strict';
+
+/**
+ * MindForge — Fail-closed advisory file lock (LOCK-01).
+ *
+ * Promoted from bin/learning/instinct-cli.js:78-100 (`withStoreLock`), preserving its
+ * semantics: an O_CREAT|O_EXCL lockfile beside the target, a bounded retry spin, a
+ * stale-reclaim by mtime for locks orphaned by a killed process, and unlink in finally.
+ *
+ * FAIL-CLOSED: when the lock cannot be taken this THROWS. It NEVER writes anyway.
+ * Deliberately NOT modelled on .agent/bin/lib/state.cjs:784-789, which unlinks the other
+ * holder's lock and writes regardless on its last retry — that converts a detectable
+ * contention error into silent data loss.
+ *
+ * `fn` MUST be SYNCHRONOUS. The re-entrancy depth counter below is only sound because
+ * nothing else in this process can interleave between acquire and release.
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const MAX_TRIES = 50;      // 50 x 20-40ms => ~1-2s ceiling before failing closed
+const WAIT_MS = 20;
+const STALE_MS = 10000;    // reclaim a lockfile whose mtime is older than this
+
+// Re-entrancy depth per lockfile. Required: knowledge-graph applyDecay() holds this
+// lock and calls deprecateEdge(), which takes the SAME lock. Without re-entrancy that
+// self-deadlocks and then fails closed, so a decay pass could never prune an edge.
+const _held = new Map(); // lockPath -> depth
+
+const _sleepView = new Int32Array(new SharedArrayBuffer(4));
+
+/** Blocking sleep that does not burn a core; busy-waits if Atomics.wait is refused. */
+function sleepSync(ms) {
+  try {
+    Atomics.wait(_sleepView, 0, 0, ms);
+  } catch {
+    const until = Date.now() + ms;
+    while (Date.now() < until) { /* busy-wait fallback */ }
+  }
+}
+
+/**
+ * Rejects an async fn. The `finally` in withFileLock unlinks the lockfile the moment
+ * fn() returns, so a promise-returning fn would run its critical section UNLOCKED while
+ * looking guarded. Failing loudly here is far cheaper than debugging that corruption.
+ */
+function assertSync(out) {
+  if (out && typeof out.then === 'function') {
+    throw new TypeError('withFileLock requires a SYNCHRONOUS fn; got a thenable');
+  }
+  return out;
+}
+
+/**
+ * Runs fn() while holding an exclusive advisory lock on `${targetPath}.lock`.
+ * @param {string} targetPath  the file being protected (the lock is a sibling `.lock`)
+ * @param {Function} fn        SYNCHRONOUS critical section; its return value is returned
+ * @param {object} [opts]      { maxTries, waitMs, staleMs, label }
+ * @returns {*} whatever fn() returns
+ * @throws if the lock cannot be acquired within maxTries — the caller MUST NOT write
+ */
+function withFileLock(targetPath, fn, opts = {}) {
+  const lock = `${targetPath}.lock`;
+
+  const depth = _held.get(lock) || 0;
+  if (depth > 0) {                       // already ours — re-enter, do not re-acquire
+    _held.set(lock, depth + 1);
+    try { return assertSync(fn()); }
+    finally { _held.set(lock, _held.get(lock) - 1); }
+  }
+
+  const maxTries = opts.maxTries ?? MAX_TRIES;
+  const waitMs = opts.waitMs ?? WAIT_MS;
+  const staleMs = opts.staleMs ?? STALE_MS;
+  const label = opts.label || targetPath;
+
+  // The lock must be creatable before the target's own mkdir runs, so ensure the dir
+  // here. A bad path still throws ENOTDIR/ENOENT to the caller, unchanged.
+  fs.mkdirSync(path.dirname(lock), { recursive: true });
+
+  let acquired = false;
+  for (let i = 0; i < maxTries && !acquired; i++) {
+    try {
+      fs.closeSync(fs.openSync(lock, 'wx'));   // O_CREAT|O_EXCL|O_WRONLY
+      acquired = true;
+    } catch (err) {
+      if (err.code !== 'EEXIST') throw err;
+      try {
+        const age = Date.now() - fs.statSync(lock).mtimeMs;
+        if (age > staleMs) { fs.unlinkSync(lock); continue; }   // orphaned by a kill
+      } catch { /* lock vanished between EEXIST and stat — retry */ }
+      sleepSync(waitMs + Math.floor(Math.random() * waitMs));   // jitter breaks the herd
+    }
+  }
+  if (!acquired) throw new Error(`could not acquire ${label} lock: ${lock}`);
+
+  _held.set(lock, 1);
+  try { return assertSync(fn()); }
+  finally {
+    _held.set(lock, 0);
+    try { fs.unlinkSync(lock); } catch { /* already gone */ }
+  }
+}
+
+module.exports = { withFileLock, MAX_TRIES, WAIT_MS, STALE_MS };

package/bin/utils/mindforge-params.js

@@ -0,0 +1,124 @@
+'use strict';
+/**
+ * MindForge — MINDFORGE.md parameter parser (single source of truth).
+ *
+ * TWO on-disk forms are supported, because both ship:
+ *
+ * 1. BRACKETED (current, MINDFORGE.md) — 43 keys in the shipped registry:
+ *        [PLANNER]  = claude-opus-4-7
+ *        [MODE]     = "Platform Sovereign"
+ *        [API_URL]  = <http://localhost:3000>
+ *        [PQAS_ENFORCED] = false  # trailing note
+ *        [FORBIDDEN] = """
+ *        ...multi-line block...
+ *        """
+ *
+ * 2. LEGACY PLAIN (shell-style) — 28 keys in examples/starter-project/MINDFORGE.md,
+ *    which ships (package.json files[] contains "examples/"), and the
+ *    tests/cli-router.test.js:110 fixture. A bracket-only parser silently
+ *    zeroes those out:
+ *        MAX_TASKS_PER_PHASE=999
+ *        DISABLED_SKILLS=            <- empty value is LEGAL, hence (.*) not (.+)
+ *
+ * Bracketed semantics are ported from sdk/src/client.ts:141-158 (the only
+ * previously correct bracket-aware reader) and extended with value
+ * normalisation so the runtime and the validator agree on one interpretation.
+ *
+ * NOT captured: prose bullets such as `- [MIN_SOUL_SCORE] — description`
+ * (section 7 of MINDFORGE.md). A bracketed key only counts when the bracket
+ * opens the line (leading whitespace allowed) and is followed by `=`.
+ *
+ * The legacy form deliberately allows NO leading whitespace, matching the two
+ * regexes it replaces (bin/validate-config.js:36, bin/models/model-router.js:48).
+ * That is a safety property, not an oversight: it stops indented `KEY=value`
+ * lines inside markdown code blocks from being read as configuration.
+ */
+
+const fs = require('fs');
+
+/** [KEY] = value — key must open the line; only spaces/tabs may precede it. */
+const ASSIGN_RE = /^[ \t]*\[([A-Z0-9_]+)\][ \t]*=[ \t]*(.*)$/;
+
+/** KEY=value — legacy plain form. Column 0 only. `(.*)`: empty values are legal. */
+const LEGACY_RE = /^([A-Z0-9_]+)=(.*)$/;
+
+const FENCE = '"""';
+
+/** Drop a trailing ` # comment`. Requires whitespace before `#` so that
+ *  values legitimately containing `#` (URL fragments, colours) survive. */
+function stripComment(raw) {
+  const i = raw.search(/\s#/);
+  return i === -1 ? raw : raw.slice(0, i);
+}
+
+/** Unwrap "quoted" values and <markdown-autolink> URLs. */
+function unwrap(v) {
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) return v.slice(1, -1);
+  if (v.length >= 2 && v.startsWith('<') && v.endsWith('>')) return v.slice(1, -1);
+  return v;
+}
+
+function normalise(raw) {
+  return unwrap(stripComment(raw).trim());
+}
+
+/**
+ * @param {string} content raw MINDFORGE.md text
+ * @returns {Record<string,string>} key -> normalised string value
+ */
+function parseParams(content) {
+  const bracketed = {};
+  const legacy    = {};
+  const lines = String(content).split(/\r?\n/);
+
+  for (let i = 0; i < lines.length; i++) {
+    const m = lines[i].match(ASSIGN_RE);
+
+    if (!m) {
+      // Legacy plain form. Only reached when the line is not a bracketed
+      // assignment; the two patterns can never both match one line.
+      const g = lines[i].match(LEGACY_RE);
+      if (g) legacy[g[1]] = normalise(g[2]);
+      continue;
+    }
+
+    const key = m[1];
+    const rest = m[2].trim();
+
+    if (rest.startsWith(FENCE)) {
+      const inline = rest.slice(FENCE.length);
+      // Single-line fenced value: [K] = """text"""
+      if (inline.trimEnd().endsWith(FENCE) && inline.trim().length >= FENCE.length) {
+        bracketed[key] = inline.trimEnd().slice(0, -FENCE.length).trim();
+        continue;
+      }
+      const block = [];
+      let j = i + 1;
+      for (; j < lines.length; j++) {
+        if (lines[j].trim() === FENCE) break;
+        block.push(lines[j]);
+      }
+      bracketed[key] = block.join('\n').trim();
+      i = j; // resume after the closing fence (or at EOF)
+      continue;
+    }
+
+    bracketed[key] = normalise(rest);
+  }
+
+  // Bracketed is the canonical modern form and wins on collision, regardless
+  // of which appeared first in the file.
+  return { ...legacy, ...bracketed };
+}
+
+/**
+ * Read + parse a MINDFORGE.md. Returns {} when the file is absent so callers
+ * can fall back to their own defaults (fail-open on absence, not on garbage).
+ * @param {string} filePath
+ */
+function readParams(filePath) {
+  if (!fs.existsSync(filePath)) return {};
+  return parseParams(fs.readFileSync(filePath, 'utf8'));
+}
+
+module.exports = { parseParams, readParams, ASSIGN_RE, LEGACY_RE };

package/bin/validate-config.js

@@ -7,8 +7,10 @@
 
 'use strict';
 
-const fs   = require('fs');
-const path = require('path');
+const fs = require('fs');
+
+// The one bracket-aware MINDFORGE.md reader (see bin/utils/mindforge-params.js).
+const { readParams } = require('./utils/mindforge-params');
 
 const CONFIG_PATH  = process.argv[2] || 'MINDFORGE.md';
 const SCHEMA_PATH  = '.mindforge/MINDFORGE-SCHEMA.json';
@@ -23,28 +25,36 @@ if (!fs.existsSync(SCHEMA_PATH)) {
   process.exit(0);
 }
 
-const content = fs.readFileSync(CONFIG_PATH, 'utf8');
 const schema  = JSON.parse(fs.readFileSync(SCHEMA_PATH, 'utf8'));
 
 const errors   = [];
 const warnings = [];
 
-// Parse key=value pairs from MINDFORGE.md
-const settings = {};
-const lines = content.split('\n');
-lines.forEach(line => {
-  const match = line.match(/^([A-Z_]+)=(.+)$/);
-  if (match) {
-    const [, key, value] = match;
-    settings[key] = value.trim();
-  }
-});
+// MINDFORGE.md declares parameters as bracketed assignments ([KEY] = value).
+// v11.9.2 and earlier matched /^([A-Z_]+)=(.+)$/, which matches ZERO lines of a
+// real MINDFORGE.md — the validator parsed 0 settings and could never fail.
+// readParams() also still handles the legacy plain KEY=value form.
+const settings = readParams(CONFIG_PATH);
+
+// Required / recommended key sets (top-level arrays in the schema). Kept
+// deliberately identical to sdk/src/client.ts validateConfig() so the SDK and
+// the CLI validator enforce ONE contract.
+const required    = new Set(Array.isArray(schema.required) ? schema.required : []);
+const recommended = new Set(Array.isArray(schema.recommended) ? schema.recommended : []);
+
+for (const key of required) {
+  if (!settings[key]) errors.push(`${key} is required but not set`);
+}
+for (const key of recommended) {
+  if (!settings[key]) warnings.push(`${key} is recommended but not set`);
+}
 
 // Validate against schema
 for (const [key, def] of Object.entries(schema.properties || {})) {
   const value = settings[key];
 
-  if (def.required && !value) {
+  // Legacy per-property `required` flag still honoured (schema.required wins).
+  if (def.required && !value && !required.has(key)) {
     errors.push(`${key} is required but not set`);
     continue;
   }
@@ -68,8 +78,16 @@ for (const [key, def] of Object.entries(schema.properties || {})) {
     errors.push(`${key}: expected true or false, got "${value}"`);
   }
 
-  if (def.nonOverridable) {
-    warnings.push(`${key}: this is a non-overridable governance primitive (value will be ignored)`);
+  if (def.type === 'string' && def.pattern && !new RegExp(def.pattern).test(value)) {
+    errors.push(`${key}: "${value}" does not match required pattern ${def.pattern}`);
+  }
+
+  // A non-overridable governance primitive may be SET (MINDFORGE.md is its
+  // source of truth) but never DISABLED. Mirrors sdk/src/client.ts:176-182,
+  // which errors on `[KEY] = false`. The old code warned on every occurrence
+  // and claimed the value "will be ignored" — which was untrue and pure noise.
+  if (def.nonOverridable && def.type === 'boolean' && value === 'false') {
+    errors.push(`${key}: non-overridable governance primitive cannot be disabled`);
   }
 }