@mindrian_os/cli 1.13.0-beta.10 → 1.13.0-beta.44

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

@@ -1,316 +0,0 @@
-#!/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

@@ -1,392 +0,0 @@
-/*
- * 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,
-};