@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/integrations/hooks.js

@@ -16,20 +16,26 @@
 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 { hooksDir, gitCommonDir } from "../extractors/git.js";
+import { homedir } from "node:os";
+import { hooksDir, gitCommonDir, isLinkedWorktree } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
 import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
 const MARK = "# >>> hunch post-commit >>>";
 const ENDMARK = "# <<< hunch post-commit <<<";
 const GIT_CONTEXT = { checkoutType: "$3" };
 const PRE_COMMIT_CONTEXT = { checkoutType: "$PRE_COMMIT_CHECKOUT_TYPE" };
-function block(invocation, opts = {}) {
+const LOCAL_ONLY_LINE = "  export HUNCH_SYNTH_PROVIDER=deterministic";
+// Tolerates hand-added quotes: missing the line would let a re-run delete it.
+const LOCAL_ONLY_RE = /^\s*export HUNCH_SYNTH_PROVIDER=["']?deterministic["']?\s*$/m;
+/** How the provider line is named among a result's kept/added options. */
+const LOCAL_ONLY_LABEL = "HUNCH_SYNTH_PROVIDER=deterministic";
+function block(invocation, opts = {}, keep) {
     // --private routes the auto-synthesized decision into the HUNCH_PRIVATE_DIR overlay
     // instead of the public repo. --commit (opt-in) also commits & pushes the repo the
     // decision landed in (the private store under --private, else this repo). The hook
     // script is local (.git/hooks/), never committed.
-    const priv = opts.private ? " --private" : "";
-    const commit = opts.commit ? " --commit" : "";
+    const priv = opts.private || keep?.flags.includes("--private") ? " --private" : "";
+    const commit = opts.commit || keep?.flags.includes("--commit") ? " --commit" : "";
     return [
         MARK,
         'if [ -z "$HUNCH_SYNC" ]; then',
@@ -37,7 +43,7 @@ function block(invocation, opts = {}) {
         // A split-private capture must not make a storage-private promise and then
         // ship the commit diff to a subscription CLI. Shared overlays are a separate
         // team policy, so only the explicit local-only mode forces deterministic.
-        ...(opts.localOnly ? ["  export HUNCH_SYNTH_PROVIDER=deterministic"] : []),
+        ...(opts.localOnly || keep?.localOnly ? [LOCAL_ONLY_LINE] : []),
         `  ( ${invocation} sync --from-hook --quiet${priv}${commit} >/dev/null 2>&1 || true ) &`,
         // Deliberately NO workspace-ledger snapshot here (docs/workspace-ledger.md): a commit
         // changes HEAD, not which branches and worktrees exist — post-checkout covers that, and
@@ -213,29 +219,257 @@ 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));
+}
+/** The flags a freshly BUILT block carries, read the way `inspectBlock` reads an
+ *  installed one: per command line, only from the text after the subcommand. A
+ *  whole-block scan would count a flag that is merely part of the launcher path
+ *  (a Hunch installed under `…/opt --strict x/…`), and so miss a real downgrade.
+ *
+ *  With `liveRoot`, only lines whose launcher works are read — for an INSTALLED
+ *  block's text, where a dead hand-kept line's `--commit` was never in effect
+ *  and carrying it into a rebuild would switch it on. */
+function builtFlags(blk, mark, liveRoot) {
+    const { re } = blockSubcommand(mark);
+    const found = new Set();
+    for (const line of blk.replace(/\r/g, "").split("\n")) {
+        if (line.trim().startsWith("#"))
+            continue;
+        const m = re.exec(line);
+        if (!m)
+            continue;
+        if (liveRoot !== undefined && !hookInvocationHealth(line.slice(0, m.index), liveRoot).ok)
+            continue;
+        for (const f of blockFlags(line.slice(m.index)))
+            found.add(f);
+    }
+    return BLOCK_FLAGS.filter((f) => found.has(f));
+}
+/** The text of `mark`'s block in `cur` (which must contain `mark`): through its
+ *  closing marker, or — when that is missing — up to the next Hunch marker line,
+ *  so another block's command further down is never read as this block's. */
+function ownBlockText(cur, mark, blockRe) {
+    const m = blockRe.exec(cur);
+    if (m)
+        return m[0];
+    const lines = cur.slice(cur.indexOf(mark)).split("\n");
+    const stop = lines.findIndex((l, i) => i > 0 && /^# (?:<<<|>>>) hunch /.test(l));
+    return (stop < 0 ? lines : lines.slice(0, stop)).join("\n");
+}
+/** 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) {
@@ -265,6 +499,107 @@ function snippetFor(t, mark, build, localInvocation) {
     }
     return build(PORTABLE_HOOK_INVOCATION, GIT_CONTEXT);
 }
+/** The repo's worktree tops as `git worktree list --porcelain` reports them:
+ *  `linked` is every entry AFTER the first (the first is always the main
+ *  worktree, or the bare repo) that is not the bare entry, and `count` is how
+ *  many non-bare worktrees the repo has — the number the shared-hooks note
+ *  quotes, which must not include a bare repo's phantom entry. Entries are
+ *  separated by blank lines and each starts with a `worktree <path>` line.
+ *  Read straight from git rather than the workspace ledger: this runs during
+ *  `hunch init`, before any ledger exists. */
+function worktreeTops(root) {
+    const out = gitRun(["worktree", "list", "--porcelain"], root).stdout;
+    if (!out)
+        return { linked: [], count: 0 };
+    const entries = out.replace(/\r/g, "").split(/\n\s*\n/).map((e) => e.split("\n"));
+    const parsed = entries
+        .map((lines) => ({
+        path: lines.find((l) => l.startsWith("worktree "))?.slice("worktree ".length) ?? "",
+        bare: lines.some((l) => l.trim() === "bare"),
+    }))
+        .filter((e) => e.path !== "");
+    return { linked: parsed.slice(1).filter((e) => !e.bare).map((e) => e.path), count: parsed.filter((e) => !e.bare).length };
+}
+/** The LINKED worktree an invocation is bound to — one it can only work from
+ *  inside, because some token is an absolute path under it (that worktree's own
+ *  node_modules install, its own source checkout) — or null.
+ *
+ *  "Inside" counts textually OR physically: a node_modules symlinked out of a
+ *  worktree still dies with `git worktree remove`, and a path spelled through
+ *  the main checkout that realpaths into a worktree is just as bound. A
+ *  RELATIVE path token is bound to nothing: the shell resolves it against the
+ *  hook's own cwd at run time, which is whichever worktree git is running in,
+ *  so it stays correct for all of them. */
+function worktreeBound(invocation, tops) {
+    const toks = shellWords(invocation);
+    if (toks === null)
+        return null;
+    const norm = (p) => (process.platform === "win32" ? resolve(p).toLowerCase() : resolve(p));
+    const textuallyInside = (top, tok) => {
+        const rel = relative(norm(top), norm(tok));
+        return rel === "" || (!rel.startsWith("..") && !isAbsolute(rel));
+    };
+    for (const top of tops) {
+        if (toks.some((t) => isAbs(t) && (textuallyInside(top, t) || isInside(top, t))))
+            return top;
+    }
+    return null;
+}
+/** The (hookName, mark) pairs of every managed block Hunch writes — the sibling
+ *  blocks that share one hooks dir, scanned for a working shared launcher.
+ *  Resolved inside a function (like `preCommitId`) because the marks are
+ *  declared further down. */
+function managedBlocks() {
+    return [
+        ["post-commit", MARK],
+        ["pre-commit", PRE_MARK],
+        ["post-merge", GROUNDING_MERGE_MARK],
+        ["post-merge", REPAIR_MERGE_MARK],
+        ["post-checkout", CHECKOUT_MARK],
+    ];
+}
+/** The repo's existing SHARED invocation to install instead of `invocation`, or
+ *  null to go on as normal (issue #316).
+ *
+ *  Linked worktrees share ONE `<git-common-dir>/hooks` directory. Rebuilding a
+ *  block from a path inside a linked worktree therefore re-points the main
+ *  checkout's and every sibling worktree's hooks at code that disappears with
+ *  `git worktree remove` — leaving all of them dead. So when the repo already
+ *  runs a Hunch bound to NO linked worktree, that invocation wins. The gate is
+ *  the caller's invocation, not `root`: an install run from the MAIN checkout
+ *  with a worktree-bound launcher poisons the shared hooks exactly the same way.
+ *
+ *  `own: true` means the block for THIS mark already carries it (the caller must
+ *  also preserve the flags it carries). Otherwise the answer came from a sibling
+ *  block: `hunch index` self-heals a missing post-merge/post-checkout hook and
+ *  agents run it from worktrees constantly — a missing block must not become the
+ *  way a worktree path gets into the shared hooks while the repo already has a
+ *  working shared launcher. */
+function sharedInvocationFor(root, mark, invocation, own) {
+    const tops = worktreeTops(root).linked;
+    if (tops.length === 0 || !worktreeBound(invocation, tops))
+        return null;
+    if (own.state === "installed") {
+        // A bound invocation always differs from an unbound one, so no separate
+        // "did it change?" test is needed to avoid a pointless rewrite.
+        return own.invocation && !worktreeBound(own.invocation, tops)
+            ? { invocation: own.invocation, own: true, flags: own.flags ?? [] }
+            : null;
+    }
+    for (const [hookName, m] of managedBlocks()) {
+        if (m === mark)
+            continue;
+        const info = blockInfo(resolveHookTarget(root, hookName, m), m, root);
+        if (info.state === "installed" && info.invocation && !worktreeBound(info.invocation, tops)) {
+            // A rebuilt block gets its options from the CALLER, so `own.flags` are
+            // the ones the old block carried that this run may be dropping — reported
+            // (droppedFlags), never restored: restoring one would fabricate a request
+            // nobody made.
+            return { invocation: info.invocation, own: false, flags: own.flags ?? [] };
+        }
+    }
+    return null;
+}
 /** Shared idempotent create/append/update-in-place logic for every hunch git
  *  hook: write a fresh hook file, replace our own managed block in place if the
  *  invocation changed, or append after any pre-existing (non-hunch) hook body
@@ -276,40 +611,108 @@ 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);
+    // Issue #316: the hooks dir is shared with every linked worktree, so prefer
+    // the repo's existing unbound command over a caller path that dies with a
+    // worktree. The invocation text comes from blockInfo, i.e. straight out of the block's
+    // command line with its quoting intact, and inspectBlock only calls a block
+    // healthy when shellWords parsed it into plain words with no shell
+    // metacharacters — so re-embedding that exact text in build() is safe.
+    const info = blockInfo(t, mark, root);
+    const shared = sharedInvocationFor(root, mark, invocation, info);
+    const blk = build(shared?.invocation ?? invocation, GIT_CONTEXT);
+    // A dead own block rebuilt from a SIBLING's launcher keeps neither its command
+    // nor its options; say which options went, so a downgraded strict guard is not
+    // the user's to discover later.
+    // The local-only provider line is such an option too: a privacy promise that
+    // goes must be named, exactly like a flag.
     const hookPath = t.hookPath;
+    const cur = existsSync(hookPath) ? readFileSync(hookPath, "utf8") : null;
+    const blockRe = new RegExp(`${escapeRe(mark)}[\\s\\S]*?${escapeRe(end)}`);
+    const own = cur?.includes(mark) ? ownBlockText(cur, mark, blockRe) : "";
+    const lost = shared && !shared.own
+        ? [...shared.flags.filter((f) => !builtFlags(blk, mark).includes(f)), ...(LOCAL_ONLY_RE.test(own) && !LOCAL_ONLY_RE.test(blk) ? [LOCAL_ONLY_LABEL] : [])]
+        : [];
+    const sharedNote = shared ? { sharedInvocation: shared.invocation, ...(lost.length > 0 ? { droppedFlags: lost } : {}) } : {};
     mkdirSync(dirname(hookPath), { recursive: true });
-    if (!existsSync(hookPath)) {
+    if (cur === null) {
         writeFileSync(hookPath, `#!/bin/sh\n${blk}\n`);
         chmodSync(hookPath, 0o755);
-        return { path: hookPath, action: "created" };
+        return { path: hookPath, action: "created", ...sharedNote };
     }
-    const cur = readFileSync(hookPath, "utf8");
     if (cur.includes(mark)) {
-        const updated = cur.replace(new RegExp(`${escapeRe(mark)}[\\s\\S]*?${escapeRe(end)}`), blk);
+        const closed = blockRe.test(cur);
+        let next = blk;
+        let note = sharedNote;
+        if (shared?.own) {
+            // A worktree-local re-run may ADD options to the shared block, never
+            // remove them or re-point it: an advisory `hunch init` from a worktree
+            // must not silently downgrade the repo's strict pre-commit guard. So the
+            // block is rebuilt as the UNION of what it carries and what this run asks
+            // for. Refusing the whole write over one omitted option would also discard
+            // the one the run DID ask for — a `hunch private` whose --private never
+            // lands keeps capturing into the public store behind a ✓ line.
+            //
+            // What the block carries is read from ALL its WORKING command lines (the
+            // options of a hand-added second line are merged in — the line itself is
+            // not kept: the block is rebuilt from the template), and the provider line
+            // is an option like any flag: a privacy promise is not a re-run's to withdraw.
+            const carried = builtFlags(own, mark, root);
+            const asked = builtFlags(blk, mark);
+            const keepsLocalOnly = LOCAL_ONLY_RE.test(own);
+            const kept = [...carried.filter((f) => !asked.includes(f)), ...(keepsLocalOnly && !LOCAL_ONLY_RE.test(blk) ? [LOCAL_ONLY_LABEL] : [])];
+            const added = [...asked.filter((f) => !carried.includes(f)), ...(!keepsLocalOnly && LOCAL_ONLY_RE.test(blk) ? [LOCAL_ONLY_LABEL] : [])];
+            const keptNote = { ...sharedNote, ...(kept.length > 0 ? { keptFlags: kept } : {}) };
+            // Nothing to add: the block stays byte-identical. Rebuilding it anyway would
+            // let a re-run that asked for nothing rewrite a line someone shaped by hand
+            // (a `--strict || true` softened guard would come back blocking).
+            if (added.length === 0)
+                return { path: hookPath, action: "kept-shared", ...keptNote };
+            next = build(shared.invocation, GIT_CONTEXT, { flags: carried, localOnly: keepsLocalOnly });
+            note = { ...keptNote, addedFlags: added };
+        }
+        // No closing marker: there is nothing to replace in place, and saying
+        // "unchanged" (or "kept") would hide that this run's block never landed.
+        if (!closed) {
+            return {
+                path: hookPath,
+                action: "unreachable",
+                reason: `the Hunch block in ${basename(hookPath)} has no closing \`${end}\` line, so it cannot be updated in place — replace it with the snippet below`,
+                snippet: next,
+                stale: true,
+                live: true,
+            };
+        }
+        const updated = cur.replace(blockRe, () => next);
         if (updated === cur)
-            return { path: hookPath, action: "unchanged" };
+            return { path: hookPath, action: "unchanged", ...sharedNote };
         writeFileSync(hookPath, updated);
         chmodSync(hookPath, 0o755);
-        return { path: hookPath, action: "updated" };
+        return { path: hookPath, action: "updated", ...note };
     }
     const appended = cur.endsWith("\n") ? `${cur}${blk}\n` : `${cur}\n${blk}\n`;
     writeFileSync(hookPath, appended);
     chmodSync(hookPath, 0o755);
-    return { path: hookPath, action: "appended" };
+    return { path: hookPath, action: "appended", ...sharedNote };
 }
 export function installPostCommitHook(root, invocation, opts = {}) {
-    return installManagedBlock(root, "post-commit", MARK, ENDMARK, (inv) => block(inv, opts), invocation);
+    return installManagedBlock(root, "post-commit", MARK, ENDMARK, (inv, _ctx, keep) => block(inv, opts, keep), invocation);
 }
 const PRE_MARK = "# >>> hunch pre-commit (constraint guard) >>>";
 const PRE_END = "# <<< hunch pre-commit <<<";
@@ -319,9 +722,10 @@ const PRE_END = "# <<< hunch pre-commit <<<";
  *  blocking invariant (see strictgate.ts), so it's safe on a shared repo.
  *  Preserves any existing pre-commit hook. */
 export function installPreCommitHook(root, invocation, strict = false) {
-    const build = (inv) => {
-        const cmd = `${inv} check --staged${strict ? " --strict" : ""}`;
-        return [PRE_MARK, strict ? cmd : `${cmd} || true`, PRE_END].join("\n");
+    const build = (inv, _ctx, keep) => {
+        const on = strict || keep?.flags.includes("--strict");
+        const cmd = `${inv} check --staged${on ? " --strict" : ""}`;
+        return [PRE_MARK, on ? cmd : `${cmd} || true`, PRE_END].join("\n");
     };
     return installManagedBlock(root, "pre-commit", PRE_MARK, PRE_END, build, invocation);
 }
@@ -366,7 +770,7 @@ function repairProvenanceMergeBlock(invocation) {
  *  (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, "managed-elsewhere": 0, unreachable: 0 };
+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
@@ -392,7 +796,17 @@ export function installPostMergeHook(root, invocation) {
         return grounding;
     if (!writes(repair))
         return repair;
-    return ACTION_RANK[repair.action] >= ACTION_RANK[grounding.action] ? repair : grounding;
+    const picked = ACTION_RANK[repair.action] >= ACTION_RANK[grounding.action] ? repair : grounding;
+    const other = picked === repair ? grounding : repair;
+    // Either half may be the one that kept the repo's shared invocation (issue
+    // #316); the ranking above can pick the other one. Carry the shared-hook facts
+    // over so the CLI line stays true about what the file now runs.
+    return {
+        ...picked,
+        ...(picked.sharedInvocation ?? other.sharedInvocation ? { sharedInvocation: picked.sharedInvocation ?? other.sharedInvocation } : {}),
+        ...(picked.keptFlags ?? other.keptFlags ? { keptFlags: picked.keptFlags ?? other.keptFlags } : {}),
+        ...(picked.droppedFlags ?? other.droppedFlags ? { droppedFlags: picked.droppedFlags ?? other.droppedFlags } : {}),
+    };
 }
 /** When two snippets for the same file are joined, drop the second's leading
  *  instruction comment (the first already says where it goes). */
@@ -422,23 +836,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 +876,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,17 +888,105 @@ 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})` : ""}`);
+}
+const KEPT_HOW = " — to change its options, re-run `hunch init` with a Hunch that is not inside a linked worktree (a global install, or the main checkout's)";
 /** 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. */
 export function formatHookInstall(root, label, h, detail = "") {
-    if (writes(h))
-        return [`  ✓ ${label} ${h.action}${detail}`];
+    // kept-shared deliberately drops `detail`: it describes the options this run
+    // ASKED for, and a run that asked for FEWER than the shared block carries (an
+    // advisory re-run of a strict guard) would describe a block that is not there
+    // (issue #316).
+    if (h.action === "kept-shared") {
+        const flags = h.keptFlags?.length ? ` with ${h.keptFlags.join(" ")}` : "";
+        // The block kept options this run did not ask for, so the way to remove them
+        // is the one thing worth saying next.
+        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 (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
+        // block: an "advisory" detail beside a kept --strict contradicts itself.
+        const opts = [h.addedFlags?.length ? `added ${h.addedFlags.join(" ")}` : "", h.keptFlags?.length ? `kept its existing ${h.keptFlags.join(" ")}` : ""].filter(Boolean).join(", ");
+        const union = opts ? ` — ${opts} (a worktree re-run adds options, never removes them)${h.keptFlags?.length ? KEPT_HOW : ""}` : "";
+        const said = h.keptFlags?.length ? "" : detail;
+        const lost = h.droppedFlags?.length ? ` — the previous block's ${h.droppedFlags.join(" ")} was not carried over; re-run with the option to restore it` : "";
+        if (h.sharedInvocation)
+            return [`  ✓ ${label} ${h.action}${said} — runs the repo's shared Hunch (${h.sharedInvocation}), not this worktree's${union}${lost}`];
+        return [`  ✓ ${label} ${h.action}${detail}${lost}`];
+    }
     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:`,
+        `  ⚠ ${label} NOT ${h.live ? "updated" : "installed"} — ${h.reason ?? "a hook manager owns this hook"}`,
+        // 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}`),
     ];
 }
+/** The closing line `hunch init` prints about the SHARED hooks dir (issue #316).
+ *  Setup used to claim "sharing the repo's hooks + memory" unconditionally —
+ *  true of memory, but the hooks dir is genuinely shared, so a block pointing
+ *  inside a linked worktree dies for every checkout when that worktree goes.
+ *
+ *  The verdict is read from what the shared blocks ACTUALLY run, not from this
+ *  run's actions: a second `hunch init` writes nothing yet the hooks are just as
+ *  broken, and the main checkout — which never used to get a note at all — is
+ *  where the user can most easily fix it. `installs` only decides between the
+ *  healthy variants. `[]` when the repo has no linked worktree. Read-only. */
+export function sharedHooksNote(root, installs) {
+    const { linked, count } = worktreeTops(root);
+    if (linked.length === 0)
+        return [];
+    const d = hooksDir(root);
+    const dir = isAbsolute(d) ? d : join(root, d);
+    // A hooks dir is shared when git resolves it inside the COMMON dir, or points
+    // outside this checkout entirely. A relative `core.hooksPath` (husky's
+    // `.husky/_`) resolves per checkout, so it is this worktree's alone.
+    const common = gitCommonDir(root);
+    const top = gitRun(["rev-parse", "--show-toplevel"], root).stdout;
+    const dirShared = (common !== "" && isInside(common, dir)) || (top !== "" && !isInside(top, dir));
+    if (dirShared) {
+        const bound = [];
+        const tops = new Set();
+        for (const [hookName, m] of managedBlocks()) {
+            const info = blockInfo(resolveHookTarget(root, hookName, m), m, root);
+            const at = info.invocation ? worktreeBound(info.invocation, linked) : null;
+            if (!at)
+                continue;
+            tops.add(at);
+            if (!bound.includes(hookName))
+                bound.push(hookName);
+        }
+        if (bound.length > 0) {
+            const one = bound.length === 1;
+            // Several blocks may be bound to different worktrees; naming the first one
+            // is enough to find the problem, and the plural says there are more.
+            const where = tops.size > 1 ? `linked worktrees (${[...tops][0]})` : `a linked worktree (${[...tops][0]})`;
+            return [`  ⚠ shared hooks dir (${dir}) — ${bound.join(", ")} run${one ? "s" : ""} Hunch from inside ${where}; removing that worktree breaks ${one ? "it" : "them"} for every checkout of this repo — install Hunch globally or in the main checkout, then re-run \`hunch init\` with it to re-point ${one ? "it" : "them"}`];
+        }
+    }
+    if (!isLinkedWorktree(root))
+        return [];
+    const wrote = installs.some((h) => writes(h));
+    if (!dirShared || !wrote)
+        return ["  ✓ linked worktree — sharing the repo's memory"];
+    if (installs.some((h) => h.sharedInvocation)) {
+        return [`  ✓ linked worktree — sharing the repo's memory; the hooks dir is shared by ${count} worktrees (${dir}) and keeps running the repo's Hunch, not this worktree's`];
+    }
+    return [`  ✓ linked worktree — sharing the repo's hooks + memory (hooks dir is shared by ${count} worktrees: ${dir})`];
+}
 //# sourceMappingURL=hooks.js.map