@mindrian_os/install 1.13.0-beta.11

package/lib/core/navigation.cjs

@@ -0,0 +1,60 @@
+'use strict';
+// Phase 109 navigation chokepoint module. The closed 13-function surface per CONTEXT D-05.
+// Every other module that touches the graph goes through this API. The Plan 109-06
+// pre-commit hook fails any new code that requires lib/core/room-db.cjs directly outside
+// the allow-list (this file, lib/core/navigation/*, room-db.cjs self, lazygraph-ops.cjs,
+// memory-ops.cjs, opportunity-ops.cjs legacy, tests/, scripts/migrate-).
+//
+// Canon Part 7: single chokepoint module re-exporting the closed surface; a 14th export
+// (note: closed surface is the documented 13-function API; the implementation module here
+// re-exports those plus internal helpers as needed) requires canon amendment.
+// Canon Part 9: navigation IS the local mind; this is the only module callers should
+// require for graph reads, ranking, packet building, and truth-state promotion.
+
+const focus = require('./navigation/focus.cjs');
+const neighborhoodMod = require('./navigation/neighborhood.cjs');
+const memoryEvents = require('./navigation/memory-events.cjs');
+const transitions = require('./navigation/transitions.cjs');
+const insights = require('./navigation/insights.cjs');
+const packet = require('./navigation/packet.cjs');
+const ingestion = require('./navigation/ingestion.cjs');
+const roomHome = require('./navigation/room-home.cjs');
+
+function notImplementedYet(name, plan) {
+  return function () {
+    throw new Error('not_implemented_yet:' + name + ':' + plan + ' - the closed 13-function navigation surface is established by Plan 109-04; this stub will be replaced by ' + plan);
+  };
+}
+
+module.exports = {
+  // Focus (Plan 109-02 LIVE).
+  getActiveFocus: focus.getActiveFocus,
+  setFocus: focus.setFocus,
+
+  // Neighborhood (Plan 109-04 LIVE).
+  getNeighborhood: neighborhoodMod.getNeighborhood,
+
+  // Insight queries (Plan 109-05 LIVE; Plan 116-01 added findSurfaceableTensions).
+  findContradictions: insights.findContradictions,
+  findUnsupportedClaims: insights.findUnsupportedClaims,
+  findBlockingAssumptions: insights.findBlockingAssumptions,
+  findStaleDecisions: insights.findStaleDecisions,
+  findOpenQuestions: insights.findOpenQuestions,
+  findSurfaceableTensions: insights.findSurfaceableTensions,
+
+  // findRecentChanges (Plan 109-03 LIVE).
+  findRecentChanges: memoryEvents.findRecentChanges,
+
+  // Opportunity ranking (Plan 109-05 LIVE).
+  findRelevantOpportunities: insights.findRelevantOpportunities,
+
+  // Brain integration (Plan 109-07 LIVE; Plan 109-08 LIVE).
+  buildBrainPacket: packet.buildBrainPacket,
+  storeBrainSuggestions: ingestion.storeBrainSuggestions,
+
+  // Room Home (Plan 109-09 LIVE - 13th and LAST live export; navigation.cjs surface COMPLETE).
+  getRoomHomeView: roomHome.getRoomHomeView,
+
+  // Truth-state chokepoint (Plan 109-04 LIVE).
+  promoteNodeStatus: transitions.promoteNodeStatus,
+};

package/lib/core/nl-graph-queries.cjs

@@ -0,0 +1,164 @@
+/**
+ * MindrianOS Plugin -- Natural Language Graph Query Templates
+ * Maps natural language intent patterns to parameterized SQL queries.
+ * Larry/host LLM calls translateQuery(intent, params) to get SQL
+ * that lazygraph-ops.cjs queryGraph can execute.
+ *
+ * Exports: translateQuery, executeNLQuery, QUERY_TEMPLATES
+ */
+
+'use strict';
+
+/**
+ * Query template definitions mapping intent names to parameterized SQL builders.
+ * Each template has: description, params (required parameter names), build function.
+ * build() returns { sql, bindings } for use with node:sqlite prepared statements.
+ */
+const QUERY_TEMPLATES = {
+
+  contradictions: {
+    description: 'Find artifacts that contradict a given artifact or section',
+    params: ['target'],
+    build: (p) => ({
+      sql: "SELECT e.source, json_extract(n.properties, '$.title') AS title, json_extract(e.properties, '$.confidence') AS confidence FROM edges e JOIN nodes n ON e.source = n.id WHERE e.type = 'CONTRADICTS' AND e.target = ?",
+      bindings: [p.target]
+    })
+  },
+
+  neighbors: {
+    description: 'Find all nodes connected to a given node (incoming + outgoing)',
+    params: ['nodeId'],
+    build: (p) => ({
+      sql: "SELECT 'outgoing' AS direction, e.target AS neighbor, e.type AS rel, json_extract(n.properties, '$.title') AS title FROM edges e JOIN nodes n ON e.target = n.id WHERE e.source = ? UNION ALL SELECT 'incoming' AS direction, e.source AS neighbor, e.type AS rel, json_extract(n.properties, '$.title') AS title FROM edges e JOIN nodes n ON e.source = n.id WHERE e.target = ?",
+      bindings: [p.nodeId, p.nodeId]
+    })
+  },
+
+  path: {
+    description: 'Find shortest path between two nodes (up to 2 hops)',
+    params: ['from', 'to'],
+    build: (p) => ({
+      sql: "SELECT e1.source AS start, e1.type AS rel1, e1.target AS mid, e2.type AS rel2, e2.target AS end FROM edges e1 JOIN edges e2 ON e1.target = e2.source WHERE e1.source = ? AND e2.target = ? UNION ALL SELECT source AS start, type AS rel1, target AS mid, NULL AS rel2, NULL AS end FROM edges WHERE source = ? AND target = ?",
+      bindings: [p.from, p.to, p.from, p.to]
+    })
+  },
+
+  stats: {
+    description: 'Graph statistics: node and edge counts by type',
+    params: [],
+    build: () => ({
+      sql: "SELECT 'nodes' AS category, type, COUNT(*) AS count FROM nodes GROUP BY type UNION ALL SELECT 'edges' AS category, type, COUNT(*) AS count FROM edges GROUP BY type",
+      bindings: []
+    })
+  },
+
+  section_artifacts: {
+    description: 'List all artifacts in a section with titles',
+    params: ['section'],
+    build: (p) => ({
+      sql: "SELECT id, json_extract(properties, '$.title') AS title, json_extract(properties, '$.methodology') AS methodology, json_extract(properties, '$.created') AS created FROM nodes WHERE type = 'Artifact' AND json_extract(properties, '$.section') = ?",
+      bindings: [p.section]
+    })
+  },
+
+  hsi_connections: {
+    description: 'Find high-surprise HSI connections sorted by score',
+    params: ['min_score'],
+    build: (p) => ({
+      sql: "SELECT e.source, e.target, json_extract(e.properties, '$.hsi_score') AS hsi_score, json_extract(e.properties, '$.surprise_type') AS surprise_type, json_extract(n1.properties, '$.title') AS source_title, json_extract(n2.properties, '$.title') AS target_title FROM edges e JOIN nodes n1 ON e.source = n1.id JOIN nodes n2 ON e.target = n2.id WHERE e.type = 'HSI_CONNECTION' AND CAST(json_extract(e.properties, '$.hsi_score') AS REAL) >= ? ORDER BY CAST(json_extract(e.properties, '$.hsi_score') AS REAL) DESC",
+      bindings: [p.min_score || 0.5]
+    })
+  },
+
+  reverse_salients: {
+    description: 'Find reverse salients (lagging sections)',
+    params: [],
+    build: () => ({
+      sql: "SELECT e.source, e.target, json_extract(e.properties, '$.differential_score') AS diff_score, json_extract(e.properties, '$.innovation_type') AS innovation_type, json_extract(e.properties, '$.innovation_thesis') AS thesis FROM edges e WHERE e.type = 'REVERSE_SALIENT' ORDER BY CAST(json_extract(e.properties, '$.differential_score') AS REAL) DESC",
+      bindings: []
+    })
+  },
+
+  causal_claims: {
+    description: 'Find causal claims with their cause-mechanism-effect chains',
+    params: [],
+    build: () => ({
+      sql: "SELECT id, json_extract(properties, '$.cause') AS cause, json_extract(properties, '$.mechanism') AS mechanism, json_extract(properties, '$.effect') AS effect, json_extract(properties, '$.confidence') AS confidence, json_extract(properties, '$.domain') AS domain FROM nodes WHERE type = 'CausalClaim' ORDER BY CAST(json_extract(properties, '$.confidence') AS REAL) DESC",
+      bindings: []
+    })
+  },
+
+  whitespace_zones: {
+    description: 'Find whitespace zones (innovation gaps) with hypotheses',
+    params: [],
+    build: () => ({
+      sql: "SELECT id, json_extract(properties, '$.brain_framework') AS framework, json_extract(properties, '$.hypothesis') AS hypothesis, json_extract(properties, '$.strategic_rank') AS strategic_rank, json_extract(properties, '$.exploration_status') AS status FROM nodes WHERE type = 'WhitespaceZone' ORDER BY CAST(json_extract(properties, '$.strategic_rank') AS REAL) DESC",
+      bindings: []
+    })
+  },
+
+  convergence: {
+    description: 'Find artifacts that converge (appear in 3+ edge types as source)',
+    params: [],
+    build: () => ({
+      sql: "SELECT e.source AS artifact, json_extract(n.properties, '$.title') AS title, COUNT(DISTINCT e.type) AS edge_type_count, GROUP_CONCAT(DISTINCT e.type) AS edge_types FROM edges e JOIN nodes n ON e.source = n.id GROUP BY e.source HAVING COUNT(DISTINCT e.type) >= 3 ORDER BY edge_type_count DESC",
+      bindings: []
+    })
+  },
+
+};
+
+/**
+ * Translate a natural language intent to parameterized SQL.
+ * @param {string} intent - Query intent key (e.g. 'contradictions', 'neighbors')
+ * @param {object} [params={}] - Parameters for the query template
+ * @returns {{ sql: string, bindings: Array, description: string } | { error: string }}
+ */
+function translateQuery(intent, params = {}) {
+  const template = QUERY_TEMPLATES[intent];
+  if (!template) {
+    const available = Object.keys(QUERY_TEMPLATES).join(', ');
+    return { error: `Unknown query intent: '${intent}'. Available: ${available}` };
+  }
+
+  // Validate required params
+  for (const required of template.params) {
+    if (params[required] === undefined || params[required] === null) {
+      return { error: `Missing required parameter '${required}' for intent '${intent}'` };
+    }
+  }
+
+  const { sql, bindings } = template.build(params);
+  return { sql, bindings, description: template.description };
+}
+
+/**
+ * Execute a natural language query against the graph.
+ * Convenience wrapper: translates intent to SQL, executes via prepared statement.
+ * @param {import('node:sqlite').DatabaseSync} conn - node:sqlite DatabaseSync instance
+ * @param {string} intent - Query intent key
+ * @param {object} [params={}] - Parameters for the query template
+ * @returns {{ rows: Array<object>, description: string, intent: string } | { error: string }}
+ */
+function executeNLQuery(conn, intent, params = {}) {
+  const translated = translateQuery(intent, params);
+  if (translated.error) {
+    return { error: translated.error };
+  }
+
+  try {
+    const stmt = conn.prepare(translated.sql);
+    const rows = translated.bindings.length > 0
+      ? stmt.all(...translated.bindings)
+      : stmt.all();
+    return { rows, description: translated.description, intent };
+  } catch (e) {
+    return { error: `Query execution failed: ${e.message}`, intent };
+  }
+}
+
+module.exports = {
+  translateQuery,
+  executeNLQuery,
+  QUERY_TEMPLATES,
+};

package/lib/core/offer-presenter.cjs

@@ -0,0 +1,406 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 91-04 -- Next-step offer presenter (Canon Part 3 + Part 4)
+ * =================================================================
+ * Converts navigation-engine.decide()'s `offer_next_step` payload into a
+ * one-line grounded suggestion that Larry surfaces at the end of a turn.
+ * Persists offer outcomes (shown / ignored / acted) to a LOCAL JSON
+ * ledger so future presentations can suppress noise after consecutive
+ * ignores (Risk 5 mitigation per 91-CONTEXT).
+ *
+ * Canonical contract:
+ *
+ *   presentOffer(decision, offerHistory, sessionCtx) -> {
+ *     offerLine: string|null,
+ *     recommendedMarker: boolean,
+ *     suppressReason: string|null
+ *   }
+ *
+ *   recordOfferOutcome(roomDir, outcome) -> void
+ *     Append { at, session_id, command, reason, outcome } to
+ *     .mindrian/offer-history.json atomically. Rotates to last 100.
+ *     Fire-and-forget; never throws.
+ *
+ *   readOfferHistory(roomDir) -> { version: 1, history: [...] [, parse_failed] }
+ *     Absent -> empty struct. Malformed -> empty struct + parse_failed:true.
+ *     Never throws.
+ *
+ *   classifyTurnOutcome(previousOffer, currentUserText) -> 'acted'|'ignored'
+ *     Wave-1 heuristic: if previousOffer.command appears as a substring of
+ *     currentUserText, mark 'acted'; otherwise 'ignored'. Best-effort.
+ *
+ * Canon Part 3 Section 6 RECOMMENDED gate:
+ *   The engine evaluates Mode A + confidence >= 0.7 + verb match (Plan
+ *   91-00 wrote brain_md_recommended_marker_rendered into the trace).
+ *   The presenter ONLY respects that flag; it does NOT re-evaluate. If
+ *   the engine renders the marker, the offer line carries '(RECOMMENDED)'
+ *   immediately after 'Offer'. Otherwise no marker.
+ *
+ * Canon Part 4: every offer outcome is a typed graph edge. The local
+ * offer-history.json is the LOCAL ledger; cross-user aggregation is out
+ * of scope for v1.11.0.
+ *
+ * Canon Part 8: pure local. Zero network. No Brain reads. No fetch. No
+ * shell-out. The only fs touches are .mindrian/offer-history.json
+ * read/write under the active room.
+ *
+ * Locked decisions (per PLAN 91-04 frontmatter must_haves):
+ *   - Format: "Offer[ (RECOMMENDED)]: Because <reason>, try <command>."
+ *   - Grounding: reason.length >= 15 AND contains a SIGNAL_KEYWORDS hit
+ *     OR a section-name pattern (heuristic regex /[a-z]+-[a-z]+/i).
+ *   - One-per-turn marker: sessionCtx.offeredThisTurn (per-process flag).
+ *   - Consecutive-ignore window: last 2 history entries; tail-relative
+ *     so a non-ignored entry between resets the counter.
+ *   - History rotation: trim to last 100 entries on append.
+ *   - Atomic write: openSync('wx') + fsync (best-effort) + rename, with
+ *     EEXIST self-heal so concurrent presenters do not deadlock.
+ *
+ * License: BSL 1.1.
+ */
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+// ---------- Frozen constants ----------
+
+// Signal keywords that mark a reason as grounded in a real source. The
+// heuristic is intentionally loose: any keyword hit qualifies. Section-
+// name regex provides additional acceptance for prose like
+// "market-analysis section MINTO is stale" without enumerating every
+// possible section.
+const SIGNAL_KEYWORDS = Object.freeze([
+  'MINTO',
+  'BRAIN',
+  'pattern',
+  'graph',
+  'reasoning',
+  'governing',
+  'evidence',
+  'confidence',
+  'health',
+  'stale',
+  'section',
+  'SWOT',
+  'audit',
+  'TAM',
+  'SAM',
+  'SOM',
+  'wicked',
+  'cascade',
+  'contradicts',
+  'converges',
+  'invalidates',
+  'enables',
+]);
+
+const GROUNDING_MIN_LENGTH = 15;
+const CONSECUTIVE_IGNORES_THRESHOLD = 2;
+const HISTORY_MAX_ENTRIES = 100;
+const HISTORY_FILE = 'offer-history.json';
+
+// Section-name heuristic: at least two lowercase letter blocks joined
+// by a hyphen, e.g. 'market-analysis', 'business-model', 'team-execution'.
+const SECTION_NAME_RE = /\b[a-z]+(?:-[a-z]+)+\b/;
+
+// ---------- Pure helpers ----------
+
+/**
+ * isReasonGrounded(reason) -> 'ok' | 'ungrounded_reason' | 'generic_reason'
+ *
+ * 'ok'                  -- length >= 15 AND signal keyword OR section name
+ * 'ungrounded_reason'   -- non-string, empty, or length < 15
+ * 'generic_reason'      -- length OK but no signal keyword AND no section name
+ */
+function isReasonGrounded(reason) {
+  if (typeof reason !== 'string') return 'ungrounded_reason';
+  if (reason.length < GROUNDING_MIN_LENGTH) return 'ungrounded_reason';
+  const lc = reason.toLowerCase();
+  for (let i = 0; i < SIGNAL_KEYWORDS.length; i += 1) {
+    if (lc.indexOf(SIGNAL_KEYWORDS[i].toLowerCase()) !== -1) {
+      return 'ok';
+    }
+  }
+  if (SECTION_NAME_RE.test(reason)) return 'ok';
+  return 'generic_reason';
+}
+
+/**
+ * countTrailingIgnores(history) -> number
+ *
+ * Counts consecutive 'ignored' outcomes at the tail of the history array.
+ * Stops at the first non-ignored entry. A 'shown', 'acted', or any other
+ * value (including 'reset') resets the counter.
+ */
+function countTrailingIgnores(history) {
+  if (!history || !Array.isArray(history.history)) return 0;
+  const arr = history.history;
+  let count = 0;
+  for (let i = arr.length - 1; i >= 0; i -= 1) {
+    const e = arr[i];
+    if (e && typeof e === 'object' && e.outcome === 'ignored') {
+      count += 1;
+    } else {
+      break;
+    }
+  }
+  return count;
+}
+
+/**
+ * formatOfferLine(command, reason, recommendedMarker) -> string
+ *
+ * Produces the canonical one-line format. Marker (when true) appears
+ * immediately after "Offer" so the grep pattern 'Offer (RECOMMENDED):'
+ * uniquely identifies a recommended offer.
+ */
+function formatOfferLine(command, reason, recommendedMarker) {
+  const prefix = recommendedMarker ? 'Offer (RECOMMENDED)' : 'Offer';
+  return prefix + ': Because ' + reason + ', try ' + command + '.';
+}
+
+// ---------- Main: presentOffer ----------
+
+/**
+ * presentOffer(decision, offerHistory, sessionCtx)
+ *
+ * Returns:
+ *   { offerLine: string|null, recommendedMarker: boolean,
+ *     suppressReason: string|null }
+ *
+ * Suppress reasons (mutually exclusive; precedence top to bottom):
+ *   - 'one_offer_per_turn'              -- session already offered this turn
+ *   - 'consecutive_ignores_threshold'   -- last 2 outcomes were 'ignored'
+ *   - 'ungrounded_reason'               -- reason missing/short
+ *   - 'generic_reason'                  -- reason fails signal-keyword gate
+ *
+ * Side effect: when an offer is rendered, sets sessionCtx.offeredThisTurn = true.
+ * Callers MUST share the same sessionCtx object across calls in the same turn
+ * for the one-per-turn cap to function. Cross-process per-turn enforcement is
+ * deferred to Task 2 wiring (where the classifier process is the per-turn
+ * boundary by construction).
+ */
+function presentOffer(decision, offerHistory, sessionCtx) {
+  const ctx = sessionCtx || {};
+  const empty = { offerLine: null, recommendedMarker: false, suppressReason: null };
+
+  // Defensive: missing decision or offer_next_step -> silent.
+  if (!decision || typeof decision !== 'object') return empty;
+  const offer = decision.offer_next_step;
+  if (offer === null || offer === undefined) return empty;
+  if (typeof offer !== 'object') return empty;
+
+  // ---- Per-turn cap (one_offer_per_turn) ----
+  if (ctx.offeredThisTurn === true) {
+    return { offerLine: null, recommendedMarker: false, suppressReason: 'one_offer_per_turn' };
+  }
+
+  // ---- Consecutive-ignore suppression ----
+  if (countTrailingIgnores(offerHistory) >= CONSECUTIVE_IGNORES_THRESHOLD) {
+    return {
+      offerLine: null,
+      recommendedMarker: false,
+      suppressReason: 'consecutive_ignores_threshold',
+    };
+  }
+
+  // ---- Grounding rule ----
+  const command = typeof offer.command === 'string' ? offer.command : '';
+  const reason = typeof offer.reason === 'string' ? offer.reason : '';
+  if (command.length === 0) {
+    // Treat empty command as not-an-offer (graceful; no suppress code).
+    return empty;
+  }
+  const groundingResult = isReasonGrounded(reason);
+  if (groundingResult !== 'ok') {
+    return { offerLine: null, recommendedMarker: false, suppressReason: groundingResult };
+  }
+
+  // ---- RECOMMENDED marker (Section 6 gate respected) ----
+  let recommendedMarker = false;
+  if (decision.decision_trace && typeof decision.decision_trace === 'object') {
+    if (decision.decision_trace.brain_md_recommended_marker_rendered === true) {
+      recommendedMarker = true;
+    }
+  }
+
+  const offerLine = formatOfferLine(command, reason, recommendedMarker);
+
+  // Mark turn as having presented an offer (per-turn cap).
+  ctx.offeredThisTurn = true;
+  return { offerLine: offerLine, recommendedMarker: recommendedMarker, suppressReason: null };
+}
+
+// ---------- recordOfferOutcome ----------
+
+/**
+ * recordOfferOutcome(roomDir, outcome)
+ *
+ * outcome shape: { outcome: 'shown'|'ignored'|'acted', session_id: string,
+ *                  command: string, reason?: string }
+ *
+ * Appends an entry with `at` = ISO-8601 timestamp. Trims to HISTORY_MAX_ENTRIES.
+ * Atomic via openSync('wx') + fsync (best-effort) + rename. Fire-and-forget;
+ * never throws. Callers do NOT need to await any return value.
+ */
+function recordOfferOutcome(roomDir, outcome) {
+  try {
+    if (!roomDir || typeof roomDir !== 'string') return;
+    if (!outcome || typeof outcome !== 'object') return;
+    const mindrianDir = path.join(roomDir, '.mindrian');
+    try { fs.mkdirSync(mindrianDir, { recursive: true }); } catch (_) {}
+    const filePath = path.join(mindrianDir, HISTORY_FILE);
+
+    // Read existing (or empty).
+    let data = { version: 1, history: [] };
+    try {
+      const raw = fs.readFileSync(filePath, 'utf8');
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === 'object' && Array.isArray(parsed.history)) {
+        data = parsed;
+        if (data.version !== 1) data.version = 1;
+        // parse_failed is a read-side flag; never persist it.
+        if (data.parse_failed !== undefined) delete data.parse_failed;
+      }
+    } catch (_) {
+      // Absent or malformed -> start fresh.
+      data = { version: 1, history: [] };
+    }
+
+    const entry = {
+      at: new Date().toISOString(),
+      session_id: typeof outcome.session_id === 'string' ? outcome.session_id : null,
+      command: typeof outcome.command === 'string' ? outcome.command : null,
+      reason: typeof outcome.reason === 'string' ? outcome.reason : null,
+      outcome: typeof outcome.outcome === 'string' ? outcome.outcome : null,
+    };
+    data.history.push(entry);
+
+    // Rotate.
+    if (data.history.length > HISTORY_MAX_ENTRIES) {
+      data.history = data.history.slice(data.history.length - HISTORY_MAX_ENTRIES);
+    }
+
+    writeHistoryAtomic(filePath, data);
+  } catch (_) {
+    // fire-and-forget
+  }
+}
+
+/**
+ * Atomic write: openSync('wx') + fsync (best-effort) + rename.
+ * EEXIST self-heal: stale tmp files from a crashed prior writer get
+ * unlinked and retried once. Never throws.
+ */
+function writeHistoryAtomic(filePath, data) {
+  try {
+    const rnd = Math.random().toString(36).slice(2, 10);
+    const tmpPath = filePath + '.tmp.' + process.pid + '.' + rnd;
+    let fd;
+    try {
+      fd = fs.openSync(tmpPath, 'wx');
+    } catch (e) {
+      if (e && e.code === 'EEXIST') {
+        try { fs.unlinkSync(tmpPath); } catch (_) {}
+        try {
+          fd = fs.openSync(tmpPath, 'wx');
+        } catch (_) { return; }
+      } else {
+        return;
+      }
+    }
+    try {
+      fs.writeSync(fd, JSON.stringify(data, null, 2));
+      try { fs.fsyncSync(fd); } catch (_) {
+        // ENOTSUP on tmpfs / overlayfs -- best-effort durability acceptable.
+      }
+    } finally {
+      try { fs.closeSync(fd); } catch (_) {}
+    }
+    try {
+      fs.renameSync(tmpPath, filePath);
+    } catch (_) {
+      try { fs.unlinkSync(tmpPath); } catch (_) {}
+    }
+  } catch (_) { /* fire-and-forget */ }
+}
+
+// ---------- readOfferHistory ----------
+
+/**
+ * readOfferHistory(roomDir) -> { version: 1, history: [...] [, parse_failed: true] }
+ *
+ * Absent file -> { version: 1, history: [] }.
+ * Malformed JSON -> { version: 1, history: [], parse_failed: true }.
+ * Never throws.
+ */
+function readOfferHistory(roomDir) {
+  const empty = { version: 1, history: [] };
+  if (!roomDir || typeof roomDir !== 'string') return empty;
+  const filePath = path.join(roomDir, '.mindrian', HISTORY_FILE);
+  let raw;
+  try {
+    raw = fs.readFileSync(filePath, 'utf8');
+  } catch (_) {
+    return empty; // absent
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(raw);
+  } catch (_) {
+    return { version: 1, history: [], parse_failed: true };
+  }
+  if (!parsed || typeof parsed !== 'object' || !Array.isArray(parsed.history)) {
+    return { version: 1, history: [], parse_failed: true };
+  }
+  return {
+    version: parsed.version === 1 ? 1 : 1,
+    history: parsed.history,
+  };
+}
+
+// ---------- classifyTurnOutcome ----------
+
+/**
+ * classifyTurnOutcome(previousOffer, currentUserText) -> 'acted' | 'ignored'
+ *
+ * Wave-1 heuristic per 91-04 PLAN: if previousOffer.command appears as a
+ * substring of currentUserText, the user 'acted' on the offer; otherwise
+ * 'ignored'. Best-effort. Future plans may layer richer detection on top.
+ *
+ * Inputs are defensive: null/non-string/empty currentUserText -> 'ignored'
+ * (the offer was shown but the user produced no text containing it). null
+ * previousOffer -> 'ignored' (no offer, but caller asked for a class --
+ * conservative default). Acceptance-intent phrases ("yes", "ok", "do it")
+ * are NOT auto-classified as acted in v1.11.0; the user must reference the
+ * command. This is intentional: false positives on auto-classification are
+ * higher cost than false negatives (we suppress real signals).
+ */
+function classifyTurnOutcome(previousOffer, currentUserText) {
+  if (!previousOffer || typeof previousOffer !== 'object') return 'ignored';
+  const command = typeof previousOffer.command === 'string' ? previousOffer.command : '';
+  if (command.length === 0) return 'ignored';
+  if (typeof currentUserText !== 'string' || currentUserText.length === 0) return 'ignored';
+  return currentUserText.indexOf(command) !== -1 ? 'acted' : 'ignored';
+}
+
+// ---------- exports ----------
+
+module.exports = {
+  presentOffer: presentOffer,
+  recordOfferOutcome: recordOfferOutcome,
+  readOfferHistory: readOfferHistory,
+  classifyTurnOutcome: classifyTurnOutcome,
+  // Internal helpers exposed for test introspection.
+  _isReasonGrounded: isReasonGrounded,
+  _countTrailingIgnores: countTrailingIgnores,
+  _formatOfferLine: formatOfferLine,
+  // Frozen constants exposed for downstream introspection.
+  SIGNAL_KEYWORDS: SIGNAL_KEYWORDS,
+  GROUNDING_MIN_LENGTH: GROUNDING_MIN_LENGTH,
+  CONSECUTIVE_IGNORES_THRESHOLD: CONSECUTIVE_IGNORES_THRESHOLD,
+  HISTORY_MAX_ENTRIES: HISTORY_MAX_ENTRIES,
+};