freeharness 0.4.1

package/dist/cli/doctor.js

@@ -0,0 +1,654 @@
+// Doctor checks that are independent of the install layout: runtime deps, settings.json
+// hook conflicts, PROVENANCE baselines vs upstream, manifest drift, and the context-budget
+// section (language lint + token budget, cache hygiene). Each returns
+// printable lines (OK/WARN/INFO prefixed); index.ts composes them with the scope checks.
+import fs from "node:fs";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { baselineStatus } from "../adapters/sync/diff.js";
+import { PLUGIN_KEY } from "../adapters/memory/vendored.js";
+import { manifestPath, readManifest } from "../infra/manifest.js";
+import { retiredFindings } from "./cleanup.js";
+import { languageLines, lintPaths } from "../adapters/content/language-lint.js";
+import { isOurHook } from "./uninstall.js";
+import { CLAUDE_MD_LINE_LIMIT, DEFAULT_PREFIX_BUDGET, cacheInvalidators, estimatePrefix, hookCount, lineCount, mcpRemoveCommand, mcpServerEntries, mcpServerNames, missingTtlKeys, readSettings } from "./prefix.js";
+import { ANTHROPIC_BASE_URL_ENV, CLAUDE_CODE_SUBAGENT_MODEL_ENV, tiersFromEnv } from "@freeharness/core";
+const DEPS = [
+    { name: "node", neededBy: "rules (memory/config guard, repeat-tool, session-start hooks), safety (security-guidance hook), cost (tracker, pruner, monitor hooks), skills (report-formatting docx)", version: ["node", "--version"] },
+    { name: "npm", neededBy: "skills (report-formatting docx deps), sdd (vendored openspec build)", version: ["npm", "--version"] },
+    { name: "bun", neededBy: "memory (worker build + plugin runtime)", version: ["bun", "--version"] },
+    { name: "uv", neededBy: "memory (Chroma vector store)", version: ["uv", "--version"] },
+    { name: "python3", neededBy: "skills (report-formatting pptx)", version: ["python3", "--version"] },
+    { name: "soffice", neededBy: "skills (report-formatting: pptx/docx -> pdf render)" },
+    { name: "pdftoppm", neededBy: "skills (report-formatting: pdf -> thumbnails)" },
+    { name: "python-pptx", neededBy: "skills (report-formatting pptx)", probe: ["python3", "-c", "import pptx"] },
+];
+// Caller's env + PYTHONDONTWRITEBYTECODE=1, so a `python3` probe (e.g. `import pptx`) never
+// leaves a bytecode cache under the home directory the probe runs against.
+const PROBE_ENV = { ...process.env, PYTHONDONTWRITEBYTECODE: "1" };
+/**
+ * Probes every runtime dependency on the current PATH.
+ * @returns One status per dependency, in table order.
+ */
+export function probeDeps() {
+    return DEPS.map((d) => {
+        const probe = d.probe ? spawnSync(d.probe[0], d.probe.slice(1), { encoding: "utf8", env: PROBE_ENV }) : spawnSync("sh", ["-c", `command -v ${d.name}`], { encoding: "utf8", env: PROBE_ENV });
+        const present = probe.status === 0;
+        let version;
+        if (present && d.version) {
+            const v = spawnSync(d.version[0], d.version.slice(1), { encoding: "utf8", env: PROBE_ENV });
+            if (v.status === 0)
+                version = /\d+\.\d+[\w.-]*/.exec(v.stdout)?.[0] ?? v.stdout.trim().split("\n")[0];
+        }
+        return { name: d.name, present, version, neededBy: d.neededBy };
+    });
+}
+/**
+ * Renders the deps table.
+ * @param deps Probe results.
+ * @returns Printable lines.
+ */
+export function depLines(deps) {
+    const lines = ["Runtime deps:"];
+    for (const d of deps) {
+        const name = d.name.padEnd(12);
+        lines.push(d.present ? `  OK   ${name} ${(d.version ?? "present").padEnd(12)} needed by: ${d.neededBy}` : `  WARN ${name} ${"missing".padEnd(12)} needed by: ${d.neededBy}`);
+    }
+    return lines;
+}
+/** Hook conflicts in a settings.json: duplicate commands, a foreign memory-injecting SessionStart hook, claude-mem hooks kept while the plugin is installed; empty when settings.json is absent. */
+export function hookConflictLines(settingsPath, pluginInstalled) {
+    let settings;
+    try {
+        settings = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+    }
+    catch {
+        return [];
+    }
+    const lines = [];
+    const hooks = settings.hooks ?? {};
+    let claudeMemHooks = 0;
+    for (const [event, entries] of Object.entries(hooks)) {
+        if (!Array.isArray(entries))
+            continue;
+        const seen = new Map();
+        for (const e of entries) {
+            for (const h of e.hooks ?? []) {
+                const cmd = h.command ?? "";
+                seen.set(cmd, (seen.get(cmd) ?? 0) + 1);
+                if (/claude-mem/.test(cmd))
+                    claudeMemHooks++;
+            }
+            if (event === "SessionStart" && !isOurHook(e) && (e.hooks ?? []).some((h) => /memory|claude-mem|recall/i.test(h.command ?? ""))) {
+                lines.push(`WARN another SessionStart hook also injects memory: ${(e.hooks ?? []).map((h) => h.command).join(" ; ")} (context may be injected twice)`);
+            }
+        }
+        for (const [cmd, n] of seen)
+            if (n > 1)
+                lines.push(`WARN duplicate hook command in ${event} (${n}x): ${cmd}`);
+    }
+    if (claudeMemHooks > 0) {
+        lines.push(pluginInstalled
+            ? `WARN ${claudeMemHooks} claude-mem hook(s) in settings.json while the ${PLUGIN_KEY} plugin is installed — the plugin ships its own hooks.json; these duplicate it: run \`freeharness cleanup --scope user\``
+            : "OK   claude-mem hook detected in settings.json (coexists; no plugin registered)");
+    }
+    return lines;
+}
+/** Canonical agent file names and skill dir names: what a project could duplicate, and what doctor tells apart from the user's own content. */
+export function canonicalNames(canonicalDir) {
+    const list = (dir, dirsOnly) => {
+        if (!fs.existsSync(dir))
+            return [];
+        return fs
+            .readdirSync(dir, { withFileTypes: true })
+            .filter((e) => (dirsOnly ? e.isDirectory() : e.isFile() && e.name.endsWith(".md") && e.name !== "README.md"))
+            .map((e) => e.name);
+    };
+    return { agents: list(path.join(canonicalDir, "agents"), false), skills: list(path.join(canonicalDir, "skills"), true) };
+}
+/** Skills and agents under a Claude dir that FreeHarness did not emit (the user's own content); never a global `openspec-*` copy or a manifest-recorded retired name. */
+export function foreignContentLines(claudeDir, canonicalDir, scope, projectRoot) {
+    const names = canonicalNames(canonicalDir);
+    const manifest = readManifest(manifestPath(scope, projectRoot));
+    const recordedRetired = new Set(retiredFindings(claudeDir, manifest).filter((f) => f.recorded).map((f) => f.path));
+    const lines = [];
+    const skillsDir = path.join(claudeDir, "skills");
+    if (fs.existsSync(skillsDir)) {
+        for (const e of fs.readdirSync(skillsDir, { withFileTypes: true })) {
+            if (!e.isDirectory() || e.name.startsWith(".") || e.name.startsWith("openspec-") || names.skills.includes(e.name))
+                continue;
+            if (recordedRetired.has(path.join(skillsDir, e.name)))
+                continue;
+            lines.push(`INFO skill ${e.name} not from FreeHarness (yours; kept)`);
+        }
+    }
+    const agentsDir = path.join(claudeDir, "agents");
+    if (fs.existsSync(agentsDir)) {
+        for (const e of fs.readdirSync(agentsDir, { withFileTypes: true })) {
+            if (!e.isFile() || !e.name.endsWith(".md") || names.agents.includes(e.name))
+                continue;
+            if (recordedRetired.has(path.join(agentsDir, e.name)))
+                continue;
+            lines.push(`INFO agent ${e.name.replace(/\.md$/, "")} not from FreeHarness (yours; kept)`);
+        }
+    }
+    return lines.sort();
+}
+/**
+ * Flags a CLI that runs from outside `~/.local/bin` while the install.sh symlink exists there:
+ * the shell resolved an older link (a global `npm link`, a stale PATH entry) ahead of ours.
+ * @param argv1 `process.argv[1]` of the running CLI.
+ * @param home Home directory.
+ * @returns One WARN line, or none.
+ */
+export function runningFromLines(argv1, home) {
+    if (!argv1)
+        return [];
+    const localBin = path.join(home, ".local", "bin");
+    const ours = path.join(localBin, "freeharness");
+    const running = path.resolve(argv1);
+    if (running.startsWith(localBin + path.sep))
+        return [];
+    try {
+        fs.lstatSync(ours);
+    }
+    catch {
+        return [];
+    }
+    return [`WARN running from ${running}; ${ours} exists — open a new terminal or run \`freeharness cleanup --scope user\` (an old npm link may shadow it)`];
+}
+/**
+ * Whether claude-mem is enabled in settings.json or registered in installed_plugins.json.
+ * @param claudeDir The ~/.claude (or project .claude) dir.
+ * @returns True when found in either place.
+ */
+export function memoryPluginInstalled(claudeDir) {
+    const read = (f) => {
+        try {
+            return JSON.parse(fs.readFileSync(f, "utf8"));
+        }
+        catch {
+            return {};
+        }
+    };
+    const settings = read(path.join(claudeDir, "settings.json"));
+    if (settings.enabledPlugins?.[PLUGIN_KEY] === true)
+        return true;
+    const ip = read(path.join(claudeDir, "plugins", "installed_plugins.json"));
+    return Boolean(ip.plugins && PLUGIN_KEY in ip.plugins);
+}
+/**
+ * PROVENANCE baseline vs upstream fork HEAD for each vendored engine.
+ * @param canonicalDir Resolved canonical directory.
+ * @returns Printable lines, one per engine.
+ */
+export function baselineLines(canonicalDir) {
+    const lines = [];
+    for (const target of ["sdd", "memory"]) {
+        const s = baselineStatus(canonicalDir, target);
+        if (!s.forkFound) {
+            lines.push(`INFO ${target}: PROVENANCE baseline ${s.baseline}; fork not found at ${s.fork} (set FREEHARNESS_UPSTREAM_${target.toUpperCase()})`);
+        }
+        else if (!s.head) {
+            lines.push(`INFO ${target}: PROVENANCE baseline ${s.baseline}; fork at ${s.fork} is not a git checkout`);
+        }
+        else if (s.head === s.baseline || s.baseline.startsWith(s.head) || s.head.startsWith(s.baseline)) {
+            lines.push(`OK   ${target}: PROVENANCE baseline ${s.baseline} == fork HEAD`);
+        }
+        else {
+            lines.push(`WARN ${target}: PROVENANCE baseline ${s.baseline} != fork HEAD ${s.head} (run: freeharness sync check ${target})`);
+        }
+    }
+    return lines;
+}
+/** Complete-but-not-archived ids named in the summary, at most. */
+const MAX_COMPLETE_IDS = 5;
+/**
+ * Reads the change status from tasks.md checkbox counts and the optional blockers file.
+ * @param projectRoot Project root.
+ * @returns Status, or null when <projectRoot>/openspec/changes is absent.
+ */
+export function openspecChangeStatus(projectRoot) {
+    const dir = path.join(projectRoot, "openspec", "changes");
+    let entries;
+    try {
+        entries = fs.readdirSync(dir, { withFileTypes: true });
+    }
+    catch {
+        return null;
+    }
+    const inFlight = [];
+    const complete = [];
+    for (const e of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+        if (!e.isDirectory() || e.name === "archive" || e.name.startsWith("."))
+            continue;
+        inFlight.push(e.name);
+        let text;
+        try {
+            text = fs.readFileSync(path.join(dir, e.name, "tasks.md"), "utf8");
+        }
+        catch {
+            continue;
+        }
+        const open = (text.match(/^\s*- \[ \]/gm) ?? []).length;
+        const done = (text.match(/^\s*- \[[xX]\]/gm) ?? []).length;
+        if (open === 0 && done > 0)
+            complete.push(e.name);
+    }
+    let blocked = null;
+    try {
+        const parsed = JSON.parse(fs.readFileSync(path.join(projectRoot, ".freeharness", "sdd", "blockers.json"), "utf8"));
+        const list = Array.isArray(parsed) ? parsed : parsed && typeof parsed === "object" && Array.isArray(parsed.blocked) ? parsed.blocked : null;
+        if (list)
+            blocked = list.filter((id) => typeof id === "string" && inFlight.includes(id));
+    }
+    catch {
+        blocked = null;
+    }
+    return { inFlight, complete, blocked };
+}
+/**
+ * The SDD status summary: WARN naming the complete-but-not-archived changes, OK otherwise.
+ * @param projectRoot Project root.
+ * @returns One line, or none when the project has no openspec/changes.
+ */
+export function openspecChangeLines(projectRoot) {
+    const s = openspecChangeStatus(projectRoot);
+    if (!s)
+        return [];
+    const blocked = s.blocked === null ? "" : `, ${s.blocked.length} blocked by unresolved headers`;
+    const tail = `${s.inFlight.length} change(s) in flight${blocked}; rule: finish or archive before opening a new change (/opsx:archive)`;
+    if (s.complete.length === 0)
+        return [`OK   openspec: ${tail}`];
+    const shown = s.complete.slice(0, MAX_COMPLETE_IDS);
+    const ids = `${shown.join(", ")}${s.complete.length > shown.length ? ", ..." : ""}`;
+    return [`WARN complete changes not archived: ${ids} — ${s.complete.length} of ${tail}`];
+}
+/**
+ * Install-manifest presence and drift (listed files that are gone).
+ * @param manifestFile The manifest path for the scope.
+ * @returns Printable lines.
+ */
+export function manifestLines(manifestFile) {
+    const m = readManifest(manifestFile);
+    if (!m)
+        return [`WARN install manifest not found at ${manifestFile} (run init; uninstall/update --check need it)`];
+    const missing = m.files.filter((f) => !fs.existsSync(f.path)).length;
+    const lines = [`OK   install manifest: ${m.files.length} files, v${m.version}${m.sourceCommit ? ` @${m.sourceCommit}` : ""}, installed ${m.installedAt}`];
+    if (missing > 0)
+        lines.push(`WARN drift: ${missing} files listed in the manifest are gone — freeharness cleanup drops removed copies from the manifest; freeharness update re-emits what should exist`);
+    else
+        lines.push("OK   no drift: every manifest file is present");
+    return lines;
+}
+/**
+ * Roots of the emitted prose for a scope: the rules file plus the harness content dirs.
+ * @param scope `user` or `project`.
+ * @param base `~/.claude` (user) or the project root (project).
+ * @returns Existing or not, in scan order; missing roots are skipped by the lint.
+ */
+export function emittedProseRoots(scope, base) {
+    if (scope === "user")
+        return [path.join(base, "CLAUDE.md"), ...["skills", "agents", "commands", "freeharness"].map((d) => path.join(base, d))];
+    return [path.join(base, "CLAUDE.md"), path.join(base, ".claude")];
+}
+/**
+ * `doctor --context-budget` section: the language lint over canonical and the emitted
+ * content (gerund preambles, Portuguese outside declared pt-BR sections). Advisory only.
+ * @param canonicalDir Resolved canonical directory (null when unresolved).
+ * @param emittedRoots Emitted prose roots for the scope.
+ * @returns Printable lines, indented under a `Context budget:` header.
+ */
+export function contextBudgetLines(canonicalDir, emittedRoots) {
+    const lines = ["Context budget:"];
+    const roots = [...(canonicalDir ? [canonicalDir] : []), ...emittedRoots];
+    for (const l of languageLines(lintPaths(roots)))
+        lines.push(`  ${l}`);
+    return lines;
+}
+/**
+ * Token side of `doctor --context-budget`: CLAUDE.md lines vs 200, hook/MCP counts, the
+ * prefix estimate vs budget, cache TTLs and cache invalidators. Each line is OK or FAIL; the
+ * section never blocks.
+ * @param inp Home, project root, budget.
+ * @returns Printable lines (indented, no header).
+ */
+export function budgetLines(inp) {
+    const home = inp.home;
+    const claudeDir = path.join(home, ".claude");
+    const globalRules = path.join(claudeDir, "CLAUDE.md");
+    const projectRules = path.join(inp.projectRoot, "CLAUDE.md");
+    const userSettingsFile = path.join(claudeDir, "settings.json");
+    const projectSettingsFiles = [path.join(inp.projectRoot, ".claude", "settings.json"), path.join(inp.projectRoot, ".claude", "settings.local.json")];
+    const lines = [];
+    const tag = (ok) => (ok ? "  OK  " : "  FAIL");
+    const pl = lineCount(projectRules);
+    lines.push(fs.existsSync(projectRules) ? `${tag(pl <= CLAUDE_MD_LINE_LIMIT)} CLAUDE.md (project): ${pl} lines (limit ${CLAUDE_MD_LINE_LIMIT}) — ${projectRules}` : `  OK   CLAUDE.md (project): none at ${projectRules}`);
+    const gl = lineCount(globalRules);
+    lines.push(fs.existsSync(globalRules) ? `${tag(gl <= CLAUDE_MD_LINE_LIMIT)} global rules: ${gl} lines (limit ${CLAUDE_MD_LINE_LIMIT}) — ${globalRules}` : `  FAIL global rules: missing ${globalRules} (run init --scope user)`);
+    const hooks = hookCount(userSettingsFile) + projectSettingsFiles.reduce((n, f) => n + hookCount(f), 0);
+    const mcp = mcpServerNames(home, inp.projectRoot);
+    lines.push(`  OK   hooks: ${hooks} command(s) registered (user + project settings); MCP servers: ${mcp.length}${mcp.length > 0 ? ` (${mcp.join(", ")})` : ""}`);
+    const est = estimatePrefix(claudeDir, [globalRules, projectRules], mcp, inp.budget ?? DEFAULT_PREFIX_BUDGET);
+    const top = est.items.slice(0, 3).map((i) => `${path.basename(path.dirname(i.source)) === "skills" || i.kind === "skill description" ? path.basename(path.dirname(i.source)) : path.basename(i.source)} ${i.tokens}`).join(", ");
+    lines.push(`${tag(est.ok)} prefix estimate: ~${est.tokens} tokens over ${est.items.length} sources (budget ${est.budget}; words x 1.3)${top ? `; top: ${top}` : ""}`);
+    const userSettings = readSettings(userSettingsFile);
+    const missing = missingTtlKeys(userSettings);
+    lines.push(missing.length === 0 ? `  OK   cache TTL: promptCacheTtl=${String(userSettings.promptCacheTtl)}, subagentPromptCacheTtl=${String(userSettings.subagentPromptCacheTtl)}` : `  FAIL cache TTL: ${missing.join(", ")} missing in ${userSettingsFile} (freeharness init --scope user --only cost)`);
+    const projectSettings = Object.assign({}, ...projectSettingsFiles.map(readSettings));
+    const inv = cacheInvalidators(userSettings, projectSettings);
+    lines.push(inv.length === 0
+        ? "  OK   cache invalidators: none (project settings do not override model / effortLevel / permissions.deny)"
+        : `  FAIL cache invalidators: ${inv.map((i) => `${i.key}=${JSON.stringify(i.project)} (user: ${i.user === undefined ? "unset" : JSON.stringify(i.user)})`).join("; ")} — project overrides in ${projectSettingsFiles[0]} invalidate the prompt cache; set them at user scope`);
+    lines.push(contextWindowLine(userSettings, projectSettings));
+    return lines;
+}
+/**
+ * Splits a model id on a trailing `[suffix]` tag (e.g. `claude-fable-5-1[1m]`).
+ * @param model Model id as recorded in settings.json.
+ * @returns Base id and suffix (null when the id carries none).
+ */
+function splitModelSuffix(model) {
+    const m = /^(.*)\[([^[\]]+)\]$/.exec(model);
+    return m ? { base: m[1], suffix: m[2] } : { base: model, suffix: null };
+}
+/**
+ * Context-window line of `doctor --context-budget`: WARN when the user or project `model`
+ * carries a `[1m]` suffix (a week on it measured 1.69B cache-read tokens), naming the suffix
+ * and the standard-window id; OK otherwise, naming the effective model (project overrides user).
+ * @param userSettings `~/.claude/settings.json` content.
+ * @param projectSettings Merged `<project>/.claude/settings.json` + `settings.local.json`.
+ * @returns One printable line.
+ */
+export function contextWindowLine(userSettings, projectSettings) {
+    const userModel = typeof userSettings.model === "string" ? userSettings.model : undefined;
+    const projectModel = typeof projectSettings.model === "string" ? projectSettings.model : undefined;
+    const userSplit = userModel ? splitModelSuffix(userModel) : undefined;
+    const projectSplit = projectModel ? splitModelSuffix(projectModel) : undefined;
+    const longContext = userSplit?.suffix?.toLowerCase() === "1m" ? { scope: "user", ...userSplit } : projectSplit?.suffix?.toLowerCase() === "1m" ? { scope: "project", ...projectSplit } : undefined;
+    if (longContext) {
+        return `  WARN context window: ${longContext.scope} settings.json model ${longContext.base}[${longContext.suffix}] (1M tokens); a week on [${longContext.suffix}] cost 1.69G cache-read tokens; standard window: ${longContext.base}`;
+    }
+    const effective = projectModel ?? userModel;
+    return `  OK   context window: standard (${effective ?? "not set"})`;
+}
+/** ms; a local server that misses this is down. */
+export const PROBE_TIMEOUT_MS = 1500;
+/**
+ * GETs a JSON endpoint with a timeout.
+ * @param url URL.
+ * @param timeoutMs Timeout.
+ * @returns Parsed JSON, or the HTTP status as an error.
+ */
+async function getJson(url, timeoutMs) {
+    const ctl = new AbortController();
+    const timer = setTimeout(() => ctl.abort(), timeoutMs);
+    try {
+        const r = await fetch(url, { signal: ctl.signal });
+        let body;
+        try {
+            body = await r.json();
+        }
+        catch {
+            body = undefined;
+        }
+        return { status: r.status, body };
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}
+/**
+ * Probes a local model server: `<base>/api/version` (Ollama) first, then `<base>/v1/models`
+ * (any OpenAI-compatible server such as llama.cpp, vLLM, LM Studio). Down = error text
+ * (ECONNREFUSED, timeout), never a throw.
+ * @param baseUrl The ANTHROPIC_BASE_URL / provider base URL.
+ * @param timeoutMs Timeout per request.
+ * @returns Probe result.
+ */
+export async function probeLocalServer(baseUrl, timeoutMs = PROBE_TIMEOUT_MS) {
+    const base = baseUrl.replace(/\/+$/, "").replace(/\/v1$/, "");
+    const errors = [];
+    try {
+        const v = await getJson(`${base}/api/version`, timeoutMs);
+        const version = v.body?.version;
+        if (v.status === 200 && typeof version === "string") {
+            let models;
+            try {
+                const tags = await getJson(`${base}/api/tags`, timeoutMs);
+                const list = tags.body?.models;
+                if (Array.isArray(list))
+                    models = list.map((m) => m.name ?? "").filter(Boolean);
+            }
+            catch {
+                models = undefined;
+            }
+            return { ok: true, kind: "ollama", detail: `ollama ${version}`, models };
+        }
+        errors.push(`/api/version -> HTTP ${v.status}`);
+    }
+    catch (e) {
+        errors.push(`/api/version -> ${describeFetchError(e, timeoutMs)}`);
+    }
+    try {
+        const m = await getJson(`${base}/v1/models`, timeoutMs);
+        const data = m.body?.data;
+        if (m.status === 200 && Array.isArray(data)) {
+            const models = data.map((d) => d.id ?? "").filter(Boolean);
+            return { ok: true, kind: "openai", detail: `openai-compatible, ${models.length} model(s)`, models };
+        }
+        errors.push(`/v1/models -> HTTP ${m.status}`);
+    }
+    catch (e) {
+        errors.push(`/v1/models -> ${describeFetchError(e, timeoutMs)}`);
+    }
+    return { ok: false, error: errors.join("; ") };
+}
+/**
+ * Short text for a fetch failure (the cause's code when present: ECONNREFUSED, ENOTFOUND).
+ * @param e Thrown value.
+ * @param timeoutMs Timeout used, for the abort message.
+ * @returns Text.
+ */
+function describeFetchError(e, timeoutMs) {
+    if (e instanceof Error) {
+        if (e.name === "AbortError")
+            return `timeout after ${timeoutMs} ms`;
+        const cause = e.cause;
+        return cause?.code ?? cause?.message ?? e.message;
+    }
+    return String(e);
+}
+/**
+ * The active local-model profile as seen in a settings.json env block.
+ * @param settingsFile settings.json path.
+ * @returns Base URL and tier models, or undefined when no base URL is set.
+ */
+export function activeProfile(settingsFile) {
+    const env = (readSettings(settingsFile).env ?? {});
+    const baseUrl = env[ANTHROPIC_BASE_URL_ENV];
+    if (typeof baseUrl !== "string" || !baseUrl)
+        return undefined;
+    const sub = env[CLAUDE_CODE_SUBAGENT_MODEL_ENV];
+    return { baseUrl, tiers: tiersFromEnv(env), subagent: typeof sub === "string" ? sub : undefined };
+}
+/**
+ * Doctor's profile line: no base URL = one OK line (default endpoint); a base URL = the
+ * probe result with the server version and the tier models (FAIL with the error when down,
+ * WARN for a tier model the server does not list).
+ * @param settingsFile settings.json path.
+ * @param probe Probe function (injectable for tests).
+ * @returns Printable lines.
+ */
+export async function profileLines(settingsFile, probe = probeLocalServer) {
+    const p = activeProfile(settingsFile);
+    if (!p)
+        return ["OK   profile: none (default Anthropic endpoint; `freeharness init --profile local-ollama` to use a local server)"];
+    const tiers = ["strong", "standard", "fast"].map((t) => `${t}=${p.tiers[t] ?? "(unset)"}`).join(" ");
+    const r = await probe(p.baseUrl);
+    if (!r.ok)
+        return [`FAIL profile: ${p.baseUrl} down — ${r.error} (start the server, or \`freeharness init --profile none\` to return to the default endpoint); tiers ${tiers}`];
+    const lines = [`OK   profile: ${p.baseUrl} up (${r.detail}); tiers ${tiers}${p.subagent ? `; subagents=${p.subagent}` : ""}`];
+    if (r.models && r.models.length > 0) {
+        for (const t of ["strong", "standard", "fast"]) {
+            const m = p.tiers[t];
+            if (m && !r.models.includes(m) && !r.models.includes(`${m}:latest`))
+                lines.push(`WARN profile: ${t} model ${m} is not listed by the server (${r.models.slice(0, 6).join(", ")}${r.models.length > 6 ? ", ..." : ""})`);
+        }
+    }
+    return lines;
+}
+/**
+ * Tool counts per MCP server name from the catalogs (the mcp profile and servers.json).
+ * @param canonicalDir Resolved canonical directory.
+ * @returns name -> approximate tool count.
+ */
+export function mcpToolCounts(canonicalDir) {
+    const counts = {};
+    try {
+        const cat = JSON.parse(fs.readFileSync(path.join(canonicalDir, "profiles", "mcp.json"), "utf8"));
+        for (const s of cat.servers)
+            counts[s.name] = s.tools_approx;
+    }
+    catch {
+        // no catalog bundled
+    }
+    try {
+        const base = JSON.parse(fs.readFileSync(path.join(canonicalDir, "mcp", "servers.json"), "utf8"));
+        for (const s of base.servers)
+            if (typeof s.tools_approx === "number" && !(s.name in counts))
+                counts[s.name] = s.tools_approx;
+    }
+    catch {
+        // no servers.json
+    }
+    return counts;
+}
+/**
+ * MCP servers with their catalog tool counts, then one line per (server, scope) naming where
+ * it lives and the exact `claude mcp remove -s <scope>` command (Claude Code keeps user/local
+ * scope in `.claude.json`, project scope in `<project>/.mcp.json`).
+ * @param home Home directory.
+ * @param projectRoot Project root.
+ * @param counts Tool counts from `mcpToolCounts`.
+ * @returns Printable lines.
+ */
+export function mcpLines(home, projectRoot, counts) {
+    const entries = mcpServerEntries(home, projectRoot);
+    if (entries.length === 0)
+        return ["OK   mcp: no servers registered (~/.claude.json user + local scopes, <project>/.mcp.json project scope)"];
+    const names = [...new Set(entries.map((e) => e.name))];
+    const total = names.reduce((n, s) => n + (counts[s] ?? 0), 0);
+    const scopesOf = (n) => [...new Set(entries.filter((e) => e.name === n).map((e) => e.scope))].join("+");
+    const lines = [`OK   mcp: ${names.length} server(s), ~${total} tools of schemas on every request: ${names.map((n) => `${n} (${counts[n] !== undefined ? `~${counts[n]} tools` : "no tool count recorded"}, ${scopesOf(n)})`).join(", ")}`];
+    for (const e of entries) {
+        const where = e.scope === "user"
+            ? `user scope in ${e.file}`
+            : e.scope === "local"
+                ? `local scope for ${e.projectPath}${e.projectPath === projectRoot ? " (this project)" : ""} in ${e.file}`
+                : `project scope in ${e.file}`;
+        const catalog = counts[e.name] === undefined ? "; not in the FreeHarness catalog (context cost unknown)" : "";
+        lines.push(`INFO mcp: ${e.name} — ${where}${catalog}; remove: ${mcpRemoveCommand(e)}`);
+    }
+    return lines;
+}
+/**
+ * What the install dirs hold: skill directories and agent `.md` files. Dotfiles (`.DS_Store`
+ * on macOS) and stray files never count.
+ * @param claudeDir `~/.claude` (or a project `.claude`).
+ * @returns Counts, or -1 for a missing directory.
+ */
+export function installedContentCounts(claudeDir) {
+    const count = (dir, keep) => {
+        if (!fs.existsSync(dir))
+            return -1;
+        return fs.readdirSync(dir, { withFileTypes: true }).filter((e) => !e.name.startsWith(".") && keep(e)).length;
+    };
+    return {
+        skills: count(path.join(claudeDir, "skills"), (e) => e.isDirectory()),
+        agents: count(path.join(claudeDir, "agents"), (e) => e.isFile() && e.name.endsWith(".md")),
+    };
+}
+/** Roots a hook command may point at without being flagged foreign. */
+export function trustedHookRoots(home) {
+    return [path.join(home, ".claude", "freeharness"), path.join(home, ".claude", "plugins"), path.join(home, ".claude-mem"), "${CLAUDE_PLUGIN_ROOT}", "${CLAUDE_PROJECT_DIR}"];
+}
+/**
+ * Extracts the script path of a hook command: the first quoted or bare token that looks
+ * like a path (starts with `/`, `~` or `$`), skipping an interpreter (`node`, `bash`, `sh`,
+ * `bun`, `python3`).
+ * @param command Hook command.
+ * @returns The path and whether an interpreter precedes it; undefined for a bare command.
+ */
+export function hookScriptPath(command) {
+    const tokens = [...command.matchAll(/"([^"]+)"|'([^']+)'|(\S+)/g)].map((m) => m[1] ?? m[2] ?? m[3]);
+    if (tokens.length === 0)
+        return undefined;
+    const interpreters = new Set(["node", "bash", "sh", "bun", "python3", "python", "npx", "uv", "uvx"]);
+    let interpreter;
+    for (const t of tokens) {
+        if (interpreters.has(t) && interpreter === undefined) {
+            interpreter = t;
+            continue;
+        }
+        if (t.startsWith("-"))
+            continue;
+        if (/^[/~$]/.test(t))
+            return { script: t, interpreter };
+        return undefined;
+    }
+    return undefined;
+}
+/**
+ * Scans the hook commands of a settings.json: a command whose script lies outside the
+ * trusted roots is WARN foreign; a script that is missing, or invoked directly without the
+ * executable bit, is WARN.
+ * @param settingsPath settings.json path.
+ * @param home Home directory.
+ * @returns Printable lines (an OK line when nothing is found; empty when the file is absent).
+ */
+export function hookScanLines(settingsPath, home) {
+    const settings = readSettings(settingsPath);
+    if (!settings.hooks)
+        return [];
+    const roots = trustedHookRoots(home);
+    const lines = [];
+    let scanned = 0;
+    for (const [event, entries] of Object.entries(settings.hooks)) {
+        for (const e of entries ?? []) {
+            for (const h of e.hooks ?? []) {
+                const cmd = h.command ?? "";
+                if (!cmd)
+                    continue;
+                scanned++;
+                const sp = hookScriptPath(cmd);
+                if (!sp) {
+                    lines.push(`WARN hook scan: ${event} runs a bare command outside the FreeHarness, plugin and memory directories: ${cmd}`);
+                    continue;
+                }
+                const expanded = sp.script.startsWith("~") ? path.join(home, sp.script.slice(1)) : sp.script;
+                if (!roots.some((r) => expanded === r || expanded.startsWith(r.endsWith("/") ? r : `${r}/`) || expanded.startsWith(`${r}${path.sep}`))) {
+                    lines.push(`WARN hook scan: ${event} command points outside the FreeHarness, plugin and memory directories (foreign): ${expanded}`);
+                    continue;
+                }
+                if (expanded.startsWith("$"))
+                    continue;
+                if (!fs.existsSync(expanded)) {
+                    lines.push(`WARN hook scan: ${event} script missing: ${expanded}`);
+                    continue;
+                }
+                if (!sp.interpreter) {
+                    try {
+                        fs.accessSync(expanded, fs.constants.X_OK);
+                    }
+                    catch {
+                        lines.push(`WARN hook scan: ${event} script is not executable (chmod +x): ${expanded}`);
+                    }
+                }
+            }
+        }
+    }
+    if (lines.length === 0)
+        lines.push(`OK   hook scan: ${scanned} command(s) inside the FreeHarness, plugin and memory directories; scripts present and executable`);
+    return lines;
+}

package/dist/cli/executor.d.ts

@@ -0,0 +1,5 @@
+import type { AdapterResult, ExecStep } from "@freeharness/core";
+import type { PackagePort } from "@freeharness/core";
+export declare function collectActions(results: AdapterResult[]): ExecStep[];
+export declare function printPlan(results: AdapterResult[], actions: ExecStep[], dryRun: boolean): void;
+export declare function runActions(actions: ExecStep[], pkg: PackagePort): Promise<void>;