@davesheffer/hunch 1.45.1 → 1.46.0

package/dist/integrations/uninstall.js

@@ -12,9 +12,9 @@
  *
  * `.hunch/` holds the engineering memory, so it stays unless `--purge`.
  */
-import { existsSync, lstatSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync, chmodSync } from "node:fs";
+import { existsSync, readFileSync, readdirSync, rmdirSync, rmSync, statSync, writeFileSync, chmodSync } from "node:fs";
 import { spawnSync } from "node:child_process";
-import { basename, join, relative, resolve } 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 { currentBranch, gitCommonDir, isGitRepo, isLinkedWorktree, separateGitDirLink } from "../extractors/git.js";
@@ -26,18 +26,39 @@ 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";
-/** The opt-out marker, at the repository root. Commit it so every clone stays opted out. */
-export const OPT_OUT_FILE = ".hunch-removed";
-export function isOptedOut(root) {
-    try {
-        return lstatSync(join(root, OPT_OUT_FILE)).isFile();
-    }
-    catch {
-        return false;
+import { isOptedOut, OPT_OUT_FILE } from "./optout.js";
+export { isOptedOut, OPT_OUT_FILE };
+/** 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) {
+    return optOutMarkerAt(start) !== null;
+}
+/** The opt-out marker that gates `start` (walked as in `optedOutAt`), or null. With
+ *  `withinRepo`, a marker counts only when the walk reaches a repository: outside one,
+ *  an ancestor's marker gates nothing. */
+export function optOutMarkerAt(start, opts = {}) {
+    let found = null;
+    for (let dir = resolve(start);;) {
+        if (!found && isOptedOut(dir)) {
+            found = join(dir, OPT_OUT_FILE);
+            if (!opts.withinRepo)
+                return found;
+        }
+        if (existsSync(join(dir, ".git")))
+            return found;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return opts.withinRepo ? null : found;
+        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\`.`;
+/** The refusal, naming the marker of the repository actually checked (#488). */
+export function optOutMessage(marker = OPT_OUT_FILE) {
+    return `Hunch was removed from this repository on purpose (${marker}), so it will not set itself up here again. To reinstall, delete ${marker} and run \`hunch init\`.`;
 }
 function markerText() {
     return [
@@ -292,6 +313,7 @@ export function planUninstall(root, opts = {}) {
     p.hookConfig(".codex/hooks.json", providerEntry);
     p.hookConfig(".github/hooks/hunch.json", providerEntry);
     p.hookConfig(".windsurf/hooks.json", providerEntry);
+    p.hookConfig(".devin/hooks.json", providerEntry);
     p.json(".agents/hooks.json", "removed the hunch hook group", (json) => {
         if (!("hunch" in json))
             return false;
@@ -441,7 +463,7 @@ export function planUninstall(root, opts = {}) {
 }
 /** Directories Hunch's writers create; removed only when left empty. Deepest first. */
 const PRUNE_DIRS = [
-    ".claude/commands", ".claude", ".cursor/rules", ".cursor", ".windsurf/rules", ".windsurf",
+    ".claude/commands", ".claude", ".cursor/rules", ".cursor", ".windsurf/rules", ".windsurf", ".devin",
     ".vscode", ".github/hooks", ".github/workflows", ".github", ".codex", ".agents",
 ];
 export function applyUninstall(plan) {

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, WHY_RECORD_ID } 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,74 @@ 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;
+    };
+    // Exact-id record reads (findings, corrections, imported ADRs, why-by-id): the
+    // same confirmation, gated to shared mode. Null means "re-read; absence is
+    // confirmed or the store is not shared", else the abstention to return instead.
+    const confirmSharedRecord = (subject) => store.mode === "shared" && store.privateDir ? confirmSharedMiss(`${subject} is absent from shared team memory`, subject) : 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 +1310,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 +1420,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 +1443,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 +1502,35 @@ 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 });
+        // An id-shaped target is an id miss when the store reported one (generated
+        // shape) or, for a hand-written id, when nothing else matched it either.
+        const idMiss = (r) => !r.byId?.record && (r.byId !== undefined || (WHY_RECORD_ID.test(target)
+            && !r.decisions.length && !r.constraints.length && !r.bugs.length && !r.components.length && !r.symbols.length));
+        // "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.
+        const heldNow = () => !!(asOf && store.why(target).byId?.record);
+        if (idMiss(w) && !heldNow()) {
+            const abstention = confirmSharedRecord(`record ${w.byId?.id ?? target}`);
+            if (abstention)
+                return err(abstention);
+            w = store.why(target, { asOf });
+        }
+        // A hand-written id held now but not in force at as_of: say so, like a generated id.
+        if (asOf && !w.byId && idMiss(w) && heldNow())
+            w = { ...w, byId: { id: target, record: null, 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 +1538,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)
@@ -1963,7 +2077,14 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         },
     }, async ({ decision_id, expected_source_hash, expected_review_hash, disposition, reviewed_by }) => {
         try {
-            const decision = store.advisoryRecs("decisions").find((candidate) => candidate.id === decision_id);
+            const find = () => store.advisoryRecs("decisions").find((candidate) => candidate.id === decision_id);
+            let decision = find();
+            if (!decision) {
+                const abstention = confirmSharedRecord(`imported ADR ${decision_id}`);
+                if (abstention)
+                    return err(abstention);
+                decision = find();
+            }
             if (!decision)
                 return invalid(`Imported ADR ${decision_id} is not present in the current advisory memory home.`);
             // Approval grants human authority, so the agent's report that the human approved
@@ -2071,21 +2192,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);
         }
@@ -2588,7 +2699,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         server.registerTool("nuryel_read", {
             title: "nuryel.state/1 read — the system-of-record answer for a subject",
-            description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped. To read observations beyond the default 64, use observed_page:{} with one scope and a subject, then pass state_of_record.observed_page.next_cursor as observed_page.cursor until null. A conflict means the observations changed: restart from the first page. Never claim complete coverage while a next cursor remains.",
+            description: "Read organizational state under a delivery receipt. Pass the principal (id, kind, grants) and the scope; optionally a subject (an entity id, a decision topic, an external `object_type:object_key`) to get state_of_record — what is current, in force, done, what it depends on and what invalidates it — plus a task phrase for the ranked delivery envelope. Scopes the principal is not granted are named in denied_scopes, never silently dropped. To read observations beyond the default 64, use observed_page:{} with one scope and a subject, then pass state_of_record.observed_page.next_cursor as observed_page.cursor until null. A conflict means the observations changed: restart from the first page. Never claim complete coverage while a next cursor remains. facets filters state_of_record and conventions only; the delivery envelope is ranked independently and keeps the constraints in force.",
             inputSchema: ReadRequestSchema.omit({ schema: true }).shape,
             outputSchema: ReadResponseSchema.shape,
         }, async (input) => {
@@ -2652,7 +2763,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         });
         server.registerTool("nuryel_write", {
             title: "nuryel.state/1 write — provenance + idempotency in, durability out",
-            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version. With capability nuryel.field-provenance/1, a derived record may carry field_provenance: [{selector:{kind:json_pointer,path:/field} or {kind:text,start:0,end:10}, value_hash:stateHash(selected scalar or text), dependency_hashes:[stateHash(existing dependency)]}]. Text offsets count Unicode code points, end exclusive. Citations are writer-supplied traceability, not verified support; negotiate support in every shared reader before writing them. With nuryel.record-visibility/1, records may carry visibility:{owner:principal-id,readers:[ids],writers:[ids]}; the owner is implicit in both lists, and writers must be readers. Owner-only audience changes require expected_version, including supersession. Restricted records require a dedicated partition; local stdio principal assertions assume trusted callers.",
+            description: "Write one record into a facet (receipts, commitments, derived, entities, relationships, or the legacy decisions/constraints/bugs/findings). The record must carry provenance; the request must carry an idempotency_key — a replay returns the original, a reused key with a different payload is refused. Ids are derived from the record's facts, never chosen. A second live decision on a topic is refused with the incumbent named; pass supersedes to replace it explicitly. organization/team/user partitions never ride a repository: they require an overlay. To show an existing captured observation under another subject without copying it, write a relationship type observation_about with from=observation id, to=subject, observation_hash, lifecycle=active, reason and hashed external evidence of the explicit association. Retire the relationship to unlink; reactivation requires expected_version. With capability nuryel.field-provenance/1, a derived record may carry field_provenance: [{selector:{kind:json_pointer,path:/field} or {kind:text,start:0,end:10}, value_hash:stateHash(selected scalar or text), dependency_hashes:[stateHash(existing dependency)]}]. Text offsets count Unicode code points, end exclusive. Citations are writer-supplied traceability, not verified support; negotiate support in every shared reader before writing them. With nuryel.record-visibility/1, records may carry visibility:{owner:principal-id,readers:[ids],writers:[ids]}; the owner is implicit in both lists, and writers must be readers. Owner-only audience changes require expected_version, including supersession. Restricted records require a dedicated partition; local stdio principal assertions assume trusted callers. expected_version is compare-and-swap against the incumbent, or with supersedes against the predecessor (its record hash or ledger seq); for a record not on file pass null, or 0 to assert the id was never written — any other value is refused as a conflict.",
             inputSchema: { ...WriteRequestSchema.omit({ schema: true }).shape, cwd: cwdHintField },
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {
@@ -2757,7 +2868,14 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         const concerns = (f) => [...f.affected_files, ...f.affected_symbols].join(", ") || "(unscoped)";
         const links = (f) => [f.violates_constraint ? `violates ${f.violates_constraint}` : "", f.method ? `re-verify via ${f.method}` : "", f.resolved_commit ? `fixed in ${f.resolved_commit.slice(0, 9)}` : ""].filter(Boolean).join("; ");
         if (id) {
-            const f = store.recs("findings").find((r) => r.id === id);
+            const find = () => store.recs("findings").find((r) => r.id === id);
+            let f = find();
+            if (!f) {
+                const abstention = confirmSharedRecord(`finding ${id}`);
+                if (abstention)
+                    return err(abstention);
+                f = find();
+            }
             if (!f)
                 return ok(`No finding "${id}".`);
             return ok(`[${f.triage}/${f.severity}] ${f.title} (${f.id}, observed ${f.observed_at.slice(0, 10)})\n${f.observation}\nconcerns: ${concerns(f)}${links(f) ? `\n${links(f)}` : ""}`);
@@ -2790,6 +2908,16 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         try {
             if (public_only && private_only)
                 return invalid("Choose only one of public_only or private_only.");
+            // A correction missing from every home this call may read is confirmed against
+            // fresh shared memory before the upgrade reports it "not found". Public-only
+            // reads never consult the team remote.
+            const heldCorrection = () => !!(store.getPrivateRec("constraints", constraint_id)
+                || (!private_only && store.json.get("constraints", constraint_id)));
+            if (!public_only && !heldCorrection()) {
+                const abstention = confirmSharedRecord(`correction ${constraint_id}`);
+                if (abstention)
+                    return err(abstention);
+            }
             // Resolve the correction's exact home before any writes. Overlay-first is
             // the same selection contract as ConstitutionService.upgradeCorrection;
             // deriving this later from a policy id is unsafe when legacy public and
@@ -3002,6 +3130,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 +3155,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 +3173,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 +3191,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 +3220,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 }
@@ -3369,6 +3514,10 @@ export async function startServer(cwd = process.cwd(), options = {}) {
     wireClientRoots(control, fallback);
     const transport = new StdioServerTransport();
     await control.server.connect(transport);
+    // Exit through process.exit on a termination signal (same conventional codes as
+    // a signal death) so NODE_V8_COVERAGE is flushed for `hunch verify --refresh-map`.
+    process.once("SIGTERM", () => process.exit(143));
+    process.once("SIGINT", () => process.exit(130));
     console.error(control.pinned
         ? `[hunch-mcp] serving Hunch over stdio (pinned root ${control.getRoot()}; client roots ignored)`
         : `[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);

package/dist/serve/app.js

@@ -35,6 +35,8 @@ import { operatorHtml, operatorCss, operatorJs } from "./operator.js";
 import { MCP_PATH, handleMcpRequest } from "./mcpHttp.js";
 export const BODY_LIMIT_BYTES = 1024 * 1024;
 const POST_ROUTES = new Map([["/nuryel/v1/read", "read"], ["/nuryel/v1/write", "write"], ["/nuryel/v1/capture", "capture"], ["/nuryel/v1/capture-batch", "capture-batch"], ["/nuryel/v1/subscribe", "subscribe"], ["/nuryel/v1/records", "records"]]);
+/** GET-only routes: any other method is 405 with `Allow: GET`, not a POST-table 404. */
+const GET_ROUTES = new Set(["/nuryel/v1/health", "/nuryel/v1/capabilities"]);
 export const PROBLEM_TYPE = "https://www.hunchmemory.com/problems/nuryel.state/1/";
 export class HttpProblem extends Error {
     status;
@@ -272,6 +274,10 @@ export function createServeApp(config, opts = {}) {
                 return send(res, 200, { ...liveness, partitions: activeConfig.partitions.map((p) => scopePath(p.scope)) });
             }
             const principal = await authenticate(req, res, url, activeConfig);
+            if (GET_ROUTES.has(url.pathname) && req.method !== "GET") {
+                res.setHeader("allow", "GET");
+                throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
+            }
             if (url.pathname === "/nuryel/v1/capabilities" && req.method === "GET") {
                 const scope = parseScopeParam(url.searchParams.get("scope"));
                 const { status, payload } = await dispatch("capabilities", principal, scope ? { scope } : {}, activeConfig);
@@ -286,8 +292,10 @@ export function createServeApp(config, opts = {}) {
                 const message = await readBody(req);
                 return await handleMcpRequest(req, res, message, (route, body) => dispatch(route, principal, body, activeConfig), (error) => problemBody(problemOf(error)), version);
             }
-            if (req.method !== "POST")
+            if (req.method !== "POST") {
+                res.setHeader("allow", "POST");
                 throw problem(405, "method-not-allowed", `${req.method} is not allowed on ${url.pathname}`);
+            }
             const route = POST_ROUTES.get(url.pathname);
             if (!route)
                 throw problem(404, "not-found", `${url.pathname} is not a nuryel.state/1 route`);

package/dist/serve/config.js

@@ -114,6 +114,11 @@ export function initServeConfig(opts) {
         if (!publicOrigin)
             throw new Error("key-bound principals require an HTTPS public origin");
     }
+    // Refuse before writing anything: a grant must name a partition this config will serve.
+    const served = new Set([...(existing?.partitions ?? []).map((p) => scopePath(p.scope)), scopePath(opts.scope)]);
+    for (const g of opts.principal?.grants ?? [])
+        if (!served.has(scopePath(g)))
+            throw new Error(`cannot grant ${scopePath(g)}: this server does not serve it`);
     const root = resolve(opts.root);
     const hunchDir = resolve(root, ".hunch");
     mkdirSync(hunchDir, { recursive: true });

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,14 +10,12 @@ 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;
+/** `nonce` is optional on READ only: this lock always writes one, but a legacy or
+ *  foreign writer's record may lack it (issue #491). */
 export interface LockOwner {
     pid: number;
     host: string;
-    nonce: string;
+    nonce?: string;
     at: string;
     start?: string;
 }