@litfamily/litgrok 1.0.27 → 1.0.29

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

@@ -7,6 +7,7 @@ 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;
@@ -759,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),
@@ -822,18 +845,25 @@ function render(input) {
     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.
-  if (!discipline && !workflow?.stage) return [compactRow({ ...shared, looks, phase })];
+  // 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, 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,6 +31,7 @@ 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|lit-adhd|lit-rewind|autoconference|autoresearch|lit-plan|litwork|review-work|lit)(?=$|[^\w-])/iu;
@@ -74,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];
@@ -438,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
@@ -446,8 +453,8 @@ 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));
@@ -473,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';
+}

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

@@ -0,0 +1,57 @@
+// The other sessions of this workspace, for the status line's extra rows. Each comes from that
+// session's liveness record and, when it has one, its workflow snapshot; this session's own files are
+// skipped. A session that is working reads `running`, one waiting at a turn end `idle`, and a finished
+// start-work (its work stage closed with every plan task checked, or the done stage) `done` for one
+// minute, then it leaves. An ended or stale session is not shown. Nothing here writes.
+
+import { createHash } from 'node:crypto';
+import { readdirSync, realpathSync } from 'node:fs';
+import { isAbsolute, join } from 'node:path';
+import { readLiveness } from './session-liveness.mjs';
+import { readWorkflowState } from './workflow-stage.mjs';
+
+export const DONE_SHOWN_MS = 60 * 1000;
+const MAX_ROWS = 4;
+const STATE_ORDER = { running: 0, idle: 1, done: 2 };
+const RECORD_NAME = /^[0-9a-f]{32}\.json$/u;
+
+const keyOf = (sessionId) => createHash('sha256').update(sessionId).digest('hex').slice(0, 32);
+
+function finished(workflow) {
+  return workflow.stage === 'done'
+    || (workflow.ended && workflow.stage === 'work' && workflow.plan?.total > 0 && workflow.plan.done === workflow.plan.total);
+}
+
+/** Up to four `{ label, pane, state }` rows, running first, then idle, then done; newest first within each. */
+export function readOtherSessions(dirs, selfSessionId, now = Date.now()) {
+  const selfName = typeof selfSessionId === 'string' && selfSessionId !== '' ? `${keyOf(selfSessionId)}.json` : null;
+  for (const directory of dirs) {
+    if (typeof directory !== 'string' || !isAbsolute(directory)) continue;
+    let root;
+    let names;
+    try {
+      root = realpathSync(directory);
+      names = readdirSync(join(root, '.grok', 'litgrok', 'liveness'));
+    } catch {
+      continue;
+    }
+    const rows = [];
+    for (const name of names) {
+      if (!RECORD_NAME.test(name) || name === selfName) continue;
+      const live = readLiveness(join(root, '.grok', 'litgrok', 'liveness', name), now);
+      if (!live || `${keyOf(live.sessionId)}.json` !== name) continue;
+      const workflow = readWorkflowState(join(root, '.grok', 'litgrok', 'session-ledger', name.replace(/\.json$/u, '.workflow.json')), live.sessionId);
+      let state;
+      if (workflow && finished(workflow)) {
+        if (now - Date.parse(workflow.updatedAt) > DONE_SHOWN_MS) continue;
+        state = 'done';
+      } else if (live.state === 'alive') state = 'running';
+      else if (live.state === 'idle') state = 'idle';
+      else continue;
+      rows.push({ label: workflow?.active ?? workflow?.stage ?? 'session', pane: live.pane, state, at: Date.parse(live.at) });
+    }
+    rows.sort((left, right) => STATE_ORDER[left.state] - STATE_ORDER[right.state] || right.at - left.at);
+    return rows.slice(0, MAX_ROWS).map(({ at: _at, ...row }) => row);
+  }
+  return [];
+}

package/.grok/rules/00-litgrok.md

@@ -102,6 +102,7 @@ Judge by this session's own state (earlier banner, plan file, workflow row), nev
 - A named discipline (`lit plan`, `lit-plan`, `start-work`, `review-work`, `lit review plan|work`) switches: ignite it once, in full.
 - `lit brainstorm|brainstorming|ideation|ideate|idea|ideas …` opens `lit-brainstorm` (options only, no edits), never deep-interview, lit-plan or the Office and film routes.
 - An approved plan or an active start-work plus a bare `lit` resumes that work; write no second plan.
+- A bare `go` within 30 minutes (plan mtime) of saving a plan here loads start-work on it.
 - `lit new …` and `lit restart …` start fresh with the full activation.
 - A bare `lit` with nothing active asks one question to confirm; `lit fix X` never does.
 

package/.grok/skills/lit-adhd/SKILL.md

@@ -48,10 +48,11 @@ node <SKILL_ROOT>/scripts/rewind.mjs --brief --lang <ko|en>
 2. The brief is the result:
 
 - a one-line headline: how many sessions, how many wait on you, how many are active, and the next step in plain words;
-- one card per live session grouped by worktree and branch (status badge, goal, a real gauge or the known facts, done, next);
-- ended sessions, one table row each, newest first;
-- a roadmap timeline (done ✓ with dates, now ▶, later ○);
-- **one recommended next step** in a box, with the word to type (`go`), then one line: "Type `go` to continue." When nothing can run on `go`, the box still recommends a real step from the records (a session waiting on the user, an open plan item, the latest active session, the latest ended one) and says that nothing runs on its own.
+- a three-line opener: **Done so far** (finished plans, commits, sessions that ended through SessionEnd), **Doing now** (waiting, active and idle counts) and **Next** (the same one step as the box);
+- one card per live, idle or waiting session grouped by worktree and branch (status badge, goal, a real gauge or the known facts, done, next);
+- done and ended sessions, one table row each, newest first, a done one marked ✓;
+- a roadmap timeline (commits ✓ with dates, finished plans ✓ done, now ▶, later ○);
+- **one recommended next step** in a box (an untagged fence), with the word to type (`go`), then one line: "Type `go` to continue." When nothing can run on `go`, the box still recommends a real step from the records (a session waiting on the user, an open plan item, the first `## Next` item of this worktree's HANDOFF.md that no checked plan row or commit already did, the latest active session, the latest ended one) and says that nothing runs on its own. A step that is already checked or committed is never offered again.
 
 **Progress gauges, required.** A gauge appears only when both numbers are real, in the form `[▉▉▉░░] 3/5` (filled `▉` done, light `░` remaining, then done/total). An unknown total has no gauge: the card states what is known in words instead. Never a question-mark gauge, never a guess, never an estimate, never a gauge of your own.
 
@@ -92,23 +93,26 @@ The collector (`scripts/lib/collect.mjs`, served as `scripts/rewind.mjs`) reads,
 | Source | What it gives | Missing reads |
 | --- | --- | --- |
 | Grok Build session records, `~/.grok/sessions/<encoded cwd>/<session-id>/` | per session: title, first and last ask, tools used, last assistant text, status | `transcripts: unknown` |
-| `plans/*.md` checkbox rows | open plans, current item, done/total, remaining names | `plans: unknown` |
-| `.handoff/HANDOFF.md`, else root `HANDOFF.md` | headings from the first 40 lines only | `handoffs: unknown` |
+| `plans/*.md` checkbox rows changed inside the window | open and finished plans, current item, done/total, remaining names; plans outside the window or past the read budget are counted as skipped | `plans: unknown` |
+| `.handoff/HANDOFF.md`, else root `HANDOFF.md` | headings from the first 40 lines, and for this worktree the items under `## Next` | `handoffs: unknown` |
+| `.grok/litgrok/liveness/<key>.json`, written by LitGrok's hooks | whether a session is working, waiting at a turn end, or ended through SessionEnd | the transcript's own status stands |
 | `git log --since` | commits in the window, matched to sessions by time and branch | `git: unknown` |
 | `herdr agent list` (only when `HERDR_ENV=1`) | agent panes | `herdr: unknown` |
 
-Session files are read head (64 KiB) and tail (256 KiB) only, under one 8 MiB budget for the whole run, through descriptors opened without following links. The store format is private and may move, so every field is read defensively and anything missing reads as unknown. Only the session's own project folder is ever listed: the store is never scanned blindly. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
+Plans and handoffs are read first, so a run whose transcripts spend the budget still shows what is left. Session files are read head (64 KiB) and tail (256 KiB) only, under one 8 MiB budget for the whole run, through descriptors opened without following links. The store format is private and may move, so every field is read defensively and anything missing reads as unknown. Only the session's own project folder is ever listed: the store is never scanned blindly. Every string is redacted before it leaves the collector: credential shapes, `NAME=value` with a secret-like name, URI userinfo, any current environment value of eight or more characters, and the home directory (shown as `~`).
 
 Grok Build keeps no litgoal ledger, workflow stack or start-work state file, so those sources stay `unknown` and the offered next step degrades to plans. A paused workflow or a start-work boundary shows in the waiting reason only when the transcript itself says so.
 
 ## Status taxonomy
 
 - `waiting-on-user`: the session's last word was the assistant asking something (a closing `?`, `lit approve`, `확인해 주세요`, `할까요`…).
-- `active`: written to within the last 15 minutes and not waiting.
-- `ended`: quiet for longer than that.
+- `active`: written to within the last 15 minutes and not waiting, or a liveness record under 15 minutes old says it is working.
+- `idle`: a liveness record under 15 minutes old says it stopped at a turn end and asked nothing.
+- `done`: its liveness record says it ended through SessionEnd, at any age.
+- `ended`: quiet for longer than 15 minutes, with no SessionEnd record.
 - `unknown`: the records held no timestamp.
 
-Sessions waiting on the user come first, then active ones, newest first.
+Sessions waiting on the user come first, then active, idle, done and ended ones, newest first.
 
 ## The next step
 

package/.grok/skills/lit-adhd/references/card-examples.md

@@ -10,18 +10,23 @@ words change with the language.
 
 1. **Headline** (`## 🧭 …`): how many sessions, how many wait on you, how many are active, and the
    next step in plain words.
-2. **One card per live session** (waiting or active), under a `### 🌿 branch · worktree` group:
-   - badge: 🟠 waiting on you, 🟢 active, ⚪ ended, ⚫ unknown, with the reason it waits;
+2. **Opener**, three lines: **Done so far** (finished plans, commits, sessions done), **Doing now**
+   (waiting, active and idle counts), **Next** (the one step the box recommends).
+3. **One card per live session** (waiting, active or idle), under a `### 🌿 branch · worktree` group:
+   - badge: 🟠 waiting on you, 🟢 active, 🔵 idle, ⚫ unknown, with the reason it waits;
    - the goal in bold, from the session's title or its first ask;
    - a gauge only when both numbers are recorded (a session backed by a plan shows its plan's
      gauge), otherwise the known facts after ⏳ (how long it ran and its last ask), never a
      question-mark gauge;
    - ✅ what was done (edited files, commits, or the tools used before any edit) and ▶ what is next
      for that session, or what it is doing now.
-3. **Ended sessions**, one table row each.
-4. **Roadmap** timeline: ✓ finished commits with their dates, ▶ the current item of each open plan
-   with its gauge, ○ the items after it.
-5. **One recommended next step** in a box, and the word to type.
+4. **Done and ended sessions**, one table row each; a session that ended through SessionEnd is done
+   and its id is marked ✓.
+5. **Roadmap** timeline: ✓ finished commits with their dates, ✓ finished plans, ▶ the current item of
+   each open plan with its gauge, ○ the items after it.
+6. **One recommended next step** in a box (an untagged fence), and the word to type. A step that a
+   checked plan row or a commit already did is never offered; with no open plan, the first remaining
+   item under this worktree's HANDOFF.md `## Next` is the fallback.
 
 ## English
 
@@ -29,6 +34,10 @@ words change with the language.
 ## 🧭 3 sessions · 1 waits on you · 1 active · next: Answer sess-wai in proj: “Which window should I start with?”
 *last 30d · 1 worktree*
 
+**Done so far:** 1 commit
+**Doing now:** 1 waits on you · 1 active
+**Next:** Answer sess-wai in proj: “Which window should I start with?”
+
 ### 🌿 `unknown` · proj
 
 > 🟠 **WAITING ON YOU** (it asked you something) · `sess-wai` · just now  
@@ -55,7 +64,7 @@ words change with the language.
 - ▶ **now** · `plans/brief.md` `[▉░░] 1/3` → 1. Collect records
   - ○ later · 2. Draw brief
 
-```text
+```
 ╭─ RECOMMENDED NEXT STEP ──────────────────────────────────────╮
 │ Answer sess-wai in proj: “Which window should I start with?” │
 ╰──────────────────────────────────────────────────────────────╯
@@ -72,6 +81,10 @@ Type **`go`** to continue.
 ## 🧭 세션 3개 · 나를 기다리는 것 1 · 진행 중 1 · 다음: proj의 sess-wai에 답하기: “Which window should I start with?”
 *최근 30d · 워크트리 1개*
 
+**지금까지 한 일:** 커밋 1개
+**지금 하는 일:** 나를 기다리는 것 1 · 진행 중 1
+**다음:** proj의 sess-wai에 답하기: “Which window should I start with?”
+
 ### 🌿 `unknown` · proj
 
 > 🟠 **나를 기다림** (질문에 답을 기다림) · `sess-wai` · 방금  
@@ -98,7 +111,7 @@ Type **`go`** to continue.
 - ▶ **지금** · `plans/brief.md` `[▉░░] 1/3` → 1. Collect records
   - ○ 이후 · 2. Draw brief
 
-```text
+```
 ╭─ 추천하는 다음 단계 ──────────────────────────────────────────╮
 │ proj의 sess-wai에 답하기: “Which window should I start with?” │
 ╰───────────────────────────────────────────────────────────────╯

package/.grok/skills/lit-adhd/references/status-taxonomy.md

@@ -1,19 +1,33 @@
 # lit-adhd status taxonomy
 
 The collector assigns every session exactly one status. The brief renders it in the user's language
-with the words below and never invents a fifth.
+with the words below and never invents a seventh.
 
 | Status | Set when | English | 한국어 |
 | --- | --- | --- | --- |
 | `waiting-on-user` | The session's last word was the assistant asking something (a closing `?`, `lit approve`, `확인해 주세요`, `할까요`…) | waiting on you | 나를 기다림 |
-| `active` | Written to within the last 15 minutes and not waiting | active | 진행 중 |
-| `ended` | Quiet for longer than 15 minutes | ended | 끝남 |
+| `active` | Written to within the last 15 minutes and not waiting, or a liveness record under 15 minutes old says `alive` | active | 진행 중 |
+| `idle` | A liveness record under 15 minutes old says `idle` (a turn ended) and the session asked nothing | idle | 쉬는 중 |
+| `done` | Its liveness record says `ended` (written by the SessionEnd hook), at any age | done | 마침 |
+| `ended` | Quiet for longer than 15 minutes, with no SessionEnd record | ended | 끝남 |
 | `unknown` | The records held no timestamp | unknown | 모름 |
 
+Liveness records live at `.grok/litgrok/liveness/<key>.json`, where `<key>` is the first 32 hex digits of
+the SHA-256 of the session id. A question the session asked still wins over any liveness record.
+
 `waitingReason` says why a session waits (`asked the user`); name it in the card's status cell when
 present: `waiting on you (asked the user)` / `나를 기다림 (질문에 답을 기다림)`.
 
-Order in the brief: waiting sessions first, then active, ended and unknown; newest first inside each group.
+Order in the brief: waiting sessions first, then active, idle, done, ended and unknown; newest first
+inside each group. Waiting, active and idle sessions get cards; done and ended ones share the history
+table, a done row marked ✓.
+
+## Plans
+
+A plan counts when its file changed inside the window; this worktree's plans are held to the window
+too. A plan with every row checked stays in the roadmap as finished (`complete: true`, no current item)
+and is counted in `roadmap.plansDone`. A plan outside the window, or one the read budget could not cover,
+is not read and is counted in `roadmap.plansSkipped`; the brief's last line says how many.
 
 ## Sources