@mindrian_os/install 1.13.0-beta.11

package/lib/render/render-v2.test.cjs

@@ -0,0 +1,267 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 102-01 -- renderer contract regression fence.
+ *
+ * History:
+ *   - Phase 99-03 shipped a positional 4-arg pass-through stub at this
+ *     module path with the contract `render(zones, mode, operator, tier)
+ *     -> envelope` and tests targeted that envelope.
+ *   - Phase 102-01 (CONTEXT D-10, RESEARCH §2) evolves the renderer to
+ *     a destructured single-arg signature `render({ zones, mode,
+ *     operator, tier, jtbd, tokenBudget, roomDir, provenance }) ->
+ *     { rendered, contract }`. The legacy 4-arg signature lives on at
+ *     lib/render/render.cjs (v1 shim) for unmigrated callers.
+ *   - This file is the new contract regression fence for Phase 102. The
+ *     scope mirrors the 99-03 fence (operator vocab + defaults + error
+ *     paths + envelope stability + mode/tier passthrough) but exercises
+ *     the v2 destructured surface.
+ *
+ * Scenarios (8 IIFE blocks):
+ *   1. 5-operator round-trip via v2 destructured API. JUST_TALK is the
+ *      explicit suppress case; the other 4 round-trip into composed output.
+ *   2. JUST_TALK default when operator omitted (undefined) -- explicit
+ *      operator: undefined is treated as "no operator" (renderer does
+ *      not throw and returns a normal envelope).
+ *   3. JUST_TALK default when operator null -- same as above; null is a
+ *      no-op operator value, NOT 'JUST_TALK' (which is a real value).
+ *   4. v2 must not throw on unknown operator strings -- Phase 102 owns
+ *      operator semantics; only specific operators (JUST_TALK,
+ *      METHODOLOGY) trigger gates. Unknown operators fall through to
+ *      composition so callers can route arbitrary string values without
+ *      a defensive try/catch wrapper.
+ *   5. Envelope shape stable -- exactly 2 keys: rendered + contract. No
+ *      `_stub` provenance leak (Phase 99-03 sentinel removed).
+ *   6. mode passthrough -- 'A' / 'B' / 'tier-0' all pass through; v2
+ *      does NOT validate mode (Phase 102-04 owns Mode B prefix logic).
+ *   7. tier passthrough -- 0 / 1 / 2 / 3 all pass through; v2 does NOT
+ *      validate tier (Phase 90 follow-on owns tier-check semantics).
+ *   8. OPERATORS export is frozen and equals the 5 canonical names.
+ *
+ * Registered in lib/memory/run-feynman-tests.cjs (same registration the
+ * 99-03 fence used; Phase 102 inherits the slot).
+ */
+
+const assert = require('node:assert/strict');
+const path = require('node:path');
+
+const RENDER_MODULE = path.resolve(__dirname, 'render-v2.cjs');
+const { render, OPERATORS } = require(RENDER_MODULE);
+
+let passed = 0;
+let failed = 0;
+
+function ok(name) {
+  passed += 1;
+  process.stdout.write('  ok ' + name + '\n');
+}
+
+function fail(name, err) {
+  failed += 1;
+  process.stdout.write('  FAIL ' + name + '\n');
+  if (err) process.stdout.write('    ' + (err.message || String(err)) + '\n');
+}
+
+const CANONICAL = [
+  'JUST_TALK',
+  'EXPLORE_CAPTURE',
+  'BUILD_ROOM',
+  'METHODOLOGY',
+  'DECISION_GATE',
+];
+
+// ---------------------------------------------------------------------------
+// Scenario 1: 5-operator round-trip via the v2 destructured API.
+// ---------------------------------------------------------------------------
+(function test1_fiveOperatorRoundTrip() {
+  for (const op of CANONICAL) {
+    const label = '5-operator round-trip: ' + op;
+    try {
+      const env = render({
+        zones: { header: '-- h --', body: 'b' },
+        mode: 'A',
+        operator: op,
+        tier: 1,
+      });
+      assert.ok(env && typeof env === 'object', 'envelope is an object');
+      assert.equal(typeof env.rendered, 'string', 'rendered is a string');
+      assert.ok(env.contract && typeof env.contract === 'object', 'contract is an object');
+
+      if (op === 'JUST_TALK') {
+        // Explicit suppress per Phase 102-01 algorithm step 6.
+        assert.equal(env.rendered, '', 'JUST_TALK rendered === ""');
+        assert.equal(env.contract.suppressed, true, 'JUST_TALK contract.suppressed === true');
+        assert.equal(env.contract.reason, 'just-talk', 'JUST_TALK contract.reason === "just-talk"');
+      } else {
+        // All other operators compose normally.
+        assert.ok(env.rendered.indexOf('-- h --') !== -1, op + ' header round-trips');
+        assert.ok(env.rendered.indexOf('b') !== -1, op + ' body round-trips');
+      }
+      ok(label);
+    } catch (e) { fail(label, e); }
+  }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 2: undefined operator does not crash, renders normally.
+// ---------------------------------------------------------------------------
+(function test2_undefinedOperator() {
+  const label = 'undefined operator does not crash';
+  try {
+    const env = render({
+      zones: { header: 'h', body: 'b' },
+      mode: 'A',
+      operator: undefined,
+      tier: 1,
+    });
+    assert.equal(typeof env.rendered, 'string', 'rendered is a string');
+    assert.ok(env.rendered.indexOf('h') !== -1, 'header rendered without an operator');
+    assert.ok(env.rendered.indexOf('b') !== -1, 'body rendered without an operator');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 3: null operator does not crash, renders normally.
+// ---------------------------------------------------------------------------
+(function test3_nullOperator() {
+  const label = 'null operator does not crash';
+  try {
+    const env = render({
+      zones: { header: 'h', body: 'b' },
+      mode: 'A',
+      operator: null,
+      tier: 1,
+    });
+    assert.equal(typeof env.rendered, 'string', 'rendered is a string');
+    assert.ok(env.rendered.indexOf('h') !== -1, 'header rendered with null operator');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 4: unknown operator does not throw -- v2 falls through to
+// composition. Phase 99-03 stub threw; Phase 102 deliberately tolerates
+// unknown operators so upstream callers (hooks, /mos:operator command)
+// can route arbitrary strings without defensive try/catch wrappers.
+// ---------------------------------------------------------------------------
+(function test4_unknownOperatorTolerated() {
+  const label = 'unknown operator does not throw (v2 tolerates)';
+  try {
+    let thrown = null;
+    let env = null;
+    try {
+      env = render({
+        zones: { header: 'h', body: 'b' },
+        mode: 'A',
+        operator: 'NOT_A_REAL_OPERATOR',
+        tier: 1,
+      });
+    } catch (e) { thrown = e; }
+    assert.equal(thrown, null, 'unknown operator must NOT throw');
+    assert.ok(env && typeof env.rendered === 'string', 'still returns a normal envelope');
+    assert.ok(env.rendered.indexOf('h') !== -1, 'composes normally for unknown operator');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 5: Envelope shape stable (exactly 2 keys, no _stub leak).
+// ---------------------------------------------------------------------------
+(function test5_envelopeShapeStable() {
+  const label = 'envelope shape stable: exactly 2 keys (rendered + contract)';
+  try {
+    const env = render({
+      zones: { header: 'h' },
+      mode: 'A',
+      operator: 'BUILD_ROOM',
+      tier: 1,
+    });
+    const keys = Object.keys(env).sort();
+    assert.deepEqual(keys, ['contract', 'rendered'], 'envelope keys are exactly {rendered, contract}');
+    assert.ok(!('_stub' in env), 'no Phase 99-03 _stub provenance leak');
+    assert.ok(!('zones' in env), 'no zones leak (Phase 99-03 pass-through removed)');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 6: mode passthrough.
+// ---------------------------------------------------------------------------
+(function test6_modePassthrough() {
+  const label = 'mode passthrough: A / B / tier-0 all render without throwing';
+  try {
+    for (const mode of ['A', 'B', 'tier-0']) {
+      const env = render({
+        zones: { header: 'h' },
+        mode: mode,
+        operator: 'BUILD_ROOM',
+        tier: 1,
+      });
+      assert.equal(typeof env.rendered, 'string', 'mode ' + mode + ' renders');
+    }
+    // Stub does NOT validate mode -- arbitrary string also passes through.
+    const env = render({
+      zones: { header: 'h' },
+      mode: 'arbitrary-mode',
+      operator: 'BUILD_ROOM',
+      tier: 1,
+    });
+    assert.equal(typeof env.rendered, 'string', 'arbitrary mode renders');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 7: tier passthrough.
+// ---------------------------------------------------------------------------
+(function test7_tierPassthrough() {
+  const label = 'tier passthrough: 0 / 1 / 2 / 3 all render without throwing';
+  try {
+    for (const tier of [0, 1, 2, 3]) {
+      const env = render({
+        zones: { header: 'h' },
+        mode: 'A',
+        operator: 'BUILD_ROOM',
+        tier: tier,
+      });
+      assert.equal(typeof env.rendered, 'string', 'tier ' + tier + ' renders');
+    }
+    // Stub does NOT validate tier -- string tier also passes through.
+    const env = render({
+      zones: { header: 'h' },
+      mode: 'A',
+      operator: 'BUILD_ROOM',
+      tier: 'arbitrary-tier',
+    });
+    assert.equal(typeof env.rendered, 'string', 'arbitrary tier renders');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+// ---------------------------------------------------------------------------
+// Scenario 8: OPERATORS export is frozen and equals the 5 canonical names.
+// ---------------------------------------------------------------------------
+(function test8_operatorsExportFrozen() {
+  const label = 'OPERATORS export is frozen and equals 5 canonical names';
+  try {
+    assert.ok(Array.isArray(OPERATORS), 'OPERATORS is an array');
+    assert.deepEqual(
+      [...OPERATORS].sort(),
+      [...CANONICAL].sort(),
+      'OPERATORS equals 5 canonical names'
+    );
+    assert.ok(Object.isFrozen(OPERATORS), 'OPERATORS is frozen');
+    ok(label);
+  } catch (e) { fail(label, e); }
+})();
+
+process.stdout.write('\n');
+process.stdout.write(
+  'Phase 102-01 renderer contract regression: ' +
+    passed + ' passed, ' + failed + ' failed\n'
+);
+process.exit(failed === 0 ? 0 : 1);

package/lib/render/render.cjs

@@ -0,0 +1,65 @@
+#!/usr/bin/env node
+'use strict';
+
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 102-01 -- v1 renderer shim (legacy 4-arg positional signature).
+ *
+ * Per Phase 102 CONTEXT.md D-10, this module ships in the same wave as
+ * lib/render/render-v2.cjs and exposes the legacy 4-arg signature so
+ * any caller that has not yet migrated to the v2 destructured API keeps
+ * working unchanged. Phase 104 migrates each call site explicitly;
+ * Phase 105 polling flags any unmigrated call site as a compliance gap.
+ *
+ *   render(zones, mode, operator, tier) -> string
+ *
+ * The shim:
+ *   - Forwards to render-v2's destructured API.
+ *   - Fills jtbd=null, tokenBudget={used:0,total:1}, roomDir from env or
+ *     process.cwd(), provenance=null per CONTEXT D-10.
+ *   - Returns just the `rendered` string (legacy callers expect a string,
+ *     not the {rendered, contract} envelope).
+ *
+ * Constraints (Phase 87 invariant):
+ *   - Zero new runtime dependencies.
+ *   - CJS only.
+ *   - The shim has zero rendering logic of its own; all muscle lives in
+ *     render-v2. If render-v2's behavior changes, the shim adapts for
+ *     free.
+ *
+ * Canon parts:
+ *   7 (Reuse Before Build) -- one renderer module, two entry points;
+ *     no parallel formatter implementations.
+ *   8 (Graph Boundary)     -- inherits Canon Part 8 compliance from
+ *     render-v2 by construction (no Brain calls anywhere in the chain).
+ */
+
+const v2 = require('./render-v2.cjs');
+
+/**
+ * Legacy 4-arg renderer entry point.
+ *
+ * @param {object|null|undefined} zones    - 4-zone payload
+ *                                           ({ header, body, signals?, footer? }).
+ * @param {string|null|undefined} mode     - 'A' | 'B' | 'tier-0'.
+ * @param {string|null|undefined} operator - one of OPERATORS or null.
+ * @param {number|string|null|undefined} tier - 0|1|2|3.
+ * @returns {string} Composed 4-zone string ('' when operator suppresses).
+ */
+function render(zones, mode, operator, tier) {
+  const result = v2.render({
+    zones: zones,
+    mode: mode,
+    operator: operator,
+    tier: tier,
+    jtbd: null,
+    tokenBudget: { used: 0, total: 1 },
+    roomDir: process.env.MINDRIAN_ROOM_DIR || process.cwd(),
+    provenance: null,
+  });
+  // v1 callers expect a string, not the {rendered, contract} envelope.
+  return result.rendered;
+}
+
+module.exports = { render, OPERATORS: v2.OPERATORS };

package/lib/state/ROOM.md

@@ -0,0 +1,46 @@
+---
+folder: lib/state
+founding_phase: 100
+purpose: STATE.md parsing utilities -- shared across phases that read project / room STATE.md
+icm_layer: 3
+canon_parts: [3, 7]
+license: BSL-1.1
+---
+
+# lib/state/ -- STATE.md Parsing Utilities
+
+This directory is the home for reusable parsers that read `STATE.md` (project-level
+at `.planning/STATE.md` and per-room at `<roomDir>/STATE.md`).
+
+## Files
+
+| File                  | Purpose                                                    | Founded |
+| --------------------- | ---------------------------------------------------------- | ------- |
+| `state-md-parser.cjs` | Decisions section parser (bullet, numbered, table formats) | 100-02  |
+
+## Why this directory exists
+
+Phase 100's heuristic JTBD classifier needs to read the last 3 decisions from
+STATE.md as Stratum 3 input (per Phase 100 CONTEXT D-04). Phase 100 CONTEXT
+`code_context` calls out the parser as a side-effect deliverable to keep STATE.md
+parsing centralized rather than duplicated across phases (101-106 will all read
+the same source).
+
+Anything that reads `## Decisions` or `### Decisions` from a STATE.md file must
+import from here, not roll its own regex.
+
+## Pattern
+
+- Pure functions; no I/O. The caller reads the file; the parser parses the string.
+- Returns chronological-recent-first arrays.
+- Tolerant of bullet, numbered list, and table formats.
+- Detects optional `[methodology: /mos:X]` and `[jtbd: <id>]` annotations.
+- CJS, zero npm deps, Canon Part 8 LOCAL-only.
+
+## Canon parts
+
+- **Part 3 (Tri-Context Decision Gate):** Decisions are the LOCAL context that
+  the gate reads. STATE.md is the durable record; this parser is the canonical
+  reader.
+- **Part 7 (Reuse Before Build):** centralizing the parser keeps Phases 101-106
+  from reinventing it.

package/lib/state/state-md-parser.cjs

@@ -0,0 +1,215 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 100-02 Task 1 -- STATE.md Decisions section parser
+ * =========================================================
+ * Reusable shared parser for the `## Decisions` (or `### Decisions`)
+ * section that appears in both project-level STATE.md and per-room
+ * STATE.md files. Phase 100 ships this as a side-effect deliverable
+ * (Decision #15 / CONTEXT code_context) -- the JTBD classifier
+ * (lib/hmi/jtbd-classifier.cjs) reads recent decisions as Stratum 3
+ * input per CONTEXT D-04, and Phase 101+ phases consume the same
+ * parser without re-implementing.
+ *
+ * Public API:
+ *   parseDecisions(stateMdText)
+ *     -> Array<{
+ *          date: string|null,           // ISO or human-readable
+ *          verb: string|null,           // one of Canon Part 3 ten or 'Free-Text'
+ *          summary: string,             // bullet body sans annotations
+ *          methodology_hook?: string,   // e.g. '/mos:rs-fetch'
+ *          jtbd?: string,               // e.g. 'find-bottleneck'
+ *          raw: string                  // original line content
+ *        }>
+ *
+ *   recentDecisions(stateMdText, n=3)
+ *     -> Array<...same shape...>
+ *
+ * Behavior:
+ *   - Pure function; no I/O. Caller reads the file.
+ *   - Tolerant of bullet, numbered list, or table formats.
+ *   - Tolerant of trailing/leading whitespace and blank lines.
+ *   - Returns chronological-recent-first (top of section assumed newest;
+ *     STATE.md convention is to prepend recent entries).
+ *   - Detects optional `[methodology: /mos:X]` annotation.
+ *   - Detects optional `[jtbd: <id>]` annotation.
+ *   - Empty / missing section returns [].
+ *
+ * Canon Part 8 compliance:
+ *   - LOCAL-only. No Brain query. No external I/O. Zero npm deps.
+ *
+ * License: BSL 1.1.
+ */
+
+'use strict';
+
+// Canon Part 3 ten verbs (lowercase compare). Plus 'Free-Text' which
+// is verb #10. We accept any leading verb token followed by ':' or '-'
+// or ' '. Unknown verbs are treated as Free-Text.
+const CANON_VERBS = [
+  'run methodology',
+  'reformulate',
+  'spawn sub-agent',
+  'navigate graph',
+  "devil's advocate",
+  'devils advocate',
+  'scenario plan',
+  'synthesize',
+  'bank opportunity',
+  'defer',
+  'free-text',
+];
+
+// Match `[methodology: /mos:X]` or `[methodology:/mos:X]`.
+const METHODOLOGY_RE = /\[methodology:\s*(\/mos:[a-z0-9_-]+|\/gsd:[a-z0-9_-]+)\s*\]/i;
+
+// Match `[jtbd: <id>]` -- id is kebab-case.
+const JTBD_RE = /\[jtbd:\s*([a-z0-9_-]+)\s*\]/i;
+
+// Match leading date in ISO (YYYY-MM-DD) or simple human form (YYYY/MM/DD,
+// "Apr 29 2026", etc.). We extract the most-leading match.
+const ISO_DATE_RE = /^(\d{4}-\d{2}-\d{2})/;
+
+// Bullet/numbered list line detector. Capture the body after the marker.
+//   - foo
+//   * foo
+//   1. foo
+//   2) foo
+const BULLET_RE = /^\s*(?:[-*+]|\d+[.)])\s+(.+)$/;
+
+// Table-row detector. Capture cells separated by `|`.
+const TABLE_ROW_RE = /^\s*\|(.+)\|\s*$/;
+
+function findSection(text, headingRegex) {
+  // Returns the body lines BETWEEN headingRegex and the next heading of equal
+  // or greater scope (## or ###).
+  const lines = text.split(/\r?\n/);
+  let inSection = false;
+  const out = [];
+  for (let i = 0; i < lines.length; i++) {
+    const line = lines[i];
+    if (!inSection) {
+      if (headingRegex.test(line)) {
+        inSection = true;
+      }
+      continue;
+    }
+    // Stop at next heading of any level (### Decisions usually sits inside ##
+    // Accumulated Context, so we stop at ## OR ### OR #).
+    if (/^#{1,6}\s+\S/.test(line)) {
+      break;
+    }
+    out.push(line);
+  }
+  return out;
+}
+
+function extractDate(body) {
+  const m = body.match(ISO_DATE_RE);
+  if (m) return m[1];
+  // Fallback: try "[Phase 71]" style as date-substitute. Treat as null date.
+  return null;
+}
+
+function extractVerb(body) {
+  const lower = body.toLowerCase().trim();
+  for (const verb of CANON_VERBS) {
+    // Verb appears at start, possibly after a date prefix that we already saw.
+    // We accept verb followed by space, colon, or end-of-segment.
+    if (lower.startsWith(verb + ' ') || lower.startsWith(verb + ':') || lower === verb) {
+      return verb === "devils advocate" ? "Devil's Advocate" : capitalizeVerb(verb);
+    }
+  }
+  return null;
+}
+
+function capitalizeVerb(v) {
+  return v.split(' ')
+    .map(w => w === "advocate" || w === "methodology" || w === "graph" || w === "plan" || w === "opportunity" || w === "agent" || w === "sub-agent"
+      ? w.charAt(0).toUpperCase() + w.slice(1)
+      : w.charAt(0).toUpperCase() + w.slice(1))
+    .join(' ');
+}
+
+function parseLine(rawBody) {
+  // rawBody is the line body AFTER bullet/number marker stripping.
+  const raw = rawBody.trim();
+  if (!raw) return null;
+
+  // Date
+  const date = extractDate(raw);
+
+  // Annotations
+  const mhMatch = raw.match(METHODOLOGY_RE);
+  const jtbdMatch = raw.match(JTBD_RE);
+  const methodology_hook = mhMatch ? mhMatch[1] : undefined;
+  const jtbd = jtbdMatch ? jtbdMatch[1] : undefined;
+
+  // Strip annotations from summary
+  let summary = raw
+    .replace(METHODOLOGY_RE, '')
+    .replace(JTBD_RE, '')
+    .replace(/\s{2,}/g, ' ')
+    .trim();
+
+  // Strip leading date from summary
+  if (date) summary = summary.replace(ISO_DATE_RE, '').trim();
+
+  // Strip leading "[Phase XX]:" prefix common in plugin STATE.md
+  summary = summary.replace(/^\[[^\]]+\]:\s*/, '').trim();
+
+  // Verb extraction (after stripping date + phase prefix)
+  const verb = extractVerb(summary) || 'Free-Text';
+
+  const out = { date, verb, summary, raw };
+  if (methodology_hook) out.methodology_hook = methodology_hook;
+  if (jtbd) out.jtbd = jtbd;
+  return out;
+}
+
+function parseDecisions(stateMdText) {
+  if (!stateMdText || typeof stateMdText !== 'string') return [];
+
+  // Tolerant headers: "## Decisions" or "### Decisions" (case-sensitive on
+  // word but allowing trailing whitespace).
+  const headingRe = /^#{2,3}\s+Decisions\s*$/;
+  const body = findSection(stateMdText, headingRe);
+
+  const out = [];
+  for (const line of body) {
+    // Bullet / numbered
+    const bulletMatch = line.match(BULLET_RE);
+    if (bulletMatch) {
+      const parsed = parseLine(bulletMatch[1]);
+      if (parsed) out.push(parsed);
+      continue;
+    }
+    // Table row -- skip header rows (contain only --- and |)
+    const tableMatch = line.match(TABLE_ROW_RE);
+    if (tableMatch) {
+      const inner = tableMatch[1];
+      // Skip header divider row like | --- | --- |
+      if (/^\s*[-:|\s]+\s*$/.test(inner)) continue;
+      // Take the LAST non-empty cell as summary, FIRST cell as potential date
+      const cells = inner.split('|').map(c => c.trim()).filter(c => c !== '');
+      if (cells.length === 0) continue;
+      const joined = cells.join(' ');
+      const parsed = parseLine(joined);
+      if (parsed) out.push(parsed);
+      continue;
+    }
+    // Plain prose lines: skip (not a decision row).
+  }
+  return out;
+}
+
+function recentDecisions(stateMdText, n) {
+  const all = parseDecisions(stateMdText);
+  const limit = (typeof n === 'number' && n > 0) ? n : 3;
+  return all.slice(0, limit);
+}
+
+module.exports = {
+  parseDecisions,
+  recentDecisions,
+};

package/lib/statusline/ROOM.md

@@ -0,0 +1,38 @@
+# lib/statusline/
+
+ICM Layer 0 identity for the statusline visibility subsystem (per CLAUDE.md decision #15).
+
+## Purpose
+
+Shared modules that support the MindrianOS statusline visibility surface across
+CLI / Desktop / Cowork. Phase 106 (statusline-visibility-context-window-broadcast)
+introduced this directory; the substrate is consumed by:
+
+- scripts/context-monitor (CLI rich statusline renderer; Phase 106 D-02)
+- scripts/statusline-fallback-echo.cjs (Desktop / Cowork prose echo; Phase 106 D-04)
+- scripts/doctor.cjs class G (visibility detector; Phase 106 D-03)
+
+## Modules
+
+- banner-suppression.cjs - shouldSuppress(touchFileContent, currentVersion, now).
+  24h timing + version-bump invalidation contract for the one-time visibility
+  banner. Extracted from the Plan 106-03 inline contract. Pure function, no I/O.
+- surface-detect.cjs - detectStatuslineSurface() returns 'CLI' / 'DESKTOP' /
+  'COWORK'. Distinct from lib/mcp/surface-detect.cjs (which picks MCP transport
+  at server startup; lowercase strings + transport field).
+
+## Canon
+
+- Part 3: statusline + fallback echo are LOCAL-context surfaces for the Decision Gate.
+- Part 8: zero remote egress; reads are local files only. Telemetry stays local.
+
+## Tests
+
+- tests/test-statusline-banner-suppression.cjs - 5 contract tests (Plan 106-03
+  fenced inline; Plan 106-04 swapped to require() the shared module).
+- tests/test-surface-detect.cjs - 6 tests for the literal-string contract
+  (CLI / DESKTOP / COWORK + never-null) and the explicit env override.
+- tests/test-fallback-echo-compose.cjs - 7 tests for echo composition + per
+  surface routing + banner suppression + graceful state-file absence.
+- tests/test-fallback-echo-30day.cjs - 5 tests for the 30-day default-flip
+  + explicit MINDRIAN_STATUSLINE_FALLBACK_ECHO override behavior.

package/lib/statusline/banner-suppression.cjs

@@ -0,0 +1,50 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 106 Plan 04 -- statusline banner-suppression module.
+ *
+ * Extracted from the inline contract fenced at
+ * tests/test-statusline-banner-suppression.cjs:49-60 by Plan 106-03
+ * (see 106-03-SUMMARY.md "Plan 106-04 Contract Handoff" section).
+ *
+ * Touch-file path: ~/.mindrian/banner-state/statusline-visibility-warned.json
+ * Shape:
+ *   {
+ *     "status": "ok" | "warn" | "error",
+ *     "last_check": "<ISO>",        // populated when status='ok'
+ *     "last_warned": "<ISO>",       // populated when status='warn' or 'error'
+ *     "installed_version": "<plugin.json version>"
+ *   }
+ *
+ * shouldSuppress() returns true ONLY when:
+ *   - touch-file content is non-null, AND
+ *   - installed_version === current plugin version (version-bump invalidates), AND
+ *   - status in {'warn', 'error'}, AND
+ *   - last_warned is a parseable ISO timestamp, AND
+ *   - last_warned is within 24h of `now`.
+ *
+ * Used by:
+ *   - scripts/statusline-fallback-echo.cjs (D-04 fallback echo, 106-04)
+ *   - tests/test-statusline-banner-suppression.cjs (5-test contract fence, 106-03)
+ *
+ * Canon Part 8: pure function, no I/O, no network, no side effects.
+ * Pure CJS, node built-ins only, zero npm deps (Phase 87 invariant).
+ */
+
+'use strict';
+
+const TWENTY_FOUR_HOURS_MS = 24 * 3600 * 1000;
+
+function shouldSuppress(touchFileContent, currentVersion, now) {
+  if (now === undefined) now = Date.now();
+  if (!touchFileContent) return false;
+  if (touchFileContent.installed_version !== currentVersion) return false;
+  if (touchFileContent.status !== 'warn' && touchFileContent.status !== 'error') return false;
+  if (!touchFileContent.last_warned) return false;
+  const warnedAt = Date.parse(touchFileContent.last_warned);
+  if (Number.isNaN(warnedAt)) return false;
+  const ageMs = now - warnedAt;
+  return ageMs < TWENTY_FOUR_HOURS_MS;
+}
+
+module.exports = { shouldSuppress, TWENTY_FOUR_HOURS_MS };