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

package/lib/core/navigation/calibration-gate.cjs

@@ -0,0 +1,284 @@
+'use strict';
+// Phase 177-08 (BCH-15 / BCH-CAL) -- the calibration gate that CAN FAIL.
+//
+// BCH-CAL is a HARNESS proven on SYNTHETIC datasets. Its headline is the FAIL
+// path: a flat reliability dataset (per-cue_type ROC-AUC ~0.5) makes the Step-0
+// DISCRIMINATION GATE fail BEFORE any curve-fit runs, so no floor/ceiling is
+// pinned, no isotonic/Platt fit is attempted, the Wave-4 arming flag stays
+// LOCKED, and a rework signal is emitted. A complementary discriminating dataset
+// proves the gate also PASSES -- it is not a gate that always fails. A gate that
+// cannot fail is not a gate.
+//
+// CHANGE-CONTROL RULE (D-9 / BCH-15): AUC_MIN and SLOPE_MIN are JUDGMENT-SET
+// constants. They are NEVER derived from the dataset (no percentile, no sweep, no
+// computed statistic). They may NEVER be lowered to unblock a wave. The
+// change-control test asserts they are byte-identical even when run against a
+// sub-threshold dataset, so the gate cannot lower its own bar to pass weak data.
+//
+// DEFERRED + HONEST: the LIVE calibration -- pinning the real behavioral-channel
+// floor/ceiling from accumulated shadow usage via a real isotonic/Platt fit -- is
+// DEFERRED until real shadow data and a ground-truth-labeling mechanism exist. The
+// shipped calibration_observations table (Phase 177-05) carries no
+// ground_truth_label column today, so the harness operates on EXPLICIT synthetic
+// observation arrays (label + confidence supplied). We do NOT fabricate a pass on
+// empty or synthetic data for the live thresholds. The gate must be ALLOWED to
+// fail, never faked to pass.
+//
+// Canon Part 8: this module reads ONLY the LOCAL engine constants and a passed-in
+// observation array. It opens NO Brain wire, mints no reach, and leaves
+// routing_source legacy (this wave still fires nothing semantic). Frozen sets
+// (the 6 reaches, the 3 postures, ALLOWED_EDGE_TYPES) are untouched.
+
+// The engine-owned floor/ceiling, read from their home rather than re-typed --
+// mirroring the calibration-log.cjs require idiom exactly so the gate can never
+// drift from the ranker's notion of FLOOR / CEILING (NO threshold literal lands
+// in a prompt; BCH-05). A PASS verdict PROPOSES pinning these; the harness reports
+// them but does NOT itself rewrite the ranker (live threshold-pinning is deferred).
+const {
+  BEHAVIORAL_CHANNEL_FLOOR,
+  BEHAVIORAL_CHANNEL_CEILING,
+} = require('../../workflow/f-selector-ranker.cjs');
+
+// JUDGMENT-SET constants. Hand-set by judgment, NEVER swept from data. See the
+// CHANGE-CONTROL RULE at the top of this file. Lowering either to unblock a wave
+// is forbidden.
+const AUC_MIN = 0.65;
+const SLOPE_MIN = 0.15;
+
+// The Wave-4 arming flag, default LOCKED. The harness NEVER mutates this constant
+// to true; a PASS verdict only RETURNS the permission to arm (armed_allowed:true).
+// Locked-by-default means Waves 4-5 stay blocked until the gate honestly PASSES.
+const BEHAVIORAL_CHANNEL_ARMED = false;
+
+/**
+ * ROC-AUC of raw_confidence vs ground_truth_label via the Mann-Whitney U rank-sum
+ * identity:  AUC = (sumRanksPos - nPos*(nPos+1)/2) / (nPos*nNeg), averaging the
+ * ranks of tied scores. Returns 0.5 (chance) when there are zero positives or zero
+ * negatives -- no discrimination is possible, so a flat/degenerate dataset reads as
+ * chance and FAILS the gate.
+ *
+ * @param {Array<{raw_confidence:number, ground_truth_label:0|1}>} observations
+ * @returns {number} AUC in [0,1]
+ */
+function rocAuc(observations) {
+  if (!Array.isArray(observations) || observations.length === 0) {
+    return 0.5;
+  }
+
+  // Sort by score ascending, then assign average ranks (1-based), tie-averaged.
+  const rows = observations
+    .map((o) => ({
+      score: typeof o.raw_confidence === 'number' ? o.raw_confidence : 0,
+      label: o.ground_truth_label === 1 ? 1 : 0,
+    }))
+    .sort((a, b) => a.score - b.score);
+
+  const n = rows.length;
+  const ranks = new Array(n);
+  let i = 0;
+  while (i < n) {
+    let j = i;
+    while (j + 1 < n && rows[j + 1].score === rows[i].score) {
+      j++;
+    }
+    // ranks are 1-based; average rank for the tie block [i..j].
+    const avgRank = (i + 1 + (j + 1)) / 2;
+    for (let k = i; k <= j; k++) {
+      ranks[k] = avgRank;
+    }
+    i = j + 1;
+  }
+
+  let nPos = 0;
+  let nNeg = 0;
+  let sumRanksPos = 0;
+  for (let k = 0; k < n; k++) {
+    if (rows[k].label === 1) {
+      nPos++;
+      sumRanksPos += ranks[k];
+    } else {
+      nNeg++;
+    }
+  }
+
+  if (nPos === 0 || nNeg === 0) {
+    return 0.5; // no discrimination possible -- chance.
+  }
+
+  return (sumRanksPos - (nPos * (nPos + 1)) / 2) / (nPos * nNeg);
+}
+
+/**
+ * Reliability-diagram slope: bin observations by raw_confidence (default 10
+ * equal-width bins on [0,1]), compute per-bin mean predicted confidence (x) and
+ * observed positive frequency (y), then the least-squares slope of y on x over
+ * non-empty bins. A flat reliability curve (observed frequency does not track
+ * predicted confidence) yields slope ~0, which FAILS SLOPE_MIN.
+ *
+ * @param {Array<{raw_confidence:number, ground_truth_label:0|1}>} observations
+ * @param {number} [bins=10]
+ * @returns {number} least-squares slope
+ */
+function reliabilitySlope(observations, bins) {
+  if (!Array.isArray(observations) || observations.length === 0) {
+    return 0;
+  }
+  const nBins = Number.isInteger(bins) && bins > 0 ? bins : 10;
+
+  const sumX = new Array(nBins).fill(0); // sum of predicted confidence per bin
+  const sumY = new Array(nBins).fill(0); // sum of labels (positive count) per bin
+  const cnt = new Array(nBins).fill(0);
+
+  for (const o of observations) {
+    const c = typeof o.raw_confidence === 'number' ? o.raw_confidence : 0;
+    const label = o.ground_truth_label === 1 ? 1 : 0;
+    let b = Math.floor(c * nBins);
+    if (b < 0) b = 0;
+    if (b >= nBins) b = nBins - 1; // confidence == 1.0 lands in the top bin
+    sumX[b] += c;
+    sumY[b] += label;
+    cnt[b] += 1;
+  }
+
+  // Per non-empty bin: x = mean predicted confidence, y = observed positive freq.
+  const xs = [];
+  const ys = [];
+  for (let b = 0; b < nBins; b++) {
+    if (cnt[b] > 0) {
+      xs.push(sumX[b] / cnt[b]);
+      ys.push(sumY[b] / cnt[b]);
+    }
+  }
+
+  const m = xs.length;
+  if (m < 2) {
+    return 0; // a single populated bin cannot express a slope.
+  }
+
+  let meanX = 0;
+  let meanY = 0;
+  for (let k = 0; k < m; k++) {
+    meanX += xs[k];
+    meanY += ys[k];
+  }
+  meanX /= m;
+  meanY /= m;
+
+  let num = 0;
+  let den = 0;
+  for (let k = 0; k < m; k++) {
+    const dx = xs[k] - meanX;
+    num += dx * (ys[k] - meanY);
+    den += dx * dx;
+  }
+
+  if (den === 0) {
+    return 0; // all bins share one predicted-confidence value -- no slope.
+  }
+
+  return num / den;
+}
+
+/**
+ * Step-0 DISCRIMINATION GATE. Input is a map of cue_type -> observation array. For
+ * each cue_type compute auc = rocAuc(rows) and slope = reliabilitySlope(rows). A
+ * cue_type PASSES iff auc >= AUC_MIN AND slope >= SLOPE_MIN. Overall pass is true
+ * iff EVERY cue_type passes.
+ *
+ * @param {Object<string, Array>} observationsByCueType
+ * @returns {{pass:boolean, perCueType:Object, failingCueTypes:string[]}}
+ */
+function runDiscriminationGate(observationsByCueType) {
+  const perCueType = {};
+  const failingCueTypes = [];
+
+  const map = observationsByCueType && typeof observationsByCueType === 'object'
+    ? observationsByCueType
+    : {};
+  const cueTypes = Object.keys(map);
+
+  // An empty map cannot demonstrate discrimination -- it FAILS (never fakes a pass
+  // on no data). Each present cue_type is graded against the judgment-set bars.
+  let overallPass = cueTypes.length > 0;
+
+  for (const cueType of cueTypes) {
+    const rows = Array.isArray(map[cueType]) ? map[cueType] : [];
+    const auc = rocAuc(rows);
+    const slope = reliabilitySlope(rows);
+    const pass = auc >= AUC_MIN && slope >= SLOPE_MIN;
+    perCueType[cueType] = { auc, slope, pass };
+    if (!pass) {
+      failingCueTypes.push(cueType);
+      overallPass = false;
+    }
+  }
+
+  return { pass: overallPass, perCueType, failingCueTypes };
+}
+
+/**
+ * BCH-CAL entry point. MUST run runDiscriminationGate FIRST, before any curve-fit.
+ *
+ * On Step-0 FAIL: returns immediately with no fit attempted and no thresholds
+ * pinned -- { pass:false, stage:'discrimination', floor:null, ceiling:null,
+ * fit:null, armed_allowed:false, rework_signal:{...} }.
+ *
+ * On Step-0 PASS: returns { pass:true, stage:'calibrated', floor, ceiling,
+ * fit:{method:'deferred', ...}, armed_allowed:true, rework_signal:null }. The
+ * fit.method:'deferred' is deliberate and honest -- the LIVE isotonic/Platt fit on
+ * real accumulated shadow data is DEFERRED until that data and a
+ * ground-truth-labeling mechanism exist. The harness proves the GATE DIRECTION
+ * (fail vs pass) on synthetic data; it does NOT fabricate a real fit.
+ *
+ * @param {Object<string, Array>} observationsByCueType
+ */
+function runCalibrationGate(observationsByCueType) {
+  const discrimination = runDiscriminationGate(observationsByCueType);
+
+  if (!discrimination.pass) {
+    // FAIL: no isotonic/Platt fit, no floor/ceiling pinned, flag stays LOCKED.
+    return {
+      pass: false,
+      stage: 'discrimination',
+      floor: null,
+      ceiling: null,
+      fit: null,
+      armed_allowed: false,
+      discrimination,
+      rework_signal: {
+        reason: 'discrimination_gate_failed',
+        failing_cue_types: discrimination.failingCueTypes,
+        per_cue_type: discrimination.perCueType,
+      },
+    };
+  }
+
+  // PASS: the Step-0 gate cleared. The harness REPORTS the engine-owned
+  // floor/ceiling a live fit would PROPOSE pinning, but the live fit itself is
+  // DEFERRED (see fit.method) -- the harness does not rewrite the ranker.
+  return {
+    pass: true,
+    stage: 'calibrated',
+    floor: BEHAVIORAL_CHANNEL_FLOOR,
+    ceiling: BEHAVIORAL_CHANNEL_CEILING,
+    fit: {
+      method: 'deferred',
+      note: 'Live isotonic/Platt fit on real accumulated shadow data is DEFERRED '
+        + 'until ground-truth-labeled shadow observations exist; the harness proves '
+        + 'the gate direction on synthetic data, it does not fabricate a real fit.',
+    },
+    armed_allowed: true,
+    discrimination,
+    rework_signal: null,
+  };
+}
+
+module.exports = {
+  AUC_MIN,
+  SLOPE_MIN,
+  BEHAVIORAL_CHANNEL_ARMED,
+  rocAuc,
+  reliabilitySlope,
+  runDiscriminationGate,
+  runCalibrationGate,
+};

package/lib/core/navigation/calibration-log.cjs

@@ -0,0 +1,141 @@
+'use strict';
+// Phase 177-05 (BCH-04) -- the thin LOCAL calibration writer.
+//
+// logCalibrationObservation(db, obs) writes exactly ONE row into the dedicated
+// calibration_observations table (minted by memory-ops.cjs initCalibrationSchema)
+// and optionally emits ONE scalar audit-marker memory_event.
+//
+// SHADOW-ONLY. This wave logs; it does NOT fire. No reach is minted, routing_source
+// stays legacy, no semantic seam opens. The writer is the observation tape Wave 3
+// (BCH-CAL) reads to pin the behavioral-channel floor/ceiling.
+//
+// THE LOAD-BEARING BEHAVIOR (BCH-04): a below-floor cue (confidence < FLOOR) STILL
+// writes a row, with cue_disposition 'discarded'. Discarded cues are LOGGED, not
+// dropped -- "shadow before trust".
+//
+// Canon Part 8: the row store is a DEDICATED LOCAL table; buildBrainPacket never
+// reads it (packet.cjs reads only nodes + identity). The columns hold ONLY scalars
+// + enum handles; no prose column exists, and the audit marker carries no row body.
+// All writes use prepared statements with ? parameters (no string interpolation).
+
+const crypto = require('node:crypto');
+const memoryEvents = require('./memory-events.cjs');
+
+// The engine-owned thresholds, read from their home rather than re-typed (the
+// computed-not-hand-typed pattern: BCH-06 / the Wave-1 ceiling derivation). If a
+// caller pre-computes band + cue_disposition, those are honored; otherwise they are
+// derived here against the live engine constants so the writer can never drift from
+// the ranker's notion of FLOOR / CEILING.
+const {
+  BEHAVIORAL_CHANNEL_FLOOR,
+  BEHAVIORAL_CHANNEL_CEILING,
+} = require('../../workflow/f-selector-ranker.cjs');
+
+/**
+ * Derive (cue_disposition, band) from a numeric confidence against the engine-owned
+ * thresholds. The protected band is the closed interval [FLOOR, CEILING]:
+ *   confidence <  FLOOR    -> { disposition: 'discarded',     band: 'below_floor' }
+ *   FLOOR <= c <= CEILING  -> { disposition: 'fired',         band: 'protected' }
+ *   confidence >  CEILING  -> { disposition: 'above_ceiling', band: 'above_ceiling' }
+ * @param {number} confidence
+ * @returns {{disposition: string, band: string}}
+ */
+function deriveDisposition(confidence) {
+  if (typeof confidence !== 'number' || Number.isNaN(confidence)) {
+    return { disposition: 'discarded', band: 'below_floor' };
+  }
+  if (confidence < BEHAVIORAL_CHANNEL_FLOOR) {
+    return { disposition: 'discarded', band: 'below_floor' };
+  }
+  if (confidence > BEHAVIORAL_CHANNEL_CEILING) {
+    return { disposition: 'above_ceiling', band: 'above_ceiling' };
+  }
+  return { disposition: 'fired', band: 'protected' };
+}
+
+/**
+ * Write ONE calibration_observations row (the dedicated-table store) and optionally
+ * emit ONE scalar audit-marker memory_event.
+ *
+ * @param {import('node:sqlite').DatabaseSync} db - caller-owned db handle (schema
+ *   must already exist via initCalibrationSchema; the chokepoint contract is that
+ *   the caller owns the open handle, mirroring writeEdge / logMemoryEvent).
+ * @param {object} obs
+ * @param {string}  [obs.cue_kind]        - the observation cue family handle (enum string,
+ *                                          e.g. reframe_cue / escape_hatch). Defaults 'unknown_cue'.
+ * @param {number}  [obs.confidence]      - numeric cue confidence.
+ * @param {string}  [obs.turn_id]         - optional turn handle.
+ * @param {number}  [obs.turn_count]      - optional turn counter scalar.
+ * @param {string}  [obs.cue_disposition] - caller pre-computed disposition; derived when absent.
+ * @param {string}  [obs.band]            - caller pre-computed band; derived when absent.
+ * @param {string}  [obs.created_by]      - defaults 'system'.
+ * @param {boolean} [obs.emit_audit_marker=true] - emit the scalar audit-marker memory_event.
+ * @param {string}  [obs.dedupe_key]      - optional dedupe key forwarded to the audit marker.
+ * @param {object}  [opts]                - { now } clock seam forwarded to logEvent.
+ * @returns {{ok: boolean, id?: string, cue_disposition?: string, band?: string, reason?: string}}
+ */
+function logCalibrationObservation(db, obs, opts) {
+  if (!db || typeof db.prepare !== 'function') {
+    return { ok: false, reason: 'invalid_db' };
+  }
+  if (!obs || typeof obs !== 'object') {
+    return { ok: false, reason: 'invalid_observation' };
+  }
+
+  const options = opts && typeof opts === 'object' ? opts : {};
+  const nowFn = typeof options.now === 'function' ? options.now : Date.now;
+  const nowMs = nowFn();
+
+  const cueKind = typeof obs.cue_kind === 'string' && obs.cue_kind.length > 0 ? obs.cue_kind : 'unknown_cue';
+  const confidence = typeof obs.confidence === 'number' ? obs.confidence : null;
+  const turnId = typeof obs.turn_id === 'string' ? obs.turn_id : null;
+  const turnCount = Number.isInteger(obs.turn_count) ? obs.turn_count : null;
+  const createdBy = typeof obs.created_by === 'string' && obs.created_by.length > 0 ? obs.created_by : 'system';
+
+  // Derive disposition + band unless the caller pre-computed them (the table stays
+  // the source of truth either way).
+  const derived = deriveDisposition(confidence);
+  const cueDisposition = typeof obs.cue_disposition === 'string' && obs.cue_disposition.length > 0
+    ? obs.cue_disposition
+    : derived.disposition;
+  const band = typeof obs.band === 'string' && obs.band.length > 0 ? obs.band : derived.band;
+
+  const id = 'calibration_observation:' + nowMs + ':' + crypto.randomBytes(4).toString('hex');
+
+  try {
+    db.prepare(
+      'INSERT INTO calibration_observations ' +
+      '(id, turn_id, turn_count, cue_kind, confidence, cue_disposition, band, created_by, created_at) ' +
+      'VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?)'
+    ).run(id, turnId, turnCount, cueKind, confidence, cueDisposition, band, createdBy, nowMs);
+  } catch (err) {
+    return { ok: false, reason: err.message };
+  }
+
+  // Optional scalar audit marker. Carries the turn handle + disposition enum +
+  // confidence scalar ONLY -- never a row body (Canon Part 8). The ROW STORE is the
+  // dedicated table above; this memory_event is just the audit trail.
+  const emitMarker = obs.emit_audit_marker !== false;
+  if (emitMarker) {
+    const markerPayload = {
+      turn_count: turnCount,
+      cue_disposition: cueDisposition,
+      confidence,
+      created_by: createdBy,
+    };
+    if (typeof obs.dedupe_key === 'string' && obs.dedupe_key.length > 0) {
+      markerPayload.dedupe_key = obs.dedupe_key;
+    }
+    // Best-effort: the audit marker must never block the row write. logEvent
+    // returns a structured result; we ignore failures here (the row already landed).
+    try {
+      memoryEvents.logEvent(db, 'calibration_observation_logged', markerPayload, options);
+    } catch (_err) {
+      // tolerant: the row store is the source of truth; the marker is advisory.
+    }
+  }
+
+  return { ok: true, id, cue_disposition: cueDisposition, band };
+}
+
+module.exports = { logCalibrationObservation, deriveDisposition };

package/lib/core/navigation/confirm-node.cjs

@@ -0,0 +1,73 @@
+'use strict';
+// Phase 129.5-02 confirmNode chokepoint + resolveByUser USER.md identity
+// resolver. Internal to lib/core/navigation/; re-exported by
+// lib/core/navigation.cjs (D-01) as the closed surface.
+//
+// Canon Part 9 v1.5 (D-01): confirmNode is the single APPROVE to promote door.
+// Every gate (the Plan 03 selector dispatcher, the Phase 130 lens-engine accept,
+// the Phase 116 tension resolution) calls this one helper; none call
+// promoteNodeStatus directly. One door for confirmation, mirroring the
+// navigation.cjs single-chokepoint pattern.
+//
+// Canon Part 9 v1.5 (D-02): resolveByUser reads the active room's USER.md
+// navigator identity, uniform across CLI / Desktop / Cowork since every room
+// carries a USER.md. It never returns an agent identity; a poisoned USER.md
+// cannot smuggle larry / brain / system / assistant into a confirm.
+//
+// This module writes NO Cypher and NO raw INSERT / UPDATE / DELETE on
+// nodes / edges. It delegates ALL writes to promoteNodeStatus. It performs one
+// read-only SELECT to resolve the node's current review_status.
+//
+// NO em-dashes in this file (CLAUDE.md HARD RULE).
+
+const path = require('node:path');
+const { promoteNodeStatus, AGENT_IDENTITIES } = require('./transitions.cjs');
+const { readUserMd } = require('../user-md-ops.cjs');
+
+// The stable non-agent default byUser. A fresh empty USER.md (or an absent one,
+// or one carrying an agent identity) resolves to this. It is deliberately NOT in
+// AGENT_IDENTITIES so a confirm attributed to it is always canon-legal.
+const NAVIGATOR_DEFAULT = 'navigator';
+
+// confirmNode(db, id, byUser, reason?)
+// Resolves the node's CURRENT review_status from the db and delegates to
+// promoteNodeStatus with the correct fromStatus, so the caller need not know the
+// from-state. Returns promoteNodeStatus's result verbatim, so the
+// agent_attribution_forbidden / invalid_transition / state_mismatch reasons all
+// surface unchanged. Returns { ok:false, reason:'unknown_node' } for a missing id.
+function confirmNode(db, id, byUser, reason) {
+  const row = db.prepare('SELECT review_status FROM nodes WHERE id = ?').get(id);
+  if (!row) {
+    return { ok: false, reason: 'unknown_node' };
+  }
+  return promoteNodeStatus(db, id, row.review_status, 'confirmed', byUser, reason);
+}
+
+// resolveByUser(roomDir)
+// Reads roomDir/USER.md and resolves the navigator identity. Precedence:
+//   1. user_id (non-empty string)
+//   2. canonical_role (non-empty string)
+//   3. NAVIGATOR_DEFAULT
+// Defense-in-depth: if the picked value lowercased is an agent identity, it is
+// coerced to NAVIGATOR_DEFAULT so a misconfigured or poisoned USER.md can never
+// attribute a confirm to larry / brain / system / assistant. NEVER throws.
+function resolveByUser(roomDir) {
+  let picked = null;
+  try {
+    const user = readUserMd(path.join(roomDir, 'USER.md'));
+    if (user) {
+      if (typeof user.user_id === 'string' && user.user_id.length > 0) {
+        picked = user.user_id;
+      } else if (typeof user.canonical_role === 'string' && user.canonical_role.length > 0) {
+        picked = user.canonical_role;
+      }
+    }
+  } catch (_e) {
+    picked = null;
+  }
+  if (!picked) return NAVIGATOR_DEFAULT;
+  if (AGENT_IDENTITIES.has(String(picked).toLowerCase())) return NAVIGATOR_DEFAULT;
+  return picked;
+}
+
+module.exports = { confirmNode, resolveByUser, NAVIGATOR_DEFAULT };

package/lib/core/navigation/dashboard-helpers.cjs

@@ -0,0 +1,145 @@
+'use strict';
+/*
+ * Phase 118 Plan 02 -- dashboard-helpers: thin wrappers used by the Plan
+ * 118-02 dashboard-graph-neighborhood MVA agent (Agent 6 of 6 in B1).
+ *
+ * Two wrappers, both kept under lib/core/navigation/ so the chokepoint module
+ * (lib/core/navigation.cjs) re-exports them as the navigator-facing API. The
+ * dashboard MVA agent goes through navigation.cjs only -- the Phase 109 D-06
+ * chokepoint invariant (Canon Part 9).
+ *
+ * Wrappers:
+ *   detectActiveRoom() -> { roomDir, hasRoomDb } | null
+ *     Resolves the active room via MindrianRooms/.rooms/registry.json (the
+ *     scripts/brain-derive-command.cjs precedent at line 142). Returns null if
+ *     no registry, no active slug, or the resolved path is not a directory.
+ *
+ *   getRecentDecisionNeighborhood(roomDir, opts) -> { nodes:[], edges:[] }
+ *     Opens room.db via lib/core/room-db.cjs (the SOLE owner of better-sqlite3
+ *     instantiation), picks the most recent 'decision' node, calls the
+ *     existing getNeighborhood() chokepoint, returns the typed neighborhood.
+ *     Returns { nodes:[], edges:[] } when room.db has no decisions yet.
+ *
+ * Canon Part 9 (Memory Locality + Interpretation): this helper IS a navigation
+ * surface; agents that need room-graph reads go through here.
+ *
+ * Canon Part 8: zero network surface. Pure LOCAL filesystem + SQLite reads.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const roomDbMod = require('../room-db.cjs');
+const neighborhoodMod = require('./neighborhood.cjs');
+
+function _safeIsFile(p) {
+  try { return fs.statSync(p).isFile(); } catch (_e) { return false; }
+}
+function _safeIsDir(p) {
+  try { return fs.statSync(p).isDirectory(); } catch (_e) { return false; }
+}
+
+/**
+ * Resolve the active room via the MindrianRooms registry. Mirrors
+ * scripts/brain-derive-command.cjs::resolveActiveRoom verbatim so the same
+ * detection rules apply across CLI commands and MVA agents.
+ *
+ * @returns {{ roomDir: string, hasRoomDb: boolean } | null}
+ */
+function detectActiveRoom() {
+  const home = process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const roomsRoot = process.env.MINDRIAN_ROOMS_ROOT
+    || process.env.MINDRIAN_ROOMS_HOME
+    || path.join(home, 'MindrianRooms');
+  const registryPath = path.join(roomsRoot, '.rooms', 'registry.json');
+  if (!_safeIsFile(registryPath)) return null;
+  let reg;
+  try {
+    reg = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+  } catch (_e) {
+    return null;
+  }
+  if (!reg || typeof reg !== 'object') return null;
+  const activeSlug = reg.active;
+  if (!activeSlug || typeof activeSlug !== 'string') return null;
+  const entry = reg.rooms && reg.rooms[activeSlug];
+  if (!entry || typeof entry !== 'object') return null;
+  const relPath = entry.path || activeSlug;
+  const absPath = path.resolve(roomsRoot, relPath);
+  if (!_safeIsDir(absPath)) return null;
+  const roomDbPath = path.join(absPath, '.mindrian', 'room.db');
+  const hasRoomDb = _safeIsFile(roomDbPath);
+  return { roomDir: absPath, hasRoomDb: hasRoomDb };
+}
+
+/**
+ * Return a 1-2 hop neighborhood snapshot of the most-recent Decision node in
+ * the room graph. The dashboard MVA agent renders this as the "your room
+ * already has N related decision nodes" surface.
+ *
+ * @param {string} roomDir   absolute path to the active room
+ * @param {{ hops?: number, limit?: number }} [opts]
+ * @returns {{ nodes: Array, edges: Array }}
+ */
+function getRecentDecisionNeighborhood(roomDir, opts) {
+  const options = opts || {};
+  const hops = Number.isInteger(options.hops) && options.hops >= 1 ? options.hops : 1;
+  const limit = Number.isInteger(options.limit) && options.limit > 0 ? options.limit : 5;
+
+  let db;
+  try {
+    db = roomDbMod.openRoomDb(roomDir);
+  } catch (_e) {
+    return { nodes: [], edges: [] };
+  }
+
+  let nodes = [];
+  let edges = [];
+  try {
+    // Pick the most recent decision node (or any node if no decisions) as focus.
+    const focusRow = db.prepare(
+      "SELECT id FROM nodes WHERE type = 'decision' ORDER BY created_at DESC LIMIT 1"
+    ).get();
+    if (!focusRow) {
+      return { nodes: [], edges: [] };
+    }
+    const focusNodeId = focusRow.id;
+    // Use the existing chokepoint to get the neighborhood. The depth + topK
+    // map onto Plan 118-02's "1-2 hop / 5-node snapshot" contract.
+    const neighborhood = neighborhoodMod.getNeighborhood(db, focusNodeId, {
+      maxDepth: hops,
+      topK: limit,
+    });
+    // Always include the focus node itself as the first node in the returned set.
+    nodes = [{ id: focusNodeId, type: 'decision' }].concat(neighborhood.map((n) => ({
+      id: n.id,
+      type: n.type,
+      score: n.score,
+      edgeTypeIn: n.edgeTypeIn,
+      depth: n.depth,
+    })));
+    // The closed neighborhood query also returns edge_path; surface a flat
+    // edges array of (source, target, type) tuples derived from the path
+    // metadata so the deck renderer (Plan 118-03) can draw the graph.
+    for (const n of neighborhood) {
+      if (n.edgePath && n.edgePath.length >= 2) {
+        const pathArr = n.edgePath;
+        for (let i = 0; i + 1 < pathArr.length; i++) {
+          edges.push({
+            source: pathArr[i],
+            target: pathArr[i + 1],
+            type: i + 1 === pathArr.length - 1 ? (n.edgeTypeIn || 'unknown') : 'path',
+          });
+        }
+      }
+    }
+  } catch (_e) {
+    nodes = [];
+    edges = [];
+  } finally {
+    try { roomDbMod.closeRoomDb(db); } catch (_e) { /* tolerant */ }
+  }
+  return { nodes, edges };
+}
+
+module.exports = { detectActiveRoom, getRecentDecisionNeighborhood };