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

package/lib/core/brain-client.cjs

@@ -1110,6 +1110,244 @@ async function schema() {
   return result;
 }
 
+/**
+ * _inferRungFromQuestion(question) -> one of the four Theo rung ids.
+ *
+ * Theo's `classify_problem_type` tool takes NO parameters (the caller
+ * classifies), and there is no free-text rung classifier anywhere in this
+ * repo (`brain-derivation.cjs::classifyProblemType` scores MINTO triples,
+ * not text). This helper fills that local gap. It is PURE and LOCAL: it
+ * never sends the question anywhere, which is the whole reason it exists
+ * (Canon Part 8 -- the question is user data and stays local).
+ *
+ * Precedence is FIXED and load-bearing (do not reorder): Wicked is the
+ * orthogonal stakeholder-conflict axis and wins outright; UnDefined's
+ * markers are the least ambiguous of the remaining three; WellDefined's
+ * markers are next; IllDefined's markers are the broadest and are also the
+ * default, so they run last and cost nothing when they lose.
+ *
+ * Multi-word markers match as a substring; single-word markers match on a
+ * word boundary so `which` does not fire inside `whichever`. Non-string or
+ * empty input returns `'IllDefined'` and never throws.
+ *
+ * @param {*} question
+ * @returns {'Wicked'|'UnDefined'|'WellDefined'|'IllDefined'}
+ */
+const _RUNG_MARKERS = [
+  { rung: 'Wicked', markers: ['stakeholder', 'disagree', 'values', 'political'] },
+  { rung: 'UnDefined', markers: ['future of', 'no boundary', 'unbounded'] },
+  { rung: 'WellDefined', markers: ['measure', 'spec', 'test', 'kpi', 'how do we'] },
+  { rung: 'IllDefined', markers: ['next big thing', 'which', 'should we', 'opportunity'] },
+];
+
+function _matchesRungMarker(text, marker) {
+  if (marker.indexOf(' ') !== -1) return text.indexOf(marker) !== -1;
+  return new RegExp('\\b' + marker + '\\b').test(text);
+}
+
+function _inferRungFromQuestion(question) {
+  if (typeof question !== 'string' || !question.trim()) return 'IllDefined';
+  const lc = question.trim().toLowerCase();
+  for (let i = 0; i < _RUNG_MARKERS.length; i++) {
+    const entry = _RUNG_MARKERS[i];
+    for (let j = 0; j < entry.markers.length; j++) {
+      if (_matchesRungMarker(lc, entry.markers[j])) return entry.rung;
+    }
+  }
+  return 'IllDefined';
+}
+
+/**
+ * _composeTheoAsk(payload, question, deps) -> composed envelope payload.
+ *
+ * Composes `directive`, `next_gate` and `grounding` onto a Theo
+ * `answer_mode: 'structured_rows'` payload so downstream consumers
+ * (`wrapDirective`, `brainRoute`, `rs-chain-feeder.cjs`) get a real
+ * framework and chain instead of an empty scaffold. `deps` is the
+ * injectable wire seam (`{ recommendChain, query }`) the offline test suite
+ * drives; it defaults to this module's own wrappers so production behavior
+ * needs no injection.
+ *
+ * Runs entirely inside one outer try/catch and NEVER throws: on any failure
+ * it still returns the same object shape with `options: []` and
+ * `chain_status: 'unreachable'`, so a rows response with a failed chain
+ * still returns `grounding`.
+ *
+ * Canon Part 8: the only two extra wire calls this makes carry a closed
+ * rung enum (`recommendChain`) and framework names Theo itself just
+ * returned (`query`, label-anchored on `(f:Framework)`, never
+ * relationship-first -- Theo's read allow-list refuses
+ * `DirectedRelationshipTypeScan`). `query_terms` (the question's own words)
+ * is the ONLY key removed from the payload, because it is the question
+ * echoed back; the row projection is by the four NAMED keys
+ * (chapterId/section/score/snippet), never a blind row copy, for the same
+ * reason plus shape stability.
+ *
+ * @param {object} payload - the raw Theo structured_rows payload
+ * @param {string} question - the original question (local only, never sent)
+ * @param {{recommendChain?: Function, query?: Function}} [deps]
+ * @returns {Promise<object>}
+ */
+function _projectGroundingRows(rows) {
+  return Array.isArray(rows)
+    ? rows
+        .filter((r) => r && typeof r === 'object')
+        .map((r) => ({ chapterId: r.chapterId, section: r.section, score: r.score, snippet: r.snippet }))
+    : [];
+}
+
+async function _composeTheoAsk(payload, question, deps) {
+  deps = deps || {};
+  const recommend = deps.recommendChain || recommendChain;
+  const runQuery = deps.query || query;
+
+  try {
+    const rung = _inferRungFromQuestion(question);
+
+    let chainRes = null;
+    let chainStatus;
+    try {
+      chainRes = await recommend(rung, 4);
+      if (chainRes == null || chainRes.error || !Array.isArray(chainRes.chain)) {
+        chainStatus = 'unreachable';
+      } else if (chainRes.chain.length === 0) {
+        chainStatus = 'empty';
+      } else {
+        chainStatus = 'ok';
+      }
+    } catch (_e) {
+      chainStatus = 'unreachable';
+    }
+    const steps = chainStatus === 'ok' ? chainRes.chain : [];
+
+    // COMMANDS: exactly one runQuery call, only when there are steps, in its
+    // own try/catch (on any failure every option gets commands: []).
+    // Label-anchored and never relationship-first: Theo's read allow-list
+    // refuses a template that starts from [:USES_FRAMEWORK].
+    const commandsByFramework = new Map();
+    if (steps.length > 0) {
+      try {
+        const names = steps
+          .map((s) => s && s.framework)
+          .filter((n) => typeof n === 'string');
+        const result = await runQuery(
+          'MATCH (f:Framework) WHERE f.name IN $names OPTIONAL MATCH (c:MindrianCommand)-[:USES_FRAMEWORK]->(f) RETURN f.name AS framework, collect(DISTINCT c.name) AS commands',
+          { names: names }
+        );
+        const records = (result && Array.isArray(result.records)) ? result.records : [];
+        for (const rec of records) {
+          if (!rec || typeof rec.framework !== 'string') continue;
+          const slugs = Array.isArray(rec.commands)
+            ? rec.commands
+                .filter((c) => typeof c === 'string' && c.length > 0)
+                .map((c) => c.replace(/^\/mos:/, ''))
+            : [];
+          commandsByFramework.set(rec.framework, slugs);
+        }
+      } catch (_e) {
+        // any failure here -> every option gets commands: [] below (Map stays empty)
+      }
+    }
+
+    // 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, 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: (sortedOptions[0] && sortedOptions[0].framework) || null, stage: rung },
+    };
+    out.next_gate = { sub_shape: 'F.1', options: sortedOptions };
+    out.grounding = {
+      source: 'theo',
+      answer_mode: payload.answer_mode,
+      rows: _projectGroundingRows(payload.rows),
+      problem_type: rung,
+      problem_type_source: 'heuristic',
+      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) {
+    const rung = _inferRungFromQuestion(question);
+    const out = Object.assign({}, payload);
+    delete out.query_terms;
+    out.directive = { guided: { questions: [], framework: null, stage: rung } };
+    out.next_gate = { sub_shape: 'F.1', options: [] };
+    out.grounding = {
+      source: 'theo',
+      answer_mode: payload.answer_mode,
+      rows: _projectGroundingRows(payload.rows),
+      problem_type: rung,
+      problem_type_source: 'heuristic',
+      chain_coverage: null,
+      chain_status: 'unreachable',
+      confidence_source: 'theo_degree_normalized',
+      option_order: 'command_bearing_first',
+    };
+    return out;
+  }
+}
+
 /**
  * Natural-language methodology question against the Brain (wraps brain_ask).
  *
@@ -1119,9 +1357,14 @@ async function schema() {
  * question. Canon Part 8: the question string carries only generic methodology
  * language -- never user artifacts, meeting text, or personal identifiers.
  *
- * Returns the parsed brain_ask payload ({ question, keyword, source, count,
- * results: [...] }) on success; a { text: 'Error: ...' } / { error: ... }
- * passthrough on a server-side error; null when the Brain is unreachable or no
+ * Two response shapes on success:
+ *   - INCUMBENT: carries `directive` already -- returned BYTE-UNCHANGED, the
+ *     same object reference, no copy.
+ *   - THEO structured_rows: `{ answer_mode: 'structured_rows', rows: [...] }`
+ *     with no `directive` -- composed through `_composeTheoAsk` into a full
+ *     envelope payload (`directive`, `next_gate`, `grounding` added).
+ * A `{ text: 'Error: ...' } / { error: ... }` sentinel passes through
+ * UNCHANGED on a server-side error; null when the Brain is unreachable or no
  * API key is configured (graceful degradation -- mirrors query()).
  *
  * @param {string} question
@@ -1129,7 +1372,15 @@ async function schema() {
  */
 async function ask(question) {
   if (typeof question !== 'string' || !question.trim()) return null;
-  return callTool('brain_ask', { question: question });
+  const raw = await callTool('brain_ask', { question: question });
+  if (raw == null) return raw; // transport-null contract, byte-locked
+  if (typeof raw !== 'object' || Array.isArray(raw)) return raw;
+  if (raw.error) return raw; // egress_blocked / tier_denied / rate_limited / invalid_key
+  if (raw.directive) return raw; // incumbent proof -- same object reference
+  if (raw.answer_mode === 'structured_rows' && Array.isArray(raw.rows)) {
+    return _composeTheoAsk(raw, question);
+  }
+  return raw;
 }
 
 /**
@@ -1162,24 +1413,64 @@ async function ask(question) {
  * @param {object} [params]  - generic-handles-only params object
  * @returns {Promise<{op: string, source?: string, count: number, rows: Array, degraded?: boolean}>}
  */
+/**
+ * _normalizeAskOpResult(result, operation) -- the askOp() shape recognizer,
+ * extracted so tests can drive it directly with zero network. Copies the
+ * dual-shape recognizer STRUCTURE from
+ * lib/core/enrichment-queue.cjs::captureReadinessMiss: one entry point, arms
+ * keyed on payload SHAPE never on key presence alone.
+ *
+ * Theo op answers carry `coverage`, never `count`, so a `count`-keyed
+ * recognizer alone reads a live three-row answer as a degraded zero. Arms,
+ * in order:
+ *   1. INCUMBENT: `count` is a number and `rows` is an array -- the exact
+ *      object askOp built before this task. MUST run first so an incumbent
+ *      payload can never take arm 2.
+ *   2. THEO: `rows` is an array (no numeric `count` required) -- reports
+ *      `coverage.matched` as `count` when it is a finite number, else
+ *      `rows.length`.
+ *   3. Everything else (null, an `{error:...}` sentinel, a `{text:...}`
+ *      passthrough, a non-array `rows`) -- the existing degraded sentinel.
+ * Degrade ONLY when `rows` is not an array.
+ *
+ * @param {*} result
+ * @param {string} operation
+ * @returns {{op: string, source?: string, count: number, rows: Array, coverage?: object, degraded?: boolean}}
+ */
+function _normalizeAskOpResult(result, operation) {
+  if (result && typeof result === 'object'
+      && typeof result.count === 'number' && Array.isArray(result.rows)) {
+    return {
+      op: result.op || operation,
+      source: result.source,
+      count: result.count,
+      rows: result.rows,
+      ...(result.degraded ? { degraded: true } : {}),
+    };
+  }
+  if (result && typeof result === 'object' && Array.isArray(result.rows)) {
+    const coverage = result.coverage;
+    const matched = (coverage && typeof coverage === 'object' && Number.isFinite(coverage.matched))
+      ? coverage.matched
+      : result.rows.length;
+    const out = {
+      op: result.op || operation,
+      source: 'theo',
+      count: matched,
+      rows: result.rows,
+    };
+    if (coverage && typeof coverage === 'object') out.coverage = coverage;
+    return out;
+  }
+  return { op: operation, count: 0, rows: [], degraded: true };
+}
+
 async function askOp(operation, params = {}) {
   try {
-    const result = await callTool('brain_ask', { op: operation, params: params || {} });
-    // callTool already parses the JSON text payload of the MCP content item,
-    // so a well-formed curated-op response arrives as the payload object.
-    if (result && typeof result === 'object'
-        && typeof result.count === 'number' && Array.isArray(result.rows)) {
-      return {
-        op: result.op || operation,
-        source: result.source,
-        count: result.count,
-        rows: result.rows,
-        ...(result.degraded ? { degraded: true } : {}),
-      };
-    }
-    // Unreachable Brain (null), an error/text passthrough, or any unexpected
-    // shape -> graceful degraded sentinel.
-    return { op: operation, count: 0, rows: [], degraded: true };
+    return _normalizeAskOpResult(
+      await callTool('brain_ask', { op: operation, params: params || {} }),
+      operation
+    );
   } catch (_err) {
     return { op: operation, count: 0, rows: [], degraded: true };
   }
@@ -2300,6 +2591,10 @@ module.exports = {
   smartSearch,
   ask,
   askOp,
+  // Quick 260910-hni: the pure local rung heuristic ask()/_composeTheoAsk
+  // uses to classify a question before the one recommend_chain wire call.
+  // A NAMED export per the locked design, not a _test-only member.
+  _inferRungFromQuestion,
   schema,
   stats,
   getBrainUrl,
@@ -2361,5 +2656,10 @@ module.exports = {
     // so the exact D-01/D-02 schedule is unit-tested with zero sleeps.
     _parseRetryAfterMs,
     _rateLimitWaitMs,
+    // Quick 260910-hni test surface: the composer's injectable deps seam
+    // and the widened askOp recognizer, both offline-drivable with zero
+    // network (see tests/test-339-theo-ask-compose.cjs).
+    _composeTheoAsk,
+    _normalizeAskOpResult,
   },
 };

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 };

package/lib/core/directive-envelope.cjs

@@ -159,6 +159,15 @@ function _copyIfPlainObject(value) {
  * `lib/mcp/no-instructions.test.cjs` exists to prevent). When neither field
  * is present, the returned object keeps the exact same seven keys in the
  * exact same insertion order it had before this change.
+ *
+ * Quick 260910-hni adds `grounding` as a THIRD named additive field, same
+ * shape guard and same reason: an untyped top-level copy would let
+ * arbitrary Brain-returned keys reach the model, exactly the leakage class
+ * `lib/mcp/no-instructions.test.cjs` exists to prevent. `_copyIfPlainObject`
+ * is a SHALLOW copy, so `grounding.rows` stays the same array reference,
+ * exactly as `refusal.next_moves` already behaves. Absence of `grounding`
+ * leaves the seven keys and their insertion order untouched
+ * (`tests/test-257-envelope-passthrough.cjs` Arm 3 pins this).
  * @param {object|null} brainResponse
  * @param {object} signals
  * @returns {object} DirectiveEnvelope per CAPABILITY-MAP spec.
@@ -206,6 +215,10 @@ function wrapDirective(brainResponse, signals) {
   if (refusal !== null) {
     envelope.refusal = refusal;
   }
+  const grounding = _copyIfPlainObject(brainResponse.grounding);
+  if (grounding !== null) {
+    envelope.grounding = grounding;
+  }
 
   return envelope;
 }