@litfamily/litclaude 1.0.10 → 1.0.13

package/plugins/litclaude/lib/hud-accent-palette.mjs

@@ -113,3 +113,36 @@ export const litBrandPrefix = (version, { noColor = false, truecolor = false, de
   out += `\x1b[38;2;${NEON_END[0]};${NEON_END[1]};${NEON_END[2]}m v${version}]\x1b[0m`;
   return out;
 };
+
+// --- Rainbow text (Jev skill hint) ------------------------------------------
+// Per-character hue sweep starting at `phase` degrees: truecolor paints exact hues, 256-color
+// snaps each hue to the 6x6x6 cube, 16-color picks the nearest bright hue, plain returns the
+// text untouched. Spaces get no escape, and stripping the escapes always gives back `text`.
+const RAINBOW_ANSI16 = Object.freeze([91, 93, 92, 96, 94, 95]);
+
+const hueToRgb = (hue) => {
+  // HSV with a softened saturation so every hue stays legible on a dark terminal.
+  const h = ((hue % 360) + 360) % 360 / 60;
+  const s = 0.65;
+  const x = 1 - Math.abs((h % 2) - 1);
+  const [r, g, b] = [[1, x, 0], [x, 1, 0], [0, 1, x], [0, x, 1], [x, 0, 1], [1, 0, x]][Math.floor(h) % 6];
+  return [r, g, b].map((channel) => Math.round(255 * (1 - s + s * channel)));
+};
+
+export const rainbowText = (text, { depth = "plain", phase = 0 } = {}) => {
+  if (!["truecolor", "256", "16"].includes(depth)) return text;
+  const chars = [...text];
+  const step = chars.length > 1 ? Math.min(60, 300 / (chars.length - 1)) : 0;
+  const painted = chars.map((char, index) => {
+    if (char === " ") return char;
+    const hue = (((phase + index * step) % 360) + 360) % 360;
+    if (depth === "16") return `\x1b[${RAINBOW_ANSI16[Math.floor(((hue + 30) % 360) / 60)]}m${char}`;
+    const [r, g, b] = hueToRgb(hue);
+    if (depth === "256") {
+      const cube = (value) => Math.round((value / 255) * 5);
+      return `\x1b[38;5;${16 + 36 * cube(r) + 6 * cube(g) + cube(b)}m${char}`;
+    }
+    return `\x1b[38;2;${r};${g};${b}m${char}`;
+  });
+  return `\x1b[1m${painted.join("")}\x1b[0m`;
+};

package/plugins/litclaude/lib/interface-mode.mjs

@@ -0,0 +1,33 @@
+// Interface-mode wording for frontend-ui-ux: build (the default), polish, audit and harden.
+//
+// Input is the hook's normalized prompt text (lower-cased, code removed, `-` and `_` turned into
+// spaces), so "stress-test" arrives as "stress test" and "read-only" as "read only". Hangul terms
+// are bare stems for the same agglutination reason the hook's UI route gives. Mode words say
+// nothing about the object; the hook pairs them with its interface-noun check before routing, so
+// "이 문단 다듬어줘" or "서버 상태 점검" never reach the skill. Video, 영상, 모션 and 발표 wording
+// is deliberately absent: those belong to other skills.
+
+// A fix requested in the same breath turns an audit back into an editing mode.
+const FIX_REQUEST = /고쳐\s*줘|바로\s*고쳐|고치고|수정해\s*줘|\b(?:then|and) fix\b|\bfix (?:everything|it all|them all)\b/u;
+const AUDIT = /\baudit\w*|\bread only\b|\bjust check\b|\btell me what['’]?s wrong\b|점검|검토만/u;
+const HARDEN = /\bharden\w*|\bstress test\w*|\bholds? up (?:under|with)\b|\brobust to\b|튼튼하게|견고하게/u;
+const NEGATED_HARDEN = /\b(?:don['’]?t|do not|no|without)\s+(?:stress test\w*|harden\w*)/gu;
+const POLISH = /\bpolish\w*|\bclean up the styling\b|\btighten up\b|\bsame layout\b|\bwithout redesigning\b|\bdon['’]?t restructure\b|\bkeep every \w+ where\b|다듬|그대로\s*두고|구조는\s*(?:그대로|손대지)/u;
+// Polish never restructures: wording that asks for a new layout or a rebuild is a build.
+const REBUILD = /(?<!without )\bredesign\w*|\bcompletely new\b|\bbrand new\b|\bfrom scratch\b|전체를\s*다시|다시\s*짜|새로\s*(?:만들|짜)/u;
+
+export const INTERFACE_MODES = Object.freeze(["build", "polish", "audit", "harden"]);
+
+// True when the text carries a polish, audit or harden word (negated harden wording excluded).
+export function hasInterfaceModeWord(normalized) {
+  const text = normalized.replace(NEGATED_HARDEN, " ");
+  return AUDIT.test(text) || HARDEN.test(text) || POLISH.test(text);
+}
+
+export function interfaceMode(normalized) {
+  const text = normalized.replace(NEGATED_HARDEN, " ");
+  if (AUDIT.test(text) && !FIX_REQUEST.test(text)) return "audit";
+  if (HARDEN.test(text)) return "harden";
+  if (POLISH.test(text) && !REBUILD.test(text)) return "polish";
+  return "build";
+}

package/plugins/litclaude/lib/interface-probe-gate.mjs

@@ -0,0 +1,125 @@
+// Interface-probe hand-off gate. A lit workflow turn (lit-loop, litwork, litgoal, a native
+// workflow, or frontend-ui-ux itself) that writes a user-facing web interface must run
+// frontend-ui-ux's interface probe before it ends: UserPromptSubmit arms the turn, PostToolUse
+// records interface edits and probe runs, and the Stop hook refuses to end the turn until a clean
+// probe run follows the last edit. Clean means the run completed: its output shows the Approve
+// verdict and no BLOCKED line, or, when the output went elsewhere, its --out manifest (written after
+// the edit) has exit code 0, every matrix row and no HIGH finding. Empty output, a BLOCKED run and
+// anything the hook cannot read are not clean. The block
+// counter is the loop brake: at most INTERFACE_PROBE_MAX_BLOCKS blocks per turn, then the stop
+// passes with a warning. Any unreadable state fails SAFE (allow).
+import { existsSync, mkdirSync, readFileSync, renameSync, rmSync, statSync, writeFileSync } from "node:fs";
+import { extname, isAbsolute, join } from "node:path";
+
+import { resolveProjectStateRoot } from "./project-state-root.mjs";
+
+export const INTERFACE_PROBE_MAX_BLOCKS = 2;
+// start-work is left out: its prompt turn must stay side-effect-free, and the plan rows it runs
+// already name frontend-ui-ux in their Verification.
+export const INTERFACE_PROBE_WORKFLOWS = Object.freeze(["lit-loop", "litwork", "litgoal", "native-workflow", "frontend-ui-ux"]);
+// Files a browser renders as the interface itself. Path segments alone (an `app/` directory) are
+// not enough here: a backend-only change must never be held for a browser probe.
+export const INTERFACE_FILE_EXTENSIONS = Object.freeze([".html", ".htm", ".css", ".scss", ".sass", ".less", ".vue", ".svelte", ".astro", ".tsx", ".jsx"]);
+
+const PROBE_COMMAND = /\bnode\b[^\n;&|]*interface-probe\.mjs/u;
+const OUT_ARGUMENT = /interface-probe\.mjs[^\n;&|]*?--out[=\s]+(?:"([^"]+)"|'([^']+)'|([^\s;&|>]+))/u;
+const MATRIX_ROWS = 7;
+const MAX_PATHS = 5;
+
+export const interfaceProbeTurnPath = (cwd = resolveProjectStateRoot()) => join(resolveProjectStateRoot(cwd), ".litclaude", "interface-probe", "turn.json");
+
+const readTurn = (cwd) => {
+  const path = interfaceProbeTurnPath(cwd);
+  if (!existsSync(path)) return null;
+  const parsed = JSON.parse(readFileSync(path, "utf8"));
+  if (!parsed || typeof parsed !== "object" || typeof parsed.sessionId !== "string" || !Number.isInteger(parsed.blockCount) || parsed.blockCount < 0) {
+    throw new Error("invalid interface-probe turn state");
+  }
+  return parsed;
+};
+
+const writeTurn = (cwd, state) => {
+  const target = interfaceProbeTurnPath(cwd);
+  mkdirSync(join(target, ".."), { recursive: true });
+  const tmp = `${target}.tmp`;
+  writeFileSync(tmp, JSON.stringify(state));
+  renameSync(tmp, target);
+  return state;
+};
+
+// Every prompt re-arms or clears the turn, so the gate never outlives the turn that armed it.
+export const recordInterfaceProbeTurn = (cwd, { sessionId, discipline, now = Date.now() }) => {
+  if (!INTERFACE_PROBE_WORKFLOWS.includes(discipline)) {
+    rmSync(interfaceProbeTurnPath(cwd), { force: true });
+    return null;
+  }
+  return writeTurn(cwd, { sessionId: typeof sessionId === "string" ? sessionId : "", discipline, promptAt: now, editAt: null, paths: [], probeAt: null, issue: null, issueAt: null, blockCount: 0, warned: false });
+};
+
+export const interfaceFilePaths = (filePaths) => filePaths.filter((path) => INTERFACE_FILE_EXTENSIONS.includes(extname(path).toLowerCase()));
+
+const probeOutput = (input) => {
+  const response = input.tool_response;
+  if (!response || typeof response !== "object") return "";
+  return [response.stdout, response.stderr, response.output].filter((part) => typeof part === "string").join("\n");
+};
+
+// Why a probe run is not clean, or null when it is.
+const probeIssue = ({ output, command, workdir, editAt }) => {
+  if (/BLOCKED:/u.test(output)) return (/BLOCKED:[^\n]*/u.exec(output)[0]).slice(0, 120);
+  if (/Verdict: Block \(/u.test(output)) return "a HIGH finding remains";
+  if (/Verdict: Approve \(0 HIGH\)/u.test(output)) return null;
+  const out = OUT_ARGUMENT.exec(command);
+  const dir = out && (out[1] ?? out[2] ?? out[3]);
+  if (!dir || dir.includes("$")) return output.trim() ? "no verdict in its output" : "empty output and no readable --out manifest";
+  try {
+    const file = join(isAbsolute(dir) ? dir : join(workdir, dir), "findings.json");
+    if (statSync(file).mtimeMs < (editAt ?? 0)) return "its --out manifest predates the last interface edit";
+    const { manifest, findings } = JSON.parse(readFileSync(file, "utf8"));
+    if (manifest?.exit_code !== 0 || (manifest.viewports_run ?? []).length < MATRIX_ROWS) return `its --out manifest shows exit ${manifest?.exit_code} with ${(manifest?.viewports_run ?? []).length} of ${MATRIX_ROWS} rows`;
+    if ((findings ?? []).some((finding) => finding.severity === "HIGH" && finding.tier !== "not_verified")) return "a HIGH finding remains";
+    return null;
+  } catch {
+    return "empty output and no readable --out manifest";
+  }
+};
+
+export const observeInterfaceProbeTool = (cwd, { input, filePaths, now = Date.now() }) => {
+  let turn;
+  try {
+    turn = readTurn(cwd);
+  } catch {
+    return null;
+  }
+  if (!turn || turn.sessionId !== input.session_id) return null;
+  const edited = interfaceFilePaths(filePaths);
+  const command = input.tool_name === "Bash" && typeof input.tool_input?.command === "string" ? input.tool_input.command : "";
+  if (edited.length) {
+    return writeTurn(cwd, { ...turn, editAt: now, paths: [...new Set([...edited, ...turn.paths])].slice(0, MAX_PATHS) });
+  }
+  if (PROBE_COMMAND.test(command)) {
+    const workdir = typeof input.cwd === "string" ? input.cwd : cwd;
+    const issue = probeIssue({ output: probeOutput(input), command, workdir, editAt: turn.editAt });
+    return writeTurn(cwd, issue ? { ...turn, issue, issueAt: now } : { ...turn, probeAt: now, issue: null, issueAt: null });
+  }
+  return null;
+};
+
+export const evaluateInterfaceProbeStop = ({ cwd, sessionId, now = Date.now() }) => {
+  const turn = readTurn(cwd);
+  if (!turn || turn.sessionId !== sessionId || turn.editAt === null) return { action: "allow", why: "no-interface-edit" };
+  if (turn.probeAt !== null && turn.probeAt >= turn.editAt) return { action: "allow", why: "probed" };
+  const detail = turn.issue && turn.issueAt >= turn.editAt
+    ? `the interface changed (${turn.paths.join(", ")}) and the last interface probe run after it was not clean: ${turn.issue}`
+    : `the interface changed (${turn.paths.join(", ")}) and no clean run of frontend-ui-ux's interface probe followed it`;
+  if (turn.blockCount >= INTERFACE_PROBE_MAX_BLOCKS) {
+    if (turn.warned) return { action: "allow", why: "capped" };
+    writeTurn(cwd, { ...turn, warned: true });
+    return { action: "warn", why: "capped", systemMessage: `LitClaude interface probe: ${detail}; allowing the stop after ${INTERFACE_PROBE_MAX_BLOCKS} reminders.` };
+  }
+  writeTurn(cwd, { ...turn, blockCount: turn.blockCount + 1, lastBlockAt: now });
+  return {
+    action: "block",
+    reason: `${detail}. Hand the interface part to Skill(frontend-ui-ux): run scripts/interface-probe.mjs from its skill directory on the built page across the full matrix, fix every HIGH finding, then run it again. If it cannot run, or a HIGH has to stay, say BLOCKED or state the limitation with its reason before finishing.`,
+  };
+};

package/plugins/litclaude/lib/jev-skill-hint.mjs

@@ -0,0 +1,445 @@
+// Optional Jev skill hint for the UserPromptSubmit hook.
+//
+// Off unless LITCLAUDE_JEV=1 and TYPESAFE_API_KEY are both in the environment. On an eligible
+// turn it asks TypeSafe's Jev model which one of this plugin's own skills fits the prompt, and
+// returns at most one fixed advisory sentence naming a skill ID it validated against the catalog
+// it sent. The response is untrusted data: no response text ever reaches the model context.
+//
+// The key is read from the environment only. It is never written, printed, traced, or placed in
+// an error: every failure is reported as a fixed reason word from FALLBACK_REASONS.
+
+import { createHash } from "node:crypto";
+import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, renameSync, writeFileSync, writeSync } from "node:fs";
+import { join } from "node:path";
+
+import { canonicalSkillIds } from "./canonical-skill-catalog.mjs";
+import { SECRET_SHAPE_PATTERNS } from "./secret-shapes.mjs";
+
+export const JEV_FLAG = "LITCLAUDE_JEV";
+export const JEV_ENDPOINT = "https://api.typesafe.ai/v1/systemone";
+export const JEV_DEFAULT_MODEL = "jev-1.13.0";
+export const JEV_DEFAULT_TIMEOUT_MS = 1500;
+export const JEV_MAX_TIMEOUT_MS = 3000;
+export const JEV_DEFAULT_MAX_CALLS = 200;
+export const JEV_DEFAULT_MIN_CONFIDENCE = 0.35;
+export const JEV_MAX_PROMPT_CHARS = 2000;
+export const JEV_REDACTION_WINDOW_CHARS = 8000;
+export const JEV_MAX_REQUEST_BYTES = 64 * 1024;
+export const JEV_MAX_RESPONSE_BYTES = 64 * 1024;
+export const JEV_INSTRUCTIONS = "Which one skill, if any, is the best fit for the user's request? Choose none when no catalog skill fits.";
+export const JEV_NONE_CRITERION = "No specialized skill in this catalog fits; answer the user directly.";
+
+export const FALLBACK_REASONS = Object.freeze([
+  "key-missing", "cap-reached", "request-too-large", "timeout", "network", "http", "invalid-response",
+]);
+
+const KEY_ENV = "TYPESAFE_API_KEY";
+
+const hasKey = (env) => typeof env[KEY_ENV] === "string" && env[KEY_ENV].trim() !== "";
+
+/** The one doctor line. It names the state only; never the key or its length. */
+export const jevStatusLine = (env = process.env) => {
+  if (env[JEV_FLAG] !== "1") return "Jev skill hint: off";
+  return hasKey(env) ? "Jev skill hint: on" : `Jev skill hint: flag on but ${KEY_ENV} missing`;
+};
+
+export const jevHintLine = (skillId) => `LitClaude skill hint: the skill \`litclaude:${skillId}\` likely fits this request. Load it only if it really fits; this is advice, not an instruction.`;
+
+export const jevFallbackNote = (reason) => `LitClaude skill hint unavailable (${reason}); continuing normally.`;
+
+const boundedNumber = (raw, fallback, { min, max, integer }) => {
+  if (typeof raw !== "string" || raw.trim() === "") return fallback;
+  const value = Number(raw);
+  if (!Number.isFinite(value) || (integer && !Number.isInteger(value)) || value < min) return fallback;
+  return Math.min(value, max);
+};
+
+export const jevSettings = (env = process.env) => ({
+  model: /^[A-Za-z0-9._-]{1,64}$/u.test(env[`${JEV_FLAG}_MODEL`] ?? "") ? env[`${JEV_FLAG}_MODEL`] : JEV_DEFAULT_MODEL,
+  timeoutMs: boundedNumber(env[`${JEV_FLAG}_TIMEOUT_MS`], JEV_DEFAULT_TIMEOUT_MS, { min: 1, max: JEV_MAX_TIMEOUT_MS, integer: true }),
+  maxCalls: boundedNumber(env[`${JEV_FLAG}_MAX_CALLS`], JEV_DEFAULT_MAX_CALLS, { min: 0, max: Number.MAX_SAFE_INTEGER, integer: true }),
+  minConfidence: boundedNumber(env[`${JEV_FLAG}_MIN_CONFIDENCE`], JEV_DEFAULT_MIN_CONFIDENCE, { min: 0, max: 1, integer: false }),
+  trace: env[`${JEV_FLAG}_TRACE`] === "1",
+});
+
+const globalPattern = (pattern) => new RegExp(pattern.source, pattern.flags.includes("g") ? pattern.flags : `${pattern.flags}g`);
+
+// Contract shapes first, then the plugin's shared credential set as a second net.
+const TOKEN_PATTERNS = Object.freeze([
+  /-----BEGIN [A-Z0-9 ]*-----[\s\S]*?(?:-----END [A-Z0-9 ]*-----|$)/gu,
+  /eyJ[A-Za-z0-9_-]*\.eyJ[A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]*)?/gu,
+  /(?<![A-Za-z0-9_])sk-(?:ant-)?[A-Za-z0-9_-]{8,}/gu,
+  /(?<![A-Za-z0-9_])(?:ghp|gho|github_pat)_[A-Za-z0-9_]{8,}/gu,
+  /(?<![A-Za-z0-9_])npm_[A-Za-z0-9]{8,}/gu,
+  /(?<![A-Za-z0-9_])apikey_[A-Za-z0-9_-]{8,}/gu,
+  /(?<![A-Za-z0-9_])xox[abprs]-[A-Za-z0-9-]{8,}/gu,
+  /(?<![A-Za-z0-9])AKIA[A-Z0-9]{12,}/gu,
+  /(?<![A-Za-z0-9_])AIza[A-Za-z0-9_-]{16,}/gu,
+  /[A-Za-z0-9+/_-]{32,}={0,2}/gu,
+  ...SECRET_SHAPE_PATTERNS.map(globalPattern),
+]);
+
+/**
+ * Redaction in the contract's order: an 8,000-character window, the literal key, home paths,
+ * e-mail addresses, token shapes, the 2,000-character cut, then any run of 8 or more token
+ * characters left at the cut, so a secret split by the cut never leaves a fragment behind.
+ */
+export const redactPromptForJev = (text, key) => {
+  let value = Array.from(typeof text === "string" ? text : "").slice(0, JEV_REDACTION_WINDOW_CHARS).join("");
+  // A key pasted into the prompt itself is removed first, even when its shape escapes the patterns.
+  if (typeof key === "string" && key !== "") value = value.split(key).join("[secret]");
+  // A home path ends at the next separator or punctuation; a trailing dot stays outside it.
+  value = value
+    .replace(/\/(?:Users|home)\/[^/\\\s,;:!?'"`()<>[\]{}]*[^/\\\s,;:!?'"`()<>[\]{}.]/gu, "~")
+    .replace(/[A-Za-z]:\\Users\\[^/\\\s,;:!?'"`()<>[\]{}]*[^/\\\s,;:!?'"`()<>[\]{}.]/gu, "~");
+  value = value.replace(/[A-Za-z0-9._%+-]+@[A-Za-z0-9-]+(?:\.[A-Za-z0-9-]+)*\.[A-Za-z]{2,}/gu, "[email]");
+  for (const pattern of TOKEN_PATTERNS) value = value.replace(pattern, "[secret]");
+  const characters = Array.from(value);
+  if (characters.length <= JEV_MAX_PROMPT_CHARS) return value;
+  return characters.slice(0, JEV_MAX_PROMPT_CHARS).join("").replace(/[A-Za-z0-9+/_=-]{8,}$/u, "[secret]");
+};
+
+const frontmatterField = (frontmatter, name) => {
+  const match = new RegExp(`^${name}:[ \\t]*(.*)$`, "mu").exec(frontmatter);
+  if (!match) return "";
+  const raw = match[1].trim();
+  if (raw.startsWith('"')) {
+    try {
+      return JSON.parse(raw);
+    } catch {
+      return raw.slice(1, -1);
+    }
+  }
+  return raw.startsWith("'") && raw.endsWith("'") ? raw.slice(1, -1) : raw;
+};
+
+/**
+ * The enrolled skills the model may load itself: every canonical skill except those marked
+ * `disable-model-invocation: true`, which only a user slash command can start.
+ */
+export const buildJevCatalog = (pluginRoot) => {
+  const catalog = [];
+  for (const skillId of canonicalSkillIds) {
+    let content;
+    try {
+      content = readFileSync(join(pluginRoot, "skills", skillId, "SKILL.md"), "utf8");
+    } catch {
+      continue;
+    }
+    const frontmatter = /^---\r?\n([\s\S]*?)\r?\n---/u.exec(content)?.[1] ?? "";
+    if (frontmatterField(frontmatter, "disable-model-invocation") === "true") continue;
+    const description = String(frontmatterField(frontmatter, "description")).slice(0, 300);
+    if (description) catalog.push({ id: skillId, description });
+  }
+  return catalog;
+};
+
+export const buildJevRequestBody = ({ model, state, catalog }) => ({
+  model,
+  state,
+  questions: {
+    which: {
+      type: "choice",
+      instructions: JEV_INSTRUCTIONS,
+      criteria: {
+        ...Object.fromEntries(catalog.map(({ id, description }) => [id, description])),
+        none: JEV_NONE_CRITERION,
+      },
+    },
+  },
+});
+
+/** Validates an untrusted response. Returns the accepted choice ID, "none", or a failure. */
+export const parseJevResponse = ({ status, text, catalogIds, minConfidence }) => {
+  if (status !== 200) return { ok: false, reason: "http" };
+  let parsed;
+  try {
+    parsed = JSON.parse(text);
+  } catch {
+    return { ok: false, reason: "invalid-response" };
+  }
+  const answer = parsed?.answers?.which;
+  const choice = answer?.choice;
+  if (typeof choice !== "string" || (choice !== "none" && !catalogIds.includes(choice))) {
+    return { ok: false, reason: "invalid-response" };
+  }
+  const confidence = answer.confidence;
+  if (typeof confidence !== "number" || !Number.isFinite(confidence)) return { ok: false, reason: "invalid-response" };
+  return { ok: true, choice, confidence, accepted: choice !== "none" && confidence >= minConfidence };
+};
+
+const readBounded = async (response) => {
+  const reader = response.body?.getReader?.();
+  if (!reader) {
+    const text = await response.text();
+    return Buffer.byteLength(text, "utf8") > JEV_MAX_RESPONSE_BYTES ? null : text;
+  }
+  const chunks = [];
+  let size = 0;
+  for (;;) {
+    const { done, value } = await reader.read();
+    if (done) break;
+    size += value.byteLength;
+    if (size > JEV_MAX_RESPONSE_BYTES) {
+      await reader.cancel().catch(() => {});
+      return null;
+    }
+    chunks.push(Buffer.from(value));
+  }
+  return Buffer.concat(chunks).toString("utf8");
+};
+
+/** One POST, no retry. Resolves to { status, text } or { reason }; never throws, never rejects. */
+const postOnce = async ({ fetchImpl, key, body, timeoutMs }) => {
+  const controller = new AbortController();
+  let timer;
+  const timeout = new Promise((resolveTimeout) => {
+    timer = setTimeout(() => {
+      controller.abort();
+      resolveTimeout({ reason: "timeout" });
+    }, timeoutMs);
+  });
+  const request = (async () => {
+    try {
+      const response = await fetchImpl(JEV_ENDPOINT, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body,
+        redirect: "error",
+        signal: controller.signal,
+      });
+      const status = response.status;
+      if (status !== 200) {
+        // An unread body would hold the connection open; release it before reporting.
+        await response.body?.cancel?.().catch(() => {});
+        return { status, text: "" };
+      }
+      const text = await readBounded(response);
+      return text === null ? { status, reason: "invalid-response" } : { status, text };
+    } catch {
+      return { reason: controller.signal.aborted ? "timeout" : "network" };
+    }
+  })();
+  try {
+    return await Promise.race([request, timeout]);
+  } finally {
+    clearTimeout(timer);
+  }
+};
+
+const safeSessionId = (sessionId) => {
+  const cleaned = typeof sessionId === "string" ? sessionId.replace(/[^A-Za-z0-9_-]/gu, "").slice(0, 64) : "";
+  return cleaned || "unknown";
+};
+
+const jevStateDirectory = (stateRoot) => join(stateRoot, ".litclaude", "jev");
+
+// Opening with O_NOFOLLOW refuses a symlink planted at a state or trace path, so a write never
+// lands outside the state folder. Where the platform lacks the flag, lstat refuses it instead.
+const NO_FOLLOW = constants.O_NOFOLLOW ?? 0;
+const refuseSymlink = (path) => {
+  if (NO_FOLLOW) return;
+  try {
+    if (lstatSync(path).isSymbolicLink()) throw new Error("symlink");
+  } catch (error) {
+    if (error?.code !== "ENOENT") throw error;
+  }
+};
+
+// The last hinted skill and its latency, kept for the HUD. Only a catalog ID and a whole
+// number of milliseconds survive a read, so the status line never echoes anything else.
+const validLast = (value) => (
+  typeof value?.skill === "string" && canonicalSkillIds.includes(value.skill)
+  && Number.isSafeInteger(value.latency_ms) && value.latency_ms >= 0
+    ? { skill: value.skill, latency_ms: value.latency_ms }
+    : null
+);
+
+const readSession = (stateRoot, sessionId) => {
+  const empty = { calls: 0, noted: false, banner: false, last: null };
+  try {
+    const path = join(jevStateDirectory(stateRoot), `session-${safeSessionId(sessionId)}.json`);
+    if (lstatSync(path).isSymbolicLink()) return empty;
+    const parsed = JSON.parse(readFileSync(path, "utf8"));
+    return {
+      calls: Number.isSafeInteger(parsed?.calls) && parsed.calls >= 0 ? parsed.calls : 0,
+      noted: parsed?.noted === true,
+      banner: parsed?.banner === true,
+      last: validLast(parsed?.last),
+    };
+  } catch {
+    return empty;
+  }
+};
+
+const writeSession = (stateRoot, sessionId, session) => {
+  try {
+    const directory = jevStateDirectory(stateRoot);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = join(directory, `session-${safeSessionId(sessionId)}.json`);
+    const temporary = `${target}.${process.pid}.tmp`;
+    refuseSymlink(temporary);
+    writeFileSync(temporary, JSON.stringify(session), {
+      mode: 0o600,
+      flag: constants.O_WRONLY | constants.O_CREAT | constants.O_TRUNC | NO_FOLLOW,
+    });
+    renameSync(temporary, target);
+    return true;
+  } catch {
+    // Session bookkeeping is best-effort; an unwritable state folder never alters the turn.
+    return false;
+  }
+};
+
+const writeTrace = (stateRoot, record) => {
+  try {
+    const directory = jevStateDirectory(stateRoot);
+    mkdirSync(directory, { recursive: true, mode: 0o700 });
+    const target = join(directory, "trace.jsonl");
+    refuseSymlink(target);
+    const fd = openSync(target, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | NO_FOLLOW, 0o600);
+    try {
+      writeSync(fd, `${JSON.stringify(record)}\n`);
+    } finally {
+      closeSync(fd);
+    }
+  } catch {
+    // The trace is an opt-in debug aid; failing to write it never alters the turn.
+  }
+};
+
+/**
+ * Called by the prompt hook at the start of every turn while the flag is on, so the HUD shows a
+ * skill only for the turn that was hinted. Touches nothing when there is no hint to clear.
+ */
+export const clearJevTurn = (stateRoot, sessionId) => {
+  const session = readSession(stateRoot, sessionId);
+  if (session.last) writeSession(stateRoot, sessionId, { ...session, last: null });
+};
+
+export const JEV_BANNER = "✦ Jev skill hint ON ✦";
+
+/**
+ * True exactly once per session, on the first turn with both switches on. The "shown" mark is
+ * written before the caller emits the banner; when it cannot be written, no banner is shown,
+ * so an unwritable state folder never repeats it.
+ */
+export const claimJevBanner = ({ env = process.env, stateRoot, sessionId } = {}) => {
+  if (env[JEV_FLAG] !== "1" || !hasKey(env) || !stateRoot) return false;
+  const session = readSession(stateRoot, sessionId);
+  if (session.banner) return false;
+  return writeSession(stateRoot, sessionId, { ...session, banner: true });
+};
+
+/**
+ * What the HUD may show: null when the flag is off, otherwise the key's presence and this
+ * turn's hint. It reports whether a key exists, never the key or its length.
+ */
+export const jevHudState = ({ env = process.env, stateRoot, sessionId } = {}) => {
+  if (env[JEV_FLAG] !== "1") return null;
+  if (!hasKey(env)) return { keyMissing: true, last: null };
+  return { keyMissing: false, last: stateRoot ? readSession(stateRoot, sessionId).last : null };
+};
+
+export const formatJevLatency = (latencyMs) => `${(latencyMs / 1000).toFixed(2)}s`;
+
+/** Host-side eligibility that needs no router: a leading command character or too little text. */
+export const isJevEligibleText = (text) => {
+  if (typeof text !== "string") return false;
+  const trimmed = text.trimStart();
+  if (/^[/!]/u.test(trimmed) || /<command-name>/u.test(text)) return false;
+  return text.replace(/\s/gu, "").length >= 4;
+};
+
+/**
+ * Runs the hint for one turn. `eligible` is the hook's own verdict (not routed, not a slash
+ * command). Returns { hint, note }: each is a fixed sentence or null, and neither ever carries
+ * response text. Never throws.
+ */
+export const suggestJevSkill = async ({
+  env = process.env,
+  prompt,
+  eligible = true,
+  sessionId,
+  stateRoot,
+  pluginRoot,
+  fetchImpl = globalThis.fetch,
+  now = () => Date.now(),
+}) => {
+  const quiet = { hint: null, note: null };
+  if (env[JEV_FLAG] !== "1") return quiet;
+  if (!eligible || !isJevEligibleText(prompt)) return quiet;
+  const settings = jevSettings(env);
+  const session = readSession(stateRoot, sessionId);
+  const state = redactPromptForJev(prompt, hasKey(env) ? env[KEY_ENV] : undefined);
+  const started = now();
+  let result = { choice: null, confidence: null, status: null, reason: null };
+  const fail = (reason) => {
+    result = { ...result, reason };
+    return reason;
+  };
+
+  let hint = null;
+  let hinted = null;
+  let failure = null;
+  if (!hasKey(env)) {
+    failure = fail("key-missing");
+  } else if (session.calls >= settings.maxCalls) {
+    failure = fail("cap-reached");
+  } else {
+    const catalog = buildJevCatalog(pluginRoot);
+    const body = JSON.stringify(buildJevRequestBody({ model: settings.model, state, catalog }));
+    if (Buffer.byteLength(body, "utf8") > JEV_MAX_REQUEST_BYTES) {
+      failure = fail("request-too-large");
+    } else {
+      // Fail closed: the call is counted on disk before it is made, and an uncountable call is
+      // never made, so an unwritable state folder cannot lift the per-session cap.
+      session.calls += 1;
+      if (!writeSession(stateRoot, sessionId, session)) return quiet;
+      const response = typeof fetchImpl === "function"
+        ? await postOnce({ fetchImpl, key: env[KEY_ENV], body, timeoutMs: settings.timeoutMs })
+        : { reason: "network" };
+      result.status = response.status ?? null;
+      if (response.reason) {
+        failure = fail(response.reason);
+      } else {
+        const parsed = parseJevResponse({
+          status: response.status,
+          text: response.text,
+          catalogIds: catalog.map(({ id }) => id),
+          minConfidence: settings.minConfidence,
+        });
+        if (!parsed.ok) {
+          failure = fail(parsed.reason);
+        } else {
+          result = { ...result, choice: parsed.choice, confidence: parsed.confidence };
+          if (parsed.accepted) {
+            hint = jevHintLine(parsed.choice);
+            hinted = parsed.choice;
+          }
+        }
+      }
+    }
+  }
+
+  const latencyMs = Math.max(0, Math.round(now() - started));
+  let note = null;
+  if (failure && !session.noted) {
+    session.noted = true;
+    note = jevFallbackNote(failure);
+  }
+  session.last = hinted ? { skill: hinted, latency_ms: latencyMs } : null;
+  writeSession(stateRoot, sessionId, session);
+  if (settings.trace) {
+    writeTrace(stateRoot, {
+      ts: new Date(started).toISOString(),
+      prompt_sha256: createHash("sha256").update(state).digest("hex"),
+      choice: result.choice,
+      confidence: result.confidence,
+      latency_ms: latencyMs,
+      http_status: result.status,
+      fallback: result.reason,
+    });
+  }
+  return { hint, note };
+};