@davesheffer/hunch 1.45.2 → 1.46.0

package/dist/integrations/hooks.js

@@ -19,6 +19,7 @@ import { join, isAbsolute, dirname, basename, relative, resolve } from "node:pat
 import { homedir } from "node:os";
 import { hooksDir, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
+import { isOptedOut, OPT_OUT_FILE } from "./optout.js";
 import { HUNCH_NPX_PACKAGE_SPEC, HUNCH_PACKAGE_NAME } from "../core/version.js";
 import { eolLengthAt, normalizeEol } from "../core/eol.js";
 const MARK = "# >>> hunch post-commit >>>";
@@ -617,6 +618,11 @@ function sharedInvocationFor(root, mark, invocation, own) {
  *  or the block would sit after an exec/exit, nothing is written and the result
  *  carries the snippet to add by hand (issue #311). */
 function installManagedBlock(root, hookName, mark, end, build, invocation) {
+    // A linked worktree whose branch predates the opt-out marker shares the main
+    // checkout's hooks dir: never re-hook a repository `hunch uninstall` opted out (#488).
+    const main = mainWorktreeRoot(root);
+    if (isOptedOut(main))
+        return { path: resolve(root, hooksDir(root), hookName), action: "opted-out", reason: `${join(main, OPT_OUT_FILE)} opts this repository out` };
     const t = resolveHookTarget(root, hookName, mark);
     if (t.manager !== "none") {
         const info = blockInfo(t, mark, root);
@@ -828,8 +834,8 @@ function repairProvenanceMergeBlock(invocation) {
  *  (the file itself is new) outranks "appended"/"updated" (an existing file
  *  changed), which outrank "unchanged". Non-writing results are handled before
  *  ranking (they must never be masked by a sibling's success). */
-const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "kept-shared": 1, "managed-elsewhere": 0, unreachable: 0 };
-const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable";
+const ACTION_RANK = { created: 3, appended: 2, updated: 2, unchanged: 1, "kept-shared": 1, "managed-elsewhere": 0, unreachable: 0, "opted-out": 0 };
+const writes = (h) => h.action !== "managed-elsewhere" && h.action !== "unreachable" && h.action !== "opted-out";
 /** Install a post-merge hook carrying TWO independently-managed blocks:
  *  re-sync the committed grounding docs when a merge brought memory in behind
  *  them (fnd_c402046ac7, HUNCH_SYNC-guarded, foreground — it rewrites five
@@ -850,6 +856,8 @@ export function installPostMergeHook(root, invocation) {
     // passed invocation unchanged — see selfBuildInvocation.
     const grounding = installManagedBlock(root, "post-merge", GROUNDING_MERGE_MARK, GROUNDING_MERGE_END, (inv, ctx) => groundingMergeBlock(ctx.portable ? inv : selfBuildInvocation(root, inv)), invocation);
     const repair = installManagedBlock(root, "post-merge", REPAIR_MERGE_MARK, REPAIR_MERGE_END, repairProvenanceMergeBlock, invocation);
+    if (grounding.action === "opted-out")
+        return grounding;
     if (!writes(grounding) && !writes(repair)) {
         return { ...grounding, snippet: `${grounding.snippet}\n${stripComment(repair.snippet ?? "", grounding.manager)}` };
     }
@@ -1025,6 +1033,8 @@ export function formatHookInstall(root, label, h, detail = "") {
         const how = h.keptFlags?.length ? KEPT_HOW : "";
         return [`  ✓ ${label} kept — the shared hook keeps running ${h.sharedInvocation}${flags} (not re-pointed at this worktree)${how}`];
     }
+    if (h.action === "opted-out")
+        return [`  - ${label} skipped — ${h.reason}`];
     if (writes(h)) {
         // A union write (issue #316). Once an option was KEPT, `detail` — which
         // describes only what this run asked for — is no longer the truth about the

package/dist/integrations/mergeDriver.js

@@ -14,6 +14,7 @@ import { readFileSync, existsSync } from "node:fs";
 import { writeFileAtomic } from "../core/io.js";
 import { assertSafeTopLevelConfigFile } from "./gitignore.js";
 import { GROUNDING_DOC_PATHS } from "./providers.js";
+import { mergeDriverShell } from "../cli/invocation.js";
 // Route the .hunch JSON records through the structured driver — but NOT the
 // manifest (an id-less `{schema_version}` object the driver can't merge by id; a
 // normal text merge with conflict markers is the right behavior for it).
@@ -58,9 +59,10 @@ export function installMergeDriver(root, invShell) {
     }
     // 2. Local git config — the driver definitions are per-clone (they reference
     //    this machine's node + cli path), so they are NOT committed; teammates
-    //    re-run init.
-    const driver = `${invShell} merge-driver "%O" "%A" "%B" "%P"`;
-    const groundingDriver = `${invShell} merge-driver-grounding "%O" "%A" "%B" "%P"`;
+    //    re-run init. Dev mode swaps `npx tsx` for Hunch's own loader (#492).
+    const shell = mergeDriverShell(invShell);
+    const driver = `${shell} merge-driver "%O" "%A" "%B" "%P"`;
+    const groundingDriver = `${shell} merge-driver-grounding "%O" "%A" "%B" "%P"`;
     const env = targetRepositoryEnv();
     try {
         execFileSync("git", ["config", "merge.hunch.name", "hunch structured JSON merge"], { cwd: root, env });

package/dist/integrations/optout.d.ts

@@ -0,0 +1,3 @@
+/** The opt-out marker, at the repository root. Commit it so every clone stays opted out. */
+export declare const OPT_OUT_FILE = ".hunch-removed";
+export declare function isOptedOut(root: string): boolean;

package/dist/integrations/optout.js

@@ -0,0 +1,17 @@
+/**
+ * The opt-out marker `hunch uninstall` leaves (#449), apart from uninstall.ts so the
+ * hook installers can honor it without an import cycle (uninstall.ts imports hooks.ts).
+ */
+import { lstatSync } from "node:fs";
+import { join } from "node:path";
+/** 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;
+    }
+}
+//# sourceMappingURL=optout.js.map

package/dist/integrations/providers.d.ts

@@ -73,8 +73,12 @@ export declare function writeCodexHooks(root: string, inv: Invocation): string;
 export declare function writeVscodeHooks(root: string, inv: Invocation): string;
 /** Windsurf's documented workspace hooks. It only supports deterministic
  * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
- * reserves the hook for strict edit protection and pipeline observation. */
-export declare function writeWindsurfHooks(root: string, inv: Invocation): string;
+ * reserves the hook for strict edit protection and pipeline observation.
+ * Devin Desktop (formerly Windsurf) reads .devin/hooks.json and ignores the
+ * legacy .windsurf/hooks.json whenever the former defines any hook, so Hunch
+ * merges into both (docs.devin.ai/desktop/cascade/hooks, #494). Both files are
+ * parsed before either is written: an unparseable one refuses the whole write. */
+export declare function writeWindsurfHooks(root: string, inv: Invocation): string[];
 /** Antigravity keeps hook groups at the top level (not under `hooks`). Hunch
  * owns only the `hunch` group and replaces its own old entries idempotently. */
 export declare function writeAntigravityHooks(root: string, inv: Invocation): string;

package/dist/integrations/providers.js

@@ -419,9 +419,26 @@ function publishedPinEvents(file) {
 }
 /** Windsurf's documented workspace hooks. It only supports deterministic
  * pre-hook blocking via exit code 2, so Hunch uses rules + MCP for context and
- * reserves the hook for strict edit protection and pipeline observation. */
+ * reserves the hook for strict edit protection and pipeline observation.
+ * Devin Desktop (formerly Windsurf) reads .devin/hooks.json and ignores the
+ * legacy .windsurf/hooks.json whenever the former defines any hook, so Hunch
+ * merges into both (docs.devin.ai/desktop/cascade/hooks, #494). Both files are
+ * parsed before either is written: an unparseable one refuses the whole write. */
 export function writeWindsurfHooks(root, inv) {
-    const file = join(root, ".windsurf", "hooks.json");
+    const files = [join(root, ".windsurf", "hooks.json"), join(root, ".devin", "hooks.json")];
+    // Same shape checks writeHookConfig applies at write time, so neither file is
+    // written when the other would refuse.
+    for (const file of files) {
+        const hooks = objectField(readJsonObj(file), "hooks", file);
+        for (const event of WINDSURF_EVENTS) {
+            if (hooks[event] !== undefined && !Array.isArray(hooks[event])) {
+                throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
+            }
+        }
+    }
+    return files.map((file) => writeWindsurfHookFile(file, inv));
+}
+function writeWindsurfHookFile(file, inv) {
     const published = hookCommand(publishedMcpInvocation(), "windsurf");
     let command = hookCommand(inv, "windsurf");
     // A source-checkout run (tsx / local dist) must never replace a tracked

package/dist/integrations/team.js

@@ -8,6 +8,7 @@
 import { existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, realpathSync, renameSync, rmSync } from "node:fs";
 import { basename, dirname, isAbsolute, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
+import { boundedSpawnSync } from "../core/boundedSpawn.js";
 import { writeFileAtomic } from "../core/io.js";
 import { machineFile } from "../core/machine.js";
 import { hunchTreeAttributesAreSafe, safeOverlayGitTreeListing, safeOverlayTree } from "../core/overlaySafety.js";
@@ -654,13 +655,14 @@ export function cloneValidatedTeamOverlay(sharedRepo, sharedRepoCwd, destination
         }
         const cloneEnv = boundedTeamGitEnv();
         stage = "clone";
-        const cloned = spawnSync("git", [
+        // Bounded so a timeout kills git's whole tree, not just the root (#498).
+        const cloned = boundedSpawnSync("git", [
             "-c", "protocol.ext.allow=never",
             "-c", `core.hooksPath=${emptyHooks}`,
             "clone", "--no-checkout", `--template=${emptyTemplate}`,
             "--", repo, stagedDest,
         ], {
-            stdio: "ignore",
+            stdout: "ignore",
             env: cloneEnv,
             timeout: timeoutMs,
         });

package/dist/integrations/uninstall.d.ts

@@ -1,6 +1,5 @@
-/** The opt-out marker, at the repository root. Commit it so every clone stays opted out. */
-export declare const OPT_OUT_FILE = ".hunch-removed";
-export declare function isOptedOut(root: string): boolean;
+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
@@ -8,7 +7,14 @@ export declare function isOptedOut(root: string): boolean;
  *  store is deliberately not a boundary: a partition store nested in an opted-out
  *  repository stays gated (fail closed). */
 export declare function optedOutAt(start: string): boolean;
-export declare function optOutMessage(): string;
+/** 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 declare function optOutMarkerAt(start: string, opts?: {
+    withinRepo?: boolean;
+}): string | null;
+/** The refusal, naming the marker of the repository actually checked (#488). */
+export declare function optOutMessage(marker?: string): string;
 export interface UninstallStep {
     /** Repo-relative (POSIX) where possible, else absolute. */
     path: string;

package/dist/integrations/uninstall.js

@@ -12,7 +12,7 @@
  *
  * `.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, dirname, join, relative, resolve } from "node:path";
 import { parse as parseToml } from "smol-toml";
@@ -26,16 +26,8 @@ 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
@@ -43,19 +35,30 @@ export function isOptedOut(root) {
  *  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 (isOptedOut(dir))
-            return true;
+        if (!found && isOptedOut(dir)) {
+            found = join(dir, OPT_OUT_FILE);
+            if (!opts.withinRepo)
+                return found;
+        }
         if (existsSync(join(dir, ".git")))
-            return false;
+            return found;
         const parent = dirname(dir);
         if (parent === dir)
-            return false;
+            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 [
@@ -310,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;
@@ -459,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

@@ -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";
@@ -1253,6 +1253,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.
@@ -1508,16 +1512,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
@@ -2066,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
@@ -2681,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) => {
@@ -2745,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 }) => {
@@ -2850,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)}` : ""}`);
@@ -2883,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
@@ -3479,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

@@ -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;

package/dist/store/hunchStore.js

@@ -1350,8 +1350,10 @@ export class HunchStore {
         const lookup = WHY_RECORD_ID.test(target) ? this.whyRecord(target, opts.canRead, opts.asOf) : undefined;
         if (lookup?.record)
             return { target, decisions: [], bugs: [], constraints: [], symbols: [], components: [], byId: lookup };
-        // A miss is reported only for a generated-shape id; anything else resolves as before.
-        const byId = lookup && WHY_GENERATED_ID.test(target) ? lookup : undefined;
+        // A miss is reported for a generated-shape id, or for any id on file that was not
+        // in force at `asOf` (issue #493); anything else resolves as before.
+        const byId = lookup && (WHY_GENERATED_ID.test(target) || (opts.asOf && this.whyRecord(target, opts.canRead).record))
+            ? lookup : undefined;
         const decisions = this.recs("decisions").filter(opts.canRead ?? (() => true));
         const bugs = this.recs("bugs").filter(opts.canRead ?? (() => true));
         const constraints = this.recs("constraints").filter(opts.canRead ?? (() => true));
@@ -1446,7 +1448,8 @@ export class HunchStore {
     }
     /** 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, maxDepth = 6) {
         return this.db.prepare(
         /* sql */ `
@@ -1455,7 +1458,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT up.node AS id, MIN(up.depth) AS depth,
              COALESCE(s.name || ' @ ' || s.file, c.name, up.node) AS via
@@ -1497,7 +1500,7 @@ export class HunchStore {
         UNION
         SELECT e."from", up.depth + 1
         FROM edges e JOIN up ON e."to" = up.node
-        WHERE e.type IN ('calls','depends_on','imports','contains','implements') AND up.depth < ?
+        WHERE e.type IN ('calls','depends_on','imports','contains','implements','references') AND up.depth < ?
       )
       SELECT s.file AS file, s.name AS via, MIN(up.depth) AS depth
       FROM up JOIN symbols s ON s.id = up.node

package/dist/store/jsonStore.d.ts

@@ -126,12 +126,22 @@ export declare class JsonStore {
      *  overlay. Returns the number of files removed. Invalidates the memoized load. */
     dropAll(kind: EntityKind): number;
     /** Persist a schema migration: rewrite every LOADABLE record in its current shape.
-     *  A record that still fails validation after migration is kept untouched (never
-     *  deleted) and counted as `skipped`, so migration can't lose data. The caller
-     *  bumps the manifest afterward. */
+     *  A record that still fails validation after migration (or whose migration
+     *  throws) is kept in its ORIGINAL shape (never deleted, never half-migrated) and
+     *  counted as `skipped`, so migration can't lose data. The caller stamps the
+     *  manifest at the returned `version`: SCHEMA_VERSION only when nothing was
+     *  skipped, else the FROM version, so a manual fix plus a rerun re-applies the
+     *  (idempotent) migrations to the skipped records instead of skipping them.
+     *  A bad record of a kind NO pending migration touches can't be fixed by a
+     *  rerun, so it is counted as `invalid` instead and doesn't hold the version. */
     persistMigration(): {
         migrated: number;
         skipped: number;
+        invalid: number;
+        version: number;
     };
+    /** Migrate + validate one raw record for persistMigration; a throwing migration
+     *  step counts as a failure, so the record stays in its original shape. */
+    private tryMigrate;
 }
 export {};