@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/extractors/parse.js

@@ -14,34 +14,37 @@ function bundleFor(spec) {
         const grammar = spec.loadGrammar();
         parser.setLanguage(grammar);
         const query = new Parser.Query(grammar, spec.query);
-        b = { parser, query };
+        const bindingQuery = spec.bindingQuery ? new Parser.Query(grammar, spec.bindingQuery) : null;
+        b = { parser, query, bindingQuery };
         cache.set(spec.grammarKey, b);
     }
     return b;
 }
+/** Per-spec templating markers with g/y stripped, so `.test()` is stateless.
+ *  Built once per language spec rather than on every parseSource call. */
+const statelessMarkers = new WeakMap();
+function templatingMarkersFor(spec) {
+    let markers = statelessMarkers.get(spec);
+    if (!markers) {
+        markers = (spec.templatingMarkers ?? []).map((re) => new RegExp(re.source, re.flags.replace(/[gy]/g, "")));
+        statelessMarkers.set(spec, markers);
+    }
+    return markers;
+}
 const STR_QUOTES = /^['"`]|['"`]$/g;
-/** Cap on a stored symbol's bodyText — large enough for review context, small
- *  enough that a huge function/file doesn't bloat every JSON symbol record. */
+/** Cap on stored symbol body text: enough context for review without bloating JSON records. */
 export const MAX_BODY_TEXT_CHARS = 4000;
 export function parseSource(file, source, opts = {}) {
     const spec = languageFor(file);
     if (!spec)
         return null;
-    // Templated text (Helm chart / Jinja CI config) isn't {spec.id} yet — a real
-    // grammar correctly reports ERROR nodes for the delimiters. Still run the
-    // parse below (a well-formed anchor elsewhere in the file still contributes
-    // a real symbol, same as any other YAML file) — just don't let those
-    // expected errors fail-close the whole-repo scan on content that was never
-    // meant to stand alone (#33). Heavy top-level templating can break error
-    // recovery badly enough that even the whole-file root node never forms
-    // (root.type becomes "ERROR", not "stream") — the fallback-symbol synthesis
-    // below covers that case so the file doesn't vanish from the component graph.
-    // String.prototype.search ignores lastIndex (unlike RegExp.test with a /g or
-    // /y flag), so a future templatingMarkers entry can't introduce cross-call
-    // statefulness here even if it forgets to keep its pattern flag-free.
-    const templated = (spec.alwaysTemplatedExtensions?.some((ext) => file.endsWith(ext)) ?? false)
-        || (spec.templatingMarkers?.some((marker) => source.search(marker) !== -1) ?? false);
-    const { parser, query } = bundleFor(spec);
+    // Templated text is not valid language text until rendered. Still parse, so real
+    // anchors/symbols are extracted, but do not let the expected errors mark the file
+    // unparseable. Severe templating may stop even the root document node from
+    // forming; the fallback whole-file symbol below covers that case.
+    const templated = (spec.alwaysTemplatedExtensions ?? []).some((ext) => file.endsWith(ext))
+        || templatingMarkersFor(spec).some((re) => re.test(source));
+    const { parser, query, bindingQuery } = bundleFor(spec);
     // The native binding caps its scratch buffer at 32 KB unless bufferSize is
     // given — without this, any source >= 32768 bytes throws "Invalid argument"
     // and would abort the whole index run. Guard with try/catch as a backstop.
@@ -81,6 +84,7 @@ export function parseSource(file, source, opts = {}) {
     const imports = [];
     const calls = [];
     const relations = [];
+    const bindings = [];
     let namespace = null;
     const originalText = (node) => usingRecoveredTree
         ? source.slice(node.startIndex, node.endIndex)
@@ -92,15 +96,12 @@ export function parseSource(file, source, opts = {}) {
         const cname = cap.name;
         const node = cap.node;
         if (cname.endsWith(".def")) {
-            // Keep the FIRST classification a node id receives: a query may have
-            // several patterns matching the same node at different specificity
-            // (e.g. a Python method inside a class body matches both a class-nested
-            // "method.def" pattern and a general "fn.def" pattern — Task 4 relies on
-            // this to classify methods correctly without special-casing Python here).
+            // First classification wins: a node matched by several patterns keeps the
+            // kind it received first (Python nested methods, Go struct/interface specs).
             if (!pendingDefs.has(node.id))
                 pendingDefs.set(node.id, { kind: spec.defKindOf[cname], def: node });
         }
-        else if (spec.nameToDef[cname]) {
+        else if (Object.hasOwn(spec.nameToDef, cname)) {
             // name capture: find its parent def node id by walking up to the def type
             const defNode = ascendToDef(node, spec.defNodeTypes);
             if (defNode) {
@@ -125,8 +126,11 @@ export function parseSource(file, source, opts = {}) {
         else if (cname === "call.member") {
             // skip builtin method names to avoid false edges to similarly-named symbols
             const text = originalText(node);
-            if (!spec.builtinMethods.has(text))
-                calls.push({ callee: text, atByte: node.startIndex, endByte: node.endIndex, member: true });
+            if (!spec.builtinMethods.has(text)) {
+                const object = node.parent?.childForFieldName("object") ?? node.parent?.childForFieldName("operand");
+                const qualifier = object?.type === "identifier" ? originalText(object) : undefined;
+                calls.push({ callee: text, atByte: node.startIndex, endByte: node.endIndex, member: true, qualifier });
+            }
         }
         else if (spec.relationKindOf?.[cname]) {
             const relation = spec.relationKindOf[cname];
@@ -139,35 +143,50 @@ export function parseSource(file, source, opts = {}) {
             });
         }
     }
+    for (const match of bindingQuery?.matches(tree.rootNode) ?? []) {
+        const text = (capture) => {
+            const node = match.captures.find((c) => c.name === capture)?.node;
+            return node ? originalText(node) : null;
+        };
+        const src = text("bind.src")?.replace(STR_QUOTES, "");
+        if (!src)
+            continue;
+        const imported = text("bind.name");
+        if (imported) {
+            const local = text("bind.local") ?? imported;
+            // `from X import Y [as Z]`: Y may be a submodule or a member; record both
+            // readings — only the one that resolves to a tracked file/symbol yields an edge.
+            if (spec.joinSubmodule)
+                bindings.push({ local, module: spec.joinSubmodule(src, imported), imported: null });
+            bindings.push({ local, module: src, imported });
+        }
+        else {
+            const local = text("bind.local") ?? spec.defaultBindingLocal?.(src) ?? null;
+            if (local)
+                bindings.push({ local, module: src, imported: null });
+        }
+    }
     for (const { kind, def, name } of pendingDefs.values()) {
-        const resolvedName = name ?? spec.fallbackDefName?.(file);
-        if (!resolvedName)
+        const symbolName = name ?? spec.fallbackDefName?.(file);
+        if (!symbolName)
             continue;
         const loc = def.endPosition.row - def.startPosition.row + 1;
         symbols.push({
-            name: resolvedName, kind,
+            name: symbolName, kind,
             startByte: def.startIndex, endByte: def.endIndex, loc,
             bodyText: originalText(def).slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
-    // Every other successfully-parsed YAML file gets at least a file-root symbol
-    // (fallbackDefName). If templating broke error recovery badly enough that
-    // the doc.def capture never fired, synthesize the same fallback here rather
-    // than let the file silently drop out of the component graph. Push it before
-    // the sort below — parse()'s callers (indexer.ts) rely on symbols staying in
-    // start-byte order.
+    // Severe templating can stop the root node from forming; synthesize the whole-file symbol.
     if (templated && spec.fallbackDefName && !symbols.some((s) => s.kind === "file")) {
         symbols.push({
-            name: spec.fallbackDefName(file),
-            kind: "file",
-            startByte: 0,
-            endByte: source.length,
-            loc: source.split("\n").length,
+            name: spec.fallbackDefName(file), kind: "file",
+            startByte: 0, endByte: source.length, loc: source.split("\n").length,
             bodyText: source.slice(0, MAX_BODY_TEXT_CHARS),
         });
     }
     symbols.sort((a, b) => a.startByte - b.startByte);
-    return { symbols, imports, calls, relations, namespace, parseable: templated || parseable };
+    return { symbols, imports, calls, relations, bindings, namespace, parseable: templated || parseable };
 }
 /** True when every ERROR/MISSING node in the tree sits in an ancestor shape this
  *  language declares as a known grammar limitation (LanguageSpec.toleratedErrorScopes).
@@ -213,7 +232,7 @@ function inToleratedScope(node, scopes) {
     }
     return false;
 }
-/** Walk up to the nearest node whose type is a definition this language recognizes. */
+/** Nearest ancestor of `node` whose type is a definition type, or null. */
 function ascendToDef(node, defNodeTypes) {
     let cur = node.parent;
     while (cur) {
@@ -224,17 +243,12 @@ function ascendToDef(node, defNodeTypes) {
     return null;
 }
 /** Map each call site to the innermost symbol whose byte-range contains it.
- *  Keyed by the symbol's position (index) in `parsed.symbols` — NOT its
- *  startByte, which is not a reliable per-symbol identity: a language whose
- *  extractor merges a synthetic whole-file symbol with independently-derived
- *  symbols (e.g. YAML's fallback-root synthetic symbol alongside Helm's
- *  regex-derived `define` blocks) can produce two distinct symbols that both
- *  start at byte 0. Indexing by array position is unique by construction,
- *  regardless of byte overlap — the caller must consume the exact same
- *  `parsed.symbols` array (or an equivalently-ordered copy) to look up a
- *  symbol by the index this function returns. The value maps callee name ->
- *  `memberOnly` (true iff every occurrence was a `x.foo()` member call, never
- *  a direct `foo()`), so the indexer can resolve member calls conservatively. */
+ *  The result is keyed by the symbol's INDEX in `parsed.symbols`, not its start
+ *  byte: two distinct symbols can share a start byte (a synthetic whole-file root
+ *  beside others starting at byte 0), so callers must look symbols up in the same
+ *  array order. Each value maps callee name -> memberOnly, true iff every
+ *  occurrence of that callee inside the symbol was a member call, so the indexer
+ *  can resolve member calls conservatively. */
 export function attributeCalls(parsed) {
     const out = new Map();
     for (const call of parsed.calls) {
@@ -250,15 +264,65 @@ export function attributeCalls(parsed) {
             }
         }
         if (best && best.name !== call.callee) {
-            if (!out.has(bestIndex))
-                out.set(bestIndex, new Map());
-            const m = out.get(bestIndex);
+            let m = out.get(bestIndex);
+            if (!m) {
+                m = new Map();
+                out.set(bestIndex, m);
+            }
             const prev = m.get(call.callee);
             m.set(call.callee, prev === undefined ? call.member : prev && call.member);
         }
     }
     return out;
 }
+/** Map each call bound to an imported module — `ns.fn()` through a module-object
+ *  binding, or `g()` through an aliased member import — to the innermost symbol
+ *  containing it (same index identity as attributeCalls). A local bound to two
+ *  different modules is ambiguous and dropped: never guess a binding. */
+export function attributeQualifiedCalls(parsed) {
+    const unique = (entries) => {
+        const out = new Map();
+        for (const [local, target] of entries) {
+            const prev = out.get(local);
+            out.set(local, prev === undefined || (prev && prev.module === target.module && prev.callee === target.callee) ? target : null);
+        }
+        return out;
+    };
+    const modules = unique(parsed.bindings.filter((b) => b.imported === null).map((b) => [b.local, { callee: "", module: b.module }]));
+    const aliases = unique(parsed.bindings.filter((b) => b.imported !== null).map((b) => [b.local, { callee: b.imported, module: b.module }]));
+    const out = new Map();
+    if (modules.size === 0 && aliases.size === 0)
+        return out;
+    for (const call of parsed.calls) {
+        let target = null;
+        if (call.member && call.qualifier) {
+            const binding = modules.get(call.qualifier);
+            if (binding)
+                target = { callee: call.callee, module: binding.module };
+        }
+        else if (!call.member) {
+            target = aliases.get(call.callee) ?? null;
+        }
+        if (!target)
+            continue;
+        let best = null;
+        let bestIndex = -1;
+        for (let i = 0; i < parsed.symbols.length; i++) {
+            const s = parsed.symbols[i];
+            if (call.atByte >= s.startByte && call.atByte < s.endByte && (!best || s.endByte - s.startByte < best.endByte - best.startByte)) {
+                best = s;
+                bestIndex = i;
+            }
+        }
+        if (bestIndex < 0)
+            continue;
+        const list = out.get(bestIndex) ?? [];
+        if (!list.some((t) => t.callee === target.callee && t.module === target.module))
+            list.push(target);
+        out.set(bestIndex, list);
+    }
+    return out;
+}
 /** Map static semantic relationships (extends/implements/trait use) to the
  * innermost enclosing declaration using the same stable symbol-index identity
  * as call attribution. */

package/dist/extractors/workspaces.js

@@ -12,6 +12,7 @@ import { execFileSync, spawnSync } from "node:child_process";
 import { existsSync, realpathSync, statSync } from "node:fs";
 import { join } from "node:path";
 import { foreignRepoEnv, gitCommonDir, mainWorktreeRoot, stableRepositoryName } from "./git.js";
+import { boundedSpawnSync } from "../core/boundedSpawn.js";
 import { extracted } from "../core/types.js";
 import { CONTROL_CHARS, MAX_BRANCHES, MAX_WORKTREES, WORKSPACE_SCHEMA_VERSION, WorkspaceSchema, isSafeBranchName, workspaceId, worktreeId, } from "../core/workspace.js";
 const SHA = /^(?:[0-9a-f]{40}|[0-9a-f]{64})$/;
@@ -353,8 +354,9 @@ function fetchedAt(root) {
 export function snapshotWorkspace(root, opts) {
     const now = opts.now ?? new Date();
     const main = mainWorktreeRoot(root);
+    // Network fetch: bounded so a timeout kills git's whole tree, not just the root (#498).
     if (opts.fetch)
-        run(main, ["fetch", "--prune", "--quiet"], 120_000);
+        boundedSpawnSync("git", ["fetch", "--prune", "--quiet"], { cwd: main, env: env(), stdout: "ignore", timeout: 120_000 });
     const def = defaultBranch(main);
     const searched = opts.squashSearchCommits ?? DEFAULT_SQUASH_SEARCH_COMMITS;
     let patchIds = null;

package/dist/integrations/claudemd.js

@@ -82,6 +82,7 @@ export function renderHunchSection(store, root) {
         bugs: store.json.loadAll("bugs").length,
         constraints: store.json.loadAll("constraints").length,
         components: store.json.loadAll("components").length,
+        // Public policies only: private-overlay policies must not change the committed block.
         policies: root ? new PolicyRepository(root, store).listPolicies({ publicOnly: true }).length : 0,
         findings: store.json.loadAll("findings").filter((f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled").length,
     };

package/dist/integrations/gitignore.js

@@ -32,12 +32,10 @@ const ENTRIES = [
     ".hunch/local.json",
     // The strict hook's append-only catch-log: clone-local, never a memory record.
     ".hunch/events.log",
-    // The post-merge hook's queue of detected-but-unconfirmed commit-provenance
-    // repairs — clone-local scratch state, never committed (`hunch repair-provenance
-    // --apply` confirms and clears it).
+    // The post-merge hook's clone-local queue of unconfirmed provenance repairs —
+    // never committed; cleared by `hunch repair-provenance --apply`.
     ".hunch/pending-commit-repairs.json",
-    // Tombstones for commit-repair matches a human rejected via `--drop` — clone-local
-    // scratch state, same discipline as the queue above.
+    // Tombstones for matches rejected via `--drop` — clone-local, never committed.
     ".hunch/dropped-commit-repairs.json",
     // A local PRIVATE overlay store (HUNCH_PRIVATE_DIR) for sensitive memory — never
     // committed. This is the conventional in-repo path; point the env elsewhere for a

package/dist/integrations/health.d.ts

@@ -40,6 +40,12 @@ export declare const HARNESSES: {
     };
 };
 export type Harness = keyof typeof HARNESSES;
+/** Devin Desktop (formerly Windsurf) reads workspace hooks from .devin/hooks.json
+ * and falls back to the legacy .windsurf/hooks.json only when that file is absent
+ * or defines no hooks (docs.devin.ai/desktop/cascade/hooks, #494). */
+export declare const DEVIN_HOOKS = ".devin/hooks.json";
+/** The hooks file the host actually reads, so doctor inspects the active one. */
+export declare function activeHooksFile(root: string, harness: Harness): string;
 export interface HealthIssue {
     file: string;
     code: string;

package/dist/integrations/health.js

@@ -29,6 +29,26 @@ export const HARNESSES = {
     windsurf: { mcp: ".windsurf/mcp_config.json", hooks: ".windsurf/hooks.json", key: "mcpServers", events: ["", "pre_write_code", "post_run_command", ""] },
     antigravity: { mcp: ".agents/mcp_config.json", hooks: ".agents/hooks.json", key: "mcpServers", events: ["PreInvocation", "PreToolUse", "", ""] },
 };
+/** Devin Desktop (formerly Windsurf) reads workspace hooks from .devin/hooks.json
+ * and falls back to the legacy .windsurf/hooks.json only when that file is absent
+ * or defines no hooks (docs.devin.ai/desktop/cascade/hooks, #494). */
+export const DEVIN_HOOKS = ".devin/hooks.json";
+/** The hooks file the host actually reads, so doctor inspects the active one. */
+export function activeHooksFile(root, harness) {
+    const legacy = HARNESSES[harness].hooks;
+    if (harness !== "windsurf" || !existsSync(join(root, DEVIN_HOOKS)))
+        return legacy;
+    try {
+        const hooks = parseJsonc(readFileSync(join(root, DEVIN_HOOKS), "utf8"))?.hooks;
+        if (hooks && typeof hooks === "object" && Object.values(hooks).some(v => Array.isArray(v) && v.length > 0))
+            return DEVIN_HOOKS;
+        return legacy;
+    }
+    catch {
+        // An unparseable .devin/hooks.json is reported against itself, not masked.
+        return DEVIN_HOOKS;
+    }
+}
 const exactVersion = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
 const pinPattern = /@davesheffer\/hunch@([^\s"'\],;]+)/g;
 const object = (v) => {
@@ -160,12 +180,13 @@ export function inspectIntegrations(root, selected) {
     }
     for (const harness of selected ? [selected] : Object.keys(HARNESSES)) {
         const spec = HARNESSES[harness];
-        if (!selected && !existsSync(join(root, spec.mcp)) && (!spec.hooks || !existsSync(join(root, spec.hooks))))
+        const hooksFile = activeHooksFile(root, harness);
+        if (!selected && !existsSync(join(root, spec.mcp)) && (!hooksFile || !existsSync(join(root, hooksFile))))
             continue;
         const capabilities = Object.fromEntries(CAPABILITIES.map(c => [c, { status: "untested", detail: "No runtime evidence" }]));
         report.harnesses.push({ harness, capabilities });
         const mcpPath = join(root, spec.mcp);
-        const hooksFileExists = Boolean(spec.hooks && existsSync(join(root, spec.hooks)));
+        const hooksFileExists = Boolean(hooksFile && existsSync(join(root, hooksFile)));
         let mcpEntryAbsent = false;
         try {
             lstatSync(mcpPath);
@@ -203,22 +224,22 @@ export function inspectIntegrations(root, selected) {
         // A hooks file that was never written is a coverage gap (the adapter is
         // not installed), not configuration drift: report it, never fail on it.
         // `--require` still refuses, because nothing unverified counts.
-        const hooksAbsent = !!spec.hooks && !existsSync(join(root, spec.hooks));
-        if (spec.hooks && !hooksAbsent) {
+        const hooksAbsent = !!hooksFile && !existsSync(join(root, hooksFile));
+        if (hooksFile && !hooksAbsent) {
             try {
-                const config = object(parseJsonc(readFileSync(join(root, spec.hooks), "utf8")));
+                const config = object(parseJsonc(readFileSync(join(root, hooksFile), "utf8")));
                 disabled = config.disableAllHooks === true;
                 events = object(harness === "antigravity" ? config.hunch : config.hooks);
                 const commands = Object.values(events).flatMap(v => hookCommands(v));
-                recordPins(spec.hooks, commands);
+                recordPins(hooksFile, commands);
                 if (commands.some(misroutedHook))
                     report.issues.push({
-                        file: spec.hooks, code: "hook-command",
+                        file: hooksFile, code: "hook-command",
                         detail: "Hunch hooks invoke the MCP subcommand instead of the hook handler; run hunch integrations repair-pins",
                     });
             }
             catch (e) {
-                report.issues.push({ file: spec.hooks, code: "hook-config", detail: e.message });
+                report.issues.push({ file: hooksFile, code: "hook-config", detail: e.message });
             }
         }
         for (const [i, capability] of ["context", "edit-blocking", "failure-capture", "compaction"].entries()) {
@@ -235,7 +256,7 @@ export function inspectIntegrations(root, selected) {
                 status.detail = capability === "context" ? "Hunch relies on instructions and voluntary MCP calls on this adapter" : "No Hunch lifecycle adapter for this capability";
             }
             else if (hooksAbsent) {
-                status.detail = `No ${spec.hooks}; run hunch init to install this host's lifecycle hooks`;
+                status.detail = `No ${hooksFile}; run hunch init to install this host's lifecycle hooks`;
             }
             else if (disabled || firmness === "off" || ((capability === "failure-capture") && process.env.HUNCH_PIPELINE === "0")) {
                 status.status = "unsupported";
@@ -248,7 +269,7 @@ export function inspectIntegrations(root, selected) {
                 }
                 else {
                     status.detail = `Missing Hunch ${event} handler`;
-                    report.issues.push({ file: spec.hooks, code: "missing-hook", detail: status.detail });
+                    report.issues.push({ file: hooksFile, code: "missing-hook", detail: status.detail });
                 }
             }
             else if (capability === "edit-blocking" && firmness !== "strict") {
@@ -302,7 +323,7 @@ export function repairIntegrationPins(root, opts = {}) {
     const version = expectedVersion(root);
     const pending = [];
     for (const [name, spec] of Object.entries(HARNESSES)) {
-        for (const file of [spec.mcp, spec.hooks].filter(Boolean)) {
+        for (const file of [spec.mcp, spec.hooks, ...(name === "windsurf" ? [DEVIN_HOOKS] : [])].filter(Boolean)) {
             const path = join(root, file);
             if (!existsSync(path) || opts.skip?.(file))
                 continue;
@@ -342,7 +363,7 @@ export function repairIntegrationPins(root, opts = {}) {
                 const replacements = new Map(values.map(v => {
                     // Every recognized npm token is shell-safe. Bare tokens also repair
                     // the legacy quoted executable, which PowerShell treats as a string.
-                    const published = file === spec.hooks ? publishedHookCommand(v) : undefined;
+                    const published = file === spec.hooks || file === DEVIN_HOOKS ? publishedHookCommand(v) : undefined;
                     const repaired = published?.replace(" hunch mcp hook", " hunch hook") ?? v;
                     return [v, replace(repaired)];
                 }).filter(([a, b]) => a !== b));

package/dist/integrations/hooks.d.ts

@@ -16,8 +16,10 @@ export interface HookInstall {
      *  managed-elsewhere: a hook manager owns the hook — nothing was written.
      *  unreachable: the existing hook ends in exec/exit before our block, or the
      *  block in it has no closing marker and so cannot be replaced in place —
-     *  nothing was written. */
-    action: "created" | "appended" | "updated" | "unchanged" | "kept-shared" | "managed-elsewhere" | "unreachable";
+     *  nothing was written.
+     *  opted-out: the main checkout opted out (#488) and git hooks live in the
+     *  common dir every worktree shares — nothing was written, on purpose. */
+    action: "created" | "appended" | "updated" | "unchanged" | "kept-shared" | "managed-elsewhere" | "unreachable" | "opted-out";
     manager?: HookManagerKind;
     /** Why nothing was written (non-writing actions only). */
     reason?: string;
@@ -109,20 +111,15 @@ export declare function installPostCommitHook(root: string, invocation: string,
  *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
  *  Preserves any existing pre-commit hook. */
 export declare function installPreCommitHook(root: string, invocation: string, strict?: boolean): HookInstall;
-/** Install a post-merge hook carrying TWO independently-managed blocks:
- *  re-sync the committed grounding docs when a merge brought memory in behind
- *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
- *  files and can never fail the merge), and opportunistically DETECT a
- *  decision's commit provenance going orphaned right after a squash-merged
- *  branch lands locally (including a fast-forward from `git pull`) — while
- *  the original commits are still fully intact and matchable — queuing the
- *  match for a human to confirm via `hunch repair-provenance --apply`
- *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
- *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
- *  Each block is keyed by its own marker pair (installManagedBlock), so
- *  re-running updates only its own block, preserves the other untouched, and
- *  a repo carrying only one half (an older install, or a hand-edited hook)
- *  gets the other appended rather than clobbered. */
+/** Install the post-merge hook. It carries two independently managed blocks:
+ *  - grounding: re-syncs committed grounding docs when a merge brought in memory.
+ *    Guarded by HUNCH_SYNC, runs in the foreground, never fails the merge.
+ *  - repair: detects a decision's commit provenance being orphaned by a
+ *    squash-merge (including a fast-forward from `git pull`) and queues the match
+ *    for `hunch repair-provenance --apply`. Guarded by HUNCH_MERGE_SYNC, runs in
+ *    the background.
+ *  Each block is keyed by its own marker pair, so a re-run updates only its own
+ *  block, and a hook that has only one half gets the other appended, not clobbered. */
 export declare function installPostMergeHook(root: string, invocation: string): HookInstall;
 export declare function installPostCheckoutHook(root: string, invocation: string): HookInstall;
 export type HookState = BlockState;

package/dist/integrations/hooks.js

@@ -19,6 +19,7 @@ import { join, isAbsolute, dirname, basename, relative, resolve } from "node:pat
 import { homedir } from "node:os";
 import { hooksDir, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
+import { isOptedOut, OPT_OUT_FILE } from "./optout.js";
 import { HUNCH_NPX_PACKAGE_SPEC, HUNCH_PACKAGE_NAME } from "../core/version.js";
 import { eolLengthAt, normalizeEol } from "../core/eol.js";
 const MARK = "# >>> hunch post-commit >>>";
@@ -617,6 +618,11 @@ function sharedInvocationFor(root, mark, invocation, own) {
  *  or the block would sit after an exec/exit, nothing is written and the result
  *  carries the snippet to add by hand (issue #311). */
 function installManagedBlock(root, hookName, mark, end, build, invocation) {
+    // A linked worktree whose branch predates the opt-out marker shares the main
+    // checkout's hooks dir: never re-hook a repository `hunch uninstall` opted out (#488).
+    const main = mainWorktreeRoot(root);
+    if (isOptedOut(main))
+        return { path: resolve(root, hooksDir(root), hookName), action: "opted-out", reason: `${join(main, OPT_OUT_FILE)} opts this repository out` };
     const t = resolveHookTarget(root, hookName, mark);
     if (t.manager !== "none") {
         const info = blockInfo(t, mark, root);
@@ -787,14 +793,12 @@ export function installPreCommitHook(root, invocation, strict = false) {
     };
     return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, build, invocation);
 }
-// Original marker, kept byte-for-byte for backward compat: an existing install's
-// grounding-refresh block must still be found and updated in place by its own
-// exact marker text (fnd_c402046ac7).
+// The original grounding marker is kept unchanged for backward compatibility, so an
+// existing grounding block is still found and updated in place.
 const GROUNDING_MERGE_MARK = "# >>> hunch post-merge >>>";
 const GROUNDING_MERGE_END = "# <<< hunch post-merge <<<";
-// Distinct marker for the (newer) repair-provenance half, so the two blocks
-// never collide inside the same post-merge hook file and each can be
-// independently created/updated/removed without touching the other.
+// The repair-provenance block gets a SEPARATE marker so the two blocks never collide
+// in one post-merge file and each can be created, updated or removed on its own.
 const REPAIR_MERGE_MARK = "# >>> hunch post-merge (repair-provenance) >>>";
 const REPAIR_MERGE_END = "# <<< hunch post-merge (repair-provenance) <<<";
 function groundingMergeBlock(invocation) {
@@ -813,43 +817,38 @@ function repairProvenanceMergeBlock(invocation) {
         REPAIR_MERGE_MARK,
         'if [ -z "$HUNCH_MERGE_SYNC" ]; then',
         "  export HUNCH_MERGE_SYNC=1",
-        // No --apply: this only detects a squash-merge orphaning a decision's commit
-        // and queues the match (.hunch/pending-commit-repairs.json, local-only) for a
-        // human to confirm via `hunch repair-provenance --apply` — the match signal
-        // (file-set overlap, not git's own rename detection) isn't strong enough to
-        // trust an unattended, backgrounded write into shared team memory.
+        // Detect-and-queue only, never --apply: the file-overlap match is not strong
+        // enough to trust an unattended write to shared memory. A human confirms the
+        // queue (.hunch/pending-commit-repairs.json) with `repair-provenance --apply`.
         `  ( ${invocation} repair-provenance --from-hook --quiet >/dev/null 2>&1 || true ) &`,
         "fi",
         REPAIR_MERGE_END,
     ].join("\n");
 }
-/** How significant a combined install result is, for picking one HookInstall
- *  action out of two independent sub-installs into the same file — "created"
- *  (the file itself is new) outranks "appended"/"updated" (an existing file
+/** Rank used to pick ONE HookInstall action out of two independent sub-installs
+ *  into the same file. "created" (the file itself is new) outranks "appended" /
+ *  "updated" (an existing file
  *  changed), which outrank "unchanged". Non-writing results are handled before
  *  ranking (they must never be masked by a sibling's success). */
-const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "kept-shared": 1, "managed-elsewhere": 0, unreachable: 0 };
-const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable";
-/** Install a post-merge hook carrying TWO independently-managed blocks:
- *  re-sync the committed grounding docs when a merge brought memory in behind
- *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
- *  files and can never fail the merge), and opportunistically DETECT a
- *  decision's commit provenance going orphaned right after a squash-merged
- *  branch lands locally (including a fast-forward from `git pull`) — while
- *  the original commits are still fully intact and matchable — queuing the
- *  match for a human to confirm via `hunch repair-provenance --apply`
- *  (HUNCH_MERGE_SYNC-guarded, backgrounded; own env var since this hook makes
- *  no commit of its own and so can't reuse HUNCH_SYNC's re-trigger guard).
- *  Each block is keyed by its own marker pair (installManagedBlock), so
- *  re-running updates only its own block, preserves the other untouched, and
- *  a repo carrying only one half (an older install, or a hand-edited hook)
- *  gets the other appended rather than clobbered. */
+const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "kept-shared": 1, "managed-elsewhere": 0, unreachable: 0, "opted-out": 0 };
+const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable" && h.action !== "opted-out";
+/** Install the post-merge hook. It carries two independently managed blocks:
+ *  - grounding: re-syncs committed grounding docs when a merge brought in memory.
+ *    Guarded by HUNCH_SYNC, runs in the foreground, never fails the merge.
+ *  - repair: detects a decision's commit provenance being orphaned by a
+ *    squash-merge (including a fast-forward from `git pull`) and queues the match
+ *    for `hunch repair-provenance --apply`. Guarded by HUNCH_MERGE_SYNC, runs in
+ *    the background.
+ *  Each block is keyed by its own marker pair, so a re-run updates only its own
+ *  block, and a hook that has only one half gets the other appended, not clobbered. */
 export function installPostMergeHook(root, invocation) {
     // Only the grounding half regenerates committed docs; repair-provenance writes
     // no docs (it only queues a match for a human to confirm), so it keeps the
     // passed invocation unchanged — see selfBuildInvocation.
     const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, (inv, ctx) => groundingMergeBlock(ctx.portable ? inv : selfBuildInvocation(root, inv)), invocation);
     const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock, invocation);
+    if (grounding.action === "opted-out")
+        return grounding;
     if (!writes(grounding) && !writes(repair)) {
         return { ...grounding, snippet: `${grounding.snippet}\n${stripComment(repair.snippet ?? "", grounding.manager)}` };
     }
@@ -1025,6 +1024,8 @@ export function formatHookInstall(root, label, h, detail = "") {
         const how = h.keptFlags?.length ? KEPT_HOW : "";
         return [`  ✓ ${label} kept — the shared hook keeps running ${h.sharedInvocation}${flags} (not re-pointed at this worktree)${how}`];
     }
+    if (h.action === "opted-out")
+        return [`  - ${label} skipped — ${h.reason}`];
     if (writes(h)) {
         // A union write (issue #316). Once an option was KEPT, `detail` — which
         // describes only what this run asked for — is no longer the truth about the