@davesheffer/hunch 1.39.2 → 1.39.3

package/dist/integrations/hooks.js

@@ -16,6 +16,7 @@
 import { readFileSync, writeFileSync, existsSync, chmodSync, mkdirSync, realpathSync } from "node:fs";
 import { spawnSync } from "node:child_process";
 import { join, isAbsolute, dirname, basename, relative, resolve } from "node:path";
+import { homedir } from "node:os";
 import { hooksDir, gitCommonDir } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
 import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
@@ -213,29 +214,222 @@ function preCommitId(mark) {
         [CHECKOUT_MARK]: "hunch-post-checkout",
     }[mark] ?? "hunch";
 }
-/** Whether our block for `mark` is present where git will actually run it. */
-function blockState(t, mark) {
+const ENV_ASSIGN = /^[A-Za-z_][A-Za-z0-9_]*=\S*$/;
+const UNQUOTED_META = /[;|&$`<>()]/;
+const LAUNCHER_EXT = /\.(?:exe|cmd|bat|ps1)$/;
+const HUNCH_ENTRY = /\/cli\/index\.(?:js|ts)$/;
+/** Split an invocation into simple shell words. Hunch writes its own paths with
+ *  JSON.stringify, so a double-quoted token decodes with JSON.parse. Anything a
+ *  shell would treat as more than a plain command (metacharacters, expansions,
+ *  an unterminated quote) yields null — we refuse to guess. */
+function shellWords(s) {
+    const out = [];
+    let i = 0;
+    while (i < s.length) {
+        const c = s[i];
+        if (/\s/.test(c)) {
+            i++;
+            continue;
+        }
+        if (c === '"' || c === "'") {
+            const end = s.indexOf(c, i + 1);
+            if (end < 0)
+                return null;
+            const raw = s.slice(i, end + 1);
+            if (c === '"') {
+                if (/[$`]/.test(raw))
+                    return null;
+                try {
+                    out.push(JSON.parse(raw));
+                }
+                catch {
+                    return null;
+                }
+            }
+            else
+                out.push(raw.slice(1, -1));
+            i = end + 1;
+            continue;
+        }
+        let j = i;
+        while (j < s.length && !/\s/.test(s[j]))
+            j++;
+        const word = s.slice(i, j);
+        if (UNQUOTED_META.test(word))
+            return null;
+        out.push(word);
+        i = j;
+    }
+    return out;
+}
+/** The launcher's own name: last path segment, lower-cased, without a Windows
+ *  executable extension — so `/usr/local/bin/hunch`, `hunch.cmd` and `hunch` all match. */
+function base(tok) {
+    return (tok.split(/[\\/]/).at(-1) ?? "").toLowerCase().replace(LAUNCHER_EXT, "");
+}
+function isAbs(tok) {
+    return isAbsolute(tok) || /^[A-Za-z]:[\\/]/.test(tok);
+}
+function isPathish(tok) {
+    return tok.includes("/") || tok.includes("\\") || isAbs(tok);
+}
+function pathExists(tok, root) {
+    // A hand-written hook may spell this machine's install as `~/…`; the shell
+    // expands it, so we must too before asking the filesystem.
+    const path = tok === "~" ? homedir() : tok.startsWith("~/") ? join(homedir(), tok.slice(2)) : tok;
+    return existsSync(isAbs(path) ? path : resolve(root, path));
+}
+const NOT_OURS = "not a command Hunch writes";
+/** Whether the command in front of a managed block's subcommand is a Hunch
+ *  launcher that could actually run (issue #315): a block whose command was
+ *  hand-edited into something else, or whose absolute node/CLI path no longer
+ *  exists after a reinstall, is present but dead. `command` is the text BEFORE
+ *  the subcommand; env assignments and a leading `(` belong to the block's own
+ *  shape and are stripped. Never spawns anything, never touches the network. */
+export function hookInvocationHealth(command, root) {
+    let rest = command.trim().replace(/^\(\s*/, "");
+    for (;;) {
+        const m = /^(\S+)\s+/.exec(rest);
+        if (!m || !ENV_ASSIGN.test(m[1]))
+            break;
+        rest = rest.slice(m[0].length);
+    }
+    const invocation = rest.trim();
+    const bad = (reason) => ({ ok: false, invocation, reason });
+    const toks = shellWords(invocation);
+    if (toks === null || toks.length === 0)
+        return bad(NOT_OURS);
+    const [head, ...rest2] = toks;
+    const missing = (tok) => `${tok} does not exist`;
+    // `<runtime> <script…>`: every non-flag token after the runtime is a script
+    // path (`<node> <cli>`, or tsx's `<node> <tsx> <cli>`) — a runtime flag like
+    // `--no-warnings` is not a path, but a runtime with no script at all is not ours.
+    const runtime = () => {
+        if (isPathish(head) && !pathExists(head, root))
+            return bad(missing(head));
+        const scripts = rest2.filter((t) => !t.startsWith("-"));
+        if (scripts.length === 0)
+            return bad(NOT_OURS);
+        const gone = scripts.find((t) => !pathExists(t, root));
+        return gone === undefined ? { ok: true, invocation } : bad(missing(gone));
+    };
+    switch (base(head)) {
+        case "hunch":
+            if (rest2.length > 0)
+                return bad(NOT_OURS);
+            if (isPathish(head) && !pathExists(head, root))
+                return bad(missing(head));
+            return { ok: true, invocation };
+        case "node":
+            return rest2.length === 0 ? bad(NOT_OURS) : runtime();
+        case "npx":
+        case "pnpm":
+        case "yarn":
+        case "bunx":
+        case "npm":
+        case "env": {
+            // A package runner in front of the launcher: `npx -y --package=…@x.y.z hunch`
+            // (PORTABLE_HOOK_INVOCATION), `npx hunch`, and the shapes users adapt the
+            // snippet into by hand (`pnpm exec hunch`, `yarn run hunch`, `npm exec --
+            // hunch`, `env X=1 hunch`). What the runner would resolve is never verified —
+            // doing so would mean a network install — so only the launcher it ends in is read.
+            const args = rest2.filter((t) => !t.startsWith("-"));
+            const last = args.at(-1);
+            if (last !== undefined && (base(last) === "hunch" || /^@davesheffer\/hunch(?:@\S+)?$/.test(last)))
+                return { ok: true, invocation };
+            const tsx = args.indexOf("tsx");
+            if (tsx >= 0 && args.length === tsx + 2) {
+                return pathExists(args[tsx + 1], root) ? { ok: true, invocation } : bad(missing(args[tsx + 1]));
+            }
+            return bad(NOT_OURS);
+        }
+        default:
+            // `resolveInvocation` writes process.execPath, which is not always named
+            // `node` (Debian's `nodejs`, a version-suffixed binary). Any other runtime
+            // is ours only as an absolute path running Hunch's own CLI entry — else
+            // `hunch init` would rewrite the same block and doctor would call it stale forever.
+            return isAbs(head) && rest2.length > 0 && HUNCH_ENTRY.test(rest2.at(-1).replace(/\\/g, "/")) ? runtime() : bad(NOT_OURS);
+    }
+}
+/** The command each managed block runs, keyed by mark. Resolved inside a
+ *  function (like `preCommitId`) because the marks are declared further down. */
+function blockSubcommand(mark) {
+    return {
+        [MARK]: { re: /(?:^|\s)sync\s+--from-hook\b/, words: "sync --from-hook" },
+        [PRE_MARK]: { re: /(?:^|\s)check\s+--staged\b/, words: "check --staged" },
+        [GROUNDING_MERGE_MARK]: { re: /(?:^|\s)grounding\s+--refresh\b/, words: "grounding --refresh" },
+        [REPAIR_MERGE_MARK]: { re: /(?:^|\s)repair-provenance\b/, words: "repair-provenance" },
+        [CHECKOUT_MARK]: { re: /(?:^|\s)workspaces\s+snapshot\b/, words: "workspaces snapshot" },
+    }[mark] ?? { re: /(?:^|\s)hunch\b/, words: "hunch" };
+}
+/** Hunch's OWN option flags a block's command line may carry after the
+ *  subcommand — the ones `hunch init` decides from its options, so a regenerated
+ *  block silently drops any the re-run does not ask for again. Fixed set, in a
+ *  stable order; anything else on the line is not ours to report. */
+const BLOCK_FLAGS = ["--private", "--commit", "--strict"];
+function blockFlags(line) {
+    return BLOCK_FLAGS.filter((f) => new RegExp(`(?:^|\\s)${escapeRe(f)}(?=\\s|$)`).test(line));
+}
+/** Inspect the command inside `mark`'s block in `file`: the block body is the
+ *  lines between the mark and the closing marker. A block may legitimately carry
+ *  several command lines (or a hand-added one); any working line makes it live. */
+function inspectBlock(file, mark, root) {
+    const { re, words } = blockSubcommand(mark);
+    const text = readText(file) ?? "";
+    const at = text.indexOf(mark);
+    const body = at < 0 ? [] : text.slice(at).replace(/\r/g, "").split("\n").slice(1);
+    let first = null;
+    for (const line of body) {
+        if (/^# <<< hunch /.test(line))
+            break;
+        if (line.trim().startsWith("#"))
+            continue;
+        const m = re.exec(line);
+        if (!m)
+            continue;
+        // Flags belong to the SUBCOMMAND, so they are read from the text after it.
+        const health = { ...hookInvocationHealth(line.slice(0, m.index), root), flags: blockFlags(line.slice(m.index)) };
+        if (health.ok)
+            return health;
+        first ??= health;
+    }
+    return first ?? { ok: false, invocation: "", reason: `the block has no \`hunch ${words}\` command`, flags: [] };
+}
+/** Whether our block for `mark` is present where git will actually run it AND
+ *  its command is a Hunch launcher that exists (issue #315 — a marker alone
+ *  proves nothing about what the block does). */
+function blockInfo(t, mark, root) {
     const inHook = markerState(t.hookPath, mark);
+    // A reachable marker only earns "installed" once its command checks out.
+    const live = (file) => {
+        const health = inspectBlock(file, mark, root);
+        return health.ok
+            ? { state: "installed", invocation: health.invocation, flags: health.flags, file }
+            : { state: "stale", invocation: health.invocation, staleReason: health.reason, flags: health.flags, file };
+    };
     switch (t.manager) {
         case "none":
-            return inHook === "reachable" ? "installed" : inHook === "unreachable" ? "unreachable" : "missing";
+            return inHook === "reachable" ? live(t.hookPath) : { state: inHook === "unreachable" ? "unreachable" : "missing", file: t.hookPath };
         case "husky":
             if (markerState(t.ownerFile, mark) === "reachable")
-                return "installed";
+                return live(t.ownerFile);
             if (markerState(t.ownerFile, mark) === "unreachable" || inHook !== "absent")
-                return "unreachable";
-            return "missing";
+                return { state: "unreachable", file: t.hookPath };
+            return { state: "missing", file: t.ownerFile };
         case "pre-commit": {
             const config = readText(t.ownerFile);
+            // The framework's own config carries the command in its own format; the
+            // `id:` is the contract, so it is taken at face value.
             if (config !== null && new RegExp(`\\bid:\\s*["']?${escapeRe(preCommitId(mark))}["']?\\s*$`, "m").test(config))
-                return "installed";
+                return { state: "installed", file: t.ownerFile };
             // Migration mode: `pre-commit install` moved the previous hook to <hook>.legacy and runs it first.
-            if (markerState(`${t.hookPath}.legacy`, mark) === "reachable")
-                return "installed";
-            return inHook !== "absent" ? "unreachable" : "missing";
+            const legacy = `${t.hookPath}.legacy`;
+            if (markerState(legacy, mark) === "reachable")
+                return live(legacy);
+            return inHook !== "absent" ? { state: "unreachable", file: t.hookPath } : { state: "missing", file: t.ownerFile };
         }
         default: // husky-legacy, tracked-hooks-path, exec-exit: the hook file itself
-            return inHook === "reachable" ? "installed" : inHook === "unreachable" ? "unreachable" : "missing";
+            return inHook === "reachable" ? live(t.hookPath) : { state: inHook === "unreachable" ? "unreachable" : "missing", file: t.hookPath };
     }
 }
 function stripMarkers(blk) {
@@ -276,14 +470,21 @@ function snippetFor(t, mark, build, localInvocation) {
 function installManagedBlock(root, hookName, mark, end, build, invocation) {
     const t = resolveHookTarget(root, hookName, mark);
     if (t.manager !== "none") {
-        if (blockState(t, mark) === "installed")
+        const info = blockInfo(t, mark, root);
+        if (info.state === "installed")
             return { path: t.ownerFile, action: "unchanged", manager: t.manager };
         return {
             path: t.ownerFile,
             action: t.manager === "exec-exit" ? "unreachable" : "managed-elsewhere",
             manager: t.manager,
-            reason: t.reason,
+            // A stale block IS reachable — the manager's file already carries one, it
+            // just cannot run. Saying "a hook manager owns this hook" would send the
+            // user looking for a block that is right there (issue #315).
+            reason: info.state === "stale"
+                ? `the Hunch block in ${basename(info.file)} is stale (${info.staleReason ?? "its command is not a Hunch launcher"}) — replace it with the snippet below`
+                : t.reason,
             snippet: snippetFor(t, mark, build, invocation),
+            ...(info.state === "stale" ? { stale: true } : {}),
         };
     }
     const blk = build(invocation, GIT_CONTEXT);
@@ -422,23 +623,34 @@ export function installPostCheckoutHook(root, invocation) {
 function reportEntry(root, hookName, marks) {
     const states = marks.map((mark) => {
         const t = resolveHookTarget(root, hookName, mark);
-        return { t, state: blockState(t, mark) };
+        return { t, ...blockInfo(t, mark, root) };
     });
     const unreachable = states.find((s) => s.state === "unreachable");
-    const pick = unreachable ?? states.find((s) => s.state === "missing") ?? states[0];
+    const stale = states.find((s) => s.state === "stale");
+    // A dead block outranks a stale one, which outranks a missing one: each is a
+    // stronger statement about why this hook is not doing its job.
+    const pick = unreachable ?? stale ?? states.find((s) => s.state === "missing") ?? states[0];
     if (!pick)
         throw new Error("reportEntry needs at least one marker");
-    const state = unreachable ? "unreachable" : states.every((s) => s.state === "installed") ? "installed" : "missing";
+    const state = unreachable ? "unreachable" : stale ? "stale" : states.every((s) => s.state === "installed") ? "installed" : "missing";
+    const invocation = [...new Set(states.map((s) => s.invocation).filter((i) => !!i))].join(" · ");
+    // Union across the hook's marks, in BLOCK_FLAGS order — a hook is re-installed
+    // as a whole, so a flag on any of its blocks is one a bare re-run would drop.
+    const flags = BLOCK_FLAGS.filter((f) => states.some((s) => s.flags?.includes(f)));
     return {
         state,
         manager: pick.t.manager,
-        path: state === "unreachable" && pick.t.manager !== "husky" ? pick.t.hookPath : pick.t.ownerFile,
-        ...(state === "unreachable" ? { reason: pick.t.reason } : {}),
+        path: state === "unreachable" && pick.t.manager !== "husky" ? pick.t.hookPath : state === "stale" ? pick.file : pick.t.ownerFile,
+        ...(state === "unreachable" ? { reason: pick.t.reason } : state === "stale" ? { reason: pick.staleReason } : {}),
+        ...(invocation ? { invocation } : {}),
+        ...(flags.length ? { flags } : {}),
     };
 }
 /** Read-only diagnostic (used by `hunch doctor`): each managed hook's state —
- *  `installed` (present where git will run it), `unreachable` (present, but
- *  after an exec/exit or in a manager-owned file git never reaches), or
+ *  `installed` (present where git will run it, running a Hunch launcher that
+ *  exists), `unreachable` (present, but after an exec/exit or in a
+ *  manager-owned file git never reaches), `stale` (present where git runs it,
+ *  but its command is not a working Hunch launcher — issue #315), or
  *  `missing`. postMerge requires BOTH halves (grounding-refresh and
  *  repair-provenance) — a repo carrying only one is a partial install, same as
  *  `installPostMergeHook` self-healing it. Never writes anything. */
@@ -451,9 +663,9 @@ export function hookReport(root) {
     };
 }
 /** Boolean view of `hookReport`: a hook counts as installed only when its
- *  managed block is present where git will actually run it, regardless of
- *  whether the invocation inside it happens to be stale. An unreachable block
- *  (issue #311) is NOT installed. */
+ *  managed block is present where git will actually run it AND the command
+ *  inside it is a Hunch launcher that exists. An unreachable block (issue #311)
+ *  and a stale one (issue #315) are both NOT installed. */
 export function hookStatus(root) {
     const r = hookReport(root);
     return {
@@ -463,6 +675,18 @@ export function hookStatus(root) {
         postCheckout: r.postCheckout.state === "installed",
     };
 }
+/** Doctor lines for where each installed/stale hook points (issue #315): hooks
+ *  sharing one invocation share one line, and a line whose invocation is not the
+ *  Hunch currently running says so. Informational — a hook may legitimately
+ *  point at a different install. Pure; the caller adds indentation and dim(). */
+export function hookInvocationLines(report, running) {
+    const named = [["post-commit", report.postCommit], ["post-merge", report.postMerge], ["pre-commit", report.preCommit], ["post-checkout", report.postCheckout]]
+        .filter(([, e]) => e.invocation && (e.state === "installed" || e.state === "stale"));
+    const grouped = new Map();
+    for (const [name, e] of named)
+        grouped.set(e.invocation, [...(grouped.get(e.invocation) ?? []), name]);
+    return [...grouped].map(([inv, names]) => `${names.join(", ")} → ${inv}${running && inv !== running ? ` (differs from the running Hunch: ${running})` : ""}`);
+}
 /** CLI lines for one install result: the usual ✓ line when the block is in a
  *  file git runs, otherwise a warning with the reason and the snippet to add to
  *  the manager's own file. */
@@ -472,7 +696,9 @@ export function formatHookInstall(root, label, h, detail = "") {
     const shown = isInside(root, h.path) ? relative(realish(root), realish(h.path)).replace(/\\/g, "/") : h.path;
     return [
         `  ⚠ ${label} NOT installed — ${h.reason ?? "a hook manager owns this hook"}`,
-        `    add this to ${shown} yourself:`,
+        // A stale block is already there and the reason said to replace it; anything
+        // else is missing and has to be added.
+        `    ${h.stale ? "replace the Hunch block in" : "add this to"} ${shown} yourself:`,
         ...(h.snippet ?? "").split("\n").map((l) => `      ${l}`),
     ];
 }

package/dist/integrations/providers.js

@@ -21,6 +21,7 @@ import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
+import { isHunchHookCommand } from "./hookmatch.js";
 import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
@@ -106,23 +107,7 @@ function isHunchProviderHook(entry) {
     // whose every nested hook is ours is ours; a mixed entry stays foreign.
     if (e && Array.isArray(e.hooks) && e.hooks.length && typeof e.command !== "string")
         return e.hooks.every(isHunchProviderHook);
-    const command = typeof e?.command === "string" ? e.command : "";
-    // Anchored to the shapes hookCommand() writes — a Hunch launcher (the pinned
-    // npm package spec, or a …/index.js|ts path for source installs) plus a tail
-    // of `hook --provider <name>`, tokens quoted or bare. The old unanchored
-    // /index\.(js|ts)/ + /\bhook\b/ pair classified FOREIGN entries like
-    // `node ./hook/index.js` as ours and silently deleted them, violating the
-    // leave-every-foreign-hook-in-place contract (con_8460b6770f, issue #41), so
-    // the bare tail must still carry --provider to match; only the LEGACY
-    // fully-quoted form (written before this quoting fix, and by hunch versions
-    // that predate --provider) may omit it, and its quotes keep it unambiguous.
-    // Source-checkout invocations generated by resolveInvocation point at the
-    // CLI entry specifically. A generic `other-tool/index.js hook` is foreign
-    // even when it happens to use Hunch's old command tail.
-    const launcher = /@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
-    const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
-    const tail = /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command);
-    return launcher && (legacyTail || tail);
+    return isHunchHookCommand(typeof e?.command === "string" ? e.command : "", true);
 }
 /** Merge our command entries into a standard `{ hooks: { Event: [] } }` file.
  * We replace only old Hunch commands and leave every foreign hook in place. */

package/dist/integrations/scaffold.d.ts

@@ -19,7 +19,7 @@ export interface ClaudeHookInstall {
  *   - UserPromptSubmit → remind the agent to consult Hunch.
  * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
  * at run time — so changing firmness needs no settings.json edit. We own only our
- * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * commands (matched by isHunchHookCommand): other hooks and settings are preserved, and a
  * non-empty file we cannot parse THROWS rather than clobbering the user's config.
  */
 export declare function installClaudeHooks(root: string, hookCmd: string): ClaudeHookInstall;

package/dist/integrations/scaffold.js

@@ -6,6 +6,7 @@
 import { readFileSync, existsSync, mkdirSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { join, dirname } from "node:path";
+import { isHunchHookCommand } from "./hookmatch.js";
 /** Merge a `hunch` server entry into .mcp.json, preserving other servers.
  *  A non-empty file we cannot parse THROWS instead of being silently replaced
  *  (con_8460b6770f — it may hold the user's other MCP servers); the caller
@@ -115,25 +116,27 @@ Reconcile decision-grounding drift for **$ARGUMENTS** (or the whole repo).
 3. Only if I explicitly say "the DECISION is stale, not the doc" (Heal B): run /capture to record a superseding decision, then return to step 2 — the prose re-derives from the new decision as a separate confirm.
 4. Report: healed (Heal A), superseded (Heal B), skipped. Never touch the graph except via an explicit Heal B capture.
 `;
-/** A settings.json hook entry is Hunch's if any of its commands is either the
- *  native/source CLI entry (`…/index.js hook`) or the exact published-package
- *  launcher written by older Hunch versions (`npx --package=…@davesheffer/hunch…
- *  hunch hook`). Matching both generations makes an upgrade idempotent instead
- *  of leaving the portable old hook alongside the new native invocation. The
- *  source form still requires `index` to be a full path segment, and the npx form
- *  requires both the scoped package and the `hunch hook` tail, so foreign hooks
- *  are preserved. */
-function isHunchHook(entry) {
-    return !!entry.hooks?.some((h) => {
-        if (typeof h.command !== "string")
-            return false;
-        const command = h.command;
-        const nativeOrSource = /(?:dist|src)[\\/]+cli[\\/]+index\.(js|ts)"?\s+hook\s*$/.test(command);
-        const publishedNpx = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
-            && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?/.test(command)
-            && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
-        return nativeOrSource || publishedNpx;
-    });
+/** Strip Hunch's own commands out of one settings.json hook entry, matching with
+ *  the SAME anchored rule the provider writers use (isHunchHookCommand, issue
+ *  #41) so an unrelated tool that merely shares our layout — `node
+ *  tools/lint/dist/cli/index.js hook` — is never classified as ours. Claude
+ *  Code's hooks carry no `--provider`, hence the bare-tail variant.
+ *
+ *  Filtering per COMMAND rather than per entry is what keeps a MIXED entry (our
+ *  hook and the user's own command side by side) intact: the entry survives with
+ *  its matcher and the user's remaining commands in order, and is dropped only
+ *  when nothing of the user's is left. Dropping the whole entry deleted user
+ *  hooks (con_8460b6770f, issue #310). */
+function withoutHunchCommands(entry, hookCmd) {
+    const hooks = entry.hooks;
+    if (!Array.isArray(hooks))
+        return entry;
+    // The command being installed is ours by definition, whatever shape a future
+    // launcher takes — so a re-run stays idempotent even if the matcher lags it.
+    const kept = hooks.filter((h) => !(typeof h?.command === "string" && (h.command === hookCmd || isHunchHookCommand(h.command, false))));
+    if (kept.length === hooks.length)
+        return entry;
+    return kept.length ? { ...entry, hooks: kept } : null;
 }
 /**
  * Install the Claude Code AGENT hooks into `.claude/settings.json` so the agent
@@ -143,7 +146,7 @@ function isHunchHook(entry) {
  *   - UserPromptSubmit → remind the agent to consult Hunch.
  * Both invoke `hunch hook`, which reads the firmness level from .hunch/config.json
  * at run time — so changing firmness needs no settings.json edit. We own only our
- * entries (matched by isHunchHook): other hooks and settings are preserved, and a
+ * commands (matched by isHunchHookCommand): other hooks and settings are preserved, and a
  * non-empty file we cannot parse THROWS rather than clobbering the user's config.
  */
 export function installClaudeHooks(root, hookCmd) {
@@ -176,7 +179,7 @@ export function installClaudeHooks(root, hookCmd) {
             throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
         }
     }
-    const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
+    const keep = (arr) => (Array.isArray(arr) ? arr.map((entry) => withoutHunchCommands(entry, hookCmd)).filter((e) => e !== null) : []);
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),
         { matcher: "Edit|Write|MultiEdit", hooks: [{ type: "command", command: hookCmd }] },

package/dist/integrations/workspaceLedger.d.ts

@@ -33,6 +33,16 @@ export type SnapshotOutcome = {
     status: "collision";
     record: Workspace;
     reason: string;
+}
+/** A PUBLIC-home snapshot is a commit on the checked-out code branch. While git is replaying
+ *  history (rebase / merge / cherry-pick / revert / bisect) or HEAD is detached, that write
+ *  would land in the middle of the operation — an untracked `ws_*.json` that makes
+ *  `git rebase --continue` abort, or a commit no branch owns. Nothing is lost: the next
+ *  branch checkout or ledger read records this machine. */
+ | {
+    status: "deferred";
+    record: Workspace;
+    reason: "git-operation-in-progress" | "detached-head";
 } | {
     status: "written";
     record: Workspace;

package/dist/integrations/workspaceLedger.js

@@ -11,7 +11,7 @@
  */
 import { execFileSync, spawnSync } from "node:child_process";
 import { createInterface } from "node:readline";
-import { foreignRepoEnv, mainWorktreeRoot } from "../extractors/git.js";
+import { foreignRepoEnv, gitHeadUnsettled, mainWorktreeRoot } from "../extractors/git.js";
 import { hunchPaths } from "../core/paths.js";
 import { readConfig, workspacesConfig } from "../core/config.js";
 import { loadOrCreateMachine } from "../core/machine.js";
@@ -47,6 +47,14 @@ export function recordWorkspaceSnapshot(store, root, opts = {}) {
     if (previous && Date.now() - Date.parse(previous.observed_at) < 86_400_000 && sameWorkspaceContent(previous, record)) {
         return { status: "unchanged", record, previous };
     }
+    // Checked as late as possible (the live snapshot above takes time, and a rebase can start or
+    // finish while it runs). A private overlay is its own repository, whose commits never touch
+    // the code branch, so only a PUBLIC home defers.
+    if (!isPrivate) {
+        const unsettled = gitHeadUnsettled(root);
+        if (unsettled)
+            return { status: "deferred", record, reason: unsettled };
+    }
     try {
         store.putCapture("workspaces", record, isPrivate);
     }

package/dist/mcp/server.d.ts

@@ -7,7 +7,17 @@
  * diagnostics go to stderr.
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { HunchStore } from "../store/hunchStore.js";
+import type { Symbol } from "../core/types.js";
 export declare const publicationVocabulary: (hunchDir: string) => RegExp[];
+/** Resolve a free-form target (symbol id / name / file path) to symbol records.
+ *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
+ *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
+ *  apart on the same question. */
+export declare function resolveSymbols(store: HunchStore, target: string): Symbol[];
+/** Resolve a target to canonical indexed file path(s) (for file-granular blast
+ *  radius). Falls back to the literal target so direct-scope checks still run. */
+export declare function resolveFiles(store: HunchStore, target: string): string[];
 export type RootControlledServer = {
     server: McpServer;
     getRoot: () => string;

package/dist/mcp/server.js

@@ -12,7 +12,8 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
-import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { hunchPaths, findRoot, toPosixTarget, repoRelativeTarget } from "../core/paths.js";
+import { isIndexedPath, matchSymbolsTiered } from "../core/glob.js";
 import { resolveMcpToolset } from "./toolset.js";
 import { readConfig } from "../core/config.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
@@ -454,23 +455,30 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** Resolve a free-form target (symbol id / name / file path) to symbol records. */
-function resolveSymbols(store, target) {
-    target = toPosixTarget(target);
+/** Resolve a free-form target (symbol id / name / file path) to symbol records.
+ *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
+ *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
+ *  apart on the same question. */
+export function resolveSymbols(store, target) {
+    // An absolute target (an agent's edit-payload path, verbatim) never matched
+    // the repo-relative stored file paths below (issue #296).
+    target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
-    const byId = syms.find((s) => s.id === target);
-    if (byId)
-        return [byId];
-    const byName = syms.filter((s) => s.name === target);
-    if (byName.length)
-        return byName;
-    return syms.filter((s) => s.file === target || s.file.endsWith(target));
+    const components = store.json.loadAll("components");
+    // A target that IS a real indexed path (has a symbol, or is covered by an
+    // indexed component even with zero symbols — README.md, package.json, ...)
+    // never falls through to the suffix tier: bare `endsWith` matched unrelated
+    // files that merely end in the same characters — "db.ts" matched "mongodb.ts"
+    // (issue #300), and a same-basename file in another directory leaked its
+    // rules onto a real indexed target with no symbols of its own (issue #299).
+    const indexed = isIndexedPath(target, syms.map((s) => s.file), components.map((c) => c.paths));
+    return matchSymbolsTiered(target, syms, indexed);
 }
 /** Resolve a target to canonical indexed file path(s) (for file-granular blast
  *  radius). Falls back to the literal target so direct-scope checks still run. */
-function resolveFiles(store, target) {
+export function resolveFiles(store, target) {
     const files = new Set(resolveSymbols(store, target).map((s) => s.file));
-    return files.size ? [...files] : [toPosixTarget(target)];
+    return files.size ? [...files] : [repoRelativeTarget(target, store.publicRoot)];
 }
 function pullBackoff(status, finishedAt, failures) {
     if (status === "updated" || status === "current") {

package/dist/serve/writelock.d.ts

@@ -3,11 +3,25 @@
 export declare const STALE_AFTER_MS = 60000;
 /** Longest a writer waits before giving up and telling the caller. */
 export declare const ACQUIRE_TIMEOUT_MS = 10000;
+/** Longest a takeover claim may sit before another contender may clear it. The
+ *  claimed section is a few syscalls, so anything this old means its claimer
+ *  crashed inside it. */
+export declare const CLAIM_STALE_MS = 10000;
 export interface LockOwner {
     pid: number;
     host: string;
     nonce: string;
     at: string;
+    start?: string;
+}
+/** Token seam: the caller's own process-instance token and a probe for another
+ *  pid's, plus the platform the decision table should reason about (the own-pid
+ *  fallback differs on linux, where pid namespaces exist). Injected by tests so
+ *  the identity paths are exercised off linux. */
+export interface StartTokenProbe {
+    self: string | null;
+    of: (pid: number) => string | null;
+    platform?: NodeJS.Platform;
 }
 export declare class WriteLockTimeout extends Error {
     readonly path: string;
@@ -16,7 +30,13 @@ export declare class WriteLockTimeout extends Error {
     constructor(path: string, heldBy: LockOwner | undefined, waitedMs: number);
 }
 export declare function writeLockPath(hunchDir: string): string;
-/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws.
+ *
+ *  `opts.startToken` is an INTERNAL TEST SEAM, not API: it lets the test suite
+ *  drive the process-identity rows of the decision table on a platform that has
+ *  no such identity. Callers outside this repo must leave it unset — the real
+ *  probe (`selfStartToken`/`startTokenOf`) is the only sound one. */
 export declare function withWriteLock<T>(hunchDir: string, fn: () => T | Promise<T>, opts?: {
     timeoutMs?: number;
+    startToken?: StartTokenProbe;
 }): Promise<T>;