@litfamily/litclaude 1.0.21 → 1.0.22

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

@@ -0,0 +1,232 @@
+// What the LIT band says, decided from a state snapshot (state.mjs) and what Claude Code reports live
+// (subagents, context usage). Pure: the mod calls these on each refresh and hands the result to the
+// band's surface module, which only draws and animates it.
+
+import { AUTOLOOP_LIMITS, GATE_LIMITS } from "./state.mjs";
+
+export const STALL_MS = 10 * 60 * 1000;
+// The context warning starts this many points before the auto-handoff percent.
+export const CONTEXT_LEAD = 5;
+
+const LIVE_AGENT = new Set(["running", "pending", "waiting", "idle"]);
+const NONTERMINAL_GOAL = new Set(["active", "blocked", "review_blocked", "needs_user_decision"]);
+const WORK_DISCIPLINES = new Set(["lit-loop", "litwork", "litgoal", "start-work", "native-workflow"]);
+
+export const formatDuration = (ms) => {
+  const seconds = Math.max(0, Math.round(ms / 1000));
+  if (seconds < 60) return `${seconds}s`;
+  const minutes = Math.floor(seconds / 60);
+  if (minutes < 60) return `${minutes}m`;
+  const hours = Math.floor(minutes / 60);
+  return minutes % 60 ? `${hours}h ${minutes % 60}m` : `${hours}h`;
+};
+
+export const formatAgo = (at, now) => (Number.isFinite(at) ? (now - at < 5000 ? "just now" : `${formatDuration(now - at)} ago`) : "—");
+
+// `activity.last` maps an agent id to the last time it was seen doing something (a tool call from its
+// loop, a status change, its first appearance) and `activity.first` to when it first appeared. A live
+// agent quiet for longer than `thresholdMs` is stalled.
+export const EMPTY_ACTIVITY = Object.freeze({ last: {}, first: {} });
+
+// Folds one `$.agent.list()` reading into the activity map: a new agent starts both clocks, a changed
+// status counts as activity, and agents that left the list are forgotten.
+export const trackAgents = (activity, agents, previousStatus, now) => {
+  const last = {};
+  const first = {};
+  for (const agent of agents) {
+    first[agent.id] = activity.first[agent.id] ?? now;
+    const changed = previousStatus[agent.id] !== undefined && previousStatus[agent.id] !== agent.status;
+    last[agent.id] = activity.last[agent.id] === undefined || changed ? now : activity.last[agent.id];
+  }
+  return { last, first };
+};
+
+export const noteAgentActivity = (activity, agentId, now) =>
+  activity.first[agentId] === undefined ? activity : { ...activity, last: { ...activity.last, [agentId]: now } };
+
+export const stalledLanes = (agents, activity, now, thresholdMs = STALL_MS) =>
+  agents
+    .filter((agent) => LIVE_AGENT.has(agent.status) && Number.isFinite(activity.last[agent.id]) && now - activity.last[agent.id] > thresholdMs)
+    .map((agent) => ({ id: agent.id, name: laneName(agent), quietMs: now - activity.last[agent.id] }));
+
+export const laneName = (agent) => String(agent.name || agent.description || agent.type || "agent").slice(0, 40);
+
+const goalIsOpen = (goal) => Boolean(goal && NONTERMINAL_GOAL.has(goal.status));
+
+const progressOf = (snapshot) => {
+  if (snapshot.work && snapshot.work.total > 0) return { done: snapshot.work.checked, total: snapshot.work.total, unit: "tasks" };
+  const goal = snapshot.goal;
+  if (goalIsOpen(goal) && goal.criteria.length > 0) {
+    return { done: goal.criteria.filter(({ status }) => status === "pass").length, total: goal.criteria.length, unit: "criteria" };
+  }
+  return null;
+};
+
+const phasesOf = ({ snapshot, discipline, progress, completing }) => {
+  const planned = Boolean(snapshot.work) || goalIsOpen(snapshot.goal);
+  const allDone = progress !== null && progress.done >= progress.total;
+  const plan = planned || completing ? "done" : discipline === "lit-plan" ? "now" : "todo";
+  let work = "todo";
+  if (completing || allDone) work = "done";
+  else if (progress !== null || WORK_DISCIPLINES.has(discipline)) work = "now";
+  let review = "todo";
+  if (completing || snapshot.goal?.status === "complete") review = "done";
+  else if (discipline === "review-work" || allDone) review = "now";
+  return { plan, work, review };
+};
+
+const gatesOf = (snapshot) => {
+  const gates = [];
+  if (snapshot.work) gates.push({ id: "plan", state: "ok", label: "plan saved" });
+  else if (snapshot.litPlan?.blockCount > 0) gates.push({ id: "plan", state: "fail", label: "plan not saved" });
+  else if (snapshot.litPlan) gates.push({ id: "plan", state: "pending", label: "plan pending" });
+  const probe = snapshot.probe;
+  if (probe?.editAt !== null && probe?.editAt !== undefined) {
+    if (probe.probeAt !== null && probe.probeAt >= probe.editAt) gates.push({ id: "probe", state: "ok", label: "ui probe passed" });
+    else if (probe.issue && probe.issueAt >= probe.editAt) gates.push({ id: "probe", state: "fail", label: "ui probe failed" });
+    else gates.push({ id: "probe", state: "pending", label: "ui probe pending" });
+  }
+  if (snapshot.motion?.blockCount > 0) gates.push({ id: "motion", state: "pending", label: "motion gate pending" });
+  if (snapshot.handoff) {
+    gates.push(snapshot.handoff.firedAt !== null
+      ? { id: "handoff", state: "ok", label: `handoff written at ${snapshot.handoff.firedAtPercent ?? snapshot.handoff.percent}%` }
+      : { id: "handoff", state: "pending", label: `handoff at ${snapshot.handoff.percent}%` });
+  }
+  return gates;
+};
+
+const contextWarningOf = (snapshot, usage) => {
+  const percent = usage?.context?.percent;
+  const handoff = snapshot.handoff;
+  if (!handoff || handoff.firedAt !== null || !Number.isFinite(percent)) return null;
+  return percent >= handoff.percent - CONTEXT_LEAD ? { percent: Math.round(percent), threshold: handoff.percent } : null;
+};
+
+/**
+ * The band's model. `agents` is `$.agent.list()`, `activity` the per-agent last-seen map, `usage`
+ * `$.session.usage()`, `notice` and `completion` whatever the mod is currently playing.
+ */
+export const buildBandModel = ({ snapshot, agents = [], activity = EMPTY_ACTIVITY, usage = null, now, band = "auto", isWorking = false, notice = null, completion = null }) => {
+  const discipline = snapshot.ignition?.discipline ?? null;
+  const progress = progressOf(snapshot);
+  const completing = completion !== null;
+  const phases = phasesOf({ snapshot, discipline, progress, completing });
+  const liveAgents = agents.filter((agent) => LIVE_AGENT.has(agent.status));
+  const boulderLanes = (snapshot.work?.lanes ?? []).filter(({ status }) => status === "active");
+  const stalls = stalledLanes(agents, activity, now);
+  const stalledIds = new Set(stalls.map(({ id }) => id));
+  const lanes = liveAgents.length > 0
+    ? liveAgents.slice(0, 6).map((agent) => ({
+      name: laneName(agent),
+      status: stalledIds.has(agent.id) ? "stalled" : agent.status,
+      elapsedMs: Number.isFinite(activity.first[agent.id]) ? now - activity.first[agent.id] : null,
+    }))
+    : boulderLanes.slice(0, 6).map((lane) => ({ name: lane.type, status: "running", elapsedMs: Number.isFinite(lane.startedAt) ? now - lane.startedAt : null }));
+  const goal = snapshot.goal;
+  const autoloop = goal?.autoloop && goal.status === "active" && snapshot.autoloop
+    ? { n: snapshot.autoloop.blockCount, max: AUTOLOOP_LIMITS.blocks, leftMs: Math.max(0, snapshot.autoloop.firstBlockAt + AUTOLOOP_LIMITS.ms - now) }
+    : null;
+  const ctxWarning = contextWarningOf(snapshot, usage);
+  const warnings = stalls.map(({ name, quietMs }) => ({ tone: "amber", subject: name, text: `quiet for ${formatDuration(quietMs)}`, hint: "wake it? (ctrl+x tab)" }));
+  const probe = snapshot.probe;
+  if (probe?.issue && probe.issueAt >= (probe.editAt ?? 0)) warnings.push({ tone: "red", subject: "ui probe", text: probe.issue, hint: "interface check failed" });
+  const active = Boolean(snapshot.work) || goalIsOpen(goal) || (discipline !== null && isWorking) || liveAgents.length > 0;
+  const visible = band === "off" ? false : band === "always" || active || notice !== null || completion !== null || warnings.length > 0;
+  return {
+    visible,
+    discipline,
+    phases,
+    progress,
+    next: snapshot.work?.nextTask ?? (goalIsOpen(goal) ? goal.criteria.find(({ status }) => status !== "pass")?.description || goal.objective || null : null),
+    lanes: { count: lanes.length, list: lanes },
+    autoloop,
+    ctxWarning,
+    warnings,
+    gates: gatesOf(snapshot),
+    card: lanes.length >= 2 || warnings.length > 0,
+    notice,
+    completion,
+  };
+};
+
+/** The spinner's suffix: the ellipsis Claude Code drew, then the discipline and the progress count. */
+export const spinnerSuffix = (model, base = "…") => {
+  if (!model?.visible || !model.discipline) return null;
+  const count = model.progress ? ` · ${model.progress.done}/${model.progress.total}` : "";
+  return `${base} · ${model.discipline}${count}`;
+};
+
+/**
+ * Gate events worth a notice, found by comparing the previous snapshot with this one. The first
+ * snapshot of a session raises nothing: only changes seen while the mod watches are announced.
+ */
+export const diffNotices = (previous, next, previousModel = null, nextModel = null) => {
+  if (!previous) return [];
+  const notices = [];
+  const plan = next.litPlan;
+  if (plan && plan.blockCount > (previous.litPlan?.blockCount ?? 0)) {
+    notices.push({ id: `plan:${plan.promptAt}:${plan.blockCount}`, tone: "pink", title: "lit-plan is not saved yet", detail: `save plans/<slug>.md before working · stop ${plan.blockCount}/${GATE_LIMITS.litPlan}` });
+  }
+  const probe = next.probe;
+  if (probe?.issue && probe.issueAt !== null && probe.issueAt !== previous.probe?.issueAt) {
+    notices.push({ id: `probe-fail:${probe.issueAt}`, tone: "red", title: "interface probe failed", detail: probe.issue });
+  } else if (probe && probe.blockCount > (previous.probe?.blockCount ?? 0)) {
+    notices.push({ id: `probe:${probe.editAt}:${probe.blockCount}`, tone: "amber", title: "interface probe pending", detail: `run the interface probe before finishing · stop ${probe.blockCount}/${GATE_LIMITS.probe}` });
+  }
+  const motion = next.motion;
+  if (motion && motion.blockCount > (previous.motion?.blockCount ?? 0)) {
+    notices.push({ id: `motion:${motion.blockCount}:${motion.runs}`, tone: "amber", title: "motion gate: the film is not done", detail: `stop ${motion.blockCount}/${GATE_LIMITS.motion}` });
+  }
+  const handoff = next.handoff;
+  if (handoff?.firedAt !== null && handoff?.firedAt !== undefined && handoff.firedAt !== previous.handoff?.firedAt) {
+    notices.push({ id: `handoff:${handoff.firedAt}`, tone: "pink", title: `auto-handoff fired at ${handoff.firedAtPercent ?? handoff.percent}%`, detail: "write the handoff, then run /compact" });
+  }
+  if (nextModel?.ctxWarning && !previousModel?.ctxWarning) {
+    const { percent, threshold } = nextModel.ctxWarning;
+    notices.push({ id: `ctx:${threshold}:${percent}`, tone: "amber", title: `context ${percent}%`, detail: `auto-handoff is armed at ${threshold}%` });
+  }
+  return notices;
+};
+
+/** A finish worth the completion moment: all tasks checked, a work completed, or a goal met. */
+export const detectCompletion = (previous, next) => {
+  if (!previous) return null;
+  const before = previous.work;
+  if (before && before.total > 0) {
+    const after = next.work?.id === before.id ? next.work : null;
+    const finished = next.completedWorkIds.includes(before.id) || (after !== null && before.checked < before.total && after.checked >= after.total);
+    if (finished) return { id: `work:${before.id}`, detail: `${before.total}/${before.total} tasks` };
+  }
+  const goal = next.goal;
+  if (goal?.status === "complete" && previous.goal && previous.goal.status !== "complete") {
+    const passed = goal.criteria.filter(({ status }) => status === "pass").length;
+    return { id: `goal:${goal.createdAt ?? goal.objective}`, detail: `goal met · ${passed}/${goal.criteria.length} criteria` };
+  }
+  return null;
+};
+
+/** The evidence pane: goal criteria, blockers, the litgoal timeline, lanes and gates. */
+export const buildEvidenceModel = ({ snapshot, ledger = [], agents = [], activity = EMPTY_ACTIVITY, now, icons = null }) => {
+  const goal = snapshot.goal;
+  return {
+    goal: goal
+      ? {
+        objective: goal.objective,
+        status: goal.status,
+        criteria: goal.criteria.map((criterion) => ({ ...criterion, ago: formatAgo(criterion.lastAt, now) })),
+        blockers: goal.blockers,
+        reviewBlocked: goal.lastCheckpoint === "review_blocked",
+      }
+      : null,
+    timeline: ledger.map((entry) => ({ ...entry, ago: formatAgo(entry.at, now) })),
+    lanes: agents.map((agent) => ({
+      name: laneName(agent),
+      type: agent.type,
+      status: agent.status,
+      quiet: Number.isFinite(activity.last[agent.id]) ? formatDuration(now - activity.last[agent.id]) : null,
+    })),
+    gates: gatesOf(snapshot),
+    work: snapshot.work ? { plan: snapshot.work.planName, done: snapshot.work.checked, total: snapshot.work.total, next: snapshot.work.nextTask } : null,
+    icons,
+  };
+};

package/plugins/litclaude/lib/motion-render-gate.mjs

@@ -13,7 +13,7 @@
 import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { isAbsolute, join, resolve } from "node:path";
 
-import { resolveProjectStateRoot } from "./project-state-root.mjs";
+import { ensureStateDirIgnored, resolveProjectStateRoot } from "./project-state-root.mjs";
 
 export const MOTION_MAX_BLOCKS = 2;
 export const MOTION_DISCIPLINE = "lit-typographic-motion";
@@ -34,6 +34,7 @@ const readTurn = (cwd) => {
 const writeTurn = (cwd, state) => {
   const target = motionTurnPath(cwd);
   mkdirSync(join(target, ".."), { recursive: true });
+  ensureStateDirIgnored(target);
   const tmp = `${target}.tmp`;
   writeFileSync(tmp, JSON.stringify(state));
   renameSync(tmp, target);

package/plugins/litclaude/lib/office-runtime.mjs

@@ -229,6 +229,12 @@ function main(argv) {
       return 0;
     }
     if (command === "ensure") {
+      // An unknown flag (a dry-run guess, a typo) stops before anything is installed.
+      const unknown = rest.find((arg) => !["--node", "--python", "--json"].includes(arg));
+      if (unknown !== undefined) {
+        console.error(`unknown ensure option: ${unknown}`);
+        return 2;
+      }
       const wantNode = rest.includes("--node") || !rest.includes("--python");
       const wantPython = rest.includes("--python") || !rest.includes("--node");
       const result = {};

package/plugins/litclaude/lib/project-state-root.mjs

@@ -1,5 +1,5 @@
-import { existsSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { closeSync, constants, existsSync, lstatSync, openSync, writeSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 
 import { findProjectRoot } from "./rules/discovery.mjs";
 
@@ -20,3 +20,35 @@ export const resolveProjectStateRoot = (startDir = process.cwd()) => {
   const start = resolve(startDir);
   return outermostGitRoot(start) ?? findProjectRoot(start) ?? start;
 };
+
+export const PROJECT_STATE_DIR = ".litclaude";
+const STATE_GITIGNORE = "# Created by LitClaude: local session state, not for commits.\n*\n";
+
+// Git skips the state folder through a `.gitignore` inside it (the pattern pytest and ruff
+// caches use), so the user's own .gitignore and .git/info/exclude stay untouched. Call it with
+// any path inside the project's state folder after creating that path. It never replaces an
+// existing file, never writes through a symlinked folder, and a failure leaves state writes alone.
+export const ensureStateDirIgnored = (pathInsideState) => {
+  let stateDir = resolve(pathInsideState);
+  while (basename(stateDir) !== PROJECT_STATE_DIR) {
+    const parent = dirname(stateDir);
+    if (parent === stateDir) return false;
+    stateDir = parent;
+  }
+  let fd;
+  try {
+    const stats = lstatSync(stateDir);
+    if (stats.isSymbolicLink() || !stats.isDirectory()) return false;
+    fd = openSync(
+      join(stateDir, ".gitignore"),
+      constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW ?? 0),
+      0o644,
+    );
+    writeSync(fd, STATE_GITIGNORE);
+    return true;
+  } catch {
+    return false;
+  } finally {
+    if (fd !== undefined) closeSync(fd);
+  }
+};

package/plugins/litclaude/lib/rules/engine.mjs

@@ -127,6 +127,7 @@ export const staticRulesBlock = ({
   skipUserHome = false,
   maxRuleChars = DEFAULT_MAX_RULE_CHARS,
   maxResultChars = DEFAULT_STATIC_MAX_RESULT_CHARS,
+  maxResultBytes,
   sessionId,
   platform,
 } = {}) => {
@@ -139,7 +140,7 @@ export const staticRulesBlock = ({
     const unique = dedupeByBody(rules);
     return claimFormattedBlock({
       rules: unique,
-      format: (selected) => formatStaticBlock(selected, { maxRuleChars, maxResultChars }),
+      format: (selected) => formatStaticBlock(selected, { maxRuleChars, maxResultChars, maxResultBytes }),
       projectRoot,
       sessionId,
     });

package/plugins/litclaude/lib/rules/format.mjs

@@ -41,6 +41,23 @@ export const truncateRuleBody = (body, { maxChars, relativePath }) => {
   return { body: `${body.slice(0, end)}${notice}`, truncated: true, originalLength: body.length };
 };
 
+const utf8Bytes = (text) => Buffer.byteLength(text, "utf8");
+
+/** Like truncateRuleBody, but counted in UTF-8 bytes; "" when not even one character fits. */
+const truncateRuleBodyToBytes = (body, { maxBytes, relativePath }) => {
+  if (utf8Bytes(body) <= maxBytes) return body;
+  const notice = truncationNotice(relativePath);
+  let room = maxBytes - utf8Bytes(notice);
+  let end = 0;
+  for (const char of body) {
+    const size = utf8Bytes(char);
+    if (size > room) break;
+    room -= size;
+    end += char.length;
+  }
+  return end === 0 ? "" : `${body.slice(0, end)}${notice}`;
+};
+
 const formatOne = (rule) => {
   const body = normalizeBody(rule.body);
   const header = `Instructions from ${inertPathLabel(rule.relativePath)}`;
@@ -65,10 +82,12 @@ const SAFETY_LINE =
 
 const emptyBlock = () => ({ text: "", emittedRules: [] });
 
-const formatBudgetedBlock = (rules, title, { maxRuleChars, maxResultChars }) => {
+// `maxResultBytes` is an optional second cap in UTF-8 bytes, for callers that share a byte budget
+// with other context; a char cap alone would have to assume the worst bytes-per-char.
+const formatBudgetedBlock = (rules, title, { maxRuleChars, maxResultChars, maxResultBytes = Infinity }) => {
   if (rules.length === 0 || maxResultChars <= 0) return emptyBlock();
   const prefix = [title, "", SAFETY_LINE].join("\n");
-  if (prefix.length >= maxResultChars) return emptyBlock();
+  if (prefix.length >= maxResultChars || utf8Bytes(prefix) >= maxResultBytes) return emptyBlock();
 
   let text = prefix;
   const emittedRules = [];
@@ -86,9 +105,11 @@ const formatBudgetedBlock = (rules, title, { maxRuleChars, maxResultChars }) =>
       if (availableBodyChars <= notice.length) break;
       body = truncateRuleBody(body, { maxChars: availableBodyChars, relativePath: rule.relativePath }).body;
     }
+    const availableBodyBytes = maxResultBytes - utf8Bytes(text) - utf8Bytes(header) - 4;
+    body = truncateRuleBodyToBytes(body, { maxBytes: availableBodyBytes, relativePath: rule.relativePath });
     if (body.length === 0) break;
     const rendered = `\n\n${formatOne({ ...rule, body })}`;
-    if (text.length + rendered.length > maxResultChars) break;
+    if (text.length + rendered.length > maxResultChars || utf8Bytes(text) + utf8Bytes(rendered) > maxResultBytes) break;
     text += rendered;
     emittedRules.push(rule);
     if (body.length < capped.length) break;

package/plugins/litclaude/lib/rules/session-state.mjs

@@ -23,7 +23,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { acquireOwnerLock, OwnerLockError, releaseOwnerLock } from "../owner-lock.mjs";
 import { POST_COMPACT_REINJECTION_BUDGET } from "./constants.mjs";
 import { pathIdentity, samePathIdentity } from "../secure-path-read.mjs";
-import { resolveProjectStateRoot } from "../project-state-root.mjs";
+import { ensureStateDirIgnored, resolveProjectStateRoot } from "../project-state-root.mjs";
 
 const MAX_TRACKED_KEYS = 500;
 const MAX_STATE_BYTES = 256 * 1024;
@@ -61,6 +61,7 @@ const safeStateDirectory = (projectRoot, { create }) => {
     if (stats.isSymbolicLink() || !stats.isDirectory()) throw new Error("unsafe state directory");
     if (!isSameOrChildPath(realRoot, realpathSync.native(current))) throw new Error("state directory escaped project");
   }
+  if (create) ensureStateDirIgnored(current);
   return current;
 };
 

package/plugins/litclaude/lib/secure-path-read.mjs

@@ -175,6 +175,52 @@ function readDescriptorToOpenedSize(descriptor, openedSize) {
   return { bytes: offset === openedSize ? bytes : bytes.subarray(0, offset), grewDuringRead };
 }
 
+/**
+ * Read at most `maxBytes` from the end of one regular file: for an append-only log that has
+ * outgrown the whole-file bound. The ancestor chain and the file get the same no-symlink checks
+ * as readRegularStable. The file may keep growing, so the range is fixed by the size at open.
+ */
+export function readRegularTail(root, path, maxBytes) {
+  const chain = openDirectoryChain(root, dirname(path), []);
+  if (chain.failure) return { failure: chain.failure };
+  let descriptor;
+  let bytes;
+  let truncated;
+  try {
+    const before = lstatSync(path, { throwIfNoEntry: false });
+    if (!before?.isFile() || before.isSymbolicLink()) {
+      closeDescriptors(chain.opened);
+      return { failure: "NON_REGULAR" };
+    }
+    descriptor = openSync(path, constants.O_RDONLY | (constants.O_NOFOLLOW ?? 0));
+    const opened = fstatSync(descriptor);
+    if (!opened.isFile() || !sameNode(before, opened)) {
+      closeDescriptors(chain.opened);
+      return { failure: "FILE_IDENTITY_CHANGED" };
+    }
+    const length = Math.min(opened.size, maxBytes);
+    const start = opened.size - length;
+    const buffer = Buffer.allocUnsafe(length);
+    let offset = 0;
+    while (offset < length) {
+      const count = readSync(descriptor, buffer, offset, length - offset, start + offset);
+      if (count === 0) break;
+      offset += count;
+    }
+    bytes = buffer.subarray(0, offset);
+    truncated = start > 0;
+  } catch {
+    closeDescriptors(chain.opened);
+    return { failure: "UNREADABLE" };
+  } finally {
+    if (descriptor !== undefined) closeSync(descriptor);
+  }
+  const ancestorsStable = verifyDirectoryChain(chain, []);
+  closeDescriptors(chain.opened);
+  if (!ancestorsStable) return { failure: "ANCESTOR_CHANGED" };
+  return { bytes, truncated };
+}
+
 export function readRegularStable(root, path, expectedSnapshot, options = {}) {
   const maxBytes = Number.isSafeInteger(options.maxBytes) && options.maxBytes >= 0
     ? options.maxBytes

package/plugins/litclaude/lib/start-work-lifecycle.mjs

@@ -18,6 +18,7 @@ import {
 import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 
 import { parsePlanTaskRows } from "./plan-task-rows.mjs";
+import { ensureStateDirIgnored } from "./project-state-root.mjs";
 import { pathIdentity, samePathIdentity } from "./secure-path-read.mjs";
 
 const SCHEMA_VERSION = 3;
@@ -64,6 +65,7 @@ const startWorkLockOwnerPath = (root) => join(startWorkLockDir(root), "owner.jso
 
 const atomicWriteJson = (path, value) => {
   mkdirSync(dirname(path), { recursive: true });
+  ensureStateDirIgnored(path);
   const temporary = `${path}.${process.pid}.${Date.now()}.tmp`;
   writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { mode: 0o600 });
   const fd = openSync(temporary, "r");
@@ -103,6 +105,7 @@ const readLockOwner = (root) => {
 export const acquireStartWorkLock = (root, options = {}) => {
   const lockDir = startWorkLockDir(root);
   mkdirSync(dirname(lockDir), { recursive: true });
+  ensureStateDirIgnored(lockDir);
   const configured = Number.parseInt(process.env.LITCLAUDE_START_WORK_LOCK_TIMEOUT_MS ?? "5000", 10);
   const timeout = Number.isFinite(options.timeoutMs)
     ? Math.max(0, options.timeoutMs)
@@ -312,6 +315,7 @@ const assertLedgerCompatible = (existing, stateEvents) => {
 const reconcileLedger = (root, state) => {
   const path = startWorkLedgerPath(root);
   mkdirSync(dirname(path), { recursive: true });
+  ensureStateDirIgnored(path);
   const existing = ledgerRecords(root);
   assertLedgerCompatible(existing, state.events);
   const ids = new Set(existing.map(({ event_id: eventId }) => eventId).filter(Boolean));

package/plugins/litclaude/lib/wikify-knowledge.mjs

@@ -25,7 +25,7 @@ import {
 } from "./secure-path-read.mjs";
 import { decodeStrictUtf8, parseStrictJson } from "./strict-json.mjs";
 import { containsSecret, URI_USERINFO_PATTERN } from "./secret-shapes.mjs";
-import { resolveProjectStateRoot } from "./project-state-root.mjs";
+import { ensureStateDirIgnored, resolveProjectStateRoot } from "./project-state-root.mjs";
 
 const MAX_LEDGER_BYTES = 4 * 1024 * 1024;
 const MAX_TEXT_BYTES = 512;
@@ -159,6 +159,7 @@ const prepareKnowledgeDirectory = (root) => {
   const litDirectory = join(canonical, ".litclaude");
   const directory = join(litDirectory, "knowledge");
   ensurePrivateDirectory(litDirectory);
+  ensureStateDirIgnored(litDirectory);
   ensurePrivateDirectory(directory);
   return directory;
 };

package/plugins/litclaude/scripts/scaffold-plan.mjs

@@ -30,7 +30,7 @@ import { dirname, isAbsolute, join, relative, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
 import { parsePlanTaskRows, planLinesOutsideFences } from "../lib/plan-task-rows.mjs";
-import { resolveProjectStateRoot } from "../lib/project-state-root.mjs";
+import { ensureStateDirIgnored, resolveProjectStateRoot } from "../lib/project-state-root.mjs";
 import { readRegularStable, samePathIdentity } from "../lib/secure-path-read.mjs";
 
 /** Canonical plan section headers, in order. */
@@ -893,6 +893,7 @@ export async function scaffold(cwd, { slug, intent, reset = false, force = false
     // Finish the symlink-safe directory setup before taking ctime-sensitive pins;
     // concurrent scaffolders then contend only on the atomic pair lock.
     await mkdirWithoutSymlinks(dirname(pairLockPath), workspaceRoot);
+    ensureStateDirIgnored(pairLockPath);
     const pairParentState = await assertSafeWriteParent(cwd, pairLockPath);
     parentStates.add(pairParentState);
     pairLock = await acquireWriteLock(pairLockPath, pairParentState);

package/plugins/litclaude/skills/lit-team/scripts/team.mjs

@@ -38,7 +38,7 @@ import { isAbsolute, join, relative, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 
 import { acquireOwnerLock, OwnerLockError, releaseOwnerLock } from "../../../lib/owner-lock.mjs";
-import { resolveProjectStateRoot } from "../../../lib/project-state-root.mjs";
+import { ensureStateDirIgnored, resolveProjectStateRoot } from "../../../lib/project-state-root.mjs";
 import { pathIdentity, samePathIdentity } from "../../../lib/secure-path-read.mjs";
 
 const MIN_MEMBERS = 2;
@@ -109,6 +109,7 @@ const safeDirectory = (cwd, components, { create }) => {
       throw new TeamError(`team state path escapes the workspace: ${current}`, 65);
     }
   }
+  if (create) ensureStateDirIgnored(current);
   return current;
 };
 

package/plugins/litclaude/skills/lit-typographic-motion/scripts/motion-runtime.mjs

@@ -25,6 +25,13 @@ export async function main(argv, { env = process.env, stdout = process.stdout, s
     stdout.write(USAGE);
     return command ? 0 : 2;
   }
+  // An install flag this script does not know (a dry-run guess, a typo) stops before anything
+  // is installed rather than being ignored.
+  const unknownInstallFlag = command === "install" ? rest.find((arg) => !["--audio", "--word-timing"].includes(arg)) : undefined;
+  if (unknownInstallFlag !== undefined) {
+    stderr.write(`unknown install option: ${unknownInstallFlag}\n${USAGE}`);
+    return 2;
+  }
   const runtime = await import("../engine/node/runtime.mjs");
   if (command === "status") {
     const status = runtime.runtimeStatus({ env });