freeharness 0.4.1

package/dist/index.js

@@ -0,0 +1,989 @@
+#!/usr/bin/env node
+// FreeHarness CLI (driving adapter): init, update, bootstrap, cleanup, doctor, list, cost, memory, sync, uninstall.
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { spawnSync } from "node:child_process";
+import { Command } from "commander";
+import { ALL_TARGETS, CAPABILITIES, DEFAULT_TARGETS, defaultCapabilityIds } from "@freeharness/core";
+import { buildPlan } from "@freeharness/core";
+import { cliVersion, resolveCanonicalDir, sourceRepoRoot } from "./infra/paths.js";
+import { manifestPath, readManifest, repoHead, writeManifest } from "./infra/manifest.js";
+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 { 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 { 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 { DEFAULT_PREFIX_BUDGET, estimatePrefix, mcpServerNames } from "./cli/prefix.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";
+const program = new Command();
+program.name("freeharness").description("Agnostic agentic engineering framework installer").version(cliVersion());
+function parseTargets(value) {
+    const items = value.split(",").map((s) => s.trim()).filter(Boolean);
+    const valid = new Set(ALL_TARGETS);
+    const bad = items.filter((i) => !valid.has(i));
+    if (bad.length > 0) {
+        throw new Error(`Unknown target(s): ${bad.join(", ")}. Valid: ${ALL_TARGETS.join(", ")}`);
+    }
+    return items;
+}
+function parseScope(value) {
+    if (value !== "project" && value !== "user") {
+        throw new Error(`Unknown scope: ${value}. Valid: project, user`);
+    }
+    return value;
+}
+/**
+ * Profile pass (v4 P6): `init --profile <id>` applies one profile file to the scope, never the
+ * capability plan. Same two passes as the install: preview (writes nothing), then confirm
+ * (or --yes) and apply; the manifest records the keys and files written so `--profile none`
+ * removes exactly them. Profiles are never part of the default set.
+ * @param opts CLI options.
+ */
+async function applyProfile(opts) {
+    const id = opts.profile;
+    const scope = parseScope(opts.scope);
+    const targets = parseTargets(opts.target);
+    const canonicalDir = resolveCanonicalDir();
+    const projectRoot = path.resolve(opts.project);
+    const claudeDir = scope === "user" ? path.join(os.homedir(), ".claude") : path.join(projectRoot, ".claude");
+    const existing = readManifest(manifestPath(scope, projectRoot))?.profiles ?? {};
+    const profile = resolveProfile(id);
+    console.log(`Profile:      ${id}${profile ? ` — ${profile.description}` : " (remove every recorded profile)"}`);
+    console.log(`Scope:        ${scope}${scope === "user" ? ` (${claudeDir})` : ` (${projectRoot})`}`);
+    console.log(`Canonical:    ${canonicalDir}`);
+    const build = (dryRun, selected) => {
+        const ctx = { canonicalDir, scope, projectRoot, claudeDir, dryRun, existing };
+        if (!profile)
+            return removeProfiles(existing, dryRun);
+        // A profile targets one harness; --target narrows nothing here but must not contradict it.
+        const target = profile.targets.find((t) => targets.includes(t)) ?? (targets.includes("plugin") ? undefined : profile.targets[0]);
+        if (!target)
+            throw new Error(`profile ${id} targets ${profile.targets.join(", ")}; pass --target ${profile.targets[0]}`);
+        if (target === "opencode" && scope !== "project")
+            throw new Error(`profile ${id} writes <project>/opencode.json: use --scope project --project <dir>`);
+        const data = loadProfileFile(canonicalDir, profile);
+        switch (profile.kind) {
+            case "claude-code-env":
+                return [applyEnvProfile(profile, data, ctx)];
+            case "opencode-provider":
+                return [applyProviderProfile(profile, data, ctx)];
+            case "mcp-catalog":
+                return [applyMcpProfile(profile, data, selected, ctx)];
+            default:
+                throw new Error(`profile ${id}: unknown kind`);
+        }
+    };
+    const print = (plans, tag) => {
+        for (const p of plans) {
+            console.log(`\n${tag}${p.target} :: profile ${p.profileId}`);
+            for (const l of p.lines)
+                console.log(l);
+            if (p.actions.length > 0) {
+                console.log(`\n${tag}actions:`);
+                for (const a of p.actions)
+                    console.log(`  - ${a.description}${a.optional ? " (optional)" : ""}\n      $ ${a.command}`);
+            }
+        }
+        if (plans.length === 0)
+            console.log(`\n${tag}no profile recorded in the manifest; nothing to remove.`);
+    };
+    // Selection (mcp profile): --select for non-interactive runs, else the prompt; no TTY = none.
+    let selected = [];
+    if (profile?.kind === "mcp-catalog") {
+        const items = mcpCatalogItems(loadProfileFile(canonicalDir, profile));
+        // --select takes names (unknown ones are reported by the plan); the prompt takes numbers too.
+        if (opts.select !== undefined)
+            selected = opts.select.split(",").map((t) => t.trim()).filter(Boolean);
+        else if (!opts.dryRun)
+            selected = await new ReadlinePrompt().select("\nMCP catalog (nothing is registered without a selection):", items);
+        if (opts.dryRun && opts.select === undefined) {
+            console.log("\nMCP catalog (dry-run shows the catalog; pass --select a,b to preview a selection):");
+            for (const it of items)
+                console.log(`  - ${it.id.padEnd(14)} ${it.label}`);
+        }
+    }
+    const preview = build(true, selected);
+    print(preview, opts.dryRun ? "[dry-run] " : "");
+    if (opts.dryRun) {
+        console.log("\n[dry-run] nothing was applied.");
+        return;
+    }
+    const changes = preview.some((p) => p.lines.some((l) => /^  (edit|write|rm|mcp):/.test(l)) || p.actions.length > 0);
+    if (!changes) {
+        console.log("\nNothing to apply.");
+        return;
+    }
+    if (!opts.yes && !(await new ReadlinePrompt().confirm("\nApply these changes?"))) {
+        console.log("Aborted; nothing was applied.");
+        return;
+    }
+    const closeWindow = openConfigWindow(configMarkerPath(scope, projectRoot, os.homedir()));
+    let plans;
+    try {
+        plans = build(false, selected);
+    }
+    finally {
+        closeWindow();
+    }
+    const records = {};
+    for (const p of plans)
+        if (p.record !== undefined)
+            records[p.profileId] = p.record;
+    const repo = sourceRepoRoot(canonicalDir);
+    const manifest = writeManifest({
+        version: cliVersion(),
+        sourceCommit: repo ? repoHead(repo) : undefined,
+        scope,
+        projectRoot,
+        targets: [...new Set(plans.map((p) => p.target))],
+        capabilities: [],
+        results: plans.map((p) => ({ capabilityId: `profile:${p.profileId}`, target: p.target, written: p.written, actions: p.actions, notes: [] })),
+        actions: plans.flatMap((p) => p.actions.map((a) => a.description)),
+        profiles: records,
+    });
+    console.log(`\nmanifest: ${manifest}`);
+    const actions = collectActions(plans.map((p) => ({ capabilityId: p.profileId, target: p.target, written: [], actions: p.actions, notes: [] })));
+    if (actions.length > 0)
+        await runActions(actions, new NodePackage());
+    console.log("\nApplied.");
+}
+// 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) {
+    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 plan = buildPlan(requested, targets, scope);
+    const canonicalDir = resolveCanonicalDir();
+    const projectRoot = path.resolve(opts.project);
+    console.log(`Scope:        ${scope}${scope === "user" ? ` (${path.join(os.homedir(), ".claude")})` : ""}`);
+    console.log(`Targets:      ${targets.join(", ")}`);
+    console.log(`Capabilities: ${plan.capabilityIds.join(", ")}`);
+    if (scope === "project")
+        console.log(`Project:      ${projectRoot}`);
+    console.log(`Canonical:    ${canonicalDir}`);
+    const allowProjectCopies = opts.allowProjectCopies === true;
+    // Pass 1 — preview (dry run, writes nothing).
+    const preview = await runPlan(plan, { scope, projectRoot, canonicalDir, dryRun: true, allowProjectCopies });
+    const actions = collectActions(preview);
+    printPlan(preview, actions, opts.dryRun);
+    if (opts.dryRun) {
+        console.log("\n[dry-run] nothing was applied.");
+        return;
+    }
+    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;
+        }
+    }
+    // Pass 2 — apply file writes, record them in the install manifest, then run the actions.
+    // The config-guard hook denies tool writes to settings.json / hooks / CLAUDE.md without a
+    // marker; the installer opens its own window (never replacing or removing a user-set one)
+    // so an init driven from inside a Claude Code session is not blocked, and closes it after.
+    const closeWindow = openConfigWindow(configMarkerPath(scope, projectRoot, os.homedir()));
+    let results;
+    try {
+        results = await runPlan(plan, { scope, projectRoot, canonicalDir, dryRun: false, allowProjectCopies });
+    }
+    finally {
+        closeWindow();
+    }
+    const repo = sourceRepoRoot(canonicalDir);
+    // Only capabilities that emitted something are recorded: a refused global-only capability
+    // (project scope) leaves no trace in the project manifest.
+    const applied = plan.capabilityIds.filter((id) => results.some((r) => r.capabilityId === id && (r.written.length > 0 || r.actions.length > 0)));
+    const manifest = writeManifest({
+        version: cliVersion(),
+        sourceCommit: repo ? repoHead(repo) : undefined,
+        scope,
+        projectRoot,
+        targets,
+        capabilities: applied,
+        results,
+        actions: actions.map((a) => a.description),
+    });
+    console.log(`\nmanifest: ${manifest}`);
+    if (actions.length > 0)
+        await runActions(actions, new NodePackage());
+    console.log("\nApplied.");
+}
+/**
+ * Resolves the prefix budget: --budget, else FREEHARNESS_PREFIX_BUDGET, else the default.
+ * @param flag Parsed --budget value.
+ * @returns Budget in tokens.
+ */
+function prefixBudget(flag) {
+    if (flag !== undefined && Number.isFinite(flag) && flag > 0)
+        return flag;
+    const env = parseInt(process.env.FREEHARNESS_PREFIX_BUDGET ?? "", 10);
+    return Number.isFinite(env) && env > 0 ? env : DEFAULT_PREFIX_BUDGET;
+}
+/**
+ * Fails fast when canonical does not come from a FreeHarness repo checkout (npm/npx installs
+ * carry no vendored engine trees or PROVENANCE to compare).
+ * @param command Command name for the message.
+ */
+function requireCheckout(command) {
+    // The vendored trees sit three levels above canonical (packages/cli/canonical or
+    // canonical/ in a checkout or fixture); an npm install has nothing there.
+    const repo = path.resolve(resolveCanonicalDir(), "..", "..", "..");
+    if (["sdd", "memory"].some((t) => fs.existsSync(path.join(repo, "packages", t, "PROVENANCE.yaml"))))
+        return;
+    throw new Error(`${command} needs a FreeHarness repo checkout (this CLI runs from an npm package, not a checkout): git clone https://github.com/anegrelli/FreeHarness.git && ./install.sh, then run it from there.`);
+}
+/**
+ * Compares the manifest's recorded version/sourceCommit with the running CLI version
+ * and, when canonical comes from a repo checkout, with its HEAD.
+ * @param scope user | project.
+ * @param projectRoot Project root.
+ * @returns Report lines and whether something newer is available.
+ */
+function checkUpdate(scope, projectRoot) {
+    const file = manifestPath(scope, projectRoot);
+    const m = readManifest(file);
+    const running = cliVersion();
+    const repo = sourceRepoRoot(resolveCanonicalDir());
+    const head = repo ? repoHead(repo) : undefined;
+    if (!m)
+        return { lines: [`no install manifest at ${file} (nothing installed here yet, or installed before manifests existed): run init`], newer: false };
+    const cmp = compareSemver(m.version, running);
+    const lines = [];
+    let newer = false;
+    if (cmp < 0) {
+        lines.push(`newer available: ${m.version} -> ${running} (CLI)`);
+        newer = true;
+    }
+    else if (cmp > 0) {
+        lines.push(`WARN installed ${m.version} is newer than this CLI (${running}); upgrade the CLI before updating`);
+    }
+    else {
+        lines.push(`version ${running}: up to date`);
+    }
+    if (head) {
+        if (!m.sourceCommit)
+            lines.push(`source commit ${head} (manifest has none recorded; will be recorded on the next apply)`);
+        else if (m.sourceCommit !== head) {
+            lines.push(`newer available: source ${m.sourceCommit} -> ${head} (repo ${repo})`);
+            newer = true;
+        }
+        else
+            lines.push(`source commit ${head}: up to date`);
+    }
+    return { lines, newer };
+}
+/**
+ * Numeric semver comparison on major.minor.patch (pre-release tags ignored).
+ * @param a Left version.
+ * @param b Right version.
+ * @returns -1 when a < b, 1 when a > b, 0 when equal.
+ */
+function compareSemver(a, b) {
+    const pa = a.split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+    const pb = b.split(/[.-]/).map((n) => parseInt(n, 10) || 0);
+    for (let i = 0; i < 3; i++) {
+        if ((pa[i] ?? 0) < (pb[i] ?? 0))
+            return -1;
+        if ((pa[i] ?? 0) > (pb[i] ?? 0))
+            return 1;
+    }
+    return 0;
+}
+function installOptions(cmd) {
+    return cmd
+        .option("--target <list>", `comma-separated targets (${ALL_TARGETS.join(",")}); plugin = emit a Claude Code plugin dir under --project`, DEFAULT_TARGETS.join(","))
+        .option("--scope <scope>", "project | user (global ~/.claude)", "project")
+        .option("--only <list>", "comma-separated capability ids (default: required ones)")
+        .option("--project <dir>", "project root (project scope only)", process.cwd())
+        .option("--dry-run", "preview the plan and actions without applying anything", false)
+        .option("--yes", "apply without interactive confirmation", false)
+        .option("--allow-project-copies", "project scope: also copy the global-only capabilities (skills, agents, safety, cost, memory, mcp) into the project; they are otherwise refused with a note", false);
+}
+installOptions(program.command("init").description("Install FreeHarness capabilities into the target harness(es); --profile applies an opt-in profile instead (local-ollama, local-llamacpp, mcp; none removes them)"))
+    .option("--profile <name>", `opt-in profile (${PROFILES.map((p) => p.id).join(", ")}, ${PROFILE_NONE}); applies the profile only, never the capability plan`)
+    .option("--select <list>", "mcp profile: comma-separated server names to register without the prompt (empty = none)")
+    .action(async (opts) => {
+    if (opts.profile)
+        await applyProfile(opts);
+    else
+        await applyPlan(opts);
+});
+const plugin = program.command("plugin").description("Claude Code plugin helpers");
+plugin
+    .command("validate <dir>")
+    .description("Schema check of an emitted plugin dir (plugin.json fields, hooks.json shape and paths, .mcp.json, agent/skill front matter, sibling marketplace.json); exit 1 on errors. The `claude plugin validate` fallback for CI runners without the claude CLI")
+    .option("--strict", "warnings fail too", false)
+    .action((dir, opts) => {
+    const v = validatePluginDir(dir, { strict: opts.strict });
+    for (const l of formatValidation(path.resolve(dir), v, opts.strict))
+        console.log(l);
+    if (!v.ok)
+        process.exit(1);
+});
+installOptions(program.command("update").description("Detect a newer FreeHarness (CLI version / repo HEAD vs the install manifest) and re-emit installed capabilities (idempotent)"))
+    .option("--check", "report only: compare the manifest with the running CLI, apply nothing", false)
+    .action(async (opts) => {
+    const scope = parseScope(opts.scope);
+    const check = checkUpdate(scope, path.resolve(opts.project));
+    for (const l of check.lines)
+        console.log(`update: ${l}`);
+    if (opts.check)
+        return;
+    console.log(check.newer ? "\nRe-running the install from the newer source:" : "\nRe-emitting anyway (idempotent):");
+    await applyPlan(opts);
+});
+program
+    .command("uninstall")
+    .description("Remove what FreeHarness emitted into a scope (install manifest entries only); never claude-mem 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)
+    .option("--yes", "remove without interactive confirmation", false)
+    .action(async (opts) => {
+    const scope = parseScope(opts.scope);
+    const projectRoot = path.resolve(opts.project);
+    const preview = uninstallScope(scope, projectRoot, true);
+    if (!preview) {
+        console.log(`No install manifest at ${manifestPath(scope, projectRoot)} — nothing to uninstall (installs made before manifests existed must be removed by hand).`);
+        return;
+    }
+    const tag = opts.dryRun ? "[dry-run] " : "";
+    console.log(`${tag}uninstall (${scope}): manifest ${preview.manifest}`);
+    console.log(`${tag}remove (${preview.remove.length}):`);
+    for (const p of preview.remove)
+        console.log(`  rm: ${p}`);
+    for (const s of preview.settings)
+        console.log(`  edit: ${s} (remove FreeHarness hook entries only)`);
+    for (const k of preview.kept)
+        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.");
+    if (opts.dryRun) {
+        console.log("\n[dry-run] nothing was removed.");
+        return;
+    }
+    if (!opts.yes && !(await new ReadlinePrompt().confirm(`\nRemove ${preview.remove.length} file(s) and prune empty dirs?`))) {
+        console.log("Aborted; nothing was removed.");
+        return;
+    }
+    const done = uninstallScope(scope, projectRoot, false);
+    for (const d of done.prunedDirs)
+        console.log(`  pruned empty dir: ${d}`);
+    console.log(`\nRemoved ${done.remove.length} file(s).`);
+});
+program
+    .command("bootstrap")
+    .description("Activate FreeHarness in a project: CLAUDE.md (template, if absent) + /fh-context command + SDD (openspec/, /opsx, openspec-* skills). Skills, agents, hooks, memory and MCP stay global")
+    .option("--target <list>", "comma-separated harnesses", "claude-code")
+    .option("--project <dir>", "project root", process.cwd())
+    .option("--dry-run", "preview without applying", false)
+    .option("--yes", "apply without confirmation", false)
+    .action(async (opts) => {
+    // Project activation writes context + SDD only; everything else is installed once per
+    // machine (install.sh / init --scope user) and would be loaded twice from a project copy.
+    await applyPlan({ target: opts.target, scope: "project", only: "rules,sdd", project: opts.project, dryRun: opts.dryRun, yes: opts.yes });
+    console.log("note:  skills, agents, hooks, memory and MCP servers are global (~/.claude); nothing per project.");
+    if (!opts.dryRun)
+        console.log(`next:  open Claude Code in ${path.resolve(opts.project)} and run /fh-context to fill CLAUDE.md (never /init); commit CLAUDE.md + openspec/.`);
+});
+/**
+ * Whether a project CLAUDE.md still carries template placeholders (`<text with spaces>` or
+ * `<dir_name>`); HTML comments and the section tags are not placeholders.
+ * @param text File content.
+ * @returns True when at least one placeholder remains.
+ */
+export function hasPlaceholders(text) {
+    const body = text.replace(/<!--[\s\S]*?-->/g, "");
+    return /<(?:[A-Za-z0-9][^<>\n]*\s[^<>\n]*|dir_name)>/.test(body);
+}
+/**
+ * Prints a cleanup plan for the preview / dry-run.
+ * @param plan The plan.
+ * @param tag Line prefix ("[dry-run] " or "").
+ */
+function printCleanup(plan, tag) {
+    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)}`);
+    for (const n of plan.notes)
+        console.log(`  note:  ${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)")
+    .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)
+    .action(async (opts) => {
+    const scope = parseScope(opts.scope);
+    const projectRoot = path.resolve(opts.project);
+    const plan = await planCleanup(scope, projectRoot, { canonicalDir: resolveCanonicalDir() });
+    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 (!opts.dryRun) {
+            const pruned = pruneManifest(scope, projectRoot);
+            if (pruned > 0)
+                console.log(`  manifest: dropped ${pruned} entr${pruned === 1 ? "y" : "ies"} that no longer exist`);
+        }
+        return;
+    }
+    printCleanup(plan, tag);
+    if (opts.dryRun) {
+        console.log("\n[dry-run] nothing was removed.");
+        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.");
+        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).`);
+});
+program
+    .command("doctor")
+    .description("Check install state; --fix re-runs missing steps; --context-budget audits language density, prefix size and cache hygiene")
+    .option("--scope <scope>", "project | user", "project")
+    .option("--project <dir>", "project root (project scope only)", process.cwd())
+    .option("--fix", "re-run install to repair missing pieces", false)
+    .option("--context-budget", "language lint over canonical and emitted content (gerund preambles, Portuguese) + CLAUDE.md lines vs 200, hook/MCP counts, prefix estimate vs budget, cache TTLs, cache invalidators; reports, never blocks", false)
+    .option("--budget <tokens>", `prefix token budget for --context-budget (default ${DEFAULT_PREFIX_BUDGET} or FREEHARNESS_PREFIX_BUDGET)`, (v) => parseInt(v, 10))
+    .action(async (opts) => {
+    const scope = parseScope(opts.scope);
+    const base = scope === "user" ? path.join(os.homedir(), ".claude") : path.resolve(opts.project);
+    const claudeDir = scope === "user" ? base : path.join(base, ".claude");
+    const rulesFile = path.join(base, "CLAUDE.md");
+    const ok = (m) => console.log(`OK   ${m}`);
+    const warn = (m) => console.log(`WARN ${m}`);
+    // Which version is running, and which binaries the shell resolves — the first
+    // thing to check after upgrading over an older install.
+    const resolve = (tool) => {
+        const r = spawnSync("sh", ["-c", `command -v ${tool}`], { encoding: "utf8" });
+        return r.status === 0 ? r.stdout.trim() : "(not on PATH)";
+    };
+    const localBin = path.join(os.homedir(), ".local", "bin");
+    console.log(`freeharness ${program.version()}  running from ${process.argv[1]}`);
+    for (const l of runningFromLines(process.argv[1], os.homedir()))
+        console.log(l);
+    const fhPath = resolve("freeharness");
+    const osPath = resolve("openspec");
+    fhPath.startsWith(localBin) ? ok(`freeharness resolves to ${fhPath}`) : warn(`freeharness resolves to ${fhPath} — not ~/.local/bin; an older install may be shadowing the new one (open a new terminal, or 'npm unlink -g freeharness')`);
+    osPath.startsWith(localBin) ? ok(`openspec resolves to ${osPath} (vendored)`) : warn(`openspec resolves to ${osPath} — not the vendored bin in ~/.local/bin (a global @fission-ai/openspec may be shadowing it)`);
+    console.log(`Scope: ${scope} (${claudeDir})`);
+    try {
+        ok(`canonical resolved: ${resolveCanonicalDir()}`);
+    }
+    catch (e) {
+        warn(`canonical not found: ${e instanceof Error ? e.message : String(e)}`);
+    }
+    fs.existsSync(rulesFile) ? ok("CLAUDE.md present") : warn(scope === "user" ? "CLAUDE.md missing (run init)" : "CLAUDE.md missing (run freeharness bootstrap)");
+    if (opts.contextBudget) {
+        let canonical = null;
+        try {
+            canonical = resolveCanonicalDir();
+        }
+        catch {
+            canonical = null;
+        }
+        for (const l of contextBudgetLines(canonical, emittedProseRoots(scope, base)))
+            console.log(l);
+        for (const l of budgetLines({ home: os.homedir(), projectRoot: path.resolve(opts.project), budget: prefixBudget(opts.budget) }))
+            console.log(l);
+    }
+    if (scope === "project") {
+        // Project activation = context + SDD; everything else is global and is only reported
+        // here when a duplicate exists (see cleanup).
+        const opsx = path.join(claudeDir, "commands", "opsx");
+        fs.existsSync(opsx) ? ok(`/opsx commands present: ${fs.readdirSync(opsx).length}`) : warn("/opsx commands missing (run freeharness bootstrap)");
+        fs.existsSync(path.join(base, FH_CONTEXT_COMMAND)) ? ok("/fh-context command present") : warn("/fh-context command missing (run freeharness bootstrap)");
+        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);
+        if (fs.existsSync(rulesFile) && hasPlaceholders(fs.readFileSync(rulesFile, "utf8"))) {
+            warn("CLAUDE.md still has <placeholder> fields: run /fh-context in Claude Code");
+        }
+        const dup = await planCleanup("project", base, { canonicalDir: resolveCanonicalDir() });
+        for (const i of dup.items)
+            warn(`duplicate of the global install: ${describeItem(i)} — run freeharness cleanup --scope project`);
+        if (dup.items.length === 0)
+            ok("no project duplicates of the global install (agents, skills, hooks, legacy /openspec commands)");
+        for (const l of manifestLines(manifestPath(scope, base)))
+            console.log(l);
+        if (opts.fix) {
+            console.log("\n--fix: re-running bootstrap (claude-code) to repair missing pieces...");
+            await applyPlan({ target: "claude-code", scope, only: "rules,sdd", project: opts.project, dryRun: false, yes: false });
+        }
+        return;
+    }
+    const settingsPath = path.join(claudeDir, "settings.json");
+    if (fs.existsSync(settingsPath)) {
+        const raw = fs.readFileSync(settingsPath, "utf8");
+        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"])
+            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)`);
+        }
+        else {
+            warn("cost-tracker hook not found (the cost capability is part of the default set; run init --only cost)");
+        }
+        const hooksDir = path.join(claudeDir, "freeharness", "hooks");
+        const missingScripts = HOOK_SCRIPTS.filter((s) => raw.includes(s) && !fs.existsSync(path.join(hooksDir, s)));
+        for (const s of missingScripts)
+            warn(`hook registered but script missing: ${path.join(hooksDir, s)} (run update)`);
+        const conflicts = hookConflictLines(settingsPath, memoryPluginInstalled(claudeDir));
+        if (conflicts.length === 0)
+            ok("no hook conflicts in settings.json");
+        for (const l of conflicts)
+            console.log(l);
+        for (const l of hookScanLines(settingsPath, os.homedir()))
+            console.log(l);
+    }
+    else {
+        warn(`${settingsPath} not found (run init)`);
+    }
+    // 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);
+    try {
+        for (const l of mcpLines(os.homedir(), path.resolve(opts.project), mcpToolCounts(resolveCanonicalDir())))
+            console.log(l);
+    }
+    catch {
+        for (const l of mcpLines(os.homedir(), path.resolve(opts.project), {}))
+            console.log(l);
+    }
+    // Skill directories and agent .md files only: a .DS_Store never counts as content.
+    const counts = installedContentCounts(claudeDir);
+    counts.skills >= 0 ? ok(`skills installed: ${counts.skills}`) : warn("skills dir not found");
+    counts.agents >= 0 ? ok(`agents installed: ${counts.agents}`) : warn("agents dir not found");
+    // The user's own skills/agents next to ours: named so nobody mistakes them for leftovers.
+    try {
+        for (const l of foreignContentLines(claudeDir, resolveCanonicalDir(), scope, base))
+            console.log(l);
+    }
+    catch {
+        /* canonical unresolved: reported above */
+    }
+    const safetyFile = scope === "user" ? path.join(os.homedir(), ".claude", "freeharness", "safety.md") : path.join(base, ".freeharness", "safety.md");
+    fs.existsSync(safetyFile) ? ok("safety.md present") : warn("safety.md not found (run init)");
+    for (const l of manifestLines(manifestPath(scope, base)))
+        console.log(l);
+    for (const l of depLines(probeDeps()))
+        console.log(l);
+    console.log("Upstream (PROVENANCE baseline vs fork HEAD):");
+    try {
+        for (const l of baselineLines(resolveCanonicalDir()))
+            console.log(`  ${l}`);
+    }
+    catch (e) {
+        console.log(`  WARN ${e instanceof Error ? e.message : String(e)}`);
+    }
+    console.log("Memory (free-mem):");
+    const memory = await diagnoseMemory();
+    for (const line of memory.lines)
+        console.log(`  ${line}`);
+    const left = await planCleanup("user", base, { memory });
+    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)");
+    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 });
+    }
+});
+const memory = program.command("memory").description("Manage the free-mem install on this machine (ours vs upstream claude-mem)");
+memory
+    .command("status")
+    .description("Which memory plugin is active (free-mem vs upstream claude-mem): plugin cache versions, registered install, running worker, data dir")
+    .action(async () => {
+    for (const line of (await diagnoseMemory()).lines)
+        console.log(line);
+});
+memory
+    .command("restart")
+    .description("Restart the free-mem worker of the registered FreeHarness build (the observer-health and version-mismatch warnings point here); an armed quota cooldown is kept on purpose")
+    .option("--dry-run", "preview without changing anything", false)
+    .option("--if-running", "exit 0 quietly when no worker is listening (install.sh after a plugin upgrade); never starts one", false)
+    .action(async (opts) => {
+    const d = await diagnoseMemory();
+    if (opts.ifRunning && !d.worker.reachable) {
+        console.log(`OK   no worker on :${d.worker.port}; nothing to restart (the next SessionStart starts the registered plugin's worker)`);
+        return;
+    }
+    const r = await restartWorker(opts.dryRun, d);
+    console.log(`${opts.dryRun ? "[dry-run] " : ""}${r.method === "nothing" ? "WARN" : "OK  "} ${r.method}: ${r.detail}`);
+    if (r.method === "nothing")
+        process.exit(1);
+});
+memory
+    .command("backup")
+    .description("Copy the claude-mem data dir (SQLite + Chroma) 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")
+    .option("--dry-run", "preview without changing anything", false)
+    .option("--yes", "apply without confirmation", false)
+    .action(async (opts) => {
+    try {
+        const preview = await activateOurs(true);
+        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");
+        console.log("  register: installed_plugins.json -> the FreeHarness build");
+        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.");
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+});
+/**
+ * True when the command line carries both `--local` and `--no-local`.
+ *
+ * Args:
+ *   argv: The process argument vector.
+ *
+ * Returns:
+ *   True when the two contradictory flags are both present.
+ */
+function hasBothLocalFlags(argv) {
+    const tokens = argv.slice(2);
+    return tokens.some((t) => t === "--local" || t.startsWith("--local=")) && tokens.includes("--no-local");
+}
+memory
+    .command("settings")
+    .description("Preview or apply the FreeHarness-recommended observer settings (model tiers, skip list, concurrency) in the claude-mem 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")
+    .action(async (opts) => {
+    try {
+        // commander resolves --local and --no-local last-wins into one option value, so a
+        // contradictory line would silently write whichever came last; the raw argv is the
+        // only place both are still visible.
+        if (hasBothLocalFlags(process.argv)) {
+            console.error("FAIL --local and --no-local cannot be combined");
+            process.exit(1);
+        }
+        let observerOpts;
+        if (Array.isArray(opts.local)) {
+            if (opts.local.length !== 2) {
+                console.error("FAIL --local needs exactly two values: <base-url> <model>");
+                process.exit(1);
+            }
+            observerOpts = { local: { baseUrl: opts.local[0], model: opts.local[1] } };
+        }
+        else if (opts.local === false) {
+            observerOpts = { noLocal: true };
+        }
+        const settingsPath = path.join(dataDir(), "settings.json");
+        const preview = previewObserverSettings(settingsPath, observerOpts);
+        if (preview.parseError)
+            console.log(`WARN ${settingsPath} is not valid JSON: ${preview.parseError}`);
+        for (const row of preview.rows) {
+            console.log(`  ${row.key}: current=${row.current ?? "(absent)"} recommended=${row.recommended} — ${row.changed ? "would change" : "same"}`);
+        }
+        if (!opts.apply)
+            return;
+        if (!opts.yes && !(await new ReadlinePrompt().confirm("\nApply the recommended observer settings?"))) {
+            console.log("Aborted; nothing changed.");
+            return;
+        }
+        const result = applyObserverSettings(settingsPath, observerOpts);
+        console.log(`OK   ${result.created ? "created" : "updated"} ${settingsPath}${result.backupPath ? ` (backup: ${result.backupPath})` : ""}`);
+        console.log("restart the worker: freeharness memory restart");
+    }
+    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("--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("--agents", "per subagent name: model, dispatch count and tokens, from the cost log's by_agent maps", false)
+    .option("--json", "print the aggregated report as JSON", false)
+    .action((opts) => {
+    if (opts.days !== undefined && (!Number.isFinite(opts.days) || opts.days < 0)) {
+        console.error("--days must be a non-negative integer");
+        process.exit(1);
+    }
+    if (opts.by !== undefined && opts.by !== "task-class") {
+        console.error("--by accepts only task-class");
+        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.
+        const file = telemetryPath(opts.dir);
+        if (!fs.existsSync(file)) {
+            console.log(`no telemetry file at ${file}`);
+            return;
+        }
+        const records = readTelemetry(file);
+        const rows = changes(records);
+        if (opts.json)
+            console.log(JSON.stringify({ file, skipped: records.skipped, rows }, null, 2));
+        else
+            for (const l of formatChanges(rows, file, records.skipped))
+                console.log(l);
+        return;
+    }
+    if (opts.agents) {
+        const log = costLogPath();
+        const priceFile = costPricesPath();
+        const prices = loadPriceTable(priceFile);
+        const rows = agents(readUsage(log), prices);
+        if (rows.length === 0) {
+            console.log(`no by_agent data in ${log}`);
+            return;
+        }
+        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 }))
+                console.log(l);
+        return;
+    }
+    const log = costLogPath();
+    const records = readUsage(log);
+    if (opts.sinks) {
+        const report = sinks(records, { days: opts.days, project: opts.project, byTaskClass: opts.by === "task-class", top: opts.top }, log);
+        if (opts.json)
+            console.log(JSON.stringify(report, null, 2));
+        else
+            for (const l of formatSinks(report))
+                console.log(l);
+        return;
+    }
+    const report = aggregate(records, { days: opts.days, project: opts.project }, log);
+    if (opts.json)
+        console.log(JSON.stringify(report, null, 2));
+    else
+        for (const l of formatReport(report))
+            console.log(l);
+});
+cost
+    .command("prefix")
+    .description("Estimate the tokens the install puts in front of every request (global rules + project CLAUDE.md + agent and skill descriptions + MCP server names; words x 1.3) against a budget")
+    .option("--project <dir>", "project root whose CLAUDE.md and .mcp.json count", process.cwd())
+    .option("--budget <tokens>", `token budget (default ${DEFAULT_PREFIX_BUDGET} or FREEHARNESS_PREFIX_BUDGET)`, (v) => parseInt(v, 10))
+    .option("--json", "print the estimate as JSON", false)
+    .action((opts) => {
+    const home = os.homedir();
+    const claudeDir = path.join(home, ".claude");
+    const projectRoot = path.resolve(opts.project);
+    const est = estimatePrefix(claudeDir, [path.join(claudeDir, "CLAUDE.md"), path.join(projectRoot, "CLAUDE.md")], mcpServerNames(home, projectRoot), prefixBudget(opts.budget));
+    if (opts.json) {
+        console.log(JSON.stringify(est, null, 2));
+        return;
+    }
+    console.log(`prefix estimate: ~${est.tokens} tokens (budget ${est.budget}) ${est.ok ? "OK" : "FAIL"} — ${est.items.length} sources, words x 1.3`);
+    console.log("top contributors:");
+    for (const i of est.items.slice(0, 10))
+        console.log(`  ${String(i.tokens).padStart(6)} ${i.kind.padEnd(18)} ${i.source}`);
+    if (!est.ok)
+        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("prices")
+    .description("Print the price table path (USD per MTok per model; edit it to your contract)")
+    .action(() => {
+    const file = costPricesPath();
+    console.log(file);
+    console.log(fs.existsSync(file) ? "present — edit to your contract; `freeharness init --only cost` never overwrites it" : "not installed yet: run `freeharness init --scope user --only cost`");
+});
+const sync = program.command("sync").description("Track the vendored engines against upstream");
+sync
+    .command("check <target>")
+    .description("Report how a vendored tree (sdd | memory) differs from the upstream fork; never merges")
+    .action(async (target) => {
+    try {
+        requireCheckout("sync check");
+        const report = await new DiffSync(resolveCanonicalDir()).check(target);
+        console.log(`sync check: ${report.target}  (baseline ${report.baseline})`);
+        if (report.changedPaths.length === 0) {
+            console.log("OK   up to date with upstream (no vendored-path changes).");
+            return;
+        }
+        console.log(`Changed vs upstream (${report.changedPaths.length}):`);
+        for (const p of report.changedPaths) {
+            const flag = report.divergent[p] ? "DIVERGENT" : report.contractAffected.includes(p) ? "CONTRACT " : "         ";
+            console.log(`  ${flag}  ${p}${report.divergent[p] ? `  — ${report.divergent[p]}` : ""}`);
+        }
+        console.log("\nReview only — adopting a change updates the vendored files and bumps the PROVENANCE baseline (`freeharness sync adopt <target>`).");
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+});
+/**
+ * Two-pass adoption: pass 1 previews the tracked-path diffs (writes nothing), then
+ * (unless --dry-run) confirm and pass 2 copies upstream over vendored + bumps the baseline.
+ * @param target sdd | memory.
+ * @param opts CLI options.
+ */
+async function adoptUpstream(target, opts) {
+    requireCheckout("sync adopt");
+    const syncPort = new DiffSync(resolveCanonicalDir());
+    const paths = opts.path && opts.path.length > 0 ? opts.path : undefined;
+    const options = { paths, forceDivergent: opts.forceDivergent };
+    const preview = await syncPort.adopt(target, { ...options, dryRun: true });
+    const check = await syncPort.check(target);
+    console.log(`sync adopt: ${target}  (baseline ${preview.baselineBefore} -> ${preview.baselineAfter})`);
+    if (paths)
+        console.log(`Paths:        ${paths.join(", ")}`);
+    console.log("Scope:        tracked paths only (engine code is never adopted here: it is a manual, build-verified port).");
+    if (preview.baselineAfter !== preview.baselineBefore) {
+        console.log(`              upstream moved ${preview.baselineBefore}..${preview.baselineAfter}; engine drift in that range is NOT covered — see the upstream-radar report (Documents/UPSTREAM-RADAR.md).`);
+    }
+    for (const w of preview.warnings)
+        console.log(`WARN  ${w}`);
+    for (const label of preview.skippedDivergent) {
+        console.log(`\nDIVERGENT  ${label} — skipped (compare by hand): ${check.divergent[label] ?? "deliberately rewritten"}`);
+    }
+    if (preview.adopted.length === 0) {
+        console.log(preview.skippedDivergent.length > 0 ? "\nNothing adoptable: only DIVERGENT drift (use --force-divergent to override, with care)." : "\nOK   up to date with upstream on the tracked paths; nothing to adopt.");
+        return;
+    }
+    console.log(`\nWould adopt (${preview.adopted.length}):`);
+    for (const label of preview.adopted) {
+        const divergentReason = check.divergent[label];
+        const flag = divergentReason ? "DIVERGENT" : check.contractAffected.some((p) => p === label || p.startsWith(`${label}/`)) ? "CONTRACT " : "         ";
+        console.log(`  ${flag}  ${label}`);
+        if (divergentReason)
+            console.log(`  WARN  --force-divergent: overwriting a deliberately rewritten file (${divergentReason}); re-apply the memory-slim rewrite afterwards.`);
+    }
+    console.log("");
+    for (const p of preview.previews) {
+        console.log(`==== ${p.label}`);
+        process.stdout.write(p.diff);
+    }
+    if (opts.dryRun) {
+        console.log("\n[dry-run] nothing was written.");
+        return;
+    }
+    if (!opts.yes) {
+        const proceed = await new ReadlinePrompt().confirm(`\nCopy ${preview.adopted.length} tracked path(s) from upstream and bump the PROVENANCE baseline to ${preview.baselineAfter}?`);
+        if (!proceed) {
+            console.log("Aborted; nothing was written.");
+            return;
+        }
+    }
+    const done = await syncPort.adopt(target, { ...options, dryRun: false });
+    for (const w of done.warnings)
+        console.log(`WARN  ${w}`);
+    console.log(`\nAdopted: ${done.adopted.join(", ")}`);
+    console.log(`PROVENANCE baseline: ${done.baselineBefore} -> ${done.baselineAfter}`);
+    console.log(target === "sdd"
+        ? "Rebuild: `npm run build` (then `npm test`); also refresh baseline_commit in sources.yaml."
+        : "Rebuild: `bun run build:plugin` in packages/memory/vendor/claude-mem/engine, then `freeharness init --only memory`; also refresh baseline_commit in sources.yaml.");
+}
+sync
+    .command("adopt <target>")
+    .description("Adopt the upstream versions of the tracked paths (sdd | memory): preview -> confirm -> copy -> bump PROVENANCE baseline. Never touches engine code")
+    .option("--path <label>", "tracked entry label to adopt (repeatable); default: all tracked entries", (v, prev = []) => [...prev, v])
+    .option("--dry-run", "preview the diffs without writing anything", false)
+    .option("--yes", "adopt without interactive confirmation", false)
+    .option("--force-divergent", "also overwrite DIVERGENT entries (deliberately rewritten files) — loud warning", false)
+    .action(async (target, opts) => {
+    try {
+        await adoptUpstream(target, opts);
+    }
+    catch (e) {
+        console.error(e instanceof Error ? e.message : String(e));
+        process.exit(1);
+    }
+});
+program
+    .command("list")
+    .description("List capabilities and what is installed")
+    .action(() => {
+    for (const c of CAPABILITIES) {
+        const flag = c.optional ? "optional" : "required";
+        const delegate = c.delegatesTo ? ` (delegates: ${c.delegatesTo})` : "";
+        console.log(`- ${c.id} [${flag}] -> ${c.targets.join(",")}${delegate}`);
+        console.log(`    ${c.description}`);
+    }
+});
+program.parseAsync(process.argv).catch((err) => {
+    console.error(err instanceof Error ? err.message : String(err));
+    process.exit(1);
+});