@davesheffer/hunch 1.41.6 → 1.42.0

package/dist/mcp/taskReportTools.js

@@ -61,12 +61,12 @@ export { verificationLauncherFor };
 export function registerTaskReportTools(server, getRoot, getStore) {
     server.registerTool("hunch_task", {
         title: "Start or finish a task's contribution report",
-        description: "Start once per user task, unless the host's prompt hook already opened the task and printed its verify command — then reuse that task_id and do not start. Pass the task_id to hunch_context. Finish before your final response and include the returned concise contribution card, without asking the user; skip finish only when the prompt hook's own instruction said this host closes the task and the task used no Hunch (no hunch_* call on this task_id, no verified check, no hook context you acted on, nothing to claim), and a task you started with this tool must always be finished. Applications are explicitly agent-reported and must name an exact delivered occurrence and record hash. Completion never implies successful verification. Not for storing decisions or claiming tests passed; use the CLI task verify wrapper for observed command results.",
+        description: "Start once per user task, unless the host's prompt hook already opened one — then reuse its task_id. Pass task_id to hunch_context. Finish before your final response and show the returned contribution card without asking; skip finish only when the hook said the host closes the task and the task used no Hunch (no hunch_* call, verified check, or hook context you acted on). A task you started must always be finished. Applications must name an exact delivered occurrence and record hash. Finishing never implies verification. Not for storing decisions or claiming tests passed; use the CLI task verify wrapper for command results.",
         inputSchema: {
             action: z.enum(["start", "finish"]), task_id: TaskIdSchema.optional(),
             title: z.string().min(1).max(200).optional(),
-            outcome: z.enum(["completed", "interrupted"]).optional(),
-            applications: z.array(ReportClaimSchema).max(20).optional(),
+            outcome: z.enum(["completed", "interrupted"]).optional().describe("\"interrupted\" when cut short."),
+            applications: z.array(ReportClaimSchema).max(20).optional().describe("Only lessons actually applied. Copy occurrence_id, record_id, content_hash exactly from hunch_report(task_id) application_references; never derive an ID from a receipt or use a scope hash."),
             cwd: z.string().optional().describe("Actual repository/worktree directory for this task."),
         },
     }, async ({ action, task_id, title, outcome, applications }) => {
@@ -88,7 +88,9 @@ export function registerTaskReportTools(server, getRoot, getStore) {
                     task = readTaskReport(root, task_id, reportSourceSnapshot(root).hash).task;
                 }
                 const launcher = verificationLauncher();
-                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to every hunch_context and decision/correction/finding capture call. Before the final response, finish with hunch_task and include its contribution card. For checks use this exact installation (the global hunch binary may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]${launcher.note}. The default budget is 15 minutes; add --timeout <seconds> before -- for a longer suite.` }], structuredContent: { task, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
+                // Compact by design (#370): the rules an agent needs to act, and exact
+                // identities; scope, title and timestamps stay in `hunch report <id> --json`.
+                return { content: [{ type: "text", text: `Task ${task.task_id} · ${task.state}. Pass task_id to hunch_context and every decision/correction/finding capture (a capture is not proof of a commit or push). To claim an application, copy occurrence_id, record_id and content_hash exactly from hunch_report(task_id) application_references, with the action you took; omit applications you did not make. Before the final response, finish with hunch_task (outcome "interrupted" if cut short) and include its contribution card verbatim, Evidence line and agent-reported label included, unless presentation_enabled is false. Never rerun an expensive check only for reporting; missing evidence stays unverified. Checks, with this exact installation (a global hunch may be stale): ${launcher.shell} task verify ${task.task_id} -- <command> [arguments]${launcher.note} (15-minute default; --timeout <seconds> before -- for longer).` }], structuredContent: { task: { task_id: task.task_id, state: task.state }, verification_argv: [...launcher.argv, "task", "verify", task.task_id, "--"] } };
             }
             if (!task_id)
                 throw new Error("finish requires the exact task_id");
@@ -105,12 +107,10 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             finishReportTask(root, task_id, outcome ?? "completed");
             // The finished task becomes graph memory through the normal capture path;
             // a failed write is disclosed on the card, never a reason to lose it.
-            let graph = null;
             let graphNote = "";
             try {
                 const saved = persistTaskRecord(root, getStore(), task_id);
                 if (saved) {
-                    graph = { id: saved.record.id, home: saved.home, flushed: saved.flushed, changed: saved.changed };
                     graphNote = `\nGraph     ${saved.changed ? "saved" : "already saved"} as ${saved.record.id} (${saved.home}${saved.flushed ? `, ${saved.flushed}` : ""})`;
                 }
                 else {
@@ -125,7 +125,10 @@ export function registerTaskReportTools(server, getRoot, getStore) {
             // The HTML evidence view is rendered on demand (hunch_report(html: true),
             // `hunch report <id> --html`, or the VS Code view); finish writes no file.
             const card = renderTaskReport(report) + graphNote;
-            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { ...boundedTaskReportForHost(report), presentation_enabled: show, contribution_card: show ? card : null, report_path: null, graph_record: graph } };
+            // Compact by design (#370): the card (in structuredContent too — some hosts
+            // show only that) and what an agent acts on. Deliveries, checks, conformance
+            // and the graph record stay in hunch_report(task_id) / `hunch report <id> --json`.
+            return { content: [{ type: "text", text: show ? card : "Task report retained. Automatic presentation is disabled; omit the contribution card from the final response." }], structuredContent: { schema: "hunch.task-finish/1", task_id: report.task.task_id, state: report.task.state, presentation_enabled: show, contribution_card: show ? card : null, full_report: `hunch report ${report.task.task_id} --json` } };
         }
         catch (error) {
             const message = `Task report unavailable: ${error.message}`;
@@ -143,8 +146,8 @@ export function registerTaskReportTools(server, getRoot, getStore) {
     });
     server.registerTool("hunch_report", {
         title: "Inspect the evidence for Hunch's contribution to a task",
-        description: "Read task reports: exact delivered memory, agent-reported applications, observed command results and explicit unknowns, as a bounded summary (identities and verdicts, not envelope text; the full report is `hunch report <id> --json`). Supply lesson for exact revision history across tasks. With neither task_id nor lesson, lists recent tasks without guessing which is yours. html writes a local private evidence view. Not a causal impact score, public export, or authority to execute verification commands.",
-        inputSchema: { task_id: TaskIdSchema.optional(), lesson: LessonReferenceSchema.optional().describe("Exact kind and record_id, optionally content_hash, to inspect retained appearances across tasks. Partial indexing requires refreshing before pagination."), before: z.number().int().positive().optional(), html: z.boolean().optional(), cwd: z.string().optional() },
+        description: "Read task reports: exact delivered memory, agent-reported applications, observed command results and explicit unknowns, as a bounded summary (identities and verdicts, not envelope text; full report is `hunch report <id> --json`). Supply lesson for exact revision history across tasks. With neither task_id nor lesson, lists recent tasks without guessing which is yours. html writes a local private evidence view. Not a causal impact score, public export, or authority to execute verification commands.",
+        inputSchema: { task_id: TaskIdSchema.optional(), lesson: LessonReferenceSchema.optional().describe("Exact kind and record_id, optionally content_hash, for retained appearances across tasks. Partial indexing needs a refresh before pagination."), before: z.number().int().positive().optional(), html: z.boolean().optional(), cwd: z.string().optional() },
     }, async ({ task_id, lesson, before, html }) => {
         try {
             const root = getRoot();

package/dist/mcp/toolset.d.ts

@@ -3,6 +3,10 @@ export declare const MCP_TOOL_GROUPS: {
     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"];
+    /** Constitution policy review; on by default once the repo holds a policy. */
+    readonly policy: readonly ["hunch_policy_candidates", "hunch_policy_plan", "hunch_policy_card", "hunch_policy_shadow", "hunch_policy_proof", "hunch_policy_evaluate", "hunch_policy_upgrade_correction"];
+    /** Research, audit and sealed-proof tools outside the everyday loop; opt-in only. */
+    readonly analysis: readonly ["hunch_project_dna", "hunch_project_dna_delta", "hunch_project_match", "hunch_change_proof", "hunch_change_identity", "hunch_shortlist", "hunch_evidence_map", "hunch_wiki_status"];
 };
 export type McpToolGroup = keyof typeof MCP_TOOL_GROUPS;
 export declare const MCP_TOOL_GROUP_NAMES: McpToolGroup[];
@@ -22,9 +26,15 @@ export declare function parseToolsetSpec(spec: string): McpToolGroup[] | null;
 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. */
+ * state records yet and could never receive its first nuryel_write otherwise.
+ * `hasPolicies` is the caller's policy evidence (public or private overlay); the
+ * first policy comes from `hunch index` or `hunch policy upgrade-correction`. The
+ * grounding block counts public policies only, so private-only policies register
+ * the tools without advertising them. The set is resolved once per process; a
+ * re-homed server keeps it until restart, as with the nuryel group. */
 export declare function resolveMcpToolset(root: string, opts?: {
     env?: NodeJS.ProcessEnv;
     configSpec?: string | null;
     pinned?: boolean;
+    hasPolicies?: boolean;
 }): McpToolset;

package/dist/mcp/toolset.js

@@ -1,10 +1,11 @@
 /** 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. */
+ * selection surface is the same for all of them, and a host that loads every
+ * schema pays for each tool on every session (#368). The everyday set is the
+ * default; the specialist groups are enabled by evidence (a root that stores
+ * nuryel state records, a repo with Constitution policies), 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";
@@ -17,6 +18,16 @@ export const MCP_TOOL_GROUPS = {
         "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",
     ],
+    /** Constitution policy review; on by default once the repo holds a policy. */
+    policy: [
+        "hunch_policy_candidates", "hunch_policy_plan", "hunch_policy_card", "hunch_policy_shadow",
+        "hunch_policy_proof", "hunch_policy_evaluate", "hunch_policy_upgrade_correction",
+    ],
+    /** Research, audit and sealed-proof tools outside the everyday loop; opt-in only. */
+    analysis: [
+        "hunch_project_dna", "hunch_project_dna_delta", "hunch_project_match", "hunch_change_proof",
+        "hunch_change_identity", "hunch_shortlist", "hunch_evidence_map", "hunch_wiki_status",
+    ],
 };
 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
@@ -45,7 +56,12 @@ export function rootStoresState(root) {
 }
 /** `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. */
+ * state records yet and could never receive its first nuryel_write otherwise.
+ * `hasPolicies` is the caller's policy evidence (public or private overlay); the
+ * first policy comes from `hunch index` or `hunch policy upgrade-correction`. The
+ * grounding block counts public policies only, so private-only policies register
+ * the tools without advertising them. The set is resolved once per process; a
+ * re-homed server keeps it until restart, as with the nuryel group. */
 export function resolveMcpToolset(root, opts = {}) {
     const env = opts.env ?? process.env;
     let groups = null;
@@ -62,7 +78,11 @@ export function resolveMcpToolset(root, opts = {}) {
             source = "config";
     }
     if (!groups) {
-        groups = opts.pinned || rootStoresState(root) ? ["nuryel"] : [];
+        groups = [];
+        if (opts.pinned || rootStoresState(root))
+            groups.push("nuryel");
+        if (opts.hasPolicies)
+            groups.push("policy");
         source = "default";
     }
     const set = new Set(groups);

package/dist/store/hunchStore.d.ts

@@ -66,6 +66,11 @@ export declare class HunchStore {
     /** How privateDir was selected. Multi-store consumers can use this instead of
      *  inferring process-global routing from process.env. */
     readonly overlaySource: OverlayResolutionSource;
+    /** A per-worktree overlay pointer this machine's setup never registered (ignored). */
+    private ignoredLocalPointer;
+    /** The routing that ignored pointer asked for, so the refusal can name the exact
+     *  setup command that re-registers it. */
+    private ignoredLocalPointerSetup;
     /** Present only when HUNCH_PRIVATE_DIR redirects this store away from the
      *  repo/worktree-local pointer. Precedence is compatibility-sensitive and stays
      *  env-first; making the redirection queryable removes the silent footgun. */
@@ -102,6 +107,9 @@ export declare class HunchStore {
      *  Callers decide where it is safe to emit (CLI/MCP stderr, doctor output); the
      *  store constructor stays side-effect-free for hooks and embedded consumers. */
     overlayResolutionWarning(teamConfigBypassed?: boolean): string | null;
+    /** Why an unregistered per-worktree pointer blocks this store, with the exact command
+     *  that re-registers it. Never auto-re-registered: the pointer may be repository content. */
+    private unregisteredPointerMessage;
     /** Where a capture belongs: an explicit private:true always goes to the overlay
      *  (putPrivate throws rather than silently landing public when none is configured);
      *  otherwise the overlay in unified ("shared") mode, else the public store. ONE home
@@ -138,10 +146,26 @@ export declare class HunchStore {
      * accidentally target a public record with the same id. */
     deleteWhereItLives<K extends EntityKind>(kind: K, id: string): boolean;
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
-     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash.
+     *  never committed). An absent file reads as {}; a present one that is unreadable,
+     *  not valid JSON (a leading UTF-8 BOM is tolerated), not a JSON object, or a symlink
+     *  throws: reading it as "no overlay" would silently open this repository PUBLIC.
      *  `autoCommit` is tri-state: true/false when the file says so, undefined when unset.
      *  `mode` records HOW the overlay was set up ("private" split vs "shared" unified). */
     private localConfig;
+    /** Why a present overlay pointer file blocks this store. */
+    private invalidPointerMessage;
+    /** The per-worktree pointer's shape, WITHOUT following any link: "absent" when neither
+     *  it nor a symlink sits there, "plain" for a regular file inside a real `.hunch`
+     *  directory of this checkout, and "unsafe" for anything else that exists (a symlinked
+     *  `local.json`, a directory, or a pointer reachable only through a symlinked `.hunch`). */
+    private localPointerFileState;
+    /** Whether a per-worktree `.hunch/local.json` naming `privateDir` was registered by this
+     *  machine's own setup rather than shipped with the checkout. The file is gitignored by
+     *  convention only, so a repository or archive can still carry one. Every setup path
+     *  (`hunch init`, `hunch private`, `hunch shared`, `hunch worktree`) also writes the
+     *  pointer in the git common dir, which no clone or checkout content can supply; the
+     *  per-worktree pointer is honored only when that pointer names the same store. */
+    private ownsLocalPointer;
     /** Merged read: public ∪ private overlay (private wins on id collision). Every
      *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-
      *  artifact writers keep using this.json.loadAll (public-only) so a private record

package/dist/store/hunchStore.js

@@ -11,14 +11,14 @@
  *   - fragility():      ranked fragility report with evidence
  */
 import { resolve, join, dirname, isAbsolute, relative } from "node:path";
-import { existsSync, readFileSync, realpathSync, statSync } from "node:fs";
+import { existsSync, lstatSync, readFileSync, realpathSync, statSync } from "node:fs";
 import { toPosixTarget, repoRelativeTarget, isRepoFile, hunchPathsForDir } from "../core/paths.js";
 import { ENTITY_KINDS } from "../core/types.js";
 import { openDb, withTx } from "./db.js";
 import { RESET_SQL, embedHash } from "./schema.js";
 import { selectEmbedder } from "./embedder.js";
 import { JsonStore } from "./jsonStore.js";
-import { gitCommonDir, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
+import { checkoutCommonDir, sameFilesystemEntry, gitWorktreeRoot, isolatedHeadSha, sameGitPublication, scopedLastChangeDates, } from "../extractors/git.js";
 import { pathMatchesGlob, pathsRelated, isIndexedPath, matchSymbolsTiered } from "../core/glob.js";
 import { cochangeFor } from "../core/cochange.js";
 import { withServedDatabase } from "../core/served.js";
@@ -64,6 +64,11 @@ export class HunchStore {
     /** How privateDir was selected. Multi-store consumers can use this instead of
      *  inferring process-global routing from process.env. */
     overlaySource;
+    /** A per-worktree overlay pointer this machine's setup never registered (ignored). */
+    ignoredLocalPointer = null;
+    /** The routing that ignored pointer asked for, so the refusal can name the exact
+     *  setup command that re-registers it. */
+    ignoredLocalPointerSetup = {};
     /** Present only when HUNCH_PRIVATE_DIR redirects this store away from the
      *  repo/worktree-local pointer. Precedence is compatibility-sensitive and stays
      *  env-first; making the redirection queryable removes the silent footgun. */
@@ -109,6 +114,13 @@ export class HunchStore {
         const resolvedEnvironmentDir = environmentDir
             ? resolve(this.paths.root, environmentDir)
             : undefined;
+        // Fail closed: a per-worktree pointer naming an overlay this machine never registered
+        // (a pre-v0.33 setup, or one shipped with the checkout) must not silently demote this
+        // store to public mode — the next hook capture or sync would publish memory meant for
+        // the overlay. Only explicit setup (or HUNCH_PRIVATE_DIR) re-establishes ownership.
+        if (this.ignoredLocalPointer && !configuredDir && !resolvedEnvironmentDir) {
+            throw new Error(this.unregisteredPointerMessage(this.ignoredLocalPointer));
+        }
         const priv = resolvedEnvironmentDir || configuredDir;
         this.overlaySource = resolvedEnvironmentDir
             ? "environment"
@@ -181,8 +193,22 @@ export class HunchStore {
         if (this.overlaySource === "environment" && teamConfigBypassed && this.privateDir) {
             return `HUNCH_PRIVATE_DIR bypasses .hunch/team.json and selects ${this.privateDir} in ${this.mode} mode; team-store auto-discovery is disabled for this process. Unset HUNCH_PRIVATE_DIR to use the advertised team store.`;
         }
+        if (this.ignoredLocalPointer && this.overlaySource === "local-config" && this.privateDir) {
+            return `.hunch/local.json points at ${this.ignoredLocalPointer}, which this machine's setup did not register, so that per-worktree pointer is ignored and the registered store ${this.privateDir} is used. Delete .hunch/local.json, or run \`hunch private\` (or \`hunch shared\`) here to change the registered store.`;
+        }
         return null;
     }
+    /** Why an unregistered per-worktree pointer blocks this store, with the exact command
+     *  that re-registers it. Never auto-re-registered: the pointer may be repository content. */
+    unregisteredPointerMessage(dir) {
+        const { mode, autoCommit } = this.ignoredLocalPointerSetup;
+        const quoted = /^[\w@%+=:,./-]+$/.test(dir) ? dir : JSON.stringify(dir);
+        const command = `hunch ${mode === "shared" ? "shared" : "private"} ${quoted}${autoCommit === false ? " --no-auto-commit" : ""}`;
+        return `.hunch/local.json names a memory store at ${dir} that this machine's setup has not registered in the git common dir, ` +
+            "so Hunch refuses to open this repository's memory rather than silently writing captures to the public .hunch/. " +
+            `If you set up that store for THIS repository, register it by running \`${command}\` in this checkout. ` +
+            "Otherwise delete .hunch/local.json. (HUNCH_PRIVATE_DIR also selects an overlay explicitly for one process.)";
+    }
     /** Where a capture belongs: an explicit private:true always goes to the overlay
      *  (putPrivate throws rather than silently landing public when none is configured);
      *  otherwise the overlay in unified ("shared") mode, else the public store. ONE home
@@ -276,41 +302,140 @@ export class HunchStore {
         return this.json.delete(kind, id);
     }
     /** The private-overlay config from the gitignored `.hunch/local.json` (per-machine,
-     *  never committed). Tolerant: returns {} on missing/invalid so reads never crash.
+     *  never committed). An absent file reads as {}; a present one that is unreadable,
+     *  not valid JSON (a leading UTF-8 BOM is tolerated), not a JSON object, or a symlink
+     *  throws: reading it as "no overlay" would silently open this repository PUBLIC.
      *  `autoCommit` is tri-state: true/false when the file says so, undefined when unset.
      *  `mode` records HOW the overlay was set up ("private" split vs "shared" unified). */
     localConfig() {
         const read = (file) => {
+            let raw;
             try {
-                if (!existsSync(file))
+                raw = readFileSync(file, "utf8");
+            }
+            catch (error) {
+                if (["ENOENT", "ENOTDIR"].includes(error.code ?? ""))
                     return {};
-                const v = JSON.parse(readFileSync(file, "utf8"));
-                const privateDir = typeof v.privateDir === "string" && v.privateDir.trim() ? v.privateDir.trim() : undefined;
-                const mode = v.mode === "private" || v.mode === "shared" ? v.mode : undefined;
-                return { privateDir, autoCommit: typeof v.autoCommit === "boolean" ? v.autoCommit : undefined, mode };
+                throw new Error(this.invalidPointerMessage(file, `cannot be read (${error.code ?? String(error)})`));
             }
-            catch {
-                return {};
+            let v;
+            try {
+                v = JSON.parse(raw.startsWith("\uFEFF") ? raw.slice(1) : raw);
+            }
+            catch (error) {
+                throw new Error(this.invalidPointerMessage(file, `is not valid JSON (${error instanceof Error ? error.message : String(error)})`));
+            }
+            if (!v || typeof v !== "object" || Array.isArray(v)) {
+                throw new Error(this.invalidPointerMessage(file, "is not a JSON object"));
             }
+            const o = v;
+            let privateDir;
+            if ("privateDir" in o) {
+                if (typeof o.privateDir !== "string" || !o.privateDir.trim()) {
+                    throw new Error(this.invalidPointerMessage(file, "has an invalid privateDir"));
+                }
+                privateDir = o.privateDir.trim();
+            }
+            let mode;
+            if ("mode" in o) {
+                if (o.mode !== "private" && o.mode !== "shared") {
+                    throw new Error(this.invalidPointerMessage(file, "has an invalid mode"));
+                }
+                mode = o.mode;
+            }
+            return { privateDir, autoCommit: typeof o.autoCommit === "boolean" ? o.autoCommit : undefined, mode };
         };
         // Per-worktree pointer first (explicit / back-compat). If it names no overlay, fall back to
         // the SHARED pointer in the git common dir — identical across ALL worktrees, so a freshly
         // added worktree (whose gitignored .hunch/local.json doesn't exist yet) still auto-discovers
-        // the same memory. The git lookup runs ONLY when the cheap per-worktree read is empty, keeping
-        // it off the hot path for already-configured checkouts.
-        const perWorktree = read(join(this.paths.hunch, "local.json"));
-        if (perWorktree.privateDir)
-            return perWorktree;
-        const common = gitCommonDir(this.paths.root);
+        // the same memory. A per-worktree pointer that names an overlay must be one this machine's
+        // setup registered (ownsLocalPointer) before it wins.
+        const perWorktreeFile = join(this.paths.hunch, "local.json");
+        const perWorktreeState = this.localPointerFileState(perWorktreeFile);
+        if (perWorktreeState === "unsafe") {
+            throw new Error(`${perWorktreeFile} (or its .hunch directory) is a symlink or not a plain file; a symlinked .hunch/local.json is never followed, ` +
+                "so Hunch refuses to open this repository's memory rather than silently writing captures to the public .hunch/. " +
+                "Re-create it as a plain file, or run `hunch private <dir>` here, or delete it.");
+        }
+        let perWorktree = perWorktreeState === "plain" ? read(perWorktreeFile) : {};
+        // The shared pointer is trusted only in a repository Git reached through this
+        // checkout's own `.git` entry, and only with the absolute path setup always writes.
+        const common = checkoutCommonDir(this.paths.root);
+        let registered = {};
         if (common) {
-            const shared = read(join(common, "hunch", "local.json"));
-            // A per-worktree `autoCommit: false` (hunch init --no-auto-commit) is an explicit
-            // local opt-out — it must survive the fall-through to the shared overlay pointer.
-            if (shared.privateDir)
-                return { ...shared, autoCommit: perWorktree.autoCommit ?? shared.autoCommit };
+            const commonFile = join(common, "hunch", "local.json");
+            const commonState = this.localPointerFileState(commonFile);
+            if (commonState === "unsafe") {
+                throw new Error(`${commonFile} (or its .hunch directory) is a symlink or not a plain file; a symlinked local.json is never followed, ` +
+                    "so Hunch refuses to open this repository's memory rather than silently writing captures to the public .hunch/. " +
+                    "Re-create it as a plain file, or run `hunch private <dir>` (or `hunch shared`) here.");
+            }
+            registered = commonState === "plain" ? read(commonFile) : {};
+            if (registered.privateDir && !isAbsolute(registered.privateDir)) {
+                throw new Error(this.invalidPointerMessage(commonFile, "has a non-absolute privateDir"));
+            }
         }
+        const shared = registered.privateDir ? registered : {};
+        if (perWorktree.privateDir && !this.ownsLocalPointer(perWorktree.privateDir, shared.privateDir)) {
+            this.ignoredLocalPointer = resolve(this.paths.root, perWorktree.privateDir);
+            this.ignoredLocalPointerSetup = { mode: perWorktree.mode, autoCommit: perWorktree.autoCommit };
+            perWorktree = {}; // not registered by this machine's setup: ignore every field it carries
+        }
+        // The registered pointer decides the store and its routing mode. A per-worktree
+        // `autoCommit: false` (hunch init --no-auto-commit) is an explicit local opt-out that
+        // survives; a checkout can never turn auto-commit on.
+        if (shared.privateDir)
+            return { ...shared, autoCommit: perWorktree.autoCommit === false ? false : shared.autoCommit };
         return perWorktree;
     }
+    /** Why a present overlay pointer file blocks this store. */
+    invalidPointerMessage(file, problem) {
+        return `${file} ${problem}, so Hunch refuses to open this repository's memory rather than silently ` +
+            "writing captures to the public .hunch/. Fix the file, or delete it and re-run `hunch private <dir>` (or `hunch shared`) here.";
+    }
+    /** The per-worktree pointer's shape, WITHOUT following any link: "absent" when neither
+     *  it nor a symlink sits there, "plain" for a regular file inside a real `.hunch`
+     *  directory of this checkout, and "unsafe" for anything else that exists (a symlinked
+     *  `local.json`, a directory, or a pointer reachable only through a symlinked `.hunch`). */
+    localPointerFileState(file) {
+        const present = (path) => {
+            try {
+                lstatSync(path);
+                return true;
+            }
+            catch {
+                return false;
+            }
+        };
+        let hunchStat;
+        try {
+            hunchStat = lstatSync(dirname(file));
+        }
+        catch {
+            return "absent";
+        }
+        if (hunchStat.isSymbolicLink())
+            return present(file) ? "unsafe" : "absent";
+        if (!hunchStat.isDirectory())
+            return "absent";
+        let stat;
+        try {
+            stat = lstatSync(file);
+        }
+        catch {
+            return "absent";
+        }
+        return !stat.isSymbolicLink() && stat.isFile() ? "plain" : "unsafe";
+    }
+    /** Whether a per-worktree `.hunch/local.json` naming `privateDir` was registered by this
+     *  machine's own setup rather than shipped with the checkout. The file is gitignored by
+     *  convention only, so a repository or archive can still carry one. Every setup path
+     *  (`hunch init`, `hunch private`, `hunch shared`, `hunch worktree`) also writes the
+     *  pointer in the git common dir, which no clone or checkout content can supply; the
+     *  per-worktree pointer is honored only when that pointer names the same store. */
+    ownsLocalPointer(privateDir, sharedDir) {
+        return !!sharedDir && sameFilesystemEntry(resolve(this.paths.root, privateDir), sharedDir);
+    }
     /** Merged read: public ∪ private overlay (private wins on id collision). Every
      *  QUERY / REINDEX path uses this so MCP + the guards see private memory. Public-
      *  artifact writers keep using this.json.loadAll (public-only) so a private record

package/dist/store/jsonStore.js

@@ -39,7 +39,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;
+/** Reads of ownership metadata that a concurrent release + re-acquire can make
+ *  fail once. A real refusal (hardlink, symlink, oversize) is persistent and
+ *  still throws after the last attempt. */
+const RMW_OWNER_READ_ATTEMPTS = 3;
 function readRmwOwner(lock) {
+    for (let attempt = 1;; attempt++) {
+        try {
+            return readRmwOwnerOnce(lock);
+        }
+        catch (error) {
+            // Residual of the excuse in readRmwOwnerOnce (issue #293, CI run
+            // 35843843780): a release AND re-acquire between the reader's failure and
+            // its re-lstat leaves the next holder's owner file in place, so a refusal
+            // caused only by the race looked real. Re-reading from scratch settles it:
+            // the race does not repeat on demand, an unsafe file does. Retrying never
+            // licenses a steal: the caller still judges the owner it finally reads.
+            if (attempt >= RMW_OWNER_READ_ATTEMPTS)
+                throw error;
+            Atomics.wait(RMW_LOCK_WAITER, 0, 0, 5);
+        }
+    }
+}
+function readRmwOwnerOnce(lock) {
     let text;
     try {
         text = readStoreArtifact(lock, ["owner.tmp.json"], 4096);
@@ -59,10 +81,9 @@ function readRmwOwner(lock) {
         // requires the lock itself to be either gone (the release we are modelling)
         // or a REAL directory that is not a link.
         //
-        // Residual accepted: a release + re-acquire between the reader's failure and
-        // this re-lstat makes a REAL refusal (hardlink/oversize) throw for a file
-        // that already belongs to the next holder. That only turns a retry into an
-        // error — it never licenses a steal, so the safe direction is preserved.
+        // A release + re-acquire between the reader's failure and this re-lstat
+        // finds the next holder's owner file and throws here; readRmwOwner re-reads
+        // from scratch before letting that surface.
         let ownerMissing = false;
         try {
             lstatSync(join(lock, "owner.tmp.json"));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.41.6",
+  "version": "1.42.0",
   "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.41.6",
+  "version": "1.42.0",
   "packages": [
     {
       "registryType": "npm",
       "registryBaseUrl": "https://registry.npmjs.org",
       "identifier": "@davesheffer/hunch",
-      "version": "1.41.6",
+      "version": "1.42.0",
       "runtimeHint": "npx",
       "packageArguments": [
         {