@davesheffer/hunch 1.23.2 → 1.24.0

package/README.md

@@ -46,7 +46,55 @@ Reload your coding assistant, then ask a normal question:
 
 `hunch init` indexes the repository, installs local lifecycle hooks, and connects supported
 assistants without replacing their existing configuration. The next session receives the relevant
-story with its sources, not a giant transcript or a generic prompt wall.
+story with its sources, not a giant transcript or a generic prompt wall. Lifecycle coverage
+depends on the harness; MCP connectivity alone does not establish automatic grounding or enforcement.
+
+To update Hunch and all configured harness pins for the current repository:
+
+```sh
+hunch update
+```
+
+Agents receive an instruction to run this when you ask **“update Hunch”** in the generated
+Hunch guidance. The command resolves npm's latest release, updates an existing dependency
+to an exact version in its current dependency section, then runs the new version's pin
+repair and integration check. Without a repository dependency it updates the global CLI.
+Use `--global` to also update the global CLI when a local dependency exists, or `--dry-run`
+to preview the commands. Restart active harnesses afterward. This applies to the current
+repository, not every project on your machine. Automatic dependency installation currently
+supports standalone npm projects; other package managers should update their dependency
+explicitly and then use `hunch integrations repair-pins`. Existing hook settings are preserved.
+An installation or check failure stops the command with a nonzero exit; completed npm
+changes are not rolled back. Fix the reported issue and rerun the command.
+
+Check the repository's integrations after upgrading Hunch or switching assistants:
+
+```sh
+hunch integrations check
+hunch integrations repair-pins
+hunch integrations check --harness claude --probe --require mcp
+hunch integrations check --harness codex --require context,edit-blocking
+```
+
+`check` exits nonzero on stale pins, malformed configuration, or missing expected hooks.
+`repair-pins` aligns existing exact npm pins with the exact Hunch dependency in `package.json`
+(or the running Hunch version when no dependency is declared). It preserves other settings,
+refuses ambiguous/custom TOML and malformed files, and does not enable enforcement.
+Reconnect active MCP sessions after repairing pins.
+
+Capabilities are reported as **verified**, **advisory-only**, **unsupported**, or **untested**.
+`--require` fails unless every named capability is verified. The Codex example currently fails:
+Hunch's Codex integration supplies MCP and instructions, with no native lifecycle adapter.
+The opt-in `--probe` starts the selected generated npm launcher, checks the server version,
+and reads memory; it may download the pinned package. It verifies a fresh MCP process only,
+not the existing host session, hook delivery, or whether a model follows the memory.
+Custom launchers and environment overrides require host-side verification.
+
+`doctor` includes this report, and session hooks with a context channel surface configuration
+problems. Checks cover repository-local configurations; global/managed overrides remain
+outside this inspection. Use `hunch integrations check` in CI to prevent pin drift; add
+`--require` for capabilities your workflow cannot operate without. Hook failure remains
+non-blocking; this explicit CI/preflight gate fails closed on unmet requirements.
 
 ## One evidence loop, not another model
 
@@ -181,7 +229,7 @@ does not host that repository. Give teammates and CI normal Git access, keep cre
 the Git credential helper, and have one maintainer connect it:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.2
+npm i -g @davesheffer/hunch@1.23.3
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -191,7 +239,7 @@ git push
 Teammates then install the same version and run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.23.2
+npm i -g @davesheffer/hunch@1.23.3
 git pull
 hunch init
 hunch doctor

package/dist/cli/index.js

@@ -24,6 +24,9 @@ import { hunchPaths, hunchPathsForDir, findRoot, toPosixTarget } from "../core/p
 import { writeFileAtomic } from "../core/io.js";
 import { looksLikeCorrection, CORRECTION_NUDGE } from "../core/correction.js";
 import { HUNCH_VERSION } from "../core/version.js";
+import { registerIntegrationCommands } from "./integrations.js";
+import { registerUpdateCommand } from "./update.js";
+import { inspectIntegrations, formatIntegrationHealth, integrationHealthFails, integrationSessionWarning } from "../integrations/health.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { JsonStore } from "../store/jsonStore.js";
 import { selectEmbedder } from "../store/embedder.js";
@@ -109,6 +112,8 @@ import { repairDecisionReference } from "../core/refrepair.js";
 import { resolveInvocation, dim, synthesisStatusLines, maybeWarnOllamaContext } from "./invocation.js";
 const program = new Command();
 program.name("hunch").description("Hunch — engineering memory and a deterministic Change Gate for AI-assisted codebases.").version(HUNCH_VERSION);
+registerIntegrationCommands(program);
+registerUpdateCommand(program);
 let openStore = null;
 function openTeamStore(root, opts = {}) {
     // A committed team.json is an explicit declaration that this checkout belongs
@@ -338,6 +343,7 @@ program
         console.log(`  ✓ linked worktree — sharing the repo's hooks + memory (no separate setup needed)`);
     }
     store.close();
+    console.log("\n" + formatIntegrationHealth(inspectIntegrations(root)));
     console.log("\nNext: make a commit (the hook captures a decision), then ask your coding assistant \"why is X built this way?\"");
     console.log("Cold start? Seed from history:  hunch backfill --since 90d");
     console.log("\n⭐ If Hunch earns its keep, a star helps others find it → https://github.com/davesheffer/hunch");
@@ -5901,6 +5907,12 @@ program
     .command("doctor")
     .description("Diagnose the environment (git, synthesis provider, index freshness).")
     .action(async () => {
+    const integrations = inspectIntegrations(findRoot());
+    console.log(formatIntegrationHealth(integrations));
+    // A shared-memory or CLI-only checkout may intentionally have no local
+    // assistant config. The explicit integrations check still fails that case.
+    if (integrations.harnesses.length > 0 && integrationHealthFails(integrations))
+        process.exitCode = 1;
     const { store, root } = storeFor();
     console.log(`Hunch root: ${root}`);
     console.log(`git repo:   ${isGitRepo(root) ? "yes" : "no"}  ${isGitRepo(root) ? `(HEAD ${headSha(root).slice(0, 8)})` : ""}`);
@@ -6069,6 +6081,11 @@ function toRepoRel(root, abs) {
     return relative(realpathNorm(root), realpathNorm(abs)).split("\\").join("/");
 }
 function emitContext(provider, event, text) {
+    if (event === "SessionStart") {
+        const warning = integrationSessionWarning(findRoot(), provider);
+        if (warning)
+            text = `${warning}\n\n${text}`;
+    }
     const output = contextHookOutput(provider, event, text);
     if (output)
         process.stdout.write(JSON.stringify(output));

package/dist/cli/integrations.js

@@ -0,0 +1,40 @@
+import { findRoot } from "../core/paths.js";
+import { CAPABILITIES, HARNESSES, inspectIntegrations, integrationHealthFails, formatIntegrationHealth, repairIntegrationPins } from "../integrations/health.js";
+import { probeIntegration } from "../integrations/probe.js";
+export function registerIntegrationCommands(program) {
+    const integrations = program.command("integrations").description("Check harness coverage and repair stale repository Hunch pins");
+    integrations.command("check")
+        .description("Fail on configuration drift; optionally require verified capabilities for CI")
+        .option("--harness <name>", "claude | codex | cursor | vscode | windsurf | antigravity")
+        .option("--require <capabilities>", "comma-separated capabilities that must be verified")
+        .option("--probe", "start the selected harness's published Hunch MCP launcher and perform a memory read (may download its pinned package)")
+        .option("--json", "machine-readable report")
+        .action(async (opts) => {
+        if (opts.harness && !Object.hasOwn(HARNESSES, opts.harness))
+            throw new Error(`unknown harness: ${opts.harness}`);
+        if (opts.probe && !opts.harness)
+            throw new Error("--probe requires --harness");
+        const required = opts.require === undefined ? [] : opts.require.split(",").map(c => c.trim());
+        if (required.some(c => !CAPABILITIES.includes(c)))
+            throw new Error(`--require accepts ${CAPABILITIES.join(",")}`);
+        const root = findRoot();
+        const report = inspectIntegrations(root, opts.harness);
+        if (opts.probe)
+            await probeIntegration(root, opts.harness, report);
+        console.log(opts.json ? JSON.stringify(report, null, 2) : formatIntegrationHealth(report));
+        if (integrationHealthFails(report, required))
+            process.exitCode = 1;
+    });
+    integrations.command("repair-pins")
+        .description("Align existing exact-version integration pins with package.json; preserves other settings and does not enable hooks")
+        .action(() => {
+        const root = findRoot();
+        const files = repairIntegrationPins(root);
+        console.log(files.length ? `Updated ${files.length} integration file(s): ${files.join(", ")}. Reconnect active MCP sessions.` : "Integration pins already aligned.");
+        const report = inspectIntegrations(root);
+        console.log(formatIntegrationHealth(report));
+        if (integrationHealthFails(report))
+            process.exitCode = 1;
+    });
+}
+//# sourceMappingURL=integrations.js.map

package/dist/cli/update.js

@@ -0,0 +1,72 @@
+import { spawnSync } from "node:child_process";
+import { existsSync, readFileSync } from "node:fs";
+import { join } from "node:path";
+import { findRoot } from "../core/paths.js";
+const PACKAGE = "@davesheffer/hunch";
+/** Arguments come only from fixed commands and a validated registry version.
+ * Windows needs the shell to resolve npm.cmd; cwd is never interpolated. */
+export function runNpm(root, args, capture = false) {
+    if (args.some(arg => !/^[a-zA-Z0-9@/_.=+:-]+$/.test(arg)))
+        throw new Error("unsafe npm argument");
+    const windows = process.platform === "win32";
+    const result = spawnSync(windows ? `npm ${args.join(" ")}` : "npm", windows ? [] : args, {
+        cwd: root, shell: windows, windowsHide: true,
+        encoding: "utf8", stdio: capture ? ["ignore", "pipe", "pipe"] : "inherit",
+    });
+    if (result.error)
+        throw result.error;
+    if (result.status !== 0)
+        throw new Error(`npm ${args.join(" ")} failed (${result.status ?? result.signal})${result.stderr ? `: ${result.stderr.trim()}` : ""}`);
+    return result.stdout ?? "";
+}
+/** Fresh child execution is essential: the currently running CLI still has the
+ * old modules loaded after npm replaces its installation. */
+export function updateHunch(root, opts = {}, run = (args, capture) => runNpm(root, args, capture), log = console.log) {
+    const file = join(root, "package.json");
+    const manifest = existsSync(file) ? JSON.parse(readFileSync(file, "utf8")) : {};
+    if (!manifest || typeof manifest !== "object" || Array.isArray(manifest))
+        throw new Error("package.json must contain an object");
+    if (manifest.name === PACKAGE)
+        throw new Error("Run hunch update in a consumer repository, not Hunch's own source checkout.");
+    const sections = ["dependencies", "devDependencies", "optionalDependencies"];
+    const declared = sections.filter(section => {
+        const deps = manifest[section];
+        if (deps !== undefined && (!deps || typeof deps !== "object" || Array.isArray(deps)))
+            throw new Error(`invalid ${section} in package.json`);
+        return deps && Object.hasOwn(deps, PACKAGE);
+    });
+    if (declared.length > 1)
+        throw new Error("Hunch is declared in multiple dependency sections; resolve the duplicate before updating.");
+    if (declared.length && (manifest.workspaces || (manifest.packageManager && !/^npm@/.test(manifest.packageManager)) || ["pnpm-lock.yaml", "yarn.lock", "bun.lock", "bun.lockb"].some(name => existsSync(join(root, name))))) {
+        throw new Error("Automatic dependency updates currently support standalone npm projects. Update Hunch to an exact version with your package manager, then run hunch integrations repair-pins.");
+    }
+    const version = JSON.parse(run(["view", `${PACKAGE}@latest`, "version", "--json"], true));
+    if (typeof version !== "string" || !/^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/.test(version))
+        throw new Error("npm returned an invalid Hunch version");
+    const spec = `${PACKAGE}@${version}`;
+    const commands = [];
+    if (declared.length) {
+        const flag = { dependencies: "--save-prod", devDependencies: "--save-dev", optionalDependencies: "--save-optional" }[declared[0]];
+        commands.push(["install", flag, "--save-exact", spec]);
+    }
+    if (!declared.length || opts.global)
+        commands.push(["install", "--global", spec]);
+    // The alias prevents npm exec from substituting a stale local hunch binary.
+    commands.push(["exec", "--yes", `--package=hunch-exact@npm:${spec}`, "--", "hunch", "integrations", "repair-pins"]);
+    log(`${opts.dryRun ? "Preview" : "Updating"}: Hunch ${version} for ${root}`);
+    for (const args of commands) {
+        log(`npm ${args.join(" ")}`);
+        if (!opts.dryRun)
+            run(args);
+    }
+    if (!opts.dryRun)
+        log("Hunch updated; repository integration check passed. Restart or reconnect active harnesses to load the new MCP version.");
+}
+export function registerUpdateCommand(program) {
+    program.command("update")
+        .description("Update Hunch to latest and repair all configured harness pins in this repository")
+        .option("--global", "also update the global CLI when a repository dependency exists")
+        .option("--dry-run", "resolve latest and print commands without changing files")
+        .action((opts) => updateHunch(findRoot(), opts));
+}
+//# sourceMappingURL=update.js.map

package/dist/integrations/claudemd.js

@@ -46,6 +46,7 @@ export function renderHunchSection(store, root) {
     lines.push("**Consult Hunch via the `hunch_*` MCP tools — pick by MOMENT, not from memory:**");
     lines.push("");
     lines.push("**Orient (session/task start):**");
+    lines.push("- When the user asks to **update Hunch**, run `hunch update` from this repository root. It updates to the latest release and repairs all configured harness pins. Use `hunch update --global` to also update a global CLI alongside a repository dependency; reconnect active MCP sessions afterward.");
     lines.push("- `hunch_context(target)` — the minimal relevant slice for what you're about to do; a task phrase falls back to the closest graph matches. **Call FIRST.**");
     lines.push("- `hunch_structure(target?)` — the indexed shape of the repo/dir/file/symbol — orient from the graph, not grep rounds.");
     lines.push("- `hunch_runbook(task)` — the proven steps for a recurring task, before re-deriving them.");

package/dist/integrations/health.js

@@ -0,0 +1,269 @@
+/** Repository integration checks. Configuration is evidence of wiring, never
+ * evidence that a host delivered context or enforced a decision. */
+import { existsSync, readFileSync, lstatSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { parseJsonc } from "../core/jsonc.js";
+import { writeFileAtomic } from "../core/io.js";
+import { HUNCH_VERSION } from "../core/version.js";
+import { readConfig } from "../core/config.js";
+import { hunchPaths } from "../core/paths.js";
+export const CAPABILITIES = ["mcp", "context", "edit-blocking", "failure-capture", "compaction"];
+export const HARNESSES = {
+    claude: { mcp: ".mcp.json", hooks: ".claude/settings.json", key: "mcpServers", events: ["SessionStart", "PreToolUse", "PostToolUseFailure", "PreCompact"] },
+    codex: { mcp: ".codex/config.toml", hooks: "", key: "", events: [] },
+    cursor: { mcp: ".cursor/mcp.json", hooks: ".cursor/hooks.json", key: "mcpServers", events: ["sessionStart", "preToolUse", "postToolUse", ""] },
+    vscode: { mcp: ".vscode/mcp.json", hooks: ".github/hooks/hunch.json", key: "servers", events: ["SessionStart", "PreToolUse", "PostToolUse", ""] },
+    windsurf: { mcp: ".windsurf/mcp_config.json", hooks: ".windsurf/hooks.json", key: "mcpServers", events: ["", "pre_write_code", "post_run_command", ""] },
+    antigravity: { mcp: ".agents/mcp_config.json", hooks: ".agents/hooks.json", key: "mcpServers", events: ["PreInvocation", "PreToolUse", "", ""] },
+};
+const exactVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+const pinPattern = /@davesheffer\/hunch@([^\s"'\],;]+)/g;
+const object = (v) => {
+    if (!v || typeof v !== "object" || Array.isArray(v))
+        throw new Error("expected a configuration object");
+    return v;
+};
+function strings(value) {
+    if (typeof value === "string")
+        return [value];
+    if (Array.isArray(value))
+        return value.flatMap(strings);
+    if (value && typeof value === "object")
+        return Object.values(value).flatMap(strings);
+    return [];
+}
+function hookCommands(value) {
+    if (Array.isArray(value))
+        return value.flatMap(hookCommands);
+    if (!value || typeof value !== "object")
+        return [];
+    const obj = value;
+    if (obj.enabled === false || (obj.type !== undefined && obj.type !== "command"))
+        return [];
+    const command = typeof obj.command === "string" ? obj.command : "";
+    const own = /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command)
+        && /\s"?hook"?(?:\s+"?--provider"?\s+"?[a-z]+"?)?\s*$/.test(command);
+    return [...(own ? [command] : []), ...(obj.hooks ? hookCommands(obj.hooks) : [])];
+}
+/** Pin repair is restricted to Hunch's marker-owned TOML block. */
+function codexBlock(raw) {
+    const start = "# >>> hunch mcp (managed) >>>";
+    const end = "# <<< hunch mcp <<<";
+    if (raw.split(start).length !== 2 || raw.split(end).length !== 2)
+        throw new Error("managed Hunch TOML block missing or duplicated; run hunch init after reviewing custom configuration");
+    const begin = raw.indexOf(start), finish = raw.indexOf(end);
+    if (finish < begin)
+        throw new Error("malformed managed Hunch TOML block");
+    const block = raw.slice(begin + start.length, finish);
+    if ((raw.match(/^\s*\[mcp_servers\.hunch\]/gm) ?? []).length !== 1)
+        throw new Error("missing or duplicate Hunch MCP table");
+    if (!/^\s*\[mcp_servers\.hunch\]\s*$/m.test(block))
+        throw new Error("Hunch table is outside its managed block");
+    return block;
+}
+export function readLauncher(root, harness) {
+    const spec = HARNESSES[harness];
+    const raw = readFileSync(join(root, spec.mcp), "utf8");
+    let config;
+    if (harness === "codex") {
+        config = object(object(parseToml(raw).mcp_servers).hunch);
+    }
+    else {
+        config = object(object(object(parseJsonc(raw))[spec.key]).hunch);
+    }
+    if (config.enabled === false || config.disabled === true)
+        throw new Error("Hunch MCP server is disabled");
+    if (typeof config.command !== "string" || !config.command.trim() || !Array.isArray(config.args) || !config.args.every(a => typeof a === "string"))
+        throw new Error("expected a local stdio command and string arguments");
+    return { command: config.command, args: config.args, customEnvironment: ["env", "env_vars", "cwd"].some(key => config[key] !== undefined) };
+}
+function expectedVersion(root) {
+    const file = join(root, "package.json");
+    if (!existsSync(file))
+        return HUNCH_VERSION;
+    const manifest = object(JSON.parse(readFileSync(file, "utf8")));
+    const declarations = [manifest.dependencies, manifest.devDependencies, manifest.optionalDependencies]
+        .filter(Boolean).map(object).map(deps => deps["@davesheffer/hunch"]).filter(v => v !== undefined);
+    if (new Set(declarations).size > 1)
+        throw new Error("conflicting Hunch dependency versions");
+    const version = declarations[0] ?? (manifest.name === "@davesheffer/hunch" ? manifest.version : HUNCH_VERSION);
+    if (typeof version !== "string" || !exactVersion.test(version))
+        throw new Error("pin @davesheffer/hunch to an exact version in package.json before checking integrations");
+    return version;
+}
+export function inspectIntegrations(root, selected) {
+    const report = { schema: "hunch.integration-health/1", expectedVersion: HUNCH_VERSION, scope: "repository-config", issues: [], harnesses: [] };
+    try {
+        report.expectedVersion = expectedVersion(root);
+    }
+    catch (e) {
+        report.issues.push({ file: "package.json", code: "dependency-version", detail: e.message });
+    }
+    const firmness = readConfig(hunchPaths(root)).firmness;
+    const recordPins = (file, values) => {
+        for (const value of values) {
+            const pins = [...value.matchAll(pinPattern)];
+            if (value.includes("@davesheffer/hunch") && !pins.length)
+                report.issues.push({ file, code: "unpinned-package", detail: "Hunch npm launcher has no exact version; run hunch init with the intended version" });
+            for (const [, version] of pins) {
+                if (version !== report.expectedVersion)
+                    report.issues.push({ file, code: "version-drift", detail: `Hunch ${version} differs from expected ${report.expectedVersion}; run hunch integrations repair-pins` });
+            }
+        }
+    };
+    for (const harness of selected ? [selected] : Object.keys(HARNESSES)) {
+        const spec = HARNESSES[harness];
+        if (!selected && !existsSync(join(root, spec.mcp)) && (!spec.hooks || !existsSync(join(root, spec.hooks))))
+            continue;
+        const capabilities = Object.fromEntries(CAPABILITIES.map(c => [c, { status: "untested", detail: "No runtime evidence" }]));
+        report.harnesses.push({ harness, capabilities });
+        try {
+            const launcher = readLauncher(root, harness);
+            recordPins(spec.mcp, [launcher.command, ...launcher.args]);
+            capabilities.mcp.detail = "Configured locally; use --probe to verify a fresh server, then reconnect the host";
+        }
+        catch (e) {
+            report.issues.push({ file: spec.mcp, code: "mcp-config", detail: e.message });
+            capabilities.mcp.detail = "MCP configuration missing, disabled, invalid, or outside supported inspection format";
+        }
+        let events = {};
+        let disabled = false;
+        if (spec.hooks) {
+            try {
+                const config = object(parseJsonc(readFileSync(join(root, spec.hooks), "utf8")));
+                disabled = config.disableAllHooks === true;
+                events = object(harness === "antigravity" ? config.hunch : config.hooks);
+                recordPins(spec.hooks, Object.values(events).flatMap(hookCommands));
+            }
+            catch (e) {
+                report.issues.push({ file: spec.hooks, code: "hook-config", detail: e.message });
+            }
+        }
+        for (const [i, capability] of ["context", "edit-blocking", "failure-capture", "compaction"].entries()) {
+            const event = spec.events[i];
+            const status = capabilities[capability];
+            if (!event) {
+                status.status = capability === "context" ? "advisory-only" : "unsupported";
+                status.detail = capability === "context" ? "Hunch relies on instructions and voluntary MCP calls on this adapter" : "No Hunch lifecycle adapter for this capability";
+            }
+            else if (disabled || firmness === "off" || ((capability === "failure-capture") && process.env.HUNCH_PIPELINE === "0")) {
+                status.status = "unsupported";
+                status.detail = "Disabled by local hook settings, firmness, or HUNCH_PIPELINE";
+            }
+            else if (!hookCommands(events[event]).some(command => {
+                const dialect = command.match(/"?--provider"?\s+"?([a-z]+)"?/i)?.[1]?.toLowerCase() ?? "claude";
+                return dialect === harness;
+            })) {
+                status.detail = `Missing Hunch ${event} handler`;
+                report.issues.push({ file: spec.hooks, code: "missing-hook", detail: status.detail });
+            }
+            else if (capability === "edit-blocking" && firmness !== "strict") {
+                status.status = "advisory-only";
+                status.detail = `firmness=${firmness}; edits are not blocked`;
+            }
+            else {
+                status.detail = `${event} configured; host delivery, matchers, and tool coverage are not verified`;
+            }
+        }
+    }
+    if (!report.harnesses.length)
+        report.issues.push({ file: ".", code: "no-integrations", detail: "No repository integrations found; global and managed host settings are not inspected" });
+    return report;
+}
+/** Repair only exact published pins. Preserve formatting and all other values.
+ * Preflight every affected file before writing any; reject malformed JSON/TOML. */
+export function repairIntegrationPins(root) {
+    const version = expectedVersion(root);
+    const pending = [];
+    for (const [name, spec] of Object.entries(HARNESSES)) {
+        for (const file of [spec.mcp, spec.hooks].filter(Boolean)) {
+            const path = join(root, file);
+            if (!existsSync(path))
+                continue;
+            // Never follow a config symlink or symlinked parent into another project.
+            let current = resolve(root);
+            for (const part of file.split("/")) {
+                current = join(current, part);
+                if (lstatSync(current).isSymbolicLink())
+                    throw new Error(`refusing to rewrite symlink: ${file}`);
+            }
+            const before = readFileSync(path, "utf8");
+            const replace = (text) => text.replace(pinPattern, (match, old) => {
+                if (!exactVersion.test(old))
+                    throw new Error(`refusing non-exact Hunch pin in ${file}`);
+                return `@davesheffer/hunch@${version}`;
+            });
+            let after;
+            if (name === "codex") {
+                readLauncher(root, "codex");
+                const block = codexBlock(before);
+                const table = object(object(parseToml(block).mcp_servers).hunch);
+                if (Object.keys(table).some(key => !["command", "args"].includes(key)))
+                    throw new Error(`custom managed settings require manual pin repair: ${file}`);
+                // Replace only the canonical args line, never comments or another table.
+                const lines = block.split("\n");
+                if (lines.some(line => line.trim() && !line.trim().startsWith("#") && !/^\s*(?:\[mcp_servers\.hunch\]|command\s*=|args\s*=)/.test(line)))
+                    throw new Error(`custom managed TOML requires manual pin repair: ${file}`);
+                const next = lines.map(line => /^\s*args\s*=/.test(line) ? replace(line.split("#")[0]) + (line.includes("#") ? `#${line.split("#").slice(1).join("#")}` : "") : line).join("\n");
+                after = before.replace(block, next);
+                parseToml(after);
+            }
+            else {
+                const config = object(parseJsonc(before));
+                const values = file === spec.mcp
+                    ? strings(object(object(config[spec.key]).hunch).args)
+                    : Object.values(object(name === "antigravity" ? config.hunch : config.hooks)).flatMap(hookCommands);
+                const replacements = new Map(values.map(v => [v, replace(v)]).filter(([a, b]) => a !== b));
+                const counts = new Map();
+                // Tokenize comments too, so a quoted command in a comment is untouched.
+                after = before.replace(/\/\/[^\n]*|\/\*[\s\S]*?\*\/|"(?:[^"\\]|\\.)*"/g, token => {
+                    if (!token.startsWith('"'))
+                        return token;
+                    const value = JSON.parse(token);
+                    const replacement = replacements.get(value);
+                    if (replacement !== undefined)
+                        counts.set(value, (counts.get(value) ?? 0) + 1);
+                    return replacement !== undefined && replacement !== value ? JSON.stringify(replacement) : token;
+                });
+                for (const [value, count] of counts) {
+                    if (count !== values.filter(v => v === value).length)
+                        throw new Error(`ambiguous Hunch string also appears outside managed settings in ${file}; refusing repair`);
+                }
+            }
+            if (before !== after)
+                pending.push({ file, before, after });
+        }
+    }
+    for (const { file, before } of pending)
+        if (readFileSync(join(root, file), "utf8") !== before)
+            throw new Error(`${file} changed during repair; retry`);
+    for (const { file, after } of pending)
+        writeFileAtomic(join(root, file), after);
+    return pending.map(p => p.file);
+}
+export function integrationHealthFails(report, required = []) {
+    return report.issues.length > 0 || report.harnesses.some(h => required.some(c => h.capabilities[c].status !== "verified"));
+}
+export function formatIntegrationHealth(report) {
+    return [
+        `Hunch integrations — expected ${report.expectedVersion} (repository configuration only)`,
+        ...report.harnesses.map(h => `${h.harness}:\n${CAPABILITIES.map(c => `  ${c}: ${h.capabilities[c].status} — ${h.capabilities[c].detail}`).join("\n")}`),
+        ...report.issues.map(i => `ERROR ${i.file}: ${i.detail}`),
+        "Configured hooks are untested until exercised inside the host. Global settings, active sessions, and model compliance are not verified.",
+    ].join("\n");
+}
+/** Bounded session warning; diagnostics must never break hook execution. */
+export function integrationSessionWarning(root, harness) {
+    try {
+        const report = inspectIntegrations(root, harness);
+        if (!report.issues.length)
+            return "";
+        const issues = [...new Set(report.issues.map(i => `${i.file}: ${i.detail}`))];
+        return `Hunch integration needs attention: ${issues.slice(0, 3).join("; ").slice(0, 1200)}. Run hunch integrations check; do not assume full harness coverage.`;
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=health.js.map

package/dist/integrations/probe.js

@@ -0,0 +1,52 @@
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { HARNESSES, readLauncher } from "./health.js";
+/** Opt-in: starts a fresh configured MCP process, never claims the current
+ * harness connection or hook delivery has been tested. No model is invoked. */
+export async function probeIntegration(root, harness, report, timeoutMs = 15_000) {
+    const health = report.harnesses.find(h => h.harness === harness);
+    if (!health)
+        throw new Error(`missing ${harness} inspection`);
+    const client = new Client({ name: "hunch-integration-probe", version: "1" });
+    let transport;
+    let timer;
+    try {
+        const launcher = readLauncher(root, harness);
+        if (launcher.customEnvironment)
+            throw new Error("custom MCP environment or working directory requires a host-side probe; no settings were ignored");
+        // Only execute the exact published launcher Hunch generates. Custom
+        // commands may need credentials or have unrelated effects; inspect only.
+        if (!/^npx(?:\.cmd)?$/.test(launcher.command) || JSON.stringify(launcher.args) !== JSON.stringify([
+            "-y", `--package=hunch-exact@npm:@davesheffer/hunch@${report.expectedVersion}`, "hunch", "mcp",
+        ]))
+            throw new Error("probe requires the generated exact-version npx launcher; repair stale pins first; custom launchers remain untested");
+        transport = new StdioClientTransport({ ...launcher, cwd: root, stderr: "pipe" });
+        transport.stderr?.on("data", () => { });
+        await Promise.race([
+            (async () => {
+                await client.connect(transport);
+                const server = client.getServerVersion();
+                if (server?.name !== "hunch" || server.version !== report.expectedVersion)
+                    throw new Error("MCP server identity/version does not match the repository dependency");
+                const { tools } = await client.listTools();
+                if (!tools.some(t => t.name === "hunch_context") || !tools.some(t => t.name === "hunch_structure"))
+                    throw new Error("required Hunch memory tools are missing");
+                const result = await client.callTool({ name: "hunch_structure", arguments: {} });
+                if (result.isError || !Array.isArray(result.content) || !result.content.some(c => c.type === "text" && c.text))
+                    throw new Error("Hunch memory read failed");
+            })(),
+            new Promise((_, reject) => { timer = setTimeout(() => reject(new Error("MCP probe timed out")), timeoutMs); }),
+        ]);
+        health.capabilities.mcp = { status: "verified", detail: `Fresh MCP process reports ${report.expectedVersion}; memory tool read succeeded. Existing host sessions were not probed` };
+    }
+    catch (e) {
+        report.issues.push({ file: HARNESSES[harness].mcp, code: "mcp-probe", detail: e.message });
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        await client.close().catch(() => { });
+        await transport?.close().catch(() => { });
+    }
+}
+//# sourceMappingURL=probe.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
@@ -69,7 +69,7 @@
     "node": ">=22.13.0"
   },
   "scripts": {
-    "version": "node tooling/sync-version-pins.mjs && git add plugin/.mcp.json server.json",
+    "version": "node tooling/sync-version-pins.mjs && git add plugin/.mcp.json server.json .windsurf/hooks.json",
     "sync-version-pins": "node tooling/sync-version-pins.mjs",
     "clean": "node --input-type=commonjs -e \"require('fs').rmSync('dist',{recursive:true,force:true})\"",
     "build": "npm run clean && tsc -p tsconfig.json",
@@ -93,6 +93,7 @@
     "@modelcontextprotocol/sdk": "^1.30.0",
     "@tree-sitter-grammars/tree-sitter-yaml": "^0.6.1",
     "commander": "^15.0.0",
+    "smol-toml": "1.8.0",
     "tree-sitter": "0.21.1",
     "tree-sitter-go": "^0.23.4",
     "tree-sitter-php": "0.23.12",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.23.2",
+  "version": "1.24.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.23.2",
+      "version": "1.24.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {