@litfamily/litclaude 1.0.25 → 1.0.26

package/plugins/litclaude/hooks/lit-mod.mjs

@@ -1,9 +1,12 @@
 // LitClaude's Claude Code mod (hooks/hooks.json `modules`). It draws the LIT card above the prompt
-// for the whole session (the `band` setting can limit it to active work or turn it off), lights a
-// chip for each LitFamily skill that fires, adds the discipline and progress to the spinner, raises
-// gate notices, and serves /lit-evidence. It is read-only: it reads LitClaude's own state files and
-// the Git HEAD through lib/mod/state.mjs, the settings for the status line's accent, and the host's
-// live figures, and never writes, spawns, fetches or calls a model.
+// for the whole session (the `band` setting can limit it to active work or turn it off): where the
+// session stands in the LIT workflow, the tool the main loop is running and for how long, a chip
+// for each LitFamily skill that fires. It adds the discipline and progress to the spinner, raises
+// gate notices, serves /lit-evidence and, when the `notify` option asks, raises a notification
+// when LIT work completes or a long LIT turn ends. It is read-only: it reads LitClaude's own state
+// files and the Git HEAD through lib/mod/state.mjs, the settings for the status line's accent, and
+// the host's live figures, and never writes, spawns, fetches or calls a model. Of a tool call it
+// keeps the tool's name and start time, never its arguments.
 // Claude Code releases before mods ignore the `modules` key and keep running the settings hooks.
 //
 // The mods loader only follows `$` into functions declared at the top of this file, so each helper
@@ -13,6 +16,7 @@ import { composeBand, composeEvidence } from "../lib/mod/frame.mjs";
 import { TIMINGS } from "../lib/mod/motion.mjs";
 import { renderBand, renderRows } from "../lib/mod/render.mjs";
 import { accentFromSettings, normalizeModSettings, resolveGlyphs } from "../lib/mod/settings.mjs";
+import { composeSvgCard } from "../lib/mod/svg-card.mjs";
 import { chipStates, litSkillId, noteSkill } from "../lib/mod/skills.mjs";
 import { detectIconFont, readGitBranch, readLedgerTail, readLitSnapshot } from "../lib/mod/state.mjs";
 import { settledSample } from "../lib/mod/timeline.mjs";
@@ -22,6 +26,7 @@ import {
   buildEvidenceModel,
   detectCompletion,
   diffNotices,
+  formatDuration,
   mergeSpawned,
   noteAgentActivity,
   noteSpawn,
@@ -39,7 +44,9 @@ const TABS = Object.freeze([
   { id: "lanes", label: "lanes", hotkey: "2" },
   { id: "gates", label: "gates", hotkey: "3" },
 ]);
-const NO_SNAPSHOT = Object.freeze({ ignition: null, work: null, completedWorkIds: [], goal: null, autoloop: null, litPlan: null, probe: null, motion: null, handoff: null });
+const NO_SNAPSHOT = Object.freeze({ ignition: null, work: null, completedWorkIds: [], goal: null, autoloop: null, litPlan: null, probe: null, motion: null, handoff: null, workflow: null });
+// A LIT turn at least this long notifies when it ends, under `notify`.
+const LONG_TURN_MS = 3 * 60 * 1000;
 
 const createLive = (options) => ({
   band: normalizeModSettings(options).band,
@@ -69,11 +76,16 @@ const createLive = (options) => ({
   settledAt: 0,
   ignitionAt: undefined,
   lastDiscipline: null,
+  step: null,
+  mainToolCalls: 0,
+  turnStartedAt: null,
+  turnNotified: false,
 });
 
 const stateIo = ($) => ({
   stat: (path) => $.fs.stat(path, { resolve: true }),
   read: (path) => $.fs.read(path),
+  list: (path) => $.fs.list(path),
 });
 
 const toastText = (raised) => `🔥 ${raised.title}${raised.detail ? ` · ${raised.detail}` : ""}`;
@@ -94,6 +106,7 @@ async function rebuild($, live) {
     skills: chipStates(live.fired, live.settledAt),
     lastDiscipline: live.lastDiscipline,
     git: live.git,
+    step: live.step,
   });
   live.model = next;
   if (previous?.visible && !next.visible && !live.exiting) {
@@ -118,10 +131,18 @@ function showNotice($, live, raised) {
   });
 }
 
-function celebrate($, live, finish) {
+// The opt-in finish notification. No sound file ships yet, so `finish+sound` notifies like `finish`.
+function notifyFinish($, options, text) {
+  if (normalizeModSettings(options).notify === "off") return;
+  $.ui.notify(text, { title: "LitClaude" }).catch(() => undefined);
+}
+
+function celebrate($, live, finish, options) {
   if (live.celebrated.has(finish.id)) return;
   live.celebrated.add(finish.id);
   live.completion = finish;
+  live.turnNotified = true;
+  notifyFinish($, options, `LIT complete · ${finish.detail}`);
   $.clock.after(TIMINGS.completion + 200, () => {
     if (live.completion?.id !== finish.id) return;
     live.completion = null;
@@ -148,7 +169,7 @@ function noteIgnition(live, ignition, now) {
   if (id) live.fired = noteSkill(live.fired, id, ignition.at ?? now);
 }
 
-async function refresh($, live) {
+async function refresh($, live, options) {
   if (live.refreshing) return;
   live.refreshing = true;
   try {
@@ -166,7 +187,7 @@ async function refresh($, live) {
     live.snapshot = fresh;
     noteIgnition(live, fresh.ignition, now);
     const finish = detectCompletion(before, fresh);
-    if (finish) celebrate($, live, finish);
+    if (finish) celebrate($, live, finish, options);
     const next = await rebuild($, live);
     const raised = diffNotices(before, fresh, previousModel, next);
     if (raised.length > 0) {
@@ -182,12 +203,12 @@ async function refresh($, live) {
   }
 }
 
-function refreshSoon($, live) {
+function refreshSoon($, live, options) {
   if (live.quickPending) return;
   live.quickPending = true;
   $.clock.after(QUICK_REFRESH_MS, () => {
     live.quickPending = false;
-    void refresh($, live);
+    void refresh($, live, options);
   });
 }
 
@@ -209,16 +230,19 @@ export const register = (on, options) => {
     live.settledAt = await $.clock.now();
     live.accent = accentFromSettings(await $.settings.read().catch(() => null), await $.env.get("LITCLAUDE_HUD_ACCENT"));
     await $.command.register({ name: PANE, description: "Show LitClaude goal criteria, evidence, lanes and gates in a pane" });
-    await refresh($, live);
+    await refresh($, live, options);
     $.clock.every(POLL_MS, () => {
-      void refresh($, live);
+      void refresh($, live, options);
     });
     return next(e);
   });
 
   on("turn.start", async ($, e, next) => {
     live.isWorking = true;
-    refreshSoon($, live);
+    live.mainToolCalls = 0;
+    live.turnStartedAt = await $.clock.now();
+    live.turnNotified = false;
+    refreshSoon($, live, options);
     return next(e);
   });
 
@@ -226,50 +250,81 @@ export const register = (on, options) => {
     // A subagent's or teammate's turn ends its run, not the main turn the card follows.
     if (typeof e.agentId === "string") {
       live.spawned = noteSpawnEnded(live.spawned, e.agentId);
-      refreshSoon($, live);
+      refreshSoon($, live, options);
       return next(e);
     }
     live.isWorking = false;
+    live.step = null;
+    live.mainToolCalls = 0;
+    const now = await $.clock.now();
+    const took = Number.isFinite(e.durationMs) ? e.durationMs : now - (live.turnStartedAt ?? now);
+    const lit = live.model && (live.model.discipline || live.model.workflow || live.model.skills.some(({ state }) => state === "current"));
+    if (lit && !live.turnNotified && took >= LONG_TURN_MS) {
+      live.turnNotified = true;
+      notifyFinish($, options, `LIT turn finished · ${live.model.title ?? "LitClaude"} · ${formatDuration(took)}`);
+    }
     // The request is over: its chips dim to the recent list until a skill fires again.
-    live.settledAt = await $.clock.now();
-    refreshSoon($, live);
+    live.settledAt = now;
+    refreshSoon($, live, options);
     return next(e);
   });
 
   on("session.measure", async ($, e, next) => {
     live.usage = { context: e.context, rateLimits: e.rateLimits };
-    if (e.changed.includes("context")) refreshSoon($, live);
+    if (e.changed.includes("context")) refreshSoon($, live, options);
     return next(e);
   });
 
   on("tool.call", async ($, e, next) => {
-    if (e.tool === "Skill") await noteFiring($, live, e.skill);
+    // The card follows the main loop: a skill a subagent loads (a reviewer reading `rules`) neither
+    // lights a chip nor retitles the card.
+    if (e.tool === "Skill" && typeof e.agentId !== "string") await noteFiring($, live, e.skill);
     if (typeof e.agentId === "string") live.spawned = noteSpawnActivity(live.spawned, e.agentId, await $.clock.now());
-    const result = await next(e);
+    // The live step: the main loop's tool by name and since when, nothing else of the call.
+    const step = typeof e.agentId === "string" ? null : { name: e.tool, at: await $.clock.now() };
+    if (step) live.mainToolCalls += 1;
+    if (step) {
+      live.step = step;
+      await rebuild($, live);
+    }
+    let result;
+    try {
+      result = await next(e);
+    } finally {
+      if (step && live.step === step) live.step = live.isWorking ? { name: "thinking", at: await $.clock.now() } : null;
+    }
     if (typeof e.agentId === "string") {
       const now = await $.clock.now();
       live.activity = noteAgentActivity(live.activity, e.agentId, now);
       live.spawned = noteSpawnActivity(live.spawned, e.agentId, now);
     }
-    refreshSoon($, live);
+    refreshSoon($, live, options);
     return result;
   }).catch(($, e, next) => next(e));
 
+  // A model request on the main loop: the step reads "thinking" until a tool call names itself.
+  on("turn.step", async function* ($, e, next) {
+    if (typeof e.agentId !== "string" && live.isWorking && live.step?.name !== "thinking") live.step = { name: "thinking", at: await $.clock.now() };
+    return yield* next(e);
+  });
+
   // Every subagent, teammate and workflow agent starts here. A workflow's never shows in
   // `$.agent.list()`, so the card keeps its own record until the agent's turn.complete.
   on("agent.spawn", async ($, e, next) => {
     const result = await next(e);
     if (typeof result?.agentId === "string") {
       live.spawned = noteSpawn(live.spawned, { id: result.agentId, description: e.description, type: e.subagentType, at: await $.clock.now() });
-      refreshSoon($, live);
+      refreshSoon($, live, options);
     }
     return result;
   }).catch(($, e, next) => next(e));
 
   // A typed `/litclaude:<name>` and the Skill tool both expand the skill's prompt here; the text
-  // passes through untouched.
+  // passes through untouched. So does a subagent's preloaded skill (an agent's `skills:` list),
+  // and the event does not say whose it is: a firing counts only before the main loop's first tool
+  // call of the turn (a typed command) or inside its Skill call.
   on("skill.prompt", async ($, e, next) => {
-    await noteFiring($, live, e.skill);
+    if (live.mainToolCalls === 0 || live.step?.name === "Skill") await noteFiring($, live, e.skill);
     return next(e);
   }).catch(($, e, next) => next(e));
 
@@ -286,7 +341,14 @@ export const register = (on, options) => {
     const elements = $.ui.resolve(e);
     const columns = Math.max(20, e.props.bodyColumns ?? e.viewport?.columns ?? 80);
     let drawn = null;
-    if (elements.Client && !live.clientFailed) {
+    if (e.surface !== "terminal" && elements.Svg) {
+      // A desktop or editor draws Text in a proportional font, so the cell-built card comes apart
+      // there; those surfaces get the card as one drawing instead.
+      if (model.visible) {
+        const { source, alt, animated } = composeSvgCard(model, { motion: settings.motion, accent: live.accent });
+        drawn = elements.Svg({ source, alt, ...(animated ? { isInteractive: true } : {}) });
+      }
+    } else if (elements.Client && !live.clientFailed) {
       drawn = elements.Client({ key: "lit-band", module: "./lit-band-client.mjs", props: { model, columns, glyphs, motion: settings.motion, accent: live.accent } });
     } else if (model.visible) {
       drawn = renderBand(elements, composeBand(model, settledSample(model), { columns, glyphs, accent: live.accent }));

package/plugins/litclaude/lib/mod/frame.mjs

@@ -1,16 +1,25 @@
-// Turns a band model and one sampled frame into the LIT card: four rows of coloured spans. A span is
+// Turns a band model and one sampled frame into the LIT card: five rows of coloured spans. A span is
 // { text, fg?, bg?, bold? }; the surface module draws each row as a line of Text elements. The card
 // draws its own rounded border so the top edge can carry the title and the bottom edge the live
 // figures, and every row is fitted to exactly the card's width, counting Hangul and emoji as two
 // cells, so nothing wraps and the card keeps its height whether LitClaude is working or idle.
 //
-//   ╭─ [🔥 LIT] · lit-loop ─────────────────────────── WORK ● ─╮
-//   │ ● PLAN ━━ [WORK] ━━ ○ REVIEW              goal ██░░░ 2/5 │
-//   │ skills [⚡ lit-plan] [⚡ litresearch] [↯ lit-docx]        │
-//   ╰─ ctx 42% ▰▰▱▱▱ · 5h 31% · 1w 12% · git main ─────────────╯
+//   ╭─ [🔥 LIT] · start-work ───────────────────────────────── WORK ● ─╮
+//   │ interview ✓ ━━ plan ✓ ━━ [work 3/7] ━━ review · ── done ·  1 lane │
+//   │ └ task 3/7 ███░░░░░ · next ▸ 4. README demo        - Bash · 0:12 │
+//   │ skills [⚡ start-work] [↯ lit-plan]                               │
+//   ╰─ ctx 42% ▰▰▱▱▱ · 5h 31% · 1w 12% · git main ─────────────────────╯
 //
-// Each bracket pair stands for the two end cells of a filled pill: the brand on pink, the active
-// phase and this request's skills on the accent with dark text, skills from earlier requests on
+// The second row is the workflow map (workflow.mjs): done stages carry a check in a colour graded
+// along the rail from flame orange through pink to the accent, the current stage is a pill, the
+// stages ahead are dim. The rail leaving the current stage fills with its count and, while
+// LitClaude works, carries a bright head; the rails ahead are dim `─`. A narrow card drops the
+// rails, then shortens the names, then shows only the current stage and its neighbours. With no
+// family to place the session in, the row is the PLAN / WORK / REVIEW track instead. The third row
+// is the stage's detail and, on the right, the tool the main loop is running and for how long.
+//
+// Each bracket pair stands for the two end cells of a filled pill: the brand on pink, the current
+// stage and this request's skills on the accent with dark text, skills from earlier requests on
 // dark grey. Those end cells are rounded Nerd Font caps in the pill's colour, or one cell of
 // padding in that colour with basic glyphs, so a pill is as wide in either glyph set.
 //
@@ -19,10 +28,12 @@
 // colour of an ASCII cell, repaints. So every change is carried by ASCII: a bar cell is a space on
 // its colour and the leading cell fades in by colour, embers are ASCII sparks, labels pop in letter
 // by letter, a notice slides by its leading spaces, a chip's light moves over its ASCII name, and a
-// glyph swaps only together with the colour of its words.
+// glyph swaps only together with the colour of its words. The map's rail cells keep their glyph
+// and move by colour alone (a colour change on `─` or `━` repaints), and the live step's spinner
+// and clock are ASCII.
 
 import { textWidth, truncateToWidth } from "./layout.mjs";
-import { barCells, lerpColor } from "./motion.mjs";
+import { barCells, gradientAt, lerpColor } from "./motion.mjs";
 import { glyphSet } from "./settings.mjs";
 import { formatDuration } from "./view.mjs";
 
@@ -195,6 +206,12 @@ const brandSpans = (sample, glyphs) => {
 const indicatorSpans = (model, sample, glyphs, accent) => {
   if (sample.completion) return [span(`DONE ${glyphs.done}`, { fg: PALETTE.green, bold: true })];
   if (model.idle) return [span("idle", { fg: PALETTE.dim })];
+  const flow = model.workflow;
+  if (flow && flow.current >= 0) {
+    const warn = model.ctxWarning && sample.warn > 0.02;
+    return [span(`${flow.stages[flow.current].id.toUpperCase()} ${warn ? glyphs.warn : glyphs.now}`, { fg: warn ? lerpColor(accent, PALETTE.amber, sample.warn) : accent, bold: true })];
+  }
+  if (flow && model.lanes.count === 0) return [span(`DONE ${glyphs.done}`, { fg: PALETTE.green, bold: true })];
   const current = PHASES.find((id) => model.phases[id] === "now");
   if (current) return [span(`${LABELS[current]} ${warned(current, sample) ? glyphs.warn : glyphs.now}`, { fg: phaseColor(current, sample, inkOf(accent)), bold: true })];
   if (PHASES.every((id) => model.phases[id] === "done") && model.lanes.count === 0) return [span(`DONE ${glyphs.done}`, { fg: PALETTE.green, bold: true })];
@@ -292,6 +309,172 @@ const phaseRow = (model, sample, { inner, glyphs, accent }) => {
   return fitRow([...track, span(" ".repeat(Math.max(2, inner - rowWidth(track) - rowWidth(tail)))), ...tail], inner);
 };
 
+// The colour of a point `position` (0 to 1) of the way along the map: flame orange, pink, accent.
+const mapColor = (accent, position) => gradientAt([PALETTE.orange, PALETTE.pink, accent], position);
+
+// A stage name cut to its first three letters, its count kept: `work 3/7` becomes `wor 3/7`.
+const shortLabel = (label) => label.replace(/^[A-Za-z]+/u, (word) => word.slice(0, 3));
+
+// The rail from stage `index - 1` to stage `index`, `cells` wide. Behind the current stage it is
+// `━` graded along the map; leaving it, `━` filled by the stage's count with a bright head while
+// LitClaude works; ahead, dim `─`. With no room for rails, one space.
+const railSpans = (model, sample, index, cells, accent) => {
+  if (cells === 0) return [span(" ")];
+  const { stages } = model.workflow;
+  const last = Math.max(1, stages.length - 1);
+  const at = (cell) => (index - 1 + (cell + 0.5) / cells) / last;
+  const into = stages[index].state;
+  const from = stages[index - 1].state;
+  let body;
+  if (into === "done" || into === "now") {
+    body = Array.from({ length: cells }, (_, cell) => span("━", { fg: mapColor(accent, at(cell)) }));
+  } else if (from === "now") {
+    const filled = model.workflow.count ? sample.fill * cells : 0;
+    const flow = model.idle ? null : sample.ambient?.flow ?? null;
+    const head = flow === null ? -1 : Math.floor(flow * cells);
+    body = Array.from({ length: cells }, (_, cell) => {
+      const base = cell < filled ? mapColor(accent, at(cell)) : PILL.rail;
+      return span("━", { fg: cell === head ? lerpColor(base, "#ffffff", 0.75) : base });
+    });
+  } else {
+    body = [span("─".repeat(cells), { fg: PILL.rail })];
+  }
+  return [span(" "), ...body, span(" ")];
+};
+
+// interview ✓ ━━ plan ✓ ━━ [work 3/7] ━━ review · ── done ·
+const mapTrack = (model, sample, { glyphs, accent, rail, short = false, window = false }) => {
+  const { stages, current } = model.workflow;
+  const last = Math.max(1, stages.length - 1);
+  const focus = current < 0 ? stages.length - 1 : current;
+  const shown = stages.map((_, index) => index).filter((index) => !window || Math.abs(index - focus) <= 1);
+  const out = [];
+  if (window && shown[0] > 0) out.push(span("… ", { fg: PALETTE.dim }));
+  shown.forEach((index) => {
+    const stage = stages[index];
+    const label = short ? shortLabel(stage.label) : stage.label;
+    const text = stage.state === "now" ? label : `${label} ${stage.state === "done" ? glyphs.done : "·"}`;
+    const revealed = revealText(text, sample.pills[Math.min(3, 1 + Math.floor(index / 2))]);
+    if (revealed === null) return;
+    if (out.length && !(window && out.length === 1 && shown[0] > 0)) out.push(...railSpans(model, sample, index, rail, accent));
+    if (stage.state === "now") {
+      let fill = model.idle ? lerpColor(accent, PILL.muted, 0.5) : accent;
+      if (model.ctxWarning) fill = lerpColor(fill, PALETTE.amber, sample.warn);
+      if (sample.ambient && !model.idle) fill = lerpColor(fill, "#ffffff", 0.2 * sample.ambient.breath);
+      const sweep = model.idle ? null : sample.ambient?.sweep ?? null;
+      out.push(...pill(litText(revealed.slice(0, label.length).padEnd(label.length), { fg: PILL.ink, bg: fill, bold: true }, sweep), fill, glyphs));
+    } else {
+      out.push(span(revealed, { fg: stage.state === "done" ? mapColor(accent, index / last) : PALETTE.dim }));
+    }
+  });
+  if (window && shown.at(-1) < stages.length - 1) out.push(span(" …", { fg: PALETTE.dim }));
+  return out;
+};
+
+const MAP_VARIANTS = Object.freeze([
+  { rail: 2 },
+  { rail: 1 },
+  { rail: 0 },
+  { rail: 0, short: true },
+  { rail: 0, short: true, window: true },
+]);
+
+// The map, then the context warning, the lanes and the autoloop budget while there is room.
+const mapRow = (model, sample, { inner, glyphs, accent }) => {
+  const tracks = MAP_VARIANTS.map((variant) => mapTrack(model, sample, { glyphs, accent, ...variant }));
+  const track = tracks.find((candidate) => rowWidth(candidate) <= inner) ?? tracks.at(-1);
+  const right = [];
+  if (sample.rest > 0) {
+    if (model.ctxWarning && sample.warn > 0.02) {
+      right.push(segment("ctx", 1, [span(`ctx ${model.ctxWarning.percent}% → ${model.ctxWarning.threshold}%`, { fg: lerpColor(PALETTE.dim, PALETTE.amber, sample.warn), bold: sample.warn > 0.5 })]));
+    }
+    if (model.lanes.count > 0) {
+      const dots = model.lanes.list.slice(0, 4).map((lane) => span(glyphs.lane, { fg: lane.status === "stalled" ? PALETTE.amber : PALETTE.green }));
+      right.push(segment("lanes", 3, [...dots, span(` ${model.lanes.count} ${model.lanes.count === 1 ? "lane" : "lanes"}`, { fg: PALETTE.dim })]));
+    }
+    if (model.autoloop) {
+      right.push(segment("loop", 4, [span(`${glyphs.loop} ${model.autoloop.n}/${model.autoloop.max}`, { fg: PALETTE.violet }), span(` · ${formatDuration(model.autoloop.leftMs)}`, { fg: PALETTE.dim })]));
+    }
+  }
+  const kept = fitJoined(right, inner - rowWidth(track) - 2);
+  const tail = joinSegments(kept, PALETTE.faint);
+  if (!tail.length) return fitRow(track, inner);
+  return fitRow([...track, span(" ".repeat(Math.max(2, inner - rowWidth(track) - rowWidth(tail)))), ...tail], inner);
+};
+
+const SPINNER = Object.freeze(["-", "\\", "|", "/"]);
+
+// m:ss, or h:mm:ss past the hour.
+export const formatClock = (ms) => {
+  const seconds = Math.max(0, Math.floor(ms / 1000));
+  const minutes = Math.floor(seconds / 60);
+  const ss = String(seconds % 60).padStart(2, "0");
+  return minutes >= 60 ? `${Math.floor(minutes / 60)}:${String(minutes % 60).padStart(2, "0")}:${ss}` : `${minutes}:${ss}`;
+};
+
+// The live step: an ASCII spinner, the tool's name and how long it has run. Nothing else of the call.
+const stepSpans = (sample, accent) => {
+  if (!sample.step) return [];
+  return [
+    span(`${SPINNER[sample.spin ?? 0]} `, { fg: accent, bold: true }),
+    span(sample.step.name, { fg: PALETTE.white }),
+    span(` · ${formatClock(sample.step.elapsedMs)}`, { fg: PALETTE.dim }),
+  ];
+};
+
+const VERDICT_STYLE = Object.freeze({
+  pass: (glyphs) => [glyphs.done, PALETTE.green],
+  fail: (glyphs) => [glyphs.fail, PALETTE.red],
+  pending: () => ["·", PALETTE.dim],
+  running: (glyphs) => [glyphs.lane, PALETTE.amber],
+});
+
+// The review lanes or a crucible verdict: each name in its verdict's colour (a lane under review
+// amber), so a change repaints.
+// `cut` shortens the names to that many letters; 0 drops them and leaves the marks.
+const verdictSpans = (verdicts, glyphs, cut = Infinity) => verdicts.flatMap(({ name, state }, index) => {
+  const [mark, color] = VERDICT_STYLE[state](glyphs);
+  const text = cut === 0 ? mark : `${name.slice(0, cut)} ${mark}`;
+  return [...(index > 0 ? [span(" ")] : []), span(text, { fg: color })];
+});
+
+// └ task 3/7 ███░░░░░ · paused · next ▸ <task>                    - Bash · 0:12
+const detailRow = (model, sample, { inner, glyphs, accent }) => {
+  const flow = model.workflow;
+  const right = stepSpans(sample, accent);
+  const segments = [];
+  if (flow?.count) {
+    const { done, total, unit } = flow.count;
+    const glow = sample.ambient && !model.idle ? 0.5 * sample.ambient.breath : sample.fillGlow ?? 0;
+    const bar = barCells(sample.fill, inner >= 70 ? 8 : 5, glow).map(({ glyph, color }) => (glyph === "█" ? span(" ", { bg: color }) : span(glyph, { fg: color })));
+    segments.push(segment("count", 1, [
+      span(`${unit} `, { fg: PALETTE.dim }),
+      span(String(done), { fg: lerpColor(PALETTE.white, PALETTE.cyan, Math.max(sample.flash, sample.fillGlow ?? 0)), bold: true }),
+      span(`/${total} `, { fg: PALETTE.dim }),
+      ...bar,
+    ], " · "));
+  }
+  const lead = [span("└ ", { fg: PALETTE.dim })];
+  const room = inner - rowWidth(lead) - (right.length ? rowWidth(right) + 2 : 0);
+  if (flow?.verdicts) {
+    const before = segments.reduce((sum, part) => sum + part.width + textWidth(part.joiner), 0);
+    const forms = [Infinity, 3, 0].map((cut) => segment("verdicts", 2, verdictSpans(flow.verdicts, glyphs, cut), " · "));
+    segments.push(forms.find((form) => before + form.width <= room) ?? forms.at(-1));
+  }
+  (flow?.items ?? []).forEach((item, index) => segments.push(segment(`item-${index}`, 3 + index, [span(item, { fg: PALETTE.white })], " · ")));
+  let left = joinSegments(fitJoined(segments, room), PALETTE.faint);
+  if (flow?.next) {
+    const gap = left.length ? [span(" · ", { fg: PALETTE.faint })] : [];
+    const label = [span("next ", { fg: PALETTE.dim }), span(`${glyphs.next} `, { fg: accent })];
+    const avail = room - rowWidth(left) - rowWidth(gap) - rowWidth(label);
+    if (avail >= 6) left = [...left, ...gap, ...label, span(truncateToWidth(flow.next, avail), { fg: PALETTE.white })];
+  }
+  if (!left.length && !right.length) return fitRow([], inner);
+  const body = [...lead, ...left];
+  if (!right.length) return fitRow(body, inner);
+  return fitRow([...body, span(" ".repeat(Math.max(1, inner - rowWidth(body) - rowWidth(right)))), ...right], inner);
+};
+
 const CHIP_TONE = Object.freeze({
   current: (accent) => ({ fill: accent, text: PILL.ink }),
   recent: () => ({ fill: PILL.muted, text: PILL.mutedText }),
@@ -320,7 +503,7 @@ const mutedPill = (text, glyphs) => pill([span(text, { fg: PALETTE.dim, bg: PILL
 const chipsRow = (model, sample, { inner, glyphs, accent }) => {
   const chips = model.skills;
   if (chips.length === 0) {
-    if (!model.idle && model.next) return fitRow([span("▸ ", { fg: accent }), span(truncateToWidth(model.next, inner - 2), { fg: PALETTE.white })], inner);
+    if (!model.idle && model.next && !model.workflow?.next) return fitRow([span("▸ ", { fg: accent }), span(truncateToWidth(model.next, inner - 2), { fg: PALETTE.white })], inner);
     if (!model.idle) return fitRow([span("no LitFamily skill yet in this request", { fg: PALETTE.dim })], inner);
     const hints = [
       [span("no LitFamily skill yet · type ", { fg: PALETTE.dim }), span("lit <task>", { fg: accent }), span(" to start one", { fg: PALETTE.dim })],
@@ -416,9 +599,10 @@ const edgeColor = (model, sample, accent) => {
 };
 
 /**
- * The card for one frame: `{ mode: "card", border, width, rows }`, always four rows (top edge,
- * phase row, chips row, bottom edge), each exactly `width` cells: the terminal's columns up to
- * CARD_MAX. `accent` is the status line's accent colour (settings.mjs accentFromSettings).
+ * The card for one frame: `{ mode: "card", border, width, rows }`, always five rows (top edge,
+ * workflow map or phase track, detail line, chips row, bottom edge), each exactly `width` cells:
+ * the terminal's columns up to CARD_MAX. `accent` is the status line's accent colour
+ * (settings.mjs accentFromSettings).
  */
 export const composeBand = (model, sample, { columns, glyphs: glyphMode = "basic", accent = PALETTE.accent }) => {
   const glyphs = glyphSet(glyphMode);
@@ -432,7 +616,13 @@ export const composeBand = (model, sample, { columns, glyphs: glyphMode = "basic
     mode: "card",
     border: edge,
     width,
-    rows: [topEdge(model, sample, options), side(phaseRow(model, sample, options)), side(middle), bottomEdge(model, sample, options)],
+    rows: [
+      topEdge(model, sample, options),
+      side(model.workflow ? mapRow(model, sample, options) : phaseRow(model, sample, options)),
+      side(detailRow(model, sample, options)),
+      side(middle),
+      bottomEdge(model, sample, options),
+    ],
   };
 };
 

package/plugins/litclaude/lib/mod/motion.mjs

@@ -30,6 +30,8 @@ export const TIMINGS = Object.freeze({
   breath: 2400,
   sweep: 1800,
   comet: 2600,
+  flow: 1400,
+  spin: 120,
   ambientFrame: 66,
 });
 

package/plugins/litclaude/lib/mod/settings.mjs

@@ -1,12 +1,15 @@
-// The LIT band's three userConfig options. The manifest declares them as plain strings without an
+// The LIT band's four userConfig options. The manifest declares them as plain strings without an
 // `options` list, because Claude Code 2.1.270 and older refuse a whole plugin whose userConfig has
 // one; the values are checked here instead, and anything unknown falls back to the default (the
-// first choice).
+// first choice). `notify` raises a notification through the person's own channel when LIT work
+// completes or a LIT turn longer than three minutes ends; `finish+sound` adds a sound only where
+// the plugin ships one, and none ships yet, so it notifies like `finish`.
 
 export const MOD_CHOICES = Object.freeze({
   motion: ["full", "subtle", "off"],
   glyphs: ["auto", "nerd", "basic"],
   band: ["always", "auto", "off"],
+  notify: ["off", "finish", "finish+sound"],
 });
 
 const pick = (value, choices) => {
@@ -18,6 +21,7 @@ export const normalizeModSettings = (options) => ({
   motion: pick(options?.motion, MOD_CHOICES.motion),
   glyphs: pick(options?.glyphs, MOD_CHOICES.glyphs),
   band: pick(options?.band, MOD_CHOICES.band),
+  notify: pick(options?.notify, MOD_CHOICES.notify),
 });
 
 // The glyph set one surface draws. Private-use Nerd Font glyphs only reach the terminal, which