@davesheffer/hunch 1.45.0 → 1.45.2

package/dist/integrations/uninstall.js

@@ -14,15 +14,15 @@
  */
 import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync, chmodSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { basename, join, relative } from "node:path";
+import { basename, dirname, join, relative, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
 import { writeFileAtomic } from "../core/io.js";
-import { gitCommonDir, isGitRepo, separateGitDirLink } from "../extractors/git.js";
+import { currentBranch, gitCommonDir, isGitRepo, isLinkedWorktree, separateGitDirLink } from "../extractors/git.js";
 import { HUNCH_END, HUNCH_START } from "./claudemd.js";
 import { ciWorkflowYaml } from "./ciAction.js";
 import { assertSafeTopLevelConfigFile, stripManagedGitignore } from "./gitignore.js";
 import { isHunchHookCommand } from "./hookmatch.js";
-import { planHookRemoval } from "./hooks.js";
+import { gitRun, isInside, planHookRemoval, worktreeTops } from "./hooks.js";
 import { ATTR_LINES, targetRepositoryEnv } from "./mergeDriver.js";
 import { antigravityMcpFile, isHunchProviderHook, readJsonObj, TOML_END, TOML_START, windsurfMcpFile } from "./providers.js";
 import { SLASH_COMMAND_FILES } from "./scaffold.js";
@@ -36,6 +36,24 @@ export function isOptedOut(root) {
         return false;
     }
 }
+/** Whether `start`, or the repository containing it, opted out: walks up through
+ *  `start`'s ancestors (which need not exist yet), stopping after the first one holding
+ *  `.git` or at the filesystem root, so a path inside an opted-out repository (`serve
+ *  init --root ./partitions/x`) is gated like the repository itself (#458). A `.hunch`
+ *  store is deliberately not a boundary: a partition store nested in an opted-out
+ *  repository stays gated (fail closed). */
+export function optedOutAt(start) {
+    for (let dir = resolve(start);;) {
+        if (isOptedOut(dir))
+            return true;
+        if (existsSync(join(dir, ".git")))
+            return false;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return false;
+        dir = parent;
+    }
+}
 export function optOutMessage() {
     return `Hunch was removed from this repository on purpose (${OPT_OUT_FILE}), so it will not set itself up here again. To reinstall, delete ${OPT_OUT_FILE} and run \`hunch init\`.`;
 }
@@ -195,6 +213,31 @@ function gitConfigHasDrivers(root) {
     const r = spawnSync("git", ["config", "--local", "--get-regexp", "^merge\\.hunch(-grounding)?\\."], { cwd: root, env: targetRepositoryEnv(), encoding: "utf8" });
     return r.status === 0 && r.stdout.trim() !== "";
 }
+/** The branch the clone treats as default: origin's HEAD, else a local main, else
+ *  master; "" when none can be named. */
+function defaultBranch(root) {
+    const head = gitRun(["symbolic-ref", "--quiet", "--short", "refs/remotes/origin/HEAD"], root);
+    if (head.status === 0 && head.stdout)
+        return head.stdout.replace(/^origin\//, "");
+    for (const b of ["main", "master"]) {
+        if (gitRun(["show-ref", "--verify", "--quiet", `refs/heads/${b}`], root).status === 0)
+            return b;
+    }
+    return "";
+}
+/** The marker is committed per branch: off the default branch, say the rest of the clone still has Hunch. */
+function branchWarning(root) {
+    try {
+        const branch = currentBranch(root);
+        const def = branch ? defaultBranch(root) : "";
+        if (!branch || !def || branch === def)
+            return null;
+        return `the ${OPT_OUT_FILE} marker is only on branch ${branch}; other branches of this clone still have Hunch's instruction blocks and config — commit and merge it, or run uninstall there too`;
+    }
+    catch {
+        return null;
+    }
+}
 /** The overlay clone a pointer names, for the "kept" note. Never deleted: it is
  *  its own repository holding memory that may not be pushed yet. */
 function pointerOverlay(file) {
@@ -295,22 +338,49 @@ export function planUninstall(root, opts = {}) {
             p.steps.push({ path: ciRel, kind: "keep", note: "it differs from the workflow Hunch generates (edited?); delete it yourself if you no longer want the Hunch Guard check" });
         }
     }
-    // Git hooks + merge driver.
+    // Git hooks + merge driver. Both live in the clone's common git dir, so they
+    // serve every worktree and every branch (#459): a linked worktree leaves them to
+    // the main checkout, and the main checkout says which worktrees lose them too.
+    // A bare common dir has no main checkout, so any worktree removes them and warns.
+    const warnings = [];
     if (isGitRepo(root)) {
+        const commonDir = gitCommonDir(root);
+        const top = gitRun(["rev-parse", "--show-toplevel"], root).stdout;
+        const here = top || root;
+        const same = (a, b) => isInside(a, b) && isInside(b, a);
+        // The main checkout as git lists it, not the common dir's parent, which in a
+        // bare clone or a --separate-git-dir checkout is no checkout at all.
+        const tops = worktreeTops(root);
+        const mainCheckout = tops.main;
+        const linked = commonDir !== "" && mainCheckout !== null && !same(mainCheckout, here) && isLinkedWorktree(root);
+        // The same test `hunch init` uses: in the common dir, or outside this checkout.
+        const shared = (file) => (commonDir !== "" && isInside(commonDir, file)) || (top !== "" && !isInside(top, file));
+        const elsewhere = (what, it) => `${what} shared by every worktree of this clone — run \`hunch uninstall\` from the main checkout (${mainCheckout}) to remove ${it}`;
+        let removesShared = false;
         for (const h of planHookRemoval(root)) {
             const path = p.rel(h.path);
             if (h.reason)
                 p.steps.push({ path, kind: "keep", note: h.reason });
-            else if (h.next === null)
-                p.steps.push({ path, kind: "delete", note: `Hunch's ${h.hookName} git hook`, run: () => rmSync(h.path, { force: true }) });
+            else if (linked && shared(h.path))
+                p.steps.push({ path, kind: "keep", note: elsewhere(`Hunch's ${h.hookName} git hook is`, "it") });
             else {
-                const next = h.next;
-                p.steps.push({ path, kind: "edit", note: `removed Hunch's block from the ${h.hookName} git hook (your own lines are kept)`, run: () => { writeFileSync(h.path, next); chmodSync(h.path, 0o755); } });
+                if (shared(h.path))
+                    removesShared = true;
+                if (h.next === null)
+                    p.steps.push({ path, kind: "delete", note: `Hunch's ${h.hookName} git hook`, run: () => rmSync(h.path, { force: true }) });
+                else {
+                    const next = h.next;
+                    p.steps.push({ path, kind: "edit", note: `removed Hunch's block from the ${h.hookName} git hook (your own lines are kept)`, run: () => { writeFileSync(h.path, next); chmodSync(h.path, 0o755); } });
+                }
             }
         }
-        if (gitConfigHasDrivers(root)) {
+        if (gitConfigHasDrivers(root) && linked) {
+            p.steps.push({ path: p.rel(join(commonDir, "config")), kind: "keep", note: elsewhere("the merge.hunch and merge.hunch-grounding drivers are", "them") });
+        }
+        else if (gitConfigHasDrivers(root)) {
+            removesShared = true;
             p.steps.push({
-                path: ".git/config", kind: "edit", note: "unregistered the merge.hunch and merge.hunch-grounding drivers",
+                path: commonDir ? p.rel(join(commonDir, "config")) : ".git/config", kind: "edit", note: "unregistered the merge.hunch and merge.hunch-grounding drivers",
                 run: () => {
                     for (const section of ["merge.hunch", "merge.hunch-grounding"]) {
                         spawnSync("git", ["config", "--local", "--remove-section", section], { cwd: root, env: targetRepositoryEnv(), stdio: "ignore" });
@@ -318,6 +388,13 @@ export function planUninstall(root, opts = {}) {
                 },
             });
         }
+        const others = linked ? [] : tops.linked.filter((w) => !same(w, here)).map((w) => resolve(w));
+        if (removesShared && others.length) {
+            warnings.push(`the git hooks and merge drivers are shared with ${others.length === 1 ? "the linked worktree" : `${others.length} linked worktrees`} ${others.join(", ")}, so they are removed there too, though ${others.length === 1 ? "it still has" : "those still have"} Hunch and no ${OPT_OUT_FILE} marker`);
+        }
+        const onBranch = branchWarning(root);
+        if (onBranch)
+            warnings.push(onBranch);
     }
     const attrs = p.text(".gitattributes");
     if (attrs !== null) {
@@ -378,7 +455,7 @@ export function planUninstall(root, opts = {}) {
     for (const dir of overlays) {
         p.steps.push({ path: p.rel(dir), kind: "keep", note: "a private/shared overlay clone: its own repository with memory that may not be pushed; never deleted here" });
     }
-    return { root, purge, steps: p.steps, refused: p.refused };
+    return { root, purge, steps: p.steps, refused: p.refused, warnings };
 }
 /** Directories Hunch's writers create; removed only when left empty. Deepest first. */
 const PRUNE_DIRS = [
@@ -430,6 +507,8 @@ export function formatUninstallPlan(plan, dryRun) {
         out.push(`  ✗ ${r.path}: ${r.reason}`);
     for (const s of plan.steps)
         out.push(`  ${icon(s.kind)} ${verb(s.kind)} ${s.path} — ${s.note}`);
+    for (const w of plan.warnings ?? [])
+        out.push(`  ⚠ ${w}`);
     return out;
 }
 //# sourceMappingURL=uninstall.js.map

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. */