@mindrian_os/install 1.13.0-beta.12 → 1.13.0-beta.13

package/lib/core/cache-prune.cjs

@@ -0,0 +1,208 @@
+'use strict';
+/*
+ * lib/core/cache-prune.cjs -- prune stale marketplace-cache version dirs.
+ *
+ * Phase 123 Plan-05 (HARNESS-123-13). Canon Part 8: this reads LOCAL files
+ * only (~/.claude/plugins/) and writes LOCAL files only (fs.rmSync on
+ * stale version dirs). Zero network surface.
+ *
+ * Background: Claude Code's marketplace install path is
+ *   ~/.claude/plugins/cache/<marketplace>/mos/<version>/
+ * where each <version> subdir is a self-contained install of that
+ * version. On `claude plugin update`, the new version is downloaded
+ * into a new <version> dir, but the old <version> dir is NEVER removed.
+ * The Windows live test of v1.13.0-beta.12 surfaced two orphans on disk
+ * (`1.12.0/`, `1.13.0-beta.9/`) alongside the active `1.13.0-beta.12/`.
+ *
+ * This helper prunes the cache, keying off Claude Code's own
+ * installed_plugins.json (the source of truth for "which version is active"):
+ *
+ *   - active version (from installed_plugins.json's mos@mindrian-marketplace
+ *     entry) is ALWAYS kept, regardless of mtime.
+ *   - the N most recent non-active versions (default N=2, sorted by mtime
+ *     DESC) are also kept.
+ *   - everything else is removed.
+ *
+ * Belt + suspenders: before every fs.rmSync call, the path's basename is
+ * cross-checked against the active version string -- if it matches, the
+ * removal is SKIPPED with a logged reason (defends against a malformed
+ * installed_plugins.json that somehow lists two different basenames as
+ * "active", or a race between this function and a concurrent install).
+ *
+ * If installed_plugins.json is unreadable (ENOENT, parse error, or no
+ * mos@mindrian-marketplace entry), the function returns
+ *   { kept: [], removed: [], skipped: true, reason: '...' }
+ * with NO mutation. Never guesses; never deletes anything in the absence
+ * of an authoritative active-version answer.
+ *
+ * Signature:
+ *   pruneMarketplaceCache({
+ *     home = os.homedir(),
+ *     marketplace = 'mindrian-marketplace',
+ *     retainCount = 2,
+ *     dryRun = false,
+ *   } = {}) => {
+ *     kept: string[],     // version basenames kept on disk (incl. active)
+ *     removed: string[],  // version basenames removed (or would be, in dryRun)
+ *     skipped: boolean,   // true if we declined to act (see `reason`)
+ *     reason: string|null // human-readable explanation, or null on success
+ *   }
+ *
+ * Canon Part 8 sanity check (cp.6): the forbidden-network-token grep
+ * exits 1 (no match) on this source file. Test cp.6 enforces it.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+// Read installed_plugins.json and pull the mos@mindrian-marketplace active
+// version. Returns { activeVersion, activeInstallPath } on success, or
+// { skipped: true, reason } on any failure.
+function readActiveVersion(home) {
+  const installedPath = path.join(home, '.claude', 'plugins', 'installed_plugins.json');
+  let raw;
+  try {
+    raw = fs.readFileSync(installedPath, 'utf8');
+  } catch (e) {
+    return { skipped: true, reason: 'installed_plugins.json unreadable (' + (e && e.code || e.message) + ') -- skipping prune' };
+  }
+  let ip;
+  try {
+    ip = JSON.parse(raw);
+  } catch (e) {
+    return { skipped: true, reason: 'installed_plugins.json parse error -- skipping prune' };
+  }
+  if (!ip || typeof ip !== 'object' || !ip.plugins || typeof ip.plugins !== 'object') {
+    return { skipped: true, reason: 'installed_plugins.json has no plugins map -- skipping prune' };
+  }
+  // Accept either key shape: 'mos@mindrian-marketplace' or 'mos'.
+  let entry = ip.plugins['mos@mindrian-marketplace'];
+  if (!entry) {
+    // Defensive: find any key whose left-of-@ is mos or mindrian-os.
+    const keys = Object.keys(ip.plugins);
+    for (const k of keys) {
+      const name = String(k).split('@')[0];
+      if (name === 'mos' || name === 'mindrian-os') { entry = ip.plugins[k]; break; }
+    }
+  }
+  if (!entry) {
+    return { skipped: true, reason: 'no active mos@mindrian-marketplace entry in installed_plugins.json -- skipping prune' };
+  }
+  if (Array.isArray(entry)) entry = entry[0];
+  if (!entry || !entry.version) {
+    return { skipped: true, reason: 'mos@mindrian-marketplace entry has no version field -- skipping prune' };
+  }
+  return {
+    activeVersion: String(entry.version),
+    activeInstallPath: entry.installPath || entry.path || entry.dir || null,
+  };
+}
+
+// List child directory names under <home>/.claude/plugins/cache/<marketplace>/mos/.
+// Returns [] if the cache dir does not exist (no-op case).
+function listCacheVersions(home, marketplace) {
+  const cacheDir = path.join(home, '.claude', 'plugins', 'cache', marketplace, 'mos');
+  if (!fs.existsSync(cacheDir)) return { cacheDir, names: [] };
+  let names = [];
+  try {
+    names = fs.readdirSync(cacheDir).filter(function (name) {
+      try { return fs.statSync(path.join(cacheDir, name)).isDirectory(); }
+      catch (_) { return false; }
+    });
+  } catch (_) { /* unreadable -- treat as empty */ }
+  return { cacheDir, names };
+}
+
+// Sort version names by mtime DESC (newest first). Falls back to lexicographic
+// order if statSync fails on any path (defensive).
+function sortByMtimeDesc(cacheDir, names) {
+  const stats = names.map(function (name) {
+    let mtimeMs = 0;
+    try { mtimeMs = fs.statSync(path.join(cacheDir, name)).mtimeMs || 0; }
+    catch (_) { mtimeMs = 0; }
+    return { name, mtimeMs };
+  });
+  stats.sort(function (a, b) {
+    if (b.mtimeMs !== a.mtimeMs) return b.mtimeMs - a.mtimeMs;
+    return a.name < b.name ? 1 : -1; // tie-break lexicographic DESC (stable)
+  });
+  return stats.map(function (s) { return s.name; });
+}
+
+function pruneMarketplaceCache(opts) {
+  const o = opts || {};
+  const home = o.home || os.homedir();
+  const marketplace = o.marketplace || 'mindrian-marketplace';
+  const retainCount = (typeof o.retainCount === 'number' && o.retainCount >= 0) ? o.retainCount : 2;
+  const dryRun = !!o.dryRun;
+
+  // Step 1: read active version. Skip entirely if unavailable -- never guess.
+  const active = readActiveVersion(home);
+  if (active.skipped) {
+    return { kept: [], removed: [], skipped: true, reason: active.reason };
+  }
+  const activeVersion = active.activeVersion;
+
+  // Step 2: list cache version dirs.
+  const { cacheDir, names } = listCacheVersions(home, marketplace);
+  if (names.length === 0) {
+    // No cache dir to prune. The active version is still "kept" conceptually
+    // (it lives in the cache when it exists; absent cache = nothing to do).
+    return { kept: [activeVersion], removed: [], skipped: false, reason: 'no cache dir to prune' };
+  }
+
+  // Step 3: build the keep-set.
+  //   - the active version is ALWAYS kept (regardless of mtime).
+  //   - then the N most recent non-active versions (by mtime DESC).
+  const sorted = sortByMtimeDesc(cacheDir, names);
+  const keep = new Set();
+  keep.add(activeVersion);
+  for (const name of sorted) {
+    if (name === activeVersion) continue;
+    if (keep.size >= retainCount + 1) break; // +1 reserves the slot for active
+    keep.add(name);
+  }
+
+  // Step 4: compute the prune set and act on it.
+  const removed = [];
+  for (const name of names) {
+    if (keep.has(name)) continue;
+    // Belt + suspenders: NEVER rm the active version's dir, no matter what.
+    if (name === activeVersion) {
+      // (Cannot reach here under normal flow -- the keep-set above always
+      // contains activeVersion. Defensive sentinel for malformed inputs.)
+      continue;
+    }
+    const target = path.join(cacheDir, name);
+    if (dryRun) {
+      removed.push(name);
+      continue;
+    }
+    try {
+      fs.rmSync(target, { recursive: true, force: true });
+      removed.push(name);
+    } catch (e) {
+      // Best-effort: a failed removal does not abort the whole prune; we
+      // record it in the reason field at the end if any failures occurred.
+      // The caller (session-start with `|| true`; doctor with try/catch +
+      // report.recoveries) handles the partial state.
+      removed.push(name + ' (rm-failed: ' + (e && e.code || e.message) + ')');
+    }
+  }
+
+  return {
+    kept: Array.from(keep),
+    removed,
+    skipped: false,
+    reason: null,
+  };
+}
+
+module.exports = {
+  pruneMarketplaceCache,
+  // Internal helpers exposed for testability + future reuse.
+  readActiveVersion,
+  listCacheVersions,
+  sortByMtimeDesc,
+};

package/lib/core/navigation/memory-events.cjs

@@ -47,13 +47,29 @@ const EVENT_TYPES = Object.freeze(new Set([
   //   fired (fingerprint detection -> spawn) -> finding_surfaced (drain -> F.1)
   //   -> user_response (Explore/Skip/Later/Free-text) OR skipped (suppression).
   //   brain_canon_drift_observed (FourLenses Brain vs FiveLenses Canon; emitted once per
-  //   session by 117-05 emitBrainCanonDrift via this EVENT_TYPES string; size 31 invariant).
+  //   session by 117-05 emitBrainCanonDrift via this EVENT_TYPES string).
+  // Size-invariant note: additive set; downstream phases extend (see the Phase 88.2-00,
+  // 89-07-00, 116-00, 117-00, 110-02 blocks). Tests assert a FLOOR + named membership,
+  // not an exact count -- so a future phase adding an event type cannot regress baseline.
   'auto_explore_fired',
   'auto_explore_finding_surfaced',
   'auto_explore_user_response',
   'auto_explore_skipped',
   'auto_explore_sanitizer_hit',
   'brain_canon_drift_observed',
+  // Phase 110-02 extension (Brain Context Packet Contract; D-07 + D-10 telemetry mirror):
+  //   brain_packet_rejected   -> an outbound packet failed in-schema validation in
+  //                              brain-client.sendPacket (reject hard -- thrown error).
+  //   brain_response_rejected -> a Brain response failed out-schema validation -> degraded
+  //                              soft, NOT ingested, no partial-ingest.
+  //   brain_legacy_path_used  -> the forward-looking deprecation guard fired (no current
+  //                              call site shipped in 110-02; see brain-client.cjs).
+  // Additive extension only; mirrors the Phase 116-00 5-tension-strings idiom and the
+  // 117-00 6-auto_explore-strings idiom. logEvent already rejects event_type values
+  // outside EVENT_TYPES -- so these are accepted only because they are now IN the Set.
+  'brain_packet_rejected',
+  'brain_response_rejected',
+  'brain_legacy_path_used',
 ]));
 
 function isPlainObject(v) {

package/lib/core/navigation/neighborhood.cjs

@@ -11,20 +11,20 @@
 // Canon Part 9: SELECT supersedes folder scanning; this is the load-bearing
 // query for the acceptance test.
 
-const NEIGHBORHOOD_SQL = "WITH RECURSIVE neighborhood(id, type, edge_path, depth, edge_type_in, last_seen_at, confidence, source_section, review_status, created_by, source_path) AS ( "
+const NEIGHBORHOOD_SQL = "WITH RECURSIVE neighborhood(id, type, edge_path, depth, edge_type_in, last_seen_at, created_at, confidence, source_section, review_status, created_by, source_path) AS ( "
   + "SELECT n.id, n.type, json_array(n.id) AS edge_path, 0 AS depth, NULL AS edge_type_in, "
-  + "n.last_seen_at, n.confidence, n.source_section, n.review_status, n.created_by, n.source_path "
+  + "n.last_seen_at, n.created_at, n.confidence, n.source_section, n.review_status, n.created_by, n.source_path "
   + "FROM nodes n WHERE n.id = :focus_node_id "
   + "UNION ALL "
   + "SELECT next_n.id, next_n.type, json_insert(nh.edge_path, '$[#]', next_n.id) AS edge_path, "
   + "nh.depth + 1 AS depth, e.type AS edge_type_in, "
-  + "next_n.last_seen_at, next_n.confidence, next_n.source_section, next_n.review_status, next_n.created_by, next_n.source_path "
+  + "next_n.last_seen_at, next_n.created_at, next_n.confidence, next_n.source_section, next_n.review_status, next_n.created_by, next_n.source_path "
   + "FROM neighborhood nh JOIN edges e ON e.source = nh.id JOIN nodes next_n ON next_n.id = e.target "
   + "WHERE nh.depth < :max_depth "
   + "AND json_array_length(nh.edge_path) < (:max_depth + 1) "
   + "AND nh.id != next_n.id "
   + ") "
-  + "SELECT id, type, edge_path, depth, edge_type_in, source_path, review_status, created_by, confidence, last_seen_at, "
+  + "SELECT id, type, edge_path, depth, edge_type_in, source_path, review_status, created_by, created_at, confidence, last_seen_at, "
   + "( "
   + "CASE edge_type_in "
   + "WHEN 'CONTRADICTS' THEN 1.0 "
@@ -70,6 +70,7 @@ function getNeighborhood(db, focusNodeId, opts) {
     sourcePath: r.source_path,
     reviewStatus: r.review_status,
     createdBy: r.created_by,
+    createdAt: r.created_at,
     confidence: r.confidence,
     lastSeenAt: r.last_seen_at,
   }));

package/lib/core/navigation/packet.cjs

@@ -9,12 +9,73 @@
 // Canon Part 9: builder produces the JS object; Phase 110 wraps with validateAndSendBrainPacket;
 // Phase 109 honors the privacy: 'no_raw_artifact_text' field by default in constraints.
 
+const fs = require('node:fs');
 const path = require('node:path');
 const crypto = require('node:crypto');
 const { getNeighborhood } = require('./neighborhood.cjs');
 const { findContradictions, findUnsupportedClaims, findRelevantOpportunities } = require('./insights.cjs');
 const { findRecentChanges } = require('./memory-events.cjs');
 
+// Phase 110-02 (D-03 + D-09): privacy-mode opt-up. local_summary_only is the default and
+// the only mode any of the 12 shipped Brain jobs ever requests (every $def.in.properties.privacy_mode
+// in data/brain-packet-schema.json is { const: 'local_summary_only' }). allow_filenames opts
+// up via .config.json preferences.brain_privacy_mode (project-level) or opts.privacyMode
+// (per-call); allow_excerpts ADDITIONALLY requires a Part-3 Decision Gate APPROVE-with-reason
+// row on the room graph tagged brain_excerpts -- there is NO shipped consumer of allow_excerpts
+// as of v1.13.0-beta.3, so it is a defined-but-unconsumed escape hatch. Config can only CAP
+// the mode, never RAISE what a job sends -- the schema's per-job const enforces this for free
+// in Phase 110-03 sendPacket.
+const PRIVACY_MODES = ['local_summary_only', 'allow_filenames', 'allow_excerpts'];
+
+function readRoomConfigPrivacyMode(roomDir) {
+  if (!roomDir) return null;
+  try {
+    const p = path.join(roomDir, '.config.json');
+    if (!fs.existsSync(p)) return null;
+    const cfg = JSON.parse(fs.readFileSync(p, 'utf8'));
+    const v = cfg && cfg.preferences && cfg.preferences.brain_privacy_mode;
+    return PRIVACY_MODES.includes(v) ? v : null;
+  } catch (_) {
+    return null;
+  }
+}
+
+// The Part-3 Decision Gate APPROVE row (Canon Part 3 + Part 4). The F.0 selector at
+// lib/hmi/shape-f0-renderer.cjs is the canonical render path that, when wired in a future
+// plan, writes the brain_excerpts-tagged APPROVE decision row that this helper looks for.
+// As of v1.13.0-beta.3 there is NO shipped consumer of allow_excerpts -- so this returns
+// false until a Part-3 gate is wired and the user approves. The query is a single guarded
+// SELECT against the local room graph (the same db handle buildBrainPacket already takes);
+// any error or absent row returns false so the resolver caps down safely.
+function roomHasExcerptApproval(db, roomDir) {
+  try {
+    if (!db) return false;
+    const row = db.prepare(
+      "SELECT 1 FROM nodes WHERE type IN ('decision','memory_event') " +
+      "AND review_status = 'confirmed' AND created_by = 'user' " +
+      "AND instr(properties, 'brain_excerpts') > 0 LIMIT 1"
+    ).get();
+    return !!row;
+  } catch (_) {
+    return false;
+  }
+}
+
+function resolvePrivacyMode(db, roomDir, opts) {
+  const options = opts || {};
+  const perCall = options.privacyMode;
+  const fromConfig = readRoomConfigPrivacyMode(roomDir);
+  const requested = (typeof perCall === 'string' && PRIVACY_MODES.includes(perCall))
+    ? perCall
+    : (fromConfig || 'local_summary_only');
+  if (requested === 'allow_excerpts' && !roomHasExcerptApproval(db, roomDir)) {
+    // Cap down per "config caps, never raises". If config said allow_filenames, keep it;
+    // otherwise drop to local_summary_only.
+    return fromConfig === 'allow_filenames' ? 'allow_filenames' : 'local_summary_only';
+  }
+  return requested;
+}
+
 function loadJtbd(roomDir, mocks) {
   if (mocks && mocks.jtbd) return mocks.jtbd;
   try { return require(path.resolve(__dirname, '..', '..', 'hmi', 'jtbd-state.cjs')); } catch (_) { return null; }
@@ -121,6 +182,11 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
   const options = opts || {};
   const mocks = options._mocks;
   const roomId = options.roomId || null;
+  const roomDir = options.roomDir || null;
+
+  // Phase 110-02: resolve the privacy mode BEFORE building the packet body so the resolved
+  // value is available on the top-level return object alongside packet_version and origin.
+  const privacyMode = resolvePrivacyMode(db, roomDir, options);
 
   // Active context. Mocks override the require() calls for hermetic tests.
   const jtbdMod = loadJtbd(null, mocks);
@@ -155,6 +221,16 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
     packet_version: '1.0',
     job,
     room_stage: getRoomStage(db),
+    // Phase 110-02 D-08 layer 1: stamp the navigation-API provenance origin. The schema's
+    // $defs.Origin enum constrains this to the closed set; brain-client.sendPacket (Phase
+    // 110-03) refuses any other value at wire time. defense-in-depth -- three layers (schema
+    // enum + pre-commit hook + sendPacket allowlist), no in-process nonce.
+    origin: 'navigation_api',
+    // Phase 110-02 D-09: top-level privacy_mode (one of D-03's 3 enum values; default
+    // local_summary_only). Separate from constraints.privacy (human-readable note) -- the
+    // schema's $defs.PrivacyMode enum + each job's $def.in.properties.privacy_mode const
+    // enforces "config caps, never raises" at the wire level in Phase 110-03 sendPacket.
+    privacy_mode: privacyMode,
     active_context: {
       jtbd: jtbdId,
       operator,
@@ -179,4 +255,14 @@ function buildBrainPacket(db, job, focusNodeId, opts) {
   };
 }
 
-module.exports = { buildBrainPacket, surface_banked_opportunities, shortText };
+module.exports = {
+  buildBrainPacket,
+  surface_banked_opportunities,
+  shortText,
+  // Phase 110-02 (D-09): exported so Phase 110-05 round-trip tests, future callers, and
+  // brain-client.sendPacket (110-03) can introspect / reuse the resolution order.
+  resolvePrivacyMode,
+  readRoomConfigPrivacyMode,
+  roomHasExcerptApproval,
+  PRIVACY_MODES,
+};

package/lib/core/navigation.cjs

@@ -57,4 +57,10 @@ module.exports = {
 
   // Truth-state chokepoint (Plan 109-04 LIVE).
   promoteNodeStatus: transitions.promoteNodeStatus,
+
+  // Memory-event logging (Phase 110-03 -- a thin re-export so brain-client.cjs can log the
+  //   brain_packet_rejected / brain_response_rejected / brain_legacy_path_used events without
+  //   reaching into the internal navigation/memory-events.cjs. The closed navigation surface is
+  //   the DOCUMENTED 13-function API; the implementation re-exports internal helpers as needed.)
+  logMemoryEvent: memoryEvents.logEvent,
 };

package/lib/core/resolve-brain-key.cjs

@@ -0,0 +1,201 @@
+'use strict';
+/*
+ * lib/core/resolve-brain-key.cjs -- the ONE resolver for "where is the Brain
+ * API key on this machine?" (Phase 123 Plan-07).
+ *
+ * Background: before this module, three different places guessed independently
+ * how to discover the Brain key (brain-client.cjs::getApiKey, session-start's
+ * shell test of MINDRIAN_BRAIN_KEY, brain-connector's skill detection). Three
+ * guessers, three failure modes -- a standard install with the key in
+ * ~/.mindrian.env was visible to brain-client but invisible to session-start,
+ * so a working HTTP-path Brain still printed a Tier-0 MCP warning. This
+ * collapses them into one source of truth. Mirrors active-plugin-root.cjs
+ * (the resolver this one is patterned on).
+ *
+ * Precedence (first hit wins) per D-31:
+ *   1. MINDRIAN_BRAIN_KEY env var     -- explicit operator intent, highest.
+ *   2. <home>/.mindrian.env           -- global backup, persists across CWDs.
+ *   3. <cwd>/.env                     -- project-local override.
+ *   4. not-found.
+ *
+ * IMPORTANT (FLAG-3 fix). The default for `home` is
+ *   process.env.HOME || process.env.USERPROFILE || os.homedir()
+ * -- NOT bare os.homedir(). On Linux/POSIX, os.homedir() reads /etc/passwd and
+ * IGNORES process.env.HOME, which breaks hermetic tests that override HOME to
+ * a scratch directory. The env-aware default matches the precedent in
+ * scripts/doctor.cjs, scripts/session-start, and lib/core/active-plugin-root.cjs.
+ *
+ * Returns { key, source, available, reason }:
+ *   - available=true:  key is the trimmed value, reason is null.
+ *   - available=false: key is null, reason is the explicit cause string
+ *                      (never a silent null -- SEC-02 rejections route here too).
+ *
+ * SEC-02 permission check (POSIX-only, no-op on Windows). When the resolved
+ * source is a key file (~/.mindrian.env or CWD .env), stat the mode. If any
+ * group or world bit is set (mode & 0o077), return available:false with the
+ * explicit reason "permissions too open: <path> is mode 0NNN, must be 0600".
+ *
+ * Use as a module:
+ *   const { resolveBrainKey } = require('<...>/lib/core/resolve-brain-key.cjs');
+ *   const r = resolveBrainKey();           // r.key, r.source, r.available, r.reason
+ *
+ * Use as a CLI (so scripts/session-start can shell out without a JSON parser
+ * in bash):
+ *   node lib/core/resolve-brain-key.cjs          -> prints JSON, exits 0
+ *
+ * Canon Part 8: this reads LOCAL files and env only. Zero network surface.
+ * The plan's verification grep against this file's source returns nothing
+ * -- no network markers in this resolver, ever. The actual Brain call is
+ * brain-client.cjs's job; this module only DISCOVERS whether a key exists.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+/**
+ * SEC-02 permission gate. POSIX-only -- on Windows POSIX mode bits do not
+ * translate to NTFS ACLs, so we return ok unconditionally there (a single
+ * stderr note would couple this resolver to a side-effect; the calling layer
+ * is the right place to surface that one-time note).
+ *
+ *   mode & 0o077 !== 0   =>   any group or world bit set   =>   reject.
+ *   0o600 / 0o400 pass; 0o644 / 0o664 / 0o666 fail.
+ *
+ * On stat failure (file vanished between exists() and stat() -- rare but
+ * possible) we treat it as not-ok with an explanatory reason rather than
+ * pretending the file is fine.
+ *
+ * @param {string} p   the file path
+ * @returns {{ok: boolean, reason: string|null}}
+ */
+function checkFilePermissions(p) {
+  if (process.platform === 'win32') {
+    return { ok: true, reason: null };
+  }
+  let stat;
+  try {
+    stat = fs.statSync(p);
+  } catch (e) {
+    return { ok: false, reason: 'unable to stat ' + p + ': ' + (e && e.code || String(e)) };
+  }
+  const mode = stat.mode & 0o777;
+  if ((mode & 0o077) !== 0) {
+    const modeStr = mode.toString(8).padStart(3, '0');
+    return {
+      ok: false,
+      reason: 'permissions too open: ' + p + ' is mode 0' + modeStr + ', must be 0600',
+    };
+  }
+  return { ok: true, reason: null };
+}
+
+/**
+ * Parse a single MINDRIAN_BRAIN_KEY=... line out of a (possibly multi-line)
+ * env-file body. Returns the trimmed value, or null if the line is absent or
+ * the value is empty. We deliberately do NOT use a full dotenv parser -- one
+ * variable, one regex, no transitive dependency.
+ *
+ * @param {string} body
+ * @returns {string|null}
+ */
+function _parseKey(body) {
+  const m = body.match(/^MINDRIAN_BRAIN_KEY\s*=\s*(.+?)\s*$/m);
+  if (!m) return null;
+  const v = m[1].trim();
+  return v.length > 0 ? v : null;
+}
+
+/**
+ * Resolve the Brain API key from the standard precedence chain.
+ *
+ * The `home` and `cwd` parameters exist as test seams. Their defaults match
+ * the precedent across the rest of the plugin (scripts/doctor.cjs, scripts/
+ * session-start, lib/core/active-plugin-root.cjs): env-aware home resolution
+ * so hermetic tests overriding process.env.HOME actually work on Linux/POSIX,
+ * where os.homedir() reads /etc/passwd and ignores the env override.
+ *
+ * @param {{home?: string, cwd?: string}} [opts]
+ * @returns {{key: string|null, source: 'env'|'mindrian-env-file'|'cwd-env-file'|'not-found', available: boolean, reason: string|null}}
+ */
+function resolveBrainKey(opts) {
+  const o = opts || {};
+  const home = o.home || process.env.HOME || process.env.USERPROFILE || os.homedir();
+  const cwd = o.cwd || process.cwd();
+
+  // (1) Env var wins.
+  if (process.env.MINDRIAN_BRAIN_KEY) {
+    const v = String(process.env.MINDRIAN_BRAIN_KEY).trim();
+    if (v.length > 0) {
+      return { key: v, source: 'env', available: true, reason: null };
+    }
+  }
+
+  // (2) <home>/.mindrian.env
+  const mindrianEnvPath = path.join(home, '.mindrian.env');
+  if (fs.existsSync(mindrianEnvPath)) {
+    const perms = checkFilePermissions(mindrianEnvPath);
+    if (!perms.ok) {
+      return { key: null, source: 'mindrian-env-file', available: false, reason: perms.reason };
+    }
+    try {
+      const body = fs.readFileSync(mindrianEnvPath, 'utf8');
+      const v = _parseKey(body);
+      if (v) {
+        return { key: v, source: 'mindrian-env-file', available: true, reason: null };
+      }
+    } catch (e) {
+      return {
+        key: null,
+        source: 'mindrian-env-file',
+        available: false,
+        reason: 'unable to read ' + mindrianEnvPath + ': ' + (e && e.code || String(e)),
+      };
+    }
+  }
+
+  // (3) <cwd>/.env
+  const cwdEnvPath = path.join(cwd, '.env');
+  if (fs.existsSync(cwdEnvPath)) {
+    const perms = checkFilePermissions(cwdEnvPath);
+    if (!perms.ok) {
+      return { key: null, source: 'cwd-env-file', available: false, reason: perms.reason };
+    }
+    try {
+      const body = fs.readFileSync(cwdEnvPath, 'utf8');
+      const v = _parseKey(body);
+      if (v) {
+        return { key: v, source: 'cwd-env-file', available: true, reason: null };
+      }
+    } catch (e) {
+      return {
+        key: null,
+        source: 'cwd-env-file',
+        available: false,
+        reason: 'unable to read ' + cwdEnvPath + ': ' + (e && e.code || String(e)),
+      };
+    }
+  }
+
+  // (4) not-found.
+  return {
+    key: null,
+    source: 'not-found',
+    available: false,
+    reason: 'MINDRIAN_BRAIN_KEY not set (env), and neither ' + mindrianEnvPath
+      + ' nor ' + cwdEnvPath + ' contains a MINDRIAN_BRAIN_KEY line',
+  };
+}
+
+module.exports = { resolveBrainKey, checkFilePermissions };
+
+// CLI entry point. session-start shells out via:
+//   node lib/core/resolve-brain-key.cjs
+// and parses the JSON. Exit 0 always (the consumer reads the JSON to learn
+// available/reason); a non-zero exit here would surface as "resolver failed"
+// rather than the clearer not-found / permissions-too-open branches.
+if (require.main === module) {
+  const r = resolveBrainKey();
+  process.stdout.write(JSON.stringify(r) + '\n');
+  process.exit(0);
+}