@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/lib/core/doctor/class-m-brain-smoke.cjs

@@ -0,0 +1,278 @@
+'use strict';
+
+/**
+ * Phase 127-02 BRAIN-MCP-127-08 (CONTEXT D4) -- Class M Brain smoke.
+ * 5-layer composable probe replacing ~60% of doctor Brain-adjacent checks.
+ *
+ * "Class M" rationale: CONTEXT D4 text reads "K" but letter K is already
+ * taken in scripts/doctor.cjs by --stale-first-touch (SEED-007). A-L are
+ * assigned. M is the next free letter. The CAPABILITY-MAP.md doc patch
+ * lands in plan 127-03.
+ *
+ * Detects 12 Phase 126 taxonomy rows:
+ *   L1 plugin_root      #5 install-cache stale, #9 install-state drift
+ *   L2 key_resolver     #1 missing key, #2 perms-too-open, #8 env unreadable,
+ *                       #13 Bearer format mismatch
+ *   L3 https_schema     #4 cold-start timeout, #14 HTTPS 401, #19 cache
+ *                       stale, #21 schema shape
+ *   L4 stdio_handshake  #15 stdio handshake never returns
+ *   L5 e2e_brain_schema #3 user-scope HTTP coexists with stdio (SHIM should
+ *                       answer, not the legacy HTTP transport)
+ *
+ * Canon Part 7 (reuse): L1/L2/L3 import the existing resolver chokepoints
+ *   (active-plugin-root, resolve-brain-key, brain-client.schema). Only the
+ *   L4/L5 stdio orchestration is net-new.
+ * Canon Part 8 (graph boundary): probe queries the methodology schema
+ *   handle only; zero user-content egress; every Brain payload routes
+ *   through brain-client.cjs (the delegation chokepoint).
+ *
+ * fail-fast cascade: if layer N fails, layers N+1..5 are SKIPPED with
+ *   reason="skipped-prior-layer-failed" so the report points at the FIRST
+ *   failure, not the cascade noise.
+ *
+ * HARD RULE: no em-dashes anywhere in this file.
+ */
+
+const path = require('node:path');
+const fs = require('node:fs');
+const { spawn } = require('node:child_process');
+
+// Layer registry. Wire-locked: the shell harness asserts id strings + order.
+const LAYERS = Object.freeze([
+  Object.freeze({ id: 'plugin_root',      name: 'L1 plugin-root-resolver' }),
+  Object.freeze({ id: 'key_resolver',     name: 'L2 brain-key-resolver' }),
+  Object.freeze({ id: 'https_schema',     name: 'L3 HTTPS schema probe' }),
+  Object.freeze({ id: 'stdio_handshake',  name: 'L4 MCP stdio handshake' }),
+  Object.freeze({ id: 'e2e_brain_schema', name: 'L5 e2e brain_schema via shim' }),
+]);
+
+const STDIO_TIMEOUT_MS = Number(process.env.MINDRIAN_BRAIN_SMOKE_TIMEOUT_MS) || 10000;
+const OVERALL_BUDGET_MS = 30000;
+
+function _now() { return Date.now(); }
+
+async function _runLayer(_name, fn) {
+  const t0 = _now();
+  try {
+    const r = await fn();
+    return { ok: !!r.ok, reason: r.reason || (r.ok ? 'pass' : 'fail'), ms: _now() - t0 };
+  } catch (e) {
+    return { ok: false, reason: 'exception: ' + (e && e.message ? e.message : String(e)), ms: _now() - t0 };
+  }
+}
+
+// L1 -- plugin-root-resolver. Reuses lib/core/active-plugin-root.cjs.
+async function _layer1(opts) {
+  const fn = opts.mockResolveRoot
+    || require('../active-plugin-root.cjs').resolveActivePluginRoot;
+  const r = fn();
+  if (!r || !r.root) {
+    const src = (r && r.source) ? r.source : 'unknown';
+    return { ok: false, reason: 'plugin root not resolved (source=' + src + ')' };
+  }
+  return { ok: true, reason: 'resolved (source=' + r.source + ', topology=' + (r.topology || 'unknown') + ')' };
+}
+
+// L2 -- key-resolver. Reuses lib/core/resolve-brain-key.cjs.
+async function _layer2(opts) {
+  const fn = opts.mockResolveKey
+    || require('../resolve-brain-key.cjs').resolveBrainKey;
+  const r = fn();
+  if (!r || !r.available) {
+    return { ok: false, reason: (r && r.reason) ? r.reason : 'key not available (no reason)' };
+  }
+  return { ok: true, reason: 'key resolved (source=' + r.source + ')' };
+}
+
+// L3 -- schema probe. Reuses lib/core/brain-client.cjs::schema(). Catches the
+// #19 cache-stale + #21 schema-shape rows at this layer.
+async function _layer3(opts) {
+  const schemaFn = opts.mockSchema
+    || (async () => require('../brain-client.cjs').schema());
+  const r = await schemaFn();
+  if (r == null) {
+    return { ok: false, reason: 'schema probe returned null (Brain unreachable or 401)' };
+  }
+  return { ok: true, reason: 'schema probe returned non-null payload' };
+}
+
+function _resolveShimPath(opts) {
+  return opts.shimPath
+    || path.resolve(__dirname, '..', '..', '..', 'bin', 'mindrian-brain-mcp-client.cjs');
+}
+
+// L4 -- MCP stdio handshake. Spawns the bundled shim and asserts initialize
+// resolves with serverInfo.name === 'mindrian-brain' within STDIO_TIMEOUT_MS.
+async function _layer4(opts) {
+  const shimPath = _resolveShimPath(opts);
+  if (!opts.mockSpawn && !fs.existsSync(shimPath)) {
+    return { ok: false, reason: 'shim binary not found at ' + shimPath };
+  }
+  const orchestrator = opts.mockSpawn || _spawnAndHandshake;
+  return orchestrator(shimPath, Object.assign({}, opts, { intent: 'handshake' }));
+}
+
+// L5 -- end-to-end brain_schema via the shim's tools/call. After initialize
+// succeeds, send a tools/call brain_schema and accept either a real schema
+// payload OR a DIRECTOR_NOT_AVAILABLE Tier-0 sentinel (the second case is
+// expected when no key is available; the L5 contract is "the shim ANSWERED
+// over the stdio path", not "the Brain returned a schema").
+async function _layer5(opts) {
+  const shimPath = _resolveShimPath(opts);
+  if (!opts.mockSpawn && !fs.existsSync(shimPath)) {
+    return { ok: false, reason: 'shim binary not found at ' + shimPath };
+  }
+  const orchestrator = opts.mockSpawn || _spawnAndHandshake;
+  return orchestrator(shimPath, Object.assign({}, opts, { intent: 'e2e_brain_schema' }));
+}
+
+// Real stdio orchestrator. opts.intent in { 'handshake', 'e2e_brain_schema' }.
+// Wraps spawn + JSON-RPC initialize + (optional) tools/call + timeout +
+// SIGTERM-on-resolve. Resolves with { ok, reason } -- never throws -- so the
+// caller sees a structured FAIL row instead of an unhandled rejection.
+function _spawnAndHandshake(shimPath, opts) {
+  return new Promise((resolve) => {
+    const proc = spawn(process.execPath, [shimPath], {
+      stdio: ['pipe', 'pipe', 'pipe'],
+      env: process.env,
+    });
+    const timer = setTimeout(function () {
+      try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+      resolve({ ok: false, reason: opts.intent + ' timed out after ' + STDIO_TIMEOUT_MS + 'ms' });
+    }, STDIO_TIMEOUT_MS);
+
+    let buf = '';
+    proc.stdout.on('data', function (chunk) {
+      buf += chunk.toString('utf8');
+      const lines = buf.split('\n');
+      buf = lines.pop();
+      for (const line of lines) {
+        if (!line.trim()) continue;
+        let msg;
+        try { msg = JSON.parse(line); }
+        catch (_) { continue; /* non-JSON line: ignore (stderr boot noise) */ }
+
+        if (msg.id === 1 && msg.result && msg.result.serverInfo) {
+          const serverName = msg.result.serverInfo.name;
+          if (opts.intent === 'handshake') {
+            clearTimeout(timer);
+            try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+            if (serverName === 'mindrian-brain') {
+              return resolve({
+                ok: true,
+                reason: 'handshake succeeded, server=mindrian-brain v' + msg.result.serverInfo.version,
+              });
+            }
+            return resolve({ ok: false, reason: 'unexpected serverInfo.name=' + serverName });
+          }
+          // L5: initialize succeeded, send tools/call brain_schema.
+          try {
+            proc.stdin.write(JSON.stringify({
+              jsonrpc: '2.0', id: 2, method: 'tools/call',
+              params: { name: 'brain_schema', arguments: {} },
+            }) + '\n');
+          } catch (e) {
+            clearTimeout(timer);
+            try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+            return resolve({ ok: false, reason: 'tools/call write error: ' + e.message });
+          }
+          continue;
+        }
+
+        if (msg.id === 2 && msg.result && msg.result.content) {
+          clearTimeout(timer);
+          try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+          const c0 = msg.result.content[0];
+          const text = c0 && c0.text;
+          let parsed;
+          try { parsed = JSON.parse(text); } catch (_) { parsed = { text: text }; }
+          if (parsed && parsed.status === 'DIRECTOR_NOT_AVAILABLE') {
+            return resolve({
+              ok: true,
+              reason: 'e2e brain_schema returned Tier-0 sentinel (expected when no key)',
+            });
+          }
+          return resolve({ ok: true, reason: 'e2e brain_schema returned a payload' });
+        }
+      }
+    });
+
+    proc.stderr.on('data', function () { /* swallow shim startup line + stderr noise */ });
+    proc.on('error', function (err) {
+      clearTimeout(timer);
+      resolve({ ok: false, reason: 'spawn error: ' + err.message });
+    });
+
+    try {
+      proc.stdin.write(JSON.stringify({
+        jsonrpc: '2.0', id: 1, method: 'initialize',
+        params: {
+          protocolVersion: '2024-11-05',
+          capabilities: {},
+          clientInfo: { name: 'class-m-smoke', version: '1.0' },
+        },
+      }) + '\n');
+    } catch (e) {
+      clearTimeout(timer);
+      try { proc.kill('SIGTERM'); } catch (_) { /* ignore */ }
+      resolve({ ok: false, reason: 'initialize write error: ' + e.message });
+    }
+  });
+}
+
+/**
+ * Run the 5-layer Brain smoke probe with fail-fast cascade.
+ *
+ * @param {{
+ *   mockResolveRoot?: function,
+ *   mockResolveKey?:  function,
+ *   mockSchema?:      function,
+ *   mockSpawn?:       function,
+ *   shimPath?:        string,
+ * }} [opts]
+ * @returns {Promise<{ok:boolean, layers:Array<{id,name,ok,reason,ms}>, overall_ms:number}>}
+ */
+async function checkBrainSmoke(opts) {
+  const o = opts || {};
+  const t0 = _now();
+  const out = { ok: true, layers: [], overall_ms: 0 };
+  let prevOk = true;
+  const layerFns = [_layer1, _layer2, _layer3, _layer4, _layer5];
+  for (let i = 0; i < LAYERS.length; i++) {
+    const meta = LAYERS[i];
+    if (!prevOk) {
+      out.layers.push({ id: meta.id, name: meta.name, ok: false, reason: 'skipped-prior-layer-failed', ms: 0 });
+      out.ok = false;
+      continue;
+    }
+    const r = await _runLayer(meta.name, function () { return layerFns[i](o); });
+    out.layers.push({ id: meta.id, name: meta.name, ok: r.ok, reason: r.reason, ms: r.ms });
+    if (!r.ok) { prevOk = false; out.ok = false; }
+  }
+  out.overall_ms = _now() - t0;
+  if (out.overall_ms > OVERALL_BUDGET_MS) {
+    out.ok = false;
+    out.layers.push({
+      id: 'budget', name: 'overall-budget', ok: false,
+      reason: 'overall_ms ' + out.overall_ms + ' > ' + OVERALL_BUDGET_MS, ms: 0,
+    });
+  }
+  return out;
+}
+
+/**
+ * Class M is diagnostic-only. There is no auto-remediation path: the 5
+ * failure surfaces require user action (install / set key / restart). This
+ * function exists for symmetry with classes that DO support --fix.
+ *
+ * @param {object} _result  the checkBrainSmoke result (unused; signature parity)
+ * @returns {{fixed: false, reason: string}}
+ */
+function fixBrainSmoke(_result) {
+  return {
+    fixed: false,
+    reason: 'class-m is diagnostic-only; remediation requires user action: install / set key / restart',
+  };
+}
+
+module.exports = { checkBrainSmoke, LAYERS, fixBrainSmoke, STDIO_TIMEOUT_MS };

package/lib/core/doctor/class-m-brain-smoke.test.cjs

@@ -0,0 +1,310 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Phase 127-02 Task 2 (TDD RED -> GREEN) -- Class M Brain smoke probe tests.
+ *
+ * Covers BRAIN-MCP-127-08 acceptance (CONTEXT Deliverable 4):
+ *   Test 1:  LAYERS constant -- exactly 5 entries with stable ids
+ *   Test 2:  checkBrainSmoke() returns { ok, layers: [5 x {id,name,ok,reason,ms}], overall_ms }
+ *   Test 3:  L1 broken topology -> L2-L5 SKIPPED with reason "skipped-prior-layer-failed"
+ *   Test 4:  L1 OK + L2 no-key -> L3-L5 SKIPPED
+ *   Test 5:  L1 + L2 OK + L3 unreachable -> L4-L5 SKIPPED
+ *   Test 6:  L1 + L2 + L3 OK + L4 timeout -> L5 SKIPPED
+ *   Test 7:  All 5 layers pass when all mocks succeed; overall_ms < 30000
+ *   Test 8:  Each layer.ms >= 0 (sanity); ms fields are numbers
+ *   Test 9:  fixBrainSmoke is a no-op (diagnostic-only invariant)
+ *   Test 10: opts injection seams (mockResolveRoot/mockResolveKey/mockSchema/mockSpawn)
+ *
+ * Hermetic via the opts injection seams -- NO real network IO, NO real spawn.
+ * The shell harness in tests/test-127-02-doctor-class-m.sh exercises real spawn
+ * against the actual shim binary.
+ *
+ * Canon parts:
+ *   - Part 7 (reuse): LAYERS L1/L2/L3 import the existing resolver chokepoints
+ *                     (active-plugin-root, resolve-brain-key, brain-client.schema)
+ *   - Part 8 (graph boundary): the smoke probe queries brain_schema only (a
+ *                              generic methodology handle); zero user content
+ *                              egress in the smoke surface.
+ *
+ * HARD RULE: no em-dashes.
+ */
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const SMOKE_PATH = path.join(REPO_ROOT, 'lib', 'core', 'doctor', 'class-m-brain-smoke.cjs');
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  if (err) process.stdout.write('    ' + (err.message || String(err)) + '\n');
+}
+
+// Helper: clean require cache so each test gets a fresh module instance with
+// fresh closure state for the opts seams.
+function freshLoad() {
+  delete require.cache[SMOKE_PATH];
+  return require(SMOKE_PATH);
+}
+
+// ---------------------------------------------------------------------------
+// Test 1: LAYERS constant shape.
+// ---------------------------------------------------------------------------
+(async function test1_layers_constant() {
+  const label = 'LAYERS constant: 5 frozen entries with stable ids';
+  try {
+    const mod = freshLoad();
+    assert.ok(Array.isArray(mod.LAYERS), 'LAYERS must be an array');
+    assert.equal(mod.LAYERS.length, 5, 'LAYERS must have exactly 5 entries');
+    const ids = mod.LAYERS.map(l => l.id);
+    assert.deepEqual(ids, [
+      'plugin_root',
+      'key_resolver',
+      'https_schema',
+      'stdio_handshake',
+      'e2e_brain_schema',
+    ], 'LAYERS ids must match the canonical 5-layer probe order');
+    for (const l of mod.LAYERS) {
+      assert.equal(typeof l.id, 'string', 'each layer has string id');
+      assert.equal(typeof l.name, 'string', 'each layer has string name');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 2: checkBrainSmoke() return shape.
+// ---------------------------------------------------------------------------
+(async function test2_return_shape() {
+  const label = 'checkBrainSmoke() returns { ok, layers:[5], overall_ms }';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      // All-pass mock chain for shape assertion
+      mockResolveRoot: () => ({ root: '/tmp/fake-root', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'], rel_types: [] }),
+      mockSpawn: async (_shimPath, opts) => ({ ok: true, reason: 'mocked ' + opts.intent }),
+    });
+    assert.equal(typeof result.ok, 'boolean', 'ok must be boolean');
+    assert.ok(Array.isArray(result.layers), 'layers must be an array');
+    assert.equal(result.layers.length, 5, 'layers must have 5 entries');
+    assert.equal(typeof result.overall_ms, 'number', 'overall_ms must be number');
+    assert.ok(result.overall_ms >= 0, 'overall_ms must be >= 0');
+    for (const l of result.layers) {
+      assert.equal(typeof l.id, 'string', 'layer.id is string');
+      assert.equal(typeof l.name, 'string', 'layer.name is string');
+      assert.equal(typeof l.ok, 'boolean', 'layer.ok is boolean');
+      assert.equal(typeof l.reason, 'string', 'layer.reason is string');
+      assert.equal(typeof l.ms, 'number', 'layer.ms is number');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 3: L1 broken -> L2..L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test3_l1_broken_cascade() {
+  const label = 'L1 broken -> L2-L5 cascade to skipped-prior-layer-failed';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: null, source: 'not-found', topology: 'not-found' }),
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].id, 'plugin_root', 'L1 id');
+    assert.equal(result.layers[0].ok, false, 'L1 must be false');
+    assert.match(result.layers[0].reason, /plugin root not resolved/i, 'L1 reason matches');
+    for (let i = 1; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 4: L1 OK + L2 no key -> L3-L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test4_l2_no_key_cascade() {
+  const label = 'L1 OK + L2 no key -> L3-L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: null, source: 'not-found', available: false, reason: 'MINDRIAN_BRAIN_KEY not set (env) ...' }),
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].ok, true, 'L1 must be true');
+    assert.equal(result.layers[1].ok, false, 'L2 must be false');
+    assert.match(result.layers[1].reason, /MINDRIAN_BRAIN_KEY not set/, 'L2 reason carries the resolver reason');
+    for (let i = 2; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 5: L1+L2 OK + L3 unreachable -> L4-L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test5_l3_unreachable_cascade() {
+  const label = 'L1+L2 OK + L3 returns null -> L4-L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => null,
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[0].ok, true, 'L1 ok');
+    assert.equal(result.layers[1].ok, true, 'L2 ok');
+    assert.equal(result.layers[2].ok, false, 'L3 must be false');
+    assert.match(result.layers[2].reason, /HTTPS|schema|unreachable/i, 'L3 reason matches');
+    for (let i = 3; i < 5; i++) {
+      assert.equal(result.layers[i].ok, false, 'L' + (i + 1) + ' must be false (skipped)');
+      assert.equal(result.layers[i].reason, 'skipped-prior-layer-failed',
+        'L' + (i + 1) + ' reason must be skipped-prior-layer-failed');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 6: L1+L2+L3 OK + L4 handshake timeout -> L5 skipped.
+// ---------------------------------------------------------------------------
+(async function test6_l4_handshake_timeout() {
+  const label = 'L1+L2+L3 OK + L4 timeout -> L5 cascade to skipped';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, opts) => {
+        if (opts.intent === 'handshake') return { ok: false, reason: 'handshake timed out after 10000ms' };
+        return { ok: true, reason: 'should-not-be-called' };
+      },
+    });
+    assert.equal(result.ok, false, 'overall must be false');
+    assert.equal(result.layers[3].ok, false, 'L4 must be false');
+    assert.match(result.layers[3].reason, /handshake|timeout/i, 'L4 reason matches');
+    assert.equal(result.layers[4].ok, false, 'L5 must be false (skipped)');
+    assert.equal(result.layers[4].reason, 'skipped-prior-layer-failed', 'L5 reason skipped');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 7: All 5 layers pass; overall_ms < 30000.
+// ---------------------------------------------------------------------------
+(async function test7_all_pass() {
+  const label = 'All 5 layers PASS via mocks; overall_ms < 30000 (30s budget)';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, _opts) => ({ ok: true, reason: 'mocked-success' }),
+    });
+    assert.equal(result.ok, true, 'overall must be true');
+    for (const l of result.layers) {
+      assert.equal(l.ok, true, 'layer ' + l.id + ' must be true');
+    }
+    assert.ok(result.overall_ms < 30000, 'overall_ms must be under 30s budget (got ' + result.overall_ms + ')');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 8: ms-field sanity.
+// ---------------------------------------------------------------------------
+(async function test8_ms_sanity() {
+  const label = 'Each layer.ms is non-negative number';
+  try {
+    const mod = freshLoad();
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/fake', source: 'env', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'k', source: 'env', available: true, reason: null }),
+      mockSchema: async () => ({ labels: ['Framework'] }),
+      mockSpawn: async (_shimPath, _opts) => ({ ok: true, reason: 'ok' }),
+    });
+    for (const l of result.layers) {
+      assert.equal(typeof l.ms, 'number', 'layer.ms is number');
+      assert.ok(l.ms >= 0, 'layer.ms must be >= 0 (got ' + l.ms + ')');
+    }
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 9: fixBrainSmoke is a no-op (diagnostic-only).
+// ---------------------------------------------------------------------------
+(async function test9_fix_is_noop() {
+  const label = 'fixBrainSmoke(result) is a no-op (diagnostic-only invariant)';
+  try {
+    const mod = freshLoad();
+    const fakeResult = { ok: false, layers: [], overall_ms: 0 };
+    const r = mod.fixBrainSmoke(fakeResult);
+    assert.equal(r.fixed, false, 'fixed must be false');
+    assert.match(r.reason, /diagnostic-only/, 'reason must indicate diagnostic-only nature');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Test 10: opts injection seams + Class M letter consistency.
+// ---------------------------------------------------------------------------
+(async function test10_opts_seams_and_class_m() {
+  const label = 'opts injection seams enable hermetic testing + Class M referenced in source';
+  try {
+    const mod = freshLoad();
+    // Verify all four seams individually substitute their layer.
+    let mockSchemaCalled = false;
+    let mockSpawnCalled = false;
+    const result = await mod.checkBrainSmoke({
+      mockResolveRoot: () => ({ root: '/tmp/seam', source: 'opts-mock', topology: 'dev-clone' }),
+      mockResolveKey: () => ({ key: 'seam-key', source: 'opts-mock', available: true, reason: null }),
+      mockSchema: async () => { mockSchemaCalled = true; return { labels: [], rel_types: [] }; },
+      mockSpawn: async (_shimPath, _opts) => { mockSpawnCalled = true; return { ok: true, reason: 'seam-mock' }; },
+    });
+    assert.equal(result.ok, true, 'all seams provided -> overall true');
+    assert.equal(mockSchemaCalled, true, 'mockSchema seam invoked for L3');
+    assert.equal(mockSpawnCalled, true, 'mockSpawn seam invoked for L4 and L5');
+    assert.equal(result.layers[0].reason, 'resolved (source=opts-mock, topology=dev-clone)', 'L1 reason carries source');
+    // Source-level class letter check (CRITICAL: plan uses Class M, not K).
+    const src = fs.readFileSync(SMOKE_PATH, 'utf8');
+    assert.match(src, /Class[- ]?M/, 'source must reference Class M (not Class K -- K is taken by --stale-first-touch)');
+    assert.equal(src.indexOf('Class K'), -1, 'source MUST NOT reference Class K (collides with existing --stale-first-touch)');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Summary -- IIFEs above are async; collect results after a microtask drain.
+// ---------------------------------------------------------------------------
+setImmediate(function summarize() {
+  // Allow any straggling async test to settle. Two passes of setImmediate is
+  // enough for the trivial test bodies above.
+  setImmediate(function () {
+    process.stdout.write('\nPASSED: ' + passed + '\nFAILED: ' + failed + '\n');
+    process.exit(failed === 0 ? 0 : 1);
+  });
+});