@mindrian_os/cli 2.0.0-beta.3 → 2.0.0-beta.31

package/bin/local-chain-recommender.cjs

@@ -0,0 +1,256 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 130.7-02 Task 2 -- bin/local-chain-recommender.cjs
+ * ========================================================
+ * The Tier-LOCAL sibling of lib/brain/chain-recommender.cjs
+ * recommendCanonicalTargets. It walks the room's recent memory_event references
+ * and AGGREGATES them BY correlation_id (not by name), returning the SAME
+ *   { correlation_id, canonical_name, primary_label }
+ * tuple shape the Brain-side recommender returns -- ranked by local aggregate
+ * weight (recency-weighted reference count). Because both sides compute the id
+ * via the one lib/core/correlation.cjs chokepoint, the local aggregate key
+ * equals the Brain node key, so the dual-graph join works BY CONSTRUCTION.
+ *
+ * Tier-LOCAL is the whole point: it NEVER requires the Brain. When the Brain is
+ * available it MAY reconcile against the Brain canonical (a value-equality check
+ * on correlation_id -- no fork because the id is canonical), but a Brain-down
+ * room still returns canonical tuples from local aggregates alone.
+ *
+ * Canon Part 9 (the navigation chokepoint): bin/ is NOT on the substrate
+ * allow-list, so this script reaches room.db ONLY through lib/core/navigation.cjs
+ * (openRoomDbForCaller / findRecentChanges / closeRoomDbForCaller). It never
+ * reaches the room-db module or the sqlite binding directly -- a direct import
+ * of either would trip scripts/check-substrate.cjs.
+ *
+ * Canon Part 8: a memory_event reference carries a correlation_id hash scalar
+ * (the Task 3 threading); the aggregate is over hashes + label enums + public
+ * methodology handles, never user content. Zero network surface here.
+ *
+ * Graceful degradation: an absent room.db (Tier 0 cold start) yields [] -- never
+ * a crash. Mirrors scripts/suggest-next-command.cjs Tier-0 degrade idiom.
+ *
+ * Usage:
+ *   node bin/local-chain-recommender.cjs
+ *   node bin/local-chain-recommender.cjs --room /path/to/room
+ *   node bin/local-chain-recommender.cjs --since <epochMs>
+ *   node bin/local-chain-recommender.cjs --json
+ *
+ * License: BSL 1.1.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..');
+// navigation.cjs is the ONLY door to room.db for this bin/ script.
+const navigation = require(path.join(REPO_ROOT, 'lib', 'core', 'navigation.cjs'));
+const correlation = require(path.join(REPO_ROOT, 'lib', 'core', 'correlation.cjs'));
+const correlationLabelIndex = require(path.join(REPO_ROOT, 'lib', 'core', 'correlation-label-index.cjs'));
+
+// The default primary label when only a name is known (a reference predating the
+// Task 3 correlation_id threading). Framework is the methodology label,
+// consistent with lib/brain/chain-recommender.cjs DEFAULT_PRIMARY_LABEL and
+// lib/core/navigation/spine-events.cjs, so a fallback-derived id joins the same
+// canonical the Brain side produces.
+const DEFAULT_PRIMARY_LABEL = 'Framework';
+
+// The memory_event event types whose reference payloads carry (or can derive) a
+// correlation_id. suggestion_surfaced is the Task-3-threaded reference; the set
+// is additive-safe (an event without a correlation_id and without a name is
+// simply skipped).
+const REFERENCE_EVENT_TYPES = Object.freeze(['suggestion_surfaced']);
+
+// Resolve a primary_label for a name from the LOCAL correlation_labels index
+// (when the caller supplies roomState.brainSections.correlation_labels) using
+// the same methodology-label-preferred heuristic as the Brain side; else default
+// to Framework. Pure; never throws.
+const LABEL_PREFERENCE = Object.freeze([
+  'Framework', 'Concept', 'Tool', 'Book', 'DictionaryTerm', 'Product', 'Person',
+]);
+function _labelRank(label) {
+  const i = LABEL_PREFERENCE.indexOf(label);
+  return i === -1 ? LABEL_PREFERENCE.length : i;
+}
+function _resolveLabelFromIndex(name, indexMap) {
+  const entries = (indexMap && Object.prototype.hasOwnProperty.call(indexMap, name))
+    ? indexMap[name] : null;
+  if (!Array.isArray(entries) || entries.length === 0) return DEFAULT_PRIMARY_LABEL;
+  let best = null;
+  for (const e of entries) {
+    if (!e || typeof e.primary_label !== 'string' || e.primary_label.length === 0) continue;
+    const cand = {
+      primary_label: e.primary_label,
+      edge_degree: Number.isFinite(Number(e.edge_degree)) ? Number(e.edge_degree) : 0,
+    };
+    if (best === null) { best = cand; continue; }
+    const rc = _labelRank(cand.primary_label);
+    const rb = _labelRank(best.primary_label);
+    if (rc < rb || (rc === rb && cand.edge_degree > best.edge_degree)) best = cand;
+  }
+  return best ? best.primary_label : DEFAULT_PRIMARY_LABEL;
+}
+
+function _readLabelIndex(roomState) {
+  if (!roomState || typeof roomState !== 'object') return {};
+  const sections = roomState.brainSections;
+  if (!sections || typeof sections !== 'object') return {};
+  const body = sections[correlationLabelIndex.LABEL_INDEX_SECTION_KEY];
+  if (typeof body !== 'string' || body.length === 0) return {};
+  try { return correlationLabelIndex.parseLabelIndex(body) || {}; }
+  catch (_e) { return {}; }
+}
+
+// For one memory_event reference, resolve its canonical tuple. Precedence:
+//   1. the reference already carries a correlation_id (Task 3 threading) -- use
+//      it as the aggregate key; name/label come from the reference when present.
+//   2. else derive from canonical_name (+ label resolved from the index or
+//      defaulted) via the SHARED chokepoint, so old un-threaded events still join
+//      consistently with the Brain side.
+// Returns null when the reference has neither an id nor a name (cannot join).
+function _referenceToCanonical(props, indexMap) {
+  if (!props || typeof props !== 'object') return null;
+  const name = (typeof props.canonical_name === 'string' && props.canonical_name.trim().length > 0)
+    ? props.canonical_name.trim() : null;
+  let label = (typeof props.primary_label === 'string' && props.primary_label.trim().length > 0)
+    ? props.primary_label.trim() : null;
+  if (name && !label) label = _resolveLabelFromIndex(name, indexMap);
+
+  if (typeof props.correlation_id === 'string' && props.correlation_id.length > 0) {
+    return {
+      correlation_id: props.correlation_id,
+      canonical_name: name,            // may be null for an id-only reference
+      primary_label: label,            // may be null for an id-only reference
+    };
+  }
+  if (name) {
+    return {
+      correlation_id: correlation.computeCorrelationId(name, label || DEFAULT_PRIMARY_LABEL),
+      canonical_name: name,
+      primary_label: label || DEFAULT_PRIMARY_LABEL,
+    };
+  }
+  return null;
+}
+
+/**
+ * recommendLocalCanonicalTargets({ roomDir, since?, roomState? } = {})
+ *   -> [ { correlation_id, canonical_name, primary_label }, ... ]
+ *
+ * Reads recent memory_event references via the navigation chokepoint, aggregates
+ * them BY correlation_id (recency-weighted reference count), and returns the
+ * canonical tuples ranked by aggregate weight. Tier-LOCAL: never requires Brain.
+ * Tier-0: returns [] when room.db is absent. Never throws, never returns null.
+ *
+ * @param {{ roomDir?: string, since?: number, roomState?: object }} [opts]
+ * @returns {Array<{correlation_id: string, canonical_name: string, primary_label: string}>}
+ */
+function recommendLocalCanonicalTargets(opts) {
+  const o = (opts && typeof opts === 'object') ? opts : {};
+  const roomDir = typeof o.roomDir === 'string' ? o.roomDir : null;
+  if (!roomDir) return [];
+  const since = Number.isFinite(o.since) ? o.since : 0;
+  const indexMap = _readLabelIndex(o.roomState);
+
+  const db = navigation.openRoomDbForCaller(roomDir);
+  if (!db) return []; // Tier 0: no room.db.
+  try {
+    // Aggregate map: correlation_id -> { tuple, weight }.
+    const agg = new Map();
+    const nowMs = Date.now();
+    for (const eventType of REFERENCE_EVENT_TYPES) {
+      let rows;
+      try {
+        rows = navigation.findRecentChanges(db, since, { eventType: eventType, limit: 500 });
+      } catch (_e) {
+        rows = [];
+      }
+      if (!Array.isArray(rows)) continue;
+      for (const r of rows) {
+        const tuple = _referenceToCanonical(r && r.properties, indexMap);
+        if (!tuple || typeof tuple.correlation_id !== 'string') continue;
+        // Recency weight: newer references weigh more. A simple monotonic decay
+        // over age in days keeps the rank stable and bounded; the exact curve is
+        // not load-bearing for the contract (one target per id, no fork).
+        const createdAt = Number.isFinite(r.createdAt) ? r.createdAt : nowMs;
+        const ageDays = Math.max(0, (nowMs - createdAt) / 86400000);
+        const weight = 1 / (1 + ageDays);
+        const prior = agg.get(tuple.correlation_id);
+        if (prior) {
+          prior.weight += weight;
+          // Backfill name/label if a later reference carries them and the prior
+          // was id-only (so the returned tuple is never half-null when any
+          // reference named the canonical).
+          if (!prior.tuple.canonical_name && tuple.canonical_name) prior.tuple.canonical_name = tuple.canonical_name;
+          if (!prior.tuple.primary_label && tuple.primary_label) prior.tuple.primary_label = tuple.primary_label;
+        } else {
+          agg.set(tuple.correlation_id, { tuple: Object.assign({}, tuple), weight: weight });
+        }
+      }
+    }
+
+    const ranked = Array.from(agg.values())
+      .sort(function (a, b) { return b.weight - a.weight; })
+      .map(function (e) {
+        return {
+          correlation_id: e.tuple.correlation_id,
+          canonical_name: e.tuple.canonical_name || null,
+          primary_label: e.tuple.primary_label || DEFAULT_PRIMARY_LABEL,
+        };
+      });
+    return ranked;
+  } catch (_e) {
+    return [];
+  } finally {
+    navigation.closeRoomDbForCaller(db);
+  }
+}
+
+// ---------- CLI (process.argv switch; mirrors suggest-next-command.cjs) ----------
+
+function _parseArgs(argv) {
+  const out = { roomDir: process.cwd(), since: 0, json: false };
+  for (let i = 2; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === '--room' && i + 1 < argv.length) { out.roomDir = argv[i + 1]; i += 1; continue; }
+    if (a === '--since' && i + 1 < argv.length) { out.since = Number(argv[i + 1]) || 0; i += 1; continue; }
+    if (a === '--json') { out.json = true; continue; }
+  }
+  return out;
+}
+
+function _main() {
+  const args = _parseArgs(process.argv);
+  let targets = [];
+  try {
+    targets = recommendLocalCanonicalTargets({ roomDir: args.roomDir, since: args.since });
+  } catch (_e) {
+    targets = [];
+  }
+  if (args.json) {
+    process.stdout.write(JSON.stringify(targets, null, 2) + '\n');
+  } else if (targets.length === 0) {
+    process.stdout.write('No local canonical targets (Tier 0 / no recent references).\n');
+  } else {
+    process.stdout.write('Local canonical targets (ranked):\n');
+    targets.forEach(function (t, i) {
+      process.stdout.write(
+        '  ' + (i + 1) + '. ' + (t.canonical_name || '(unnamed)') +
+        ' [' + t.primary_label + '] ' + t.correlation_id + '\n'
+      );
+    });
+  }
+  process.exit(0);
+}
+
+module.exports = {
+  recommendLocalCanonicalTargets: recommendLocalCanonicalTargets,
+  DEFAULT_PRIMARY_LABEL: DEFAULT_PRIMARY_LABEL,
+};
+
+if (require.main === module) {
+  _main();
+}

package/bin/mindrian-brain-mcp-client.cjs

@@ -0,0 +1,319 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * mindrian-brain MCP stdio shim (Phase 127, BRAIN-MCP-127-01)
+ *
+ * Local stdio MCP server that proxies the 6 canonical Brain tools to the
+ * remote Render-hosted Brain via lib/core/brain-client.cjs. Bundled with the
+ * plugin via .mcp.json so every new install gets mindrian-brain auto-loaded
+ * with zero user wiring beyond MINDRIAN_BRAIN_KEY in env / ~/.mindrian.env.
+ *
+ * Canon Part 7: ~85% reuse of brain-client.cjs -- this file is JUST a stdio
+ * transport wrapper. It contains zero network code; every Brain payload is
+ * constructed by brain-client.cjs (which inherits Phase 110 typed-packet
+ * enforcement on its typed-job entry; this shim proxies the 6
+ * tool-surface entry points which carry only generic methodology handles
+ * per Canon Part 8).
+ *
+ * Canon Part 8: adversarial scan against this file's active code MUST return
+ * zero matches for the network-surface token set (delegation property --
+ * every network call lives in brain-client.cjs).
+ *
+ * HARD RULE: no em-dashes anywhere in this file (hyphens only).
+ */
+
+const path = require('path');
+
+// -- Dependency self-heal (Option D, debug session
+// mcp-servers-cache-missing-node-modules). `claude plugin update` can land a
+// fresh plugin cache with NO node_modules; on the first post-update session
+// this MCP server may spawn before the SessionStart reconcile hook finishes its
+// npm install. mcp-dep-heal.cjs + npm-install-lock.cjs are pure node-built-in
+// modules (safe to require with node_modules absent). ensureDepsPresent runs a
+// guarded one-shot `npm install` if node_modules is missing/incomplete BEFORE
+// the SDK/zod requires below; requireWithHeal is the per-require backstop.
+const { ensureDepsPresent, requireWithHeal, beginConnectPathBudget, connectPathRemainingMs } = require('../lib/core/mcp-dep-heal.cjs');
+const healLog = (msg) => { try { process.stderr.write(msg + '\n'); } catch (e) { /* swallow */ } };
+// Phase 266 Plan 03 (MCPFIX-03): this process is answering a host that is
+// already counting down a ~30-second connect timeout, so the heal is bounded
+// to CONNECT_PATH_BUDGET_MS instead of the full hook-path budget.
+//
+// Phase 266 Plan 05 (MCPFIX-03 gap closure): arms ONE process-wide connect
+// deadline at the earliest possible moment. Every connectPath:true heal call
+// in this file (this ensureDepsPresent and the three requireWithHeal calls
+// below) now spends from this ONE shrinking budget. Before Phase 266 Plan 05
+// each of those four calls started its own fresh 15000ms clock, for a
+// measured worst case of 60296ms, double the host's ~30000ms connect timeout
+// the budget exists to respect.
+beginConnectPathBudget();
+const depHealOutcome = ensureDepsPresent({ log: healLog, connectPath: true });
+if (depHealOutcome && depHealOutcome.ok === false) {
+  healLog(
+    '[mindrian-brain] dependency heal did not complete inside the connect budget (' +
+      connectPathRemainingMs() + 'ms left); the requires below will propagate immediately rather than starting a new install'
+  );
+}
+
+const { McpServer } = requireWithHeal('@modelcontextprotocol/sdk/server/mcp.js', { log: healLog, connectPath: true });
+const { StdioServerTransport } = requireWithHeal('@modelcontextprotocol/sdk/server/stdio.js', { log: healLog, connectPath: true });
+const { z } = requireWithHeal('zod', { log: healLog, connectPath: true });
+
+const brainClient = require('../lib/core/brain-client.cjs');
+const { wrapDirective } = require('../lib/core/directive-envelope.cjs');
+const { tier0Response: chokepointTier0, refusalResponse } = require('../lib/core/refusal-messaging.cjs');
+
+const pluginRoot = path.resolve(__dirname, '..');
+const pluginMeta = require('../.claude-plugin/plugin.json');
+const version = pluginMeta.version;
+
+// Tier-0 sentinel -- structured DIRECTOR_NOT_AVAILABLE response. Returned by
+// the 5 tools that surface raw Brain payloads (query/schema/search/stats/write).
+// brain_ask wraps Tier-0 differently (in a DirectiveEnvelope) so Larry's
+// surface reads a uniform shape regardless of tier.
+//
+// Phase 127-02 BRAIN-MCP-127-09 refactor: this is now a one-line passthrough
+// to the single chokepoint at lib/core/refusal-messaging.cjs (renamed from
+// tier0-messaging.cjs in Phase 252-01, SWEEP-01). The local symbol
+// is preserved so existing tests + tool closures keep their reference.
+// Delegation property: zero duplicate sentinel-shape definition lives here.
+function tier0Response(commandContext) {
+  return chokepointTier0(commandContext);
+}
+
+function asContent(obj) {
+  return { content: [{ type: 'text', text: JSON.stringify(obj) }] };
+}
+
+// Phase 257 (D-03/D-05, LOCUS-01, Task 2) -- maps a raw brainClient result to
+// a typed refusal on the two non-success shapes a raw-passthrough tool can
+// see: `result == null` (the pre-existing transport-failure contract) and the
+// Part 8 sentinel object `{error:'egress_blocked',...}` (a constitutional
+// block, distinct from an outage). Zero shape definition lives here (Part 7)
+// -- this helper only chooses WHICH chokepoint call to make, mirroring
+// tier0Response's one-line delegation immediately above. Any other result
+// (success payload, or a sentinel with a different .error) passes through
+// unchanged, by identity.
+function honestRefusal(result, toolName) {
+  if (result == null) return refusalResponse('unreachable', { tool: toolName });
+  if (result && typeof result === 'object' && result.error === 'egress_blocked') {
+    return refusalResponse('egress_blocked', { tool: toolName, egress_class: result.egress_class });
+  }
+  return result;
+}
+
+// Phase 250-04 (HONEST-03, SEED-011 Option A): every gate below awaits
+// brainClient.ensureAvailable() instead of calling the synchronous
+// isAvailable(). This IS the "first Brain consult" seam -- Larry's native
+// MCP tool calls in Claude Code CLI chat route through THIS shim (Desktop
+// and Cowork reach the remote pws-brain-mcp MCP server directly and are
+// unaffected), so without this change silent registration would only ever
+// fire for direct brain-client.cjs consumers (e.g. /mos: command scripts),
+// never for the primary chat-driven consult path. ensureAvailable() is a
+// pure passthrough to isAvailable() when a key already resolves (fast,
+// no network); it only awaits a mint attempt when the ladder is empty.
+const server = new McpServer({ name: 'mindrian-brain', version: version });
+
+// ---------------------------------------------------------------------------
+// Phase 257 Plan 08 (D-09, LOCUS-07) -- the undeclared-key smuggling gap.
+// Provenance: the Theo consult's GUARD-01
+// (/home/jsagi/Theo/src/mcp/register-content-tool.ts, a different repo, read
+// only) measured that a plain zod raw-shape input schema silently ACCEPTS an
+// undeclared key and drops it before the handler ever sees it -- a call
+// carrying {question:'x', roomSecret:'LEAK'} succeeds, the handler receives
+// only {question:'x'}, and nothing logs, rejects, or traces the extra field.
+// A Part 8 violation the content classifier structurally cannot see, because
+// classify() only ever inspects keys the schema declared.
+//
+// MEASURED THIS PHASE, on this repo's own installed pins (see
+// tests/test-257-strict-input-shapes.cjs Arms Z1-Z3): the same gap exists
+// here. A strict zod object shape closes it: safeParse rejects with an
+// unrecognized_keys issue instead of silently dropping the field.
+//
+// MEASURED MECHANISM (Arm Z4, do not "simplify" this back to the OLD
+// positional registration form). The SDK's positional tool-registration
+// overload (name, description, schema, callback) detects its schema
+// argument with isZodRawShapeCompat, which returns FALSE for a ZodObject
+// instance (a ZodObject is a schema, not a raw shape) -- so passing a strict
+// zod object positionally falls into the annotations branch and THROWS
+// ("expected a Zod schema or ToolAnnotations, but received an unrecognized
+// object"). The config-object registration overload used below (name,
+// {description, inputSchema}, callback) routes inputSchema through
+// getZodSchemaObject, which returns a ZodObject unchanged -- this is the
+// only form that preserves strictness on the pinned SDK, which is why every
+// registration in this file was migrated to it.
+// ---------------------------------------------------------------------------
+
+// ---------------------------------------------------------------------------
+// Phase 339, 2026-09-03 (D-13, PREP half). The plugin is between two Brain
+// backends for the duration of the Theo cutover soak: the tool descriptions
+// below no longer name a specific graph engine, embedding model, or auth
+// tier, because any such claim is wrong on one side of the flip. Backend-
+// agnostic wording is true on BOTH sides at every moment of the soak.
+//
+// What these edits deliberately do NOT change: tool NAMES (verify-release
+// gate 19 checks these against every hooks.json Brain matcher and every
+// agent allowed-tools entry -- renaming a tool would break that gate, a
+// description edit cannot); and connector declarations (those live in
+// markdown frontmatter, not in this CJS file, which is why neither
+// build-connector-registry.cjs nor check-shape-declaration.cjs walks bin/).
+// ---------------------------------------------------------------------------
+
+// -- brain_ask: highest-level entry; wraps response in DirectiveEnvelope.
+server.registerTool(
+  'brain_ask',
+  {
+    description: 'Ask the remote teaching graph a natural-language methodology question. Routing happens server-side. Returns a DirectiveEnvelope carrying the directive content; the envelope degrades harmlessly to an empty signals set when the upstream response carries none. Reach for this first for an open methodology question; use brain_search when you already know the topic and want matching nodes directly.',
+    inputSchema: z.strictObject({ question: z.string().describe('A methodology question (generic framework handles only -- never user artifacts or personal data per Canon Part 8).') }),
+  },
+  async ({ question }) => {
+    if (!(await brainClient.ensureAvailable())) {
+      // Keyless path unchanged (127-02 sentinel, byte-locked).
+      return asContent(wrapDirective(null, { brain_unreachable: true, command_context: 'brain_ask' }));
+    }
+    const raw = await brainClient.ask(question);
+    if (raw == null) {
+      // Phase 250-01 (HONEST-01, site #9 conflation fix): a VALID-key
+      // transport failure is honestly distinct from the keyless case above --
+      // wrap refusalResponse('unreachable', ...) in the SAME wrapDirective
+      // envelope mechanism via its typed-directive pass-through, so the
+      // envelope carries kind='unreachable' and an honest reason instead of
+      // silently reusing the keyless tier0 sentinel shape.
+      const refusal = refusalResponse('unreachable', { tool: 'brain_ask' });
+      return asContent(wrapDirective({
+        directive: { guided: { questions: [], framework: null, stage: 'tier_0_' + refusal.kind } },
+        next_gate: { sub_shape: 'F.1', options: refusal.next_moves.slice() },
+        refusal: refusal,
+      }, { brain_unreachable: true, command_context: 'brain_ask' }));
+    }
+    // Phase 257 (D-03, LOCUS-01, G1) -- THE MEASURED DEFECT. brainClient.ask()
+    // can also resolve to the Part 8 sentinel OBJECT
+    // {error:'egress_blocked', tool:'brain_ask', egress_class:...} -- which is
+    // NOT null, so before this branch existed control fell all the way through
+    // to `wrapDirective(raw, signals)` below and rendered a well-formed EMPTY
+    // DirectiveEnvelope with no trace of the block: the words 'egress_blocked',
+    // 'error' and 'content_set' appeared nowhere in what the model received.
+    // The sentinel is deliberately an OBJECT rather than null
+    // (lib/core/brain-client.cjs:576-580) precisely so a constitutional
+    // refusal can never be confused with a transport outage -- this branch is
+    // the honest-refusal idiom for that object, cloned from the `raw == null`
+    // branch immediately above. CRITICAL: signals must NOT carry the
+    // transport-outage flag the branch above sets -- that would re-create the
+    // exact refusal-versus-outage conflation this branch exists to fix, one
+    // layer up in the signals plane. Only `tool` and `egress_class` cross
+    // into refusalResponse; the question text is never echoed.
+    if (raw && typeof raw === 'object' && raw.error === 'egress_blocked') {
+      const refusal = refusalResponse('egress_blocked', { tool: 'brain_ask', egress_class: raw.egress_class });
+      return asContent(wrapDirective({
+        directive: { guided: { questions: [], framework: null, stage: 'tier_0_' + refusal.kind } },
+        next_gate: { sub_shape: 'F.1', options: refusal.next_moves.slice() },
+        refusal: refusal,
+      }, { command_context: 'brain_ask' }));
+    }
+    const signals = (raw && typeof raw === 'object' && raw.mode_signals) ? raw.mode_signals : {};
+    return asContent(wrapDirective(raw, signals));
+  }
+);
+
+// -- brain_query: raw Cypher (generic methodology handles only).
+// NOTE: strictness applies at the TOP level only, to reject undeclared
+// sibling keys of cypher/params. `params` itself stays z.record(z.any()) --
+// it is a Cypher binding map whose keys are legitimately arbitrary. Do NOT
+// make params strict internally; that would break legitimate bindings.
+server.registerTool(
+  'brain_query',
+  {
+    description: 'Cypher query against the Brain teaching graph. Generic framework handles only (Canon Part 8). Returns { records: [...] } on success.',
+    inputSchema: z.strictObject({
+      cypher: z.string().describe('Cypher query string.'),
+      params: z.record(z.any()).optional().describe('Optional binding map -- generic handles only.'),
+    }),
+  },
+  async ({ cypher, params }) => {
+    if (!(await brainClient.ensureAvailable())) return asContent(tier0Response('brain_query'));
+    const r = await brainClient.query(cypher, params);
+    // Phase 257 (D-05, G2, ACCEPTED GAP): query()'s null-return contract is
+    // NOT changed by this phase. query() returns null on a Part 8 block at
+    // lib/core/brain-client.cjs:884, BEFORE callTool() ever runs, so this
+    // call site can never see the egress_blocked sentinel -- honestRefusal()
+    // is a deliberate no-op on the block path here, always taking the
+    // `result == null` -> 'unreachable' branch. This conflation (a block
+    // reported as an outage) is a KNOWN and ACCEPTED gap for this phase,
+    // pinned by roughly 82 degradation tests keyed on query()'s null
+    // contract and by Plan 07's own invariant test so it cannot drift
+    // silently. See docs/257-NOTE-part8-enforcement-locus-rulings.md section 3.
+    return asContent(honestRefusal(r, 'brain_query'));
+  }
+);
+
+// -- brain_schema: cached 30 min in brain-client; passthrough here.
+server.registerTool(
+  'brain_schema',
+  {
+    description: 'Reports the teaching graph schema: labels, relationship types and property keys from the remote teaching graph. Memoized for 30 minutes.',
+    inputSchema: z.strictObject({}),
+  },
+  async () => {
+    if (!(await brainClient.ensureAvailable())) return asContent(tier0Response('brain_schema'));
+    const r = await brainClient.schema();
+    return asContent(honestRefusal(r, 'brain_schema'));
+  }
+);
+
+// -- brain_search: semantic via locally-embedded e5 vectors, with a graph
+// fulltext fallback (smartSearch handles the fallback branch).
+server.registerTool(
+  'brain_search',
+  {
+    description: 'Semantic search over the teaching graph.',
+    inputSchema: z.strictObject({
+      query: z.string().describe('Search query (generic methodology language -- Canon Part 8).'),
+      namespace: z.string().optional(),
+      topK: z.number().int().min(1).max(50).optional(),
+    }),
+  },
+  async ({ query, namespace, topK }) => {
+    if (!(await brainClient.ensureAvailable())) return asContent(tier0Response('brain_search'));
+    const r = await brainClient.smartSearch(query, { namespace: namespace, topK: topK });
+    return asContent(honestRefusal(r, 'brain_search'));
+  }
+);
+
+// -- brain_stats: operational stats passthrough.
+server.registerTool(
+  'brain_stats',
+  {
+    description: 'Reports teaching-graph size and coverage counts, plus last-update markers, from the remote teaching graph.',
+    inputSchema: z.strictObject({}),
+  },
+  async () => {
+    if (!(await brainClient.ensureAvailable())) return asContent(tier0Response('brain_stats'));
+    const r = await brainClient.stats();
+    return asContent(honestRefusal(r, 'brain_stats'));
+  }
+);
+
+// -- brain_write: admin-tier; not user-surfaced but proxied for parity.
+server.registerTool(
+  'brain_write',
+  {
+    description: 'Write Cypher to the Brain. The remote may refuse writes unconditionally regardless of key. Generic methodology framework writes only (Canon Part 8).',
+    inputSchema: z.strictObject({ cypher: z.string().describe('Cypher write query (generic methodology only).') }),
+  },
+  async ({ cypher }) => {
+    if (!(await brainClient.ensureAvailable())) return asContent(tier0Response('brain_write'));
+    const r = await brainClient.write(cypher);
+    return asContent(honestRefusal(r, 'brain_write'));
+  }
+);
+
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  process.stderr.write('[mindrian-brain] MCP server v' + version + ' started (stdio)\n');
+}
+
+main().catch((err) => {
+  process.stderr.write('[mindrian-brain] Fatal: ' + (err && err.message ? err.message : String(err)) + '\n');
+  process.exit(1);
+});