@davesheffer/hunch 1.32.4 → 1.32.5

package/dist/constitution/behaviorEvaluator.js

@@ -130,7 +130,7 @@ export function evaluateExecutableBehaviorPolicy(root, policy, opts = {}) {
         // longer match the commit's dependency inputs. Name each with its recovery;
         // both stay `error`, never a coerced pass.
         if (!existsSync(join(root, ".hunch-cache", "behavior-deps"))) {
-            return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-cache-absent" }, "error", "no dependency snapshot cache exists on this machine (.hunch-cache/behavior-deps); executable behavior is unevaluated here, not failed — provision the policy's snapshots (hunch constitution bootstrap --behavior-deps <candidate>) or evaluate where they were built");
+            return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-cache-absent" }, "error", "no dependency snapshot cache exists on this machine (.hunch-cache/behavior-deps); executable behavior is unevaluated here, not failed — provision the policy's snapshots (hunch constitution g2 --behavior-deps <candidate> --behavior-review-hash <hash>) or evaluate where they were built");
         }
         return evaluation(policy, commit, { ...baseExecution, commit, error_code: "dependency-snapshot-unavailable" }, "error", `no unique exact dependency snapshot matches this commit's package.json/package-lock.json among the policy's pinned ids (${assertion.dependency_snapshot_ids.join(", ")}); dependency inputs changed since compilation — re-plan and re-prove the policy (rb_g2_stale_policy_01)`);
     }

package/dist/constitution/repository.d.ts

@@ -9,6 +9,7 @@ export declare class PolicyRepository {
     private readonly privateHome?;
     constructor(root: string, store: HunchStore);
     private dir;
+    private ensureDir;
     private policiesIn;
     private proofsIn;
     private evidenceIn;

package/dist/constitution/repository.js

@@ -1,6 +1,7 @@
-import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync } from "node:fs";
-import { join } from "node:path";
+import { existsSync, mkdirSync, readdirSync, rmSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
 import { writeFileAtomic, writeFileAtomicIfAbsent } from "../core/io.js";
+import { readStoreArtifact, storeArtifactPath } from "../core/storeArtifact.js";
 import { shortHash } from "../core/ids.js";
 import { canonicalHash, policySemanticHash, proofPlanContentHash } from "./canonical.js";
 import { proofCorpusContentHash } from "./corpus.js";
@@ -9,13 +10,40 @@ import { assertCompositionBinding, compositionDescendants, policyProofHash } fro
 import { currentShadowDispositions, policyEvaluationContentHash, shadowDispositionContentHash, shadowDispositionJudgmentHash, shadowEvaluationContentHash, shadowEvaluationIdentityHash, } from "./shadow.js";
 import { HistoryDispositionSchema, ProofCorpusSchema, PolicyProofSchema, ProofPlanSchema, PolicySpecSchema, ShadowRecordSchema, EvidenceEventSchema, } from "./schema.js";
 const encode = (value) => JSON.stringify(value, null, 2) + "\n";
+const MAX_POLICY_ARTIFACT_BYTES = 8 * 1024 * 1024;
+function assertPolicyArtifactSize(data) {
+    if (Buffer.byteLength(data, "utf8") > MAX_POLICY_ARTIFACT_BYTES) {
+        throw new Error(`policy artifact exceeds the ${MAX_POLICY_ARTIFACT_BYTES}-byte limit`);
+    }
+}
+function artifactFile(dir, name) {
+    return storeArtifactPath(dir, name);
+}
+function writeArtifact(dir, name, data) {
+    assertPolicyArtifactSize(data);
+    const file = artifactFile(dir, name);
+    writeFileAtomic(file, data);
+    artifactFile(dir, name);
+}
+function writeArtifactIfAbsent(dir, name, data) {
+    assertPolicyArtifactSize(data);
+    const file = artifactFile(dir, name);
+    const created = writeFileAtomicIfAbsent(file, data);
+    if (created)
+        artifactFile(dir, name);
+    return created;
+}
 function loadRecords(dir, parse, label) {
-    if (!existsSync(dir))
+    const safeDir = storeArtifactPath(dirname(dir), basename(dir));
+    if (!existsSync(safeDir))
         return [];
     const out = [];
-    for (const name of readdirSync(dir).filter((n) => n.endsWith(".json")).sort()) {
+    for (const name of readdirSync(safeDir).filter((n) => n.endsWith(".json")).sort()) {
         try {
-            out.push(parse(JSON.parse(readFileSync(join(dir, name), "utf8"))));
+            const raw = readStoreArtifact(safeDir, [name], MAX_POLICY_ARTIFACT_BYTES);
+            if (raw === null)
+                throw new Error("record disappeared while it was being read");
+            out.push(parse(JSON.parse(raw)));
         }
         catch (e) {
             // A policy store can control CI. Skipping a corrupt record would turn an
@@ -41,7 +69,12 @@ export class PolicyRepository {
         const base = home === "private" ? this.privateHome : this.publicHome;
         if (!base)
             throw new Error("No private Hunch overlay is configured; refusing to write a private policy.");
-        return join(base, kind);
+        return storeArtifactPath(base, kind);
+    }
+    ensureDir(home, kind) {
+        const dir = this.dir(home, kind);
+        mkdirSync(dir, { recursive: true });
+        return storeArtifactPath(dirname(dir), basename(dir));
     }
     policiesIn(home) {
         if (home === "private" && !this.privateHome)
@@ -200,9 +233,9 @@ export class PolicyRepository {
         return dispositions.sort((left, right) => left.id.localeCompare(right.id));
     }
     homeOfPolicy(id) {
-        if (this.privateHome && existsSync(join(this.dir("private", "policies"), `${id}.json`)))
+        if (this.privateHome && existsSync(artifactFile(this.dir("private", "policies"), `${id}.json`)))
             return "private";
-        if (existsSync(join(this.dir("public", "policies"), `${id}.json`)))
+        if (existsSync(artifactFile(this.dir("public", "policies"), `${id}.json`)))
             return "public";
         return undefined;
     }
@@ -213,9 +246,8 @@ export class PolicyRepository {
             throw new Error(`refusing to write ${parsed.data_class} policy ${parsed.id} into its existing public home; migrate it to the private overlay first`);
         }
         const home = opts.private ? "private" : existing ?? (parsed.data_class !== "public" || this.store.unified ? "private" : "public");
-        const dir = this.dir(home, "policies");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "policies");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     /** Publish a new policy lifecycle record without overwriting a concurrent
@@ -238,9 +270,8 @@ export class PolicyRepository {
             return { policy: existing, created: false };
         if (otherHome)
             throw new Error(`policy ${parsed.id} already exists in the ${home === "public" ? "private" : "public"} home`);
-        const dir = this.dir(home, "policies");
-        mkdirSync(dir, { recursive: true });
-        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed))) {
+        const dir = this.ensureDir(home, "policies");
+        if (writeArtifactIfAbsent(dir, `${parsed.id}.json`, encode(parsed))) {
             const racedOtherHome = this.getPolicy(parsed.id, home === "public" ? { privateOnly: true } : { publicOnly: true });
             if (racedOtherHome)
                 throw new Error(`policy ${parsed.id} was published concurrently in both public and private homes`);
@@ -277,9 +308,8 @@ export class PolicyRepository {
                 assertCompositionBinding(policy, composition, plan.composition);
             }
         }
-        const dir = this.dir(home, "proofs");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "proofs");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     /** Publish an immutable proof without replacing a concurrent writer. */
@@ -315,9 +345,8 @@ export class PolicyRepository {
                 throw new Error(`proof ${parsed.id} already exists with different immutable content`);
             return { proof: existing, created: false };
         }
-        const dir = this.dir(home, "proofs");
-        mkdirSync(dir, { recursive: true });
-        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed)))
+        const dir = this.ensureDir(home, "proofs");
+        if (writeArtifactIfAbsent(dir, `${parsed.id}.json`, encode(parsed)))
             return { proof: parsed, created: true };
         const winner = this.getProof(parsed.id, homeOpts);
         if (!winner)
@@ -346,9 +375,8 @@ export class PolicyRepository {
             if (parsed.policy_candidate_hash !== policyProofHash(policy, composition))
                 throw new Error(`composite plan ${parsed.id} policy hash mismatch`);
         }
-        const dir = this.dir(home, "plans");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "plans");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     /** Publish an immutable proof plan without replacing a concurrent writer. */
@@ -378,9 +406,8 @@ export class PolicyRepository {
                 throw new Error(`proof plan ${parsed.id} already exists with different immutable content`);
             return { plan: existing, created: false };
         }
-        const dir = this.dir(home, "plans");
-        mkdirSync(dir, { recursive: true });
-        if (writeFileAtomicIfAbsent(join(dir, `${parsed.id}.json`), encode(parsed)))
+        const dir = this.ensureDir(home, "plans");
+        if (writeArtifactIfAbsent(dir, `${parsed.id}.json`, encode(parsed)))
             return { plan: parsed, created: true };
         const winner = this.getPlan(parsed.id, homeOpts);
         if (!winner)
@@ -400,9 +427,8 @@ export class PolicyRepository {
         if (!policy || parsed.data_class !== policy.data_class || parsed.policy_hash !== policySemanticHash(policy)) {
             throw new Error(`corpus ${parsed.id} does not match policy ${policyId} semantics/data class`);
         }
-        const dir = this.dir(home, "corpora");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${policyId}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "corpora");
+        writeArtifact(dir, `${policyId}.json`, encode(parsed));
         return parsed;
     }
     putEvidence(event, opts = {}) {
@@ -413,9 +439,8 @@ export class PolicyRepository {
         if (home === "public" && parsed.data_class !== "public") {
             throw new Error(`refusing to write ${parsed.data_class} evidence ${parsed.id} into the public home`);
         }
-        const dir = this.dir(home, "evidence");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "evidence");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     putDisposition(disposition, policyId) {
@@ -451,9 +476,8 @@ export class PolicyRepository {
         if (!current && parsed.supersedes)
             throw new Error(`history disposition ${parsed.id} supersedes no current disposition for this proof hit`);
         currentHistoryDispositions([...records, parsed]);
-        const dir = this.dir(home, "dispositions");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "dispositions");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     putShadowEvaluation(evaluation, policyId) {
@@ -483,9 +507,8 @@ export class PolicyRepository {
         const existing = this.listShadowEvaluations(homeOpts).find((record) => shadowEvaluationIdentityHash(record) === shadowEvaluationIdentityHash(parsed));
         if (existing)
             return existing;
-        const dir = this.dir(home, "shadow");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "shadow");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
     putShadowDisposition(disposition, policyId) {
@@ -521,9 +544,8 @@ export class PolicyRepository {
         if (!current && parsed.supersedes)
             throw new Error(`shadow disposition ${parsed.id} supersedes no current disposition for this evaluation`);
         currentShadowDispositions([...records, parsed]);
-        const dir = this.dir(home, "shadow");
-        mkdirSync(dir, { recursive: true });
-        writeFileAtomic(join(dir, `${parsed.id}.json`), encode(parsed));
+        const dir = this.ensureDir(home, "shadow");
+        writeArtifact(dir, `${parsed.id}.json`, encode(parsed));
         return parsed;
     }
 }
@@ -653,14 +675,18 @@ export function movePolicyArtifactsToPrivate(publicHunchDir, privateHunchDir) {
         }
     }
     for (const { kind, from, to, pub, priv, keyFor } of staged) {
+        storeArtifactPath(dirname(from), basename(from));
         if (!pub.length && !existsSync(from))
             continue;
+        storeArtifactPath(dirname(to), basename(to));
         mkdirSync(to, { recursive: true });
+        storeArtifactPath(dirname(to), basename(to));
         for (const rec of pub) {
             const key = keyFor(rec);
             if (!priv.has(key))
-                writeFileAtomic(join(to, `${key}.json`), encode(rec));
+                writeArtifact(to, `${key}.json`, encode(rec));
         }
+        storeArtifactPath(dirname(from), basename(from));
         rmSync(from, { recursive: true, force: true });
         counts[kind] = pub.length;
     }

package/dist/core/agenthook.js

@@ -60,11 +60,15 @@ function applyPatchInput(raw) {
     const file = PATCH_FILE.exec(patch)?.[1];
     return file ? { file_path: file, content: patch } : undefined;
 }
-function normalizeToolInput(value) {
+function normalizeToolInput(value, allowPatch = false) {
     const raw = obj(value);
     if (!raw)
         return undefined;
-    const patched = applyPatchInput(raw);
+    // Only Codex's apply_patch tool carries patch text in a generic `input`,
+    // `patch`, or `content` field. A normal Write can contain documentation or
+    // examples with these markers; interpreting those as a patch would retarget
+    // policy to the first file named in the prose.
+    const patched = allowPatch ? applyPatchInput(raw) : undefined;
     if (patched)
         return patched;
     const replacementChunks = Array.isArray(raw.ReplacementChunks) ? raw.ReplacementChunks : raw.replacementChunks;
@@ -205,7 +209,8 @@ export function normalizeHookEvent(raw, provider) {
     const event = eventName(input.hook_event_name ?? input.hookEventName ?? input.event, provider);
     if (!event)
         return null;
-    const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput);
+    const rawToolName = stringAt(input, "tool_name", "toolName");
+    const toolInput = normalizeToolInput(input.tool_input ?? input.toolInput, provider === "codex" && /^(?:apply_patch|patch)$/i.test(rawToolName ?? ""));
     const toolOutcome = normalizeToolOutcome(input, event);
     return {
         hook_event_name: event,
@@ -214,7 +219,7 @@ export function normalizeHookEvent(raw, provider) {
         // says `prompt_id`; both are native per-prompt identities, never synthesized.
         ...(provider === "codex" && input.prompt_id === undefined && input.turn_id !== undefined ? { prompt_id: typeof input.turn_id === "string" ? input.turn_id : "" } : {}),
         ...(provider === "claude" || provider === "codex" ? Object.fromEntries(["prompt_id", "cwd", "agent_id"].filter(key => input[key] !== undefined).map(key => [key, typeof input[key] === "string" ? input[key] : ""])) : {}),
-        tool_name: hunchToolName(stringAt(input, "tool_name", "toolName"), toolInput ?? {}),
+        tool_name: hunchToolName(rawToolName, toolInput ?? {}),
         tool_input: toolInput,
         ...(toolOutcome ? { tool_outcome: toolOutcome } : {}),
         prompt: stringAt(input, "prompt", "user_prompt", "userPrompt"),

package/dist/core/checkreport.js

@@ -200,7 +200,7 @@ export function renderMarkdown(r) {
             r.regBlocking ? `${r.regBlocking} blocking-linked regression(s)` : "",
             r.vetoBlocking ? `${r.vetoBlocking} reversed-decision veto(es)` : "",
         ].filter(Boolean).join(" + ");
-        out.push(`❌ **This PR breaks ${reasons}.** Resolve or supersede the decision before merge.`);
+        out.push(`❌ **Merge requires review: ${reasons}.** Check the cited evidence and verify that the recorded requirements still hold before merging.`);
     }
     else if (r.strict) {
         out.push(`ℹ️ Nothing here is a direct, high-confidence, non-stale blocking invariant — **not blocking** this PR.`);

package/dist/core/events.js

@@ -16,8 +16,9 @@
  *  assert — those are conformance-only predicates checked by a different gate
  *  (`hunch conform`), not the edit hook. This schema records only what each gate
  *  actually knows; it never fabricates the conformance shape for a plain block. */
-import { appendFileSync, readFileSync } from "node:fs";
+import { appendFileSync, closeSync, constants, fstatSync, lstatSync, openSync } from "node:fs";
 import { join } from "node:path";
+import { readStoreArtifact, storeArtifactPath } from "./storeArtifact.js";
 export function eventsLogPath(paths) {
     return join(paths.hunch, "events.log");
 }
@@ -25,19 +26,34 @@ export function eventsLogPath(paths) {
  *  call site is the edit hook, which MUST NEVER break an agent on failure
  *  (con_03a0b94b2e). A dropped catch-log line is an acceptable loss. */
 export function appendEvent(paths, event) {
+    let fd;
     try {
-        appendFileSync(eventsLogPath(paths), `${JSON.stringify(event)}\n`);
+        const file = storeArtifactPath(paths.hunch, "events.log");
+        fd = openSync(file, constants.O_WRONLY | constants.O_APPEND | constants.O_CREAT | constants.O_NOFOLLOW);
+        const opened = fstatSync(fd);
+        const current = lstatSync(storeArtifactPath(paths.hunch, "events.log"));
+        if (!opened.isFile() || opened.nlink !== 1 || opened.dev !== current.dev || opened.ino !== current.ino)
+            return;
+        appendFileSync(fd, `${JSON.stringify(event)}\n`);
     }
     catch {
         /* best effort — a lost audit line must never surface to the agent */
     }
+    finally {
+        if (fd !== undefined) {
+            try {
+                closeSync(fd);
+            }
+            catch { /* logging remains best effort on close failure too */ }
+        }
+    }
 }
 /** Read + parse the catch-log. Malformed lines are skipped, not fatal (the log is
  *  derived; one bad line never poisons the aggregation). Missing log → []. */
 export function readEvents(paths) {
     let raw;
     try {
-        raw = readFileSync(eventsLogPath(paths), "utf8");
+        raw = readStoreArtifact(paths.hunch, ["events.log"]) ?? "";
     }
     catch {
         return []; // no catches recorded yet

package/dist/core/io.js

@@ -1,5 +1,5 @@
 /** Durable file writes for the Hunch. */
-import { closeSync, fsyncSync, linkSync, openSync, renameSync, rmSync, writeSync } from "node:fs";
+import { closeSync, fchmodSync, fsyncSync, linkSync, lstatSync, openSync, renameSync, rmSync, writeFileSync } from "node:fs";
 import { dirname } from "node:path";
 let counter = 0;
 const renameRetryDelaysMs = [10, 20, 40, 80];
@@ -24,20 +24,17 @@ const renameRetryWaiter = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_
  */
 export function writeFileAtomic(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    let mode;
     try {
-        const fd = openSync(tmp, "w");
-        try {
-            writeSync(fd, data);
-            fsyncSync(fd); // data blocks reach disk before the rename's metadata can
-        }
-        finally {
-            closeSync(fd);
-        }
+        const existing = lstatSync(file);
+        if (existing.isFile())
+            mode = existing.mode & 0o777;
     }
-    catch (e) {
-        cleanupTmp(tmp);
-        throw e;
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
     }
+    writeFileAtomicTmp(tmp, data, mode);
     try {
         renameWithContentionRetry(tmp, file);
     }
@@ -85,8 +82,10 @@ function isRenameContention(error) {
  * semantics, so concurrent lifecycle writers can never be overwritten. */
 export function writeFileAtomicIfAbsent(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    // An occupied temp path is an error, not evidence that the target exists.
+    // Only enter the publication/cleanup block once we own the temporary file.
+    writeFileAtomicTmp(tmp, data);
     try {
-        writeFileAtomicTmp(tmp, data);
         linkSync(tmp, file);
         return true;
     }
@@ -104,14 +103,26 @@ export function writeFileAtomicIfAbsent(file, data) {
     }
 }
 /** Write + fsync a fresh temp file (shared by both atomic writers). */
-function writeFileAtomicTmp(tmp, data) {
-    const fd = openSync(tmp, "w");
+function writeFileAtomicTmp(tmp, data, mode) {
+    // Exclusive creation rejects stale files and links without truncating their
+    // contents. If open fails, the path belongs to somebody else: never unlink it.
+    const fd = openSync(tmp, "wx", mode ?? 0o666);
     try {
-        writeSync(fd, data);
-        fsyncSync(fd);
+        try {
+            writeFileSync(fd, data);
+            // The replacement inode must retain an existing file's permissions,
+            // including private config files that contain credentials.
+            if (mode !== undefined)
+                fchmodSync(fd, mode);
+            fsyncSync(fd);
+        }
+        finally {
+            closeSync(fd);
+        }
     }
-    finally {
-        closeSync(fd);
+    catch (error) {
+        cleanupTmp(tmp);
+        throw error;
     }
 }
 /** Remove a temp file, riding out a transient external hold (AV/indexer) with one

package/dist/core/jsonc.js

@@ -24,7 +24,7 @@ export function parseJsonc(raw) {
             continue;
         }
         if (char === "/" && next === "/") {
-            while (index < raw.length && raw[index] !== "\n")
+            while (index < raw.length && raw[index] !== "\n" && raw[index] !== "\r")
                 index += 1;
             withoutComments += "\n";
             continue;
@@ -33,7 +33,12 @@ export function parseJsonc(raw) {
             index += 2;
             while (index < raw.length && !(raw[index] === "*" && raw[index + 1] === "/"))
                 index += 1;
+            if (index >= raw.length)
+                throw new SyntaxError("unterminated JSONC block comment");
             index += 1;
+            // A comment separates tokens. Removing it outright would silently turn
+            // invalid input such as 1/* comment */2 into the valid number 12.
+            withoutComments += " ";
             continue;
         }
         withoutComments += char;
@@ -62,8 +67,13 @@ export function parseJsonc(raw) {
             let cursor = index + 1;
             while (cursor < withoutComments.length && /\s/.test(withoutComments[cursor]))
                 cursor += 1;
-            if (withoutComments[cursor] === "}" || withoutComments[cursor] === "]")
-                continue;
+            if (withoutComments[cursor] === "}" || withoutComments[cursor] === "]") {
+                const previous = normalized.trimEnd().at(-1);
+                // A trailing comma must follow a value, never an empty collection or
+                // another comma. Keep malformed input intact for JSON.parse to reject.
+                if (previous && !"[{,:".includes(previous))
+                    continue;
+            }
         }
         normalized += char;
     }

package/dist/core/storeArtifact.d.ts

@@ -0,0 +1,7 @@
+/** Containment for store artifacts outside JsonStore's entity registry (ledgers,
+ * policy proofs, and local audit logs). The explicitly selected store's parent
+ * may have a platform alias, but no component inside that store may be a link. */
+export declare function storeArtifactPath(hunchDir: string, ...parts: string[]): string;
+/** A missing artifact is distinct from an unsafe/unreadable artifact. Reuse the
+ * scanner's bounded descriptor read; policy and ledger corruption must fail visibly. */
+export declare function readStoreArtifact(hunchDir: string, parts: string[], maxBytes?: number): string | null;

package/dist/core/storeArtifact.js

@@ -0,0 +1,62 @@
+import { lstatSync, realpathSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
+import { createRepoFileReader } from "./safeRepoFile.js";
+/** Containment for store artifacts outside JsonStore's entity registry (ledgers,
+ * policy proofs, and local audit logs). The explicitly selected store's parent
+ * may have a platform alias, but no component inside that store may be a link. */
+export function storeArtifactPath(hunchDir, ...parts) {
+    let path = resolve(hunchDir);
+    let parent;
+    try {
+        parent = realpathSync(dirname(path));
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+        parent = dirname(path);
+    }
+    let expected = join(parent, basename(path));
+    const check = (directory) => {
+        try {
+            const stat = lstatSync(path);
+            if (stat.isSymbolicLink() || (directory ? !stat.isDirectory() : !stat.isFile() && !stat.isDirectory())
+                || (stat.isFile() && stat.nlink !== 1) || realpathSync(path) !== expected) {
+                throw new Error(`unsafe store artifact path ${path}: symlinks, hard links and special files are refused`);
+            }
+        }
+        catch (error) {
+            if (error.code !== "ENOENT")
+                throw error;
+        }
+    };
+    check(true);
+    for (let index = 0; index < parts.length; index++) {
+        const part = parts[index];
+        if (!/^[A-Za-z0-9._-]+$/.test(part) || part === "." || part === "..")
+            throw new Error("unsafe store artifact path component");
+        path = join(path, part);
+        expected = join(expected, part);
+        check(index < parts.length - 1);
+    }
+    return path;
+}
+/** A missing artifact is distinct from an unsafe/unreadable artifact. Reuse the
+ * scanner's bounded descriptor read; policy and ledger corruption must fail visibly. */
+export function readStoreArtifact(hunchDir, parts, maxBytes = 256 * 1024 * 1024) {
+    const file = storeArtifactPath(hunchDir, ...parts);
+    try {
+        if (!lstatSync(file).isFile())
+            throw new Error(`unsafe store artifact path ${file}: expected an ordinary file`);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    const text = createRepoFileReader(dirname(resolve(hunchDir)), { maxBytes })(file);
+    if (text === null)
+        throw new Error(`unsafe or unreadable store artifact ${file}`);
+    storeArtifactPath(hunchDir, ...parts);
+    return text;
+}
+//# sourceMappingURL=storeArtifact.js.map

package/dist/integrations/claudeConfig.js

@@ -146,12 +146,29 @@ export function healClaudeConfigCaseSplit(opts = {}) {
         if (keys.length < 2)
             continue; // no casing split for this directory
         keys.sort(); // deterministic first-wins union
-        const blocks = keys.map((k) => (isPlainObject(projects[k]) ? projects[k] : {}));
+        // A root object can still contain malformed project blocks. Do not replace a
+        // user's scalar/array block, or normalize malformed nested MCP/list fields,
+        // merely because another drive-letter casing is valid.
+        for (const key of keys) {
+            const block = projects[key];
+            if (!isPlainObject(block)) {
+                throw new Error(`refusing to modify ${file}: project ${key} is not an object; fix it, then re-run.`);
+            }
+            const mcp = block.mcpServers;
+            if (mcp !== undefined && !isPlainObject(mcp)) {
+                throw new Error(`refusing to modify ${file}: project ${key}.mcpServers must be an object; fix it, then re-run.`);
+            }
+            for (const listKey of ["enabledMcpjsonServers", "disabledMcpjsonServers"]) {
+                const list = block[listKey];
+                if (list !== undefined && (!Array.isArray(list) || !list.every((value) => typeof value === "string"))) {
+                    throw new Error(`refusing to modify ${file}: project ${key}.${listKey} must be a string array; fix it, then re-run.`);
+                }
+            }
+        }
+        const blocks = keys.map((k) => projects[k]);
         const u = unionConfig(blocks);
         let groupChanged = false;
         for (const k of keys) {
-            if (!isPlainObject(projects[k]))
-                projects[k] = {};
             if (applyUnion(projects[k], u))
                 groupChanged = true;
         }

package/dist/integrations/health.js

@@ -52,7 +52,7 @@ function hookCommands(value) {
     if (obj.enabled === false || (obj.type !== undefined && obj.type !== "command"))
         return [];
     const command = typeof obj.command === "string" ? obj.command : "";
-    const own = /(?:@davesheffer\/hunch|[\\/]index\.(?:js|ts))/.test(command)
+    const own = /(?:@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts))/.test(command)
         && /\s"?hook"?(?:\s+"?--provider"?\s+"?[a-z]+"?)?\s*$/.test(command);
     return [...(own ? [command] : []), ...(obj.hooks ? hookCommands(obj.hooks) : [])];
 }

package/dist/integrations/providers.js

@@ -24,6 +24,7 @@ import { join, dirname } from "node:path";
 import { renderHunchSection, stripManagedSection, upsertSection, updateClaudeMd } from "./claudemd.js";
 import { headFileContent, isGitCleanPath } from "../extractors/git.js";
 import { parseJsonc } from "../core/jsonc.js";
+import { parse as parseToml } from "smol-toml";
 /** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
  *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
  *  user's other MCP servers. */
@@ -65,6 +66,18 @@ function writeJson(file, obj) {
     writeFileAtomic(file, JSON.stringify(obj, null, 2) + "\n");
     return file;
 }
+/** A present managed container must have the object shape its host expects.
+ * Arrays and primitives are valid JSON/TOML values, but assigning properties to
+ * them either throws or silently disappears during JSON serialization. Refuse
+ * those shapes instead of claiming an install succeeded. */
+function objectField(json, key, file) {
+    const value = json[key];
+    if (value === undefined)
+        return {};
+    if (value && typeof value === "object" && !Array.isArray(value))
+        return value;
+    throw new Error(`refusing to edit ${file}: ${key} must be a JSON object when present; fix it, then re-run.`);
+}
 /** Quote one argv token only when it needs quoting. These commands are run by
  * whatever shell the host assistant uses, which on Windows is PowerShell — and
  * PowerShell parses a QUOTED first token as a string expression, not a command,
@@ -103,7 +116,10 @@ function isHunchProviderHook(entry) {
     // the bare tail must still carry --provider to match; only the LEGACY
     // fully-quoted form (written before this quoting fix, and by hunch versions
     // that predate --provider) may omit it, and its quotes keep it unambiguous.
-    const launcher = /@davesheffer\/hunch|[\\/]index\.(?:js|ts)(?=["\s]|$)/.test(command);
+    // Source-checkout invocations generated by resolveInvocation point at the
+    // CLI entry specifically. A generic `other-tool/index.js hook` is foreign
+    // even when it happens to use Hunch's old command tail.
+    const launcher = /@davesheffer\/hunch|(?:dist|src)[\\/]+cli[\\/]+index\.(?:js|ts)(?=["\s]|$)/.test(command);
     const legacyTail = /\s"hook"(?:\s+"--provider"\s+"[a-z]+")?\s*$/.test(command);
     const tail = /\s"?hook"?\s+"?--provider"?\s+"?[a-z]+"?\s*$/.test(command);
     return launcher && (legacyTail || tail);
@@ -112,11 +128,13 @@ function isHunchProviderHook(entry) {
  * We replace only old Hunch commands and leave every foreign hook in place. */
 function writeHookConfig(file, entries) {
     const json = readJsonObj(file);
-    const hooks = json.hooks && typeof json.hooks === "object" && !Array.isArray(json.hooks)
-        ? json.hooks
-        : {};
+    const hooks = objectField(json, "hooks", file);
     for (const [event, next] of Object.entries(entries)) {
-        const old = Array.isArray(hooks[event]) ? hooks[event] : [];
+        const existing = hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
+        }
+        const old = (existing ?? []);
         hooks[event] = [...old.filter((entry) => !isHunchProviderHook(entry)), ...next];
     }
     json.hooks = hooks;
@@ -126,7 +144,7 @@ function writeHookConfig(file, entries) {
 export function writeCursorMcp(root, inv) {
     const file = join(root, ".cursor", "mcp.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -135,7 +153,7 @@ export function writeCursorMcp(root, inv) {
 export function writeVscodeMcp(root, inv) {
     const file = join(root, ".vscode", "mcp.json");
     const json = readJsonObj(file);
-    json.servers = json.servers ?? {};
+    json.servers = objectField(json, "servers", file);
     json.servers.hunch = { type: "stdio", command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -166,7 +184,7 @@ export function writeAntigravityMcp(inv, home = homedir()) {
     if (!file)
         return null;
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -176,7 +194,7 @@ export function writeAntigravityMcp(inv, home = homedir()) {
 export function writeAntigravityWorkspaceMcp(root, inv) {
     const file = join(root, ".agents", "mcp_config.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -213,9 +231,30 @@ export function writeCodexConfig(root, inv) {
     if (/^\s*\[mcp_servers\.hunch\]/m.test(base)) {
         throw new Error(`refusing to edit ${file}: it already defines [mcp_servers.hunch] outside Hunch's managed block. Remove it, then re-run.`);
     }
+    // Validate the complete original document before stripping any managed block.
+    // Even Hunch-owned malformed content must be preserved until the user reviews
+    // it; otherwise a repair can silently erase an unparseable configuration.
+    if (content.trim()) {
+        try {
+            parseToml(content);
+        }
+        catch (e) {
+            throw new Error(`refusing to overwrite ${file}: could not parse TOML (${e.message}). Fix it, then re-run.`);
+        }
+    }
     base = base.trimEnd();
+    const next = base ? `${base}\n\n${block}\n` : `${block}\n`;
+    // A syntactically valid parent value can still make the appended table
+    // illegal (`mcp_servers = 42` followed by `[mcp_servers.hunch]`). Validate
+    // the exact candidate before touching the user's file.
+    try {
+        parseToml(next);
+    }
+    catch (e) {
+        throw new Error(`refusing to overwrite ${file}: resulting TOML is invalid (${e.message}). Fix it, then re-run.`);
+    }
     mkdirSync(dirname(file), { recursive: true });
-    writeFileAtomic(file, base ? `${base}\n\n${block}\n` : `${block}\n`);
+    writeFileAtomic(file, next);
     return file;
 }
 /** AGENTS.md — the cross-tool ambient-instruction standard (Codex and a growing
@@ -242,7 +281,7 @@ export function writeCursorRule(root, store) {
 export function writeWindsurfMcp(root, inv) {
     const file = join(root, ".windsurf", "mcp_config.json");
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -258,7 +297,7 @@ export function writeWindsurfGlobalMcp(inv, home = homedir()) {
     if (!file)
         return null;
     const json = readJsonObj(file);
-    json.mcpServers = json.mcpServers ?? {};
+    json.mcpServers = objectField(json, "mcpServers", file);
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     return writeJson(file, json);
 }
@@ -347,9 +386,13 @@ function antigravityHandler(command) {
 export function writeAntigravityHooks(root, inv) {
     const file = join(root, ".agents", "hooks.json");
     const json = readJsonObj(file);
-    const group = json.hunch && typeof json.hunch === "object" && !Array.isArray(json.hunch)
-        ? json.hunch
-        : {};
+    const group = objectField(json, "hunch", file);
+    for (const event of ["PreInvocation", "PreToolUse", "Stop"]) {
+        const existing = group[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hunch.${event} must be an array when present; fix it, then re-run.`);
+        }
+    }
     const command = hookCommand(inv, "antigravity");
     const keep = (event) => Array.isArray(group[event])
         ? group[event].filter((entry) => {

package/dist/integrations/scaffold.js

@@ -27,7 +27,11 @@ export function writeMcpJson(root, inv) {
             }
         }
     }
-    json.mcpServers = json.mcpServers ?? {};
+    const servers = json.mcpServers;
+    if (servers !== undefined && (!servers || typeof servers !== "object" || Array.isArray(servers))) {
+        throw new Error(`refusing to edit ${file}: mcpServers must be a JSON object when present; fix it, then re-run.`);
+    }
+    json.mcpServers = servers ?? {};
     json.mcpServers.hunch = { command: inv.command, args: [...inv.args, "mcp"] };
     // Atomic: .mcp.json holds the user's other servers — a torn write would leave
     // it unparseable, which this writer then refuses to touch (issue #43).
@@ -114,7 +118,7 @@ function isHunchHook(entry) {
         if (typeof h.command !== "string")
             return false;
         const command = h.command;
-        const nativeOrSource = /[\\/]index\.(js|ts)"?\s+hook\s*$/.test(command);
+        const nativeOrSource = /(?:dist|src)[\\/]+cli[\\/]+index\.(js|ts)"?\s+hook\s*$/.test(command);
         const publishedNpx = /^\s*"?npx(?:\.cmd)?"?\s+/i.test(command)
             && /--package=(?:hunch-exact@npm:)?@davesheffer\/hunch(?:@[^"\s]+)?/.test(command)
             && /\s"?hunch"?\s+"?hook"?\s*$/.test(command);
@@ -151,7 +155,17 @@ export function installClaudeHooks(root, hookCmd) {
             }
         }
     }
-    json.hooks = json.hooks ?? {};
+    const hooks = json.hooks;
+    if (hooks !== undefined && (!hooks || typeof hooks !== "object" || Array.isArray(hooks))) {
+        throw new Error(`refusing to edit ${file}: hooks must be a JSON object when present; fix it, then re-run.`);
+    }
+    json.hooks = hooks ?? {};
+    for (const event of ["PreToolUse", "UserPromptSubmit", "SessionStart", "SubagentStart", "PreCompact", "PostToolUse", "PostToolUseFailure", "Stop"]) {
+        const existing = json.hooks[event];
+        if (existing !== undefined && !Array.isArray(existing)) {
+            throw new Error(`refusing to edit ${file}: hooks.${event} must be an array when present; fix it, then re-run.`);
+        }
+    }
     const keep = (arr) => (Array.isArray(arr) ? arr.filter((e) => !isHunchHook(e)) : []);
     json.hooks.PreToolUse = [
         ...keep(json.hooks.PreToolUse),

package/dist/mcp/server.js

@@ -15,7 +15,7 @@ import { resolveMcpToolset } from "./toolset.js";
 import { readConfig } from "../core/config.js";
 import { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
-import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { StateRefusal, SubscribeResponseSchema, capabilities, partitionOf, readState, recordsState, stateHomeFor, subscribeState, writeState } from "../store/stateBinding.js";
 import { captureState, captureBatchState } from "../store/stateCapture.js";
 import { CaptureRequestSchema, CaptureBatchRequestSchema, CaptureBatchResultSchema, STATE_CAPTURE_VERSION, STATE_CAPTURE_BATCH_VERSION } from "../core/stateContract.js";
 import { ReadRequestSchema, ReadResponseSchema, WriteRequestSchema, WriteResultSchema, SubscribeRequestSchema, RecordsRequestSchema, RecordsResponseSchema, STATE_READ_VERSION, STATE_WRITE_VERSION, STATE_SUBSCRIBE_VERSION, STATE_RECORDS_VERSION, stateHash } from "../core/stateContract.js";
@@ -1869,7 +1869,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             try {
                 // Same cross-process lock `hunch serve` takes: a second agent writing over stdio must
                 // not race the HTTP server between the ledger read and the record write.
-                const result = await withWriteLock(hunchPaths(root).hunch, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
+                const { hunchDir } = stateHomeFor(store, input.scope);
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, ...input }, {
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} ${result.record_id} (${result.durability}) ${result.record_hash}`, result);
@@ -1885,7 +1886,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             outputSchema: WriteResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {
             try {
-                const result = await withWriteLock(hunchPaths(root).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
+                const { hunchDir } = stateHomeFor(store, input.scope);
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, ...input }, {
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`${result.outcome} observation ${result.record_id} (${result.durability}); this does not assert currentness. ${result.record_hash}`, result);
@@ -1901,7 +1903,8 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             outputSchema: CaptureBatchResultSchema.shape,
         }, async ({ cwd: _cwd, ...input }) => {
             try {
-                const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
+                const { hunchDir } = stateHomeFor(store, input.scope);
+                const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, ...input }, {
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message, startupTeamRoute ?? undefined),
                 }));
                 return stateResult(`Capture batch: ${result.results.filter(r => r.status === "saved").length} saved/replayed, ${result.results.filter(r => r.status === "refused").length} refused.${result.reviews ? ` Reviews: ${result.reviews.filter(r => r.status === "saved").length} withdrawn/replayed, ${result.reviews.filter(r => r.status === "refused").length} refused.` : ''} Inspect each indexed result.`, result);
@@ -2057,7 +2060,7 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
             const report = store.buildCheckReport(files, diff, { strict: true, lastChange: (f) => lastChangeDate(f, root) });
             const v = verdict(report);
             const head = v === "block"
-                ? "VERDICT: ⛔ BLOCK — this change breaks a recorded invariant or re-opens a known bug."
+                ? "VERDICT: ⛔ BLOCK — a recorded guard requires review; inspect the cited scope and evidence below before merge."
                 : v === "warn"
                     ? "VERDICT: ⚠ WARN — this change touches engineering memory; review the cited why below before merge."
                     : "VERDICT: ✅ PASS — touches no recorded invariants and re-introduces nothing deliberately retired.";

package/dist/serve/app.js

@@ -19,7 +19,7 @@ import { createServer } from "node:http";
 import { HunchStore } from "../store/hunchStore.js";
 import { hunchPaths } from "../core/paths.js";
 import { flushCapture } from "../integrations/sync.js";
-import { StateRefusal, capabilities, mergeReadResponses, readState, recordsState, subscribeState, writeState } from "../store/stateBinding.js";
+import { StateRefusal, capabilities, mergeReadResponses, readState, recordsState, stateHomeFor, subscribeState, writeState } from "../store/stateBinding.js";
 import { STATE_READ_VERSION, STATE_RECORDS_VERSION, STATE_SUBSCRIBE_VERSION, STATE_WRITE_VERSION, ReadScopesSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
 import { partitionFor, resolvePrincipal } from "./config.js";
 import { WriteLockTimeout, withWriteLock } from "./writelock.js";
@@ -177,23 +177,26 @@ export function createServeApp(config, opts = {}) {
             if (url.pathname === "/nuryel/v1/write") {
                 const scope = requireScope(principal, body);
                 const { store, root } = storeFor(scope);
-                const result = await withWriteLock(hunchPaths(root).hunch, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
+                const { hunchDir } = stateHomeFor(store, scope);
+                const result = await withWriteLock(hunchDir, () => writeState(store, { schema: STATE_WRITE_VERSION, principal, ...body }, {
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
             if (url.pathname === "/nuryel/v1/capture") {
                 const scope = requireScope(principal, body);
-                const { store } = storeFor(scope);
-                const result = await withWriteLock(hunchPaths(store.publicRoot).hunch, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
-                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(store.publicRoot).hunch, isPrivate, message),
+                const { store, root } = storeFor(scope);
+                const { hunchDir } = stateHomeFor(store, scope);
+                const result = await withWriteLock(hunchDir, () => captureState(store, { schema: STATE_CAPTURE_VERSION, principal, ...body }, {
+                    flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, result.outcome === "created" ? 201 : 200, result);
             }
             if (url.pathname === "/nuryel/v1/capture-batch") {
                 const scope = requireScope(principal, body);
                 const { store, root } = storeFor(scope);
-                const result = await withWriteLock(hunchPaths(root).hunch, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
+                const { hunchDir } = stateHomeFor(store, scope);
+                const result = await withWriteLock(hunchDir, () => captureBatchState(store, { schema: STATE_CAPTURE_BATCH_VERSION, principal, ...body }, {
                     flush: (isPrivate, message) => flushCapture(store, hunchPaths(root).hunch, isPrivate, message),
                 }));
                 return send(res, 200, result);

package/dist/serve/writelock.js

@@ -65,8 +65,14 @@ function stealable(path, owner, now) {
     catch {
         return false;
     }
-    if (owner && owner.host === hostname() && !pidAlive(owner.pid))
-        return true;
+    // A same-host live PID is authoritative even when a long-running write has
+    // exceeded the stale-age heuristic. Age alone cannot distinguish a slow
+    // writer from a dead one; stealing here would let two writers interleave
+    // their record and ledger updates. The age fallback is only safe when the
+    // owner is from another host (whose PID we cannot probe) or its metadata is
+    // unreadable.
+    if (owner && owner.host === hostname())
+        return !pidAlive(owner.pid);
     return ageMs > STALE_AFTER_MS;
 }
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/dist/store/changeLedger.js

@@ -9,11 +9,12 @@
  * sequence to reconcile. Merging two clones' ledgers for the same scope is not decided
  * here (see docs/nuryel-state-contract.md, "Not decided here").
  */
-import { existsSync, mkdirSync, readFileSync } from "node:fs";
-import { join, resolve } from "node:path";
+import { mkdirSync } from "node:fs";
+import { basename, join, resolve } from "node:path";
 import { createHash } from "node:crypto";
 import { z } from "zod";
 import { writeFileAtomic } from "../core/io.js";
+import { readStoreArtifact, storeArtifactPath } from "../core/storeArtifact.js";
 import { ChangeEventSchema, ScopeSchema, scopePath } from "../core/stateContract.js";
 export const LEDGER_SCHEMA_VERSION = "nuryel.ledger/1";
 export const CHANGES_DIR = "changes";
@@ -60,11 +61,11 @@ export function emptyLedger(scope) {
  *  error (never silently treated as empty — that would restart the sequence). */
 export function readLedger(hunchDir, scope) {
     const file = resolve(ledgerFile(hunchDir, scope));
-    if (!existsSync(file)) {
+    const text = readStoreArtifact(hunchDir, [CHANGES_DIR, basename(file)]);
+    if (text === null) {
         validatedSnapshots.delete(file);
         return emptyLedger(scope);
     }
-    const text = readFileSync(file, "utf8");
     const cached = validatedSnapshots.get(file);
     if (cached?.text === text && cached.scope === scopePath(scope)) {
         validatedSnapshots.delete(file);
@@ -96,8 +97,8 @@ export function writeLedger(hunchDir, ledger) {
     writeValidatedLedger(hunchDir, LedgerSchema.parse(ledger));
 }
 function writeValidatedLedger(hunchDir, ledger) {
-    const file = ledgerFile(hunchDir, ledger.scope);
-    mkdirSync(join(hunchDir, CHANGES_DIR), { recursive: true });
+    const file = storeArtifactPath(hunchDir, CHANGES_DIR, basename(ledgerFile(hunchDir, ledger.scope)));
+    mkdirSync(storeArtifactPath(hunchDir, CHANGES_DIR), { recursive: true });
     writeFileAtomic(file, JSON.stringify(ledger, null, 2) + "\n");
 }
 /** Append events (in order) and remember an idempotency key in ONE atomic write, so a

package/dist/store/jsonStore.d.ts

@@ -79,9 +79,9 @@ export declare class JsonStore {
      *  two unsynchronized RMWs over index.json each read the same base array and the
      *  second rename silently erases the first's record. `mkdirSync` is the atomic
      *  acquire (EEXIST = held). A stale lock (killed process) is taken over by age;
-     *  against a live contender we wait briefly and then proceed WITH a warning —
-     *  never worse than the historical lockless behavior, and capture paths must not
-     *  start throwing on lock contention. */
+     *  against a live contender we wait briefly and then refuse the write. Proceeding
+     *  without the lock would reintroduce the record-loss race this mutex exists to
+     *  prevent. */
     private withSingleFileLock;
     /** Write a single record (validated) to its JSON file / into the index array. */
     put<K extends EntityKind>(kind: K, record: EntityFor[K]): EntityFor[K];

package/dist/store/jsonStore.js

@@ -4,10 +4,12 @@
  * authoritative read/write surface; SQLite is rebuilt from it.
  */
 import { closeSync, constants, fstatSync, lstatSync, mkdirSync, openSync, opendirSync, readSync, realpathSync, rmSync, } from "node:fs";
+import { hostname } from "node:os";
 import { isAbsolute, join, relative, resolve, sep } from "node:path";
 import { ENTITY_KINDS, SCHEMAS } from "../core/types.js";
 import { BASELINE_VERSION, migrateRaw, SCHEMA_VERSION } from "../core/migrate.js";
 import { writeFileAtomic } from "../core/io.js";
+import { readStoreArtifact } from "../core/storeArtifact.js";
 /** High-cardinality collections (symbols, edges) are stored as a single
  *  index.json array — there can be thousands, and one file per edge would create
  *  enormous git noise. Curated, low-volume entities (components, decisions, bugs,
@@ -35,6 +37,29 @@ export const MAX_JSON_RECORD_BYTES = 8 * 1024 * 1024;
 export const MAX_JSON_INDEX_BYTES = 256 * 1024 * 1024;
 export const MAX_JSON_MANIFEST_BYTES = 64 * 1024;
 export const MAX_JSON_DIRECTORY_ENTRIES_PER_KIND = 100_000;
+function readRmwOwner(lock) {
+    const text = readStoreArtifact(lock, ["owner.tmp.json"], 4096);
+    if (text === null)
+        return undefined;
+    try {
+        const parsed = JSON.parse(text);
+        if (typeof parsed.pid !== "number" || !Number.isInteger(parsed.pid) || parsed.pid < 1 || typeof parsed.host !== "string")
+            return undefined;
+        return { pid: parsed.pid, host: parsed.host };
+    }
+    catch {
+        return undefined;
+    }
+}
+function rmwPidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
 function missing(error) {
     return error.code === "ENOENT";
 }
@@ -431,30 +456,51 @@ export class JsonStore {
      *  two unsynchronized RMWs over index.json each read the same base array and the
      *  second rename silently erases the first's record. `mkdirSync` is the atomic
      *  acquire (EEXIST = held). A stale lock (killed process) is taken over by age;
-     *  against a live contender we wait briefly and then proceed WITH a warning —
-     *  never worse than the historical lockless behavior, and capture paths must not
-     *  start throwing on lock contention. */
+     *  against a live contender we wait briefly and then refuse the write. Proceeding
+     *  without the lock would reintroduce the record-loss race this mutex exists to
+     *  prevent. */
     withSingleFileLock(kind, directory, fn) {
         const lock = join(directory.lexical, ".rmw-lock");
         const deadline = Date.now() + 2_000;
         for (;;) {
+            if (Date.now() >= deadline)
+                throw new Error(`[hunch] timed out acquiring the ${kind} index lock (still held: ${lock})`);
             try {
                 mkdirSync(lock);
+                // Record ownership inside the already-exclusive directory. A live local
+                // writer may exceed the stale-age heuristic while serializing a large
+                // index; its PID must prevent a second writer from taking over.
+                try {
+                    writeFileAtomic(join(lock, "owner.tmp.json"), JSON.stringify({ pid: process.pid, host: hostname() }));
+                }
+                catch (error) {
+                    try {
+                        rmSync(lock, { recursive: true, force: true });
+                    }
+                    catch { /* report the ownership failure below */ }
+                    throw new Error(`[hunch] could not record ownership for the ${kind} index lock: ${error.message}`, { cause: error });
+                }
                 break;
             }
-            catch {
+            catch (error) {
+                if (error.code !== "EEXIST")
+                    throw error;
+                let stat;
                 try {
-                    if (Date.now() - lstatSync(lock).mtimeMs > 10_000) {
-                        rmSync(lock, { recursive: true, force: true }); // no live spawn holds a lock this old
-                        continue;
-                    }
+                    stat = lstatSync(lock);
                 }
-                catch {
-                    continue; /* vanished between attempts — retry the acquire */
+                catch (statError) {
+                    if (statError.code === "ENOENT")
+                        continue; // vanished between mkdir and inspect
+                    throw statError;
                 }
-                if (Date.now() >= deadline) {
-                    console.warn(`[hunch] proceeding without the ${kind} index lock (still held: ${lock})`);
-                    return fn();
+                const owner = readRmwOwner(lock);
+                const stale = owner && owner.host === hostname()
+                    ? !rmwPidAlive(owner.pid)
+                    : Date.now() - stat.mtimeMs > 10_000;
+                if (stale) {
+                    rmSync(lock, { recursive: true, force: true });
+                    continue;
                 }
                 Atomics.wait(RMW_LOCK_WAITER, 0, 0, 25);
             }
@@ -512,7 +558,12 @@ export class JsonStore {
             // Sorted by id so the index has ONE canonical order — re-indexing after a
             // git merge (which the driver also id-sorts) doesn't churn the whole file.
             validated.sort((a, b) => String(a.id).localeCompare(String(b.id)));
-            this.writeContainedFile(directory, this.fileFor(kind, "index"), encode(validated), this.maxBytes(kind));
+            // A rebuild is also a read-modify-write boundary from the perspective of
+            // concurrent put/delete callers: without the same mutex it can publish
+            // over an update that acquired the lock moments earlier (or vice versa).
+            this.withSingleFileLock(kind, directory, () => {
+                this.writeContainedFile(directory, this.fileFor(kind, "index"), encode(validated), this.maxBytes(kind));
+            });
             return;
         }
         // One file per record: preflight EVERY existing JSON file before touching

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.32.4",
+  "version": "1.32.5",
   "mcpName": "io.github.davesheffer/hunch",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",

package/server.json

@@ -7,13 +7,13 @@
     "source": "github"
   },
   "websiteUrl": "https://www.hunchmemory.com",
-  "version": "1.32.4",
+  "version": "1.32.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.32.4",
+      "version": "1.32.5",
       "runtimeHint": "npx",
       "packageArguments": [
         {