@litfamily/litgrok 1.0.16 → 1.0.17

package/.grok/hooks/auto-handoff-gate.mjs

@@ -8,11 +8,12 @@
 // what makes it fire once.
 
 import { createHash } from 'node:crypto';
-import { existsSync, lstatSync, readFileSync } from 'node:fs';
+import { lstatSync, readFileSync } from 'node:fs';
 import { dirname, join, relative, resolve } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveAutoHandoff } from './auto-handoff.mjs';
 import { readContextRecord } from './litgrok-hud-state.mjs';
+import { readLedgerRecords } from './record-passive-event.mjs';
 
 export const DIRECTIVE_SIGNAL = 'auto-handoff-directive';
 export const RELOAD_SIGNAL = 'auto-handoff-reload';
@@ -40,21 +41,6 @@ function carriesMarker(text, marker) {
   return text.split(/\r?\n/).some((line) => lineCarriesMarker(line, marker));
 }
 
-function ledgerRecords(ledgerFile, sessionId) {
-  if (!existsSync(ledgerFile)) return [];
-  const records = [];
-  for (const line of readFileSync(ledgerFile, 'utf8').split(/\r?\n/)) {
-    if (!line) continue;
-    try {
-      const record = JSON.parse(line);
-      if (record.sessionId === sessionId) records.push(record);
-    } catch {
-      // A damaged line is skipped; the recorder itself refuses to append to a ledger it cannot read.
-    }
-  }
-  return records;
-}
-
 function lastIndex(records, predicate, after = -1) {
   for (let index = records.length - 1; index > after; index -= 1) {
     if (predicate(records[index])) return index;
@@ -121,7 +107,7 @@ export function evaluateAutoHandoff({ event, env = process.env, workspaceRoot, e
   const settings = resolveAutoHandoff({ env, dirs: [workspaceRoot, eventCwd] });
   if (!settings.active) return { block: false };
 
-  const records = ledgerRecords(ledgerFile, sessionId);
+  const records = readLedgerRecords(ledgerFile, sessionId);
   const directiveIndex = lastIndex(records, (record) => record.signal === DIRECTIVE_SIGNAL);
   const compactIndex = directiveIndex < 0 ? -1 : lastIndex(records, (record) => record.event === 'PostCompact', directiveIndex);
 

package/.grok/hooks/auto-handoff.mjs

@@ -4,9 +4,10 @@
 // environment); `on` without a number reuses the last value, and there is no built-in default.
 
 import { randomUUID } from 'node:crypto';
-import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
-import { isAbsolute, join } from 'node:path';
+import { lstatSync, mkdirSync, readFileSync, realpathSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { dirname, isAbsolute, join, resolve } from 'node:path';
 import { readNewestContextRecord } from './litgrok-hud-state.mjs';
+import { ignoreStateDirectory } from './record-passive-event.mjs';
 
 export const ENABLE_VARIABLE = 'LITGROK_AUTO_HANDOFF';
 export const PERCENT_VARIABLE = 'LITGROK_AUTO_HANDOFF_PERCENT';
@@ -23,6 +24,58 @@ function configPath(directory) {
   return join(directory, ...CONFIG_FILE.split('/'));
 }
 
+function present(path) {
+  try {
+    lstatSync(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function samePath(left, right) {
+  const canonical = (path) => {
+    try {
+      return realpathSync(path);
+    } catch {
+      return resolve(path);
+    }
+  };
+  return canonical(left) === canonical(right);
+}
+
+// Project hooks run only from a Git project root, and Grok hands its workspace root to the Stop hook and
+// the status line. The command picks the nearest Git root from any subfolder; outside Git it uses cwd.
+export function projectRoot(cwd) {
+  let directory = resolve(cwd);
+  for (;;) {
+    if (present(join(directory, '.git'))) return { root: directory, git: true };
+    const parent = dirname(directory);
+    if (parent === directory) return { root: resolve(cwd), git: false };
+    directory = parent;
+  }
+}
+
+// The host decides the workspace root, so say when the chosen folder may not be the one it uses.
+function rootNotes({ root, git }, home) {
+  const notes = [];
+  if (!git) {
+    notes.push(`Note: no Git root above ${root}, so this setting belongs to that folder alone. Project hooks need a Git root, and they read this file only when Grok Build starts in that folder.`);
+  } else if (home && samePath(root, home)) {
+    notes.push(`Note: the Git root here is your home folder (${root}), so this setting applies to Grok Build sessions started in your home folder. For a project inside it, run git init in the project and run this command there.`);
+  }
+  for (let directory = dirname(root); ; directory = dirname(directory)) {
+    // A dotfiles repository at home is not a project root unless LitGrok already keeps state there.
+    const homeRepository = home && samePath(directory, home) && !present(join(directory, '.grok', 'litgrok'));
+    if (!homeRepository && (present(join(directory, '.git')) || present(join(directory, '.grok', 'litgrok')))) {
+      notes.push(`Note: ${directory} above it is also a project root. The hooks read the file under the folder where you start Grok Build: ${configPath(root)} when you start in ${root}, or ${configPath(directory)} when you start in ${directory}. Run this command in the folder where you start Grok Build.`);
+      break;
+    }
+    if (dirname(directory) === directory) break;
+  }
+  return notes;
+}
+
 // Returns { found: false } or { found: true, valid, enabled, percent, reason }.
 export function readAutoHandoffFile(directory) {
   const path = configPath(directory);
@@ -127,6 +180,7 @@ function ensureDirectory(path) {
 export function writeAutoHandoffFile(directory, settings) {
   ensureDirectory(join(directory, '.grok'));
   ensureDirectory(join(directory, '.grok', 'litgrok'));
+  ignoreStateDirectory(join(directory, '.grok', 'litgrok'));
   const target = configPath(directory);
   try {
     const existing = lstatSync(target);
@@ -189,13 +243,17 @@ export async function runAutoHandoff(args, { env = process.env, stdout = process
     return 1;
   }
 
-  const resolved = resolveAutoHandoff({ env, dirs: [cwd] });
+  const located = projectRoot(cwd);
+  const { root } = located;
+  const notes = rootNotes(located, env.HOME || null);
+  const file = `Project file: ${configPath(root)}`;
+  const resolved = resolveAutoHandoff({ env, dirs: [root] });
   if (action === 'status') {
-    stdout.write(`${describe(resolved, env).join('\n')}\n`);
+    stdout.write(`${[...describe(resolved, env), file, ...notes].join('\n')}\n`);
     return 0;
   }
 
-  const stored = readAutoHandoffFile(cwd);
+  const stored = readAutoHandoffFile(root);
   const previous = stored.found && stored.valid ? stored.percent : null;
   let next;
   if (action === 'off') {
@@ -211,12 +269,12 @@ export async function runAutoHandoff(args, { env = process.env, stdout = process
   }
 
   try {
-    writeAutoHandoffFile(cwd, next);
+    writeAutoHandoffFile(root, next);
   } catch (error) {
     return fail(`litgrok auto-handoff: ${error instanceof Error ? error.message : String(error)}`);
   }
 
-  const after = resolveAutoHandoff({ env, dirs: [cwd] });
+  const after = resolveAutoHandoff({ env, dirs: [root] });
   const lines = [];
   if (action === 'off') {
     lines.push('Automatic handoff is OFF for this project.');
@@ -225,6 +283,7 @@ export async function runAutoHandoff(args, { env = process.env, stdout = process
     lines.push(`Automatic handoff is ON at ${next.percent} percent for this project.`);
     lines.push('When a turn ends with the context at or above that percent, the model is asked to write a handoff and then to tell you to run /compact.');
   }
+  lines.push(`Saved in ${configPath(root)}`, ...notes);
   if (after.enabled !== next.enabled) lines.push(`Warning: ${ENABLE_VARIABLE} is set in this shell, so sessions started from here stay ${after.enabled ? 'ON' : 'OFF'}.`);
   const { warning } = hostWarning(next.enabled ? next.percent : null, env);
   if (warning) lines.push(warning);

package/.grok/hooks/deliverable-hedge-guard.mjs

@@ -97,14 +97,15 @@ function loadRules() {
 }
 
 async function readEvent() {
-  let input = '';
-  let oversized = false;
+  // Decode once: a multi-byte character can straddle two pipe chunks.
+  const chunks = [];
+  let bytes = 0;
   for await (const chunk of process.stdin) {
-    input += chunk;
-    if (Buffer.byteLength(input) > MAX_EVENT_BYTES) { input = ''; oversized = true; }
+    bytes += chunk.length;
+    if (bytes <= MAX_EVENT_BYTES) chunks.push(chunk);
   }
-  if (oversized) throw new Error('event exceeded the size limit; write left unchanged');
-  try { return JSON.parse(input); } catch { throw new Error('event could not be parsed; write left unchanged'); }
+  if (bytes > MAX_EVENT_BYTES) throw new Error('event exceeded the size limit; write left unchanged');
+  try { return JSON.parse(Buffer.concat(chunks).toString('utf8')); } catch { throw new Error('event could not be parsed; write left unchanged'); }
 }
 
 try {

package/.grok/hooks/lit-status-line.mjs

@@ -1,20 +1,50 @@
 #!/usr/bin/env node
 
-import { isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { closeSync, constants, fstatSync, openSync, readFileSync, readSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
 import { resolveAutoHandoff } from './auto-handoff.mjs';
 import { readHudRecordForCwd, writeContextRecord } from './litgrok-hud-state.mjs';
 
 const MAX_INPUT_BYTES = 64 * 1024;
 const GRADIENT_STOPS = [[255, 99, 55], [255, 45, 149], [0, 229, 255]];
+const BRAND_COLOR = [255, 99, 55];
+// Grok cuts each line at 1024 characters, escapes included.
+const MAX_LINE_CHARACTERS = 1024;
+const RECORD_SCHEMA = 'litgrok.hook-event/v1';
+// The ribbon reads only the end of the session ledger, enough for a few hundred records.
+const LEDGER_TAIL_BYTES = 128 * 1024;
+const COMPLETE_SHOWN_MS = 20 * 1000;
+const HANDOFF_NEAR_POINTS = 10;
+const CLOCK_SKEW_MS = 5 * 1000;
+const TOOL_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
+// [background, foreground] of each pill.
+const PILLS = {
+  brand: [[255, 45, 149], [18, 6, 12]],
+  running: [[10, 166, 194], [0, 19, 24]],
+  complete: [[29, 77, 54], [184, 245, 207]],
+  warning: [[90, 58, 8], [255, 210, 138]],
+};
+const TEXT = { dim: [139, 148, 158], amber: [255, 175, 60], green: [107, 219, 143] };
+const GLYPHS = {
+  basic: { running: '●', complete: '✓', warning: '⚠', timer: '', tools: (n) => `${n} tool${n === 1 ? '' : 's'}`, agents: (n) => `${n} agent${n === 1 ? '' : 's'}` },
+  nerd: { running: '\uf111', complete: '\uf00c', warning: '\uf071', timer: '\uf017 ', tools: (n) => `\uf0ad ${n}`, agents: (n) => `\uf0c0 ${n}` },
+};
+const ANSI_16 = [[0, 0, 0], [205, 0, 0], [0, 205, 0], [205, 205, 0], [0, 0, 238], [205, 0, 205], [0, 205, 205], [229, 229, 229],
+  [127, 127, 127], [255, 0, 0], [0, 255, 0], [255, 255, 0], [92, 92, 255], [255, 0, 255], [0, 255, 255], [255, 255, 255]];
 
 async function readInput() {
-  let input = '';
+  // Decode once: a multi-byte character can straddle two pipe chunks.
+  const chunks = [];
+  let bytes = 0;
   for await (const chunk of process.stdin) {
-    input += chunk;
-    if (Buffer.byteLength(input) > MAX_INPUT_BYTES) return null;
+    bytes += chunk.length;
+    if (bytes > MAX_INPUT_BYTES) return null;
+    chunks.push(chunk);
   }
   try {
-    const value = JSON.parse(input);
+    const value = JSON.parse(Buffer.concat(chunks).toString('utf8'));
     return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
   } catch {
     return null;
@@ -31,9 +61,42 @@ function plainText(value, fallback) {
   return cleaned || fallback;
 }
 
-function contextPercent(value) {
-  if (typeof value !== 'number' || !Number.isFinite(value)) return '?';
-  return String(Math.round(Math.max(0, Math.min(100, value))));
+// The installer writes its manifest beside the hooks folder, so an installed copy can name its version.
+function installedVersion() {
+  try {
+    const manifest = JSON.parse(readFileSync(join(dirname(dirname(fileURLToPath(import.meta.url))), '.litgrok-install-manifest.json'), 'utf8'));
+    return typeof manifest?.version === 'string' && /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?$/u.test(manifest.version) ? manifest.version : '';
+  } catch {
+    return '';
+  }
+}
+
+// Grok sends effort.level only for models that take a reasoning effort.
+function effortLevel(value) {
+  return typeof value === 'string' && /^[a-z][a-z-]{0,11}$/u.test(value) ? value : '';
+}
+
+function windowSize(value) {
+  if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) return '';
+  if (value >= 1000000 && value % 100000 === 0) return `${value / 1000000}m`;
+  return `${Math.max(1, Math.round(value / 1000))}k`;
+}
+
+function contextBar(percent) {
+  const exact = (percent * 3) / 100;
+  const filled = Math.floor(exact);
+  const partialBlocks = ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉'];
+  const partial = filled < 3 && exact > filled ? Math.max(1, Math.min(7, Math.round((exact - filled) * 8))) : 0;
+  return `${'█'.repeat(filled)}${partialBlocks[partial]}${'░'.repeat(3 - filled - (partial > 0 ? 1 : 0))}`;
+}
+
+// A percent Grok did not send shows as ?, never as a guess.
+function contextText(contextWindow) {
+  const size = windowSize(contextWindow?.context_window_size);
+  const value = contextWindow?.used_percentage;
+  if (typeof value !== 'number' || !Number.isFinite(value)) return size ? `ctx ?/${size}` : 'ctx ?';
+  const percent = Math.round(Math.max(0, Math.min(100, value)));
+  return `ctx [${contextBar(percent)}] ${percent}%${size ? `/${size}` : ''}`;
 }
 
 function cellWidth(character) {
@@ -65,37 +128,62 @@ function clipCells(text, maximum) {
   return result;
 }
 
+function distance(left, right) {
+  return left.reduce((total, value, index) => total + (value - right[index]) ** 2, 0);
+}
+
+function xterm256(rgb) {
+  const levels = [0, 95, 135, 175, 215, 255];
+  const nearest = (value) => levels.reduce((best, level, index) => (Math.abs(level - value) < Math.abs(levels[best] - value) ? index : best), 0);
+  const cube = rgb.map(nearest);
+  const gray = Math.max(0, Math.min(23, Math.round((rgb.reduce((total, value) => total + value, 0) / 3 - 8) / 10)));
+  const grayValue = 8 + gray * 10;
+  return distance(rgb, [grayValue, grayValue, grayValue]) < distance(rgb, cube.map((index) => levels[index]))
+    ? 232 + gray
+    : 16 + cube[0] * 36 + cube[1] * 6 + cube[2];
+}
+
+// depth is 24 (truecolor), 256 or 16; the 16-colour codes are the nearest of the standard xterm palette.
+function sgr(rgb, depth, background = false) {
+  if (depth === 256) return `\u001b[${background ? 48 : 38};5;${xterm256(rgb)}m`;
+  if (depth === 16) {
+    const index = ANSI_16.reduce((best, color, at) => (distance(rgb, color) < distance(rgb, ANSI_16[best]) ? at : best), 0);
+    return `\u001b[${(index < 8 ? 30 : 82) + index + (background ? 10 : 0)}m`;
+  }
+  return `\u001b[${background ? 48 : 38};2;${rgb.join(';')}m`;
+}
+
 function gradientColor(position) {
   const stop = position <= 0.5 ? 0 : 1;
   const fraction = position <= 0.5 ? position * 2 : (position - 0.5) * 2;
   return GRADIENT_STOPS[stop].map((value, index) => Math.round(value + (GRADIENT_STOPS[stop + 1][index] - value) * fraction));
 }
 
-function paintLabel(text) {
+// Bold is set once and each letter only changes the colour, so the longest label stays far below the cut.
+function paintLabel(text, depth) {
   const characters = [...text];
-  return characters.map((character, index) => {
+  return `\u001b[1m${characters.map((character, index) => {
     if (character === ' ') return character;
     const position = characters.length === 1 ? 0 : index / (characters.length - 1);
-    return `\u001b[1m\u001b[38;2;${gradientColor(position).join(';')}m${character}\u001b[0m`;
-  }).join('');
+    return `${sgr(gradientColor(position), depth)}${character}`;
+  }).join('')}\u001b[0m`;
 }
 
-function formatRow(discipline, model, context, color) {
+function formatRow({ discipline, model, effort, context, version }, depth, maxCells) {
+  const brand = `[🔥LIT${version ? ` v${version}` : ''}]`;
+  const suffix = `${effort ? ` [${effort}]` : ''} │ ${context}`;
+  let ignition = '';
+  let ignitionText = '';
   if (discipline) {
-    const prefix = '🔥 LIT IGNITED · ';
-    const maxDisciplineCells = discipline === 'lit-scientific-visualization' ? 32 : 24;
-    const disciplineText = clipCells(discipline, maxDisciplineCells);
-    const label = `LIT IGNITED · ${disciplineText}`;
-    const middle = ` ${disciplineText} 🔥 │ `;
-    const suffix = ` │ ctx ${context}%`;
-    const modelText = clipCells(model, Math.max(0, 79 - width(prefix + middle + suffix)));
-    return `🔥 ${color ? paintLabel(label) : label} 🔥 │ ${modelText}${suffix}`;
+    // The skill name gives way after the model, and the model keeps at least its ellipsis.
+    const room = maxCells - width(`${brand} 🔥 LIT IGNITED ·  🔥 | ${suffix}`) - 1;
+    const maxDisciplineCells = Math.max(1, Math.min(discipline === 'lit-scientific-visualization' ? 32 : 24, room));
+    const label = `LIT IGNITED · ${clipCells(discipline, maxDisciplineCells)}`;
+    ignitionText = ` 🔥 ${label} 🔥`;
+    ignition = ` 🔥 ${depth ? paintLabel(label, depth) : label} 🔥`;
   }
-  const prefix = 'LIT · grok │ ';
-  const suffix = ` │ ctx ${context}%`;
-  const modelText = clipCells(model, Math.max(0, 79 - width(prefix + suffix)));
-  const row = `${prefix}${modelText}${suffix}`;
-  return color ? `\u001b[1m\u001b[38;2;255;99;55m${row}\u001b[0m` : row;
+  const modelText = clipCells(model, Math.max(1, maxCells - width(`${brand}${ignitionText} | ${suffix}`)));
+  return `${depth ? `\u001b[1m${sgr(BRAND_COLOR, depth)}${brand}\u001b[0m` : brand}${ignition} | ${modelText}${suffix}`;
 }
 
 // Automatic handoff needs Grok's context percent, which only the status line receives. Nothing is
@@ -116,6 +204,162 @@ function recordContextForHandoff(status) {
   });
 }
 
+function statusDirs(status) {
+  return [status?.workspace?.repo_root, status?.workspace?.current_dir, status?.cwd];
+}
+
+// The passive hooks keep the session ledger under the workspace root Grok gives them, which the status
+// input names as one of these folders. Only a regular file is read, and only its end.
+function readLedgerTail(status) {
+  const sessionId = status?.session_id;
+  if (typeof sessionId !== 'string' || sessionId === '' || sessionId.length > 512) return null;
+  const name = `${createHash('sha256').update(sessionId).digest('hex').slice(0, 32)}.jsonl`;
+  for (const directory of statusDirs(status)) {
+    if (typeof directory !== 'string' || !isAbsolute(directory)) continue;
+    let descriptor;
+    try {
+      descriptor = openSync(join(realpathSync(directory), '.grok', 'litgrok', 'session-ledger', name), constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    } catch {
+      continue;
+    }
+    try {
+      const file = fstatSync(descriptor);
+      if (!file.isFile()) return null;
+      const length = Math.min(file.size, LEDGER_TAIL_BYTES);
+      const buffer = Buffer.alloc(length);
+      let text = buffer.subarray(0, readSync(descriptor, buffer, 0, length, file.size - length)).toString('utf8');
+      // A read that starts mid-file drops its first, partial line.
+      if (length < file.size) text = text.slice(text.indexOf('\n') + 1 || text.length);
+      return text.split('\n').flatMap((line) => {
+        try {
+          const record = JSON.parse(line);
+          return record?.schema === RECORD_SCHEMA && record.sessionId === sessionId && Number.isFinite(Date.parse(record.recordedAt)) ? [record] : [];
+        } catch {
+          return [];
+        }
+      });
+    } catch {
+      return null;
+    } finally {
+      closeSync(descriptor);
+    }
+  }
+  return null;
+}
+
+// What the ledger says about the current turn: it starts at the prompt Grok names, or the latest one.
+// A turn whose start is not in the tail is unknown, so nothing is counted.
+function turnActivity(records, promptId) {
+  if (!records) return null;
+  const prompts = records.flatMap((record, index) => (record.event === 'UserPromptSubmit' ? [index] : []));
+  const matching = typeof promptId === 'string' ? prompts.filter((index) => records[index].promptId === promptId) : [];
+  const start = (matching.length > 0 ? matching : prompts).at(-1);
+  if (start === undefined) return null;
+  const turn = records.slice(start + 1);
+  const count = (event) => turn.filter((record) => record.event === event).length;
+  const held = (record) => record.signal === 'plan-gate-block' || record.signal === 'auto-handoff-directive'
+    || (record.signal === 'auto-handoff-reload' && record.outcome === 'loaded');
+  const last = turn.at(-1);
+  const ended = last?.event === 'Stop' && !held(last);
+  return {
+    startedAt: Date.parse(records[start].recordedAt),
+    endedAt: ended ? Date.parse(last.recordedAt) : null,
+    tools: turn.filter((record) => TOOL_EVENTS.has(record.event)).length,
+    agents: Math.max(0, count('SubagentStart') - count('SubagentStop')),
+    planGate: !ended && turn.some((record) => record.signal === 'plan-gate-block'),
+    handoffAsked: !ended && turn.some((record) => record.signal === 'auto-handoff-directive'),
+  };
+}
+
+function duration(ms) {
+  const seconds = Math.floor(ms / 1000);
+  if (seconds < 60) return `${seconds}s`;
+  if (seconds < 3600) return `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s`;
+  return `${Math.floor(seconds / 3600)}h${String(Math.floor(seconds / 60) % 60).padStart(2, '0')}m`;
+}
+
+// Returns [long, short] warning text, or null. A plan-gate hold comes first, then a handoff request,
+// then a context at or near the automatic-handoff percent.
+function warningText(status, activity) {
+  if (activity?.planGate) return ['plan gate: save plans/<slug>.md', 'plan gate'];
+  if (activity?.handoffAsked) return ['handoff requested', 'handoff'];
+  const used = status?.context_window?.used_percentage;
+  if (typeof used !== 'number' || !Number.isFinite(used)) return null;
+  const settings = resolveAutoHandoff({ env: process.env, dirs: statusDirs(status) });
+  if (!settings.active) return null;
+  const percent = Math.round(Math.max(0, Math.min(100, used)));
+  if (percent >= settings.percent) return [`ctx ${percent}% ≥ handoff at ${settings.percent}%`, `ctx ${percent}%≥${settings.percent}%`];
+  if (percent >= settings.percent - HANDOFF_NEAR_POINTS) return [`ctx ${percent}% → handoff at ${settings.percent}%`, `ctx ${percent}%→${settings.percent}%`];
+  return null;
+}
+
+function bandState(status, now) {
+  const started = status?.turn?.started_at_ms;
+  const running = typeof started === 'number' && Number.isFinite(started) && started > 0;
+  const activity = turnActivity(readLedgerTail(status), running ? status.prompt_id : undefined);
+  const warning = warningText(status, activity);
+  let timer = null;
+  let state = null;
+  if (running) {
+    state = 'running';
+    if (started <= now + CLOCK_SKEW_MS) timer = duration(Math.max(0, now - started));
+  } else if (activity?.endedAt && now - activity.endedAt <= COMPLETE_SHOWN_MS && activity.endedAt <= now + CLOCK_SKEW_MS) {
+    state = 'complete';
+    timer = duration(Math.max(0, activity.endedAt - activity.startedAt));
+  }
+  if (state === null && warning === null) return null;
+  return { state, timer, warning, activity: running || state === 'complete' ? activity : null };
+}
+
+function pill(text, kind, depth, nerd) {
+  if (!depth) return { plain: `(${text})`, painted: `(${text})` };
+  const [background, foreground] = PILLS[kind];
+  if (nerd) {
+    const cap = (glyph) => `${sgr(background, depth)}${glyph}\u001b[0m`;
+    return { plain: `${text}`, painted: `${cap('')}${sgr(background, depth, true)}${sgr(foreground, depth)}\u001b[1m${text}\u001b[0m${cap('')}` };
+  }
+  return { plain: ` ${text} `, painted: `${sgr(background, depth, true)}${sgr(foreground, depth)}\u001b[1m ${text} \u001b[0m` };
+}
+
+function renderBand(discipline, band, depth, nerd, { warningIndex = 0, tools = true, agents = true, timer = true, warning = true, brand = 'full', skillCells = Infinity }) {
+  const glyphs = nerd ? GLYPHS.nerd : GLYPHS.basic;
+  const kind = band.warning ? 'warning' : band.state === 'complete' ? 'complete' : 'running';
+  const pills = [pill(brand === 'full' ? '🔥 LIT' : '🔥', 'brand', depth, nerd), pill(`${glyphs[kind]} ${clipCells(discipline, skillCells)}`, kind, depth, nerd)];
+  const items = [];
+  const paint = (text, rgb, bold = false) => (depth ? `${bold ? '\u001b[1m' : ''}${sgr(rgb, depth)}${text}\u001b[0m` : text);
+  if (band.warning && warning) items.push({ plain: band.warning[warningIndex], painted: paint(band.warning[warningIndex], TEXT.amber, true) });
+  if (band.state === 'complete') items.push({ plain: 'complete', painted: paint('complete', TEXT.green, true) });
+  if (band.timer && timer) items.push({ plain: `${glyphs.timer}${band.timer}`, painted: paint(`${glyphs.timer}${band.timer}`, TEXT.dim) });
+  if (band.activity && tools) items.push({ plain: glyphs.tools(band.activity.tools), painted: paint(glyphs.tools(band.activity.tools), TEXT.dim) });
+  if (band.activity && agents && band.state === 'running' && band.activity.agents > 0) {
+    items.push({ plain: glyphs.agents(band.activity.agents), painted: paint(glyphs.agents(band.activity.agents), TEXT.dim) });
+  }
+  const separator = { plain: ' · ', painted: paint(' · ', TEXT.dim) };
+  const join = (key) => [pills.map((part) => part[key]).join(' '), items.map((part) => part[key]).join(separator[key])].filter(Boolean).join(' ');
+  return { plain: join('plain'), painted: join('painted') };
+}
+
+// Narrow rows give up tool calls first, then subagents, the timer, the long warning, the warning itself
+// and the brand's name, and last of all clip the skill name.
+function formatBand(discipline, band, depth, nerd, maxCells) {
+  const tiers = [
+    {},
+    { tools: false },
+    { tools: false, agents: false },
+    { tools: false, agents: false, timer: false },
+    { tools: false, agents: false, timer: false, warningIndex: 1 },
+    { tools: false, agents: false, timer: false, warningIndex: 1, brand: 'compact' },
+    { tools: false, agents: false, timer: false, warning: false, brand: 'compact' },
+  ];
+  for (const tier of tiers) {
+    const row = renderBand(discipline, band, depth, nerd, tier);
+    if (width(row.plain) <= maxCells && row.painted.length <= MAX_LINE_CHARACTERS) return row.painted;
+  }
+  const last = tiers.at(-1);
+  const room = maxCells - width(renderBand('', band, depth, nerd, { ...last, skillCells: 0 }).plain);
+  return renderBand(discipline, band, depth, nerd, { ...last, skillCells: Math.max(1, room) }).painted;
+}
+
 const input = await readInput();
 try {
   recordContextForHandoff(input);
@@ -131,7 +375,27 @@ try {
 }
 const discipline = record?.discipline ?? null;
 const model = plainText(input?.model?.display_name, 'grok');
-const context = contextPercent(input?.context_window?.used_percentage);
-const color = process.env.LITGROK_HUD_COLOR !== '0' && !Object.hasOwn(process.env, 'NO_COLOR');
-const row = formatRow(discipline, model, context, color);
-process.stdout.write(`${row}\n`);
+const colorSetting = process.env.LITGROK_HUD_COLOR;
+const depth = colorSetting === '0' || Object.hasOwn(process.env, 'NO_COLOR') ? 0 : colorSetting === '256' ? 256 : colorSetting === '16' ? 16 : 24;
+// Grok sets COLUMNS to the width of the row; without it the row keeps to 79 cells.
+const columns = Number.parseInt(process.env.COLUMNS ?? '', 10);
+const maxCells = Number.isFinite(columns) && columns >= 20 ? Math.min(columns, 1000) - 1 : 79;
+const row = formatRow({
+  discipline,
+  model,
+  effort: effortLevel(input?.effort?.level),
+  context: contextText(input?.context_window),
+  version: installedVersion(),
+}, depth, maxCells);
+// The ribbon is a second line, shown only while a skill is active and a turn runs, has just ended or
+// needs attention. LITGROK_HUD_LINES=1 keeps the compact row alone.
+let band = null;
+if (discipline && process.env.LITGROK_HUD_LINES !== '1') {
+  try {
+    const state = bandState(input, Date.now());
+    if (state) band = formatBand(discipline, state, depth, process.env.LITGROK_HUD_GLYPHS === 'nerd', maxCells);
+  } catch {
+    band = null;
+  }
+}
+process.stdout.write(band ? `${row}\n${band}\n` : `${row}\n`);

package/.grok/hooks/plan-gate.mjs

@@ -11,21 +11,13 @@ import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node
 import { join } from 'node:path';
 
 import { countImplementationRows } from '../skills/lit-plan/scripts/scaffold-plan.mjs';
+import { readLedgerRecords } from './record-passive-event.mjs';
 
 export const PLAN_GATE_SIGNAL = 'plan-gate-block';
 export const PLAN_GATE_MAX_BLOCKS = 2;
 const SCAFFOLD = '.grok/skills/lit-plan/scripts/scaffold-plan.mjs';
 const MAX_PLAN_BYTES = 256 * 1024;
 
-function ledgerRecords(ledgerFile, sessionId) {
-  if (!existsSync(ledgerFile)) return [];
-  return readFileSync(ledgerFile, 'utf8')
-    .split(/\r?\n/)
-    .filter(Boolean)
-    .map((line) => JSON.parse(line))
-    .filter((record) => record.sessionId === sessionId);
-}
-
 function turnStart(records, promptId) {
   const prompts = records.filter((record) => record.event === 'UserPromptSubmit');
   const matching = typeof promptId === 'string' ? prompts.filter((record) => record.promptId === promptId) : [];
@@ -59,7 +51,7 @@ export function evaluatePlanGate({ event, workspaceRoot, sessionId, ledgerFile }
   if (event.reason !== undefined && event.reason !== 'end_turn') return { block: false };
   if (event.subagentType !== undefined) return { block: false };
 
-  const records = ledgerRecords(ledgerFile, sessionId);
+  const records = readLedgerRecords(ledgerFile, sessionId);
   const { since, litPlanTurn } = turnStart(records, event.promptId);
   const planMode = event.permissionMode === 'plan' || litPlanTurn;
   const written = plansWrittenSince(workspaceRoot, since);