@litfamily/litmuse 0.1.2 → 0.1.3

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # Changelog
 
+## 0.1.3 — 2026-10-28
+
+- After you save a plan, typing `go` within 30 minutes starts it. A plan saved by another session, or an older one, does not.
+- lit-plan checks that every command touching a path outside the project is covered by a `Scope roots:` line, and start-work points to that check. A command quoted in a code block or inline code is treated as text and does not count.
+- The LIT card is clearer about other sessions: running ones come first, then idle ones, each named by its skill and, inside herdr, its pane. A finished start-work stays as done for a minute and then leaves. When a newer LitMuse is installed than the one this session loaded, the card says `restart to <version>`.
+- `lit-adhd` reads your plans before transcripts, keeps finished plans as complete, picks up the `## Next` section of this worktree's handoff, marks sessions as done or idle, and opens with a three-line summary. Its next step no longer repeats one that is already done.
+- A linked git worktree keeps its own `.litmuse` state instead of writing into the main checkout's.
+- New `TRADEMARK.md`: the code stays MIT; the LitMuse and LitFamily names and art are covered there.
+- The hook code changed, so Muse asks you to approve the LitMuse hooks again after the update; `npx @litfamily/litmuse install` lists them and asks once.
+
 ## 0.1.2 — 2026-10-27
 
 - Three new skills, so LitMuse now has 42. `lit-schematic` draws P&IDs with ISA-5.1 tags and control loops, apparatus figures for papers and isometric cutaways, as editable SVG with a QA gate. `lit-hijack` studies a tool you point it at and rebuilds what you want from it clean-room, with a gate after each phase. `lit-adhd` (also `lit-rewind`) is a briefing across your recent Muse sessions: what each one asked, did and is waiting on, with a single next step that a bare `go` picks up.

package/README.md

@@ -178,7 +178,7 @@ The document, diagram, README-cover and figure skills ship pinned engines (`offi
 
 **4 commands**: `/lit <route> <task>`, `/lit-korean <file or text>`, `/lit-status`, `/lit-hud`.
 
-**10 hooks**: SessionStart (LitMuse context and routes; after a compaction it re-injects the saved handoff once, and it adds the answer style you chose with `litmuse style`), UserPromptSubmit (`lit` activation; a later `lit` while its route is active continues it, `lit <other route>` switches, a bare `lit` resumes a started plan, `lit new` or `lit restart` starts over), PreToolUse (during lit-plan: writes through write_file, edit_file, apply_patch or delete_file stay inside `plans/` and `.litmuse/`, shell commands are read-only, and only read-only LitMuse agents may be spawned; on every route: guards against clustered negations and clustered hedges that a write adds to Markdown or text prose), PostToolUse (the tool ledger, plus the whole-line comments an edit added for comment-checker and an advisory lit-humanizer check on written prose; on the motion route it also notes each render and each image `read_file` opened), PostToolUseFailure (ledger), Stop (a lit-plan turn ends after its plan file exists; a motion turn ends when the skill's done-check passes on the last render, or after two holds with a plain not-done notice; start-work keeps going while plan rows are open and litgoal while criteria are open, each at most 3 holds in a row without progress), PreCompact (writes `.litmuse/handoff/latest.md` before Muse compacts), SubagentStart (the return format for child agents), SubagentStop and SessionEnd (ledger lines). The hooks also keep a live record of the route, plan progress and running child agents, which `/lit-status` and `npx @litfamily/litmuse status --card` show, because Muse's `/hud` shows fixed fields only.
+**10 hooks**: SessionStart (LitMuse context and routes; after a compaction it re-injects the saved handoff once, and it adds the answer style you chose with `litmuse style`), UserPromptSubmit (`lit` activation; a later `lit` while its route is active continues it, `lit <other route>` switches, a bare `lit` resumes a started plan, `lit new` or `lit restart` starts over), PreToolUse (during lit-plan: writes through write_file, edit_file, apply_patch or delete_file stay inside `plans/` and `.litmuse/`, shell commands are read-only, and only read-only LitMuse agents may be spawned; on every route: guards against clustered negations and clustered hedges that a write adds to Markdown or text prose), PostToolUse (the tool ledger, plus the whole-line comments an edit added for comment-checker and an advisory lit-humanizer check on written prose; on the motion route it also notes each render and each image `read_file` opened), PostToolUseFailure (ledger), Stop (a lit-plan turn ends after its plan file exists, and a one-word `go` in the same session within 30 minutes then starts that plan with start-work; a motion turn ends when the skill's done-check passes on the last render, or after two holds with a plain not-done notice; start-work keeps going while plan rows are open and litgoal while criteria are open, each at most 3 holds in a row without progress), PreCompact (writes `.litmuse/handoff/latest.md` before Muse compacts), SubagentStart (the return format for child agents), SubagentStop and SessionEnd (ledger lines). The hooks also keep a live record of the route, plan progress and running child agents, plus each session's liveness (PostToolUse says alive, Stop idle, SessionEnd ended), which `/lit-status` and `npx @litfamily/litmuse status --card` show, because Muse's `/hud` shows fixed fields only. The card lists other sessions of the project running first, then idle, keeps a finished start-work as done for a minute, names a herdr pane session `<skill> · <pane>`, and says `restart to <version>` when a newer LitMuse was installed after the session started.
 
 **11 agents**, spawned as `litmuse/<name>`: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, and five Korean prose agents. Reviewers and the Korean agents get read and search tools only.
 
@@ -215,3 +215,5 @@ LitMuse is one of the seven LitFamily packages, and the seven armored robots on
 ## License
 
 MIT, © LitMuse contributors. LitMuse is an independent community project and is not affiliated with or endorsed by Meta.
+
+The LitMuse and LitFamily names, logos and mascot art are covered by [TRADEMARK.md](./TRADEMARK.md).

package/README_ko-KR.md

@@ -178,7 +178,7 @@ Muse의 `/hud`는 켜고 끄는 고정 항목 목록이라서 플러그인 글
 
 **명령 4개**: `/lit <경로> <작업>`, `/lit-korean <파일 또는 글>`, `/lit-status`, `/lit-hud`.
 
-**훅 10개**: SessionStart(LitMuse 컨텍스트와 경로 표. 컴팩션 뒤에는 저장해 둔 인계 메모를 한 번 다시 넣고, `litmuse style`로 고른 답변 스타일도 더함), UserPromptSubmit(맨 앞의 `lit` 활성화. 같은 경로가 이미 켜져 있으면 이어서 진행, 다른 경로면 전환, 맨 `lit`은 시작한 계획을 재개, `lit new`·`lit restart`는 새로 시작), PreToolUse(lit-plan 동안 write_file·edit_file·apply_patch·delete_file 쓰기는 `plans/`와 `.litmuse/` 안으로 제한하고 셸 명령은 읽기 전용만 허용, 자식 에이전트는 읽기 전용 LitMuse 에이전트만 허용, 모든 경로에서 쓰기가 Markdown이나 텍스트 글에 새로 더하는 부정문 몰림과 얼버무림 몰림 검사), PostToolUse(도구 기록, 편집이 새로 더한 한 줄 주석을 comment-checker에 넘기고 쓴 글에는 lit-humanizer 참고 검사. 모션 경로에서는 렌더 실행과 `read_file`로 연 이미지도 기록), PostToolUseFailure(기록), Stop(lit-plan 턴은 계획 파일이 생긴 뒤 끝남. 모션 턴은 마지막 렌더가 스킬의 완료 검사를 통과하면 끝나고, 두 번 붙잡은 뒤에는 아직 끝나지 않았다고 분명히 말하게 함. start-work는 계획 행이, litgoal은 기준이 남아 있으면 이어 가되 진전 없이 연속 3번까지만 붙잡음), PreCompact(Muse가 컴팩션하기 전에 `.litmuse/handoff/latest.md`를 씀), SubagentStart(자식 에이전트의 보고 형식), SubagentStop·SessionEnd(기록 줄). 훅은 경로, 계획 진행, 실행 중인 자식 에이전트도 실시간 기록으로 남기며, Muse의 `/hud`는 고정 항목만 보여 주므로 이 기록은 `/lit-status`와 `npx @litfamily/litmuse status --card`로 봅니다.
+**훅 10개**: SessionStart(LitMuse 컨텍스트와 경로 표. 컴팩션 뒤에는 저장해 둔 인계 메모를 한 번 다시 넣고, `litmuse style`로 고른 답변 스타일도 더함), UserPromptSubmit(맨 앞의 `lit` 활성화. 같은 경로가 이미 켜져 있으면 이어서 진행, 다른 경로면 전환, 맨 `lit`은 시작한 계획을 재개, `lit new`·`lit restart`는 새로 시작), PreToolUse(lit-plan 동안 write_file·edit_file·apply_patch·delete_file 쓰기는 `plans/`와 `.litmuse/` 안으로 제한하고 셸 명령은 읽기 전용만 허용, 자식 에이전트는 읽기 전용 LitMuse 에이전트만 허용, 모든 경로에서 쓰기가 Markdown이나 텍스트 글에 새로 더하는 부정문 몰림과 얼버무림 몰림 검사), PostToolUse(도구 기록, 편집이 새로 더한 한 줄 주석을 comment-checker에 넘기고 쓴 글에는 lit-humanizer 참고 검사. 모션 경로에서는 렌더 실행과 `read_file`로 연 이미지도 기록), PostToolUseFailure(기록), Stop(lit-plan 턴은 계획 파일이 생긴 뒤 끝나고, 같은 세션에서 30분 안에 `go` 한 단어를 입력하면 그 계획을 start-work로 시작. 모션 턴은 마지막 렌더가 스킬의 완료 검사를 통과하면 끝나고, 두 번 붙잡은 뒤에는 아직 끝나지 않았다고 분명히 말하게 함. start-work는 계획 행이, litgoal은 기준이 남아 있으면 이어 가되 진전 없이 연속 3번까지만 붙잡음), PreCompact(Muse가 컴팩션하기 전에 `.litmuse/handoff/latest.md`를 씀), SubagentStart(자식 에이전트의 보고 형식), SubagentStop·SessionEnd(기록 줄). 훅은 경로, 계획 진행, 실행 중인 자식 에이전트와 세션별 활동 상태(PostToolUse는 alive, Stop은 idle, SessionEnd는 ended)도 실시간 기록으로 남기며, Muse의 `/hud`는 고정 항목만 보여 주므로 이 기록은 `/lit-status`와 `npx @litfamily/litmuse status --card`로 봅니다. 카드는 같은 프로젝트의 다른 세션을 실행 중인 것부터 쉬는 것 순으로 보여 주고, 끝난 start-work는 1분 동안 done으로 두었다가 지우며, herdr 창 세션은 `<skill> · <pane>`으로 표시하고, 세션 시작 뒤 더 새 LitMuse가 설치되면 `restart to <버전>`을 띄웁니다.
 
 **에이전트 11개**, `litmuse/<이름>`으로 띄웁니다: lit-planner, lit-executor, lit-verifier, qa-runner, quality-reviewer, librarian-researcher, 그리고 한국어 글 에이전트 다섯. 리뷰어와 한국어 에이전트는 읽기와 검색 도구만 씁니다.
 
@@ -215,3 +215,5 @@ LitMuse는 LitFamily 패키지 일곱 개 가운데 하나이고, 표지의 로
 ## 라이선스
 
 MIT, © LitMuse contributors. LitMuse는 독립 커뮤니티 프로젝트이며 Meta와 제휴하거나 Meta의 보증을 받은 프로젝트가 아닙니다.
+
+LitMuse와 LitFamily 이름, 로고, 마스코트 그림에는 [TRADEMARK.md](./TRADEMARK.md)가 적용됩니다.

package/TRADEMARK.md

@@ -0,0 +1,12 @@
+# Trademark policy
+
+The code in this repository is free to use under the MIT License (see `LICENSE`). The names **LitMuse**
+and **LitFamily**, and the logos and mascot art, are not part of that license.
+
+- You can fork, change and share the code under MIT.
+- If you publish a changed version, give it a different name and logo, and do not suggest that the
+  LitMuse maintainers made or endorse it.
+- You can say in plain text that your project is "based on LitMuse" or "a fork of LitMuse".
+- Unchanged copies, such as mirrors and package caches, may keep the name.
+
+Questions: open an issue at https://github.com/wjgoarxiv/litmuse/issues.

package/lib/stage-card.mjs

@@ -1,8 +1,14 @@
 import { readFileSync, readdirSync, statSync, existsSync } from 'node:fs';
 import { join } from 'node:path';
-import { latestFile, readStage, stageFile, workspaceHash } from '../plugin/hooks/lib/stage.mjs';
+import { latestFile, readLiveness, readStage, stageFile, workspaceHash } from '../plugin/hooks/lib/stage.mjs';
+import { newerThan } from '../plugin/hooks/lib/common.mjs';
+import { readManifest } from './bundle.mjs';
+import { paths } from './paths.mjs';
 import { gauge } from '../plugin/lib/rewind/gauge.mjs';
-import { REVIEW_LANES } from '../plugin/hooks/lib/workflow-stack.mjs';
+import { REVIEW_LANES, projectKey, resolveProjectStateRoot } from '../plugin/hooks/lib/workflow-stack.mjs';
+
+// The hooks write `.litmuse` at the project state root, which may sit above the card's cwd.
+const stacksDir = (cwd) => join(resolveProjectStateRoot(cwd), '.litmuse', 'workflow-stack');
 
 export function fmtDuration(ms) {
   const s = Math.max(0, Math.floor(ms / 1000));
@@ -92,7 +98,7 @@ export function rainbowLine(text) {
 // Fresh workflow stacks mean recent sessions worth briefing: any stack file touched in 24 h.
 export function freshStacks(cwd, now = Date.now()) {
   try {
-    const dir = join(cwd, '.litmuse', 'workflow-stack');
+    const dir = stacksDir(cwd);
     const day = 24 * 60 * 60 * 1000;
     return readdirSync(dir).some((name) => name.endsWith('.json') && now - statSync(join(dir, name)).mtimeMs <= day);
   } catch {
@@ -104,7 +110,7 @@ export function freshStacks(cwd, now = Date.now()) {
 // resolves from exactly one source, in this order: the frame's recorded k/n, the named plan's
 // rows, the active goal's criteria, otherwise the indeterminate pulse. Frames without a stage
 // (a pure `record` spine) and frames older than 24 h are dropped; sibling sessions older than
-// 15 minutes are skipped. Order is fixed (own stack, then siblings by file name), so a repaint
+// 15 minutes are skipped. Order is fixed (own stack, then other sessions as below), so a repaint
 // with no change is byte-identical.
 const THREAD_CAP = 6;
 const THREAD_STALE_MS = 24 * 60 * 60 * 1000;
@@ -140,45 +146,104 @@ const frameRow = (frame, session, cwd, goal) => ({
   verdicts: frame.verdicts && typeof frame.verdicts === 'object' ? { ...frame.verdicts } : undefined,
 });
 
-export function threadRows({ cwd, session, now = Date.now() }) {
+// Other sessions of this project come from two sources: their fresh workflow stacks and their liveness
+// records (alive, idle, ended, written by the hooks). Each reads `running`, `idle` or `done`; a session
+// that ended, or whose start-work plan is fully ticked, reads `done` for a minute and then leaves the
+// card. Running rows come first, then paused and idle ones, then done; ties keep the name order. A
+// session started in a herdr pane is named `<skill> · <pane>` instead of by its id, and a session with
+// no stack still gets a row (skill from its stage record, else `session`), even as the only row.
+const DONE_SHOW_MS = 60 * 1000;
+const OTHER_RANK = Object.freeze({ running: 0, paused: 1, idle: 1, done: 2 });
+const fileKey = (session) => String(session).replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128);
+
+const finishedAt = (frame, live, cwd) => {
+  if (live?.state === 'ended') return Date.parse(live.at);
+  if (frame?.skill === 'start-work' && frame.ref?.plan) {
+    const plan = planProgress(cwd, frame.ref.plan);
+    if (plan && plan.total > 0 && plan.done >= plan.total && Number.isFinite(plan.mtimeMs)) return plan.mtimeMs;
+  }
+  return null;
+};
+
+function otherRows({ cwd, own, names, stacks, env, now, goal }) {
+  const others = new Map();
+  for (const name of names) {
+    const path = join(stacks, name);
+    let mtime = 0;
+    try {
+      mtime = statSync(path).mtimeMs;
+    } catch {
+      continue;
+    }
+    if (now - mtime > SIBLING_FRESH_MS) continue;
+    const top = readStackFile(path)?.frames.at(-1);
+    if (top?.stage) others.set(name.replace(/\.json$/, ''), { frame: top });
+  }
+  const root = projectKey(cwd);
+  for (const live of readLiveness(env)) {
+    if (typeof live.session !== 'string' || typeof live.cwd !== 'string' || live.session === own) continue;
+    if (projectKey(live.cwd) !== root) continue;
+    const entry = others.get(live.session);
+    if (!entry && live.state !== 'ended' && now - Date.parse(live.at) > SIBLING_FRESH_MS) continue;
+    others.set(live.session, { ...entry, live });
+  }
+  const rows = [];
+  for (const [id, { frame, live }] of [...others].sort(([a], [b]) => a.localeCompare(b))) {
+    const done = finishedAt(frame, live, cwd);
+    if (done !== null && !(now - done <= DONE_SHOW_MS)) continue;
+    const word = done !== null ? 'done' : live?.state === 'idle' ? 'idle' : 'running';
+    const route = frame ? null : readStage(stageFile(cwd, id, env))?.route;
+    const row = frame ? frameRow(frame, id, cwd, goal) : { session: id, skill: typeof route === 'string' && route ? route : 'session', stage: null, gauge: '' };
+    // The status word already says running; an unknown count adds nothing.
+    if (row.gauge === gauge(null, null)) row.gauge = '';
+    rows.push({
+      ...row,
+      status: frame?.status === 'paused' && word !== 'done' ? 'paused' : word,
+      pane: typeof live?.pane === 'string' ? live.pane : null,
+      sibling: true,
+    });
+  }
+  return rows.sort((a, b) => OTHER_RANK[a.status] - OTHER_RANK[b.status]);
+}
+
+export function threadRows({ cwd, session, env = process.env, now = Date.now() }) {
   const goal = activeGoal(cwd);
-  let dir = null;
+  const stacks = stacksDir(cwd);
+  let dir = [];
   try {
-    dir = readdirSync(join(cwd, '.litmuse', 'workflow-stack'));
-  } catch {
-    return [];
-  }
-  const own = session ? `${String(session).replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128)}.json` : null;
+    dir = readdirSync(stacks);
+  } catch { /* no stacks yet: liveness may still name other sessions */ }
+  const own = session ? fileKey(session) : null;
   const rows = [];
   if (own) {
-    const stack = readStackFile(join(cwd, '.litmuse', 'workflow-stack', own));
+    const stack = readStackFile(join(stacks, `${own}.json`));
     for (const frame of stack?.frames ?? []) {
       if (!frame.stage) continue;
       if (frame.at && now - Date.parse(frame.at) > THREAD_STALE_MS) continue;
       rows.push(frameRow(frame, session, cwd, goal));
     }
   }
-  for (const name of dir.filter((entry) => entry.endsWith('.json') && entry !== own).sort()) {
-    const path = join(cwd, '.litmuse', 'workflow-stack', name);
-    let mtime = 0;
-    try {
-      mtime = statSync(path).mtimeMs;
-    } catch {
-      continue;
-    }
-    if (now - mtime > SIBLING_FRESH_MS) continue;
-    const stack = readStackFile(path);
-    const top = stack?.frames.at(-1);
-    if (!top?.stage) continue;
-    rows.push({ ...frameRow(top, name.replace(/\.json$/, ''), cwd, goal), sibling: true });
-  }
+  const names = dir.filter((entry) => entry.endsWith('.json') && entry !== `${own}.json`);
+  rows.push(...otherRows({ cwd, own, names, stacks, env, now, goal }));
   return { rows: rows.slice(0, THREAD_CAP), omitted: Math.max(0, rows.length - THREAD_CAP) };
 }
 
+// The restart chip: the installed bundle carries a newer version than the code this session loaded at
+// SessionStart, so the hooks and skills in use are older until Muse restarts. Unknown either way: no chip.
+function restartTo(rec, env) {
+  if (typeof rec?.loadedVersion !== 'string') return null;
+  try {
+    const installed = readManifest(paths(env).stage).version;
+    return typeof installed === 'string' && newerThan(installed, rec.loadedVersion) ? installed : null;
+  } catch {
+    return null;
+  }
+}
+
 export function buildCard({ cwd, session, env = process.env, now = Date.now() }) {
   const rec = loadStage({ cwd, session, env });
   const goal = activeGoal(cwd);
-  const threads = threadRows({ cwd, session: rec?.session ?? session ?? null, now });
+  const threads = threadRows({ cwd, session: rec?.session ?? session ?? null, env, now });
   if (!rec) return { active: false, route: null, goal, plan: planProgress(cwd, null), lanes: [], threads, idle: freshStacks(cwd, now), now, noColor: Boolean(env.NO_COLOR) };
   const lanes = (rec.lanes ?? []).map((l) => ({
     id: l.id, type: l.type, status: l.status,
@@ -188,6 +253,7 @@ export function buildCard({ cwd, session, env = process.env, now = Date.now() })
     active: Boolean(rec.route), route: rec.route ?? null, keyword: rec.keyword ?? null, kind: rec.kind ?? null,
     session: rec.session ?? null, activeMs: rec.route && rec.activatedAt ? now - rec.activatedAt : null,
     plan: planProgress(cwd, rec.plan ?? null), lanes, goal, threads, idle: !rec.route && freshStacks(cwd, now), updated: rec.updated ?? null, now, noColor: Boolean(env.NO_COLOR),
+    restartTo: restartTo(rec, env),
   };
 }
 
@@ -248,14 +314,16 @@ export function renderCard(card) {
   const out = [];
   const color = !card.noColor;
   out.push(headlineFor(card, color));
+  if (card.restartTo) out.push(`restart to ${card.restartTo}: LitMuse was updated after this session loaded it`);
   if (!card.active && card.idle) out.push('idle — say `lit adhd` for the cross-session brief');
   const threads = card.threads?.rows ?? [];
   if (threads.length) {
     out.push('threads:');
     threads.forEach((thread, index) => {
       const branch = index === threads.length - 1 && !card.threads.omitted ? '└─' : '├─';
-      const where = thread.sibling ? ` (${thread.session})` : '';
-      out.push(`${branch} ${thread.skill}${thread.stage ? ` ${thread.stage}` : ''} ${thread.status} ${thread.gauge}${where}`);
+      const name = thread.pane ? `${thread.skill} · ${thread.pane}` : thread.skill;
+      const where = thread.sibling && !thread.pane ? ` (${thread.session})` : '';
+      out.push(`${branch} ${name}${thread.stage ? ` ${thread.stage}` : ''} ${thread.status}${thread.gauge ? ` ${thread.gauge}` : ''}${where}`);
     });
     if (card.threads.omitted) out.push(`+${card.threads.omitted} more`);
   }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@litfamily/litmuse",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Installer for LitMuse: skills, hooks and agents that help Meta's Muse Code plan, build, check and hand off work.",
   "keywords": [
     "muse",
@@ -47,7 +47,8 @@
     "README.md",
     "README_ko-KR.md",
     "CHANGELOG.md",
-    "LICENSE"
+    "LICENSE",
+    "TRADEMARK.md"
   ],
   "publishConfig": {
     "access": "public"

package/plugin/.muse-plugin/plugin.json

@@ -2,7 +2,7 @@
   "schemaVersion": 1,
   "name": "litmuse",
   "displayName": "LitMuse",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "LitFamily workflows for Muse Code: bare lit activation, planning, evidence-bound execution, review, research, handoff and Korean prose care.",
   "compat": {
     "source": "native",
@@ -251,7 +251,7 @@
           "node",
           "hooks/session-start.mjs",
           "--digest",
-          "11ba46df6010f4d8"
+          "aa3c8c817b3b5263"
         ],
         "timeoutMs": 5000
       },
@@ -262,7 +262,7 @@
           "node",
           "hooks/user-prompt-submit.mjs",
           "--digest",
-          "c55594062398b5ea"
+          "17cbcfe331b17df6"
         ],
         "timeoutMs": 5000,
         "statusMessage": "LitMuse route check"
@@ -274,7 +274,7 @@
           "node",
           "hooks/pre-tool-use.mjs",
           "--digest",
-          "b98a3b323bb1756c"
+          "a46607c7dd5c7dcd"
         ],
         "timeoutMs": 5000
       },
@@ -285,7 +285,7 @@
           "node",
           "hooks/post-tool-use.mjs",
           "--digest",
-          "1aae7c29d41747b8"
+          "0c70692956033463"
         ],
         "timeoutMs": 5000
       },
@@ -296,7 +296,7 @@
           "node",
           "hooks/post-tool-use-failure.mjs",
           "--digest",
-          "3f1b940d78192ff9"
+          "6904dd5da8def1dd"
         ],
         "timeoutMs": 5000
       },
@@ -307,7 +307,7 @@
           "node",
           "hooks/stop.mjs",
           "--digest",
-          "0bd9020bf0bbc1af"
+          "ffd3ec1cb2687eb2"
         ],
         "timeoutMs": 5000
       },
@@ -318,7 +318,7 @@
           "node",
           "hooks/subagent-start.mjs",
           "--digest",
-          "6694ead2b6e3ac2b"
+          "b97c259487df63c1"
         ],
         "timeoutMs": 5000
       },
@@ -329,7 +329,7 @@
           "node",
           "hooks/subagent-stop.mjs",
           "--digest",
-          "023daac9ec9f7aeb"
+          "6d4dbf1e969d4d7b"
         ],
         "timeoutMs": 5000
       },
@@ -340,7 +340,7 @@
           "node",
           "hooks/session-end.mjs",
           "--digest",
-          "18f92d375de7d7b0"
+          "b0f6069317813e37"
         ],
         "timeoutMs": 5000
       },
@@ -351,7 +351,7 @@
           "node",
           "hooks/pre-compact.mjs",
           "--digest",
-          "dfdcd29de71fafe0"
+          "c844b43a044a2533"
         ],
         "timeoutMs": 5000
       }

package/plugin/commands/lit-status.md

@@ -9,7 +9,8 @@ Print the LitMuse status card for this workspace. Scope: $ARGUMENTS (empty means
    - Route and time active: the newest record from `latest.json` (route, activatedAt, kind), or else the `route` on the last line of the newest `.litmuse/ledger/*.jsonl`.
    - Plan: the plan named in the record, or else the newest `plans/*.md`. Count `- [x] N.` against all `- [ ] N.` and `- [x] N.` rows, and name the first open row.
    - Lanes: the record's `lanes` entries with `status` running, done or failed, and their elapsed time (`endedAt` or now, minus `startedAt`).
-   - Threads: `.litmuse/workflow-stack/<session>.json` frames (paused spines above running sides) plus other sessions' fresh paused tops: a real gauge when the count is known, the `… N steps` fact line otherwise — never a placeholder. Six rows at most, then `+N more`; an idle card offers `lit adhd` instead.
+   - Threads: `.litmuse/workflow-stack/<session>.json` frames (paused spines above running sides) at the project state root (a linked worktree keeps its own), then other sessions of this project from their fresh stack tops and their liveness records (`stage/liveness/<session>.json`: `alive`, `idle`, `ended`). Other sessions read `running`, `idle` or `done`, running first; a session that ended or whose start-work plan is fully ticked reads `done` for one minute, then leaves; a session in a herdr pane is named `<skill> · <pane>`; a lone other session still gets its row. A real gauge when the count is known, the `… N steps` fact line otherwise — never a placeholder. Six rows at most, then `+N more`; an idle card offers `lit adhd` instead.
+   - Restart chip: when the installed bundle (`$XDG_DATA_HOME/litmuse/bundle/.muse-plugin/plugin.json`) is newer than the `loadedVersion` SessionStart recorded, add `restart to <version>`; when either is unknown, add nothing.
    - Goal: each `.litmuse/goals/*.json` whose status is `active`, with its objective and the criteria that are not `pass`.
 3. Add the first lines of `.litmuse/handoff/latest.md` if present, and the count of tool events and failures in the newest ledger.
 

package/plugin/hooks/lib/next-step.mjs

@@ -1,9 +1,10 @@
-// The `go` half of the lit-adhd brief: the collector writes this session's next-step record
-// under `.litmuse/adhd/`, and a later whole-prompt `go` reads it back and deletes it. The session
+// The `go` half of the lit-adhd brief and of a saved lit-plan: the collector (or the Stop hook,
+// for a plan) writes this session's next-step record under `.litmuse/adhd/`, and a later
+// whole-prompt `go` reads it back and deletes it. The session
 // binding is the file name, so another session's record is never opened. A step older than 30
 // minutes is stale: the brief it came from no longer describes the work.
-import { closeSync, constants, fstatSync, openSync, readFileSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeSync } from 'node:fs';
+import { dirname, join } from 'node:path';
 
 import { workspaceOf } from './common.mjs';
 import { resolveProjectStateRoot } from './workflow-stack.mjs';
@@ -20,6 +21,49 @@ const nextStepFile = (cwd, sessionId) => {
   return join(resolveProjectStateRoot(cwd), '.litmuse', 'adhd', `next-${id}.json`);
 };
 
+const PLAN_NAME = /^plans\/[A-Za-z0-9._-]+\.md$/u;
+
+// `.litmuse` and `.litmuse/adhd` must be real folders (or not there yet): a linked one would carry
+// the record out of the project.
+const realDirs = (root, dir) => {
+  for (const part of [join(root, '.litmuse'), dir]) {
+    try {
+      if (!lstatSync(part).isDirectory()) return false;
+    } catch { /* absent: mkdir makes a real one */ }
+  }
+  mkdirSync(dir, { recursive: true });
+  return !lstatSync(join(root, '.litmuse')).isSymbolicLink() && !lstatSync(dir).isSymbolicLink();
+};
+
+/**
+ * The lit-plan half of `go`: once a planning turn has saved `plans/<slug>.md`, records it as this
+ * session's `start-plan` step, so a whole-prompt `go` within 30 minutes starts start-work on it.
+ * Plan names outside `plans/<slug>.md` and linked state folders write nothing. Never throws.
+ */
+export const putNextStep = (payload, plan, now = Date.now()) => {
+  const sessionId = typeof payload?.session_id === 'string' && payload.session_id ? payload.session_id : null;
+  if (!sessionId || typeof plan !== 'string' || !PLAN_NAME.test(plan) || /[\r\n]/u.test(plan)) return null;
+  try {
+    const cwd = workspaceOf(payload);
+    const path = nextStepFile(cwd, sessionId);
+    if (!realDirs(resolveProjectStateRoot(cwd), dirname(path))) return null;
+    const staging = `${path}.${process.pid}.tmp`;
+    try {
+      unlinkSync(staging);
+    } catch { /* no leftover */ }
+    const fd = openSync(staging, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0), 0o600);
+    try {
+      writeSync(fd, `${JSON.stringify({ kind: 'start-plan', target: { plan }, at: new Date(now).toISOString() })}\n`);
+    } finally {
+      closeSync(fd);
+    }
+    renameSync(staging, path);
+    return path;
+  } catch {
+    return null;
+  }
+};
+
 /**
  * Reads and deletes this session's next-step record. Returns `{kind, target}` when the record is
  * whole and at most 30 minutes old, otherwise null; a stale or unreadable record is deleted all

package/plugin/hooks/lib/stage.mjs

@@ -1,4 +1,4 @@
-import { readFileSync, writeFileSync, mkdirSync, lstatSync, renameSync, realpathSync } from 'node:fs';
+import { readFileSync, writeFileSync, mkdirSync, lstatSync, renameSync, realpathSync, readdirSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { homedir } from 'node:os';
 import { createHash } from 'node:crypto';
@@ -66,8 +66,9 @@ export function readStage(file) {
   }
 }
 
-// mutate(record) returns the next record (or nothing to keep it). Never throws.
-export function updateStage(payload, mutate, env = process.env) {
+// mutate(record) returns the next record (or nothing to keep it). Never throws. `pointer: false` leaves
+// `latest.json` alone, for writes that say nothing about which session the user is driving.
+export function updateStage(payload, mutate, env = process.env, { pointer = true } = {}) {
   try {
     const cwd = workspaceOf(payload);
     const file = stageFile(cwd, payload.session_id, env);
@@ -83,9 +84,10 @@ export function updateStage(payload, mutate, env = process.env) {
     next.lanes = next.lanes.slice(-MAX_LANES);
     for (const k of ['route', 'keyword', 'plan', 'kind']) if (k in next) next[k] = clip(next[k]);
     if (!atomicWrite(file, next)) return false;
-    const pointer = readStage(latestFile(env)) ?? {};
-    pointer[next.workspace] = { session: payload.session_id, updated: now };
-    atomicWrite(latestFile(env), pointer);
+    if (!pointer) return true;
+    const latest = readStage(latestFile(env)) ?? {};
+    latest[next.workspace] = { session: payload.session_id, updated: now };
+    atomicWrite(latestFile(env), latest);
     return true;
   } catch {
     return false;
@@ -141,6 +143,51 @@ export function recordLaneStop(payload, env = process.env) {
   }, env);
 }
 
+// Liveness: each session's last hook event as one small record, `stage/liveness/<session>.json`, apart from the
+// stage record so a tool call never rewrites `latest.json`. PostToolUse and its failure twin say `alive`, Stop says
+// `idle`, SessionEnd says `ended`. The card reads these to sort other sessions into running, idle and gone. A
+// repeat of the same state inside 30 s writes nothing, so a busy session costs one write per half minute.
+export const LIVENESS_STATES = Object.freeze(['alive', 'idle', 'ended']);
+const LIVENESS_REPEAT_MS = 30_000;
+// A herdr pane id is short and plain (`w2B:p3`); anything else is dropped rather than stored.
+const PANE_ID = /^[A-Za-z0-9][A-Za-z0-9:_-]{0,31}$/;
+
+export function livenessDir(env = process.env) {
+  return join(stageRoot(env), 'liveness');
+}
+
+export function readLiveness(env = process.env) {
+  try {
+    return readdirSync(livenessDir(env)).filter((n) => n.endsWith('.json')).map((n) => readStage(join(livenessDir(env), n))).filter(Boolean);
+  } catch {
+    return [];
+  }
+}
+
+export function markLiveness(payload, state, { env = process.env, now = Date.now() } = {}) {
+  try {
+    const id = safeId(payload?.session_id);
+    if (!id || !LIVENESS_STATES.includes(state)) return false;
+    const root = stageRoot(env);
+    const dir = livenessDir(env);
+    if (isLink(root) || !safeDir(dir)) return false;
+    const file = join(dir, `${id}.json`);
+    const prev = isLink(file) ? null : readStage(file);
+    if (prev && prev.state === state && now - Date.parse(prev.at) < LIVENESS_REPEAT_MS) return false;
+    const cwd = workspaceOf(payload);
+    const pane = typeof env.HERDR_PANE_ID === 'string' && PANE_ID.test(env.HERDR_PANE_ID) ? env.HERDR_PANE_ID : null;
+    return atomicWrite(file, { version: 1, session: id, state, at: new Date(now).toISOString(), cwd, workspace: workspaceHash(cwd), pane });
+  } catch {
+    return false;
+  }
+}
+
+// The plugin version this session's hooks and skills were loaded from, for the card's restart chip.
+export function recordLoadedVersion(payload, version, env = process.env) {
+  if (typeof version !== 'string' || !/^\d+\.\d+\.\d+/.test(version)) return false;
+  return updateStage(payload, (rec) => ({ ...rec, loadedVersion: version }), env, { pointer: false });
+}
+
 export function recordSessionEnd(payload, env = process.env) {
   return updateStage(payload, (rec, now) => {
     rec.route = null;

package/plugin/hooks/lib/workflow-stack.mjs

@@ -8,7 +8,7 @@
 // file per session, whole, and the status card reads it back through its own guarded read. Frames
 // keep skills, stages and counts only; never a prompt, a command or a path other than a
 // project-relative plan name.
-import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, renameSync, writeFileSync, existsSync } from 'node:fs';
+import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, readSync, realpathSync, renameSync, writeFileSync, existsSync } from 'node:fs';
 import { basename, dirname, join, resolve } from 'node:path';
 
 export const MAX_FRAMES = 3;
@@ -239,19 +239,37 @@ export const applyStackEvent = (stack, event, now = new Date()) => {
 };
 
 // State placement: the outermost git root owns `.litmuse`, so a nested package shares its
-// parent's state; without git the workspace itself owns it.
+// parent's state; without git the workspace itself owns it. A linked worktree (its `.git` is a
+// file) is its own root: the climb stops there, so its state never lands in the main checkout.
+// Every reader and writer of `.litmuse` resolves through this one function.
 export const resolveProjectStateRoot = (startDir = process.cwd()) => {
   const start = resolve(startDir);
   let root = null;
   let current = start;
   for (;;) {
-    if (existsSync(join(current, '.git'))) root = current;
+    const git = join(current, '.git');
+    if (existsSync(git)) {
+      root = current;
+      try {
+        if (!lstatSync(git).isDirectory()) return root;
+      } catch { /* vanished between checks: keep climbing */ }
+    }
     const parent = dirname(current);
     if (parent === current) return root ?? start;
     current = parent;
   }
 };
 
+// The project a recorded cwd belongs to, for comparing records: links resolved first, so a session
+// that reached the project through a symlinked path (`/var` vs `/private/var`) is the same project.
+export const projectKey = (dir) => {
+  let real = resolve(dir);
+  try {
+    real = realpathSync(real);
+  } catch { /* gone or unreadable: compare as written */ }
+  return resolveProjectStateRoot(real);
+};
+
 const fileName = (sessionId) => `${String(sessionId ?? 'session').replace(/[^A-Za-z0-9_-]/gu, '_').slice(0, 128) || 'session'}.json`;
 
 export const stackPath = (cwd, sessionId) => join(resolveProjectStateRoot(cwd), '.litmuse', 'workflow-stack', fileName(sessionId));

package/plugin/hooks/post-tool-use-failure.mjs

@@ -1,6 +1,8 @@
 import { run, activeRoute, appendLedger, toolName, toolInput } from './lib/common.mjs';
+import { markLiveness } from './lib/stage.mjs';
 
 run((payload) => {
+  markLiveness(payload, 'alive');
   const state = activeRoute(payload);
   if (!state) return;
   appendLedger(payload, {

package/plugin/hooks/post-tool-use.mjs

@@ -4,6 +4,7 @@ import { pathToFileURL } from 'node:url';
 import { run, activeRoute, appendLedger, emitContext, toolName, toolInput, workspaceOf, PLUGIN_ROOT } from './lib/common.mjs';
 import { extractAddedComments } from './lib/added-comments.mjs';
 import { MOTION_ROUTE, recordMotionTool } from './lib/motion.mjs';
+import { markLiveness } from './lib/stage.mjs';
 
 const FILE_TOOLS = new Set(['write_file', 'edit_file', 'apply_patch']);
 const PROSE_FILE = /\.(md|mdx|markdown|txt)$/i;
@@ -82,6 +83,7 @@ async function proseBlock(tool, input, cwd) {
 }
 
 run((payload) => {
+  markLiveness(payload, 'alive');
   postWrite(payload).catch(() => {});
 });
 

package/plugin/hooks/session-end.mjs

@@ -1,8 +1,9 @@
 import { run, readSession, writeSession, appendLedger } from './lib/common.mjs';
-import { recordSessionEnd } from './lib/stage.mjs';
+import { markLiveness, recordSessionEnd } from './lib/stage.mjs';
 
 run((payload) => {
   recordSessionEnd(payload);
+  markLiveness(payload, 'ended');
   const state = readSession(payload);
   if (!state) return;
   if (state.route) appendLedger(payload, { event: 'SessionEnd', route: state.route });