@litfamily/litopencode 1.0.20 → 1.0.22

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;

package/dist/tui/mission-motion.js

@@ -1,6 +1,6 @@
 // Motion for the mission chip and panel. Everything here is a pure function of a clock value, so the
 // TUI only runs a frame timer while one of these tracks is still moving and stays static otherwise.
-import { missionRowKeys } from "./mission-model.js";
+import { currentStepIndex, missionRowKeys } from "./mission-model.js";
 export const motionTiming = Object.freeze({
     stagger: 60,
     entry: 160,
@@ -96,6 +96,8 @@ function settleTime(state) {
         end = Math.max(end, state.barDelay + motionTiming.fill);
     if (state.celebrate)
         end = Math.max(end, motionTiming.complete);
+    if (state.stageFrom !== undefined)
+        end = Math.max(end, motionTiming.shimmer);
     return end;
 }
 /**
@@ -110,8 +112,12 @@ export function planMotion(prev, next, now, state, enabled = true) {
     const current = sampleMotion(state, now);
     const appearing = prev === undefined || !prev.active;
     const before = new Set(appearing ? [] : missionRowKeys(prev));
-    const entering = missionRowKeys(next).filter((key) => !before.has(key));
+    // The live step changes with every tool call, so its row appears in place instead of sliding in.
+    const entering = missionRowKeys(next).filter((key) => !before.has(key) && key !== "live");
     const goalArrived = !appearing && prev?.goal === undefined && next.goal !== undefined;
+    const from = appearing || prev === undefined ? -1 : currentStepIndex(prev);
+    const to = currentStepIndex(next);
+    const celebrate = !appearing && prev?.complete !== true && next.complete;
     return {
         changeAt: now,
         entering,
@@ -121,12 +127,14 @@ export function planMotion(prev, next, now, state, enabled = true) {
         barDelay: goalArrived || appearing ? motionTiming.fillDelayOnGoal : 0,
         warnFrom: appearing ? nextWarn : current.warn,
         warnTo: nextWarn,
-        celebrate: !appearing && prev?.complete !== true && next.complete
+        celebrate,
+        ...(from >= 0 && to > from && prev?.family === next.family ? { stageFrom: from } : {}),
+        ...(celebrate && from >= 0 ? { celebrateFrom: from } : {})
     };
 }
 export function sampleMotion(state, now) {
     if (state.changeAt === undefined) {
-        return { t: Number.POSITIVE_INFINITY, entering: [], chipEnter: false, barRatio: state.barTo, warn: state.warnTo, moving: false };
+        return { t: Number.POSITIVE_INFINITY, entering: [], chipEnter: false, barRatio: state.barTo, warn: state.warnTo, now, moving: false };
     }
     const t = now - state.changeAt;
     const moving = t < settleTime(state);
@@ -138,10 +146,12 @@ export function sampleMotion(state, now) {
         chipEnter: moving && state.chipEnter,
         barRatio: clamp01(state.barFrom + (state.barTo - state.barFrom) * fill),
         warn: clamp01(state.warnFrom + (state.warnTo - state.warnFrom) * fade),
-        ...(moving && state.celebrate ? { celebrate: t } : {}),
+        ...(moving && state.celebrate ? { celebrate: t, ...(state.celebrateFrom === undefined ? {} : { celebrateFrom: state.celebrateFrom }) } : {}),
+        ...(moving && state.stageFrom !== undefined ? { stageFrom: state.stageFrom } : {}),
+        now,
         moving
     };
 }
-export function restingFrameFor(view) {
-    return { t: Number.POSITIVE_INFINITY, entering: [], chipEnter: false, barRatio: ratio(view), warn: warnTarget(view), moving: false };
+export function restingFrameFor(view, now) {
+    return { t: Number.POSITIVE_INFINITY, entering: [], chipEnter: false, barRatio: ratio(view), warn: warnTarget(view), ...(now === undefined ? {} : { now }), moving: false };
 }

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

@@ -1,4 +1,4 @@
-import { type MissionInput, type TodoInput } from "./mission-model.ts";
+import { type LiveStep, type MissionInput, type ResearchInput, type TodoInput, type WorkInput } from "./mission-model.ts";
 import { type SkillChip } from "./mission-skills.ts";
 type MessageLike = {
     readonly id: string;
@@ -47,22 +47,52 @@ export type MissionStateSource = {
     };
     part(messageID: string): ReadonlyArray<{
         readonly type?: string;
+        readonly tool?: unknown;
+        readonly state?: unknown;
         readonly metadata?: unknown;
     }>;
 };
 /** The same root the server plugin uses: the worktree unless it is the filesystem root, else the directory. */
 export declare function missionProjectRoot(paths: MissionStateSource["path"]): string | undefined;
+/** Reads goals.json under `root`, refusing symbolic links and oversized files. */
+export declare function createLedgerReader(): (root: string | undefined) => unknown;
 /**
- * Reads goals.json under `root`, refusing symbolic links and oversized files. The result is cached
- * on mtime and size, so calling it on every refresh costs one lstat.
+ * Reads this session's bounded work from work-schema-3.json and the checklist of the plan it names.
+ * The plan must be a regular file inside `root`; anything else leaves the checklist out.
  */
-export declare function createLedgerReader(): (root: string | undefined) => unknown;
-export declare function readMissionInput(state: MissionStateSource, sessionID: string, ledger: unknown, now: number): MissionInput;
+export declare function createWorkReader(): (root: string | undefined, sessionID: string) => WorkInput | undefined;
+/**
+ * What a litresearch run folder says so far. The skill keeps a root-owned journal.md, an append-only
+ * claim-graph.jsonl and a final report.md; the stage is read from them: a report is synthesis, a
+ * claim with a gate result is verify, a journal whose last heading names EXPAND is expand, claims are
+ * a wave (numbered by the highest `wave` field or `## Wave` heading), and nothing yet is decompose.
+ */
+export declare function readResearchRun(journal: string, claimGraph: string, reported: boolean, touchedAt: number): ResearchInput;
+/**
+ * The most recently written run under .litopencode/litgoal/lit-loop/research/, or undefined when
+ * there is none. Symbolic links are skipped and only the three known files are read.
+ */
+export declare function readLatestResearchRun(root: string | undefined): ResearchInput | undefined;
+/**
+ * The tool the session's latest assistant message is running: its name and `time.start` from the
+ * running tool part. The input is never read.
+ */
+export declare function readLiveStep(state: MissionStateSource, messages: ReadonlyArray<MessageLike>): LiveStep | undefined;
+export type MissionRecords = {
+    readonly work?: WorkInput;
+    readonly research?: ResearchInput;
+};
+export declare function readMissionInput(state: MissionStateSource, sessionID: string, ledger: unknown, now: number, records?: MissionRecords): MissionInput;
 export type CardInput = {
     readonly chips: readonly SkillChip[];
+    readonly busy: boolean;
     readonly contextPercent: number | null;
     readonly branch?: string;
 };
-/** What the band card shows beside the mission: the session's skill chips, context use and git branch. */
+/**
+ * What the band card shows beside the mission: the session's skill chips, whether a turn is running,
+ * context use and git branch. OpenCode keeps each session's last `session.status` ({ type: "busy" },
+ * "retry" or "idle"); a session it has not seen run has none, which counts as not running.
+ */
 export declare function readCardInput(state: MissionStateSource, sessionID: string): CardInput;
 export {};