@litfamily/litgrok 1.0.26 → 1.0.28

package/.grok/hooks/lit-mark.mjs

@@ -104,6 +104,48 @@ export function lockup(productName) {
   return standard.map((row, index) => row.padEnd(28) + (index === 5 ? `  ${label}` : ''));
 }
 
+// The psychedelic rewind hue for the lit-adhd card and ignition mark: one hue at a time at a
+// steady lightness, so the card never flashes. `motion` is 'full' (a 24-second hue cycle),
+// 'subtle' (a slow 96-second drift) or 'off' (one still rainbow frame). Returns [r, g, b].
+export function rewindHue(nowMs, motion = 'full') {
+  return hueToRgb(rewindBaseAngle(nowMs, motion));
+}
+
+// One full wheel across a run of `total` cells, so each cell of a pill or mark takes its own
+// step round the wheel at the same steady lightness. Colour moves only on fixed glyphs.
+export function rewindCellRgb(nowMs, motion, index, total) {
+  const base = rewindBaseAngle(nowMs, motion);
+  const step = total > 1 ? 360 / total : 0;
+  return hueToRgb((((base + step * index) % 360) + 360) % 360);
+}
+
+function rewindBaseAngle(nowMs, motion = 'full') {
+  if (motion !== 'subtle' && motion !== 'off' && motion !== 'full') motion = 'full';
+  const time = Number.isFinite(nowMs) ? nowMs : 0;
+  const hue = motion === 'off' ? 280 : (((time % 96_000) + 96_000) % 96_000) / 96_000 * 360;
+  const period = motion === 'subtle' ? 1 : 4;
+  return (((hue * period) % 360) + 360) % 360;
+}
+
+function hueToRgb(angle) {
+  const saturation = 0.85;
+  const lightness = 0.62;
+  const chroma = (1 - Math.abs(2 * lightness - 1)) * saturation;
+  const part = chroma * (1 - Math.abs(((angle / 60) % 2) - 1));
+  const match = lightness - chroma / 2;
+  let red;
+  let green;
+  let blue;
+  if (angle < 60) [red, green, blue] = [chroma, part, 0];
+  else if (angle < 120) [red, green, blue] = [part, chroma, 0];
+  else if (angle < 180) [red, green, blue] = [0, chroma, part];
+  else if (angle < 240) [red, green, blue] = [0, part, chroma];
+  else if (angle < 300) [red, green, blue] = [part, 0, chroma];
+  else [red, green, blue] = [chroma, 0, part];
+  const channel = (value) => Math.max(0, Math.min(255, Math.round((value + match) * 255)));
+  return [channel(red), channel(green), channel(blue)];
+}
+
 export function colorize(rows, { mode = 'none' } = {}) {
   if (!['truecolor', '256', 'none'].includes(mode)) throw new TypeError('Invalid color mode');
   if (mode === 'none') return [...rows];

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

@@ -5,7 +5,9 @@ import { closeSync, constants, fstatSync, openSync, readFileSync, readSync, real
 import { dirname, isAbsolute, join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { resolveAutoHandoff } from './auto-handoff.mjs';
+import { rewindCellRgb } from './lit-mark.mjs';
 import { readHudRecordForCwd, writeContextRecord } from './litgrok-hud-state.mjs';
+import { readOtherSessions } from './session-rows.mjs';
 import { STAGES, readWorkflowState } from './workflow-stage.mjs';
 
 const MAX_INPUT_BYTES = 64 * 1024;
@@ -38,17 +40,17 @@ const GLYPHS = {
   basic: {
     fire: '🔥', tick: '✓', cross: '✗', dot: '·', lit: '━', unlit: '─', run: '●', warn: '⚠', elbow: '└', next: '▸', sep: '│',
     full: '▮', empty: '▯', rail: '▎', ellipsis: '…', spinner: BRAILLE, bar: ['█', '░', ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']],
-    timer: '', tools: (n) => plural(n, 'tool'), agents: (n) => plural(n, 'agent'), git: 'git ',
+    timer: '', burst: '★', tools: (n) => plural(n, 'tool'), agents: (n) => plural(n, 'agent'), git: 'git ',
   },
   nerd: {
     fire: '🔥', tick: '', cross: '', dot: '·', lit: '━', unlit: '─', run: '', warn: '', elbow: '└', next: '▸', sep: '│',
     full: '▮', empty: '▯', rail: '▎', ellipsis: '…', spinner: BRAILLE, bar: ['█', '░', ['', '▏', '▎', '▍', '▌', '▋', '▊', '▉']],
-    timer: ' ', tools: (n) => ` ${n}`, agents: (n) => ` ${n}`, git: ' ',
+    timer: ' ', burst: '★', tools: (n) => ` ${n}`, agents: (n) => ` ${n}`, git: ' ',
   },
   ascii: {
     fire: '', tick: '+', cross: 'x', dot: '-', lit: '=', unlit: '-', run: '*', warn: '!', elbow: '`', next: '>', sep: '|',
     full: '#', empty: '-', rail: '|', ellipsis: '~', spinner: ['|', '/', '-', '\\'], bar: ['#', '-', ['']],
-    timer: '', tools: (n) => plural(n, 'tool'), agents: (n) => plural(n, 'agent'), git: 'git ',
+    timer: '', burst: '*', tools: (n) => plural(n, 'tool'), agents: (n) => plural(n, 'agent'), git: 'git ',
   },
 };
 // Grok's own tool names, shortened to the words people know them by. Any other name shows as sent.
@@ -158,9 +160,17 @@ function painter(depth) {
   return {
     depth,
     fg: (text, role, bold = false) => (depth && text ? `${bold ? '\u001b[1m' : ''}${sgr(ROLES[role], depth)}${text}\u001b[0m` : text),
+    hue: (text, rgb, bold = false) => (depth && text ? `${bold ? '\u001b[1m' : ''}${sgr(rgb, depth)}${text}\u001b[0m` : text),
   };
 }
 
+// The rewind look's motion: 'full' cycles the hue, 'subtle' drifts it slowly, 'off' holds one still
+// rainbow frame. Anything else is 'full'.
+function hudMotion(env = process.env) {
+  const motion = (env.LITGROK_HUD_MOTION ?? 'full').toLowerCase();
+  return motion === 'off' || motion === 'subtle' ? motion : 'full';
+}
+
 // A filled chip on the pink (the brand) or the accent (the current stage) with dark text and a space of
 // padding each side; a Nerd Font gives it rounded caps, and without colour it falls back to brackets.
 function chip(text, background, paint, nerd, open = '(', close = ')') {
@@ -474,13 +484,68 @@ function disciplineName(name, glyphs, cells = Infinity) {
   return clipCells(name, Math.min(cells, name === 'lit-scientific-visualization' ? 32 : 24), glyphs.ellipsis);
 }
 
+// The look registry: a discipline maps to one look, and every route that runs a skill goes through
+// the collector's discipline, so bare words, slash commands, skill loads and aliases all select it.
+// Grok's one line can only tint and label, so a look is a tint plus a label (the card adds the pill).
+const LOOKS = { 'lit-adhd': 'rewind', 'review-work': 'lanes' };
+function lookOf(discipline, stage = null) {
+  if (typeof discipline === 'string' && Object.hasOwn(LOOKS, discipline)) return LOOKS[discipline];
+  if (stage === 'review') return 'lanes';
+  return 'plain';
+}
+
+// review-work's six lanes. Progress is real only: the test lane follows the workflow test verdict
+// and a lane with no report stays dim, never a fake fill.
+const REVIEW_LANES = ['behavior', 'test', 'safety', 'integration', 'documentation', 'regression'];
+function laneStates(workflow) {
+  const verdict = workflow?.test?.verdict;
+  return REVIEW_LANES.map((name) => ({
+    name,
+    state: name === 'test' && (verdict === 'pass' || verdict === 'fail') ? verdict : 'unreported',
+  }));
+}
+
+// Waiting on the user: a held plan gate (the typed start-work boundary) or a live Ask tool call.
+// The next UserPromptSubmit starts a new turn, so the label stops the moment the user types.
+function waitingOf(activity) {
+  if (!activity) return null;
+  if (activity.planGate) return { reason: 'plan gate' };
+  if (activity.live?.name === 'ask_user_question') return { reason: 'question' };
+  return null;
+}
+
 // The ignition mark of the one-line row: the pink 🔥 LIT chip, then IGNITED · <discipline> 🔥 in the accent.
 // Without colour it reads 🔥 LIT IGNITED · <discipline> 🔥. A narrow row clips the discipline, never the frame.
+// While lit-adhd is the discipline the mark keeps its shape but the discipline rides a hue that turns
+// (one still rainbow frame when the HUD motion is off): the tint, never a flash.
 function ignitionSegment(discipline, glyphs, paint, nerd, options = {}) {
   const label = glyphs.fire ? `${glyphs.fire} LIT` : 'LIT';
   const brand = chip(label, 'pink', paint, nerd, '', '');
   const build = (name) => `${brand.plain} IGNITED ${glyphs.dot} ${name}${glyphs.fire ? ` ${glyphs.fire}` : ''}`;
   const frame = width(build(''));
+  const ignitionLook = options.look ?? lookOf(discipline);
+  if (ignitionLook === 'rewind') {
+    // Each cell of the mark past the brand rides its own step round the wheel (one still rainbow
+    // frame when the HUD motion is off): the tint, never a flash.
+    const motion = hudMotion();
+    const when = options.now ?? Date.now();
+    const rainbow = (text) => {
+      const cells = [...text];
+      return cells.map((cell, index) => paint.hue(cell, rewindCellRgb(when, motion, index, cells.length), true)).join('');
+    };
+    return segment(build(disciplineName(discipline, glyphs)), (text) => `${brand.painted}${rainbow(text.slice(brand.plain.length))}`, {
+      ...options, minCells: frame + 1, shrink: (cells) => build(disciplineName(discipline, glyphs, Math.max(1, cells - frame))),
+    });
+  }
+  if (ignitionLook === 'lanes') {
+    const lanes = options.lanes ?? laneStates(null);
+    const reported = lanes.filter((lane) => lane.state !== 'unreported').length;
+    const full = build(`REVIEW ${reported}/${lanes.length}`);
+    return segment(full, (text) => `${brand.painted}${paint.fg(text.slice(brand.plain.length), 'accent', true)}`, {
+      ...options, minCells: frame + 1,
+      shrink: (cells) => (cells < width(full) ? clipCells(full, Math.max(1, cells), glyphs.ellipsis) : full),
+    });
+  }
   return segment(build(disciplineName(discipline, glyphs)), (text) => `${brand.painted}${paint.fg(text.slice(brand.plain.length), 'accent', true)}`, {
     ...options, minCells: frame + 1, shrink: (cells) => build(disciplineName(discipline, glyphs, Math.max(1, cells - frame))),
   });
@@ -498,11 +563,23 @@ function figureLeads(figures, glyphs, paint, afterMark) {
 // handoff percent, cost and branch. It is the whole HUD between workflows and in LITGROK_HUD_LINES=1
 // mode. A narrow row gives up the branch, the handoff percent, the cost and the version, then clips the
 // model name and last the discipline.
-function compactRow({ status, discipline, version, glyphs, paint, nerd, handoff, maxCells }) {
+function compactRow({ status, discipline, version, glyphs, paint, nerd, handoff, maxCells, looks = null, phase = null }) {
   const [model, context, ...extras] = figureSegments(status, { glyphs, paint, handoff });
-  const figures = [model, context, ...(discipline ? [ignitionSegment(discipline, glyphs, paint, nerd, { clip: 1 })] : []), ...extras];
+  const figures = [model, context];
+  if (discipline) {
+    figures.push(looks?.look === 'lanes'
+      ? ignitionSegment(discipline, glyphs, paint, nerd, { clip: 1, lanes: looks.lanes, look: looks.look })
+      : ignitionSegment(discipline, glyphs, paint, nerd, { clip: 1 }));
+  }
+  figures.push(...extras);
   const left = [brandSegment(version, glyphs, paint, { clip: 3 }), ...figureLeads(figures, glyphs, paint, true)];
-  return layoutLine({ left, separator: { plain: ' ', painted: ' ' }, rail: { plain: '', painted: '' }, maxCells, ellipsis: glyphs.ellipsis });
+  const right = [];
+  if (looks?.waiting) right.push(segment(`YOUR TURN · ${looks.waiting.reason}`, (text) => paint.fg(text, 'yellow', true), {
+    drop: 0.6, clip: 3, minCells: width('YOUR TURN'),
+    shrink: (cells) => (cells < width(`YOUR TURN · ${looks.waiting.reason}`) ? clipCells('YOUR TURN', Math.max(1, cells), glyphs.ellipsis) : `YOUR TURN · ${looks.waiting.reason}`),
+  }));
+  if (looks?.burst) right.push(segment(`${glyphs.burst} complete${phase?.timer ? ` ${phase.timer}` : ''}`, (text) => paint.fg(text, 'pink', true), { drop: 1 }));
+  return layoutLine({ left, right, separator: { plain: ' ', painted: ' ' }, rail: { plain: '', painted: '' }, maxCells, ellipsis: glyphs.ellipsis });
 }
 
 // The current stage's label: its name, the plan's checked tasks while working, and a tick once the
@@ -584,14 +661,50 @@ function railFor(paint, glyphs) {
 // The card's title: the mark, the pink 🔥 LIT chip and the discipline, then at the right edge the turn's
 // tool calls and subagents beside its state, as the family card's corner reads (● 1m42s running,
 // ✓ complete, ⚠ a warning, idle).
-function titleLine({ discipline, version, glyphs, paint, nerd, phase, warning, activity, maxCells, rail }) {
+function titleLine({ discipline, version, glyphs, paint, nerd, phase, warning, activity, maxCells, rail, now, looks = null }) {
   const brand = chip(glyphs.fire ? `${glyphs.fire} LIT` : 'LIT', 'pink', paint, nerd);
   const name = discipline ?? 'workflow';
+  const look = looks?.look ?? lookOf(discipline);
+  const lanes = look === 'lanes' ? (looks?.lanes ?? laneStates(null)) : null;
+  const reported = lanes ? lanes.filter((lane) => lane.state !== 'unreported').length : 0;
+  // The rewind pill rides the wheel cell by cell, like the ignition mark below. The lanes pill
+  // names review-work's six lanes; a lane with a verdict takes its colour, the rest stay dim.
+  const nameText = look === 'rewind' ? `✺ REWIND ${disciplineName(name, glyphs)}`
+    : lanes ? `REVIEW ${lanes.map((lane) => lane.name).join(' · ')}` : `${glyphs.dot} ${disciplineName(name, glyphs)}`;
+  const paintLane = (laneName) => {
+    const state = lanes.find((lane) => lane.name === laneName)?.state;
+    if (state === 'pass') return paint.fg(laneName, 'green', true);
+    if (state === 'fail') return paint.fg(laneName, 'red', true);
+    return paint.fg(laneName, 'dim');
+  };
+  const namePaint = look === 'rewind'
+    ? (text) => {
+      const motion = hudMotion();
+      const when = now ?? Date.now();
+      const cells = [...text];
+      return cells.map((cell, index) => paint.hue(cell, rewindCellRgb(when, motion, index, cells.length), true)).join('');
+    }
+    : lanes
+      ? (text) => {
+        const prefix = 'REVIEW ';
+        if (!text.startsWith(prefix)) return paint.fg(text, 'accent', true);
+        const names = text.slice(prefix.length).split(' · ');
+        const painted = names.map((laneName) => (lanes.some((lane) => lane.name === laneName)
+          ? paintLane(laneName) : paint.fg(laneName, 'accent', true)));
+        return `${paint.fg(prefix, 'accent', true)}${painted.join(paint.fg(' · ', 'dim'))}`;
+      }
+      : (text) => `${paint.fg(glyphs.dot, 'dim')} ${paint.fg(text.slice(glyphs.dot.length + 1), discipline ? 'accent' : 'dim', Boolean(discipline))}`;
+  const shrinkName = lanes
+    ? (cells) => {
+      const short = `REVIEW ${reported}/${lanes.length}`;
+      return cells < width(nameText) ? clipCells(short, Math.max(1, cells), glyphs.ellipsis) : nameText;
+    }
+    : (cells) => `${glyphs.dot} ${disciplineName(name, glyphs, Math.max(1, cells - width(glyphs.dot) - 1))}`;
   const left = [
     brandSegment(version, glyphs, paint, { clip: 3 }),
     { ...segment(brand.plain, () => brand.painted), lead: ' | ', leadPainted: paint.fg(' | ', 'accent') },
-    segment(`${glyphs.dot} ${disciplineName(name, glyphs)}`, (text) => `${paint.fg(glyphs.dot, 'dim')} ${paint.fg(text.slice(glyphs.dot.length + 1), discipline ? 'accent' : 'dim', Boolean(discipline))}`, {
-      clip: 0.5, minCells: width(glyphs.dot) + 2, shrink: (cells) => `${glyphs.dot} ${disciplineName(name, glyphs, Math.max(1, cells - width(glyphs.dot) - 1))}`,
+    segment(nameText, namePaint, {
+      clip: 0.5, minCells: lanes ? width(`REVIEW ${reported}/${lanes.length}`) : width(glyphs.dot) + 2, shrink: shrinkName,
     }),
   ];
   const right = [];
@@ -600,10 +713,16 @@ function titleLine({ discipline, version, glyphs, paint, nerd, phase, warning, a
     if (phase.phase === 'running' && activity.agents > 0) parts.push(glyphs.agents(activity.agents));
     if (parts.length > 0) right.push(segment(parts.join(` ${glyphs.dot} `), (text) => paint.fg(text, 'dim'), { drop: 4 }));
   }
-  if (warning) right.push(segment(`${glyphs.warn} ${warning[1]}`, (text) => paint.fg(text, 'yellow', true), { drop: 1 }));
+  if (looks?.waiting) right.push(segment(`YOUR TURN · ${looks.waiting.reason}`, (text) => paint.fg(text, 'yellow', true), {
+    drop: 0.6, clip: 3, minCells: width('YOUR TURN'),
+    shrink: (cells) => (cells < width(`YOUR TURN · ${looks.waiting.reason}`) ? clipCells('YOUR TURN', Math.max(1, cells), glyphs.ellipsis) : `YOUR TURN · ${looks.waiting.reason}`),
+  }));
+  else if (warning) right.push(segment(`${glyphs.warn} ${warning[1]}`, (text) => paint.fg(text, 'yellow', true), { drop: 1 }));
   if (phase.phase === 'running') right.push(segment(`${glyphs.run} ${phase.timer ? `${glyphs.timer}${phase.timer}` : 'running'}`, (text) => paint.fg(text, 'accent', true), { drop: 2 }));
-  else if (phase.phase === 'complete') right.push(segment(`${glyphs.tick} complete ${phase.timer}`, (text) => paint.fg(text, 'green', true), { drop: 2 }));
-  else if (!warning) right.push(segment('idle', (text) => paint.fg(text, 'dim'), { drop: 2 }));
+  else if (phase.phase === 'complete') {
+    if (looks?.burst) right.push(segment(`${glyphs.burst} complete ${phase.timer}`, (text) => paint.fg(text, 'pink', true), { drop: 2 }));
+    else right.push(segment(`${glyphs.tick} complete ${phase.timer}`, (text) => paint.fg(text, 'green', true), { drop: 2 }));
+  } else if (!warning && !looks?.waiting) right.push(segment('idle', (text) => paint.fg(text, 'dim'), { drop: 2 }));
   return layoutLine({ left, right, separator: { plain: ' ', painted: ' ' }, rail, maxCells, ellipsis: glyphs.ellipsis });
 }
 
@@ -641,6 +760,28 @@ function detailLine({ workflow, live, warning, glyphs, paint, now, maxCells, rai
   return layoutLine({ left, right, separator: { plain: ` ${glyphs.dot} `, painted: paint.fg(` ${glyphs.dot} `, 'dim') }, rail: elbow, maxCells, ellipsis: glyphs.ellipsis });
 }
 
+// One row per other session of this workspace: `● start-work · w2B:p2 running`. The name clips first;
+// the state word stays.
+function otherSessionLine(row, { glyphs, paint, maxCells, rail }) {
+  const mark = row.state === 'running' ? glyphs.run : row.state === 'done' ? glyphs.tick : glyphs.dot;
+  const role = row.state === 'running' ? 'accent' : row.state === 'done' ? 'green' : 'dim';
+  const name = row.pane ? `${plainText(row.label, 'session')} ${glyphs.dot} ${row.pane}` : plainText(row.label, 'session');
+  const text = mark ? `${mark} ${name}` : name;
+  const lead = mark ? `${mark} ` : '';
+  return layoutLine({
+    left: [
+      segment(text, (value) => paint.fg(value, role, row.state !== 'idle'), {
+        clip: 1, minCells: width(lead) + 1, shrink: (cells) => `${lead}${clipCells(name, Math.max(1, cells - width(lead)), glyphs.ellipsis)}`,
+      }),
+      segment(row.state, (value) => paint.fg(value, role)),
+    ],
+    separator: { plain: ' ', painted: ' ' },
+    rail,
+    maxCells,
+    ellipsis: glyphs.ellipsis,
+  });
+}
+
 function figuresLine({ status, glyphs, paint, handoff, maxCells, rail }) {
   return layoutLine({
     left: figureLeads(figureSegments(status, { glyphs, paint, handoff }), glyphs, paint, false),
@@ -681,10 +822,8 @@ function render(input) {
     handoff = { active: false, percent: null };
   }
   const version = installedVersion();
-  const shared = { status: input, discipline, version, glyphs, paint, nerd, handoff, maxCells };
-  if (process.env.LITGROK_HUD_LINES === '1') return [compactRow(shared)];
-
   const now = Date.now();
+  const shared = { status: input, discipline, version, glyphs, paint, nerd, handoff, maxCells, now };
   let activity = null;
   try {
     activity = turnActivity(readLedgerTail(input), input?.prompt_id);
@@ -697,20 +836,34 @@ function render(input) {
   } catch {
     workflow = null;
   }
-  // The card shows while a discipline is active or the session has a workflow stage; otherwise the
-  // HUD is the single row.
-  if (!discipline && !workflow?.stage) return [compactRow(shared)];
   const turn = turnState(input, activity, now);
   const phase = phaseOf(now, activity, turn);
+  const looks = {
+    look: lookOf(discipline, workflow?.stage ?? null),
+    lanes: laneStates(workflow),
+    waiting: waitingOf(activity),
+    burst: phase.phase === 'complete' && workflow?.stage === 'done',
+  };
+  if (process.env.LITGROK_HUD_LINES === '1') return [compactRow({ ...shared, looks, phase })];
+  let others = [];
+  try {
+    others = readOtherSessions(statusDirs(input), input?.session_id, now);
+  } catch {
+    others = [];
+  }
+  const rail = railFor(paint, glyphs);
+  const otherLines = others.map((row) => otherSessionLine(row, { glyphs, paint, maxCells, rail }));
+  // The card shows while a discipline is active or the session has a workflow stage; otherwise the
+  // HUD is the single row, with the other sessions' rows under it.
+  if (!discipline && !workflow?.stage) return [compactRow({ ...shared, looks, phase }), ...otherLines];
   const warning = warningText(input, activity, handoff);
   const live = turn.running ? activity?.live ?? null : null;
-  const rail = railFor(paint, glyphs);
-  const lines = [titleLine({ ...shared, phase, warning, activity: phase.phase === 'idle' ? null : activity, rail })];
+  const lines = [titleLine({ ...shared, phase, warning, activity: phase.phase === 'idle' ? null : activity, rail, looks })];
   if (workflow?.stage) lines.push(mapLine(workflow, { paint, glyphs, nerd, running: turn.running, now }, rail, maxCells));
   const detail = detailLine({ workflow, live, warning, glyphs, paint, now, maxCells, rail });
   if (detail) lines.push(detail);
   lines.push(figuresLine({ ...shared, rail }));
-  return lines;
+  return [...lines, ...otherLines];
 }
 
 

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

@@ -3,14 +3,16 @@
 // Host contract (documented Stop decision control): stdout `{"decision":"block","reason"}` keeps
 // the agent working; empty stdout with exit 0 allows the stop; failures fail open. The prompt text
 // is never persisted, so the gate arms on `permissionMode === "plan"`, on the ledger's lit-plan
-// discipline marker for the turn, and on a plan file written this turn that carries zero rows. At
+// discipline marker for the turn, on a plan file written this turn that carries zero rows, and on
+// one whose todos name a folder outside the project with no `Scope roots:` line covering it. At
 // most two blocks per session; after that it passes with a stderr warning so a condition the model
 // cannot resolve never loops.
 
 import { existsSync, lstatSync, readdirSync, readFileSync, statSync } from 'node:fs';
 import { join } from 'node:path';
 
-import { countImplementationRows } from '../skills/lit-plan/scripts/scaffold-plan.mjs';
+import { countImplementationRows, planLinesOutsideFences } from '../skills/lit-plan/scripts/scaffold-plan.mjs';
+import { describeScopePath, uncoveredScopePaths } from '../skills/lit-plan/scripts/scope-roots.mjs';
 import { readLedgerRecords } from './record-passive-event.mjs';
 
 export const PLAN_GATE_SIGNAL = 'plan-gate-block';
@@ -38,7 +40,13 @@ function plansWrittenSince(workspaceRoot, since) {
     const status = statSync(path);
     if (status.size > MAX_PLAN_BYTES) continue;
     if (since !== null && status.mtimeMs < since) continue;
-    plans.push({ name: `plans/${entry.name}`, mtimeMs: status.mtimeMs, rows: countImplementationRows(readFileSync(path, 'utf8')) });
+    const text = readFileSync(path, 'utf8');
+    plans.push({
+      name: `plans/${entry.name}`,
+      mtimeMs: status.mtimeMs,
+      rows: countImplementationRows(text),
+      outside: uncoveredScopePaths(planLinesOutsideFences(text), workspaceRoot),
+    });
   }
   return plans.sort((left, right) => right.mtimeMs - left.mtimeMs);
 }
@@ -62,6 +70,8 @@ export function evaluatePlanGate({ event, workspaceRoot, sessionId, ledgerFile }
     reason = `lit-plan must persist plans/<slug>.md before finishing this planning turn: run \`node ${SCAFFOLD} <slug>\` from the project root, append column-zero \`- [ ] N. <title>\` task rows under "## Todos", then run \`node ${SCAFFOLD} --check plans/<slug>.md\`.`;
   } else if (newest && newest.rows === 0 && (planMode || since !== null)) {
     reason = `${newest.name} was written this turn but has no column-zero \`- [ ] 1. <title>\` task row; start-work cannot execute it. Append the task rows under "## Todos", then run \`node ${SCAFFOLD} --check ${newest.name}\`.`;
+  } else if (newest && newest.outside.length > 0 && (planMode || since !== null)) {
+    reason = `${newest.name} names folders outside the project that start-work would have to stop and ask for. ${newest.outside.map(describeScopePath).join(' ')} Then run \`node ${SCAFFOLD} --check ${newest.name}\`.`;
   }
   if (reason === null) return { block: false };
 

package/.grok/hooks/record-passive-event.mjs

@@ -19,6 +19,7 @@ import {
 } from 'node:fs';
 import { basename, dirname, isAbsolute, join } from 'node:path';
 import { writeHudRecords } from './litgrok-hud-state.mjs';
+import { writeLiveness } from './session-liveness.mjs';
 import { entryFromPrompt, readWorkflowState, testVerdict, updateWorkflowState, workflowStatePath } from './workflow-stage.mjs';
 
 const MAX_EVENT_BYTES = 1024 * 1024;
@@ -30,9 +31,15 @@ const KEPT_SEGMENTS = 2;
 const ROTATION_LOCK_STALE_MS = 30 * 1000;
 const TOOL_EVENTS = new Set(['PostToolUse', 'PostToolUseFailure']);
 const RECORD_SCHEMA = 'litgrok.hook-event/v1';
+const LIVENESS_BY_EVENT = Object.freeze({ PostToolUse: 'alive', PostToolUseFailure: 'alive', Stop: 'idle', SessionEnd: 'ended' });
 // A finished call by one of these tools cannot have changed a plan file, so it skips the plan reread.
 const READ_ONLY_TOOLS = /^(?:read_file|grep|list_dir|glob|todo_write|web_search|web_fetch|read|ls)$/iu;
-const HUD_DISCIPLINE_PATTERN = /(?:^|[\s/])(lit-scientific-visualization|lit-handoff|lit-brainstorm|autoconference|autoresearch|lit-plan|litwork|lit)(?=$|[^\w-])/iu;
+const HUD_DISCIPLINE_PATTERN = /(?:^|[\s/])(lit-scientific-visualization|lit-handoff|lit-brainstorm|lit-adhd|lit-rewind|autoconference|autoresearch|lit-plan|litwork|review-work|lit)(?=$|[^\w-])/iu;
+// The skill also runs from bare words, the rule and the catalog, where no prompt names it. Its
+// collector starting is the run, so that call switches the card to the rewind look. The command
+// text is only inspected, never stored: the ledger keeps the tool name alone.
+const ADHD_COLLECTOR_SCRIPT = /lit-adhd\/scripts\/rewind\.mjs/u;
+const ADHD_COLLECTOR_RUN = /(?:^|[\s"'])(?:--brief|--json)(?:$|[\s"'=])/u;
 
 function maskCode(text) {
   return text.replace(/[^\r\n]/gu, '\u0000');
@@ -69,9 +76,13 @@ function maskInlineCode(text) {
   return output + text.slice(cursor);
 }
 
+// A message relayed from another session is quoted data, never this user's route; an unclosed
+// block runs to the end of the prompt.
+const CROSS_SESSION_BLOCK = /<cross-session-message\b[^>]*>[\s\S]*?(?:<\/cross-session-message>|$)/gu;
+
 function visiblePromptText(prompt) {
   let fence = null;
-  const lines = prompt.match(/[^\n]*\n|[^\n]+$/gu) ?? [];
+  const lines = prompt.replace(CROSS_SESSION_BLOCK, ' ').match(/[^\n]*\n|[^\n]+$/gu) ?? [];
   const withoutFences = lines.map((line) => {
     if (fence !== null) {
       const close = line.match(/^[\t ]{0,3}(`+|~+)[\t ]*(?:\r?\n)?$/u)?.[1];
@@ -93,7 +104,9 @@ function hudDisciplineFromPrompt(prompt) {
   const match = HUD_DISCIPLINE_PATTERN.exec(visiblePromptText(prompt));
   if (!match) return null;
   const token = match[1].toLowerCase();
-  return token === 'lit' ? 'litwork' : token;
+  if (token === 'lit') return 'litwork';
+  if (token === 'lit-rewind') return 'lit-adhd';
+  return token;
 }
 
 class RecorderError extends Error {
@@ -431,7 +444,8 @@ export async function recordPassiveEvent(expectedEvent) {
     const tool = toolRecord(event, expectedEvent);
     if (tool) record.tool = tool;
     if (typeof event.promptId === 'string') record.promptId = event.promptId;
-    const entry = expectedEvent === 'UserPromptSubmit' && typeof event.prompt === 'string' ? entryFromPrompt(visiblePromptText(event.prompt)) : null;
+    const visiblePrompt = expectedEvent === 'UserPromptSubmit' && typeof event.prompt === 'string' ? visiblePromptText(event.prompt) : null;
+    const entry = visiblePrompt === null ? null : entryFromPrompt(visiblePrompt);
     const ledgerFile = environment.sessionId === null ? null : ledgerPath(environment.realWorkspaceRoot, environment.sessionId);
     // A bare `lit` continues the discipline the last explicit switch selected, and with it that discipline's gate.
     const continued = entry?.entry === 'continue' && ledgerFile !== null
@@ -439,12 +453,24 @@ export async function recordPassiveEvent(expectedEvent) {
       : null;
     const selected = entry === null || entry.entry === 'continue' ? undefined
       : entry.discipline === 'lit-brainstorm' ? 'lit-brainstorm' : entry.stage === 'plan' ? 'lit-plan' : null;
-    const discipline = expectedEvent === 'UserPromptSubmit' && typeof event.prompt === 'string'
-      && (/(?:^|[\s/])lit-plan(?:$|[^\w-])/iu.test(event.prompt) || entry?.discipline === 'lit-plan' || continued === 'lit-plan') ? 'lit-plan' : null;
+    const discipline = visiblePrompt !== null
+      && (/(?:^|[\s/])lit-plan(?:$|[^\w-])/iu.test(visiblePrompt) || entry?.discipline === 'lit-plan' || continued === 'lit-plan') ? 'lit-plan' : null;
     let hudDiscipline = null;
     if (expectedEvent === 'UserPromptSubmit') {
       hudDiscipline = continued ?? (entry?.discipline !== undefined ? entry.discipline : hudDisciplineFromPrompt(event.prompt));
     }
+    if (expectedEvent === 'PreToolUse') {
+      const command = event?.toolInput?.command ?? event?.toolInput?.cmd;
+      if (typeof command === 'string' && ADHD_COLLECTOR_SCRIPT.test(command) && ADHD_COLLECTOR_RUN.test(command)) {
+        writeHudRecords({
+          env: process.env,
+          sessionId: environment.sessionId,
+          cwd: environment.eventCwd,
+          workspaceRoot: environment.realWorkspaceRoot,
+          discipline: 'lit-adhd',
+        });
+      }
+    }
     if (discipline !== null) record.discipline = discipline;
     if (entry?.stage && continued !== 'lit-brainstorm') record.stage = entry.stage;
     // Only the verdict and one count of a test run are kept, never the command or its output.
@@ -454,6 +480,14 @@ export async function recordPassiveEvent(expectedEvent) {
     if (ledgerFile !== null) {
       appendRecord(ledgerFile, record);
       await noteWorkflow(ledgerFile, environment, expectedEvent, record, entry?.entry, selected);
+      // Liveness is best effort: a refused or failed write never changes this hook's output.
+      if (Object.hasOwn(LIVENESS_BY_EVENT, expectedEvent)) {
+        try {
+          writeLiveness({ ledgerFile, sessionId: environment.sessionId, cwd: environment.eventCwd, state: LIVENESS_BY_EVENT[expectedEvent] });
+        } catch {
+          // The ledger record above is the durable trace.
+        }
+      }
     }
     if (expectedEvent === 'UserPromptSubmit') {
       writeHudRecords({

package/.grok/hooks/session-end.json

@@ -0,0 +1,15 @@
+{
+  "hooks": {
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "session-end.mjs",
+            "timeout": 5
+          }
+        ]
+      }
+    ]
+  }
+}

package/.grok/hooks/session-end.mjs

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+
+// No end-reason field is documented, so this records only the session end and marks its liveness `ended`.
+import { recordPassiveEvent } from './record-passive-event.mjs';
+
+await recordPassiveEvent('SessionEnd');

package/.grok/hooks/session-liveness.mjs

@@ -0,0 +1,102 @@
+// Liveness: one small record per session under `.grok/litgrok/liveness/<key>.json`, so the status line
+// and lit-adhd can tell a session that is working (`alive`, from PostToolUse and its failure hook)
+// from one waiting at a turn end (`idle`, from Stop) and one that is gone (`ended`, from SessionEnd).
+// A session that dies without SessionEnd leaves its last record behind; a reader treats a record older
+// than fifteen minutes as ended. The herdr pane id is kept only when it is a plain short token.
+
+import { randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { basename, dirname, join } from 'node:path';
+
+export const LIVENESS_REPEAT_MS = 30 * 1000;
+export const LIVENESS_STALE_MS = 15 * 60 * 1000;
+const LIVENESS_STATES = new Set(['alive', 'idle', 'ended']);
+const MAX_RECORD_BYTES = 4096;
+const PANE_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,63}$/u;
+
+function livenessError(code) {
+  const error = new Error(code);
+  error.code = code;
+  return error;
+}
+
+// `.grok/litgrok/session-ledger/<key>.jsonl` -> `.grok/litgrok/liveness/<key>.json`.
+export function livenessPath(ledgerFile) {
+  return join(dirname(dirname(ledgerFile)), 'liveness', basename(ledgerFile).replace(/\.jsonl$/u, '.json'));
+}
+
+function ensureLivenessDirectory(path) {
+  try {
+    mkdirSync(path, { mode: 0o700 });
+  } catch (error) {
+    if (error?.code !== 'EEXIST') throw error;
+  }
+  const status = lstatSync(path);
+  if (!status.isDirectory() || status.isSymbolicLink()) throw livenessError('LIVENESS_DIRECTORY_UNSAFE');
+}
+
+export function paneIdFrom(env) {
+  const value = env?.HERDR_PANE_ID;
+  return typeof value === 'string' && PANE_ID.test(value) ? value : null;
+}
+
+function validRecord(record) {
+  return record !== null && typeof record === 'object' && !Array.isArray(record)
+    && typeof record.sessionId === 'string' && record.sessionId.length > 0 && record.sessionId.length <= 512
+    && typeof record.cwd === 'string'
+    && LIVENESS_STATES.has(record.state)
+    && (record.pane === null || (typeof record.pane === 'string' && PANE_ID.test(record.pane)))
+    && typeof record.at === 'string' && Number.isFinite(Date.parse(record.at));
+}
+
+function readRaw(path) {
+  try {
+    const status = lstatSync(path);
+    if (!status.isFile() || status.isSymbolicLink() || status.size > MAX_RECORD_BYTES) return null;
+    const record = JSON.parse(readFileSync(path, 'utf8'));
+    return validRecord(record) ? record : null;
+  } catch {
+    return null;
+  }
+}
+
+/** The record at `path`, with `state: 'ended'` once it is older than fifteen minutes, or null. */
+export function readLiveness(path, now = Date.now()) {
+  const record = readRaw(path);
+  if (record === null) return null;
+  return now - Date.parse(record.at) > LIVENESS_STALE_MS ? { ...record, state: 'ended' } : record;
+}
+
+/**
+ * Writes this session's state. Returns `'unchanged'` when the same state and pane were written less
+ * than thirty seconds ago, `'written'` otherwise. Refuses a target that is not a regular file.
+ */
+export function writeLiveness({ ledgerFile, sessionId, cwd, state, env = process.env, now = Date.now() }) {
+  if (!LIVENESS_STATES.has(state)) throw livenessError('LIVENESS_STATE_INVALID');
+  const target = livenessPath(ledgerFile);
+  ensureLivenessDirectory(dirname(target));
+  try {
+    const existing = lstatSync(target);
+    if (!existing.isFile() || existing.isSymbolicLink()) throw livenessError('LIVENESS_RECORD_UNSAFE');
+  } catch (error) {
+    if (error?.code !== 'ENOENT') throw error;
+  }
+  const record = { sessionId, cwd, state, pane: paneIdFrom(env), at: new Date(now).toISOString() };
+  if (!validRecord(record)) throw livenessError('LIVENESS_RECORD_INVALID');
+  const previous = readRaw(target);
+  if (previous && previous.state === state && previous.pane === record.pane && now - Date.parse(previous.at) < LIVENESS_REPEAT_MS) {
+    return 'unchanged';
+  }
+  const temporary = join(dirname(target), `.liveness-${randomUUID()}.tmp`);
+  try {
+    writeFileSync(temporary, `${JSON.stringify(record)}\n`, { flag: 'wx', mode: 0o600 });
+    renameSync(temporary, target);
+  } finally {
+    try {
+      unlinkSync(temporary);
+    } catch (error) {
+      if (error?.code !== 'ENOENT') throw error;
+    }
+  }
+  return 'written';
+}