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

package/lib/core/resolve-active-room.cjs

@@ -0,0 +1,602 @@
+'use strict';
+/*
+ * lib/core/resolve-active-room.cjs -- the ONE resolver for "which room is
+ * active on this machine?" (Phase 127.3 Plan 00).
+ *
+ * Background: before this module, FOUR different places guessed independently
+ * (jtbd-update.cjs:65-79 hardcoded the legacy active_room+Array shape;
+ * intent-classifier.cjs:680-706 read the current active+Object shape correctly;
+ * memory-command.cjs:108-139 tolerated both; check-onboard-statusline.cjs and
+ * hmi-compliance-poll.cjs and jtbd-command.cjs and operator-command.cjs each
+ * carried independent copies). FOUR guessers, four failure modes -- the JTBD
+ * memory layer was silently dead in every release since v1.11.x because one
+ * of those guessers always returned null. This collapses them into one source
+ * of truth. Mirrors lib/core/resolve-brain-key.cjs (the resolver this one is
+ * patterned on; the Canon Part 7 precedent from Phase 123 Plan-07).
+ *
+ * Precedence (first hit wins):
+ *   1. CLAUDE_ACTIVE_ROOM env var       -- explicit test/operator override.
+ *   2. MINDRIAN_ROOMS_HOME/.rooms/registry.json `active` field (current shape).
+ *   3. MINDRIAN_ROOMS_HOME/.rooms/registry.json `active_room` field (legacy
+ *      shape, still tolerated for backward compat).
+ *   4. not-found.
+ *
+ * Returns { slug, abs_path } on hit, null on miss. NEVER throws -- callers
+ * depend on null-on-failure semantics (the graceful-degradation pattern
+ * shipped throughout the spine scripts).
+ *
+ * IMPORTANT (FLAG-3 fix). The default for the home directory 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, lib/core/active-plugin-root.cjs,
+ * and lib/core/resolve-brain-key.cjs.
+ *
+ * Sealed/archived disposition: entry.sealed === true OR entry.status ===
+ * 'sealed' OR entry.status === 'archived' returns null. The resolver does NOT
+ * surface non-active rooms even if they are the registry's nominal active
+ * slug -- the registry's job is to mark them, this resolver's job is to
+ * honor the mark.
+ *
+ * abs_path resolution: prefer entry.abs_path if set, else entry.path
+ * (resolved relative against home), else compose <home>/<slug>. Final gate:
+ * fs.existsSync(abs_path) -- if the directory does not exist on disk, return
+ * null (a registry pointing at a deleted directory is a stale registry).
+ *
+ * Use as a module:
+ *   const { resolveActiveRoom } = require('<...>/lib/core/resolve-active-room.cjs');
+ *   const r = resolveActiveRoom();      // r.slug, r.abs_path   OR   null
+ *
+ * Use as a CLI (so bash wrappers can shell out without a JSON parser):
+ *   node lib/core/resolve-active-room.cjs    -> prints JSON, exits 0 on hit, 1 on miss.
+ *
+ * The exit-code distinction is intentional. resolve-brain-key.cjs exits 0
+ * always (its result has more nuanced fields like reason+source); this
+ * resolver's null-or-object shape maps cleanly to exit-code semantics.
+ *
+ * Canon Part 8: this reads LOCAL files and env only. Zero network surface.
+ * The structural source-grep tripwire in tests/test-resolve-active-room-canonical.cjs
+ * (rar.11) asserts this invariant on every CI run.
+ *
+ * Canon Part 9: this is a READ-only registry resolver. It does NOT open the
+ * per-room SQLite graph (that is the navigation chokepoint's domain).
+ * Calling-side code that needs a graph read must go through the navigation
+ * chokepoint AFTER resolving the room dir here. The structural source-grep
+ * tripwire in tests/test-resolve-active-room-canonical.cjs (rar.12) asserts
+ * this invariant on every CI run by scanning this file for the forbidden
+ * SQLite-driver and graph-chokepoint tokens.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+/**
+ * readRegistry(home) -> parsed registry object, or null.
+ * Missing file / malformed JSON both collapse to null (never throws) so every
+ * caller keeps the null-on-failure contract.
+ *
+ * @param {string} home
+ * @returns {object|null}
+ */
+function readRegistry(home) {
+  try {
+    const regPath = path.join(home, '.rooms', 'registry.json');
+    if (!fs.existsSync(regPath)) return null;
+    const reg = JSON.parse(fs.readFileSync(regPath, 'utf8'));
+    return (reg && typeof reg === 'object') ? reg : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * registryRoomPath(home, slug, reg) -> abs_path string, or null.
+ *
+ * The ONE slug -> directory derivation (Canon Part 7). Precedence:
+ * entry.abs_path -> entry.path (resolved against home when relative) ->
+ * <home>/<slug>. Final gate: the directory must exist on disk.
+ *
+ * RCA resolve-active-room-cross-session-bleed (D2): before this helper existed,
+ * resolveWriteRoom's leg 2 derived the bound room's directory as the bare
+ * path.join(home, primary). That is FALSE for every SUB-room, whose registry
+ * `path` is nested (e.g. motj-ecosystem/sub-rooms/jonathan-contractor-motj).
+ * The existsSync gate then failed and leg 2 fell through to leg 3 -- so a
+ * session correctly bound to a sub-room silently resolved to the machine-wide
+ * reg.active instead, which is the cross-session bleed itself. resolveActiveRoom
+ * already did this derivation correctly; extracting it here gives leg 2 the SAME
+ * correct derivation rather than a fifth independent guess (the SEED-034
+ * four-guessers lesson).
+ *
+ * Sealed/archived disposition is deliberately NOT applied here -- it is the
+ * caller's policy. resolveActiveRoom gates on it before calling; leg 2 keeps its
+ * documented exists-on-disk-only contract.
+ *
+ * NEVER throws.
+ *
+ * @param {string} home
+ * @param {string} slug
+ * @param {object} [reg] - a pre-read registry (avoids a second file read)
+ * @returns {string|null}
+ */
+function registryRoomPath(home, slug, reg) {
+  try {
+    if (typeof slug !== 'string' || slug.length === 0) return null;
+    const registry = (reg && typeof reg === 'object') ? reg : readRegistry(home);
+
+    let entry = null;
+    if (registry) {
+      if (Array.isArray(registry.rooms)) {
+        entry = registry.rooms.find(function (r) {
+          return r && (r.slug === slug || r.name === slug);
+        }) || null;
+      } else if (registry.rooms && typeof registry.rooms === 'object') {
+        entry = registry.rooms[slug] || null;
+      }
+    }
+
+    let abs_path;
+    if (entry && typeof entry.abs_path === 'string' && entry.abs_path.length > 0) {
+      abs_path = entry.abs_path;
+    } else if (entry && typeof entry.path === 'string' && entry.path.length > 0) {
+      abs_path = path.isAbsolute(entry.path) ? entry.path : path.join(home, entry.path);
+    } else {
+      // No entry, or an entry with no location: fall back to the flat default.
+      // An unregistered-but-present directory still resolves, which preserves
+      // leg 2's pre-existing behavior for a binding the registry does not know.
+      abs_path = path.join(home, slug);
+    }
+
+    if (!fs.existsSync(abs_path)) return null;
+    return abs_path;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/*
+ * OWNERSHIP OF reg.active (RCA registry-active-session-unbound-inheritance).
+ *
+ * reg.active is a single machine-wide slug. An UNBOUND session inheriting it is
+ * correct for the tier-0 single-session user (Decision #8) and WRONG when a
+ * different, concurrently-live session set it seconds ago. A bare "does
+ * active_session equal my session id" test cannot separate those two: a fresh
+ * unbound session never wrote `active`, so the match is always false and the
+ * check silently degrades into "never inherit" -- which kills the card for every
+ * user who never binds.
+ *
+ * The separating signal is LIVENESS OF THE SETTER, and it needs no new
+ * infrastructure. The only writer of `reg.active` (scripts/room-registry
+ * set-active / create) runs inside the owning session's own process tree, so it
+ * already has both halves in its environment: CLAUDE_CODE_SESSION_ID (the same
+ * UUID the hook reader resolves) and CLAUDE_PID (the `claude` CLI process, which
+ * lives exactly as long as the session). Recording them beside `active` makes
+ * registry.json its own liveness record, and the reader gets a THREE-way answer:
+ *
+ *   unowned      -- no active_session field (a pre-upgrade registry, or a
+ *                   set-active run outside a session). Today's behavior.
+ *   self         -- I set it. Inherit.
+ *   stale        -- someone else set it, and that process is gone. Inherit.
+ *                   This is the tier-0 restart case: quit Claude Code, reopen,
+ *                   new unbound session, old pid dead -> inherit exactly as before.
+ *   foreign-live -- someone else set it AND their process is still running.
+ *                   Do NOT inherit. This is the bleed.
+ *
+ * Every uncertain path resolves to inheritable:true, so the tier-0 promise holds
+ * by construction: no session id, no ownership fields, no pid, an unprobeable
+ * pid, an unparseable timestamp, or any thrown error all reproduce today's
+ * behavior exactly. Only a positively-proven live foreign owner declines.
+ */
+
+// Fail-open ceiling on the pid probe, NOT a liveness window. A pid can be
+// recycled by the OS; beyond this age the probe is no longer trustworthy
+// evidence of the ORIGINAL process, so ownership degrades to `stale` and the
+// reader inherits (today's behavior). Deliberately generous: real sessions run
+// for many hours, and a long-running owner must keep being recognised as live.
+// This is NOT a frozen-family scalar (MAX_K / DIAL_REACH_K / 0.70 / 0.15 are
+// untouched).
+const OWNERSHIP_MAX_AGE_MS = 86400000; // 24h
+
+/**
+ * ownerProcessAlive(pid) -> boolean. Composes session-presence.cjs's shipped
+ * `isAlive` (process.kill(pid, 0), itself cloned from write-lock.cjs) rather
+ * than minting a fifth copy of the probe (Canon Part 7, the SEED-034
+ * four-guessers lesson). Only that ONE primitive is reused; the module's
+ * per-room presence LEDGER stays out of this path (it is per-room, so it could
+ * never answer "is the session that set reg.active still live").
+ *
+ * A probe that cannot run returns FALSE, which routes to `stale` ->
+ * inheritable -> today's behavior. Never throws.
+ *
+ * @param {number|null} pid
+ * @returns {boolean}
+ */
+function ownerProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    const presence = require('./session-presence.cjs');
+    return presence.isAlive(pid) === true;
+  } catch (_e) {
+    // Cannot probe -> fail OPEN (not live -> inheritable).
+    return false;
+  }
+}
+
+/**
+ * resolveActiveOwnership -- who set reg.active, and are they still here?
+ *
+ * Returns { state, owner, pid, at, inheritable }. `state` is one of
+ * 'unowned' | 'override' | 'anonymous-reader' | 'self' | 'stale' | 'foreign-live'.
+ * `inheritable` is false ONLY for 'foreign-live'. NEVER throws.
+ *
+ * Canon Part 8/9: reads registry.json and probes a local pid. Zero network,
+ * zero graph surface.
+ *
+ * @param {{sessionId?: string, home?: string, reg?: object, now?: number}} [opts]
+ * @returns {{state: string, owner: string|null, pid: number|null, at: string|null, inheritable: boolean}}
+ */
+function resolveActiveOwnership(opts) {
+  const unowned = { state: 'unowned', owner: null, pid: null, at: null, inheritable: true };
+  try {
+    const o = opts || {};
+    const home = o.home || process.env.MINDRIAN_ROOMS_HOME
+      || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+
+    // An explicit CLAUDE_ACTIVE_ROOM override outranks the registry in
+    // resolveActiveRoom, so it must outrank ownership too: an operator or a
+    // hermetic test that pins the room is never second-guessed.
+    if (process.env.CLAUDE_ACTIVE_ROOM) {
+      const v = String(process.env.CLAUDE_ACTIVE_ROOM).trim();
+      if (v.length > 0 && fs.existsSync(v)) {
+        return { state: 'override', owner: null, pid: null, at: null, inheritable: true };
+      }
+    }
+
+    const reg = (o.reg && typeof o.reg === 'object') ? o.reg : readRegistry(home);
+    if (!reg) return unowned;
+
+    const owner = (typeof reg.active_session === 'string' && reg.active_session.length > 0)
+      ? reg.active_session
+      : null;
+    // No ownership recorded: a pre-upgrade registry, or a set-active run outside
+    // any session. Byte-identical to pre-fix behavior (the backward-compat floor).
+    if (!owner) return unowned;
+
+    const rawPid = reg.active_session_pid;
+    let pid = null;
+    if (Number.isInteger(rawPid) && rawPid > 0) {
+      pid = rawPid;
+    } else if (typeof rawPid === 'string' && /^[0-9]+$/.test(rawPid)) {
+      const parsed = parseInt(rawPid, 10);
+      if (Number.isInteger(parsed) && parsed > 0) pid = parsed;
+    }
+    const at = (typeof reg.active_session_at === 'string' && reg.active_session_at.length > 0)
+      ? reg.active_session_at
+      : null;
+
+    const sessionId = (typeof o.sessionId === 'string' && o.sessionId.length > 0)
+      ? o.sessionId
+      : null;
+    // A reader with no identity cannot claim the value is foreign. Fail open.
+    if (!sessionId) {
+      return { state: 'anonymous-reader', owner: owner, pid: pid, at: at, inheritable: true };
+    }
+    if (sessionId === owner) {
+      return { state: 'self', owner: owner, pid: pid, at: at, inheritable: true };
+    }
+
+    // Pid-recycle ceiling (see OWNERSHIP_MAX_AGE_MS).
+    const nowMs = Number.isFinite(o.now) ? o.now : Date.now();
+    const atMs = at ? Date.parse(at) : NaN;
+    if (Number.isFinite(atMs) && (nowMs - atMs) > OWNERSHIP_MAX_AGE_MS) {
+      return { state: 'stale', owner: owner, pid: pid, at: at, inheritable: true };
+    }
+
+    if (!ownerProcessAlive(pid)) {
+      return { state: 'stale', owner: owner, pid: pid, at: at, inheritable: true };
+    }
+    return { state: 'foreign-live', owner: owner, pid: pid, at: at, inheritable: false };
+  } catch (_e) {
+    // Defense in depth: an ownership fault must never cost a session its room.
+    return unowned;
+  }
+}
+
+/**
+ * Resolve the active room from the precedence chain. Returns
+ *   { slug: string, abs_path: string }   on hit
+ *   null                                  on miss
+ * NEVER throws -- the top-level try/catch returns null on any unexpected
+ * error. Callers across the spine (jtbd-update, intent-classifier,
+ * memory-command, jtbd-command, operator-command, hmi-compliance-poll,
+ * check-onboard-statusline) all expect this null-on-failure shape.
+ *
+ * The `home` opt is a test seam; default is the env-aware form (FLAG-3
+ * landmine; bare os.homedir() reads /etc/passwd on Linux and ignores
+ * process.env.HOME, breaking hermetic mkdtempSync-based fixtures).
+ *
+ * @param {{home?: string}} [opts]
+ * @returns {{slug: string, abs_path: string}|null}
+ */
+function resolveActiveRoom(opts) {
+  try {
+    const o = opts || {};
+    const home = o.home || process.env.MINDRIAN_ROOMS_HOME
+      || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+
+    // (1) CLAUDE_ACTIVE_ROOM env override beats registry. The env value is
+    // expected to be an absolute directory path; slug is derived from
+    // basename. Operators and hermetic tests rely on this seam.
+    if (process.env.CLAUDE_ACTIVE_ROOM) {
+      const v = String(process.env.CLAUDE_ACTIVE_ROOM).trim();
+      if (v.length > 0 && fs.existsSync(v)) {
+        return { slug: path.basename(v), abs_path: v };
+      }
+    }
+
+    // (2) + (3) Registry.json -- support both legacy (active_room) and
+    // current (active) field names for the active slug.
+    const reg = readRegistry(home);
+    if (!reg) return null;
+
+    const slug = (typeof reg.active === 'string' && reg.active.length > 0)
+      ? reg.active
+      : (typeof reg.active_room === 'string' && reg.active_room.length > 0)
+      ? reg.active_room
+      : null;
+    if (!slug) return null;
+
+    // Support both Array form (legacy) and Object form (current) for the
+    // rooms field. Object lookup is O(1) via reg.rooms[slug]; Array lookup
+    // matches on .slug or .name.
+    let entry = null;
+    if (Array.isArray(reg.rooms)) {
+      entry = reg.rooms.find(function (r) {
+        return r && (r.slug === slug || r.name === slug);
+      }) || null;
+    } else if (reg.rooms && typeof reg.rooms === 'object') {
+      entry = reg.rooms[slug] || null;
+    }
+    if (!entry) return null;
+
+    // Sealed/archived disposition. The registry's job is to mark; this
+    // resolver's job is to honor the mark.
+    if (entry.sealed === true) return null;
+    if (entry.status === 'sealed' || entry.status === 'archived') return null;
+
+    // Resolve room directory through the ONE shared derivation (abs_path ->
+    // path -> default <home>/<slug>), which also applies the final
+    // exists-on-disk gate. A registry pointing at a deleted directory is
+    // stale; surface null rather than a phantom path.
+    const abs_path = registryRoomPath(home, slug, reg);
+    if (!abs_path) return null;
+
+    return { slug: slug, abs_path: abs_path };
+  } catch (_e) {
+    // Defense-in-depth: NEVER throw. The spine scripts treat null as
+    // "no active room; silently exit" -- a throw here would break that.
+    return null;
+  }
+}
+
+/**
+ * resolveWriteRoom -- the ONE session-aware WRITE precedence (PSB-02, PSB-15,
+ * D-02). Both write-guards (the intent-classifier tripwire and the
+ * write-scope-check middleware) inherit their write-target resolution from
+ * THIS function, so session precedence lives in exactly one place (the
+ * SEED-034 four-guessers lesson: do NOT add a second resolver).
+ *
+ * Precedence (first hit wins):
+ *   Leg 1 -- `.room-root` walk-up from filePath (room-root.cjs resolveRoomRoot):
+ *            a file physically inside a room ROOT writes to THAT room, no matter
+ *            what the session or registry says. source:'room-root'.
+ *   Leg 2 -- session.primary (session-binding.cjs readSessionBinding): the
+ *            per-session default write target, but ONLY when that room exists on
+ *            disk (a primary pointing at a deleted/never-created room falls
+ *            through, never returns a dead room). source:'session.primary'.
+ *   Leg 3 -- reg.active DEMOTED (resolveActiveRoom): the fresh-session
+ *            seed-default. reg.active is no longer the write AUTHORITY for a
+ *            bound session (PSB-15); it is reached only when no `.room-root`
+ *            wins and the session is unbound. source:'reg.active'.
+ *
+ * Returns { slug, abs_path, source } on hit, null on total miss. NEVER throws:
+ * a failure in any leg falls through to the next (mirrors resolveActiveRoom's
+ * never-throw discipline). Additive -- this does NOT change resolveActiveRoom's
+ * own precedence or signature.
+ *
+ * Canon Part 8/9: this reads only the LOCAL filesystem session/registry files.
+ * It requires room-root.cjs and session-binding.cjs (both pure-fs modules); it
+ * introduces zero SQLite driver and zero graph-chokepoint token, so the
+ * rar.11/rar.12 source-grep tripwires stay green.
+ *
+ * @param {{filePath?: string, sessionId?: string, home?: string}} [opts]
+ * @returns {{slug: string, abs_path: string, source: string}|null}
+ */
+function resolveWriteRoom(opts) {
+  const o = opts || {};
+  const filePath = o.filePath;
+  const sessionId = o.sessionId;
+  const home = o.home || process.env.MINDRIAN_ROOMS_HOME
+    || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+
+  // Leg 1: a `.room-root` sentinel above the file wins over everything.
+  try {
+    const roomRoot = require('./room-root.cjs');
+    const rootDir = roomRoot.resolveRoomRoot(filePath);
+    if (typeof rootDir === 'string' && rootDir.length > 0) {
+      return { slug: path.basename(rootDir), abs_path: rootDir, source: 'room-root' };
+    }
+  } catch (_e) { /* leg 1 failed -- fall through to session.primary */ }
+
+  // Legs 2 + 3 are the SESSION-SCOPED precedence, implemented once in
+  // resolveSessionRoom and shared with the hook consumers (Canon Part 7).
+  return resolveSessionRoom({ sessionId: sessionId, home: home });
+}
+
+/**
+ * resolveSessionRoom -- the ONE session-scoped READ resolver: "which room does
+ * THIS session belong to?" (RCA resolve-active-room-cross-session-bleed, D1).
+ *
+ * Precedence (first hit wins):
+ *   Leg A -- session.primary (session-binding.cjs readSessionBinding), resolved
+ *            to its REAL directory through registryRoomPath so a SUB-room
+ *            binding resolves correctly. source:'session.primary'.
+ *   Leg B -- reg.active (resolveActiveRoom), the fresh-session seed-default for
+ *            a genuinely UNBOUND session. source:'reg.active'.
+ *
+ * OPT-IN ownership gate (RCA registry-active-session-unbound-inheritance): pass
+ * `requireOwnership: true` and leg B additionally refuses to inherit a reg.active
+ * that a DIFFERENT, still-live session set (see resolveActiveOwnership). It
+ * defaults FALSE on purpose. resolveWriteRoom and the 9 MCP tool modules keep
+ * calling this with the flag OFF, so their behavior is byte-identical and the
+ * write path carries zero blast radius; only the F.1 reach-card consumer -- the
+ * site the RCA identifies as THE bleed (card header_room + decision-trace write
+ * location) -- opts in. A caller that opts in MUST treat a null return as a
+ * deliberate DECLINE and must not fall back to the machine-wide value, or the
+ * gate is a no-op.
+ *
+ * This is resolveWriteRoom's legs 2+3 with leg 1 (the `.room-root` walk-up)
+ * deliberately EXCLUDED. That matters: resolveWriteRoom's leg 1 answers "where
+ * does THIS FILE belong", and with no filePath it silently walks up from
+ * process.cwd(). A hook that only wants "which room is this session in" must
+ * not inherit a cwd-derived answer, so it calls THIS function instead of
+ * resolveWriteRoom({}) -- same shared implementation, no accidental leg-1 leak.
+ *
+ * Why this exists at all: scripts/intent-classifier.cjs resolved the room for
+ * the F.1 navigation-engine block and the F.8 / zero-score gate state via the
+ * MACHINE-WIDE resolveActiveRoomDir(). With several concurrent CLI sessions on
+ * one machine, every session therefore rendered its Decision Gate cards -- and
+ * wrote its decision traces -- against whichever room another session last
+ * activated. This is a DIFFERENT defect from the c123f3d7 fix: that one repaired
+ * the WRITER (room_bind could not persist session.primary on stdio); this one is
+ * a READER that never consulted the session-aware precedence at all.
+ *
+ * Returns { slug, abs_path, source } on hit, null on total miss. NEVER throws.
+ * Canon Part 8/9: LOCAL filesystem reads only, zero network, zero graph token.
+ *
+ * @param {{sessionId?: string, home?: string, requireOwnership?: boolean}} [opts]
+ * @returns {{slug: string, abs_path: string, source: string}|null}
+ */
+function resolveSessionRoom(opts) {
+  const o = opts || {};
+  const sessionId = o.sessionId;
+  const home = o.home || process.env.MINDRIAN_ROOMS_HOME
+    || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+
+  // Leg A: session.primary, but only when the room exists on disk. A primary
+  // naming a non-existent room (or the reserved no-room sentinel) falls through
+  // rather than resolving to a dead directory.
+  try {
+    const sessionBinding = require('./session-binding.cjs');
+    const binding = sessionBinding.readSessionBinding(sessionId, { home: home });
+    const primary = (binding && typeof binding.primary === 'string' && binding.primary.length > 0)
+      ? binding.primary
+      : null;
+    if (primary) {
+      const absPath = registryRoomPath(home, primary);
+      if (absPath) {
+        return { slug: primary, abs_path: absPath, source: 'session.primary' };
+      }
+    }
+  } catch (_e) { /* leg A failed -- fall through to the demoted reg.active */ }
+
+  // Leg B: reg.active DEMOTED to the fresh-session seed-default (PSB-15).
+  try {
+    // Opt-in ownership gate. Reached ONLY for a session with no usable
+    // session.primary, i.e. exactly the unbound case this gate exists for. A
+    // bound session never gets here, so binding always outranks ownership.
+    if (o.requireOwnership === true) {
+      const ownership = resolveActiveOwnership({ home: home, sessionId: sessionId });
+      if (ownership && ownership.inheritable === false) return null;
+    }
+    const active = resolveActiveRoom({ home: home });
+    if (active) {
+      return { slug: active.slug, abs_path: active.abs_path, source: 'reg.active' };
+    }
+  } catch (_e) { /* leg B failed -- total miss */ }
+
+  return null;
+}
+
+/**
+ * resolveSessionScope -- the ONE session-aware tripwire on-scope test (PSB-03,
+ * D-02). The intent-classifier tripwire (Wave 3) asks this instead of the old
+ * single-equality `best.name === active` silence test: a top-scoring room is
+ * ON-scope iff it is a MEMBER of this session's bound SET.
+ *
+ * An unbound session (empty/absent binding) yields onScope:false -- this is
+ * precisely what graduates the tripwire into the F.8 binding gate (an unbound
+ * session must be asked which room it is writing to). Membership is a plain
+ * `bound.includes(topRoom)`; the reserved `__no_room__` dev-repo sentinel is a
+ * first-class member (readSessionBinding round-trips it), so a session that
+ * chose dev-repo/no-room is on-scope for a no-room write and does NOT re-fire
+ * the gate.
+ *
+ * NEVER throws: a corrupt binding file collapses to the safe default
+ * ({ onScope:false, bound:[] }). Canon Part 8/9: filesystem-only, zero graph
+ * token (rar.11/rar.12 stay green).
+ *
+ * @param {{sessionId?: string, topRoom?: string, home?: string}} [opts]
+ * @returns {{onScope: boolean, bound: string[]}}
+ */
+function resolveSessionScope(opts) {
+  const o = opts || {};
+  const sessionId = o.sessionId;
+  const topRoom = o.topRoom;
+  const home = o.home || process.env.MINDRIAN_ROOMS_HOME
+    || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+  try {
+    const sessionBinding = require('./session-binding.cjs');
+    const binding = sessionBinding.readSessionBinding(sessionId, { home: home });
+    const bound = (binding && Array.isArray(binding.bound)) ? binding.bound : [];
+    return { onScope: bound.indexOf(topRoom) !== -1, bound: bound };
+  } catch (_e) {
+    // Safe default: an unreadable binding is off-scope, which fires the gate
+    // rather than silently allowing an unscoped write. Never throw into a hook.
+    return { onScope: false, bound: [] };
+  }
+}
+
+/**
+ * Convenience wrapper: returns the active room's slug, or null.
+ * @returns {string|null}
+ */
+function resolveActiveRoomSlug() {
+  const r = resolveActiveRoom();
+  return r ? r.slug : null;
+}
+
+/**
+ * Convenience wrapper: returns the active room's absolute directory path,
+ * or null. This is the most common consumer entry point (jtbd-update.cjs,
+ * intent-classifier.cjs, hmi-compliance-poll.cjs all need the dir).
+ * @returns {string|null}
+ */
+function resolveActiveRoomDir() {
+  const r = resolveActiveRoom();
+  return r ? r.abs_path : null;
+}
+
+module.exports = {
+  resolveActiveRoom,
+  resolveActiveRoomSlug,
+  resolveActiveRoomDir,
+  resolveWriteRoom,
+  resolveSessionRoom,
+  resolveSessionScope,
+  registryRoomPath,
+  resolveActiveOwnership,
+  OWNERSHIP_MAX_AGE_MS,
+};
+
+// CLI entry. Bash wrappers can shell out via:
+//   node lib/core/resolve-active-room.cjs
+// stdout receives a JSON line (the resolved object, or the literal "null").
+// Exit code: 0 on hit, 1 on miss. The exit-code distinction lets bash
+// dispatch without parsing JSON.
+if (require.main === module) {
+  const r = resolveActiveRoom();
+  process.stdout.write(JSON.stringify(r) + '\n');
+  process.exit(r ? 0 : 1);
+}