@davesheffer/hunch 1.39.2 → 1.39.3

package/dist/serve/writelock.js

@@ -7,18 +7,28 @@
  * processes can both complete the read before either writes. An in-process mutex
  * does not span processes, so the lock is a file created with `open(path, "wx")` —
  * atomic on POSIX and Windows. A holder that dies leaves the file behind; a lock is
- * stealable once its owner is provably gone (pid dead on the same host) or older
- * than any plausible write.
+ * stealable once its owner is provably gone (pid dead — or RECYCLED — on the same
+ * host) or older than any plausible write. "Recycled" is decided by comparing the
+ * owner's recorded process-instance token with the current holder's, by string
+ * equality and never by clock arithmetic (see core/procstart.ts). Removing a stale
+ * lock is itself serialized behind an exclusive `.reclaim` claim directory, because
+ * judging and removing are two steps and two contenders can otherwise both "win"
+ * (see `takeOver`).
  */
 import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
-import { closeSync, openSync, readFileSync, rmSync, statSync, writeSync } from "node:fs";
+import { closeSync, mkdirSync, openSync, readFileSync, rmSync, rmdirSync, statSync, writeSync } from "node:fs";
 import { join } from "node:path";
+import { heldLockNonces, judgeSameHostOwner, selfStartToken, startTokenOf } from "../core/procstart.js";
 /** Longest a write may hold the lock before another process may steal it: a put plus a
  *  git commit and push — seconds, not minutes. */
 export const STALE_AFTER_MS = 60_000;
 /** Longest a writer waits before giving up and telling the caller. */
 export const ACQUIRE_TIMEOUT_MS = 10_000;
+/** Longest a takeover claim may sit before another contender may clear it. The
+ *  claimed section is a few syscalls, so anything this old means its claimer
+ *  crashed inside it. */
+export const CLAIM_STALE_MS = 10_000;
 const POLL_MS = 25;
 export class WriteLockTimeout extends Error {
     path;
@@ -42,7 +52,13 @@ function readOwner(path) {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
         if (typeof parsed.pid !== "number" || typeof parsed.nonce !== "string")
             return undefined;
-        return { pid: parsed.pid, host: typeof parsed.host === "string" ? parsed.host : "", nonce: parsed.nonce, at: typeof parsed.at === "string" ? parsed.at : "" };
+        return {
+            pid: parsed.pid,
+            host: typeof parsed.host === "string" ? parsed.host : "",
+            nonce: parsed.nonce,
+            at: typeof parsed.at === "string" ? parsed.at : "",
+            ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
+        };
     }
     catch {
         return undefined; // released between our open and this read, or truncated by a crash — age decides
@@ -57,7 +73,7 @@ function pidAlive(pid) {
         return error.code === "EPERM"; // exists, another user — alive for our purposes
     }
 }
-function stealable(path, owner, now) {
+function stealable(path, owner, now, token) {
     let ageMs;
     try {
         ageMs = now - statSync(path).mtimeMs;
@@ -71,15 +87,124 @@ function stealable(path, owner, now) {
     // their record and ledger updates. The age fallback is only safe when the
     // owner is from another host (whose PID we cannot probe) or its metadata is
     // unreadable.
-    if (owner && owner.host === hostname())
-        return !pidAlive(owner.pid);
+    //
+    // The one exception is a PID that is alive but is no longer the OWNER: PIDs
+    // are recycled, and a container restart routinely gives the new writer the
+    // dead one's exact pid and hostname, so the orphaned lock names the contender
+    // itself and is never taken over again (issue #287). The owner's recorded
+    // process-instance token settles it by plain string equality — no clock is
+    // read, because the lock's mtime and a start time come from different clocks
+    // and any skew between them would "prove" a live owner recycled and steal its
+    // lock. Anything the token cannot settle stays "not proven".
+    //
+    // The whole table lives in core/procstart.ts so this lock and jsonStore's
+    // `.rmw-lock` can never drift apart; "age" means it proved nothing and the
+    // fallback below governs, exactly as for a foreign host.
+    if (owner && owner.host === hostname()) {
+        const verdict = judgeSameHostOwner(owner, {
+            alive: pidAlive,
+            self: token.self,
+            tokenOf: token.of,
+            platform: token.platform ?? process.platform,
+            selfPid: process.pid,
+            heldNonces: heldLockNonces,
+        });
+        if (verdict !== "age")
+            return verdict === "stale";
+    }
     return ageMs > STALE_AFTER_MS;
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
-/** Hold the partition's lock across `fn` (sync or async); released even if it throws. */
+/** The claim a contender must hold to REMOVE a stale lock. A sibling directory,
+ *  created with the same exclusive `mkdir` the commit lock uses
+ *  (src/extractors/git.ts `acquireCommitLock`) — a directory because an empty one
+ *  is invisible to git and can never be staged. */
+function claimPath(lockPath) {
+    return `${lockPath}.reclaim`;
+}
+/**
+ * Remove a stale lock under an exclusive claim, and report whether the path may
+ * now be free. "judge stale → rm → create" is NOT atomic: two contenders can
+ * both judge the same corpse stale, the first removes it and creates its own,
+ * and the second then removes that FRESH lock and creates a second holder
+ * (issue #287). Serializing the removal behind one claim closes it.
+ *
+ * INVARIANT: a stale lock's path can only be vacated by a claim holder (its
+ * owner is dead and will never release), and only one contender holds the claim
+ * at a time — so between the re-judge below and the `rm` nothing can replace the
+ * lock. A contender that judged stale a moment earlier re-judges under the
+ * claim, sees the winner's fresh live lock, and removes nothing.
+ *
+ * Residuals accepted:
+ *  (i) an AGE-judged lock (foreign host, unprobeable owner, or unreadable owner
+ *      metadata) whose owner is actually alive and releases inside the
+ *      re-judge→rm window — the same class as the already-accepted "stolen after
+ *      STALE_AFTER_MS";
+ *  (ii) two contenders racing to clear a STRANDED claim. A claim's staleness is
+ *      judged by ITS MTIME against OUR clock — the one clock comparison left in
+ *      the takeover path — and there is no claim-nonce file to fall back on. So
+ *      with filesystem/host clock skew beyond CLAIM_STALE_MS every LIVE claim
+ *      looks stranded, and with three or more simultaneous contenders exclusion
+ *      degrades to the pre-fix race. Without such skew it needs a claim section
+ *      that is stranded plus simultaneous removers — and "stranded" is NOT only a
+ *      crash: a STALL longer than CLAIM_STALE_MS between the re-judge and the
+ *      `rm` (SIGSTOP, a VM pause or live migration, a laptop sleep) does it too.
+ *      One other contender is then enough: it clears the "stranded" claim, takes
+ *      over and publishes a LIVE lock, and the resumed claimer's `rm` removes
+ *      that live lock; the unconditional `rmdirSync(claim)` in the `finally` can
+ *      likewise remove a SUCCESSOR's claim. Same probability class as the age
+ *      steal we already accept — a process stalled past the stale window while
+ *      another writes — which is why it is accepted here too;
+ *  (iii) a stranded claim blocks any takeover for up to CLAIM_STALE_MS —
+ *      bounded, needing the same crash OR over-CLAIM_STALE_MS stall; a filesystem
+ *      clock AHEAD of this host extends that block by the amount of the skew;
+ *  (iv) MIXED VERSIONS: a pre-fix `hunch` ignores `.reclaim` entirely, so the
+ *      takeover race persists until every writer on the store is upgraded.
+ */
+function takeOver(path, token) {
+    const claim = claimPath(path);
+    try {
+        mkdirSync(claim);
+    }
+    catch (error) {
+        if (error.code === "EEXIST") {
+            // Someone else is mid-takeover — or crashed inside one. Clear only a
+            // provably stranded claim; either way, do not take over this round (the
+            // caller falls through to its deadline check and sleep, never a hot spin).
+            try {
+                if (Date.now() - statSync(claim).mtimeMs > CLAIM_STALE_MS)
+                    rmdirSync(claim);
+            }
+            catch { /* vanished, or another contender cleared it first */ }
+        }
+        return false;
+    }
+    try {
+        // RE-JUDGE from scratch under the claim: the lock we judged stale may already
+        // have been replaced by the winner's live one.
+        const current = readOwner(path);
+        if (!stealable(path, current, Date.now(), token))
+            return false;
+        rmSync(path, { force: true });
+        return true;
+    }
+    finally {
+        try {
+            rmdirSync(claim);
+        }
+        catch { /* best effort; a stranded claim is cleared by age */ }
+    }
+}
+/** Hold the partition's lock across `fn` (sync or async); released even if it throws.
+ *
+ *  `opts.startToken` is an INTERNAL TEST SEAM, not API: it lets the test suite
+ *  drive the process-identity rows of the decision table on a platform that has
+ *  no such identity. Callers outside this repo must leave it unset — the real
+ *  probe (`selfStartToken`/`startTokenOf`) is the only sound one. */
 export async function withWriteLock(hunchDir, fn, opts = {}) {
     const path = writeLockPath(hunchDir);
     const timeoutMs = opts.timeoutMs ?? ACQUIRE_TIMEOUT_MS;
+    const token = opts.startToken ?? { self: selfStartToken(), of: startTokenOf };
     const nonce = randomBytes(8).toString("hex");
     const started = Date.now();
     let fd;
@@ -87,22 +212,31 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
     for (;;) {
         try {
             fd = openSync(path, "wx");
+            // Synchronously adjacent to the successful create, before any await: from
+            // here on this nonce is one WE hold, so our own later calls do not mistake
+            // it for a predecessor's (and adding it before the open would make a mere
+            // waiter look like a holder).
+            heldLockNonces.add(nonce);
             break;
         }
         catch (error) {
             if (error.code !== "EEXIST")
                 throw error;
             lastOwner = readOwner(path);
-            if (stealable(path, lastOwner, Date.now())) {
-                rmSync(path, { force: true });
+            if (stealable(path, lastOwner, Date.now(), token) && takeOver(path, token))
                 continue;
-            }
             if (Date.now() - started >= timeoutMs)
                 throw new WriteLockTimeout(path, lastOwner, Date.now() - started);
             await sleep(POLL_MS);
         }
     }
-    const owner = { pid: process.pid, host: hostname(), nonce, at: new Date().toISOString() };
+    const owner = {
+        pid: process.pid,
+        host: hostname(),
+        nonce,
+        at: new Date().toISOString(),
+        ...(token.self !== null ? { start: token.self } : {}),
+    };
     try {
         writeSync(fd, JSON.stringify(owner));
     }
@@ -113,10 +247,17 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
     }
     finally {
         // Only remove a lock that is still ours: if we overran STALE_AFTER_MS and were stolen
-        // from, the file now protects another writer.
-        const current = readOwner(path);
-        if (!current || current.nonce === nonce)
-            rmSync(path, { force: true });
+        // from, the file now protects another writer. The nonce is dropped in a
+        // `finally` of its own, so a throw from the conditional remove can never
+        // leave us vouching for a lock we no longer hold.
+        try {
+            const current = readOwner(path);
+            if (!current || current.nonce === nonce)
+                rmSync(path, { force: true });
+        }
+        finally {
+            heldLockNonces.delete(nonce);
+        }
     }
 }
 //# sourceMappingURL=writelock.js.map

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, 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";
@@ -1184,7 +1184,9 @@ export class HunchStore {
      *  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 +1196,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
+        // (a symbol's exact file, or an indexed component's path glob — so a
+        // symbol-less real file still counts as real), never the filesystem: a
+        // deleted-but-still-indexed path must answer the same either way. Suffix
+        // matching stays reserved for a target that is not itself a real indexed
+        // path, e.g. a short/partial reference like "x/scenario.ts".
+        const indexed = isIndexedPath(target, symbols.map((s) => s.file), components.map((c) => c.paths));
+        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))))
@@ -1426,6 +1441,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 +1458,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 = isIndexedPath(t, this.recs("symbols").map((s) => s.file), this.recs("components").map((c) => c.paths));
         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 + indexed-suffix guard as liveFindingsFor/why() (issue #299).
+        const t = repoRelativeTarget(scope, this.paths.root);
+        const indexed = isIndexedPath(t, this.recs("symbols").map((s) => s.file), this.recs("components").map((c) => c.paths));
         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 +2075,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];