@mindrian_os/install 1.13.0-beta.11

package/lib/memory/explain-decision-footer.test.cjs

@@ -0,0 +1,316 @@
+#!/usr/bin/env node
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 94-09 -- /mos:explain-decision Action Footer fixture tests
+ * =================================================================
+ * Per QA handoff Section 3 FIX-8: scripts/explain-decision-command.cjs
+ * renderTrace() output ends with `---` and no Next: action footer. The
+ * 4-zone Action Footer rule in skills/ui-system/SKILL.md (Section 1
+ * Zone 4: "NEVER omitted") is violated for /mos:explain-decision.
+ *
+ * Plan 94-09 appends an Action Footer at the END of the rendered output,
+ * AFTER the existing closing `---` separator. The footer offers 3
+ * canonical /mos:* commands (status / act / suggest-next) per the QA
+ * handoff Section 3 FIX-8 verbatim suggestion.
+ *
+ * Canon Part 7 (Reuse Before Build): extends scripts/explain-decision-
+ * command.cjs renderTrace() output by appending a footer. The 9 trace
+ * fields covered by lib/memory/explain-decision-command.test.cjs Tests
+ * 1-12 are byte-identical before the footer; the new footer is purely
+ * additive at the tail.
+ *
+ * Canon Part 3 (Tri-Context Decision Gate): the footer offers verbs
+ * from the canonical 10-verb vocabulary (status -> Synthesize, act ->
+ * Run Methodology, suggest-next -> Free-Text / Spawn Sub-Agent). No
+ * new verbs introduced.
+ *
+ * Test map:
+ *   T1 footer presence: last 5 lines of stdout contain literal 'Next:'
+ *   T2 footer content: footer contains at least 2 /mos: command refs
+ *   T3 non-regression: existing renderTrace prefix output (header +
+ *      9 trace fields + closing `---`) remains intact when the footer
+ *      is appended. Verified by checking that all existing markers
+ *      (Tier Mode, BRAIN.md signal, Five-Signal Triangulation, Chosen
+ *      rationale, the closing `---`) are still present and in order.
+ *   T4 graceful empty path: when the trace is empty (no decisions
+ *      recorded yet), the footer STILL renders. Stdout still contains
+ *      'Next:' substring.
+ *
+ * Registered in lib/memory/run-feynman-tests.cjs.
+ */
+
+'use strict';
+
+const assert = require('node:assert/strict');
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const { spawnSync } = require('node:child_process');
+
+const REPO = path.resolve(__dirname, '..', '..');
+const SCRIPT_PATH = path.join(REPO, 'scripts/explain-decision-command.cjs');
+
+// ---------- Test scaffolding ----------
+
+let passed = 0;
+let failed = 0;
+function run(name, fn) {
+  try {
+    fn();
+    process.stdout.write('ok  ' + name + '\n');
+    passed += 1;
+  } catch (err) {
+    process.stderr.write('FAIL ' + name + '\n');
+    process.stderr.write(String(err && err.stack ? err.stack : err) + '\n');
+    failed += 1;
+  }
+}
+
+// ---------- Fixture builders ----------
+
+const TMPDIRS = [];
+
+process.on('exit', () => {
+  for (const d of TMPDIRS) {
+    try { fs.rmSync(d, { recursive: true, force: true }); } catch (_) {}
+  }
+});
+
+function makeRoomsFixture(label) {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), '94-09-' + label + '-'));
+  TMPDIRS.push(tmp);
+  const root = path.join(tmp, 'MindrianRooms');
+  fs.mkdirSync(root, { recursive: true });
+  const roomDir = path.join(root, 'fixture-room');
+  fs.mkdirSync(roomDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(roomDir, 'STATE.md'),
+    '---\nproject: fixture room\n---\n\n# Fixture Room\n'
+  );
+  const regDir = path.join(root, '.rooms');
+  fs.mkdirSync(regDir, { recursive: true });
+  fs.writeFileSync(
+    path.join(regDir, 'registry.json'),
+    JSON.stringify({
+      version: 1,
+      active: 'fixture-room',
+      rooms: {
+        'fixture-room': { path: 'fixture-room' },
+      },
+    }, null, 2)
+  );
+  return { tmp: tmp, root: root, roomDir: roomDir };
+}
+
+function writeTraceFile(roomDir, sessionId, traces) {
+  const dir = path.join(roomDir, '.mindrian', 'decision-traces');
+  fs.mkdirSync(dir, { recursive: true });
+  const fp = path.join(dir, sessionId + '.json');
+  fs.writeFileSync(
+    fp,
+    JSON.stringify(
+      { version: 1, session_id: sessionId, traces: traces },
+      null,
+      2
+    )
+  );
+  return fp;
+}
+
+function makeTrace(turn, overrides) {
+  const base = {
+    turn: turn,
+    at: '2026-04-29T12:00:0' + (turn % 10) + '.000Z',
+    elapsed_ms: 12,
+    brain_md_version: 1,
+    brain_md_staleness: 'fresh',
+    brain_md_stale_reason: null,
+    brain_md_weight_applied: 1.0,
+    brain_md_recommended_confidence: 0.85,
+    brain_md_recommended_marker_rendered: true,
+    brain_md_tier_mode: 'mode_a',
+    brain_md_sections_consumed: ['pattern_matches', 'wicked_indicators'],
+    icm_scope: { section: 'market-analysis', scope_path: 'fixture-room/market-analysis' },
+    sql_signals: { edge_counts: 12, contradictions: 1, convergences: 3 },
+    minto_reasoning: {
+      governing_thought: 'Customers will pay for clarity',
+      reasoning_health_score: 0.7,
+      is_stale: false,
+    },
+    intent_persona: {
+      larry_persona: 'Researcher',
+      brain_persona: 'Implicit',
+      detection_confidence: 0.6,
+    },
+    chosen_rationale: 'Mode A: BRAIN.md fresh; pattern_matches confidence above 0.7 floor.',
+  };
+  return Object.assign({}, base, overrides || {});
+}
+
+function runCommand(roomDir, args, extraEnv) {
+  const env = Object.assign({}, process.env, {
+    MINDRIAN_ROOMS_HOME: path.dirname(roomDir),
+    MINDRIAN_ROOMS_ROOT: path.dirname(roomDir),
+  }, extraEnv || {});
+  return spawnSync(process.execPath, [SCRIPT_PATH].concat(args || []), {
+    env: env,
+    encoding: 'utf8',
+    timeout: 5000,
+  });
+}
+
+// =========================================================
+// Tests T1-T4 (Plan 94-09 Action Footer)
+// =========================================================
+
+run('T1 footer presence: last 5 lines of stdout contain literal Next:', () => {
+  const fix = makeRoomsFixture('t1');
+  writeTraceFile(fix.roomDir, 'sid-t1', [makeTrace(1)]);
+  const res = runCommand(fix.roomDir, [], { CLAUDE_SESSION_ID: 'sid-t1' });
+  assert.equal(res.status, 0, 'exit 0; stderr: ' + (res.stderr || ''));
+  const out = res.stdout || '';
+  // Trim trailing whitespace then split into lines.
+  const lines = out.replace(/\s+$/, '').split('\n');
+  const last5 = lines.slice(-5).join('\n');
+  assert.equal(
+    last5.indexOf('Next:') !== -1,
+    true,
+    'expected "Next:" in last 5 lines; got last 5 lines:\n' + last5 + '\n\nFull output:\n' + out
+  );
+});
+
+run('T2 footer content: at least 2 /mos: command refs in footer', () => {
+  const fix = makeRoomsFixture('t2');
+  writeTraceFile(fix.roomDir, 'sid-t2', [makeTrace(1)]);
+  const res = runCommand(fix.roomDir, [], { CLAUDE_SESSION_ID: 'sid-t2' });
+  assert.equal(res.status, 0, 'exit 0; stderr: ' + (res.stderr || ''));
+  const out = res.stdout || '';
+  // Locate the Next: marker and count /mos: occurrences AFTER it. The
+  // pre-94-09 output may already contain /mos: in advisory paths or
+  // in the chosen_rationale body. We isolate the footer by anchoring
+  // on the literal 'Next:' substring.
+  const idx = out.indexOf('Next:');
+  assert.equal(
+    idx !== -1,
+    true,
+    'expected "Next:" anchor; got:\n' + out
+  );
+  const footer = out.slice(idx);
+  const matches = footer.match(/\/mos:/g) || [];
+  assert.equal(
+    matches.length >= 2,
+    true,
+    'expected at least 2 /mos: commands in footer; found '
+      + matches.length + ' in:\n' + footer
+  );
+});
+
+run('T3 non-regression: existing renderTrace markers preserved before footer', () => {
+  const fix = makeRoomsFixture('t3');
+  writeTraceFile(fix.roomDir, 'sid-t3', [makeTrace(1)]);
+  const res = runCommand(fix.roomDir, [], { CLAUDE_SESSION_ID: 'sid-t3' });
+  assert.equal(res.status, 0, 'exit 0; stderr: ' + (res.stderr || ''));
+  const out = res.stdout || '';
+  // The 9 trace-field markers from lib/memory/explain-decision-command.test.cjs
+  // Tests 1-4 must all still appear in the output.
+  const requiredMarkers = [
+    'Navigation Engine Decision Trace', // header
+    'Turn 1',                            // structural turn
+    'Tier Mode',                         // brain_md_tier_mode label
+    'mode_a',                            // tier_mode value
+    'BRAIN.md signal',                   // section header
+    'version:',
+    'staleness:',
+    'stale_reason:',
+    'weight_applied:',
+    'sections_consumed:',
+    'RECOMMENDED marker',
+    'rendered:',
+    'highest_confidence:',
+    'Five-Signal Triangulation',
+    'ICM scope',
+    'SQL signals',
+    'Feynman-MINTO',
+    'BRAIN patterns',
+    'Intent + Persona',
+    'Chosen rationale',                  // chosen_rationale section
+    'pattern_matches',                   // brain_md_sections_consumed value
+    'market-analysis',                   // icm_scope.section value
+    'Customers will pay',                // minto_reasoning.governing_thought
+    'Researcher',                        // intent_persona.larry_persona
+    'Mode A: BRAIN.md fresh',            // chosen_rationale verbatim prefix
+  ];
+  for (const m of requiredMarkers) {
+    assert.equal(
+      out.indexOf(m) !== -1,
+      true,
+      'pre-94-09 marker missing after footer append: "' + m + '"'
+        + '\nFull output:\n' + out
+    );
+  }
+  // The closing `---` separator MUST appear BEFORE the Next: footer.
+  // Pre-94-09 output ended with `---\n`. Plan 94-09 appends the footer
+  // AFTER that `---`, so the order is: ...content... `---` ... `Next:`.
+  const sepIdx = out.lastIndexOf('\n---');
+  const nextIdx = out.indexOf('Next:');
+  assert.equal(
+    sepIdx !== -1,
+    true,
+    'closing `---` separator missing; got:\n' + out
+  );
+  assert.equal(
+    nextIdx !== -1,
+    true,
+    '"Next:" footer missing; got:\n' + out
+  );
+  assert.equal(
+    sepIdx < nextIdx,
+    true,
+    'closing `---` must precede the Next: footer; sepIdx=' + sepIdx
+      + ' nextIdx=' + nextIdx + '\nFull output:\n' + out
+  );
+});
+
+run('T4 graceful empty path: footer renders when no decisions yet', () => {
+  // Empty traces array. Pre-94-09 the script prints the
+  // "No decisions recorded for this session." advisory and exits 0
+  // with no footer. Plan 94-09 appends the footer to the empty path
+  // too, so the user always gets a navigable next step.
+  const fix = makeRoomsFixture('t4');
+  writeTraceFile(fix.roomDir, 'empty-sid', []);
+  const res = runCommand(fix.roomDir, [], { CLAUDE_SESSION_ID: 'empty-sid' });
+  assert.equal(res.status, 0, 'exit 0; stderr: ' + (res.stderr || ''));
+  const out = res.stdout || '';
+  // Empty-path advisory still rendered.
+  assert.equal(
+    out.indexOf('No decisions recorded') !== -1,
+    true,
+    'empty-path advisory missing; got:\n' + out
+  );
+  // Footer rendered too.
+  assert.equal(
+    out.indexOf('Next:') !== -1,
+    true,
+    'expected "Next:" footer on empty-path output; got:\n' + out
+  );
+  // At least 2 /mos: command refs after the Next: anchor.
+  const idx = out.indexOf('Next:');
+  const footer = out.slice(idx);
+  const matches = footer.match(/\/mos:/g) || [];
+  assert.equal(
+    matches.length >= 2,
+    true,
+    'expected at least 2 /mos: commands in empty-path footer; found '
+      + matches.length + ' in:\n' + footer
+  );
+});
+
+// ---------- Reporter ----------
+
+process.stdout.write('\n');
+process.stdout.write('explain-decision-footer: ' + passed + '/' + (passed + failed) + ' passed\n');
+if (failed > 0) {
+  process.exit(1);
+}
+process.exit(0);

package/lib/memory/explored-materials-store.cjs

@@ -0,0 +1,392 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 117-01 Wave 1 -- explored-materials-store substrate.
+ *
+ * JSONL append-only state store at ~/.mindrian/explored-materials/<roomSlug>.jsonl.
+ * Per CLAUDE.md workspace guard: writes OUTSIDE plugin repo (os.homedir()).
+ * Per Canon Part 8: USER_CONTENT_KEY_DENYLIST guards against telemetry leakage.
+ *
+ * Graph-native HARD RULE (memory feedback_reverse_salient_agent_graph_native.md):
+ *   1. NEVER require room-db.cjs (Phase 109 D-06 chokepoint).
+ *   2. NEVER require brain-client (Canon Part 8 boundary).
+ *   3. NEVER call console.log or process.stdout.write (dual-surface telemetry contract).
+ *
+ * Pattern: append-only writer + LWW replay (mirrors lib/memory/pending-tension-store.cjs
+ * Phase 116-01 verbatim; field substitutions per RESEARCH Section 3 sibling code-clone).
+ *
+ * DELTA vs Phase 116-01 pending-tension-store.cjs: same 8-export skeleton; field
+ * renames (tension_id -> material_id; tension_type -> mtime_seconds; source_node_ids
+ * -> relative_file_path). State machine vocabulary differs (queued | in_flight |
+ * completed | failed instead of queued | surfaced | resolved | dropped). 2 new
+ * exports added (markFailed, sweepStaleInFlight) to handle the in_flight
+ * stale-sweep that 116 does not have because tensions have no background-spawn
+ * lifecycle.
+ *
+ * Pure CJS, node built-ins only, zero new runtime dependencies.
+ */
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+const crypto = require('node:crypto');
+
+// ---------- Constants ----------
+
+const EXPLORED_MATERIALS_DIR = path.join(os.homedir(), '.mindrian', 'explored-materials');
+
+const VALID_STATES = Object.freeze(new Set(['queued', 'in_flight', 'completed', 'failed']));
+
+const VALID_RESPONSES = Object.freeze(new Set(['EXPLORE', 'SKIP', 'LATER', 'FREE_TEXT']));
+
+const VALID_SUPPRESS_REASONS = Object.freeze(new Set([
+  'tier_0',
+  'just_talk',
+  'dispatcher_load_failed',
+  'pickShape_unavailable',
+  'all_pipelines_empty',
+  'brain_baseline_unavailable',
+  'rate_limited',
+  'daily_cap_exceeded',
+  'room_dir_not_writable',
+  'ledger_replay_failed',
+  'hybrid_mode_insufficient_corpus',
+  'sanitizer_blocked',
+  'invalid_args',
+]));
+
+// User-content key denylist (Canon Part 8 -- artifact bodies, titles, transcripts
+// live in the graph, never in this JSONL). Rejection is fail-fast at
+// appendMaterial time so a caller bug never leaks user content to disk.
+// NOTE: relative_file_path IS allowed in the ledger (LOCAL-only state file
+// outside the plugin repo per workspace guard), but MUST be hashed to
+// file_path_sha256 BEFORE any memory_event payload write or telemetry mirror.
+const USER_CONTENT_KEY_DENYLIST = Object.freeze(new Set([
+  'body_text',
+  'source_title',
+  'target_title',
+  'artifact_body',
+  'note_content',
+  'transcript_content',
+  'meeting_summary',
+  'cv_content',
+  'file_content',
+]));
+
+const MATERIAL_ID_LEN = 32;
+const STALE_IN_FLIGHT_MS_DEFAULT = 300000; // 5 minutes per RESEARCH scenario 7
+
+// ---------- Material id (deterministic, second-precision) ----------
+
+/**
+ * Compute the deterministic material id for a (roomDir, relativeFilePath, mtimeMs)
+ * tuple. Per RESEARCH Section 4.5: mtime is FLOORED to seconds for cross-fs
+ * portability (FAT32, NFS, etc. lack ms-precision; risk T1).
+ *
+ * @param {string} roomDir            absolute path to room (with .room-root)
+ * @param {string} relativeFilePath   path relative to roomDir
+ * @param {number} mtimeMs            file mtime in ms-epoch
+ * @returns {string} 32-char hex sha256 prefix
+ */
+function computeMaterialId(roomDir, relativeFilePath, mtimeMs) {
+  const seconds = Math.floor(Number(mtimeMs) / 1000);
+  const basis = String(roomDir) + '|' + String(relativeFilePath) + '|' + String(seconds);
+  return crypto.createHash('sha256').update(basis).digest('hex').slice(0, MATERIAL_ID_LEN);
+}
+
+// ---------- JSONL path resolution (workspace-guard-clean) ----------
+
+/**
+ * Resolve the JSONL path for a given room slug. Always returns a path under
+ * os.homedir() per CLAUDE.md workspace guard (OUTSIDE the plugin repo).
+ *
+ * @param {string} roomSlug
+ * @returns {string} absolute path
+ */
+function jsonlPath(roomSlug) {
+  const safeSlug = encodeURIComponent(String(roomSlug || 'default-room'));
+  return path.join(EXPLORED_MATERIALS_DIR, safeSlug + '.jsonl');
+}
+
+// ---------- Internal helpers ----------
+
+function isPlainObject(v) {
+  return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+
+function isHex32(v) {
+  return typeof v === 'string' && /^[0-9a-f]{32}$/.test(v);
+}
+
+function violatesUserContentBoundary(entry) {
+  for (const k of Object.keys(entry)) {
+    if (USER_CONTENT_KEY_DENYLIST.has(k)) return k;
+  }
+  return null;
+}
+
+// ---------- Validation ----------
+
+/**
+ * Validate the shape of an entry. Returns { ok: true } on success, or
+ * { ok: false, reason, offending_key? } on rejection.
+ *
+ * Canon Part 8 enforcement: any USER_CONTENT_KEY_DENYLIST key in the entry
+ * triggers a canon_part_8_violation rejection (fail-fast before disk write).
+ *
+ * @param {object} entry
+ * @returns {{ok: true} | {ok: false, reason: string, offending_key?: string}}
+ */
+function validateEntryShape(entry) {
+  if (!isPlainObject(entry)) {
+    return { ok: false, reason: 'entry_not_object' };
+  }
+  // Canon Part 8 boundary -- check FIRST so a payload with denylist keys is
+  // rejected even if other shape checks would also fail.
+  const violator = violatesUserContentBoundary(entry);
+  if (violator) {
+    return { ok: false, reason: 'canon_part_8_violation', offending_key: violator };
+  }
+  if (!isHex32(entry.material_id)) {
+    return { ok: false, reason: 'invalid_material_id' };
+  }
+  if (!VALID_STATES.has(entry.state)) {
+    return { ok: false, reason: 'invalid_state' };
+  }
+  if (!Number.isInteger(entry.mtime_seconds) || entry.mtime_seconds < 0) {
+    return { ok: false, reason: 'invalid_mtime_seconds' };
+  }
+  if (!Number.isInteger(entry.fired_at) || entry.fired_at < 0) {
+    return { ok: false, reason: 'invalid_fired_at' };
+  }
+  return { ok: true };
+}
+
+// ---------- Public API ----------
+
+/**
+ * Append a material entry to the room's JSONL file. Creates the directory if
+ * missing. Validates shape + Canon Part 8 boundary; rejects user-content
+ * fields.
+ *
+ * @param {string} roomSlug
+ * @param {object} entry  conforming to RESEARCH Section 4.5 schema
+ * @returns {{ok: true, path: string} | {ok: false, reason: string, offending_key?: string}}
+ */
+function appendMaterial(roomSlug, entry) {
+  const validation = validateEntryShape(entry);
+  if (!validation.ok) return validation;
+  try {
+    fs.mkdirSync(EXPLORED_MATERIALS_DIR, { recursive: true });
+    const file = jsonlPath(roomSlug);
+    fs.appendFileSync(file, JSON.stringify(entry) + '\n');
+    return { ok: true, path: file };
+  } catch (err) {
+    const msg = (err && err.message) ? String(err.message) : 'append_failed';
+    return { ok: false, reason: msg.slice(0, 80) };
+  }
+}
+
+/**
+ * Read all materials for a room, applying LWW replay (last entry per
+ * material_id wins). Returns [] when the file is missing. Tolerates corrupt
+ * lines by skipping them silently.
+ *
+ * @param {string} roomSlug
+ * @returns {Array<object>}
+ */
+function readMaterials(roomSlug) {
+  const file = jsonlPath(roomSlug);
+  if (!fs.existsSync(file)) return [];
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (_e) {
+    return [];
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  const byId = new Map();
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (_e) {
+      continue; // corrupt line tolerated per RESEARCH Section 4.5 LWW replay tolerance
+    }
+    if (!isPlainObject(entry) || !isHex32(entry.material_id)) continue;
+    byId.set(entry.material_id, entry);
+  }
+  return Array.from(byId.values());
+}
+
+/**
+ * Find the latest entry for a single material_id. Returns null when missing.
+ * Sorts by fired_at descending so the most-recent entry wins regardless of
+ * append order.
+ *
+ * @param {string} roomSlug
+ * @param {string} materialId   32-char hex
+ * @returns {object|null}
+ */
+function findLatest(roomSlug, materialId) {
+  if (!isHex32(materialId)) return null;
+  const file = jsonlPath(roomSlug);
+  if (!fs.existsSync(file)) return null;
+  let raw;
+  try {
+    raw = fs.readFileSync(file, 'utf8');
+  } catch (_e) {
+    return null;
+  }
+  const lines = raw.split('\n').filter(Boolean);
+  let latest = null;
+  for (const line of lines) {
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch (_e) {
+      continue;
+    }
+    if (!isPlainObject(entry)) continue;
+    if (entry.material_id !== materialId) continue;
+    if (latest === null) {
+      latest = entry;
+      continue;
+    }
+    const a = Number.isInteger(entry.fired_at) ? entry.fired_at : 0;
+    const b = Number.isInteger(latest.fired_at) ? latest.fired_at : 0;
+    if (a >= b) latest = entry;
+  }
+  return latest;
+}
+
+/**
+ * Mark a material as completed. Appends a transition entry where state is
+ * 'completed' and finding_count is set from fields.
+ *
+ * @param {string} roomSlug
+ * @param {string} materialId
+ * @param {object} fields  { finding_count: number }
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function markCompleted(roomSlug, materialId, fields) {
+  const prev = findLatest(roomSlug, materialId);
+  if (!prev) return { ok: false, reason: 'material_not_found' };
+  const fc = (fields && Number.isInteger(fields.finding_count)) ? fields.finding_count : null;
+  const next = Object.assign({}, prev, {
+    state: 'completed',
+    finding_count: fc,
+    in_flight_since: null,
+  });
+  const r = appendMaterial(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true };
+}
+
+/**
+ * Mark a material as failed with a suppression reason. If the material is
+ * not yet in the ledger, append a fresh 'failed' entry (suppression on the
+ * very first detection event).
+ *
+ * @param {string} roomSlug
+ * @param {string} materialId
+ * @param {string} suppressReason  one of VALID_SUPPRESS_REASONS
+ * @returns {{ok: true} | {ok: false, reason: string}}
+ */
+function markFailed(roomSlug, materialId, suppressReason) {
+  if (!VALID_SUPPRESS_REASONS.has(suppressReason)) {
+    return { ok: false, reason: 'invalid_suppress_reason' };
+  }
+  if (!isHex32(materialId)) {
+    return { ok: false, reason: 'invalid_material_id' };
+  }
+  const prev = findLatest(roomSlug, materialId);
+  let next;
+  if (prev) {
+    next = Object.assign({}, prev, {
+      state: 'failed',
+      suppress_reason: suppressReason,
+      in_flight_since: null,
+    });
+  } else {
+    // Suppression on first event -- caller has not yet appended a queued entry.
+    next = {
+      material_id: materialId,
+      file_path_sha256: null,
+      relative_file_path: null,
+      mtime_seconds: 0,
+      fired_at: Date.now(),
+      state: 'failed',
+      finding_count: null,
+      surfaced: false,
+      user_response: null,
+      responded_at: null,
+      suppress_reason: suppressReason,
+      in_flight_since: null,
+    };
+  }
+  const r = appendMaterial(roomSlug, next);
+  if (!r.ok) return r;
+  return { ok: true };
+}
+
+/**
+ * Sweep stale in_flight entries. Per RESEARCH scenario 7 (5min stale
+ * recovery): an entry with state==='in_flight' AND
+ * (now - in_flight_since) > staleMs is transitioned to 'failed' with
+ * suppress_reason='rate_limited' (benign reason; the spawn child likely
+ * crashed or timed out, and the next detection of the same material_id
+ * will be free to fire fresh).
+ *
+ * Idempotent: re-running on the same JSONL is a no-op when no entries are
+ * stale (terminal states 'completed' and 'failed' are excluded from the scan).
+ *
+ * Sync. Never throws. On any error returns { ok: true, swept: 0 } so the
+ * SessionStart hook can never be derailed by a sweep failure.
+ *
+ * @param {string} roomSlug
+ * @param {object} opts  { staleMs: number }
+ * @returns {{ok: true, swept: number}}
+ */
+function sweepStaleInFlight(roomSlug, opts) {
+  try {
+    const staleMs = (opts && Number.isInteger(opts.staleMs) && opts.staleMs > 0)
+      ? opts.staleMs
+      : STALE_IN_FLIGHT_MS_DEFAULT;
+    const now = Date.now();
+    const entries = readMaterials(roomSlug);
+    let swept = 0;
+    for (const e of entries) {
+      if (!isPlainObject(e)) continue;
+      if (e.state !== 'in_flight') continue;
+      if (!Number.isInteger(e.in_flight_since)) continue;
+      if ((now - e.in_flight_since) <= staleMs) continue;
+      const r = markFailed(roomSlug, e.material_id, 'rate_limited');
+      if (r && r.ok) swept += 1;
+    }
+    return { ok: true, swept: swept };
+  } catch (_e) {
+    return { ok: true, swept: 0 };
+  }
+}
+
+// ---------- Module exports ----------
+
+module.exports = {
+  computeMaterialId,
+  jsonlPath,
+  validateEntryShape,
+  appendMaterial,
+  readMaterials,
+  findLatest,
+  markCompleted,
+  markFailed,
+  sweepStaleInFlight,
+  EXPLORED_MATERIALS_DIR,
+  MATERIAL_ID_LEN,
+  VALID_STATES,
+  VALID_RESPONSES,
+  VALID_SUPPRESS_REASONS,
+  USER_CONTENT_KEY_DENYLIST,
+};