@davesheffer/hunch 1.8.2 → 1.9.2

package/dist/constitution/staticGraphBaseline.js

@@ -0,0 +1,44 @@
+import { CODE_EXTENSIONS } from "../extractors/languages.js";
+import { replacementFreeCommitFiles, replacementFreeExactCommit, replacementFreeIsAncestorOrSame, } from "./replacementFreeGit.js";
+const touchesGraphOrCheckoutInputs = (files) => files.some((file) => CODE_EXTENSIONS.some((extension) => file.endsWith(extension))
+    || file === ".gitattributes"
+    || file.endsWith("/.gitattributes"));
+/** Canonical committed identity for the deterministic static graph.
+ *
+ * Public Hunch pumping creates clone-local commits containing `.hunch/` JSON and
+ * sometimes refreshed grounding docs. Those commits do not change anything the
+ * indexer parses, so binding a shared static receipt to their local SHA makes the
+ * same graph produce different artifact ids in otherwise identical clones. Walk
+ * first-parent until the newest indexed-code or checkout-attribute change instead.
+ * Attributes are a boundary because proof replay validates them before materializing
+ * exact source bytes. A merge is always a boundary: its resolution can change the
+ * effective tree even when a simple diff listing is incomplete. Reverts touch code
+ * and therefore remain distinct. */
+export function canonicalStaticGraphBaseline(root, ref = "HEAD") {
+    const repositoryRef = replacementFreeExactCommit(root, ref);
+    if (!repositoryRef)
+        throw new Error(`static graph baseline needs a resolvable Git commit, got ${ref}`);
+    let current = repositoryRef;
+    const seen = new Set();
+    while (!seen.has(current)) {
+        seen.add(current);
+        if (replacementFreeExactCommit(root, `${current}^2`))
+            return current;
+        if (touchesGraphOrCheckoutInputs(replacementFreeCommitFiles(root, current)))
+            return current;
+        // With no indexed-code commit at all, the repository root is the one
+        // cross-clone-resolvable anchor for the empty static graph. Returning the
+        // caller's docs/memory-only HEAD would reintroduce clone-local receipt churn.
+        const parent = replacementFreeExactCommit(root, `${current}^1`);
+        if (!parent)
+            return current;
+        if (parent === current)
+            return repositoryRef;
+        current = parent;
+    }
+    return current;
+}
+export function isAncestorOrSame(root, ancestor, descendant) {
+    return replacementFreeIsAncestorOrSame(root, ancestor, descendant);
+}
+//# sourceMappingURL=staticGraphBaseline.js.map

package/dist/constitution/structural.js

@@ -1,4 +1,5 @@
-import { basename } from "node:path";
+import { builtinModules } from "node:module";
+import { basename, extname } from "node:path";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { pathMatchesGlob } from "../core/glob.js";
 import { shortHash } from "../core/ids.js";
@@ -9,6 +10,7 @@ import { clampCandidateLimit, durationCutoff } from "./bootstrap.js";
 import { compileStructuralPolicy } from "./compiler.js";
 import { extractStructuralDelta } from "./delta.js";
 import { EvidenceEventSchema, PolicySpecSchema, } from "./schema.js";
+const builtinModuleSpecifiers = new Set(builtinModules);
 const exactSelector = (symbol) => ({ selector: `symbol:${symbol.file}:${symbol.name}` });
 function scopeFor(store, file, publicOnly) {
     const components = (publicOnly ? store.json.loadAll("components") : store.recs("components"))
@@ -20,6 +22,58 @@ function scopeFor(store, file, publicOnly) {
 function candidateId(assertion, scope) {
     return `cand_${shortHash(canonicalHash({ assertion, scope }))}`;
 }
+/** Bind one exact file/package boundary to the existing static import graph.
+ * The file-level fact is anchored to the first stable symbol because the
+ * indexer attaches every external import in a file to every symbol in it. */
+export function inspectExternalImportBoundary(store, file, specifier, opts = {}) {
+    const supportedExtensions = new Set([".ts", ".tsx", ".mts", ".cts", ".js", ".jsx", ".mjs", ".cjs"]);
+    if (!supportedExtensions.has(extname(file).toLowerCase())) {
+        return {
+            candidate: null,
+            reason: `${file} is outside MD-1a's TypeScript/JavaScript static ESM import-declaration projection`,
+            code: "unsupported_file",
+        };
+    }
+    const exactSpecifier = specifier.trim();
+    const dependency = externalPackage(exactSpecifier);
+    const external = externalImportNodeId(exactSpecifier);
+    const exactNpmPackage = /^(?:@[A-Za-z0-9][A-Za-z0-9._~-]*\/)?[A-Za-z0-9][A-Za-z0-9._~-]*$/;
+    if (!dependency || !external || dependency !== exactSpecifier || builtinModuleSpecifiers.has(exactSpecifier)
+        || !exactNpmPackage.test(exactSpecifier)) {
+        return {
+            candidate: null,
+            reason: `${specifier} is not one exact top-level npm package identity; package subpaths, built-ins, and scheme specifiers are unsupported`,
+            code: "unsupported_dependency",
+        };
+    }
+    const symbols = (opts.publicOnly ? store.json.loadAll("symbols") : store.recs("symbols"))
+        .filter((symbol) => symbol.file === file)
+        .sort((left, right) => left.id.localeCompare(right.id));
+    if (!symbols.length)
+        return { candidate: null, reason: `${file} has no exact current symbol to anchor a file-scoped import policy`, code: "missing_anchor" };
+    const edges = opts.publicOnly ? store.json.loadAll("edges") : store.recs("edges");
+    const symbolIds = new Set(symbols.map((symbol) => symbol.id));
+    if (edges.some((edge) => edge.type === "imports" && symbolIds.has(edge.from) && edge.to === external)) {
+        return { candidate: null, reason: `${file} currently imports ${dependency}; fix the baseline before Hunch builds a proof packet`, code: "baseline_violated" };
+    }
+    const assertion = {
+        kind: "not-reaches",
+        subject: exactSelector(symbols[0]),
+        relation: { edges: ["imports"], transitive: false, max_depth: 1 },
+        object: { selector: `external:${dependency}` },
+    };
+    const scope = scopeFor(store, file, !!opts.publicOnly);
+    return {
+        candidate: {
+            id: candidateId(assertion, scope),
+            assertion,
+            scope,
+            basis: "correction-forbidden-import",
+            reason: `human correction forbids direct external package ${dependency} in ${file}`,
+        },
+        reason: null,
+    };
+}
 function alternativeFor(candidate) {
     return {
         id: candidate.id,
@@ -45,16 +99,18 @@ function candidateContext(enumerated, selected, conflicts = [], incumbent = null
         counterexamples: [...new Set(counterexamples)].sort(),
     };
 }
-function structuralKey(policy) {
+export function structuralKey(policy) {
     return canonicalHash({ assertion: policy.assertion, scope: policy.scope, data_class: policy.data_class });
 }
 function scopesOverlap(left, right) {
     const repoOverlap = !left.repos.length || !right.repos.length || left.repos.some((repo) => right.repos.includes(repo));
-    const pathOverlap = !left.paths.length || !right.paths.length || left.paths.some((path) => right.paths.includes(path));
+    const pathOverlap = !left.paths.length || !right.paths.length || left.paths.some((leftPath) => right.paths.some((rightPath) => leftPath === rightPath
+        || pathMatchesGlob(leftPath, rightPath)
+        || pathMatchesGlob(rightPath, leftPath)));
     const componentOverlap = !left.components.length || !right.components.length || left.components.some((component) => right.components.includes(component));
     return repoOverlap && pathOverlap && componentOverlap;
 }
-function directConflict(candidate, incumbent) {
+export function directConflict(candidate, incumbent) {
     const left = candidate.assertion;
     const right = incumbent.assertion;
     if (!((left.kind === "reaches" && right.kind === "not-reaches") || (left.kind === "not-reaches" && right.kind === "reaches")))

package/dist/core/autoreview.js

@@ -48,7 +48,7 @@ export function planAutoReview(drafts, allDecisions, verdicts, cfg = {}) {
     }
     return plan;
 }
-/** Total drafts the plan would mutate (accept + both delete buckets). */
+/** Total drafts the plan would mutate (accept + both rejection buckets). */
 export function planMutations(plan) {
     return plan.accept.length + plan.rejectDuplicate.length + plan.rejectIrrelevant.length;
 }

package/dist/core/canonicalOrder.js

@@ -0,0 +1,6 @@
+/** Locale-free UTF-16 code-unit ordering for content-addressed artifacts.
+ * Never use localeCompare where ordering contributes to a hash or selection. */
+export function compareCodeUnits(left, right) {
+    return left < right ? -1 : left > right ? 1 : 0;
+}
+//# sourceMappingURL=canonicalOrder.js.map

package/dist/core/conformance.js

@@ -1,56 +1,97 @@
-function resolveSymbol(store, ref) {
-    const syms = store.recs("symbols");
+function resolveSymbols(graph, ref) {
+    const syms = graph.symbols;
     if (ref.startsWith("sym_"))
-        return syms.find((s) => s.id === ref) ?? null;
+        return syms.filter((s) => s.id === ref);
     if (ref.includes(":")) {
-        const [f, n] = ref.split(":");
-        return syms.find((s) => s.name === n && (s.file === f || s.file.endsWith("/" + (f ?? "")))) ?? null;
+        const split = ref.lastIndexOf(":");
+        const file = ref.slice(0, split);
+        const name = ref.slice(split + 1);
+        return syms.filter((s) => s.name === name && (s.file === file || s.file.endsWith("/" + file)));
     }
-    return syms.find((s) => s.name === ref) ?? null;
+    return syms.filter((s) => s.name === ref);
 }
-function reaches(store, id, transitive) {
-    const set = new Set();
-    for (const d of store.getDependencies(id, transitive ? 6 : 1)) {
-        if (transitive || d.depth === 1)
-            set.add(d.id);
+function reaches(graph, id, transitive) {
+    const reached = new Set();
+    const seen = new Set([id]);
+    const queue = [{ id, depth: 0 }];
+    const maxDepth = transitive ? 6 : 1;
+    const traversable = new Set(["calls", "depends_on", "imports", "contains"]);
+    const outgoing = new Map();
+    for (const edge of graph.edges) {
+        if (!traversable.has(edge.type))
+            continue;
+        const targets = outgoing.get(edge.from) ?? [];
+        targets.push(edge.to);
+        outgoing.set(edge.from, targets);
     }
-    return set;
+    while (queue.length) {
+        const current = queue.shift();
+        if (current.depth >= maxDepth)
+            continue;
+        for (const next of outgoing.get(current.id) ?? []) {
+            reached.add(next);
+            if (seen.has(next))
+                continue;
+            seen.add(next);
+            queue.push({ id: next, depth: current.depth + 1 });
+        }
+    }
+    return reached;
 }
-function evalPredicate(store, d, p) {
+function evalPredicate(graph, d, p) {
     const base = { decision: d.id, title: d.title, assert: p.assert, subject: p.subject, object: p.object };
-    const subj = resolveSymbol(store, p.subject);
+    const subjects = resolveSymbols(graph, p.subject);
     if (p.assert === "exists") {
-        return { ...base, satisfied: !!subj, detail: subj ? `${p.subject} exists (${subj.file})` : `${p.subject} no longer exists in the graph` };
+        return { ...base, satisfied: subjects.length > 0, detail: subjects.length ? `${p.subject} exists (${subjects.map((subject) => subject.file).join(", ")})` : `${p.subject} no longer exists in the graph` };
     }
-    if (!subj)
+    if (!subjects.length)
         return { ...base, satisfied: false, detail: `subject "${p.subject}" not found in the graph — intent's subject is gone` };
     const wantReach = p.assert === "calls" || p.assert === "imports";
-    const obj = p.object ? resolveSymbol(store, p.object) : null;
-    if (!obj) {
+    const objects = p.object ? resolveSymbols(graph, p.object) : [];
+    if (!objects.length) {
         // a required target gone ⇒ the link can't hold (violated); a forbidden one trivially holds.
         return { ...base, satisfied: !wantReach, detail: `target "${p.object ?? ""}" not found in the graph` };
     }
-    const linked = reaches(store, subj.id, p.transitive).has(obj.id);
+    // A required relation cannot guess which same-name symbol carries the intent.
+    // Force qualification instead of accidentally proving a different binding.
+    if (wantReach && (subjects.length !== 1 || objects.length !== 1)) {
+        return {
+            ...base,
+            satisfied: false,
+            detail: `ambiguous required binding (${subjects.length} subject, ${objects.length} target matches) — qualify as file:symbol; intent VIOLATED`,
+        };
+    }
+    // A forbidden relation is conservative in the other direction: ANY matching
+    // subject reaching ANY same-name target is a real counterexample. Looking at
+    // only the first target lets a duplicate symbol hide a violation.
+    const linked = subjects.some((subject) => {
+        const reached = reaches(graph, subject.id, p.transitive);
+        return objects.some((object) => reached.has(object.id));
+    });
     const satisfied = wantReach ? linked : !linked;
     const via = p.transitive ? " (transitively)" : "";
     const detail = satisfied
         ? wantReach
-            ? `${subj.name} →${via} ${obj.name} ✓`
-            : `${subj.name} does not reach ${obj.name} ✓`
+            ? `${p.subject} →${via} ${p.object} ✓`
+            : `${p.subject} does not reach ${p.object} ✓`
         : wantReach
-            ? `${subj.name} no longer reaches${via} ${obj.name} — intent VIOLATED`
-            : `${subj.name} now reaches${via} ${obj.name} — intent VIOLATED`;
+            ? `${p.subject} no longer reaches${via} ${p.object} — intent VIOLATED`
+            : `${p.subject} now reaches${via} ${p.object} — intent VIOLATED`;
     return { ...base, satisfied, detail };
 }
 /** Check every in-force decision's conformance predicates against the CURRENT graph.
- *  `.satisfied === false` means the code drifted from the recorded intent. Deterministic. */
-export function checkConformance(store) {
+ *  `.satisfied === false` means the code drifted from the recorded intent. Deterministic.
+ *  `publicOnly` selects every input at the JSON read boundary so a private decision,
+ *  symbol, or edge can never influence (or be rendered into) a public CI receipt. */
+export function checkConformance(store, opts = {}) {
+    const load = (kind) => opts.publicOnly ? store.json.loadAll(kind) : store.recs(kind);
+    const graph = opts.graph ?? { symbols: load("symbols"), edges: load("edges") };
     const out = [];
-    for (const d of store.recs("decisions")) {
+    for (const d of load("decisions")) {
         if (d.status === "superseded" || d.superseded_by)
             continue; // in-force decisions only
         for (const p of d.conformance ?? [])
-            out.push(evalPredicate(store, d, p));
+            out.push(evalPredicate(graph, d, p));
     }
     return out;
 }

package/dist/core/docscan.js

@@ -19,6 +19,7 @@ import { readFileSync, readdirSync, existsSync } from "node:fs";
 import { join, extname } from "node:path";
 import { parseDocAnchors } from "./docanchors.js";
 import { currentForTopic } from "./topics.js";
+import { compareCodeUnits } from "./canonicalOrder.js";
 export const STALE_MARKER = /\b(proposed|not yet implemented|no code yet)\b/i;
 export const SRC_REF = /\bsrc\/[A-Za-z0-9_\-/]+\.ts\b/g;
 const SKIP_DIRS = new Set(["node_modules", ".git", ".hunch", ".hunch-private", "dist", "vscode-extension", "site"]);
@@ -111,6 +112,6 @@ export function scanRepoDocs(decisions, root) {
         const title = /^#\s+(.+)$/m.exec(text)?.[1]?.trim() ?? doc.rel;
         out.push({ rel: doc.rel, title, topics, srcRefs, status, issues });
     }
-    return out.sort((a, b) => a.rel.localeCompare(b.rel));
+    return out.sort((a, b) => compareCodeUnits(a.rel, b.rel));
 }
 //# sourceMappingURL=docscan.js.map

package/dist/core/escalations.js

@@ -46,6 +46,17 @@ export function policyEscalations(policies) {
             });
         }
         else if (p.state === "proposed") {
+            if (p.activation_gate?.status === "blocked") {
+                out.push({
+                    kind: "policy-proposal",
+                    topic: p.id,
+                    decisionIds: [p.id],
+                    question: `Proposed rule "${clip(p.statement)}" (${p.id}) is ready for review but mechanically blocked from activation — keep it as evidence?`,
+                    detail: `state proposed · ${p.proof ? `proof ${p.proof}` : "no proof"} · authority none · activation gate ${p.activation_gate.kind}`,
+                    resolution: `inspect: hunch policy card ${p.id} — activation remains unavailable until the source-currentness gate is implemented and cleared`,
+                });
+                continue;
+            }
             out.push({
                 kind: "policy-proposal",
                 topic: p.id,

package/dist/core/io.js

@@ -1,15 +1,18 @@
 /** Durable file writes for the Hunch. */
-import { writeFileSync, renameSync, rmSync } from "node:fs";
+import { linkSync, writeFileSync, renameSync, rmSync } from "node:fs";
 let counter = 0;
+const renameRetryDelaysMs = [10, 20, 40, 80];
+const renameRetryWaiter = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
 /**
  * Write `data` to `file` via a temp file + rename, so an interrupted write can't
  * leave the target truncated (the symbols/edges index is the worst to half-write).
  *
  * Windows caveat: renameSync can't REPLACE a file another process holds open (even
  * for read) — it throws EPERM/EBUSY/EACCES, exactly when the MCP server is reading
- * while a CLI writes. Atomicity is crash-safety insurance, not worth FAILING a write
- * the old in-place writeFileSync would have completed — so we fall back to a direct
- * write there. The temp file is always cleaned up; a failed write never leaks it.
+ * while a CLI writes. Retry that atomic replacement with bounded backoff. If the
+ * contention persists, fail with the old target untouched; never trade availability
+ * for a direct write that an interruption could truncate. Failed writes clean up the
+ * temporary file.
  */
 export function writeFileAtomic(file, data) {
     const tmp = `${file}.tmp${process.pid}.${counter++}`;
@@ -21,16 +24,48 @@ export function writeFileAtomic(file, data) {
         throw e;
     }
     try {
-        renameSync(tmp, file);
+        renameWithContentionRetry(tmp, file);
     }
     catch (e) {
         safeRm(tmp);
-        const code = e.code;
-        if (code === "EPERM" || code === "EBUSY" || code === "EACCES") {
-            writeFileSync(file, data); // non-atomic fallback (matches pre-hardening behavior)
+        throw e;
+    }
+}
+function renameWithContentionRetry(from, to) {
+    for (let attempt = 0;; attempt++) {
+        try {
+            renameSync(from, to);
             return;
         }
-        throw e;
+        catch (error) {
+            const delayMs = renameRetryDelaysMs[attempt];
+            if (delayMs === undefined || !isRenameContention(error))
+                throw error;
+            Atomics.wait(renameRetryWaiter, 0, 0, delayMs);
+        }
+    }
+}
+function isRenameContention(error) {
+    const code = error.code;
+    return code === "EPERM" || code === "EBUSY" || code === "EACCES";
+}
+/** Atomically create a complete file only when no target exists. A same-dir
+ * hard link publishes the fully written temp inode with create-if-absent
+ * semantics, so concurrent lifecycle writers can never be overwritten. */
+export function writeFileAtomicIfAbsent(file, data) {
+    const tmp = `${file}.tmp${process.pid}.${counter++}`;
+    try {
+        writeFileSync(tmp, data);
+        linkSync(tmp, file);
+        return true;
+    }
+    catch (error) {
+        if (error.code === "EEXIST")
+            return false;
+        throw error;
+    }
+    finally {
+        safeRm(tmp);
     }
 }
 function safeRm(p) {

package/dist/core/overlaySafety.js

@@ -0,0 +1,178 @@
+import { existsSync, lstatSync, readdirSync, realpathSync } from "node:fs";
+import { isAbsolute, join, relative, resolve, sep } from "node:path";
+import { ENTITY_KINDS } from "./types.js";
+function pathIsWithin(path, parent) {
+    const rel = relative(parent, path);
+    return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+/** Validate the materialized overlay without following links. Git's metadata is
+ * deliberately skipped, but its own directory must still be contained under the
+ * canonical overlay root. Every remotely controlled entry must be an ordinary
+ * file or real directory whose canonical path stays inside that root. */
+export function safeOverlayTree(root) {
+    try {
+        const lexicalRoot = resolve(root);
+        const rootStat = lstatSync(lexicalRoot);
+        if (rootStat.isSymbolicLink() || !rootStat.isDirectory())
+            return false;
+        const canonicalRoot = realpathSync(lexicalRoot);
+        const walk = (dir, topLevel = false) => {
+            const dirStat = lstatSync(dir);
+            if (dirStat.isSymbolicLink() || !dirStat.isDirectory())
+                return false;
+            if (!pathIsWithin(realpathSync(dir), canonicalRoot))
+                return false;
+            for (const name of readdirSync(dir)) {
+                const entry = join(dir, name);
+                const stat = lstatSync(entry);
+                if (stat.isSymbolicLink())
+                    return false;
+                if (!pathIsWithin(realpathSync(entry), canonicalRoot))
+                    return false;
+                if (topLevel && (name === ".gitignore" || name === ".gitattributes")
+                    && (!stat.isFile() || stat.nlink !== 1))
+                    return false;
+                if (topLevel && name === ".hunch" && !stat.isDirectory())
+                    return false;
+                if (topLevel && name === ".git") {
+                    if (!stat.isDirectory())
+                        return false;
+                    continue;
+                }
+                if (stat.isDirectory()) {
+                    if (!walk(entry))
+                        return false;
+                }
+                else if (!stat.isFile()) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        if (!walk(lexicalRoot, true))
+            return false;
+        const hunchDir = join(lexicalRoot, ".hunch");
+        if (existsSync(hunchDir)) {
+            for (const kind of ENTITY_KINDS) {
+                const kindDir = join(hunchDir, kind);
+                if (existsSync(kindDir) && !lstatSync(kindDir).isDirectory())
+                    return false;
+            }
+            for (const name of ["manifest.json", "config.json"]) {
+                const file = join(hunchDir, name);
+                if (existsSync(file) && !lstatSync(file).isFile())
+                    return false;
+            }
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/** Validate `git ls-tree -r -t -z <exact-oid>` output before checkout. A Git
+ * remote can encode symlinks (120000) and gitlinks (160000); accepting only
+ * ordinary blobs and trees makes the fetched object graph safe to materialize.
+ * The explicit Hunch topology rules keep canonical record directories and
+ * capability/config paths from changing shape on a later pull. */
+export function safeOverlayGitTreeListing(listing) {
+    const entries = new Map();
+    for (const row of listing.split("\0")) {
+        if (!row)
+            continue;
+        const tab = row.indexOf("\t");
+        if (tab <= 0)
+            return false;
+        const header = row.slice(0, tab).match(/^([0-7]{6}) (blob|tree|commit) ([0-9a-f]+)$/);
+        if (!header)
+            return false;
+        const path = row.slice(tab + 1);
+        const segments = path.split("/");
+        if (!path || path.startsWith("/") || path.includes("\\")
+            || segments.some((segment) => !segment || segment === "." || segment === ".."
+                || segment.toLowerCase() === ".git" || segment === ".hunch-commit.lock")) {
+            return false;
+        }
+        // These are clone-local/derived runtime artifacts, never graph source of
+        // truth. Accepting a tracked pointer can disclose or redirect a machine's
+        // private store; tracked SQLite/temp/cache artifacts poison the clean-tree
+        // and additive-publication contracts on every later request.
+        if (path === ".hunch/local.json"
+            || path === ".hunch-cache" || path.startsWith(".hunch-cache/")
+            || /^\.hunch\/[^/]+\.sqlite[^/]*$/i.test(path)
+            || (path.startsWith(".hunch/") && segments.slice(1).some((segment) => segment.includes(".tmp")))) {
+            return false;
+        }
+        const mode = header[1];
+        const type = header[2];
+        const ordinaryTree = mode === "040000" && type === "tree";
+        const ordinaryBlob = (mode === "100644" || mode === "100755") && type === "blob";
+        if (!ordinaryTree && !ordinaryBlob)
+            return false;
+        if (entries.has(path))
+            return false;
+        entries.set(path, type);
+    }
+    const isTree = (path) => !entries.has(path) || entries.get(path) === "tree";
+    const isBlob = (path) => !entries.has(path) || entries.get(path) === "blob";
+    if (!isTree(".hunch"))
+        return false;
+    for (const kind of ENTITY_KINDS)
+        if (!isTree(`.hunch/${kind}`))
+            return false;
+    for (const path of [".gitattributes", ".gitignore", ".hunch/manifest.json", ".hunch/config.json"]) {
+        if (!isBlob(path))
+            return false;
+    }
+    return true;
+}
+/** A dedicated Hunch overlay needs exactly one attribute capability: selecting
+ * the locally installed `merge=hunch` JSON merge driver, plus Hunch's exact
+ * `.hunch/manifest.json merge=text` override (the manifest has no record id and
+ * must use Git's built-in text merge). Reject every other token/pattern pair,
+ * including byte-transforming built-ins such as `ident` and
+ * `working-tree-encoding`, rather than maintaining a command-key blacklist.
+ * Blank lines and comments remain harmless. */
+export function hunchAttributesAreSafe(content) {
+    for (const line of content.split(/\r?\n/)) {
+        const candidate = line.trimStart();
+        if (!candidate || candidate.startsWith("#"))
+            continue;
+        const fields = candidate.split(/\s+/);
+        if (fields.length < 2)
+            return false;
+        const attributes = fields.slice(1);
+        if (attributes.every((attribute) => attribute === "merge=hunch"))
+            continue;
+        if (fields[0] === ".hunch/manifest.json"
+            && attributes.every((attribute) => attribute === "merge=text"))
+            continue;
+        return false;
+    }
+    return true;
+}
+/** Validate every committed .gitattributes blob in an already-safe ls-tree
+ * listing. Blob loading is injected so clone and later-pull seams share one
+ * parser without either trusting worktree bytes before materialization. */
+export function hunchTreeAttributesAreSafe(listing, readBlob) {
+    if (!safeOverlayGitTreeListing(listing))
+        return false;
+    for (const row of listing.split("\0")) {
+        if (!row)
+            continue;
+        const tab = row.indexOf("\t");
+        if (tab < 1)
+            return false;
+        const header = row.slice(0, tab).match(/^100(?:644|755) blob ([0-9a-f]{40,64})$/i);
+        const path = row.slice(tab + 1);
+        if (path !== ".gitattributes" && !path.endsWith("/.gitattributes"))
+            continue;
+        if (!header)
+            return false;
+        const content = readBlob(header[1]);
+        if (content === null || !hunchAttributesAreSafe(content))
+            return false;
+    }
+    return true;
+}
+//# sourceMappingURL=overlaySafety.js.map

package/dist/core/paths.js

@@ -1,6 +1,6 @@
 /** Filesystem layout for the Hunch (DESIGN.md §6 folder structure). */
 import { join } from "node:path";
-import { existsSync, statSync } from "node:fs";
+import { existsSync, realpathSync, statSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 export const HUNCH_DIR = ".hunch";
 /** Canonicalize a free-form path/target to repo-relative POSIX form. Hunch stores
@@ -27,7 +27,18 @@ export function hunchPaths(root) {
  *  PRIVATE overlay store (HUNCH_PRIVATE_DIR), which lives in a separate repo the
  *  user controls rather than under the current repo's `.hunch/`. */
 export function hunchPathsForDir(hunchDir) {
-    const hunch = resolve(hunchDir);
+    const lexical = resolve(hunchDir);
+    // An explicitly configured PRIVATE overlay may intentionally be a
+    // final-component symlink to a distinct physical repository. Resolve that
+    // user-selected root before handing it to JsonStore; public hunchPaths()
+    // deliberately does not do this, so a committed public `.hunch` symlink and
+    // every kind/record symlink remain fail-closed.
+    let hunch = lexical;
+    try {
+        if (statSync(lexical).isDirectory())
+            hunch = realpathSync(lexical);
+    }
+    catch { /* missing overlay root is created at the lexical location */ }
     return {
         root: dirname(hunch),
         hunch,