@davesheffer/hunch 1.45.2 → 1.47.0

package/dist/mcp/server.js

@@ -69,7 +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 { 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";
@@ -90,24 +90,25 @@ const err = (text) => ({ content: [{ type: "text", text }], isError: true });
  *  Transient states that say "retry" in their own words stay unprefixed. */
 const refused = (text) => err(`Refused: ${text}`);
 const invalid = (text) => err(`Invalid: ${text}`);
-/** Shared by every auto-committing write tool (issue #20): the MCP `roots` protocol
- *  cannot see an agent-driven `cd`/EnterWorktree, so a stdio server's cached root
- *  never moves on its own — this is the client-agnostic fallback, resolved fresh on
- *  every call by the generic tool wrapper below (see extractCwdHint). */
+/** Shared by every auto-committing write tool. The MCP roots protocol cannot observe an
+ *  agent-driven directory change or worktree entry, so a stdio server's cached root never
+ *  moves by itself; this field is the client-agnostic fallback, resolved fresh on every
+ *  call by the generic tool wrapper. */
 const cwdHintField = z.string().optional().describe("Your current directory, when it differs from where this session started (e.g. a worktree); " +
     "writes then commit there, not to the original root.");
 /** Shared by hunch_record_decision/correction/finding — identical text repeated 3x
  *  otherwise. hunch_context's task_id field differs (delivery vs. save) and keeps its
  *  own description. */
 const saveTaskIdField = TaskIdSchema.optional().describe("Task ID, to attribute this save to it; never affects capture authority.");
-/** Pull `cwd` out of a tool call's already-parsed input without assuming any one
- *  tool's exact input shape — every write tool spreads the same cwdHintField in,
- *  but the wrapper below runs for every tool, read or write. */
-function extractCwdHint(input) {
-    if (!input || typeof input !== "object")
+/** Pulls the cwd hint out of a tool call's already-parsed first argument. The wrapper
+ *  runs for EVERY tool (read and write), so this assumes nothing about any one tool's
+ *  input shape: anything that is not an object with a non-blank string `cwd` yields
+ *  undefined. The original (untrimmed) string is returned. */
+function cwdHintOf(input) {
+    if (typeof input !== "object" || input === null)
         return undefined;
     const cwd = input.cwd;
-    return typeof cwd === "string" && cwd.trim() ? cwd : undefined;
+    return typeof cwd === "string" && cwd.trim() !== "" ? cwd : undefined;
 }
 /** Honest auto-commit suffix: reports only what flushCapture ACTUALLY did. A skipped
  *  commit (backstop/lock/nothing staged) says nothing — the record is on disk and the
@@ -150,11 +151,9 @@ const publicHomeNote = (home, hasPrivate, record, hunchDir) => {
         return risk;
     return "\nℹ Landed in the COMMITTED PUBLIC store (publishes with the repo). For sensitive/strategy content, re-record with private:true — the overlay store." + risk;
 };
-/** Self-diagnosing destination report (issue #17/#20): the exact failure mode this
- *  guards against is silent — a capture landing in the wrong repo/branch with no
- *  sign of it short of a manual `git log` audit. Every auto-committing write tool
- *  appends this so the destination is always visible in the response, whether or
- *  not a cwd hint was involved in choosing it. */
+/** Self-diagnosing destination suffix for every auto-committing write tool. A capture
+ *  silently landing in the wrong repo or branch is only discoverable by auditing git log
+ *  by hand, so the destination is ALWAYS shown, whether or not a cwd hint chose it. */
 const destinationNote = (destRoot) => {
     const branch = currentBranch(destRoot);
     return ` [captured${branch ? ` on branch ${branch}` : ""} in ${destRoot}]`;
@@ -586,12 +585,10 @@ function nuryelWriteSubject(facet, record) {
     const kind = facet.endsWith("s") ? facet.slice(0, -1) : facet;
     return `${kind}${typeof label === "string" ? ` "${label.slice(0, 60)}"` : ""} (nuryel_write)`;
 }
-/** Where a capture keyed to `home` actually lands: the private overlay directory when
- *  one is configured, else the public repo root. Centralizes the branch used at every
- *  destination-reporting call site below — `hunch_policy_upgrade_correction` once
- *  diverged from this (computing its own `artifactHome` but reporting the public root
- *  regardless), silently misreporting the destination for a private-homed proof. */
-const resolveDestRoot = (home, store, root) => home === "private" && store.privateDir ? store.privateDir : root;
+/** Where a capture keyed to a storage home actually lands. Centralized so every
+ *  destination-reporting call site agrees: hunch_policy_upgrade_correction once computed
+ *  its own home but reported the public root regardless, misreporting a private-homed proof. */
+const destinationRoot = (home, store, root) => home === "private" && store.privateDir ? store.privateDir : root;
 // Read-side token budgets: every tool result is injected into a Claude Code
 // 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
@@ -993,13 +990,12 @@ function qualityNudge(rec) {
     }
     return "";
 }
-/** Resolve a free-form target (symbol id / name / file path) to symbol records.
- *  Tiered exact-id > exact-name > exact-file > segment-anchored-suffix matching,
- *  shared with `HunchStore.why()` via `matchSymbolsTiered` so the two don't drift
- *  apart on the same question. */
+/** Resolve a free-form target (symbol id, name, or file path) to symbol records using
+ *  tiered matching — exact id, then exact name, then exact file, then a path-segment-anchored
+ *  suffix. Shared with HunchStore.why() through matchSymbolsTiered so the two never disagree. */
 export function resolveSymbols(store, target) {
-    // An absolute target (an agent's edit-payload path, verbatim) never matched
-    // the repo-relative stored file paths below (issue #296).
+    // An absolute path (an agent's verbatim edit-payload path) must match the repo-relative
+    // stored file paths (issue #296).
     target = repoRelativeTarget(target, store.publicRoot);
     const syms = store.json.loadAll("symbols");
     const components = store.json.loadAll("components");
@@ -1253,6 +1249,10 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         }
         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.
@@ -1368,23 +1368,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => hiddenTools.has(name) ? undefined : registerTool(name, config, async (...args) => {
-        // Claude Code CLI never advertises `roots`/`roots/list_changed` for an agent-driven
-        // `cd` or EnterWorktree (issue #20) — the cached `root` above just never moves, so a
-        // write silently lands wherever the process was spawned. Write tools accept an
-        // optional `cwd` argument (see cwdHintField) as a client-agnostic fallback: resolved
-        // fresh on EVERY call instead of trusted from a cache, and re-homing this stdio
-        // process the same way a `roots` notification would. Only safe when this is the
-        // sole in-flight request — re-homing under a concurrent request would tear its
-        // root/store out from under it, so that case is refused rather than risked.
-        const cwdHint = extractCwdHint(args[0]);
+        // The Claude Code CLI never advertises roots/list_changed for an agent `cd` or worktree
+        // entry, so the cached root never moves and writes land where the process was spawned.
+        // Write tools therefore accept an optional `cwd` (see cwdHintField) as a client-agnostic
+        // fallback, resolved fresh on every call rather than cached, re-homing this stdio
+        // process the way a roots notification would. That is only safe when no other request
+        // is in flight, so that case is refused instead of risked.
+        const cwdHint = cwdHintOf(args[0]);
         // A pinned root is the whole point of `hunch mcp --root`: a served partition must not
         // follow the caller's working directory into some other checkout.
         if (cwdHint !== undefined && !pinned) {
             const target = canonicalRootPath(findRoot(cwdHint));
             if (target !== canonicalRootPath(root)) {
-                if (activeRequests) {
-                    return err(`Hunch is mid-request against ${root} and cannot safely switch to the working directory you passed ` +
-                        `(resolves to ${target}) while another call is in flight. Retry this call once the other one completes.`);
+                if (activeRequests !== 0) {
+                    return err(`Hunch is serving ${root} and cannot safely switch to your working directory (${target}) while another call is in flight. Retry once the other call completes.`);
                 }
                 try {
                     setRoot(cwdHint);
@@ -1508,16 +1505,23 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         if (as_of && !asOf)
             return invalid(`Could not resolve as_of "${as_of}" to a commit.`);
         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.
-        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}`);
+        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
@@ -1912,13 +1916,13 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
     // -- hunch_now (the hot view: recent activity + roadmap) --------------------
     // PUBLIC store only, per dec_29eff08c69's jurisdiction rule: an assistant may
     // paste this anywhere, so it must be publishable by construction. Union view
-    // stays behind `hunch now --private` on the local terminal. EXCEPTION: a
-    // queued commit-repair's liveness is checked against the full store (see
-    // below), so a private-overlay decision's id and commit shas — never its
-    // title — can surface in the escalation line.
+    // is available only through the local terminal command `hunch now --private`.
+    // Exception: a queued commit-repair's liveness is checked against the full store, so a
+    // private-overlay decision's id and commit shas (never its title) may appear in the
+    // escalation line.
     server.registerTool("hunch_now", {
         title: "Recent activity + the roadmap (the hot view)",
-        description: "What just happened and what's next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning what to work on. Same data as the wiki's now.md. Public store only, EXCEPT a queued commit-repair's liveness is checked against the full store (so a private-overlay decision's fully-answerable repair doesn't go silently unanswerable); only its id and the commit shas ever surface, never its title.",
+        description: "What just happened and what is next, straight from the graph: the last N decisions, the ROADMAP, and any inline human question such as an imported ADR awaiting explicit approve/decline. Call at session start to orient, or before planning. Same data as the wiki's now.md. Public store only — except that a queued commit-repair's liveness is checked against the full store, so a private-overlay decision's answerable repair does not go silently unanswerable; only its id and commit shas ever surface, never its title.",
         inputSchema: {
             recent_limit: z.number().optional().describe("How many recent decisions to include (default 5)."),
             roadmap_limit: z.number().optional().describe("How many roadmap entries to include (default 2); the rest are counted."),
@@ -1951,18 +1955,15 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             L.push("", ws);
         const escalations = pendingEscalations(store.advisoryRecs("decisions"));
         escalations.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // liveness checked against the full store (repair-provenance reads the
-        // full store too) even though the title stays scoped to advisoryRecs —
-        // an overlay decision's repair is fully answerable, so it must not go
-        // silent here just because its title is private.
-        const hunchNowQueue = readActivePendingRepairs(root);
-        escalations.push(...commitRepairEscalations(hunchNowQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchNowQueue)));
-        // Only ACTIONABLE entries are a question the assistant can put to the human
-        // directly — a duplicate-id commit-repair follower whose own resolution
-        // says "act on a different entry first" isn't one (#61).
-        const actionableNow = actionableEscalations(escalations);
-        if (actionableNow.length) {
-            L.push("", `⚖ ${actionableNow.length} decision(s) need the human's call — ASK inline (never queue): ${actionableNow.map((e) => e.question).join(" · ")}`);
+        // Liveness is checked against the FULL store (the title stays scoped to advisory
+        // records), so an overlay decision's repair does not go silent.
+        const repairQueue = readActivePendingRepairs(root);
+        escalations.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
+        // A duplicate-id commit-repair follower whose own answer is "act on a different
+        // entry first" is not a question to raise (#61).
+        const actionable = actionableEscalations(escalations);
+        if (actionable.length) {
+            L.push("", `⚖ ${actionable.length} decision(s) need the human's call — ASK inline (never queue): ${actionable.map((e) => e.question).join(" · ")}`);
         }
         return ok(L.join("\n"));
     });
@@ -2028,24 +2029,20 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
         // Premise decay: a live decision whose recorded reason died. Question-framed
         // like every entry here — authority never changes until the human answers.
         items.push(...premiseEscalations(store.advisoryRecs("decisions"), { now: new Date().toISOString(), exists: (p) => existsSync(join(root, p)) }));
-        // See the sibling hunch_now handler above for why `live` is the full store.
-        const hunchEscalationsQueue = readActivePendingRepairs(root);
-        items.push(...commitRepairEscalations(hunchEscalationsQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, hunchEscalationsQueue)));
+        // Live set is the full store, for the reason given in the sibling hunch_now handler.
+        const repairQueue = readActivePendingRepairs(root);
+        items.push(...commitRepairEscalations(repairQueue, store.advisoryRecs("decisions"), store.recs("decisions"), withheldRewrites(root, repairQueue)));
         try {
             items.push(...policyEscalations(new ConstitutionService(store, root).list({ publicOnly: true }).map((p) => ({ ...p, last_action: p.audit.at(-1)?.action ?? null }))));
         }
         catch { /* constitution unavailable — memory escalations still surface */ }
         if (!items.length)
             return ok("✓ Nothing needs a human decision — memory is auto-trusted and self-consistent.");
-        // Only ACTIONABLE entries are a question to ask the human directly — a
-        // duplicate-id commit-repair follower whose own resolution says "act on
-        // a different entry first" still surfaces below for transparency, but
-        // isn't itself something to raise as a decision (#61).
+        // Only actionable entries are questions to raise; non-actionable followers still
+        // appear below for transparency (#61).
         const L = [escalationHeadline(items, "mcp"), ""];
         for (const e of items) {
-            // Marked distinctly (never the "⚖ question" glyph) when it isn't
-            // itself something to raise — an entry whose own answer is "act on a
-            // different entry first" reads as informational, not as a question.
+            // Non-actionable entries are marked distinctly so they read as informational, not as a question.
             L.push(`${e.actionable === false ? "·" : "⚖"} ${e.question}`);
             L.push(`   ${e.detail}`);
             L.push(`   → ${e.resolution}`, "");
@@ -2066,7 +2063,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
@@ -2456,7 +2460,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const where = decision.private
                 ? ` [PRIVATE overlay — not committed to this repo]${flushed}`
                 : home === "private" ? ` [SHARED store — one source of truth for the whole team]${flushed}` : flushed;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(home, store, root));
             // The chain (nuryel.state/1): a `shipped` receipt in an organization drawer rests on
             // this decision by id + the hash ON FILE + this repository's partition. Hand the ref
             // over now so the agent never rests on a pre-store hash or re-derives the scope.
@@ -2567,7 +2571,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const tierNote = `
 
 ⚠ ${why} — this rule is agent_recorded TESTIMONY${capped ? ` and was capped from "${requested.severity}" to "${rec.severity}"` : ""}. It IS enforced: the pre-edit hook and CI surface it on every matching edit from now on. What it cannot do is DENY an edit — only a rule a human confirmed outside the agent channel may block. The human confirms it by running: ${confirmCommand(rec.id, { private: home === "private", severity: requested.severity })}`;
-            const dest = destinationNote(resolveDestRoot(home, store, root));
+            const dest = destinationNote(destinationRoot(home, store, root));
             return ok(`${existing ? "Updated" : "Recorded"} ${rec.severity} constraint ${rec.id}: "${rec.statement}" (scope: ${rec.scope.join(", ")}).${where}${dest} It now ${enforce}.${reviewNote}${tierNote}`);
         }
         catch (e) {
@@ -2648,8 +2652,9 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 ? `\n\n△ violates_constraint ${rec.violates_constraint} resolves to no known constraint — if the rule isn't recorded yet, hunch_record_correction it and re-record this finding with the real id.`
                 : "";
             const noEvidence = rec.evidence.length ? "" : "\n\n△ No evidence attached — a finding without the query/output that produced it is an opinion. Re-record with evidence when you have it.";
-            const dest = destinationNote(resolveDestRoot(home, store, root));
-            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where}${dest} It now grounds edits to: ${[...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)"}.${danglingCon}${noEvidence}`);
+            const dest = destinationNote(destinationRoot(home, store, root));
+            const grounds = [...rec.affected_files, ...rec.affected_symbols].join(", ") || "(nothing — add affected_files/symbols so it surfaces at edit time)";
+            return ok(`${existing ? "Updated" : "Recorded"} finding ${id}: "${rec.title}" (${rec.triage}/${rec.severity}, observed ${rec.observed_at.slice(0, 10)}).${where}${dest} It now grounds edits to: ${grounds}.${danglingCon}${noEvidence}`);
         }
         catch (e) {
             return err(`Failed to record finding: ${e.message}`);
@@ -2681,7 +2686,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) => {
@@ -2745,7 +2750,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 }) => {
@@ -2850,7 +2855,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)}` : ""}`);
@@ -2883,6 +2895,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
@@ -2915,7 +2937,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (artifactHome === "private") {
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", `hunch: prove correction ${constraint_id}`, startupTeamRoute ?? undefined);
             }
-            const destRoot = resolveDestRoot(artifactHome, store, root);
+            const destRoot = destinationRoot(artifactHome, store, root);
             const destination = { root: destRoot, branch: currentBranch(destRoot) };
             if (include_artifacts)
                 return ok(JSON.stringify({ ...upgrade, destination }, null, 2));
@@ -3104,7 +3126,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             if (!home)
                 throw new Error(`policy ${policy_id} has no exact storage home`);
             flushMemoryHome(store, hunchPaths(root).hunch, home, `hunch: plan policy ${policy_id}`, startupTeamRoute ?? undefined);
-            const destRoot = resolveDestRoot(home, store, root);
+            const destRoot = destinationRoot(home, store, root);
             return ok(JSON.stringify({ ...plan, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
         }
         catch (e) {
@@ -3402,7 +3424,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                     dependencyTimeoutMs: dependency_timeout_ms ?? 300_000,
                 });
                 flushMemoryHome(store, hunchPaths(root).hunch, "private", "hunch: materialize G2 behavior policies", startupTeamRoute ?? undefined);
-                const destRoot = resolveDestRoot("private", store, root);
+                const destRoot = destinationRoot("private", store, root);
                 return ok(JSON.stringify({ ...materialized, destination: { root: destRoot, branch: currentBranch(destRoot) } }, null, 2));
             }
             catch (e) {
@@ -3479,6 +3501,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

@@ -10,10 +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;
+/** `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;
 }

package/dist/serve/writelock.js

@@ -13,7 +13,9 @@
  * equality and never by clock arithmetic (see core/procstart.ts). Where no token can
  * compare them (macOS, Windows, legacy records) a stale-looking lock whose live pid
  * belongs to a process CREATED after the lock's recorded `at` is taken over too: that
- * process cannot be the one that took it (issue #287). Removing a stale
+ * process cannot be the one that took it (issue #287). That creation-time check
+ * runs on macOS and Windows only; on linux `processStartedAt` returns null, so a
+ * tokenless live pid there is never taken over. Removing a stale
  * lock is itself serialized behind an exclusive `.reclaim` claim directory, because
  * judging and removing are two steps and two contenders can otherwise both "win"
  * (see `takeOver`).
@@ -56,12 +58,19 @@ export function writeLockPath(hunchDir) {
 function readOwner(path) {
     try {
         const parsed = JSON.parse(readFileSync(path, "utf8"));
-        if (typeof parsed.pid !== "number" || typeof parsed.nonce !== "string")
+        // A missing nonce is not unreadable metadata: the pid still names a
+        // same-host owner, so it gets the live-pid judgement `.rmw-lock` gives it,
+        // never the age fallback that would steal a live writer's lock (#491).
+        // The pid check mirrors `.rmw-lock`'s: `kill(0|-n, 0)` signals a process
+        // group and always "succeeds" (a live wedge forever), and a fractional or
+        // huge pid throws (stolen even when fresh) — so such a record is unreadable
+        // and age decides.
+        if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid < 1)
             return undefined;
         return {
             pid: parsed.pid,
             host: typeof parsed.host === "string" ? parsed.host : "",
-            nonce: parsed.nonce,
+            ...(typeof parsed.nonce === "string" ? { nonce: parsed.nonce } : {}),
             at: typeof parsed.at === "string" ? parsed.at : "",
             ...(typeof parsed.start === "string" ? { start: parsed.start } : {}),
         };
@@ -268,6 +277,11 @@ export async function withWriteLock(hunchDir, fn, opts = {}) {
         // from, the file now protects another writer. The nonce is dropped in a
         // `finally` of its own, so a throw from the conditional remove can never
         // leave us vouching for a lock we no longer hold.
+        //
+        // DIFFERS from `.rmw-lock` on release: a readable record WITHOUT a nonce is
+        // left in place here (it is not ours — a legacy or foreign writer replaced
+        // our file), where `.rmw-lock` removes it. Only an unreadable record is
+        // removed unconditionally.
         try {
             const current = readOwner(path);
             if (!current || current.nonce === nonce)

package/dist/store/hunchStore.d.ts

@@ -403,7 +403,8 @@ export declare class HunchStore {
     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. */
+     *  walk edges BACKWARD (edges.to = current) following call/dep/import/contains,
+     *  plus `references` — the only edge YAML/Helm/Kustomize emit (issue #486). */
     getDependents(id: string, maxDepth?: number): Array<{
         id: string;
         depth: number;