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

package/lib/mcp/tools/gate.cjs

@@ -0,0 +1,392 @@
+'use strict';
+// Phase 198-05 (SPEC-4, Task 2) -- gate_render + gate_answer MCP tools.
+//
+// gate_render composes the Mindrian gate superset card via the renderer
+// ladder (lib/mcp/gate-render.cjs) for the CALLING client's own capabilities
+// (real elicitation capability negotiated at MCP initialize time; a
+// recognized Claude host surface falls to the thin-adapter AskUserQuestion
+// rung; everything else gets the headless structured-text rung -- RESEARCH
+// A2 re-check: Claude Code/Desktop still do not declare the elicitation
+// client capability, issue #2799 still open as of this build; the ladder
+// keeps all three rungs regardless).
+//
+// gate_answer accepts the canonical { gate_id, chosen, verdict } payload and,
+// on an approve verdict, RATIFIES the decision by routing the write through
+// lib/core/navigation.cjs (Part 9, T-198-04) -- this file never opens the
+// graph store directly.
+//
+// T-198-10 (spoofing): gate_answer only ratifies a gate_id THIS server
+// process actually minted via gate_render -- a small in-memory, single-use
+// live-gate ledger (mint on gate_render, consume on gate_answer) rejects a
+// forged or replayed gate_id before any write happens.
+//
+// Canon Part 7: reuses lib/mcp/gate-render.cjs (Task 1) for all rendering /
+// answer normalization; this file is the tool surface + ratification only.
+// Canon Part 8: zero Brain/network tokens.
+// Canon Part 11 (born-wired): register(server, ctx) + connectors export,
+// same disjoint-file module contract as lib/mcp/tools/room.cjs and
+// lib/mcp/tools/graph.cjs (198-04) -- never requires those modules or
+// lib/mcp/tool-router.cjs at module-load time.
+
+const { z } = require('zod');
+
+const gateRender = require('../gate-render.cjs');
+const gateLedger = require('../gate-ledger.cjs');
+const navigation = require('../../core/navigation.cjs');
+const { resolveEffectiveSessionId } = require('../../core/session-binding.cjs');
+const { resolveSessionRoomDir } = require('../session-room.cjs');
+
+function textResponse(payload, isError) {
+  const result = { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  if (isError) result.isError = true;
+  return result;
+}
+
+// -----------------------------------------------------------------------
+// T-198-10 spoofing mitigation, now on the SHARED ledger: gate_answer only
+// ratifies a gate_id THIS process minted via gate_render, single-use, TTL-
+// bounded. Phase 238-02 built lib/mcp/gate-ledger.cjs as the ONE ledger both
+// this file and chain.cjs mint into and consume from -- until 238-03, this
+// file kept its own private _liveGates Map, minted separately from chain.
+// cjs's own _resumeLedger under the SAME T-198-10 doctrine, and the two were
+// never joined: a gate_id minted by a chain halt could not be consumed by a
+// gate answer (238-RESEARCH.md Finding 1). This block is the gate-side half
+// of joining them; 238-04 re-points chain.cjs onto the same module.
+//
+// gateLedger.cjs is NOT a lib/mcp/tools/*.cjs module (it lives one directory
+// up), so requiring it here mirrors this file's own pre-existing require of
+// ../gate-render.cjs -- not a tools/tools collision under the disjoint-file
+// contract (lib/mcp/register-core-tools.cjs).
+//
+// _mintLiveGate / _consumeLiveGate stay as real named functions so the
+// existing tests/test-198-*.cjs files (which reach through _internal) keep
+// resolving; they are now thin wrappers over gateLedger.mintGate/consumeGate.
+function _mintLiveGate(gateId, card, sessionId) {
+  gateLedger.mintGate(gateId, {
+    card: card,
+    sessionId: sessionId,
+    kind: (card && typeof card.kind === 'string' && card.kind.length > 0) ? card.kind : 'general',
+  });
+}
+
+function _consumeLiveGate(gateId, sessionId) {
+  return gateLedger.consumeGate(gateId, sessionId);
+}
+
+/**
+ * detectClientCapabilities -- the ladder's capability read. Real elicitation
+ * capability comes from the MCP initialize handshake (server.server.
+ * getClientCapabilities()). Claude Code/Desktop/Cowork do not declare it
+ * (RESEARCH A2, issue #2799 open) -- they are identified by the D-07
+ * MINDRIAN_MCP_FIRST surface list on ctx.surface instead. Any other caller
+ * (VS Code, MCP Inspector, an unrecognized surface) falls to the headless
+ * text rung.
+ */
+const CLAUDE_HOST_SURFACES = ['cli', 'desktop', 'cowork'];
+
+function detectClientCapabilities(server, ctx) {
+  let elicitation = false;
+  try {
+    const caps = (server && server.server && typeof server.server.getClientCapabilities === 'function')
+      ? server.server.getClientCapabilities()
+      : null;
+    elicitation = !!(caps && caps.elicitation);
+  } catch (_e) {
+    elicitation = false;
+  }
+  const surface = (ctx && typeof ctx.surface === 'string') ? ctx.surface : null;
+  const claudeCode = !elicitation && surface !== null && CLAUDE_HOST_SURFACES.indexOf(surface) !== -1;
+  return { elicitation: elicitation, claudeCode: claudeCode };
+}
+
+const gateOptionSchema = z.object({
+  id: z.string().min(1).optional(),
+  label: z.string().min(1),
+  description: z.string().optional(),
+  rank: z.number().optional(),
+  preview: z.string().optional(),
+});
+
+function register(server, ctx) {
+  server.tool(
+    'gate_render',
+    'Render the Mindrian gate superset card (options + per-option descriptions + ranks + previews + single/multi-select) via the capability-detected 3-rung renderer ladder: MCP elicitation, Claude Code AskUserQuestion thin adapter, or headless structured text. Returns a gate_id minted into this server process\'s in-memory ledger, which gate_answer must reference to ratify; nothing is persisted and the id does not survive a restart.',
+    {
+      gate_id: z.string().min(1).optional(),
+      header: z.string().optional(),
+      kind: z.string().optional()
+        .describe("e.g. 'binding' for the D-04 once-per-session-on-ambiguity F.8 card; defaults to 'general'."),
+      ambiguous: z.boolean().optional()
+        .describe("Only relevant to kind:'binding' -- an unambiguous context never fires the card."),
+      select_mode: z.enum(['single', 'multi']).optional(),
+      options: z.array(gateOptionSchema).min(1),
+      subject_node_id: z.string().min(1).optional()
+        .describe('Opaque LOCAL room-graph node id, provenance only. Nothing consumes this yet -- carried on the minted gate card for a later write half. Canon Part 8: must never be a Brain identifier or room content.'),
+      evidence_node_ids: z.array(z.string().min(1)).optional()
+        .describe('Opaque LOCAL room-graph node ids, provenance only. Nothing consumes this yet -- carried on the minted gate card for a later write half. Canon Part 8: must never be Brain identifiers or room content.'),
+    },
+    async ({ gate_id, header, kind, ambiguous, select_mode, options, subject_node_id, evidence_node_ids }, extra) => {
+      const sessionId = resolveEffectiveSessionId(undefined, extra);
+      const capabilities = detectClientCapabilities(server, ctx);
+      const card = { gate_id: gate_id, header: header, kind: kind, ambiguous: ambiguous, selectMode: select_mode, options: options, subject_node_id: subject_node_id, evidence_node_ids: evidence_node_ids };
+      const renderCtx = { capabilities: capabilities, sessionId: sessionId };
+      if (capabilities.elicitation && server && server.server && typeof server.server.elicitInput === 'function') {
+        renderCtx.elicitInput = function (params) { return server.server.elicitInput(params); };
+      }
+
+      let result;
+      try {
+        result = await gateRender.renderGate(card, renderCtx);
+      } catch (e) {
+        return textResponse({ ok: false, reason: 'render_failed', detail: String((e && e.message) || e) }, true);
+      }
+
+      if (result.suppressed) {
+        return textResponse({ ok: true, suppressed: true, gate_id: result.card.gate_id });
+      }
+
+      _mintLiveGate(result.card.gate_id, result.card, sessionId);
+      const response = {
+        ok: true,
+        gate_id: result.card.gate_id,
+        renderer: result.renderer,
+        rendered: result.rendered,
+      };
+      // Elicitation completes its round trip INLINE (server.server.elicitInput
+      // awaits the live client response within THIS call, unlike the other two
+      // rungs whose answer arrives later via a separate gate_answer call). When
+      // it produced an answer, surface it now and consume the live-gate entry
+      // immediately so the SAME gate_id cannot be replayed through gate_answer.
+      if (result.answer) {
+        _consumeLiveGate(result.card.gate_id, sessionId);
+        response.answer = result.answer;
+      }
+      return textResponse(response);
+    }
+  );
+
+  server.tool(
+    'gate_answer',
+    'Ratify a gate decision. Accepts the canonical { gate_id, chosen, verdict } payload; only ratifies a gate_id THIS server process minted through the shared ledger (lib/mcp/gate-ledger.cjs), including a gate id minted by a chain_run halt (T-198-10 spoofing guard, session-scoped). chosen must be an option id or an option label from the card that was actually minted; a chosen value outside that set is rejected with chosen_not_in_card_options before any write happens. On an approve verdict, routes the material write through lib/core/navigation.cjs (Part 9) -- never a direct DB write. An approve verdict ALSO writes a typed decision node with SOURCED_FROM provenance edges to the card\'s subject/evidence node ids, plus a USES_FRAMEWORK edge when the gate came from a chain halt with an active framework; the node is promoted to confirmed via navigation.confirmNode, recording the human APPROVE. When the gate_id was minted by a chain_run halt at a material step, gate_answer is ALSO the verb that resumes that chain: an approve verdict runs the halted step and continues the chain in this SAME call, returning the result nested under chain_result; if the continued chain halts again at a later material step, chain_result carries the next gate_id to answer the same way. The gate is single-use, so a second gate_answer for the same gate_id, or a chain_run call threaded with the same answer afterward, is refused with unknown_or_expired_gate and nothing re-runs.',
+    {
+      gate_id: z.string().min(1),
+      chosen: z.array(z.string().min(1)).min(1),
+      verdict: z.enum(['approve', 'reject', 'defer']),
+    },
+    async ({ gate_id, chosen, verdict }, extra) => {
+      const sessionId = resolveEffectiveSessionId(undefined, extra);
+      const live = _consumeLiveGate(gate_id, sessionId);
+      if (!live) {
+        return textResponse({ ok: false, reason: 'unknown_or_expired_gate', gate_id: gate_id }, true);
+      }
+      if (live.ok === false) {
+        return textResponse({ ok: false, reason: live.reason, gate_id: gate_id }, true);
+      }
+      // GATE-01 G-2 (ASVS V5 value-domain check): the minted card is in hand
+      // right here, and until now it went unused -- chosen was copied
+      // verbatim into a ratified memory_event without ever checking it was
+      // among the card's actual options. This check runs strictly BEFORE
+      // resolveSessionRoomDir / openRoomDbForCaller / logMemoryEvent below,
+      // so a rejected answer opens no DB and writes no row.
+      const validChosen = gateRender.validateChosenAgainstCard(live.card, chosen);
+      if (!validChosen) {
+        const validOptionIds = (live.card && Array.isArray(live.card.options))
+          ? live.card.options.map((o) => o.id)
+          : [];
+        return textResponse({
+          ok: false,
+          reason: 'chosen_not_in_card_options',
+          gate_id: gate_id,
+          valid_option_ids: validOptionIds,
+        }, true);
+      }
+      // quick task 260819-c55 (Task 2): a material_step entry with no
+      // callable resumeFn is refused honestly BEFORE any room db is opened
+      // and BEFORE any ratification is written -- a gate whose execution
+      // owner is gone must not leave a ratified memory_event for a step
+      // that will never run, the same conservative direction the
+      // chosen-validation check above already takes.
+      if (live.kind === 'material_step' && typeof live.resumeFn !== 'function') {
+        return textResponse({ ok: false, reason: 'resume_owner_missing', gate_id: gate_id }, true);
+      }
+
+      // Persist the RESOLVED option ids (validChosen), not the raw submitted
+      // chosen array -- a label that resolved to an id must not leave a raw
+      // label string in the ratified memory_event. Mirrors the
+      // AskUserQuestion rung's own _resolveChosenIds -> normalizeGateAnswer
+      // call shape in gate-render.cjs.
+      const answer = gateRender.normalizeGateAnswer(gate_id, validChosen, verdict);
+
+      const roomDir = resolveSessionRoomDir(sessionId, ctx);
+      const db = navigation.openRoomDbForCaller(roomDir);
+      if (!db) {
+        return textResponse({ ok: false, reason: 'no_room_db', room_dir: roomDir }, true);
+      }
+      let logResult;
+      let reasoningNode = null;
+      try {
+        logResult = navigation.logMemoryEvent(db, 'mcp_client_event_logged', {
+          label: 'gate_answer',
+          gate_id: answer.gate_id,
+          chosen: answer.chosen,
+          verdict: answer.verdict,
+        });
+
+        // Quick task 260903-i2x (T2 node-writing half) -- ADDITIVE ONLY. The
+        // logMemoryEvent bookkeeping row above is unchanged; this is new
+        // code alongside it, never a replacement. Only an approve verdict
+        // mints a typed decision node; reject/defer write nothing extra.
+        // Wrapped in try/catch so no reasoning-write fault can ever break
+        // gate ratification (mirrors the writeEdge ok-stability doctrine at
+        // edges.cjs:1088-1100 -- response.ok never flips on this path).
+        if (answer.verdict === 'approve') {
+          try {
+            const nodeId = navigation.REASONING_NODE_ID('decision:gate', answer.gate_id);
+            if (nodeId) {
+              // Derive text, bounded and local-only, never fabricated: prefer
+              // the minted card's header, else the labels of the resolved
+              // chosen options looked up by id, else the raw chosen ids.
+              let text = '';
+              if (live.card && typeof live.card.header === 'string' && live.card.header.length > 0) {
+                text = live.card.header;
+              } else if (live.card && Array.isArray(live.card.options)) {
+                const labels = answer.chosen
+                  .map((id) => {
+                    const opt = live.card.options.find((o) => o && (o.id === id || o.label === id));
+                    return opt ? opt.label : null;
+                  })
+                  .filter((l) => typeof l === 'string' && l.length > 0);
+                text = labels.length > 0 ? labels.join('; ') : answer.chosen.join('; ');
+              } else {
+                text = answer.chosen.join('; ');
+              }
+
+              // DC-2: `live` IS the consumed ledger entry chain.cjs minted
+              // with `haltedStep` (chain.cjs:350-375), so `live.haltedStep.
+              // framework` is readable here with NO chain.cjs change needed.
+              // DC-3: sensors.cjs's framework_run halt path mints NO ledger
+              // entry (it never requires gate-ledger.cjs), so its gate can
+              // never reach gate_answer and its USES_FRAMEWORK edge is
+              // structurally unreachable -- a named, deliberate gap, not an
+              // oversight (see CLAUDE.md handoff row).
+              const framework = (live.haltedStep && typeof live.haltedStep.framework === 'string')
+                ? live.haltedStep.framework
+                : null;
+
+              // live.card.subjectNodeId / evidenceNodeIds are the NORMALIZED
+              // camelCase fields gate-render.cjs::normalizeCard guarantees on
+              // EVERY card (quick 260903-h27), always present and always
+              // defaulted -- no shape check is needed here.
+              const writeResult = navigation.writeReasoningNode(db, {
+                nodeId: nodeId,
+                nodeType: 'decision',
+                epistemicType: 'decision',
+                text: text,
+                sourcePath: 'gate:' + answer.gate_id,
+                subjectNodeId: live.card && live.card.subjectNodeId,
+                evidenceNodeIds: live.card && live.card.evidenceNodeIds,
+                framework: framework,
+                origin: 'gate_answer',
+              });
+
+              let confirmed = false;
+              if (writeResult && writeResult.ok === true) {
+                // DC-4 / Canon Part 9 role 5: the human APPROVE at a Decision
+                // Gate is exactly what confirmNode exists to record; minting
+                // 'confirmed' directly in the writer would be a
+                // constitutional breach (memory-artifacts.cjs:333-339). A
+                // promotion failure leaves the node at 'proposed' and is
+                // recorded on the response, never thrown.
+                try {
+                  const confirmResult = navigation.confirmNode(
+                    db, writeResult.node_id, navigation.resolveByUser(roomDir), 'gate_answer approve'
+                  );
+                  confirmed = !!(confirmResult && confirmResult.ok === true);
+                } catch (_e) {
+                  confirmed = false;
+                }
+              }
+              reasoningNode = Object.assign({}, writeResult, { confirmed: confirmed });
+            }
+          } catch (e) {
+            reasoningNode = { ok: false, reason: 'reasoning_write_threw', detail: String((e && e.message) || e).slice(0, 80) };
+          }
+        }
+      } finally {
+        navigation.closeRoomDbForCaller(db);
+      }
+
+      const response = {
+        ok: true,
+        gate_id: answer.gate_id,
+        chosen: answer.chosen,
+        verdict: answer.verdict,
+        ratified: answer.verdict === 'approve',
+        memory_event: logResult,
+      };
+      if (answer.verdict === 'approve') {
+        response.reasoning_node = reasoningNode;
+      }
+
+      // Ordering doctrine (quick task 260819-c55, Task 2): the ratification
+      // memory_event above is written BEFORE the step executes, deliberately.
+      // The halted step may be irreversible, so a step that runs must never
+      // be unrecorded; the inverse case -- a ratification recorded for a
+      // step that then faulted -- stays visible through chain_result.ok:false
+      // below and is the recoverable direction.
+      if (live.kind === 'material_step') {
+        let chainResult;
+        try {
+          chainResult = await live.resumeFn({ gate_id: answer.gate_id, chosen: answer.chosen, verdict: answer.verdict });
+        } catch (e) {
+          chainResult = { ok: false, reason: 'resume_fault', detail: String((e && e.message) || e) };
+        }
+        // Nest, do not spread: chain_result carries its own ok / completed /
+        // halted / executed / gate_id / chain_output / gate keys, and
+        // flattening them would clobber the ratification fields above.
+        response.resumed = true;
+        response.chain_result = chainResult;
+        if (chainResult && chainResult.ok === false) {
+          response.ok = false;
+        }
+        return textResponse(response, response.ok === false);
+      }
+
+      return textResponse(response);
+    }
+  );
+}
+
+// Born-wired SOURCE of truth (Part 11 R1/R16). Both tools reach a genuine
+// Decision-Gate fork (they ARE the HITL surface). scripts/build-connector-
+// registry.cjs discovers this export and regenerates data/mcp-tool-
+// connectors.json + data/connector-registry.json from it; never hand-edit
+// either generated file.
+const connectors = [
+  {
+    tool: 'gate_render',
+    surface: 'gate_render',
+    connector: 'mcp-tool',
+    hitl_shape: 'F.1',
+    hitl_why: 'Renders the Mindrian gate superset card via the 3-rung renderer ladder for a genuine Decision-Gate fork; the F.8/F.9 shipped renderers it composes from are the same binding/reconcile HITL shapes.',
+  },
+  {
+    tool: 'gate_answer',
+    surface: 'gate_answer',
+    connector: 'mcp-tool',
+    hitl_shape: 'F.1',
+    hitl_why: 'Ratifies a gate decision; an approve verdict routes a material write through navigation.cjs (Part 9) -- the fork the human already resolved via gate_render -- and now also writes a typed decision node with SOURCED_FROM/USES_FRAMEWORK provenance edges, promoted to confirmed via confirmNode.',
+  },
+];
+
+module.exports = {
+  register: register,
+  connectors: connectors,
+  _internal: {
+    resolveSessionRoomDir: resolveSessionRoomDir,
+    detectClientCapabilities: detectClientCapabilities,
+    _liveGates: gateLedger._internal._ledger,
+    _mintLiveGate: _mintLiveGate,
+    _consumeLiveGate: _consumeLiveGate,
+  },
+};

package/lib/mcp/tools/graph-reason.cjs

@@ -0,0 +1,130 @@
+'use strict';
+// Phase 270-10 Task 3 (MEMOP-07/MEMOP-13) -- graph_reason, the operator's own
+// genuinely graph-native Tool.
+//
+// `graph_query` (lib/mcp/tools/graph.cjs) is a bare getNeighborhood wrapper
+// and is already thin (RESEARCH.md 3.3's own closing line: do not re-expose
+// it under a new name and call that graph-native). This tool exposes TWO
+// reads a flat tree or a KV store structurally could not answer:
+//
+//   transitive_support           -- a claim's support closure through
+//     intermediate nodes (navigation.findTransitiveSupport, the recursive
+//     CTE upgrade of findUnsupportedClaims's single-hop NOT EXISTS check).
+//   nearest_sub_room_decisions   -- structural-distance ranking of decision
+//     nodes ACROSS a room.db boundary (icm-forest.cjs::findNearestSubRoomDecisions,
+//     the second read-only consumer of rollupSubRooms).
+//
+// Re-exposing getNeighborhood under a new name here would not be graph-native,
+// only renamed -- this file never calls it directly (see the grep-checkable
+// note at the bottom of the handler below).
+//
+// ONE tool with a bounded mode enum, not three tools. RESEARCH.md 2.3
+// established that the number and size of registered tool descriptions is
+// the ONLY token lever this repo has, so three near-identical schemas would
+// work directly against this phase's own goal. Pitfall P1 (tool-router.cjs's
+// z.enum anti-pattern) is specifically an enum spanning a MIX of 'none' and
+// F.* hitl_shape operations, losing per-operation safety tracking. This mode
+// enum is NOT that: every mode here is a pure read with hitl_shape 'none', so
+// there is no material operation hiding behind the dispatch for tracking to
+// lose. That distinction -- reusing the one-tool-many-modes SHAPE while never
+// inheriting the shape-tracking GAP -- is the whole point of building this as
+// one tool rather than three.
+//
+// point_in_time / queryAsOf (RESEARCH.md 3.3 candidate 3) is DELIBERATELY
+// DEFERRED, not silently omitted (see this plan's SUMMARY for the recorded
+// decision): queryAsOf(db, nodeKey, T_tx, T_v) is a single-node bitemporal
+// point lookup, not a graph traversal, and needs its own (nodeKey, T_tx, T_v)
+// parameter shape unrelated to this schema's node/depth/result-count fields --
+// bolting it on would bloat the schema for a capability that is not "multi-hop",
+// the theme this tool exists to add. It already has a navigation.cjs
+// re-export with zero MCP surface (queryAsOf: pointInTime.queryAsOf) and is
+// better served by its own small tool in a later phase.
+//
+// Canon Part 8: every read goes through the navigation.cjs chokepoint; zero
+// Brain calls, zero network calls. No em-dashes. CJS only.
+
+const { z } = require('zod');
+
+const navigation = require('../../core/navigation.cjs');
+const { resolveEffectiveSessionId } = require('../../core/session-binding.cjs');
+const { resolveSessionRoomDir } = require('../session-room.cjs');
+
+function textResponse(payload, isError) {
+  const result = { content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }] };
+  if (isError) result.isError = true;
+  return result;
+}
+
+function register(server, ctx) {
+  server.tool(
+    'graph_reason',
+    'Multi-hop graph reads a flat tree or a plain lookup cannot express. Mode transitive_support traces whether a claim is supported directly, only transitively through intermediate nodes, or not at all -- prefer it over graph_query when the question is "supported how, through what chain," not "what is adjacent." Mode nearest_sub_room_decisions ranks a room\'s sub-rooms by which one\'s decisions sit structurally nearest a focus node, crossing the room.db boundary read-only. Every mode is a pure read; it never writes a node or an edge.',
+    {
+      mode: z.enum(['transitive_support', 'nearest_sub_room_decisions'])
+        .describe('Which graph-native read to run.'),
+      node_id: z.string().min(1).optional()
+        .describe('The focus node id. Required for transitive_support. Optional for nearest_sub_room_decisions (falls back to room-tree distance alone when absent).'),
+      max_depth: z.number().int().min(1).max(5).optional()
+        .describe('Cascade bound for transitive_support (default 5, the same bound findBlockingAssumptions uses). Unused by nearest_sub_room_decisions.'),
+      max_results: z.number().int().min(1).max(50).optional()
+        .describe('Max results for nearest_sub_room_decisions (default 10, hard-capped server-side regardless of this value). Unused by transitive_support.'),
+    },
+    async ({ mode, node_id, max_depth, max_results }, extra) => {
+      if (mode === 'transitive_support' && (typeof node_id !== 'string' || node_id.length === 0)) {
+        return textResponse({ ok: false, reason: 'missing_node_id', mode: mode });
+      }
+
+      const sessionId = resolveEffectiveSessionId(undefined, extra);
+      const roomDir = resolveSessionRoomDir(sessionId, ctx);
+
+      // The two modes take asymmetric inputs, and that asymmetry is
+      // deliberate, not an inconsistency: transitive_support runs a single
+      // recursive SELECT over an already-open db handle (the ordinary Part 9
+      // shape every other read tool in this file uses). nearest_sub_room_
+      // decisions instead takes a room DIRECTORY, because it manages its OWN
+      // cross-room ATTACH lifecycle end to end via rollupSubRooms (open,
+      // ATTACH each child read-only, DETACH, close) -- handing it an
+      // already-open handle would not fit that lifecycle, and opening a
+      // second db handle here just to hand it over unused would be pointless.
+      // Both modes still close everything they open, in a finally, below.
+      const db = navigation.openRoomDbForCaller(roomDir);
+      if (!db) {
+        return textResponse({ ok: false, reason: 'no_room_db', room_dir: roomDir, mode: mode });
+      }
+      try {
+        if (mode === 'transitive_support') {
+          const result = navigation.findTransitiveSupport(db, node_id, { maxDepth: max_depth });
+          return textResponse({ ok: true, mode: mode, room_dir: roomDir, ...result });
+        }
+        // mode === 'nearest_sub_room_decisions'. icm-forest.cjs opens and
+        // closes its OWN db handle internally (it takes a directory, not a
+        // handle); this file's own `db` above is opened only to satisfy the
+        // no_room_db refusal check every mode here shares, and is closed in
+        // the finally below regardless of which branch ran.
+        const { findNearestSubRoomDecisions } = require('../../core/icm-forest.cjs');
+        const result = findNearestSubRoomDecisions(roomDir, { focusNodeId: node_id, maxResults: max_results });
+        return textResponse({ ok: true, mode: mode, ...result });
+      } catch (e) {
+        return textResponse({ ok: false, reason: (e && e.message) || 'graph_reason_failed', mode: mode, room_dir: roomDir }, true);
+      } finally {
+        navigation.closeRoomDbForCaller(db);
+      }
+    }
+  );
+}
+
+// Born-wired SOURCE of truth (Part 11 R1/R16). scripts/build-connector-
+// registry.cjs discovers this export and regenerates data/mcp-tool-
+// connectors.json + data/connector-registry.json from it; never hand-edit
+// either generated file.
+const connectors = [
+  {
+    tool: 'graph_reason',
+    surface: 'graph_reason',
+    connector: 'mcp-tool',
+    hitl_shape: 'none',
+    hitl_why: 'Every mode is a pure read through the navigation.cjs chokepoint: no node minted, no edge written, and specifically NO cross-room edge materialized (edges.cjs:45, "Cross-room aggregation forbidden"). Contrast with graph_write\'s F.1: this tool never writes, the read/write line RESEARCH.md 2.5 names as the load-bearing distinction this phase preserves.',
+  },
+];
+
+module.exports = { register, connectors };