@mindrian_os/install 1.13.0-beta.16 → 1.13.0-beta.19

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

package/lib/core/navigation/edges.cjs

@@ -33,6 +33,41 @@ const ALLOWED_EDGE_TYPES = Object.freeze(new Set([
   // Phase 125 D7 -- F-selector decision edges (LOCKED LOCAL per Canon Part 8).
   'DEFERRED',
   'REJECTED',
+  // Phase 120-00 Wave 1 extension (Breakthrough Scan / Category G; D-18 HARD FLOOR enforcement
+  //   + D-20 Cypher-provable principle). DERIVED_FROM is the structural enforcement: a
+  //   Breakthrough node CANNOT surface without at least one DERIVED_FROM edge to an
+  //   Artifact node. Mirrors the Phase 125-00 DEFERRED + REJECTED additive idiom.
+  //
+  // Canon Part 4: every choice is graph data. The Breakthrough node + its DERIVED_FROM
+  //   edges are the graph-native artifact of pattern detection.
+  //
+  // Canon Part 8: writeEdge takes (db, params) over a LOCAL room.db handle; DERIVED_FROM
+  //   never crosses to Brain. Cross-room aggregation forbidden (Phase 8 cross-room fence).
+  //
+  // D-20 enforcement: lib/core/breakthrough/schema.cjs::writeBreakthrough wraps the
+  //   Breakthrough node insert + N DERIVED_FROM edge inserts in a single SQLite transaction.
+  //   If any step fails, the transaction rolls back -- partial Breakthrough state CANNOT
+  //   land. The Cypher invariant `MATCH (b:Breakthrough)-[:DERIVED_FROM]->(a:Artifact)
+  //   RETURN count(a)` is guaranteed >= 1 by construction.
+  'DERIVED_FROM',
+  // Phase 120-02 Wave 2 extension (Breakthrough Scan / Category G; D-09 file-as-decision
+  //   bridge). FILED_AS_DECISION is the typed edge that promotes a Breakthrough node into
+  //   the Phase 88 decision-log machinery when the user picks the [File as decision]
+  //   verb on F.7. Mirrors the Phase 120-00 DERIVED_FROM additive idiom verbatim.
+  //
+  // Canon Part 4: every choice is graph data. The Breakthrough -> Decision edge is the
+  //   graph-native bridge that lets future related breakthroughs reference the filed
+  //   decision via ENABLES edges (per CONTEXT.md D-15 "may be referenced as ENABLES in
+  //   future related breakthroughs").
+  //
+  // Canon Part 8: writeEdge takes (db, params) over a LOCAL room.db handle;
+  //   FILED_AS_DECISION never crosses to Brain. Cross-room aggregation forbidden.
+  //
+  // Emitted by: lib/core/breakthrough/verb-dispatch.cjs::handleFileAsDecision.
+  // The destination Decision node id is 'decision:' + breakthroughId by convention;
+  // Phase 88 decision-log machinery (or a future Phase 121 housekeeping pass) is
+  // responsible for materializing the Decision node body when one does not yet exist.
+  'FILED_AS_DECISION',
 ]));
 
 function isPlainObject(v) {

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

@@ -109,6 +109,132 @@ const EVENT_TYPES = Object.freeze(new Set([
   //   investment_level_at_decision}. NO cascade edge written (miss is temporal-only).
   //   Canon Part 8: user_intent stays LOCAL; never sent to Brain.
   'f_selector_miss',
+  // Phase 121.5-00 extension (SessionStart Coordinator: D-16 isolation + D-14 budget telemetry).
+  // Emitted by lib/sessionstart/contributor-isolator.cjs::runContributor on contributor failure
+  // and by scripts/sessionstart-coordinator.cjs::runAll on every coordinator pass.
+  //   sessionstart_contributor_failed -> a single contributor threw / validation-failed; coordinator
+  //                                      dropped it and continued. Payload: {contributor_id: <ladder id>,
+  //                                      error_class: <constructor name; enum-only>}. No stack, no
+  //                                      user content -- Canon Part 8 boundary preserved by the
+  //                                      isolator (stack lives in the LOCAL JSONL telemetry only).
+  //   sessionstart_coordinator_run    -> one envelope emitted; payload carries scalar counts
+  //                                      (fragments_total, fragments_compressed, fragments_dropped,
+  //                                      bytes_emitted). Scalars + enums only.
+  // Additive extension only; mirrors the Phase 110-02 / 116-00 / 117-00 / 124-02 / 125-01 / 125-06
+  // / 125-07 idiom verbatim. logEvent already rejects event_type values outside EVENT_TYPES.
+  'sessionstart_contributor_failed',
+  'sessionstart_coordinator_run',
+  // Phase 119-00 Wave 1 extension (Room-as-Receipt Invariant; D-01 + D-04 + D-06 telemetry mirror).
+  // Per CONTEXT.md Implementation Decisions D-01 + D-04 + D-06: the auto-create entrypoint
+  // (room_auto_created) fires synchronously inside scripts/auto-explore-fingerprint.cjs BEFORE
+  // the detached auto-explore-fire spawn so the spawned auto-explore output lands in a real
+  // room.db. The naming-decided + discarded events land in Plan 119-01.
+  //
+  // Additive extension; mirrors the Phase 124-02 2-string idiom and the Phase 117-00 6-string
+  // idiom. logEvent already rejects event_type values outside EVENT_TYPES -- so these are
+  // accepted only because they are now IN the Set. Set size grows by 3 (was 38 before Phase
+  // 119; now 41 baseline; coexists additively with any concurrent phase extension).
+  //
+  // Canon Part 9: SQL is the local mind; every choice is graph data. These three events are
+  // the canonical Part 10 sub-claim 3 ("rooms are receipts, not entry points") telemetry mirror.
+  'room_auto_created',
+  'room_naming_decided',
+  'room_discarded',
+  // Phase 119-01 Wave 2 extension (Room-as-Receipt Invariant; D-06 discard-cascade safety net).
+  // Per CONTEXT.md Architectural Decision item 4 (Claude's Discretion): the discard cascade
+  // is a SQLite transaction wrapping fs.rmSync + registry purge + memory_event emission.
+  // When the transaction fails partway (fs.rmSync raises EBUSY / EACCES, OR the registry
+  // purge fails non-atomically), the memory_event below lands so /mos:doctor can find
+  // orphaned rooms on next session-start.
+  //
+  // Additive extension only; mirrors the Plan 119-00 idiom verbatim. logEvent already
+  // rejects event_type values outside EVENT_TYPES -- so this is accepted only because
+  // it is now IN the Set. Set size grows by 1 (was 41 after Plan 119-00; now 42 baseline).
+  //
+  // Canon Part 9: SQL is the local mind; even partial failures become graph data so the
+  // recovery hook (/mos:doctor --orphaned-room-cleanup, deferred to v1.13.0 housekeeping)
+  // can scan + remediate.
+  'room_discard_partial_failure',
+  // Phase 120-00 Wave 1 extension (Breakthrough Scan / Category G; D-01..D-06 detector tier
+  // + D-09 file-as-decision bridge + D-10 mandatory dismiss + D-19 canary auto-throttle).
+  //
+  // Six strings; mirrors the Phase 119-00 3-string + 117-00 6-string + 124-02 2-string
+  // additive idiom. logEvent already rejects event_type values outside EVENT_TYPES -- so
+  // these are accepted only because they are now IN the Set. Set size grows by 6 (was 42
+  // baseline after Phase 119-01; now 48 baseline).
+  //
+  // Canon Part 10 sub-claim 5: variable reward fires automatically; the math IS the surface.
+  //   These six events are the canonical telemetry mirror for the breakthrough lifecycle:
+  //   soft-fire (buffer-only) -> hard-fire (surfaced) -> user response (confirm/dismiss/file)
+  //   -> canary auto-throttle (D-19 30%-over-100-fire-window static threshold).
+  //
+  // Canon Part 4: every choice is graph data. The breakthrough_filed_as_decision event is
+  //   the bridge to Phase 88 decision-log machinery -- promotes a breakthrough to a
+  //   first-class decision with audit trail.
+  //
+  // Canon Part 8: payloads carry scalar enums + framework names + sha256 hashes only;
+  //   theme strings are sanitized at write time per the Phase 90-06 sanitizeDetailScalar
+  //   precedent. Raw artifact content never lands in a memory_event.
+  'breakthrough_detected_soft',
+  'breakthrough_surfaced',
+  'breakthrough_confirmed',
+  'breakthrough_dismissed',
+  'breakthrough_filed_as_decision',
+  'breakthrough_throttled',
+  // Phase 120-02 Wave 2 additive extension (D-20 third structural enforcement
+  //   point: surfaceBreakthrough refuses provenance-less Breakthrough nodes at
+  //   surface time and emits this event for /mos:doctor traceability). Mirrors
+  //   the Phase 120-00 6-string additive idiom verbatim. logEvent already
+  //   rejects event_type values outside EVENT_TYPES -- so this is accepted only
+  //   because it is now IN the Set. Set size grows additively by 1.
+  //
+  // Canon Part 4: every choice is graph data -- the refusal itself is a typed
+  //   signal that an upstream caller attempted to bypass the D-20 invariant.
+  // Canon Part 8: pure LOCAL telemetry; no Brain coupling; payload carries
+  //   breakthrough_id + reason scalars only.
+  'breakthrough_surface_blocked',
+  // Phase 120-03 Wave 2 additive extension (D-18 SOFT_BAND review queue telemetry
+  //   mirror). Mirrors the Phase 120-02 1-string + Phase 120-00 6-string + 117-00
+  //   6-string + 124-02 2-string additive idiom verbatim. logEvent already rejects
+  //   event_type values outside EVENT_TYPES -- so this is accepted only because it
+  //   is now IN the Set. Set size grows additively by 1.
+  //
+  // Canon Part 4: every choice is graph data; the SOFT_BAND review queue is the
+  //   typed graph signal for D-18 mid-confidence candidates that the system queues
+  //   for manual sample-20% weekly review (becomes retraining data per CONTEXT.md).
+  // Canon Part 8: payload carries scalar enums (kind), numeric confidence, and the
+  //   queue_id handle; no raw artifact content lands in this event.
+  // Canon Part 9: ALL writes via navigation.cjs::logMemoryEvent chokepoint.
+  'breakthrough_in_review_queue',
+  // 260517-dcw dogfood-bridge extension (Canon Part 6 Product-as-Venture; D-04
+  //   dog-fooding mandate telemetry mirror). Six strings; mirrors the Phase 120-00
+  //   6-string + 117-00 6-string + 124-02 2-string + 110-02 3-string additive idiom.
+  //   logEvent already rejects event_type values outside EVENT_TYPES -- so these are
+  //   accepted only because they are now IN the Set. Set size grows by 6 (was 48
+  //   baseline after Phase 120-00; now 54 baseline).
+  //
+  // Canon Part 9 binding: SQL is the local mind; the plugin's own development
+  //   activity becomes graph data in the plugin's own venture room. Every Edit/
+  //   Write/MultiEdit on the plugin repo that matches the dog-food filter is a
+  //   file_changed event in ~/MindrianRooms/mindrian/room.db.
+  //
+  // Canon Part 8 binding: payloads carry the absolute path string (LOCAL data,
+  //   already on the local box; never sent to Brain), the tool name (enum scalar:
+  //   Edit / Write / MultiEdit), and the ISO timestamp. Zero user-content egress.
+  //
+  // Active emit site: scripts/dogfood-emit.cjs (file_changed only in this plan).
+  // Stub event types (no callers yet; reserved for future triggers per task_scope):
+  //   commit_landed       -> a git post-commit hook (future)
+  //   phase_completed     -> /gsd:phase-complete (future)
+  //   release_shipped     -> scripts/release.sh post-publish (future)
+  //   tester_signal       -> tester reply ingestion (future)
+  //   decision_captured   -> /mos:decide F.1 selector (future)
+  'file_changed',
+  'commit_landed',
+  'phase_completed',
+  'release_shipped',
+  'tester_signal',
+  'decision_captured',
 ]));
 
 function isPlainObject(v) {

package/lib/core/navigation.cjs

@@ -30,6 +30,7 @@ const packet = require('./navigation/packet.cjs');
 const ingestion = require('./navigation/ingestion.cjs');
 const roomHome = require('./navigation/room-home.cjs');
 const edges = require('./navigation/edges.cjs');
+const dashboardHelpers = require('./navigation/dashboard-helpers.cjs');
 
 function notImplementedYet(name, plan) {
   return function () {
@@ -88,4 +89,14 @@ module.exports = {
   //   116/117/118 will extend the allowlist additively for tension / auto-explore /
   //   MVA edges. Same additive-re-export pattern as logMemoryEvent + firstCapturedLastTouchedBySection.)
   writeEdge: edges.writeEdge,
+
+  // Dashboard MVA helpers (Phase 118 Plan 02 -- additive re-export so the
+  //   lib/agents/mva/dashboard-graph-neighborhood.cjs agent goes through the
+  //   navigation chokepoint per Canon Part 9 D-06 invariant. Same additive-
+  //   re-export pattern as logMemoryEvent / firstCapturedLastTouchedBySection /
+  //   writeEdge. detectActiveRoom mirrors scripts/brain-derive-command.cjs
+  //   line 142 verbatim; getRecentDecisionNeighborhood is a thin wrapper that
+  //   resolves the focus node + calls the existing getNeighborhood chokepoint.)
+  detectActiveRoom: dashboardHelpers.detectActiveRoom,
+  getRecentDecisionNeighborhood: dashboardHelpers.getRecentDecisionNeighborhood,
 };

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

@@ -0,0 +1,107 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-04 Plan 04 Task 1 -- resolve-vercel-key.
+ *
+ * The ONE resolver for "where is the Vercel deploy token on this machine?".
+ * Mirrors lib/core/resolve-brain-key.cjs (Phase 95.6 / Phase 123 Plan-07).
+ *
+ * Precedence per LD2 (Locked Decision 2 in 118-CONTEXT.md):
+ *   1. process.env.VERCEL_TOKEN      -- explicit operator intent, highest.
+ *   2. <home>/.mindrian.env          -- global backup, persists across CWDs.
+ *   3. <cwd>/.env                    -- project-local override.
+ *   4. null                          -- triggers local-file fallback path.
+ *
+ * Quote-stripping: handles both `VERCEL_TOKEN="abc"` (double-quoted) and
+ * `VERCEL_TOKEN=abc` (raw) per feedback_gmail_qp_env_var_corruption.md.
+ *
+ * Returns:
+ *   resolveVercelKey({home?, cwd?}) -> string | null
+ *
+ * Constants:
+ *   VERCEL_PROJECT_NAME = 'mindrianos-briefs'
+ *
+ * Canon Part 8: this module reads LOCAL files and env only. Zero network
+ * surface. The Vercel API call is mva-vercel-deploy.cjs's job; this module
+ * only DISCOVERS whether a token exists.
+ *
+ * No transitive runtime dependencies; node built-ins only.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+/** @type {string} The project name on Vercel where deck deploys live. */
+const VERCEL_PROJECT_NAME = 'mindrianos-briefs';
+
+/**
+ * Parse a single VERCEL_TOKEN=... line out of a (possibly multi-line) env-file
+ * body. Returns the trimmed value with surrounding double-quotes stripped, or
+ * null if the line is absent or the value is empty.
+ *
+ * @param {string} body
+ * @returns {string|null}
+ */
+function _parseKey(body) {
+  const m = body.match(/^VERCEL_TOKEN\s*=\s*(.+?)\s*$/m);
+  if (!m) return null;
+  let v = m[1].trim();
+  // Strip surrounding double-quotes if present
+  if (v.length >= 2 && v.startsWith('"') && v.endsWith('"')) {
+    v = v.slice(1, -1);
+  }
+  return v.length > 0 ? v : null;
+}
+
+/**
+ * Resolve the Vercel deploy token from the standard precedence chain.
+ *
+ * The `home` and `cwd` parameters exist as test seams (mirrors
+ * resolve-brain-key.cjs pattern). Env-aware home resolution so hermetic tests
+ * overriding process.env.HOME work on Linux/POSIX, where os.homedir() reads
+ * /etc/passwd and ignores the env override.
+ *
+ * @param {{home?: string, cwd?: string}} [opts]
+ * @returns {string|null}
+ */
+function resolveVercelKey(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.VERCEL_TOKEN) {
+    const v = String(process.env.VERCEL_TOKEN).trim();
+    if (v.length > 0) return v;
+  }
+
+  // (2) <home>/.mindrian.env
+  const mindrianEnvPath = path.join(home, '.mindrian.env');
+  if (fs.existsSync(mindrianEnvPath)) {
+    try {
+      const body = fs.readFileSync(mindrianEnvPath, 'utf8');
+      const v = _parseKey(body);
+      if (v) return v;
+    } catch (_e) { /* fall through */ }
+  }
+
+  // (3) <cwd>/.env
+  const cwdEnvPath = path.join(cwd, '.env');
+  if (fs.existsSync(cwdEnvPath)) {
+    try {
+      const body = fs.readFileSync(cwdEnvPath, 'utf8');
+      const v = _parseKey(body);
+      if (v) return v;
+    } catch (_e) { /* fall through */ }
+  }
+
+  // (4) not-found
+  return null;
+}
+
+module.exports = {
+  resolveVercelKey,
+  VERCEL_PROJECT_NAME,
+};

package/lib/core/resolve-vercel-key.test.cjs

@@ -0,0 +1,137 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 118-04 Plan 04 Task 1 -- resolve-vercel-key tests.
+ *
+ * Mirrors test patterns from lib/core/resolve-brain-key.cjs tests.
+ * Precedence per LD2: process.env.VERCEL_TOKEN -> <home>/.mindrian.env ->
+ * <cwd>/.env -> null.
+ *
+ * Quote-stripping: handles both `VERCEL_TOKEN="abc"` (double-quoted) and
+ * `VERCEL_TOKEN=abc` (raw) per feedback_gmail_qp_env_var_corruption.md.
+ *
+ * VERCEL_PROJECT_NAME is exported as the constant 'mindrianos-briefs'.
+ */
+'use strict';
+
+const test = require('node:test');
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+function _mkTmpHome() {
+  return fs.mkdtempSync(path.join(os.tmpdir(), 'mva-vercel-key-test-'));
+}
+
+function _cleanup(dir) {
+  try { fs.rmSync(dir, { recursive: true, force: true }); } catch (_e) { /* ignore */ }
+}
+
+// Force-reload module after env mutation
+function _freshRequire() {
+  const p = require.resolve('./resolve-vercel-key.cjs');
+  delete require.cache[p];
+  return require('./resolve-vercel-key.cjs');
+}
+
+test('Test 1: process.env.VERCEL_TOKEN takes precedence over file', () => {
+  const home = _mkTmpHome();
+  try {
+    fs.writeFileSync(path.join(home, '.mindrian.env'),
+      'VERCEL_TOKEN="from-file"\n', { mode: 0o600 });
+    const prev = process.env.VERCEL_TOKEN;
+    process.env.VERCEL_TOKEN = 'from-env';
+    try {
+      const { resolveVercelKey } = _freshRequire();
+      const r = resolveVercelKey({ home });
+      assert.equal(r, 'from-env');
+    } finally {
+      if (prev === undefined) { delete process.env.VERCEL_TOKEN; }
+      else { process.env.VERCEL_TOKEN = prev; }
+    }
+  } finally {
+    _cleanup(home);
+  }
+});
+
+test('Test 2: ~/.mindrian.env with quoted VERCEL_TOKEN resolves correctly', () => {
+  const home = _mkTmpHome();
+  try {
+    fs.writeFileSync(path.join(home, '.mindrian.env'),
+      'OTHER_VAR=ignore\nVERCEL_TOKEN="abc123"\n', { mode: 0o600 });
+    const prev = process.env.VERCEL_TOKEN;
+    delete process.env.VERCEL_TOKEN;
+    try {
+      const { resolveVercelKey } = _freshRequire();
+      const r = resolveVercelKey({ home, cwd: home });
+      assert.equal(r, 'abc123');
+    } finally {
+      if (prev !== undefined) process.env.VERCEL_TOKEN = prev;
+    }
+  } finally {
+    _cleanup(home);
+  }
+});
+
+test('Test 3: no env + no file = null', () => {
+  const home = _mkTmpHome();
+  try {
+    const prev = process.env.VERCEL_TOKEN;
+    delete process.env.VERCEL_TOKEN;
+    try {
+      const { resolveVercelKey } = _freshRequire();
+      const r = resolveVercelKey({ home, cwd: home });
+      assert.equal(r, null);
+    } finally {
+      if (prev !== undefined) process.env.VERCEL_TOKEN = prev;
+    }
+  } finally {
+    _cleanup(home);
+  }
+});
+
+test('Test 4: ~/.mindrian.env with unquoted VERCEL_TOKEN resolves correctly', () => {
+  const home = _mkTmpHome();
+  try {
+    fs.writeFileSync(path.join(home, '.mindrian.env'),
+      'VERCEL_TOKEN=raw-no-quotes\n', { mode: 0o600 });
+    const prev = process.env.VERCEL_TOKEN;
+    delete process.env.VERCEL_TOKEN;
+    try {
+      const { resolveVercelKey } = _freshRequire();
+      const r = resolveVercelKey({ home, cwd: home });
+      assert.equal(r, 'raw-no-quotes');
+    } finally {
+      if (prev !== undefined) process.env.VERCEL_TOKEN = prev;
+    }
+  } finally {
+    _cleanup(home);
+  }
+});
+
+test('Test 5: VERCEL_PROJECT_NAME exported constant === mindrianos-briefs', () => {
+  const { VERCEL_PROJECT_NAME } = _freshRequire();
+  assert.equal(VERCEL_PROJECT_NAME, 'mindrianos-briefs');
+});
+
+test('Test 5b: CWD .env fallback when ~/.mindrian.env absent', () => {
+  const home = _mkTmpHome();
+  const cwd = _mkTmpHome();
+  try {
+    fs.writeFileSync(path.join(cwd, '.env'),
+      'VERCEL_TOKEN="from-cwd-env"\n', { mode: 0o600 });
+    const prev = process.env.VERCEL_TOKEN;
+    delete process.env.VERCEL_TOKEN;
+    try {
+      const { resolveVercelKey } = _freshRequire();
+      const r = resolveVercelKey({ home, cwd });
+      assert.equal(r, 'from-cwd-env');
+    } finally {
+      if (prev !== undefined) process.env.VERCEL_TOKEN = prev;
+    }
+  } finally {
+    _cleanup(home);
+    _cleanup(cwd);
+  }
+});