@fusengine/harness 0.1.90 → 0.1.91

package/src/runtime/lifecycle/cartographer/fs-util.ts

@@ -0,0 +1,64 @@
+/**
+ * Filesystem helpers for the cartographer tree walk. Ports the fs parts of
+ * `describe.py` (file desc) and `write_recursive.py` (children + counts).
+ */
+import { readFileSync, readdirSync } from "node:fs";
+import { extname, join } from "node:path";
+import { descFromText } from "../../../policy/cartographer/describe";
+import { parseField } from "../../../policy/cartographer/frontmatter";
+
+/**
+ * Read a file and derive its one-line description (frontmatter / heading /
+ * comment). "" on any error or when nothing is found.
+ * @param filePath - Absolute path to the file.
+ * @returns The description, or "".
+ */
+export function getFileDesc(filePath: string): string {
+  let text = "";
+  try {
+    text = readFileSync(filePath, "utf-8");
+  } catch {
+    return "";
+  }
+  const suffix = extname(filePath);
+  const mdField = suffix === ".md" ? parseField(text, "description") : "";
+  return descFromText(suffix, text, mdField);
+}
+
+/**
+ * Recursively count files whose relative path parts are all visible (no leading
+ * "." or "_") and none excluded. Best-effort (partial count on errors).
+ * @param dir - Directory to count under.
+ * @param exclude - Directory/name set to skip.
+ * @returns The file count.
+ */
+export function countFiles(dir: string, exclude: ReadonlySet<string>): number {
+  let total = 0;
+  try {
+    for (const e of readdirSync(dir, { withFileTypes: true })) {
+      if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+      if (e.isDirectory()) total += countFiles(join(dir, e.name), exclude);
+      else if (e.isFile()) total += 1;
+    }
+  } catch { /* best effort */ }
+  return total;
+}
+
+/** Absolute children of `source`, split into dirs/files, sorted by full path. */
+export function listChildren(source: string, exclude: ReadonlySet<string>): { dirs: string[]; files: string[] } {
+  const dirs: string[] = [];
+  const files: string[] = [];
+  let entries;
+  try {
+    entries = readdirSync(source, { withFileTypes: true });
+  } catch {
+    return { dirs, files };
+  }
+  for (const e of entries) {
+    if (e.name.startsWith(".") || e.name.startsWith("_") || exclude.has(e.name)) continue;
+    const abs = join(source, e.name);
+    if (e.isDirectory()) dirs.push(abs);
+    else if (e.isFile()) files.push(abs);
+  }
+  return { dirs: dirs.sort(), files: files.sort() };
+}

package/src/runtime/lifecycle/cartographer/merge.ts

@@ -0,0 +1,51 @@
+/**
+ * Index merge — preserves enriched descriptions across regenerations. Ports
+ * `merge_index.py` (merge_lines + .enriched.json sidecar).
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEntry } from "../../../policy/cartographer/entry";
+
+/**
+ * Load the `.enriched.json` sidecar's `entries` map for an output index.
+ * @param outputIndexPath - Path to the index.md being written.
+ * @returns The path→desc enrichment map (possibly empty).
+ */
+export function loadEnriched(outputIndexPath: string): Record<string, string> {
+  const sidecar = join(dirname(outputIndexPath), ".enriched.json");
+  try {
+    if (!existsSync(sidecar)) return {};
+    const data = JSON.parse(readFileSync(sidecar, "utf-8")) as { entries?: Record<string, string> };
+    return data.entries ?? {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * Merge freshly generated lines with prior descriptions: enriched sidecar wins,
+ * else a longer pre-existing description is preserved.
+ * @param newLines - The freshly generated index lines.
+ * @param outputIndexPath - Path to the existing index.md (if any).
+ * @returns The merged lines.
+ */
+export function mergeLines(newLines: string[], outputIndexPath: string): string[] {
+  const enriched = loadEnriched(outputIndexPath);
+  const existingDescs: Record<string, string> = {};
+  if (existsSync(outputIndexPath)) {
+    try {
+      for (const line of readFileSync(outputIndexPath, "utf-8").split("\n")) {
+        const e = parseEntry(line);
+        if (e) existingDescs[e.path] = e.desc;
+      }
+    } catch { /* ignore */ }
+  }
+  return newLines.map((line) => {
+    const e = parseEntry(line);
+    if (!e) return line;
+    if (e.path in enriched) return `${e.prefix}[${e.name}](${e.path}) — ${enriched[e.path]}`;
+    const old = existingDescs[e.path] ?? "";
+    if (old.length > e.desc.length) return `${e.prefix}[${e.name}](${e.path}) — ${old}`;
+    return line;
+  });
+}

package/src/runtime/lifecycle/cartographer/project-map.ts

@@ -0,0 +1,49 @@
+/**
+ * Project map generation. Ports `generate_project_map.py` (project map only).
+ */
+import { existsSync, statSync } from "node:fs";
+import { homedir } from "node:os";
+import { join, resolve } from "node:path";
+import { EXCLUDE_DIRS, PROJECT_INDICATORS } from "../../../policy/cartographer/indicators";
+import { writeTree } from "./write-tree";
+
+/** True when `dir` is a real directory. */
+function isDirectory(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * True when `dir` looks like a project root (has an indicator file) and is not
+ * the home directory or filesystem root.
+ * @param dir - Directory to test.
+ * @returns Whether `dir` is a project root.
+ */
+export function isProject(dir: string): boolean {
+  const resolved = resolve(dir);
+  const home = resolve(homedir());
+  if (resolved === home || resolved === "/") return false;
+  for (const f of PROJECT_INDICATORS) {
+    if (existsSync(join(dir, f))) return true;
+  }
+  return false;
+}
+
+/**
+ * Generate the `.cartographer/project` index tree for `cwd` when it is a real
+ * project directory. Always returns "" (no additionalContext emitted).
+ * @param cwd - The working directory.
+ * @param outputDir - Override for the output tree root.
+ * @returns "" (side-effect only).
+ */
+export function generateProjectMap(cwd: string, outputDir?: string): string {
+  const projectDir = resolve(cwd);
+  const out = outputDir ?? join(projectDir, ".cartographer", "project");
+  if (!isDirectory(projectDir)) return "";
+  if (!isProject(projectDir)) return "";
+  writeTree(projectDir, out, "", EXCLUDE_DIRS);
+  return "";
+}

package/src/runtime/lifecycle/cartographer/scan-hooks.ts

@@ -0,0 +1,48 @@
+/**
+ * Hook scanning (fs). Ports `_scan_hooks` from `scan_plugins.py`: reads a
+ * plugin's `hooks/hooks.json` and reduces it to a single `("hooks", "<events>", "")`
+ * row. The `hooks` value (or the whole document) is either a MAP of event →
+ * entries (keys are the events) or a LIST of entries each carrying an `event`.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import type { ScanRow } from "../../../policy/cartographer/build-tree";
+
+/** True for a non-null plain object (excludes arrays), mirroring Python `isinstance(x, dict)`. */
+function isPlainObject(v: unknown): v is Record<string, unknown> {
+  return typeof v === "object" && v !== null && !Array.isArray(v);
+}
+
+/** Sort unique non-empty strings alpha (byte-order). */
+function sortedEvents(events: Iterable<string>): string[] {
+  return [...new Set([...events].filter((e) => e))].sort((a, b) => a.localeCompare(b, "en"));
+}
+
+/** Derive hook event names from the `hooks.json` data (map keys, or list `event` fields). */
+function hookEvents(hooksData: unknown): string[] {
+  if (isPlainObject(hooksData)) {
+    return sortedEvents(Object.keys(hooksData).filter((k) => !k.startsWith("_")));
+  }
+  if (Array.isArray(hooksData)) {
+    return sortedEvents(hooksData.map((h) => (isPlainObject(h) ? String(h.event ?? "") : "")));
+  }
+  return [];
+}
+
+/**
+ * Scan `hooks/hooks.json` into a single `("hooks", "<events>", "")` row.
+ * @param root - Absolute plugin directory.
+ * @returns The single hooks row, or `[]` when absent/empty/unreadable.
+ */
+export function scanHooks(root: string): ScanRow[] {
+  const file = join(root, "hooks", "hooks.json");
+  if (!existsSync(file)) return [];
+  try {
+    const raw: unknown = JSON.parse(readFileSync(file, "utf-8"));
+    const hooksData = isPlainObject(raw) ? (raw.hooks ?? raw) : {};
+    const events = hookEvents(hooksData);
+    return events.length ? [["hooks", events.join(", "), ""]] : [];
+  } catch {
+    return [];
+  }
+}

package/src/runtime/lifecycle/cartographer/scan.ts

@@ -0,0 +1,81 @@
+/**
+ * Plugin scanning (fs). Ports `scan_plugins.py`: turns a plugin's
+ * agents/skills/commands/hooks into ordered `[type, name, desc]` rows.
+ */
+import { existsSync, readFileSync, readdirSync, statSync } from "node:fs";
+import { extname, join } from "node:path";
+import type { ScanRow } from "../../../policy/cartographer/build-tree";
+import { parseBodyDesc, parseField } from "../../../policy/cartographer/frontmatter";
+import { scanHooks } from "./scan-hooks";
+
+/** Sorted entry names of `dir` (alpha, byte-order), or `[]` on error. */
+function sortedNames(dir: string): string[] {
+  try {
+    return readdirSync(dir).sort((a, b) => a.localeCompare(b, "en"));
+  } catch {
+    return [];
+  }
+}
+
+/** Read a `.md` frontmatter field from a file path, "" when missing/unreadable. */
+function fileField(path: string, field: string): string {
+  try {
+    return parseField(readFileSync(path, "utf-8"), field);
+  } catch {
+    return "";
+  }
+}
+
+/** Scan `agents/*.md` → `("agent", name, desc[:50])` rows. */
+export function scanAgents(root: string): ScanRow[] {
+  const dir = join(root, "agents");
+  return sortedNames(dir)
+    .filter((n) => extname(n) === ".md")
+    .map((n): ScanRow => {
+      const f = join(dir, n);
+      const name = fileField(f, "name") || n.replace(/\.md$/, "");
+      return ["agent", name, fileField(f, "description").slice(0, 50)];
+    });
+}
+
+/** Scan `skills/<dir>/SKILL.md` → `("skill", dir, desc)` rows. */
+function scanSkills(root: string): ScanRow[] {
+  const dir = join(root, "skills");
+  const rows: ScanRow[] = [];
+  for (const name of sortedNames(dir)) {
+    try {
+      if (!statSync(join(dir, name)).isDirectory()) continue;
+    } catch {
+      continue;
+    }
+    const skillMd = join(dir, name, "SKILL.md");
+    let desc = "";
+    if (existsSync(skillMd)) {
+      desc = fileField(skillMd, "description");
+      if (!desc) {
+        try {
+          desc = parseBodyDesc(readFileSync(skillMd, "utf-8"));
+        } catch { /* keep "" */ }
+      }
+    }
+    rows.push(["skill", name, desc || "(no description)"]);
+  }
+  return rows;
+}
+
+/** Scan `commands/*.md` → `("command", "/name", desc[:50])` rows. */
+function scanCommands(root: string): ScanRow[] {
+  const dir = join(root, "commands");
+  return sortedNames(dir)
+    .filter((n) => extname(n) === ".md")
+    .map((n): ScanRow => ["command", `/${n.replace(/\.md$/, "")}`, fileField(join(dir, n), "description").slice(0, 50)]);
+}
+
+/**
+ * Scan a single plugin directory into ordered `[type, name, desc]` rows.
+ * @param pluginDir - Absolute plugin directory.
+ * @returns The agents + skills + commands + hooks rows.
+ */
+export function scanPlugin(pluginDir: string): ScanRow[] {
+  return [...scanAgents(pluginDir), ...scanSkills(pluginDir), ...scanCommands(pluginDir), ...scanHooks(pluginDir)];
+}

package/src/runtime/lifecycle/cartographer/session-start.ts

@@ -0,0 +1,33 @@
+/**
+ * Cartographer SessionStart handler. Ports BOTH halves of the Python maps:
+ * `generate_project_map.py` (regenerate `.cartographer/project`) and
+ * `generate_map.py` (regenerate the plugin ecosystem map), emitting the
+ * navigation context from the latter as additionalContext.
+ */
+import { resolve } from "node:path";
+import { generateProjectMap } from "./project-map";
+import { generateEcosystemMap } from "./ecosystem-map";
+import { contextResponse } from "../../../adapters/claude";
+
+/**
+ * Resolve the marketplace plugins dir from `CLAUDE_PLUGIN_ROOT`, mirroring the
+ * Python hook which passes `${CLAUDE_PLUGIN_ROOT}/..` to `generate_map.py`.
+ * @returns The plugins dir (env `/..`), or `undefined` to fall back to auto-detect.
+ */
+function pluginsDirFromEnv(): string | undefined {
+  const root = process.env.CLAUDE_PLUGIN_ROOT;
+  return root ? resolve(root, "..") : undefined;
+}
+
+/**
+ * Regenerate the project map + plugin ecosystem map for `cwd` on SessionStart.
+ * Emits the ecosystem navigation context as additionalContext (or "").
+ * @param cwd - The working directory.
+ * @param now - Clock for the ecosystem map banner timestamp.
+ * @returns The SessionStart additionalContext response, or "".
+ */
+export function cartoSessionStart(cwd: string, now: number = Date.now()): string {
+  generateProjectMap(cwd);
+  const ctx = generateEcosystemMap(now, pluginsDirFromEnv());
+  return ctx ? contextResponse("SessionStart", ctx) : "";
+}

package/src/runtime/lifecycle/cartographer/track-enrichment.ts

@@ -0,0 +1,45 @@
+/**
+ * Enrichment tracker (PostToolUse Edit/Write on `.cartographer/**\/index.md`).
+ * Ports `track-enrichment.py`: persists manual descriptions to a sidecar so the
+ * next regeneration can preserve them.
+ */
+import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { parseEnrichment } from "../../../policy/cartographer/entry";
+
+/** Shape of the `.enriched.json` sidecar. */
+interface EnrichedSidecar {
+  version: number;
+  entries: Record<string, string>;
+}
+
+/**
+ * Record manually-edited descriptions from a cartographer `index.md` into the
+ * adjacent `.enriched.json` sidecar. No-op for unrelated paths. No stdout.
+ * @param filePath - The edited file path.
+ */
+export function trackEnrichment(filePath: string): void {
+  if (!filePath || !filePath.includes(".cartographer") || !filePath.endsWith("index.md")) return;
+  if (!existsSync(filePath)) return;
+  const sidecar = join(dirname(filePath), ".enriched.json");
+  let existing: EnrichedSidecar = { version: 1, entries: {} };
+  if (existsSync(sidecar)) {
+    try {
+      existing = JSON.parse(readFileSync(sidecar, "utf-8")) as EnrichedSidecar;
+    } catch { /* keep default */ }
+  }
+  const entries = (existing.entries ??= {});
+  let text = "";
+  try {
+    text = readFileSync(filePath, "utf-8");
+  } catch {
+    return;
+  }
+  for (const line of text.split("\n")) {
+    const e = parseEnrichment(line);
+    if (e) entries[e[0]] = e[1];
+  }
+  try {
+    writeFileSync(sidecar, JSON.stringify(existing, null, 2) + "\n", "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/cartographer/write-plugin-map.ts

@@ -0,0 +1,43 @@
+/**
+ * Per-plugin map writer (fs). Ports `write_plugin_map.py`: writes a level-2
+ * `<plugin>/index.md` (indented linked tree) then recurses agents/skills/
+ * commands into deeper index trees. Reuses `buildTree`, `mergeLines`, `writeTree`.
+ */
+import { mkdirSync, statSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+import { buildTree, type ScanRow } from "../../../policy/cartographer/build-tree";
+import { mergeLines } from "./merge";
+import { writeTree } from "./write-tree";
+
+/** True when `dir` is a real directory. */
+function isDir(dir: string): boolean {
+  try {
+    return statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Write `<outputDir>/<pluginName>/index.md` (indented linked tree) and recurse
+ * agents/skills/commands into their own index trees rooted there.
+ * @param outputDir - The map root directory.
+ * @param pluginName - Display name of the plugin (the index subfolder).
+ * @param version - Plugin version ("" to omit).
+ * @param items - The scanned `[type, name, desc]` rows.
+ * @param pluginPath - Absolute source plugin directory (for recursion).
+ */
+export function writePluginMap(outputDir: string, pluginName: string, version: string, items: ReadonlyArray<ScanRow>, pluginPath: string): void {
+  const pluginDir = join(outputDir, pluginName);
+  mkdirSync(pluginDir, { recursive: true });
+  const ver = version ? ` (v${version})` : "";
+  const tree = items.length ? buildTree(items, true) : "└── (empty)";
+  const newLines = `# ${pluginName}${ver}\n\n${tree}`.split("\n");
+  const indexPath = join(pluginDir, "index.md");
+  writeFileSync(indexPath, mergeLines(newLines, indexPath).join("\n") + "\n", "utf-8");
+
+  for (const section of ["agents", "skills", "commands"]) {
+    const src = join(pluginPath, section);
+    if (isDir(src)) writeTree(src, join(pluginDir, section), "../index.md");
+  }
+}

package/src/runtime/lifecycle/cartographer/write-tree.ts

@@ -0,0 +1,44 @@
+/**
+ * Recursive index.md tree writer. Ports `write_recursive.py`.
+ */
+import { mkdirSync, writeFileSync } from "node:fs";
+import { basename, join } from "node:path";
+import { countFiles, getFileDesc, listChildren } from "./fs-util";
+import { mergeLines } from "./merge";
+
+/**
+ * Write `index.md` files mirroring `source` under `output`, recursing into
+ * subdirectories. Directory lines carry a file-count hint; file lines carry a
+ * derived description and link to the real absolute source path.
+ * @param source - Absolute source directory.
+ * @param output - Absolute output directory for the index tree.
+ * @param back - Relative `← back` link target ("" at the root).
+ * @param exclude - Directory/name set to skip.
+ */
+export function writeTree(source: string, output: string, back: string = "", exclude?: ReadonlySet<string>): void {
+  const ex = exclude ?? new Set<string>();
+  mkdirSync(output, { recursive: true });
+  const { dirs, files } = listChildren(source, ex);
+  const lines: string[] = [`# ${basename(source)}\n`];
+  if (back) lines.push(`> [← back](${back})\n`);
+  const total = dirs.length + files.length;
+  let idx = 0;
+  for (const d of dirs) {
+    idx += 1;
+    const conn = idx === total ? "└──" : "├──";
+    const count = countFiles(d, ex);
+    const hint = count ? ` — ${count} files` : "";
+    lines.push(`${conn} [${basename(d)}/](./${basename(d)}/index.md)${hint}`);
+    writeTree(d, join(output, basename(d)), "../index.md", exclude);
+  }
+  for (const f of files) {
+    idx += 1;
+    const conn = idx === total ? "└──" : "├──";
+    const desc = getFileDesc(f);
+    const suffix = desc ? ` — ${desc}` : "";
+    lines.push(`${conn} [${basename(f)}](${f})${suffix}`);
+  }
+  const indexPath = join(output, "index.md");
+  const merged = mergeLines(lines, indexPath);
+  writeFileSync(indexPath, merged.join("\n") + "\n", "utf-8");
+}

package/src/runtime/lifecycle/changelog-research.ts

@@ -0,0 +1,43 @@
+/**
+ * Changelog research tracker (PostToolUse exa/WebFetch/WebSearch). Ports
+ * `track-watch-research.py`: logs research queries to
+ * `~/.claude/logs/00-changelog/<utc-date>-research.json`.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { claudeHome } from "../home-state";
+import { isoUtc, todayUtc } from "./security/skill-state";
+
+/** A recorded changelog research query. */
+interface ChangelogQuery {
+  timestamp: string;
+  tool: string;
+  query: string;
+}
+
+/**
+ * Append an exa/WebFetch/WebSearch query to today's changelog research log.
+ * No-op for other tools. No stdout (errors swallowed).
+ * @param tool - The tool name.
+ * @param input - The tool input (query/url/prompt).
+ * @param now - Clock.
+ * @param home - Home dir.
+ */
+export function trackWatchResearch(tool: string, input: Record<string, unknown>, now: number = Date.now(), home: string = homedir()): void {
+  if (!tool.includes("exa") && !tool.includes("WebFetch") && !tool.includes("WebSearch")) return;
+  const query = String(input.query ?? input.url ?? input.prompt ?? "");
+  const dir = join(claudeHome(home), "logs", "00-changelog");
+  try {
+    mkdirSync(dir, { recursive: true });
+    const path = join(dir, `${todayUtc(now)}-research.json`);
+    let state: { queries: ChangelogQuery[] } = { queries: [] };
+    if (existsSync(path)) {
+      try {
+        state = JSON.parse(readFileSync(path, "utf-8")) as { queries: ChangelogQuery[] };
+      } catch { state = { queries: [] }; }
+    }
+    state.queries.push({ timestamp: isoUtc(now), tool, query });
+    writeFileSync(path, JSON.stringify(state, null, 2), "utf-8");
+  } catch { /* best effort */ }
+}

package/src/runtime/lifecycle/check-file-size.ts

@@ -0,0 +1,61 @@
+/**
+ * PostToolUse (matcher "Write|Edit") for the solid scope: warn when a file
+ * exceeds the adaptive `SOLID_FILE_LIMIT` (set by `solidDetectStart` at
+ * SessionStart, keyed off the detected project type). Ports `check-file-size.py`.
+ * Non-blocking (`additionalContext`), unlike the fixed-ceiling core-guards gate.
+ */
+import { extname } from "node:path";
+import { readText, pathExists } from "../../util/runtime-io";
+import { contextResponse } from "../../adapters/claude";
+import { parseEnvInt } from "../../config/env";
+
+/** Per-language "blank or comment" line pattern (parity `count_loc`'s `code_comment` map). */
+const COMMENT_RE: Record<string, RegExp> = {
+  ts: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  tsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  js: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  jsx: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  go: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  rs: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  java: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  swift: /^\s*$|^\s*\/\/|^\s*\/\*|^\s*\*/,
+  php: /^\s*$|^\s*\/\/|^\s*#|^\s*\/\*|^\s*\*/,
+  py: /^\s*$|^\s*#|^\s*"""|^\s*'''/,
+};
+
+/** Count lines of code excluding comments/blanks for `filePath`'s extension (raw length when unmapped). */
+export function countLoc(filePath: string, content: string): number {
+  const pattern = COMMENT_RE[extname(filePath).slice(1)];
+  const lines = content.split("\n");
+  return pattern ? lines.filter((l) => !pattern.test(l)).length : lines.length;
+}
+
+/**
+ * Warn when a written/edited file exceeds `SOLID_FILE_LIMIT` (default 100).
+ * Inert when `SOLID_PROJECT_TYPE` is absent/"unknown" (parity: the Python hook
+ * no-ops outside a detected project).
+ * @param tool - The tool name (only "Write"/"Edit" are checked).
+ * @param filePath - The written file's absolute path.
+ * @param env - Environment (defaults to `process.env`).
+ * @returns The PostToolUse `additionalContext` response, or `""` when clean/inert.
+ */
+export function checkFileSize(tool: string, filePath: string, env: Record<string, string | undefined> = process.env): string {
+  const ptype = env.SOLID_PROJECT_TYPE ?? "";
+  if (!ptype || ptype === "unknown") return "";
+  if (tool !== "Write" && tool !== "Edit") return "";
+  if (!filePath || !pathExists(filePath)) return "";
+
+  let content: string;
+  try {
+    content = readText(filePath);
+  } catch {
+    return "";
+  }
+
+  const limit = parseEnvInt(env.SOLID_FILE_LIMIT, 100);
+  const loc = countLoc(filePath, content);
+  if (loc <= limit) return "";
+
+  const name = filePath.split("/").pop() ?? filePath;
+  return contextResponse("PostToolUse", `SOLID: ${name} has ${loc} lines (limit: ${limit}). Consider splitting into smaller modules.`);
+}

package/src/runtime/lifecycle/codex-resync/fingerprint.ts

@@ -0,0 +1,63 @@
+import { existsSync, lstatSync, readFileSync, readdirSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { join } from "node:path";
+import { atomicWrite } from "../../../util/json-io";
+import { pathExists } from "../../../util/runtime-io";
+import { buildPluginRoots } from "./plugin-roots";
+
+/** Where the last-applied plugin-cache fingerprint is persisted. */
+function manifestPath(codexHome: string): string {
+  return join(codexHome, "fusengine", "state", "agents-cache-fingerprint.json");
+}
+
+/** sha256 over sorted "plugin=root" pairs — stable while cache resolution is unchanged. */
+export function fingerprint(roots: Map<string, string>): string {
+  const sorted = [...roots.entries()].sort(([a], [b]) => a.localeCompare(b));
+  const hash = createHash("sha256");
+  for (const [plugin, root] of sorted) hash.update(`${plugin}=${root}\n`);
+  return hash.digest("hex");
+}
+
+/** The last-persisted fingerprint, or `undefined` (missing/corrupt — treated as "never resynced"). */
+export function readFingerprint(codexHome: string): string | undefined {
+  try {
+    const raw = JSON.parse(readFileSync(manifestPath(codexHome), "utf8")) as { fingerprint?: string };
+    return raw.fingerprint;
+  } catch {
+    return undefined;
+  }
+}
+
+/** Persist the applied fingerprint atomically (tmp+rename via {@link atomicWrite}). */
+export function writeFingerprint(codexHome: string, value: string): void {
+  atomicWrite(manifestPath(codexHome), JSON.stringify({ fingerprint: value }));
+}
+
+/** True when a direct symlink child of `dir` points at a now-missing target. */
+export function hasDanglingSymlink(dir: string): boolean {
+  if (!existsSync(dir)) return false;
+  try {
+    for (const name of readdirSync(dir)) {
+      const full = join(dir, name);
+      if (lstatSync(full).isSymbolicLink() && !existsSync(full)) return true;
+    }
+  } catch { /* best-effort */ }
+  return false;
+}
+
+/**
+ * Resolve the current plugin roots + fingerprint. `undefined` = nothing cached
+ * (fail-open — the initial installer, not this hook, owns that case).
+ * @param pluginsRoot - The plugin cache root.
+ */
+export function resolveCurrentFingerprint(pluginsRoot: string): { roots: Map<string, string>; value: string } | undefined {
+  if (!pathExists(pluginsRoot)) return undefined;
+  const roots = buildPluginRoots(pluginsRoot);
+  if (roots.size === 0) return undefined;
+  return { roots, value: fingerprint(roots) };
+}
+
+/** True when a resync is due: fingerprint changed/never recorded, or a command symlink is dangling. */
+export function needsResync(codexHome: string, currentValue: string, promptsDir: string): boolean {
+  return currentValue !== readFingerprint(codexHome) || hasDanglingSymlink(promptsDir);
+}