freeharness 0.4.1 → 0.4.2

package/dist/index.js

@@ -12,20 +12,25 @@ import { manifestPath, readManifest, repoHead, writeManifest } from "./infra/man
 import { runPlan } from "./cli/runner.js";
 import { collectActions, printPlan, runActions } from "./cli/executor.js";
 import { uninstallScope } from "./cli/uninstall.js";
-import { applyCleanup, describeItem, planCleanup, pruneManifest } from "./cli/cleanup.js";
+import { describeItem, planCleanup, pruneManifest } from "./cli/cleanup.js";
+import { archiveRootFor, describeHard, planHard, printable } from "./cli/hard-cleanup.js";
+import { runCleanupPass2 } from "./cli/cleanup-prompt.js";
+import { freeMemEnabled } from "./cli/install-facts.js";
 import { FH_CONTEXT_COMMAND } from "./adapters/harness/claude-code.js";
-import { baselineLines, budgetLines, contextBudgetLines, depLines, emittedProseRoots, foreignContentLines, hookConflictLines, hookScanLines, installedContentCounts, manifestLines, mcpLines, mcpToolCounts, memoryPluginInstalled, openspecChangeLines, probeDeps, profileLines, runningFromLines } from "./cli/doctor.js";
+import { autoMemoryLine, baselineLines, budgetLines, contextBudgetLines, depLines, emittedProseRoots, foreignContentLines, guardRuntimeLines, hookConflictLines, hookScanLines, installedContentCounts, manifestLines, mcpLines, mcpToolCounts, memoryPluginInstalled, openspecChangeLines, probeDeps, profileLines, reportOnlyLauncherLines, runningFromLines, sessionModelLine } from "./cli/doctor.js";
 import { applyEnvProfile, applyMcpProfile, applyProviderProfile, loadProfileFile, mcpCatalogItems, removeProfiles, resolveProfile } from "./cli/profile.js";
 import { formatValidation, validatePluginDir } from "./cli/plugin-validate.js";
 import { PROFILES, PROFILE_NONE } from "@freeharness/core";
-import { agents, aggregate, changes, costLogLine, costLogPath, costPricesPath, formatAgents, formatChanges, formatInjectionLine, formatReport, formatSinks, loadPriceTable, readTelemetry, readUsage, sinks, telemetryPath } from "./cli/cost.js";
+import { agents, aggregate, changes, costLogLine, costLogPath, costPricesPath, escapeJsonControls, formatAgents, formatChanges, formatInjectionLine, formatReport, formatRoutingReport, formatSinks, loadPriceTable, readTelemetry, readUsage, retroJson, retroLine, routingReportForProject, routingReportJson, sinks, telemetryPath, untaggedShare } from "./cli/cost.js";
 import { DEFAULT_PREFIX_BUDGET, estimatePrefix, mcpServerNames } from "./cli/prefix.js";
+import { DEFAULT_QUOTA_DAYS, costQuota } from "./cli/cost-quota.js";
 import { HOOK_SCRIPTS } from "./adapters/harness/claude-code.js";
 import { configMarkerPath, openConfigWindow } from "./infra/fsutil.js";
 import { NodePackage } from "./adapters/package/node.js";
 import { ReadlinePrompt } from "./adapters/prompt/readline.js";
 import { DiffSync } from "./adapters/sync/diff.js";
-import { activateOurs, applyObserverSettings, backupMemoryData, dataDir, diagnoseMemory, previewObserverSettings, restartWorker } from "./adapters/memory/doctor.js";
+import { activateOurs, applyObserverSettings, backupMemoryData, dataDir, diagnoseMemory, previewObserverSettings, restartAfterStage, restartWorker, workerRunning } from "./adapters/memory/doctor.js";
+import { claudePluginPaths, pluginVersion, stagePluginCache, stageStamp, vendoredMemoryEngineDir } from "./adapters/memory/vendored.js";
 const program = new Command();
 program.name("freeharness").description("Agnostic agentic engineering framework installer").version(cliVersion());
 function parseTargets(value) {
@@ -158,17 +163,25 @@ async function applyProfile(opts) {
         await runActions(actions, new NodePackage());
     console.log("\nApplied.");
 }
+/**
+ * The capability ids a plan installs.
+ * @param only The `--only` list, when given.
+ * @param extra Capabilities added to the default set when `only` is absent.
+ * @returns The requested ids.
+ */
+function requestedCapabilities(only, extra = []) {
+    return only ? only.split(",").map((s) => s.trim()).filter(Boolean) : [...new Set([...defaultCapabilityIds(), ...extra])];
+}
 // Two-pass install: pass 1 previews (writes nothing), then (unless --dry-run) confirm
-// and pass 2 applies file writes, then run the side-effecting actions.
-async function applyPlan(opts) {
+// and pass 2 applies file writes, then run the side-effecting actions. Returns whether
+// pass 2 ran.
+async function applyPlan(opts, hooks = {}) {
     const targets = parseTargets(opts.target);
     const scope = parseScope(opts.scope);
     if (targets.includes("plugin") && scope !== "project") {
         throw new Error("--target plugin writes a plugin directory under --project <dir>; it is project-scoped (use --scope project).");
     }
-    const requested = opts.only
-        ? opts.only.split(",").map((s) => s.trim()).filter(Boolean)
-        : defaultCapabilityIds();
+    const requested = requestedCapabilities(opts.only, hooks.extra);
     const plan = buildPlan(requested, targets, scope);
     const canonicalDir = resolveCanonicalDir();
     const projectRoot = path.resolve(opts.project);
@@ -183,15 +196,17 @@ async function applyPlan(opts) {
     const preview = await runPlan(plan, { scope, projectRoot, canonicalDir, dryRun: true, allowProjectCopies });
     const actions = collectActions(preview);
     printPlan(preview, actions, opts.dryRun);
+    for (const l of hooks.planLines ?? [])
+        console.log(`${opts.dryRun ? "[dry-run] " : ""}${l}`);
     if (opts.dryRun) {
         console.log("\n[dry-run] nothing was applied.");
-        return;
+        return false;
     }
     if (!opts.yes) {
         const proceed = await new ReadlinePrompt().confirm("\nApply these changes and run the actions above?");
         if (!proceed) {
             console.log("Aborted; nothing was applied.");
-            return;
+            return false;
         }
     }
     // Pass 2 — apply file writes, record them in the install manifest, then run the actions.
@@ -224,6 +239,28 @@ async function applyPlan(opts) {
     if (actions.length > 0)
         await runActions(actions, new NodePackage());
     console.log("\nApplied.");
+    return true;
+}
+/**
+ * The checkout's vendored memory plugin dir, which the memory install stages.
+ * @returns The plugin dir, or undefined without a vendored engine.
+ */
+function vendoredPluginDir() {
+    const engine = vendoredMemoryEngineDir(resolveCanonicalDir());
+    return engine ? path.join(path.dirname(engine), "plugin") : undefined;
+}
+/**
+ * Prints the outcome of a worker restart after a stage; a failure names the engine log and
+ * never fails the command.
+ * @param r The restart decision and outcome.
+ */
+function printRestart(r) {
+    if (!r.planned)
+        return;
+    if (r.error)
+        console.log(`WARN worker restart failed: ${r.error}; see ${r.log}`);
+    else
+        console.log(`OK   worker restarted: ${r.result?.detail ?? ""}`);
 }
 /**
  * Resolves the prefix budget: --budget, else FREEHARNESS_PREFIX_BUDGET, else the default.
@@ -347,11 +384,27 @@ installOptions(program.command("update").description("Detect a newer FreeHarness
     if (opts.check)
         return;
     console.log(check.newer ? "\nRe-running the install from the newer source:" : "\nRe-emitting anyway (idempotent):");
-    await applyPlan(opts);
+    // Optional capabilities the manifest records (memory) are re-emitted too, so a newer
+    // vendored memory build reaches the plugin cache; the worker state is read before any write,
+    // and a re-stage is detected by the cache marker the staging rewrites.
+    const recorded = readManifest(manifestPath(scope, path.resolve(opts.project)))?.capabilities ?? [];
+    const extra = recorded.filter((id) => CAPABILITIES.some((c) => c.id === id));
+    const pluginDir = vendoredPluginDir();
+    const memory = pluginDir && requestedCapabilities(opts.only, extra).includes("memory") && parseTargets(opts.target).includes("claude-code") ? pluginDir : undefined;
+    const cacheDir = memory ? claudePluginPaths(pluginVersion(memory)).cacheDir : "";
+    const wasRunning = memory !== undefined && (await workerRunning());
+    const before = memory ? stageStamp(cacheDir) : null;
+    const planned = memory ? await restartAfterStage(wasRunning, { staged: stagePluginCache(memory, cacheDir, { dryRun: true }).staged }, true) : undefined;
+    const planLines = planned ? [`restart worker: ${planned.planned ? "yes" : `no (${planned.reason})`}`] : [];
+    const applied = await applyPlan(opts, { extra, planLines });
+    if (memory && applied) {
+        const after = stageStamp(cacheDir);
+        printRestart(await restartAfterStage(wasRunning, { staged: after !== null && after !== before }, false));
+    }
 });
 program
     .command("uninstall")
-    .description("Remove what FreeHarness emitted into a scope (install manifest entries only); never claude-mem data or user files")
+    .description("Remove what FreeHarness emitted into a scope (install manifest entries only); never memory data or user files")
     .option("--scope <scope>", "project | user (global ~/.claude)", "project")
     .option("--project <dir>", "project root (project scope only)", process.cwd())
     .option("--dry-run", "list what would be removed without removing anything", false)
@@ -375,7 +428,7 @@ program
         console.log(`  keep: ${k.path} — ${k.reason}`);
     for (const m of preview.missing)
         console.log(`  gone: ${m}`);
-    console.log("Never touched: settings.json (beyond our hooks), the claude-mem plugin cache and data dir, files not in the manifest.");
+    console.log("Never touched: settings.json (beyond our hooks), the memory plugin cache and memory data dir, files not in the manifest.");
     if (opts.dryRun) {
         console.log("\n[dry-run] nothing was removed.");
         return;
@@ -414,35 +467,57 @@ export function hasPlaceholders(text) {
     const body = text.replace(/<!--[\s\S]*?-->/g, "");
     return /<(?:[A-Za-z0-9][^<>\n]*\s[^<>\n]*|dir_name)>/.test(body);
 }
+/** Row label of a cleanup item, padded to one width. */
+function itemLabel(i) {
+    if (i.group === "backups")
+        return "backup";
+    if (i.refused)
+        return "keep  ";
+    if (i.archiveDest !== undefined)
+        return "move  ";
+    return "remove";
+}
 /**
  * Prints a cleanup plan for the preview / dry-run.
  * @param plan The plan.
  * @param tag Line prefix ("[dry-run] " or "").
+ * @param hard The `--hard` plan, printed after the cleanup plan.
  */
-function printCleanup(plan, tag) {
+function printCleanup(plan, tag, hard) {
     const items = plan.items;
     console.log(`${tag}cleanup (${plan.scope}): ${items.length} item(s)`);
     for (const i of items)
-        console.log(`  ${i.group === "backups" ? "backup" : i.refused ? "keep  " : "remove"}: ${describeItem(i)}`);
+        console.log(`  ${itemLabel(i)}: ${printable(describeItem(i))}`);
     for (const n of plan.notes)
-        console.log(`  note:  ${n}`);
+        console.log(`  note:  ${printable(n)}`);
+    if (!hard)
+        return;
+    console.log(`${tag}hard cleanup (${hard.scope}): ${hard.items.length} item(s), archive ${printable(hard.archiveRoot)}`);
+    for (const i of hard.items)
+        console.log(`  ${printable(describeHard(i))}`);
+    for (const n of hard.notes)
+        console.log(`  note:  ${printable(n)}`);
 }
 program
     .command("cleanup")
-    .description("Remove leftovers of earlier installs: user = parked upstream claude-mem, its backups, upstream claude-mem hook entries in settings.json (plugin registered), legacy /openspec commands, global @fission-ai/openspec, a global npm freeharness link; project = legacy /openspec commands, project copies of global agents/skills, duplicate hook entries. Fixed list; nothing else is touched (your own skills/agents are never listed)")
+    .description("Remove leftovers of earlier installs: user = parked upstream claude-mem, memory backups, upstream claude-mem hook entries in settings.json (free-mem plugin registered), upstream IDE rule files (~/.agent(s)/rules/*-context.md, moved into the dated archive), upstream claude-mem MCP servers in other clients' configs (Antigravity/Gemini, Claude Desktop, Cursor, OpenCode; an archived copy of each file is made first), the thedotmack marketplace directory and its registrations, legacy /openspec commands, global @fission-ai/openspec, a global npm freeharness link; project = legacy /openspec commands, project copies of global agents/skills, duplicate hook entries. Fixed list; nothing else is touched (your own skills/agents are never listed). --hard also moves stale artifacts into ~/Archive/freeharness-<date>/ and deletes none")
     .option("--scope <scope>", "project | user (global ~/.claude)", "project")
     .option("--project <dir>", "project root (project scope only)", process.cwd())
     .option("--dry-run", "list what would be removed without removing anything", false)
-    .option("--yes", "remove without interactive confirmation (backups included)", false)
+    .option("--yes", "skip every prompt, including the --hard move", false)
+    .option("--hard", "also move into ~/Archive/freeharness-<date>/: user = memory logs older than 14 days, all but the newest backup of each settings and plugin-registry file, a dead upstream claude-mem registry entry; project = SDD workspaces of archived changes, .freeharness/parked/, build junk under canonical/", false)
     .action(async (opts) => {
     const scope = parseScope(opts.scope);
     const projectRoot = path.resolve(opts.project);
-    const plan = await planCleanup(scope, projectRoot, { canonicalDir: resolveCanonicalDir() });
+    // One clock read per run, so cleanup and hard moves share one dated archive.
+    const now = new Date();
+    const plan = await planCleanup(scope, projectRoot, { canonicalDir: resolveCanonicalDir(), archiveRoot: archiveRootFor(os.homedir(), now) });
+    const hard = opts.hard ? planHard(scope, projectRoot, { now }) : undefined;
     const tag = opts.dryRun ? "[dry-run] " : "";
-    if (plan.items.length === 0) {
-        console.log(`cleanup (${scope}): nothing to do.`);
-        for (const n of plan.notes)
-            console.log(`  note:  ${n}`);
+    if (plan.items.length === 0 && (hard?.items.length ?? 0) === 0) {
+        console.log(`cleanup (${scope}): nothing to do${hard ? " (hard list checked)" : ""}.`);
+        for (const n of [...plan.notes, ...(hard?.notes ?? [])])
+            console.log(`  note:  ${printable(n)}`);
         if (!opts.dryRun) {
             const pruned = pruneManifest(scope, projectRoot);
             if (pruned > 0)
@@ -450,40 +525,24 @@ program
         }
         return;
     }
-    printCleanup(plan, tag);
+    printCleanup(plan, tag, hard);
     if (opts.dryRun) {
         console.log("\n[dry-run] nothing was removed.");
+        if (hard || plan.items.some((i) => i.archiveDest !== undefined))
+            console.log("[dry-run] nothing was moved.");
         return;
     }
-    const removable = plan.items.filter((i) => !i.refused);
-    const main = removable.filter((i) => i.group !== "backups");
-    const backups = removable.filter((i) => i.group === "backups");
-    let confirmMain = opts.yes;
-    let confirmBackups = opts.yes;
-    if (!opts.yes) {
-        const prompt = new ReadlinePrompt();
-        if (main.length > 0)
-            confirmMain = await prompt.confirm(`\nRemove the ${main.length} item(s) above (backups excluded)?`);
-        if (backups.length > 0) {
-            const total = backups.reduce((n, b) => n + (b.bytes ?? 0), 0);
-            confirmBackups = await prompt.confirm(`Also delete the ${backups.length} claude-mem backup dir(s) (${total >= 1048576 ? `${(total / 1048576).toFixed(1)} MB` : `${total} B`})? They cannot be recovered.`);
-        }
-    }
-    if (!confirmMain && !confirmBackups) {
-        console.log("Aborted; nothing was removed.");
+    const outcome = await runCleanupPass2({ plan, hard, yes: opts.yes, prompt: new ReadlinePrompt(), log: (line) => console.log(line) });
+    if (!outcome)
         return;
-    }
-    const done = applyCleanup(plan, (i) => (i.group === "backups" ? confirmBackups : confirmMain));
-    for (const r of done.removed)
-        console.log(`  removed: ${r}`);
-    for (const k of done.skipped)
-        console.log(`  kept:    ${k}`);
-    for (const w of done.warnings)
-        console.log(`  WARN     ${w}`);
     const pruned = pruneManifest(scope, path.resolve(opts.project));
     if (pruned > 0)
         console.log(`  manifest: dropped ${pruned} entr${pruned === 1 ? "y" : "ies"} that no longer exist`);
-    console.log(`\nRemoved ${done.removed.length} item(s).`);
+    console.log(`\nRemoved ${outcome.done.removed.length} item(s).`);
+    const moved = outcome.done.moved.length + (outcome.archived?.moved.length ?? 0);
+    const archiveRoot = hard?.archiveRoot ?? plan.archiveRoot;
+    if (archiveRoot && (hard || moved > 0))
+        console.log(`Moved ${moved} item(s) to ${printable(archiveRoot)}.`);
 });
 program
     .command("doctor")
@@ -544,6 +603,8 @@ program
         fs.existsSync(path.join(base, "openspec", "config.yaml")) ? ok("openspec/ present") : warn("openspec/ missing (run freeharness bootstrap)");
         for (const l of openspecChangeLines(base))
             console.log(l);
+        for (const l of (await import("./cli/doctor.js")).staleTreeLines(base))
+            console.log(l);
         if (fs.existsSync(rulesFile) && hasPlaceholders(fs.readFileSync(rulesFile, "utf8"))) {
             warn("CLAUDE.md still has <placeholder> fields: run /fh-context in Claude Code");
         }
@@ -566,13 +627,25 @@ program
         raw.includes("freeharness-session-start") ? ok("FreeHarness SessionStart hook present") : warn("FreeHarness SessionStart hook not found");
         raw.includes("freeharness-memory-guard") ? ok("memory-guard hook present") : warn("memory-guard hook not found");
         raw.includes("freeharness-security-guidance") ? ok("security-guidance hook present") : warn("security-guidance hook not found");
-        for (const h of ["freeharness-config-guard", "freeharness-repeat-tool", "freeharness-precompact"])
+        for (const h of ["freeharness-config-guard", "freeharness-repeat-tool", "freeharness-precompact", "freeharness-reload-context"])
             raw.includes(h) ? ok(`${h.replace("freeharness-", "")} hook present`) : warn(`${h.replace("freeharness-", "")} hook not found (run init --only rules)`);
         raw.includes("freeharness-converge") ? ok("converge hook present (armed per project by .freeharness/converge.json)") : warn("converge hook not found (run init --only sdd)");
         if (raw.includes("freeharness-cost-tracker")) {
             console.log(costLogLine(costLogPath()));
             for (const h of ["freeharness-output-pruner", "freeharness-context-monitor"])
                 raw.includes(h) ? ok(`${h.replace("freeharness-", "")} hook present`) : warn(`${h.replace("freeharness-", "")} hook not found (run init --only cost)`);
+            // Without it the SDD task state stops moving between dispatches, silently. Checked per
+            // event because one surviving entry would satisfy a whole-file search; an unparseable
+            // file falls back to that search.
+            let sddMissing;
+            try {
+                const events = JSON.parse(raw).hooks ?? {};
+                sddMissing = ["SubagentStart", "SubagentStop"].filter((e) => !(JSON.stringify(events[e] ?? null) ?? "").includes("freeharness-sdd-context"));
+            }
+            catch {
+                sddMissing = raw.includes("freeharness-sdd-context") ? [] : ["SubagentStart", "SubagentStop"];
+            }
+            sddMissing.length === 0 ? ok("sdd-context hook present") : warn(`freeharness-sdd-context hook not found on ${sddMissing.join(" and ")} (run init --only cost)`);
         }
         else {
             warn("cost-tracker hook not found (the cost capability is part of the default set; run init --only cost)");
@@ -588,6 +661,8 @@ program
             console.log(l);
         for (const l of hookScanLines(settingsPath, os.homedir()))
             console.log(l);
+        for (const l of guardRuntimeLines(settingsPath))
+            console.log(l);
     }
     else {
         warn(`${settingsPath} not found (run init)`);
@@ -595,6 +670,8 @@ program
     // v4 P6: the active local-model profile (probe) and the MCP servers with tool counts.
     for (const l of await profileLines(settingsPath))
         console.log(l);
+    console.log(sessionModelLine(settingsPath));
+    console.log(autoMemoryLine(settingsPath, freeMemEnabled(claudeDir)));
     try {
         for (const l of mcpLines(os.homedir(), path.resolve(opts.project), mcpToolCounts(resolveCanonicalDir())))
             console.log(l);
@@ -637,7 +714,9 @@ program
     for (const i of left.items)
         warn(`leftover of an earlier install: ${describeItem(i)} — run freeharness cleanup --scope user`);
     if (left.items.length === 0)
-        ok("no leftovers of earlier installs (parked claude-mem, backups, upstream claude-mem hooks, legacy /openspec commands, global @fission-ai/openspec, global npm freeharness)");
+        ok("no leftovers of earlier installs (parked upstream claude-mem, memory backups, upstream claude-mem hooks, legacy /openspec commands, global @fission-ai/openspec, global npm freeharness)");
+    for (const l of reportOnlyLauncherLines(os.homedir()))
+        console.log(l);
     if (opts.fix) {
         console.log("\n--fix: re-running install (claude-code) to repair missing pieces...");
         await applyPlan({ target: "claude-code", scope, project: opts.project, dryRun: false, yes: false });
@@ -669,34 +748,43 @@ memory
 });
 memory
     .command("backup")
-    .description("Copy the claude-mem data dir (SQLite + Chroma) to a timestamped sibling; the original is untouched")
+    .description("Copy the memory data dir (the SQLite database and its files) to a timestamped sibling; the original is untouched")
     .action(() => {
     const dest = backupMemoryData();
     console.log(`OK   backup written: ${dest}`);
 });
 memory
     .command("activate")
-    .description("Make the FreeHarness build (free-mem) the only active memory plugin: stop the running worker, move foreign cache versions aside (never deleted), register ours")
+    .description("Make the FreeHarness build (free-mem) the only active memory plugin: stop the running worker, move foreign cache versions aside (never deleted), stage a newer vendored build, register ours, restart a worker that was running")
     .option("--dry-run", "preview without changing anything", false)
     .option("--yes", "apply without confirmation", false)
     .action(async (opts) => {
     try {
-        const preview = await activateOurs(true);
+        const activateOpts = { pluginDir: vendoredPluginDir() };
+        const preview = await activateOurs(true, activateOpts);
         console.log(`${opts.dryRun ? "[dry-run] " : ""}activate plan:`);
         console.log(`  stop running worker: ${preview.stoppedWorker ? "yes" : "none running"}`);
         for (const d of preview.disabled)
             console.log(`  move aside: ${d}`);
         if (preview.disabled.length === 0)
             console.log("  move aside: nothing foreign in the cache");
+        for (const n of preview.stageNotes)
+            console.log(`  stage plugin cache: ${n}`);
         console.log("  register: installed_plugins.json -> the FreeHarness build");
+        console.log(`  restart worker: ${preview.restart.planned ? "yes" : `no (${preview.restart.reason})`}`);
         if (opts.dryRun)
             return;
         if (!opts.yes && !(await new ReadlinePrompt().confirm("\nApply? (run `freeharness memory backup` first if you have not)"))) {
             console.log("Aborted; nothing changed.");
             return;
         }
-        await activateOurs(false);
-        console.log("OK   activated. Open a new Claude Code session: SessionStart starts the FreeHarness worker.");
+        const applied = await activateOurs(false, activateOpts);
+        for (const n of applied.stage?.staged ? applied.stage.notes : [])
+            console.log(`OK   ${n}`);
+        printRestart(applied.restart);
+        console.log(applied.restart.planned && !applied.restart.error
+            ? "OK   activated."
+            : "OK   activated. Open a new Claude Code session: SessionStart starts the FreeHarness worker.");
     }
     catch (e) {
         console.error(e instanceof Error ? e.message : String(e));
@@ -718,11 +806,11 @@ function hasBothLocalFlags(argv) {
 }
 memory
     .command("settings")
-    .description("Preview or apply the FreeHarness-recommended observer settings (model tiers, skip list, concurrency) in the claude-mem settings.json")
+    .description("Preview or apply the FreeHarness-recommended observer settings (model tiers, skip list, concurrency) in the memory settings.json")
     .option("--apply", "write the recommended settings (two-pass: without this, preview only)", false)
     .option("--yes", "apply without interactive confirmation", false)
-    .option("--local <values...>", "switch to the local provider: CLAUDE_MEM_PROVIDER plus four CLAUDE_MEM_LOCAL_* keys, plus CLAUDE_MEM_SKIP_TOOLS narrowed so the local model observes Read, Glob and Grep again; two values, <base-url> then <model>")
-    .option("--no-local", "switch back to the claude provider: CLAUDE_MEM_PROVIDER=claude and CLAUDE_MEM_SKIP_TOOLS restored to the recommended default")
+    .option("--local <values...>", "switch to the local provider: FREE_MEM_PROVIDER plus four FREE_MEM_LOCAL_* keys, plus FREE_MEM_SKIP_TOOLS narrowed so the local model observes Read, Glob and Grep again (CLAUDE_MEM_* names are still read for one release); two values, <base-url> then <model>")
+    .option("--no-local", "switch back to the claude provider: FREE_MEM_PROVIDER=claude and FREE_MEM_SKIP_TOOLS restored to the recommended default")
     .action(async (opts) => {
     try {
         // commander resolves --local and --no-local last-wins into one option value, so a
@@ -765,20 +853,48 @@ memory
         process.exit(1);
     }
 });
+memory
+    .command("import")
+    .description("Move Claude Code's own memory files (auto memory and agent memory) into free-mem once: preview, store each file through the worker without the observer model (private tags stripped, text fenced as untrusted data), then move it into ~/Archive/freeharness-<date>/memory-import/ (never deleted; a failed file stays in place)")
+    .option("--project <dir>", "project whose .claude/agent-memory and .claude/agent-memory-local are collected; repeatable (default: the current directory)", (v, prev) => [...prev, v], [])
+    .option("--yes", "apply without interactive confirmation", false)
+    .option("--dry-run", "preview only: list the files and write nothing", false)
+    .action(async (opts) => {
+    try {
+        const { importMemoryFiles } = await import("./cli/memory-import.js");
+        const outcome = await importMemoryFiles({
+            projects: opts.project.length > 0 ? opts.project.map((p) => path.resolve(p)) : [process.cwd()],
+            now: new Date(),
+            dryRun: opts.dryRun,
+            confirm: () => (opts.yes ? Promise.resolve(true) : new ReadlinePrompt().confirm("\nImport these files into free-mem and move them into the archive?")),
+            log: (line) => console.log(line),
+            error: (line) => console.error(line),
+        });
+        if (outcome.exitCode !== 0)
+            process.exit(outcome.exitCode);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+});
 const cost = program.command("cost").description("Token/cost usage recorded by the cost-tracker hook (cost capability)");
 cost
     .command("report")
     .description("Aggregate ~/.claude/freeharness/cost/usage.jsonl per project and per model (last snapshot per session); --sinks ranks token sinks (sessions, tools, pruned bytes) per project or per task class")
-    .option("--days <n>", "only sessions from the last N days", (v) => parseInt(v, 10))
+    .option("--days <n>", "only sessions from the last N days (also bounds --changes)", (v) => parseInt(v, 10))
     .option("--project <name>", "only this project (basename of the session cwd)")
     .option("--sinks", "rank token sinks: sessions by tokens with tool-output share and pruned bytes, tools by output; untagged sessions counted", false)
     .option("--by <group>", "with --sinks: group sessions by `task-class` (default: per session)")
     .option("--top <n>", "with --sinks: rows per project", (v) => parseInt(v, 10), 10)
     .option("--changes", "per change: session count, median and total tokens per sink, USD and tier mix, from the project telemetry file", false)
-    .option("--dir <path>", "with --changes: the project root whose .freeharness/telemetry.jsonl to read (default: the current working directory)")
+    .option("--dir <path>", "with --changes, --routing or --retro: the project root whose .freeharness/telemetry.jsonl or .freeharness/sdd/ ledgers to read (default: the current working directory)")
     .option("--agents", "per subagent name: model, dispatch count and tokens, from the cost log's by_agent maps", false)
+    .option("--routing", "per implementer configuration (model + effort of a task's first impl dispatch): dispatch counts, escalations and USD per accepted task, from the SDD dispatch ledgers under .freeharness/sdd/ joined with tasks.md acceptance", false)
+    .option("--retro", "with --change: print the change's retrospective line (dispatches, cache reads, ceilings, stops, fix rounds, USD, lead sessions, Claude Code versions) from its ledger and the project telemetry", false)
+    .option("--change <id>", "with --routing: limit to this change; with --retro: the change to measure")
     .option("--json", "print the aggregated report as JSON", false)
-    .action((opts) => {
+    .action(async (opts) => {
     if (opts.days !== undefined && (!Number.isFinite(opts.days) || opts.days < 0)) {
         console.error("--days must be a non-negative integer");
         process.exit(1);
@@ -787,6 +903,28 @@ cost
         console.error("--by accepts only task-class");
         process.exit(1);
     }
+    if (opts.retro) {
+        for (const [set, flag] of [[opts.change === undefined, "--retro requires --change <id>"], [opts.routing, "--retro and --routing are separate reports; pass one"], [opts.changes, "--retro and --changes are separate reports; pass one"]]) {
+            if (set) {
+                console.error(flag);
+                process.exit(1);
+            }
+        }
+        const result = await retroLine(path.resolve(opts.dir ?? process.cwd()), opts.change);
+        if (opts.json && result.ledger)
+            console.log(escapeJsonControls(JSON.stringify(retroJson(result), null, 2)));
+        else
+            console.log(result.line);
+        return;
+    }
+    if (opts.change !== undefined && !opts.routing) {
+        console.error("--change requires --routing or --retro");
+        process.exit(1);
+    }
+    if (opts.routing && opts.changes) {
+        console.error("--routing and --changes are separate reports; pass one");
+        process.exit(1);
+    }
     if (opts.changes) {
         // --changes reads a project directory (--dir, default cwd): unlike --project, which
         // filters the other reports by the session's project *name*, this is a filesystem root.
@@ -796,11 +934,28 @@ cost
             return;
         }
         const records = readTelemetry(file);
-        const rows = changes(records);
+        const result = changes(records, undefined, undefined, undefined, { days: opts.days });
+        const skippedTs = opts.days === undefined ? undefined : result.skippedTs;
+        if (opts.json)
+            console.log(JSON.stringify({ file, skipped: records.skipped, ...(skippedTs === undefined ? {} : { skipped_ts: skippedTs }), rows: result.rows, pricing: result.pricing, excluded: result.excluded, session_classes: result.classes, untagged_share: untaggedShare(result.classes) }, null, 2));
+        else
+            for (const l of formatChanges(result.rows, file, records.skipped, result.pricing, result.excluded, result.classes, skippedTs))
+                console.log(l);
+        return;
+    }
+    if (opts.routing) {
+        const priceFile = costPricesPath();
+        const root = path.resolve(opts.dir ?? process.cwd());
+        const ledgerRoot = path.join(root, ".freeharness", "sdd");
+        if (!opts.json && !fs.existsSync(ledgerRoot)) {
+            console.log(`no dispatch ledger directory at ${ledgerRoot}`);
+            return;
+        }
+        const result = routingReportForProject(root, opts.change, loadPriceTable(priceFile), priceFile);
         if (opts.json)
-            console.log(JSON.stringify({ file, skipped: records.skipped, rows }, null, 2));
+            console.log(escapeJsonControls(JSON.stringify(routingReportJson(result), null, 2)));
         else
-            for (const l of formatChanges(rows, file, records.skipped))
+            for (const l of formatRoutingReport(result))
                 console.log(l);
         return;
     }
@@ -808,7 +963,7 @@ cost
         const log = costLogPath();
         const priceFile = costPricesPath();
         const prices = loadPriceTable(priceFile);
-        const rows = agents(readUsage(log), prices);
+        const { rows, pricing } = agents(readUsage(log), prices, priceFile);
         if (rows.length === 0) {
             console.log(`no by_agent data in ${log}`);
             return;
@@ -816,14 +971,16 @@ cost
         if (opts.json)
             console.log(JSON.stringify(rows, null, 2));
         else
-            for (const l of formatAgents(rows, { file: priceFile, loaded: Object.keys(prices).length > 0 }))
+            for (const l of formatAgents(rows, pricing))
                 console.log(l);
         return;
     }
     const log = costLogPath();
     const records = readUsage(log);
+    const priceFile = costPricesPath();
+    const prices = loadPriceTable(priceFile);
     if (opts.sinks) {
-        const report = sinks(records, { days: opts.days, project: opts.project, byTaskClass: opts.by === "task-class", top: opts.top }, log);
+        const report = sinks(records, { days: opts.days, project: opts.project, byTaskClass: opts.by === "task-class", top: opts.top }, log, prices, priceFile);
         if (opts.json)
             console.log(JSON.stringify(report, null, 2));
         else
@@ -831,7 +988,7 @@ cost
                 console.log(l);
         return;
     }
-    const report = aggregate(records, { days: opts.days, project: opts.project }, log);
+    const report = aggregate(records, { days: opts.days, project: opts.project }, log, prices, priceFile);
     if (opts.json)
         console.log(JSON.stringify(report, null, 2));
     else
@@ -861,6 +1018,26 @@ cost
         console.log(`over budget by ${est.tokens - est.budget} tokens: trim the largest contributors (rules first: every line rides on every request).`);
     console.log(formatInjectionLine(est.injection));
 });
+cost
+    .command("quota")
+    .description("Fit the subscription window percentages the quota tap recorded (~/.claude/freeharness/quota-readings.jsonl) to the transcript tokens of each rising interval: percent per million cache-read and fresh tokens per model family, once a window has three intervals per weight")
+    .option("--days <n>", `only readings from the last N days (default ${DEFAULT_QUOTA_DAYS})`)
+    .option("--json", "print the intervals, their readings and the fit as JSON", false)
+    .option("--write", "store the calibrated windows' weights in ~/.claude/freeharness/quota-calibration.json (nothing else is written)", false)
+    .action((opts) => {
+    if (opts.days !== undefined && !/^[1-9][0-9]{0,5}$/.test(opts.days)) {
+        console.error("--days must be a positive integer");
+        process.exit(1);
+    }
+    try {
+        for (const l of costQuota({ days: opts.days === undefined ? undefined : Number(opts.days), json: opts.json, write: opts.write }))
+            console.log(l);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+});
 cost
     .command("prices")
     .description("Print the price table path (USD per MTok per model; edit it to your contract)")

package/dist/infra/fsutil.d.ts

@@ -22,11 +22,39 @@ export interface HookEntry {
         command: string;
         async?: boolean;
         timeout?: number;
+        onFailure?: "block" | "continue";
     }[];
 }
-/** Additive, deduped by command; never removes existing entries, so claude-mem stays intact. */
-export declare function mergeClaudeHook(settingsPath: string, eventName: string, entry: HookEntry, dryRun: boolean): {
-    added: boolean;
+/** `replacedCommand` is the first owned command that differed from the new one; absent when only identical duplicates collapsed or only `onFailure` changed. */
+export type HookMergeOutcome = {
+    outcome: "added" | "present";
+} | {
+    outcome: "replaced";
+    replacedCommand?: string;
+    onFailureChanged?: true;
+};
+export type HookMergeResult = HookMergeOutcome & {
+    /** The owned script also runs in an entry FreeHarness leaves as is: shared with, or chained to, a foreign command. */
+    hasSharedCopy: boolean;
+};
+/**
+ * Merges one hook entry into a settings event, deduped by command.
+ *
+ * Without `ownerKey` the merge is purely additive. With it, entries whose every command
+ * runs the owned script with flags only are FreeHarness's own: the first is replaced in
+ * place when its command or `onFailure` differs and the rest are dropped, so a flag change
+ * never leaves a stale copy running beside the new one and an older install gains the
+ * fail-closed field. Every other entry, claude-mem's included,
+ * stays as is, even one that mixes the owned script with a foreign command or chains one
+ * to it; that one is only reported.
+ * @param entry Entry to merge; its first command is the dedupe key.
+ * @param dryRun Computes the result without writing.
+ * @param ownerKey Command prefix that runs the owned script, without flags.
+ * @returns What the merge appended, replaced or left running in a shared entry; `collapsed` when
+ *   several owned copies became one, so the note names a collapse rather than a reset.
+ */
+export declare function mergeClaudeHook(settingsPath: string, eventName: string, entry: HookEntry, dryRun: boolean, ownerKey?: string): HookMergeResult & {
+    collapsed?: true;
 };
 /** A key is written only when absent, so a value the user (or another tool) set is never overwritten; `$comment` keys are never copied. */
 export declare function mergeSettingsKeys(settingsPath: string, entries: Record<string, unknown>, dryRun: boolean): {