freeharness 0.4.1

package/dist/adapters/content/language-lint.js

@@ -0,0 +1,191 @@
+// Language lint for model-facing prose (rules, skills, agents, commands, hook messages):
+// flags gerund preambles and Portuguese text so `doctor --context-budget` can report the
+// first violation per file. Advisory only: findings are lines, never an exit status.
+import fs from "node:fs";
+import path from "node:path";
+/** File extensions scanned as prose. */
+const PROSE_EXT = new Set([".md", ".txt", ".markdown"]);
+/** First-person progressive preambles and progressive openers at the start of a line. */
+const GERUND_PATTERNS = [
+    /\b(?:I|We)(?:'ll| will| would) be \w+ing\b/i,
+    /\b(?:I|We)(?:'m| am|'re| are) going to\b/i,
+    /\b(?:I|We)(?:'ll| will) (?:now |just )?\w+ing\b/i,
+    /\bLet me\b/,
+    /\bLet's (?:start|begin) by\b/i,
+    /^(?:Now|Currently|Still|First,?|Next,?) \w+ing\b/,
+    /^\w+ing (?:the|your|this|that|these|those|it|now|to)\b.*(?:\.\.\.|…)\s*$/,
+];
+/**
+ * Portuguese function words that rarely occur in English prose. Ambiguous tokens shared
+ * with English (`a`, `as`, `no`, `do`, `me`) are left out on purpose.
+ */
+const PT_STOPWORDS = new Set([
+    "que", "não", "nao", "para", "com", "uma", "um", "você", "voce", "está", "esta", "também", "tambem",
+    "mas", "por", "como", "mais", "dos", "das", "nos", "nas", "ou", "se", "ao", "à", "são", "sao", "foi",
+    "ser", "isso", "esse", "essa", "este", "pelo", "pela", "sobre", "quando", "onde", "então", "entao",
+    "porque", "já", "muito", "sem", "entre", "até", "ate", "seu", "sua", "seus", "suas", "ele", "ela",
+    "eles", "elas", "nós", "da", "de", "em", "na", "os", "o", "e", "é", "há", "deve", "devem", "pode",
+    "podem", "cada", "todo", "toda", "todos", "todas", "aqui", "depois", "antes", "ainda", "apenas",
+]);
+/** Minimum words on a line before the stopword ratio is measured. */
+const PT_MIN_WORDS = 6;
+/** Stopword share at which a line counts as Portuguese. */
+const PT_RATIO = 0.25;
+/**
+ * Removes inline code spans and double-quoted examples so rule text that quotes a banned
+ * phrase ("I will be doing") is not itself flagged.
+ * @param line Raw line.
+ * @returns Line with quoted material blanked.
+ */
+function stripQuoted(line) {
+    return line.replace(/`[^`]*`/g, " ").replace(/"[^"]*"/g, " ").replace(/“[^”]*”/g, " ");
+}
+/**
+ * Strips markdown list, heading and emphasis markers from the start of a line.
+ * @param line Raw line.
+ * @returns Text after the leading markup.
+ */
+function stripMarkup(line) {
+    return line.replace(/^\s*(?:[-*+]|\d+[.)]|#{1,6}|\|)\s*/, "").replace(/^\*\*?|\*\*?$/g, "").trim();
+}
+/**
+ * Whether the line reads as Portuguese by stopword share.
+ * @param text Line without quoted material.
+ * @returns True above the threshold on lines with enough words.
+ */
+function isPortuguese(text) {
+    const words = text.toLowerCase().match(/(?<![\p{L}\p{N}_])\p{L}+(?![\p{L}\p{N}_])/gu) ?? [];
+    if (words.length < PT_MIN_WORDS)
+        return false;
+    const hits = words.filter((w) => PT_STOPWORDS.has(w)).length;
+    return hits / words.length >= PT_RATIO;
+}
+/**
+ * Reads the `lang:` key of a YAML front-matter block at the top of the text.
+ * @param lines File lines.
+ * @returns The declared language, or null.
+ */
+function frontMatterLang(lines) {
+    if (lines[0]?.trim() !== "---")
+        return null;
+    for (let i = 1; i < lines.length; i += 1) {
+        if (lines[i].trim() === "---")
+            return null;
+        const m = /^lang:\s*["']?([\w-]+)/.exec(lines[i]);
+        if (m)
+            return m[1];
+    }
+    return null;
+}
+/**
+ * Lints one prose file.
+ *
+ * Skipped: YAML front matter, fenced code, blockquotes, and lines under a
+ * `<!-- lang: pt-BR -->` marker (until `<!-- lang: en -->`). A file whose front matter
+ * declares `lang: pt-BR` is skipped entirely.
+ * @param file Absolute path.
+ * @param text File contents (read from `file` when omitted).
+ * @returns Every finding in line order (the caller keeps the first).
+ */
+export function lintText(file, text) {
+    const body = text ?? fs.readFileSync(file, "utf8");
+    const lines = body.split("\n");
+    const declared = frontMatterLang(lines);
+    if (declared && /^pt/i.test(declared))
+        return [];
+    const out = [];
+    let inFrontMatter = lines[0]?.trim() === "---";
+    let inFence = false;
+    let inPt = false;
+    for (let i = inFrontMatter ? 1 : 0; i < lines.length; i += 1) {
+        const raw = lines[i];
+        const trimmed = raw.trim();
+        if (inFrontMatter) {
+            if (trimmed === "---")
+                inFrontMatter = false;
+            continue;
+        }
+        if (/^(?:```|~~~)/.test(trimmed)) {
+            inFence = !inFence;
+            continue;
+        }
+        if (inFence)
+            continue;
+        const marker = /<!--\s*lang:\s*([\w-]+)\s*-->/.exec(trimmed);
+        if (marker) {
+            inPt = /^pt/i.test(marker[1]);
+            continue;
+        }
+        if (inPt || trimmed.startsWith(">") || trimmed === "")
+            continue;
+        const text = stripMarkup(stripQuoted(raw));
+        if (text === "")
+            continue;
+        const gerund = GERUND_PATTERNS.find((p) => p.test(text));
+        if (gerund) {
+            out.push({ file, line: i + 1, pattern: `gerund-preamble (${gerund.exec(text)?.[0] ?? ""})`, text: trimmed });
+            continue;
+        }
+        if (isPortuguese(text))
+            out.push({ file, line: i + 1, pattern: "portuguese", text: trimmed });
+    }
+    return out;
+}
+/**
+ * Walks a directory for prose files.
+ * @param dir Root.
+ * @returns Absolute file paths, sorted.
+ */
+export function proseFiles(dir) {
+    const out = [];
+    if (!fs.existsSync(dir))
+        return out;
+    const walk = (d) => {
+        for (const e of fs.readdirSync(d, { withFileTypes: true })) {
+            if (e.name === "node_modules" || e.name.startsWith(".git"))
+                continue;
+            const p = path.join(d, e.name);
+            if (e.isDirectory())
+                walk(p);
+            else if (PROSE_EXT.has(path.extname(e.name)))
+                out.push(p);
+        }
+    };
+    walk(dir);
+    return out.sort();
+}
+/**
+ * Lints every prose file under the given roots (files or directories) and keeps the first
+ * finding per file.
+ * @param roots Files or directories to scan; missing paths are ignored.
+ * @returns Findings and the scanned-file count.
+ */
+export function lintPaths(roots) {
+    const files = new Set();
+    for (const r of roots) {
+        if (!fs.existsSync(r))
+            continue;
+        if (fs.statSync(r).isDirectory())
+            for (const f of proseFiles(r))
+                files.add(f);
+        else if (PROSE_EXT.has(path.extname(r)))
+            files.add(r);
+    }
+    const findings = [];
+    for (const f of [...files].sort()) {
+        const first = lintText(f)[0];
+        if (first)
+            findings.push(first);
+    }
+    return { findings, scanned: files.size };
+}
+/**
+ * Renders the language section of `doctor --context-budget`.
+ * @param report Result of {@link lintPaths}.
+ * @returns Printable lines: one OK line, or one FAIL line per flagged file.
+ */
+export function languageLines(report) {
+    if (report.findings.length === 0)
+        return [`OK   language: ${report.scanned} prose files, no gerund preamble or Portuguese outside declared pt-BR sections`];
+    return report.findings.map((f) => `FAIL language: ${f.file}:${f.line} ${f.pattern}: ${f.text.length > 100 ? `${f.text.slice(0, 97)}...` : f.text}`);
+}

package/dist/adapters/harness/claude-code.d.ts

@@ -0,0 +1,57 @@
+import type { Capability } from "@freeharness/core";
+import type { AdapterResult, InstallContext } from "@freeharness/core";
+import type { HarnessPort } from "@freeharness/core";
+export { ROUTING_FILE } from "../../infra/routing.js";
+/**
+ * Capabilities that live in the machine-global install (~/.claude). At project scope the
+ * adapter refuses them unless `allowProjectCopies` is set: Claude Code loads user and
+ * project dirs together, so a project copy shows every agent/skill/hook twice.
+ */
+export declare const GLOBAL_ONLY_CAPABILITIES: readonly string[];
+/** Project slash command written by `bootstrap` (rules, project scope): fills the CLAUDE.md placeholders. */
+export declare const FH_CONTEXT_COMMAND: string;
+/** SessionStart matcher: compact/resume/fork get the re-orientation block, startup/clear the pointer. */
+export declare const SESSION_START_MATCHER = "startup|clear|compact|resume|fork";
+/** Flags baked into the hook commands (the fragment defaults; edit settings.json to tune). */
+export declare const OUTPUT_PRUNER_FLAGS = "--max-bytes 8192 --max-lines 200";
+export declare const CONTEXT_MONITOR_FLAGS = "--budget 200000 --thresholds 60,85";
+export declare const CONFIG_GUARD_FLAGS = "--ttl 30";
+export declare const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500";
+/**
+ * Per-hook timeout (seconds) on SessionEnd entries. Claude Code gives SessionEnd hooks a
+ * shared 1.5 s budget by default and raises it to the highest `timeout` set in a settings
+ * file (up to 60 s); the cost tracker reads the whole transcript, which a long session
+ * pushes past 1.5 s.
+ */
+export declare const SESSION_END_TIMEOUT_S = 10;
+/** Every hook script FreeHarness emits (rules + safety + cost capabilities), for doctor and uninstall. */
+export declare const HOOK_SCRIPTS: readonly string[];
+export declare class ClaudeCodeAdapter implements HarnessPort {
+    readonly target: "claude-code";
+    apply(cap: Capability, ctx: InstallContext): Promise<AdapterResult>;
+}
+/**
+ * Reports and, only once confirmed, strips a trailing `[1m]` suffix from the scope's own
+ * `model` value. The emitted defaults never force or replace a model family: a value with no
+ * suffix, or a bracketed suffix other than `1m` (case-insensitive), is left untouched. A `[1m]`
+ * value is named in pass 1 (`dry`) as what a confirmed pass 2 would write (the same id, suffix
+ * removed); the rewrite itself happens only in pass 2.
+ * @param settingsPath The scope's settings.json.
+ * @param dry Dry run (pass 1: report only).
+ * @param res Adapter result to report into.
+ */
+export declare function reportAndStripLongContextModel(settingsPath: string, dry: boolean, res: AdapterResult): void;
+/**
+ * Creates the `.freeharness/sdd/` workspace and seeds the project `.gitignore` at project
+ * scope: the transient SDD workspace line and the two agent-memory tree lines
+ * (`.claude/agent-memory/`, `.claude/agent-memory-local/`). `.claude/` is tracked in a
+ * FreeHarness-activated project, so an agent's `MEMORY.md` (written by Claude Code under
+ * `memory: project` / `memory: local`) would otherwise become a committed, attacker-supplied
+ * instruction channel injected into that agent's next prompt. `.gitignore` is never ours to
+ * remove. The durable evidence is `.freeharness/telemetry.jsonl`, appended by the cost-tracker
+ * hook at session end; nothing else is seeded or read here.
+ * @param projectRoot Project root.
+ * @param dry Dry run.
+ * @param res Adapter result to report into.
+ */
+export declare function seedProjectEvidence(projectRoot: string, dry: boolean, res: AdapterResult): void;

package/dist/adapters/harness/claude-code.js

@@ -0,0 +1,385 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+import { copyDir, copyExecutable, ensureDir, mergeClaudeHook, mergeSettingsKeys, readText, writeText, writeTextIfAbsent } from "../../infra/fsutil.js";
+import { AGENT_MEMORY_GITIGNORE_LINE, AGENT_MEMORY_LOCAL_GITIGNORE_LINE, SDD_DIR, SDD_GITIGNORE_LINE, ensureGitignoreLine, ensureSddDir, } from "../../infra/dogfood.js";
+import { rewriteAgentModel } from "@freeharness/core";
+import { initProject } from "@freeharness/sdd/init";
+import { VendoredMemory, vendoredMemoryEngineDir } from "../memory/vendored.js";
+import { vendoredSddBin } from "../../infra/paths.js";
+import { ROUTING_FILE, routingSourcePath } from "../../infra/routing.js";
+// Re-exported: callers keep importing the routing file name from the claude-code adapter.
+export { ROUTING_FILE } from "../../infra/routing.js";
+/**
+ * Capabilities that live in the machine-global install (~/.claude). At project scope the
+ * adapter refuses them unless `allowProjectCopies` is set: Claude Code loads user and
+ * project dirs together, so a project copy shows every agent/skill/hook twice.
+ */
+export const GLOBAL_ONLY_CAPABILITIES = ["skills", "agents", "safety", "cost", "memory", "mcp"];
+/** Project slash command written by `bootstrap` (rules, project scope): fills the CLAUDE.md placeholders. */
+export const FH_CONTEXT_COMMAND = path.join(".claude", "commands", "fh-context.md");
+/** SessionStart matcher: compact/resume/fork get the re-orientation block, startup/clear the pointer. */
+export const SESSION_START_MATCHER = "startup|clear|compact|resume|fork";
+/** Flags baked into the hook commands (the fragment defaults; edit settings.json to tune). */
+export const OUTPUT_PRUNER_FLAGS = "--max-bytes 8192 --max-lines 200";
+export const CONTEXT_MONITOR_FLAGS = "--budget 200000 --thresholds 60,85";
+export const CONFIG_GUARD_FLAGS = "--ttl 30";
+export const REPEAT_TOOL_FLAGS = "--thresholds 3,5,8 --preview-chars 500";
+/**
+ * Per-hook timeout (seconds) on SessionEnd entries. Claude Code gives SessionEnd hooks a
+ * shared 1.5 s budget by default and raises it to the highest `timeout` set in a settings
+ * file (up to 60 s); the cost tracker reads the whole transcript, which a long session
+ * pushes past 1.5 s.
+ */
+export const SESSION_END_TIMEOUT_S = 10;
+/** Every hook script FreeHarness emits (rules + safety + cost capabilities), for doctor and uninstall. */
+export const HOOK_SCRIPTS = [
+    "freeharness-session-start",
+    "freeharness-memory-guard.mjs",
+    "freeharness-config-guard.mjs",
+    "freeharness-repeat-tool.mjs",
+    "freeharness-security-guidance.mjs",
+    "freeharness-cost-tracker.mjs",
+    "freeharness-output-pruner.mjs",
+    "freeharness-context-monitor.mjs",
+    "freeharness-precompact.mjs",
+    "freeharness-auto-memory.mjs",
+    "freeharness-converge.mjs",
+];
+export class ClaudeCodeAdapter {
+    target = "claude-code";
+    async apply(cap, ctx) {
+        const res = { capabilityId: cap.id, target: this.target, written: [], actions: [], notes: [] };
+        const C = ctx.canonicalDir;
+        const dry = ctx.dryRun;
+        const user = ctx.scope === "user";
+        const home = os.homedir();
+        // Hooks (and every global-only capability) are emitted at user scope, or into a project
+        // only on explicit request. A plain project install writes context + SDD, nothing else.
+        const projectCopies = user || ctx.allowProjectCopies === true;
+        if (!projectCopies && GLOBAL_ONLY_CAPABILITIES.includes(cap.id)) {
+            res.notes.push(`'${cap.id}' is a global capability; installed by install.sh / \`freeharness init --scope user\` (a project copy would be loaded twice). Pass --allow-project-copies to init to force a project copy.`);
+            return res;
+        }
+        const claudeDir = user ? path.join(home, ".claude") : path.join(ctx.projectRoot, ".claude");
+        const rulesFile = user ? path.join(home, ".claude", "CLAUDE.md") : path.join(ctx.projectRoot, "CLAUDE.md");
+        const skillsDir = path.join(claudeDir, "skills");
+        const agentsDir = path.join(claudeDir, "agents");
+        const settingsPath = path.join(claudeDir, "settings.json");
+        const hooksDir = user
+            ? path.join(home, ".claude", "freeharness", "hooks")
+            : path.join(ctx.projectRoot, ".freeharness", "hooks");
+        const safetyFile = user
+            ? path.join(home, ".claude", "freeharness", "safety.md")
+            : path.join(ctx.projectRoot, ".freeharness", "safety.md");
+        const ssScript = path.join(hooksDir, "freeharness-session-start");
+        const mgScript = path.join(hooksDir, "freeharness-memory-guard.mjs");
+        // user scope bakes an absolute path; project scope uses ${CLAUDE_PROJECT_DIR}.
+        const ssCmd = user ? `"${ssScript}"` : '"${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-session-start"';
+        const mgCmd = user
+            ? `node "${mgScript}"`
+            : 'node "${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-memory-guard.mjs"';
+        const sgScript = path.join(hooksDir, "freeharness-security-guidance.mjs");
+        const sgCmd = user
+            ? `node "${sgScript}"`
+            : 'node "${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-security-guidance.mjs"';
+        const ctScript = path.join(hooksDir, "freeharness-cost-tracker.mjs");
+        const ctPrices = path.join(hooksDir, "cost-prices.json");
+        const ctCmd = user
+            ? `node "${ctScript}"`
+            : 'node "${CLAUDE_PROJECT_DIR}/.freeharness/hooks/freeharness-cost-tracker.mjs"';
+        const hookCmd = (script, flags) => `${user ? `node "${path.join(hooksDir, script)}"` : `node "\${CLAUDE_PROJECT_DIR}/.freeharness/hooks/${script}"`}${flags ? ` ${flags}` : ""}`;
+        const emitHook = (script, flags, events, note) => {
+            res.written.push(writeText(path.join(hooksDir, script), readText(path.join(C, "hooks", script)), dry));
+            const cmd = hookCmd(script, flags);
+            let added = false;
+            for (const e of events) {
+                const entry = { ...(e.matcher ? { matcher: e.matcher } : {}), hooks: [{ type: "command", command: cmd, ...(e.event === "SessionEnd" ? { timeout: SESSION_END_TIMEOUT_S } : {}) }] };
+                added = mergeClaudeHook(settingsPath, e.event, entry, dry).added || added;
+            }
+            res.notes.push(added ? `Added ${note}.` : `${script} hook already present.`);
+        };
+        switch (cap.id) {
+            case "rules": {
+                if (user) {
+                    res.written.push(writeText(rulesFile, readText(path.join(C, "rules", "CLAUDE.md")), dry));
+                    const tpl = path.join(home, ".claude", "freeharness", "project-CLAUDE.template.md");
+                    res.written.push(writeText(tpl, readText(path.join(C, "rules", "project-CLAUDE.template.md")), dry));
+                    res.notes.push("Project CLAUDE.md template shipped to ~/.claude/freeharness/ for /init and per-project scaffolding.");
+                }
+                else {
+                    // Project scope seeds CONTEXT (the template), never the global rules, and
+                    // never clobbers an existing file. Behavior comes from --scope user.
+                    const seeded = writeTextIfAbsent(rulesFile, readText(path.join(C, "rules", "project-CLAUDE.template.md")), dry);
+                    res.written.push(seeded.path);
+                    if (seeded.skipped)
+                        (res.skipped ??= []).push(seeded.path);
+                    res.notes.push(seeded.skipped
+                        ? "Project CLAUDE.md already exists; left untouched. Behavior rules come from --scope user."
+                        : "Seeded project CLAUDE.md from the FreeHarness template; fill in project context. Behavior rules come from --scope user.");
+                    res.written.push(writeText(path.join(ctx.projectRoot, FH_CONTEXT_COMMAND), readText(path.join(C, "commands", "fh-context.md")), dry));
+                    res.notes.push("Wrote .claude/commands/fh-context.md: run /fh-context in Claude Code to fill the CLAUDE.md placeholders (never /init).");
+                    seedProjectEvidence(ctx.projectRoot, dry, res);
+                    if (!projectCopies) {
+                        res.notes.push("Hooks are global (~/.claude/settings.json); none merged into the project settings.json.");
+                        break;
+                    }
+                }
+                res.written.push(copyExecutable(path.join(C, "hooks", "freeharness-session-start"), ssScript, dry));
+                const ssEntry = { matcher: SESSION_START_MATCHER, hooks: [{ type: "command", command: ssCmd, async: false }] };
+                const ss = mergeClaudeHook(settingsPath, "SessionStart", ssEntry, dry);
+                res.notes.push(ss.added ? "Added SessionStart pointer hook (additive; claude-mem untouched; compact/resume re-inject the checkpoint)." : "SessionStart hook already present.");
+                // Routing table beside the script the hook reads it from.
+                res.written.push(writeText(path.join(hooksDir, ROUTING_FILE), readText(routingSourcePath(C)), dry));
+                res.written.push(writeText(mgScript, readText(path.join(C, "hooks", "freeharness-memory-guard.mjs")), dry));
+                const mgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: mgCmd }] };
+                const mg = mergeClaudeHook(settingsPath, "PreToolUse", mgEntry, dry);
+                res.notes.push(mg.added ? "Added memory-guard hook (PreToolUse denies memory .md writes; saves tokens)." : "Memory-guard hook already present.");
+                emitHook("freeharness-config-guard.mjs", CONFIG_GUARD_FLAGS, [{ event: "PreToolUse", matcher: "Edit|Write|MultiEdit|Bash" }], "config-guard hook (PreToolUse denies settings/.mcp.json/hook/CLAUDE.md writes without .freeharness/allow-config-edit)");
+                emitHook("freeharness-repeat-tool.mjs", REPEAT_TOOL_FLAGS, [{ event: "PreToolUse" }, { event: "UserPromptSubmit" }], "repeat-tool hook (PreToolUse reminds at 3/5/8 identical calls; UserPromptSubmit resets; advisory)");
+                // Memory-independent: the skeleton is built locally; the worker summary is best effort.
+                emitHook("freeharness-precompact.mjs", "", [{ event: "PreCompact" }], "precompact hook (PreCompact writes the checkpoint skeleton + file-op list for SessionStart and asks a running claude-mem worker for a summary; worker down = skipped)");
+                break;
+            }
+            case "skills": {
+                res.written.push(...copyDir(path.join(C, "skills"), skillsDir, dry, {
+                    transform: (c) => rewriteAgentModel(c, this.target),
+                    transformOnly: (n) => n === "SKILL.md",
+                }));
+                const rfScripts = path.join(skillsDir, "report-formatting", "scripts");
+                res.actions.push({
+                    description: "Install report-formatting .docx deps (docx, image-size)",
+                    command: "npm install --no-audit --no-fund",
+                    cwd: rfScripts,
+                    optional: true,
+                });
+                res.actions.push({
+                    description: "Install report-formatting .pptx deps (python-pptx, lxml, Pillow, defusedxml)",
+                    command: "python3 -m pip install -r pptx/requirements.txt --break-system-packages",
+                    cwd: rfScripts,
+                    optional: true,
+                });
+                break;
+            }
+            case "agents":
+                res.written.push(...copyDir(path.join(C, "agents"), agentsDir, dry, {
+                    skip: (n) => n === "README.md",
+                    transform: (c) => rewriteAgentModel(c, this.target),
+                }));
+                break;
+            case "safety": {
+                res.written.push(writeText(safetyFile, readText(path.join(C, "rules", "safety.md")), dry));
+                // Advisory PreToolUse hook: warns on vulnerability sinks in Edit/Write content,
+                // never blocks. Same additive merge as the memory guard.
+                res.written.push(writeText(sgScript, readText(path.join(C, "hooks", "freeharness-security-guidance.mjs")), dry));
+                const sgEntry = { matcher: "Write|Edit|MultiEdit", hooks: [{ type: "command", command: sgCmd }] };
+                const sg = mergeClaudeHook(settingsPath, "PreToolUse", sgEntry, dry);
+                res.notes.push(sg.added ? "Added security-guidance hook (PreToolUse warns on vulnerability sinks; advisory only)." : "Security-guidance hook already present.");
+                break;
+            }
+            case "sdd": {
+                const src = path.join(C, "openspec");
+                const dest = path.join(home, ".local", "share", "openspec", "schemas", "spec-driven");
+                res.actions.push({
+                    description: "Install spec-driven schema override (user-global)",
+                    command: `mkdir -p "${dest}/templates" && cp "${src}/schema.spec-driven.yaml" "${dest}/schema.yaml" && cp -R "${src}/templates/." "${dest}/templates/"`,
+                });
+                // packages/cli/canonical -> ../../sdd = packages/sdd; the workspace root is two
+                // levels above it. Build through the root workspaces (npm -w) so hoisted deps resolve.
+                const sddDir = path.join(C, "..", "..", "sdd");
+                const workspaceRoot = path.join(sddDir, "..", "..");
+                if (fs.existsSync(path.join(sddDir, "package.json"))) {
+                    const sddBin = path.join(sddDir, "dist", "src", "bin", "openspec.js");
+                    res.actions.push({
+                        description: "Expose the vendored `openspec` on PATH via ~/.local/bin (shadows the system openspec; ensure ~/.local/bin is on PATH)",
+                        command: `npm install --no-audit --no-fund -w @freeharness/sdd && npm run build -w @freeharness/sdd && chmod +x "${sddBin}" && mkdir -p "$HOME/.local/bin" && ln -sf "${sddBin}" "$HOME/.local/bin/openspec"`,
+                        cwd: workspaceRoot,
+                        optional: true,
+                    });
+                }
+                else if (vendoredSddBin()) {
+                    // npm/npx install: the sdd package is bundled and already built; link its bin.
+                    const sddBin = vendoredSddBin();
+                    res.actions.push({
+                        description: "Expose the bundled `openspec` on PATH via ~/.local/bin (shadows the system openspec; ensure ~/.local/bin is on PATH)",
+                        command: `chmod +x "${sddBin}" && mkdir -p "$HOME/.local/bin" && ln -sf "${sddBin}" "$HOME/.local/bin/openspec"`,
+                        optional: true,
+                    });
+                }
+                else {
+                    res.notes.push("Vendored @freeharness/sdd not resolvable; expose the vendored openspec bin manually.");
+                }
+                if (user) {
+                    // Converge loop: the Stop hook is global; a project arms it by writing
+                    // .freeharness/converge.json. Off everywhere else (no file = no-op).
+                    emitHook("freeharness-converge.mjs", "", [{ event: "Stop" }], "converge hook (Stop blocks with the next unchecked task + Verify line while <project>/.freeharness/converge.json exists and rounds < max_rounds; off without the file)");
+                    res.notes.push("SDD is project-scoped: run `freeharness bootstrap` inside each project.");
+                }
+                else if (dry) {
+                    res.notes.push("Would initialize OpenSpec (/opsx commands + skills + openspec/) via the vendored engine.");
+                }
+                else {
+                    const r = await initProject({ target: "claude", projectDir: ctx.projectRoot });
+                    res.written.push(...r.written);
+                    res.notes.push(...r.notes);
+                }
+                break;
+            }
+            case "memory": {
+                // Optional tier-0 spike, off by default (FREEHARNESS_AUTO_MEMORY=on); registered even
+                // when the vendored engine is absent because it only reads the dogfood log.
+                emitHook("freeharness-auto-memory.mjs", "", [{ event: "SessionEnd" }], "auto-memory hook (SessionEnd curates one line per project into ~/.claude/freeharness/MEMORY.md; OFF until FREEHARNESS_AUTO_MEMORY=on)");
+                const engineDir = vendoredMemoryEngineDir(C);
+                if (!engineDir) {
+                    // --bridge fallback: vendored engine absent; upstream installer does the rest.
+                    res.actions.push({ description: "Install claude-mem plugin + wire hooks/MCP (bridge: vendored engine absent)", command: "npx claude-mem install", optional: true });
+                    res.notes.push("Vendored engine not found; bridging to upstream `npx claude-mem install`.");
+                    break;
+                }
+                // Real plugin install from OUR build (MemoryPort). Dry-run previews every step
+                // and writes nothing; the apply pass builds, stages, and registers the plugin.
+                const mem = new VendoredMemory(engineDir, this.target);
+                const merge = (r) => {
+                    res.written.push(...r.written);
+                    res.actions.push(...r.actions);
+                    res.notes.push(...r.notes);
+                };
+                const pre = await mem.ensurePrerequisites(ctx);
+                merge(pre);
+                if (pre.notes.some((n) => n.startsWith("MISSING: Bun"))) {
+                    res.notes.push("memory: install blocked until Bun is present.");
+                    break;
+                }
+                merge(await mem.migrateExisting(ctx));
+                merge(await mem.install(ctx.scope, ctx));
+                merge(await mem.registerHooks(ctx.scope, ctx));
+                res.notes.push("Worker start + recall are verified on the machine (needs the Claude Agent SDK key / network); not exercised by the installer.");
+                break;
+            }
+            case "mcp": {
+                const cfg = JSON.parse(readText(path.join(C, "mcp", "servers.json")));
+                const sc = user ? "user" : "local";
+                for (const s of cfg.servers) {
+                    if (!s.targets.includes("claude-code"))
+                        continue;
+                    res.actions.push({
+                        description: `Register MCP server ${s.name}${s.optional ? " (optional)" : ""}`,
+                        command: `claude mcp add ${s.name} -s ${sc} -- ${s.command} ${s.args.join(" ")}`,
+                        optional: true, // a failing/missing `claude` must not abort the whole install
+                    });
+                }
+                break;
+            }
+            case "cost": {
+                // Stop + SessionEnd append usage snapshots to cost/usage.jsonl; the price table is
+                // seeded once and never overwritten (the user edits it to the account's contract).
+                res.written.push(writeText(ctScript, readText(path.join(C, "hooks", "freeharness-cost-tracker.mjs")), dry));
+                const prices = writeTextIfAbsent(ctPrices, readText(path.join(C, "hooks", "cost-prices.json")), dry);
+                res.written.push(prices.path);
+                if (prices.skipped)
+                    (res.skipped ??= []).push(prices.path);
+                const stop = mergeClaudeHook(settingsPath, "Stop", { hooks: [{ type: "command", command: ctCmd }] }, dry);
+                const end = mergeClaudeHook(settingsPath, "SessionEnd", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, dry);
+                // SubagentStop mirrors SessionEnd: a long dispatch also pushes the subagent's own
+                // transcript past the default budget.
+                const subagentStop = mergeClaudeHook(settingsPath, "SubagentStop", { hooks: [{ type: "command", command: ctCmd, timeout: SESSION_END_TIMEOUT_S }] }, dry);
+                res.notes.push(stop.added || end.added || subagentStop.added ? "Added cost-tracker hooks (Stop + SessionEnd + SubagentStop append usage/ledger entries; never block)." : "Cost-tracker hooks already present.");
+                res.notes.push(prices.skipped ? `Price table kept as is: ${ctPrices} (edit to your contract).` : `Price table seeded at ${ctPrices} — placeholders; edit to your contract. Report: freeharness cost report.`);
+                emitHook("freeharness-output-pruner.mjs", OUTPUT_PRUNER_FLAGS, [{ event: "PostToolUse", matcher: "Bash" }], "output-pruner hook (PostToolUse trims Bash output over 8 KB / 200 lines; full copy under ~/.claude/freeharness/tool-output/)");
+                emitHook("freeharness-context-monitor.mjs", CONTEXT_MONITOR_FLAGS, [{ event: "Stop" }], "context-monitor hook (Stop warns the user once at 60% and 85% of the context budget)");
+                // Cache-hygiene settings: additive, existing keys win.
+                const tpl = JSON.parse(readText(path.join(C, "settings", "settings.cache-hygiene.claude-code.json")));
+                const merged = mergeSettingsKeys(settingsPath, tpl, dry);
+                res.notes.push(merged.added.length > 0
+                    ? `Added cache-hygiene settings ${merged.added.join(", ")} = 1h${merged.kept.length > 0 ? ` (kept existing ${merged.kept.join(", ")})` : ""}; CLAUDE_AUTOCOMPACT_PCT_OVERRIDE stays optional (see the template comment).`
+                    : `Cache-hygiene settings already present (${merged.kept.join(", ")}); left as they are.`);
+                reportAndStripLongContextModel(settingsPath, dry, res);
+                break;
+            }
+            default:
+                res.notes.push(`No claude-code action for capability '${cap.id}'.`);
+        }
+        return res;
+    }
+}
+/**
+ * Splits a model id on a trailing `[suffix]` tag (e.g. `claude-fable-5-1[1m]`). Mirrors
+ * `splitModelSuffix` in `../../cli/doctor.js`, duplicated here rather than shared: adapters
+ * never import the cli layer (`scripts/check-arch.mjs`).
+ * @param model Model id as recorded in settings.json.
+ * @returns Base id and suffix (null when the id carries none).
+ */
+function splitModelSuffix(model) {
+    const m = /^(.*)\[([^[\]]+)\]$/.exec(model);
+    return m ? { base: m[1], suffix: m[2] } : { base: model, suffix: null };
+}
+/**
+ * Reports and, only once confirmed, strips a trailing `[1m]` suffix from the scope's own
+ * `model` value. The emitted defaults never force or replace a model family: a value with no
+ * suffix, or a bracketed suffix other than `1m` (case-insensitive), is left untouched. A `[1m]`
+ * value is named in pass 1 (`dry`) as what a confirmed pass 2 would write (the same id, suffix
+ * removed); the rewrite itself happens only in pass 2.
+ * @param settingsPath The scope's settings.json.
+ * @param dry Dry run (pass 1: report only).
+ * @param res Adapter result to report into.
+ */
+export function reportAndStripLongContextModel(settingsPath, dry, res) {
+    let current = {};
+    if (fs.existsSync(settingsPath)) {
+        try {
+            current = JSON.parse(fs.readFileSync(settingsPath, "utf8"));
+        }
+        catch (e) {
+            res.notes.push(`settings.json not parsed (${settingsPath}): ${e instanceof Error ? e.message : String(e)}; model-suffix check skipped.`);
+            return;
+        }
+    }
+    const currentModel = typeof current.model === "string" ? current.model : undefined;
+    if (currentModel === undefined)
+        return;
+    const { base, suffix } = splitModelSuffix(currentModel);
+    if (suffix?.toLowerCase() !== "1m")
+        return;
+    res.notes.push(`model: ${currentModel} (would become ${base})`);
+    if (dry)
+        return;
+    current.model = base;
+    ensureDir(path.dirname(settingsPath), false);
+    fs.writeFileSync(settingsPath, JSON.stringify(current, null, 2), "utf8");
+    res.notes.push(`Rewrote model = ${base} in ${settingsPath} (stripped the ${suffix} suffix).`);
+}
+/**
+ * Creates the `.freeharness/sdd/` workspace and seeds the project `.gitignore` at project
+ * scope: the transient SDD workspace line and the two agent-memory tree lines
+ * (`.claude/agent-memory/`, `.claude/agent-memory-local/`). `.claude/` is tracked in a
+ * FreeHarness-activated project, so an agent's `MEMORY.md` (written by Claude Code under
+ * `memory: project` / `memory: local`) would otherwise become a committed, attacker-supplied
+ * instruction channel injected into that agent's next prompt. `.gitignore` is never ours to
+ * remove. The durable evidence is `.freeharness/telemetry.jsonl`, appended by the cost-tracker
+ * hook at session end; nothing else is seeded or read here.
+ * @param projectRoot Project root.
+ * @param dry Dry run.
+ * @param res Adapter result to report into.
+ */
+export function seedProjectEvidence(projectRoot, dry, res) {
+    const sdd = ensureSddDir(projectRoot, dry);
+    if (sdd.created)
+        res.notes.push(`Created ${SDD_DIR}/ (subagent-driven-development briefs and review packages).`);
+    const gitignoreLines = [
+        { line: SDD_GITIGNORE_LINE, reason: "briefs and review packages are transient" },
+        { line: AGENT_MEMORY_GITIGNORE_LINE, reason: "agent memory is never a committed, attacker-supplied input" },
+        { line: AGENT_MEMORY_LOCAL_GITIGNORE_LINE, reason: "agent memory is never a committed, attacker-supplied input" },
+    ];
+    for (const { line, reason } of gitignoreLines) {
+        const gi = ensureGitignoreLine(projectRoot, line, dry);
+        if (gi.added) {
+            res.written.push(gi.path);
+            (res.skipped ??= []).push(gi.path);
+            res.notes.push(`Added \`${line}\` to .gitignore (${reason}).`);
+        }
+        else {
+            res.notes.push(`.gitignore already lists \`${line}\`.`);
+        }
+    }
+    res.notes.push("telemetry lands in .freeharness/telemetry.jsonl (written by the cost tracker at session end; commit it when you want it as evidence).");
+}

package/dist/adapters/harness/index.d.ts

@@ -0,0 +1,3 @@
+import type { HarnessTarget } from "@freeharness/core";
+import type { HarnessPort } from "@freeharness/core";
+export declare function getAdapter(target: HarnessTarget): HarnessPort;