freeharness 0.4.1

package/dist/cli/executor.js

@@ -0,0 +1,48 @@
+// Flatten results into a deduplicated action list (same command+cwd runs once).
+export function collectActions(results) {
+    const seen = new Set();
+    const out = [];
+    for (const r of results) {
+        for (const a of r.actions) {
+            const key = `${a.cwd ?? ""}::${a.command}`;
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            out.push(a);
+        }
+    }
+    return out;
+}
+// Render the planned writes/notes per capability plus the consolidated actions.
+export function printPlan(results, actions, dryRun) {
+    const tag = dryRun ? "[dry-run] " : "";
+    for (const r of results) {
+        if (r.written.length === 0 && r.notes.length === 0)
+            continue;
+        console.log(`\n${tag}${r.target} :: ${r.capabilityId}`);
+        for (const f of r.written)
+            console.log(`  write: ${f}`);
+        for (const n of r.notes)
+            console.log(`  note:  ${n}`);
+    }
+    if (actions.length > 0) {
+        console.log(`\n${tag}actions:`);
+        for (const a of actions) {
+            const cwd = a.cwd ? `  [cwd: ${a.cwd}]` : "";
+            console.log(`  - ${a.description}${a.optional ? " (optional)" : ""}${cwd}\n      $ ${a.command}`);
+        }
+    }
+}
+// Run the actions in order. Optional actions warn on failure; required ones abort.
+export async function runActions(actions, pkg) {
+    for (const a of actions) {
+        console.log(`\n$ ${a.command}${a.cwd ? `   (in ${a.cwd})` : ""}`);
+        const r = await pkg.exec(a);
+        if (!r.ok) {
+            if (a.optional)
+                console.warn(`WARN  optional action failed (exit ${r.code}): ${a.description}`);
+            else
+                throw new Error(`Action failed (exit ${r.code}): ${a.description}`);
+        }
+    }
+}

package/dist/cli/plugin-validate.d.ts

@@ -0,0 +1,37 @@
+/** Result of validating one plugin directory. */
+export interface PluginValidation {
+    ok: boolean;
+    errors: string[];
+    warnings: string[];
+    /** Counts for the summary line. */
+    counts: {
+        agents: number;
+        skills: number;
+        hookCommands: number;
+        mcpServers: number;
+    };
+}
+/**
+ * Hook events Claude Code dispatches, per the lifecycle table of
+ * https://code.claude.com/docs/en/hooks (a typo here is a silent no-op, so it is an error).
+ * `scripts/simulate-session.mjs` checks every emitted event against the same list.
+ */
+export declare const HOOK_EVENTS: Set<string>;
+/**
+ * Validates a plugin directory (and, when present, the marketplace manifest in its parent).
+ * @param dir The plugin directory (holds `.claude-plugin/plugin.json`).
+ * @param opts `strict`: warnings count as errors; `marketplace`: explicit marketplace.json path (default: `<dir>/../.claude-plugin/marketplace.json` when it exists).
+ * @returns Errors, warnings and counts.
+ */
+export declare function validatePluginDir(dir: string, opts?: {
+    strict?: boolean;
+    marketplace?: string;
+}): PluginValidation;
+/**
+ * Renders a validation as printable lines.
+ * @param dir Directory validated.
+ * @param v Result.
+ * @param strict Whether warnings fail.
+ * @returns Lines.
+ */
+export declare function formatValidation(dir: string, v: PluginValidation, strict: boolean): string[];

package/dist/cli/plugin-validate.js

@@ -0,0 +1,256 @@
+// Local schema check of an emitted Claude Code plugin directory (v4 P5.1): the manifest's
+// required fields, the hooks.json shape, every ${CLAUDE_PLUGIN_ROOT} path resolving to a file,
+// .mcp.json, agent and skill front matter, and the sibling marketplace manifest. Mirrors what
+// `claude plugin validate --strict` rejects so the distribution test and a CI runner without
+// the `claude` CLI catch the same classes of defect. Pure functions over the file system;
+// index.ts prints and sets the exit code.
+import fs from "node:fs";
+import path from "node:path";
+/**
+ * Hook events Claude Code dispatches, per the lifecycle table of
+ * https://code.claude.com/docs/en/hooks (a typo here is a silent no-op, so it is an error).
+ * `scripts/simulate-session.mjs` checks every emitted event against the same list.
+ */
+export const HOOK_EVENTS = new Set([
+    "SessionStart", "Setup", "UserPromptSubmit", "UserPromptExpansion", "PreToolUse", "PermissionRequest", "PermissionDenied", "PostToolUse", "PostToolUseFailure", "PostToolBatch",
+    "Notification", "MessageDisplay", "SubagentStart", "SubagentStop", "TaskCreated", "TaskCompleted", "Stop", "StopFailure", "TeammateIdle", "InstructionsLoaded", "ConfigChange",
+    "CwdChanged", "DirectoryAdded", "FileChanged", "WorktreeCreate", "WorktreeRemove", "PreCompact", "PostCompact", "PreModelSwitch", "PostModelSwitch", "Elicitation",
+    "ElicitationResult", "SessionEnd",
+]);
+/** Plugin names are kebab-case (marketplace and `claude plugin install <name>@<market>`). */
+const KEBAB = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
+const SEMVER = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+/**
+ * Reads and parses a JSON file; a parse failure becomes one error.
+ * @param file Path.
+ * @param errors Sink.
+ * @returns Parsed object or undefined.
+ */
+function readJson(file, errors) {
+    try {
+        const v = JSON.parse(fs.readFileSync(file, "utf8"));
+        if (!v || typeof v !== "object" || Array.isArray(v)) {
+            errors.push(`${file}: not a JSON object`);
+            return undefined;
+        }
+        return v;
+    }
+    catch (e) {
+        errors.push(`${file}: ${e instanceof Error ? e.message : String(e)}`);
+        return undefined;
+    }
+}
+/**
+ * Front matter of a markdown file (`name`, `description`), or undefined when absent.
+ * @param file Path.
+ * @returns Key -> first-line value.
+ */
+function frontMatter(file) {
+    const text = fs.readFileSync(file, "utf8");
+    const m = /^---\n([\s\S]*?)\n---/.exec(text);
+    if (!m)
+        return undefined;
+    const out = {};
+    for (const line of m[1].split("\n")) {
+        const kv = /^([\w-]+):\s*(.*)$/.exec(line);
+        if (kv)
+            out[kv[1]] = kv[2].trim();
+    }
+    return out;
+}
+/**
+ * Validates a plugin directory (and, when present, the marketplace manifest in its parent).
+ * @param dir The plugin directory (holds `.claude-plugin/plugin.json`).
+ * @param opts `strict`: warnings count as errors; `marketplace`: explicit marketplace.json path (default: `<dir>/../.claude-plugin/marketplace.json` when it exists).
+ * @returns Errors, warnings and counts.
+ */
+export function validatePluginDir(dir, opts = {}) {
+    const errors = [];
+    const warnings = [];
+    const counts = { agents: 0, skills: 0, hookCommands: 0, mcpServers: 0 };
+    const root = path.resolve(dir);
+    if (!fs.existsSync(root) || !fs.statSync(root).isDirectory()) {
+        return { ok: false, errors: [`${root}: not a directory`], warnings, counts };
+    }
+    // Manifest: name, version, description required; author/keywords typed when present.
+    const manifestFile = path.join(root, ".claude-plugin", "plugin.json");
+    if (!fs.existsSync(manifestFile))
+        errors.push(`${manifestFile}: missing (required: .claude-plugin/plugin.json)`);
+    const manifest = fs.existsSync(manifestFile) ? readJson(manifestFile, errors) : undefined;
+    if (manifest) {
+        for (const key of ["name", "version", "description"]) {
+            if (typeof manifest[key] !== "string" || !manifest[key].trim())
+                errors.push(`plugin.json: required field '${key}' missing or not a non-empty string`);
+        }
+        if (typeof manifest.name === "string" && !KEBAB.test(manifest.name))
+            errors.push(`plugin.json: name '${manifest.name}' is not kebab-case`);
+        if (typeof manifest.version === "string" && !SEMVER.test(manifest.version))
+            errors.push(`plugin.json: version '${manifest.version}' is not semver`);
+        if (manifest.author !== undefined && (typeof manifest.author !== "object" || manifest.author === null || typeof manifest.author.name !== "string"))
+            errors.push("plugin.json: author must be an object with a name");
+        if (manifest.keywords !== undefined && (!Array.isArray(manifest.keywords) || manifest.keywords.some((k) => typeof k !== "string")))
+            errors.push("plugin.json: keywords must be an array of strings");
+        for (const key of ["homepage", "repository", "license"])
+            if (manifest[key] !== undefined && typeof manifest[key] !== "string")
+                errors.push(`plugin.json: ${key} must be a string`);
+    }
+    // Agents: one .md per agent with name + description front matter.
+    const agentsDir = path.join(root, "agents");
+    if (fs.existsSync(agentsDir)) {
+        for (const f of fs.readdirSync(agentsDir).filter((n) => n.endsWith(".md")).sort()) {
+            counts.agents++;
+            const fm = frontMatter(path.join(agentsDir, f));
+            if (!fm)
+                errors.push(`agents/${f}: front matter missing`);
+            else {
+                if (!fm.name)
+                    errors.push(`agents/${f}: front matter 'name' missing`);
+                if (!fm.description)
+                    errors.push(`agents/${f}: front matter 'description' missing`);
+                if (fm.model && !/^(opus|sonnet|haiku|inherit|[\w.-]+)$/.test(fm.model))
+                    errors.push(`agents/${f}: model '${fm.model}' invalid`);
+                // Key presence, not truthiness: `memory:` with no value declares the key with an unusable value.
+                if ("memory" in fm && !["user", "project", "local"].includes(fm.memory))
+                    errors.push(`agents/${f}: memory '${fm.memory}' invalid`);
+            }
+        }
+    }
+    // Skills: <name>/SKILL.md with name + description.
+    const skillsDir = path.join(root, "skills");
+    if (fs.existsSync(skillsDir)) {
+        for (const e of fs.readdirSync(skillsDir, { withFileTypes: true }).filter((x) => x.isDirectory()).sort((a, b) => a.name.localeCompare(b.name))) {
+            const skill = path.join(skillsDir, e.name, "SKILL.md");
+            if (!fs.existsSync(skill)) {
+                warnings.push(`skills/${e.name}: no SKILL.md (directory ignored by Claude Code)`);
+                continue;
+            }
+            counts.skills++;
+            const fm = frontMatter(skill);
+            if (!fm)
+                errors.push(`skills/${e.name}/SKILL.md: front matter missing`);
+            else {
+                if (!fm.name)
+                    errors.push(`skills/${e.name}/SKILL.md: front matter 'name' missing`);
+                else if (fm.name !== e.name)
+                    warnings.push(`skills/${e.name}/SKILL.md: front matter name '${fm.name}' differs from the directory name`);
+                if (!fm.description)
+                    errors.push(`skills/${e.name}/SKILL.md: front matter 'description' missing`);
+            }
+        }
+    }
+    // Hooks: {description?, hooks: {Event: [{matcher?, hooks: [{type: "command", command}]}]}}.
+    const hooksFile = path.join(root, "hooks", "hooks.json");
+    if (fs.existsSync(hooksFile)) {
+        const doc = readJson(hooksFile, errors);
+        const events = doc?.hooks;
+        if (doc && (!events || typeof events !== "object" || Array.isArray(events)))
+            errors.push("hooks/hooks.json: 'hooks' must be an object keyed by event");
+        else if (events) {
+            for (const [event, entries] of Object.entries(events)) {
+                if (!HOOK_EVENTS.has(event))
+                    errors.push(`hooks/hooks.json: unknown event '${event}'`);
+                if (!Array.isArray(entries)) {
+                    errors.push(`hooks/hooks.json: ${event} must be an array of entries`);
+                    continue;
+                }
+                entries.forEach((entry, i) => {
+                    const e = entry;
+                    if (e.matcher !== undefined && typeof e.matcher !== "string")
+                        errors.push(`hooks/hooks.json: ${event}[${i}].matcher must be a string`);
+                    if (!Array.isArray(e.hooks) || e.hooks.length === 0) {
+                        errors.push(`hooks/hooks.json: ${event}[${i}].hooks must be a non-empty array`);
+                        return;
+                    }
+                    e.hooks.forEach((h, j) => {
+                        const hook = h;
+                        counts.hookCommands++;
+                        if (!["command", "prompt", "agent", "http", "mcp_tool"].includes(String(hook.type)))
+                            errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].type must be command|http|mcp_tool|prompt|agent`);
+                        if (hook.type === "command" && (typeof hook.command !== "string" || !hook.command.trim()))
+                            errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].command missing`);
+                        if (hook.timeout !== undefined && typeof hook.timeout !== "number")
+                            errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}].timeout must be a number`);
+                        if (typeof hook.command === "string") {
+                            for (const m of hook.command.matchAll(/\$\{CLAUDE_PLUGIN_ROOT\}\/([^\s"']+)/g)) {
+                                const target = path.join(root, m[1]);
+                                if (!fs.existsSync(target))
+                                    errors.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}] references \${CLAUDE_PLUGIN_ROOT}/${m[1]} which does not exist`);
+                            }
+                            if (!hook.command.includes("${CLAUDE_PLUGIN_ROOT}") && /(^|\s)\/\S+/.test(hook.command))
+                                warnings.push(`hooks/hooks.json: ${event}[${i}].hooks[${j}] uses an absolute path instead of \${CLAUDE_PLUGIN_ROOT}`);
+                        }
+                    });
+                });
+            }
+        }
+    }
+    // .mcp.json: {mcpServers: {name: {command|url}}}.
+    const mcpFile = path.join(root, ".mcp.json");
+    if (fs.existsSync(mcpFile)) {
+        const doc = readJson(mcpFile, errors);
+        const servers = doc?.mcpServers;
+        if (doc && (!servers || typeof servers !== "object" || Array.isArray(servers)))
+            errors.push(".mcp.json: 'mcpServers' must be an object");
+        else if (servers) {
+            for (const [name, s] of Object.entries(servers)) {
+                counts.mcpServers++;
+                if (typeof s.command !== "string" && typeof s.url !== "string")
+                    errors.push(`.mcp.json: server '${name}' needs a command or a url`);
+                if (s.args !== undefined && !Array.isArray(s.args))
+                    errors.push(`.mcp.json: server '${name}' args must be an array`);
+            }
+        }
+    }
+    // Marketplace (sibling .claude-plugin/marketplace.json): name, owner, plugins[] with a
+    // source that resolves to a plugin dir.
+    const marketFile = opts.marketplace ?? path.join(path.dirname(root), ".claude-plugin", "marketplace.json");
+    if (fs.existsSync(marketFile)) {
+        const m = readJson(marketFile, errors);
+        if (m) {
+            if (typeof m.name !== "string" || !KEBAB.test(m.name))
+                errors.push("marketplace.json: 'name' missing or not kebab-case");
+            if (!m.owner || typeof m.owner !== "object" || typeof m.owner.name !== "string")
+                errors.push("marketplace.json: 'owner.name' missing");
+            if (!Array.isArray(m.plugins) || m.plugins.length === 0)
+                errors.push("marketplace.json: 'plugins' must be a non-empty array");
+            else {
+                m.plugins.forEach((p, i) => {
+                    if (typeof p.name !== "string" || !KEBAB.test(p.name))
+                        errors.push(`marketplace.json: plugins[${i}].name missing or not kebab-case`);
+                    if (typeof p.source === "string") {
+                        if (p.source.startsWith("./") || p.source.startsWith("../")) {
+                            const target = path.resolve(path.dirname(marketFile), "..", p.source);
+                            if (!fs.existsSync(path.join(target, ".claude-plugin", "plugin.json")))
+                                errors.push(`marketplace.json: plugins[${i}].source '${p.source}' has no .claude-plugin/plugin.json`);
+                            else if (manifest && p.name === manifest.name && p.version !== undefined && p.version !== manifest.version)
+                                warnings.push(`marketplace.json: plugins[${i}].version ${String(p.version)} differs from plugin.json ${String(manifest.version)}`);
+                        }
+                    }
+                    else if (!p.source || typeof p.source !== "object")
+                        errors.push(`marketplace.json: plugins[${i}].source must be a relative path or a source object`);
+                });
+            }
+        }
+    }
+    else if (!opts.marketplace) {
+        warnings.push(`no marketplace manifest at ${marketFile} (install with --plugin-dir, or add one for \`claude plugin marketplace add\`)`);
+    }
+    const ok = errors.length === 0 && (!opts.strict || warnings.length === 0);
+    return { ok, errors, warnings, counts };
+}
+/**
+ * Renders a validation as printable lines.
+ * @param dir Directory validated.
+ * @param v Result.
+ * @param strict Whether warnings fail.
+ * @returns Lines.
+ */
+export function formatValidation(dir, v, strict) {
+    const lines = [`plugin validate${strict ? " --strict" : ""}: ${dir}`];
+    for (const e of v.errors)
+        lines.push(`  ERROR ${e}`);
+    for (const w of v.warnings)
+        lines.push(`  WARN  ${w}`);
+    lines.push(`  ${v.ok ? "OK  " : "FAIL"} ${v.counts.agents} agents, ${v.counts.skills} skills, ${v.counts.hookCommands} hook commands, ${v.counts.mcpServers} MCP servers; ${v.errors.length} error(s), ${v.warnings.length} warning(s)${strict && v.warnings.length > 0 ? " (strict: warnings fail)" : ""}`);
+    return lines;
+}

package/dist/cli/prefix.d.ts

@@ -0,0 +1,68 @@
+/** Default prefix budget (`FREEHARNESS_PREFIX_BUDGET` or `--budget` override). */
+export declare const DEFAULT_PREFIX_BUDGET = 12000;
+/** Line limit for a CLAUDE.md (global or project). */
+export declare const CLAUDE_MD_LINE_LIMIT = 200;
+/** One prefix contributor. */
+export interface PrefixItem {
+    /** Absolute file (or a `mcp:` pseudo path). */
+    source: string;
+    /** rules | agent description | skill description | mcp servers | session-start. */
+    kind: string;
+    words: number;
+    tokens: number;
+}
+/** The prefix estimate. */
+export interface PrefixEstimate {
+    items: PrefixItem[];
+    tokens: number;
+    budget: number;
+    ok: boolean;
+    /** Session-start routing injection: apart from `items`, `tokens` and `ok`. */
+    injection: PrefixItem;
+}
+/** ~1.3 tokens per word of English prose: the rule of thumb used everywhere here. */
+export declare function estimateTokens(text: string): {
+    words: number;
+    tokens: number;
+};
+/** A front matter `description:` value (single-line or folded until the next key), CRLF-tolerant. */
+export declare function frontMatterDescription(text: string): string;
+/** True when SKILL.md sets `disable-model-invocation: true` (excluded from the prefix). */
+export declare function isModelDisabled(text: string): boolean;
+/** Where Claude Code stores an MCP server: the three `claude mcp add --scope` values. */
+export type McpScope = "user" | "local" | "project";
+/** One registered MCP server with the scope it lives in. */
+export interface McpServerEntry {
+    name: string;
+    scope: McpScope;
+    /** The file that declares it (`~/.claude.json` or `<project>/.mcp.json`). */
+    file: string;
+    /** Local: the keyed project path; project: the project root. */
+    projectPath?: string;
+}
+/** `~/.claude.json`, or `CLAUDE_CONFIG_DIR`'s copy when that override is set and present. */
+export declare function claudeJsonPath(home: string, env?: NodeJS.ProcessEnv): string;
+/** MCP servers per scope: user (`.claude.json` top level), local (its `projects[<path>]`), project (`<projectRoot>/.mcp.json`). */
+export declare function mcpServerEntries(home: string, projectRoot: string): McpServerEntry[];
+/** The `claude mcp remove` invocation; local/project scope must run from the entry's project dir. */
+export declare function mcpRemoveCommand(e: McpServerEntry): string;
+/** Deduplicated MCP server names across every scope (the estimate's tool-count proxy). */
+export declare function mcpServerNames(home: string, projectRoot: string): string[];
+/** Hook commands registered in a settings.json (0 when absent or malformed). */
+export declare function hookCount(file: string): number;
+/** Estimates the prefix: rules, agent/skill descriptions under `claudeDir`, MCP server names. */
+export declare function estimatePrefix(claudeDir: string, rulesFiles: string[], mcp: string[], budget?: number): PrefixEstimate;
+/** Settings keys whose project-scope override differs from user scope (cache invalidators). */
+export interface Invalidator {
+    key: string;
+    project: unknown;
+    user: unknown;
+}
+/** Reads a settings.json (empty object when absent or malformed). */
+export declare function readSettings(file: string): Record<string, unknown>;
+/** Project-scope `model`/`effortLevel`/`permissions.deny` overrides that invalidate the prompt cache. */
+export declare function cacheInvalidators(userSettings: Record<string, unknown>, projectSettings: Record<string, unknown>): Invalidator[];
+/** Missing prompt-cache TTL keys (empty when both are present). */
+export declare function missingTtlKeys(settings: Record<string, unknown>): string[];
+/** Line count of a file (0 when absent). */
+export declare function lineCount(file: string): number;

package/dist/cli/prefix.js

@@ -0,0 +1,218 @@
+// Prefix estimate: tokens the harness puts in front of every request, the session-start
+// injection counted apart, and the cache-hygiene facts `doctor --context-budget` and
+// `cost prefix` report. Pure functions over the file system; index.ts prints.
+import fs from "node:fs";
+import path from "node:path";
+import { frontmatterBody } from "@freeharness/core";
+import { ROUTING_FILE } from "../infra/routing.js";
+/** Default prefix budget (`FREEHARNESS_PREFIX_BUDGET` or `--budget` override). */
+export const DEFAULT_PREFIX_BUDGET = 12_000;
+/** Line limit for a CLAUDE.md (global or project). */
+export const CLAUDE_MD_LINE_LIMIT = 200;
+/** ~1.3 tokens per word of English prose: the rule of thumb used everywhere here. */
+export function estimateTokens(text) {
+    const words = text.split(/\s+/).filter(Boolean).length;
+    return { words, tokens: Math.round(words * 1.3) };
+}
+/** A front matter `description:` value (single-line or folded until the next key), CRLF-tolerant. */
+export function frontMatterDescription(text) {
+    const body = frontmatterBody(text);
+    if (body === undefined)
+        return "";
+    const lines = body.split(/\r?\n/);
+    const out = [];
+    let inDesc = false;
+    for (const l of lines) {
+        const m = /^description:\s*(.*)$/.exec(l);
+        if (m) {
+            inDesc = true;
+            out.push(m[1].replace(/^[>|]-?\s*$/, ""));
+            continue;
+        }
+        if (inDesc) {
+            if (/^\S/.test(l))
+                break;
+            out.push(l.trim());
+        }
+    }
+    return out.join(" ").trim();
+}
+/** True when SKILL.md sets `disable-model-invocation: true` (excluded from the prefix). */
+export function isModelDisabled(text) {
+    const body = frontmatterBody(text);
+    if (body === undefined)
+        return false;
+    return body.split(/\r?\n/).some((l) => /^disable-model-invocation:\s*true\s*$/.test(l));
+}
+/** Word content of a session-start script's `POINTER_LINES` array; `found` false on a miss (e.g. a rename) names it instead of a silent 0. */
+function pointerLineText(text) {
+    const arr = /POINTER_LINES\s*=\s*\[([\s\S]*?)\]/.exec(text);
+    if (!arr)
+        return { text: "", found: false };
+    const strings = [];
+    const re = /(['"`])((?:\\.|(?!\1)[^\\])*)\1/g;
+    let m;
+    while ((m = re.exec(arr[1])))
+        strings.push(m[2]);
+    return { text: strings.join(" "), found: true };
+}
+/** `.md` files of a directory, or each subdirectory's SKILL.md when `skills`. */
+function listMarkdown(dir, skills) {
+    if (!fs.existsSync(dir))
+        return [];
+    const out = [];
+    for (const e of fs.readdirSync(dir, { withFileTypes: true })) {
+        if (skills) {
+            const f = path.join(dir, e.name, "SKILL.md");
+            if (e.isDirectory() && fs.existsSync(f))
+                out.push(f);
+        }
+        else if (e.isFile() && e.name.endsWith(".md") && e.name !== "README.md")
+            out.push(path.join(dir, e.name));
+    }
+    return out.sort();
+}
+/** `~/.claude.json`, or `CLAUDE_CONFIG_DIR`'s copy when that override is set and present. */
+export function claudeJsonPath(home, env = process.env) {
+    const configDir = env.CLAUDE_CONFIG_DIR;
+    if (configDir) {
+        const inConfig = path.join(configDir, ".claude.json");
+        if (fs.existsSync(inConfig))
+            return inConfig;
+    }
+    return path.join(home, ".claude.json");
+}
+/** MCP servers per scope: user (`.claude.json` top level), local (its `projects[<path>]`), project (`<projectRoot>/.mcp.json`). */
+export function mcpServerEntries(home, projectRoot) {
+    const out = [];
+    const claudeJson = claudeJsonPath(home);
+    try {
+        const parsed = JSON.parse(fs.readFileSync(claudeJson, "utf8"));
+        for (const n of Object.keys(parsed.mcpServers ?? {}))
+            out.push({ name: n, scope: "user", file: claudeJson });
+        for (const [p, cfg] of Object.entries(parsed.projects ?? {}))
+            for (const n of Object.keys(cfg?.mcpServers ?? {}))
+                out.push({ name: n, scope: "local", file: claudeJson, projectPath: p });
+    }
+    catch {
+        // absent or malformed
+    }
+    const projectFile = path.join(projectRoot, ".mcp.json");
+    try {
+        const parsed = JSON.parse(fs.readFileSync(projectFile, "utf8"));
+        for (const n of Object.keys(parsed.mcpServers ?? {}))
+            out.push({ name: n, scope: "project", file: projectFile, projectPath: projectRoot });
+    }
+    catch {
+        // absent or malformed
+    }
+    const rank = { user: 0, local: 1, project: 2 };
+    return out.sort((a, b) => a.name.localeCompare(b.name) || rank[a.scope] - rank[b.scope] || (a.projectPath ?? "").localeCompare(b.projectPath ?? ""));
+}
+/** The `claude mcp remove` invocation; local/project scope must run from the entry's project dir. */
+export function mcpRemoveCommand(e) {
+    const remove = `claude mcp remove ${e.name} -s ${e.scope}`;
+    return e.scope === "user" || !e.projectPath ? remove : `cd "${e.projectPath}" && ${remove}`;
+}
+/** Deduplicated MCP server names across every scope (the estimate's tool-count proxy). */
+export function mcpServerNames(home, projectRoot) {
+    return [...new Set(mcpServerEntries(home, projectRoot).map((e) => e.name))].sort();
+}
+/** Hook commands registered in a settings.json (0 when absent or malformed). */
+export function hookCount(file) {
+    try {
+        const parsed = JSON.parse(fs.readFileSync(file, "utf8"));
+        let n = 0;
+        for (const entries of Object.values(parsed.hooks ?? {}))
+            for (const e of entries ?? [])
+                n += (e.hooks ?? []).length;
+        return n;
+    }
+    catch {
+        return 0;
+    }
+}
+/** Estimates the prefix: rules, agent/skill descriptions under `claudeDir`, MCP server names. */
+export function estimatePrefix(claudeDir, rulesFiles, mcp, budget = DEFAULT_PREFIX_BUDGET) {
+    const items = [];
+    const read = (f) => {
+        try {
+            return fs.readFileSync(f, "utf8");
+        }
+        catch {
+            return "";
+        }
+    };
+    for (const f of rulesFiles) {
+        if (!fs.existsSync(f))
+            continue;
+        items.push({ source: f, kind: "rules", ...estimateTokens(read(f)) });
+    }
+    for (const f of listMarkdown(path.join(claudeDir, "agents"), false))
+        items.push({ source: f, kind: "agent description", ...estimateTokens(frontMatterDescription(read(f))) });
+    for (const f of listMarkdown(path.join(claudeDir, "skills"), true)) {
+        const text = read(f);
+        if (isModelDisabled(text))
+            continue;
+        items.push({ source: f, kind: "skill description", ...estimateTokens(frontMatterDescription(text)) });
+    }
+    if (mcp.length > 0)
+        items.push({ source: `mcp:${mcp.join(",")}`, kind: "mcp servers", ...estimateTokens(mcp.join(" ")) });
+    const tokens = items.reduce((n, i) => n + i.tokens, 0);
+    items.sort((a, b) => b.tokens - a.tokens || a.source.localeCompare(b.source));
+    // Injected once into the session-start turn, never every request: excluded from `tokens`/`ok`.
+    // A missing file contributes 0 words, named in `source`.
+    const routingFile = path.join(claudeDir, "freeharness", "hooks", ROUTING_FILE);
+    const sessionStartFile = path.join(claudeDir, "freeharness", "hooks", "freeharness-session-start");
+    const routingExists = fs.existsSync(routingFile);
+    const sessionStartExists = fs.existsSync(sessionStartFile);
+    const pointer = sessionStartExists ? pointerLineText(read(sessionStartFile)) : { text: "", found: true };
+    const injectionText = `${routingExists ? read(routingFile) : ""} ${pointer.text}`;
+    const routingLabel = routingExists ? routingFile : `${routingFile} (missing)`;
+    const pointerLabel = sessionStartExists
+        ? `${sessionStartFile}${pointer.found ? "" : " (pointer lines not found)"}`
+        : `${sessionStartFile} (missing)`;
+    const injection = {
+        source: `${routingLabel} + ${pointerLabel}`,
+        kind: "session-start",
+        ...estimateTokens(injectionText),
+    };
+    return { items, tokens, budget, ok: tokens <= budget, injection };
+}
+/** Reads a settings.json (empty object when absent or malformed). */
+export function readSettings(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, "utf8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Project-scope `model`/`effortLevel`/`permissions.deny` overrides that invalidate the prompt cache. */
+export function cacheInvalidators(userSettings, projectSettings) {
+    const out = [];
+    const get = (s, key) => (key === "permissions.deny" ? s.permissions?.deny : s[key]);
+    for (const key of ["model", "effortLevel", "permissions.deny"]) {
+        const p = get(projectSettings, key);
+        if (p === undefined)
+            continue;
+        const u = get(userSettings, key);
+        if (JSON.stringify(p) !== JSON.stringify(u))
+            out.push({ key, project: p, user: u });
+    }
+    return out;
+}
+/** Missing prompt-cache TTL keys (empty when both are present). */
+export function missingTtlKeys(settings) {
+    return ["promptCacheTtl", "subagentPromptCacheTtl"].filter((k) => settings[k] === undefined);
+}
+/** Line count of a file (0 when absent). */
+export function lineCount(file) {
+    try {
+        const text = fs.readFileSync(file, "utf8");
+        return text === "" ? 0 : text.replace(/\n$/, "").split("\n").length;
+    }
+    catch {
+        return 0;
+    }
+}