@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/core/taskReportHook.d.ts

@@ -39,7 +39,7 @@ export declare function taskInstruction(task: {
 }, cwdLiteral: string, provider: HookProvider, launcher?: () => {
     shell: string;
     note?: string;
-}): string;
+}, form?: "full" | "compact"): string;
 /** A prompt the host generated to report a background command's completion,
  * not something the user typed. */
 export declare function isNotificationPrompt(prompt: string | undefined): boolean;

package/dist/core/taskReportHook.js

@@ -9,6 +9,7 @@ import { aliasReportTask, continuationLinks, finishReportTask, isEmptyTaskReport
 import { reportSourceSnapshot } from "./taskReportEvidence.js";
 import { renderTaskReport } from "./taskReportRender.js";
 import { verificationLauncher } from "./verifyLauncher.js";
+import { injectionMode } from "./hookcache.js";
 /** The exact task identity a native host prompt maps to. */
 export function promptTaskId(root, sessionId, promptId, agentId = null, provider = "claude") {
     return `htask_${reportHash([canonicalReportRoot(root), provider, sessionId, promptId, agentId]).slice(7, 31)}`;
@@ -144,7 +145,7 @@ export function startHookReport(root, provider, event) {
             // this prompt's Stop and hook observations report to that task.
             if (previous && previous.task_id !== id && isNotificationPrompt(event.prompt) && previous.closed_by !== "agent") {
                 aliasReportTask(root, id, previous.task_id);
-                return taskInstruction(previous, cwdLiteral, provider);
+                return sessionTaskInstruction(previous, cwdLiteral, provider, event.session_id);
             }
             const continued = previous && previous.task_id !== id ? continuationLinks(previous) : null;
             if (continued)
@@ -165,7 +166,18 @@ export function startHookReport(root, provider, event) {
             throw error;
         task = existing;
     }
-    return taskInstruction(task, cwdLiteral, provider);
+    return sessionTaskInstruction(task, cwdLiteral, provider, event.session_id);
+}
+/** The generic rules are the same on every prompt of a session; only the ID and
+ * the launcher line change. Print them in full once per session (and again after
+ * compaction, which resets the dedup map), then a compact line that still carries
+ * everything the prompt needs: its ID, cwd, verify command, no-start and finish
+ * rule. The dedup key hashes the full wording for a placeholder task, so a new
+ * launcher or rule text is delivered in full again. Fail-open: any cache error
+ * yields the full form (injectionMode never throws and defaults to "full"). */
+function sessionTaskInstruction(task, cwdLiteral, provider, sessionId) {
+    const rules = taskInstruction({ task_id: "htask_" + "0".repeat(24), title: NATIVE_TASK_TITLE }, "\"<cwd>\"", provider);
+    return taskInstruction(task, cwdLiteral, provider, verificationLauncher, injectionMode(sessionId, "prompt-task-rules", rules) === "delta" ? "compact" : "full");
 }
 /** The hook already opened the task, so the model needs no start call: the only
  * thing start used to supply was verification_argv, and the launcher is printed
@@ -179,11 +191,15 @@ export function startHookReport(root, provider, event) {
  * cannot be computed, fall back to asking for the start call — that path is then
  * the only source of both the launcher and the finish instruction, so it carries
  * its own finish sentence. */
-export function taskInstruction(task, cwdLiteral, provider, launcher = verificationLauncher) {
+export function taskInstruction(task, cwdLiteral, provider, launcher = verificationLauncher, form = "full") {
     const head = `Hunch has already opened this prompt's report: ${task.task_id}. Reuse this exact ID; never open another report. Pass this task_id and cwd: ${cwdLiteral} to hunch_context and decision/correction/finding captures.`;
     let verify;
     try {
         const l = launcher();
+        if (form === "compact") {
+            const finishRule = HOST_CLOSES_TASK.has(provider) ? "finish only if this task used Hunch" : `finish it yourself with hunch_task(action: "finish", task_id, cwd)`;
+            return `Hunch report for this prompt: ${task.task_id} (cwd: ${cwdLiteral}). Use it instead of any earlier ID. Never call hunch_task start. Checks: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Same rules as this session's first report; ${finishRule}.`;
+        }
         verify = ` Never call hunch_task start for it. For checks, run: ${l.shell} task verify ${task.task_id} -- <command> [arguments]${l.note ?? ""}. Default budget 15 min; add --timeout <seconds> before -- for longer suites.`;
     }
     catch {

package/dist/extractors/git.d.ts

@@ -19,6 +19,12 @@ export declare function gitWorktreeRoot(cwd: string): string | null;
  * `.hunch-private/.hunch` can never stage or commit into the code repository. */
 export declare function isGitRepoRoot(cwd: string): boolean;
 export declare function gitNullDevice(): string;
+/** 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
+ * this exact even on case-sensitive Windows directories; canonical text is a
+ * conservative fallback for filesystems that do not expose stable IDs. */
+export declare function sameFilesystemEntry(left: string, right: string): boolean;
 /** Whether two paths resolve to the same repository identity. Comparing only
  * worktree roots is insufficient: linked worktrees have different roots but
  * share one Git common directory and therefore one publishable history. */
@@ -156,6 +162,31 @@ export declare function gitDir(cwd: string): string;
  *  `gitDir`, which is per-worktree). Absolute, so callers can anchor worktree-shared
  *  state (the private-overlay pointer) at one stable place. "" when not a git repo. */
 export declare function gitCommonDir(cwd: string): string;
+/** The git common dir for `cwd`, but only when Git reached it through the worktree's own
+ *  `.git` entry and that entry is one Git itself set up (gitDirServesWorktree). Checkout
+ *  content can never supply a `.git` entry through Git (Git refuses to track `.git`), but
+ *  an extracted archive can, so the entry alone proves nothing. A directory that merely
+ *  looks like a repository (HEAD/objects/refs/config committed as ordinary files) is never
+ *  accepted, whichever Git version runs. "" when there is no such repo. */
+export declare function checkoutCommonDir(cwd: string): string;
+/** Hunch's back-link inside a separate git dir, naming the one checkout it serves. Git
+ *  records nothing for `git init --separate-git-dir` (no `core.worktree`, no worktree
+ *  registry entry), so without this a `.git` file could name any repository's git dir. */
+export declare function separateGitDirLink(gitdir: string): string;
+/** Explicit setup (`hunch private` / `hunch shared` / `hunch worktree`) run in a checkout
+ *  created by `git init --separate-git-dir`: record that this checkout owns its git dir,
+ *  then resolve it through checkoutCommonDir. Called ONLY from a command the user ran in
+ *  this checkout — never while opening a store, so repository content can never claim a
+ *  git dir. Refuses another checkout's own `.git` directory, a git dir inside the
+ *  checkout, a symlinked `.git`, and a git dir whose back-link names a different checkout
+ *  whose `.git` file still names it. "" when this is not such a layout. */
+export declare function claimSeparateGitDir(cwd: string): string;
+/** The separate git dir claimSeparateGitDir WOULD claim for `cwd`, without writing
+ *  anything (setup snapshots it for rollback). null when the layout is not claimable. */
+export declare function separateGitDirCandidate(cwd: string): {
+    gitDir: string;
+    top: string;
+} | null;
 /** True when `cwd` is inside a LINKED worktree (not the main checkout): its own git
  *  dir differs from the shared common dir. Used by `hunch doctor` and setup messaging. */
 export declare function isLinkedWorktree(cwd: string): boolean;

package/dist/extractors/git.js

@@ -7,6 +7,7 @@ import { isAbsolute, resolve, join, basename, dirname, relative, sep, posix } fr
 import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
+import { writeFileAtomic } from "../core/io.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
 import { createRepoFileReader } from "../core/safeRepoFile.js";
 import { DIFF_TRUNCATED_LINE } from "./diff.js";
@@ -227,7 +228,7 @@ function clearStrandedIndexLock(repoDir, env, sinceMs, error) {
  * directory that Node reached through its long path. A nonzero file ID keeps
  * this exact even on case-sensitive Windows directories; canonical text is a
  * conservative fallback for filesystems that do not expose stable IDs. */
-function sameFilesystemEntry(left, right) {
+export function sameFilesystemEntry(left, right) {
     try {
         const leftStat = statSync(left, { bigint: true });
         const rightStat = statSync(right, { bigint: true });
@@ -1916,6 +1917,184 @@ export function gitCommonDir(cwd) {
         return "";
     return isAbsolute(p) ? p : resolve(cwd, p);
 }
+/** The git common dir for `cwd`, but only when Git reached it through the worktree's own
+ *  `.git` entry and that entry is one Git itself set up (gitDirServesWorktree). Checkout
+ *  content can never supply a `.git` entry through Git (Git refuses to track `.git`), but
+ *  an extracted archive can, so the entry alone proves nothing. A directory that merely
+ *  looks like a repository (HEAD/objects/refs/config committed as ordinary files) is never
+ *  accepted, whichever Git version runs. "" when there is no such repo. */
+export function checkoutCommonDir(cwd) {
+    // Isolated env: a hook's exported GIT_DIR/GIT_COMMON_DIR must not redirect resolution
+    // away from `cwd`'s own layout.
+    const [top, own, commonOut] = gitSafeIsolated(["-c", "safe.bareRepository=explicit", "rev-parse", "--show-toplevel", "--absolute-git-dir", "--git-common-dir"], cwd).split("\n");
+    if (!top || !own || !commonOut)
+        return "";
+    const common = isAbsolute(commonOut) ? commonOut : resolve(cwd, commonOut);
+    const dotGit = join(top, ".git");
+    try {
+        // lstat: Git never creates `.git` as a symlink, so a linked `.git` is treated like a
+        // `.git` file — it must be vouched for by the repository it reaches.
+        const entry = lstatSync(dotGit);
+        const stat = entry.isSymbolicLink() ? statSync(dotGit) : entry;
+        const indirect = entry.isSymbolicLink() || stat.isFile();
+        if (stat.isDirectory()) {
+            if (!sameFilesystemEntry(own, dotGit))
+                return "";
+        }
+        else if (stat.isFile()) {
+            const named = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(dotGit, "utf8"))?.[1];
+            if (!named || !sameFilesystemEntry(own, resolve(top, named)))
+                return "";
+        }
+        else {
+            return "";
+        }
+        if (!gitDirServesWorktree(own, common, top, dotGit, indirect, entry.isSymbolicLink()))
+            return "";
+    }
+    catch {
+        return "";
+    }
+    if (!insideDirectory(cwd, top))
+        return "";
+    return canonicalPath(common);
+}
+/** Whether `path` physically is `dir` or lies below it, by filesystem identity rather than
+ *  path text, so a case variant or firmlink spelling of the same directory still counts.
+ *  The walk starts from the resolved path: a symlink inside `dir` that leads elsewhere does
+ *  not count as inside. */
+function insideDirectory(path, dir) {
+    for (let at = canonicalPath(path);; at = dirname(at)) {
+        if (sameFilesystemEntry(at, dir))
+            return true;
+        if (dirname(at) === at)
+            return false;
+    }
+}
+/** Whether Git itself set up `gitdir` to serve the worktree at `top`, so that `common` is
+ *  genuinely this checkout's repository:
+ *  - `gitdir` IS the common dir (no `commondir` indirection): a real `.git` directory, or,
+ *    reached through a `.git` file or symlink, a repository whose `core.worktree` resolves
+ *    to `top` (a submodule). `git init --separate-git-dir` sets no `core.worktree`, so that
+ *    layout is accepted only through a `.git` FILE (never a symlink) whose git dir lies
+ *    outside the checkout and carries Hunch's back-link naming `top` — written only by
+ *    explicit setup run in that checkout (claimSeparateGitDir);
+ *  - otherwise `gitdir` must be registered in the common dir's own `worktrees/` directory,
+ *    its `gitdir` back-link must name `top/.git`, and that `.git` must not be a symlink.
+ *    A git dir anywhere else can name any repository through a `commondir` file, so it is
+ *    never accepted. */
+function gitDirServesWorktree(gitdir, common, top, dotGit, indirect, symlinked) {
+    if (sameFilesystemEntry(gitdir, common)) {
+        if (!indirect)
+            return true;
+        const worktree = gitSafeIsolated(["config", "--file", join(gitdir, "config"), "--get", "core.worktree"], gitdir);
+        if (worktree)
+            return sameFilesystemEntry(resolve(gitdir, worktree), top);
+        return !symlinked && separateGitDirLinksTo(gitdir, top);
+    }
+    // A linked worktree's back-link names its own `.git` file, and a symlink resolves to the
+    // very file it points at, so the back-link cannot vouch for a symlinked `.git`.
+    if (symlinked)
+        return false;
+    const registry = dirname(canonicalPath(gitdir));
+    if (basename(registry) !== "worktrees" || !sameFilesystemEntry(dirname(registry), common))
+        return false;
+    try {
+        const backLink = readFileSync(join(gitdir, "gitdir"), "utf8").trim();
+        if (!backLink)
+            return false;
+        // Same file AND same parent directory: a hard link to another worktree's `.git` file
+        // shares its inode but not its directory. Identity, not path text, so case variants
+        // and firmlink spellings that Git may have written still match.
+        const named = resolve(gitdir, backLink);
+        return basename(named) === ".git" && sameFilesystemEntry(named, dotGit) && sameFilesystemEntry(dirname(named), top);
+    }
+    catch {
+        return false;
+    }
+}
+/** Hunch's back-link inside a separate git dir, naming the one checkout it serves. Git
+ *  records nothing for `git init --separate-git-dir` (no `core.worktree`, no worktree
+ *  registry entry), so without this a `.git` file could name any repository's git dir. */
+export function separateGitDirLink(gitdir) {
+    return join(gitdir, "hunch", "checkout-root");
+}
+/** Whether a separate git dir is vouched for `top`: it lies outside the checkout (so no
+ *  checkout or archive content can supply it or its back-link) and its Hunch back-link
+ *  names `top`. */
+function separateGitDirLinksTo(gitdir, top) {
+    if (insideDirectory(gitdir, top))
+        return false;
+    try {
+        const linked = readFileSync(separateGitDirLink(gitdir), "utf8").trim();
+        return !!linked && isAbsolute(linked) && sameFilesystemEntry(linked, top);
+    }
+    catch {
+        return false;
+    }
+}
+/** Explicit setup (`hunch private` / `hunch shared` / `hunch worktree`) run in a checkout
+ *  created by `git init --separate-git-dir`: record that this checkout owns its git dir,
+ *  then resolve it through checkoutCommonDir. Called ONLY from a command the user ran in
+ *  this checkout — never while opening a store, so repository content can never claim a
+ *  git dir. Refuses another checkout's own `.git` directory, a git dir inside the
+ *  checkout, a symlinked `.git`, and a git dir whose back-link names a different checkout
+ *  whose `.git` file still names it. "" when this is not such a layout. */
+export function claimSeparateGitDir(cwd) {
+    const candidate = separateGitDirCandidate(cwd);
+    if (!candidate)
+        return "";
+    try {
+        const link = separateGitDirLink(candidate.gitDir);
+        mkdirSync(dirname(link), { recursive: true });
+        writeFileAtomic(link, `${canonicalPath(candidate.top)}\n`);
+    }
+    catch {
+        return "";
+    }
+    return checkoutCommonDir(cwd);
+}
+/** The separate git dir claimSeparateGitDir WOULD claim for `cwd`, without writing
+ *  anything (setup snapshots it for rollback). null when the layout is not claimable. */
+export function separateGitDirCandidate(cwd) {
+    const [top, own, commonOut] = gitSafeIsolated(["-c", "safe.bareRepository=explicit", "rev-parse", "--show-toplevel", "--absolute-git-dir", "--git-common-dir"], cwd).split("\n");
+    if (!top || !own || !commonOut)
+        return null;
+    const common = isAbsolute(commonOut) ? commonOut : resolve(cwd, commonOut);
+    if (!sameFilesystemEntry(own, common) || !insideDirectory(cwd, top))
+        return null;
+    const dotGit = join(top, ".git");
+    const namesOwn = (file) => {
+        try {
+            if (!lstatSync(file).isFile())
+                return false;
+            const named = /^gitdir:\s*(.+?)\s*$/m.exec(readFileSync(file, "utf8"))?.[1];
+            return !!named && sameFilesystemEntry(own, resolve(dirname(file), named));
+        }
+        catch {
+            return false;
+        }
+    };
+    if (!namesOwn(dotGit))
+        return null;
+    if (gitSafeIsolated(["config", "--file", join(own, "config"), "--get", "core.worktree"], own))
+        return null;
+    if (insideDirectory(own, top))
+        return null;
+    try {
+        const parentDotGit = join(dirname(canonicalPath(own)), ".git");
+        if (lstatSync(parentDotGit).isDirectory() && sameFilesystemEntry(parentDotGit, own))
+            return null;
+    }
+    catch { /* not another checkout's embedded .git directory */ }
+    try {
+        const prior = readFileSync(separateGitDirLink(own), "utf8").trim();
+        if (prior && !sameFilesystemEntry(prior, top) && namesOwn(join(prior, ".git")))
+            return null;
+    }
+    catch { /* no back-link yet */ }
+    return { gitDir: canonicalPath(own), top };
+}
 /** True when `cwd` is inside a LINKED worktree (not the main checkout): its own git
  *  dir differs from the shared common dir. Used by `hunch doctor` and setup messaging. */
 export function isLinkedWorktree(cwd) {

package/dist/extractors/nativeTreeSitter.d.ts

@@ -33,7 +33,8 @@ export declare class NativeTreeSitterLoadError extends Error {
  *  survives both. */
 export declare function isParserLoadError(e: unknown): boolean;
 /** Load all native tree-sitter addons (the parser runtime + every grammar) from
- * process-owned temp copies. Windows keeps loaded `.node` files locked for the
+ * content-addressed copies in a per-user temp cache — never from the installed
+ * package. Windows keeps loaded `.node` files locked for the
  * process lifetime; redirecting the upstream loaders means npm can replace the
  * installed package during an active MCP session without killing that session
  * or falling back to a stale binary. */

package/dist/extractors/nativeTreeSitter.js

@@ -1,9 +1,15 @@
 import { createRequire } from "node:module";
-import { copyFileSync, mkdirSync, mkdtempSync, readdirSync, rmSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { basename, dirname, join } from "node:path";
+import { createHash } from "node:crypto";
+import { copyFileSync, lstatSync, mkdirSync, mkdtempSync, readdirSync, readFileSync, renameSync, rmSync, statSync, utimesSync } from "node:fs";
+import { tmpdir, userInfo } from "node:os";
+import { basename, dirname, join, relative, sep } from "node:path";
 const runtimeRequire = createRequire(import.meta.url);
+/** Legacy per-process copy dirs (`hunch-tree-sitter-<pid>-*`), pruned when dead. */
 const COPY_PREFIX = "hunch-tree-sitter-";
+/** Per-user cache of content-addressed copies (`hunch-tree-sitter-cache-<user>`). */
+const CACHE_PREFIX = "hunch-tree-sitter-cache-";
+/** A hash dir no process has used for this long is pruned. */
+const CACHE_TTL_MS = 30 * 24 * 60 * 60 * 1000;
 const NATIVE_PACKAGES = [
     "tree-sitter",
     "tree-sitter-typescript",
@@ -84,21 +90,116 @@ function removeStaleCopies() {
 function environmentKey(packageName) {
     return `${packageName.toUpperCase().replaceAll("-", "_")}_PREBUILD`;
 }
-function copyNativeBinding(packageName, copyRoot, nodeGypBuild) {
+/** The per-user copy cache. A binary copied to a fresh path costs a first-load
+ *  assessment (macOS checks every never-seen dylib: ~2s per addon, six addons)
+ *  on every process; the same bytes at a path already loaded once cost ~0ms. So
+ *  copies are content-addressed and reused across processes instead of made per
+ *  process. The directory is private to the user: an addon dlopen'd from a
+ *  location another account can write would be code execution as this user. */
+function cacheRoot() {
+    const uid = typeof process.getuid === "function" ? process.getuid() : null;
+    let user = String(uid ?? "");
+    if (!user) {
+        try {
+            user = userInfo().username;
+        }
+        catch {
+            user = "user";
+        }
+    }
+    const root = join(tmpdir(), `${CACHE_PREFIX}${user.replace(/[^A-Za-z0-9_.-]/g, "_")}`);
+    mkdirSync(root, { recursive: true, mode: 0o700 });
+    const st = lstatSync(root);
+    if (!st.isDirectory() || st.isSymbolicLink())
+        throw new Error(`tree-sitter copy cache is not a directory: ${root}`);
+    // POSIX: refuse a cache another account owns or can write into. (Windows has
+    // no uid and a per-user TEMP; its ACLs are not mode bits.)
+    if (uid !== null && (st.uid !== uid || (st.mode & 0o022) !== 0)) {
+        throw new Error(`tree-sitter copy cache is not private to this user: ${root}`);
+    }
+    return root;
+}
+function sha256(bytes) {
+    return createHash("sha256").update(bytes).digest("hex");
+}
+function copyNativeBinding(packageName, root, nodeGypBuild) {
     const packageRoot = dirname(runtimeRequire.resolve(`${packageName}/package.json`));
     const source = nodeGypBuild.path(packageRoot);
-    const packageCopy = join(copyRoot, packageName);
+    const bytes = readFileSync(source);
+    const digest = sha256(bytes);
+    const hashDir = join(root, digest.slice(0, 32));
+    const packageCopy = join(hashDir, packageName);
     const normalized = source.replaceAll("\\", "/");
     const prebuild = /\/prebuilds\/([^/]+)\/[^/]+$/.exec(normalized);
     const destination = prebuild
         ? join(packageCopy, "prebuilds", prebuild[1], basename(source))
         : join(packageCopy, "build", "Release", basename(source));
-    mkdirSync(dirname(destination), { recursive: true });
-    copyFileSync(source, destination);
+    // Reuse only bytes that still hash to the installed binary: a truncated or
+    // replaced copy is rewritten, never loaded.
+    const intact = () => {
+        try {
+            return sha256(readFileSync(destination)) === digest;
+        }
+        catch {
+            return false;
+        }
+    };
+    // Mark the hash dir in use BEFORE verifying it, so a concurrent prune
+    // cannot remove it between the check and the dlopen.
+    try {
+        const now = new Date();
+        utimesSync(hashDir, now, now);
+    }
+    catch { /* not created yet */ }
+    if (!intact()) {
+        mkdirSync(dirname(destination), { recursive: true, mode: 0o700 });
+        // Atomic: a concurrent process sees the old file or the complete new one.
+        const partial = `${destination}.${process.pid}.${Date.now()}.tmp`;
+        try {
+            copyFileSync(source, partial);
+            renameSync(partial, destination);
+        }
+        catch (error) {
+            try {
+                rmSync(partial, { force: true });
+            }
+            catch { /* best effort */ }
+            // Windows refuses to replace a copy another process has loaded; that copy
+            // is then the same bytes, which is all this needs.
+            if (!intact())
+                throw error;
+        }
+        if (!intact())
+            throw new Error(`tree-sitter copy does not match its source: ${destination}`);
+    }
     return packageCopy;
 }
+/** Hash dirs unused for CACHE_TTL_MS belong to replaced installs. Deleting one
+ *  that is still loaded fails on Windows (retried by a later process) and is
+ *  harmless on POSIX (the mapping outlives the directory entry). */
+function pruneCache(root, keep) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return;
+    }
+    const cutoff = Date.now() - CACHE_TTL_MS;
+    for (const entry of entries) {
+        if (!entry.isDirectory() || keep.has(entry.name))
+            continue;
+        const dir = join(root, entry.name);
+        try {
+            if (statSync(dir).mtimeMs < cutoff)
+                rmSync(dir, { recursive: true, force: true, maxRetries: 2 });
+        }
+        catch { /* in use or already gone */ }
+    }
+}
 /** Load all native tree-sitter addons (the parser runtime + every grammar) from
- * process-owned temp copies. Windows keeps loaded `.node` files locked for the
+ * content-addressed copies in a per-user temp cache — never from the installed
+ * package. Windows keeps loaded `.node` files locked for the
  * process lifetime; redirecting the upstream loaders means npm can replace the
  * installed package during an active MCP session without killing that session
  * or falling back to a stale binary. */
@@ -126,25 +227,33 @@ function loadRuntime() {
     // 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|-go|-php|-yaml)?|tree_sitter(?:_[a-z]+)*_binding)\.node$/.test(path)
-        && !new RegExp(`(?:^|[\\\\/])${COPY_PREFIX}\\d+-`).test(path));
+        && !new RegExp(`(?:^|[\\\\/])(?:${COPY_PREFIX}\\d+-|${CACHE_PREFIX})`).test(path));
     if (preloaded.length) {
         throw new Error(`tree-sitter native addon was loaded before Hunch could isolate it: ${preloaded.join(", ")}`);
     }
     removeStaleCopies();
-    const copyRoot = mkdtempSync(join(tmpdir(), `${COPY_PREFIX}${process.pid}-`));
+    // A refused cache (another account's or a group-writable dir squatting the
+    // predictable name) must not kill parsing: fall back to a private
+    // per-process copy dir, which removeStaleCopies prunes once the pid is gone.
+    let root;
+    let shared = true;
+    try {
+        root = cacheRoot();
+    }
+    catch {
+        root = mkdtempSync(join(tmpdir(), `${COPY_PREFIX}${process.pid}-`));
+        shared = false;
+    }
     const previous = new Map();
+    const used = new Set();
     try {
-        // Resolved INSIDE the try: if node-gyp-build cannot be resolved (a partial
-        // install, npm mid-swap) the catch below still removes the copy dir we just
-        // created. Outside it, every retry — and failure is deliberately not
-        // memoized, so a long-lived MCP server retries forever — leaked one empty
-        // hunch-tree-sitter-<pid>-* dir that removeStaleCopies can never prune,
-        // because it only prunes dirs whose pid is dead.
         const nodeGypBuild = runtimeRequire("node-gyp-build");
         for (const packageName of NATIVE_PACKAGES) {
             const key = environmentKey(packageName);
             previous.set(key, process.env[key]);
-            process.env[key] = copyNativeBinding(packageName, copyRoot, nodeGypBuild);
+            const packageCopy = copyNativeBinding(packageName, root, nodeGypBuild);
+            used.add(relative(root, packageCopy).split(sep)[0]);
+            process.env[key] = packageCopy;
         }
         const Parser = runtimeRequire("tree-sitter");
         const languages = runtimeRequire("tree-sitter-typescript");
@@ -154,13 +263,6 @@ function loadRuntime() {
         const yaml = runtimeRequire("@tree-sitter-grammars/tree-sitter-yaml");
         runtime = { Parser, typescript: languages.typescript, tsx: languages.tsx, python, go, php: php.php, yaml };
     }
-    catch (error) {
-        try {
-            rmSync(copyRoot, { recursive: true, force: true });
-        }
-        catch { /* best effort */ }
-        throw error;
-    }
     finally {
         for (const [key, value] of previous) {
             if (value === undefined)
@@ -169,12 +271,8 @@ function loadRuntime() {
                 process.env[key] = value;
         }
     }
-    process.once("exit", () => {
-        try {
-            rmSync(copyRoot, { recursive: true, force: true });
-        }
-        catch { /* next process prunes it */ }
-    });
+    if (shared)
+        pruneCache(root, used);
     return runtime;
 }
 //# sourceMappingURL=nativeTreeSitter.js.map

package/dist/integrations/claudemd.d.ts

@@ -1,4 +1,18 @@
 import type { HunchStore } from "../store/hunchStore.js";
+import { groundingTemplate } from "../core/groundingLag.js";
+/** Version of the block's PROSE. Bump it whenever renderHunchSection's wording
+ *  changes. A block without the stamp is template 1. */
+export declare const GROUNDING_TEMPLATE = 2;
+export { groundingTemplate };
+/** Never downgrade a block's prose (fnd_f6875f475b). The post-commit capture runs
+ *  the PINNED hunch, which can be older than the renderer that wrote the committed
+ *  block (a branch that develops the renderer, or a repo whose pin lags its docs).
+ *  When the existing block carries a newer template than `section`, keep its prose
+ *  and move only the record counts, so the counts stay true without reverting text
+ *  this version did not author. The preserved block keeps its wiki line and those
+ *  Top-invariants lines whose constraint this version still renders.
+ *  Returns the section to write. */
+export declare function preserveNewerTemplate(existing: string, section: string): string;
 /** 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,
@@ -8,6 +22,10 @@ export declare function renderHunchSection(store: HunchStore, root?: string): st
 /** Insert/replace the marker-delimited HUNCH section in a markdown doc, preserving
  *  all user-authored content outside the markers. Shared by CLAUDE.md, AGENTS.md,
  *  and .github/copilot-instructions.md so every assistant gets the same grounding. */
-export declare function upsertSection(file: string, section: string, fallbackTitle: string): string;
+export declare function upsertSection(file: string, section: string, fallbackTitle: string, opts?: {
+    force?: boolean;
+}): string;
 /** Insert/replace the HUNCH section in CLAUDE.md, preserving everything else. */
-export declare function updateClaudeMd(root: string, store: HunchStore): string;
+export declare function updateClaudeMd(root: string, store: HunchStore, opts?: {
+    force?: boolean;
+}): string;