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

package/lib/statusline/cockpit-signals.cjs

@@ -0,0 +1,312 @@
+// lib/statusline/cockpit-signals.cjs -- Phase 187 (statusline-navigator-cockpit)
+//
+// Maps the REAL local signals to the four-tier cockpit state object consumed by
+// lib/statusline/cockpit-renderer.cjs. This is the signal-mapping seam called
+// from scripts/context-monitor on the hot path: it reads only cheap LOCAL files
+// and never calls /mos:doctor (or anything else) on the hot path.
+//
+// SIGNAL SOURCING (Phase 187-01, honest map):
+//   ctx %      -> passed in from context-monitor's AUTO_COMPACT_BUFFER math (host-exposed).
+//   room       -> passed in (STATE.md current_room, host-derived).
+//   brain      -> passed in (MINDRIAN_BRAIN_KEY proxy, host-derived).
+//   next-move  -> jtbd || governing-thought || 'continue'. There is NO dedicated
+//                 imperative next-move signal exposed to the statusline on the hot
+//                 path (the host hands the statusline Claude Code JSON, not Larry's
+//                 routed next step); jtbd is the honest proxy. NAMED DEBT.
+//   room-health-> read from a LOCAL doctor health cache at
+//                 ~/.mindrian/room-health.json {status:'sound'|'drift'|'broken'}.
+//                 /mos:doctor does NOT write this cache today (it writes
+//                 doctor-applied.json, not a room-health status), so absent the
+//                 cache the cockpit renders the default ✅ sound. The READ path is
+//                 wired so the ⚠/🔴 states light up the instant doctor (or a
+//                 session-start hook) starts writing the cache. NAMED DEBT: the
+//                 WRITE side is not yet wired; the host does not expose a live
+//                 room-health signal on the hot path (contract open-item 3).
+//   post-update-> ~/.mindrian/post-update-restart-pending touch-file IS exposed
+//                 today (written by scripts/doctor.cjs --post-update). When present
+//                 it escalates health to drift and promotes "-> run /mos:doctor --fix".
+//   voice glyph-> ~/.mindrian/voice-mark.json side-channel {color|move|turn}, bound
+//                 to the Tier-1 glyph via the Phase 182.1 detector. NAMED DEBT: the
+//                 WRITE side (a turn-capture hook that records Larry's last-turn voice
+//                 mark) is not yet wired -- the host does not expose the assistant's
+//                 last-turn text to the statusline -- so absent the side-channel the
+//                 Tier-1 voice glyph is omitted (⬡ + 🧠 still render).
+//   stance     -> ~/.mindrian/stance-state.json side-channel, read READ-ONLY via
+//                 lib/core/stance-state.cjs (Phase 192-03). This is the CLI-enhancement
+//                 half of SEED-042 (the posture dial); the cross-surface footer-affordance
+//                 baseline is 192-03. LIVE-DERIVED per turn: the chip + forced voice color
+//                 change the instant /mos:stance rewrites the file, and vanish (byte-stable
+//                 default) the instant the override is reset to null.
+//
+// Canon Part 8 (Graph Boundary): LOCAL only. Zero network, zero Brain. Every fs
+// op is try/caught; any failure degrades to the safe default, never throws.
+//
+// GLYPH FENCE: not on the carve-out allowlist -- contains none of the three
+// EXCLUSIVE glyphs (chart / target / gear).
+//
+// House rule: hyphens only, no em-dashes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+let voiceMark = null;
+try {
+  voiceMark = require('../hmi/voice-color-mark.cjs');
+} catch (_e) { /* graceful: no voice glyph */ }
+
+// Phase 192-03 stance-state reader (SEED-042 posture dial). Required the same
+// defensive way as voiceMark so a missing module degrades the stance chip to
+// off rather than crashing the ~300ms statusline redraw. READ-ONLY consumption:
+// this file never re-implements readStance / forcedVoiceColorForStance.
+let stanceState = null;
+try {
+  stanceState = require('../core/stance-state.cjs');
+} catch (_e) { /* graceful: no stance chip */ }
+
+// Quick-task 20260702: the routed-next-step side-channel (closes the 192-04
+// deriveNextMove NAMED DEBT). Required the same defensive way as voiceMark /
+// stanceState so a missing module degrades the Next-move cue to the jtbd proxy
+// rather than crashing the ~300ms statusline redraw. READ-ONLY consumption on the
+// hot path (the WRITE side is the shipped router chokepoint suggestNext).
+let nextMoveCache = null;
+try {
+  nextMoveCache = require('./next-move-cache.cjs');
+} catch (_e) { /* graceful: fall back to the jtbd proxy */ }
+
+function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function mindrianDir() {
+  return path.join(homeDir(), '.mindrian');
+}
+
+/**
+ * Read the LOCAL doctor room-health cache. Defensive: a missing / malformed /
+ * unreadable cache returns null (caller falls back to 'sound').
+ * @returns {'sound'|'drift'|'broken'|null}
+ */
+function readHealthStatus() {
+  try {
+    const p = path.join(mindrianDir(), 'room-health.json');
+    const raw = fs.readFileSync(p, 'utf8');
+    const data = JSON.parse(raw);
+    const status = data && typeof data.status === 'string' ? data.status : null;
+    if (status === 'sound' || status === 'drift' || status === 'broken') return status;
+    return null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Detect the post-update drift signal (the one room-integrity signal exposed
+ * on the hot path today). True when the post-update-restart-pending touch-file
+ * is present.
+ * @returns {boolean}
+ */
+function readPostUpdate() {
+  try {
+    return fs.existsSync(path.join(mindrianDir(), 'post-update-restart-pending'));
+  } catch (_e) {
+    return false;
+  }
+}
+
+/**
+ * Resolve the Tier-1 Voice Signature glyph from the LOCAL voice-mark
+ * side-channel, bound via the Phase 182.1 detector. Returns one of the 5 De
+ * Stijl emoji squares, or null (no side-channel / native host / no detector).
+ * @returns {string|null}
+ */
+function readVoiceGlyph() {
+  if (!voiceMark) return null;
+  let data;
+  try {
+    const p = path.join(mindrianDir(), 'voice-mark.json');
+    data = JSON.parse(fs.readFileSync(p, 'utf8'));
+  } catch (_e) {
+    return null;
+  }
+  if (!data || typeof data !== 'object') return null;
+  try {
+    if (typeof data.color === 'string') {
+      const g = voiceMark.glyphForColor(data.color);
+      if (g) return g;
+    }
+    if (typeof data.move === 'string') {
+      const g = voiceMark.glyphForMove(data.move);
+      if (g) return g;
+    }
+    if (typeof data.turn === 'string' && data.turn.length > 0) {
+      const v = voiceMark.detectVoiceMark(data.turn);
+      if (v && v.valid && v.color) {
+        const g = voiceMark.glyphForColor(v.color);
+        if (g) return g;
+      }
+    }
+  } catch (_e) { /* graceful */ }
+  return null;
+}
+
+/**
+ * Read the LOCAL routed-next-step cache (quick-task 20260702). Hot-path cheap:
+ * one small file read via the next-move-cache side-channel, written by the shipped
+ * router chokepoint (navigation-engine-offer.suggestNext). READ-ONLY: this file
+ * never re-implements the router. Defensive: a missing module / absent / malformed
+ * cache returns null (caller falls back to the jtbd proxy). Never throws (Part 8).
+ * @returns {string|null}
+ */
+function readRoutedNextMove() {
+  try {
+    if (!nextMoveCache || typeof nextMoveCache.readNextMove !== 'function') return null;
+    const cue = nextMoveCache.readNextMove();
+    return (typeof cue === 'string' && cue.trim()) ? cue.trim() : null;
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Derive the Tier-3 next-move cue. The REAL routed next step (the shipped router's
+ * last resolved offer, read from the LOCAL cache) leads -- this is the live wire
+ * that closes the 192-04 NAMED DEBT, so "Next:" changes as the routed step changes.
+ * jtbd is the honest proxy when the router has not offered / abstained; the
+ * governing thought is the secondary fallback; the honest "--" placeholder is the
+ * safe default (Ruling 3c, 2026-07-02): it reads as "no routed step yet", NEVER the
+ * lying word "continue" (which pretended a live cue existed when it did not). The
+ * routed cache is now ALSO fed by the per-turn decide() cue (fire_skill / fired
+ * reach), not just the offer-resolver, so the routed leg wins far more often --
+ * closing the "dead Next: continue" root cause.
+ * @param {Object} opts
+ * @returns {string}
+ */
+function deriveNextMove(opts) {
+  const o = opts || {};
+  const routed = readRoutedNextMove();
+  if (routed) return routed;
+  if (typeof o.jtbd === 'string' && o.jtbd.trim()) return o.jtbd.trim();
+  if (typeof o.governingThought === 'string' && o.governingThought.trim()) {
+    const gt = o.governingThought.trim();
+    return gt.length > 48 ? gt.slice(0, 47) + '…' : gt;
+  }
+  return '--';
+}
+
+/**
+ * Collect the full four-tier cockpit state from the host-exposed scalars plus
+ * the LOCAL signal reads. Pure-ish: reads only cheap LOCAL files, every op
+ * try/caught, never throws.
+ *
+ * @param {Object} opts
+ * @param {string}        [opts.roomName]
+ * @param {number|null}   [opts.ctxPct]
+ * @param {string}        [opts.jtbd]
+ * @param {string}        [opts.governingThought]
+ * @param {boolean}       [opts.brainConnected]
+ * @param {string}        [opts.who] - 'larry' | 'claude' (default larry)
+ * @param {string}        [opts.agentLabel] - non-Larry agent display name
+ * @returns {Object} cockpit state for renderCockpit
+ */
+/**
+ * Read the voice-SWITCH state from the LOCAL voice-mark side-channel (Phase 187.1).
+ * The extended voice-mark.json schema (written by the 187.1-02 checkpoint hook)
+ * carries `switched_now` (a switch was detected on the latest turn) + prior/current
+ * who. Defensive: a missing / v1 / malformed file returns the no-switch default, so
+ * the passive Tier-1 switch chip simply does not show until the WRITE side lands.
+ * @returns {{switched: boolean, direction: ('larry-to-claude'|'claude-to-larry'|null)}}
+ */
+function readVoiceSwitchState() {
+  try {
+    const p = path.join(mindrianDir(), 'voice-mark.json');
+    const data = JSON.parse(fs.readFileSync(p, 'utf8'));
+    if (!data || typeof data !== 'object' || data.switched_now !== true) {
+      return { switched: false, direction: null };
+    }
+    const prior = data.prior_who, cur = data.current_who;
+    let direction = null;
+    if (prior === 'larry' && cur === 'claude') direction = 'larry-to-claude';
+    else if (prior === 'claude' && cur === 'larry') direction = 'claude-to-larry';
+    return { switched: true, direction };
+  } catch (_e) {
+    return { switched: false, direction: null };
+  }
+}
+
+/**
+ * Read the LOCAL stance override (SEED-042 posture dial, Phase 192-03) into the
+ * cockpit signal set. READ-ONLY: delegates to lib/core/stance-state.cjs's
+ * readStance() + forcedVoiceColorForStance(); it never re-implements either or
+ * re-declares STANCES. Mirrors readVoiceSwitchState's try/catch-degrade idiom:
+ * a missing module, an absent / malformed stance-state.json, or a throwing
+ * readStance() all degrade to {stance:null, forced_voice_color:null}. Never
+ * throws (Part 8).
+ * @returns {{stance: ('research'|'tell-act'|'ask'|'redteam'|null), forced_voice_color: ('red'|'blue'|null)}}
+ */
+function readStanceState() {
+  try {
+    if (!stanceState || typeof stanceState.readStance !== 'function') {
+      return { stance: null, forced_voice_color: null };
+    }
+    const stance = stanceState.readStance();
+    if (stance === null || stance === undefined) {
+      return { stance: null, forced_voice_color: null };
+    }
+    const forced = typeof stanceState.forcedVoiceColorForStance === 'function'
+      ? stanceState.forcedVoiceColorForStance(stance)
+      : null;
+    return { stance: stance, forced_voice_color: forced || null };
+  } catch (_e) {
+    return { stance: null, forced_voice_color: null };
+  }
+}
+
+function collectSignals(opts) {
+  const o = opts || {};
+  const postUpdate = readPostUpdate();
+  const cachedHealth = readHealthStatus();
+  // Default sound; post-update escalates inside the renderer (effectiveHealth).
+  const health = cachedHealth || 'sound';
+
+  return {
+    room: typeof o.roomName === 'string' && o.roomName ? o.roomName : 'MindrianOS',
+    health: health,
+    post_update: postUpdate,
+    ctx_pct: (typeof o.ctxPct === 'number' && !Number.isNaN(o.ctxPct)) ? o.ctxPct : null,
+    next_move: deriveNextMove(o),
+    brain: o.brainConnected === true,
+    voice_glyph: readVoiceGlyph(),
+    // Voice Signature (Part 12): WHO is speaking. Default larry -- the
+    // conversational surface IS Larry (Part 10); claude only on explicit
+    // non-Larry agent. agent_label names the host agent when not Larry.
+    who: (typeof o.who === 'string' && o.who.toLowerCase() === 'claude') ? 'claude' : 'larry',
+    agent_label: (typeof o.agentLabel === 'string' && o.agentLabel.trim()) ? o.agentLabel.trim() : '',
+    // Voice SWITCH (Part 12, 187.1-03): when a larry<->claude switch was just
+    // detected, the renderer REPLACES the steady WHO glyph with a passive
+    // announcement. Reads the LOCAL voice-mark side-channel; default no-switch.
+    ...(function () { const sw = readVoiceSwitchState(); return { voice_switched: sw.switched, switch_direction: sw.direction }; })(),
+    // Stance override (SEED-042 posture dial, 192-04; softened by Phase 210 item B):
+    // when a stance is active the renderer shows a passive [stance] chip and
+    // applies the stance's DEFAULT voice color (redteam=red / tell-act=blue) as a
+    // preference -- natural voice detection wins when it yields a color. Absent /
+    // null override -> both fields are null and the render is byte-identical to
+    // pre-plan (R4). Degrades silently on any read failure, matching the
+    // surrounding convention. Field names kept stable across the seam.
+    ...(function () { const st = readStanceState(); return { stance: st.stance, stance_forced_color: st.forced_voice_color }; })(),
+  };
+}
+
+module.exports = {
+  collectSignals,
+  readHealthStatus,
+  readPostUpdate,
+  readVoiceGlyph,
+  readVoiceSwitchState,
+  readStanceState,
+  deriveNextMove,
+  readRoutedNextMove,
+  mindrianDir,
+};

package/lib/statusline/cockpit-telemetry.cjs

@@ -0,0 +1,152 @@
+// lib/statusline/cockpit-telemetry.cjs -- Phase 187 (statusline-navigator-cockpit)
+//
+// The INV-SL-2 measurement hook. INV-SL-2 (docs/STATUSLINE-CONTRACT.md, NORMATIVE):
+//
+//   "The line's success metric is the PERCENTAGE OF STATUSLINE EXPOSURES THAT
+//    LEAD TO A REAL ADVANCING ACTION within the session. Time-on-line,
+//    glance-count, and status-interaction-rate MUST NOT be optimization metrics."
+//
+// This is Gauge 2 (transfer-per-invocation, Canon Part 5 / Appendix D entry 31)
+// pointed at the statusline: the line earns its place only if its prompts ADVANCE
+// real decisions. This hook records the EXPOSURE half of that ratio as a LOCAL,
+// honest, minimal JSONL event. The ADVANCING-ACTION half (correlating an exposure
+// to a downstream real move) is a NAMED RESIDUAL -- not wired here, because doing
+// it honestly needs a session-wide correlation surface this hook deliberately
+// does not build.
+//
+// HONEST + MINIMAL:
+//   - Scalar / enum fields ONLY (state name, ctx band, hero, has_fix). No prose,
+//     no room name, no user content (Part 8).
+//   - Debounced by STATE-SIGNATURE change (not every statusline redraw, which
+//     fires on every prompt cycle): we log when the navigator is EXPOSED TO A NEW
+//     cockpit state, which is the meaningful INV-SL-2 trigger, not raw glance
+//     count (the contract forbids glance-count as a metric). A tiny marker file
+//     (statusline-last.json) holds the last signature.
+//   - Best-effort: every fs op is try/caught; telemetry must never crash or slow
+//     the statusline. A write failure is swallowed.
+//
+// Canon Part 8 (Graph Boundary): LOCAL only. Append-only JSONL under
+// ~/.mindrian/telemetry/. Zero network, zero Brain. Mirrors the established
+// LOCAL-JSONL telemetry pattern (lib/core/telemetry/writer.cjs,
+// ~/.mindrian/telemetry/query-efficiency.jsonl).
+//
+// GLYPH FENCE: not on the carve-out allowlist -- contains none of the three
+// EXCLUSIVE glyphs (chart / target / gear).
+//
+// House rule: hyphens only, no em-dashes.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+const os = require('node:os');
+
+const { analyze } = require('./cockpit-renderer.cjs');
+
+const SCHEMA_VERSION = 1;
+const MAX_STRING_LEN = 120;
+
+function homeDir() {
+  return process.env.HOME || process.env.USERPROFILE || os.homedir();
+}
+
+function telemetryDir() {
+  return path.join(homeDir(), '.mindrian', 'telemetry');
+}
+
+function exposureFile() {
+  return path.join(telemetryDir(), 'statusline-exposure.jsonl');
+}
+
+function markerFile() {
+  return path.join(telemetryDir(), 'statusline-last.json');
+}
+
+function sessionId() {
+  const sid = process.env.CLAUDE_SESSION_ID;
+  return (typeof sid === 'string' && sid.length > 0) ? sid.slice(0, MAX_STRING_LEN) : 'default';
+}
+
+/**
+ * The scalar/enum signature of an exposure: the four facts INV-SL-2 cares about,
+ * none of them user content. Derived from the renderer's single-source-of-truth
+ * analyze().
+ * @param {Object} state - cockpit state
+ * @returns {{state:string, ctx_band:string, hero:string, has_fix:boolean}}
+ */
+function exposureSignature(state) {
+  const a = analyze(state || {});
+  return {
+    state: a.state,
+    ctx_band: a.ctx_band,
+    hero: a.hero,
+    has_fix: a.has_fix,
+  };
+}
+
+function readMarker() {
+  try {
+    return JSON.parse(fs.readFileSync(markerFile(), 'utf8'));
+  } catch (_e) {
+    return null;
+  }
+}
+
+/**
+ * Record a statusline EXPOSURE (INV-SL-2). Debounced by state-signature change
+ * within a session: re-rendering the SAME cockpit state does not log a new
+ * exposure (glance-count is explicitly NOT a metric). Returns {written:boolean}.
+ *
+ * @param {Object} state - cockpit state
+ * @returns {{written:boolean}}
+ */
+function recordExposure(state) {
+  try {
+    const sig = exposureSignature(state);
+    const session = sessionId();
+    const last = readMarker();
+    if (last &&
+        last.session === session &&
+        last.state === sig.state &&
+        last.ctx_band === sig.ctx_band &&
+        last.hero === sig.hero) {
+      // Same state this session: not a new exposure. Do not bloat the log.
+      return { written: false };
+    }
+
+    const record = {
+      event: 'statusline_exposure',
+      schema_version: SCHEMA_VERSION,
+      timestamp: new Date().toISOString(),
+      session_id: session,
+      state: sig.state,
+      ctx_band: sig.ctx_band,
+      hero: sig.hero,
+      has_fix: sig.has_fix,
+    };
+
+    fs.mkdirSync(telemetryDir(), { recursive: true });
+    fs.appendFileSync(exposureFile(), JSON.stringify(record) + '\n', 'utf8');
+    try {
+      fs.writeFileSync(markerFile(), JSON.stringify({
+        session: session,
+        state: sig.state,
+        ctx_band: sig.ctx_band,
+        hero: sig.hero,
+      }));
+    } catch (_e) { /* best-effort marker */ }
+    return { written: true };
+  } catch (_e) {
+    // Best-effort: telemetry must never crash or slow the statusline.
+    return { written: false };
+  }
+}
+
+module.exports = {
+  recordExposure,
+  exposureSignature,
+  telemetryDir,
+  exposureFile,
+  markerFile,
+  SCHEMA_VERSION,
+};

package/lib/statusline/ctx-window.cjs

@@ -0,0 +1,135 @@
+// lib/statusline/ctx-window.cjs -- Quick task 20260702-statusline-context-aware
+//
+// Bucket-1(d): resolve the context-budget percentage from Claude Code's native
+// statusline stdin JSON (data.context_window) instead of the local estimate,
+// with the estimate kept as the FALLBACK for older CC (native fields absent).
+//
+// Why native beats the estimate: CC exposes the real usage directly
+// (used_percentage) plus the hard cliff flag (exceeds_200k_tokens). Reading the
+// native number removes an entire modeling layer and tracks the host's own gauge.
+//
+// GOTCHAS honored (from the CC statusline JSON contract):
+//   - Token fields changed MEANING in CC v2.1.132: we read the stable
+//     PERCENTAGE fields (used_percentage / remaining_percentage), never raw token
+//     counts, so the meaning-shift does not reach us.
+//   - current_usage can be null right after /compact -- in which case
+//     used_percentage is absent/null. We guard that (isFiniteNum) and FALL
+//     THROUGH to the remaining-based derivation rather than rendering a wrong 0.
+//   - Older CC exposes neither -> we return { pct: null } and the renderer
+//     suppresses the gauge (the shipped "no data = no bar" contract).
+//
+// RCA statusline-context-pct-stale-post-compact (2026-07-28) -- THE SCALE RULE:
+// both branches MUST answer the same question ("what percent of the context
+// window is used"), because the second is a FALLBACK for the first, and a
+// fallback that changes the meaning of the number is a wrong number.
+//
+// The fallback used to re-derive "used" from remaining_percentage through the
+// AUTO_COMPACT_BUFFER reservation, which answers a DIFFERENT question ("what
+// percent of the way to the auto-compact trigger"). Measured against 787 real
+// captured host payloads spanning 11 model ids (Apr-Jul 2026),
+// `used_percentage + remaining_percentage === 100` EXACTLY, in every single one:
+// the two fields are exact arithmetic complements carrying the same information,
+// and remaining_percentage is raw window-remaining that does NOT already encode
+// the reservation. So the old buffer transform DOUBLE-COUNTED it and inflated the
+// gauge by up to +16.5 points (true 50 -> 60, true 70 -> 84, true 78 -> 93,
+// true 83.5 -> 100). Since the fallback fires precisely on the post-/compact turn
+// (used_percentage null), the gauge JUMPED UP right after a compact -- read by the
+// navigator as a stale/frozen number that ignored the compact.
+//
+// The correct derivation needs no modeling layer at all: pct = 100 - remaining.
+// It needs no compact-detection heuristic and no stdin field the host does not
+// actually send. AUTO_COMPACT_BUFFER is retained below as documentation of the
+// real host threshold, but it MUST NOT be used to rescale the gauge.
+//
+// Pure + LOCAL (Canon Part 8): a plain object in, a { pct, source } out. Zero
+// network, zero Brain, zero side effects, never throws.
+//
+// House rule: hyphens only, no em-dashes.
+
+'use strict';
+
+// The auto-compact headroom the host reserves before compaction fires, i.e. the
+// used-percentage at which auto-compact is expected to trigger is roughly
+// (100 - AUTO_COMPACT_BUFFER). DOCUMENTATION ONLY as of the 2026-07-28 RCA: it
+// describes a host threshold, it is NOT a scale factor for the gauge. Applying it
+// to the percentage is what produced the post-/compact inflation (see the header).
+const AUTO_COMPACT_BUFFER = 16.5;
+
+function isFiniteNum(x) {
+  return typeof x === 'number' && Number.isFinite(x);
+}
+
+function clampPct(x) {
+  return Math.max(0, Math.min(100, Math.round(x)));
+}
+
+/**
+ * Derive percent-of-window-USED from remaining_percentage, on the SAME scale the
+ * native used_percentage branch reports (the scale rule in the header).
+ *
+ * The host emits these two fields as exact complements (verified across 787 real
+ * captured payloads, 11 model ids: used + remaining === 100, always), so this is
+ * an exact recovery of used_percentage, not a lossy estimate. The name is kept
+ * for the module's existing public surface.
+ *
+ * Returns null when remaining is not a finite number.
+ *
+ * @param {number|null|undefined} remaining - context_window.remaining_percentage
+ * @returns {number|null}
+ */
+function estimateFromRemaining(remaining) {
+  if (!isFiniteNum(remaining)) return null;
+  return clampPct(100 - remaining);
+}
+
+/**
+ * Resolve the context-budget percentage from the native context_window object.
+ *
+ * Priority:
+ *   1. exceeds_200k_tokens === true    -> { pct: 100, source: 'native' } (hard cliff)
+ *   2. used_percentage finite          -> { pct: clamp(used), source: 'native' }
+ *   3. remaining_percentage finite     -> { pct: 100 - remaining, source: 'estimate' }
+ *   4. neither                         -> { pct: null, source: 'none' }
+ *
+ * Branches 2 and 3 return the SAME quantity on the SAME scale (the scale rule in
+ * the header); `source` reports provenance only, never a change of meaning.
+ *
+ * A null / non-object context_window degrades to { pct: null, source: 'none' }.
+ * Never throws.
+ *
+ * @param {Object|null|undefined} cw - data.context_window from the CC stdin JSON
+ * @returns {{ pct: number|null, source: 'native'|'estimate'|'none' }}
+ */
+function resolveCtxPct(cw) {
+  const c = (cw && typeof cw === 'object') ? cw : null;
+  if (!c) return { pct: null, source: 'none' };
+
+  // Hard cliff: the host says the 200k window is exceeded. That is the cliff
+  // regardless of any (possibly stale/null) percentage field.
+  if (c.exceeds_200k_tokens === true) {
+    return { pct: 100, source: 'native' };
+  }
+
+  // Native used percentage (preferred). Guards the post-/compact null: when
+  // current_usage is null the host omits / nulls used_percentage, so isFiniteNum
+  // fails and we fall through to the estimate rather than rendering a wrong 0.
+  if (isFiniteNum(c.used_percentage)) {
+    return { pct: clampPct(c.used_percentage), source: 'native' };
+  }
+
+  // Fallback from remaining_percentage (older CC, or null-after-/compact). Same
+  // scale as the native branch above -- see the scale rule in the header.
+  const est = estimateFromRemaining(c.remaining_percentage);
+  if (est !== null) {
+    return { pct: est, source: 'estimate' };
+  }
+
+  return { pct: null, source: 'none' };
+}
+
+module.exports = {
+  resolveCtxPct,
+  estimateFromRemaining,
+  clampPct,
+  AUTO_COMPACT_BUFFER,
+};

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,
+};