@davesheffer/hunch 1.45.0 → 1.45.2

package/dist/store/hunchStore.js

@@ -4,7 +4,7 @@
  *
  *   - reindex():        JSON  -> SQLite (rebuild the derived index + FTS)
  *   - search():         FTS5 ranked query (hunch_query)
- *   - why():            decisions/bugs/constraints explaining a path/symbol
+ *   - why():            decisions/bugs/constraints explaining a path/symbol, or one record by id
  *   - getDependents():  recursive-CTE blast radius over the call/dep graph
  *   - checkConstraints(): constraints whose scope matches a glob/path
  *   - bugLineage():     bugs matching a symptom/symbol + their lineage
@@ -26,6 +26,7 @@ import { normalizePath, rankTaskRecords, recordIdsOf, selectLatestTasks, selectT
 import { resolveTaskRankingMode } from "../core/taskRankingMode.js";
 import { currentForTopic, isInForce } from "../core/topics.js";
 import { edgeId } from "../core/ids.js";
+import { WHY_GENERATED_ID, WHY_RECORD_ID } from "../core/whyRecord.js";
 import { isStrictBlocker, isVetoBlocker } from "../core/strictgate.js";
 import { effectiveForbids, matchForbids } from "../core/constraintmatch.js";
 import { analyzeDiff, diffContentGaps } from "../extractors/diff.js";
@@ -1343,6 +1344,14 @@ export class HunchStore {
         // 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);
+        // A record id (every delivered brief line ends in `hunch_why("dec_…")`) resolves
+        // to that record directly (issue #474). With `asOf`, a record not in force then
+        // is "no record"; status stays as stored, like the path view (see whyRecord).
+        const lookup = WHY_RECORD_ID.test(target) ? this.whyRecord(target, opts.canRead, opts.asOf) : undefined;
+        if (lookup?.record)
+            return { target, decisions: [], bugs: [], constraints: [], symbols: [], components: [], byId: lookup };
+        // A miss is reported only for a generated-shape id; anything else resolves as before.
+        const byId = lookup && WHY_GENERATED_ID.test(target) ? lookup : undefined;
         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));
@@ -1379,8 +1388,62 @@ export class HunchStore {
                 && inWindow(c.valid_from, c.valid_to, asOf)),
             symbols: matchedSymbols,
             components: components.filter((c) => c.paths.some((g) => pathMatchesGlob(target, g) || [...fileSet].some((f) => pathMatchesGlob(f, g)))),
+            ...(byId ? { byId } : {}),
         };
     }
+    /** Look a record up by id across the record kinds why() explains (public ∪ private
+     *  via recs(), narrowed by `canRead`). A decision carries its supersession chain.
+     *  With `asOf`, a record outside its valid window then is "no record", and only
+     *  chain links/neighbours already in effect then are shown. Status is the STORED
+     *  status, exactly as the path/symbol view prints it.
+     *  Neighbour ids the caller may not read are never printed. */
+    whyRecord(id, canRead = () => true, asOf) {
+        const find = (kind) => this.recs(kind).find((r) => r.id === id && canRead(r));
+        // Decisions the caller may read that had taken effect by `asOf` (all when no asOf).
+        const decs = new Map(this.recs("decisions").filter((x) => canRead(x) && inWindow(x.valid_from, null, asOf)).map((x) => [x.id, x]));
+        const visible = (ref) => (ref && decs.has(ref) ? ref : null);
+        const existed = (instant) => !asOf || instant <= asOf;
+        let record = null;
+        switch (id.slice(0, id.indexOf("_"))) {
+            case "dec": {
+                const d = find("decisions");
+                if (!d || !inWindow(d.valid_from, d.valid_to, asOf))
+                    break;
+                // Stored status, as the path view prints it; asOf only hides neighbours not yet in effect.
+                const shown = { ...d, supersedes: visible(d.supersedes), superseded_by: visible(d.superseded_by) };
+                record = { kind: "decision", record: shown, chain: supersessionChain(shown, decs) };
+                break;
+            }
+            case "con": {
+                const c = find("constraints");
+                if (!c || !inWindow(c.valid_from, c.valid_to, asOf))
+                    break;
+                record = { kind: "constraint", record: { ...c, source_decision: visible(c.source_decision) } };
+                break;
+            }
+            case "bug": {
+                const b = find("bugs");
+                if (b)
+                    record = { kind: "bug", record: b };
+                break;
+            }
+            case "fnd": {
+                const f = find("findings");
+                if (f && existed(f.observed_at))
+                    record = { kind: "finding", record: f };
+                break;
+            }
+            // Not gated by asOf: the path view lists components regardless of asOf too.
+            // Findings stay gated by observed_at (the path view does not list findings).
+            case "cmp": {
+                const c = find("components");
+                if (c)
+                    record = { kind: "component", record: c };
+                break;
+            }
+        }
+        return { id, record, ...(asOf ? { asOf } : {}) };
+    }
     /** Transitive blast radius: every symbol/component that (in)directly depends on
      *  `id`, via a recursive CTE over the edges graph (hunch_get_dependents). We
      *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains. */
@@ -2334,6 +2397,22 @@ function inWindow(valid_from, valid_to, asOf) {
         return false;
     return true;
 }
+/** A decision's supersedes/superseded_by chain over `decs` (the readable, already
+ *  in-effect decisions), oldest first, cycle-guarded. `d` is the record as shown. */
+function supersessionChain(d, decs) {
+    const seen = new Set([d.id]);
+    const back = [];
+    for (let cur = d.supersedes ? decs.get(d.supersedes) : undefined; cur && !seen.has(cur.id); cur = cur.supersedes ? decs.get(cur.supersedes) : undefined) {
+        seen.add(cur.id);
+        back.unshift(cur);
+    }
+    const fwd = [];
+    for (let cur = d.superseded_by ? decs.get(d.superseded_by) : undefined; cur && !seen.has(cur.id); cur = cur.superseded_by ? decs.get(cur.superseded_by) : undefined) {
+        seen.add(cur.id);
+        fwd.push(cur);
+    }
+    return [...back, d, ...fwd].map((x) => ({ id: x.id, status: x.status, title: x.title }));
+}
 function round(n) {
     return Math.round(n * 100) / 100;
 }

package/dist/store/jsonStore.d.ts

@@ -6,8 +6,11 @@ export declare const MAX_JSON_RECORD_BYTES: number;
 export declare const MAX_JSON_INDEX_BYTES: number;
 export declare const MAX_JSON_MANIFEST_BYTES: number;
 export declare const MAX_JSON_DIRECTORY_ENTRIES_PER_KIND = 100000;
+/** When the process now holding `pid` was created (wall-clock ms), or null. */
+type StartedAtProbe = (pid: number) => number | null;
 export declare class JsonStore {
     private readonly paths;
+    private readonly lockOpts;
     private _warnedForward;
     /** Memoized validated records per kind. loadAll() is on every read-path method
      *  (why/checkConstraints/fragility/assembleContext…), each of which previously
@@ -20,7 +23,13 @@ export declare class JsonStore {
     private readonly lexicalRoot;
     private readonly canonicalRoot;
     private readonly lexicalHunch;
-    constructor(paths: HunchPaths);
+    /** `lockOpts.startedAt` is an INTERNAL TEST SEAM, not API: it replaces the OS
+     *  creation-time probe of the `.rmw-lock` "unproven" rule so the suite can
+     *  drive it on linux, where the real probe reports nothing. Callers outside
+     *  this repo must leave it unset — `processStartedAt` is the only sound probe. */
+    constructor(paths: HunchPaths, lockOpts?: {
+        startedAt?: StartedAtProbe;
+    });
     private lstatOrMissing;
     private expectedCanonical;
     /** Require an ordinary, canonically-contained directory. Creation is one
@@ -125,3 +134,4 @@ export declare class JsonStore {
         skipped: number;
     };
 }
+export {};

package/dist/store/jsonStore.js

@@ -11,7 +11,7 @@ import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { BASELINE_VERSION, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
 import { writeFileAtomic } from "../core/io.js";
 import { readStoreArtifact } from "../core/storeArtifact.js";
-import { heldLockNonces, judgeSameHostOwner, selfStartToken, startTokenOf } from "../core/procstart.js";
+import { createdAfterLock, heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
 /** High-cardinality collections (symbols, edges) are stored as a single
  *  index.json array — there can be thousands, and one file per edge would create
  *  enormous git noise. Curated, low-volume entities (components, decisions, bugs,
@@ -118,6 +118,7 @@ function readRmwOwnerOnce(lock) {
             host: parsed.host,
             ...(typeof parsed.nonce === "string" ? { nonce: parsed.nonce } : {}),
             ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
+            ...(typeof parsed.at === "string" ? { at: parsed.at } : {}),
         };
     }
     catch {
@@ -143,9 +144,14 @@ const RMW_CLAIM_STALE_MS = 10_000;
  *  The owner's recorded process-instance token settles that by string equality
  *  (core/procstart.ts); no clock is compared, because a lock's mtime and a start
  *  time come from different clocks and any skew would "prove" a live owner
- *  recycled. `readRmwOwner` stays FIRST: it throws on unsafe/hardlinked or
- *  oversized ownership metadata, and unsafe ownership never licenses removal. */
-function rmwLockIsStale(lock) {
+ *  recycled. Where no token exists (macOS, Windows) a live pid is "unproven",
+ *  and an AGED lock is still taken over once the OS proves the process now
+ *  holding that pid was created after the lock's recorded `at` (issue #457) —
+ *  the same `createdAfterLock` rule as the write lock. `startedAt` is
+ *  memoized per acquisition by the caller, because the OS probe spawns.
+ *  `readRmwOwner` stays FIRST: it throws on unsafe/hardlinked or oversized
+ *  ownership metadata, and unsafe ownership never licenses removal. */
+function rmwLockIsStale(lock, startedAt) {
     let stat;
     try {
         stat = lstatSync(lock);
@@ -157,9 +163,10 @@ function rmwLockIsStale(lock) {
     }
     const owner = readRmwOwner(lock);
     if (owner && owner.host === hostname()) {
-        // One shared table with src/serve/writelock.ts (core/procstart.ts), so the
-        // two locks can never drift apart; "age" means nothing was proven and the
-        // fallback below governs, exactly as for a foreign host.
+        // One shared table with src/serve/writelock.ts (core/procstart.ts), and one
+        // shared creation-time check for an "unproven" pid, so the two locks apply
+        // the same rule; "age" means nothing was proven and the fallback below
+        // governs, exactly as for a foreign host.
         const verdict = judgeSameHostOwner(owner, {
             alive: rmwPidAlive,
             self: selfStartToken(),
@@ -168,6 +175,8 @@ function rmwLockIsStale(lock) {
             selfPid: process.pid,
             heldNonces: heldLockNonces,
         });
+        if (verdict === "unproven")
+            return Date.now() - stat.mtimeMs > 10_000 && createdAfterLock(owner, startedAt);
         if (verdict !== "age")
             return verdict === "stale";
     }
@@ -210,7 +219,7 @@ function rmwLockIsStale(lock) {
  * so the race persists until every writer on the store is upgraded. Returns true
  * when the path may now be free.
  */
-function takeOverRmwLock(lock) {
+function takeOverRmwLock(lock, startedAt) {
     const claim = `${lock}.reclaim`;
     try {
         mkdirSync(claim);
@@ -229,7 +238,7 @@ function takeOverRmwLock(lock) {
         return false;
     }
     try {
-        if (!rmwLockIsStale(lock))
+        if (!rmwLockIsStale(lock, startedAt))
             return false; // re-judged from scratch under the claim
         rmSync(lock, { recursive: true, force: true });
         return true;
@@ -253,6 +262,7 @@ function unsafePath(path, reason) {
 }
 export class JsonStore {
     paths;
+    lockOpts;
     _warnedForward = false;
     /** Memoized validated records per kind. loadAll() is on every read-path method
      *  (why/checkConstraints/fragility/assembleContext…), each of which previously
@@ -265,8 +275,13 @@ export class JsonStore {
     lexicalRoot;
     canonicalRoot;
     lexicalHunch;
-    constructor(paths) {
+    /** `lockOpts.startedAt` is an INTERNAL TEST SEAM, not API: it replaces the OS
+     *  creation-time probe of the `.rmw-lock` "unproven" rule so the suite can
+     *  drive it on linux, where the real probe reports nothing. Callers outside
+     *  this repo must leave it unset — `processStartedAt` is the only sound probe. */
+    constructor(paths, lockOpts = {}) {
         this.paths = paths;
+        this.lockOpts = lockOpts;
         this.lexicalRoot = resolve(paths.root);
         this.canonicalRoot = realpathSync(this.lexicalRoot);
         this.lexicalHunch = resolve(paths.hunch);
@@ -666,6 +681,15 @@ export class JsonStore {
         const lock = join(directory.lexical, ".rmw-lock");
         const deadline = Date.now() + 2_000;
         const nonce = randomBytes(8).toString("hex");
+        // The creation-time probe spawns; ask it once per pid for this acquisition,
+        // not on every poll nor again under the takeover claim (as writelock.ts).
+        const createdAt = new Map();
+        const probe = this.lockOpts.startedAt ?? processStartedAt;
+        const startedAt = (pid) => {
+            if (!createdAt.has(pid))
+                createdAt.set(pid, probe(pid));
+            return createdAt.get(pid);
+        };
         for (;;) {
             try {
                 mkdirSync(lock);
@@ -676,10 +700,11 @@ export class JsonStore {
                 // writer may exceed the stale-age heuristic while serializing a large
                 // index; its PID must prevent a second writer from taking over. The
                 // process-instance token (when this platform has one) is what lets a
-                // successor tell that PID apart from a recycled one.
+                // successor tell that PID apart from a recycled one; without one, `at`
+                // lets it prove the pid's current process was created after this lock.
                 try {
                     const start = selfStartToken();
-                    writeFileAtomic(join(lock, "owner.tmp.json"), JSON.stringify({ pid: process.pid, host: hostname(), nonce, ...(start !== null ? { start } : {}) }));
+                    writeFileAtomic(join(lock, "owner.tmp.json"), JSON.stringify({ pid: process.pid, host: hostname(), nonce, at: new Date().toISOString(), ...(start !== null ? { start } : {}) }));
                 }
                 catch (error) {
                     try {
@@ -694,7 +719,7 @@ export class JsonStore {
             catch (error) {
                 if (error.code !== "EEXIST")
                     throw error;
-                if (rmwLockIsStale(lock) && takeOverRmwLock(lock))
+                if (rmwLockIsStale(lock, startedAt) && takeOverRmwLock(lock, startedAt))
                     continue;
                 // The deadline is checked only AFTER an acquire has been attempted: with
                 // the check at the top of the loop, a successful takeover could still be

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.45.0",
+  "version": "1.45.2",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.45.0",
+  "version": "1.45.2",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.45.0",
+      "version": "1.45.2",
       "runtimeHint": "npx",
       "packageArguments": [
         {