@litfamily/litopencode 1.0.21 → 1.0.22

package/CHANGELOG.md

@@ -5,6 +5,14 @@ are tracked separately from this product history.
 
 ## Unreleased
 
+## 1.0.22 - 2026-10-13
+
+- The LIT card, the chip beside the prompt and the sidebar now show where you are in the workflow, not only which skill ran. A map runs `interview › plan › work › review › done` and lights the step you are on with its count, such as `WORK 3/7` while `/start-work` works through a saved plan. A lit-loop goal counts its criteria instead (`CRITERION 1/3`), and a litresearch run follows its own steps from `decompose` through each `wave` to `synthesis`. A step the request went past without doing shows `–`. The sidebar draws the map top to bottom with a line that fills as you move forward.
+- While a tool runs, its name and running time sit beside the map, like `⠹ bash · 0:48`. Only the tool's name and start time are read, never its command or arguments, and the step disappears when the turn ends.
+- A finished mission can now tell you so. Add `{ "notify": true }` to the LitOpenCode entry in `tui.json` for a desktop notification and the `done` sound, or turn either one off with `{ "notify": { "sound": false } }` or `{ "notify": { "desktop": false } }`. It is off until you add it, and OpenCode plays nothing unless its own `"attention": { "enabled": true }` is set too.
+- The README pictures of the status card are new captures from OpenCode showing the workflow map, the live tool step and the card after the turn, in English and Korean.
+- A lit-loop turn shows its criteria even when the agent writes `goals.json` by hand, as one goal at the top or nested under `goal`, with `completed` or `done` counted as passed. A goal marked complete by hand passed no gate, so review stays at `–`; only a goal completed through the ledger, whose gate includes review, marks it done. In the criterion view the card leaves out the separate criteria count, so the live step keeps its room on the row.
+
 ## 1.0.21 - 2026-10-12
 
 - The README demo on GitHub is a new film of one real OpenCode turn. It plays without music, and a numbered label names each part LitOpenCode adds as it appears: the `lit` word, the status card switching to WORK, the light mode for a small fix, the reply that reads before editing, the fix with its test, the real test run and the closing summary.

package/README-Ko-KR.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/cover-motion.webp" width="100%" alt="LitFamily 모션 커버: 다섯 로봇 패널이 차례로 켜지고, LitOpenCode 로봇의 눈과 테두리가 빛난 뒤 LITFAMILY와 KEEP THE WORK LIT. 문구가 밝아지는 영상" /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode는 OpenCode용 워크플로 플러그인입니다. 프롬프트에 `lit`만 붙이면 계획하고, 만들고, 확인하고, 기록까지 남겨서 다음 세션이 어디서 멈췄는지 바로 압니다.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/badge-version.svg" alt="1.0.21" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/badge-version.svg" alt="1.0.22" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="월간 npm 다운로드 수" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/badge-license.svg" alt="MIT 라이선스" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub 스타" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## 더 보기
 
 - [GitHub의 사용 안내](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide-Ko-KR.md): 설치 옵션, 자동 인수인계, 문제 해결, 제거
-- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/reference.md)
-- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/privacy.md)
-- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/LICENSE) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [워크플로 상세 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/reference-Ko-KR.md) · [English reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/reference.md)
+- [마이그레이션 안내](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/CHANGELOG.md) · [개인정보와 네트워크 동작](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/privacy.md)
+- [LitFamily 허브](https://github.com/wjgoarxiv/litfamily) · [MIT 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/LICENSE) · [ASCII 글꼴 라이선스](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>ASCII 로고 복사</summary>

package/README.md

@@ -1,13 +1,13 @@
-<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
+<p align="center"><picture><source media="(prefers-reduced-motion: reduce)" srcset="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/cover-motion-still.webp" /><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/cover-motion.webp" width="100%" alt="LitFamily motion cover: five armored robots power on one by one, the LitOpenCode robot wakes with glowing eyes and a lit frame, then LITFAMILY and KEEP THE WORK LIT. light up." /></picture></p>
 
 # LitOpenCode
 
 **LitOpenCode is a workflow plugin for OpenCode. Add `lit` to a prompt and the work gets planned, built, checked and written down, so the next session knows where you stopped.**
 
 <p align="center">
-<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/badge-version.svg" alt="1.0.21" /></a>
+<a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/badge-version.svg" alt="1.0.22" /></a>
 <a href="https://www.npmjs.com/package/@litfamily/litopencode"><img src="https://img.shields.io/npm/dm/@litfamily/litopencode?label=downloads&color=D7F75B" alt="npm downloads per month" /></a>
-<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
+<a href="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/LICENSE"><img src="https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/badge-license.svg" alt="MIT license" /></a>
 <a href="https://github.com/wjgoarxiv/litopencode"><img src="https://img.shields.io/github/stars/wjgoarxiv/litopencode?style=social" alt="GitHub stars" /></a>
 </p>
 
@@ -57,9 +57,9 @@ npm uninstall -g @litfamily/litopencode
 ## More
 
 - [Guide on GitHub](https://github.com/wjgoarxiv/litopencode/blob/main/docs/guide.md): install options, automatic handoff, troubleshooting and removal.
-- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/reference.md)
-- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/privacy.md)
-- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/LICENSE) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.21/docs/assets/readme/JetBrainsMono-OFL.txt)
+- [Workflow reference](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/reference.md)
+- [Migration notes](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/migration.md) · [Changelog](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/CHANGELOG.md) · [Privacy and network behavior](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/privacy.md)
+- [LitFamily hub](https://github.com/wjgoarxiv/litfamily) · [MIT license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/LICENSE) · [ASCII font license](https://cdn.jsdelivr.net/npm/@litfamily/litopencode@1.0.22/docs/assets/readme/JetBrainsMono-OFL.txt)
 
 <details>
 <summary>Copy ASCII logo</summary>

package/dist/tui/mission-band.d.ts

@@ -11,6 +11,17 @@ export type BandOptions = {
  * `band: { card: true }` adds the detail card under the status card. Anything else keeps the defaults.
  */
 export declare function readBandOptions(options: unknown): BandOptions;
+export type NotifyOptions = {
+    readonly enabled: boolean;
+    readonly desktop: boolean;
+    readonly sound: boolean;
+};
+/**
+ * Reads the finish alert switch from the plugin's tui.json options. It is off unless `notify` is true
+ * (desktop notification and the host's `done` sound) or an object that turns either part off with
+ * `desktop: false` or `sound: false`.
+ */
+export declare function readNotifyOptions(options: unknown): NotifyOptions;
 /**
  * The skill chips row, exactly `width` cells: bright accent pills for the current request first, then
  * dim recent names, and `+N` for the ones that do not fit. The label goes before any chip does.

package/dist/tui/mission-band.js

@@ -4,8 +4,8 @@
 // It reuses the chip's pills, the panel's bar and the shared motion frame, so the chip, the panel and
 // the band always move together.
 import { ease, mixHex, motionTiming, seg } from "./mission-motion.js";
-import { contextWarnPercent, missionStatus } from "./mission-model.js";
-import { cellWidth, chipSparkCells, chipSparkWidth, fade, lineWidth, missionPanel, progressBar, shimmerAt, shine, statusSegments, stepPill, truncateCells } from "./mission-text.js";
+import { contextWarnPercent, currentStepIndex, missionStatus, stepName } from "./mission-model.js";
+import { cellWidth, chipSparkCells, chipSparkWidth, crumb, fade, lineWidth, linkColor, liveSegments, missionPanel, progressBar, shimmerAt, shine, stageFlash, statusSegments, truncateCells } from "./mission-text.js";
 /**
  * Reads the band switches from the plugin's tui.json options: `band: false` turns the band off,
  * `band: { card: true }` adds the detail card under the status card. Anything else keeps the defaults.
@@ -17,12 +17,31 @@ export function readBandOptions(options) {
     const card = typeof band === "object" && band !== null && band.card === true;
     return { enabled: true, card };
 }
+/**
+ * Reads the finish alert switch from the plugin's tui.json options. It is off unless `notify` is true
+ * (desktop notification and the host's `done` sound) or an object that turns either part off with
+ * `desktop: false` or `sound: false`.
+ */
+export function readNotifyOptions(options) {
+    const notify = typeof options === "object" && options !== null ? options.notify : undefined;
+    if (notify === true)
+        return { enabled: true, desktop: true, sound: true };
+    if (typeof notify !== "object" || notify === null)
+        return { enabled: false, desktop: false, sound: false };
+    const record = notify;
+    const desktop = record.desktop !== false;
+    const sound = record.sound !== false;
+    return { enabled: desktop || sound, desktop, sound };
+}
 const minimumText = 12;
 function elapsedText(minutes) {
     const total = Math.max(0, minutes ?? 0);
     return total < 60 ? `${total}m` : `${Math.floor(total / 60)}h${String(total % 60).padStart(2, "0")}`;
 }
-/** The text after the bar: a warning (⚑ and words) replaces the next task; a finished mission shows COMPLETE. */
+/**
+ * The text after the bar: a warning (⚑ and words) replaces the live step and the next task; a finished
+ * mission shows COMPLETE. Otherwise the live step, then the next task when it still has room.
+ */
 function trailing(view, frame, palette, room) {
     if (view.complete) {
         // Before COMPLETE pops in, the slot stays empty rather than flashing the header's "● active".
@@ -37,9 +56,12 @@ function trailing(view, frame, palette, room) {
         const color = warning.kind === "retry" ? mixHex(palette.warning, palette.error, 0.5) : palette.warning;
         return [{ text: "  ⚑ ", fg: color, bold: true }, { text: truncateCells(warning.text, room - 4), fg: color }];
     }
-    if (view.next === undefined)
-        return [];
-    return [{ text: "  ▸ ", fg: palette.muted }, { text: truncateCells(view.next, room - 4), fg: palette.text }];
+    const live = liveSegments(view, frame, palette, Math.min(28, room - 2));
+    const lead = live.length === 0 ? [] : [{ text: "  ", fg: palette.muted }, ...live];
+    const left = room - lineWidth(lead);
+    if (view.next === undefined || left < minimumText)
+        return lead;
+    return [...lead, { text: "  ▸ ", fg: palette.muted }, { text: truncateCells(view.next, left - 4), fg: palette.text }];
 }
 /** Cuts or pads a line to exactly `width` cells, keeping wide glyphs whole. */
 function fitLine(line, width, palette) {
@@ -105,7 +127,7 @@ function phaseLabel(view, frame, palette, rest) {
         return { text: "✓ COMPLETE", fg: palette.success, bold: true };
     if (status.tone === "warning")
         return { text: `⚑ ${status.text}`, fg: mixHex(palette.info, palette.warning, Math.max(frame.warn, 0.5)), bold: true };
-    return { text: `● ${view.phase.toUpperCase()}`, fg: palette.info, bold: true };
+    return { text: `● ${stepName(view.phase, view).toUpperCase()}`, fg: palette.info, bold: true };
 }
 function topLine(view, frame, palette, width, border, rest) {
     const brand = [{ text: "🔥 ", fg: palette.text }, { text: "LIT", fg: shine(palette.primary, palette, 0.5, shimmerAt(frame), 0.6), bold: true }];
@@ -148,17 +170,22 @@ function bottomLine(view, figures, palette, width, border) {
     }
     return fitLine([{ text: "╰" + "─".repeat(Math.max(0, width)), fg: border }], width, palette);
 }
+/** The whole stage map as a breadcrumb, `plan ✓ ━ WORK 1/3 ─ review ─ done`, or only the running stage when tight. */
 function trackPills(view, frame, palette, tight) {
     const alpha = (index) => (frame.chipEnter ? ease.outCubic(seg(frame.t, index * motionTiming.stagger, motionTiming.entry)) : 1);
-    if (tight) {
-        const current = view.steps.find((step) => step.state === "now" || step.state === "warn") ?? view.steps[view.complete ? 2 : view.active ? 1 : 0];
-        return [fade(stepPill(current, view, frame, palette), alpha(0), palette)];
-    }
+    const reached = currentStepIndex(view);
+    const current = Math.min(view.steps.length - 1, Math.max(0, reached));
+    const flash = stageFlash(frame);
+    if (tight)
+        return crumb(view, current, frame, palette, 0, flash).map((segment) => fade(segment, alpha(0), palette));
     const out = [];
-    view.steps.forEach((step, index) => {
-        if (index > 0)
-            out.push(fade({ text: " ━ ", fg: view.steps[index - 1].state === "done" ? palette.success : palette.borderSubtle }, alpha(index), palette));
-        out.push(fade(stepPill(step, view, frame, palette), alpha(index), palette));
+    view.steps.forEach((_step, index) => {
+        if (index > 0) {
+            const color = linkColor(view, index, frame, palette, palette.borderSubtle);
+            out.push(fade({ text: color === palette.borderSubtle ? " ─ " : " ━ ", fg: color }, alpha(index), palette));
+        }
+        for (const segment of crumb(view, index, frame, palette, 0, index === current && reached >= 0 ? flash : -1))
+            out.push(fade(segment, alpha(index), palette));
     });
     return out;
 }
@@ -186,7 +213,8 @@ function trackRow(view, frame, palette, width, last) {
     for (const plan of trackPlans) {
         const pills = trackPills(view, frame, palette, plan.tight);
         const bar = plan.bar > 0 && view.progress !== undefined ? [gap, ...progressBar(frame.barRatio, plan.bar, palette, sweep)] : [];
-        const goal = view.goal;
+        // In the criterion loop the stage itself counts criteria, so the count is not repeated.
+        const goal = view.family === "loop" ? undefined : view.goal;
         const criteria = plan.criteria && goal !== undefined ? [gap, { text: `${goal.passed}/${goal.total} criteria`, fg: goal.total > 0 && goal.passed === goal.total ? palette.success : palette.muted }] : [];
         const fixed = lineWidth(pills) + lineWidth(bar) + lineWidth(criteria);
         if (fixed > width)

package/dist/tui/mission-model.d.ts

@@ -9,6 +9,34 @@ export type TodoInput = {
     readonly content: string;
     readonly status: string;
 };
+/** The plan file's `- [ ]` / `- [x]` rows: how many are ticked, how many exist, and the first open one. */
+export type PlanChecklist = {
+    readonly done: number;
+    readonly total: number;
+    readonly next?: string;
+};
+/** This session's bounded work from work-schema-3.json: its status, recorded progress turns and plan. */
+export type WorkInput = {
+    readonly status: string;
+    readonly iterations: number;
+    readonly plan?: PlanChecklist;
+};
+export type ResearchStage = "decompose" | "wave" | "expand" | "verify" | "synthesis";
+/** The latest litresearch run folder: what its journal, claim graph and report say so far. */
+export type ResearchInput = {
+    readonly stage: ResearchStage;
+    readonly waves: number;
+    readonly claims: number;
+    readonly verified: number;
+    readonly reported: boolean;
+    /** Last write to the run folder, in ms; a run older than the session's first lit turn is earlier work. */
+    readonly touchedAt: number;
+};
+/** The tool the session is running now: its name and start time only, never its input. */
+export type LiveStep = {
+    readonly tool: string;
+    readonly start: number;
+};
 export type MissionInput = {
     readonly marks: readonly LitMark[];
     readonly agent?: string;
@@ -19,9 +47,17 @@ export type MissionInput = {
     readonly pendingPermissions?: number;
     readonly pendingQuestions?: number;
     readonly contextPercent?: number | null;
+    readonly work?: WorkInput;
+    readonly research?: ResearchInput;
+    readonly live?: LiveStep;
     readonly now: number;
 };
-export type StepId = "plan" | "work" | "review";
+/**
+ * Which stage table the map follows: the main chain, lit-loop's criterion loop (the same stages with
+ * the work stage counting criteria), or a litresearch run.
+ */
+export type MissionFamily = "main" | "loop" | "research";
+export type StepId = "interview" | "plan" | "work" | "review" | "done" | ResearchStage;
 export type StepState = "done" | "skip" | "now" | "todo" | "warn";
 export type MissionStep = {
     readonly id: StepId;
@@ -50,13 +86,22 @@ export type MissionEvent = {
 export type MissionView = {
     readonly active: boolean;
     readonly discipline: string;
-    readonly phase: StepId | "done";
+    readonly family: MissionFamily;
+    readonly phase: StepId;
     readonly steps: readonly MissionStep[];
     readonly progress?: {
         readonly done: number;
         readonly total: number;
     };
     readonly next?: string;
+    /** The lead of the detail line: `task 3`, or a research run's claim counts. */
+    readonly detail?: string;
+    /** Recorded turns of the current loop: bounded work progress, or lit-loop goal checkpoints. */
+    readonly iteration?: number;
+    /** How many tasks the saved plan holds, shown beside the plan stage. */
+    readonly planTasks?: number;
+    readonly wave?: number;
+    readonly live?: LiveStep;
     readonly goal?: MissionGoal;
     readonly blockers: readonly {
         readonly id: string;
@@ -77,9 +122,28 @@ export type MissionNotice = {
     readonly celebrate?: boolean;
 };
 export declare const contextWarnPercent = 75;
+export declare const familySteps: Readonly<Record<MissionFamily, readonly StepId[]>>;
 export declare const idleMission: MissionView;
 /** Reads one part's `metadata.litopencode` mark. Anything without that shape is not a mark. */
 export declare function readLitMark(metadata: unknown, at: number): LitMark | undefined;
+/** The name a stage shows: the loop counts criteria at its work stage and a research wave carries its number. */
+export declare function stepName(id: StepId, view: Pick<MissionView, "family" | "wave">): string;
+/** Index of the stage that is running (or flagged); the step count once complete; -1 while idle. */
+export declare function currentStepIndex(view: Pick<MissionView, "steps" | "complete" | "active">): number;
+/**
+ * Counts a plan's checkbox rows at column zero (`- [ ] 1. title — …`). The first open row, cut at its
+ * em dash, becomes the next item. Indented rows are not tasks.
+ */
+export declare function planChecklist(text: string): PlanChecklist | undefined;
+/**
+ * Lenient read of work-schema-3.json for one session: undefined when it is absent, another session's,
+ * cancelled, or not the schema-3 shape. Iterations count the recorded `work.progressed` turns.
+ */
+export declare function readWorkState(raw: unknown, sessionID: string): {
+    readonly status: string;
+    readonly iterations: number;
+    readonly planPath: string;
+} | undefined;
 type LedgerCriterion = {
     readonly id: string;
     readonly scenario: string;
@@ -106,8 +170,10 @@ type LedgerGoal = {
         readonly resolved: boolean;
         readonly needsUserDecision: boolean;
     }[];
+    /** Written by the ledger CLI, whose completion gate checks evidence; a hand-written goal passed none. */
+    readonly gated: boolean;
 };
-/** Lenient read of goals.json: the active goal, or undefined when the file is absent or not the ledger shape. */
+/** Lenient read of goals.json: the goal it names, or undefined when there is none. */
 export declare function readActiveGoal(raw: unknown): LedgerGoal | undefined;
 export declare function formatAgo(at: string, now: number): string;
 export declare function buildMissionView(input: MissionInput): MissionView;

package/dist/tui/mission-model.js

@@ -1,19 +1,22 @@
 // The mission view model for the OpenCode TUI. It reads only what LitOpenCode already leaves behind:
 // the `metadata.litopencode` marks the plugin attaches to user-message parts on activation and on
-// commands, the host todo list, and the evidence ledger in .litopencode/litgoal/lit-loop/goals.json.
-// No new state is written for the TUI.
+// commands, the host todo list and running tool, the evidence ledger in
+// .litopencode/litgoal/lit-loop/goals.json, the bounded work record work-schema-3.json with its plan
+// checklist, and litresearch run folders. No new state is written for the TUI.
 export const contextWarnPercent = 75;
 const timelineLimit = 4;
 const staleGoalSlackMs = 60_000;
+export const familySteps = Object.freeze({
+    main: Object.freeze(["interview", "plan", "work", "review", "done"]),
+    loop: Object.freeze(["interview", "plan", "work", "review", "done"]),
+    research: Object.freeze(["decompose", "wave", "expand", "verify", "synthesis"])
+});
 export const idleMission = Object.freeze({
     active: false,
     discipline: "",
+    family: "main",
     phase: "plan",
-    steps: Object.freeze([
-        { id: "plan", state: "todo" },
-        { id: "work", state: "todo" },
-        { id: "review", state: "todo" }
-    ]),
+    steps: Object.freeze(familySteps.main.map((id) => Object.freeze({ id, state: "todo" }))),
     blockers: Object.freeze([]),
     warnings: Object.freeze([]),
     timeline: Object.freeze([]),
@@ -46,29 +49,108 @@ export function readLitMark(metadata, at) {
 function stepOf(name) {
     if (name === "")
         return undefined;
+    if (name === "deep-interview" || name.endsWith("-interview"))
+        return "interview";
     if (name === "review-work" || name.includes("review"))
         return "review";
-    if (name === "lit-plan" || name.endsWith("-plan") || name === "lit-crucible" || name === "deep-interview")
+    if (name === "lit-plan" || name.endsWith("-plan") || name === "lit-crucible")
         return "plan";
     return "work";
 }
-/** Lenient read of goals.json: the active goal, or undefined when the file is absent or not the ledger shape. */
+function isResearchName(name) {
+    return name === "litresearch" || name === "lit-research";
+}
+/** The name a stage shows: the loop counts criteria at its work stage and a research wave carries its number. */
+export function stepName(id, view) {
+    if (id === "work" && view.family === "loop")
+        return "criterion";
+    if (id === "wave")
+        return `wave ${Math.max(1, view.wave ?? 1)}`;
+    return id;
+}
+/** Index of the stage that is running (or flagged); the step count once complete; -1 while idle. */
+export function currentStepIndex(view) {
+    if (!view.active)
+        return -1;
+    const index = view.steps.findIndex((step) => step.state === "now" || step.state === "warn");
+    return index >= 0 ? index : view.complete ? view.steps.length : -1;
+}
+/**
+ * Counts a plan's checkbox rows at column zero (`- [ ] 1. title — …`). The first open row, cut at its
+ * em dash, becomes the next item. Indented rows are not tasks.
+ */
+export function planChecklist(text) {
+    let done = 0;
+    let total = 0;
+    let next;
+    for (const line of text.split(/\r?\n/u)) {
+        const match = /^- \[( |x|X)\] +(.*)$/u.exec(line);
+        if (match === null)
+            continue;
+        total += 1;
+        if (match[1] !== " ")
+            done += 1;
+        else if (next === undefined)
+            next = match[2].split(" — ")[0].trim();
+    }
+    if (total === 0)
+        return undefined;
+    return { done, total, ...(next === undefined || next === "" ? {} : { next }) };
+}
+/**
+ * Lenient read of work-schema-3.json for one session: undefined when it is absent, another session's,
+ * cancelled, or not the schema-3 shape. Iterations count the recorded `work.progressed` turns.
+ */
+export function readWorkState(raw, sessionID) {
+    if (!isRecord(raw) || raw.schemaVersion !== 3 || raw.sessionID !== sessionID)
+        return undefined;
+    const status = text(raw.status);
+    if (status === "" || status === "cancelled")
+        return undefined;
+    const history = Array.isArray(raw.history) ? raw.history.filter(isRecord) : [];
+    const plan = isRecord(raw.plan) ? text(raw.plan.path) : "";
+    return { status, iterations: history.filter((entry) => entry.type === "work.progressed").length, planPath: plan };
+}
+// The ledger CLI accepts `passed`, `failed` and `completed` as spellings of its own statuses; a goals.json
+// the agent writes by hand also marks a finished criterion `completed` or `done`.
+const criterionStatusSpellings = { passed: "pass", completed: "pass", complete: "pass", done: "pass", failed: "fail" };
+const goalStatusSpellings = { completed: "complete", done: "complete" };
+/**
+ * Picks the goal out of goals.json: the ledger's active goal, else what an agent writes by hand —
+ * a goal nested under `goal`, the last entry of a `goals` list, or one goal object at the top.
+ */
+function pickGoal(raw) {
+    const hasCriteria = (value) => isRecord(value) && Array.isArray(value.criteria);
+    if (Array.isArray(raw.goals)) {
+        if (raw.activeGoalId !== undefined) {
+            const active = raw.goals.find((candidate) => isRecord(candidate) && candidate.id === raw.activeGoalId);
+            return isRecord(active) ? active : undefined;
+        }
+        return raw.goals.filter(hasCriteria).at(-1);
+    }
+    if (hasCriteria(raw.goal))
+        return raw.goal;
+    return hasCriteria(raw) ? raw : undefined;
+}
+/** Lenient read of goals.json: the goal it names, or undefined when there is none. */
 export function readActiveGoal(raw) {
-    if (!isRecord(raw) || !Array.isArray(raw.goals))
+    if (!isRecord(raw))
         return undefined;
-    const goal = raw.goals.find((candidate) => isRecord(candidate) && candidate.id === raw.activeGoalId);
-    if (!isRecord(goal))
+    const goal = pickGoal(raw);
+    if (goal === undefined)
         return undefined;
     const list = (value) => (Array.isArray(value) ? value.filter(isRecord) : []);
+    const status = text(goal.status);
     return {
+        gated: goal !== raw && Array.isArray(raw.goals) && raw.activeGoalId !== undefined,
         title: text(goal.title) || text(goal.objective),
-        status: text(goal.status),
+        status: goalStatusSpellings[status] ?? status,
         createdAt: text(goal.createdAt),
         updatedAt: text(goal.updatedAt),
         criteria: list(goal.criteria).map((criterion) => ({
             id: text(criterion.id),
             scenario: text(criterion.scenario),
-            status: text(criterion.status),
+            status: criterionStatusSpellings[text(criterion.status)] ?? text(criterion.status),
             evidence: list(criterion.evidence).map((entry) => ({ kind: text(entry.kind), ref: text(entry.ref), at: text(entry.at) }))
         })),
         checkpoints: list(goal.checkpoints).map((entry) => ({ summary: text(entry.summary), at: text(entry.at) })),
@@ -131,16 +213,27 @@ export function buildMissionView(input) {
     const planSaved = planMark !== undefined && planMark.blocked !== true;
     const planBlocked = planMark?.blocked === true;
     const discipline = latest?.mode && latest.mode !== "bounded-authority-lifecycle" ? latest.mode : latest?.command ?? input.agent ?? "lit";
+    // A research run counts when this session started it or wrote to it; an older folder is earlier work.
+    const research = input.research !== undefined && !(input.research.touchedAt < marks[0].at - staleGoalSlackMs) ? input.research : undefined;
+    const researching = isResearchName(discipline) || (research !== undefined && !research.reported);
+    const work = input.work;
     const counted = input.todos.filter((todo) => todo.status !== "cancelled");
+    const planList = work?.plan;
     const progress = counted.length > 0
         ? { done: counted.filter((todo) => todo.status === "completed").length, total: counted.length }
-        : goal !== undefined && goal.criteria.length > 0
-            ? { done: goal.criteria.filter((criterion) => criterion.status === "pass").length, total: goal.criteria.length }
-            : undefined;
+        : planList !== undefined
+            ? { done: planList.done, total: planList.total }
+            : goal !== undefined && goal.criteria.length > 0
+                ? { done: goal.criteria.filter((criterion) => criterion.status === "pass").length, total: goal.criteria.length }
+                : undefined;
+    const countsTasks = counted.length > 0 || planList !== undefined;
     const nextTodo = counted.find((todo) => todo.status === "in_progress") ?? counted.find((todo) => todo.status === "pending");
     const nextCriterion = goal?.criteria.find((criterion) => criterion.status !== "pass");
+    const family = researching ? "research" : !countsTasks && goal !== undefined && goal.criteria.length > 0 && /lit-?loop|litgoal/u.test(discipline) ? "loop" : "main";
     const blockers = (goal?.reviewBlockers ?? []).filter((blocker) => !blocker.resolved);
-    const complete = goal?.status === "complete" || (progress !== undefined && progress.total > 0 && progress.done === progress.total && goal === undefined && counted.length > 0);
+    const complete = researching
+        ? research?.reported === true
+        : goal?.status === "complete" || (progress !== undefined && progress.total > 0 && progress.done === progress.total && goal === undefined && countsTasks);
     let phase = latest === undefined ? agentStep ?? "work" : stepOf(latest.command ?? latest.mode ?? "") ?? "work";
     if (latest?.operation === "save-plan" && !planBlocked)
         phase = "work";
@@ -148,6 +241,8 @@ export function buildMissionView(input) {
     const workComplete = progress === undefined || progress.done === progress.total;
     if (blockers.length > 0 || goal?.status === "review_blocked")
         phase = workComplete ? "review" : phase === "review" ? "review" : "work";
+    if (researching)
+        phase = research?.stage ?? "decompose";
     if (complete)
         phase = "done";
     const warnings = [];
@@ -168,23 +263,51 @@ export function buildMissionView(input) {
     if (typeof input.contextPercent === "number" && input.contextPercent >= contextWarnPercent) {
         warnings.push({ kind: "context", text: `ctx ${Math.round(input.contextPercent)}%` });
     }
-    const order = ["plan", "work", "review"];
-    const position = phase === "done" ? order.length : order.indexOf(phase);
-    const planned = planMark !== undefined || agentStep === "plan" || marks.some((mark) => stepOf(mark.command ?? mark.mode ?? "") === "plan");
+    const order = familySteps[family];
+    const position = complete ? order.length : order.indexOf(phase);
+    const visited = (id) => {
+        if (id === "interview")
+            return agentStep === "interview" || marks.some((mark) => stepOf(mark.command ?? mark.mode ?? "") === "interview");
+        if (id === "plan")
+            return planMark !== undefined || work !== undefined || agentStep === "plan" || marks.some((mark) => stepOf(mark.command ?? mark.mode ?? "") === "plan");
+        // Finished todos alone prove no review; a review command, a review blocker or the goal ledger's
+        // completion gate does.
+        if (id === "review")
+            return (goal?.status === "complete" && goal.gated) || blockers.length > 0 || (goal?.reviewBlockers.length ?? 0) > 0 || marks.some((mark) => stepOf(mark.command ?? mark.mode ?? "") === "review");
+        return true;
+    };
     const steps = order.map((id, index) => {
         if (index < position)
-            return { id, state: id === "plan" && !planned ? "skip" : "done" };
+            return { id, state: visited(id) ? "done" : "skip" };
         if (index > position)
             return { id, state: "todo" };
         return { id, state: warnings.length > 0 ? "warn" : "now" };
     });
+    const iteration = work !== undefined && work.iterations > 0 ? work.iterations : family === "loop" && goal !== undefined && goal.checkpoints.length > 0 ? goal.checkpoints.length : undefined;
+    const nextPlan = nextTodo === undefined ? planList?.next : undefined;
+    const detail = family === "research"
+        ? research === undefined ? undefined : `${research.claims} claims · ${research.verified} verified`
+        : countsTasks && progress !== undefined && progress.done < progress.total ? `task ${progress.done + 1}` : undefined;
+    const live = input.live !== undefined && (input.sessionStatus === "busy" || input.sessionStatus === "retry") ? input.live : undefined;
     return {
         active: true,
         discipline,
+        family,
         phase,
         steps,
-        ...(progress === undefined ? {} : { progress }),
-        ...(nextTodo !== undefined ? { next: nextTodo.content } : nextCriterion !== undefined ? { next: `${nextCriterion.id} ${nextCriterion.scenario}`.trim() } : {}),
+        ...(family === "research" || progress === undefined ? {} : { progress }),
+        ...(family === "research"
+            ? {}
+            : nextTodo !== undefined
+                ? { next: nextTodo.content }
+                : nextPlan !== undefined
+                    ? { next: nextPlan }
+                    : nextCriterion !== undefined ? { next: `${nextCriterion.id} ${nextCriterion.scenario}`.trim() } : {}),
+        ...(detail === undefined ? {} : { detail }),
+        ...(iteration === undefined ? {} : { iteration }),
+        ...(planList === undefined ? {} : { planTasks: planList.total }),
+        ...(family === "research" && research !== undefined && research.waves > 0 ? { wave: research.waves } : {}),
+        ...(live === undefined ? {} : { live }),
         ...(goal === undefined
             ? {}
             : {
@@ -287,14 +410,17 @@ export function missionRowKeys(view) {
     const keys = ["h1", "h2", "b1"];
     if (view.goal !== undefined)
         keys.push("title");
-    keys.push("steps");
+    view.steps.forEach((step, index) => keys.push(...(index === 0 ? [] : [`link:${index}`]), `step:${step.id}`));
     if (view.progress !== undefined)
         keys.push("bar");
-    const detail = (view.next !== undefined && !view.complete) || view.goal !== undefined || view.warnings.length > 0;
-    if (detail)
+    const line = (view.next !== undefined || view.detail !== undefined) && !view.complete;
+    const live = view.live !== undefined && !view.complete;
+    if (line || live || view.goal !== undefined || view.warnings.length > 0)
         keys.push("b2");
-    if (view.next !== undefined && !view.complete)
-        keys.push("next");
+    if (line)
+        keys.push("detail");
+    if (live)
+        keys.push("live");
     if (view.goal !== undefined)
         keys.push("crit");
     view.warnings.forEach((warning) => keys.push(`warn:${warning.kind}:${warning.text}`));

package/dist/tui/mission-motion.d.ts

@@ -41,6 +41,10 @@ export type MotionState = {
     readonly warnFrom: number;
     readonly warnTo: number;
     readonly celebrate: boolean;
+    /** The stage index the map moved forward from; the connectors below it fill and the chip flashes once. */
+    readonly stageFrom?: number;
+    /** The stage that was running when the mission completed; it and the stages after it flip to done in turn. */
+    readonly celebrateFrom?: number;
 };
 export type MotionFrame = {
     /** Milliseconds since the last change; Infinity once settled or when motion is off. */
@@ -52,6 +56,11 @@ export type MotionFrame = {
     readonly warn: number;
     /** Milliseconds into the completion moment while it plays, otherwise undefined. */
     readonly celebrate?: number;
+    readonly celebrateFrom?: number;
+    /** While a stage change plays: the stage index the map moved forward from. */
+    readonly stageFrom?: number;
+    /** The clock this frame was sampled at, for the live step's elapsed time. */
+    readonly now?: number;
     readonly moving: boolean;
 };
 export declare const idleMotion: MotionState;
@@ -63,4 +72,4 @@ export declare function rowEntryStart(state: Pick<MotionState, "entering" | "chi
  */
 export declare function planMotion(prev: MissionView | undefined, next: MissionView, now: number, state: MotionState, enabled?: boolean): MotionState;
 export declare function sampleMotion(state: MotionState, now: number): MotionFrame;
-export declare function restingFrameFor(view: MissionView): MotionFrame;
+export declare function restingFrameFor(view: MissionView, now?: number): MotionFrame;