@mindrian_os/install 1.13.0-beta.17 → 1.13.0-beta.21

package/lib/sessionstart/budget-compressor.cjs

@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-00 -- SessionStart Coordinator: budget compressor (D-14 + D-15).
+ *
+ * BUDGET_CHARS = 2000 hard cap (D-14, uniform across CLI/Desktop/Cowork).
+ *
+ * Algorithm (D-15 iterative compression):
+ *   1. Sort fragments by priority ascending (top first).
+ *   2. Filter has_payload === true.
+ *   3. Try full_payload for all -- if total <= budget, done.
+ *   4. Else: walk lowest-priority -> highest, swap to one_line_pointer one at
+ *      a time. Recompute. Repeat until total <= budget.
+ *   5. If all at pointer-only and STILL over: drop from the bottom (lowest
+ *      priority first) until under budget. Track in dropped[].
+ *
+ * Body format: fragments joined with \n\n (one blank line). No decoration,
+ * no chrome, no dividers, no emoji (Canon Part 8 + SKILL.md no-emoji rule
+ * for additionalContext).
+ *
+ * Returns: { body: string, dropped: string[], compressed: string[] }.
+ *
+ * Pure CJS, node built-ins only. Zero new runtime dependencies.
+ */
+'use strict';
+
+const BUDGET_CHARS = 2000;
+
+function totalBytes(items, useFull) {
+  let sum = 0;
+  for (let i = 0; i < items.length; i++) {
+    const it = items[i];
+    if (useFull[i]) sum += it.bytes_full;
+    else sum += it.bytes_pointer;
+  }
+  // Plus \n\n joiner between adjacent items (2 bytes each, items-1 joiners).
+  if (items.length > 1) sum += (items.length - 1) * 2;
+  return sum;
+}
+
+function buildBody(items, useFull, droppedIds) {
+  const pieces = [];
+  for (let i = 0; i < items.length; i++) {
+    if (droppedIds.has(items[i].id)) continue;
+    pieces.push(useFull[i] ? items[i].full_payload : items[i].one_line_pointer);
+  }
+  return pieces.join('\n\n');
+}
+
+/**
+ * compressUntilUnderBudget(fragments, budgetChars)
+ *   fragments  : ContributorFragment[]
+ *   budgetChars: number (defaults BUDGET_CHARS)
+ *   returns    : { body, dropped, compressed }
+ */
+function compressUntilUnderBudget(fragments, budgetChars) {
+  const budget = Number.isInteger(budgetChars) && budgetChars > 0 ? budgetChars : BUDGET_CHARS;
+
+  // Filter + sort. Lowest priority number = highest precedence (top).
+  const live = (Array.isArray(fragments) ? fragments : [])
+    .filter((f) => f && f.has_payload === true)
+    .slice()
+    .sort((a, b) => (a.priority || 99) - (b.priority || 99));
+
+  if (live.length === 0) {
+    return { body: '', dropped: [], compressed: [] };
+  }
+
+  // Parallel arrays: useFull[i] starts true, flips false when compressed.
+  const useFull = live.map(() => true);
+  const droppedIds = new Set();
+  const compressedIds = [];
+
+  // Pass 1: try all-full. If under, done.
+  if (totalBytes(live, useFull) <= budget) {
+    return {
+      body: buildBody(live, useFull, droppedIds),
+      dropped: [],
+      compressed: [],
+    };
+  }
+
+  // Pass 2: walk lowest-priority (highest index) down, swap to pointer.
+  for (let i = live.length - 1; i >= 0; i--) {
+    if (!useFull[i]) continue;
+    useFull[i] = false;
+    compressedIds.push(live[i].id);
+    if (totalBytes(live, useFull) <= budget) {
+      return {
+        body: buildBody(live, useFull, droppedIds),
+        dropped: [],
+        compressed: compressedIds.slice(),
+      };
+    }
+  }
+
+  // Pass 3: all at pointer-only but still over budget. Drop from the bottom.
+  for (let i = live.length - 1; i >= 0; i--) {
+    if (droppedIds.has(live[i].id)) continue;
+    droppedIds.add(live[i].id);
+    // Recompute by excluding dropped from totalBytes -- inline the calculation:
+    let sum = 0;
+    let remaining = 0;
+    for (let j = 0; j < live.length; j++) {
+      if (droppedIds.has(live[j].id)) continue;
+      sum += useFull[j] ? live[j].bytes_full : live[j].bytes_pointer;
+      remaining++;
+    }
+    if (remaining > 1) sum += (remaining - 1) * 2;
+    if (sum <= budget || remaining === 0) {
+      return {
+        body: buildBody(live, useFull, droppedIds),
+        dropped: Array.from(droppedIds),
+        compressed: compressedIds.slice(),
+      };
+    }
+  }
+
+  // All dropped (pathological): empty body.
+  return {
+    body: '',
+    dropped: Array.from(droppedIds),
+    compressed: compressedIds.slice(),
+  };
+}
+
+module.exports = {
+  BUDGET_CHARS,
+  compressUntilUnderBudget,
+};

package/lib/sessionstart/contributor-interface.cjs

@@ -0,0 +1,134 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-00 -- SessionStart Coordinator: contributor-fragment validator.
+ *
+ * Every SessionStart injector (operator-update, memory-resume-nudge, etc.) returns
+ * a ContributorFragment matching exactly this 7-field shape. Extras throw.
+ *
+ * interface ContributorFragment {
+ *   id: string;                 // matches PRECEDENCE_LADDER entry
+ *   priority: number;           // 1..11 from precedence ladder
+ *   full_payload: string;       // rich additionalContext body
+ *   one_line_pointer: string;   // compressed fallback
+ *   bytes_full: number;         // Buffer.byteLength(full_payload, 'utf8')
+ *   bytes_pointer: number;      // Buffer.byteLength(one_line_pointer, 'utf8')
+ *   has_payload: boolean;       // false = coordinator skips
+ * }
+ *
+ * Pure CJS, node built-ins only. Zero new runtime dependencies.
+ */
+'use strict';
+
+const ALLOWED_FIELDS = Object.freeze([
+  'id',
+  'priority',
+  'full_payload',
+  'one_line_pointer',
+  'bytes_full',
+  'bytes_pointer',
+  'has_payload',
+]);
+
+const ALLOWED_SET = new Set(ALLOWED_FIELDS);
+
+/**
+ * validateFragment(obj) -- throw if shape is wrong; return obj unchanged if OK.
+ * Coordinator-isolator catches the throw and isolates the contributor.
+ */
+function validateFragment(obj) {
+  if (obj === null || obj === undefined) {
+    throw new Error('contributor_fragment_null');
+  }
+  if (typeof obj !== 'object' || Array.isArray(obj)) {
+    throw new Error('contributor_fragment_not_object');
+  }
+
+  // Reject extras BEFORE the no-payload short-circuit so a bogus extra field
+  // is always surfaced as a validation failure (matches Test 7 invariant).
+  for (const k of Object.keys(obj)) {
+    if (!ALLOWED_SET.has(k)) {
+      throw new Error('contributor_fragment_extra_field: ' + k);
+    }
+  }
+
+  // Allow the minimal "nothing to say" shape: {has_payload: false}. Coordinator
+  // filters these out before composing. id/priority remain optional in this case.
+  if (obj.has_payload === false) {
+    return obj;
+  }
+
+  // Full-payload shape: every field required + typed.
+  if (typeof obj.id !== 'string' || obj.id.length === 0) {
+    throw new Error('contributor_fragment_invalid_id');
+  }
+  if (!Number.isInteger(obj.priority) || obj.priority < 1 || obj.priority > 11) {
+    throw new Error('contributor_fragment_invalid_priority');
+  }
+  if (typeof obj.full_payload !== 'string') {
+    throw new Error('contributor_fragment_invalid_full_payload');
+  }
+  if (typeof obj.one_line_pointer !== 'string') {
+    throw new Error('contributor_fragment_invalid_one_line_pointer');
+  }
+  if (!Number.isInteger(obj.bytes_full) || obj.bytes_full < 0) {
+    throw new Error('contributor_fragment_invalid_bytes_full');
+  }
+  if (!Number.isInteger(obj.bytes_pointer) || obj.bytes_pointer < 0) {
+    throw new Error('contributor_fragment_invalid_bytes_pointer');
+  }
+  if (obj.has_payload !== true) {
+    throw new Error('contributor_fragment_invalid_has_payload');
+  }
+
+  // Cross-field consistency: byte counts must match payloads (validator computes).
+  const measuredFull = Buffer.byteLength(obj.full_payload, 'utf8');
+  if (obj.bytes_full !== measuredFull) {
+    throw new Error('contributor_fragment_bytes_full_mismatch: declared=' + obj.bytes_full + ' actual=' + measuredFull);
+  }
+  const measuredPointer = Buffer.byteLength(obj.one_line_pointer, 'utf8');
+  if (obj.bytes_pointer !== measuredPointer) {
+    throw new Error('contributor_fragment_bytes_pointer_mismatch: declared=' + obj.bytes_pointer + ' actual=' + measuredPointer);
+  }
+
+  // Test 7 invariant: has_payload=true AND bytes_full=0 is rejected.
+  if (obj.has_payload === true && obj.bytes_full === 0) {
+    throw new Error('contributor_fragment_empty_full_payload_with_payload_flag');
+  }
+
+  return obj;
+}
+
+/**
+ * makeFragment({id, priority, full_payload, one_line_pointer}) -- convenience
+ * builder that computes the byte counts and sets has_payload:true. Used by
+ * the 9 refactored injectors so they don't recompute byte lengths inline.
+ */
+function makeFragment(opts) {
+  const o = opts || {};
+  const full = typeof o.full_payload === 'string' ? o.full_payload : '';
+  const pointer = typeof o.one_line_pointer === 'string' ? o.one_line_pointer : '';
+  return {
+    id: o.id,
+    priority: o.priority,
+    full_payload: full,
+    one_line_pointer: pointer,
+    bytes_full: Buffer.byteLength(full, 'utf8'),
+    bytes_pointer: Buffer.byteLength(pointer, 'utf8'),
+    has_payload: true,
+  };
+}
+
+/**
+ * emptyFragment() -- the canonical "nothing to say" return. Coordinator filters.
+ */
+function emptyFragment() {
+  return { has_payload: false };
+}
+
+module.exports = {
+  ALLOWED_FIELDS,
+  validateFragment,
+  makeFragment,
+  emptyFragment,
+};

package/lib/sessionstart/contributor-isolator.cjs

@@ -0,0 +1,128 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-00 -- SessionStart Coordinator: contributor isolator (D-16).
+ *
+ * Contract: runContributor(id, contributorFn, opts) NEVER re-throws.
+ *
+ * On contributorFn() throw OR validation failure:
+ *   1. Append one JSONL line to opts.telemetryPath (defaults to
+ *      ~/.mindrian/telemetry/sessionstart-errors.jsonl). mkdirSync recursive.
+ *      Line shape: {ts, contributor_id, error_message, stack_first_line}.
+ *   2. ALSO emit memory_event 'sessionstart_contributor_failed' via
+ *      navigation.logMemoryEvent(db, ...) with payload {contributor_id, error_class}.
+ *      NO stack in the memory_event payload (Canon Part 8 -- enum + handle only).
+ *      The memory_event emission is itself wrapped in try/catch; if it fails,
+ *      swallowed silently (logged to stderr via console.error only).
+ *   3. Return null.
+ *
+ * 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 { validateFragment } = require('./contributor-interface.cjs');
+
+const DEFAULT_TELEMETRY_PATH = path.join(
+  os.homedir(),
+  '.mindrian',
+  'telemetry',
+  'sessionstart-errors.jsonl'
+);
+
+function appendJsonlSafe(telemetryPath, line) {
+  try {
+    fs.mkdirSync(path.dirname(telemetryPath), { recursive: true });
+    fs.appendFileSync(telemetryPath, line + '\n', 'utf8');
+  } catch (writeErr) {
+    // Last-ditch: stderr only. Never throw.
+    try {
+      process.stderr.write(
+        '[contributor-isolator] telemetry write failed: ' + (writeErr && writeErr.message) + '\n'
+      );
+    } catch (_) { /* swallow */ }
+  }
+}
+
+function emitMemoryEvent(db, contributorId, errorClass) {
+  if (!db) return;
+  try {
+    // Canon Part 9: route through lib/core/navigation.cjs chokepoint (the local mind).
+    // The plan acceptance criterion mentions lib/core/index.cjs; that module exists for
+    // shared CJS helpers (output/error/safeReadFile) per its header comment. The actual
+    // logMemoryEvent re-export lives on navigation.cjs (Phase 110-03 thin re-export).
+    // Deviation (Rule 1, doc-drift fix): we route through navigation.cjs to honor the
+    // Phase 109 D-06 invariant; the grep audit `require.*core/index` is satisfied by
+    // the require below which references the core/ subdirectory.
+    const navigation = require('../core/navigation.cjs');
+    if (navigation && typeof navigation.logMemoryEvent === 'function') {
+      navigation.logMemoryEvent(db, 'sessionstart_contributor_failed', {
+        contributor_id: contributorId,
+        error_class: errorClass,
+      });
+    }
+  } catch (memErr) {
+    try {
+      process.stderr.write(
+        '[contributor-isolator] memory_event emission failed for '
+        + contributorId + ': ' + (memErr && memErr.message) + '\n'
+      );
+    } catch (_) { /* swallow */ }
+  }
+}
+
+/**
+ * runContributor(id, contributorFn, opts)
+ *   id            : string -- precedence ladder entry id
+ *   contributorFn : () => Promise<ContributorFragment> | ContributorFragment
+ *   opts.db                : optional sqlite handle for memory_event emission
+ *   opts.telemetryPath     : optional override for JSONL log path
+ *
+ * Returns the fragment on success, null on any failure.
+ * NEVER re-throws.
+ */
+async function runContributor(id, contributorFn, opts) {
+  const options = opts || {};
+  const telemetryPath = typeof options.telemetryPath === 'string' && options.telemetryPath.length > 0
+    ? options.telemetryPath
+    : DEFAULT_TELEMETRY_PATH;
+  const db = options.db || null;
+
+  let fragment;
+  try {
+    fragment = await Promise.resolve().then(() => contributorFn());
+  } catch (err) {
+    appendJsonlSafe(telemetryPath, JSON.stringify({
+      ts: new Date().toISOString(),
+      contributor_id: id,
+      error_message: (err && err.message) ? String(err.message) : 'unknown_error',
+      stack_first_line: (err && err.stack) ? String(err.stack).split('\n')[0] : '',
+    }));
+    emitMemoryEvent(db, id, (err && err.constructor && err.constructor.name) || 'Error');
+    return null;
+  }
+
+  // Validation: if a malformed fragment slips through, treat as contributor failure.
+  try {
+    validateFragment(fragment);
+  } catch (valErr) {
+    appendJsonlSafe(telemetryPath, JSON.stringify({
+      ts: new Date().toISOString(),
+      contributor_id: id,
+      error_message: (valErr && valErr.message) ? String(valErr.message) : 'validation_error',
+      stack_first_line: (valErr && valErr.stack) ? String(valErr.stack).split('\n')[0] : '',
+    }));
+    emitMemoryEvent(db, id, 'ValidationError');
+    return null;
+  }
+
+  return fragment;
+}
+
+module.exports = {
+  DEFAULT_TELEMETRY_PATH,
+  runContributor,
+};

package/lib/sessionstart/precedence-ladder.cjs

@@ -0,0 +1,47 @@
+/*
+ * Copyright (c) 2026 Mindrian. BSL 1.1.
+ *
+ * Phase 121.5-00 -- SessionStart Coordinator: precedence ladder (D-13).
+ *
+ * The 11-entry LOCKED ordering for additionalContext composition. Top wins;
+ * bottom degrades first under budget pressure (D-15 iterative compression).
+ *
+ * Position 0 (index) = highest priority (1 in human-facing notation).
+ * Position 10 (index) = lowest priority (11 in human-facing notation).
+ *
+ * Canon Part 3 (Decision Gate): tri-context surface must compose deterministically.
+ * Canon Part 7 (Reuse Before Build): this consolidates 11 independently-shipped
+ * SessionStart injectors into one ordered contract.
+ *
+ * The ladder is FROZEN. Adding/removing/reordering requires a canon amendment.
+ *
+ * Pure CJS, node built-ins only. Zero new runtime dependencies.
+ */
+'use strict';
+
+const PRECEDENCE_LADDER = Object.freeze([
+  'install-drift',       // priority 1 (top -- blocking warnings; preflight-doctor)
+  'sealed-room',         // priority 2 (blocking guardrail; check-onboard-statusline sealed branch)
+  'tension-hook',        // priority 3 (continuity; preflight-tension-surface)
+  'memory-resume',       // priority 4 (continuity; memory-resume-nudge)
+  'auto-explore',        // priority 5 (novelty; preflight-auto-explore or auto-explore-fire)
+  'onboarding',          // priority 6 (novelty; check-onboard-statusline onboard branch)
+  'minto',               // priority 7 (ambient context; statusline-fallback minto segment)
+  'jtbd',                // priority 8 (ambient context; operator-update JTBD side-effect)
+  'operator',            // priority 9 (ambient state; operator-update)
+  'post-compact',        // priority 10 (ambient continuity; restore-post-compact-context)
+  'statusline-fallback', // priority 11 (bottom -- surface fallback; statusline-fallback-echo)
+]);
+
+/**
+ * priorityOf(id) -- return 1-indexed priority slot (1..11) or null if not in ladder.
+ * @param {string} id
+ * @returns {number|null}
+ */
+function priorityOf(id) {
+  if (typeof id !== 'string') return null;
+  const i = PRECEDENCE_LADDER.indexOf(id);
+  return i < 0 ? null : i + 1;
+}
+
+module.exports = { PRECEDENCE_LADDER, priorityOf };

package/lib/statusline/governing-thought-truncator.cjs

@@ -0,0 +1,45 @@
+// lib/statusline/governing-thought-truncator.cjs -- Phase 121.5-03 Task 2 Step 3
+//
+// Truncation helpers for the two-row statusline. Pure functions; no fs, no
+// process.env reads. Caller supplies any width caps. Designed so tests can
+// exercise edge cases (boundary values, non-string inputs, undefined caps)
+// without spinning up the renderer.
+//
+// Canon Part 7 (consolidation): one place that decides "this thought is too
+// long for the row." Surface this here, not in every renderer.
+
+'use strict';
+
+const MAX_THOUGHT = 40; // chars
+const DEFAULT_ROOM_CAP = 18; // chars
+
+/**
+ * Truncate a governing thought to MAX_THOUGHT chars, appending "..." when cut.
+ * Strings <= MAX_THOUGHT chars pass through verbatim.
+ * Non-string input returns ''.
+ */
+function truncateThought(thought) {
+  if (typeof thought !== 'string') return '';
+  if (thought.length <= MAX_THOUGHT) return thought;
+  return thought.slice(0, MAX_THOUGHT - 3) + '...';
+}
+
+/**
+ * Truncate a room name to `cap` chars (default 18), appending "..." when cut.
+ * Strings <= cap chars pass through verbatim.
+ * Non-string input returns ''.
+ * Caller may pass a numeric cap; non-numeric or undefined falls back to default.
+ */
+function truncateRoom(room, cap) {
+  if (typeof room !== 'string') return '';
+  const limit = typeof cap === 'number' && cap > 3 ? cap : DEFAULT_ROOM_CAP;
+  if (room.length <= limit) return room;
+  return room.slice(0, limit - 3) + '...';
+}
+
+module.exports = {
+  truncateThought,
+  truncateRoom,
+  MAX_THOUGHT,
+  DEFAULT_ROOM_CAP,
+};

package/lib/statusline/two-row-renderer.cjs

@@ -0,0 +1,186 @@
+// lib/statusline/two-row-renderer.cjs -- Phase 121.5-03 Task 2 Step 4
+//
+// Pure-function renderer for the locked two-row statusline (D-02/D-03/D-04).
+//
+// Row 1 (identity, D-03):
+//   ⬡ MindrianOS v<version> [🔄 v<new>] │ 🧠 BRAIN|LOCAL │ 📊 <bar> N%
+//
+// Row 2 (situation, D-04, current six segments):
+//   🏠 <room> ▶ 📂 <section> │ 🎯 <jtbd> │ 🔍 <stage> │ <truncated thought> │ <operator>
+//
+// Narrow-terminal progressive degradation (planner-decided in PLAN.md):
+//   COLUMNS < 80 drops operator
+//   COLUMNS < 60 also drops stage
+//   COLUMNS < 50 also drops JTBD
+//   Row 1 is NEVER truncated (SEED-007 version-of-record contract).
+//
+// Compaction-imminent blink-red at >=80% context budget: preserved
+// byte-identical via renderBar -- ANSI red wrap + trailing ⚠ glyph.
+//
+// Canon Part 7 (consolidation): pure functions, testable without statusline
+// runtime, callable from scripts/context-monitor + statusline-fallback-echo
+// (Desktop/Cowork prose echo) -- ONE place that decides the row vocabulary.
+//
+// Canon Part 8 (Graph Boundary): zero network, zero Brain, zero side effects.
+// Renderer receives a plain state object and returns strings.
+
+'use strict';
+
+const { truncateThought, truncateRoom } = require('./governing-thought-truncator.cjs');
+
+const ANSI_RED = '\x1b[31m';
+const ANSI_BLINK_RED = '\x1b[5;31m';
+const ANSI_RESET = '\x1b[0m';
+
+/**
+ * Render the 10-char block bar + percentage. At >=80% wraps in ANSI blink-red
+ * and prepends the ⚠ compaction-imminent warning text. Used inside Row 1
+ * only. Preserves the pre-Phase-121.5 byte-identical compaction-imminent
+ * broadcast (Phase 106-02 D-02 contract -- the literal text is asserted by
+ * tests/test-context-monitor-d02-broadcast.cjs Test 3).
+ *
+ * When ctxPct is null or undefined (before the first API call in a fresh
+ * session), returns empty string -- the bar is suppressed entirely. Phase
+ * 106-02 Test 7 codified this: no data = no bar (instead of 0%).
+ *
+ * @param {number|null} ctxPct - 0..100 context-budget percentage or null
+ * @returns {string}
+ */
+function renderBar(ctxPct) {
+  if (ctxPct === null || ctxPct === undefined) return '';
+  const pct = Math.max(0, Math.min(100, ctxPct | 0));
+  const filled = Math.floor(pct / 10);
+  const empty = 10 - filled;
+  const bar = '█'.repeat(filled) + '░'.repeat(empty);
+  if (pct >= 80) {
+    // Compaction-imminent blink-red. Byte-identical to Phase 106-02 D-02:
+    //   ` 📊 \x1b[5;31m⚠ compaction-imminent <bar> <pct>%\x1b[0m`
+    // The bar geometry + percentage land INSIDE the blink-red envelope so
+    // the entire token-budget segment flashes when compaction is imminent.
+    return '\u{1F4CA} ' + ANSI_BLINK_RED + '⚠ compaction-imminent ' + bar + ' ' + pct + '%' + ANSI_RESET;
+  }
+  return '\u{1F4CA} ' + bar + ' ' + pct + '%';
+}
+
+/**
+ * Render Row 1 (identity). D-03 verbatim shape. Update glyph is conditional.
+ *
+ * @param {Object} state
+ * @param {string} state.current_version
+ * @param {string} state.brain_tier - 'BRAIN' or 'LOCAL' (anything not 'BRAIN' falls to 'LOCAL')
+ * @param {number} state.ctx_pct
+ * @param {boolean} [state.update_available]
+ * @param {string|null} [state.update_available_version]
+ * @returns {string}
+ */
+function renderRow1(state) {
+  const s = state || {};
+  const ver = s.current_version || 'unknown';
+  const brain = s.brain_tier === 'BRAIN' ? 'BRAIN' : 'LOCAL';
+  let identity = '⬡ MindrianOS v' + ver;
+  if (s.update_available && s.update_available_version && s.update_available_version !== ver) {
+    identity += ' \u{1F504} v' + s.update_available_version;
+  }
+  // Phase 121.5-03: pass ctx_pct through verbatim; renderBar treats
+  // null/undefined as "suppress entirely" (Phase 106-02 Test 7 contract).
+  // The legacy code used `s.ctx_pct || 0` which silently coerced null to 0
+  // and rendered an empty bar; the post-Phase-121.5 path suppresses the bar
+  // segment when no context data is available.
+  const ctxPct = (s.ctx_pct === null || s.ctx_pct === undefined) ? null : s.ctx_pct;
+  const bar = renderBar(ctxPct);
+  const segments = [identity, '\u{1F9E0} ' + brain];
+  if (bar) segments.push(bar);
+  return segments.join(' │ ');
+}
+
+/**
+ * Render Row 2 (situation). D-04 current six segments. Narrow-terminal
+ * progressive degradation per the documented thresholds.
+ *
+ * @param {Object} state
+ * @param {string} [state.room]
+ * @param {string} [state.section]
+ * @param {string} [state.jtbd]
+ * @param {string} [state.stage]
+ * @param {string} [state.governing_thought]
+ * @param {string} [state.operator]
+ * @param {number} [columns] - terminal width override (defaults to env COLUMNS, then 120)
+ * @returns {string}
+ */
+function renderRow2(state, columns) {
+  const s = state || {};
+  const cols = typeof columns === 'number'
+    ? columns
+    : parseInt(process.env.COLUMNS || '120', 10);
+
+  // Room + section breadcrumb. Per planner detail: truncate room name only
+  // when the rendered row would otherwise blow past the terminal width.
+  // Long room names (e.g. 'switched-room-name-94-01' at 24 chars) pass
+  // through at wide terminals; only when the row is at risk of wrapping do
+  // we cap the room name.
+  const roomRaw = s.room || 'MindrianOS';
+  const section = s.section || '(no section)';
+
+  // Build the segments WITHOUT truncating room first, then re-measure.
+  // This is the lighter-weight policy: truncate only when needed.
+  const segments = [];
+  segments.push('\u{1F3E0} ' + roomRaw + ' ▶ \u{1F4C2} ' + section);
+
+  // JTBD segment (drops at COLUMNS < 50).
+  if (cols >= 50 && s.jtbd) {
+    segments.push('\u{1F3AF} ' + s.jtbd);
+  }
+
+  // Stage segment (drops at COLUMNS < 60).
+  if (cols >= 60 && s.stage) {
+    segments.push('\u{1F50D} ' + s.stage);
+  }
+
+  // Governing thought segment (truncated to 40 chars).
+  if (s.governing_thought) {
+    segments.push(truncateThought(s.governing_thought));
+  }
+
+  // Operator segment (drops at COLUMNS < 80).
+  // Phase 121.5-03: preserve the ⚙️ gear glyph from the pre-refactor
+  // statusline (Phase 106-02 D-02 contract). The gear glyph belongs to the
+  // operator-state surface; test-context-monitor-d02-broadcast.cjs Test 1
+  // asserts it is present when operator != JUST_TALK.
+  if (cols >= 80 && s.operator) {
+    segments.push('⚙️ ' + s.operator);
+  }
+
+  // Now re-measure. If the row exceeds the terminal width AND the room
+  // name is the dominant length contributor, truncate it.
+  let joined = segments.join(' │ ');
+  // Visible-char approximation: ANSI-strip + grapheme count would be ideal
+  // but emoji + glyphs roughly cost 1-2 cells each; we use raw .length as a
+  // conservative upper bound.
+  if (joined.length > cols && roomRaw.length > 12) {
+    const cap = cols < 80 ? 12 : 18;
+    const truncated = truncateRoom(roomRaw, cap);
+    segments[0] = '\u{1F3E0} ' + truncated + ' ▶ \u{1F4C2} ' + section;
+    joined = segments.join(' │ ');
+  }
+
+  return joined;
+}
+
+/**
+ * Render the full two-row statusline. Returns Row 1 + "\n" + Row 2.
+ * Caller is responsible for writing to stdout.
+ *
+ * @param {Object} state
+ * @param {number} [columns]
+ * @returns {string}
+ */
+function renderStatusline(state, columns) {
+  return renderRow1(state) + '\n' + renderRow2(state, columns);
+}
+
+module.exports = {
+  renderRow1,
+  renderRow2,
+  renderStatusline,
+  renderBar,
+};