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

package/data/hooks-markers.json

@@ -0,0 +1,25 @@
+{
+  "_mcpFirst198Migrated": {
+    "_note": "Phase 198-08 (SPEC-5, D-05/D-06) migration markers, extended by Phase 198-09 (D-05 final wave). Each entry names a hook script that now dispatches to lib/mcp/adapter-client.cjs behind MINDRIAN_MCP_FIRST ('cli' or 'all') instead of running its business logic locally; flag OFF (unset/empty, the default) keeps the pre-migration legacy behavior byte-identical (SPEC-7). This is metadata for tests/test-198-adapter-budget.test.cjs's import-audit + line-count budget (D-06) to enumerate -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key in hooks/hooks.json. Migration order is D-05: statusline + SessionStart FIRST (198-08); Stop-gate enforcement LAST (198-09, this entry), only after server-side gate dedup + relevance existed (lib/mcp/gate-dedup.cjs, Task 1 of 198-09). scripts/check-card-fire.cjs is NOT listed here -- it stays a separate Stop hook entry that no-ops under the flag (deferring to on-stop's daemon-backed decision), never itself migrated to a thin adapter shape.",
+    "surfaces": [
+      {
+        "script": "scripts/statusline-mos-dispatch",
+        "tool": "status_read",
+        "note": "Statusline segment (spend/cap from day one). Flag ON wakes the daemon and queries status_read; flag OFF execs the legacy scripts/statusline-mos exactly as shipped."
+      },
+      {
+        "script": "scripts/sessionstart-coordinator.cjs",
+        "tool": "room_state_bound,status_read",
+        "note": "SessionStart binding + status segments. Flag ON wakes the daemon and queries room_state_bound + status_read (runThinAdapter); flag OFF runs the full 11-contributor runAll() exactly as shipped."
+      },
+      {
+        "script": "scripts/on-stop",
+        "tool": "stop_gate_check",
+        "note": "Stop-gate enforcement + business close-out (D-05 final wave). Flag ON wakes the daemon and queries stop_gate_check (lib/mcp/tools/stop-gate.cjs -> lib/mcp/stop-gate-handler.cjs -- gate-dedup + relevance gate the fire decision, the shipped check-card-fire.cjs predicate is the final authority, the daemon owns STATE.md/memory-lifecycle/minto-debouncer/folder-memory close-out); flag OFF runs the full legacy body exactly as shipped."
+      }
+    ]
+  },
+  "_firstInstallRouterOrdering": {
+    "_note": "Phase 267.2-06 (HOOK-08). scripts/first-install-router.cjs is registered in the UserPromptSubmit chain immediately AFTER scripts/mva-detect.cjs and before scripts/brain-derivation-drain.cjs. This is metadata for a human reader (and any future drift test) -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key in hooks/hooks.json. ORDERING IS LOAD BEARING: the router consumes the pending MVA state that mva-detect.cjs writes on the same turn, so running before it would read a stale or absent state. Do not reorder these two entries without re-checking this dependency."
+  }
+}

package/hooks/hooks.json

@@ -1,27 +1,4 @@
 {
-  "_mcpFirst198Migrated": {
-    "_note": "Phase 198-08 (SPEC-5, D-05/D-06) migration markers, extended by Phase 198-09 (D-05 final wave). Each entry names a hook script that now dispatches to lib/mcp/adapter-client.cjs behind MINDRIAN_MCP_FIRST ('cli' or 'all') instead of running its business logic locally; flag OFF (unset/empty, the default) keeps the pre-migration legacy behavior byte-identical (SPEC-7). This is metadata for tests/test-198-adapter-budget.test.cjs's import-audit + line-count budget (D-06) to enumerate -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key below. Migration order is D-05: statusline + SessionStart FIRST (198-08); Stop-gate enforcement LAST (198-09, this entry), only after server-side gate dedup + relevance existed (lib/mcp/gate-dedup.cjs, Task 1 of 198-09). scripts/check-card-fire.cjs is NOT listed here -- it stays a separate Stop hook entry that no-ops under the flag (deferring to on-stop's daemon-backed decision), never itself migrated to a thin adapter shape.",
-    "surfaces": [
-      {
-        "script": "scripts/statusline-mos-dispatch",
-        "tool": "status_read",
-        "note": "Statusline segment (spend/cap from day one). Flag ON wakes the daemon and queries status_read; flag OFF execs the legacy scripts/statusline-mos exactly as shipped."
-      },
-      {
-        "script": "scripts/sessionstart-coordinator.cjs",
-        "tool": "room_state_bound,status_read",
-        "note": "SessionStart binding + status segments. Flag ON wakes the daemon and queries room_state_bound + status_read (runThinAdapter); flag OFF runs the full 11-contributor runAll() exactly as shipped."
-      },
-      {
-        "script": "scripts/on-stop",
-        "tool": "stop_gate_check",
-        "note": "Stop-gate enforcement + business close-out (D-05 final wave). Flag ON wakes the daemon and queries stop_gate_check (lib/mcp/tools/stop-gate.cjs -> lib/mcp/stop-gate-handler.cjs -- gate-dedup + relevance gate the fire decision, the shipped check-card-fire.cjs predicate is the final authority, the daemon owns STATE.md/memory-lifecycle/minto-debouncer/folder-memory close-out); flag OFF runs the full legacy body exactly as shipped."
-      }
-    ]
-  },
-  "_firstInstallRouterOrdering": {
-    "_note": "Phase 267.2-06 (HOOK-08). scripts/first-install-router.cjs is registered in the UserPromptSubmit chain immediately AFTER scripts/mva-detect.cjs and before scripts/brain-derivation-drain.cjs. This is metadata for a human reader (and any future drift test) -- it is NOT consumed by Claude Code's hook loader, which only reads the 'hooks' key below. ORDERING IS LOAD BEARING: the router consumes the pending MVA state that mva-detect.cjs writes on the same turn, so running before it would read a stale or absent state. Do not reorder these two entries without re-checking this dependency."
-  },
   "hooks": {
     "SessionStart": [
       {

package/lib/core/brain-client.cjs

@@ -305,6 +305,34 @@ function isAvailable() {
   return !!getApiKey();
 }
 
+// Quick 260911-iko (D-04): the opaque per-install header, spread into both
+// of callTool's wire requests. A per-process memo is correct here (mirrors
+// the getApiKey() memo idiom above) and must be commented as such: the id
+// only changes on reinstall or on a `doctor --reset-install-id` run, and
+// both of those happen in a DIFFERENT process, so re-reading it on every
+// call would buy nothing. Wrapped in its own try/catch so a missing or
+// broken install-id module can never take a Brain call down -- the header
+// is a bucket key, never a requirement (D-04: omitted, never an error).
+//
+// This helper never touches the Part 8 egress belt (classify() at
+// callTool's egress-guard call below): that belt classifies `args`, and
+// headers are not payload. The install id never enters `args` and must
+// never be added to them.
+let _memoizedInstallIdHeaders = null;
+function _installIdHeaders() {
+  if (_memoizedInstallIdHeaders) return _memoizedInstallIdHeaders;
+  try {
+    const installIdMod = require('./install-id.cjs');
+    const id = installIdMod.getInstallId();
+    _memoizedInstallIdHeaders = (typeof id === 'string')
+      ? { [installIdMod.installIdHeaderName]: id }
+      : {};
+  } catch (_e) {
+    _memoizedInstallIdHeaders = {};
+  }
+  return _memoizedInstallIdHeaders;
+}
+
 // ---------------------------------------------------------------------------
 // Phase 250-04 (HONEST-03, SEED-011 Option A) -- per-install silent
 // registration. Design doc: docs/BRAIN-IDENTITY-DESIGN.md.
@@ -350,6 +378,12 @@ async function _tryAutoRegister() {
 
   try {
     const installId = crypto.randomUUID();
+    // Quick 260911-iko: the x-theo-install-id header does NOT ride here.
+    // D-04 names callTool's two header blocks only; registration is a
+    // different endpoint with its own contract, and it runs before there is
+    // an established Brain session to bucket. Adding it here would be a
+    // change to Theo's registration surface, which D-06 says must be
+    // announced to Theo first -- a deliberate exclusion, not a miss.
     const res = await fetch(`${BRAIN_URL}/register`, {
       method: 'POST',
       signal: AbortSignal.timeout(BRAIN_REQUEST_TIMEOUT_MS),
@@ -456,6 +490,7 @@ async function _ensureSession(apiKey) {
         'Content-Type': 'application/json',
         'Accept': 'application/json, text/event-stream',
         'Authorization': `Bearer ${apiKey}`,
+        ..._installIdHeaders(),
       },
       body: JSON.stringify({
         jsonrpc: '2.0',
@@ -675,6 +710,7 @@ async function callTool(toolName, args) {
             'Content-Type': 'application/json',
             'Accept': 'application/json, text/event-stream',
             'Authorization': `Bearer ${key}`,
+            ..._installIdHeaders(),
           },
           body: JSON.stringify({
             jsonrpc: '2.0',
@@ -1250,29 +1286,68 @@ async function _composeTheoAsk(payload, question, deps) {
     }
 
     // CONFIDENCE: top step reads exactly 0.9; a missing/non-finite degree -> 0.5.
+    // theo_rank and the command-bearing-first sort below never touch this
+    // computation -- the sort reorders `options`, it never recomputes a
+    // confidence value (Quick 260911-ddd, DDD-01).
     const top = steps.reduce((max, s) => {
       const d = s && Number.isFinite(s.degree) ? s.degree : 0;
       return d > max ? d : max;
     }, 0);
-    const options = steps.map((s) => {
+    const options = steps.map((s, idx) => {
       const degree = s && s.degree;
       let confidence = 0.5;
       if (top > 0 && Number.isFinite(degree)) {
         confidence = Math.max(0.5, Math.min(0.9, Math.round((0.5 + 0.4 * (degree / top)) * 100) / 100));
       }
+      // Quick 260911-ddd (DDD-01): theo_rank carries Theo's own rank so it
+      // is never lost by the reorder below. Theo's `step` field when it is
+      // a finite number, else the 1-based index of this step WITHIN Theo's
+      // own chain array, computed here before any sort so a later reorder
+      // can never leak into this number.
+      const theoRank = (s && Number.isFinite(s.step)) ? s.step : idx + 1;
       return {
         framework: s && s.framework,
         confidence: confidence,
         commands: commandsByFramework.get(s && s.framework) || [],
+        theo_rank: theoRank,
       };
     });
 
+    // Quick 260911-ddd (DDD-01): stable partition, command-bearing options
+    // first, Theo's relative order preserved inside each group. Theo's
+    // ranking is NEVER altered at the source -- this reorders the plugin's
+    // OWN options array only. A single forward pass into two queues, then
+    // concatenated, is stable BY CONSTRUCTION; it does not rest on
+    // Array.prototype.sort's engine-stability semantics. When every option
+    // or no option carries a command, one queue is empty and the
+    // concatenation is the identity, so Theo's order survives unchanged
+    // for free.
+    //
+    // DOWNSTREAM CONSEQUENCE, stated here so it is not mistaken for a
+    // regression later: lib/mcp/brain-router.cjs:398 derives topConf from
+    // options[0].confidence. On a chain whose top-ranked framework has no
+    // command, the routed confidence now reads the first command-bearing
+    // option's confidence (0.83 on the live IllDefined shape, previously
+    // 0.9) -- that is the intended meaning of the change (confidence
+    // describes the option actually surfaced to the user), not a bug.
+    // brain-router.cjs is deliberately NOT touched to compensate for this.
+    const commandBearing = [];
+    const commandLess = [];
+    for (const opt of options) {
+      if (Array.isArray(opt.commands) && opt.commands.length > 0) {
+        commandBearing.push(opt);
+      } else {
+        commandLess.push(opt);
+      }
+    }
+    const sortedOptions = commandBearing.concat(commandLess);
+
     const out = Object.assign({}, payload);
     delete out.query_terms;
     out.directive = {
-      guided: { questions: [], framework: (steps[0] && steps[0].framework) || null, stage: rung },
+      guided: { questions: [], framework: (sortedOptions[0] && sortedOptions[0].framework) || null, stage: rung },
     };
-    out.next_gate = { sub_shape: 'F.1', options: options };
+    out.next_gate = { sub_shape: 'F.1', options: sortedOptions };
     out.grounding = {
       source: 'theo',
       answer_mode: payload.answer_mode,
@@ -1282,6 +1357,10 @@ async function _composeTheoAsk(payload, question, deps) {
       chain_coverage: (chainRes && chainRes.coverage && typeof chainRes.coverage === 'object') ? chainRes.coverage : null,
       chain_status: chainStatus,
       confidence_source: 'theo_degree_normalized',
+      // Quick 260911-ddd (DDD-01): names the applied ordering so a
+      // consumer never has to branch on the key's presence -- present here
+      // AND on the trailing catch path below.
+      option_order: 'command_bearing_first',
     };
     return out;
   } catch (_e) {
@@ -1299,6 +1378,7 @@ async function _composeTheoAsk(payload, question, deps) {
       chain_coverage: null,
       chain_status: 'unreachable',
       confidence_source: 'theo_degree_normalized',
+      option_order: 'command_bearing_first',
     };
     return out;
   }

package/lib/core/brain-prewarm.cjs

@@ -0,0 +1,164 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Quick 260911-ddd (DDD-02) -- a content-free Brain pre-warm fired at MCP
+ * shim startup so the Brain is already warm by the time the first question
+ * arrives, instead of leaving every cold Render wake to silently degrade
+ * /mos:act's Tier 3 race to the local heuristic (see
+ * lib/mcp/brain-route-bound.cjs for the measured cold-wake numbers this
+ * exists to cover).
+ *
+ * WHY THE TIMEOUT DOES NOT BOUND THE WAKE ITSELF: the request reaching
+ * Render is what wakes the instance; aborting our own wait does not cancel
+ * that in-flight wake on Render's side. The timeout here only bounds how
+ * long THIS PROCESS holds the marker write open waiting for a verdict --
+ * which is why 15000 ms is generous without costing anyone anything: even
+ * if we give up waiting, the wake we triggered keeps running on Render and
+ * the NEXT real call benefits from it.
+ *
+ * CANON PART 8 (D-02): the probe sends theo_health with NO ARGUMENTS
+ * (`callTool('theo_health', {})`, the exact shape class-m-brain-smoke.cjs:225
+ * already ships) and the marker persists ONLY {at, ok, origin_host} --
+ * never a response body, never a header value, never a question. Every fs
+ * and network failure is swallowed; this function NEVER throws and NEVER
+ * rejects.
+ *
+ * MCP STDIO SAFETY: this file writes NOTHING to stdout, ever, because it
+ * can run inside an MCP stdio process where a stray stdout byte corrupts
+ * the JSON-RPC transport. A single stderr line only when MINDRIAN_DEBUG is
+ * set.
+ *
+ * The deps seam ({ probe, originHost, now, homeDir, timeoutMs }, all
+ * optional) mirrors the same injectable-probe discipline
+ * lib/core/doctor/class-m-brain-smoke.cjs already uses for its own
+ * theoHealthFn seam, so a test drives every arm through deps and never
+ * touches a real Brain.
+ *
+ * No em-dashes. CJS only.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+
+const DEFAULT_PREWARM_TIMEOUT_MS = 15000;
+
+const debugLog = (msg) => {
+  if (!process.env.MINDRIAN_DEBUG) return;
+  try {
+    process.stderr.write('[brain-prewarm] ' + msg + '\n');
+  } catch (_e) {
+    // swallow -- this function must never throw
+  }
+};
+
+/**
+ * Derive the timeout (ms) for the probe race. Reads
+ * MINDRIAN_BRAIN_PREWARM_TIMEOUT_MS when it parses to a finite positive
+ * integer; otherwise DEFAULT_PREWARM_TIMEOUT_MS.
+ * @returns {number}
+ */
+function _resolveTimeoutMs() {
+  const raw = process.env.MINDRIAN_BRAIN_PREWARM_TIMEOUT_MS;
+  if (typeof raw !== 'string' || raw.trim().length === 0) return DEFAULT_PREWARM_TIMEOUT_MS;
+  const parsed = Number(raw);
+  if (!Number.isFinite(parsed) || !Number.isInteger(parsed) || parsed <= 0) return DEFAULT_PREWARM_TIMEOUT_MS;
+  return parsed;
+}
+
+/**
+ * Reduce a Brain origin URL to its host only (never the full URL, never a
+ * path, never a query string -- the marker holds origin_host, not the URL).
+ * @param {string} url
+ * @returns {string|null}
+ */
+function _hostOnly(url) {
+  if (typeof url !== 'string' || url.length === 0) return null;
+  try {
+    return new URL(url).host || null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * markerPath(homeDir) -- the on-disk location of the pre-warm marker.
+ * @param {string} [homeDir] defaults to MINDRIAN_HOME or ~/.mindrian
+ * @returns {string}
+ */
+function markerPath(homeDir) {
+  const home = homeDir || process.env.MINDRIAN_HOME || path.join(os.homedir(), '.mindrian');
+  return path.join(home, 'brain-prewarm.json');
+}
+
+/**
+ * prewarm(deps) -- fires one content-free theo_health probe and persists a
+ * minimal marker. NEVER throws, NEVER rejects, NEVER writes to stdout.
+ *
+ * @param {object} [deps]
+ * @param {() => Promise<any>} [deps.probe] defaults to
+ *   `() => require('./brain-client.cjs').callTool('theo_health', {})`,
+ *   required LAZILY so importing this module costs nothing.
+ * @param {string} [deps.originHost] defaults to the host of
+ *   `require('./brain-client.cjs').getBrainUrl()`.
+ * @param {() => Date} [deps.now] defaults to `() => new Date()`.
+ * @param {string} [deps.homeDir] defaults to MINDRIAN_HOME or ~/.mindrian.
+ * @param {number} [deps.timeoutMs] defaults to
+ *   MINDRIAN_BRAIN_PREWARM_TIMEOUT_MS or 15000.
+ * @returns {Promise<{ at: string, ok: boolean, origin_host: string|null }>}
+ */
+async function prewarm(deps) {
+  deps = deps || {};
+  const probe = deps.probe || (() => require('./brain-client.cjs').callTool('theo_health', {}));
+  const originHost = (typeof deps.originHost === 'string')
+    ? deps.originHost
+    : _hostOnly((() => {
+        try {
+          return require('./brain-client.cjs').getBrainUrl();
+        } catch (_e) {
+          return null;
+        }
+      })());
+  const now = deps.now || (() => new Date());
+  const homeDir = deps.homeDir;
+  const timeoutMs = Number.isFinite(deps.timeoutMs) && deps.timeoutMs > 0 ? deps.timeoutMs : _resolveTimeoutMs();
+
+  let ok = false;
+  try {
+    const TIMEOUT_SENTINEL = Symbol('brain-prewarm-timeout');
+    const result = await Promise.race([
+      Promise.resolve()
+        .then(() => probe())
+        .catch(() => null),
+      new Promise((resolve) => setTimeout(() => resolve(TIMEOUT_SENTINEL), timeoutMs)),
+    ]);
+    ok = !!(result && result !== TIMEOUT_SENTINEL && typeof result === 'object');
+  } catch (_e) {
+    ok = false;
+  }
+
+  // Canon Part 8 (D-02): EXACTLY three keys, nothing else. Never any part
+  // of the probe response body, never a key, never a question.
+  const marker = { at: now().toISOString(), ok: ok, origin_host: originHost || null };
+
+  try {
+    const filePath = markerPath(homeDir);
+    fs.mkdirSync(path.dirname(filePath), { recursive: true });
+    fs.writeFileSync(filePath, JSON.stringify(marker), 'utf8');
+    debugLog('marker written: ' + JSON.stringify(marker));
+  } catch (e) {
+    debugLog('marker write failed: ' + (e && e.message ? e.message : String(e)));
+  }
+
+  return marker;
+}
+
+// Directly spawnable: `node lib/core/brain-prewarm.cjs`.
+if (require.main === module) {
+  prewarm().catch(() => {});
+}
+
+module.exports = { prewarm, markerPath };