@davesheffer/hunch 1.39.2 → 1.39.3

package/dist/extractors/git.d.ts

@@ -162,6 +162,11 @@ export declare function isLinkedWorktree(cwd: string): boolean;
 /** Current branch name (e.g. "main", "feat/x"), or "" in detached HEAD / non-repo.
  *  Stamped onto auto-captured decisions so branch-scoped work stays filterable. */
 export declare function currentBranch(cwd: string): string;
+/** Whether HEAD is somewhere a write must not land: mid rebase/merge/cherry-pick/revert/bisect
+ *  ("git-operation-in-progress", which wins when both hold), or detached ("detached-head").
+ *  null when HEAD is a settled branch — and also when git cannot answer at all (not a repo,
+ *  git missing), so a caller keeps its pre-existing behavior rather than failing closed. */
+export declare function gitHeadUnsettled(cwd: string): "git-operation-in-progress" | "detached-head" | null;
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export declare function commitFiles(sha: string, cwd: string): string[];

package/dist/extractors/git.js

@@ -4,7 +4,7 @@ import { execFileSync } from "node:child_process";
 import { createHash } from "node:crypto";
 import { devNull, tmpdir } from "node:os";
 import { isAbsolute, resolve, join, basename, dirname, relative, sep } from "node:path";
-import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync } from "node:fs";
+import { mkdtempSync, openSync, closeSync, readSync, mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync, existsSync } from "node:fs";
 import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
 import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
@@ -1686,14 +1686,25 @@ export function syncExistingHunch(hunchDir, protectedRepoRoot, timeoutMs = CAPTU
     }
 }
 const UNKNOWN_LOCK_STALE_MS = 10 * 60_000;
+// An owner-less lock directory is also a NORMAL transient state: the window
+// between the two mkdir calls in createOwnedCommitLock, the release window where
+// recursive cleanup removes owner-<pid> before the outer directory, and a lost
+// reclaim race. This bounds how long a lock may stay owner-less before it is
+// treated as stranded. At ENTRY it is compared with the directory's mtime
+// (creating the directory, or adding/removing a child entry, touches it), so an
+// old stranded lock no-ops instantly. INSIDE the wait loop it is a local
+// continuously-owner-less timer instead, so the wait depends on neither
+// filesystem mtime semantics nor clock agreement between writers.
+const OWNERLESS_LOCK_FRESH_MS = 2_000;
 function createOwnedCommitLock(lock) {
     let created = false;
     try {
         // mkdir is the exclusive atomic operation here. Renaming a staged directory
         // is NOT exclusive on POSIX: it may replace an already-existing empty lock
         // directory, which would steal a fresh legacy/ownerless lock. There is a
-        // harmless ownerless window between these two mkdir calls; contenders treat
-        // it as held until the conservative legacy TTL expires.
+        // harmless ownerless window between these two mkdir calls: it reads as held,
+        // and is reclaimed only after the conservative legacy TTL expires. A capture
+        // waits it out (waitForCommitLockHandoff); other callers just report busy.
         mkdirSync(lock);
         created = true;
         // Empty directories are not Git worktree entries, so owner metadata cannot
@@ -1781,21 +1792,66 @@ function acquireCommitLock(lock) {
     }
     return createOwnedCommitLock(lock) ? { state: "acquired" } : { state: "held-unknown" };
 }
+/** Is an owner-less lock directory recent enough to be a transient window
+ * rather than a stranded one? Only meaningful for the FIRST snapshot, where
+ * there is no local history to measure against. An unreadable directory is not
+ * assumed transient: only ENOENT is, because the owner may have just finished
+ * releasing. `Math.abs` so a clock-skewed far-FUTURE mtime is not read as
+ * recent forever. */
+function ownerlessLockLooksTransient(lock) {
+    try {
+        return Math.abs(Date.now() - statSync(lock).mtimeMs) <= OWNERLESS_LOCK_FRESH_MS;
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
 function waitForCommitLockHandoff(lock, first, timeoutMs) {
-    if (first.state !== "held-live" || first.ownerPid === process.pid)
+    if (first.state === "held-live" && first.ownerPid === process.pid)
+        return false;
+    // An owner-less FIRST snapshot is either a transient window (creation,
+    // release, lost reclaim race) or a stranded/legacy lock. Only the former is
+    // worth waiting for: a stranded lock must not block the capture for the whole
+    // handoff. This is the one place the WAIT POLICY consults the directory's
+    // mtime; acquireCommitLock still stats it for the legacy reclaim TTL.
+    if (first.state === "held-unknown" && !ownerlessLockLooksTransient(lock))
         return false;
     const deadline = Date.now() + timeoutMs;
     const sleeper = new Int32Array(new SharedArrayBuffer(4));
     let attempt = first;
+    // How long the lock has read as held-unknown CONTINUOUSLY, measured locally:
+    // a sighting of a live owner resets it, because a genuine release window lasts
+    // milliseconds. Reading it from this clock keeps the wait independent of the
+    // filesystem's mtime granularity and of other writers' clocks. Besides a truly
+    // owner-less directory this also covers a dead owner whose reclaim another
+    // process has claimed — equally not a handoff this contender can wait for.
+    let ownerlessSince = first.state === "held-unknown" ? Date.now() : null;
+    // "Held" while the directory is not even there means mkdir keeps failing for a
+    // reason that is not contention — a missing, read-only or full store — and no
+    // amount of waiting will hand anything off. Require a short streak so one
+    // sample taken mid-release is not mistaken for it.
+    let vanishedStreak = 0;
     while (Date.now() < deadline) {
         if (attempt.state === "acquired")
             return true;
-        // Once the first snapshot proved a live owner, an owner-less snapshot can be
-        // the normal release window: recursive cleanup removes owner-<pid> before
-        // removing the outer lock directory. Keep the bounded handoff wait through
-        // that transient state instead of reporting a false busy/no-op result.
-        if (attempt.state === "held-live" && attempt.ownerPid === process.pid)
-            return false;
+        if (attempt.state === "held-live") {
+            if (attempt.ownerPid === process.pid)
+                return false;
+            ownerlessSince = null;
+            vanishedStreak = 0;
+        }
+        else if (attempt.state === "held-unknown") {
+            ownerlessSince ??= Date.now();
+            if (Date.now() - ownerlessSince > OWNERLESS_LOCK_FRESH_MS)
+                return false;
+            if (!existsSync(lock)) {
+                vanishedStreak += 1;
+                if (vanishedStreak >= 3)
+                    return false;
+            }
+            else
+                vanishedStreak = 0;
+        }
         Atomics.wait(sleeper, 0, 0, Math.min(25, deadline - Date.now()));
         attempt = acquireCommitLock(lock);
     }
@@ -1877,6 +1933,27 @@ export function currentBranch(cwd) {
     const b = gitSafe(["rev-parse", "--abbrev-ref", "HEAD"], cwd);
     return b === "HEAD" ? "" : b; // detached HEAD reports "HEAD" — treat as no branch
 }
+/** The state files git writes while it is replaying history. `git rev-parse --git-path`
+ *  resolves each against THIS worktree's private git dir (a linked worktree keeps its own
+ *  rebase-merge/MERGE_HEAD), so a rebase in one worktree never reads as one in another. */
+const UNSETTLED_HEAD_PATHS = ["rebase-merge", "rebase-apply", "MERGE_HEAD", "CHERRY_PICK_HEAD", "REVERT_HEAD", "BISECT_LOG"];
+/** Whether HEAD is somewhere a write must not land: mid rebase/merge/cherry-pick/revert/bisect
+ *  ("git-operation-in-progress", which wins when both hold), or detached ("detached-head").
+ *  null when HEAD is a settled branch — and also when git cannot answer at all (not a repo,
+ *  git missing), so a caller keeps its pre-existing behavior rather than failing closed. */
+export function gitHeadUnsettled(cwd) {
+    // One spawn: `git rev-parse --git-path a --git-path b …` prints one line per path.
+    const out = gitSafe(["rev-parse", ...UNSETTLED_HEAD_PATHS.flatMap((p) => ["--git-path", p])], cwd);
+    if (!out)
+        return null; // git could not answer (not a repo) — fail open
+    const paths = out.split("\n").map((p) => p.trim()).filter(Boolean);
+    if (paths.length !== UNSETTLED_HEAD_PATHS.length)
+        return null;
+    if (paths.some((p) => existsSync(isAbsolute(p) ? p : resolve(cwd, p))))
+        return "git-operation-in-progress";
+    // `git symbolic-ref -q HEAD` exits non-zero exactly when HEAD is detached.
+    return gitSafe(["symbolic-ref", "-q", "HEAD"], cwd) ? null : "detached-head";
+}
 /** Files changed in a single commit. `--root` makes the initial commit (which
  *  has no parent) report its files as additions instead of returning nothing. */
 export function commitFiles(sha, cwd) {

package/dist/extractors/indexer.d.ts

@@ -51,5 +51,15 @@ export declare function assertCompleteRepoScan(scan: RepoScan): void;
  * the durable graph merely by inspecting it. Existing public graph records remain
  * inputs for the same churn/component enrichment semantics as a persisted index. */
 export declare function scanRepo(store: HunchStore, root: string, opts?: ScanRepoOptions): RepoScan;
+/** True for an edge this indexer produced: the scan re-derives exactly these on
+ *  every pass, so they — and only they — are safe to replace wholesale. */
+export declare function isExtractorEdge(edge: Edge): boolean;
+/** Merge a fresh scan into the stored edge set. A scan can only re-derive what
+ *  it extracted; `supersedes` edges (written by the store) and human-reviewed
+ *  Landscape relationships have no other source, so replacing the whole index
+ *  with the scan deleted them on every `hunch index` (issue #288). Non-extractor
+ *  edges are carried forward in their stored order and win an id collision:
+ *  a reviewed or store-written fact outranks a re-derivable one. */
+export declare function mergeScannedEdges(stored: Edge[], scanned: Edge[]): Edge[];
 /** Persist one pure scan into the Git-native source of truth. */
 export declare function indexRepo(store: HunchStore, root: string, opts?: IndexRepoOptions): IndexResult;

package/dist/extractors/indexer.js

@@ -560,6 +560,22 @@ export function scanRepo(store, root, opts = {}) {
         issues,
     };
 }
+/** True for an edge this indexer produced: the scan re-derives exactly these on
+ *  every pass, so they — and only they — are safe to replace wholesale. */
+export function isExtractorEdge(edge) {
+    return edge.schema === "hunch.edge/1" && edge.provenance.source === "extracted";
+}
+/** Merge a fresh scan into the stored edge set. A scan can only re-derive what
+ *  it extracted; `supersedes` edges (written by the store) and human-reviewed
+ *  Landscape relationships have no other source, so replacing the whole index
+ *  with the scan deleted them on every `hunch index` (issue #288). Non-extractor
+ *  edges are carried forward in their stored order and win an id collision:
+ *  a reviewed or store-written fact outranks a re-derivable one. */
+export function mergeScannedEdges(stored, scanned) {
+    const carried = stored.filter((edge) => !isExtractorEdge(edge));
+    const carriedIds = new Set(carried.map((edge) => edge.id));
+    return [...carried, ...scanned.filter((edge) => !carriedIds.has(edge.id))];
+}
 /** Persist one pure scan into the Git-native source of truth. */
 export function indexRepo(store, root, opts = {}) {
     if (opts.requireClean) {
@@ -576,7 +592,7 @@ export function indexRepo(store, root, opts = {}) {
     if (opts.requireComplete)
         assertCompleteRepoScan(scan);
     store.json.replaceAll("symbols", scan.symbols);
-    store.json.replaceAll("edges", scan.edges);
+    store.json.replaceAll("edges", mergeScannedEdges(store.json.loadAll("edges"), scan.edges));
     store.json.replaceAll("components", scan.components);
     return scan.result;
 }

package/dist/extractors/k8sManifest.js

@@ -71,6 +71,20 @@ const BARE_TEMPLATE_LINE = /^\s*(?:-\s+)?\{\{[\s\S]*$/;
 // -- reparenting the item's real children one level up (`containers.name`
 // instead of `containers[0].name`), silently dropping every reference under it.
 const BARE_LIST_MARKER = /^(\s*)-[ \t]*\r?$/;
+// A list item whose ENTIRE content is a block-scalar header (`- |`, `- |-`,
+// `- >`, `- |2`, `- | # comment`) -- the idiomatic way a chart inlines a shell
+// script into `args:`/`command:`. The item's value is opaque TEXT, not YAML,
+// yet the body lines look exactly like manifest fields (a heredoc'd
+// `secretKeyRef:` block is the canonical case), and this line matches neither
+// KEY_LINE (no colon) nor BARE_LIST_MARKER (something follows the dash), so it
+// fell to the unrecognized-line branch and the script body was then scanned as
+// the surrounding container's children -- inventing a reference to a resource
+// that only ever existed as text. The `key: |` form needs no such handling:
+// its body nests under the key's OWN frame, where no reference field-path can
+// match. The rest is captured (not `[|>]` inline) so the header can be run
+// through stripTrailingComment before BLOCK_SCALAR_HEADER, exactly as a
+// key line's value is.
+const BLOCK_SCALAR_LIST_ITEM = /^(\s*)-[ \t]+(.*?)\r?$/;
 // A YAML block-scalar header (`|`, `>`, plus an optional chomping indicator
 // `+`/`-` and/or an explicit indent digit, in either order: `|`, `|-`, `>+`,
 // `|2`, `|2-`, `|-2`). When a key's value is JUST this header, the real
@@ -138,8 +152,21 @@ function scanFieldPaths(text, baseChar) {
     // avoid. Silently ignoring what the scanner can't parse is not safe here;
     // "I can't tell" must read as "unresolved," the same as a real template.
     const unresolvedContainers = new Set();
+    // The framePath of every container that DIRECTLY holds a key written with no
+    // value at all (`tier:`). Deliberately its own set rather than more entries
+    // in unresolvedContainers: an ordinary container like `spec:` legitimately
+    // holds value-less keys (every nested mapping starts with one), so folding
+    // these in would destroy that set's meaning -- "the scanner could not
+    // account for this line". Only a map that is supposed to be FLAT
+    // (selector/labels) cares, and it checks this set itself.
+    const valuelessKeyParents = new Set();
     const stack = [];
     let charOffset = baseChar;
+    // Indent of the `-` of a `- |` list item whose block-scalar body is being
+    // skipped, or null when no such skip is active. The body ends at the first
+    // line indented at or shallower than that dash (YAML's own rule for where a
+    // sequence item's content stops).
+    let blockScalarSkipIndent = null;
     const popToForListItem = (dashIndent) => {
         while (stack.length) {
             const top = stack[stack.length - 1];
@@ -205,6 +232,31 @@ function scanFieldPaths(text, baseChar) {
     for (const line of text.split("\n")) {
         const lineStartChar = charOffset;
         charOffset += line.length + 1; // +1 for the \n split() consumed
+        // Inside a `- |` item's body: these lines are script/config TEXT, so they
+        // must never be read as field structure. Runs after the charOffset
+        // bookkeeping above so skipped lines still advance the offset exactly --
+        // every atChar/endChar after the block scalar depends on it.
+        if (blockScalarSkipIndent !== null) {
+            // A blank line is part of the block scalar (YAML lets a scalar body
+            // contain empty lines at any indent), never its terminator.
+            if (line.trim().length === 0)
+                continue;
+            if (BARE_TEMPLATE_LINE.test(line)) {
+                // A `{{ }}` action line's own indentation carries no structural
+                // meaning (`{{-` chomps it; the `| indent N` idiom puts the action at
+                // column 0 -- see markAllOpenContainersUnresolved), so a column-0
+                // action inside a script body must NOT be read as a dedent that ends
+                // the skip and re-exposes the remaining body lines as fields. Taint
+                // conservatively and stay in the skip: we cannot tell whether the
+                // action sits inside the scalar or after it.
+                markAllOpenContainersUnresolved();
+                continue;
+            }
+            const indent = line.length - line.trimStart().length;
+            if (indent > blockScalarSkipIndent)
+                continue; // still the scalar's body
+            blockScalarSkipIndent = null; // dedented out of the item -- real YAML again
+        }
         if (BARE_TEMPLATE_LINE.test(line)) {
             markAllOpenContainersUnresolved();
             continue;
@@ -215,6 +267,18 @@ function scanFieldPaths(text, baseChar) {
             enterListItem(dashIndent, dashIndent + 1);
             continue;
         }
+        // Checked BEFORE the KEY_LINE match: KEY_LINE can't match this shape
+        // anyway (no colon), but without this branch it would land in the
+        // unrecognized-line branch below and the body would be scanned as fields.
+        const blockScalarItem = BLOCK_SCALAR_LIST_ITEM.exec(line);
+        if (blockScalarItem && BLOCK_SCALAR_HEADER.test(stripTrailingComment(blockScalarItem[2]).trim())) {
+            const dashIndent = blockScalarItem[1].length;
+            // It IS a real sequence item, so enter it exactly as the bare-marker
+            // form does -- sibling items after this one must keep their indices.
+            enterListItem(dashIndent, dashIndent + 1);
+            blockScalarSkipIndent = dashIndent;
+            continue;
+        }
         const m = KEY_LINE.exec(line);
         if (!m) {
             // Any other non-blank, non-comment line is a shape this scanner can't
@@ -268,6 +332,18 @@ function scanFieldPaths(text, baseChar) {
             unresolvedContainers.add(parentPath);
             continue;
         }
+        // A key written with NO value (`tier:`) creates a frame but never an
+        // entry, so it is invisible to extractLiteralLabelMap -- which then
+        // returns the map MINUS that key. For a flat string->string map
+        // (selector/labels) a value-less direct child is either a null value or a
+        // nested container; either way the key is silently absent, and a selector
+        // short one key matches strictly MORE workloads than the real one -- the
+        // same over-permissive failure as every other unresolved case here.
+        // Recorded after the block-scalar branch above, which already taints the
+        // parent for its own reason. Note `tier: ""` is NOT value-less: quotes
+        // survive stripTrailingComment/trim, so it stays a literal empty string.
+        if (value.length === 0)
+            valuelessKeyParents.add(parentPath);
         if (value.length > 0) {
             const colonIdx = line.indexOf(":", dashIndent);
             const valueStartInLine = line.indexOf(value, colonIdx);
@@ -309,7 +385,7 @@ function scanFieldPaths(text, baseChar) {
         // line, since that line's own popToForListItem/popOrdinary call pops
         // back to (but never past) this key's frame.
     }
-    return { entries, unresolvedContainers };
+    return { entries, unresolvedContainers, valuelessKeyParents };
 }
 function findEntry(entries, path) {
     return entries.find((e) => e.path === path);
@@ -422,9 +498,14 @@ export const LABELS_PATH_BY_KIND = {
  *  exists, or any direct-child leaf is itself templated -- a partially-literal
  *  map is still unusable for subset-match without evaluating the templated
  *  half, so the whole map is treated as unresolved. */
-function extractLiteralLabelMap(prefix, entries, unresolvedContainers) {
+function extractLiteralLabelMap(prefix, entries, unresolvedContainers, valuelessKeyParents) {
     if (unresolvedContainers.has(prefix))
         return null;
+    // A value-less direct child (`tier:`) never produced an entry at all, so the
+    // map below would come back without it -- see valuelessKeyParents' comment
+    // in scanFieldPaths for why a short map is the dangerous direction.
+    if (valuelessKeyParents.has(prefix))
+        return null;
     // A real Kubernetes label/selector map is always flat (string -> string) --
     // any entry whose parentPath is a DEEPER descendant of prefix (not prefix
     // itself) means some direct child of prefix was itself a nested container
@@ -464,7 +545,7 @@ function extractLiteralLabelMap(prefix, entries, unresolvedContainers) {
     }
     return pairs.length > 0 ? Object.fromEntries(pairs) : null;
 }
-function buildDocument(text, docStartChar, entries, unresolvedContainers) {
+function buildDocument(text, docStartChar, entries, unresolvedContainers, valuelessKeyParents) {
     const kindEntry = findEntry(entries, "kind");
     const kind = kindEntry?.value.form === "literal" ? kindEntry.value.value : null;
     if (!kind || !ALLOWED_KINDS.has(kind))
@@ -474,20 +555,27 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers) {
         ? { kind, name: nameEntry.value, startChar: docStartChar, endChar: docStartChar + text.length }
         : null;
     const references = [...extractFieldReferences(kind, entries), ...extractOwnerReferenceCandidates(entries)];
-    const selector = kind === "Service" ? extractLiteralLabelMap("spec.selector", entries, unresolvedContainers) : null;
+    const selector = kind === "Service" ? extractLiteralLabelMap("spec.selector", entries, unresolvedContainers, valuelessKeyParents) : null;
     const labelsPath = LABELS_PATH_BY_KIND[kind];
-    const labels = labelsPath ? extractLiteralLabelMap(labelsPath, entries, unresolvedContainers) : null;
+    const labels = labelsPath ? extractLiteralLabelMap(labelsPath, entries, unresolvedContainers, valuelessKeyParents) : null;
     return { resource, references, selector, labels };
 }
-// Matches a YAML document-start marker (`---`, optionally with a trailing
-// comment -- `--- # second doc` is legal YAML) or a document-end marker
-// (`...`). Without the trailing-comment allowance, a commented separator
-// silently failed to split at all, merging two documents into one -- the
-// later document's fields overwrite the earlier one's (object spread order),
-// and the earlier resource's symbol/edges vanish entirely. `----` (four or
-// more dashes) is deliberately NOT a separator -- real YAML doesn't treat it
-// as one either.
-const DOC_SEPARATOR = /^(?:---(?:[ \t]+#.*)?|\.\.\.)[ \t]*\r?$/m;
+// Matches a YAML document-start marker (`---`) or a document-end marker
+// (`...`). Per the YAML spec `---` FOLLOWED BY WHITESPACE starts a document
+// whatever trails it on that line -- a comment (`--- # second doc`), a tag
+// (`--- !!map`), an anchor (`--- &base`) -- so the trailing text is matched
+// generically rather than as a comment only. Without that, a tagged or
+// anchored separator silently failed to split at all, merging two documents
+// into one: the later document's fields overwrite the earlier one's (object
+// spread order), and the earlier resource's symbol/edges vanish entirely.
+// Whatever trails the marker is consumed WITH the boundary -- for a tag or
+// anchor nothing is lost, and inline content written after the marker
+// (`--- kind: Pod`, legal but vanishingly rare) is dropped, which errs toward
+// fewer edges, this module's standing bias. `----` (four or more dashes) is
+// deliberately NOT a separator -- real YAML doesn't treat it as one either,
+// and it still isn't here: the dashes must be followed by whitespace or end
+// of line.
+const DOC_SEPARATOR = /^(?:---(?:[ \t]+.*)?|\.\.\.)[ \t]*\r?$/m;
 export function extractK8sManifest(source) {
     const docs = [];
     const boundaries = [];
@@ -499,8 +587,8 @@ export function extractK8sManifest(source) {
         const start = starts[i];
         const end = ends[i];
         const text = source.slice(start, end);
-        const { entries, unresolvedContainers } = scanFieldPaths(text, start);
-        docs.push(buildDocument(text, start, entries, unresolvedContainers));
+        const { entries, unresolvedContainers, valuelessKeyParents } = scanFieldPaths(text, start);
+        docs.push(buildDocument(text, start, entries, unresolvedContainers, valuelessKeyParents));
     }
     return docs;
 }

package/dist/integrations/hookmatch.d.ts

@@ -0,0 +1,25 @@
+/**
+ * The single rule for "is this hook command Hunch's own?", shared by every hook
+ * writer (scaffold.ts for Claude Code's .claude/settings.json, providers.ts for
+ * Cursor/Codex/VS Code/Windsurf/Antigravity). One rule, because each writer
+ * deletes what it classifies as ours, and a writer that guesses wide deletes the
+ * user's hooks (con_8460b6770f).
+ */
+/** Does one command string invoke Hunch's own hook?
+ *
+ * Anchored to the shapes hookCommand() / resolveInvocation() write — a Hunch
+ * launcher (the pinned npm package spec, or a …/dist|src/cli/index.js|ts path for
+ * source installs) plus a `hook` tail, 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).
+ *
+ * `requireProvider` distinguishes the two writers. Provider configs always carry
+ * `hook --provider <name>`, so their tail must too; only the LEGACY fully-quoted
+ * form (written before the quoting fix, and by hunch versions that predate
+ * --provider) may omit it, and its quotes keep it unambiguous. Claude Code's own
+ * settings.json never carries --provider, so a bare `hook` tail is all that is
+ * left to match on — and a bare tail alone is far too weak, so there the WHOLE
+ * command must be one of the two shapes `hunch init` has ever written (see
+ * isClaudeCodeHookCommand). */
+export declare function isHunchHookCommand(command: string, requireProvider: boolean): boolean;

package/dist/integrations/hookmatch.js

@@ -0,0 +1,58 @@
+/**
+ * The single rule for "is this hook command Hunch's own?", shared by every hook
+ * writer (scaffold.ts for Claude Code's .claude/settings.json, providers.ts for
+ * Cursor/Codex/VS Code/Windsurf/Antigravity). One rule, because each writer
+ * deletes what it classifies as ours, and a writer that guesses wide deletes the
+ * user's hooks (con_8460b6770f).
+ */
+/** Does one command string invoke Hunch's own hook?
+ *
+ * Anchored to the shapes hookCommand() / resolveInvocation() write — a Hunch
+ * launcher (the pinned npm package spec, or a …/dist|src/cli/index.js|ts path for
+ * source installs) plus a `hook` tail, 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).
+ *
+ * `requireProvider` distinguishes the two writers. Provider configs always carry
+ * `hook --provider <name>`, so their tail must too; only the LEGACY fully-quoted
+ * form (written before the quoting fix, and by hunch versions that predate
+ * --provider) may omit it, and its quotes keep it unambiguous. Claude Code's own
+ * settings.json never carries --provider, so a bare `hook` tail is all that is
+ * left to match on — and a bare tail alone is far too weak, so there the WHOLE
+ * command must be one of the two shapes `hunch init` has ever written (see
+ * isClaudeCodeHookCommand). */
+export function isHunchHookCommand(command, requireProvider) {
+    if (!requireProvider)
+        return isClaudeCodeHookCommand(command);
+    const published = /@davesheffer\/hunch/.test(command);
+    const launcher = published || /(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
+    const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
+    return launcher && (legacyTail || /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command));
+}
+const ABSOLUTE = String.raw `(?:\/|[A-Za-z]:[\\/]|\\\\)`;
+const CLI_ENTRY = String.raw `[\\/](?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)`;
+const SOURCE_HOOK = new RegExp(String.raw `^\s*(?:"?npx(?:\.cmd)?"?\s+"?tsx"?|"[^"]+"|\S+)\s+(?:"${ABSOLUTE}[^"]*${CLI_ENTRY}"|${ABSOLUTE}\S*${CLI_ENTRY})\s+"?hook"?\s*$`);
+/** The bare-`hook` shapes written into .claude/settings.json, matched as a whole
+ *  command so nothing chained before or after one can be swept out with it:
+ *
+ *   - published: `npx -y --package=[hunch-exact@npm:]@davesheffer/hunch[@v] hunch hook`
+ *   - source / `npm link` / dev: `<runtime> <ABSOLUTE …/dist|src/cli/index.js|ts> hook`
+ *
+ *  Quoting is NOT the discriminator. shellInvocation() leaves a safe token bare, so
+ *  since v1.21.1 a POSIX source install writes `/usr/bin/node /abs/dist/cli/index.js
+ *  hook` with no quotes at all (quotes appear only for a space or a Windows
+ *  backslash, and on every token before v1.21.1). Requiring them left our own hook
+ *  in place and appended another on each `hunch init`. What every version shares is
+ *  an absolute entry path — resolveInvocation() derives it from import.meta.url —
+ *  and that is what keeps a tool which merely shares the layout
+ *  (`node tools/lint/dist/cli/index.js hook`) foreign; deleting it was issue #310.
+ *  A foreign tool invoked by ABSOLUTE path with this exact layout and a lone `hook`
+ *  argument is still indistinguishable by string alone. */
+function isClaudeCodeHookCommand(command) {
+    const published = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
+        && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?(?=["\s])/.test(command)
+        && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
+    return published || SOURCE_HOOK.test(command);
+}
+//# sourceMappingURL=hookmatch.js.map

package/dist/integrations/hooks.d.ts

@@ -18,6 +18,9 @@ export interface HookInstall {
     reason?: string;
     /** What to add to `path` by hand (non-writing actions only). */
     snippet?: string;
+    /** The file already carries a Hunch block, but a dead one: the snippet
+     *  REPLACES it rather than being added (non-writing actions only). */
+    stale?: boolean;
 }
 /** Portable invocation for text that lands in a TRACKED file (a husky script, a
  *  committed hooks dir, .pre-commit-config.yaml): the same exact-version npx
@@ -30,7 +33,23 @@ export declare const PORTABLE_HOOK_INVOCATION: string;
  *  or a trailing top-level `if … else … fi` whose every branch ends in
  *  `exec`/`exit` — the shape of the pre-commit framework's generated hook. */
 export declare function terminalExitLine(content: string): string | null;
-type BlockState = "installed" | "unreachable" | "missing";
+type BlockState = "installed" | "unreachable" | "stale" | "missing";
+/** The result of inspecting the command a managed block actually runs (issue #315). */
+export type HookInvocationHealth = {
+    ok: true;
+    invocation: string;
+} | {
+    ok: false;
+    invocation: string;
+    reason: string;
+};
+/** 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 declare function hookInvocationHealth(command: string, root: string): HookInvocationHealth;
 export declare function installPostCommitHook(root: string, invocation: string, opts?: {
     private?: boolean;
     commit?: boolean;
@@ -64,8 +83,13 @@ export interface HookReportEntry {
     manager: HookManagerKind;
     /** The file where the block lives (or should live). */
     path: string;
-    /** Why an `unreachable` block never runs. */
+    /** Why an `unreachable` block never runs, or why a `stale` one could not work. */
     reason?: string;
+    /** Where the hook points: the distinct invocations of its marks' blocks. */
+    invocation?: string;
+    /** Hunch's own option flags the hook's blocks carry (`--private`, `--commit`,
+     *  `--strict`) — what a plain `hunch init` re-run would drop. Omitted when none. */
+    flags?: string[];
 }
 export interface HookReport {
     postCommit: HookReportEntry;
@@ -74,22 +98,29 @@ export interface HookReport {
     postCheckout: HookReportEntry;
 }
 /** 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. */
 export declare function hookReport(root: string): HookReport;
 /** 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 declare function hookStatus(root: string): {
     postCommit: boolean;
     preCommit: boolean;
     postMerge: boolean;
     postCheckout: boolean;
 };
+/** 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 declare function hookInvocationLines(report: HookReport, running: string): string[];
 /** 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. */