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

package/lib/core/brain-response-sanitize.cjs

@@ -0,0 +1,396 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 117-04 -- Brain response sanitizer (SEED-003 A3 implementation).
+ *
+ * Per SEED-003 A3 spec: PostToolUse hook on Brain MCP tool calls uses
+ * hookSpecificOutput.updatedToolOutput to scan + redact accidental
+ * user-data echo before the response reaches the model. This is the
+ * structural enforcement of Canon Part 8 the canon has been describing
+ * as "PR review" (check-brain-boundary.cjs PR gate, listed as "pending"
+ * in CANON-PHASE-MAP.md Part 8 row).
+ *
+ * Phase 90 shipped 5 Canon Part 8 tripwires (schema-leak heuristic scan,
+ * deriveSection chokepoint, brain-md-invariants body-text scan,
+ * sanitizeDetailScalar in cross-room aggregator, cross-scenario sweep).
+ * This module adds the 6th tripwire: response-side scan.
+ *
+ * v1 ships PII pattern redaction ONLY. Conservative non-allowlist
+ * redaction (8+ consecutive non-allowlist tokens) stays DISABLED until
+ * Phase 121 telemetry calibrates false-positive rate. Risk T4 mitigated
+ * by starting permissive; tighten after empirical observation.
+ *
+ * Pure CJS, node built-ins only.
+ */
+'use strict';
+
+const crypto = require('node:crypto');
+
+/**
+ * BRAIN_TOOL_MATCHER -- the single exported tool-name authority for the Brain
+ * MCP door. Phase 239 (BRAIN-01): the two prior copies of this pattern (the
+ * hooks/hooks.json matchers and this module's own isBrainTool prefix test)
+ * drifted independently and both went dead the moment the Brain server
+ * shipped inside a plugin instead of as a bare project-scoped server.
+ *
+ * Per the official Claude Code plugins reference, a plugin-bundled MCP
+ * server's tool names take the shape
+ *   mcp__plugin_<plugin-name>_<server-name>__<tool>
+ * and "a matcher written against the bare server key never fires." This
+ * repo's plugin name is "mos" (.claude-plugin/plugin.json) and its Brain
+ * server key is "mindrian-brain" (.mcp.json), so the live plugin-scoped name
+ * is mcp__plugin_mos_mindrian-brain__brain_*. The dead literal this replaces
+ * was mcp__brain_* -- keep that string ONLY as the superseded example above,
+ * never as a live pattern anywhere in this repo.
+ *
+ * Two scopes, not one (239-RESEARCH.md Pitfall 6): this repo's root
+ * .mcp.json also doubles as a project-scoped .mcp.json when the repo itself
+ * is opened in Claude Code, which yields mcp__mindrian-brain__* instead (no
+ * plugin_<name>_ prefix). Desktop and Cowork resolve plugin scope; CLI in
+ * this dev checkout may resolve project scope. This is a Tri-Polar concern,
+ * not cosmetic, so the pattern below covers both with one optional
+ * non-capturing group.
+ *
+ * hooks/hooks.json's two matchers (PreToolUse, PostToolUse) MUST equal this
+ * exact string byte for byte; tests/test-brain-response-sanitize.cjs asserts
+ * that parity so drift becomes a red test instead of a silent no-op.
+ * See also scripts/check-brain-tool-liveness.cjs (Phase 239 plan 03), the
+ * gate that proves this pattern actually matches the live registered names
+ * via a real MCP tools/list handshake, not by inspection alone.
+ */
+const BRAIN_TOOL_MATCHER = 'mcp__(?:plugin_[a-z0-9_-]+_)?(?:mindrian-brain|pws-brain-mcp)__.*';
+
+/**
+ * _BRAIN_TOOL_RE -- anchored RegExp compiled once at module scope, derived
+ * from BRAIN_TOOL_MATCHER. hooks/hooks.json intentionally carries the
+ * UNANCHORED pattern, because that is exactly how Claude Code evaluates a
+ * hook matcher (official hooks docs: matchers are "JavaScript regular
+ * expression, unanchored", tested with RegExp.prototype.test, which
+ * succeeds on a match anywhere in the value). isBrainTool anchors with
+ * ^...$ because the tighter posture closes threat T3: an unanchored
+ * in-code re-check would let a foreign MCP server whose name merely
+ * CONTAINS "mindrian-brain" (e.g. a plugin-prefix trick) slip through the
+ * defense-in-depth backstop even if the host matcher were somehow bypassed.
+ * The plugin-prefix character class is deliberately bounded to
+ * [a-z0-9_-]+, NOT .*, for the same T3 reason: an over-broad pattern such
+ * as mcp__.*brain.* would let a third-party server named e.g. "evil-brain"
+ * be treated as the trusted Brain.
+ */
+const _BRAIN_TOOL_RE = new RegExp('^' + BRAIN_TOOL_MATCHER + '$');
+
+/**
+ * BRAIN_SHAPED_TOOL_MATCHER -- the scrutiny-scope authority, alongside the
+ * byte-unchanged BRAIN_TOOL_MATCHER trust-scope authority above. Quick task
+ * 260906-gr1: closes the Part 8 egress-guard bypass for an MCP connector
+ * registered under a non-canonical key (the live `theo` case, recorded as an
+ * accepted residual risk in docs/339-NOTE-theo-desktop-connector-key.md
+ * Section 2 and superseded in Section 8).
+ *
+ * (a) TWO PREDICATES, TWO DIFFERENT QUESTIONS. `isBrainTool` (above) answers
+ * "is this THE trusted Brain connector?" (trust) and is byte-unchanged by
+ * this addition. `isBrainShapedTool` (below) answers "might this be carrying
+ * methodology traffic to a Brain backend, so Part 8 must inspect it?"
+ * (scrutiny). Brain-shaped grants INSPECTION, never TRUST: the guard can
+ * only block or gate a Brain-shaped call, never grant an allow the payload
+ * had not already earned. So threat T3 (anti-impersonation) is unaffected --
+ * `mcp__evil-brain__brain_ask` becomes Brain-shaped (inspected) while
+ * `isBrainTool` on the same name stays false (still not trusted).
+ *
+ * (b) A RULE, NOT A ROSTER. Alternation 2 below is a connector-agnostic
+ * suffix rule (`brain_<verb>`), not a maintained list of known operation
+ * names. The docblock above this one already records the Phase 239 drift
+ * incident: two copies of a tool-name pattern (hooks.json and this module's
+ * own prefix test) went independently stale the moment the Brain server
+ * shipped inside a plugin. A roster is exactly that same shape of liability
+ * -- one more list that can silently drift out of sync with the live tool
+ * surface. A structural rule has no roster to drift.
+ *
+ * (c) THE DISJOINTNESS PROOF, BY NAME. This plugin ships its own LOCAL
+ * `mindrian-os` MCP server (`.mcp.json`), whose tools carry user room
+ * content BY DESIGN -- that is the local side of Canon Part 8, not the
+ * Brain side. `room_bind`, `graph_write`, `gate_render`, `gate_answer`,
+ * `chain_run` and `room_search` are LOCAL `mindrian-os` tool names and are
+ * therefore deliberately OUTSIDE this scope: none of them starts with
+ * `brain_`. `tests/test-260906-gr1-brain-shaped-tool-gate.cjs` is the
+ * standing guard that keeps this true -- it enumerates the local tool
+ * surface from disk and asserts zero collisions, so a future local tool
+ * named `brain_*` becomes a red test rather than a silently bricked local
+ * write path.
+ *
+ * (d) KNOWN BOUND. The connector-key character class in alternation 2
+ * (`[a-z0-9_-]+`) is lowercase-only, matching the existing plugin-prefix
+ * class in BRAIN_TOOL_MATCHER above. An uppercase connector key falls
+ * outside this scope.
+ */
+const BRAIN_SHAPED_TOOL_MATCHER = 'mcp__(?:(?:plugin_[a-z0-9_-]+_)?(?:mindrian-brain|pws-brain-mcp)__.*|[a-z0-9_-]+__brain_[a-z0-9_]+)';
+
+/**
+ * _BRAIN_SHAPED_TOOL_RE -- anchored RegExp compiled once at module scope,
+ * mirroring the exact anchoring asymmetry of _BRAIN_TOOL_RE above:
+ * hooks/hooks.json carries the UNANCHORED string (Claude Code evaluates
+ * matchers unanchored), and this in-code re-check anchors with ^...$
+ * because the tighter posture is the backstop.
+ */
+const _BRAIN_SHAPED_TOOL_RE = new RegExp('^' + BRAIN_SHAPED_TOOL_MATCHER + '$');
+
+/**
+ * PII_PATTERNS -- regex catalogue per RESEARCH Section 4.6.
+ * Each pattern carries a name for telemetry attribution (Phase 121).
+ *
+ * Patterns (6 total):
+ *   ssn       -- US SSN format XXX-XX-XXXX
+ *   email     -- RFC 5322 simplified
+ *   phone     -- US phone XXX-XXX-XXXX or XXX.XXX.XXXX
+ *   money     -- $X, $X.XX, $XM/K/B suffix
+ *   iso_date  -- YYYY-MM-DD
+ *   abs_path  -- POSIX absolute paths under /home/X or /Users/X
+ */
+const PII_PATTERNS = Object.freeze([
+  { name: 'ssn',      regex: /\b\d{3}-\d{2}-\d{4}\b/g },
+  { name: 'email',    regex: /\b[\w.+-]+@[\w-]+\.[\w.-]+\b/g },
+  { name: 'phone',    regex: /\b\d{3}[-.]\d{3}[-.]\d{4}\b/g },
+  { name: 'money',    regex: /\$\d+(?:\.\d+)?[MmKkBb]?\b/g },
+  { name: 'iso_date', regex: /\b\d{4}-\d{2}-\d{2}\b/g },
+  { name: 'abs_path', regex: /\/(?:home|Users)\/[\w-]+\/[\w/.-]+/g },
+]);
+
+/**
+ * ALLOWLIST -- framework names + section names + methodology verbs + enum scalars.
+ * v1 list seeds from RESEARCH Section 4.6 + references/methodology/index.md.
+ * Tightened over time as Phase 121 telemetry calibrates.
+ *
+ * v1 redaction is pattern-only (PII_PATTERNS). The ALLOWLIST is exported
+ * for downstream consumers (e.g. Phase 121 telemetry attribution) and is
+ * NOT consulted by sanitize() in v1. When Phase 121 calibrates a non-
+ * allowlist redaction mode, ALLOWLIST membership becomes the carve-out.
+ */
+const ALLOWLIST = Object.freeze(new Set([
+  // Framework names (from references/methodology/index.md):
+  'JTBD', 'MECE', 'Six Thinking Hats', 'Beautiful Questions', 'BONO', 'PAEI',
+  'SWOT', 'Porter Five Forces', 'Reverse Salients', 'Hooked Model',
+  'Cynefin', 'OODA', 'BMC', 'STP',
+  // Section names:
+  'problem-definition', 'market-analysis', 'solution-design', 'business-model',
+  'competitive-analysis', 'team-execution', 'legal-ip', 'financial-model',
+  'team', 'meetings',
+  // Methodology verbs:
+  'decomposition', 'hypothesis', 'cascade', 'whitespace', 'analogy',
+  'contradiction', 'convergence', 'reverse salient', 'cross-domain',
+  // Enum scalars:
+  'Tier 0', 'Tier 1', 'Tier 2', 'Mode A', 'Mode B', 'Mode C',
+]));
+
+/**
+ * isBrainTool(toolName) -- matcher for PostToolUse hook scope.
+ * Phase 239 (BRAIN-01): anchored re-check derived from BRAIN_TOOL_MATCHER,
+ * covering both the plugin-scoped live name
+ * (mcp__plugin_mos_mindrian-brain__brain_*) and the project-scoped dev
+ * checkout name (mcp__mindrian-brain__brain_*). The old mcp__brain_* prefix
+ * test is the superseded dead literal this replaces; it never matched a
+ * live registered name once the Brain server shipped inside the "mos"
+ * plugin. See the BRAIN_TOOL_MATCHER docblock above for the full reasoning
+ * (scope coverage, anchoring asymmetry, threat T3).
+ *
+ * @param {string} toolName    tool name string from PostToolUse stdin
+ * @returns {boolean}          true iff the tool is a Brain MCP tool
+ */
+function isBrainTool(toolName) {
+  return typeof toolName === 'string' && _BRAIN_TOOL_RE.test(toolName);
+}
+
+/**
+ * isBrainShapedTool(toolName) -- matcher for the widened Part 8 scrutiny
+ * scope. Quick task 260906-gr1. See the BRAIN_SHAPED_TOOL_MATCHER docblock
+ * above for the full reasoning (the two-predicates distinction, why this is
+ * a rule and not a roster, the local-surface disjointness proof, and the
+ * lowercase-only bound).
+ *
+ * @param {string} toolName    tool name string from PreToolUse/PostToolUse stdin
+ * @returns {boolean}          true iff the tool is Brain-shaped (in scope for
+ *                             Part 8 inspection, which is NOT the same as
+ *                             being the trusted Brain connector)
+ */
+function isBrainShapedTool(toolName) {
+  return typeof toolName === 'string' && _BRAIN_SHAPED_TOOL_RE.test(toolName);
+}
+
+/**
+ * sanitize(text) -- apply PII pattern redaction with deterministic sha256
+ * placeholder. ALLOWLIST entries pass through unchanged in v1 because the
+ * v1 redaction engine is pattern-only (regex matches). The ALLOWLIST is
+ * for the Phase 121 calibration path.
+ *
+ * v1 ships PII patterns only. Generic-token redaction (8+ consecutive
+ * non-allowlist tokens) is DISABLED until Phase 121 telemetry calibrates.
+ *
+ * Determinism: same input always produces the same redacted output.
+ * The placeholder format is `[REDACTED:<8-hex>]` where the hex is the
+ * first 8 chars of sha256(matched-substring).
+ *
+ * @param {string} text        input text (any type; coerced to string)
+ * @returns {string}           sanitized text
+ */
+function sanitize(text) {
+  const input = String(text == null ? '' : text);
+  if (input.length === 0) return input;
+  let result = input;
+  for (const pat of PII_PATTERNS) {
+    result = result.replace(pat.regex, function(match) {
+      const hash = crypto.createHash('sha256').update(match).digest('hex').slice(0, 8);
+      return '[REDACTED:' + hash + ']';
+    });
+  }
+  return result;
+}
+
+/**
+ * sanitizeDetailed(text) -- Phase 117-05 extension. Returns BOTH sanitized
+ * text AND a per-pattern redaction count map so the PostToolUse hook can
+ * emit one auto_explore_sanitizer_hit telemetry event per matched pattern.
+ *
+ * Backward-compatible: sanitize() still returns the sanitized string only.
+ * This variant is for telemetry callers (brain-response-sanitize-hook.cjs).
+ *
+ * @param {string} text   input text
+ * @returns {{text: string, redactions: object}}  redactions keyed by pattern name
+ */
+function sanitizeDetailed(text) {
+  const input = String(text == null ? '' : text);
+  const redactions = { ssn: 0, email: 0, phone: 0, money: 0, iso_date: 0, abs_path: 0 };
+  if (input.length === 0) return { text: input, redactions: redactions };
+  let result = input;
+  for (const pat of PII_PATTERNS) {
+    result = result.replace(pat.regex, function(match) {
+      redactions[pat.name] = (redactions[pat.name] || 0) + 1;
+      const hash = crypto.createHash('sha256').update(match).digest('hex').slice(0, 8);
+      return '[REDACTED:' + hash + ']';
+    });
+  }
+  return { text: result, redactions: redactions };
+}
+
+/**
+ * extractResponseText(toolResponse) -- the SINGLE shared text-reading seam for
+ * a PostToolUse tool_response. Quick task 260807-h5s (defect A1).
+ *
+ * WHY THIS EXISTS. The original code in BOTH buildEnvelope and
+ * scripts/brain-response-sanitize-hook.cjs read `tool_response.text` and
+ * nothing else. A real MCP tool result does NOT carry a bare `.text`: it
+ * carries an array of content blocks under `.content`. So every live Brain
+ * call produced `undefined` there, the sanitizer ran over an empty string, and
+ * the ENTIRE Brain response was silently blanked before it reached the model.
+ * Both call sites route through THIS function so the identical defect cannot
+ * re-diverge across the two files (Canon Part 7, reuse before build).
+ *
+ * Resolution order, first match wins:
+ *   1. a string                  -> return it.
+ *   2. .text is a string         -> return it (the legacy fixture shape, still
+ *                                   honoured so every pre-existing fixture and
+ *                                   any transport that really does send a bare
+ *                                   .text keeps working).
+ *   3. .content is an array      -> join the text values of every element whose
+ *                                   type is the literal 'text', with newlines.
+ *   4. the value IS an array     -> apply rule 3 to it directly.
+ *   5. anything else             -> ''.
+ *
+ * Every branch is guarded so a malformed or hostile shape returns '' rather
+ * than throwing: the hook's always-exit-0 contract is load-bearing (threat
+ * T-h5s-05, a throw here would stall the agent loop).
+ *
+ * @param {*} toolResponse   the raw tool_response value off PostToolUse stdin
+ * @returns {string}         recovered text, or '' when nothing is recoverable
+ */
+function extractResponseText(toolResponse) {
+  try {
+    if (typeof toolResponse === 'string') return toolResponse;
+    if (toolResponse === null || typeof toolResponse !== 'object') return '';
+
+    if (!Array.isArray(toolResponse) && typeof toolResponse.text === 'string') {
+      return toolResponse.text;
+    }
+
+    const blocks = Array.isArray(toolResponse)
+      ? toolResponse
+      : (Array.isArray(toolResponse.content) ? toolResponse.content : null);
+    if (!blocks) return '';
+
+    const parts = [];
+    for (let i = 0; i < blocks.length; i++) {
+      const b = blocks[i];
+      if (b === null || typeof b !== 'object') continue;
+      if (b.type === 'text' && typeof b.text === 'string') parts.push(b.text);
+    }
+    return parts.join('\n');
+  } catch (_e) {
+    return '';
+  }
+}
+
+/**
+ * buildEnvelope(toolName, originalToolResponse) -- produce the PostToolUse hook
+ * envelope. Returns the JSON object to write to stdout.
+ *
+ * If isBrainShapedTool returns false, returns a passthrough envelope (no
+ * updatedToolOutput). Other tools' responses are not modified. Quick task
+ * 260906-gr1: retargeted from isBrainTool to isBrainShapedTool so this
+ * function has ONE gate rather than two that can diverge from the live
+ * hook (scripts/brain-response-sanitize-hook.cjs), which builds its own
+ * envelope inline and is not on this code path today -- precisely why a
+ * divergence here would have gone unnoticed.
+ *
+ * ENVELOPE SHAPE (corrected by quick task 260807-h5s, defect A2/A3). The shape
+ * documented here before was WRONG on both the input side and the output side,
+ * and both halves shipped:
+ *   {
+ *     continue: true,
+ *     hookSpecificOutput: {
+ *       hookEventName: 'PostToolUse',
+ *       updatedToolOutput: [ { type: 'text', text: '<sanitized response>' } ]
+ *     }
+ *   }
+ * updatedToolOutput MUST be an ARRAY of content blocks, never a bare object.
+ * The client-side length reducer walks this value with a reduce over content
+ * blocks, so a bare object has no reduce method and the user sees the raw
+ * "e.reduce is not a function" error instead of their Brain answer. The key
+ * name stays `updatedToolOutput`: the Claude Code binary describes
+ * `updatedMCPToolOutput` as MCP-only while telling callers to prefer
+ * `updatedToolOutput`.
+ *
+ * The input side is read through extractResponseText, which understands MCP
+ * content blocks; see that function's docblock for why the old `.text`-only
+ * read blanked every live Brain response.
+ *
+ * @param {string} toolName               tool name from PostToolUse stdin
+ * @param {*}      originalToolResponse   tool_response value (content blocks,
+ *                                        a bare .text, a string, or an array)
+ * @returns {object}                      envelope ready for JSON.stringify -> stdout
+ */
+function buildEnvelope(toolName, originalToolResponse) {
+  if (!isBrainShapedTool(toolName)) {
+    return { continue: true };
+  }
+  const text = extractResponseText(originalToolResponse);
+  const sanitized = sanitize(text);
+  return {
+    continue: true,
+    hookSpecificOutput: {
+      hookEventName: 'PostToolUse',
+      updatedToolOutput: [
+        { type: 'text', text: sanitized },
+      ],
+    },
+  };
+}
+
+module.exports = {
+  sanitize,
+  sanitizeDetailed,
+  extractResponseText,
+  buildEnvelope,
+  isBrainTool,
+  isBrainShapedTool,
+  BRAIN_TOOL_MATCHER,
+  BRAIN_SHAPED_TOOL_MATCHER,
+  PII_PATTERNS,
+  ALLOWLIST,
+};

package/lib/core/breakthrough/canary.cjs

@@ -0,0 +1,134 @@
+'use strict';
+/*
+ * Phase 120-02 Wave 2 Task 1 -- D-19 per-detector dismissal-rate canary. Per
+ * CONTEXT.md D-19 verbatim:
+ *
+ *   Track per-detector dismissal rate over a 100-fire rolling window. If the
+ *   rate crosses 30%, auto-throttle that detector to soft-fire-only until
+ *   manually reviewed. This is the user-telling-us-with-the-dismiss-button
+ *   signal -- catches drift before it shows up in any other metric.
+ *
+ * STATIC thresholds for v1.13.0 (ML-tuned weights deferred to v1.14.0 per
+ * CONTEXT.md OUT OF SCOPE). The auto-throttle recovery surface (the user-facing
+ * "this detector needs review" affordance) is deferred to Phase 121
+ * housekeeping per CONTEXT.md Deferred Ideas. v1.13.0 only emits the
+ * `breakthrough_throttled` event for /mos:doctor to find.
+ *
+ * Canon Part 8 + Part 9: ALL reads via navigation.cjs::findRecentChanges
+ *   chokepoint (Canon Part 9 D-06); pure LOCAL; no Brain coupling.
+ *
+ * Em-dash HARD RULE (CLAUDE.md feedback_no_emdashes): use "--" not U+2014.
+ *
+ * Pure CJS, node built-ins only, zero deps.
+ *
+ * Coordination note: scoring.cjs (Plan 120-01 Task 3) also exports the D-19
+ * canary constants + isThrottledKind. canary.cjs is the PRIMARY ownership for
+ * v1.13.0+ -- scoring.cjs's copy is kept byte-stable for backwards compat with
+ * Plan 120-01 acceptance; downstream code should import from canary.cjs going
+ * forward. The two surfaces share the same threshold values verbatim.
+ */
+
+const navigation = require('../navigation.cjs');
+
+// CONTEXT.md D-19 verbatim lock. Object.freeze is not strictly required for
+// primitive numbers (they are immutable by value) but the named exports +
+// scaffold-harness shell grep + unit test (Test 15) form the three-layer
+// invariant defense.
+const D19_DISMISSAL_THRESHOLD = 0.30;
+const D19_FIRE_WINDOW = 100;
+const D19_MIN_SAMPLE = 10;
+
+// 90-day search window for canary lookups. Older events stay in log but the
+// canary considers them stale (mirrors the scoring.cjs PRIOR_WINDOW_DAYS=90).
+const CANARY_WINDOW_MS = 90 * 24 * 3600 * 1000;
+const CANARY_QUERY_LIMIT = 500;
+
+// computeDismissalRate -- D-19 canary computation for a single detector kind.
+//
+// Returns { rate, sample_size, throttled }:
+//   - rate: dismissed_in_window / sample_size (or 0 if sample_size = 0).
+//   - sample_size: number of recent surfaces for kind, capped at D19_FIRE_WINDOW.
+//   - throttled: true IFF sample_size >= D19_MIN_SAMPLE AND rate > D19_DISMISSAL_THRESHOLD.
+//
+// Implementation:
+//   1. Read recent breakthrough_surfaced events for the kind (most-recent first).
+//   2. Take the top D19_FIRE_WINDOW (the rolling window).
+//   3. Read recent breakthrough_dismissed events; match against the in-window
+//      surfaced ids (a dismiss for an out-of-window fire is noise).
+//   4. Apply the D19_MIN_SAMPLE floor before throttling kicks in (1-of-2 = 50%
+//      would otherwise trip the 30% canary on essentially noise).
+//
+// Graceful degradation: missing/invalid kind or db -> returns the zero-state
+// object. Chokepoint throw -> same. Fail-open: never lock out a detector on
+// infra hiccup.
+function computeDismissalRate(kind, db) {
+  try {
+    if (!kind || !db) return { rate: 0, sample_size: 0, throttled: false };
+    const since = Date.now() - CANARY_WINDOW_MS;
+    const surfaced = navigation.findRecentChanges(db, since, {
+      eventType: 'breakthrough_surfaced',
+      limit: CANARY_QUERY_LIMIT,
+    }) || [];
+    const dismissed = navigation.findRecentChanges(db, since, {
+      eventType: 'breakthrough_dismissed',
+      limit: CANARY_QUERY_LIMIT,
+    }) || [];
+    const kindSurfaced = surfaced
+      .filter(function (e) { return e && e.properties && e.properties.kind === kind; })
+      .slice(0, D19_FIRE_WINDOW);
+    const sample = kindSurfaced.length;
+    const fireIds = new Set(
+      kindSurfaced
+        .map(function (e) { return e.properties && e.properties.breakthrough_id; })
+        .filter(function (id) { return typeof id === 'string' && id.length > 0; })
+    );
+    const dismissedInWindow = dismissed.filter(function (e) {
+      return e && e.properties && e.properties.kind === kind &&
+             typeof e.properties.breakthrough_id === 'string' &&
+             fireIds.has(e.properties.breakthrough_id);
+    }).length;
+    const rate = sample > 0 ? dismissedInWindow / sample : 0;
+    const throttled = sample >= D19_MIN_SAMPLE && rate > D19_DISMISSAL_THRESHOLD;
+    return { rate: rate, sample_size: sample, throttled: throttled };
+  } catch (_e) {
+    return { rate: 0, sample_size: 0, throttled: false };
+  }
+}
+
+// isThrottled -- thin convenience wrapper. Use computeDismissalRate when the
+// caller also needs the rate + sample_size scalars (e.g., for breakthrough_throttled
+// event payload). Per-kind isolation is enforced by the kind filter inside
+// computeDismissalRate -- one drifting detector cannot throttle siblings.
+function isThrottled(kind, db) {
+  return computeDismissalRate(kind, db).throttled;
+}
+
+// emitThrottleEvent -- writes a breakthrough_throttled memory_event via the
+// navigation.cjs chokepoint. Payload carries the canary scalars + a wall-clock
+// timestamp + a source_path so /mos:doctor can find throttled detectors at
+// session-start.
+//
+// The auto-throttle recovery surface (the user-facing affordance for unthrottling)
+// is DEFERRED to Phase 121 housekeeping. v1.13.0 just persists the signal.
+function emitThrottleEvent(kind, db, result) {
+  const safeResult = (result && typeof result === 'object') ? result : { rate: 0, sample_size: 0 };
+  const payload = {
+    kind: kind,
+    rate: typeof safeResult.rate === 'number' ? safeResult.rate : 0,
+    sample_size: typeof safeResult.sample_size === 'number' ? safeResult.sample_size : 0,
+    threshold: D19_DISMISSAL_THRESHOLD,
+    throttled_at: Date.now(),
+    source_path: 'system:breakthrough-canary',
+    created_by: 'system',
+  };
+  return navigation.logMemoryEvent(db, 'breakthrough_throttled', payload);
+}
+
+module.exports = {
+  computeDismissalRate: computeDismissalRate,
+  isThrottled: isThrottled,
+  emitThrottleEvent: emitThrottleEvent,
+  D19_DISMISSAL_THRESHOLD: D19_DISMISSAL_THRESHOLD,
+  D19_FIRE_WINDOW: D19_FIRE_WINDOW,
+  D19_MIN_SAMPLE: D19_MIN_SAMPLE,
+};

package/lib/core/breakthrough/canary.test.cjs

@@ -0,0 +1,136 @@
+'use strict';
+
+/*
+ * Phase 120-02 Wave 2 Task 1 -- D-19 per-detector dismissal-rate canary unit tests.
+ *
+ * Tests 15-23 cover:
+ *   - D19 constants verbatim (D19_DISMISSAL_THRESHOLD=0.30 / D19_FIRE_WINDOW=100 /
+ *     D19_MIN_SAMPLE=10)
+ *   - computeDismissalRate empty / below-sample / happy-path
+ *   - isThrottled per-kind isolation
+ *   - emitThrottleEvent writes breakthrough_throttled via navigation.logMemoryEvent
+ *   - Canon Part 8 source-grep + em-dash HARD RULE (Tests 22 + 23)
+ */
+
+const test = require('node:test');
+const { strict: assert } = require('node:assert');
+const fs = require('node:fs');
+const os = require('node:os');
+const path = require('node:path');
+
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+const canary = require(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'canary.cjs'));
+const navigation = require(path.join(REPO_ROOT, 'lib', 'core', 'navigation.cjs'));
+const { openRoomDb } = require(path.join(REPO_ROOT, 'lib', 'core', 'room-db.cjs'));
+
+function makeTmpDb(prefix) {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), prefix));
+  const db = openRoomDb(dir);
+  return { dir, db };
+}
+
+function seedSurfacedDismissedPair(db, kind, breakthroughId, dismissed) {
+  const surfacedR = navigation.logMemoryEvent(db, 'breakthrough_surfaced', {
+    breakthrough_id: breakthroughId,
+    kind: kind,
+    source_path: 'system:test',
+    created_by: 'system',
+  });
+  assert.equal(surfacedR.ok, true);
+  if (dismissed) {
+    const dismR = navigation.logMemoryEvent(db, 'breakthrough_dismissed', {
+      breakthrough_id: breakthroughId,
+      kind: kind,
+      source_path: 'system:test',
+      created_by: 'system',
+    });
+    assert.equal(dismR.ok, true);
+  }
+}
+
+test('120-02 Task 1 Test 15: D-19 constants verbatim', () => {
+  assert.equal(canary.D19_DISMISSAL_THRESHOLD, 0.30);
+  assert.equal(canary.D19_FIRE_WINDOW, 100);
+  assert.equal(canary.D19_MIN_SAMPLE, 10);
+});
+
+test('120-02 Task 1 Test 16: computeDismissalRate on empty db -> rate=0 sample=0 throttled=false', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t16-');
+  const r = canary.computeDismissalRate('convergence', db);
+  assert.equal(r.rate, 0);
+  assert.equal(r.sample_size, 0);
+  assert.equal(r.throttled, false);
+});
+
+test('120-02 Task 1 Test 17: computeDismissalRate below D19_MIN_SAMPLE -> throttled stays false', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t17-');
+  // 5 surfaced + 2 dismissed; 40% rate; but sample < D19_MIN_SAMPLE=10 -> not throttled.
+  for (let i = 0; i < 3; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:' + i, false);
+  for (let i = 3; i < 5; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:' + i, true);
+  const r = canary.computeDismissalRate('convergence', db);
+  assert.equal(r.sample_size, 5);
+  // 2 out of 5 = 0.4 rate, but throttled gates on sample size.
+  assert.ok(r.rate > 0);
+  assert.equal(r.throttled, false);
+});
+
+test('120-02 Task 1 Test 18: computeDismissalRate with sample >= floor + rate above threshold -> throttled=true', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t18-');
+  // 12 surfaced + 5 dismissed (5/12 ~= 0.42 > 0.30); sample 12 > 10 floor.
+  for (let i = 0; i < 7; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:s' + i, false);
+  for (let i = 0; i < 5; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:d' + i, true);
+  const r = canary.computeDismissalRate('convergence', db);
+  assert.equal(r.sample_size, 12);
+  assert.ok(r.rate > 0.30, 'rate should exceed 0.30 threshold');
+  assert.equal(r.throttled, true);
+});
+
+test('120-02 Task 1 Test 19: isThrottled returns true when computeDismissalRate.throttled is true', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t19-');
+  for (let i = 0; i < 7; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:s' + i, false);
+  for (let i = 0; i < 5; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:d' + i, true);
+  assert.equal(canary.isThrottled('convergence', db), true);
+});
+
+test('120-02 Task 1 Test 20: isThrottled isolated per-kind -- throttled convergence does NOT throttle cross_domain_analogy', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t20-');
+  // Throttle convergence.
+  for (let i = 0; i < 7; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:cs' + i, false);
+  for (let i = 0; i < 5; i++) seedSurfacedDismissedPair(db, 'convergence', 'bk:cd' + i, true);
+  // cross_domain_analogy has no events.
+  assert.equal(canary.isThrottled('convergence', db), true);
+  assert.equal(canary.isThrottled('cross_domain_analogy', db), false);
+});
+
+test('120-02 Task 1 Test 21: emitThrottleEvent writes breakthrough_throttled memory_event', () => {
+  const { dir, db } = makeTmpDb('p120-02-t1-t21-');
+  const rate = { rate: 0.35, sample_size: 100, throttled: true };
+  const r = canary.emitThrottleEvent('convergence', db, rate);
+  assert.equal(r.ok, true);
+  assert.match(r.eventId, /^memory_event:breakthrough_throttled:/);
+  // Verify the event landed.
+  const found = navigation.findRecentChanges(db, 0, { eventType: 'breakthrough_throttled', limit: 10 });
+  assert.equal(found.length, 1);
+  assert.equal(found[0].properties.kind, 'convergence');
+  assert.equal(found[0].properties.rate, 0.35);
+  assert.equal(found[0].properties.threshold, 0.30);
+  assert.equal(found[0].properties.sample_size, 100);
+  assert.ok(typeof found[0].properties.throttled_at === 'number');
+});
+
+test('120-02 Task 1 Test 22: Canon Part 8 source-grep -- zero Brain coupling in canary.cjs', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'canary.cjs'), 'utf8');
+  assert.equal(/require\s*\(\s*['"][^'"]*brain-client[^'"]*['"]\s*\)/.test(src), false,
+    'canary.cjs must not require brain-client');
+  assert.equal(/fetch\s*\(\s*['"][^'"]*brain\.mindrian/.test(src), false,
+    'canary.cjs must not fetch brain.mindrian.*');
+});
+
+test('120-02 Task 1 Test 23: em-dash HARD RULE -- zero U+2014 in canary.cjs', () => {
+  const src = fs.readFileSync(path.join(REPO_ROOT, 'lib', 'core', 'breakthrough', 'canary.cjs'), 'utf8');
+  let count = 0;
+  for (const ch of src) {
+    if (ch.charCodeAt(0) === 0x2014) count++;
+  }
+  assert.equal(count, 0, 'canary.cjs must contain zero U+2014 em-dash characters');
+});