@davesheffer/hunch 1.39.2 → 1.40.0

package/dist/store/changeLedger.d.ts

@@ -128,9 +128,15 @@ export declare function compactLedger(hunchDir: string, scope: Scope, opts?: {
 /** Three-way merge of one scope's ledger, for the git merge driver: two clones that both
  *  appended to the same partition. The union of events is kept (identity = what changed, to
  *  which hash, when, by whom), ordered by time then ours-before-theirs, and RE-SEQUENCED from
- *  the higher floor; every subscriber's cursor is therefore invalid after a merge and the gap
- *  rule makes it resynchronize. Idempotency entries are unioned; a key both sides used for
- *  different records is a conflict the caller must surface (ours is kept). */
+ *  the higher floor. When that renumbering moves an event either side had already published,
+ *  no pre-merge cursor of EITHER side can be trusted — a cursor could otherwise sit above an
+ *  event that now holds a lower seq and never see it (issue #285). The floor is then raised
+ *  past BOTH pre-merge heads, so every such cursor satisfies subscribe's `after_seq <
+ *  floor_seq` and resynchronizes from the floor; a cursor equal to the larger head is exactly
+ *  the failing case, hence the `+ 1`. A merge that renumbers nothing keeps today's seqs (no
+ *  cursor could have seen a different numbering) and the floor stays put. Idempotency entries
+ *  are unioned; a key both sides used for different records is a conflict the caller must
+ *  surface (ours is kept). */
 export declare function mergeLedgers(base: Ledger | null, ours: Ledger, theirs: Ledger): {
     ledger: Ledger;
     conflicts: string[];

package/dist/store/changeLedger.js

@@ -5,9 +5,9 @@
  * other record, appended atomically (con_902759b3dc). It holds the strictly ordered
  * ChangeEvent stream for that scope (seq 1, 2, 3 … with no gaps) plus the idempotency
  * table the write verb replays from. Seq is per scope, assigned by the writer in the
- * home the scope lives in; a scope has exactly ONE ledger, so there is never a second
- * sequence to reconcile. Merging two clones' ledgers for the same scope is not decided
- * here (see docs/nuryel-state-contract.md, "Not decided here").
+ * home the scope lives in; a scope has exactly ONE ledger per clone, so within a clone there
+ * is never a second sequence to reconcile. Two clones that both appended to one scope are
+ * reconciled by `mergeLedgers` (below), for the git merge driver.
  */
 import { mkdirSync } from "node:fs";
 import { basename, join, resolve } from "node:path";
@@ -34,8 +34,9 @@ export const LedgerSchema = z.object({
     schema: z.literal(LEDGER_SCHEMA_VERSION),
     scope: ScopeSchema,
     head_seq: z.number().int().nonnegative(),
-    /** Events below this seq were compacted away. `events` starts at floor_seq + 1. A subscriber
-     *  whose cursor is below the floor must resynchronize (the contract's gap rule, made explicit). */
+    /** Events below this seq were compacted away, or were invalidated by a merge that renumbered
+     *  them (see `mergeLedgers`). `events` starts at floor_seq + 1. A subscriber whose cursor is
+     *  below the floor must resynchronize (the contract's gap rule, made explicit). */
     floor_seq: z.number().int().nonnegative().default(0),
     events: z.array(ChangeEventSchema),
     idempotency: z.record(z.string(), IdempotencyEntrySchema).default({}),
@@ -151,9 +152,15 @@ const eventIdentity = (e) => [e.change, e.facet, e.record_id, e.record_hash, e.a
 /** Three-way merge of one scope's ledger, for the git merge driver: two clones that both
  *  appended to the same partition. The union of events is kept (identity = what changed, to
  *  which hash, when, by whom), ordered by time then ours-before-theirs, and RE-SEQUENCED from
- *  the higher floor; every subscriber's cursor is therefore invalid after a merge and the gap
- *  rule makes it resynchronize. Idempotency entries are unioned; a key both sides used for
- *  different records is a conflict the caller must surface (ours is kept). */
+ *  the higher floor. When that renumbering moves an event either side had already published,
+ *  no pre-merge cursor of EITHER side can be trusted — a cursor could otherwise sit above an
+ *  event that now holds a lower seq and never see it (issue #285). The floor is then raised
+ *  past BOTH pre-merge heads, so every such cursor satisfies subscribe's `after_seq <
+ *  floor_seq` and resynchronizes from the floor; a cursor equal to the larger head is exactly
+ *  the failing case, hence the `+ 1`. A merge that renumbers nothing keeps today's seqs (no
+ *  cursor could have seen a different numbering) and the floor stays put. Idempotency entries
+ *  are unioned; a key both sides used for different records is a conflict the caller must
+ *  surface (ours is kept). */
 export function mergeLedgers(base, ours, theirs) {
     if (scopePath(ours.scope) !== scopePath(theirs.scope))
         throw new Error("ledgers for different scopes cannot be merged");
@@ -169,9 +176,28 @@ export function mergeLedgers(base, ours, theirs) {
         add(e);
     for (const e of theirs.events)
         add(e);
-    const ranked = order.map((e, i) => ({ e, i, side: (ours.events.includes(e) ? 0 : 1) }));
+    // The tiebreak is "ours before theirs", so only an event theirs ALONE contributed sorts late:
+    // side 1 iff theirs holds it and neither ours nor base does. Deciding by object identity
+    // (`includes`) would instead put anything ours compacted away — base's object, which `add`
+    // keeps — after its same-`at` siblings and silently reorder a batch both sides already had.
+    const ourIdentities = new Set(ours.events.map(eventIdentity));
+    const baseIdentities = new Set((base?.events ?? []).map(eventIdentity));
+    const theirsOnly = (e) => {
+        const k = eventIdentity(e);
+        return !ourIdentities.has(k) && !baseIdentities.has(k);
+    };
+    const ranked = order.map((e, i) => ({ e, i, side: (theirsOnly(e) ? 1 : 0) }));
     ranked.sort((a, b) => a.e.at.localeCompare(b.e.at) || a.side - b.side || a.i - b.i);
-    const floor = Math.max(base?.floor_seq ?? 0, ours.floor_seq, theirs.floor_seq);
+    const theirSeqs = new Map(theirs.events.map((e) => [eventIdentity(e), e.seq]));
+    const ourSeqs = new Map(ours.events.map((e) => [eventIdentity(e), e.seq]));
+    let floor = Math.max(base?.floor_seq ?? 0, ours.floor_seq, theirs.floor_seq);
+    const renumbers = ranked.some(({ e }, i) => {
+        const k = eventIdentity(e);
+        const merged = floor + i + 1;
+        return (ourSeqs.get(k) ?? merged) !== merged || (theirSeqs.get(k) ?? merged) !== merged;
+    });
+    if (renumbers)
+        floor = Math.max(floor, Math.max(ours.head_seq, theirs.head_seq) + 1);
     const events = ranked.map(({ e }, i) => ({ ...e, seq: floor + i + 1 }));
     const conflicts = [];
     const idempotency = { ...(base?.idempotency ?? {}), ...theirs.idempotency, ...ours.idempotency };

package/dist/store/hunchStore.d.ts

@@ -335,6 +335,29 @@ export declare class HunchStore {
      *  present in the indexed symbol/component tables can enter the frontier, so
      *  shared external-package hubs never become context or bridge unrelated symbols. */
     private graphExpand;
+    /** The WIDE definition of "is `t` a real path?" — the gate used by the matchers
+     *  that ATTRIBUTE records to a target silently (why(), liveFindingsFor, tasksFor,
+     *  `resolveSymbols` in the MCP server). They also run for a file an agent is
+     *  about to create, where the covering component glob is the only signal there
+     *  is, so the answer must not depend on the file already being on disk. The
+     *  resolvers that NAME the file they resolved to (resolveNodeIds, structure())
+     *  deliberately use the narrower `isRepoFile` instead.
+     *
+     *  Graph data FIRST (a symbol's exact file, or an indexed component's path glob),
+     *  so a deleted-but-still-indexed path and a time-travel (`asOf`) query answer the
+     *  same as before (issue #299). The working tree is consulted only as a LAST
+     *  resort, for the case the index cannot see: a real file with zero tree-sitter
+     *  symbols and no covering component glob, which otherwise suffix-leaked an
+     *  unrelated same-basename file's records (issue #334). When the working tree is
+     *  unavailable or the file is gone, behaviour is exactly the pre-#334 behaviour.
+     *
+     *  `t` must already be repo-relative (`repoRelativeTarget`). `graph` lets a caller
+     *  that has already narrowed the graph (why()'s `canRead` visibility filter) ask
+     *  the question over exactly the records it may see, rather than all of them. */
+    isKnownPath(t: string, graph?: {
+        symbols: readonly Symbol[];
+        components: readonly Component[];
+    }): boolean;
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
      *  return only decisions/constraints whose valid-time window contained that
@@ -379,7 +402,20 @@ export declare class HunchStore {
      *  or the id itself when unindexed. */
     nodeLabel(id: string): string;
     /** Resolve a free-form target (symbol id / name / file path, component id / name)
-     *  to graph node ids — symbols win over components, exact file before suffix. */
+     *  to graph node ids — symbols win over components, exact file before suffix.
+     *  Shares why()/resolveSymbols' tiered matcher rather than one un-tiered SQL OR:
+     *  the flat query matched every tier at once, so a root `index.ts` also returned
+     *  `a/index.ts`'s symbols, and an absolute target matched nothing at all (#335).
+     *
+     *  The suffix gate here is `isRepoFile`, NOT the wider `isKnownPath`: the
+     *  exact-file tier has already run, so the only case left is a real on-disk file
+     *  with zero symbols (#334). Glob coverage alone would wrongly block a target
+     *  that no file actually carries — with a `src/**` component, `src/x.ts` living
+     *  at `packages/a/src/x.ts` stopped resolving. This resolver names the file it
+     *  resolved to in its result, so a suffix resolution is visible and only a file
+     *  that really exists may block it; why()/the pre-edit hook attribute records
+     *  silently and also run for a file about to be created, so they keep the wider
+     *  `isKnownPath`. */
     resolveNodeIds(target: string): string[];
     /** PR impact (read-only, ADVISORY — never gates): the dependency + memory surface
      *  of a change. Composes the SAME primitives as buildCheckReport (blast radius,
@@ -590,9 +626,13 @@ export type StructureView = {
         callers: string[];
         callees: string[];
     }>;
-} | {
+}
+/** `realFile`: the target IS a regular file in the working tree, it just has no
+ *  indexed symbols — a different answer from "no such path" (#334). */
+ | {
     kind: "none";
     target: string;
+    realFile?: boolean;
 };
 export interface StaleRecord {
     kind: string;

package/dist/store/hunchStore.js

@@ -12,14 +12,14 @@
  */
 import { resolve, join, dirname, isAbsolute, relative } from "node:path";
 import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
-import { toPosixTarget, hunchPathsForDir } from "../core/paths.js";
+import { toPosixTarget, repoRelativeTarget, isRepoFile, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { gitCommonDir, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
-import { pathMatchesGlob, pathsRelated } from "../core/glob.js";
+import { pathMatchesGlob, pathsRelated, isIndexedPath, matchSymbolsTiered } from "../core/glob.js";
 import { cochangeFor } from "../core/cochange.js";
 import { withServedDatabase } from "../core/served.js";
 import { normalizePath, rankTaskRecords, recordIdsOf, selectLatestTasks, selectTaskSlots } from "../core/taskRanking.js";
@@ -1178,13 +1178,40 @@ export class HunchStore {
         }
         return hits;
     }
+    /** The WIDE definition of "is `t` a real path?" — the gate used by the matchers
+     *  that ATTRIBUTE records to a target silently (why(), liveFindingsFor, tasksFor,
+     *  `resolveSymbols` in the MCP server). They also run for a file an agent is
+     *  about to create, where the covering component glob is the only signal there
+     *  is, so the answer must not depend on the file already being on disk. The
+     *  resolvers that NAME the file they resolved to (resolveNodeIds, structure())
+     *  deliberately use the narrower `isRepoFile` instead.
+     *
+     *  Graph data FIRST (a symbol's exact file, or an indexed component's path glob),
+     *  so a deleted-but-still-indexed path and a time-travel (`asOf`) query answer the
+     *  same as before (issue #299). The working tree is consulted only as a LAST
+     *  resort, for the case the index cannot see: a real file with zero tree-sitter
+     *  symbols and no covering component glob, which otherwise suffix-leaked an
+     *  unrelated same-basename file's records (issue #334). When the working tree is
+     *  unavailable or the file is gone, behaviour is exactly the pre-#334 behaviour.
+     *
+     *  `t` must already be repo-relative (`repoRelativeTarget`). `graph` lets a caller
+     *  that has already narrowed the graph (why()'s `canRead` visibility filter) ask
+     *  the question over exactly the records it may see, rather than all of them. */
+    isKnownPath(t, graph) {
+        const symbols = graph?.symbols ?? this.recs("symbols");
+        const components = graph?.components ?? this.recs("components");
+        return isIndexedPath(t, symbols.map((s) => s.file), components.map((c) => c.paths))
+            || isRepoFile(this.paths.root, t);
+    }
     /** All decisions/bugs/constraints/symbols/components touching a file path or
      *  symbol name (hunch_why). Pass `{ asOf }` (an ISO instant) to TIME-TRAVEL:
      *  return only decisions/constraints whose valid-time window contained that
      *  instant — "what did we believe as of commit X?". Omit `asOf` for the full,
      *  history-inclusive view (backward-compatible default). */
     why(target, opts = {}) {
-        target = toPosixTarget(target);
+        // An absolute target (an agent's edit-payload path, verbatim) never matched
+        // the repo-relative stored file paths below (issue #299).
+        target = repoRelativeTarget(target, this.paths.root);
         const decisions = this.recs("decisions").filter(opts.canRead ?? (() => true));
         const bugs = this.recs("bugs").filter(opts.canRead ?? (() => true));
         const constraints = this.recs("constraints").filter(opts.canRead ?? (() => true));
@@ -1194,11 +1221,24 @@ export class HunchStore {
         // pathsRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
         // so an unanchored suffix pulled unrelated files' records into why()/the
         // pre-edit grounding block (issue #32). Segment-anchored matching only.
-        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || pathsRelated(s.file, target));
+        //
+        // A target that IS a path Hunch's index already knows about (README.md,
+        // vscode-extension/index.ts, ...) names exactly one file — suffix-matching
+        // it too pulls in every OTHER file that merely shares a basename (issue
+        // #299: root index.ts delivered vscode-extension/index.ts's rules and vice
+        // versa). "Known to the index" is answered from already-loaded graph data
+        // first (a symbol's exact file, or an indexed component's path glob — so a
+        // symbol-less indexed file still counts as real), and only then from the
+        // working tree, for a real file the index cannot see at all (issue #334).
+        // See isKnownPath. Suffix matching stays reserved for a target that is not
+        // itself a real path, e.g. a short/partial reference like "x/scenario.ts".
+        const indexed = this.isKnownPath(target, { symbols, components });
+        const suffixMatch = (file) => !indexed && pathsRelated(file, target);
+        const matchedSymbols = matchSymbolsTiered(target, symbols, indexed);
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
         const isPath = target.includes("/") || target.includes(".");
-        const fileMatch = (files) => files.some((f) => f === target || (isPath && pathsRelated(f, target)) || fileSet.has(f));
+        const fileMatch = (files) => files.some((f) => f === target || (isPath && suffixMatch(f)) || fileSet.has(f));
         return {
             target,
             decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
@@ -1320,10 +1360,23 @@ export class HunchStore {
         return c?.v ?? id;
     }
     /** Resolve a free-form target (symbol id / name / file path, component id / name)
-     *  to graph node ids — symbols win over components, exact file before suffix. */
+     *  to graph node ids — symbols win over components, exact file before suffix.
+     *  Shares why()/resolveSymbols' tiered matcher rather than one un-tiered SQL OR:
+     *  the flat query matched every tier at once, so a root `index.ts` also returned
+     *  `a/index.ts`'s symbols, and an absolute target matched nothing at all (#335).
+     *
+     *  The suffix gate here is `isRepoFile`, NOT the wider `isKnownPath`: the
+     *  exact-file tier has already run, so the only case left is a real on-disk file
+     *  with zero symbols (#334). Glob coverage alone would wrongly block a target
+     *  that no file actually carries — with a `src/**` component, `src/x.ts` living
+     *  at `packages/a/src/x.ts` stopped resolving. This resolver names the file it
+     *  resolved to in its result, so a suffix resolution is visible and only a file
+     *  that really exists may block it; why()/the pre-edit hook attribute records
+     *  silently and also run for a file about to be created, so they keep the wider
+     *  `isKnownPath`. */
     resolveNodeIds(target) {
-        const t = toPosixTarget(target);
-        const sym = this.db.prepare(`SELECT id FROM symbols WHERE id = ? OR name = ? OR file = ? OR file LIKE ? LIMIT 20`).all(t, t, t, `%/${t}`);
+        const t = repoRelativeTarget(target, this.paths.root);
+        const sym = matchSymbolsTiered(t, this.recs("symbols"), isRepoFile(this.paths.root, t)).slice(0, 20);
         if (sym.length)
             return sym.map((r) => r.id);
         const cmp = this.db.prepare(`SELECT id FROM components WHERE id = ? OR name = ? LIMIT 5`).all(t, t);
@@ -1380,10 +1433,27 @@ export class HunchStore {
                 dirs: [...dirs.entries()].map(([dir, v]) => ({ dir, ...v })).sort((a, b) => b.symbols - a.symbols),
             };
         }
-        const t = toPosixTarget(target.trim()).replace(/\/+$/, "");
+        // An absolute target (an agent's edit-payload path, verbatim) never matched the
+        // repo-relative stored file paths below and fell all the way to "none" (#335).
+        const t = repoRelativeTarget(target.trim(), this.paths.root).replace(/\/+$/, "");
         // FILE: exact path or unique suffix
         const fileRows = this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(t);
-        const fileHit = fileRows.length ? t : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
+        // Only the SUFFIX fallback is gated, and by `isRepoFile` rather than the wider
+        // `isKnownPath`: the exact-path tier above has already run, so the only case
+        // left is a real on-disk file with zero symbols, whose outline must not come
+        // from an unrelated same-basename file (#334). Glob coverage alone is not
+        // existence — with a `src/**` component, `src/x.ts` living at
+        // `packages/a/src/x.ts` would stop resolving. structure() names the file it
+        // resolved to, so a suffix resolution is visible and only a file that really
+        // exists may block it; why()/the pre-edit hook attribute records silently and
+        // also run for a file about to be created, so they keep `isKnownPath`.
+        // Directory targets are unaffected — a directory is never an `isRepoFile`
+        // (regular files only), so they keep flowing to the dir tier below.
+        const fileHit = fileRows.length
+            ? t
+            : isRepoFile(this.paths.root, t)
+                ? []
+                : this.db.prepare(`SELECT DISTINCT file FROM symbols WHERE file LIKE ?`).all(`%/${t}`).map((r) => r.file);
         const file = typeof fileHit === "string" ? fileHit : fileHit.length === 1 ? fileHit[0] : null;
         if (file) {
             const syms = fileRows.length ? fileRows : this.db.prepare(`SELECT id, name, kind, loc, fan_in, fan_out FROM symbols WHERE file = ? ORDER BY fan_in DESC, name`).all(file);
@@ -1412,7 +1482,10 @@ export class HunchStore {
                 matches: named.map((m) => ({ ...m, callers: this.edgeNeighbors(m.id, "in", 6), callees: this.edgeNeighbors(m.id, "out", 6) })),
             };
         }
-        return { kind: "none", target: t };
+        // A real on-disk file with zero indexed symbols reaches "none" too (#334). Flag
+        // it so the renderer doesn't tell the user it isn't a known file when we just
+        // stat'd it.
+        return { kind: "none", target: t, ...(isRepoFile(this.paths.root, t) ? { realFile: true } : {}) };
     }
     /** Labelled one-hop edge neighbors of a node ("in" = who reaches it, "out" = what it reaches). */
     edgeNeighbors(id, dir, limit) {
@@ -1426,6 +1499,10 @@ export class HunchStore {
      *  longer enforced. Pass `{ asOf }` to instead return the invariants in force at
      *  that instant (time-travel: "what must I not have broken as of commit X?"). */
     checkConstraints(scope, opts = {}) {
+        // Constraint scopes are always repo-relative; an absolute target (an
+        // agent's edit-payload path, verbatim) matched nothing even when a
+        // blocking rule plainly applied (issue #296).
+        scope = repoRelativeTarget(scope, this.paths.root);
         const all = this.recs("constraints");
         const asOf = opts.asOf;
         return all
@@ -1439,21 +1516,29 @@ export class HunchStore {
      *  glob, and the queried scope may be either too. Advisory only — findings never
      *  enter any block path. Sorted worst-first, then id for stable output. */
     liveFindingsFor(scope) {
-        const t = toPosixTarget(scope);
+        // Same absolute-target and same-basename-leak gaps as why() (issue #299): an
+        // un-rewritten absolute scope never matched the repo-relative `affected_files`
+        // below, and an un-guarded suffix fallback could pull in an unrelated file
+        // that merely shares a basename. Normalize once and reuse the same "is this
+        // path known to the index" guard.
+        const t = repoRelativeTarget(scope, this.paths.root);
+        const indexed = this.isKnownPath(t);
         const live = (f) => f.triage === "open" || f.triage === "accepted-risk" || f.triage === "scheduled";
         return this.recs("findings")
             .filter(live)
-            .filter((f) => f.affected_files.some((af) => pathMatchesGlob(t, af) || pathMatchesGlob(af, t) || pathsRelated(toPosixTarget(af), t))
-            || f.affected_symbols.some((s) => s === scope))
+            .filter((f) => f.affected_files.some((af) => pathMatchesGlob(t, af) || pathMatchesGlob(af, t) || (!indexed && pathsRelated(toPosixTarget(af), t)))
+            || f.affected_symbols.some((s) => s === t))
             .sort((a, b) => (SEV_FINDING[b.severity] ?? 0) - (SEV_FINDING[a.severity] ?? 0) || a.id.localeCompare(b.id));
     }
     /** Finished agent tasks that touched a file or glob (rule-checked changes and
      *  denied edits), newest first. Graph memory, so it spans machines and survives
      *  the local ledger's retention window. */
     tasksFor(scope, limit = 8) {
-        const t = toPosixTarget(scope);
+        // Same normalization + known-path suffix guard as liveFindingsFor/why() (issue #299).
+        const t = repoRelativeTarget(scope, this.paths.root);
+        const indexed = this.isKnownPath(t);
         return this.recs("tasks")
-            .filter((r) => r.files.some((f) => pathMatchesGlob(t, f) || pathMatchesGlob(f, t) || pathsRelated(toPosixTarget(f), t)))
+            .filter((r) => r.files.some((f) => pathMatchesGlob(t, f) || pathMatchesGlob(f, t) || (!indexed && pathsRelated(toPosixTarget(f), t))))
             .sort((a, b) => b.finished_at.localeCompare(a.finished_at) || a.id.localeCompare(b.id))
             .slice(0, Math.max(1, limit));
     }
@@ -2048,7 +2133,10 @@ export class HunchStore {
      *  a task on `target`, ordered by what matters most — invariants first, then the
      *  why, then blast radius and bug history — trimmed to a rough token budget. */
     assembleContext(target, budget = 1500, opts = {}) {
-        target = toPosixTarget(target);
+        // An absolute target (an agent's edit-payload path, verbatim) must be
+        // repo-relative BEFORE it reaches why()/liveFindingsFor() below, or an
+        // absolute path never matches the repo-relative stored data (issue #299).
+        target = repoRelativeTarget(target, this.paths.root);
         const w = this.why(target, opts);
         const symIds = w.symbols.map((s) => s.id);
         const blast = new Map();

package/dist/store/jsonStore.d.ts

@@ -78,10 +78,12 @@ export declare class JsonStore {
      *  The long-lived MCP server and CLI hooks write the same `.hunch/` concurrently;
      *  two unsynchronized RMWs over index.json each read the same base array and the
      *  second rename silently erases the first's record. `mkdirSync` is the atomic
-     *  acquire (EEXIST = held). A stale lock (killed process) is taken over by age;
-     *  against a live contender we wait briefly and then refuse the write. Proceeding
-     *  without the lock would reintroduce the record-loss race this mutex exists to
-     *  prevent. */
+     *  acquire (EEXIST = held). A stale lock (killed process, or one whose pid was
+     *  RECYCLED) is taken over behind an exclusive `.reclaim` claim — see
+     *  `takeOverRmwLock`, because judging and removing are two steps and two
+     *  contenders could otherwise both "win". Against a live contender we wait
+     *  briefly and then refuse the write. Proceeding without the lock would
+     *  reintroduce the record-loss race this mutex exists to prevent. */
     private withSingleFileLock;
     /** Write a single record (validated) to its JSON file / into the index array. */
     put<K extends EntityKind>(kind: K, record: EntityFor[K]): EntityFor[K];