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

package/lib/mcp/session-catchup.cjs

@@ -0,0 +1,349 @@
+'use strict';
+
+/**
+ * MindrianOS Plugin -- Session Catch-Up (SCHED-01)
+ *
+ * On MCP server init (Cowork), reads room/.mindrian/last-session.json,
+ * computes what changed since the last session:
+ *   - Hours since last scout run
+ *   - Predictions approaching deadline
+ *   - New files added since last session
+ *   - Stale sections (no updates in 7+ days)
+ *
+ * Returns a structured catch-up summary for the first resource notification.
+ * Writes last-session.json on SIGTERM / graceful shutdown.
+ *
+ * @module session-catchup
+ */
+
+const fs = require('fs');
+const path = require('path');
+
+const STALE_THRESHOLD_DAYS = 7;
+const MS_PER_HOUR = 3600000;
+const MS_PER_DAY = 86400000;
+
+/**
+ * Path to last-session.json inside a room.
+ * @param {string} roomDir
+ * @returns {string}
+ */
+function lastSessionPath(roomDir) {
+  return path.join(roomDir, '.mindrian', 'last-session.json');
+}
+
+/**
+ * Read the last session record.
+ * @param {string} roomDir
+ * @returns {{ timestamp: string, scoutTimestamp: string|null, fileSnapshot: string[], activeMethodology: string|null } | null}
+ */
+function readLastSession(roomDir) {
+  const p = lastSessionPath(roomDir);
+  try {
+    const raw = fs.readFileSync(p, 'utf8');
+    return JSON.parse(raw);
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Write the last session record.
+ * @param {string} roomDir
+ * @param {object} data
+ */
+function writeLastSession(roomDir, data) {
+  const p = lastSessionPath(roomDir);
+  const dir = path.dirname(p);
+  try {
+    if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(p, JSON.stringify(data, null, 2));
+  } catch (e) {
+    process.stderr.write(`[session-catchup] Failed to write last-session.json: ${e.message}\n`);
+  }
+}
+
+/**
+ * Recursively collect all .md files in a directory with their mtimes.
+ * @param {string} dir
+ * @param {string} baseDir - root for relative paths
+ * @returns {Array<{relPath: string, mtime: number}>}
+ */
+function collectFiles(dir, baseDir) {
+  const results = [];
+  if (!fs.existsSync(dir)) return results;
+
+  try {
+    const entries = fs.readdirSync(dir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (entry.name.startsWith('.')) continue;
+      const fullPath = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        results.push(...collectFiles(fullPath, baseDir));
+      } else if (entry.name.endsWith('.md') && entry.name !== 'STATE.md' && entry.name !== 'ROOM.md') {
+        try {
+          const stat = fs.statSync(fullPath);
+          results.push({
+            relPath: path.relative(baseDir, fullPath),
+            mtime: stat.mtimeMs,
+          });
+        } catch (_e) { /* skip */ }
+      }
+    }
+  } catch (_e) { /* skip */ }
+
+  return results;
+}
+
+/**
+ * Read prediction registry and find approaching deadlines.
+ * @param {string} roomDir
+ * @returns {Array<{title: string, deadline: string, daysRemaining: number}>}
+ */
+function getApproachingPredictions(roomDir) {
+  const registryPath = path.join(roomDir, '.predictions', 'REGISTRY.json');
+  if (!fs.existsSync(registryPath)) return [];
+
+  try {
+    const raw = fs.readFileSync(registryPath, 'utf8');
+    const registry = JSON.parse(raw);
+    const predictions = registry.predictions || registry.entries || [];
+    const now = Date.now();
+    const approaching = [];
+
+    for (const pred of predictions) {
+      if (!pred.deadline && !pred.due_date) continue;
+      const deadline = pred.deadline || pred.due_date;
+      const deadlineMs = new Date(deadline).getTime();
+      if (isNaN(deadlineMs)) continue;
+
+      const daysRemaining = Math.floor((deadlineMs - now) / MS_PER_DAY);
+      // Show predictions due within 14 days (including overdue)
+      if (daysRemaining <= 14) {
+        approaching.push({
+          title: pred.title || pred.description || pred.id || 'Untitled prediction',
+          deadline,
+          daysRemaining,
+        });
+      }
+    }
+
+    // Sort: overdue first, then by soonest
+    approaching.sort((a, b) => a.daysRemaining - b.daysRemaining);
+    return approaching;
+  } catch (_e) {
+    return [];
+  }
+}
+
+/**
+ * Detect stale sections (no file updates in 7+ days).
+ * @param {string} roomDir
+ * @returns {Array<{section: string, daysSinceUpdate: number}>}
+ */
+function getStaleSections(roomDir) {
+  const stale = [];
+  const now = Date.now();
+
+  try {
+    const entries = fs.readdirSync(roomDir, { withFileTypes: true });
+    for (const entry of entries) {
+      if (!entry.isDirectory()) continue;
+      if (entry.name.startsWith('.') || entry.name === 'exports' || entry.name === 'intelligence') continue;
+
+      const sectionDir = path.join(roomDir, entry.name);
+      const files = collectFiles(sectionDir, sectionDir);
+      if (files.length === 0) continue;
+
+      const latestMtime = Math.max(...files.map(f => f.mtime));
+      const daysSince = Math.floor((now - latestMtime) / MS_PER_DAY);
+
+      if (daysSince >= STALE_THRESHOLD_DAYS) {
+        stale.push({
+          section: entry.name,
+          daysSinceUpdate: daysSince,
+        });
+      }
+    }
+  } catch (_e) { /* skip */ }
+
+  // Sort by stalest first
+  stale.sort((a, b) => b.daysSinceUpdate - a.daysSinceUpdate);
+  return stale;
+}
+
+/**
+ * Compute the full catch-up summary for this session.
+ *
+ * @param {string} roomDir - Absolute path to room directory
+ * @returns {{ hasCatchUp: boolean, hoursSinceLastSession: number|null, hoursSinceScout: number|null, newFiles: string[], predictionsApproaching: Array, staleSections: Array, summary: string }}
+ */
+function computeCatchUp(roomDir) {
+  const result = {
+    hasCatchUp: false,
+    hoursSinceLastSession: null,
+    hoursSinceScout: null,
+    newFiles: [],
+    predictionsApproaching: [],
+    staleSections: [],
+    summary: '',
+  };
+
+  if (!fs.existsSync(roomDir)) {
+    result.summary = 'No room directory found.';
+    return result;
+  }
+
+  const lastSession = readLastSession(roomDir);
+  const now = Date.now();
+
+  // Hours since last session
+  if (lastSession && lastSession.timestamp) {
+    const lastMs = new Date(lastSession.timestamp).getTime();
+    if (!isNaN(lastMs)) {
+      result.hoursSinceLastSession = Math.round((now - lastMs) / MS_PER_HOUR * 10) / 10;
+      result.hasCatchUp = true;
+    }
+  }
+
+  // Hours since last scout
+  if (lastSession && lastSession.scoutTimestamp) {
+    const scoutMs = new Date(lastSession.scoutTimestamp).getTime();
+    if (!isNaN(scoutMs)) {
+      result.hoursSinceScout = Math.round((now - scoutMs) / MS_PER_HOUR * 10) / 10;
+    }
+  }
+
+  // New files since last session
+  if (lastSession && lastSession.fileSnapshot) {
+    const previousFiles = new Set(lastSession.fileSnapshot);
+    const currentFiles = collectFiles(roomDir, roomDir);
+    result.newFiles = currentFiles
+      .filter(f => !previousFiles.has(f.relPath))
+      .map(f => f.relPath);
+  }
+
+  // Approaching predictions
+  result.predictionsApproaching = getApproachingPredictions(roomDir);
+
+  // Stale sections
+  result.staleSections = getStaleSections(roomDir);
+
+  // Build human-readable summary
+  const parts = [];
+
+  if (result.hoursSinceLastSession !== null) {
+    parts.push(`Last session was ${result.hoursSinceLastSession} hours ago.`);
+  } else {
+    parts.push('This is the first session (no previous session data).');
+  }
+
+  if (result.hoursSinceScout !== null && result.hoursSinceScout > 24) {
+    parts.push(`Scout hasn't run in ${Math.round(result.hoursSinceScout)} hours - consider running /mos:scout.`);
+  }
+
+  if (result.newFiles.length > 0) {
+    parts.push(`${result.newFiles.length} new file(s) since last session: ${result.newFiles.slice(0, 5).join(', ')}${result.newFiles.length > 5 ? '...' : ''}`);
+  }
+
+  const overdue = result.predictionsApproaching.filter(p => p.daysRemaining < 0);
+  const urgent = result.predictionsApproaching.filter(p => p.daysRemaining >= 0 && p.daysRemaining <= 3);
+  if (overdue.length > 0) {
+    parts.push(`${overdue.length} OVERDUE prediction(s): ${overdue.map(p => p.title).join(', ')}`);
+  }
+  if (urgent.length > 0) {
+    parts.push(`${urgent.length} prediction(s) due within 3 days: ${urgent.map(p => p.title).join(', ')}`);
+  }
+
+  if (result.staleSections.length > 0) {
+    parts.push(`${result.staleSections.length} stale section(s) (7+ days): ${result.staleSections.map(s => `${s.section} (${s.daysSinceUpdate}d)`).join(', ')}`);
+  }
+
+  result.summary = parts.join(' ');
+  if (result.predictionsApproaching.length > 0 || result.staleSections.length > 0 || result.newFiles.length > 0) {
+    result.hasCatchUp = true;
+  }
+
+  return result;
+}
+
+/**
+ * Create a snapshot of the current session state for later comparison.
+ * Call this on SIGTERM or session end.
+ *
+ * @param {string} roomDir
+ * @param {object} [extra] - Additional fields to persist (scoutTimestamp, activeMethodology)
+ */
+function snapshotSession(roomDir, extra = {}) {
+  const currentFiles = collectFiles(roomDir, roomDir);
+  const data = {
+    timestamp: new Date().toISOString(),
+    scoutTimestamp: extra.scoutTimestamp || null,
+    activeMethodology: extra.activeMethodology || null,
+    fileSnapshot: currentFiles.map(f => f.relPath),
+    fileCount: currentFiles.length,
+  };
+  writeLastSession(roomDir, data);
+}
+
+/**
+ * Register SIGTERM handler to snapshot session on server shutdown.
+ * Safe to call multiple times (idempotent) -- the SIGTERM/SIGINT/beforeExit
+ * listeners themselves are attached exactly once, ever, per process.
+ *
+ * Phase 270-08 addition: an optional `extraTeardown` callback (e.g.
+ * lib/mcp/tree-watcher.cjs's stopTreeWatcher) can be registered to run
+ * alongside the session snapshot on the SAME shutdown event, so a second
+ * caller never needs to add its own independent process.on('SIGTERM'/
+ * 'SIGINT'/'beforeExit') listener. Each registered call's `roomDir`
+ * argument is ignored after the first (this handler is a process-wide
+ * singleton, matching its pre-existing idempotent contract); pass a falsy
+ * roomDir when the ONLY reason for this call is to register extraTeardown.
+ *
+ * @param {string} roomDir
+ * @param {function} [extraTeardown] - optional additional callback run on
+ *   the same shutdown event, after the session snapshot. Never let one
+ *   teardown callback's failure block another's.
+ */
+let _shutdownRegistered = false;
+const _extraTeardownCallbacks = [];
+function registerShutdownHandler(roomDir, extraTeardown) {
+  if (typeof extraTeardown === 'function') _extraTeardownCallbacks.push(extraTeardown);
+  if (_shutdownRegistered) return;
+  _shutdownRegistered = true;
+
+  // I-4 fix: guard against double-fire when SIGINT triggers followed by beforeExit
+  let _shutdownDone = false;
+  const handler = () => {
+    if (_shutdownDone) return;
+    _shutdownDone = true;
+    try {
+      snapshotSession(roomDir);
+      process.stderr.write('[session-catchup] Session state saved on shutdown.\n');
+    } catch (e) {
+      process.stderr.write(`[session-catchup] Failed to save on shutdown: ${e.message}\n`);
+    }
+    for (const cb of _extraTeardownCallbacks) {
+      try {
+        cb();
+      } catch (e) {
+        process.stderr.write(`[session-catchup] an extra teardown callback failed: ${e && e.message ? e.message : String(e)}\n`);
+      }
+    }
+  };
+
+  process.on('SIGTERM', handler);
+  process.on('SIGINT', handler);
+  // Also handle graceful exit
+  process.on('beforeExit', handler);
+}
+
+module.exports = {
+  computeCatchUp,
+  snapshotSession,
+  readLastSession,
+  writeLastSession,
+  registerShutdownHandler,
+  getApproachingPredictions,
+  getStaleSections,
+};

package/lib/mcp/session-registry.cjs

@@ -0,0 +1,113 @@
+'use strict';
+// Phase 198-02 (SPEC-1, D-02) -- MCP connection <-> sessionId <-> Phase-194
+// binding key. This is a WIRE-AND-CONSUME module: it keys into
+// lib/core/session-binding.cjs (the shipped Phase 194 store) and
+// lib/core/session-presence.cjs (the shipped per-room presence ledger). It
+// stores NO room state itself -- binding reads/writes stay in session-binding.cjs.
+//
+// D-02 design pin (the one-namespace rule): the MCP connection's sessionId IS
+// the Phase-194 binding key. There is no second session namespace. A caller
+// (the daemon's onsessioninitialized callback, or a future stdio shim passing
+// a hook-derived sessionId through as the connection key) calls open(sid) with
+// that SAME string; readSessionBinding(sid)/writeSessionBinding(sid, ...)
+// then resolve against the identical key.
+//
+// isSafeSlug is IMPORTED from session-binding.cjs (the predicate that guards
+// the store), never re-implemented here (Canon Part 7).
+//
+// Canon Part 8: zero Brain/network token. CJS only. No em-dashes.
+
+const path = require('node:path');
+const os = require('node:os');
+const { isSafeSlug, readSessionBinding } = require('../core/session-binding.cjs');
+const sessionPresence = require('../core/session-presence.cjs');
+
+// In-memory only -- a durable daemon process holds this for its lifetime.
+// openSessions: the set of sessionIds this registry currently considers open.
+// connectionMap: connectionKey -> sessionId. A stdio-shim-supplied hook
+// sessionId is accepted verbatim (connectionKey === sessionId when the caller
+// does not supply a distinct connectionKey), so sessionIdFor(hookSid) resolves
+// to itself with no second lookup table entry required.
+const openSessions = new Set();
+const connectionMap = new Map();
+
+function resolveRoomsHome() {
+  return process.env.MINDRIAN_ROOMS_HOME
+    || path.join(process.env.HOME || process.env.USERPROFILE || os.homedir(), 'MindrianRooms');
+}
+
+/**
+ * open(sid, opts) -- register a connection under sessionId `sid`. When
+ * opts.connectionKey differs from `sid` (e.g. a transport-minted id distinct
+ * from a hook-supplied session string), the registry keys BOTH: the
+ * connectionKey resolves to `sid`, and `sid` resolves to itself directly.
+ * Rejects an unsafe slug (path-traversal guard, shared with the binding
+ * store) and returns null without registering anything.
+ *
+ * @param {string} sid
+ * @param {{connectionKey?: string}} [opts]
+ * @returns {string|null} the registered sessionId, or null on rejection
+ */
+function open(sid, opts) {
+  if (!isSafeSlug(sid)) return null;
+  openSessions.add(sid);
+  const o = opts || {};
+  const connectionKey = (typeof o.connectionKey === 'string' && isSafeSlug(o.connectionKey))
+    ? o.connectionKey
+    : sid;
+  connectionMap.set(connectionKey, sid);
+  return sid;
+}
+
+/**
+ * has(sid) -- is this sessionId currently open?
+ * @param {string} sid
+ * @returns {boolean}
+ */
+function has(sid) {
+  return openSessions.has(sid);
+}
+
+/**
+ * sessionIdFor(connectionKey) -- resolve a connection key (transport-minted
+ * id or hook-supplied sessionId string) to its registered sessionId. Returns
+ * null when the connection is not (or no longer) registered.
+ *
+ * @param {string} connectionKey
+ * @returns {string|null}
+ */
+function sessionIdFor(connectionKey) {
+  if (typeof connectionKey !== 'string') return null;
+  if (connectionMap.has(connectionKey)) return connectionMap.get(connectionKey);
+  return openSessions.has(connectionKey) ? connectionKey : null;
+}
+
+/**
+ * close(sid) -- deregister a connection's sessionId. Idempotent (closing a
+ * sid that was never open, or twice, is a no-op). Where this session's global
+ * binding names a `primary` room, its per-room presence ledger entry is
+ * deregistered too (deregisterPresence is fire-and-forget and never throws --
+ * session-presence.cjs's own contract). Never throws.
+ *
+ * @param {string} sid
+ */
+function close(sid) {
+  if (!isSafeSlug(sid)) return;
+  openSessions.delete(sid);
+  for (const key of connectionMap.keys()) {
+    if (connectionMap.get(key) === sid) connectionMap.delete(key);
+  }
+  try {
+    const home = resolveRoomsHome();
+    const binding = readSessionBinding(sid, { home: home });
+    const primary = binding && typeof binding.primary === 'string' ? binding.primary : null;
+    if (primary) {
+      const roomDir = path.join(home, primary);
+      sessionPresence.deregisterPresence({ sessionId: sid, roomDir: roomDir, home: home });
+    }
+  } catch (_e) {
+    // Fire-and-forget: presence deregistration failure never blocks connection close.
+  }
+}
+
+module.exports = { open, close, has, sessionIdFor };

package/lib/mcp/session-room.cjs

@@ -0,0 +1,124 @@
+'use strict';
+// Phase 248-01 (CTX-01/CTX-02) -- the ONE MCP room resolver.
+//
+// This module replaces the NINE independent gate-then-fallthrough
+// resolveSessionRoomDir/resolveWriteTargetDir copies that used to live one
+// per lib/mcp/tools/*.cjs file plus lib/mcp/tool-router.cjs and
+// lib/mcp/stop-gate-handler.cjs (research census, verified 2026-08-10).
+// Reintroducing a copy anywhere under lib/mcp/ turns
+// tests/test-248-resolver-census.cjs red (source-grep tripwire).
+//
+// THE DOCTRINE CHANGE (named explicitly, never slipped in): binding reads are
+// now UNCONDITIONAL. Every retired copy only consulted a session's room_bind
+// write inside `if (isMcpFirst(surface))`, and MINDRIAN_MCP_FIRST is unset on
+// every install by default (D-07), so room_bind's write was never read. This
+// module calls core resolveSessionRoom / resolveWriteRoom WITHOUT any
+// isMcpFirst gate on the read path -- the flag and the surface are simply not
+// inputs to room resolution anymore. An unbound session still resolves
+// byte-identically to legacy (core Leg B IS resolveActiveRoom); a bound
+// session is finally honored regardless of flag state. MINDRIAN_MCP_FIRST's
+// remaining consumers after this collapse are daemon lifecycle/registration
+// concerns (bin/mindrian-mcp-server.cjs) and the write-path PERMISSION gate
+// (isWritePathEnabled, lib/mcp/mcp-first-flag.cjs) -- an orthogonal question
+// ("may this call write") this module never answers.
+//
+// Canon Part 7 (reuse before build): this module mints NO new precedence. It
+// is a thin, options-object-only wrapper around the SHIPPED, TESTED core
+// ladder in lib/core/resolve-active-room.cjs (resolveSessionRoom for reads,
+// resolveWriteRoom for writes) -- the SEED-034 four-guessers lesson
+// resolve-active-room.cjs already fixed for the rest of the tree.
+//
+// Canon Part 8/9: LOCAL filesystem reads only (the core ladder's own
+// registry.json / session-binding-file reads), zero network egress, zero
+// graph-chokepoint token -- this module never opens room.db.
+//
+// The census contract: tests/test-248-resolver-census.cjs turns red on any
+// second `function resolveSessionRoomDir` under lib/mcp/, any executable
+// `isMcpFirst(` outside mcp-first-flag.cjs, or any executable
+// `resolveWriteRoom(`/`resolveActiveRoom(` outside this file.
+//
+// No em-dashes. CJS only.
+
+const { resolveSessionRoom, resolveWriteRoom } = require('../core/resolve-active-room.cjs');
+
+// The stable stderr token for the D-04 compat-shim deprecation log (SPEC-1
+// acceptance, Part 11 threat T-198-08), moved here verbatim from
+// tool-router.cjs (its former sole owner). Grepped verbatim by prior
+// acceptance criteria (198-02); never rename without updating every
+// consumer.
+const MCP_FIRST_DEPRECATED_ACTIVE_WRITE = 'MCP_FIRST_DEPRECATED_ACTIVE_WRITE';
+
+/**
+ * resolveMcpSessionRoom(opts) -- the ONE shared MCP room resolver.
+ *
+ * @param {{sessionId?: string, ctx?: {fallbackRoomDir?: string, surface?: string},
+ *   forWrite?: boolean, noFloor?: boolean}} [opts]
+ * @returns {{dir: string|null, slug: string|null, source: string}}
+ *   source is one of 'session.primary', 'room-root' (forWrite only),
+ *   'reg.active', 'boot-fallback', 'cwd', 'none'. Never throws.
+ */
+function resolveMcpSessionRoom(opts) {
+  const o = (opts && typeof opts === 'object') ? opts : {};
+  const sessionId = o.sessionId;
+  const ctx = (o.ctx && typeof o.ctx === 'object') ? o.ctx : {};
+  const forWrite = o.forWrite === true;
+  const noFloor = o.noFloor === true;
+  const home = process.env.MINDRIAN_ROOMS_HOME;
+
+  let hit = null;
+  try {
+    if (forWrite) {
+      // Preserves the `.room-root` cwd walk-up (leg 1) exactly as the
+      // flag-ON write path did today. This leg must NEVER leak into reads --
+      // resolveSessionRoom exists precisely to exclude it (its own header,
+      // lib/core/resolve-active-room.cjs lines 459-464).
+      hit = resolveWriteRoom({ sessionId: sessionId, home: home });
+    } else {
+      hit = resolveSessionRoom({ sessionId: sessionId, home: home });
+    }
+  } catch (_e) {
+    // Never throws: any resolver failure falls to the floor below (mirrors
+    // every retired copy's discipline).
+    hit = null;
+  }
+
+  if (hit && hit.abs_path) {
+    if (forWrite && hit.source === 'reg.active') {
+      // D-04: reg.active is a READ-fallback for a binding-less session, not
+      // write authority anymore. Log, don't silently authorize.
+      try {
+        process.stderr.write(
+          MCP_FIRST_DEPRECATED_ACTIVE_WRITE + ' session=' + String(sessionId) + ' room=' + hit.slug + '\n'
+        );
+      } catch (_logErr) { /* stderr write failure never blocks the write */ }
+    }
+    return { dir: hit.abs_path, slug: hit.slug, source: hit.source };
+  }
+
+  if (noFloor) {
+    return { dir: null, slug: null, source: 'none' };
+  }
+  if (ctx.fallbackRoomDir) {
+    return { dir: ctx.fallbackRoomDir, slug: null, source: 'boot-fallback' };
+  }
+  return { dir: process.cwd(), slug: null, source: 'cwd' };
+}
+
+/**
+ * resolveSessionRoomDir(sessionId, ctx) -- back-compat string wrapper, the
+ * drop-in the nine former copies re-export. Floors exactly as they did
+ * today.
+ *
+ * @param {string|undefined} sessionId
+ * @param {{fallbackRoomDir?: string, surface?: string}} [ctx]
+ * @returns {string}
+ */
+function resolveSessionRoomDir(sessionId, ctx) {
+  return resolveMcpSessionRoom({ sessionId: sessionId, ctx: ctx }).dir;
+}
+
+module.exports = {
+  resolveMcpSessionRoom,
+  resolveSessionRoomDir,
+  MCP_FIRST_DEPRECATED_ACTIVE_WRITE,
+};

package/lib/mcp/sse-event-bus.cjs

@@ -0,0 +1,98 @@
+'use strict';
+// Phase 198-03 (D-01, RESEARCH Open Question 3) -- minimal additive SSE event
+// bus for live statusline segments (the opencode /event pattern). In-process,
+// loopback-only; a durable daemon process holds the subscriber set for its
+// lifetime, mirroring lib/mcp/session-registry.cjs's in-process-only shape.
+//
+// The vocabulary is FROZEN and additive-only (Open Question 3, resolved in
+// this plan): new kinds may be appended in a later phase, never renamed or
+// removed. EVENT_KINDS carries navigator-facing segment data ONLY
+// (status/gate/reconcile signals) -- never room content bound for the Brain
+// (Part 8). status_read's spend/cap segment travels here starting Plan 06.
+//
+// No em-dashes. CJS only. Zero Brain/network token.
+
+const EVENT_KINDS = Object.freeze(['status-segment', 'gate-fired', 'reconcile-raised']);
+
+// In-memory subscriber set. Never persisted; a subscriber that disconnects
+// (its 'close' event fires, when the object exposes `on`) is deregistered.
+const subscribers = new Set();
+
+/**
+ * subscribe(res) -- attach an SSE response stream. `res` is any object
+ * exposing `write(str)`; `on(event, cb)` and `writeHead(status, headers)` are
+ * used when present but are NOT required (a plain mock satisfying only
+ * `write` still registers -- this keeps the module unit-testable without a
+ * real HTTP response). When `writeHead` is available, the standard SSE
+ * headers are sent once on subscribe. When `on` is available, the stream
+ * auto-deregisters on its 'close' event. Never throws.
+ *
+ * @param {{write: function(string): void, on?: function, writeHead?: function}} res
+ */
+function subscribe(res) {
+  if (!res || typeof res.write !== 'function') return;
+  try {
+    if (typeof res.writeHead === 'function') {
+      res.writeHead(200, {
+        'Content-Type': 'text/event-stream',
+        'Cache-Control': 'no-cache',
+        'Connection': 'keep-alive',
+      });
+      // Node/Express buffer headers until the first body write unless
+      // explicitly flushed -- without this a real client (EventSource, curl)
+      // sees nothing at all until the first publish(), indistinguishable from
+      // a hung connection. Flush immediately so "the stream is open" is its
+      // own signal, independent of when the first event arrives.
+      if (typeof res.flushHeaders === 'function') {
+        try { res.flushHeaders(); } catch (_e2) { /* best-effort */ }
+      }
+    }
+  } catch (_e) {
+    // A header-write failure never blocks registration -- the subscriber can
+    // still receive publish() frames on `write`.
+  }
+  subscribers.add(res);
+  if (typeof res.on === 'function') {
+    try {
+      res.on('close', () => { subscribers.delete(res); });
+    } catch (_e) {
+      // A mock `on` that throws still leaves the subscriber registered; a
+      // dead-stream write failure in publish() below reaps it instead.
+    }
+  }
+}
+
+/**
+ * publish(kind, payload) -- broadcast an SSE event to every live subscriber.
+ * Silently no-ops on a kind outside the frozen EVENT_KINDS vocabulary or a
+ * payload that cannot be JSON-serialized (refusal, not a throw, on a hot
+ * server-side publish path). A subscriber whose `write` throws (a dead
+ * stream) is deregistered rather than letting it break the broadcast to
+ * every other subscriber. Never throws into the caller.
+ *
+ * @param {string} kind - one of EVENT_KINDS
+ * @param {object} payload
+ */
+function publish(kind, payload) {
+  try {
+    if (EVENT_KINDS.indexOf(kind) === -1) return;
+    let data;
+    try {
+      data = JSON.stringify(payload === undefined ? null : payload);
+    } catch (_e) {
+      return;
+    }
+    const frame = 'event: ' + kind + '\ndata: ' + data + '\n\n';
+    for (const res of subscribers) {
+      try {
+        res.write(frame);
+      } catch (_e) {
+        subscribers.delete(res);
+      }
+    }
+  } catch (_e) {
+    // Never throw into the publishing call site (mirrors session-registry.close).
+  }
+}
+
+module.exports = { EVENT_KINDS, publish, subscribe };