@litfamily/litmuse 0.1.2 → 0.1.3

package/plugin/hooks/session-start.mjs

@@ -4,6 +4,8 @@ import { homedir } from 'node:os';
 import { run, emitContext, PLUGIN_ROOT, pluginVersion, cachedLatest, newerThan, readSession, sessionPath, workspaceOf } from './lib/common.mjs';
 import { SKILL_ROUTES } from './lib/routes.mjs';
 import { readFreshSnapshot } from './lib/handoff-snapshot.mjs';
+import { resolveProjectStateRoot } from './lib/workflow-stack.mjs';
+import { recordLoadedVersion } from './lib/stage.mjs';
 
 const STDOUT_BUDGET = 15 * 1024;
 const STYLE_FILES = { eli5: 'style-eli5.md', 'asd-ste100': 'style-asd-ste100.md' };
@@ -53,7 +55,7 @@ function suggestAdhdOnce(payload) {
     const cwd = workspaceOf(payload);
     const rec = readSession(payload);
     if (rec && rec.route) return null;
-    const dir = join(cwd, '.litmuse', 'workflow-stack');
+    const dir = join(resolveProjectStateRoot(cwd), '.litmuse', 'workflow-stack');
     const day = 24 * 60 * 60 * 1000;
     const fresh = readdirSync(dir).some((name) => name.endsWith('.json') && Date.now() - statSync(join(dir, name)).mtimeMs <= day);
     if (!fresh) return null;
@@ -81,6 +83,7 @@ function fenced(text, room) {
 
 run((payload) => {
   const version = pluginVersion();
+  recordLoadedVersion(payload, version);
   const base = readFileSync(join(PLUGIN_ROOT, 'context', 'session.md'), 'utf8').replaceAll('{{version}}', version);
   const routes = SKILL_ROUTES.map((r) => `- ${r.id}: ${r.when}`).join('\n');
   const parts = [base.trim(), `LitMuse routes (skill id: use when)\n${routes}`];

package/plugin/hooks/stop.mjs

@@ -3,16 +3,31 @@ import { join } from 'node:path';
 import { run, block, activeRoute, writeSession, workspaceOf } from './lib/common.mjs';
 import { continuationHold } from './lib/continuation.mjs';
 import { MOTION_ROUTE, evaluateMotionStop } from './lib/motion.mjs';
+import { putNextStep } from './lib/next-step.mjs';
+import { markLiveness } from './lib/stage.mjs';
 
+// The newest plan written since the route started, as `plans/<name>.md`, or null.
 function planWrittenSince(cwd, since) {
   const dir = join(cwd, 'plans');
-  if (!existsSync(dir)) return false;
-  return readdirSync(dir).some((f) => f.endsWith('.md') && statSync(join(dir, f)).mtimeMs >= since);
+  if (!existsSync(dir)) return null;
+  let best = null;
+  for (const f of readdirSync(dir)) {
+    if (!f.endsWith('.md')) continue;
+    let mtime;
+    try {
+      mtime = statSync(join(dir, f)).mtimeMs;
+    } catch {
+      continue; // removed since the listing
+    }
+    if (mtime >= since && (!best || mtime > best.mtime)) best = { name: `plans/${f}`, mtime };
+  }
+  return best?.name ?? null;
 }
 
 // The lit-plan gate holds a turn at most once, so a model that cannot write the plan still ends. The motion gate holds
 // at most twice, then asks the reply to say the render is not done.
 run((payload) => {
+  markLiveness(payload, 'idle');
   const state = activeRoute(payload);
   if (!state) return;
   if (state.route === MOTION_ROUTE) {
@@ -24,8 +39,13 @@ run((payload) => {
     return;
   }
   const turn = payload.turn_id ?? state.turnId ?? 'turn';
+  const saved = planWrittenSince(workspaceOf(payload), state.activatedAt ?? 0);
+  // A saved plan arms a one-word `go` for this session; the skill's closing line says so.
+  if (saved) {
+    putNextStep(payload, saved);
+    return;
+  }
   if (state.stopHeldFor === turn) return;
-  if (planWrittenSince(workspaceOf(payload), state.activatedAt ?? 0)) return;
   writeSession(payload, { ...state, stopHeldFor: turn });
   block('LitMuse lit-plan gate: this planning turn has no plan file yet. Write the plan to plans/<slug>.md (task rows as "- [ ] N. <title>"), then end the turn and point the user to /start-work.');
 });

package/plugin/hooks/user-prompt-submit.mjs

@@ -164,7 +164,7 @@ run((payload) => {
       stackStart(payload, 'start-work', { plan }, false);
       recordRoute(payload, { route: 'start-work', keyword: 'go', kind: 'ignite', plan, activatedAt: Date.now() });
       emitContext('UserPromptSubmit', [
-        ...activation({ route: 'start-work', keyword: 'go', bare: false, resume: false, restart: false, trailing: false }, payload),
+        activation({ route: 'start-work', keyword: 'go', bare: false, resume: false, restart: false, trailing: false }, payload),
         `Plan: ${plan}. The typed go is the approval: the work starts without a separate approval turn; work through its open rows in order.`,
       ].join('\n'));
       return;

package/plugin/lib/rewind/collect.mjs

@@ -6,7 +6,7 @@
 import { execFileSync } from 'node:child_process';
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, readdirSync, existsSync } from 'node:fs';
 import { homedir } from 'node:os';
-import { basename, dirname, join, resolve } from 'node:path';
+import { basename, join, resolve } from 'node:path';
 
 import { parsePlanTaskRows } from '../plan-task-rows.mjs';
 import { PULSE_UNKNOWN, aggregateProgress, clipToWidth, displayWidth, progressOf } from './gauge.mjs';
@@ -14,6 +14,8 @@ import { chooseNextStep, writeNextStep } from './next-step.mjs';
 import { makeRedactor } from './redact.mjs';
 import { findTranscripts, makeBudget, readTranscriptLines, sessionRecord } from './transcripts.mjs';
 import { rainbowLine } from '../../../lib/stage-card.mjs';
+import { projectKey, resolveProjectStateRoot } from '../../hooks/lib/workflow-stack.mjs';
+import { readLiveness } from '../../hooks/lib/stage.mjs';
 
 const SMALL_FILE_BYTES = 1024 * 1024;
 const HERDR_TIMEOUT_MS = 2000;
@@ -67,18 +69,6 @@ const entries = (directory) => {
 
 const defaultExec = (file, args, options) => execFileSync(file, args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'], ...options });
 
-const outermostRoot = (startDir) => {
-  const start = resolve(startDir);
-  let root = null;
-  let current = start;
-  for (;;) {
-    if (existsSync(join(current, '.git'))) root = current;
-    const parent = dirname(current);
-    if (parent === current) return root ?? start;
-    current = parent;
-  }
-};
-
 const worktreesOf = (cwd, exec) => {
   try {
     const out = exec('git', ['worktree', 'list', '--porcelain'], { cwd, timeout: GIT_TIMEOUT_MS });
@@ -99,24 +89,37 @@ const mtimeOf = (path) => {
   }
 };
 
-const plansIn = (root, budget, redact, local) => {
+// Every plan with real rows, finished ones included (a finished plan is done work, not a missing
+// one). A plan the read budget can no longer cover whole is counted in `skipped`, never half-read.
+const plansIn = (root, budget, redact, local, skipped) => {
   const list = entries(join(root, 'plans'));
   if (!list) return null;
   return list.filter((entry) => entry.isFile() && entry.name.endsWith('.md')).sort((a, b) => a.name.localeCompare(b.name)).flatMap((entry) => {
-    const text = readSmallFile(join(root, 'plans', entry.name), budget);
+    const path = join(root, 'plans', entry.name);
+    let size = 0;
+    try {
+      size = lstatSync(path).size;
+    } catch {
+      return [];
+    }
+    if (budget.limit - budget.used < Math.min(size, SMALL_FILE_BYTES)) {
+      budget.exhausted = true;
+      skipped.count += 1;
+      return [];
+    }
+    const text = readSmallFile(path, budget);
     if (text === null) return [];
     const rows = parsePlanTaskRows(text);
     if (!rows.length || isTemplate(rows)) return [];
     const open = rows.filter((row) => !row.checked);
-    if (!open.length) return [];
     const done = rows.length - open.length;
     return [{
       worktree: redact(root),
       plan: `plans/${entry.name}`,
       local,
-      changedMs: mtimeOf(join(root, 'plans', entry.name)),
+      changedMs: mtimeOf(path),
       rows: rows.map((row) => ({ checked: row.checked, title: clipToWidth(redact(row.text), NAME_MAX) })),
-      current: clipToWidth(redact(open[0].text), NAME_MAX),
+      current: open.length ? clipToWidth(redact(open[0].text), NAME_MAX) : null,
       progress: progressOf(done, rows.length, open.map((row) => clipToWidth(redact(row.text), NAME_MAX))),
     }];
   });
@@ -141,7 +144,21 @@ const goalsOf = (root, budget, redact) => {
   });
 };
 
-const handoffsOf = (root, budget, redact) => {
+// The first item under a `## Next` or `## Next Steps` heading, list marker removed, or null.
+const nextItemOf = (text) => {
+  const lines = text.split('\n');
+  const at = lines.findIndex((line) => /^#{1,3} Next(?: Steps)?\s*$/iu.test(line.trim()));
+  if (at < 0) return null;
+  for (const line of lines.slice(at + 1)) {
+    if (/^#{1,6} /u.test(line)) return null;
+    const item = line.replace(/^\s*(?:[-*+]|\d+[.)])\s+/u, '').trim();
+    if (item) return item;
+  }
+  return null;
+};
+
+// Handoff headings from the first 40 lines; for this worktree's own files only, the Next item too.
+const handoffsOf = (root, budget, redact, local) => {
   const files = (entries(root) ?? [])
     .filter((entry) => entry.isFile() && /^HANDOFF.*\.md$/u.test(entry.name))
     .map((entry) => join(root, entry.name));
@@ -150,7 +167,8 @@ const handoffsOf = (root, budget, redact) => {
   return files.map((path) => {
     const text = readSmallFile(path, budget) ?? '';
     const headings = text.split('\n').slice(0, 40).filter((line) => /^#{1,3} /u.test(line)).map((line) => clipToWidth(redact(line), 100));
-    return { worktree: redact(root), file: basename(path), headings };
+    const next = local ? nextItemOf(text) : null;
+    return { worktree: redact(root), file: basename(path), headings, local, next: next ? clipToWidth(redact(next), 100) : null };
   });
 };
 
@@ -189,29 +207,49 @@ const stacksOf = (root, budget, redact) => {
   });
 };
 
-// This host has no start-work lifecycle state: the session's own stage record says whether a
-// start-work run is the live route and which plan it carries. Boundaries are not tracked here,
-// so a paused boundary never comes from this source.
-const startWorkOf = (root, budget, redact, env, sessionId) => {
-  const stateHome = env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state');
-  const file = sessionId ? join(stateHome, 'litmuse', 'stage', `${String(sessionId).replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128)}.json`) : null;
-  const record = file ? readJson(file, budget) : null;
-  if (!record || record.route !== 'start-work') return null;
-  const plan = typeof record.plan === 'string' && /^plans\/[A-Za-z0-9._-]+\.md$/u.test(record.plan) ? record.plan : null;
+// This host has no start-work lifecycle state: the stage records say it. This session's record
+// says whether a start-work run is the live route and which plan it carries; any session's record
+// whose plan is fully ticked is a completed run (`complete`, with the plan's change time). Only a
+// start-work route stores a plan on the record, so a plan there means a run. Boundaries are not
+// tracked here, so a paused boundary never comes from this source.
+const PLAN_NAME = /^plans\/[A-Za-z0-9._-]+\.md$/u;
+const stageDirOf = (env) => join(env.XDG_STATE_HOME || join(env.HOME || homedir(), '.local', 'state'), 'litmuse', 'stage');
+const STAGE_RECORDS_MAX = 200;
+
+const runOf = (root, record, sessionId, budget, redact) => {
+  const plan = typeof record.plan === 'string' && PLAN_NAME.test(record.plan) ? record.plan : null;
   const planText = plan ? readSmallFile(join(root, plan), budget) : null;
   const rows = planText === null ? [] : parsePlanTaskRows(planText);
   const open = rows.filter((row) => !row.checked);
-  return [{
+  const id = typeof record.session === 'string' ? record.session : sessionId ?? null;
+  return {
     worktree: redact(root),
-    workId: `stage-${record.session ?? sessionId ?? 'unknown'}`,
+    workId: `stage-${id ?? 'unknown'}`,
     plan: plan ?? 'unknown',
-    status: 'active',
-    sessionId: typeof record.session === 'string' ? record.session : sessionId ?? null,
-    id8: typeof (record.session ?? sessionId) === 'string' ? String(record.session ?? sessionId).slice(0, 8) : 'unknown',
+    status: rows.length && !open.length ? 'complete' : 'active',
+    sessionId: id,
+    id8: typeof id === 'string' ? id.slice(0, 8) : 'unknown',
+    completedMs: rows.length && !open.length ? mtimeOf(join(root, plan)) : null,
     progress: rows.length
       ? progressOf(rows.length - open.length, rows.length, open.map((row) => clipToWidth(redact(row.text), NAME_MAX)))
       : progressOf(null, null),
-  }];
+  };
+};
+
+const startWorkOf = (root, budget, redact, env, sessionId) => {
+  const dir = stageDirOf(env);
+  const own = sessionId ? readJson(join(dir, `${String(sessionId).replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128)}.json`), budget) : null;
+  const runs = own && own.route === 'start-work' ? [runOf(root, own, sessionId, budget, redact)] : [];
+  const list = entries(dir);
+  const here = projectKey(root);
+  for (const entry of (list ?? []).filter((item) => item.isFile() && item.name.endsWith('.json') && item.name !== 'latest.json').slice(0, STAGE_RECORDS_MAX)) {
+    const record = readJson(join(dir, entry.name), budget);
+    if (!record || typeof record.session !== 'string' || typeof record.cwd !== 'string' || !PLAN_NAME.test(String(record.plan))) continue;
+    if (projectKey(record.cwd) !== here) continue;
+    const run = runOf(root, record, null, budget, redact);
+    if (run.status === 'complete' && !runs.some((item) => item.workId === run.workId)) runs.push(run);
+  }
+  return runs.length || own ? runs : null;
 };
 
 const herdrOf = (env, exec, redact) => {
@@ -231,7 +269,9 @@ const sessionStoreDir = (env) => {
 };
 
 const known = (list) => (list === null ? 'unknown' : 'ok');
-const statusRank = { 'waiting-on-user': 0, active: 1, ended: 2, unknown: 3 };
+const statusRank = { 'waiting-on-user': 0, active: 1, idle: 2, done: 3, ended: 4, unknown: 5 };
+// A host may log a line or two after the Stop hook or the last plan tick; this much lag still counts.
+const SETTLE_SLACK_MS = 30_000;
 
 /**
  * Collects the brief. Options: `cwd`, `here` (cwd only), `since` (`7d`), `max` (12), `sessionId`
@@ -254,10 +294,30 @@ export const collectRewind = ({
   const sinceMs = parseSince(since) ?? parseSince(DEFAULT_SINCE);
   const limit = Number.isInteger(max) && max > 0 ? Math.min(max, 50) : DEFAULT_MAX;
   const start = resolve(cwd);
-  const stateRoot = outermostRoot(start);
+  const stateRoot = resolveProjectStateRoot(start);
   const listed = here ? null : worktreesOf(start, exec);
   const roots = [...new Set([start, ...(here ? [] : listed ?? [stateRoot])])];
 
+  // The small records come first, then transcripts: a busy session store must never crowd the
+  // plans out of the shared read budget.
+  const isLocal = (root) => resolve(root) === stateRoot || resolve(root) === start;
+  const collectEach = (read) => {
+    const results = roots.map(read);
+    return results.every((value) => value === null) ? null : results.flatMap((value) => value ?? []);
+  };
+  const skippedPlans = { count: 0 };
+  const plans = collectEach((root) => plansIn(root, budget, redact, isLocal(root), skippedPlans));
+  const litgoal = collectEach((root) => {
+    const goals = goalsOf(root, budget, redact);
+    return goals ? goals.map((goal) => ({ ...goal, local: isLocal(root) })) : null;
+  });
+  const handoffs = roots.flatMap((root) => handoffsOf(root, budget, redact, isLocal(root)));
+  const workflows = collectEach((root) => stacksOf(root, budget, redact));
+  const startWorkRuns = collectEach((root) => startWorkOf(root, budget, redact, env, sessionId));
+  const startWork = startWorkRuns && startWorkRuns.filter((run, index) => startWorkRuns.findIndex((item) => item.workId === run.workId) === index);
+  const commits = collectEach((root) => commitsOf(root, sinceMs, now, exec, redact));
+  const herdr = herdrOf(env, exec, redact);
+
   const transcripts = findTranscripts(sessionStoreDir(env), roots);
   const sessions = [];
   for (const file of transcripts.files) {
@@ -269,22 +329,26 @@ export const collectRewind = ({
     sessions.push(session);
   }
 
-  const collectEach = (read) => {
-    const results = roots.map(read);
-    return results.every((value) => value === null) ? null : results.flatMap((value) => value ?? []);
-  };
-  const plans = collectEach((root) => plansIn(root, budget, redact, resolve(root) === stateRoot || resolve(root) === start));
-  const litgoal = collectEach((root) => {
-    const goals = goalsOf(root, budget, redact);
-    return goals ? goals.map((goal) => ({ ...goal, local: resolve(root) === stateRoot || resolve(root) === start })) : null;
-  });
-  const handoffs = roots.flatMap((root) => handoffsOf(root, budget, redact));
-  const commits = collectEach((root) => commitsOf(root, sinceMs, now, exec, redact));
-  const workflows = collectEach((root) => stacksOf(root, budget, redact));
-  const startWork = collectEach((root) => startWorkOf(root, budget, redact, env, sessionId));
-  const herdr = herdrOf(env, exec, redact);
+  // The hooks' liveness records: Stop marks a session idle, SessionEnd marks it ended.
+  const liveness = new Map(readLiveness(env).map((item) => [item.session, item]));
 
   // A session waits on the user when it asked something, or holds a paused frame or a boundary.
+  // Another session that is otherwise active reads `done` when its start-work run completed after its
+  // last log line, and `idle` when its last hook event is a Stop no older than that line.
+  for (const session of sessions) {
+    const live = liveness.get(session.sessionId);
+    const finished = (startWork ?? []).find((item) => item.status === 'complete' && item.sessionId === session.sessionId);
+    const self = Boolean(sessionId) && session.sessionId === sessionId;
+    if (!self && session.status === 'active' && session.lastMs !== null) {
+      if (finished && finished.completedMs !== null && finished.completedMs >= session.lastMs - SETTLE_SLACK_MS) {
+        session.status = 'done';
+        session.finishedPlan = finished.plan;
+      } else if (live?.state === 'idle' && Date.parse(live.at) >= session.lastMs - SETTLE_SLACK_MS) {
+        session.status = 'idle';
+      }
+    }
+    if (!self && live?.state === 'ended' && session.status !== 'waiting-on-user') session.status = 'ended';
+  }
   for (const session of sessions) {
     const frames = (workflows ?? []).filter((frame) => frame.sessionId === session.sessionId);
     const top = frames.at(-1);
@@ -308,11 +372,12 @@ export const collectRewind = ({
   }
   sessions.sort((a, b) => statusRank[a.status] - statusRank[b.status] || (b.lastMs ?? 0) - (a.lastMs ?? 0));
 
-  // This worktree's open plans and the ones another worktree touched inside the window are listed,
-  // this one's first, then the most recently changed, up to a short cap; a stale plan elsewhere is
-  // left out entirely. Unfilled scaffolds never reach the list (plansIn drops them). The roadmap gauge
-  // counts this worktree only, since a sum over unrelated branches measures nothing.
-  const recent = (plan) => plan.local || (plan.changedMs !== null && now - plan.changedMs <= sinceMs);
+  // Plans changed inside the window are listed, this worktree's included, finished ones too (they
+  // count as done): this worktree's first, then the most recently changed, up to a short cap; a plan
+  // last changed before the window is left out, here or elsewhere. Unfilled scaffolds never reach the
+  // list (plansIn drops them). The roadmap gauge counts this worktree only, since a sum over unrelated
+  // branches measures nothing.
+  const recent = (plan) => plan.changedMs !== null && now - plan.changedMs <= sinceMs;
   const orderedPlans = (plans ?? []).filter(recent).sort((a, b) => Number(b.local) - Number(a.local) || (b.changedMs ?? 0) - (a.changedMs ?? 0));
   const shownPlans = orderedPlans.slice(0, PLAN_LIMIT);
   const localGoals = (litgoal ?? []).filter((goal) => goal.local);
@@ -341,6 +406,7 @@ export const collectRewind = ({
     roadmap: {
       plans: shownPlans,
       plansOmitted: orderedPlans.length - shownPlans.length,
+      plansSkipped: skippedPlans.count,
       // Another worktree's finished objective is history, not roadmap.
       litgoal: (litgoal ?? []).filter((goal) => goal.local || goal.status !== 'complete'),
       progress: roadmapItems.length ? aggregateProgress(roadmapItems) : progressOf(null, null),
@@ -353,6 +419,7 @@ export const collectRewind = ({
   };
   const next = chooseNextStep(data, sessionId);
   data.next = next;
+  data.opener = openerOf(data, sessionId, redact(start));
   data.nextRecorded = false;
   if (record && sessionId) {
     try {
@@ -382,10 +449,12 @@ const remainingLine = (names, width) => {
 // ANSI pieces never reach the width math: every row is clipped raw, then painted.
 const ESC = '\u001b[';
 const paint = (code, text) => `${ESC}${code}m${text}${ESC}0m`;
-const STATUS_BADGE = { 'waiting-on-user': '● waiting on you', active: '● ACTIVE', ended: '○ Ended', unknown: '○ unknown' };
+const STATUS_BADGE = { 'waiting-on-user': '● waiting on you', active: '● ACTIVE', idle: '◌ idle', done: '✓ done', ended: '○ Ended', unknown: '○ unknown' };
 const BADGE_PAINT = {
   'waiting-on-user': (text) => paint('33;1', text),
   active: (text) => paint('32;1', text),
+  idle: (text) => paint('2', text),
+  done: (text) => paint('32', text),
   ended: (text) => paint('2', text),
   unknown: (text) => paint('2', text),
 };
@@ -412,6 +481,7 @@ const sessionNext = (session, data) => {
   const frame = data.workflows.find((item) => item.id8 === session.id8 && item.status === 'paused' && data.next.say);
   if (frame) return `say "${data.next.say}" to resume the paused ${frame.skill}`;
   if (session.status === 'waiting-on-user') return session.waitingReason === 'start-work boundary' ? 'answer the boundary: `lit approve` or `lit deny`' : 'answer its question';
+  if (session.status === 'done' && session.finishedPlan) return `start-work finished ${session.finishedPlan}`;
   return null;
 };
 
@@ -489,8 +559,10 @@ const sessionCard = (session, data, emitLine, now) => {
   const commits = (session.done?.commits ?? []).map((commit) => `${commit.hash} ${commit.subject}`);
   if (tools || commits.length) emitLine([['✅ Done: ', (text) => paint('32', text)], [[tools, ...commits].filter(Boolean).join(' · '), null]]);
   // A card with no recorded edit yet names what it is doing now: its last tool call, name only.
-  // (This host's log keeps no file list, so commits are the only edits it can show.)
-  if (!commits.length && !(session.done?.files ?? []).length && session.lastAction?.tool) emitLine([['▶ Now: ', (text) => paint('33', text)], [session.lastAction.tool, null]]);
+  // (This host's log keeps no file list, so commits are the only edits it can show.) An idle or done
+  // session is doing nothing now, so its last call is history and never shown as current.
+  const settled = session.status === 'idle' || session.status === 'done';
+  if (!settled && !commits.length && !(session.done?.files ?? []).length && session.lastAction?.tool) emitLine([['▶ Now: ', (text) => paint('33', text)], [session.lastAction.tool, null]]);
   const next = sessionNext(session, data);
   if (next) emitLine([['➤ Next: ', (text) => paint('36;1', text)], [next, null]]);
 };
@@ -566,11 +638,60 @@ const suggestion = (data) => {
   if (plan) return { text: `Next in ${plan.local ? plan.plan : `${basename(String(plan.worktree))}/${plan.plan}`}: ${clipToWidth(String(plan.current), 60)}`, say: 'go' };
   const active = sessions.find((session) => session.status === 'active' && !session.self);
   if (active) return { text: `Check on ${active.id8} in ${place(active)} (${goal(active)})`, say: null };
-  const ended = sessions.find((session) => session.status === 'ended' && !session.self);
-  if (ended) return { text: `Pick up ${ended.id8} in ${place(ended)}: ${goal(ended)}`, say: null };
+  // Then the newest session that is not running: review what a done one finished, or pick up an
+  // idle or ended one. A finished step is never offered again as the thing to do.
+  const settled = sessions.find((session) => ['done', 'idle', 'ended'].includes(session.status) && !session.self);
+  if (settled?.status === 'done') return { text: `Review what ${settled.id8} finished in ${place(settled)}: ${settled.finishedPlan ?? goal(settled)}`, say: null };
+  if (settled) return { text: `Pick up ${settled.id8} in ${place(settled)}: ${goal(settled)}`, say: null };
   return { text: 'No session or plan in this window: say what to start', say: null };
 };
 
+// With no step for `go`, this worktree's HANDOFF Next item comes before the generic suggestion; it
+// is shown only, never something `go` runs.
+const handoffNextOf = (data) => (data.handoffs ?? []).find((handoff) => handoff.local && handoff.next)?.next ?? null;
+const stepOf = (data) => {
+  if (data.next?.kind && data.next.kind !== 'none') return null;
+  const handoff = handoffNextOf(data);
+  return handoff ? { text: handoff, say: null } : suggestion(data);
+};
+const goStepText = (next) => {
+  const target = next.target?.plan ?? next.target?.skill ?? '';
+  return `${next.kind.replace(/-/g, ' ')}${target ? `: ${target}` : ''}${next.say ? ` (say "${next.say}")` : ''}`;
+};
+
+/**
+ * The three lines that open the brief, from records only. Done: this worktree's newest commits in the
+ * window (two at most), then its completed start-work runs and fully ticked plans (three items in
+ * all), else its finished goal. Doing: this session's top frame, else its running start-work, else
+ * the newest active session's goal. Next: the recommended step and the word to say.
+ */
+const openerOf = (data, sessionId, here) => {
+  const subjects = data.commits.filter((commit) => commit.worktree === here).slice(0, 2).map((commit) => commit.subject);
+  const runs = data.startWork.filter((work) => work.status === 'complete' && work.worktree === here);
+  const runPlans = new Set(runs.map((work) => work.plan));
+  const finished = [
+    ...runs.map((work) => `${work.plan} (start-work complete)`),
+    ...data.roadmap.plans.filter((plan) => plan.local && plan.current === null && !runPlans.has(plan.plan)).map((plan) => `${plan.plan} ${plan.progress.gauge}`),
+  ];
+  const items = [...subjects, ...new Set(finished)].slice(0, 3);
+  const goal = data.roadmap.litgoal.find((item) => item.local && item.status === 'complete');
+  const frame = data.workflows.filter((item) => Boolean(sessionId) && item.sessionId === sessionId).at(-1);
+  const work = data.startWork.find((item) => item.status === 'active' && Boolean(sessionId) && item.sessionId === sessionId);
+  const active = data.sessions.find((session) => session.status === 'active');
+  const known = (part) => part && part !== 'unknown';
+  const doing = frame
+    ? [frame.skill, frame.stage, frame.progress?.gauge].filter(known).join(' · ')
+    : work
+      ? ['start-work', work.plan, work.progress?.gauge].filter(known).join(' · ')
+      : active ? clipToWidth(String(known(active.title) ? active.title : active.asked?.[0] ?? 'unknown'), 80) : 'nothing running';
+  const step = stepOf(data);
+  return {
+    done: items.length ? items.join('; ') : goal ? goal.objective : 'nothing finished in this window',
+    doing,
+    next: step ? `${step.text}${step.say ? ` (say "${step.say}")` : ''}` : goStepText(data.next),
+  };
+};
+
 // Wraps a step to the box at word breaks, three lines at most, the last one clipped.
 const wrap = (text, width, rows = 3) => {
   const out = [''];
@@ -590,9 +711,15 @@ export const renderRewind = (data, width = 100, { color = false } = {}) => {
   const emitLine = (segments) => emit(out, color, width, segments);
   const put = (raw, fn = null) => emitLine([[raw, fn]]);
   const frame = Math.max(width, 20);
-  const step = data.next?.kind && data.next.kind !== 'none' ? null : suggestion(data);
+  const step = stepOf(data);
   const nextKind = data.next.kind.replace(/-/g, ' ');
   const nextSay = data.next.say ? ` (say "${data.next.say}")` : '';
+  // Three plain lines open the brief: done so far, doing now, next.
+  if (data.opener) {
+    put(`Done so far: ${data.opener.done}`);
+    put(`Doing now: ${data.opener.doing}`);
+    put(`Next: ${data.opener.next}`);
+  }
   // The one static rainbow line of this surface marks the adhd turn (no animation on this host).
   const headline = `lit-adhd: ${data.summary.sessions} session(s) · ${data.summary.waitingOnUser} waiting on you · next: ${step ? step.text : `${nextKind}${nextSay}`}`;
   put(headline, color ? (text) => rainbowLine(text) : null);
@@ -646,6 +773,8 @@ export const renderRewind = (data, width = 100, { color = false } = {}) => {
   put('Nothing runs on its own here: open that session, or say what to do.');
   const unread = Object.entries(data.sources).filter(([, status]) => status !== 'ok').map(([name]) => SOURCE_LABELS[name] ?? name);
   if (unread.length) put(`Not read: ${unread.join(', ')}.`);
+  const skipped = data.roadmap.plansSkipped ?? 0;
+  if (skipped > 0) put(`${skipped} ${skipped === 1 ? 'plan was' : 'plans were'} not read (read budget used up).`);
   return `${out.join('\n')}\n`;
 };
 

package/plugin/lib/rewind/transcripts.mjs

@@ -17,6 +17,8 @@ const ACTIVE_MS = 15 * 60 * 1000;
 export const makeBudget = (limit = TOTAL_BUDGET_BYTES) => ({ limit, used: 0, exhausted: false });
 
 const readSlice = (fd, position, length, budget) => {
+  // An empty slice (a head-only peek) reads nothing; it must not mark the budget used up.
+  if (length <= 0) return '';
   const allowed = Math.min(length, budget.limit - budget.used);
   if (allowed <= 0) {
     budget.exhausted = true;

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

@@ -47,14 +47,15 @@ verdicts: [PASS, FAIL, BLOCKED]
 
 ## #contract.outputs
 
-The brief has six parts, in this order:
+The brief opens with three lines, then has six parts, in this order:
 
+0. **Three opening lines**, copied from `opener` in the user's language: `Done so far:` (`opener.done`: this worktree's newest commits in the window, two at most, then its completed start-work runs as `<plan> (start-work complete)` and its fully ticked plans with their gauge, three items in all, else its finished goal, else "nothing finished in this window"); `Doing now:` (`opener.doing`: this session's top frame with stage and gauge, else its running start-work plan, else the newest active session's goal, else "nothing running"); `Next:` (`opener.next`: the one next step, with the word to say in brackets). In Korean: `지금까지:`, `지금:`, `다음:`.
 1. **Headline.** Sessions found, how many wait on the user, the one next step: `7 sessions · 1 waiting on you · next: resume frame (say "lit continue")` / `세션 7개 · 나를 기다리는 것 1 · 다음: resume frame ("lit continue")`.
-2. **One card per live session.** Sessions that wait on the user or are active come first, grouped under their worktree. A status badge (`● waiting on you`, `● ACTIVE`, in the user's language) with the id, the route when known, and the age; the goal in plain words; the known facts (`⏳ 3m of work · last ask: "…"`, in the user's language); a real gauge with what is left; what was done (`✅ Done:`, tools named never counted, and commits); what it is doing now when no edit is on record (`▶ Now:`, the last tool call by name); what is next (`➤ Next:`).
+2. **One card per live session.** Sessions that wait on the user come first, then active, idle and done ones, grouped under their worktree. A status badge (`● waiting on you`, `● ACTIVE`, `◌ idle`, `✓ done`, in the user's language) with the id, the route when known, and the age; the goal in plain words; the known facts (`⏳ 3m of work · last ask: "…"`, in the user's language); a real gauge with what is left; what was done (`✅ Done:`, tools named never counted, and commits); what it is doing now when no edit is on record (`▶ Now:`, the last tool call by name, for a session that is still running); what is next (`➤ Next:`). A done session's next line names the plan its run finished (`start-work finished plans/a.md`); an idle or done session's last tool call is history, never offered as its next step.
 3. **Ended sessions, one bordered table.** Ended sessions collapse into a ruled table (`id | tree | goal | ago | done`), at most 8 rows with a count of the rest. The age reads the largest unit (`6h`, not `6h 40m`); the done cell reads commits or the file count, never both.
-4. **Roadmap timeline.** Done `✓` (finished plans and landed commits with dates), now `▶` (the current item of each open plan), later `○` (remaining names), then goal objectives with their gauges. Plans from other worktrees carry their worktree name, and only the ones touched inside the window are listed; unfilled plan scaffolds never appear. When `plansOmitted` is above zero, say how many more open plans exist.
+4. **Roadmap timeline.** Done `✓` (finished plans, which count toward the roadmap gauge, and landed commits with dates), now `▶` (the current item of each open plan), later `○` (remaining names), then goal objectives with their gauges. Every plan is held to the window: only plans changed inside it are listed, this worktree's included, and plans from other worktrees carry their worktree name; unfilled plan scaffolds never appear. When `plansOmitted` is above zero, say how many more open plans exist; when `roadmap.plansSkipped` is above zero, say on the last line how many plans were not read because the read budget ran out.
 5. **Paused work.** Each paused frame from `workflows` with its gauge and a resume offer: `lit-loop [▉▉▉░░░░] 3/7 paused, resume?` / `lit-loop [▉▉▉░░░░] 3/7 일시정지, 이어갈까요?`.
-6. **One next step in a box.** Exactly one, from `next`: what it does, then "say go" (or the `say` word). When nothing can run on `go`, the box still recommends a real step from the records (a session waiting on the user, a paused workflow, an open plan item, the latest active session, the latest ended one) and says that nothing runs on its own.
+6. **One next step in a box.** Exactly one, from `next`: what it does, then "say go" (or the `say` word). When nothing can run on `go`, the box still recommends a real step from the records, in this order: the first item under `## Next` or `## Next Steps` in this worktree's own `HANDOFF*.md` (`handoffs[].next`), a session waiting on the user, a paused workflow, an open plan item, the latest active session, then the newest session that is not running (review what a done one finished, or pick up an idle or ended one). It says that nothing runs on its own, and a HANDOFF step never carries a word to type. A step that is already done is never offered again.
 
 **Progress gauges (D9), required.** One real gauge per session and per plan, each copied verbatim from the collector, in the form `[▉▉▉░░] 3/5` (filled `▉` done, light `░` remaining, then done/total). The remaining items are listed by name under each gauge, from its `remaining` array, clipped by the collector to fit. A gauge renders only when both numbers are real: an unknown total is the known-facts line (`… 3 steps`, or `… running` when nothing is counted), never `?`, never a guess, never an estimate, never a gauge of your own.
 
@@ -116,24 +117,27 @@ The collector (`plugin/lib/rewind/collect.mjs`, served as `litmuse rewind`) read
 | Source | What it gives | Missing reads |
 | --- | --- | --- |
 | Muse transcripts, `<data>/muse/sessions/*/*/*/session.jsonl` | per session: title, first and last ask, tools used, status | `transcripts: unknown` |
-| `plans/*.md` checkbox rows | open plans, current item, done/total, remaining names | `plans: unknown` |
+| `plans/*.md` checkbox rows | plans changed inside the window (open and finished), current item, done/total, remaining names | `plans: unknown` |
 | `.litmuse/goals/*.json` | objective and passed/total criteria per goal | `litgoal: unknown` |
-| `HANDOFF*.md` and `.litmuse/handoff/latest.md` | headings from the first 40 lines only | `handoffs: unknown` |
+| `HANDOFF*.md` and `.litmuse/handoff/latest.md` | headings from the first 40 lines; for this worktree's own files, the first item under `## Next` / `## Next Steps` | `handoffs: unknown` |
 | `git log --since` | commits in the window, matched to sessions by time and branch | `git: unknown` |
 | `.litmuse/workflow-stack/*.json` | running and paused disciplines with stage and k/n | `workflowStack: unknown` |
-| the session's own stage record | live start-work route and its plan, with the plan's own progress | `startWork: unknown` |
+| the stage records (`$XDG_STATE_HOME/litmuse/stage/`) | this session's live start-work route and plan; any session's completed run (its plan fully ticked) | `startWork: unknown` |
+| the liveness records (`stage/liveness/`) | each session's last hook event: `alive` (a tool call), `idle` (Stop), `ended` (SessionEnd) | the transcript time alone decides |
 | `herdr agent list` (only when `HERDR_ENV=1`) | agent panes | `herdr: unknown` |
 
-Transcripts 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; subagent transcripts are skipped. A session belongs to a worktree when the `cwd` its log records sits inside it. 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 `~`). Assistant text and changed files are not in this host's log records, so the brief shows commits and tool names instead.
+Plans, goals, handoffs, workflow stacks and stage records are read first, then transcripts, so a busy session store never crowds out the plans; a plan the budget can no longer cover is counted in `roadmap.plansSkipped`, never half-read. Transcripts 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; subagent transcripts are skipped. A session belongs to a worktree when the `cwd` its log records sits inside it. 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 `~`). Assistant text and changed files are not in this host's log records, so the brief shows commits and tool names instead.
 
 ## Status taxonomy
 
 - `waiting-on-user`: the session's last word was the assistant asking something, or it holds a paused workflow frame or a start-work boundary awaiting `lit approve`.
 - `active`: written to within the last 15 minutes and not waiting.
-- `ended`: quiet for longer than that.
+- `idle`: another session whose last hook event is a Stop no older than its last log line.
+- `done`: another session whose start-work run completed (plan fully ticked) after its last log line.
+- `ended`: quiet for longer than 15 minutes, or its last hook event was SessionEnd.
 - `unknown`: the transcript 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 and done ones, newest first. This session always reads active while it runs the brief.
 
 ## The next step
 
@@ -172,7 +176,7 @@ lit-adhd is a read-only discipline: it never pushes, pauses or finishes a workfl
 ## Stop and report
 
 - Stop with `BLOCKED: lit-adhd collector unavailable (<reason>)` when the collector exits non-zero or is not found; never rebuild the brief from memory.
-- The reply is the six-part brief (summary, live cards, ended rows, roadmap, paused work, one next step) and nothing more. Name every `unknown` source once on the last line.
+- The reply is the three opening lines and the six-part brief (summary, live cards, ended rows, roadmap, paused work, one next step) and nothing more. Name every `unknown` source once on the last line.
 - Start nothing: the user's `go` starts the next step, not this turn.
 
 ## Pitfalls
@@ -183,6 +187,9 @@ lit-adhd is a read-only discipline: it never pushes, pauses or finishes a workfl
 | `sources.transcripts: unknown` | No `muse/sessions/` folder under the data dir | Say no session records were found; still show plans and goals |
 | `budget.exhausted: true` | The 8 MiB budget ran out | Say older sessions were not read |
 | no gauge line on a card | No stack or start-work records progress for that session | Say the elapsed time and last action instead of a count; never print a placeholder pulse |
-| `next.kind: none` | No single next step runs on `go` | The box recommends a real step from the records; say it, do not run it or invent another |
+| `next.kind: none` | No single next step runs on `go` | The box recommends a real step from the records (this worktree's HANDOFF Next item first); say it, do not run it or invent another |
+| `roadmap.plansSkipped` above zero | The read budget ran out before those plan files | Say how many plans were not read |
+| a plan you expected is missing | It was last changed before the window (`--since`, 7 days by default) | Say a wider `--since` lists it |
+| `opener.doing: nothing running` | No frame, start-work or active session is on record | Print it as given |
 
 See `references/card-examples.md` for complete briefs in English and Korean and `references/status-taxonomy.md` for the status wording in both languages.