@litfamily/litopencode 1.0.31 → 1.0.33

package/dist/tui.js

@@ -4,15 +4,21 @@ import { jsx } from "@opentui/solid/jsx-runtime";
 import { buildMissionView, lastMission, leadingNotice, missionNotices } from "./tui/mission-model.js";
 import { idleMotion, motionTiming, planMotion, sampleMotion } from "./tui/mission-motion.js";
 import { chipBudget, chipLine, homeLine, missionPanel, paletteFromTheme, panelWidth } from "./tui/mission-text.js";
-import { createLedgerReader, createWorkReader, missionProjectRoot, readCardInput, readLatestResearchRun, readMissionInput } from "./tui/mission-source.js";
+import { adhdSuggestDue, createLedgerReader, createWorkReader, earlierWorkWindowMs, hasEarlierWork, messageTimes, missionProjectRoot, wayBackDue, readCardInput, readLatestResearchRun, readMissionInput, readThreadSources } from "./tui/mission-source.js";
 import { chipShimmer, idleChipMotion, planChipMotion } from "./tui/mission-skills.js";
 import { bandCard, readBandOptions, readNotifyOptions, statusCard } from "./tui/mission-band.js";
+import { activeSkillLook, turnGlow, waitingOnYou } from "./tui/mission-looks.js";
+import { rainbowActive, rainbowAllowed, rainbowAt, rainbowShows, rainbowTickMs } from "./tui/mission-rainbow.js";
+import { threadLineCount, threadsOf } from "./tui/mission-threads.js";
+import { readPackageMetadata } from "./cli/json.js";
+import { readInstalledVersions, restartVersion } from "./restart-notice.js";
 export const litOpenCodeTuiPluginId = "litopencode";
 const homeLineWidth = 69;
 const refreshDelayMs = 80;
 const ledgerPollMs = 2000;
 const toastMs = 4000;
 const liveTickMs = 1000;
+const restartCheckMs = 10 * 60_000;
 const trackedSessionLimit = 4;
 const refreshEvents = [
     "message.updated",
@@ -50,6 +56,25 @@ const tui = async (api, options) => {
     let refreshTimer;
     let pollTimer;
     let liveTimer;
+    let bandTimer;
+    const suggested = new Set();
+    const suggestedDays = new Map();
+    const colorAllowed = rainbowAllowed(motionEnabled, process.env.NO_COLOR);
+    // The version this start loaded; an install newer than it shows `restart to <v>` and one toast.
+    const loaded = await readPackageMetadata().catch(() => undefined);
+    const [restartTo, setRestartTo] = createSignal(undefined);
+    let restartTimer;
+    async function checkRestart() {
+        if (loaded === undefined)
+            return;
+        const target = restartVersion(loaded.version, await readInstalledVersions(loaded.packageRoot).catch(() => []));
+        if (target === undefined || target === restartTo())
+            return;
+        if (restartTo() === undefined) {
+            api.ui.toast({ variant: "info", title: "🔥 LIT", message: `LitOpenCode ${target} is installed. Restart OpenCode to load it.`, duration: toastMs });
+        }
+        setRestartTo(target);
+    }
     const state = () => api.state;
     const palette = () => paletteFromTheme(api.theme.current, api.theme.mode());
     // OpenCode keeps the sidebar choice in its KV store under "sidebar" ("auto" or "hide"); a child
@@ -64,6 +89,30 @@ const tui = async (api, options) => {
         const session = api.state.session.get(sessionID);
         return typeof session?.parentID === "string" && session.parentID !== "";
     }
+    // lit-adhd plays the rainbow and a working lane without a real total plays a pulse; both step at 4 Hz
+    // and only while they are on screen, and neither runs under reduced motion or NO_COLOR.
+    function rainbowOn(entry, now) {
+        return colorAllowed && rainbowShows(rainbowActive(entry.view, entry.card.chips, entry.card.busy), entry.rainbowSeen, entry.lastPromptAt, now);
+    }
+    function bandStepping(entry) {
+        if (!colorAllowed)
+            return false;
+        if (entry.waiting || rainbowOn(entry, Date.now()))
+            return true;
+        return entry.card.threads?.some((row) => row.status === "working" && row.done === undefined) === true;
+    }
+    function syncBandTimer() {
+        const needed = [...sessions.values()].some(bandStepping);
+        if (needed && bandTimer === undefined)
+            bandTimer = setInterval(() => {
+                setClock(Date.now());
+                syncBandTimer();
+            }, rainbowTickMs);
+        if (!needed && bandTimer !== undefined) {
+            clearInterval(bandTimer);
+            bandTimer = undefined;
+        }
+    }
     function anyMoving(now) {
         for (const entry of sessions.values())
             if (sampleMotion(entry.motion, now).moving || chipShimmer(entry.chipMotion, now) !== undefined)
@@ -103,16 +152,48 @@ const tui = async (api, options) => {
             .notify({ title: "🔥 LIT complete", message: notice.message, notification: notify.desktop, sound: notify.sound ? { name: "done" } : false })
             .catch(() => undefined);
     }
+    // The card keeps the tallest lane count it reached while lanes are live or a turn runs, and drops back to
+    // four rows only once everything has settled, so the prompt does not jump between repaints.
+    function holdRows(held, rows, busy) {
+        if (rows > 0)
+            return Math.max(held, rows);
+        return busy ? held : 0;
+    }
+    // One toast per session, for a fresh root session in a workspace that has earlier work to pick up.
+    function suggestAdhd(sessionID) {
+        if (suggested.has(sessionID) || isChildSession(sessionID))
+            return;
+        suggested.add(sessionID);
+        const source = state();
+        const created = api.state.session.get(sessionID)?.time?.created;
+        const now = Date.now();
+        if (source.session.messages(sessionID).length > 0 || typeof created !== "number" || now - created > 2 * 60_000)
+            return;
+        const root = missionProjectRoot(source.path);
+        if (root === undefined || !hasEarlierWork(root, sessionID, now, earlierWorkWindowMs) || !adhdSuggestDue(suggestedDays, root, now))
+            return;
+        api.ui.toast({ variant: "info", title: "🔥 LIT", message: "Earlier work here. Say lit adhd to pick up where you left off.", duration: toastMs });
+    }
     function refresh(sessionID) {
         const now = Date.now();
         const source = state();
         const root = missionProjectRoot(source.path);
         const ledger = readLedger(root);
-        const next = buildMissionView(readMissionInput(source, sessionID, ledger, now, { work: readWork(root, sessionID), research: readLatestResearchRun(root) }));
-        const card = readCardInput(source, sessionID);
+        const work = readWork(root, sessionID);
+        const next = buildMissionView(readMissionInput(source, sessionID, ledger, now, { work, research: readLatestResearchRun(root) }));
+        const threads = threadsOf(readThreadSources(source, sessionID, root, now), now);
+        const times = messageTimes(source, sessionID);
+        const card = {
+            ...readCardInput(source, sessionID),
+            ...(threads === undefined ? {} : { threads }),
+            ...(wayBackDue(times.lastAt, now, hasEarlierWork(root, sessionID, now, earlierWorkWindowMs)) ? { earlier: true } : {})
+        };
         const entry = sessions.get(sessionID);
         const viewChanged = entry === undefined || JSON.stringify(entry.view) !== JSON.stringify(next);
-        if (!viewChanged && JSON.stringify(entry.card) === JSON.stringify(card))
+        const rainbowSeen = rainbowActive(next, card.chips, card.busy) ? now : entry?.rainbowSeen;
+        const waiting = waitingOnYou(next, card.busy, { asked: card.asked === true, userSpokeLast: card.userSpokeLast === true, blockedReply: card.blockedReply === true, boundary: work?.boundary === true });
+        const promptMoved = entry?.lastPromptAt !== times.lastPromptAt;
+        if (!viewChanged && !promptMoved && JSON.stringify(entry.card) === JSON.stringify(card) && entry.rainbowSeen === rainbowSeen && entry.waiting === waiting)
             return;
         if (entry !== undefined && viewChanged) {
             const notices = missionNotices(entry.view, next);
@@ -127,12 +208,17 @@ const tui = async (api, options) => {
             view: next,
             card,
             motion: viewChanged ? planMotion(entry?.view, next, now, entry?.motion ?? idleMotion, motionEnabled) : entry.motion,
-            chipMotion: planChipMotion(entry?.card.chips, card.chips, now, entry?.chipMotion ?? idleChipMotion, motionEnabled)
+            chipMotion: planChipMotion(entry?.card.chips, card.chips, now, entry?.chipMotion ?? idleChipMotion, motionEnabled),
+            reserve: holdRows(entry?.reserve ?? 0, threadLineCount(threads), card.busy),
+            ...(rainbowSeen === undefined ? {} : { rainbowSeen }),
+            ...(times.lastPromptAt === undefined ? {} : { lastPromptAt: times.lastPromptAt }),
+            waiting
         });
         setClock(now);
         setRevision(revision() + 1);
         ensureFrames();
         syncLiveTick();
+        syncBandTimer();
     }
     function refreshTracked() {
         refreshTimer = undefined;
@@ -143,7 +229,7 @@ const tui = async (api, options) => {
     // Ledger writes from a terminal or another session fire no TUI event, so an active mission
     // re-reads goals.json (one lstat while unchanged) every two seconds. Idle sessions do not poll.
     function syncPoll() {
-        const active = [...sessions.values()].some((entry) => entry.view.active);
+        const active = [...sessions.values()].some((entry) => entry.view.active || entry.card.threads !== undefined);
         if (active && pollTimer === undefined)
             pollTimer = setInterval(refreshTracked, ledgerPollMs);
         if (!active && pollTimer !== undefined) {
@@ -164,6 +250,7 @@ const tui = async (api, options) => {
         queueMicrotask(() => {
             refresh(sessionID);
             syncPoll();
+            suggestAdhd(sessionID);
         });
     }
     // Opening a session loads its messages and parts over HTTP, which fires no bus event. Reading the
@@ -200,7 +287,11 @@ const tui = async (api, options) => {
     for (const type of refreshEvents) {
         api.event.on(type, scheduleRefresh);
     }
+    void checkRestart();
+    restartTimer = setInterval(() => void checkRestart(), restartCheckMs);
     api.lifecycle.onDispose(() => {
+        if (restartTimer !== undefined)
+            clearInterval(restartTimer);
         if (frameTimer !== undefined)
             clearInterval(frameTimer);
         if (refreshTimer !== undefined)
@@ -209,6 +300,8 @@ const tui = async (api, options) => {
             clearInterval(pollTimer);
         if (liveTimer !== undefined)
             clearInterval(liveTimer);
+        if (bandTimer !== undefined)
+            clearInterval(bandTimer);
         sessions.clear();
     });
     api.slots.register({
@@ -322,8 +415,20 @@ const tui = async (api, options) => {
                                     frame: snapshot.frame,
                                     chips: snapshot.card.chips,
                                     busy: snapshot.card.busy,
+                                    motion: motionEnabled,
+                                    reserve: snapshot.reserve,
+                                    ...(snapshot.card.threads === undefined ? {} : { threads: snapshot.card.threads }),
+                                    ...(snapshot.card.earlier === true ? { earlier: true } : {}),
+                                    ...(snapshot.waiting ? { turn: { glow: turnGlow(snapshot.now, colorAllowed) } } : {}),
+                                    ...(rainbowOn(snapshot, snapshot.now) ? { rainbow: rainbowAt(snapshot.now) } : {}),
+                                    ...(snapshot.card.lanes !== undefined && activeSkillLook(snapshot.view, snapshot.card.chips, snapshot.card.busy) === "review" ? { lanes: snapshot.card.lanes } : {}),
                                     ...(shimmer === undefined ? {} : { shimmer }),
-                                    figures: { contextPercent: snapshot.card.contextPercent, ...(snapshot.card.branch === undefined ? {} : { branch: snapshot.card.branch }), inLane: snapshot.inLane },
+                                    figures: {
+                                        contextPercent: snapshot.card.contextPercent,
+                                        ...(snapshot.card.branch === undefined ? {} : { branch: snapshot.card.branch }),
+                                        inLane: snapshot.inLane,
+                                        ...(restartTo() === undefined ? {} : { restartTo: restartTo() })
+                                    },
                                     ...(last === undefined ? {} : { last })
                                 }, colors, width);
                                 const rows = lines.map(lineElement);

package/dist/uiux-visual-catalog.js

@@ -1,7 +1,7 @@
 export const frontendUiUxFeature = {
     id: "frontend-ui-ux",
     title: "Frontend UI/UX",
-    summary: "Builds and inspects authorized interfaces using an evolving beta2 contract and offline design intelligence.",
+    summary: "Builds and inspects authorized interfaces using an evolving beta2 contract, offline design intelligence and a locked house style with a rich default.",
     bindings: [
         {
             kind: "config",
@@ -15,6 +15,12 @@ export const frontendUiUxFeature = {
             surface: "OpenCode native skill frontend-ui-ux",
             description: "Ships focused contract references plus an exact verified 167-file canonical design library. The canonical route is inert and separate from the normalized retrieval dataset."
         },
+        {
+            kind: "config",
+            id: "skills/frontend-ui-ux/kit",
+            surface: "OpenCode native skill frontend-ui-ux",
+            description: "Ships five house styles, the token-only component sheet and three layout starters; scripts/design-lock.mjs writes the design lock, tokens and fonts into a new project, and the probe checks the rendered page against it (DS-001 to DS-008)."
+        },
         {
             kind: "cli",
             id: "litopencode install",
@@ -29,6 +35,7 @@ export const frontendUiUxFeature = {
         }
     ],
     verification: [
+        "node --test test/frontend-design-lock.test.mjs",
         "node --test --test-name-pattern='uiux\\.' test/runtime-skills.test.mjs test/packed-artifact.test.mjs",
         "node --test --test-name-pattern='integration\\.installed-nested-assets' test/cli-install-surface.test.mjs",
         "npm run check:managed-skill-manifest",

package/dist/v2/events.js

@@ -1,5 +1,6 @@
 import { createAutoHandoff } from "../auto-handoff-hooks.js";
 import { LifecycleConflictError, LifecycleSafetyError, createBoundedAuthorityLifecycle, parseFencedProgress } from "../bounded-authority.js";
+import { markLiveness } from "../session-liveness.js";
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -100,6 +101,7 @@ export function createV2Events(options) {
                     if (step.sessionID === sessionID)
                         steps.delete(messageID);
                 options.onSessionDeleted(sessionID);
+                await markLiveness(options.projectRoot, sessionID, "ended");
                 await toHandoff("session.deleted", { info: { id: sessionID } });
                 return;
             case "session.step.started": {
@@ -138,6 +140,7 @@ export function createV2Events(options) {
                 await toHandoff("session.status", { sessionID, status: data.status });
                 return;
             case "session.idle":
+                await markLiveness(options.projectRoot, sessionID, "idle");
                 await toHandoff("session.idle", { sessionID });
                 return;
             case "session.compaction.ended":

package/dist/v2/session-hooks.js

@@ -6,12 +6,14 @@
 // than from LitOpenCode's own instructions (local knowledge, a start-work receipt, an auto-handoff setting
 // reply) rides the latest user message instead, the channel it had on OpenCode 1.
 import { fileURLToPath } from "node:url";
-import { createActivationMemory, decideReentry } from "../activation-reentry.js";
+import { typedPromptReply } from "../adhd-next.js";
+import { createActivationMemory, decideReentry, recordActivation } from "../activation-reentry.js";
 import { detectChatActivationMode, promptForChatActivationMode } from "../activation-routing.js";
-import { startWorkPromptInjection } from "../activation-workflow-prompts.js";
+import { adhdSessionNote, litAdhdPromptInjection, startWorkPromptInjection } from "../activation-workflow-prompts.js";
 import { autoHandoffSettingText } from "../auto-handoff.js";
 import { applyTrustedStartWorkDirective, parseStartWorkLifecycleDirective } from "../bounded-authority-hooks.js";
 import { queryKnowledge } from "../knowledge.js";
+import { startTypedWork, typedStartArgument } from "../start-work-typed.js";
 import { createLitGoalOperations } from "../ledger.js";
 import { applyCompactionRuleReset, applyStaticRuleInjection } from "../rules/hooks.js";
 import { isReadOnlyWorkflowFamilyPlan } from "../workflow-families.js";
@@ -125,13 +127,42 @@ export function createV2SessionHooks(options) {
         catch { // no-excuse-ok: catch -- local relevance must never block the user message.
             // A malformed or unreadable knowledge store stays silent instead of inventing context.
         }
+        const typed = await typedPromptReply(options.projectRoot, event.sessionID, input, activationMemory, options.config.boundedAuthority);
+        if (typed !== undefined) {
+            state.turn.push(typed.text);
+            event.metadata = { ...(event.metadata ?? {}), litopencode: { mode: typed.mode, trigger: "lit", source: "prompt", typed: typed.kind } };
+            if (typed.continued)
+                options.onActivation?.(event.sessionID, typed.mode);
+            return;
+        }
+        // An installed alias file makes the host expand /lit-adhd (or /lit-rewind) itself, so the prompt
+        // arrives as the command body with no plugin mark; it still runs the brief and takes its look.
+        if (input.trimStart().startsWith(litAdhdPromptInjection.trim())) {
+            state.turn.push(adhdSessionNote(event.sessionID));
+            event.metadata = { ...(event.metadata ?? {}), litopencode: { mode: "lit-adhd", trigger: "lit", source: "alias" } };
+            options.onActivation?.(event.sessionID, "lit-adhd");
+            return;
+        }
         const mode = detectChatActivationMode(input, session.agent);
         if (mode === undefined)
             return;
         const trigger = mode === "lit-handoff" ? "handoff" : mode === "lit-scientific-visualization" ? mode : "lit";
         let activation = promptForChatActivationMode(mode, input);
+        if (mode === "lit-adhd")
+            activation = `${activation}\n${adhdSessionNote(event.sessionID)}`;
         if (mode === "start-work" && session.agent !== "lit-plan") {
             const directive = parseStartWorkLifecycleDirective(input, { chat: true });
+            const planArgument = directive === undefined ? typedStartArgument(input) : undefined;
+            if (planArgument !== undefined) {
+                const started = await startTypedWork({
+                    projectRoot: options.projectRoot,
+                    sessionID: event.sessionID,
+                    ...(planArgument === "" ? {} : { plan: planArgument }),
+                    options: options.config.boundedAuthority
+                });
+                if (started.quiet !== true)
+                    state.user.push(started.text);
+            }
             if (directive?.action === "resume") {
                 try {
                     const receipt = await applyTrustedStartWorkDirective(options.projectRoot, event.sessionID, directive, options.config.boundedAuthority);
@@ -160,15 +191,17 @@ export function createV2SessionHooks(options) {
             activation = `${reentry.line}\n${activation}`;
         else if (reentry.kind === "confirm")
             activation = `${activation}\n${reentry.line}`;
+        if (reentry.kind !== "confirm" && mode !== "lit-handoff" && mode !== "lit-scientific-visualization") {
+            const recorded = await recordActivation({ memory: activationMemory, projectRoot: options.projectRoot, sessionID: event.sessionID, mode });
+            if (recorded.line !== undefined)
+                activation = `${activation}\n${recorded.line}`;
+        }
         state.activation = activation;
         event.metadata = {
             ...(event.metadata ?? {}),
             litopencode: { mode, trigger, source: "prompt", ...(reentry.kind === "full" ? {} : { reentry: reentry.kind }) }
         };
         options.onActivation?.(event.sessionID, mode);
-        if (reentry.kind !== "confirm" && mode !== "lit-handoff" && mode !== "lit-scientific-visualization") {
-            activationMemory.remember(event.sessionID, mode);
-        }
         if (mode === "lit-task" || mode === "lit-recap" || mode === "lit-brainstorm" || isReadOnlyWorkflowFamilyPlan(mode))
             return;
         try {

package/dist/workflow-stack.d.ts

@@ -0,0 +1,53 @@
+export declare const workflowStackSchema = "litopencode.workflow-stack/v1";
+export type FrameStatus = "active" | "paused";
+export type StackFrame = {
+    readonly skill: string;
+    readonly status: FrameStatus;
+    readonly at: number;
+    readonly phase?: string;
+    /** Both counts or neither: an unknown total is never stored as zero. */
+    readonly done?: number;
+    readonly total?: number;
+};
+export type WorkflowStack = {
+    readonly schema: typeof workflowStackSchema;
+    readonly sessionID: string;
+    readonly frames: readonly StackFrame[];
+    readonly updatedAt: number;
+};
+export type FrameProgress = {
+    readonly phase?: string;
+    readonly done?: number;
+    readonly total?: number;
+};
+export declare function isSpineSkill(skill: string): boolean;
+export declare function emptyStack(sessionID: string): WorkflowStack;
+/** A new spine skill ends whatever the stack held: the user moved on to a different discipline. */
+export declare function startSpine(stack: WorkflowStack, skill: string, now: number): WorkflowStack;
+/** Records the spine's progress without pausing it, so a later pause or a card read has real numbers. */
+export declare function pauseSpine(stack: WorkflowStack, now: number, progress?: FrameProgress): WorkflowStack;
+/**
+ * Starts a side skill. An active spine is paused under it, keeping its stage and counts; a second side
+ * skill replaces the first. With no spine the side skill stands alone.
+ */
+export declare function pushSide(stack: WorkflowStack, skill: string, now: number, progress: FrameProgress | undefined): WorkflowStack;
+/** Closes the side frame and makes the paused spine active again at the stage it was paused in. */
+export declare function resumeSpine(stack: WorkflowStack, now: number): {
+    readonly stack: WorkflowStack;
+    readonly resumed?: StackFrame;
+};
+export declare function stackFile(projectRoot: string, sessionID: string): string;
+/** The session's stack, or undefined when the id is unsafe, the file is missing, a link, oversized or malformed. */
+export declare function readStack(projectRoot: string, sessionID: string): Promise<WorkflowStack | undefined>;
+export declare function writeStack(projectRoot: string, stack: WorkflowStack): Promise<void>;
+export type SiblingOptions = {
+    readonly now: number;
+    readonly freshMs: number;
+    readonly max: number;
+};
+/** Other sessions' stacks that moved recently, for the thread rows. Links and the session's own file are skipped. */
+export declare function readSiblingStacks(projectRoot: string, selfID: string, options: SiblingOptions): Promise<readonly WorkflowStack[]>;
+/** The TUI reads on its own refresh and cannot await: the same checks as `readStack`, synchronously. */
+export declare function readStackSync(projectRoot: string, sessionID: string): WorkflowStack | undefined;
+/** Synchronous twin of `readSiblingStacks`. */
+export declare function readSiblingStacksSync(projectRoot: string, selfID: string, options: SiblingOptions): readonly WorkflowStack[];

package/dist/workflow-stack.js

@@ -0,0 +1,196 @@
+import { lstatSync, readFileSync, readdirSync } from "node:fs";
+import fs from "node:fs/promises";
+import path from "node:path";
+import { createRuntimePaths } from "./state.js";
+// A session's workflow stack: the discipline it is running (the spine) and, while another lit command
+// is interjected, the paused spine underneath it. An interjected command pauses the spine and never
+// erases it, so `lit continue` returns to the same stage and the same k/n. Transitions are pure; the
+// store keeps one small JSON file per session so the TUI band and a restarted plugin read the same
+// record.
+export const workflowStackSchema = "litopencode.workflow-stack/v1";
+const spineSkills = new Set(["lit-loop", "lit-plan", "start-work", "lit-task"]);
+const safeSessionID = /^[A-Za-z0-9][A-Za-z0-9_-]{0,127}$/u;
+const stackByteLimit = 64 * 1024;
+const frameLimit = 4;
+export function isSpineSkill(skill) {
+    return spineSkills.has(skill);
+}
+export function emptyStack(sessionID) {
+    return { schema: workflowStackSchema, sessionID, frames: [], updatedAt: 0 };
+}
+function counts(progress) {
+    const done = progress?.done;
+    const total = progress?.total;
+    return Number.isInteger(done) && Number.isInteger(total) && total > 0 && done >= 0 && done <= total
+        ? { done: done, total: total }
+        : {};
+}
+function frame(skill, status, at, progress) {
+    return { skill, status, at, ...(progress?.phase === undefined ? {} : { phase: progress.phase }), ...counts(progress) };
+}
+function withFrames(stack, frames, now) {
+    return { ...stack, frames: frames.slice(-frameLimit), updatedAt: now };
+}
+/** A new spine skill ends whatever the stack held: the user moved on to a different discipline. */
+export function startSpine(stack, skill, now) {
+    return withFrames(stack, [frame(skill, "active", now)], now);
+}
+/** Records the spine's progress without pausing it, so a later pause or a card read has real numbers. */
+export function pauseSpine(stack, now, progress) {
+    const [spine, ...rest] = stack.frames;
+    if (spine === undefined || !isSpineSkill(spine.skill))
+        return stack;
+    return withFrames(stack, [frame(spine.skill, "paused", spine.at, { phase: progress?.phase ?? spine.phase, done: progress?.done ?? spine.done, total: progress?.total ?? spine.total }), ...rest], now);
+}
+/**
+ * Starts a side skill. An active spine is paused under it, keeping its stage and counts; a second side
+ * skill replaces the first. With no spine the side skill stands alone.
+ */
+export function pushSide(stack, skill, now, progress) {
+    const spine = stack.frames.find((candidate) => isSpineSkill(candidate.skill));
+    if (spine === undefined)
+        return withFrames(stack, [frame(skill, "active", now)], now);
+    const paused = pauseSpine({ ...stack, frames: [spine] }, now, progress).frames[0];
+    return withFrames(stack, [paused, frame(skill, "active", now)], now);
+}
+/** Closes the side frame and makes the paused spine active again at the stage it was paused in. */
+export function resumeSpine(stack, now) {
+    const spine = stack.frames.find((candidate) => isSpineSkill(candidate.skill) && candidate.status === "paused");
+    if (spine === undefined)
+        return { stack };
+    const resumed = { ...spine, status: "active" };
+    return { stack: withFrames(stack, [resumed], now), resumed };
+}
+export function stackFile(projectRoot, sessionID) {
+    if (!safeSessionID.test(sessionID))
+        throw new Error("workflow stack session id must match [A-Za-z0-9_-]");
+    return path.join(createRuntimePaths(projectRoot).workflowStackDir, `${sessionID}.json`);
+}
+function isFrame(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const record = value;
+    const optionalInt = (field) => field === undefined || (Number.isInteger(field) && field >= 0);
+    return typeof record.skill === "string" && (record.status === "active" || record.status === "paused") && Number.isFinite(record.at) &&
+        (record.phase === undefined || typeof record.phase === "string") && optionalInt(record.done) && optionalInt(record.total);
+}
+async function readRegular(file) {
+    try {
+        const stat = await fs.lstat(file);
+        if (!stat.isFile() || stat.size > stackByteLimit)
+            return undefined;
+        return await fs.readFile(file, "utf8");
+    }
+    catch {
+        return undefined;
+    }
+}
+function parseStack(text, sessionID) {
+    if (text === undefined)
+        return undefined;
+    let value;
+    try {
+        value = JSON.parse(text);
+    }
+    catch {
+        return undefined;
+    }
+    if (typeof value !== "object" || value === null)
+        return undefined;
+    const record = value;
+    if (record.schema !== workflowStackSchema || record.sessionID !== sessionID || !Array.isArray(record.frames) || !record.frames.every(isFrame) || !Number.isFinite(record.updatedAt))
+        return undefined;
+    return { schema: workflowStackSchema, sessionID, frames: record.frames.slice(-frameLimit), updatedAt: record.updatedAt };
+}
+/** The session's stack, or undefined when the id is unsafe, the file is missing, a link, oversized or malformed. */
+export async function readStack(projectRoot, sessionID) {
+    if (!safeSessionID.test(sessionID))
+        return undefined;
+    return parseStack(await readRegular(stackFile(projectRoot, sessionID)), sessionID);
+}
+export async function writeStack(projectRoot, stack) {
+    const file = stackFile(projectRoot, stack.sessionID);
+    const dir = path.dirname(file);
+    await fs.mkdir(dir, { recursive: true });
+    const dirStat = await fs.lstat(dir);
+    if (!dirStat.isDirectory())
+        throw new Error("workflow stack directory is not a directory");
+    try {
+        if ((await fs.lstat(file)).isSymbolicLink())
+            throw new Error("workflow stack file is a link");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const temp = `${file}.${process.pid}.tmp`;
+    await fs.writeFile(temp, `${JSON.stringify(stack)}\n`, { mode: 0o600 });
+    await fs.rename(temp, file);
+}
+/** Other sessions' stacks that moved recently, for the thread rows. Links and the session's own file are skipped. */
+export async function readSiblingStacks(projectRoot, selfID, options) {
+    const dir = createRuntimePaths(projectRoot).workflowStackDir;
+    let names;
+    try {
+        names = await fs.readdir(dir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const sessionID = name.slice(0, -".json".length);
+        if (sessionID === selfID || !safeSessionID.test(sessionID))
+            continue;
+        const stack = parseStack(await readRegular(path.join(dir, name)), sessionID);
+        if (stack === undefined || stack.frames.length === 0 || options.now - stack.updatedAt > options.freshMs)
+            continue;
+        found.push(stack);
+        if (found.length >= options.max)
+            break;
+    }
+    return found;
+}
+function readRegularSync(file) {
+    try {
+        const stat = lstatSync(file);
+        return stat.isFile() && stat.size <= stackByteLimit ? readFileSync(file, "utf8") : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+/** The TUI reads on its own refresh and cannot await: the same checks as `readStack`, synchronously. */
+export function readStackSync(projectRoot, sessionID) {
+    if (!safeSessionID.test(sessionID))
+        return undefined;
+    return parseStack(readRegularSync(stackFile(projectRoot, sessionID)), sessionID);
+}
+/** Synchronous twin of `readSiblingStacks`. */
+export function readSiblingStacksSync(projectRoot, selfID, options) {
+    const dir = createRuntimePaths(projectRoot).workflowStackDir;
+    let names;
+    try {
+        names = readdirSync(dir);
+    }
+    catch {
+        return [];
+    }
+    const found = [];
+    for (const name of names.sort()) {
+        if (!name.endsWith(".json"))
+            continue;
+        const sessionID = name.slice(0, -".json".length);
+        if (sessionID === selfID || !safeSessionID.test(sessionID))
+            continue;
+        const stack = parseStack(readRegularSync(path.join(dir, name)), sessionID);
+        if (stack === undefined || stack.frames.length === 0 || options.now - stack.updatedAt > options.freshMs)
+            continue;
+        found.push(stack);
+        if (found.length >= options.max)
+            break;
+    }
+    return found;
+}

package/docs/assets/readme/badge-version.svg

@@ -1 +1 @@
-<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.31"><title>release: 1.0.31</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.31</text></g></svg>
+<svg xmlns="http://www.w3.org/2000/svg" width="146" height="20" role="img" aria-label="release: 1.0.33"><title>release: 1.0.33</title><g shape-rendering="crispEdges"><rect width="49" height="20" fill="#080d14"/><rect x="49" width="97" height="20" fill="#ff6337"/></g><g fill="#fff" text-anchor="middle" font-family="Verdana,Geneva,DejaVu Sans,sans-serif" text-rendering="geometricPrecision" font-size="110"><text x="255" y="140" textLength="390" transform="scale(.1)">release</text><text x="965" y="140" textLength="870" transform="scale(.1)" fill="#080D14">1.0.33</text></g></svg>