@davesheffer/hunch 1.45.1 → 1.45.2

package/dist/mcp/server.js

@@ -33,7 +33,7 @@ import { knownRepoDeps } from "../synthesis/tripwires.js";
 import { refreshExistingGrounding } from "../integrations/providers.js";
 import { workspaceLedgerView, renderWorktreeTable, renderBranchTable, workspaceSummaryLine, snapshotHasHome, recordWorkspaceSnapshot, branchRows, worktreeRows } from "../integrations/workspaceLedger.js";
 import { workspacesConfig } from "../core/config.js";
-import { revParse, asOfDate, revExists, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatus, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
+import { revParse, asOfDate, revExists, lastChangeDate, checkFreshnessRevision, teamPullIsFresh, rangeFiles, rangeGateDiff, commitFiles, commitGateDiff, stagedFiles, stagedGateDiff, workingFiles, workingGateDiff, pullHunchStatusDetailed, describePullFailure, sameRemoteUrl, currentBranch, worktreePaths, pathKnownToHistory } from "../extractors/git.js";
 import { flushCapture, flushMemoryHome, pinSharedRemote } from "../integrations/sync.js";
 import { withWriteLock } from "../serve/writelock.js";
 import { advertisedTeamRemoteContract, ensureTeamOverlay, isTeamStoreTrusted, overlayMatchesTeamRemote, teamWiringConsented, untrustedTeamStoreMessage, readTeamConfig, teamRemoteContract, teamSharedRef } from "../integrations/team.js";
@@ -69,6 +69,7 @@ import { nowData, wikiStatus, publicHome, readWikiManifestAt } from "../wiki/wik
 import { HUNCH_VERSION } from "../core/version.js";
 import { assertCompleteRepoScan, indexRepo, scanRepo } from "../extractors/indexer.js";
 import { liveForTopic, historyForTopic, rejectedForTopic, captureConflicts } from "../core/topics.js";
+import { formatWhyRecord, more, WHY_CAP } from "../core/whyRecord.js"; // WHY_CAP: per record-type cap in hunch_why
 import { pendingEscalations, policyEscalations, commitRepairEscalations, actionableEscalations, escalationHeadline } from "../core/escalations.js";
 import { readActivePendingRepairs, withheldRewrites } from "../core/repairqueue.js";
 import { scanRecord, publicationWarning, loadVocabulary } from "../core/publication.js";
@@ -595,7 +596,6 @@ const resolveDestRoot = (home, store, root) => home === "private" && store.priva
 // session, so an uncapped list pollutes the context window. Cap each list to its
 // highest-signal head (records are pre-sorted by severity/confidence) and tell the
 // caller what was withheld rather than truncating silently.
-const WHY_CAP = 6; // per record-type in hunch_why
 const DEP_CAP = 25; // dependents in hunch_get_dependents
 const QUERY_HITS = 8; // hunch_query matches (was 12)
 const FINDINGS_CAP = 12; // hunch_findings listing
@@ -624,7 +624,6 @@ export const firstSentence = (text) => {
 };
 const SEV_CONSTRAINT = { blocking: 3, warning: 2, advisory: 1 };
 const SEV_BUG = { critical: 4, high: 3, medium: 2, low: 1 };
-const more = (total, cap, hint = "") => total > cap ? `\n  …(+${total - cap} more${hint ? ` — ${hint}` : ""})` : "";
 const EXECUTION_OBLIGATION_SCHEMA = z.object({
     id: z.string(),
     origin: z.enum(["memory", "episode", "manual"]),
@@ -1088,10 +1087,11 @@ function prepareRoot(root, explicitOverlay, requireIndex) {
         let consecutivePullFailures = 0;
         if (store.privateDir) {
             try {
-                const status = pullHunchStatus(store.privateDir, {
-                    timeoutMs: 5_000,
+                const { status, detail } = pullHunchStatusDetailed(store.privateDir, {
                     remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
                 });
+                if (detail)
+                    console.error(`[hunch-mcp] team memory pull failed (${describePullFailure(detail)})`);
                 ({ nextRemotePullAt, consecutivePullFailures } = pullBackoff(status, Date.now(), 0));
             }
             catch {
@@ -1145,6 +1145,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     let store = initial.store;
     let nextRemotePullAt = initial.nextRemotePullAt;
     let consecutivePullFailures = initial.consecutivePullFailures;
+    // Consecutive FAILED forced pulls (any subject); reset by any fresh pull.
+    let forcedFailureStreak = 0;
+    // When the last fresh pull (ordinary or forced) finished; a forced failure
+    // older than this is never reused, since team memory was refreshed since.
+    let lastFreshPullAt = 0;
     let indexedSourceStamp = initial.indexedSourceStamp;
     const matchesStartupTeamRoute = () => {
         if (!teamAdvertised || !store.privateDir || !startupTeamConfig || !startupTeamRoute)
@@ -1165,6 +1170,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     const notePull = (status, finishedAt) => {
         ({ nextRemotePullAt, consecutivePullFailures } =
             pullBackoff(status, finishedAt, consecutivePullFailures));
+        if (teamPullIsFresh(status)) {
+            forcedFailureStreak = 0;
+            lastFreshPullAt = finishedAt;
+        }
     };
     const pullTeamMemory = (force = false) => {
         if (!store.privateDir)
@@ -1174,10 +1183,12 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             return "cooldown";
         let status;
         try {
-            status = pullHunchStatus(store.privateDir, {
-                timeoutMs: 5_000,
+            const pulled = pullHunchStatusDetailed(store.privateDir, {
                 remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
             });
+            status = pulled.status;
+            if (pulled.detail)
+                console.error(`[hunch-mcp] team memory pull failed (${describePullFailure(pulled.detail)})`);
         }
         catch {
             status = "failed";
@@ -1191,6 +1202,70 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     const refreshIndex = () => {
         indexedSourceStamp = rebuildFreshIndex(store);
     };
+    const FORCED_PULL_RETRY_MS = 2_000;
+    const FORCED_FAILURE_LIMIT = 3;
+    let lastForcedFailure = null;
+    // True only during the synchronous prefix of a tool callback whose request
+    // wrapper just pulled shared memory fresh (set/cleared around the callback).
+    let requestPulledFresh = false;
+    // An exact local miss in shared mode is an authority claim: local absence must
+    // never be presented as team absence. Ordinary request pulls honour cooldown and
+    // failure backoff, so bypass it once. Returns null after a fresh convergence
+    // (the caller re-reads), else the explicit abstention to return instead.
+    // Two throttles keep the synchronous fetch off the hot path: a miss in a
+    // request whose ordinary pull already converged needs no second fetch, and a
+    // forced pull that failed within FORCED_PULL_RETRY_MS for the SAME subject is
+    // reused, not retried, so a client looping on one miss against a dead remote
+    // cannot block stdio on each call. A different subject still fetches: a remote
+    // restored moments later must converge for the next distinct read — until
+    // FORCED_FAILURE_LIMIT forced pulls have failed in a row (any subject); then
+    // misses reuse the last failure until the ordinary backoff window has passed.
+    // Any fresh pull resets the streak (notePull).
+    const confirmSharedMiss = (absenceClaim, subject) => {
+        let status;
+        if (requestPulledFresh) {
+            status = "current";
+        }
+        else if (lastForcedFailure && lastForcedFailure.at > lastFreshPullAt && ((lastForcedFailure.subject === subject
+            && Date.now() - lastForcedFailure.at < FORCED_PULL_RETRY_MS)
+            || (forcedFailureStreak >= FORCED_FAILURE_LIMIT && Date.now() < nextRemotePullAt))) {
+            status = lastForcedFailure.status;
+        }
+        else {
+            status = pullTeamMemory(true);
+            if (status === "cooldown" || status === "not_shared" || !teamPullIsFresh(status)) {
+                lastForcedFailure = { at: Date.now(), status, subject };
+                forcedFailureStreak++;
+            }
+            else {
+                lastForcedFailure = null;
+            }
+        }
+        if (status === "cooldown" || status === "not_shared" || !teamPullIsFresh(status)) {
+            return `Shared team memory refresh is ${status}; Hunch cannot confirm that ${absenceClaim}. Retry when the shared store is available.`;
+        }
+        try {
+            if (store.sourceStamp() !== indexedSourceStamp)
+                refreshIndex();
+        }
+        catch {
+            return `Shared team memory refreshed, but its derived index could not be rebuilt; Hunch cannot confirm that ${subject} is absent. Retry this read.`;
+        }
+        return null;
+    };
+    // Policy reads: confirm a local policy (or its referenced proof) miss against
+    // fresh shared memory before the service reports "not found". Public-only reads
+    // and non-shared stores never consult the team remote.
+    const confirmSharedPolicy = (policyId, publicOnly) => {
+        if (publicOnly || store.mode !== "shared" || !store.privateDir)
+            return null;
+        const repository = new PolicyRepository(root, store);
+        const policy = repository.getPolicy(policyId);
+        if (policy && (!policy.proof || repository.getProof(policy.proof)))
+            return null;
+        const subject = policy ? `proof ${policy.proof} of policy ${policyId}` : `policy ${policyId}`;
+        return confirmSharedMiss(`${subject} is absent from shared team memory`, subject);
+    };
     // Resolve the embedder ONCE for this long-lived process (never throws; null when
     // the optional model isn't installed). The model then loads lazily on the first
     // hunch_query and stays warm — and hybridSearch degrades to FTS until then.
@@ -1231,6 +1306,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         nextRemotePullAt = prepared.nextRemotePullAt;
         consecutivePullFailures = prepared.consecutivePullFailures;
         indexedSourceStamp = prepared.indexedSourceStamp;
+        lastForcedFailure = null;
+        forcedFailureStreak = 0;
         previous.close();
         console.error(`[hunch-mcp] serving Hunch at ${root} (client root)`);
     };
@@ -1339,8 +1416,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
                 return refused("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
             }
+            let pulledFresh = false;
             if (store.mode === "shared" && store.privateDir) {
-                pullTeamMemory();
+                const pulled = pullTeamMemory();
+                pulledFresh = pulled !== "cooldown" && pulled !== "not_shared" && teamPullIsFresh(pulled);
                 // Recompute the full semantic + physical snapshot after the synchronous
                 // network seam. A paired team.json/origin change can occur while fetch is
                 // blocked; serving after that race would attach the old checkout to a new
@@ -1360,7 +1439,17 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     refreshIndex();
             }
             catch { /* corrupt/churning local source — serve the last durable indexed view */ }
-            const result = await withInitiator(initiatorFromClient(server.server.getClientVersion()?.name), () => callback(...args));
+            // A shared-miss check in the callback's synchronous prefix may reuse this
+            // request's fresh pull; any later (post-await) check falls back to a forced pull.
+            const result = await withInitiator(initiatorFromClient(server.server.getClientVersion()?.name), () => {
+                requestPulledFresh = pulledFresh;
+                try {
+                    return callback(...args);
+                }
+                finally {
+                    requestPulledFresh = false;
+                }
+            });
             if (teamAdvertised && !matchesStartupTeamRoute()) {
                 return refused("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
             }
@@ -1409,16 +1498,28 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_why ------------------------------------------------------------
     server.registerTool("hunch_why", {
         title: "Explain why a file/symbol is the way it is",
-        description: "Return the decisions, bugs, and constraints that explain a file path or symbol — the 'why' and the 'what must not break', with evidence. Pass `as_of` (a commit/tag/branch) to time-travel: see what was believed at that point in history. Use when you need the full rationale for ONE target. Not for a budgeted task brief (hunch_context), keyword search (hunch_query), or where-is-it questions (hunch_structure).",
+        description: "Return the decisions, bugs, and constraints that explain a file path or symbol, or one record by id (dec_/con_/bug_/fnd_/cmp_) — the 'why' and the 'what must not break', with evidence. Pass `as_of` (a commit/tag/branch) to time-travel: see what was believed at that point in history. Use when you need the full rationale for ONE target. Not for a budgeted task brief (hunch_context), keyword search (hunch_query), or where-is-it questions (hunch_structure).",
         inputSchema: {
-            target: z.string().describe("A file path (e.g. src/auth/session.ts) or symbol name."),
+            target: z.string().describe("A file path (e.g. src/auth/session.ts), symbol name, or record id (e.g. dec_0b5d2be516)."),
             as_of: z.string().optional().describe("Time-travel ref: a commit sha, tag, or branch (e.g. v0.7.0). Omit for the current view."),
         },
     }, async ({ target, as_of }) => {
         const asOf = as_of ? asOfDate(as_of, root) : undefined;
         if (as_of && !asOf)
             return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
-        const w = store.why(target, { asOf });
+        let w = store.why(target, { asOf });
+        // "No record <id>" is a team-absence claim in shared mode: confirm the local
+        // miss against a fresh pull first, like hunch_current_decision. A record held
+        // locally but outside its as_of window is not a team-absence claim: no pull.
+        if (w.byId && !w.byId.record && store.mode === "shared" && store.privateDir
+            && !(asOf && store.why(target).byId?.record)) {
+            const abstention = confirmSharedMiss(`record ${w.byId.id} is absent from shared team memory`, `record ${w.byId.id}`);
+            if (abstention)
+                return err(abstention);
+            w = store.why(target, { asOf });
+        }
+        if (w.byId?.record)
+            return ok(formatWhyRecord(w.byId).join("\n"));
         // Highest-signal first, then cap: invariants by severity, decisions by
         // confidence, bugs by severity — so a hot file's trim drops the tail, not
         // the records that matter most.
@@ -1426,6 +1527,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         const constraints = [...w.constraints].sort((a, b) => (SEV_CONSTRAINT[b.severity] ?? 0) - (SEV_CONSTRAINT[a.severity] ?? 0));
         const bugs = [...w.bugs].sort((a, b) => (SEV_BUG[b.severity] ?? 0) - (SEV_BUG[a.severity] ?? 0));
         const parts = [`Why for "${target}":`];
+        if (w.byId)
+            parts.push(`\n${formatWhyRecord(w.byId).join("\n")}`);
         if (decisions.length)
             parts.push(`\nDECISIONS:\n${decisions.slice(0, WHY_CAP).map((d) => `  • ${d.id} [${d.status}] ${d.title}\n      ${d.decision}${provLine(d)}`).join("\n")}${more(decisions.length, WHY_CAP, "narrow the target")}`);
         if (constraints.length)
@@ -2071,21 +2174,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         let live = liveForTopic(decs, topic);
         // A prior transient fetch failure may have placed ordinary tool traffic in
         // backoff. That is acceptable for cached positive reads, but an exact topic
-        // miss is an authority claim: local absence must never be presented as team
-        // absence. Bypass the cooldown once, then reread only after a successful
-        // bounded convergence. An unavailable remote produces an explicit abstention.
+        // miss must be confirmed against fresh team memory (confirmSharedMiss).
         if (live.length === 0 && store.mode === "shared" && store.privateDir) {
-            const status = pullTeamMemory(true);
-            if (status === "cooldown" || status === "not_shared" || !teamPullIsFresh(status)) {
-                return err(`Shared team memory refresh is ${status}; Hunch cannot confirm that topic "${topic}" has no current decision. Retry when the shared store is available.`);
-            }
-            try {
-                if (store.sourceStamp() !== indexedSourceStamp)
-                    refreshIndex();
-            }
-            catch {
-                return err(`Shared team memory refreshed, but its derived index could not be rebuilt; Hunch cannot confirm that topic "${topic}" is absent. Retry this read.`);
-            }
+            const abstention = confirmSharedMiss(`topic "${topic}" has no current decision`, `topic "${topic}"`);
+            if (abstention)
+                return err(abstention);
             decs = store.recs("decisions");
             live = liveForTopic(decs, topic);
         }
@@ -3002,6 +3095,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ policy_id, public_only }) => {
         try {
+            const abstention = confirmSharedPolicy(policy_id, public_only);
+            if (abstention)
+                return err(abstention);
             const service = new ConstitutionService(store, root);
             const plan = service.plan(policy_id, { publicOnly: public_only });
             const home = public_only ? "public" : service.repository.homeOfPolicy(policy_id);
@@ -3024,6 +3120,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ policy_id, public_only }) => {
         try {
+            const abstention = confirmSharedPolicy(policy_id, public_only);
+            if (abstention)
+                return err(abstention);
             return ok(JSON.stringify(new ConstitutionService(store, root).card(policy_id, { publicOnly: public_only }), null, 2));
         }
         catch (e) {
@@ -3039,6 +3138,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ policy_id, public_only }) => {
         try {
+            const abstention = confirmSharedPolicy(policy_id, public_only);
+            if (abstention)
+                return err(abstention);
             return ok(JSON.stringify(new ConstitutionService(store, root).shadowReport(policy_id, {}, { publicOnly: public_only }), null, 2));
         }
         catch (e) {
@@ -3054,6 +3156,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ policy_id, public_only }) => {
         try {
+            const abstention = confirmSharedPolicy(policy_id, public_only);
+            if (abstention)
+                return err(abstention);
             const service = new ConstitutionService(store, root);
             const policy = service.get(policy_id, { publicOnly: public_only });
             if (!policy.proof)
@@ -3080,6 +3185,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 throw new Error("choose either workspace or commit for executable-behavior evaluation");
             if (commit && !revExists(commit, root))
                 throw new Error(`commit ref ${JSON.stringify(commit)} does not resolve`);
+            if (policy_id) {
+                const abstention = confirmSharedPolicy(policy_id, public_only);
+                if (abstention)
+                    return err(abstention);
+            }
             const exactCommit = commit ? revParse(`${commit}^{commit}`, root) : undefined;
             const behavior = workspace ? { workspace }
                 : exactCommit ? { commit: exactCommit }

package/dist/serve/writelock.d.ts

@@ -1,3 +1,6 @@
+/** Shared with jsonStore's `.rmw-lock` (core/procstart.ts); re-exported so this
+ *  module's surface is unchanged. */
+export { CREATED_AFTER_SLACK_MS } 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 declare const STALE_AFTER_MS = 60000;
@@ -7,10 +10,6 @@ export declare const ACQUIRE_TIMEOUT_MS = 10000;
  *  claimed section is a few syscalls, so anything this old means its claimer
  *  crashed inside it. */
 export declare const CLAIM_STALE_MS = 10000;
-/** How much later than the lock's recorded `at` the pid's current process must
- *  have been created before it is proven not to be the owner. A genuine owner
- *  started BEFORE it took the lock; the slack only absorbs clock granularity. */
-export declare const CREATED_AFTER_SLACK_MS = 5000;
 export interface LockOwner {
     pid: number;
     host: string;

package/dist/serve/writelock.js

@@ -22,7 +22,10 @@ import { hostname } from "node:os";
 import { randomBytes } from "node:crypto";
 import { closeSync, mkdirSync, openSync, readFileSync, rmSync, rmdirSync, statSync, writeSync } from "node:fs";
 import { join } from "node:path";
-import { heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
+import { createdAfterLock, heldLockNonces, judgeSameHostOwner, processStartedAt, selfStartToken, startTokenOf } from "../core/procstart.js";
+/** Shared with jsonStore's `.rmw-lock` (core/procstart.ts); re-exported so this
+ *  module's surface is unchanged. */
+export { CREATED_AFTER_SLACK_MS } 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;
@@ -33,10 +36,6 @@ export const ACQUIRE_TIMEOUT_MS = 10_000;
  *  crashed inside it. */
 export const CLAIM_STALE_MS = 10_000;
 const POLL_MS = 25;
-/** How much later than the lock's recorded `at` the pid's current process must
- *  have been created before it is proven not to be the owner. A genuine owner
- *  started BEFORE it took the lock; the slack only absorbs clock granularity. */
-export const CREATED_AFTER_SLACK_MS = 5_000;
 export class WriteLockTimeout extends Error {
     path;
     heldBy;
@@ -104,9 +103,10 @@ function stealable(path, owner, now, token) {
     // 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.
+    // The whole table, and the creation-time check for an "unproven" pid, live in
+    // core/procstart.ts so this lock and jsonStore's `.rmw-lock` apply one rule;
+    // "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,
@@ -117,21 +117,12 @@ function stealable(path, owner, now, token) {
             heldNonces: heldLockNonces,
         });
         if (verdict === "unproven")
-            return ageMs > STALE_AFTER_MS && createdAfterLock(owner, token);
+            return ageMs > STALE_AFTER_MS && createdAfterLock(owner, token.startedAt);
         if (verdict !== "age")
             return verdict === "stale";
     }
     return ageMs > STALE_AFTER_MS;
 }
-/** Is the process now holding the owner's pid provably newer than the lock?
- *  Unreadable either way means not proven, and a live pid keeps its lock. */
-function createdAfterLock(owner, token) {
-    const at = Date.parse(owner.at);
-    if (!Number.isFinite(at))
-        return false;
-    const started = (token.startedAt ?? processStartedAt)(owner.pid);
-    return started !== null && started > at + CREATED_AFTER_SLACK_MS;
-}
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 /** The claim a contender must hold to REMOVE a stale lock. A sibling directory,
  *  created with the same exclusive `mkdir` the commit lock uses

package/dist/store/hunchStore.d.ts

@@ -4,6 +4,7 @@ import { type DB } from "./db.js";
 import { type Embedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
 import { type RankingContext, type RankingQuery, type RankingWeights, type SlotOptions, type TaskSelection } from "../core/taskRanking.js";
+import { type WhyById } from "../core/whyRecord.js";
 import { type VetoTier } from "../core/strictgate.js";
 import { type DiffAnalysis, type DiffStatus } from "../extractors/diff.js";
 import type { CheckReport, CausalWhy, ImpactReport } from "../core/checkreport.js";
@@ -43,6 +44,8 @@ export interface WhyResult {
     constraints: Constraint[];
     symbols: Symbol[];
     components: Component[];
+    /** Set when the target is a record id (`dec_…`, `con_…`, …; issue #474). */
+    byId?: WhyById;
 }
 export interface FragileNode {
     id: string;
@@ -391,6 +394,13 @@ export declare class HunchStore {
         asOf?: string;
         canRead?: (record: unknown) => boolean;
     }): WhyResult;
+    /** 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. */
+    private whyRecord;
     /** 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. */

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 {};