@litfamily/litclaude 1.0.21 → 1.0.23

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

@@ -0,0 +1,314 @@
+// 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.
+// 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
+// below takes `$` and the per-load `live` record explicitly instead of closing over them.
+
+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 { 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";
+import {
+  EMPTY_ACTIVITY,
+  buildBandModel,
+  buildEvidenceModel,
+  detectCompletion,
+  diffNotices,
+  noteAgentActivity,
+  spinnerSuffix,
+  trackAgents,
+} from "../lib/mod/view.mjs";
+
+const PANE = "lit-evidence";
+const POLL_MS = 2000;
+const QUICK_REFRESH_MS = 250;
+const TABS = Object.freeze([
+  { id: "goal", label: "goal", hotkey: "1" },
+  { 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 createLive = (options) => ({
+  band: normalizeModSettings(options).band,
+  iconFont: { present: false, path: null, note: "basic: not checked yet" },
+  env: {},
+  snapshot: null,
+  model: null,
+  agents: [],
+  usage: null,
+  activity: EMPTY_ACTIVITY,
+  statusById: {},
+  isWorking: false,
+  notice: null,
+  completion: null,
+  exiting: false,
+  clientFailed: false,
+  refreshing: false,
+  quickPending: false,
+  paneOpen: false,
+  evidenceTab: "goal",
+  ledger: [],
+  celebrated: new Set(),
+  accent: undefined,
+  git: null,
+  fired: [],
+  settledAt: 0,
+  ignitionAt: undefined,
+  lastDiscipline: null,
+});
+
+const stateIo = ($) => ({
+  stat: (path) => $.fs.stat(path, { resolve: true }),
+  read: (path) => $.fs.read(path),
+});
+
+const toastText = (raised) => `🔥 ${raised.title}${raised.detail ? ` · ${raised.detail}` : ""}`;
+
+async function rebuild($, live) {
+  const now = await $.clock.now();
+  const previous = live.model;
+  const next = buildBandModel({
+    snapshot: live.snapshot ?? NO_SNAPSHOT,
+    agents: live.agents,
+    activity: live.activity,
+    usage: live.usage,
+    now,
+    band: live.band,
+    isWorking: live.isWorking,
+    notice: live.notice,
+    completion: live.completion,
+    skills: chipStates(live.fired, live.settledAt),
+    lastDiscipline: live.lastDiscipline,
+    git: live.git,
+  });
+  live.model = next;
+  if (previous?.visible && !next.visible && !live.exiting) {
+    // Keep the band mounted while its surface module plays the exit, then let it go.
+    live.exiting = true;
+    $.clock.after(TIMINGS.exit + 80, () => {
+      live.exiting = false;
+      $.ui.invalidate("ui.render");
+    });
+  }
+  if (JSON.stringify(previous) !== JSON.stringify(next)) $.ui.invalidate("ui.render");
+  return next;
+}
+
+function showNotice($, live, raised) {
+  live.notice = raised;
+  $.ui.toast(toastText(raised));
+  $.clock.after(TIMINGS.noticeHold, () => {
+    if (live.notice?.id !== raised.id) return;
+    live.notice = null;
+    void rebuild($, live);
+  });
+}
+
+function celebrate($, live, finish) {
+  if (live.celebrated.has(finish.id)) return;
+  live.celebrated.add(finish.id);
+  live.completion = finish;
+  $.clock.after(TIMINGS.completion + 200, () => {
+    if (live.completion?.id !== finish.id) return;
+    live.completion = null;
+    void rebuild($, live);
+  });
+}
+
+// A firing of a skill or command by name; anything that is not LitClaude's is ignored.
+async function noteFiring($, live, name) {
+  const id = litSkillId(name);
+  if (!id) return;
+  live.fired = noteSkill(live.fired, id, await $.clock.now());
+  live.lastDiscipline = id;
+  await rebuild($, live);
+}
+
+// The prompt hook rewrites the ignition record on every prompt; a new record naming a discipline is
+// a bare `lit` (or slash) routing, and lights that skill's chip at the time the hook wrote it.
+function noteIgnition(live, ignition, now) {
+  if (!ignition || ignition.at === live.ignitionAt) return;
+  live.ignitionAt = ignition.at;
+  live.lastDiscipline = ignition.discipline;
+  const id = litSkillId(ignition.discipline);
+  if (id) live.fired = noteSkill(live.fired, id, ignition.at ?? now);
+}
+
+async function refresh($, live) {
+  if (live.refreshing) return;
+  live.refreshing = true;
+  try {
+    const [cwd, sessionId] = await Promise.all([$.session.cwd(), $.session.id()]);
+    const fresh = await readLitSnapshot(stateIo($), { cwd, sessionId, env: live.env });
+    live.git = await readGitBranch(stateIo($), cwd).catch(() => live.git);
+    live.agents = await $.agent.list().catch(() => []);
+    live.usage = await $.session.usage().catch(() => live.usage);
+    const now = await $.clock.now();
+    live.activity = trackAgents(live.activity, live.agents, live.statusById, now);
+    live.statusById = Object.fromEntries(live.agents.map((agent) => [agent.id, agent.status]));
+    const before = live.snapshot;
+    const previousModel = live.model;
+    live.snapshot = fresh;
+    noteIgnition(live, fresh.ignition, now);
+    const finish = detectCompletion(before, fresh);
+    if (finish) celebrate($, live, finish);
+    const next = await rebuild($, live);
+    const raised = diffNotices(before, fresh, previousModel, next);
+    if (raised.length > 0) {
+      for (const extra of raised.slice(0, -1)) $.ui.toast(toastText(extra));
+      showNotice($, live, raised.at(-1));
+      await rebuild($, live);
+    }
+    if (live.paneOpen) live.ledger = await readLedgerTail(stateIo($), fresh.stateRoot);
+  } catch {
+    // A failed read leaves the last good band in place; the next poll tries again.
+  } finally {
+    live.refreshing = false;
+  }
+}
+
+function refreshSoon($, live) {
+  if (live.quickPending) return;
+  live.quickPending = true;
+  $.clock.after(QUICK_REFRESH_MS, () => {
+    live.quickPending = false;
+    void refresh($, live);
+  });
+}
+
+export const register = (on, options) => {
+  const live = createLive(options);
+
+  on("session.start", async ($, e, next) => {
+    live.env = {
+      TMPDIR: await $.env.get("TMPDIR"),
+      LITCLAUDE_HUD_STATE_ROOT: await $.env.get("LITCLAUDE_HUD_STATE_ROOT"),
+      LITCLAUDE_AUTO_HANDOFF: await $.env.get("LITCLAUDE_AUTO_HANDOFF"),
+      LITCLAUDE_AUTO_HANDOFF_PERCENT: await $.env.get("LITCLAUDE_AUTO_HANDOFF_PERCENT"),
+    };
+    live.iconFont = await detectIconFont(stateIo($), {
+      HOME: await $.env.get("HOME"),
+      XDG_DATA_HOME: await $.env.get("XDG_DATA_HOME"),
+      LOCALAPPDATA: await $.env.get("LOCALAPPDATA"),
+    });
+    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);
+    $.clock.every(POLL_MS, () => {
+      void refresh($, live);
+    });
+    return next(e);
+  });
+
+  on("turn.start", async ($, e, next) => {
+    live.isWorking = true;
+    refreshSoon($, live);
+    return next(e);
+  });
+
+  on("turn.complete", async ($, e, next) => {
+    live.isWorking = false;
+    // The request is over: its chips dim to the recent list until a skill fires again.
+    live.settledAt = await $.clock.now();
+    refreshSoon($, live);
+    return next(e);
+  });
+
+  on("session.measure", async ($, e, next) => {
+    live.usage = { context: e.context, rateLimits: e.rateLimits };
+    if (e.changed.includes("context")) refreshSoon($, live);
+    return next(e);
+  });
+
+  on("tool.call", async ($, e, next) => {
+    if (e.tool === "Skill") await noteFiring($, live, e.skill);
+    const result = await next(e);
+    if (typeof e.agentId === "string") live.activity = noteAgentActivity(live.activity, e.agentId, await $.clock.now());
+    refreshSoon($, live);
+    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.
+  on("skill.prompt", async ($, e, next) => {
+    await noteFiring($, live, e.skill);
+    return next(e);
+  }).catch(($, e, next) => next(e));
+
+  on("ui.fault", async ($, e, next) => {
+    if (e.component === "AbovePrompt") live.clientFailed = true;
+    return next(e);
+  });
+
+  on("ui.render", { component: "AbovePrompt" }, async ($, e, next) => {
+    const settings = normalizeModSettings(options);
+    const glyphs = resolveGlyphs(settings.glyphs, e.surface, live.iconFont.present);
+    const model = live.model;
+    if (!model || settings.band === "off" || e.props.hasSurvey || (!model.visible && !live.exiting)) return next(e);
+    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) {
+      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 }));
+    }
+    const below = await next(e);
+    if (!drawn) return below;
+    return below ? elements.Box({ flexDirection: "column", children: [drawn, below] }) : drawn;
+  });
+
+  on("ui.render", { component: "Spinner" }, async ($, e, next) => {
+    const suffix = spinnerSuffix(live.model, e.props.suffix);
+    return suffix ? next({ ...e, props: { ...e.props, suffix } }) : next(e);
+  });
+
+  on("command.run", { command: PANE }, async ($) => {
+    live.paneOpen = true;
+    if (live.snapshot) live.ledger = await readLedgerTail(stateIo($), live.snapshot.stateRoot);
+    await $.ui.open({ id: PANE, title: "LIT evidence", focus: true, closeOnEscape: true });
+    return {};
+  }).catch(() => ({ text: "The LIT evidence pane could not open; LitClaude state is unchanged." }));
+
+  on("ui.close", async ($, e, next) => {
+    if (e.id === PANE) live.paneOpen = false;
+    return next(e);
+  }).catch(($, e, next) => next(e));
+
+  on("ui.render", { component: "Pane", requestId: PANE }, async ($, e) => {
+    const settings = normalizeModSettings(options);
+    const glyphs = resolveGlyphs(settings.glyphs, e.surface, live.iconFont.present);
+    const elements = $.ui.resolve(e);
+    const columns = Math.max(20, e.props.bodyColumns ?? 60);
+    const now = await $.clock.now();
+    const evidence = buildEvidenceModel({ snapshot: live.snapshot ?? NO_SNAPSHOT, ledger: live.ledger, agents: live.agents, activity: live.activity, now, icons: `${glyphs} glyphs (${settings.glyphs}); ${live.iconFont.note}` });
+    const tabs = TABS.map((tab) => elements.Button({
+      key: `tab-${tab.id}`,
+      label: tab.label,
+      hotkey: tab.hotkey,
+      plain: true,
+      dimColor: tab.id !== live.evidenceTab,
+      onPress: () => {
+        live.evidenceTab = tab.id;
+        $.ui.invalidate("ui.render");
+      },
+    }));
+    return elements.Box({
+      flexDirection: "column",
+      children: [
+        elements.Box({ flexDirection: "row", gap: 2, children: tabs }),
+        ...renderRows(elements, composeEvidence(evidence, live.evidenceTab, { columns, glyphs })),
+      ],
+    });
+  });
+};

package/plugins/litclaude/lib/auto-handoff.mjs

@@ -16,6 +16,7 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { latestUsageTokens } from "./cache-measurement.mjs";
+import { ensureStateDirIgnored } from "./project-state-root.mjs";
 
 export const AUTO_HANDOFF_FLAG = "LITCLAUDE_AUTO_HANDOFF";
 export const AUTO_HANDOFF_PERCENT = "LITCLAUDE_AUTO_HANDOFF_PERCENT";
@@ -62,6 +63,7 @@ const stateDirectory = (stateRoot, { create = false } = {}) => {
     }
     if (!stat.isDirectory()) throw new Error("state folder is not a real folder");
   }
+  if (create) ensureStateDirIgnored(directory);
   return directory;
 };
 

package/plugins/litclaude/lib/automatic-update-refresh.mjs

@@ -0,0 +1,4 @@
+import { refreshSessionUpdateCache } from "./automatic-update.mjs";
+
+const [cachePath, generation, registryUrl] = process.argv.slice(2);
+if (cachePath && generation && registryUrl) await refreshSessionUpdateCache({ cachePath, generation, registryUrl });

package/plugins/litclaude/lib/automatic-update.mjs

@@ -1,4 +1,4 @@
-import { spawnSync as nodeSpawnSync } from "node:child_process";
+import { spawn as nodeSpawn, spawnSync as nodeSpawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import {
   appendFileSync,
@@ -15,6 +15,7 @@ import {
 } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 export const PACKAGE_NAME = "@litfamily/litclaude";
 const MARKETPLACE_NAME = "litclaude-ai";
@@ -25,6 +26,9 @@ export const AUTO_UPDATE_TIMEOUT_MS = AUTO_UPDATE_INSTALL_TIMEOUT_MS + AUTO_UPDA
 export const AUTO_UPDATE_LOCK_STALE_MS = 60_000;
 export const AUTO_UPDATE_MAX_OUTPUT_BYTES = 128 * 1_024;
 export const AUTO_UPDATE_SCHEMA = 1;
+const REGISTRY_REQUEST_TIMEOUT_MS = 3_000;
+const REGISTRY_MAX_RESPONSE_BYTES = 64 * 1_024;
+const DEFAULT_REGISTRY = "https://registry.npmjs.org/";
 
 const stableSemverPattern = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)$/u;
 const generationPattern = /^[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/u;
@@ -456,6 +460,131 @@ const resultWithoutSecrets = ({ receiptPath, journalPath, backupPath, ...result
   backupPath: backupPath ?? null,
 });
 
+const readCacheRecord = (cachePath, now) => {
+  try {
+    const parsed = JSON.parse(readFileSync(cachePath, "utf8"));
+    return validCacheRecord(parsed, now) ? parsed : null;
+  } catch {
+    return null;
+  }
+};
+
+// The install child sees only a sanitized `npm_config_registry`, so the version check
+// reads that same registry, and the npm default otherwise.
+const registryLatestUrl = (env = process.env) => {
+  const registry = safeUrl(env?.npm_config_registry ?? env?.NPM_CONFIG_REGISTRY) ?? DEFAULT_REGISTRY;
+  return new URL(`${encodeURIComponent(PACKAGE_NAME)}/latest`, registry).toString();
+};
+
+const readCappedBody = async (response) => {
+  const length = response.headers.get("content-length");
+  if (length !== null && (!/^(0|[1-9]\d*)$/u.test(length) || Number(length) > REGISTRY_MAX_RESPONSE_BYTES)) {
+    throw new Error("registry response is too large");
+  }
+  const chunks = [];
+  let size = 0;
+  for await (const chunk of response.body ?? []) {
+    size += chunk.byteLength;
+    if (size > REGISTRY_MAX_RESPONSE_BYTES) throw new Error("registry response is too large");
+    chunks.push(Buffer.from(chunk));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+// Runs in the detached child. It writes only when the attempt it was started for still
+// owns the cache, so a newer attempt or the terminal notifier is never overwritten.
+export const refreshSessionUpdateCache = async ({
+  cachePath,
+  generation,
+  registryUrl,
+  fetch = globalThis.fetch,
+  now = () => Date.now(),
+} = {}) => {
+  try {
+    if (!safeUrl(registryUrl, { allowPath: true })) return false;
+    const response = await fetch(registryUrl, {
+      headers: { accept: "application/json", "user-agent": "litclaude-ai-update-notifier" },
+      redirect: "error",
+      signal: AbortSignal.timeout(REGISTRY_REQUEST_TIMEOUT_MS),
+    });
+    if (response.status !== 200) return false;
+    if (!/^application\/json(?:\s*;\s*charset=(?:utf-8|utf8))?$/iu.test(response.headers.get("content-type")?.trim() ?? "")) return false;
+    const parsed = JSON.parse(await readCappedBody(response));
+    if (parsed?.name !== PACKAGE_NAME) return false;
+    parseStableSemver(parsed.version);
+    const completedAt = canonicalNow(now);
+    const previous = readCacheRecord(cachePath, completedAt);
+    if (previous?.generation !== generation) return false;
+    writeAtomic(cachePath, `${JSON.stringify({
+      schema: 3,
+      packageName: PACKAGE_NAME,
+      latestVersion: parsed.version,
+      checkedAt: new Date(completedAt).toISOString(),
+      attemptedAt: previous.attemptedAt,
+      generation,
+    })}\n`);
+    return true;
+  } catch {
+    return false;
+  }
+};
+
+const spawnSessionCacheRefresh = (cachePath, generation, registryUrl, env = process.env, spawnProcess = nodeSpawn) => {
+  const child = spawnProcess(
+    process.execPath,
+    [fileURLToPath(new URL("./automatic-update-refresh.mjs", import.meta.url)), cachePath, generation, registryUrl],
+    { detached: true, stdio: "ignore", windowsHide: true, env: sanitizeNpmEnvironment(env) },
+  );
+  child.once("error", () => {});
+  child.unref();
+  return true;
+};
+
+// SessionStart never waits on the network. It records the attempt (one per 24 hours),
+// hands the registry request to a detached child, and a later session reads the result.
+// A cache file it cannot read as its own record, such as another package's, is left as is.
+const scheduleSessionCacheRefresh = ({ cachePath, env, now, spawnRefresh }) => {
+  try {
+    const previous = readCacheRecord(cachePath, now);
+    if (!previous && existsSync(cachePath)) return "preserved";
+    if (previous && now - Date.parse(previous.attemptedAt) < CACHE_TTL_MS) return "throttled";
+    const generation = randomUUID();
+    writeAtomic(cachePath, `${JSON.stringify({
+      schema: 3,
+      packageName: PACKAGE_NAME,
+      latestVersion: previous?.latestVersion ?? null,
+      checkedAt: previous?.checkedAt ?? null,
+      attemptedAt: new Date(now).toISOString(),
+      generation,
+    })}\n`);
+    return spawnRefresh(cachePath, generation, registryLatestUrl(env), env) === false ? "spawn-error" : "scheduled";
+  } catch {
+    return "spawn-error";
+  }
+};
+
+const installedPluginVersion = (claudeHome) => {
+  try {
+    const registry = JSON.parse(readFileSync(join(claudeHome, "plugins", "installed_plugins.json"), "utf8"));
+    const version = registry?.plugins?.["litclaude@litclaude-ai"]?.[0]?.version;
+    parseStableSemver(version);
+    return version;
+  } catch {
+    return null;
+  }
+};
+
+const recentlyFailed = (autoRoot, targetVersion, now) => {
+  try {
+    const receipt = JSON.parse(readFileSync(join(autoRoot, "receipt.json"), "utf8"));
+    if (!["rolled-back", "failed"].includes(receipt?.status) || receipt.targetVersion !== targetVersion) return false;
+    const age = now - Date.parse(receipt.finishedAt);
+    return age >= 0 && age < CACHE_TTL_MS;
+  } catch {
+    return false;
+  }
+};
+
 export const runAutomaticUpdate = ({
   surface = "management",
   command = "install",
@@ -477,6 +606,7 @@ export const runAutomaticUpdate = ({
   spawn = nodeSpawnSync,
   verifyInstall = verifyInstalledVersion,
   restore = restoreTransaction,
+  spawnRefresh = spawnSessionCacheRefresh,
 } = {}) => {
   const resolvedLitHome = litHome ?? env.LITCLAUDE_HOME ?? resolveHome();
   const resolvedClaudeHome = claudeHome ?? env.CLAUDE_CONFIG_DIR ?? env.CLAUDE_HOME ?? resolveClaudeHome();
@@ -493,9 +623,26 @@ export const runAutomaticUpdate = ({
   }
   const timestamp = canonicalNow(now);
   const candidate = readCacheCandidate(resolvedCachePath, currentVersion, timestamp);
+  if (surface === "session-start" && ["stale-cache", "no-candidate"].includes(candidate.status)) {
+    return {
+      ...candidate,
+      refresh: scheduleSessionCacheRefresh({ cachePath: resolvedCachePath, env, now: timestamp, spawnRefresh }),
+    };
+  }
   if (candidate.status !== "candidate") return candidate;
+  // A long-lived Claude Code process keeps running the hook from the version folder it
+  // started with, so its own version lags behind what an earlier session installed.
+  const installedVersion = installedPluginVersion(resolvedClaudeHome);
+  if (installedVersion && compareStableSemver(installedVersion, candidate.version) >= 0) {
+    return { status: "already-installed", installedVersion, targetVersion: candidate.version };
+  }
 
   const autoRoot = automaticUpdateRoot(resolvedLitHome);
+  // A failed target stays in the cache until the registry moves on, so without this every
+  // new session would spend the whole install budget on it again.
+  if (recentlyFailed(autoRoot, candidate.version, timestamp)) {
+    return { status: "backoff", targetVersion: candidate.version };
+  }
   const lockPath = join(autoRoot, "install.lock");
   let lease;
   try {

package/plugins/litclaude/lib/cache-measurement.mjs

@@ -4,8 +4,9 @@
 // provider usage fields. This module never returns transcript text, rule bodies,
 // file contents, secrets, or network metadata.
 
+import { lstatSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
-import { MAX_BOUNDED_FILE_BYTES, readRegularStable } from "./secure-path-read.mjs";
+import { MAX_BOUNDED_FILE_BYTES, readRegularStable, readRegularTail } from "./secure-path-read.mjs";
 import { dedupeByBody } from "./rules/format.mjs";
 
 const MAX_TRANSCRIPT_BYTES = MAX_BOUNDED_FILE_BYTES;
@@ -177,11 +178,71 @@ export const latestUsageTokensFromText = (transcriptText) => {
   return latest ?? 0;
 };
 
+// A long session's transcript outgrows the whole-file bound, but the latest usage record sits
+// near its end. Read a short tail first and the full bound only when that tail holds none.
+const USAGE_TAIL_WINDOWS = [2 * 1024 * 1024, MAX_TRANSCRIPT_BYTES];
+
+// The read starts one byte before the window. When that byte is a newline the window begins on
+// a whole record and keeps it; otherwise everything up to the first newline is a cut fragment.
+export const latestUsageTokensInTail = (transcriptPath, windowBytes) => {
+  const result = readRegularTail(dirname(transcriptPath), transcriptPath, windowBytes + 1);
+  if (result.failure) return { tokens: 0, failed: true, truncated: false };
+  let text = result.bytes.toString("utf8");
+  if (result.truncated) {
+    const firstBreak = text.indexOf("\n");
+    text = firstBreak === -1 ? "" : text.slice(firstBreak + 1);
+  }
+  return { tokens: latestUsageTokensFromText(text), failed: false, truncated: result.truncated };
+};
+
+const latestUsageTokensFromTail = (transcriptPath) => {
+  for (const window of USAGE_TAIL_WINDOWS) {
+    const { tokens, failed, truncated } = latestUsageTokensInTail(transcriptPath, window);
+    if (failed) return 0;
+    if (tokens > 0 || !truncated) return tokens;
+  }
+  return 0;
+};
+
+/**
+ * latestUsageTokens behind a one-entry cache file keyed by the transcript's path, file identity,
+ * size and mtime. The status line redraws far more often than the transcript changes, and a
+ * long transcript whose last 2 MiB holds no usage record would otherwise cost an 8 MiB read on
+ * every redraw. The cache holds only that key and a number; any cache failure just reads.
+ */
+export const latestUsageTokensCached = (transcriptPath, cachePath) => {
+  if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return 0;
+  let key;
+  try {
+    const stats = lstatSync(transcriptPath);
+    key = { path: transcriptPath, dev: stats.dev, ino: stats.ino, size: stats.size, mtimeMs: stats.mtimeMs };
+  } catch {
+    return 0;
+  }
+  try {
+    const cached = JSON.parse(readFileSync(cachePath, "utf8"));
+    if (Object.keys(key).every((field) => cached?.[field] === key[field]) && Number.isSafeInteger(cached.tokens)) return cached.tokens;
+  } catch {
+    // No usable cache entry: measure below.
+  }
+  const tokens = latestUsageTokens(transcriptPath);
+  try {
+    mkdirSync(dirname(cachePath), { recursive: true });
+    const staging = `${cachePath}.${process.pid}.tmp`;
+    writeFileSync(staging, `${JSON.stringify({ ...key, tokens })}\n`);
+    renameSync(staging, cachePath);
+  } catch {
+    // The number is still right; only the next redraw pays for the read again.
+  }
+  return tokens;
+};
+
 /** Match HUD context sizing while applying the same bounded local-file policy. */
 export const latestUsageTokens = (transcriptPath) => {
   if (typeof transcriptPath !== "string" || transcriptPath.length === 0) return 0;
   try {
     const result = readRegularStable(dirname(transcriptPath), transcriptPath, undefined, { maxBytes: MAX_TRANSCRIPT_BYTES });
+    if (result.failure === "FILE_TOO_LARGE") return latestUsageTokensFromTail(transcriptPath);
     return result.failure ? 0 : latestUsageTokensFromText(result.bytes.toString("utf8"));
   } catch {
     return 0;

package/plugins/litclaude/lib/canonical-skill-resources.mjs

@@ -14,7 +14,7 @@ export const canonicalSkillResourceManifest = Object.freeze(
     ["lib/office-runtime-lock/package-lock.json", "4b9552dba69bf2803cecdf71996d26de0497004c00d1e1f5753a5b299f85d8ba"],
     ["lib/office-runtime-lock/package.json", "edf7fee2ba78d6ad42bf5761678b2a2210adb7282108864360f83c46adb59708"],
     ["lib/office-runtime-lock/requirements.lock", "7c63ce0de1ae9a912d1e546e9c01dd99a705d4a50435f36040d351cc3e6e6014"],
-    ["lib/office-runtime.mjs", "268e8ca9bb6a08dcb43ea2b40c899e776db850adfcb284a89d315d3c1a535438"],
+    ["lib/office-runtime.mjs", "24d108a4ae7aa98dd0d6f2fa66686d7c9f020ecf42fe641241be2869075bbea3"],
     ["lib/office_data.py", "0f4c2449622b6d59630e60508594d181279052c41918df4370e11a68df1ee239"],
     ["lib/office_runtime_bootstrap.py", "28812ef485f73f413c6d08cfff326290b301a0d7358260a2a0496edd8f71f4e9"],
     ["lib/ooxml_integrity.py", "85e5cba28aa3b9f4f4c28f59c6118439a985fe4f29e25274ae63e9ef1edf15e3"],
@@ -24,20 +24,20 @@ export const canonicalSkillResourceManifest = Object.freeze(
     ["lib/render_pages.py", "413f5fc234f69493ebbb62dbc3c9d683435fed2ce09c5cf5ae576095a57de071"],
     ["lib/rules/constants.mjs", "de97cc08ca834c35ba89a3d384517ae3f24fd52502b8ccd7a3c8227981e3f6c9"],
     ["lib/rules/discovery.mjs", "8a3d445c2d55c4d65c721c2724c4f927ffbd6dfa31472be857d9c827274c6456"],
-    ["lib/rules/engine.mjs", "ce7a019d51c87af875d5ef21004c08f0c333c4cf9696afa28b85fc7ece3cd5d1"],
-    ["lib/rules/format.mjs", "3def47d9c479ed123f94602ad6eb1fcec8ce992ef0ff23516826860e92456e8f"],
+    ["lib/rules/engine.mjs", "5c01500bcfd762a7367a0cb9b503c71678e3504eeb2f2873329c0d9321841939"],
+    ["lib/rules/format.mjs", "c745e01e460f9d57e28881a56af5d1376952b548a33d44feec7914e9fdccbddd"],
     ["lib/rules/frontmatter.mjs", "d0272fb934407b20a425a546c7762ba90e6d6d3bbdad083228698e9bd5b58b4b"],
     ["lib/rules/glob.mjs", "e0b138279b9608e879af5f680643a0c4aefb00b388e0ba42f98f6eead3c08caf"],
     ["lib/rules/matcher.mjs", "83334358a035a9fedf3d7970b2454825d4ca8d0082b5a8779efc8ad8fdeecd5b"],
     ["lib/rules/ordering.mjs", "c6da1ef0b228b8f0932b54422d2bc9744eb6bfbb8f5bb70b30b8f1a798765d1c"],
     ["lib/rules/scanner.mjs", "c62d672a66af25f29fe1d05b09288583425a2bf55f20d788f81d1578035f79f9"],
-    ["lib/rules/session-state.mjs", "ad660cadf147b102437da95a771bae19ee2140bf39c58915b8cb498e8d04f2af"],
+    ["lib/rules/session-state.mjs", "23d50ebdf80f389b715751d9d0f7096669db0b2e61885d0d2df114d64be18ea0"],
     ["lib/secret-shapes.mjs", "7dc58f1caa6d5fc9dc43797a703911e1ec26689a082bb6972f6ed71722a01d57"],
-    ["lib/secure-path-read.mjs", "c2991d0279f7399c3022c78babe28e653260f2a2e9ff4a5df692883ccf8807fd"],
+    ["lib/secure-path-read.mjs", "31fbfe38a350b5fe3194c84f4cb3a84125dd16a1dc506bae91ff7bd5ff024d56"],
     ["lib/strict-json.mjs", "d941f327aabce5ffc212770852cfbc7e08dd03471e4e9bc9560eff54f06d489a"],
     ["lib/wikify-knowledge-cli.mjs", "6835f8d6d98a3dd26266409366c23b2da437c0cd41e63537f0f200667655132b"],
-    ["lib/wikify-knowledge.mjs", "00dc8509d007484105dab87c1562d1657ef0f01ac8840a7d2f18898768d375b3"],
-    ["scripts/scaffold-plan.mjs", "b171ffccdaff8b9a586fe65590a154eeb663e7359fd34b6ee0e942d452381d2a"],
+    ["lib/wikify-knowledge.mjs", "feaa8d1fc9606b00f5fa49115385a797c285eefdc9e202d94809f6c3cff5d224"],
+    ["scripts/scaffold-plan.mjs", "6f4b098613f0c22d317aa23cdbe51f4fae64fbfed4cbb0e227b3a4e3e0a97404"],
     ["skills/autoconference/SKILL.md", "e034a0232d59bea9f9ed27bb8844a7ee039dd5c7d38aeaffaa32e7ee63daa5ad"],
     ["skills/autoresearch/SKILL.md", "2b69c53bade3851cfb9c770bce80afe5f9e75b9629719e9ba95a4b0045eaf5b3"],
     ["skills/browser-drive/scripts/capability-probe.mjs", "69fbf97638165d8dac5297c6c2e7b18c5757605acdcaed3ce96f745dc3c72532"],
@@ -731,7 +731,7 @@ export const canonicalSkillResourceManifest = Object.freeze(
     ["skills/lit-pptx/templates/tonalities/signal/pack.yaml", "c4c92302e739b1a9f4fde25b2961272207a56a943cb8dde94cbd3a401b05a7d8"],
     ["skills/lit-pptx/templates/tonalities/studio/pack.yaml", "ac3164e0333a51282c7c612eccaffbd3144e65e878731304c06f9c5b3cf1da60"],
     ["skills/lit-team/SKILL.md", "6d4ca726d1240db7692ccc95802ab6abfd45588147ec663dafa1b3b233a08a13"],
-    ["skills/lit-team/scripts/team.mjs", "a0be61f09cc1c10989b12709135ac4b99260496f840dcf58514478082e239fe7"],
+    ["skills/lit-team/scripts/team.mjs", "2c6df317dbe726315676e8632cba0a229653e80a9fe8456eaa617d4185e9577f"],
     ["skills/lit-typographic-motion/SKILL.md", "df3fcd7e8c91b9d617cebf0a466ee169f1155d5544984bbfc753f20322491a52"],
     ["skills/lit-typographic-motion/engine/NOTICE", "6734178ad953e5f40585d000c13e4803e670d9e8982b7f6ef0395d47a9eedf30"],
     ["skills/lit-typographic-motion/engine/THIRD_PARTY_NOTICES", "931b4b52cfc52b398124de5f48c51c946d85ff6036643ead116b00f9342aa1b2"],
@@ -834,7 +834,7 @@ export const canonicalSkillResourceManifest = Object.freeze(
     ["skills/lit-typographic-motion/references/treatment.md", "382b9454d8de1e9eca1e29b927ecc351972b0fd9853a01b02c6451e8e6e341ed"],
     ["skills/lit-typographic-motion/references/type-craft.md", "5bac1461a4ecb64dc4492e7b765934e2ec0d17f848e720f281cb3031b7750903"],
     ["skills/lit-typographic-motion/scripts/motion-doctor.mjs", "5c55feeaefbdc042c1c512ff30baabc3568dc7fa0d63dc430cf6b440ec3a4cbb"],
-    ["skills/lit-typographic-motion/scripts/motion-runtime.mjs", "262756f9bc58ae47f6be179ba01e0ca05a3bccc16210636a95a89131b2445b1b"],
+    ["skills/lit-typographic-motion/scripts/motion-runtime.mjs", "8cf247a25b9ec3c4745f608fd618aeb4e069940cdb97354682066121eea50f47"],
     ["skills/lit-typographic-motion/scripts/motion.mjs", "373665f2c82a19f5d703fd74743c95cd6760e7da8ec267797ce964cfa43edf9d"],
     ["skills/litresearch/ATTRIBUTION.md", "1ed8b43d48a13d7fc106cbfd86bc1bac0316529bdac4e2e38043fafeae2a8e15"],
     ["skills/litwork/SKILL.md", "5c5964d4df69c0e7cc7505f2dec38beed9413e79d64eb61f325012215e86d0ba"],