@davesheffer/hunch 1.10.0 → 1.10.2

package/dist/mcp/roots.js

@@ -5,10 +5,26 @@
  * another workspace or linked worktree. MCP roots are the client-neutral protocol
  * mechanism for following that change.
  */
-import { statSync } from "node:fs";
+import { realpathSync, statSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { findRoot, HUNCH_DIR, isDir } from "../core/paths.js";
+/** One canonical spelling per directory. `findRoot` only resolve()s, but a
+ *  client's roots/list URI can spell the same repo differently — VS Code sends
+ *  a lowercase drive letter (`c:\…`) while the spawn cwd has `C:\…`, and Git
+ *  for Windows can surface 8.3/short names. Raw string comparison then treats
+ *  ONE repo as different roots: a full re-prepare (new store + reindex) on
+ *  every connect, or a false "multiple roots equally plausible" refusal
+ *  (issue #54). realpathSync.native returns the on-disk spelling for all of
+ *  these; fall back to the input when the path is transiently unreadable. */
+export function canonicalRootPath(root) {
+    try {
+        return realpathSync.native(root);
+    }
+    catch {
+        return root;
+    }
+}
 function toPath(uri) {
     if (!uri.startsWith("file:"))
         return "";
@@ -44,12 +60,12 @@ export function resolveActiveRoot(rootUris, fallbackCwd) {
         const start = rootStart(toPath(uri));
         if (!start)
             continue;
-        const root = findRoot(start);
+        const root = canonicalRootPath(findRoot(start));
         if (!candidates.includes(root))
             candidates.push(root);
     }
     if (!candidates.length)
-        return findRoot(fallbackCwd);
+        return canonicalRootPath(findRoot(fallbackCwd));
     if (candidates.length === 1)
         return candidates[0];
     const withStore = candidates.filter((candidate) => isDir(join(candidate, HUNCH_DIR)));

package/dist/mcp/server.js

@@ -11,7 +11,7 @@ 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 { canonicalRootPath, resolveActiveRoot } from "./roots.js";
 import { HunchStore } from "../store/hunchStore.js";
 import { selectEmbedder } from "../store/embedder.js";
 import { decisionId, findingId } from "../core/ids.js";
@@ -278,8 +278,11 @@ export function buildServerWithRootControl(initialRoot) {
     let pendingScheduled = false;
     let closed = false;
     const activateRoot = (next) => {
-        const canonical = findRoot(next);
-        if (canonical === root)
+        // canonicalRootPath: a case/8.3 spelling difference must not read as a
+        // DIFFERENT repo — that closed the live store and re-prepared everything
+        // on every same-repo client connect (issue #54).
+        const canonical = canonicalRootPath(findRoot(next));
+        if (canonical === canonicalRootPath(root))
             return;
         const prepared = prepareRoot(canonical, explicitOverlay, true);
         const previous = store;
@@ -386,12 +389,18 @@ export function buildServerWithRootControl(initialRoot) {
                 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 */ }
             }
+            // Stamp check in EVERY mode, not only shared: a CLI capture or post-commit
+            // hook in another terminal writes JSON that mtime-invalidated loadAll sees
+            // immediately, while the SQLite FTS/graph index this long-lived process
+            // serves would stay frozen at startup — split-brain answers within one
+            // session (JSON-backed tools fresh, query/structure/dependents stale)
+            // until restart (issue #49).
+            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.");
@@ -1518,6 +1527,7 @@ export function buildServerWithRootControl(initialRoot) {
         server,
         getRoot: () => root,
         setRoot,
+        cancelPendingRoot: () => { pendingRoot = null; },
     };
 }
 /** Back-compatible server construction for tests and callers that do not need
@@ -1546,6 +1556,14 @@ export function wireClientRoots(control, fallback) {
                 return;
             const next = resolveActiveRoot((response?.roots ?? []).map((root) => root.uri), fallback);
             if (!next) {
+                // Cancel a swap parked by an EARLIER generation. setRoot defers when a tool
+                // request is in flight; if the client's advertised set has since become
+                // ambiguous, applying that stale swap once the request drains would re-home
+                // to a repo the client no longer unambiguously advertises — writing (and
+                // auto-committing) a capture into the wrong repository, which is precisely
+                // what this refusal exists to prevent. Without this the message below was
+                // also a lie: the root did NOT stay put.
+                control.cancelPendingRoot();
                 console.error("[hunch-mcp] multiple client roots are equally plausible; keeping the current Hunch root");
                 return;
             }

package/dist/store/compact.js

@@ -58,6 +58,12 @@ export function planCompaction(input, opts) {
                 continue; // d is being removed → its references don't count
             if (d.supersedes)
                 refDec.add(d.supersedes);
+            // superseded_by is a reference too: supersedeIn() sets old.superseded_by
+            // without requiring the successor's `supersedes`, so removing a later-
+            // rejected successor would leave the surviving record with a dangling
+            // pointer AND permanently non-live for its topic (issue #36).
+            if (d.superseded_by)
+                refDec.add(d.superseded_by);
             if (d.caused_by_bug)
                 refBug.add(d.caused_by_bug);
         }

package/dist/store/hunchStore.js

@@ -760,11 +760,14 @@ export class HunchStore {
         const symbols = this.recs("symbols");
         const components = this.recs("components");
         const asOf = opts.asOf;
-        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || s.file.endsWith(target));
+        // pathRelated, not bare endsWith: "scenario.ts".endsWith("io.ts") is true,
+        // so an unanchored suffix pulled unrelated files' records into why()/the
+        // pre-edit grounding block (issue #32). Segment-anchored matching only.
+        const matchedSymbols = symbols.filter((s) => s.file === target || s.name === target || s.id === target || pathRelated(s.file, target));
         const symIds = new Set(matchedSymbols.map((s) => s.id));
         const fileSet = new Set(matchedSymbols.map((s) => s.file));
         const isPath = target.includes("/") || target.includes(".");
-        const fileMatch = (files) => files.some((f) => f === target || (isPath && (f.endsWith(target) || target.endsWith(f))) || fileSet.has(f));
+        const fileMatch = (files) => files.some((f) => f === target || (isPath && pathRelated(f, target)) || fileSet.has(f));
         return {
             target,
             decisions: decisions.filter((d) => (fileMatch(d.related_files) || d.related_components.some((c) => components.find((x) => x.id === c && fileMatch(x.paths))))
@@ -1525,7 +1528,9 @@ const RRF_W_GRAPH = numEnv("HUNCH_RRF_W_GRAPH", 0.5);
 const GRAPH_GAMMA = numEnv("HUNCH_GRAPH_GAMMA", 0.25);
 function numEnv(name, dflt) {
     const v = Number(process.env[name]);
-    return Number.isFinite(v) && v > 0 ? v : dflt;
+    // >= 0, not > 0: zero is the documented kill-switch (HUNCH_RRF_W_*=0 disables
+    // a stream); rejecting it silently re-enabled the default weight (issue #33).
+    return Number.isFinite(v) && v >= 0 ? v : dflt;
 }
 /** Pack a vector's exact bytes for SQLite. Explicit offset+length so a SUBARRAY
  *  view (byteOffset != 0) writes only its slice, not the whole backing buffer.

package/dist/store/jsonStore.js

@@ -14,6 +14,9 @@ import { writeFileAtomic } from "../core/io.js";
  *  constraints) are one file per record so they're cleanly reviewable in PRs. */
 const SINGLE_FILE = { symbols: "index.json", edges: "index.json" };
 const encode = (v) => JSON.stringify(v, null, 2) + "\n";
+// Sleep primitive for the single-file RMW lock's bounded spin (issue #35);
+// same idiom as core/io.ts's rename backoff.
+const RMW_LOCK_WAITER = new Int32Array(new SharedArrayBuffer(Int32Array.BYTES_PER_ELEMENT));
 /** Curated entities are intentionally small, human-reviewable records. Symbols
  * and edges are dense indexes, so they get a much larger but still finite cap. */
 export const MAX_JSON_RECORD_BYTES = 8 * 1024 * 1024;
@@ -389,6 +392,14 @@ export class JsonStore {
                 const text = this.readContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
                 if (text === null)
                     continue;
+                // A 0-byte per-record file is a merge-driver TOMBSTONE, not a record:
+                // git cannot delete through a merge driver, so "both sides deleted" is
+                // materialized as an empty %A (issue #37). Human-approved refinement of
+                // con_947c578b2c's boundary (2026-08-04): an empty file holds no record
+                // to migrate or drop, and Hunch's own atomic writes (con_902759b3dc)
+                // never produce one — emptiness is unambiguous, so no warning.
+                if (text.trim() === "")
+                    continue;
                 raw = JSON.parse(text);
             }
             catch (e) {
@@ -403,6 +414,49 @@ export class JsonStore {
         }
         return out;
     }
+    /** Cross-process mutex for single-file index read-modify-write (issue #35).
+     *  The long-lived MCP server and CLI hooks write the same `.hunch/` concurrently;
+     *  two unsynchronized RMWs over index.json each read the same base array and the
+     *  second rename silently erases the first's record. `mkdirSync` is the atomic
+     *  acquire (EEXIST = held). A stale lock (killed process) is taken over by age;
+     *  against a live contender we wait briefly and then proceed WITH a warning —
+     *  never worse than the historical lockless behavior, and capture paths must not
+     *  start throwing on lock contention. */
+    withSingleFileLock(kind, directory, fn) {
+        const lock = join(directory.lexical, ".rmw-lock");
+        const deadline = Date.now() + 2_000;
+        for (;;) {
+            try {
+                mkdirSync(lock);
+                break;
+            }
+            catch {
+                try {
+                    if (Date.now() - lstatSync(lock).mtimeMs > 10_000) {
+                        rmSync(lock, { recursive: true, force: true }); // no live spawn holds a lock this old
+                        continue;
+                    }
+                }
+                catch {
+                    continue; /* vanished between attempts — retry the acquire */
+                }
+                if (Date.now() >= deadline) {
+                    console.warn(`[hunch] proceeding without the ${kind} index lock (still held: ${lock})`);
+                    return fn();
+                }
+                Atomics.wait(RMW_LOCK_WAITER, 0, 0, 25);
+            }
+        }
+        try {
+            return fn();
+        }
+        finally {
+            try {
+                rmSync(lock, { recursive: true, force: true });
+            }
+            catch { /* stale-takeover reclaims it */ }
+        }
+    }
     /** Write a single record (validated) to its JSON file / into the index array. */
     put(kind, record) {
         const schema = SCHEMAS[kind];
@@ -416,11 +470,14 @@ export class JsonStore {
             // record can't silently drop schema-invalid / future-schema siblings — the
             // same reason delete() reads raw. Keep the index sorted by id (stable diff,
             // and agrees with the merge driver so a re-index after a merge is a no-op).
-            const f = this.fileFor(kind, validated.id);
-            const arr = this.readRawArray(kind, directory, f).filter((r) => r?.id !== validated.id);
-            arr.push(validated);
-            arr.sort((a, b) => String(a?.id).localeCompare(String(b?.id)));
-            this.writeContainedFile(directory, f, encode(arr), this.maxBytes(kind));
+            // Locked: the read-modify-write below is what issue #35 races.
+            this.withSingleFileLock(kind, directory, () => {
+                const f = this.fileFor(kind, validated.id);
+                const arr = this.readRawArray(kind, directory, f).filter((r) => r?.id !== validated.id);
+                arr.push(validated);
+                arr.sort((a, b) => String(a?.id).localeCompare(String(b?.id)));
+                this.writeContainedFile(directory, f, encode(arr), this.maxBytes(kind));
+            });
         }
         else {
             this.writeContainedFile(directory, this.fileFor(kind, validated.id), encode(validated), this.maxBytes(kind));
@@ -446,19 +503,27 @@ export class JsonStore {
             this.writeContainedFile(directory, this.fileFor(kind, "index"), encode(validated), this.maxBytes(kind));
             return;
         }
-        // One file per record: preflight EVERY existing JSON file before deleting
+        // One file per record: preflight EVERY existing JSON file before touching
         // any, so one malicious symlink cannot cause a partially-cleared store.
         const existing = this.jsonFileNames(kind);
         for (const name of existing) {
             this.validateExistingFile(directory, join(directory.lexical, name), this.maxBytes(kind));
         }
-        for (const name of existing) {
-            this.removeContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
-        }
+        // WRITE-FIRST, delete-stale-LAST (issue #30). The old delete-all-then-rewrite
+        // sequence had a crash window in which the kind directory held nothing — and
+        // `hunch private --migrate` runs replaceAll on the OVERLAY, so that window
+        // covered private-only records existing nowhere else. Now a crash mid-write
+        // leaves old ∪ new (same id → same file, so no duplicates), and a crash
+        // mid-delete leaves only stale extras — no state loses records.
+        const keep = new Set(validated.map((r) => `${r.id}.json`));
         for (const r of validated) {
             const id = r.id;
             this.writeContainedFile(directory, this.fileFor(kind, id), encode(r), this.maxBytes(kind));
         }
+        for (const name of existing) {
+            if (!keep.has(name))
+                this.removeContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
+        }
     }
     /** Read a single-file index as a raw array (no validation). Missing/empty → [].
      *  A non-empty file that fails to parse THROWS — we must never silently treat a
@@ -482,6 +547,29 @@ export class JsonStore {
     get(kind, id) {
         return this.loadAll(kind).find((r) => r.id === id);
     }
+    /** On-disk record count, independent of validation: per-record kinds count
+     *  every non-tombstone .json file (a 0-byte merge tombstone is an intentional
+     *  absence), single-file kinds count raw array entries (a corrupt index file
+     *  throws readRawArray's own actionable refusal). Lets a caller about to
+     *  DELETE the kind — `hunch private --migrate` — prove the validating loader
+     *  dropped nothing first, instead of silently destroying the records loadAll
+     *  skipped (issue #29, the same never-silently-drop contract as
+     *  con_947c578b2c). */
+    rawRecordCount(kind) {
+        const directory = this.safeKindDirectory(kind, false);
+        if (!directory)
+            return 0;
+        const single = SINGLE_FILE[kind];
+        if (single)
+            return this.readRawArray(kind, directory, join(directory.lexical, single)).length;
+        let count = 0;
+        for (const name of this.jsonFileNames(kind)) {
+            const text = this.readContainedFile(directory, join(directory.lexical, name), this.maxBytes(kind));
+            if (text !== null && text.trim() !== "")
+                count++;
+        }
+        return count;
+    }
     /** Remove a record (used by the curate/reject flow). Returns true if removed.
      *  For single-file kinds we operate on the RAW JSON array (not the validating
      *  loader) so deleting one record can't silently drop schema-invalid siblings. */
@@ -491,16 +579,20 @@ export class JsonStore {
             const directory = this.safeKindDirectory(kind, false);
             if (!directory)
                 return false;
-            const f = this.fileFor(kind, "index");
-            const arr = this.readRawArray(kind, directory, f);
-            if (!this.validateExistingFile(directory, f, this.maxBytes(kind)))
-                return false;
-            const next = arr.filter((r) => r?.id !== id);
-            if (next.length === arr.length)
-                return false;
-            this.writeContainedFile(directory, f, encode(next), this.maxBytes(kind));
-            this.invalidate(kind);
-            return true;
+            // Locked like put(): an unsynchronized delete racing a concurrent put
+            // over the same index would resurrect or drop records (issue #35).
+            return this.withSingleFileLock(kind, directory, () => {
+                const f = this.fileFor(kind, "index");
+                const arr = this.readRawArray(kind, directory, f);
+                if (!this.validateExistingFile(directory, f, this.maxBytes(kind)))
+                    return false;
+                const next = arr.filter((r) => r?.id !== id);
+                if (next.length === arr.length)
+                    return false;
+                this.writeContainedFile(directory, f, encode(next), this.maxBytes(kind));
+                this.invalidate(kind);
+                return true;
+            });
         }
         this.assertSafeRecordId(id);
         const directory = this.safeKindDirectory(kind, false);

package/dist/store/privateMigrate.js

@@ -21,6 +21,18 @@ export function movePublicMemoryToPrivate(pub, priv) {
     let total = 0;
     for (const kind of ENTITY_KINDS) {
         const pubRecs = pub.loadAll(kind);
+        // The validating loader SKIPS corrupt/invalid/future-schema records with a
+        // warning — but the CLI empties the public store right after this returns,
+        // which would silently DELETE exactly those skipped records (and then
+        // untrack + gitignore their only git history). Refuse instead: prove every
+        // on-disk record actually loaded before anything becomes deletable
+        // (issue #29). A kind whose only records are invalid also stops here, so
+        // the "0 loaded → skip merge" path below can never precede a wipe.
+        const rawCount = pub.rawRecordCount(kind);
+        if (rawCount !== pubRecs.length) {
+            throw new Error(`refusing to migrate ${kind}: ${rawCount - pubRecs.length} on-disk record(s) failed to load (see the warnings above) `
+                + `and would be deleted without ever reaching the overlay. Fix or remove them, then re-run \`hunch private --migrate\`.`);
+        }
         if (pubRecs.length === 0)
             continue;
         const privRecs = priv.loadAll(kind);

package/dist/synthesis/provider.js

@@ -24,7 +24,7 @@
  * Every provider returns the same shape so the rest of the system never knows
  * (or cares) which one ran.
  */
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync } from "node:fs";
 import { isIP } from "node:net";
 import { tmpdir } from "node:os";
@@ -66,6 +66,20 @@ export function pexecIn(cmd, args, opts = {}) {
         let err = "";
         let outLen = 0;
         let settled = false;
+        // Windows spawns through a cmd.exe wrapper (shell:true), and child.kill()
+        // terminates only that wrapper — the actual agent CLI survives as an orphan,
+        // still burning the user's subscription after every timeout, accumulating
+        // with each post-commit hook fire (issue #44). taskkill /T fells the tree.
+        // Best-effort by design: the wrapper kill below still runs either way.
+        const killTree = () => {
+            if (IS_WIN && child.pid) {
+                try {
+                    execFile("taskkill", ["/pid", String(child.pid), "/T", "/F"], { windowsHide: true }, () => { });
+                }
+                catch { /* taskkill unavailable — fall through to the wrapper kill */ }
+            }
+            child.kill();
+        };
         const done = (fn) => {
             if (settled)
                 return;
@@ -76,7 +90,7 @@ export function pexecIn(cmd, args, opts = {}) {
         };
         const timer = opts.timeout
             ? setTimeout(() => {
-                child.kill();
+                killTree();
                 done(() => reject(new Error(`"${cmd}" timed out after ${opts.timeout}ms`)));
             }, opts.timeout)
             : null;
@@ -84,7 +98,7 @@ export function pexecIn(cmd, args, opts = {}) {
         child.stdout.on("data", (d) => {
             outLen += d.length;
             if (outLen > max) {
-                child.kill();
+                killTree();
                 done(() => reject(new Error(`"${cmd}" exceeded maxBuffer (${max} bytes)`)));
                 return;
             }
@@ -323,6 +337,18 @@ class ClaudeCliProvider extends PromptSynthProvider {
         const childEnv = { ...process.env };
         delete childEnv.ANTHROPIC_API_KEY;
         delete childEnv.ANTHROPIC_AUTH_TOKEN;
+        // Gateway ROUTING is metered per-token exactly like a raw API key: with
+        // CLAUDE_CODE_USE_BEDROCK/VERTEX set (common in enterprise shell profiles
+        // for interactive use), headless `claude -p` bills AWS/GCP on every
+        // significant commit — silently, from a post-commit hook (issue #39,
+        // con_2ce3f2a547). Strip the routing switches and their endpoint overrides
+        // so the CLI falls through to subscription auth here too.
+        delete childEnv.CLAUDE_CODE_USE_BEDROCK;
+        delete childEnv.CLAUDE_CODE_USE_VERTEX;
+        delete childEnv.ANTHROPIC_BEDROCK_BASE_URL;
+        delete childEnv.ANTHROPIC_VERTEX_BASE_URL;
+        delete childEnv.ANTHROPIC_VERTEX_PROJECT_ID;
+        delete childEnv.CLOUD_ML_REGION;
         // Single-shot text synthesis: no tools, no agentic loop. The prompt carries
         // all needed context inline, so run from a neutral cwd to avoid loading this
         // repo's own hunch MCP server / CLAUDE.md on every commit (cheaper, and no

package/dist/wiki/wiki.js

@@ -28,7 +28,7 @@
  */
 import { createHash } from "node:crypto";
 import { existsSync, readFileSync, mkdirSync, rmSync } from "node:fs";
-import { join, dirname } from "node:path";
+import { join, dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { writeFileAtomic } from "../core/io.js";
 import { compareCodeUnits } from "../core/canonicalOrder.js";
 import { hunchPaths, toPosixTarget } from "../core/paths.js";
@@ -36,15 +36,61 @@ import { isLive } from "../core/topics.js";
 import { scanRepoDocs } from "../core/docscan.js";
 import { adoptedSlug, adoptionHash, renderAdoptedDoc } from "./adopt.js";
 import { assembleGraphData, renderGraphPage } from "./graph.js";
+/** A wiki directory that is safe to join against the pages root: relative, POSIX,
+ *  no trailing slash, and free of any "." / ".." / empty segment. `.` would alias
+ *  the pages root itself (clobbering tracked files like README.md) and `..` writes
+ *  the rendered graph — which for the private home is the FULL overlay union —
+ *  outside the repository entirely. Returns undefined for anything unsafe. */
+function validDir(d) {
+    if (!d)
+        return undefined;
+    const v = toPosixTarget(d).replace(/\/+$/, "");
+    if (!v || isAbsolute(v) || /^[a-zA-Z]:/.test(v))
+        return undefined;
+    if (v.split("/").some((seg) => seg === "" || seg === "." || seg === ".."))
+        return undefined;
+    return v;
+}
 /** Normalize a --dir override: POSIX separators, no trailing slash — the dir is
- *  a committed manifest key prefix, so it must hash identically on every OS. */
-const normDir = (d) => d ? toPosixTarget(d).replace(/\/+$/, "") || undefined : undefined;
+ *  a committed manifest key prefix, so it must hash identically on every OS.
+ *  An unsafe override THROWS rather than silently falling back, so a rejected flag
+ *  can never quietly write somewhere else. */
+const normDir = (d) => {
+    if (d === undefined)
+        return undefined;
+    const v = validDir(d);
+    if (!v) {
+        throw new Error(`refusing --dir ${JSON.stringify(d)}: the wiki directory must be a relative path inside the repository (no "." or ".." segments, not absolute).`);
+    }
+    return v;
+};
+/** Resolve a manifest page key to an absolute path INSIDE this home's page
+ *  directory, or null when it escapes.
+ *
+ *  Both inputs that reach the join are untrusted. `.hunch/wiki-manifest.json` is a
+ *  COMMITTED file (so CI can gate on it), which makes every page KEY inside it
+ *  PR- and merge-influenceable — and `wikiStatus` classifies any key no current
+ *  artifact claims as an orphan to be deleted. Without this check a key like
+ *  "../../id_rsa" turned a plain `hunch wiki` into arbitrary file deletion, with
+ *  `hunch drift` politely instructing the maintainer to run it. Re-checked at BOTH
+ *  the write and the delete site, so a manifest written before this guard existed
+ *  still cannot escape. */
+function containedPagePath(home, page) {
+    if (!page || page.includes("\0") || isAbsolute(page) || /^[a-zA-Z]:/.test(page))
+        return null;
+    const baseDir = resolve(join(home.pagesRoot, home.dir));
+    const abs = resolve(join(home.pagesRoot, ...page.split("/")));
+    const rel = relative(baseDir, abs);
+    if (!rel || rel === ".." || rel.startsWith(`..${sep}`) || isAbsolute(rel))
+        return null;
+    return abs;
+}
 export function publicHome(root, dirOverride) {
     const manifestPath = join(hunchPaths(root).hunch, "wiki-manifest.json");
     return {
         kind: "public",
         pagesRoot: root,
-        dir: normDir(dirOverride) ?? readWikiManifestAt(manifestPath)?.dir ?? "wiki",
+        dir: normDir(dirOverride) ?? validDir(readWikiManifestAt(manifestPath)?.dir) ?? "wiki",
         manifestPath,
         source: "public",
     };
@@ -60,7 +106,7 @@ export function privateHome(store, dirOverride) {
     return {
         kind: "private",
         pagesRoot: dirname(store.privateDir),
-        dir: normDir(dirOverride) ?? readWikiManifestAt(manifestPath)?.dir ?? "wiki",
+        dir: normDir(dirOverride) ?? validDir(readWikiManifestAt(manifestPath)?.dir) ?? "wiki",
         manifestPath,
         source: "all",
     };
@@ -515,6 +561,11 @@ export function wikiStatus(store, home, srcRoot) {
     for (const [page, p] of Object.entries(manifest?.pages ?? {})) {
         if (expected.has(page))
             continue;
+        // The manifest is committed, so a key is attacker-influenceable through an
+        // ordinary PR — and reaching this list means "delete this file". Only a key
+        // that resolves inside this home's page directory may be classified at all.
+        if (!containedPagePath(home, page))
+            continue;
         (p.component.startsWith(ADOPTED_PREFIX) ? adoptionOrphans : orphans).push(page);
     }
     return { home, entries, docs, adoptions, adoptionOrphans, decisions, specs, index, now, graph, repoWide, orphans };
@@ -556,7 +607,10 @@ export async function generateWiki(store, srcRoot, home, opts) {
     /** Written-bytes ledger — the hand-edit tripwire recorded per page. */
     const bytesByPage = new Map();
     const put = (page, content) => {
-        writeFileAtomic(join(home.pagesRoot, ...page.split("/")), content);
+        const abs = containedPagePath(home, page);
+        if (!abs)
+            throw new Error(`refusing to write wiki page ${JSON.stringify(page)}: it resolves outside ${join(home.pagesRoot, home.dir)}`);
+        writeFileAtomic(abs, content);
         bytesByPage.set(page, sha16(content));
         written.push(page);
     };
@@ -614,8 +668,16 @@ export async function generateWiki(store, srcRoot, home, opts) {
     const removed = [];
     for (const [pages, why] of [[status.orphans, "component gone"], [status.adoptionOrphans, "original healed or removed — copy retired"]]) {
         for (const page of pages) {
+            // Re-assert containment at the DELETE site too: wikiStatus already filters
+            // escaping manifest keys, but this is the primitive that removes files, so it
+            // must not depend on an upstream filter having run.
+            const abs = containedPagePath(home, page);
+            if (!abs) {
+                log(`  ⚠ ${page} — refusing to remove a manifest entry that resolves outside ${join(home.pagesRoot, home.dir)}`);
+                continue;
+            }
             try {
-                rmSync(join(home.pagesRoot, ...page.split("/")), { force: true });
+                rmSync(abs, { force: true });
             }
             catch {
                 /* best effort */
@@ -627,8 +689,26 @@ export async function generateWiki(store, srcRoot, home, opts) {
     if (written.length || removed.length) {
         const pages = {};
         const entry = (page, component, hash, state) => {
-            const keep = state === "fresh" ? prior?.pages[page] : undefined;
-            pages[page] = keep ?? { component, hash, generated: opts.now, bytes: bytesByPage.get(page) };
+            const prev = prior?.pages[page];
+            const justWritten = bytesByPage.get(page);
+            // Carry the prior entry forward ONLY for a fresh page this run did not rewrite.
+            // A full regen (`only: "all"`) rewrites every page, so reusing the prior entry
+            // there recorded the OLD bytes against freshly written content — making the
+            // hand-edit tripwire fire on Hunch's own output, so `hunch wiki --check` exited
+            // 1 immediately after a successful `hunch wiki` and the tripwire's signal for a
+            // REAL hand edit was destroyed.
+            if (state === "fresh" && justWritten === undefined && prev) {
+                pages[page] = prev;
+                return;
+            }
+            pages[page] = {
+                component,
+                hash,
+                // Keep the original stamp for an unchanged-but-rewritten page so a full regen
+                // stays byte-idempotent in git.
+                generated: state === "fresh" && prev ? prev.generated : opts.now,
+                bytes: justWritten ?? prev?.bytes,
+            };
         };
         for (const e of status.entries)
             entry(e.page, e.pack.component.id, e.hash, e.state);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@davesheffer/hunch",
-  "version": "1.10.0",
+  "version": "1.10.2",
   "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.",