@davesheffer/hunch 0.14.0 → 0.14.2

package/README.md

@@ -85,6 +85,17 @@ Claude Code in the repo** afterward to pick up the `hunch_*` tools. (Each teamma
 `hunch init` once to wire up their own clone; the captured `.hunch/` content is shared
 via git.)
 
+> **Prefer `hunch init` (project-local `.mcp.json`) over a global `claude mcp add`.**
+> `.mcp.json` is registered by file path, so it's robust. A global `claude mcp add`
+> writes to `~/.claude.json` keyed by the raw working-directory string — and **on
+> Windows** that's a trap: drive letters are case-insensitive (`c:\` and `C:\` are the
+> same folder) but Claude Code compares the key case-sensitively, so it can create two
+> project blocks for one directory and a session that resolves to the *other* casing
+> sees no `hunch_*` tools (registration looked fine, the tools just aren't there). If
+> you hit this, run **`hunch doctor`** — on Windows it detects the split and heals it
+> (merging the MCP servers across both casings, after backing up `~/.claude.json`).
+> `hunch init` runs the same heal automatically at the end.
+
 ### 4. Use it
 
 ```bash
@@ -109,8 +120,10 @@ The MCP tools Claude calls under the hood: `hunch_why`, `hunch_query`,
 `hunch_check_constraints`, `hunch_get_dependents` (blast radius), `hunch_blast_radius`
 (dependent files + near-violations a change could break indirectly), `hunch_bug_lineage`,
 `hunch_context` (surgical minimal slice for a task), `hunch_timeline` (a target's decision
-history over time), `hunch_record_decision` (write-back). `hunch_why` and `hunch_context`
-take an optional `as_of` (commit/tag/branch) to **time-travel** the graph to a past state.
+history over time), `hunch_merge_verdict` (a cited BLOCK/WARN/PASS over a diff — see below),
+and the write-backs `hunch_record_decision`, `hunch_record_correction` (turn a correction into
+an enforced invariant — see below). `hunch_why` and `hunch_context` take an optional `as_of`
+(commit/tag/branch) to **time-travel** the graph to a past state.
 
 ### Works with any MCP assistant
 

package/dist/cli/index.js

@@ -34,6 +34,7 @@ import { writeCiWorkflow } from "../integrations/ciAction.js";
 import { updateClaudeMd } from "../integrations/claudemd.js";
 import { writeMcpJson, writeSlashCommands, installClaudeHooks } from "../integrations/scaffold.js";
 import { scaffoldProviders } from "../integrations/providers.js";
+import { healClaudeConfigCaseSplit } from "../integrations/claudeConfig.js";
 import { formatContext } from "../core/format.js";
 import { readConfig, writeConfig, FIRMNESS_LEVELS, isFirmness } from "../core/config.js";
 import { blockingInScope } from "../core/hookpolicy.js";
@@ -106,7 +107,10 @@ program
         console.log("  ⚠ not a git repo — skipped hooks (run `git init` to enable the learning loop)");
     }
     const mcp = writeMcpJson(root, inv.mcp);
-    console.log(`  ✓ wrote ${rel(root, mcp)} (registers the Hunch MCP server)`);
+    // .mcp.json is the CANONICAL registration: Claude Code resolves it by file path,
+    // so it's immune to the Windows ~/.claude.json drive-letter case-split that a
+    // global `claude mcp add` is prone to (see `hunch doctor`).
+    console.log(`  ✓ wrote ${rel(root, mcp)} (registers the Hunch MCP server — canonical, path-keyed; prefer over a global \`claude mcp add\`)`);
     const cmds = writeSlashCommands(root);
     console.log(`  ✓ wrote ${cmds.length} slash commands (/hunch-why, /hunch-fix, /hunch-fragile)`);
     const cmd = updateClaudeMd(root, store);
@@ -131,6 +135,10 @@ program
             if (p.error)
                 console.log(`  ⚠ skipped ${p.assistant}: ${p.error}`);
     }
+    // Windows self-heal: if an earlier global `claude mcp add` left a drive-letter
+    // case-split in ~/.claude.json, merge it so hunch resolves under either casing.
+    // No-op (silent) off Windows.
+    reportClaudeConfigHeal();
     store.close();
     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");
@@ -940,11 +948,37 @@ program
     else {
         console.log(dim(`semantic:   off (keyword search only) — enable: npm i -g @huggingface/transformers && hunch embed`));
     }
+    // Windows: detect/heal the Claude Code ~/.claude.json drive-letter case-split
+    // that silently hides the hunch_* MCP tools. No-op (silent) off Windows.
+    reportClaudeConfigHeal();
     store.close();
 });
 function rel(root, p) {
     return p.startsWith(root) ? p.slice(root.length + 1) : p;
 }
+/** Run the Windows ~/.claude.json drive-letter case-split heal and print what it
+ *  did. Silent + no-op off Windows. A parse refusal is surfaced as a warning, never
+ *  thrown out of doctor/init (those commands must still complete). */
+function reportClaudeConfigHeal() {
+    let res;
+    try {
+        res = healClaudeConfigCaseSplit();
+    }
+    catch (e) {
+        console.log(`  ⚠ Claude config: ${e.message}`);
+        return;
+    }
+    if (!res.applicable)
+        return; // non-Windows: the case-split bug can't occur
+    if (!res.changed) {
+        console.log(dim(`Claude config: no drive-letter project split (${res.file})`));
+        return;
+    }
+    for (const g of res.groups) {
+        console.log(`✓ healed Claude Code project case-split: mirrored [${g.servers.join(", ")}] across ${g.casings.join("  ·  ")}`);
+    }
+    console.log(dim(`  ↳ backup: ${res.backup}`));
+}
 function dim(s) {
     return `\x1b[2m${s}\x1b[0m`;
 }

package/dist/integrations/claudeConfig.js

@@ -0,0 +1,171 @@
+/**
+ * Heal a Windows-only Claude Code misconfiguration that silently hides Hunch's
+ * `hunch_*` MCP tools.
+ *
+ * THE BUG (Claude Code's, not Hunch's): Claude Code stores per-project config in
+ * `~/.claude.json` under a `projects` map keyed by the raw cwd STRING. Windows
+ * drive letters are case-insensitive (`c:\` and `C:\` are the same directory) but
+ * Claude Code compares the key case-sensitively. So it can create TWO project
+ * blocks for one real directory:
+ *
+ *   "c:/Users/me/repo" -> mcpServers: {}                 (what one session resolves to)
+ *   "C:/Users/me/repo" -> mcpServers: { hunch: {…} }     (where `claude mcp add` wrote)
+ *
+ * A session whose cwd resolves to the OTHER casing reads the empty block → no
+ * hunch tools, even though registration "succeeded".
+ *
+ * Only the GLOBAL `claude mcp add` route (cwd-string-keyed in ~/.claude.json) is
+ * fragile. Hunch's own project-local `.mcp.json` (scaffold.ts writeMcpJson) is
+ * IMMUNE — Claude resolves it by file path, not by a cwd string key.
+ */
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { existsSync, readFileSync, copyFileSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
+/** Absolute path to Claude Code's per-user config (`~/.claude.json`). */
+export function claudeConfigPath() {
+    return join(homedir(), ".claude.json");
+}
+/** Group key for two project keys that point at the SAME real directory. The bug
+ *  is purely drive-letter case (+ slash style), so we normalize ONLY those — never
+ *  the rest of the path — so genuinely distinct projects are never merged. */
+function normalizeProjectKey(key) {
+    return key.replace(/\\/g, "/").replace(/^([A-Za-z]):/, (_m, d) => `${d.toLowerCase()}:`);
+}
+function isPlainObject(v) {
+    return !!v && typeof v === "object" && !Array.isArray(v);
+}
+function asStringArray(v) {
+    return Array.isArray(v) ? v.filter((x) => typeof x === "string") : [];
+}
+/** Union the MCP config across all casing variants of one real project. First-wins
+ *  on a server-name collision (keys iterated in sorted order for determinism) so we
+ *  never clobber an existing server definition; enabled/disabled lists are deduped
+ *  unions. */
+function unionConfig(blocks) {
+    const servers = {};
+    const enabled = new Set();
+    const disabled = new Set();
+    for (const b of blocks) {
+        if (isPlainObject(b.mcpServers)) {
+            for (const [name, cfg] of Object.entries(b.mcpServers))
+                if (!(name in servers))
+                    servers[name] = cfg;
+        }
+        for (const s of asStringArray(b.enabledMcpjsonServers))
+            enabled.add(s);
+        for (const s of asStringArray(b.disabledMcpjsonServers))
+            disabled.add(s);
+    }
+    return { servers, enabled: [...enabled], disabled: [...disabled] };
+}
+/** Mirror the union into one casing block, touching ONLY the three MCP keys and
+ *  ADDING missing entries (never overwriting an existing one). Returns true if the
+ *  block changed. */
+function applyUnion(block, u) {
+    let changed = false;
+    if (!isPlainObject(block.mcpServers)) {
+        block.mcpServers = {};
+        if (Object.keys(u.servers).length)
+            changed = true;
+    }
+    for (const [name, cfg] of Object.entries(u.servers)) {
+        if (!(name in block.mcpServers)) {
+            block.mcpServers[name] = cfg;
+            changed = true;
+        }
+    }
+    const mergeList = (key, extra) => {
+        if (!extra.length)
+            return;
+        const cur = asStringArray(block[key]);
+        const merged = [...new Set([...cur, ...extra])];
+        if (merged.length !== cur.length) {
+            block[key] = merged;
+            changed = true;
+        }
+    };
+    mergeList("enabledMcpjsonServers", u.enabled);
+    mergeList("disabledMcpjsonServers", u.disabled);
+    return changed;
+}
+/** Windows-safe timestamp for the backup filename (no `:` — invalid on NTFS). */
+function backupStamp() {
+    return new Date().toISOString().replace(/[:.]/g, "-");
+}
+/**
+ * Scan `~/.claude.json` for project keys that collapse to the same real directory
+ * but differ by drive-letter case, and HEAL each split by computing the UNION of
+ * its casings' MCP config and MIRRORING that union back into EVERY casing.
+ *
+ * Why mirror (not merge-into-one-canonical-and-delete-the-rest): we cannot predict
+ * which casing a given Claude Code session will resolve its cwd to. If we collapsed
+ * to a single canonical key, a session that lands on a deleted casing would get a
+ * fresh empty block → hunch missing again. Mirroring the union guarantees that
+ * whichever casing wins, the server is there — and it deletes nothing Claude made.
+ *
+ * Safety: no-op on non-Windows; backs up the file (timestamped copy) BEFORE any
+ * write; merges only (never clobbers other servers/keys); and THROWS rather than
+ * overwrite a non-empty file it cannot parse (mirrors readJsonObj in providers.ts).
+ */
+export function healClaudeConfigCaseSplit(opts = {}) {
+    const platform = opts.platform ?? process.platform;
+    const file = opts.file ?? claudeConfigPath();
+    const base = { platform, applicable: platform === "win32", file, changed: false, groups: [] };
+    if (platform !== "win32")
+        return base; // the case-split bug is Windows-only
+    if (!existsSync(file))
+        return base;
+    const raw = readFileSync(file, "utf8");
+    if (!raw.trim())
+        return base;
+    let root;
+    try {
+        const v = JSON.parse(raw);
+        if (!isPlainObject(v))
+            throw new Error("not a JSON object");
+        root = v;
+    }
+    catch (e) {
+        throw new Error(`refusing to modify ${file}: could not parse it (${e.message}). Fix or remove it, then re-run.`);
+    }
+    const projects = root.projects;
+    if (!isPlainObject(projects))
+        return base; // nothing to heal
+    // Bucket the raw project keys by their normalized real path.
+    const buckets = new Map();
+    for (const key of Object.keys(projects)) {
+        const norm = normalizeProjectKey(key);
+        const arr = buckets.get(norm) ?? [];
+        arr.push(key);
+        buckets.set(norm, arr);
+    }
+    const groups = [];
+    let changed = false;
+    for (const [norm, keys] of buckets) {
+        if (keys.length < 2)
+            continue; // no casing split for this directory
+        keys.sort(); // deterministic first-wins union
+        const blocks = keys.map((k) => (isPlainObject(projects[k]) ? projects[k] : {}));
+        const u = unionConfig(blocks);
+        let groupChanged = false;
+        for (const k of keys) {
+            if (!isPlainObject(projects[k]))
+                projects[k] = {};
+            if (applyUnion(projects[k], u))
+                groupChanged = true;
+        }
+        if (groupChanged) {
+            changed = true;
+            groups.push({ realPath: norm, casings: keys, servers: Object.keys(u.servers) });
+        }
+    }
+    if (!changed)
+        return { ...base, groups };
+    // Back up the exact original bytes BEFORE writing the healed config.
+    const backup = `${file}.hunch-bak-${backupStamp()}`;
+    copyFileSync(file, backup);
+    writeFileAtomic(file, JSON.stringify(root, null, 2) + "\n");
+    return { ...base, changed: true, backup, groups };
+}
+//# sourceMappingURL=claudeConfig.js.map

package/dist/synthesis/provider.js

@@ -177,6 +177,18 @@ class CliSynthProvider {
         return draft;
     }
 }
+// A model id comes from a HUNCH_*_MODEL env var and ends up as an argv token that,
+// on Windows, pexecIn joins into the cmd.exe line (shell:true, to resolve the npm
+// `.cmd` shim). The untrusted prompt always travels via stdin — never argv — so the
+// ONLY non-literal token reaching that shell line is this model id. Reject anything
+// with whitespace or a cmd.exe metacharacter so a poisoned env var can't smuggle
+// `& evil.exe` into the line; fall back to the provider default rather than crash on
+// a mere typo. (pexecIn itself stays general — callers may legitimately pass a
+// pre-quoted path token — so the guard lives here, at the untrusted-input source.)
+const MODEL_RE = /^[A-Za-z0-9._:/-]+$/;
+export function safeModel(v, fallback) {
+    return v && MODEL_RE.test(v) ? v : fallback;
+}
 // --------------------------------------------------------------------------
 // Provider A: headless `claude -p` CLI — billed to the user's Claude subscription
 // --------------------------------------------------------------------------
@@ -184,7 +196,7 @@ class ClaudeCliProvider extends CliSynthProvider {
     name = "claude-cli";
     // Default to the `haiku` alias (cheap/fast, and survives model retirements)
     // rather than a pinned dated id; override with HUNCH_SYNTH_MODEL if needed.
-    model = process.env.HUNCH_SYNTH_MODEL || "haiku";
+    model = safeModel(process.env.HUNCH_SYNTH_MODEL, "haiku");
     async available() {
         try {
             await pexecIn("claude", ["--version"], { timeout: 8000 });
@@ -242,7 +254,7 @@ class ClaudeCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 class CodexCliProvider extends CliSynthProvider {
     name = "codex-cli";
-    model = process.env.HUNCH_CODEX_MODEL; // omit → codex uses its configured default
+    model = safeModel(process.env.HUNCH_CODEX_MODEL, undefined); // omit → codex uses its configured default
     async available() {
         try {
             await pexecIn("codex", ["--version"], { timeout: 8000 });
@@ -266,7 +278,7 @@ class CodexCliProvider extends CliSynthProvider {
 // --------------------------------------------------------------------------
 class CursorCliProvider extends CliSynthProvider {
     name = "cursor-agent";
-    model = process.env.HUNCH_CURSOR_MODEL;
+    model = safeModel(process.env.HUNCH_CURSOR_MODEL, undefined);
     async available() {
         try {
             await pexecIn("cursor-agent", ["--version"], { timeout: 8000 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "0.14.0",
+  "version": "0.14.2",
   "license": "MIT",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Hunch — an Engineering Memory OS: a persistent, git-native reasoning graph over a codebase, exposed to Claude Code via MCP.",
@@ -20,7 +20,8 @@
     "dist/**/*.js"
   ],
   "publishConfig": {
-    "access": "public"
+    "access": "public",
+    "provenance": true
   },
   "keywords": [
     "claude-code",