@davesheffer/hunch 1.41.6 → 1.43.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,12 +191,16 @@ 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();
-        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.`;
+        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 ?? ""}. Verify with the tests that cover your change (the files you edited and their tests); the full suite is CI's job. The default budget is 15 min; add --timeout <seconds> before -- only if the whole suite is really needed.`;
     }
     catch {
         return `${head} Call hunch_task(action: "start", task_id: "${task.task_id}", title: ${JSON.stringify(task.title)}, cwd: ${cwdLiteral}) to obtain verification_argv, and finish with hunch_task(action: "finish", task_id, cwd) before responding and show its card.`;

package/dist/core/taskSelection.d.ts

@@ -0,0 +1,67 @@
+/**
+ * Task-scored memory selection (memory-selection design, point 1-3; Gate A v5).
+ *
+ * The pre-edit hook used to deliver every record anchored to a file, so a hub
+ * file filled the headline cap with memory unrelated to the task. This selector
+ * scores the live store against the prompt ONCE per task; file grounding then
+ * keeps only the decisions, bugs and findings that qualified (constraints are
+ * exempt: they are scoped rules, not relevance guesses).
+ *
+ * PURE on purpose: no fs, no store. Inputs are passed in, so an offline replay
+ * can run it against an old store snapshot. The rule is fixed before
+ * measurement (no vectors in this step): a record qualifies on >= 2 distinct
+ * task terms in its title/rationale, or on a repo path the prompt names that
+ * matches the record's files or scope. Below that, nothing (silence, no filler).
+ * A term common to many live records (document frequency above the cap) names
+ * no task and does not count toward the two.
+ */
+import type { Bug, Constraint, Decision, Finding } from "./types.js";
+export interface TaskSelectionRecords {
+    decisions: readonly Decision[];
+    bugs: readonly Bug[];
+    constraints: readonly Constraint[];
+    findings: readonly Finding[];
+}
+export type TaskSelectionKind = "decision" | "bug" | "constraint" | "finding";
+export interface TaskSelection {
+    /** Every record clearing the threshold (ids only). */
+    qualifying: string[];
+    /** At most k, ordered; blocking constraints are never listed (they arrive at edit time). */
+    top: Array<{
+        id: string;
+        kind: TaskSelectionKind;
+        title: string;
+    }>;
+}
+export declare function isFilterableSelectionId(id: string): boolean;
+export declare function isBareFollowUp(prompt: string): boolean;
+export interface TaskSelectionOptions {
+    /** Prompt-time list size (design: K = 3). */
+    k?: number;
+    /** Optional existence check for a repo-relative path the prompt names. */
+    pathExists?: (path: string) => boolean;
+    /** Repository root, only to strip it from absolute paths in the prompt (string work, no fs). */
+    root?: string;
+}
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export declare const MIN_DF_CAP = 3;
+export declare const DF_CAP_RATIO = 0.05;
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export declare function liveSelectionRecords(all: TaskSelectionRecords): TaskSelectionRecords;
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export declare function promptPaths(prompt: string, root?: string): string[];
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export declare function selectForTask(records: TaskSelectionRecords, promptText: string, opts?: TaskSelectionOptions): TaskSelection;

package/dist/core/taskSelection.js

@@ -0,0 +1,196 @@
+import { lexicalTokens, PROFILE_BASE_SCORE, SEVERITY } from "./delivery.js";
+import { pathMatchesGlob } from "./glob.js";
+/** Id prefixes of the kinds file grounding filters by a selection (ids.ts:
+ *  decisionId/bugId/findingId). Constraints (con_) always pass, so a selection
+ *  holding no id with one of these prefixes filters nothing useful — it would
+ *  only hide every decision, bug and finding — and counts as no selection. */
+const FILTERABLE_ID_PREFIXES = ["dec_", "bug_", "fnd_"];
+export function isFilterableSelectionId(id) {
+    return FILTERABLE_ID_PREFIXES.some((prefix) => id.startsWith(prefix));
+}
+/** Words a bare follow-up is made of ("continue", "go on", "yes do it", "ok,
+ *  next step please"). A prompt of only these names no task of its own and
+ *  inherits the continued task's selection; any other word — a verb and an
+ *  object ("fix sampler"), a path, another language — is a task of its own
+ *  (fail-safe: its own selection, or unfiltered grounding). */
+const CONTINUATION_WORDS = new Set([
+    "continue", "continuing", "go", "on", "ahead", "proceed", "resume", "carry", "keep", "going",
+    "yes", "yep", "yeah", "y", "ok", "okay", "sure", "please", "pls", "do", "it", "that", "this",
+    "next", "step", "again", "lgtm", "sounds", "good", "fine", "and", "the", "with", "now",
+]);
+export function isBareFollowUp(prompt) {
+    const words = (prompt ?? "").toLowerCase().split(/[^\p{L}\p{N}]+/u).filter(Boolean);
+    return words.length > 0 && words.every((word) => CONTINUATION_WORDS.has(word));
+}
+const BRACKET_PAIRS = { "(": ")", "[": "]", "{": "}" };
+const CLOSING_BRACKETS = { ")": "(", "]": "[", "}": "{" };
+/** Every `close` in text[from, to) follows its `open` (properly nested, none left open). */
+function balanced(text, from, to, open, close) {
+    let depth = 0;
+    for (let i = from; i < to; i++) {
+        if (text[i] === open)
+            depth++;
+        else if (text[i] === close && --depth < 0)
+            return false;
+    }
+    return depth === 0;
+}
+/** Strip quoting, sentence punctuation, unmatched or wrapping brackets and a
+ *  possessive `'s` from a prompt token until stable. A bracket the path itself
+ *  uses (`(auth)/x.ts`, `[id]/page.tsx`, `src/app/(auth)`) is balanced and stays.
+ *  Works on [a, b) indices with bracket counts kept current, so trimming a run of
+ *  n unmatched brackets is linear, not n rescans of the token. */
+const MAX_PATH_TOKEN_CHARS = 1024;
+/** Wrapping pairs unwrapped per token; each unwrap rescans the token, and prose never nests deeper. */
+const MAX_UNWRAPS = 8;
+function trimPathToken(raw) {
+    const counts = { "(": 0, ")": 0, "[": 0, "]": 0, "{": 0, "}": 0 };
+    for (let i = 0; i < raw.length; i++)
+        if (raw[i] in counts)
+            counts[raw[i]]++;
+    const n = (ch) => counts[ch];
+    const dropAt = (i) => { if (raw[i] in counts)
+        counts[raw[i]]--; };
+    let a = 0;
+    let b = raw.length;
+    let unwraps = 0;
+    for (let before = -1; a < b && before !== b - a;) {
+        before = b - a;
+        // A trailing opening bracket can never close, so it goes first (keeps `[id]/x.ts[` from losing its head).
+        const lastOpen = raw[b - 1];
+        if (BRACKET_PAIRS[lastOpen] && n(lastOpen) > n(BRACKET_PAIRS[lastOpen]))
+            dropAt(--b);
+        if (a >= b)
+            break;
+        const head = raw[a];
+        const close = BRACKET_PAIRS[head];
+        const headOpen = CLOSING_BRACKETS[head];
+        if ("`'\"<\u2018\u201c".includes(head))
+            dropAt(a++);
+        else if (close && unwraps < MAX_UNWRAPS && b - a >= 2 && raw[b - 1] === close && n(head) === n(close) && balanced(raw, a + 1, b - 1, head, close)) {
+            unwraps++;
+            dropAt(a++);
+            dropAt(--b);
+        }
+        else if (close && n(head) > n(close))
+            dropAt(a++);
+        else if (headOpen && n(head) > n(headOpen))
+            dropAt(a++);
+        if (a >= b)
+            break;
+        const tail = raw[b - 1];
+        const open = CLOSING_BRACKETS[tail];
+        if ("`'\">,.;:!?\u2019\u201d".includes(tail))
+            dropAt(--b);
+        else if (open && n(open) < n(tail))
+            dropAt(--b);
+        if (b - a >= 2 && "sS".includes(raw[b - 1]) && "'\u2019".includes(raw[b - 2]))
+            b -= 2;
+    }
+    return raw.slice(a, b);
+}
+const MIN_DISTINCT_TERMS = 2;
+/** Document-frequency cap, fixed before the pilot replay: a prompt term counts
+ *  only when at most max(MIN_DF_CAP, ceil(DF_CAP_RATIO × live records)) records
+ *  contain it. */
+export const MIN_DF_CAP = 3;
+export const DF_CAP_RATIO = 0.05;
+const DEFAULT_K = 3;
+const LIVE_FINDING_TRIAGE = new Set(["open", "accepted-risk", "scheduled"]);
+/** The live slice the pre-edit grounding would ever deliver at HEAD: decisions and
+ *  constraints still in force (the store's why() window plus delivery's retired
+ *  test), every bug (why() keeps fixed ones as lessons), and findings whose triage
+ *  liveFindingsFor() keeps. */
+export function liveSelectionRecords(all) {
+    return {
+        decisions: all.decisions.filter((d) => d.status !== "rejected" && d.status !== "superseded" && !d.superseded_by && d.valid_to == null),
+        bugs: [...all.bugs],
+        constraints: all.constraints.filter((c) => c.status !== "retired" && c.valid_to == null),
+        findings: all.findings.filter((f) => LIVE_FINDING_TRIAGE.has(f.triage)),
+    };
+}
+/** Repo paths the prompt names: a markdown link `[label](target)` reads as its
+ *  target, then a whitespace token containing `/` or ending in a file extension,
+ *  stripped of quoting/punctuation/unmatched brackets, a trailing `:line[:col]`
+ *  or `:start-end` and a possessive `'s`, forward-slashed, repo-relative. A drive-letter root compares
+ *  case-insensitively (Windows paths are case-insensitive on every host). */
+export function promptPaths(prompt, root) {
+    const out = new Set();
+    const rootPrefix = root ? `${root.replace(/\\/g, "/").replace(/\/+$/, "")}/` : null;
+    // Label and target may each hold one level of brackets (`[app/[id]/x.ts](app/[id]/x.ts)`,
+    // a linked `src/app/(auth)/page.tsx`); the label never spans a `[`, so a run of `[` fails fast.
+    const links = prompt.replace(/\[(?:[^[\]\n]|\[[^[\]\n]{0,256}\]){0,256}\]\(((?:[^()\s]|\([^()\s]{0,256}\)){1,1024})\)/g, " $1 ");
+    for (const raw of links.split(/\s+/)) {
+        // No repo path is this long; trimming pasted junk one bracket at a time would stall the prompt hook.
+        if (raw.length > MAX_PATH_TOKEN_CHARS)
+            continue;
+        let token = trimPathToken(raw).replace(/\\/g, "/").replace(/:\d+(?:[:-]\d+)?$/, "");
+        if (!token || /^[a-z][a-z0-9+.-]*:\/\//i.test(token))
+            continue;
+        if (!token.includes("/") && !/\.[a-z0-9]{1,8}$/i.test(token))
+            continue;
+        if (rootPrefix) {
+            const foldCase = process.platform === "win32" || /^[a-z]:\//i.test(token);
+            if (foldCase ? token.toLowerCase().startsWith(rootPrefix.toLowerCase()) : token.startsWith(rootPrefix))
+                token = token.slice(rootPrefix.length);
+        }
+        token = token.replace(/^(?:\.\/)+/, "");
+        // Absolute (outside the root) or parent-relative paths name nothing in this repo.
+        if (!token || token.startsWith("/") || /^[a-z]:/i.test(token) || token.split("/").includes(".."))
+            continue;
+        out.add(token);
+    }
+    return [...out];
+}
+/** Score live records against one prompt. Text fields per kind (title + rationale):
+ *  decision title/context/decision; bug title/symptom/root_cause; constraint
+ *  statement/rationale; finding title/observation. Path anchors: decision
+ *  related_files, bug/finding affected_files, constraint scope globs. Priority
+ *  ties break on the builder profile's kind/severity score in delivery.ts. */
+export function selectForTask(records, promptText, opts = {}) {
+    const k = Math.max(0, opts.k ?? DEFAULT_K);
+    const taskTerms = lexicalTokens(promptText ?? "");
+    // Without an existence check (pure/offline) only a slashed token is trusted as a
+    // path: "e.g.", "Node.js" or "v1.2" would otherwise match a broad glob.
+    const paths = promptPaths(promptText ?? "", opts.root).filter((p) => opts.pathExists ? opts.pathExists(p) : p.includes("/"));
+    if (!taskTerms.size && !paths.length)
+        return { qualifying: [], top: [] };
+    const base = PROFILE_BASE_SCORE.builder;
+    // Tokenize every record once: the same tokens feed the document frequency and the score.
+    const candidates = [];
+    const consider = (id, kind, title, text, anchors, priority, listable) => {
+        candidates.push({ id, kind, title, tokens: lexicalTokens(text.join(" ")), anchors, priority, listable });
+    };
+    for (const c of records.constraints) {
+        consider(c.id, "constraint", c.statement, [c.statement, c.rationale], c.scope, base.constraints + SEVERITY[c.severity] * 10 + (c.provenance.confidence ?? 0), c.severity !== "blocking");
+    }
+    for (const d of records.decisions) {
+        consider(d.id, "decision", d.title, [d.title, d.context, d.decision], d.related_files, base.decisions + (d.status === "accepted" ? 20 : 0) + (d.provenance.confidence ?? 0), true);
+    }
+    for (const b of records.bugs) {
+        consider(b.id, "bug", b.title, [b.title, b.symptom, b.root_cause], b.affected_files, base.bugs + SEVERITY[b.severity] * 10 + (b.status === "open" || b.status === "regressed" ? 10 : 0), true);
+    }
+    for (const f of records.findings) {
+        consider(f.id, "finding", f.title, [f.title, f.observation], f.affected_files, base.findings + SEVERITY[f.severity] * 10, true);
+    }
+    const dfCap = Math.max(MIN_DF_CAP, Math.ceil(DF_CAP_RATIO * candidates.length));
+    const rareTerms = [...taskTerms].filter((term) => candidates.filter((c) => c.tokens.has(term)).length <= dfCap);
+    const scored = [];
+    for (const { tokens, anchors, ...rest } of candidates) {
+        let terms = 0;
+        for (const term of rareTerms)
+            if (tokens.has(term))
+                terms++;
+        const pathHits = paths.filter((p) => anchors.some((anchor) => pathMatchesGlob(p, anchor))).length;
+        if (pathHits > 0 || terms >= MIN_DISTINCT_TERMS)
+            scored.push({ ...rest, pathHits, terms });
+    }
+    // A record anchored to more of the files the prompt names outranks one that
+    // shares a single (often hub) file with it; rare terms break the remaining ties.
+    scored.sort((a, b) => b.pathHits - a.pathHits || b.terms - a.terms || b.priority - a.priority || a.id.localeCompare(b.id));
+    return {
+        qualifying: scored.map((s) => s.id),
+        top: scored.filter((s) => s.listable).slice(0, k).map(({ id, kind, title }) => ({ id, kind, title })),
+    };
+}
+//# sourceMappingURL=taskSelection.js.map

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. */