@davesheffer/hunch 1.32.4 → 1.32.7

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/extractors/git.js

@@ -1769,7 +1769,11 @@ function waitForCommitLockHandoff(lock, first, timeoutMs) {
     while (Date.now() < deadline) {
         if (attempt.state === "acquired")
             return true;
-        if (attempt.state !== "held-live" || attempt.ownerPid === process.pid)
+        // Once the first snapshot proved a live owner, an owner-less snapshot can be
+        // the normal release window: recursive cleanup removes owner-<pid> before
+        // removing the outer lock directory. Keep the bounded handoff wait through
+        // that transient state instead of reporting a false busy/no-op result.
+        if (attempt.state === "held-live" && attempt.ownerPid === process.pid)
             return false;
         Atomics.wait(sleeper, 0, 0, Math.min(25, deadline - Date.now()));
         attempt = acquireCommitLock(lock);

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

@@ -14,6 +14,8 @@ import { readHookObservations } from "../core/hookObservations.js";
 const CAPABILITY_EVIDENCE = {
     context: ["SessionStart", "UserPromptSubmit"],
     "edit-blocking": ["PreToolUse"],
+    // A successful PostToolUse only proves that the post hook ran. A provider
+    // may instead include an explicit failure status in that same event.
     "failure-capture": ["PostToolUseFailure", "PostToolUse"],
     compaction: ["PreCompact"],
 };
@@ -34,6 +36,15 @@ const object = (v) => {
         throw new Error("expected a configuration object");
     return v;
 };
+function evidenceFor(capability, harness, observed, expectedVersion) {
+    const matches = observed.filter(o => o.provider === harness && (capability !== "failure-capture"
+        ? CAPABILITY_EVIDENCE[capability].includes(o.event)
+        : o.event === "PostToolUseFailure" || (o.event === "PostToolUse" && o.outcome === "failure")));
+    // A stale row must not hide a fresh result recorded by a newer hook. Keep a
+    // matching stale row as the fallback so the caller can explain why it is not
+    // verified rather than treating the evidence as absent.
+    return matches.find(o => o.version === expectedVersion && Date.now() - Date.parse(o.at) <= OBSERVATION_FRESH_MS) ?? matches[0];
+}
 function strings(value) {
     if (typeof value === "string")
         return [value];
@@ -52,7 +63,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) : [])];
 }
@@ -192,7 +203,7 @@ export function inspectIntegrations(root, selected) {
             else {
                 // Verified only by an event the host actually delivered, on the expected
                 // version, recently. Matchers and tool coverage beyond that event stay unproven.
-                const hit = observed.find(o => o.provider === harness && CAPABILITY_EVIDENCE[capability].includes(o.event));
+                const hit = evidenceFor(capability, harness, observed, report.expectedVersion);
                 const fresh = hit !== undefined && Date.now() - Date.parse(hit.at) <= OBSERVATION_FRESH_MS;
                 if (hit && fresh && hit.version === report.expectedVersion) {
                     status.status = "verified";
@@ -201,6 +212,9 @@ export function inspectIntegrations(root, selected) {
                 else if (hit) {
                     status.detail = `${event} configured; last observed ${hit.at} on Hunch ${hit.version}${hit.version === report.expectedVersion ? " (stale)" : `, not the expected ${report.expectedVersion}`}`;
                 }
+                else if (capability === "failure-capture" && observed.some(o => o.provider === harness && o.event === "PostToolUse")) {
+                    status.detail = `${event} configured; PostToolUse was observed, but no explicit failed-tool event was delivered, so failure capture remains untested`;
+                }
                 else {
                     status.detail = `${event} configured; host delivery, matchers, and tool coverage are not verified`;
                 }

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);
 }
@@ -306,7 +345,9 @@ export function writeCodexHooks(root, inv) {
         SessionStart: [entry()],
         UserPromptSubmit: [entry()],
         PreToolUse: [entry("apply_patch")],
-        PostToolUse: [entry("apply_patch|shell|local_shell")],
+        // Codex's native command tool arrives as `Bash` (or `PowerShell` on
+        // Windows), while older hosts may expose shell/local_shell names.
+        PostToolUse: [entry("apply_patch|Bash|PowerShell|shell|local_shell")],
         Stop: [entry()],
         PreCompact: [entry()],
         SubagentStart: [entry()],
@@ -347,9 +388,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";
@@ -1753,7 +1753,11 @@ export function buildServerWithRootControl(initialRoot, options = {}) {
                 spawned_decision: finding.spawned_decision ?? existing?.spawned_decision ?? null,
                 observed_at: existing?.observed_at ?? now, // first observation wins — updates re-verify, not re-date
                 resolved_commit: finding.resolved_commit ?? existing?.resolved_commit ?? null,
-                provenance: { source: "human_confirmed", confidence: 0.95, evidence: finding.evidence ?? existing?.provenance.evidence ?? [], last_verified: now },
+                // Findings have no authenticated capture front door. Calling this MCP tool is
+                // agent testimony, even when the observation is updating a record that a human
+                // confirmed previously; only an explicit human-authored path may mint the
+                // human_confirmed tier.
+                provenance: { source: "agent_recorded", confidence: 0.75, evidence: finding.evidence ?? existing?.provenance.evidence ?? [], last_verified: now },
             };
             const stored = store.putCapture("findings", rec, !!finding.private);
             const observed = observeReportCapture(root, task_id, "findings", stored, home, !!existing, home === "private" ? store.privateDir ?? undefined : hunchPaths(root).hunch);
@@ -1869,7 +1873,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 +1890,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 +1907,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 +2064,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];