@mindrian_os/install 1.13.0-beta.11

package/lib/core/mullins-scaffold.cjs

@@ -0,0 +1,160 @@
+/**
+ * MindrianOS Plugin -- Mullins Scaffold Loader (Phase 84-04)
+ *
+ * Loads the canonical Mullins 7-domain venture assessment scaffold from
+ * skills/mullins-scaffold/scaffold.json and exposes a small read-only API for
+ * callers that want to enumerate sections, fetch a single section, or test for
+ * existence. The scaffold is a TEMPLATE, not a mandatory skeleton: rooms that
+ * reference it gain structure, rooms that ignore it are structurally
+ * unaffected. Materialization (writing sections into a room) is deferred to
+ * v1.10.9; this module never touches disk and never mutates STATE.md.
+ *
+ * The scaffold JSON is loaded lazily and cached in module scope. Internal
+ * failures (missing file, malformed JSON) degrade to safe fallbacks ([], null,
+ * false) so early-hook callers cannot crash the plugin if the file is absent.
+ *
+ * Closes SCOPE-NB-01 and SCOPE-NB-02.
+ *
+ * Exports: loadScaffold, listSections, getSection, sectionExists,
+ *          getDomainsForSection
+ */
+
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+
+const SCAFFOLD_PATH = path.join(
+  __dirname,
+  '..',
+  '..',
+  'skills',
+  'mullins-scaffold',
+  'scaffold.json'
+);
+
+let cache = null;
+let loadAttempted = false;
+
+/**
+ * Read and parse skills/mullins-scaffold/scaffold.json once and cache the
+ * result in module scope. Subsequent calls return the cached value. On any
+ * filesystem or JSON parse error, the cache is set to a safe empty document
+ * and a debug line is written to stderr; callers always receive a usable
+ * object shape.
+ *
+ * @returns {{version: number, generated_from: string, sections: Array<object>}}
+ *   The parsed scaffold document, or an empty fallback document on error.
+ */
+function loadScaffold() {
+  if (cache !== null) return cache;
+  if (loadAttempted) return cache || { version: 0, generated_from: '', sections: [] };
+  loadAttempted = true;
+  try {
+    const raw = fs.readFileSync(SCAFFOLD_PATH, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (!parsed || !Array.isArray(parsed.sections)) {
+      throw new Error('scaffold.json missing sections array');
+    }
+    cache = parsed;
+    return cache;
+  } catch (err) {
+    if (process.env.MOS_DEBUG) {
+      process.stderr.write(
+        '[mullins-scaffold] loadScaffold failed: ' + (err && err.message) + '\n'
+      );
+    }
+    cache = { version: 0, generated_from: '', sections: [] };
+    return cache;
+  }
+}
+
+/**
+ * Return all scaffold sections as a shallow-cloned array. Callers may mutate
+ * the returned array without affecting the module cache. Returns an empty
+ * array if the scaffold could not be loaded.
+ *
+ * @returns {Array<{id: string, domain: string, title: string, prompt: string, required: boolean}>}
+ */
+function listSections() {
+  try {
+    const doc = loadScaffold();
+    if (!doc || !Array.isArray(doc.sections)) return [];
+    return doc.sections.map(function (s) {
+      return Object.assign({}, s);
+    });
+  } catch (err) {
+    if (process.env.MOS_DEBUG) {
+      process.stderr.write(
+        '[mullins-scaffold] listSections failed: ' + (err && err.message) + '\n'
+      );
+    }
+    return [];
+  }
+}
+
+/**
+ * Return a single section by its kebab-case id, or null if no such section
+ * exists. The returned object is a shallow clone so callers cannot mutate the
+ * module cache.
+ *
+ * @param {string} id - The section id (e.g. 'market-size-now').
+ * @returns {{id: string, domain: string, title: string, prompt: string, required: boolean}|null}
+ */
+function getSection(id) {
+  try {
+    if (typeof id !== 'string' || id.length === 0) return null;
+    const doc = loadScaffold();
+    if (!doc || !Array.isArray(doc.sections)) return null;
+    const found = doc.sections.find(function (s) {
+      return s && s.id === id;
+    });
+    return found ? Object.assign({}, found) : null;
+  } catch (err) {
+    if (process.env.MOS_DEBUG) {
+      process.stderr.write(
+        '[mullins-scaffold] getSection failed: ' + (err && err.message) + '\n'
+      );
+    }
+    return null;
+  }
+}
+
+/**
+ * Test whether a section id exists in the scaffold.
+ *
+ * @param {string} id - The section id to test.
+ * @returns {boolean} True if a section with this id exists, false otherwise.
+ */
+function sectionExists(id) {
+  try {
+    return getSection(id) !== null;
+  } catch (err) {
+    return false;
+  }
+}
+
+/**
+ * Return the Mullins domain string for a given section id, or null if the
+ * section is unknown. Useful for routing logic that wants to group artifacts
+ * by domain without re-parsing the scaffold.
+ *
+ * @param {string} id - The section id.
+ * @returns {string|null} The domain slug (e.g. 'market-attractiveness') or null.
+ */
+function getDomainsForSection(id) {
+  try {
+    const section = getSection(id);
+    return section && section.domain ? section.domain : null;
+  } catch (err) {
+    return null;
+  }
+}
+
+module.exports = {
+  loadScaffold: loadScaffold,
+  listSections: listSections,
+  getSection: getSection,
+  sectionExists: sectionExists,
+  getDomainsForSection: getDomainsForSection,
+};

package/lib/core/nav-dial.cjs

@@ -0,0 +1,316 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-06 -- Larry dial: pure resolver + formatter for the statusline
+ * navigation indicator
+ * =======================================================================
+ * Pure-function module. Zero I/O. Caller (scripts/context-monitor) reads
+ * the latest decision-trace entry from .mindrian/decision-traces/<session>
+ * .json and passes it in as a plain object. This module returns the dial
+ * position and a formatted segment string for the statusline.
+ *
+ * Three positions: Investigate | Blend | Insight. The active position
+ * carries a glyph (check / warn / low / --) drawn from the Canon Part 2
+ * UI vocabulary, byte-identical with Plan 88.1-04 statusline-cache
+ * classifyHealth (mirrored here, not require'd, to keep lib/core/ self-
+ * contained and lib/memory/ <-> lib/core/ decoupled).
+ *
+ * Position mapping (engine-state-derived):
+ *   - tier_0                                       -> Investigate / -- / null
+ *   - mode_b OR weight < 0.3                       -> Investigate / warn / active
+ *   - mode_a + weight 0.3..0.7                     -> Blend / warn / active
+ *   - mode_a + weight 0.7..0.9                     -> Blend / check / active
+ *   - mode_a + weight >= 0.9 + insight rationale   -> Insight / check / active
+ *   - mode_a + weight >= 0.9 + non-insight         -> Blend / check / active
+ *   - null trace OR malformed                      -> Investigate / -- / null
+ *
+ * Insight markers: 'synthesize' | 'insight' | 'converge' (case-insensitive)
+ * appearing anywhere in chosen_rationale promote weight >= 0.9 from Blend
+ * to Insight. The keyword set is canonical to Phase 91 and matches the
+ * Canon Part 3 verb 'Synthesize' (collapse branches back to insight).
+ *
+ * Canon references:
+ *   Part 2  UI glyph vocabulary -- check / warn / low / --, byte-identical
+ *     to lib/core/statusline-cache.cjs classifyHealth (see line 94 of that
+ *     file). Mirrored here as a 4-line function to keep this module
+ *     dependency-free.
+ *   Part 3  Tri-Context Decision Gate -- dial position reflects the
+ *     triangulated tier_mode + weight_applied result; never an arbitrary
+ *     scrollwheel state. Updates per turn as new traces land.
+ *   Part 8  Graph Boundary -- this module performs ZERO I/O. Caller does
+ *     all reads from .mindrian/decision-traces/<session>.json (LOCAL only).
+ *     No fetch, no Brain client, no shell-out, no network surface.
+ *
+ * Tyler meeting quote (Canon Appendix D / Phase 91-CONTEXT R4):
+ *   "my students almost unanimously said, 'We love the slider.'"
+ * The dial is pedagogically meaningful (tied to engine state), not a
+ * gimmick. The reason field is the audit trail; /mos:explain-decision
+ * surfaces the same chosen_rationale that drove the dial.
+ *
+ * API:
+ *   resolveDialPosition(trace) -> {label, glyph, highlight, reason}
+ *     - trace: a decision-trace entry (the last element of traces[] in
+ *       a .mindrian/decision-traces/<session>.json file). null is allowed.
+ *     - label: 'Investigate' | 'Blend' | 'Insight'
+ *     - glyph: 'check' | 'warn' | 'low' | '--'
+ *     - highlight: 'active' | null
+ *     - reason: human-readable string explaining why this position
+ *
+ *   formatDialSegment(position) -> string
+ *     - position: object returned by resolveDialPosition
+ *     - returns: 'Larry: Investigate | Blend | Insight' with the active
+ *       position visually emphasized via De Stijl ANSI color codes
+ *       (mirrors visual-ops.cjs ANSI palette without requiring it)
+ *     - byte-budget: visible chars (ANSI-stripped) <= 60
+ *
+ *   classifyHealth(score) -> 'check' | 'warn' | 'low' | '--'
+ *     - mirror of lib/core/statusline-cache.cjs classifyHealth
+ *     - 0.7 -> check; 0.4 -> warn; 0.0 -> low; null/NaN/string -> '--'
+ *
+ * Three-surface compatible: pure CJS, node built-ins not even used (the
+ * module imports nothing). Works the same on CLI + Desktop MCP + Cowork.
+ */
+
+'use strict';
+
+// ---------- Frozen constants ----------
+
+// Insight markers in chosen_rationale (case-insensitive).
+// Synthesize: Canon Part 3 verb 7 (collapse branches back to insight).
+// Converge:   Canon Part 4 cross-relationship signal (3+ sections agree).
+// Insight:    plain English; the engine signals when it has reached one.
+const INSIGHT_MARKERS = ['synthesize', 'insight', 'converge'];
+
+// Canon Part 2 thresholds. Byte-identical to Plan 88.1-04
+// statusline-cache.cjs classifyHealth (lines 94-99 of that file).
+const HEALTH_CHECK_THRESHOLD = 0.7;
+const HEALTH_WARN_THRESHOLD = 0.4;
+
+// Tier-mode weight bands (Phase 91 D-04 mapping).
+// weight < BLEND_FLOOR             -> Investigate (low confidence band)
+// BLEND_FLOOR <= weight < BLEND_STRONG  -> Blend / warn
+// BLEND_STRONG <= weight < INSIGHT_FLOOR -> Blend / check
+// weight >= INSIGHT_FLOOR + insight markers -> Insight / check
+const BLEND_FLOOR = 0.3;
+const BLEND_STRONG = 0.7;
+const INSIGHT_FLOOR = 0.9;
+
+// ---------- classifyHealth (Canon Part 2 mirror) ----------
+//
+// Mirrors lib/core/statusline-cache.cjs classifyHealth byte-identically.
+// This is the canonical glyph vocabulary across L3 surfaces (statusline,
+// hook systemMessage, /mos:status, the dial). Re-mirrored instead of
+// require'd so this module stays dependency-free and three-surface.
+function classifyHealth(score) {
+  if (typeof score !== 'number' || !Number.isFinite(score)) return '--';
+  if (score >= HEALTH_CHECK_THRESHOLD) return 'check';
+  if (score >= HEALTH_WARN_THRESHOLD) return 'warn';
+  return 'low';
+}
+
+// ---------- resolveDialPosition ----------
+
+/**
+ * Map a decision-trace entry to a dial position.
+ *
+ * The trace shape is the same one Plan 91-02 writes and Plan 91-05 reads.
+ * The function never throws; every malformed input falls through to the
+ * Investigate / -- / null default ('no_trace_available' or 'malformed').
+ *
+ * @param {object|null} trace - decision-trace entry (last of traces[])
+ * @returns {{label: string, glyph: string, highlight: string|null, reason: string}}
+ */
+function resolveDialPosition(trace) {
+  // Null / non-object trace -> default.
+  if (!trace || typeof trace !== 'object') {
+    return {
+      label: 'Investigate',
+      glyph: '--',
+      highlight: null,
+      reason: 'no_trace_available'
+    };
+  }
+
+  const tierMode = trace.brain_md_tier_mode;
+  const weight = trace.brain_md_weight_applied;
+  const rationale = typeof trace.chosen_rationale === 'string'
+    ? trace.chosen_rationale
+    : '';
+
+  // Tier 0: pre-engine, default investigate state. No highlight (the dial
+  // shows three positions but none is active until the engine has spoken).
+  if (tierMode === 'tier_0') {
+    return {
+      label: 'Investigate',
+      glyph: '--',
+      highlight: null,
+      reason: 'tier_0_fallback'
+    };
+  }
+
+  // Mode B: Brain offline. Engine running on local triple only. Investigate
+  // with a warn glyph -- the engine has spoken, but the signal is partial.
+  if (tierMode === 'mode_b') {
+    return {
+      label: 'Investigate',
+      glyph: 'warn',
+      highlight: 'active',
+      reason: 'Brain offline; investigating locally with MINTO + SQL only'
+    };
+  }
+
+  // Mode A: full triangulation. Weight band picks the position.
+  if (tierMode === 'mode_a') {
+    if (typeof weight !== 'number' || !Number.isFinite(weight)) {
+      // Missing weight on a mode_a trace is malformed; soft-fail to default.
+      return {
+        label: 'Investigate',
+        glyph: '--',
+        highlight: null,
+        reason: 'malformed_trace_missing_weight'
+      };
+    }
+
+    // Low-confidence band: still in investigate territory.
+    if (weight < BLEND_FLOOR) {
+      return {
+        label: 'Investigate',
+        glyph: 'warn',
+        highlight: 'active',
+        reason: 'low_confidence_or_offline'
+      };
+    }
+
+    // Mid blend band: Blend with warn glyph.
+    if (weight < BLEND_STRONG) {
+      return {
+        label: 'Blend',
+        glyph: 'warn',
+        highlight: 'active',
+        reason: 'Blending MINTO + Brain at ' + weight.toFixed(2) + ' weight'
+      };
+    }
+
+    // Strong blend band: Blend with check glyph.
+    if (weight < INSIGHT_FLOOR) {
+      return {
+        label: 'Blend',
+        glyph: 'check',
+        highlight: 'active',
+        reason: 'Strong MINTO + Brain agreement, blending'
+      };
+    }
+
+    // Insight band: weight >= 0.9. Promote to Insight only when rationale
+    // carries insight markers. Otherwise stay in Blend / check (high
+    // confidence routine framework lookup, not a synthesis moment).
+    const lower = rationale.toLowerCase();
+    let isInsight = false;
+    for (const marker of INSIGHT_MARKERS) {
+      if (lower.indexOf(marker) !== -1) {
+        isInsight = true;
+        break;
+      }
+    }
+    if (isInsight) {
+      return {
+        label: 'Insight',
+        glyph: 'check',
+        highlight: 'active',
+        reason: 'Converging signals, insight mode'
+      };
+    }
+    return {
+      label: 'Blend',
+      glyph: 'check',
+      highlight: 'active',
+      reason: 'High confidence, blending without explicit insight marker'
+    };
+  }
+
+  // Unknown tier_mode (forward-compat with future engine modes) -> default.
+  return {
+    label: 'Investigate',
+    glyph: '--',
+    highlight: null,
+    reason: 'unknown_tier_mode'
+  };
+}
+
+// ---------- formatDialSegment ----------
+
+// De Stijl ANSI palette (mirror of lib/core/visual-ops.cjs ANSI struct;
+// duplicated here so this module imports nothing). The five colors used
+// by the dial are dim/muted (inactive label), green (check), yellow
+// (warn), red (low), and bold (highlight).
+const ANSI = {
+  reset:  '\x1b[0m',
+  bold:   '\x1b[1m',
+  dim:    '\x1b[2m',
+  green:  '\x1b[38;2;45;107;74m',   // ds-green
+  yellow: '\x1b[38;2;200;164;60m',  // ds-yellow
+  red:    '\x1b[38;2;166;61;47m',   // ds-red
+  muted:  '\x1b[38;2;160;154;144m'  // ds-muted
+};
+
+const DIAL_LABELS = ['Investigate', 'Blend', 'Insight'];
+
+function glyphColor(glyph) {
+  if (glyph === 'check') return ANSI.green;
+  if (glyph === 'warn')  return ANSI.yellow;
+  if (glyph === 'low')   return ANSI.red;
+  return ANSI.muted;
+}
+
+/**
+ * Render the dial segment string for the statusline.
+ *
+ * Format (no highlight):  'Larry: Investigate | Blend | Insight'
+ * Format (highlighted):   'Larry: Investigate | [bold]Blend[/bold] | Insight'
+ *   plus a leading colored glyph indicator on the active label.
+ *
+ * Visible byte-length stripped of ANSI is <= 60 chars (Test 10 contract).
+ * The longest variant is 'Larry: Investigate | Blend | Insight' = 36 chars,
+ * well under the budget. Highlight does not add visible chars.
+ *
+ * @param {{label: string, glyph: string, highlight: string|null}} position
+ * @returns {string} the formatted segment string ('' on null/invalid input)
+ */
+function formatDialSegment(position) {
+  if (!position || typeof position !== 'object') return '';
+  if (typeof position.label !== 'string') return '';
+
+  const labels = DIAL_LABELS.map((label) => {
+    if (label === position.label && position.highlight === 'active') {
+      // Active label: bold + glyph color so the eye lands here.
+      return ANSI.bold + glyphColor(position.glyph) + label + ANSI.reset;
+    }
+    // Inactive label: dim/muted.
+    return ANSI.dim + ANSI.muted + label + ANSI.reset;
+  });
+
+  // Separator between labels.
+  const sep = ' ' + ANSI.muted + '|' + ANSI.reset + ' ';
+
+  // 'Larry:' prefix in dim white so it doesn't compete with the active
+  // label for attention.
+  const prefix = ANSI.dim + 'Larry:' + ANSI.reset + ' ';
+
+  return prefix + labels.join(sep);
+}
+
+// ---------- Exports ----------
+
+module.exports = {
+  // Pure functions.
+  resolveDialPosition: resolveDialPosition,
+  formatDialSegment: formatDialSegment,
+  classifyHealth: classifyHealth,
+  // Frozen constants (exposed for tests + future composition).
+  INSIGHT_MARKERS: INSIGHT_MARKERS,
+  HEALTH_CHECK_THRESHOLD: HEALTH_CHECK_THRESHOLD,
+  HEALTH_WARN_THRESHOLD: HEALTH_WARN_THRESHOLD,
+  BLEND_FLOOR: BLEND_FLOOR,
+  BLEND_STRONG: BLEND_STRONG,
+  INSIGHT_FLOOR: INSIGHT_FLOOR
+};

package/lib/core/navigation/ROOM.md

@@ -0,0 +1,15 @@
+# lib/core/navigation/
+
+Phase 109 navigation spine internal helpers. Each .cjs file in this directory is an internal helper that lib/core/navigation.cjs (Plan 109-04) re-exports as part of the closed 13-function API surface.
+
+Files:
+- focus.cjs - getActiveFocus + setFocus + computeAutoFocus (Plan 109-02 / NAV-109-01)
+- neighborhood.cjs - getNeighborhood recursive CTE wrapper (Plan 109-04 / NAV-109-02; not yet shipped)
+- insights.cjs - 7 insight query primitives (Plan 109-05 / NAV-109-04; not yet shipped)
+- packet.cjs - buildBrainPacket + storeBrainSuggestions (Plans 109-07 + 109-08 / NAV-109-06 + NAV-109-07; not yet shipped)
+- room-home.cjs - getRoomHomeView composition (Plan 109-09 / NAV-109-08; not yet shipped)
+- transitions.cjs - promoteNodeStatus chokepoint (Plan 109-04 / NAV-109-05; not yet shipped)
+
+All helpers accept the open db handle as the first parameter; never call openRoomDb internally (the chokepoint module owns the lifecycle).
+
+Owner: Phase 109 SQL Context-Memory Navigation Spine.

package/lib/core/navigation/explanation.cjs

@@ -0,0 +1,43 @@
+'use strict';
+// Phase 109-05 templated explanation renderer. ZERO LLM in the loop per RESEARCH section 2.5.
+// Closed kind enum; each kind has a deterministic template using typed edge labels.
+//
+// Canon Part 4: every choice is graph data; explanation strings render the typed
+// edge labels (CONTRADICTS, SUPPORTS, DEPENDS_ON, ENABLES, EVIDENCES) directly so
+// users can read "the graph paths AS the explanation".
+// Canon Part 9: ZERO LLM in the loop; the "graph paths as explanation" pattern is
+// the structural substitute for prompt-generated narrative.
+
+function shortId(id) {
+  if (typeof id !== 'string') return String(id);
+  const parts = id.split(':');
+  if (parts.length < 2) return id;
+  return parts[0] + ':' + parts.slice(1).join(':');
+}
+
+function daysSince(epochMs) {
+  const dms = Date.now() - epochMs;
+  return Math.max(0, Math.floor(dms / (24 * 60 * 60 * 1000)));
+}
+
+function renderExplanation(kind, payload) {
+  const p = payload || {};
+  switch (kind) {
+    case 'contradiction':
+      return shortId(p.claimA) + ' CONTRADICTS ' + shortId(p.claimB) + ' (depth ' + (p.depth != null ? p.depth : 1) + ')';
+    case 'unsupported':
+      return shortId(p.claim) + ' is ' + (p.reviewStatus || 'confirmed') + ' but has no SUPPORTS edge (last touched ' + daysSince(p.lastSeenAt || Date.now()) + ' days ago)';
+    case 'blocking':
+      return shortId(p.assumption) + ' blocks ' + shortId(p.goal) + ' via path ' + (Array.isArray(p.cascadePath) ? p.cascadePath.map(shortId).join(' -> ') : '');
+    case 'stale':
+      return shortId(p.decision) + ' is confirmed but has not been touched in ' + daysSince(p.lastSeenAt) + ' days';
+    case 'open':
+      return shortId(p.question) + ' has been open for ' + daysSince(p.createdAt) + ' days with no SUPPORTS or EVIDENCES edge';
+    case 'opportunity':
+      return shortId(p.opportunityId) + ' (' + (p.hsiBand || 'unknown') + ' HSI band; ' + (p.jtbdMatch > 0 ? 'matches active JTBD' : 'no JTBD overlap') + '; ' + (p.depth != null ? p.depth : '?') + ' hop(s) from focus)';
+    default:
+      return '[explanation unavailable for kind=' + kind + ']';
+  }
+}
+
+module.exports = { renderExplanation, shortId, daysSince };

package/lib/core/navigation/focus.cjs

@@ -0,0 +1,135 @@
+'use strict';
+// Phase 109-02 focus helpers. Internal to lib/core/navigation/.
+// Re-exported by lib/core/navigation.cjs (Plan 109-04) as the closed surface.
+//
+// Canon Part 1: the focus node is the wicked navigator's working-memory
+// anchor. Canon Part 4: every setFocus writes a focus_changed memory_event
+// (audit trail). Canon Part 9: focus persists in room.db, never in process
+// memory.
+
+const path = require('node:path');
+const crypto = require('node:crypto');
+
+const VALID_SET_BY = new Set(['user', 'larry', 'auto-from-jtbd', 'auto-from-operator', 'auto-from-state']);
+
+function getActiveFocus(db, sessionId) {
+  const row = db.prepare(
+    "SELECT sf.session_id, sf.focus_node_id, sf.focus_type, sf.set_at, sf.set_by " +
+    "FROM session_focus sf " +
+    "WHERE sf.session_id = ?"
+  ).get(sessionId);
+  if (!row) return null;
+  return {
+    sessionId: row.session_id,
+    focusNodeId: row.focus_node_id,
+    focusType: row.focus_type,
+    setAt: row.set_at,
+    setBy: row.set_by,
+  };
+}
+
+function lookupNodeType(db, nodeId) {
+  const row = db.prepare('SELECT type FROM nodes WHERE id = ?').get(nodeId);
+  return row ? row.type : null;
+}
+
+function setFocus(db, sessionId, nodeId, setBy) {
+  if (!VALID_SET_BY.has(setBy)) {
+    return { ok: false, reason: 'invalid_set_by' };
+  }
+  const nodeType = lookupNodeType(db, nodeId);
+  if (!nodeType) {
+    return { ok: false, reason: 'unknown_node' };
+  }
+  // Capture previous focus for the focus_changed event payload.
+  const prior = getActiveFocus(db, sessionId);
+  const previousId = prior ? prior.focusNodeId : null;
+  const nowMs = Date.now();
+  const eventId = 'memory_event:focus_changed:' + sessionId + ':' + nowMs + ':' + crypto.randomBytes(4).toString('hex');
+  db.exec('BEGIN');
+  try {
+    db.prepare(
+      "INSERT OR REPLACE INTO session_focus (session_id, focus_node_id, focus_type, set_at, set_by) VALUES (?, ?, ?, ?, ?)"
+    ).run(sessionId, nodeId, nodeType, nowMs, setBy);
+    const props = JSON.stringify({
+      event_type: 'focus_changed',
+      session_id: sessionId,
+      previous_focus_node_id: previousId,
+      new_focus_node_id: nodeId,
+      set_by: setBy,
+    });
+    db.prepare(
+      "INSERT INTO nodes (id, type, properties, source_path, created_by, confidence, review_status, created_at, last_seen_at) " +
+      "VALUES (?, 'memory_event', ?, ?, 'system', NULL, 'confirmed', ?, ?)"
+    ).run(eventId, props, 'session:' + sessionId, nowMs, nowMs);
+    db.exec('COMMIT');
+  } catch (err) {
+    db.exec('ROLLBACK');
+    return { ok: false, reason: err.message };
+  }
+  return { ok: true, eventId };
+}
+
+function loadJtbdState(roomDir, mocks) {
+  if (mocks && mocks.jtbd) return mocks.jtbd;
+  try {
+    return require(path.resolve(__dirname, '..', '..', 'hmi', 'jtbd-state.cjs'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function loadOperator(roomDir, mocks) {
+  if (mocks && mocks.operator) return mocks.operator;
+  try {
+    return require(path.resolve(__dirname, '..', '..', 'conversation', 'operator.cjs'));
+  } catch (_) {
+    return null;
+  }
+}
+
+function ensureNodeExists(db, nodeId) {
+  const row = db.prepare('SELECT id FROM nodes WHERE id = ?').get(nodeId);
+  return Boolean(row);
+}
+
+function computeAutoFocus(db, roomDir, sessionId, opts) {
+  const options = opts || {};
+  const mocks = options._mocks;
+  const roomId = options.roomId || (roomDir ? path.basename(roomDir) : null);
+
+  // Rule 1: active JTBD.
+  const jtbdMod = loadJtbdState(roomDir, mocks);
+  const jtbd = jtbdMod ? jtbdMod.getCurrent(roomDir) : null;
+  if (jtbd && jtbd.current && jtbd.current.id) {
+    const candidate = 'jtbd:' + jtbd.current.id;
+    if (ensureNodeExists(db, candidate)) {
+      return { focusNodeId: candidate, focusType: 'jtbd', setBy: 'auto-from-jtbd' };
+    }
+  }
+
+  // Rule 2: operator DECISION_GATE -> most recent unconfirmed decision.
+  const opMod = loadOperator(roomDir, mocks);
+  const op = opMod ? opMod.getCurrent(roomDir) : null;
+  if (op && op.current === 'DECISION_GATE') {
+    const row = db.prepare(
+      "SELECT id, type FROM nodes WHERE type = 'decision' AND review_status IN ('proposed','needs_evidence') ORDER BY created_at DESC LIMIT 1"
+    ).get();
+    if (row) {
+      return { focusNodeId: row.id, focusType: row.type, setBy: 'auto-from-operator' };
+    }
+  }
+
+  // Rule 3: room root node.
+  if (roomId) {
+    const candidate = 'room:' + roomId;
+    if (ensureNodeExists(db, candidate)) {
+      return { focusNodeId: candidate, focusType: 'room', setBy: 'auto-from-state' };
+    }
+  }
+
+  // Rule 4: cold start.
+  return null;
+}
+
+module.exports = { getActiveFocus, setFocus, computeAutoFocus, VALID_SET_BY };