@mindrian_os/cli 2.0.0-beta.33 → 2.0.0-beta.37

package/lib/core/install-id.cjs

@@ -0,0 +1,232 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Quick 260911-iko (D-01 through D-08) -- the opaque per-install id Theo
+ * uses to bucket "one install calling twice" apart from "two installs
+ * calling once", without ever learning who the install belongs to.
+ *
+ * WHAT IT IS FOR: Theo needs a bucket key. Today it has none, and every
+ * substitute it could reach for instead (a key, a hostname, an account id)
+ * would be user data crossing the Brain boundary, which Canon Part 8
+ * forbids. A 128-bit coin flip minted locally and sent as a header is the
+ * one answer that gives Theo the bucketing and gives the user nothing to
+ * leak.
+ *
+ * WHY A CSPRNG VALUE IS A GENERIC HANDLE, NOT USER DATA (D-07): the value
+ * is `crypto.randomBytes(16)`, 16 bytes straight out of the platform CSPRNG
+ * with NO INPUT at all. There is no function from the user, the machine,
+ * the account, the room, the path, the hostname, or the Brain key to this
+ * value, so there is nothing to invert. A hash of an identifier would still
+ * BE that identifier wearing a hat: the same user on two installs would
+ * hash to the same bucket, and anyone holding the identifier could confirm
+ * a match. A random 128-bit value cannot do either. It carries exactly one
+ * bit of meaning: "the caller that sent this header before is the caller
+ * sending it now."
+ *
+ * THE EXPLICIT FORBIDDEN LIST -- this module must NEVER derive the id from:
+ *   - os.hostname()
+ *   - os.userInfo() / os.userInfo().username
+ *   - process.env.USER / process.env.USERNAME / process.env.LOGNAME
+ *   - process.cwd()
+ *   - a home directory path
+ *   - a MAC address or machine id
+ *   - an account id or room name
+ *   - the Brain key (process.env.MINDRIAN_BRAIN_KEY, resolve-brain-key.cjs)
+ *   - a hash of any of the above (crypto's createHash)
+ * tests/test-339-install-id-header.cjs arm 9 scans THIS FILE with comments
+ * stripped and fails the suite if any of those tokens appears outside this
+ * prose -- so this comment is safe and LOAD-BEARING, and must stay.
+ *
+ * NEVER LOGGED, NEVER PRINTED IN FULL (D-03): doctor reports presence only,
+ * and on rotation the word "rotated" -- never the value. The id itself is
+ * the user's own to read from their own file.
+ *
+ * Posture copied deliberately from lib/core/brain-prewarm.cjs: this module
+ * NEVER throws to its caller and NEVER writes to stdout, because it can run
+ * inside an MCP stdio process where a stray stdout byte corrupts the
+ * JSON-RPC transport. A single stderr line, guarded by MINDRIAN_DEBUG, is
+ * permitted, and it prints the FILE PATH or an error message only, never
+ * the id value.
+ *
+ * CJS only, no new dependencies: require only fs, path, os, crypto.
+ * No em-dashes (hyphens only).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const crypto = require('crypto');
+
+const INSTALL_ID_HEADER_NAME = 'x-theo-install-id';
+const ID_SHAPE_RE = /^[a-f0-9]{32}$/;
+const FILE_NAME = 'theo-install-id.json';
+
+const debugLog = (msg) => {
+  if (!process.env.MINDRIAN_DEBUG) return;
+  try {
+    process.stderr.write('[install-id] ' + msg + '\n');
+  } catch (_e) {
+    // swallow -- this function must never throw
+  }
+};
+
+/**
+ * installIdPath(homeDir) -- the on-disk location of the id file.
+ *
+ * Deliberately duplicates the SAME resolution expression as
+ * lib/core/brain-prewarm.cjs::markerPath rather than extracting a shared
+ * helper -- two call sites is below the threshold where coupling two
+ * never-throws modules beats a duplicated two-line expression. Safety net:
+ * tests/test-339-install-id-header.cjs arm 10 asserts both modules resolve
+ * to the same directory (the drift guard). Extraction trigger: a THIRD
+ * call site.
+ *
+ * @param {string} [homeDir] defaults to MINDRIAN_HOME or ~/.mindrian
+ * @returns {string}
+ */
+function installIdPath(homeDir) {
+  const home = homeDir || process.env.MINDRIAN_HOME || path.join(os.homedir(), '.mindrian');
+  return path.join(home, FILE_NAME);
+}
+
+/**
+ * Read the id file and return the id string, or null on any failure, any
+ * shape mismatch, or a fresh homeDir with no file yet. Never mints, never
+ * writes, never throws.
+ * @param {string} filePath
+ * @returns {string|null}
+ */
+function _readValidId(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.id === 'string' && ID_SHAPE_RE.test(parsed.id)) {
+      return parsed.id;
+    }
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * peekInstallId({ homeDir }) -- read-only. Returns the id when the file
+ * holds a valid one, otherwise null. NEVER mints, NEVER writes, NEVER
+ * throws. This exists so the doctor can report presence without a
+ * diagnostic run silently creating the thing it is diagnosing.
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function peekInstallId(opts) {
+  const o = opts || {};
+  try {
+    return _readValidId(installIdPath(o.homeDir));
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Atomically write { id, minted_at } to installIdPath(homeDir), mode 0600.
+ * Every fs operation is wrapped; any failure returns false and leaves no
+ * temp file behind.
+ * @param {string} homeDir
+ * @param {string} id
+ * @returns {boolean}
+ */
+function _atomicWrite(homeDir, id) {
+  const finalPath = installIdPath(homeDir);
+  const dir = path.dirname(finalPath);
+  const tmpPath = path.join(
+    dir,
+    FILE_NAME + '.tmp-' + process.pid + '-' + crypto.randomBytes(3).toString('hex')
+  );
+  const body = { id: id, minted_at: new Date().toISOString() };
+  const json = JSON.stringify(body);
+  try {
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(tmpPath, json, { encoding: 'utf8', mode: 0o600 });
+    fs.renameSync(tmpPath, finalPath);
+    if (process.platform !== 'win32') {
+      try {
+        fs.chmodSync(finalPath, 0o600);
+      } catch (_e) {
+        // belt only -- the write-time mode already applied it.
+      }
+    }
+    debugLog('id written: ' + finalPath);
+    return true;
+  } catch (e) {
+    debugLog('id write failed: ' + (e && e.message ? e.message : String(e)));
+    try {
+      fs.unlinkSync(tmpPath);
+    } catch (_e) {
+      // no temp file to clean up, or already gone.
+    }
+    return false;
+  }
+}
+
+/**
+ * getInstallId({ homeDir }) -- mint-once. peekInstallId first; on a hit
+ * return it. On a miss, mint a fresh 32-hex id from crypto.randomBytes(16),
+ * write it atomically, then RE-CHECK for a concurrent winner: two processes
+ * making their first Brain call at the same instant must converge on ONE
+ * bucket, not split it. Every failure returns null rather than throwing.
+ *
+ * Returning null rather than an unpersisted in-memory id on a write
+ * failure is deliberate: a volatile id would send a different value on
+ * every process and quietly break the one-install-one-id property the
+ * whole header exists to provide.
+ *
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function getInstallId(opts) {
+  const o = opts || {};
+  const existing = peekInstallId(o);
+  if (existing) return existing;
+
+  const minted = crypto.randomBytes(16).toString('hex');
+  const wrote = _atomicWrite(o.homeDir, minted);
+  if (!wrote) {
+    // Concurrent-winner re-check even on our own write failure: another
+    // process may have won the race while we were failing.
+    return peekInstallId(o);
+  }
+
+  // Concurrent-winner re-check: if another process's mint landed between
+  // our write and this read, defer to it so both processes converge on one
+  // bucket rather than splitting into two.
+  const afterWrite = peekInstallId(o);
+  if (afterWrite && afterWrite !== minted) {
+    return afterWrite;
+  }
+  return afterWrite || minted;
+}
+
+/**
+ * resetInstallId({ homeDir }) -- mints unconditionally and REPLACES,
+ * skipping the concurrent-winner re-check (rotation must win over an
+ * existing file by definition). Same atomic write, same mode, same
+ * never-throws contract.
+ * @param {{homeDir?: string}} [opts]
+ * @returns {string|null}
+ */
+function resetInstallId(opts) {
+  const o = opts || {};
+  const minted = crypto.randomBytes(16).toString('hex');
+  const wrote = _atomicWrite(o.homeDir, minted);
+  return wrote ? minted : null;
+}
+
+module.exports = {
+  installIdHeaderName: INSTALL_ID_HEADER_NAME,
+  installIdPath: installIdPath,
+  peekInstallId: peekInstallId,
+  getInstallId: getInstallId,
+  resetInstallId: resetInstallId,
+};

package/lib/core/integration-registry.cjs

@@ -1,19 +1,20 @@
 'use strict';
 
 /**
- * Integration Registry — detects available integrations from env, MCP config, filesystem.
+ * Integration Registry - detects available integrations from env, MCP config, filesystem.
  *
  * Zero npm dependencies. Pure Node.js built-ins only (Phase 10 pattern).
  *
  * Exports:
- *   INTEGRATION_CATALOG — all known integrations with detection config
- *   detectIntegrations(options) — scan all integrations, return structured status
- *   checkIntegration(name) — single integration check
- *   getContextTriggers(userMessage, roomState) — suggest integrations based on context
+ *   INTEGRATION_CATALOG - all known integrations with detection config
+ *   detectIntegrations(options) - scan all integrations, return structured status
+ *   checkIntegration(name) - single integration check
+ *   getContextTriggers(userMessage, roomState) - suggest integrations based on context
  */
 
 const fs = require('fs');
 const path = require('path');
+const os = require('os');
 
 /**
  * Catalog of all known integrations.
@@ -61,19 +62,92 @@ const INTEGRATION_CATALOG = {
   },
 };
 
+/**
+ * Read and JSON.parse a config file. Returns the parsed object, or null on
+ * any failure (missing file, unreadable, malformed JSON). Private: the one
+ * fs.readFileSync + JSON.parse site both parseMcpConfig() and
+ * readScopedMcpServers() delegate to, so there is exactly one place that
+ * touches disk for either reader (Canon Part 7, no third reader minted).
+ */
+function _readJsonConfig(configPath) {
+  try {
+    const raw = fs.readFileSync(configPath, 'utf-8');
+    return JSON.parse(raw);
+  } catch (e) {
+    return null;
+  }
+}
+
 /**
  * Parse .mcp.json to extract configured MCP server keys.
  * Returns array of server key strings (lowercased).
+ * Byte-unchanged behavior from before the _readJsonConfig extraction: any
+ * read/parse failure still yields [].
  */
 function parseMcpConfig(mcpConfigPath) {
-  try {
-    const raw = fs.readFileSync(mcpConfigPath, 'utf-8');
-    const parsed = JSON.parse(raw);
-    const servers = parsed.mcpServers || parsed.servers || {};
-    return Object.keys(servers).map(k => k.toLowerCase());
-  } catch (e) {
-    return [];
+  const parsed = _readJsonConfig(mcpConfigPath);
+  if (!parsed) return [];
+  const servers = parsed.mcpServers || parsed.servers || {};
+  return Object.keys(servers).map(k => k.toLowerCase());
+}
+
+/**
+ * Read Claude Code's own MCP server config (~/.claude.json by default) and
+ * project the mcpServers entries at BOTH scopes Claude Code actually has for
+ * this file: top-level mcpServers (scope "user") and
+ * projects[projectDir].mcpServers (scope "local"). This intentionally never
+ * reads a repo's own .mcp.json ("project" scope in Claude Code's own
+ * vocabulary) -- that is a different file entirely and is out of scope for
+ * this reader by construction, never by discipline.
+ *
+ * SECURITY (Canon Part 8, quick task 260911-axz, T-axz-01): the returned
+ * shape is a STRUCTURAL secret-leak guard, not a discretionary one. Each
+ * entry is projected down to exactly { name, scope, url_host, type }. This
+ * function NEVER copies `headers`, NEVER copies the full `url` (only the
+ * host, derived via `new URL(entry.url).host`), and NEVER copies `env`, so
+ * no caller of this function -- today or in a future edit -- can leak a
+ * Bearer token, an API key, or any other header value even by accident:
+ * the bytes are never read into the return value in the first place.
+ *
+ * @param {{configPath?: string, projectDir?: string}} [opts]
+ * @returns {Array<{name: string, scope: 'user'|'local', url_host: string|null, type: string|null}>}
+ */
+function readScopedMcpServers(opts) {
+  const o = opts || {};
+  const configPath = o.configPath || path.join(os.homedir(), '.claude.json');
+  const projectDir = o.projectDir || process.cwd();
+
+  const parsed = _readJsonConfig(configPath);
+  if (!parsed) return [];
+
+  const out = [];
+  const pushScope = (serversObj, scope) => {
+    if (!serversObj || typeof serversObj !== 'object') return;
+    for (const name of Object.keys(serversObj)) {
+      const entry = serversObj[name] || {};
+      let url_host = null;
+      if (typeof entry.url === 'string' && entry.url.length > 0) {
+        try {
+          url_host = new URL(entry.url).host;
+        } catch (_e) {
+          url_host = null;
+        }
+      }
+      out.push({
+        name: name,
+        scope: scope,
+        url_host: url_host,
+        type: typeof entry.type === 'string' ? entry.type : null,
+      });
+    }
+  };
+
+  pushScope(parsed.mcpServers, 'user');
+  if (parsed.projects && typeof parsed.projects === 'object' && parsed.projects[projectDir]) {
+    pushScope(parsed.projects[projectDir].mcpServers, 'local');
   }
+
+  return out;
 }
 
 /**
@@ -98,8 +172,8 @@ function detectObsidianVault(workDir) {
 
 /**
  * Detect status of a single integration.
- * @param {string} name — integration key from INTEGRATION_CATALOG
- * @param {object} opts — { workDir, mcpKeys }
+ * @param {string} name - integration key from INTEGRATION_CATALOG
+ * @param {object} opts - { workDir, mcpKeys }
  * @returns {object} status object
  */
 function detectSingle(name, opts) {
@@ -147,8 +221,8 @@ function detectSingle(name, opts) {
 /**
  * Detect all integrations.
  * @param {object} options
- * @param {string} options.workDir — defaults to process.cwd()
- * @param {string} options.mcpConfig — path to .mcp.json (defaults to workDir/.mcp.json)
+ * @param {string} options.workDir - defaults to process.cwd()
+ * @param {string} options.mcpConfig - path to .mcp.json (defaults to workDir/.mcp.json)
  * @returns {object} keyed by integration name, each with status object
  */
 function detectIntegrations(options = {}) {
@@ -168,8 +242,8 @@ function detectIntegrations(options = {}) {
 
 /**
  * Check a single integration by name.
- * @param {string} name — integration key
- * @param {object} options — same as detectIntegrations
+ * @param {string} name - integration key
+ * @param {object} options - same as detectIntegrations
  * @returns {object} status object for that integration
  */
 function checkIntegration(name, options = {}) {
@@ -184,8 +258,8 @@ function checkIntegration(name, options = {}) {
  * Analyze user message + room state and return integration suggestions.
  * Returns at most 1 suggestion. Suppressed during active methodology.
  *
- * @param {string} userMessage — the user's current message
- * @param {object} roomState — current room state (activeMethodology truthy = suppress)
+ * @param {string} userMessage - the user's current message
+ * @param {object} roomState - current room state (activeMethodology truthy = suppress)
  * @returns {Array<{integration: string, reason: string, offer_text: string}>}
  */
 function getContextTriggers(userMessage, roomState = {}) {
@@ -229,4 +303,6 @@ module.exports = {
   detectIntegrations,
   checkIntegration,
   getContextTriggers,
+  parseMcpConfig,
+  readScopedMcpServers,
 };

package/lib/mcp/brain-composition-census.cjs

@@ -77,15 +77,28 @@
  *     Section 3.5's explicit APPROVE condition) or validateSites() throws
  *     at module load.
  *
- * This module is a DECLARATION only: it requires nothing, executes
- * nothing, opens no wire. The scanner that reconciles it against source
- * lives in the test, not here -- that split is what lets this file hold
- * plain quoted path strings as DATA without ever matching its own
- * require-expression scan pattern.
+ * This module is a DECLARATION that requires exactly one pure-data leaf
+ * (brain-route-bound.cjs) and nothing else; it still EXECUTES nothing and
+ * OPENS NO WIRE (Quick 260911-ddd, DDD-02: the leaf itself requires nothing
+ * and opens no wire either, so this property still holds transitively).
+ * The scanner that reconciles this declaration against source lives in the
+ * test, not here -- that split is what lets this file hold plain quoted
+ * path strings as DATA without ever matching its own require-expression
+ * scan pattern. The new require names `brain-route-bound.cjs`, which
+ * matches neither the census scan's REACH_RE (brain-client|chain-
+ * recommender) nor its wire-pattern scan, so this file's own scan-safety
+ * property is unaffected.
  *
  * No em-dashes. CJS only.
  */
 
+// Quick 260911-ddd (DDD-02): the single source of the Tier 3 bound. Reading
+// the leaf here (rather than reading brain-router.cjs's own export) keeps
+// the DECLARATION direction correct: this census depends on the constant,
+// never on the implementation, so the declaration cannot silently drift
+// out of sync with a router edit.
+const { BRAIN_ROUTE_TIMEOUT_MS } = require('./brain-route-bound.cjs');
+
 const COMPOSITION_SITES = Object.freeze([
   Object.freeze({
     file: 'lib/mcp/brain-router.cjs',
@@ -94,7 +107,10 @@ const COMPOSITION_SITES = Object.freeze([
     via: "brainClient.ask(question) -- a generic problem-type/complexity enum question, never room content",
     reaches_brain: true,
     belt: 'callTool',
-    bound_ms: 2000,
+    // Quick 260911-ddd (DDD-02): bound_ms is the DEFAULT from the single
+    // source (lib/mcp/brain-route-bound.cjs); MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS
+    // can move the APPLIED bound at runtime without editing this file.
+    bound_ms: BRAIN_ROUTE_TIMEOUT_MS,
     frequency: 'one call per act* invocation, Tier 3 only (Tier 1 cache and Tier 2 local heuristic run first and can short-circuit before this call is made)',
     reason: "D-01 ratifies this as the orchestration tool's live Brain-grounded recommendation leg, shipped before this phase existed. Desktop and Cowork have no MCP hook surface, so this is their only Brain-grounded enrichment path for act*.",
     ratified_by: 'D-01',

package/lib/mcp/brain-route-bound.cjs

@@ -0,0 +1,66 @@
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Quick 260911-ddd (DDD-02) -- the single source of truth for
+ * brain-router.cjs's Tier 3 race bound. A pure-data leaf: requires nothing,
+ * opens no wire. lib/mcp/brain-router.cjs reads BRAIN_ROUTE_TIMEOUT_MS /
+ * resolveBrainRouteTimeoutMs() to build its Promise.race; brain-composition-
+ * census.cjs's bound_ms entry reads BRAIN_ROUTE_TIMEOUT_MS so the census
+ * DECLARATION depends on a constant instead of on the router's own
+ * implementation -- that direction (census -> leaf, never census -> router)
+ * is what keeps the census honest: a router edit can never silently move the
+ * bound the census reports without also moving this leaf.
+ *
+ * WHY 6000, MEASURED GROUND (not intuition):
+ *
+ * The raced call is brainClient.ask(), which since quick 260910-hni makes
+ * THREE sequential Theo calls (brain_ask, then recommend_chain, then
+ * brain_query). A Render instance waking from spin-down was measured at
+ * 2.034 s on the FIRST call alone, and Theo redeploys on every push to its
+ * main, opening a fresh cold window each time. So the old 2000 ms bound
+ * could not cover even a WARM three-call composition on a slow link, let
+ * alone a cold one -- every cold window silently degraded /mos:act to the
+ * local heuristic with no disclosure of why.
+ *
+ * 6000 is the measured 2.034 s cold wake plus two warm follow-on calls
+ * (roughly 1 s total) with roughly 2x headroom on top of that sum.
+ *
+ * THE ACCEPTED COST: when Theo is genuinely down, the race now rejects at
+ * 6 s instead of 2 s. This is a real cost, not hand-waved away -- but
+ * localRec (lib/mcp/brain-router.cjs's Tier 2 local heuristic) is already
+ * computed BEFORE the race starts, so the Tier 2 answer is instant once the
+ * race loses and /mos:act still resolves either way. The trade is a rarer
+ * 6 s worst case against a silently degraded recommendation on every cold
+ * window -- accepted (see the threat register, T-ddd-04).
+ *
+ * No em-dashes. CJS only.
+ */
+
+/**
+ * The default Tier 3 race bound in milliseconds. See the file header for
+ * the measured justification.
+ * @type {number}
+ */
+const BRAIN_ROUTE_TIMEOUT_MS = 6000;
+
+/**
+ * resolveBrainRouteTimeoutMs(env) -- honors MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS
+ * only when it parses to a finite integer strictly greater than 0;
+ * otherwise returns BRAIN_ROUTE_TIMEOUT_MS unchanged. A malformed operator
+ * env can never zero out or invert the bound.
+ *
+ * @param {object} [env] defaults to process.env
+ * @returns {number}
+ */
+function resolveBrainRouteTimeoutMs(env) {
+  const source = env || process.env;
+  const raw = source && source.MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS;
+  if (typeof raw !== 'string' || raw.trim().length === 0) return BRAIN_ROUTE_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) return BRAIN_ROUTE_TIMEOUT_MS;
+  return parsed;
+}
+
+module.exports = { BRAIN_ROUTE_TIMEOUT_MS, resolveBrainRouteTimeoutMs };

package/lib/mcp/brain-router.cjs

@@ -6,7 +6,7 @@
  * 3-tier fallback for framework recommendations:
  *   Tier 1: In-memory cache (instant, 10-min TTL)
  *   Tier 2: Local heuristic from problem-types.md (~100ms)
- *   Tier 3: Brain API via brain-client.cjs (2s hard timeout)
+ *   Tier 3: Brain API via brain-client.cjs (bound: MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS, default 6000ms -- lib/mcp/brain-route-bound.cjs)
  *
  * RECOMMENDS only -- never executes frameworks.
  * Called by orchestration router for act*, suggest-next commands.
@@ -14,6 +14,12 @@
 
 const path = require('path');
 const { safeReadFile } = require('../core/index.cjs');
+// Quick 260911-ddd (DDD-02): the single source of the Tier 3 race bound.
+// See brain-route-bound.cjs's header for the measured 6000 ms justification
+// and brain-composition-census.cjs, whose bound_ms entry reads this SAME
+// leaf. brain-composition-census provenance: this file's Tier 3 race is
+// enumerated in lib/mcp/brain-composition-census.cjs.
+const { BRAIN_ROUTE_TIMEOUT_MS, resolveBrainRouteTimeoutMs } = require('./brain-route-bound.cjs');
 
 // ---------------------------------------------------------------------------
 // Cache (Tier 1)
@@ -287,11 +293,12 @@ function localRoute(roomDir, stateContent, intent) {
 // Phase 254 (COMP-01): this call is enumerated in
 // lib/mcp/brain-composition-census.cjs as the 'orchestration (act,
 // act-chain, act-dry-run, act-swarm)' reaching site -- reaches_brain: true,
-// belt: 'callTool', bound_ms: 2000 (the Promise.race wrap in recommend()
-// below). D-01 (254-CONTEXT.md) ratified this as SHIPPED, released
-// behaviour, not a new decision. A new composed Brain call anywhere under
-// lib/mcp/ requires an entry there or the build fails
-// (tests/test-254-composition-census.cjs).
+// belt: 'callTool', bound_ms: BRAIN_ROUTE_TIMEOUT_MS (Quick 260911-ddd,
+// DDD-02; the Promise.race wrap in recommend() below, default 6000ms,
+// overridable via MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS). D-01 (254-CONTEXT.md)
+// ratified this as SHIPPED, released behaviour, not a new decision. A new
+// composed Brain call anywhere under lib/mcp/ requires an entry there or
+// the build fails (tests/test-254-composition-census.cjs).
 async function brainRoute(roomDir, stateContent, intent) {
   // Phase 339 Plan 05 (D-03b), 2026-09-03: reset at entry so a value read
   // by a caller can only ever reflect THIS invocation's own outcome.
@@ -422,7 +429,8 @@ async function brainRoute(roomDir, stateContent, intent) {
 
 /**
  * Get a framework recommendation for a room.
- * 3-tier fallback: cache -> local heuristic -> Brain API (2s timeout).
+ * 3-tier fallback: cache -> local heuristic -> Brain API (bound:
+ * MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS, default 6000ms).
  *
  * @param {string} roomDir - Path to room directory
  * @param {{ intent?: string, mode?: string }} [options]
@@ -457,11 +465,15 @@ async function recommend(roomDir, options = {}) {
   // Tier 2: Local heuristic (always computed as fallback)
   const localRec = localRoute(roomDir, stateContent, intent);
 
-  // Tier 3: Brain API (2s timeout, non-blocking)
+  // Tier 3: Brain API (bound: MINDRIAN_BRAIN_ROUTE_TIMEOUT_MS, default
+  // 6000ms; non-blocking -- localRec above is already computed, so the
+  // Tier 2 answer is instant once this race loses). Quick 260911-ddd
+  // (DDD-02): evaluated at CALL TIME so an env override is honored per
+  // call and is testable, rather than a frozen 2000 literal.
   try {
     const brainRec = await Promise.race([
       brainRoute(roomDir, stateContent, intent),
-      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), 2000))
+      new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')), resolveBrainRouteTimeoutMs()))
     ]);
     if (brainRec) {
       setCache(cacheKey, brainRec);
@@ -548,4 +560,7 @@ function validateChain(roomDir, chain) {
   return { valid: true };
 }
 
-module.exports = { recommend, validateChain };
+// Quick 260911-ddd (DDD-02): re-exported so the Tier 3 bound pin is
+// readable from either side (this file and brain-composition-census.cjs
+// both read the same lib/mcp/brain-route-bound.cjs leaf).
+module.exports = { recommend, validateChain, BRAIN_ROUTE_TIMEOUT_MS, resolveBrainRouteTimeoutMs };

package/lib/mcp/hook-adapter-audit.cjs

@@ -1,7 +1,9 @@
 'use strict';
 // Phase 198-08 (SPEC-5, D-06) -- hook-adapter-audit: the measured
 // "adapter-only" budget for MIGRATED hook scripts (enumerated from
-// hooks/hooks.json's _mcpFirst198Migrated marker, Task 1). Two checks:
+// data/hooks-markers.json's _mcpFirst198Migrated marker, moved there by
+// quick task 260911-juq because the Claude Code hook loader warns on
+// unknown top-level keys in hooks/hooks.json). Two checks:
 //   1. IMPORT AUDIT -- a migrated hook script's own require() calls (after
 //      comment-stripping, so a header/doc comment naming lib/core does not
 //      self-invalidate the gate) never reach into lib/core, lib/workflow, or
@@ -14,10 +16,10 @@
 //      cannot silently re-fatten a thin adapter back into a business-logic
 //      script without this test failing.
 //
-// Scope: ONLY the surfaces hooks.json's own migration marker names (D-05:
-// statusline + SessionStart THIS plan; Stop-gate scripts are Plan 09's
-// concern and are never enumerated here -- enumeration comes from the
-// marker, not a hand-maintained list, so Plan 09 adding its own marker
+// Scope: ONLY the surfaces data/hooks-markers.json's own migration marker
+// names (D-05: statusline + SessionStart THIS plan; Stop-gate scripts are
+// Plan 09's concern and are never enumerated here -- enumeration comes from
+// the marker, not a hand-maintained list, so Plan 09 adding its own marker
 // entries later does not require touching this file).
 //
 // No em-dashes. CJS only.
@@ -26,7 +28,7 @@ const fs = require('node:fs');
 const path = require('node:path');
 
 const REPO_ROOT = path.resolve(__dirname, '..', '..');
-const HOOKS_JSON_PATH = path.join(REPO_ROOT, 'hooks', 'hooks.json');
+const HOOKS_MARKERS_PATH = path.join(REPO_ROOT, 'data', 'hooks-markers.json');
 
 // Measured baseline + a small margin (D-06: "set the budget from the thin
 // post-migration line counts with a small margin; record the exact numbers
@@ -68,15 +70,17 @@ const LINE_BUDGETS = {
 const FORBIDDEN_IMPORT_PATTERN = /require\(.*lib\/core|require\(.*lib\/workflow|require\(.*lib\/memory/;
 
 /**
- * migratedSurfaces() -- read hooks.json's _mcpFirst198Migrated.surfaces
- * marker (Task 1) and return the list of migrated script paths (repo-root
+ * migratedSurfaces() -- read data/hooks-markers.json's
+ * _mcpFirst198Migrated.surfaces marker (Task 1; moved out of hooks/hooks.json
+ * by quick task 260911-juq so the hook loader stops warning on unknown
+ * top-level keys) and return the list of migrated script paths (repo-root
  * relative). Never throws; a missing/malformed marker returns [].
  *
  * @returns {string[]}
  */
 function migratedSurfaces() {
   try {
-    const raw = fs.readFileSync(HOOKS_JSON_PATH, 'utf8');
+    const raw = fs.readFileSync(HOOKS_MARKERS_PATH, 'utf8');
     const parsed = JSON.parse(raw);
     const marker = parsed && parsed._mcpFirst198Migrated;
     const surfaces = marker && Array.isArray(marker.surfaces) ? marker.surfaces : [];

package/npm-shrinkwrap.json

@@ -1,12 +1,12 @@
 {
   "name": "@mindrian_os/cli",
-  "version": "2.0.0-beta.33",
+  "version": "2.0.0-beta.37",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@mindrian_os/cli",
-      "version": "2.0.0-beta.33",
+      "version": "2.0.0-beta.37",
       "license": "BSL-1.1",
       "dependencies": {
         "@ig3/markdown-it-wikilinks": "^1.0.2",