freeharness 0.4.1

package/dist/cli/cleanup.js

@@ -0,0 +1,382 @@
+// Cleanup removes leftovers of earlier installs from a fixed, enumerated list; nothing is
+// discovered by heuristics. User scope: parked upstream claude-mem + data backups, upstream
+// claude-mem hooks in settings.json (once the plugin is registered), legacy /openspec commands,
+// the global @fission-ai/openspec package, a global npm `freeharness` link, retired names
+// (RETIRED) still on disk after a rename or a fold when the manifest records them. Project
+// scope: legacy /openspec commands, project copies of canonical agents/skills, duplicate
+// FreeHarness hook entries. Never listed: the schema override, non-canonical skills/agents,
+// `openspec-*` skills, `.claude/commands/opsx/` (the user's or ours).
+//
+// Two-pass: `planCleanup` computes the list untouched; `applyCleanup` removes the confirmed items.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { PLUGIN_KEY, PLUGIN_NAME, UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_KEY, UPSTREAM_PLUGIN_NAME } from "../adapters/memory/vendored.js";
+import { manifestPath, readManifest } from "../infra/manifest.js";
+import { configDir, dataDir, diagnoseMemory } from "../adapters/memory/doctor.js";
+import { canonicalNames, memoryPluginInstalled } from "./doctor.js";
+import { isClaudeMemHook, isOurHook, pruneHooksMatching } from "./uninstall.js";
+/** The vendored `openspec` bin replaces it. */
+export const LEGACY_OPENSPEC_PACKAGE = "@fission-ai/openspec";
+/** A global link of it shadows the ~/.local/bin symlink. */
+export const CLI_PACKAGE = "freeharness";
+/** Retired by a rename or a fold, bare names under `~/.claude`. */
+export const RETIRED = {
+    skills: ["local-code-intel"],
+    agents: ["mle-reviewer", "mle-evaluator"],
+};
+/** Sums the size (bytes) of every file under a directory. */
+export function dirBytes(dir) {
+    let total = 0;
+    const walk = (d) => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            const p = path.join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (e.isFile())
+                total += fs.statSync(p).size;
+        }
+    };
+    try {
+        walk(dir);
+    }
+    catch {
+        /* unreadable subtree: report what was counted */
+    }
+    return total;
+}
+/** Renders a byte count for the preview (e.g. "12.3 MB"). */
+export function humanBytes(n) {
+    if (n >= 1073741824)
+        return `${(n / 1073741824).toFixed(1)} GB`;
+    if (n >= 1048576)
+        return `${(n / 1048576).toFixed(1)} MB`;
+    if (n >= 1024)
+        return `${(n / 1024).toFixed(1)} KB`;
+    return `${n} B`;
+}
+function npmProbeEnv() {
+    return { ...process.env, NPM_CONFIG_LOGS_MAX: "0", NPM_CONFIG_UPDATE_NOTIFIER: "false", NPM_CONFIG_CACHE: path.join(os.tmpdir(), "freeharness-npm-probe") }; // no trace left in HOME
+}
+/** Top-level packages of the global npm install: name -> version ("?" when unreported), null when npm is unavailable. */
+export function globalNpmPackages() {
+    const r = spawnSync("npm", ["ls", "-g", "--depth=0", "--json"], { encoding: "utf8", timeout: 20000, env: npmProbeEnv() });
+    if (r.error || typeof r.stdout !== "string" || r.stdout.trim() === "")
+        return null;
+    try {
+        // `npm ls` exits non-zero on unmet peers but still prints the tree.
+        const tree = JSON.parse(r.stdout);
+        return Object.fromEntries(Object.entries(tree.dependencies ?? {}).map(([name, dep]) => [name, dep.version ?? "?"]));
+    }
+    catch {
+        return null;
+    }
+}
+/** The `<npm prefix -g>/bin/freeharness` shadowing ours on PATH (an old `npm link -g`); undefined when absent, identical to ours, or npm is unavailable. */
+export function globalNpmFreeharnessBin() {
+    const r = spawnSync("npm", ["prefix", "-g"], { encoding: "utf8", timeout: 20000, env: npmProbeEnv() });
+    if (r.error || r.status !== 0 || typeof r.stdout !== "string")
+        return undefined;
+    const prefix = r.stdout.trim();
+    if (!prefix)
+        return undefined;
+    const bin = path.join(prefix, "bin", CLI_PACKAGE);
+    const ours = path.join(os.homedir(), ".local", "bin", CLI_PACKAGE);
+    if (path.resolve(bin) === path.resolve(ours))
+        return undefined;
+    try {
+        fs.lstatSync(bin); // a dangling link still shadows and still needs `npm unlink`
+    }
+    catch {
+        return undefined;
+    }
+    return bin;
+}
+/** Claude-mem data backups written by `freeharness memory backup` (`<dataDir>-backup-<stamp>`), oldest first. */
+export function memoryBackupDirs() {
+    const data = dataDir();
+    const parent = path.dirname(data);
+    const prefix = `${path.basename(data)}-backup-`;
+    if (!fs.existsSync(parent))
+        return [];
+    return fs
+        .readdirSync(parent, { withFileTypes: true })
+        .filter((e) => e.isDirectory() && e.name.startsWith(prefix))
+        .map((e) => path.join(parent, e.name))
+        .sort();
+}
+/** Plugin keys registered in Claude Code's installed_plugins.json (e.g. "name@marketplace"); empty when absent or unreadable. */
+function installedPluginKeys(cfg) {
+    try {
+        const raw = JSON.parse(fs.readFileSync(path.join(cfg, "plugins", "installed_plugins.json"), "utf8"));
+        return Object.keys(raw.plugins ?? {});
+    }
+    catch {
+        return [];
+    }
+}
+/** Drops install-manifest entries whose file no longer exists (else every removal is "drift"); 0 without a manifest. */
+export function pruneManifest(scope, projectRoot) {
+    const file = manifestPath(scope, projectRoot);
+    const m = readManifest(file);
+    if (!m)
+        return 0;
+    const kept = m.files.filter((f) => fs.existsSync(f.path));
+    const dropped = m.files.length - kept.length;
+    if (dropped > 0)
+        fs.writeFileSync(file, JSON.stringify({ ...m, files: kept, updatedAt: new Date().toISOString() }, null, 2) + "\n");
+    return dropped;
+}
+/** Retired skill/agent names still present under a `.claude` dir: `update`'s additive merge never deletes them; an absent path is skipped. */
+export function retiredFindings(claudeDir, manifest) {
+    const groups = [
+        { kind: "skill", dir: "skills", names: RETIRED.skills },
+        { kind: "agent", dir: "agents", names: RETIRED.agents },
+    ];
+    const found = [];
+    for (const { kind, dir, names } of groups) {
+        for (const name of names) {
+            const fileName = kind === "agent" ? `${name}.md` : name;
+            const p = path.join(claudeDir, dir, fileName);
+            if (!fs.existsSync(p))
+                continue;
+            const under = `${p}${path.sep}`;
+            const recorded = manifest?.files.some((f) => f.path === p || f.path.startsWith(under)) ?? false;
+            found.push({ kind, name, path: p, recorded });
+        }
+    }
+    return found;
+}
+/** Computes the user-scope cleanup list; nothing is touched. */
+async function planUser(deps) {
+    const plan = { scope: "user", items: [], notes: [] };
+    const cfg = configDir();
+    // `memory activate` parks foreign versions under the upstream root (doctor.ts's
+    // disabledRoot): an upstream install or a pre-rename FreeHarness build, never ours.
+    const disabled = path.join(cfg, "plugins", "cache", UPSTREAM_MARKETPLACE_OWNER, `${UPSTREAM_PLUGIN_NAME}.disabled`);
+    if (fs.existsSync(disabled)) {
+        const d = deps.memory ?? (await diagnoseMemory());
+        const item = { kind: "dir", target: disabled, reason: "upstream claude-mem parked by `memory activate`", group: "memory", bytes: dirBytes(disabled) };
+        if (d.verdict !== "ours") {
+            const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
+            item.refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
+        }
+        plan.items.push(item);
+    }
+    // Superseded FreeHarness builds: our own cache versions (.install-version present) that are
+    // not the registered installPath, left behind by a version bump. A legacy-root build that
+    // is also `ours` is excluded: the migration item below already covers that whole tree.
+    {
+        const d = deps.memory ?? (await diagnoseMemory());
+        if (d.activeInstallPath) {
+            for (const c of d.cache.filter((c) => c.ours && !c.legacy && path.resolve(c.dir) !== path.resolve(d.activeInstallPath))) {
+                plan.items.push({ kind: "dir", target: c.dir, reason: `superseded FreeHarness memory build ${c.version} (registered: ${d.activeVersion ?? "?"})`, group: "memory", bytes: dirBytes(c.dir) });
+            }
+        }
+    }
+    for (const b of memoryBackupDirs()) {
+        plan.items.push({ kind: "dir", target: b, reason: "memory data backup written by `memory backup`", group: "backups", bytes: dirBytes(b) });
+    }
+    // Upstream claude-mem wired via settings.json: once the plugin (its own hooks.json) is
+    // registered, these entries run every hook twice.
+    const userSettings = path.join(cfg, "settings.json");
+    if (fs.existsSync(userSettings) && memoryPluginInstalled(cfg) && pruneHooksMatching(userSettings, isClaudeMemHook, true) > 0) {
+        plan.items.push({ kind: "hooks", target: userSettings, reason: `upstream claude-mem hook entries (the ${PLUGIN_KEY} plugin ships its own hooks.json; these run every hook twice)`, group: "memory", hookOwner: UPSTREAM_PLUGIN_NAME });
+    }
+    // Leftovers of a `registerHooks` migration: the pre-rename cache dir (gated on its own
+    // existence, not the key's) and the disabled key (listed only while present). Both stay
+    // refused while the old key is enabled, or (same VERDICT check as above) while the build is
+    // not verified as sole active plugin — installed_plugins.json alone can register the
+    // upstream key here with no enabledPlugins entry at all.
+    {
+        const d = deps.memory ?? (await diagnoseMemory());
+        const oldCacheDir = path.join(cfg, "plugins", "cache", UPSTREAM_MARKETPLACE_OWNER, UPSTREAM_PLUGIN_NAME);
+        let oldKeyValue;
+        try {
+            const settings = JSON.parse(fs.readFileSync(userSettings, "utf8"));
+            oldKeyValue = settings.enabledPlugins?.[UPSTREAM_PLUGIN_KEY];
+        }
+        catch {
+            oldKeyValue = undefined;
+        }
+        let refused;
+        if (oldKeyValue === true) {
+            refused = `the ${UPSTREAM_PLUGIN_KEY} key is still enabled — migrate first: \`freeharness init --scope user --only memory\``;
+        }
+        else if (d.verdict !== "ours") {
+            const verdictLine = d.lines.find((l) => l.includes("VERDICT")) ?? `verdict ${d.verdict}`;
+            refused = `the FreeHarness build is not the only active memory plugin yet (${verdictLine.replace(/^(OK|WARN)\s+/, "")}); run \`freeharness memory activate\` first`;
+        }
+        if (fs.existsSync(oldCacheDir)) {
+            plan.items.push({ kind: "dir", target: oldCacheDir, reason: `previous registration, migrated to ${PLUGIN_NAME}`, group: "memory", bytes: dirBytes(oldCacheDir), refused });
+        }
+        if (oldKeyValue !== undefined) {
+            plan.items.push({ kind: "settings-key", target: userSettings, reason: `disabled ${UPSTREAM_PLUGIN_KEY} key left in enabledPlugins after migrating to ${PLUGIN_KEY}`, group: "memory", settingsKey: UPSTREAM_PLUGIN_KEY, refused });
+        }
+    }
+    const legacy = path.join(cfg, "commands", "openspec");
+    if (fs.existsSync(legacy)) {
+        plan.items.push({ kind: "dir", target: legacy, reason: "legacy OpenSpec /openspec:* commands (replaced by /opsx)", group: "legacy", bytes: dirBytes(legacy) });
+    }
+    // A user-level `openspec init` leaves OpenSpec skills/commands in ~/.claude; FreeHarness
+    // emits those per project only, so a global copy shows them twice everywhere.
+    const globalSkills = path.join(cfg, "skills");
+    if (fs.existsSync(globalSkills)) {
+        for (const n of fs.readdirSync(globalSkills).filter((n) => n.startsWith("openspec-")).sort()) {
+            const d = path.join(globalSkills, n);
+            plan.items.push({ kind: "dir", target: d, reason: "global copy of an OpenSpec skill (FreeHarness emits openspec-* skills per project)", group: "legacy", bytes: dirBytes(d) });
+        }
+    }
+    const globalOpsx = path.join(cfg, "commands", "opsx");
+    if (fs.existsSync(globalOpsx)) {
+        plan.items.push({ kind: "dir", target: globalOpsx, reason: "global copy of the /opsx commands (FreeHarness emits them per project)", group: "legacy", bytes: dirBytes(globalOpsx) });
+    }
+    // Claude Code plugins are removed by Claude Code itself; report only.
+    for (const key of installedPluginKeys(cfg).filter((k) => /openspec|claude-mem/i.test(k) && k !== PLUGIN_KEY)) {
+        plan.notes.push(`Claude Code plugin ${key} is installed (not removed here): run \`claude plugin uninstall ${key}\` if it duplicates FreeHarness`);
+    }
+    const pkgs = globalNpmPackages();
+    if (pkgs === null)
+        plan.notes.push(`npm not available: global ${LEGACY_OPENSPEC_PACKAGE} and ${CLI_PACKAGE} not checked`);
+    else {
+        const v = pkgs[LEGACY_OPENSPEC_PACKAGE];
+        if (v !== undefined)
+            plan.items.push({ kind: "npm-global", target: LEGACY_OPENSPEC_PACKAGE, reason: `global npm package ${v} (shadowed by the vendored openspec bin)`, group: "npm" });
+        // A global `npm link` of the CLI resolves before ~/.local/bin on most PATHs and may
+        // point at an older build.
+        const linkedBin = globalNpmFreeharnessBin();
+        if (pkgs[CLI_PACKAGE] !== undefined || linkedBin) {
+            plan.items.push({ kind: "npm-global", target: CLI_PACKAGE, reason: `npm -g ${CLI_PACKAGE} (old npm link; shadows ~/.local/bin)${linkedBin ? ` at ${linkedBin}` : ""}`, group: "npm", unlink: true });
+        }
+    }
+    // Retired names: listed only when the manifest records the path, so a same-named
+    // user-owned skill/agent stays untouched (doctor reports that case as INFO, never here).
+    const manifest = readManifest(manifestPath("user", ""));
+    for (const f of retiredFindings(path.join(os.homedir(), ".claude"), manifest)) {
+        if (!f.recorded)
+            continue;
+        plan.items.push({
+            kind: f.kind === "skill" ? "dir" : "file",
+            target: f.path,
+            reason: `retired ${f.kind} (renamed or folded elsewhere; kept on disk by update's additive manifest merge)`,
+            group: "retired",
+            bytes: f.kind === "skill" ? dirBytes(f.path) : undefined,
+        });
+    }
+    plan.notes.push(`kept: ${path.join(os.homedir(), ".local", "share", "openspec", "schemas", "spec-driven")} (the FreeHarness schema override)`);
+    return plan;
+}
+/** Computes the project-scope cleanup list; nothing is touched. */
+function planProject(projectRoot, deps) {
+    const plan = { scope: "project", items: [], notes: [] };
+    const claude = path.join(projectRoot, ".claude");
+    const legacy = path.join(claude, "commands", "openspec");
+    if (fs.existsSync(legacy)) {
+        plan.items.push({ kind: "dir", target: legacy, reason: "legacy OpenSpec /openspec:* commands (replaced by /opsx)", group: "legacy", bytes: dirBytes(legacy) });
+    }
+    if (deps.canonicalDir) {
+        const names = canonicalNames(deps.canonicalDir);
+        for (const a of names.agents) {
+            const f = path.join(claude, "agents", a);
+            if (fs.existsSync(f) && fs.statSync(f).isFile()) {
+                plan.items.push({ kind: "file", target: f, reason: "project copy of a global FreeHarness agent (shown twice in Claude Code)", group: "duplicates" });
+            }
+        }
+        for (const s of names.skills) {
+            const d = path.join(claude, "skills", s);
+            if (fs.existsSync(d) && fs.statSync(d).isDirectory()) {
+                plan.items.push({ kind: "dir", target: d, reason: "project copy of a global FreeHarness skill (shown twice in Claude Code)", group: "duplicates", bytes: dirBytes(d) });
+            }
+        }
+    }
+    const settings = path.join(claude, "settings.json");
+    if (fs.existsSync(settings) && pruneHooksMatching(settings, isOurHook, true) > 0) {
+        plan.items.push({ kind: "hooks", target: settings, reason: "FreeHarness hook entries (duplicates of the global ~/.claude/settings.json hooks)", group: "duplicates", hookOwner: "freeharness" });
+    }
+    // Old project-scope emission (pre-v0.3.0): hook scripts + safety.md under
+    // <project>/.freeharness/. Only FreeHarness-named files are listed; the manifest and
+    // anything foreign in that dir stay.
+    const fhDir = path.join(projectRoot, ".freeharness");
+    const oldHooks = path.join(fhDir, "hooks");
+    if (fs.existsSync(oldHooks)) {
+        const ours = fs.readdirSync(oldHooks).filter((n) => n.startsWith("freeharness-"));
+        if (ours.length > 0 && ours.length === fs.readdirSync(oldHooks).length) {
+            plan.items.push({ kind: "dir", target: oldHooks, reason: "old project-scope hook scripts (hooks are global since v0.3.0)", group: "duplicates", bytes: dirBytes(oldHooks) });
+        }
+        else {
+            for (const n of ours)
+                plan.items.push({ kind: "file", target: path.join(oldHooks, n), reason: "old project-scope hook script (hooks are global since v0.3.0)", group: "duplicates" });
+        }
+    }
+    const oldSafety = path.join(fhDir, "safety.md");
+    if (fs.existsSync(oldSafety))
+        plan.items.push({ kind: "file", target: oldSafety, reason: "old project-scope safety.md (global since v0.3.0)", group: "duplicates" });
+    plan.notes.push(`kept: ${path.join(claude, "commands", "opsx")} and ${path.join(claude, "skills", "openspec-*")} (ours)`);
+    return plan;
+}
+/** Builds the cleanup plan for a scope without touching anything; `items` is empty when there is nothing to do. */
+export async function planCleanup(scope, projectRoot, deps = {}) {
+    return scope === "user" ? planUser(deps) : planProject(projectRoot, deps);
+}
+/** Removes the confirmed items of a plan (`confirmed` defaults to all); refused items are always skipped. */
+export function applyCleanup(plan, confirmed = () => true) {
+    const out = { removed: [], skipped: [], warnings: [] };
+    for (const item of plan.items) {
+        if (item.refused || !confirmed(item)) {
+            out.skipped.push(item.target);
+            continue;
+        }
+        switch (item.kind) {
+            case "dir":
+            case "file":
+                fs.rmSync(item.target, { recursive: true, force: true });
+                out.removed.push(item.target);
+                break;
+            case "hooks": {
+                const claudeMem = item.hookOwner === UPSTREAM_PLUGIN_NAME;
+                pruneHooksMatching(item.target, claudeMem ? isClaudeMemHook : isOurHook, false);
+                out.removed.push(`${item.target} (${claudeMem ? UPSTREAM_PLUGIN_NAME : "FreeHarness"} hook entries)`);
+                break;
+            }
+            case "npm-global": {
+                const env = { ...process.env, NPM_CONFIG_UPDATE_NOTIFIER: "false" };
+                const run = (verb) => spawnSync("npm", [verb, "-g", item.target], { encoding: "utf8", timeout: 120000, env });
+                // A linked checkout goes through `unlink`; a real global install answers to `uninstall`.
+                const verbs = item.unlink ? ["unlink", "uninstall"] : ["uninstall"];
+                let verb = verbs[0];
+                let r = run(verb);
+                for (const next of verbs.slice(1)) {
+                    if (r.status === 0)
+                        break;
+                    verb = next;
+                    r = run(verb);
+                }
+                if (r.status === 0)
+                    out.removed.push(`npm -g ${item.target}`);
+                else
+                    out.warnings.push(`npm ${verb} -g ${item.target} failed (exit ${r.status ?? "?"}): ${(r.stderr || r.stdout || "").trim().split("\n")[0]}`);
+                break;
+            }
+            case "settings-key": {
+                const settings = JSON.parse(fs.readFileSync(item.target, "utf8"));
+                if (item.settingsKey && settings.enabledPlugins)
+                    delete settings.enabledPlugins[item.settingsKey];
+                fs.writeFileSync(item.target, JSON.stringify(settings, null, 2) + "\n", "utf8");
+                out.removed.push(`${item.target} (removed ${item.settingsKey} from enabledPlugins)`);
+                break;
+            }
+        }
+    }
+    return out;
+}
+/** Renders a plan item for the preview / doctor output, one line, without the OK/WARN prefix. */
+export function describeItem(item) {
+    const size = item.bytes !== undefined ? ` (${humanBytes(item.bytes)})` : "";
+    const what = item.kind === "npm-global"
+        ? `npm ${item.unlink ? "unlink" : "uninstall"} -g ${item.target}`
+        : item.kind === "hooks" || item.kind === "settings-key"
+            ? `edit: ${item.target}`
+            : `rm: ${item.target}`;
+    return `${what}${size} — ${item.reason}${item.refused ? ` — REFUSED: ${item.refused}` : ""}`;
+}

package/dist/cli/cost.d.ts

@@ -0,0 +1,304 @@
+import type { PrefixItem } from "./prefix.js";
+export interface UsageBucket {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    messages?: number;
+    est_usd?: number;
+}
+export interface AgentUsage {
+    model: string;
+    usage: {
+        input: number;
+        output: number;
+        cache_read: number;
+        cache_write: number;
+        total: number;
+    };
+    messages: number;
+    /** Transcript count merged into this entry; absent on lines predating per-transcript merging. */
+    dispatches?: number;
+}
+export interface UsageRecord {
+    ts: string;
+    event?: string;
+    session_id: string;
+    project: string;
+    cwd?: string;
+    transcript?: string;
+    models?: string[];
+    usage: UsageBucket & {
+        total?: number;
+    };
+    by_model?: Record<string, UsageBucket>;
+    turns?: number;
+    assistant_messages?: number;
+    est_usd: number;
+    warnings?: string[];
+    /** Optional: absent on lines written by an older cost-tracker hook. */
+    task_class?: string;
+    pruned_bytes?: number;
+    context_tokens?: number;
+    tool_calls?: number;
+    tool_output_chars?: number;
+    by_tool?: Record<string, {
+        calls: number;
+        output_chars: number;
+    }>;
+    /** Additive; absent on older lines. */
+    by_agent?: Record<string, AgentUsage>;
+    subagents?: {
+        input: number;
+        output: number;
+        cache_read: number;
+        cache_write: number;
+        total: number;
+    };
+    context_window?: number;
+    model_suffix?: string | null;
+    context_window_source?: "model" | "settings" | "inferred";
+}
+export interface PrunedRecord {
+    kind: "pruned";
+    ts: string;
+    session_id: string;
+    project: string;
+    bytes: number;
+    lines?: number;
+    path?: string;
+    command?: string;
+}
+export interface CostRow {
+    key: string;
+    sessions: number;
+    turns: number;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    est_usd: number;
+}
+export interface CostReport {
+    log: string;
+    since?: string;
+    project?: string;
+    lines: number;
+    sessions: number;
+    byProject: CostRow[];
+    byModel: CostRow[];
+    total: CostRow;
+    last?: string;
+}
+/** Filters accepted by `cost report`. */
+export interface CostFilter {
+    /** Only sessions whose last snapshot is within the last N days. */
+    days?: number;
+    /** Only this project (basename of the session cwd). */
+    project?: string;
+    /** Reference "now" (tests); defaults to the wall clock. */
+    now?: Date;
+}
+/** Usage log path: FREEHARNESS_COST_LOG when set, else ~/.claude/freeharness/cost/usage.jsonl (may not exist yet). */
+export declare function costLogPath(): string;
+/** Installed price table path (user scope): ~/.claude/freeharness/hooks/cost-prices.json (may not exist yet). */
+export declare function costPricesPath(): string;
+/** Reads and parses usage.jsonl (malformed lines skipped); records in file order, empty when the file is absent. */
+export declare function readUsage(file: string): UsageRecord[];
+/** Reads usage.jsonl into usage snapshots and pruner records (malformed lines skipped); file order, empty when the file is absent. */
+export declare function readLog(file: string): {
+    usage: UsageRecord[];
+    pruned: PrunedRecord[];
+};
+/**
+ * Keeps the last snapshot per session (transcript path, else session id, else the
+ * line itself) so cumulative lines are not summed twice; one record per session,
+ * in first-seen order.
+ */
+export declare function latestPerSession(records: UsageRecord[]): UsageRecord[];
+/** Aggregates usage lines into per-project and per-model rows plus a total; rows sorted by estimated USD descending. */
+export declare function aggregate(records: UsageRecord[], filter?: CostFilter, log?: string): CostReport;
+/** Formats a token count compactly (1.2k, 3.4M). */
+export declare function fmtTokens(n: number): string;
+/** Renders the report as aligned text tables. */
+export declare function formatReport(report: CostReport): string[];
+/**
+ * Renders the `cost prefix` session-start injection as one line, apart from the main-session
+ * total: Claude Code injects the routing table into the session-start turn only, so its cost
+ * never rides every request the way the counted items do.
+ * @param injection The estimate's `injection` item.
+ * @returns The formatted line.
+ */
+export declare function formatInjectionLine(injection: PrefixItem): string;
+/** Doctor summary for the cost log: size, entries, last entry. */
+export declare function costLogLine(file: string): string;
+/** Filters accepted by `cost report --sinks`. */
+export interface SinksFilter extends CostFilter {
+    /** Group sessions by task class instead of listing them. */
+    byTaskClass?: boolean;
+    top?: number;
+}
+/** One ranked sink row (a session or a task class). */
+export interface SinkRow {
+    key: string;
+    task_class: string;
+    sessions: number;
+    tokens: number;
+    output: number;
+    tool_output_tokens: number;
+    tool_output_share: number;
+    pruned_bytes: number;
+    est_usd: number;
+}
+export interface ToolRow {
+    tool: string;
+    calls: number;
+    output_tokens: number;
+}
+export interface SinksReport {
+    log: string;
+    since?: string;
+    project?: string;
+    by: "session" | "task-class";
+    sessions: number;
+    untagged: number;
+    pruned_bytes: number;
+    byProject: {
+        project: string;
+        rows: SinkRow[];
+        tools: ToolRow[];
+        notes: string[];
+    }[];
+}
+/**
+ * Ranks token sinks per project: sessions (or task classes) by total tokens with the
+ * tool-output share and the pruned bytes recovered, and tools by output. Sessions without a
+ * task class are `untagged` and counted.
+ */
+export declare function sinks(records: UsageRecord[], filter?: SinksFilter, log?: string): SinksReport;
+/** Renders the sinks report. */
+export declare function formatSinks(report: SinksReport): string[];
+/** One `.freeharness/telemetry.jsonl` record written by the cost-tracker hook on SessionEnd (data-contract.md Sink Schema). */
+export interface TelemetryRecord {
+    ts: string;
+    session_id: string;
+    project: string;
+    started: string | null;
+    ended: string;
+    turns: number;
+    change: string | null;
+    task: string | null;
+    tier: string | null;
+    task_class: string;
+    sinks: {
+        main: {
+            input: number;
+            output: number;
+            cache_read: number;
+            cache_write: number;
+            total: number;
+        };
+        subagents: {
+            input: number;
+            output: number;
+            cache_read: number;
+            cache_write: number;
+            total: number;
+        };
+        by_agent: Record<string, AgentUsage>;
+        observer: {
+            tokens: number;
+            model: string | null;
+        } | null;
+        observer_local: {
+            tokens: number;
+            model: string | null;
+        } | null;
+        tool_output_chars: number;
+        pruned_bytes: number;
+        agent_calls: number;
+    };
+    est_usd: number;
+    context_max: number;
+    context_window: number;
+    warnings: string[];
+}
+/**
+ * Reads `.freeharness/telemetry.jsonl`: a line that is not valid JSON or lacks
+ * `session_id` is skipped and counted on the returned array's `skipped` property; the
+ * last record per `session_id` wins (ties broken by later `ts`), matching the
+ * `latestPerSession` rule for usage.jsonl. Deduplicated records in first-seen order;
+ * empty (with `skipped: 0`) when the file is absent.
+ */
+export declare function readTelemetry(file: string): TelemetryRecord[] & {
+    skipped: number;
+};
+/** One `cost report --changes` row: a tagged change, or the `untagged` catch-all. */
+export interface ChangeRow {
+    change: string;
+    sessions: number;
+    medianMain: number;
+    totalMain: number;
+    medianSubagents: number;
+    totalSubagents: number;
+    totalObserver: number;
+    est_usd: number;
+    tierMix: string;
+}
+/**
+ * Groups telemetry records by their tagged `change` (records with no `change` fall
+ * into `untagged`): session count, median and total main/subagent tokens, summed
+ * observer tokens, summed est USD, and the tier mix (`standard 2, fast 1`, tiers with
+ * no session omitted). One row per change, ranked by total main tokens descending.
+ */
+export declare function changes(records: TelemetryRecord[]): ChangeRow[];
+/** Renders the `--changes` report; `skipped` counts lines `readTelemetry` dropped (malformed or without `session_id`). */
+export declare function formatChanges(rows: ChangeRow[], file: string, skipped: number): string[];
+/** Price row per MTok as read from `cost-prices.json` (see `canonical/hooks/cost-prices.json`). */
+interface PriceRow {
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    window?: number;
+}
+/**
+ * Loads the price table for `agents()`'s USD estimate; a missing or malformed file
+ * yields an empty table so the estimate degrades to 0 instead of throwing.
+ * Mirrors `loadPrices` in canonical/hooks/freeharness-cost-tracker.mjs; kept as a
+ * separate copy since the hook is a standalone, dependency-free .mjs the CLI does not
+ * import from. Returns model name -> price row (per MTok).
+ */
+export declare function loadPriceTable(file: string): Record<string, PriceRow>;
+/** One `cost report --agents` row (ranked by total tokens). */
+export interface AgentRow {
+    name: string;
+    model: string;
+    /** Transcript count (`AgentUsage.dispatches`, summed across sessions; 1 per entry on older lines that predate the field). */
+    dispatches: number;
+    /** Assistant-message count (`AgentUsage.messages`, summed across sessions); a separate figure from `dispatches`. */
+    messages: number;
+    input: number;
+    output: number;
+    cache_read: number;
+    cache_write: number;
+    tokens: number;
+    est_usd: number;
+}
+/**
+ * Ranks subagent dispatches by total tokens from each session's last `by_agent`
+ * snapshot: per agent name, the model with the most tokens (ties broken by name,
+ * mirroring the hook's `mergeAgentUsage`), `dispatches` and `messages` each summed
+ * across sessions from their own fields (an entry from before per-transcript merging
+ * carries no `dispatches` and counts as 1), tokens per bucket summed across sessions,
+ * and an est USD from the price table. Rows ranked by total tokens descending.
+ */
+export declare function agents(records: UsageRecord[], prices?: Record<string, PriceRow>): AgentRow[];
+/** Renders the `--agents` report; `priceTable.loaded: false` prints a notice, `true` (or omitted) prints none. */
+export declare function formatAgents(rows: AgentRow[], priceTable?: {
+    file: string;
+    loaded: boolean;
+}): string[];
+/** Per-project telemetry file path: `<dir>/.freeharness/telemetry.jsonl` (may not exist yet); `dir` defaults to the current working directory. */
+export declare function telemetryPath(dir?: string): string;
+export {};