@davesheffer/hunch 1.32.3 → 1.32.5

package/dist/mcp/toolset.d.ts

@@ -0,0 +1,30 @@
+export declare const MCP_TOOL_GROUPS: {
+    /** nuryel.state/1 — the state-partition contract (Sofia-style agents). */
+    readonly nuryel: readonly ["nuryel_capabilities", "nuryel_read", "nuryel_write", "nuryel_capture", "nuryel_capture_batch", "nuryel_subscribe", "nuryel_records"];
+    /** Constitution G2/G3 experiment-track tools; the CLI remains the primary surface. */
+    readonly "constitution-experiments": readonly ["hunch_constitution_g2_readiness", "hunch_constitution_g3_readiness", "hunch_constitution_g2_shadow_queue", "hunch_constitution_g2_operational_drill", "hunch_constitution_g2_candidates", "hunch_constitution_g2_behavior_candidates", "hunch_constitution_g2_behavior_replay", "hunch_constitution_g2_behavior_materialization", "hunch_constitution_g2_behavior_policy_materialize"];
+};
+export type McpToolGroup = keyof typeof MCP_TOOL_GROUPS;
+export declare const MCP_TOOL_GROUP_NAMES: McpToolGroup[];
+export interface McpToolset {
+    enabled: (group: McpToolGroup) => boolean;
+    groups: McpToolGroup[];
+    hidden: string[];
+    /** Where the selection came from, for the startup log and doctor. */
+    source: "env" | "config" | "default";
+}
+/** Grammar shared by the env var and the config value: `all`, `core`, or a
+ * comma-separated list of extra groups on top of core (`core,nuryel`). Unknown
+ * words are ignored rather than failing the server. */
+export declare function parseToolsetSpec(spec: string): McpToolGroup[] | null;
+/** A root that already stores nuryel state records is a state partition and
+ * needs the nuryel tools; every other root gets the everyday set by default. */
+export declare function rootStoresState(root: string): boolean;
+/** `pinned` is `hunch mcp --root <dir>`: a server dedicated to one root, which is
+ * how state partitions are served — including a brand-new partition that has no
+ * state records yet and could never receive its first nuryel_write otherwise. */
+export declare function resolveMcpToolset(root: string, opts?: {
+    env?: NodeJS.ProcessEnv;
+    configSpec?: string | null;
+    pinned?: boolean;
+}): McpToolset;

package/dist/mcp/toolset.js

@@ -0,0 +1,72 @@
+/** Which MCP tool groups a server exposes. Every host shares one server, so the
+ * selection surface is the same for all of them: 57 tools with ~24 KB of
+ * descriptions dilute tool choice for everyday grounding. The everyday set is
+ * the default; the two specialist groups are enabled by evidence (a root that
+ * stores nuryel state records), by `.hunch/config.json` `mcp_tools`, or by the
+ * `HUNCH_MCP_TOOLS` environment variable. Hidden tools are not registered at
+ * all, so a client never sees them in tools/list. */
+import { existsSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { STATE_KINDS } from "../core/stateDelivery.js";
+export const MCP_TOOL_GROUPS = {
+    /** nuryel.state/1 — the state-partition contract (Sofia-style agents). */
+    nuryel: ["nuryel_capabilities", "nuryel_read", "nuryel_write", "nuryel_capture", "nuryel_capture_batch", "nuryel_subscribe", "nuryel_records"],
+    /** Constitution G2/G3 experiment-track tools; the CLI remains the primary surface. */
+    "constitution-experiments": [
+        "hunch_constitution_g2_readiness", "hunch_constitution_g3_readiness", "hunch_constitution_g2_shadow_queue",
+        "hunch_constitution_g2_operational_drill", "hunch_constitution_g2_candidates", "hunch_constitution_g2_behavior_candidates",
+        "hunch_constitution_g2_behavior_replay", "hunch_constitution_g2_behavior_materialization", "hunch_constitution_g2_behavior_policy_materialize",
+    ],
+};
+export const MCP_TOOL_GROUP_NAMES = Object.keys(MCP_TOOL_GROUPS);
+/** Grammar shared by the env var and the config value: `all`, `core`, or a
+ * comma-separated list of extra groups on top of core (`core,nuryel`). Unknown
+ * words are ignored rather than failing the server. */
+export function parseToolsetSpec(spec) {
+    const words = spec.split(",").map(w => w.trim().toLowerCase()).filter(Boolean);
+    if (!words.length)
+        return null;
+    if (words.includes("all"))
+        return [...MCP_TOOL_GROUP_NAMES];
+    return MCP_TOOL_GROUP_NAMES.filter(g => words.includes(g));
+}
+/** A root that already stores nuryel state records is a state partition and
+ * needs the nuryel tools; every other root gets the everyday set by default. */
+export function rootStoresState(root) {
+    return STATE_KINDS.some(kind => {
+        const dir = join(root, ".hunch", kind);
+        try {
+            return existsSync(dir) && readdirSync(dir).some(f => f.endsWith(".json"));
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** `pinned` is `hunch mcp --root <dir>`: a server dedicated to one root, which is
+ * how state partitions are served — including a brand-new partition that has no
+ * state records yet and could never receive its first nuryel_write otherwise. */
+export function resolveMcpToolset(root, opts = {}) {
+    const env = opts.env ?? process.env;
+    let groups = null;
+    let source = "default";
+    const fromEnv = env.HUNCH_MCP_TOOLS?.trim();
+    if (fromEnv) {
+        groups = parseToolsetSpec(fromEnv);
+        if (groups)
+            source = "env";
+    }
+    if (!groups && opts.configSpec?.trim()) {
+        groups = parseToolsetSpec(opts.configSpec);
+        if (groups)
+            source = "config";
+    }
+    if (!groups) {
+        groups = opts.pinned || rootStoresState(root) ? ["nuryel"] : [];
+        source = "default";
+    }
+    const set = new Set(groups);
+    const hidden = MCP_TOOL_GROUP_NAMES.filter(g => !set.has(g)).flatMap(g => [...MCP_TOOL_GROUPS[g]]);
+    return { enabled: g => set.has(g), groups: [...set], hidden, source };
+}
+//# sourceMappingURL=toolset.js.map

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.3",
+  "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.3",
+  "version": "1.32.5",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.32.3",
+      "version": "1.32.5",
       "runtimeHint": "npx",
       "packageArguments": [
         {