@davesheffer/hunch 1.10.0 → 1.10.2

package/dist/extractors/git.js

@@ -166,6 +166,39 @@ function canonicalPath(path) {
 export function gitNullDevice() {
     return process.platform === "win32" ? "NUL" : devNull;
 }
+/** How long a live gitindex.lock can plausibly be held: every Hunch git spawn
+ *  carries a timeout well under this, so an OLDER lock provably has no living
+ *  owner in any Hunch flow. */
+const STALE_INDEX_LOCK_MS = 30_000;
+/** Heal a stranded `.git/index.lock` (issue #53). Two ways one appears:
+ *  (a) THIS call's git was timeout-killed — TerminateProcess on Windows skips
+ *      git's cleanup, so a lock created at/after this attempt started is ours;
+ *  (b) a PREVIOUS run crashed/was killed — git then fails FAST forever after,
+ *      and the best-effort flush paths swallow it, so captures keep "succeeding"
+ *      while nothing commits. A pre-existing lock older than any live git's
+ *      possible hold time has no living owner and is safe to remove.
+ *  Returns true when a lock was removed (a retry is then sensible). */
+function clearStrandedIndexLock(repoDir, env, sinceMs, error) {
+    const killed = error?.code === "ETIMEDOUT" || !!error?.signal;
+    try {
+        const rel = execFileSync("git", ["-C", repoDir, "rev-parse", "--git-path", "index.lock"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 5_000,
+        }).trim();
+        const lockPath = isAbsolute(rel) ? rel : join(repoDir, rel);
+        const mtimeMs = statSync(lockPath).mtimeMs;
+        const stranded = killed
+            ? mtimeMs >= sinceMs // created by the git we just killed
+            : mtimeMs <= Date.now() - STALE_INDEX_LOCK_MS; // left behind long before this attempt
+        if (!stranded)
+            return false;
+        rmSync(lockPath, { force: true });
+        console.error(`hunch: removed a stranded index.lock at "${repoDir}" (${killed ? "this git operation timed out" : "left by an earlier interrupted git"}); retrying.`);
+        return true;
+    }
+    catch {
+        return false; // no lock present, or git itself unavailable — nothing to heal
+    }
+}
 /** Compare physical directory identity before path text. Git for Windows can
  * return an 8.3/short or differently-cased spelling for the same top-level
  * directory that Node reached through its long path. A nonzero file ID keeps
@@ -515,13 +548,21 @@ export function commitAndPushHunch(hunchDir, message, opts) {
             GIT_ATTR_NOSYSTEM: "1",
         });
         const run = (args) => {
-            try {
-                execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
-                return true;
-            }
-            catch {
-                return false; // best-effort: nothing staged / not a repo / offline
+            for (let attempt = 0; attempt < 2; attempt++) {
+                const startedAt = Date.now();
+                try {
+                    execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+                    return true;
+                }
+                catch (error) {
+                    // best-effort: nothing staged / not a repo / offline — EXCEPT a
+                    // stranded index.lock, which would otherwise fail every future
+                    // flush silently (issue #53); heal it and retry once.
+                    if (!clearStrandedIndexLock(hunchDir, env, startedAt, error))
+                        return false;
+                }
             }
+            return false;
         };
         if (opts.push !== false) {
             if (!overlayAttributeSourcesAreSafe(hunchDir, env)) {
@@ -598,18 +639,29 @@ export function commitAndPushHunch(hunchDir, message, opts) {
         if (!hooksDir)
             return null;
         const commitPaths = [...memoryPaths, ...(opts.alsoStage ?? [])];
-        try {
-            execFileSync("git", [
-                "-C", hunchDir,
-                "-c", `core.hooksPath=${hooksDir}`,
-                ...(opts.push === false ? [] : ["-c", `core.attributesFile=${gitNullDevice()}`]),
-                "-c", "core.autocrlf=false",
-                "-c", "commit.gpgsign=false",
-                "commit", "--no-gpg-sign", "--only", "-m", message, "--", ...commitPaths,
-            ], { stdio: "ignore", env, timeout: 15_000 });
-            committed = true;
+        // One retry after healing a stranded index.lock (issue #53): a lock left by
+        // a timeout-killed or crashed git otherwise fails EVERY later flush fast and
+        // silently — captures keep reporting success while nothing commits.
+        for (let attempt = 0; attempt < 2 && !committed; attempt++) {
+            const commitStartedAt = Date.now();
+            try {
+                execFileSync("git", [
+                    "-C", hunchDir,
+                    "-c", `core.hooksPath=${hooksDir}`,
+                    ...(opts.push === false ? [] : ["-c", `core.attributesFile=${gitNullDevice()}`]),
+                    "-c", "core.autocrlf=false",
+                    "-c", "commit.gpgsign=false",
+                    "commit", "--no-gpg-sign", "--only", "-m", message, "--", ...commitPaths,
+                ], { stdio: "ignore", env, timeout: 15_000 });
+                committed = true;
+            }
+            catch (error) {
+                // Nothing staged / not a repo stays quiet, as before; only a healed
+                // stranded lock earns the single retry.
+                if (!clearStrandedIndexLock(hunchDir, env, commitStartedAt, error))
+                    break;
+            }
         }
-        catch { /* nothing staged / not a repo */ }
         if (!committed)
             return null;
         if (opts.push !== false) {
@@ -659,6 +711,22 @@ export function isGitCleanPath(root, rel) {
         return false;
     }
 }
+/** The committed (HEAD) content of a tracked file, or null when the path is
+ *  untracked/absent at HEAD or git is unavailable. Used to decide whether a
+ *  dirty grounding doc differs from HEAD ONLY inside its generated section
+ *  (the stranded-grounding heal, fnd_b269d5c422). */
+export function headFileContent(root, rel) {
+    try {
+        return execFileSync("git", ["-C", root, "show", `HEAD:${rel.replace(/\\/g, "/")}`], {
+            encoding: "utf8",
+            env: foreignRepoEnv(process.env),
+            maxBuffer: 16 * 1024 * 1024,
+        });
+    }
+    catch {
+        return null;
+    }
+}
 /** Is the staged set a clean, MEMORY-ONLY change — only JSON record adds/updates, nothing else?
  *  The overlay store is entirely JSON (decisions/, bugs/, …, manifest.json). A real memory sync
  *  is purely additive; a DELETION, rename, or any non-.json staged path means hunchDir is NOT a
@@ -1123,6 +1191,7 @@ function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories
     if (!hooksDir)
         return "failed";
     const tryGit = (args, timeout = timeoutMs) => {
+        const startedAt = Date.now();
         try {
             execFileSync("git", [
                 "-C", hunchDir,
@@ -1136,7 +1205,10 @@ function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories
             });
             return true;
         }
-        catch {
+        catch (error) {
+            // Same stranding class as the commit path: a timeout-killed merge/fetch
+            // leaves index.lock behind and wedges every later sync (issue #53).
+            clearStrandedIndexLock(hunchDir, env, startedAt, error);
             return false;
         }
     };
@@ -1522,6 +1594,13 @@ function waitForCommitLockHandoff(lock, first, timeoutMs) {
         Atomics.wait(sleeper, 0, 0, Math.min(25, deadline - Date.now()));
         attempt = acquireCommitLock(lock);
     }
+    // The deadline can expire DURING the final wait+acquire; without this check an
+    // acquire that succeeded on that last iteration returned false while this
+    // process's owner directory held the lock — never released (the caller bails
+    // before its try/finally), wedging every flush in every process until this one
+    // exited (issue #48).
+    if (attempt.state === "acquired")
+        return true;
     return false;
 }
 export function headSha(cwd) {
@@ -1595,7 +1674,7 @@ export function currentBranch(cwd) {
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export function commitFiles(sha, cwd) {
-    const out = gitSafe(["diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha], cwd);
+    const out = gitSafe(["-c", "core.quotePath=false", "diff-tree", "--no-commit-id", "--name-only", "-r", "--root", sha], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
 /** Raw `git log` over `.hunch/`, paired with parseMemoryLog — the memory-move
@@ -2011,7 +2090,7 @@ export function fileGitMetrics(cwd, want, days = 90) {
         return out;
     // churn — one windowed log; tally each wanted path's appearances (= commits).
     if (days > 0) {
-        const raw = gitSafe(["log", `--since=${days}.days.ago`, "--name-only", "--format="], cwd);
+        const raw = gitSafe(["-c", "core.quotePath=false", "log", `--since=${days}.days.ago`, "--name-only", "--format="], cwd);
         if (raw) {
             for (const line of raw.split("\n")) {
                 const e = line && out.get(line);
@@ -2023,7 +2102,7 @@ export function fileGitMetrics(cwd, want, days = 90) {
     // last commit — one newest-first log; the FIRST time a path appears is its most
     // recent commit. NUL-prefixed lines mark commit boundaries; the rest are paths.
     // 256MB buffer for the all-history name-only stream on large repos.
-    const raw = gitSafe(["log", "--name-only", "--format=%x00%h"], cwd, 256 * 1024 * 1024);
+    const raw = gitSafe(["-c", "core.quotePath=false", "log", "--name-only", "--format=%x00%h"], cwd, 256 * 1024 * 1024);
     if (raw) {
         let remaining = out.size;
         let sha = "";
@@ -2044,17 +2123,23 @@ export function fileGitMetrics(cwd, want, days = 90) {
     }
     return out;
 }
-/** Files staged for commit (for `hunch check` pre-commit enforcement). */
+/** Files staged for commit (for `hunch check` pre-commit enforcement).
+ *
+ *  Every path enumerator here pins `core.quotePath=false` (issue #50): with
+ *  git's default quotePath, any path holding bytes > 0x7F comes back
+ *  octal-quoted (`"src/caf\303\251.ts"`), which matches neither the store's
+ *  POSIX paths nor constraint scope globs — a blocking constraint over such a
+ *  file graded as a vacuous PASS, and its churn/last-commit metrics read zero. */
 export function stagedFiles(cwd) {
-    const out = gitSafe(["diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd);
+    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
 /** Files changed anywhere in the working tree compared with HEAD: both staged
  * and unstaged tracked files, plus untracked files. This powers the local,
  * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
 export function workingFiles(cwd) {
-    const changed = gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
-    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
+    const changed = gitSafe(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
+    const untracked = gitSafe(["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
     return [...new Set([...changed, ...untracked])].sort();
 }
 /** Does a ref resolve to a commit in this repo? Lets `--base` fail LOUDLY on an
@@ -2066,7 +2151,7 @@ export function revExists(ref, cwd) {
 /** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
  *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
 export function rangeFiles(base, cwd, head = "HEAD") {
-    const out = gitSafe(["diff", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
+    const out = gitSafe(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
 /** Commit subjects on `head` since `base` (2-dot: commits added by the task),
@@ -2095,8 +2180,8 @@ export function stagedDiff(cwd, maxBytes = 60_000) {
  * intentionally contribute no synthetic content to regression analysis. */
 export function workingDiff(cwd, maxBytes = 60_000) {
     let out = gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
-    const tracked = new Set(gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
-    const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
+    const tracked = new Set(gitSafe(["-c", "core.quotePath=false", "diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
+    const untracked = gitSafe(["-c", "core.quotePath=false", "ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
     const readWorkingFile = createRepoFileReader(cwd);
     for (const file of untracked) {
         try {
@@ -2146,7 +2231,7 @@ export function fixCommits(spec, cwd, max = 200) {
 }
 /** All tracked files matching the given extensions. */
 export function trackedFiles(cwd, exts) {
-    const out = gitSafe(["ls-files"], cwd);
+    const out = gitSafe(["-c", "core.quotePath=false", "ls-files"], cwd);
     const all = out ? out.split("\n").filter(Boolean) : [];
     return all.filter((f) => exts.some((e) => f.endsWith(e)));
 }

package/dist/extractors/languages.js

@@ -6,19 +6,25 @@
  * four files.
  */
 import { loadNativeTreeSitter } from "./nativeTreeSitter.js";
-const TS_QUERY = `
-  (function_declaration name: (identifier) @fn.name) @fn.def
-  (generator_function_declaration name: (identifier) @fn.name) @fn.def
-  (method_definition name: (property_identifier) @method.name) @method.def
-  (class_declaration name: (type_identifier) @class.name) @class.def
-  (interface_declaration name: (type_identifier) @iface.name) @iface.def
-  (type_alias_declaration name: (type_identifier) @type.name) @type.def
-  (variable_declarator
-     name: (identifier) @arrow.name
-     value: [(arrow_function) (function_expression)]) @arrow.def
-  (import_statement source: (string) @import.src)
-  (call_expression function: (identifier) @call.id)
-  (call_expression function: (member_expression property: (property_identifier) @call.member))
+const TS_QUERY = `
+  (function_declaration name: (identifier) @fn.name) @fn.def
+  (generator_function_declaration name: (identifier) @fn.name) @fn.def
+  (method_definition name: (property_identifier) @method.name) @method.def
+  (class_declaration name: (type_identifier) @class.name) @class.def
+  (interface_declaration name: (type_identifier) @iface.name) @iface.def
+  (type_alias_declaration name: (type_identifier) @type.name) @type.def
+  (variable_declarator
+     name: (identifier) @arrow.name
+     value: [(arrow_function) (function_expression)]) @arrow.def
+  (import_statement source: (string) @import.src)
+  (call_expression function: (identifier) @call.id)
+  (call_expression function: (member_expression property: (property_identifier) @call.member))
+  ;; Construction IS a call. Without these, \`new Foo()\` produced no edge at all, so
+  ;; every class in a TS/JS repo had fan_in 0: blast radius before a constructor
+  ;; change came back empty, and a \`not-calls\` conformance predicate over a class
+  ;; could never see its own counterexample.
+  (new_expression constructor: (identifier) @call.id)
+  (new_expression constructor: (member_expression property: (property_identifier) @call.member))
 `;
 const TS_BUILTIN_METHODS = new Set([
     "map", "filter", "forEach", "reduce", "find", "findIndex", "some", "every", "includes",
@@ -65,21 +71,28 @@ const TSX = {
     grammarKey: "tsx",
     loadGrammar: () => loadNativeTreeSitter().tsx,
 };
-const PY_QUERY = `
-  (class_definition
-    name: (identifier) @class.name
-    body: (block
-      [
-        (function_definition name: (identifier) @method.name) @method.def
-        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
-      ])) @class.def
-  (function_definition name: (identifier) @fn.name) @fn.def
-  (import_statement name: (dotted_name) @import.src)
-  (import_statement name: (aliased_import name: (dotted_name) @import.src))
-  (import_from_statement module_name: (dotted_name) @import.src)
-  (import_from_statement module_name: (relative_import) @import.src)
-  (call function: (identifier) @call.id)
-  (call function: (attribute attribute: (identifier) @call.member))
+const PY_QUERY = `
+  (class_definition
+    name: (identifier) @class.name
+    body: (block
+      [
+        (function_definition name: (identifier) @method.name) @method.def
+        (decorated_definition definition: (function_definition name: (identifier) @method.name) @method.def)
+      ])) @class.def
+  ;; Every class, including one with no directly-nested def: dataclasses, Exception
+  ;; subclasses, Enums, TypedDicts and pydantic models are method-less by design and
+  ;; were invisible to the entire graph (no symbol, no component, no edges), so
+  ;; \`hunch why\` and blast radius came back empty for exactly the classes a refactor
+  ;; breaks. parse.ts keys pendingDefs by node id and keeps the first classification,
+  ;; so a class that ALSO matches the method-bearing pattern above is not duplicated.
+  (class_definition name: (identifier) @class.name) @class.def
+  (function_definition name: (identifier) @fn.name) @fn.def
+  (import_statement name: (dotted_name) @import.src)
+  (import_statement name: (aliased_import name: (dotted_name) @import.src))
+  (import_from_statement module_name: (dotted_name) @import.src)
+  (import_from_statement module_name: (relative_import) @import.src)
+  (call function: (identifier) @call.id)
+  (call function: (attribute attribute: (identifier) @call.member))
 `;
 const PY_BUILTIN_METHODS = new Set([
     "get", "set", "keys", "values", "items", "pop", "popitem", "update", "setdefault", "copy", "clear",

package/dist/extractors/nativeTreeSitter.js

@@ -64,7 +64,12 @@ function copyNativeBinding(packageName, copyRoot, nodeGypBuild) {
 export function loadNativeTreeSitter() {
     if (runtime)
         return runtime;
-    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /tree-sitter(?:-typescript|-python)?\.node$/.test(path)
+    // Both binding spellings: prebuilds ship as tree-sitter[-typescript|-python].node,
+    // while from-source builds are named after the binding.gyp target with
+    // underscores (tree_sitter_runtime_binding.node, tree_sitter_python_binding.node,
+    // …). Missing the underscore names let an already-loaded source-built addon slip
+    // past this guard and defeat the file-lock isolation entirely (issue #52).
+    const preloaded = Object.keys(runtimeRequire.cache).filter((path) => /(?:tree-sitter(?:-typescript|-python)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
         && !new RegExp(`(?:^|[\\\\/])${COPY_PREFIX}\\d+-`).test(path));
     if (preloaded.length) {
         throw new Error(`tree-sitter native addon was loaded before Hunch could isolate it: ${preloaded.join(", ")}`);

package/dist/extractors/testreport.js

@@ -56,7 +56,8 @@ export function parseTestReport(output) {
         // Collect the following more-indented diagnostic block as the message.
         const baseIndent = leadingSpaces(raw);
         const block = [];
-        for (let j = i + 1; j < lines.length; j++) {
+        let j = i + 1;
+        for (; j < lines.length; j++) {
             const ln = lines[j];
             if (ln.trim() === "") {
                 block.push("");
@@ -68,6 +69,11 @@ export function parseTestReport(output) {
         }
         const diag = block.join("\n").trim();
         failMap.set(name, { test: name, message: diag ? `${name}\n${diag}` : name });
+        // Skip the consumed diagnostic block (issue #51): re-visiting it let
+        // TAP-looking text QUOTED INSIDE an error message (assertion diffs in this
+        // very repo quote "ok N - …" lines) parse as real results — a phantom pass
+        // can mark a previously-open bug fixed without any test having re-run.
+        i = j - 1;
     }
     // A test can legitimately appear as both (flaky retry) — trust the failure.
     for (const name of failMap.keys())

package/dist/integrations/claudemd.js

@@ -3,12 +3,24 @@
  * context loaded every session for free"). We own ONLY the region between the
  * HUNCH markers — any user-authored content outside it is preserved verbatim.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
+import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
 const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
 const END = "<!-- HUNCH:END -->";
+/** Remove the managed HUNCH section (markers inclusive), leaving only the
+ *  user-authored surroundings. Lets a caller decide whether two versions of a
+ *  doc differ ONLY in generated content (the stranded-grounding heal,
+ *  fnd_b269d5c422): equal outside the block ⇒ regenerating cannot lose prose. */
+export function stripManagedSection(text) {
+    const iStart = text.indexOf(START);
+    const iEnd = text.indexOf(END);
+    if (iStart < 0 || iEnd <= iStart)
+        return text;
+    return text.slice(0, iStart) + text.slice(iEnd + END.length);
+}
 export function renderHunchSection(store, root) {
     const constraints = store.json
         .loadAll("constraints")
@@ -103,12 +115,14 @@ export function upsertSection(file, section, fallbackTitle) {
         content = `${fallbackTitle}\n\n${section}\n`;
     }
     mkdirSync(dirname(file), { recursive: true }); // e.g. .github/ for copilot-instructions
-    writeFileSync(file, content);
+    // Atomic: this file carries the USER'S prose around the managed block — a torn
+    // write must not be able to truncate it (issue #43).
+    writeFileAtomic(file, content);
     return file;
 }
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
 export function updateClaudeMd(root, store) {
-    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${root.split("/").pop()}`);
+    return upsertSection(join(root, "CLAUDE.md"), renderHunchSection(store, root), `# ${basename(root)}`);
 }
 function sev(s) {
     return { blocking: 3, warning: 2, advisory: 1 }[s] ?? 0;

package/dist/integrations/providers.js

@@ -17,11 +17,12 @@
  * Every writer MERGES into existing files (preserving other servers / user prose)
  * and is idempotent, so re-running `hunch init` is safe.
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
-import { renderHunchSection, upsertSection, updateClaudeMd } from "./claudemd.js";
-import { isGitCleanPath } from "../extractors/git.js";
+import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
+import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 /** Strip // line and block comments + trailing commas (JSONC → JSON). String-aware
  *  (double-quoted, with escapes) so a // inside a value isn't mangled. VS Code's
  *  .vscode/mcp.json is JSONC, so we must tolerate comments. */
@@ -135,7 +136,9 @@ function tomlStr(s) {
 }
 function writeJson(file, obj) {
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, JSON.stringify(obj, null, 2) + "\n");
+    // Atomic: these files hold the USER'S merged servers/hooks — a torn write would
+    // leave them unparseable, which every writer here then refuses to touch (#43).
+    writeFileAtomic(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
 /** Provider hook commands live in tracked config files, so use the structured
@@ -148,7 +151,14 @@ function hookCommand(inv, provider) {
 function isHunchProviderHook(entry) {
     const e = entry && typeof entry === "object" ? entry : null;
     const command = typeof e?.command === "string" ? e.command : "";
-    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command) && /\bhook\b/.test(command);
+    // Anchored to the exact shape hookCommand() writes — JSON-quoted parts ending
+    // in "hook" "--provider" "<name>" — plus a Hunch launcher (the pinned npm
+    // package spec, or a quoted …/index.js|ts path for source installs). The old
+    // unanchored /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries
+    // like `node ./hook/index.js` as ours and silently deleted them, violating
+    // the leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41).
+    return /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts)")/.test(command)
+        && /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
 }
 /** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
  * We replace only old Hunch commands and leave every foreign hook in place. */
@@ -255,7 +265,7 @@ export function writeCodexConfig(root, inv) {
     }
     base = base.trimEnd();
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    writeFileAtomic(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
     return file;
 }
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
@@ -273,7 +283,7 @@ export function writeCursorRule(root, store) {
     const file = join(root, ".cursor", "rules", "hunch.mdc");
     const body = `---\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\nalwaysApply: true\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, body);
+    writeFileAtomic(file, body);
     return file;
 }
 /** Windsurf (Cascade): .windsurf/mcp_config.json — same `mcpServers` shape as
@@ -308,7 +318,7 @@ export function writeWindsurfRule(root, store) {
     const file = join(root, ".windsurf", "rules", "hunch.md");
     const body = `---\ntrigger: always_on\ndescription: Hunch engineering memory — consult the hunch_* MCP tools before editing\n---\n\n${renderHunchSection(store, root)}\n`;
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, body);
+    writeFileAtomic(file, body);
     return file;
 }
 /** Cursor's hook API is beta, but its project-level config accepts this standard
@@ -434,22 +444,50 @@ export function refreshExistingGrounding(root, store) {
     }
     return changed;
 }
-/** Capture-commit refresh: rewrite ONLY grounding docs that are git-clean, and return the
- *  absolute paths of the ones that changed so the caller folds them into the memory commit
- *  (commitAndPushHunch alsoStage). This keeps committed record counts permanently true —
- *  every capture used to bump the count and re-stale the committed docs, failing the
- *  release gate's clean-tree check on the next CI index (the refresh-counts treadmill).
- *  A user-dirty or untracked doc is left completely untouched (never refreshed, never
- *  staged); it heals on the next manual `hunch sync` or `hunch index`. */
+/** Wholly-Hunch-owned grounding docs (namespaced rule files the generators emit
+ *  in full). Any dirt in these is generated dirt by contract — there is no user
+ *  prose to protect, so a stale copy is always safe to regenerate and stage. */
+const WHOLLY_OWNED_GROUNDING = new Set([
+    join(".cursor", "rules", "hunch.mdc"),
+    join(".windsurf", "rules", "hunch.md"),
+]);
+/** Is a DIRTY grounding doc's divergence from HEAD confined to generated content?
+ *  Marker-managed docs (CLAUDE.md, AGENTS.md, copilot-instructions): compare
+ *  worktree vs HEAD with the managed section stripped from both — equal outside
+ *  the block means regenerating cannot lose user prose. Wholly-owned rule files
+ *  need no comparison. Untracked files return false: a doc the user hasn't
+ *  committed is theirs to stage. */
+function generatedDirtOnly(root, rel, current) {
+    if (WHOLLY_OWNED_GROUNDING.has(rel))
+        return headFileContent(root, rel) !== null;
+    const head = headFileContent(root, rel);
+    if (head === null)
+        return false;
+    return stripManagedSection(head) === stripManagedSection(current);
+}
+/** Capture-commit refresh: rewrite grounding docs that are git-clean OR whose only
+ *  divergence from HEAD is generated content, and return the absolute paths to fold
+ *  into the memory commit (commitAndPushHunch alsoStage). This keeps committed record
+ *  counts permanently true — every capture used to bump the count and re-stale the
+ *  committed docs, failing the release gate's clean-tree check on the next CI index
+ *  (the refresh-counts treadmill). The generated-dirt branch closes the second half
+ *  (fnd_b269d5c422): once a doc went stale-dirty, the clean-only rule skipped it on
+ *  every later flush FOREVER, and each release needed a manual chore commit. A doc
+ *  whose USER PROSE differs from HEAD is still left completely untouched. */
 export function refreshCommittableGrounding(root, store) {
     const changed = [];
     for (const [rel, write] of groundingTargets(root, store)) {
         const file = join(root, rel);
-        if (!existsSync(file) || !isGitCleanPath(root, rel))
+        if (!existsSync(file))
             continue;
         const before = readFileSync(file, "utf8");
+        const clean = isGitCleanPath(root, rel);
+        if (!clean && !generatedDirtOnly(root, rel, before))
+            continue;
         write();
-        if (readFileSync(file, "utf8") !== before)
+        // A doc that was stale-DIRTY must be staged even when the regeneration is a
+        // byte no-op — the commit is what re-syncs HEAD with the worktree.
+        if (readFileSync(file, "utf8") !== before || !clean)
             changed.push(file);
     }
     return changed;

package/dist/integrations/scaffold.js

@@ -3,7 +3,8 @@
  *   - .mcp.json          → registers the `hunch` MCP server with Claude Code
  *   - .claude/commands/* → user-triggered slash commands for the §5 workflows
  */
-import { readFileSync, writeFileSync, existsSync, mkdirSync } from "node:fs";
+import { readFileSync, existsSync, mkdirSync } from "node:fs";
+import { writeFileAtomic } from "../core/io.js";
 import { join, dirname } from "node:path";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers.
  *  A non-empty file we cannot parse THROWS instead of being silently replaced
@@ -28,7 +29,9 @@ export function writeMcpJson(root, inv) {
     }
     json.mcpServers = json.mcpServers ?? {};
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
-    writeFileSync(file, JSON.stringify(json, null, 2) + "\n");
+    // Atomic: .mcp.json holds the user's other servers — a torn write would leave
+    // it unparseable, which this writer then refuses to touch (issue #43).
+    writeFileAtomic(file, JSON.stringify(json, null, 2) + "\n");
     return file;
 }
 const WHY_CMD = `---
@@ -168,13 +171,17 @@ export function installClaudeHooks(root, hookCmd) {
     if (existed && before === next)
         return { path: file, action: "unchanged" };
     mkdirSync(dirname(file), { recursive: true });
-    writeFileSync(file, next);
+    writeFileAtomic(file, next);
     return { path: file, action: existed ? "updated" : "created" };
 }
+/** Ownership marker for generated slash commands: its presence means Hunch may
+ *  refresh the file; deleting the line hands the file to the user for good. */
+const CMD_MARKER = "<!-- hunch:generated — refreshed by hunch init; delete this line to take ownership -->";
 export function writeSlashCommands(root) {
     const dir = join(root, ".claude", "commands");
     mkdirSync(dir, { recursive: true });
     const written = [];
+    const skipped = [];
     const files = [
         ["hunch-why.md", WHY_CMD],
         ["hunch-fix.md", FIX_CMD],
@@ -185,9 +192,18 @@ export function writeSlashCommands(root) {
     ];
     for (const [name, body] of files) {
         const p = join(dir, name);
-        writeFileSync(p, body);
+        // Generic names (capture/heal/audit) are plausibly the USER'S OWN commands;
+        // hunch-prefixed names are namespaced ours. Overwrite an existing file only
+        // when it carries the ownership marker or the hunch- namespace — never
+        // silently replace user content (issue #42). Pre-marker Hunch installs skip
+        // once and report; re-adopt by deleting the file and re-running init.
+        if (existsSync(p) && !name.startsWith("hunch-") && !readFileSync(p, "utf8").includes("hunch:generated")) {
+            skipped.push(p);
+            continue;
+        }
+        writeFileAtomic(p, `${body}\n${CMD_MARKER}\n`);
         written.push(p);
     }
-    return written;
+    return { written, skipped };
 }
 //# sourceMappingURL=scaffold.js.map