@davesheffer/hunch 1.9.2 → 1.9.4

package/README.md

@@ -16,10 +16,9 @@ strict enforcement.
 **Memory is the input. The product boundary is the receipt:** relevant evidence before an edit,
 then a deterministic check of the change against the rules your team has explicitly trusted.
 
-> **New in v1.9.2:** Matrix mode gives the whole team one live, private Git memory across fresh
-> clones, worktrees, CLI checks, and MCP assistants. npm publishes with short-lived OIDC
-> credentials, while the editor companion ships as one immutable, publicly verified Open VSX
-> artifact.
+> **New in v1.9.4:** MCP connections stay collision-safe across repositories and simultaneous
+> captures, while generated MCP, hook, plugin, and CI commands pin the exact npm release that
+> created them.
 
 ## Start in five minutes
 
@@ -82,7 +81,7 @@ Git repo that every teammate can access, install the Matrix release on team mach
 have one maintainer run:
 
 ```bash
-npm i -g @davesheffer/hunch@1.9.2
+npm i -g @davesheffer/hunch@1.9.4
 hunch shared --repo git@github.com:acme/project-hunch-memory.git
 git add .gitignore .hunch/team.json
 git commit -m "chore: connect shared Hunch memory"
@@ -97,7 +96,7 @@ printed by Hunch. Omit `--migrate` for a new setup.
 After the pointer commit lands, teammates need Hunch installed and Git access to the memory repo:
 
 ```bash
-npm i -g @davesheffer/hunch@1.9.2
+npm i -g @davesheffer/hunch@1.9.4
 git pull
 hunch init
 hunch doctor

package/dist/cli/invocation.js

@@ -6,11 +6,16 @@
  *  same import-safety to be unit-testable. */
 import { fileURLToPath } from "node:url";
 import { probeOllamaNumCtx } from "../synthesis/provider.js";
-/** Published package name — used for OS-agnostic invocations (see below). */
-const PKG = "@davesheffer/hunch";
+import { HUNCH_NPX_PACKAGE_SPEC } from "../core/version.js";
 export function dim(s) {
     return `\x1b[2m${s}\x1b[0m`;
 }
+/** Portable invocation written into committed MCP/provider configuration.
+ * Keep it independently testable so the distribution pin cannot silently
+ * regress to npm's moving latest tag. */
+export function publishedMcpInvocation() {
+    return { command: "npx", args: ["-y", `--package=${HUNCH_NPX_PACKAGE_SPEC}`, "hunch"] };
+}
 /** The doctor command's synthesis-status line(s) for a resolved provider.
  *  Exported for testing — the previous version (a bare provider-name switch,
  *  before the resolveSynthesisProvider preference system existed) had zero
@@ -65,15 +70,16 @@ export function resolveInvocation() {
     // Running from an installed copy (global, local, or npx cache — i.e. NOT a
     // source checkout we're hacking on). The MCP/provider config files we write
     // are committed and shared across a team via git, so they must NOT embed this
-    // machine's absolute path or OS-specific separators. Reference Hunch by its
-    // published package name instead, which `npx` resolves the same on any OS and
-    // any clone. The git hook lives in per-machine .git/hooks (never committed),
-    // so it keeps the PATH-robust absolute-node invocation below.
+    // machine's absolute path or OS-specific separators. Reference the exact
+    // published Hunch package instead, which `npx` resolves the same on any OS
+    // and any clone without floating to a newer release. The git hook lives in
+    // per-machine .git/hooks (never committed), so it keeps the PATH-robust
+    // absolute-node invocation below.
     const installed = !isDev && entry.replace(/\\/g, "/").includes("/node_modules/");
     if (installed) {
         return {
             shell: `${q(process.execPath)} ${q(entry)}`,
-            mcp: { command: "npx", args: ["-y", PKG] },
+            mcp: publishedMcpInvocation(),
         };
     }
     if (isDev) {

package/dist/core/paths.js

@@ -53,16 +53,16 @@ export function hunchPathsForDir(hunchDir) {
  *  WITHOUT `.hunch` stops the walk: an ancestor `.hunch` above the repo
  *  boundary belongs to some other scope (e.g. a stray ~/.hunch) and must never
  *  hijack a fresh repo — init would scaffold, index, and scan OUTSIDE the repo. */
+export function isDir(path) {
+    try {
+        return statSync(path).isDirectory();
+    }
+    catch {
+        return false;
+    }
+}
 export function findRoot(start = process.cwd()) {
     let cur = resolve(start);
-    const isDir = (p) => {
-        try {
-            return statSync(p).isDirectory();
-        }
-        catch {
-            return false;
-        }
-    };
     for (;;) {
         if (isDir(join(cur, HUNCH_DIR)))
             return cur; // a `.hunch` regular file is not a root

package/dist/core/version.js

@@ -16,4 +16,13 @@ export const HUNCH_VERSION = (() => {
         return "0.0.0";
     }
 })();
+/** Exact public npm package consumed by generated CI and shared MCP/provider
+ * configs. A floating package name would let one committed configuration run
+ * different Hunch semantics as npm's latest release changes. */
+export const HUNCH_PACKAGE_SPEC = `@davesheffer/hunch@${HUNCH_VERSION}`;
+/** npm alias used by npx launchers. Giving the fetched package a distinct local
+ * alias prevents npm exec from treating this repository (which has the same
+ * package name) as satisfying the request and then falling through to an older
+ * global `hunch` executable. */
+export const HUNCH_NPX_PACKAGE_SPEC = `hunch-exact@npm:${HUNCH_PACKAGE_SPEC}`;
 //# sourceMappingURL=version.js.map

package/dist/integrations/ciAction.js

@@ -8,7 +8,7 @@
  */
 import { mkdirSync, writeFileSync, existsSync } from "node:fs";
 import { join } from "node:path";
-import { HUNCH_VERSION } from "../core/version.js";
+import { HUNCH_PACKAGE_SPEC } from "../core/version.js";
 // `\${{ … }}` keeps GitHub Actions expressions literal inside this template
 // literal (a bare `${` would be JS interpolation).
 export function ciWorkflowYaml() {
@@ -44,7 +44,7 @@ jobs:
         # Pin the same release that generated this file so every assistant and CI
         # evaluate the graph with identical semantics. Dependabot/Renovate (or a
         # deliberate hunch-ci refresh) can advance this in a reviewed change.
-        run: npm install -g @davesheffer/hunch@${HUNCH_VERSION}
+        run: npm install -g ${HUNCH_PACKAGE_SPEC}
 
       - name: Fetch the PR base branch
         # checkout sets up no origin/<base> tracking ref; create it explicitly so

package/dist/mcp/roots.js

@@ -0,0 +1,58 @@
+/**
+ * Resolve MCP client roots to the one repository this server may safely serve.
+ *
+ * A server process keeps the cwd it was spawned with, while the client can move to
+ * another workspace or linked worktree. MCP roots are the client-neutral protocol
+ * mechanism for following that change.
+ */
+import { statSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { findRoot, HUNCH_DIR, isDir } from "../core/paths.js";
+function toPath(uri) {
+    if (!uri.startsWith("file:"))
+        return "";
+    try {
+        return fileURLToPath(uri);
+    }
+    catch {
+        return "";
+    }
+}
+function rootStart(path) {
+    try {
+        const stat = statSync(path);
+        if (stat.isDirectory())
+            return path;
+        if (stat.isFile())
+            return dirname(path);
+    }
+    catch {
+        // Missing/inaccessible roots are unusable.
+    }
+    return "";
+}
+/**
+ * Returns null when several advertised repositories are equally plausible.
+ * The roots protocol exposes a set of URI/name pairs, not an "active root" bit;
+ * choosing the first Hunch store in that case could silently write repo B's
+ * decision into repo A.
+ */
+export function resolveActiveRoot(rootUris, fallbackCwd) {
+    const candidates = [];
+    for (const uri of rootUris) {
+        const start = rootStart(toPath(uri));
+        if (!start)
+            continue;
+        const root = findRoot(start);
+        if (!candidates.includes(root))
+            candidates.push(root);
+    }
+    if (!candidates.length)
+        return findRoot(fallbackCwd);
+    if (candidates.length === 1)
+        return candidates[0];
+    const withStore = candidates.filter((candidate) => isDir(join(candidate, HUNCH_DIR)));
+    return withStore.length === 1 ? withStore[0] : null;
+}
+//# sourceMappingURL=roots.js.map

package/dist/mcp/server.js

@@ -8,8 +8,10 @@
  */
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { RootsListChangedNotificationSchema } from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import { hunchPaths, findRoot, toPosixTarget } from "../core/paths.js";
+import { resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId } from "../core/ids.js";
@@ -121,14 +123,41 @@ function resolveFiles(store, target) {
     const files = new Set(resolveSymbols(store, target).map((s) => s.file));
     return files.size ? [...files] : [toPosixTarget(target)];
 }
-export function buildServer(root) {
+function pullBackoff(status, finishedAt, failures) {
+    if (status === "updated" || status === "current") {
+        return { consecutivePullFailures: 0, nextRemotePullAt: finishedAt + 1_000 };
+    }
+    if (status === "busy") {
+        return { consecutivePullFailures: failures, nextRemotePullAt: finishedAt + 100 };
+    }
+    if (status === "unconfigured") {
+        return { consecutivePullFailures: 0, nextRemotePullAt: finishedAt + 30_000 };
+    }
+    const consecutivePullFailures = Math.min(failures + 1, 6);
+    return {
+        consecutivePullFailures,
+        nextRemotePullAt: finishedAt + Math.min(30_000, 1_000 * (2 ** (consecutivePullFailures - 1))),
+    };
+}
+function rebuildFreshIndex(store) {
+    for (let attempt = 0; attempt < 2; attempt++) {
+        const before = store.sourceStamp();
+        store.reindexFresh();
+        const after = store.sourceStamp();
+        if (before === after)
+            return after;
+    }
+    return undefined;
+}
+/** Prepare and validate a complete root context before publishing it to handlers.
+ *  A failed re-home therefore leaves the previous graph fully active. */
+function prepareRoot(root, explicitOverlay, requireIndex) {
     // Team auto-discovery: a committed .hunch/team.json advertises the shared store — a
     // fresh clone (a new teammate, a headless agent, a CI workflow) wires itself BEFORE the
     // store is constructed, so every consumer resolves the same single source of truth.
     // Once that declaration is present it is fail-closed: starting against the public
     // graph after an invalid config, failed first clone, or dead pointer would let both
     // reads and writes silently escape the team's memory spine.
-    const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
     const teamFile = join(hunchPaths(root).hunch, "team.json");
     const teamAdvertised = !explicitOverlay && existsSync(teamFile);
     const startupTeamConfig = teamAdvertised ? readTeamConfig(root) : null;
@@ -137,18 +166,70 @@ export function buildServer(root) {
     }
     ensureTeamOverlay(root);
     const store = new HunchStore(hunchPaths(root));
-    if (teamAdvertised && (store.mode !== "shared"
-        || !store.privateDir
-        || !existsSync(store.privateDir)
-        || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+    try {
+        if (teamAdvertised && (store.mode !== "shared"
+            || !store.privateDir
+            || !existsSync(store.privateDir)
+            || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+            throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to start MCP on another graph");
+        }
+        const startupTeamRoute = teamAdvertised && store.privateDir
+            ? teamRemoteContract(root, join(store.privateDir, ".."))
+            : null;
+        if (startupTeamRoute)
+            pinSharedRemote(store, startupTeamRoute);
+        let nextRemotePullAt = 0;
+        let consecutivePullFailures = 0;
+        if (store.privateDir) {
+            try {
+                const status = pullHunchStatus(store.privateDir, {
+                    timeoutMs: 5_000,
+                    remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
+                });
+                ({ nextRemotePullAt, consecutivePullFailures } = pullBackoff(status, Date.now(), 0));
+            }
+            catch {
+                // Offline / no remote — proceed with the validated local store.
+            }
+        }
+        let indexedSourceStamp;
+        try {
+            indexedSourceStamp = rebuildFreshIndex(store);
+        }
+        catch (error) {
+            if (requireIndex)
+                throw error;
+            console.error("[hunch-mcp] reindex on startup failed:", error.message);
+        }
+        return {
+            root,
+            teamFile,
+            teamAdvertised,
+            startupTeamConfig,
+            startupTeamRoute,
+            store,
+            nextRemotePullAt,
+            consecutivePullFailures,
+            indexedSourceStamp,
+        };
+    }
+    catch (error) {
         store.close();
-        throw new Error("the advertised team memory store is unavailable or tracks a different remote; refusing to start MCP on another graph");
+        throw error;
     }
-    const startupTeamRoute = teamAdvertised && store.privateDir
-        ? teamRemoteContract(root, join(store.privateDir, ".."))
-        : null;
-    if (startupTeamRoute)
-        pinSharedRemote(store, startupTeamRoute);
+}
+export function buildServerWithRootControl(initialRoot) {
+    const explicitOverlay = !!process.env.HUNCH_PRIVATE_DIR?.trim();
+    const initial = prepareRoot(initialRoot, explicitOverlay, false);
+    let root = initial.root;
+    let teamFile = initial.teamFile;
+    let teamAdvertised = initial.teamAdvertised;
+    let startupTeamConfig = initial.startupTeamConfig;
+    let startupTeamRoute = initial.startupTeamRoute;
+    let store = initial.store;
+    let nextRemotePullAt = initial.nextRemotePullAt;
+    let consecutivePullFailures = initial.consecutivePullFailures;
+    let indexedSourceStamp = initial.indexedSourceStamp;
     const matchesStartupTeamRoute = () => {
         if (!teamAdvertised || !store.privateDir || !startupTeamConfig || !startupTeamRoute)
             return !teamAdvertised;
@@ -165,24 +246,9 @@ export function buildServer(root) {
     // session sees memory captured on other machines/worktrees before we index — making the
     // overlay genuinely one source of truth. Remote calls are bounded; request-time failures
     // back off exponentially instead of freezing every tool on the same unavailable remote.
-    let nextRemotePullAt = 0;
-    let consecutivePullFailures = 0;
     const notePull = (status, finishedAt) => {
-        if (status === "updated" || status === "current") {
-            consecutivePullFailures = 0;
-            nextRemotePullAt = finishedAt + 1_000;
-        }
-        else if (status === "busy") {
-            nextRemotePullAt = finishedAt + 100;
-        }
-        else if (status === "unconfigured") {
-            consecutivePullFailures = 0;
-            nextRemotePullAt = finishedAt + 30_000;
-        }
-        else {
-            consecutivePullFailures = Math.min(consecutivePullFailures + 1, 6);
-            nextRemotePullAt = finishedAt + Math.min(30_000, 1_000 * (2 ** (consecutivePullFailures - 1)));
-        }
+        ({ nextRemotePullAt, consecutivePullFailures } =
+            pullBackoff(status, finishedAt, consecutivePullFailures));
     };
     const pullTeamMemory = (force = false) => {
         if (!store.privateDir)
@@ -195,86 +261,146 @@ export function buildServer(root) {
             remote: startupTeamRoute ?? advertisedTeamRemoteContract(root, join(store.privateDir, "..")),
         }), Date.now());
     };
-    if (store.privateDir) {
-        try {
-            pullTeamMemory(true);
-        }
-        catch { /* offline / no remote — proceed with local */ }
-    }
     // A source stamp is acknowledged ONLY after a stable, successful rebuild. If
     // another process changes the atomic JSON tree during the rebuild, retry once;
     // continued churn leaves the marker unset so the next request tries again.
-    let indexedSourceStamp;
     const refreshIndex = () => {
-        for (let attempt = 0; attempt < 2; attempt++) {
-            const before = store.sourceStamp();
-            store.reindexFresh();
-            const after = store.sourceStamp();
-            if (before === after) {
-                indexedSourceStamp = after;
-                return;
-            }
-        }
-        indexedSourceStamp = undefined;
+        indexedSourceStamp = rebuildFreshIndex(store);
     };
-    // Ensure the SQLite index reflects the JSON source of truth on startup.
-    try {
-        refreshIndex();
-    }
-    catch (e) {
-        console.error("[hunch-mcp] reindex on startup failed:", e.message);
-    }
     // Resolve the embedder ONCE for this long-lived process (never throws; null when
     // the optional model isn't installed). The model then loads lazily on the first
     // hunch_query and stays warm — and hybridSearch degrades to FTS until then.
     const embedderReady = selectEmbedder();
     const server = new McpServer({ name: "hunch", version: HUNCH_VERSION });
+    let activeRequests = 0;
+    let pendingRoot = null;
+    let pendingScheduled = false;
+    let closed = false;
+    const activateRoot = (next) => {
+        const canonical = findRoot(next);
+        if (canonical === root)
+            return;
+        const prepared = prepareRoot(canonical, explicitOverlay, true);
+        const previous = store;
+        root = prepared.root;
+        teamFile = prepared.teamFile;
+        teamAdvertised = prepared.teamAdvertised;
+        startupTeamConfig = prepared.startupTeamConfig;
+        startupTeamRoute = prepared.startupTeamRoute;
+        store = prepared.store;
+        nextRemotePullAt = prepared.nextRemotePullAt;
+        consecutivePullFailures = prepared.consecutivePullFailures;
+        indexedSourceStamp = prepared.indexedSourceStamp;
+        previous.close();
+        console.error(`[hunch-mcp] serving Hunch at ${root} (client root)`);
+    };
+    const applyPendingRoot = () => {
+        pendingScheduled = false;
+        if (closed || activeRequests || !pendingRoot)
+            return;
+        const next = pendingRoot;
+        pendingRoot = null;
+        try {
+            activateRoot(next);
+        }
+        catch (error) {
+            console.error(`[hunch-mcp] client root change refused: ${error.message}`);
+        }
+    };
+    const schedulePendingRoot = () => {
+        if (closed || activeRequests || !pendingRoot || pendingScheduled)
+            return;
+        pendingScheduled = true;
+        queueMicrotask(applyPendingRoot);
+    };
+    const setRoot = (next) => {
+        if (closed)
+            throw new Error("MCP server is closed");
+        const canonical = findRoot(next);
+        if (canonical === root) {
+            pendingRoot = null;
+            return;
+        }
+        if (activeRequests) {
+            pendingRoot = canonical;
+            return;
+        }
+        pendingRoot = null;
+        activateRoot(canonical);
+    };
+    const dispose = () => {
+        if (closed)
+            return;
+        closed = true;
+        pendingRoot = null;
+        store.close();
+    };
+    const underlyingClose = server.close.bind(server);
+    server.close = async () => {
+        try {
+            await underlyingClose();
+        }
+        finally {
+            dispose();
+        }
+    };
+    const priorOnClose = server.server.onclose;
+    server.server.onclose = () => {
+        dispose();
+        priorOnClose?.();
+    };
     const registerTool = server.registerTool.bind(server);
     server.registerTool = ((name, config, callback) => registerTool(name, config, async (...args) => {
-        // Routing is live state, not a startup constant. A branch switch or
-        // `hunch shared` can add/remove team.json while this stdio process remains
-        // alive; serving the old store after that boundary would write the wrong
-        // graph. Refuse and require a reconnect instead of attempting an in-place
-        // HunchStore swap while requests may be active.
-        // The explicit process overlay intentionally outranks committed team
-        // discovery for this process, both at startup and at every later request.
-        const teamFileNow = !explicitOverlay && existsSync(teamFile);
-        if (teamFileNow !== teamAdvertised) {
-            return err("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
-        }
-        const currentTeamConfig = teamFileNow ? readTeamConfig(root) : null;
-        if (teamAdvertised && !matchesStartupTeamRoute()) {
-            return err("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
-        }
-        if (teamFileNow && (!currentTeamConfig
-            || store.mode !== "shared"
-            || !store.privateDir
-            || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
-            return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
-        }
-        if (store.mode === "shared" && store.privateDir) {
-            try {
-                pullTeamMemory();
+        activeRequests++;
+        try {
+            // Routing is live state, not a startup constant. A branch switch or
+            // `hunch shared` can add/remove team.json while this stdio process remains
+            // alive; serving the old store after that boundary would write the wrong
+            // graph. Protocol-driven root swaps are prepared atomically and deferred
+            // until this request count reaches zero, so every handler sees one stable
+            // root/store/route epoch for its complete execution.
+            const teamFileNow = !explicitOverlay && existsSync(teamFile);
+            if (teamFileNow !== teamAdvertised) {
+                return err("The committed team-memory routing changed after this MCP process started. Reconnect Hunch before reading or writing memory.");
             }
-            catch { /* offline / lock held / invalid remote — use local */ }
-            // Recompute the full semantic + physical snapshot after the synchronous
-            // network seam. A paired team.json/origin change can occur while fetch is
-            // blocked; serving after that race would attach the old checkout to a new
-            // destination even though the pull itself correctly refused.
+            const currentTeamConfig = teamFileNow ? readTeamConfig(root) : null;
             if (teamAdvertised && !matchesStartupTeamRoute()) {
-                return err("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
+                return err("The team-memory URL or branch changed after this MCP process started. Refusing the old graph; reconnect Hunch first.");
             }
-            try {
-                if (store.sourceStamp() !== indexedSourceStamp)
-                    refreshIndex();
+            if (teamFileNow && (!currentTeamConfig
+                || store.mode !== "shared"
+                || !store.privateDir
+                || !overlayMatchesTeamRemote(root, join(store.privateDir, "..")))) {
+                return err("The committed team memory destination is invalid or no longer matches this process. Refusing the stale graph; reconnect Hunch first.");
             }
-            catch { /* corrupt/churning local source — serve the last durable indexed view */ }
+            if (store.mode === "shared" && store.privateDir) {
+                try {
+                    pullTeamMemory();
+                }
+                catch { /* offline / lock held / invalid remote — use local */ }
+                // Recompute the full semantic + physical snapshot after the synchronous
+                // network seam. A paired team.json/origin change can occur while fetch is
+                // blocked; serving after that race would attach the old checkout to a new
+                // destination even though the pull itself correctly refused.
+                if (teamAdvertised && !matchesStartupTeamRoute()) {
+                    return err("The team-memory route changed during refresh. Refusing to serve a stale or redirected graph; reconnect Hunch first.");
+                }
+                try {
+                    if (store.sourceStamp() !== indexedSourceStamp)
+                        refreshIndex();
+                }
+                catch { /* corrupt/churning local source — serve the last durable indexed view */ }
+            }
+            const result = await callback(...args);
+            if (teamAdvertised && !matchesStartupTeamRoute()) {
+                return err("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
+            }
+            return result;
         }
-        const result = await callback(...args);
-        if (teamAdvertised && !matchesStartupTeamRoute()) {
-            return err("The team-memory route changed while the tool was running. Its startup destination was not published; reconnect Hunch before retrying.");
+        finally {
+            activeRequests--;
+            schedulePendingRoot();
         }
-        return result;
     }));
     // -- hunch_query ----------------------------------------------------------
     server.registerTool("hunch_query", {
@@ -613,6 +739,23 @@ export function buildServer(root) {
             // same-id public record (and vice versa).
             const home = store.captureHome(!!decision.private);
             const existing = home === "private" ? store.getPrivateRec("decisions", id) : store.json.get("decisions", id);
+            // A commit-keyed id intentionally lets a human capture upgrade the machine draft
+            // for that commit. Once the slot is human-confirmed, however, a differently
+            // identified decision must never reuse it: that would silently replace the first
+            // ADR while reporting success (issue #23). Topic is the canonical identity when
+            // both sides have one; otherwise a matching title permits anchoring/refining the
+            // same record without blocking the existing draft-upgrade contract.
+            const sameHumanIdentity = existing?.topic && decision.topic
+                ? decision.topic === existing.topic
+                : existing?.title === decision.title;
+            const conflictsWithHuman = !!existing?.provenance.source.includes("human_confirmed")
+                && !sameHumanIdentity;
+            if (conflictsWithHuman) {
+                return err(`Decision id ${id} already identifies a different human-confirmed decision: ` +
+                    `"${existing.title}"${existing.topic ? ` (topic "${existing.topic}")` : ""}. ` +
+                    `Refusing to overwrite it with "${decision.title}"${decision.topic ? ` (topic "${decision.topic}")` : ""}. ` +
+                    "Record the additional decision without commit, or reuse the incumbent topic/title when refining the same decision.");
+            }
             const source = existing && existing.provenance.source.includes("llm_draft")
                 ? "llm_draft+human_confirmed"
                 : "human_confirmed";
@@ -1280,7 +1423,16 @@ export function buildServer(root) {
             return err(`Failed to materialize G2 behavior policies: ${e.message}`);
         }
     });
-    return server;
+    return {
+        server,
+        getRoot: () => root,
+        setRoot,
+    };
+}
+/** Back-compatible server construction for tests and callers that do not need
+ *  to drive roots directly. The server still owns and closes its active store. */
+export function buildServer(root) {
+    return buildServerWithRootControl(root).server;
 }
 function provLine(record) {
     const p = record?.provenance;
@@ -1289,12 +1441,44 @@ function provLine(record) {
     const v = p.last_verified ? `, verified ${p.last_verified.slice(0, 10)}` : "";
     return `\n      ⟨${p.source ?? "?"}, confidence ${p.confidence ?? "?"}${v}⟩`;
 }
+/** Query client roots after initialization and follow later list changes.
+ *  Generation ordering prevents a slow stale roots/list response from winning. */
+export function wireClientRoots(control, fallback) {
+    let generation = 0;
+    const syncRoots = async () => {
+        const mine = ++generation;
+        try {
+            if (!control.server.server.getClientCapabilities()?.roots)
+                return;
+            const response = await control.server.server.listRoots();
+            if (mine !== generation)
+                return;
+            const next = resolveActiveRoot((response?.roots ?? []).map((root) => root.uri), fallback);
+            if (!next) {
+                console.error("[hunch-mcp] multiple client roots are equally plausible; keeping the current Hunch root");
+                return;
+            }
+            control.setRoot(next);
+        }
+        catch (error) {
+            // A client without roots support keeps the spawn root. A client-provided
+            // root that fails fail-closed validation is also refused without taking
+            // down the existing, already-validated graph.
+            if (mine === generation) {
+                console.error(`[hunch-mcp] could not apply client roots: ${error.message}`);
+            }
+        }
+    };
+    control.server.server.oninitialized = () => { void syncRoots(); };
+    control.server.server.setNotificationHandler(RootsListChangedNotificationSchema, async () => { await syncRoots(); });
+}
 /** Start the stdio server (called by `hunch mcp`). */
 export async function startServer(cwd = process.cwd()) {
-    const root = findRoot(cwd);
-    const server = buildServer(root);
+    const fallback = findRoot(cwd);
+    const control = buildServerWithRootControl(fallback);
+    wireClientRoots(control, fallback);
     const transport = new StdioServerTransport();
-    await server.connect(transport);
-    console.error(`[hunch-mcp] serving Hunch at ${root} over stdio`);
+    await control.server.connect(transport);
+    console.error(`[hunch-mcp] serving Hunch over stdio (spawn root ${control.getRoot()}; resolving client roots…)`);
 }
 //# sourceMappingURL=server.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.9.2",
+  "version": "1.9.4",
   "license": "Apache-2.0",
   "author": "Dave Sheffer <dave.sheffer1@gmail.com>",
   "description": "Engineering memory and a deterministic Change Gate for AI-assisted codebases: decisions, rejected approaches, constraints, and bug lineage become portable context and opt-in enforcement for every MCP assistant.",