@mindrian_os/install 1.13.0-beta.11

package/lib/core/reverse-salient-persona-suffix.cjs

@@ -0,0 +1,115 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 89-07 Wave 2 -- ReverseSalientAgent persona suffix.
+ *
+ * Maps Phase 115 USER.md role_blend -> persona-aware F.0 header suffix.
+ * 7 canonical role keys + 2 aliases + default fallback.
+ *
+ * Lex tie-break per Phase 115 D-AMEND-04 (agents/larry-extended.md lines 78-100):
+ *   1. Filter to canonical keys with positive numeric weight
+ *   2. Sort filtered keys alphabetically
+ *   3. Walk in sorted order, keep highest-weight; on ties, alphabetical earlier wins
+ *   4. Any error / no canonical match / all-zero weights -> default
+ *
+ * Editorial copy (SCOPE B Section 6 of 89-07-RESEARCH.md, confidence: LOW):
+ *   founder        -> 'shipping risk'
+ *   researcher     -> 'evidence gap'
+ *   researcher_ind -> 'evidence gap'        (functionally a researcher persona)
+ *   founder_grant  -> 'submission risk'     (grant-specific founder)
+ *   investor       -> 'thesis fragility'
+ *   operator       -> 'execution gap'
+ *   mentor         -> 'coaching wedge'
+ *   domain_expert  -> 'physical-reality friction'
+ *   student        -> 'understanding gap'
+ *   default        -> 'lagging component'
+ *
+ * Wording is tunable post-empathy-audit per RESEARCH Confidence: LOW caveat.
+ * Final copy is subject to revision after the beta.4 empathy audit, at which
+ * point both this module and any consumer test would be updated together.
+ *
+ * Pure CJS, zero dependencies, never throws.
+ */
+
+'use strict';
+
+// Frozen suffix map. 9 keys + default = 10 entries.
+const PERSONA_SUFFIX = Object.freeze({
+  founder:        'shipping risk',
+  researcher:     'evidence gap',
+  researcher_ind: 'evidence gap',
+  founder_grant:  'submission risk',
+  investor:       'thesis fragility',
+  operator:       'execution gap',
+  mentor:         'coaching wedge',
+  domain_expert:  'physical-reality friction',
+  student:        'understanding gap',
+  default:        'lagging component',
+});
+
+// Frozen canonical key list. Order is alphabetical (matches lex tie-break
+// expectation in tests). 9 canonical + 'default' = 10 entries.
+const CANONICAL_KEYS = Object.freeze([
+  'default',
+  'domain_expert',
+  'founder',
+  'founder_grant',
+  'investor',
+  'mentor',
+  'operator',
+  'researcher',
+  'researcher_ind',
+  'student',
+]);
+
+/**
+ * Pick the persona suffix string for a USER.md role_blend object.
+ *
+ * @param {object|null|undefined} roleBlend
+ *   { founder?: number, researcher?: number, ... } per Phase 115 schema.
+ * @returns {string} One of the PERSONA_SUFFIX values; 'lagging component' on
+ *                   any failure / cold-start / empty / all-zero / unknown-key.
+ */
+function suffixFor(roleBlend) {
+  try {
+    // Reject non-object, null, undefined, primitives.
+    if (roleBlend === null || roleBlend === undefined) return PERSONA_SUFFIX.default;
+    if (typeof roleBlend !== 'object') return PERSONA_SUFFIX.default;
+    // Arrays pass typeof === 'object' but their numeric-index keys never match
+    // CANONICAL_KEYS so they fall through to default. We document this rather
+    // than special-case Array.isArray(...) since the filter step handles it.
+
+    const keys = Object.keys(roleBlend);
+    if (keys.length === 0) return PERSONA_SUFFIX.default;
+
+    // Canonical-only candidates with positive numeric weight; lex tie-break by
+    // walking sorted keys (alphabetical earlier wins on ties because we keep
+    // strict > comparison and the earlier key was assigned first).
+    const canonicalSorted = keys
+      .filter((k) => CANONICAL_KEYS.indexOf(k) !== -1)
+      .sort();
+
+    let best = null;
+    let bestWeight = 0;
+    for (const k of canonicalSorted) {
+      const w = roleBlend[k];
+      if (typeof w === 'number' && Number.isFinite(w) && w > bestWeight) {
+        best = k;
+        bestWeight = w;
+      }
+    }
+    if (best === null || bestWeight <= 0) return PERSONA_SUFFIX.default;
+    // Reliability fence: if PERSONA_SUFFIX somehow lacks the canonical key
+    // (shouldn't be possible since CANONICAL_KEYS and PERSONA_SUFFIX are
+    // co-frozen at module load), fall through to default.
+    return PERSONA_SUFFIX[best] || PERSONA_SUFFIX.default;
+  } catch (_e) {
+    return PERSONA_SUFFIX.default;
+  }
+}
+
+module.exports = {
+  suffixFor: suffixFor,
+  PERSONA_SUFFIX: PERSONA_SUFFIX,
+  CANONICAL_KEYS: CANONICAL_KEYS,
+};

package/lib/core/room-classifier-strict-mode.cjs

@@ -0,0 +1,229 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ * (Business Source License 1.1; SPDX BUSL-1.1; see LICENSE.)
+ *
+ * Phase 94-06 -- Room classifier strict-mode override
+ *
+ * Pure-function detector that resolves three unambiguous user-input
+ * patterns directly to a registered room, bypassing the similarity
+ * heuristic in scripts/intent-classifier.cjs:
+ *
+ *   1. Numeric position    'switch to 8' or '8'              -> registry[N-1]
+ *   2. Explicit slug       'curriculum-redesign-fall-2026'    -> exact slug
+ *                          '/mos:rooms <slug>'
+ *   3. Quoted exact name   '"Beta"' / '"Curriculum Redesign"' -> name OR slug
+ *
+ * First match wins (numeric, then slug, then quoted). When NO pattern
+ * matches, returns null and the classifier falls through to its existing
+ * similarity heuristic. The override is forward-additive: similarity
+ * heuristic is unchanged.
+ *
+ * Canon Part 3 (10-verb vocabulary preserved): strict-mode is a routing
+ * OVERRIDE, not a new verb. The 10 canonical verbs in
+ * lib/core/navigation-engine-shared.cjs are untouched.
+ *
+ * Canon Part 4 (every choice is graph data): when the override fires,
+ * the caller emits a Section-8 decision-trace edge with
+ * routing_source: 'strict_mode' so /mos:explain-decision can attribute
+ * the resolution.
+ *
+ * Canon Part 7 (reuse before build): extends scripts/intent-classifier.cjs
+ * by composition (separate helper module imported by the classifier),
+ * NOT by replacing the existing similarity heuristic. The justification
+ * bar for net-new capability is met: strict-mode handles cases the
+ * similarity heuristic cannot disambiguate (numeric position has no
+ * token overlap; explicit slug should never be misrouted; quoted exact
+ * name is the user's clearest signal).
+ *
+ * Lawrence Aronhime reproducer fence (2026-04-28 38-min live test):
+ * with two rooms loaded ('core-power-isolation' +
+ * 'curriculum-redesign-fall-2026'), Lawrence's four utterances kept
+ * resolving to the WRONG room. Plan 94-06 fences callouts 1 (numeric),
+ * 2 (slug-form), and 4 (slash command) via this module. Callout 3
+ * ('the curriculum room', natural language) is known-deferred to
+ * v1.11.3 because it requires a natural-language intent layer.
+ *
+ * Pure CJS, zero npm deps. Never throws.
+ */
+'use strict';
+
+// ---------- Routing source constant ----------
+
+// Section-8 decision-trace edge value when this layer fires. Forward-
+// additive per Phase 91 invariant: existing routing_source values
+// ('engine' | 'legacy' | 'mixed' | 'classifier') are unaffected.
+const STRICT_MODE_ROUTING_SOURCE = 'strict_mode';
+
+// ---------- Pattern regexes ----------
+
+// Numeric: 'switch to 8' or '8' or 'go to 5' or 'jump to 3' or
+// 'move to 2'. Bounded to a small synonym set so we don't accidentally
+// match prose like 'jump 3 hoops' (no 'to' keyword).
+const NUMERIC_PATTERN = /^(?:(?:switch|go|jump|move)\s+to\s+)?(\d+)$/i;
+
+// Explicit slug: lowercase letters, digits, hyphens. 3-80 chars total.
+// Starts AND ends with alphanumeric (no leading/trailing hyphen).
+// Optional '/mos:rooms ' prefix to honor the canonical command form.
+const SLUG_PATTERN = /^(?:\/mos:rooms\s+)?([a-z0-9][a-z0-9-]{1,78}[a-z0-9])$/;
+
+// Quoted: any quoted span (single or double). The captured inner text
+// is the candidate room name OR slug.
+const QUOTED_PATTERN = /^['"]([^'"]+)['"]$/;
+
+// ---------- Registry parsing ----------
+
+/**
+ * parseRegistryRooms(reg) -> [{slug, name, path?}]
+ *
+ * Normalize the registry rooms field into a deterministic array of room
+ * records. Tolerates the array form, the object form, and the legacy
+ * string-only form. Preserves insertion order so 1-indexed numeric
+ * position is deterministic.
+ */
+function parseRegistryRooms(reg) {
+  if (!reg || !reg.rooms) return [];
+  const out = [];
+  if (Array.isArray(reg.rooms)) {
+    for (const r of reg.rooms) {
+      if (typeof r === 'string') {
+        out.push({ slug: r, name: r });
+      } else if (r && typeof r === 'object') {
+        const slug = (typeof r.slug === 'string' && r.slug)
+          ? r.slug
+          : (typeof r.name === 'string' ? r.name : null);
+        if (!slug) continue;
+        const name = (typeof r.name === 'string' && r.name) ? r.name : slug;
+        out.push({ slug: slug, name: name, path: r.path || null });
+      }
+    }
+    return out;
+  }
+  if (typeof reg.rooms === 'object') {
+    // Object form: keys are slugs; values are metadata objects. Order
+    // is the JSON insertion order (V8 preserves; per ES2015 spec for
+    // string keys). 1-indexed numeric position resolves to
+    // Object.keys(...)[N-1].
+    for (const slug of Object.keys(reg.rooms)) {
+      const meta = reg.rooms[slug];
+      const name = (meta && typeof meta.venture_name === 'string' && meta.venture_name)
+        ? meta.venture_name
+        : (meta && typeof meta.name === 'string' && meta.name ? meta.name : slug);
+      out.push({
+        slug: slug,
+        name: name,
+        path: (meta && typeof meta.path === 'string') ? meta.path : null,
+      });
+    }
+    return out;
+  }
+  return [];
+}
+
+// ---------- Strict-mode detector ----------
+
+/**
+ * detectStrictMode(prompt, registry) -> {slug, name, pattern, routing_source} | null
+ *
+ * Pure function. Tries the three strict-mode patterns in precedence
+ * order and returns the first match. Returns null when no pattern
+ * applies (caller falls through to similarity heuristic).
+ *
+ * Never throws. Defensive on registry shape (array OR object form).
+ *
+ * @param {string} prompt
+ * @param {object} registry
+ * @returns {{slug:string, name:string, pattern:string, routing_source:string} | null}
+ */
+function detectStrictMode(prompt, registry) {
+  if (typeof prompt !== 'string') return null;
+  const trimmed = prompt.trim();
+  if (!trimmed) return null;
+
+  const rooms = parseRegistryRooms(registry);
+  if (rooms.length === 0) return null;
+
+  // Pattern 1: numeric (1-indexed registry position).
+  const numMatch = trimmed.match(NUMERIC_PATTERN);
+  if (numMatch) {
+    const idx = parseInt(numMatch[1], 10) - 1;
+    if (idx >= 0 && idx < rooms.length) {
+      const r = rooms[idx];
+      return {
+        slug: r.slug,
+        name: r.name,
+        path: r.path,
+        pattern: 'numeric',
+        routing_source: STRICT_MODE_ROUTING_SOURCE,
+        input: prompt,
+      };
+    }
+    // Numeric pattern matched syntactically but index out of bounds.
+    // Return null so the similarity heuristic gets a turn.
+    return null;
+  }
+
+  // Pattern 2: explicit slug (case-sensitive against registry slugs).
+  const slugMatch = trimmed.match(SLUG_PATTERN);
+  if (slugMatch) {
+    const candidate = slugMatch[1];
+    for (const r of rooms) {
+      if (r.slug === candidate) {
+        return {
+          slug: r.slug,
+          name: r.name,
+          path: r.path,
+          pattern: 'slug',
+          routing_source: STRICT_MODE_ROUTING_SOURCE,
+          input: prompt,
+        };
+      }
+    }
+    // Pattern matched but slug not registered. Fall through to
+    // pattern 3 / similarity (do NOT short-circuit; the slug form
+    // may also be a quoted-or-natural-language input that happens
+    // to look slug-like).
+  }
+
+  // Pattern 3: quoted exact name OR slug. Single OR double quote span.
+  // Name match is case-insensitive; slug match is case-insensitive too
+  // (slugs in registry are lowercase by convention but user may type
+  // 'Curriculum-Redesign-Fall-2026' with title case).
+  const quoteMatch = trimmed.match(QUOTED_PATTERN);
+  if (quoteMatch) {
+    const candidate = quoteMatch[1];
+    const candidateLower = candidate.toLowerCase();
+    for (const r of rooms) {
+      if (r.slug === candidate
+        || (typeof r.name === 'string' && r.name === candidate)
+        || (typeof r.name === 'string' && r.name.toLowerCase() === candidateLower)
+        || r.slug.toLowerCase() === candidateLower) {
+        return {
+          slug: r.slug,
+          name: r.name,
+          path: r.path,
+          pattern: 'quoted',
+          routing_source: STRICT_MODE_ROUTING_SOURCE,
+          input: prompt,
+        };
+      }
+    }
+    // Pattern matched but no name/slug matches. Fall through.
+  }
+
+  return null;
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  detectStrictMode: detectStrictMode,
+  parseRegistryRooms: parseRegistryRooms,
+  STRICT_MODE_ROUTING_SOURCE: STRICT_MODE_ROUTING_SOURCE,
+  // Pattern regexes are exported for downstream tooling that wants to
+  // reuse the canonical patterns (e.g. /mos:explain-decision rendering
+  // or future natural-language layer that wants to disambiguate from
+  // strict-mode patterns).
+  NUMERIC_PATTERN: NUMERIC_PATTERN,
+  SLUG_PATTERN: SLUG_PATTERN,
+  QUOTED_PATTERN: QUOTED_PATTERN,
+};

package/lib/core/room-db.cjs

@@ -0,0 +1,127 @@
+'use strict';
+// Composition entry point for room.db. Phase 109 chains two idempotent migrations
+// after the existing schema init: nodes-provenance (Plan 109-01) then session_focus
+// (Plan 109-02).
+//
+// Phase 109-02 contract change (parallel-worktree merge surface):
+// openRoomDb is now SYNCHRONOUS and returns the bare node:sqlite DatabaseSync
+// handle (not the legacy { db, conn } async tuple). Pre-Phase-109 callers that
+// did `const handle = await openRoomDb(roomDir); handle.db.prepare(...)` need to
+// either:
+//   (a) drop the await and use the returned db directly, or
+//   (b) call the openGraph low-level API directly.
+// The async tuple shape was a leak from lazygraph-ops.cjs openGraph(); the
+// navigation API (Plan 109-04) and all 109-* helpers consume the bare db.
+// Plan 109-01's nodes-provenance migration was authored against the same
+// sync contract; the orchestrator merges both 109-01 and 109-02 worktrees
+// onto the same single-line migration chain shown below.
+//
+// Phase 109-06 addition: runtime soft-defense audit log per RESEARCH section 3.3.
+// When openRoomDb is called from outside the navigation/* allow-list, we append
+// one JSONL line to ~/.mindrian/telemetry/navigation-bypass.jsonl. Defensive
+// (never throws). LOCAL only (Canon Part 8). sha256-hashed room slug. Mirrors
+// Phase 88.1-16 query-efficiency telemetry pattern. Opt-out via env var
+// MINDRIAN_DISABLE_BYPASS_AUDIT=1.
+
+const path = require('node:path');
+const fs = require('node:fs');
+const os = require('node:os');
+const crypto = require('node:crypto');
+const { DatabaseSync } = require('node:sqlite');
+const lazygraph = require('./lazygraph-ops.cjs');
+const memory = require('./memory-ops.cjs');
+const { runMigration: runPhase109SessionFocus } = require('./migrations/phase-109-session-focus.cjs');
+
+// Plan 109-01 migration is loaded best-effort. In a parallel worktree where
+// 109-01 has not yet shipped, the require will throw MODULE_NOT_FOUND and we
+// fall back to the 109-02 migration's defensive ensureProvenanceColumns()
+// backfill (which is a strict subset of the 109-01 schema work). Once 109-01
+// merges, this loader resolves and the canonical migration runs first.
+let runPhase109NodesProvenance = null;
+try {
+  runPhase109NodesProvenance = require('./migrations/phase-109-nodes-provenance.cjs').runMigration;
+} catch (_e) {
+  // 109-01 not present in this worktree; 109-02 migration handles its own
+  // FK target schema needs additively.
+}
+
+// Phase 109-06 runtime soft-defense. Inspect Error().stack to find the first
+// frame outside this file. If that frame is NOT inside the navigation allow-list,
+// append one JSONL line to ~/.mindrian/telemetry/navigation-bypass.jsonl with
+// scalar fields only (timestamp, caller path, sha256 room hash). Defensive at
+// every step: try/catch swallow, stack-parse failures default to 'unknown'.
+function auditBypassIfNeeded(roomDir) {
+  if (process.env.MINDRIAN_DISABLE_BYPASS_AUDIT === '1') return;
+  let callerFile = 'unknown';
+  try {
+    const stack = (new Error()).stack.split('\n');
+    // Walk frames after the Error constructor. Skip any frame whose file is
+    // room-db.cjs itself (this function + openRoomDb wrapper).
+    for (let i = 1; i < Math.min(stack.length, 12); i++) {
+      const frame = stack[i];
+      // Match either '(path:line:col)' or 'at path:line:col' shapes.
+      const m = frame.match(/\(([^)]+):\d+:\d+\)/) || frame.match(/at\s+(.+):\d+:\d+/);
+      if (m && m[1] && !/room-db\.cjs$/.test(m[1])) {
+        callerFile = m[1];
+        break;
+      }
+    }
+  } catch (_) { /* swallow */ }
+  const normalized = callerFile.replace(/\\/g, '/');
+  // Allow-list mirrors the pre-commit hook list. No JSONL write for legitimate
+  // navigation/* + tests + migration scripts callers.
+  if (
+    normalized.includes('/lib/core/navigation/') ||
+    normalized.endsWith('/lib/core/navigation.cjs') ||
+    /[\\/]tests[\\/]/.test(callerFile) ||
+    /[\\/]scripts[\\/]migrate-/.test(callerFile) ||
+    /[\\/]lib[\\/]core[\\/]migrations[\\/]/.test(callerFile)
+  ) {
+    return;
+  }
+  try {
+    const dir = path.join(os.homedir(), '.mindrian', 'telemetry');
+    fs.mkdirSync(dir, { recursive: true });
+    const sha = crypto.createHash('sha256').update(String(roomDir || '')).digest('hex').slice(0, 16);
+    const line = JSON.stringify({ ts: Date.now(), caller: callerFile, room_hash: sha }) + '\n';
+    fs.appendFileSync(path.join(dir, 'navigation-bypass.jsonl'), line);
+  } catch (_) { /* never throw */ }
+}
+
+function openRoomDb(roomDir) {
+  // Soft-defense MUST be first so the caller is detected even when downstream
+  // schema init throws. Defensive (never throws) per Canon Part 8.
+  auditBypassIfNeeded(roomDir);
+  const resolved = path.resolve(roomDir);
+  const dbDir = path.join(resolved, '.mindrian');
+  const dbPath = path.join(dbDir, 'room.db');
+  fs.mkdirSync(dbDir, { recursive: true });
+  const db = new DatabaseSync(dbPath);
+  db.exec('PRAGMA journal_mode = WAL');
+  db.exec('PRAGMA foreign_keys = ON');
+  // Init lazygraph schema (nodes + edges + indices) sync via the same call
+  // the async wrapper makes internally.
+  lazygraph.initSchema(db);
+  // Init memory schema (identity / facts / sessions / fragments / assumptions / etc).
+  memory.initMemorySchema(db);
+  // Phase 109 migrations in order: nodes provenance first (109-01), then
+  // session_focus (109-02). Both are idempotent via identity sentinels.
+  if (runPhase109NodesProvenance) {
+    runPhase109NodesProvenance(db);
+  }
+  runPhase109SessionFocus(db);
+  return db;
+}
+
+function closeRoomDb(handle) {
+  // Tolerant: accept either bare DatabaseSync (current contract) or the legacy
+  // { db, conn } shape during the merge cycle.
+  const db = handle && handle.db ? handle.db : handle;
+  try {
+    db.close();
+  } catch (_e) {
+    // already closed; ignore
+  }
+}
+
+module.exports = { openRoomDb, closeRoomDb };

package/lib/core/room-ops-async.cjs

@@ -0,0 +1,92 @@
+/**
+ * MindrianOS Plugin -- Room Ops (ASYNC entry point)
+ * ==================================================
+ * execFile (promisified via util.promisify) variants of the public room-ops
+ * surface. Import this from MCP tool-router and any caller that returns a
+ * Promise to the MCP runtime.
+ *
+ * NEVER call from CLI scripts that expect synchronous semantics -- use
+ * room-ops-sync.cjs. Key-set parity between sync and async is enforced by
+ * lib/memory/sync-async-entry-points.test.cjs.
+ *
+ * Phase 87-04 sync/async split (CASCADE-06). Eliminates the MCP blocking
+ * I/O footgun: env branching inside a single module made it too easy to
+ * ship synchronous subprocess I/O into the MCP handler path on accident.
+ *
+ * License: BSL 1.1 (Business Source License 1.1) -- see LICENSE.
+ */
+
+'use strict';
+
+const path = require('path');
+const util = require('util');
+const { execFile } = require('child_process');
+const execFileAsync = util.promisify(execFile);
+const { discoverSections } = require('./section-registry.cjs');
+const { resolveRoom: resolveRoomShared } = require('./room-ops-shared.cjs');
+
+const SCRIPTS_DIR = path.resolve(__dirname, '../../scripts');
+
+/**
+ * List discovered sections with metadata (async).
+ * Wraps the pure synchronous discoverSections() call in an async shape for
+ * API symmetry with room-ops-sync.cjs.
+ * @param {string} roomDir - Path to room directory
+ * @returns {Promise<{ sections: Array, core_count: number, extended_count: number }>}
+ */
+async function listSections(roomDir) {
+  const resolved = path.resolve(roomDir);
+  const discovery = discoverSections(resolved);
+
+  const sections = discovery.all.map(name => {
+    const meta = discovery.getMeta(name);
+    return {
+      name,
+      type: meta.type,
+      label: meta.label,
+      color: meta.color,
+    };
+  });
+
+  return {
+    sections,
+    core_count: discovery.core.length,
+    extended_count: discovery.extended.length,
+  };
+}
+
+/**
+ * Run analyze-room script against a room directory (async).
+ * Uses execFile (promisified via util.promisify) rather than the blocking
+ * subprocess API, so the MCP handler loop stays non-blocking.
+ * @param {string} roomDir - Path to room directory
+ * @returns {Promise<string>} Raw script output
+ */
+async function analyzeRoom(roomDir) {
+  const resolved = path.resolve(roomDir);
+  const scriptPath = path.join(SCRIPTS_DIR, 'analyze-room');
+  try {
+    const { stdout } = await execFileAsync('bash', [scriptPath, resolved], {
+      timeout: 10000,
+      maxBuffer: 10 * 1024 * 1024,
+      encoding: 'utf-8',
+    });
+    return stdout;
+  } catch (e) {
+    throw new Error(`analyze-room failed: ${e.message}`);
+  }
+}
+
+/**
+ * Resolve the active room directory path (async wrapper around the pure
+ * shared implementation). Wrapped in an async function for signature parity
+ * with the other async exports and to keep the test's AsyncFunction assertion
+ * uniform across every exported function name.
+ * @param {string} workDir - Workspace root directory
+ * @returns {Promise<string|null>}
+ */
+async function resolveRoom(workDir) {
+  return resolveRoomShared(workDir);
+}
+
+module.exports = { listSections, analyzeRoom, resolveRoom };

package/lib/core/room-ops-shared.cjs

@@ -0,0 +1,64 @@
+/**
+ * MindrianOS Plugin -- Room Ops (shared pure logic)
+ * ==================================================
+ * Pure helpers with NO child_process I/O. Both room-ops-sync.cjs and
+ * room-ops-async.cjs import from this file. If you need to add a helper
+ * that calls execSync or execFile, put it in the sync or async entry
+ * point, not here.
+ *
+ * Phase 87-04 sync/async split (CASCADE-06). Eliminates the env-branching
+ * footgun (R4) by making the sync/async contract a require-time choice.
+ *
+ * License: BSL 1.1 (Business Source License 1.1) -- see LICENSE.
+ */
+
+'use strict';
+
+const path = require('path');
+const fs = require('fs');
+
+/**
+ * Trivial path helper kept here for symmetry with future shared utilities.
+ * Pure string/fs-path math; no I/O.
+ * @param {string} roomDir
+ * @returns {string}
+ */
+function resolveRoomPath(roomDir) {
+  return path.resolve(roomDir);
+}
+
+/**
+ * Resolve the active room directory path.
+ *
+ * Strategy 1: Read .rooms/registry.json and follow `active` -> rooms[active].path
+ * Strategy 2: Fall back to the legacy `room/` directory
+ *
+ * Pure fs + JSON logic, no child_process. Shared between sync and async
+ * entry points (both re-export this function under its original name).
+ *
+ * @param {string} workDir - Workspace root directory
+ * @returns {string|null} Absolute room path, or null if no room found
+ */
+function resolveRoom(workDir) {
+  const resolved = path.resolve(workDir);
+  const registryPath = path.join(resolved, '.rooms', 'registry.json');
+
+  // Strategy 1: Registry
+  if (fs.existsSync(registryPath)) {
+    try {
+      const reg = JSON.parse(fs.readFileSync(registryPath, 'utf8'));
+      if (reg.active && reg.rooms && reg.rooms[reg.active]) {
+        const roomPath = path.resolve(resolved, reg.rooms[reg.active].path);
+        if (fs.existsSync(roomPath)) return roomPath;
+      }
+    } catch (_e) { /* fall through to legacy */ }
+  }
+
+  // Strategy 2: Legacy
+  const legacy = path.join(resolved, 'room');
+  if (fs.existsSync(legacy)) return legacy;
+
+  return null;
+}
+
+module.exports = { resolveRoomPath, resolveRoom };