@davesheffer/hunch 1.8.3 → 1.9.2

package/dist/extractors/git.js

@@ -1,9 +1,59 @@
 /** Deterministic git introspection for the extractor + learning loop.
  *  No LLM here — just parsing what git already knows. */
 import { execFileSync } from "node:child_process";
-import { isAbsolute, resolve, join, basename, dirname } from "node:path";
-import { mkdirSync, rmSync, statSync, realpathSync, readFileSync } from "node:fs";
+import { createHash } from "node:crypto";
+import { devNull } from "node:os";
+import { isAbsolute, resolve, join, basename, dirname, relative, sep } from "node:path";
+import { mkdirSync, rmSync, statSync, lstatSync, realpathSync, readFileSync, renameSync, readdirSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { MEMLOG_FORMAT } from "../core/memorylog.js";
+import { hunchAttributesAreSafe, hunchTreeAttributesAreSafe, safeOverlayTree } from "../core/overlaySafety.js";
+import { createRepoFileReader } from "../core/safeRepoFile.js";
+// `git` exports these repository-local variables to hooks. They outrank cwd/-C,
+// so carrying them from the code repository into a command for the memory
+// overlay can target the wrong index/object store. This is the documented set
+// from `git rev-parse --local-env-vars`; keep explicit global credentials and
+// transport settings, but always clear repository identity before selecting cwd.
+const LOCAL_GIT_ENV_VARS = [
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",
+    "GIT_OBJECT_DIRECTORY", "GIT_DIR", "GIT_WORK_TREE", "GIT_IMPLICIT_WORK_TREE", "GIT_GRAFT_FILE",
+    "GIT_INDEX_FILE", "GIT_NO_REPLACE_OBJECTS", "GIT_REPLACE_REF_BASE", "GIT_PREFIX",
+    "GIT_INTERNAL_SUPER_PREFIX", "GIT_SHALLOW_FILE", "GIT_COMMON_DIR",
+];
+export function foreignRepoEnv(source) {
+    const env = { ...source };
+    for (const key of LOCAL_GIT_ENV_VARS)
+        delete env[key];
+    for (const key of Object.keys(env)) {
+        if (/^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key))
+            delete env[key];
+    }
+    return env;
+}
+function machineCommitEnv(repoRoot, source) {
+    const env = foreignRepoEnv(source);
+    const configured = (key) => {
+        try {
+            return execFileSync("git", ["-C", repoRoot, "config", "--get", key], {
+                encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            }).trim();
+        }
+        catch {
+            return "";
+        }
+    };
+    const name = configured("user.name");
+    const email = configured("user.email");
+    if (!env.GIT_AUTHOR_NAME && !name)
+        env.GIT_AUTHOR_NAME = "Hunch Memory";
+    if (!env.GIT_COMMITTER_NAME && !name)
+        env.GIT_COMMITTER_NAME = "Hunch Memory";
+    if (!env.GIT_AUTHOR_EMAIL && !email)
+        env.GIT_AUTHOR_EMAIL = "hunch-memory@localhost";
+    if (!env.GIT_COMMITTER_EMAIL && !email)
+        env.GIT_COMMITTER_EMAIL = "hunch-memory@localhost";
+    return env;
+}
 function git(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     // stdio: capture stdout, silence stderr (so "no commits yet" etc. don't leak).
     return execFileSync("git", args, {
@@ -19,6 +69,23 @@ function gitSafe(args, cwd, maxBuffer) {
         return "";
     }
 }
+/** Object-identity reads must not inherit clone-local replacement refs/grafts.
+ * Most Git helpers intentionally preserve ordinary repository behavior; use
+ * this narrower path only where a cross-clone canonical identity is minted. */
+function gitSafeWithoutReplacements(args, cwd, maxBuffer = 64 * 1024 * 1024) {
+    try {
+        return execFileSync("git", args, {
+            cwd,
+            encoding: "utf8",
+            env: { ...process.env, GIT_NO_REPLACE_OBJECTS: "1" },
+            maxBuffer,
+            stdio: ["ignore", "pipe", "ignore"],
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
 function gitRawSafe(args, cwd, maxBuffer = 64 * 1024 * 1024) {
     try {
         return execFileSync("git", args, {
@@ -30,9 +97,323 @@ function gitRawSafe(args, cwd, maxBuffer = 64 * 1024 * 1024) {
         return null;
     }
 }
+function gitSafeIsolated(args, cwd, maxBuffer = 64 * 1024 * 1024) {
+    try {
+        return execFileSync("git", args, {
+            cwd, encoding: "utf8", maxBuffer,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: foreignRepoEnv(process.env),
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function gitRawSafeIsolated(args, cwd, maxBuffer = 64 * 1024 * 1024) {
+    try {
+        return execFileSync("git", args, {
+            cwd, encoding: "utf8", maxBuffer,
+            stdio: ["ignore", "pipe", "ignore"],
+            env: foreignRepoEnv(process.env),
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function headShaWithEnv(cwd, env) {
+    return gitSafeWithEnv(["rev-parse", "HEAD"], cwd, env);
+}
+/** Git query for a repository other than the invocation repository. The
+ * caller supplies an environment with code-repo GIT_DIR/GIT_INDEX_FILE state
+ * removed, so hooks cannot redirect an overlay query back into the code repo. */
+function gitSafeWithEnv(args, cwd, env) {
+    try {
+        return execFileSync("git", ["-C", cwd, ...args], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
 export function isGitRepo(cwd) {
     return gitSafe(["rev-parse", "--is-inside-work-tree"], cwd) === "true";
 }
+/** Canonical worktree root, or null when Git cannot positively identify one.
+ * Callers enforcing a privacy boundary must distinguish "different repo" from
+ * "malformed/unknown Git state" instead of treating both as safe. */
+export function gitWorktreeRoot(cwd) {
+    const top = gitSafeIsolated(["rev-parse", "--show-toplevel"], cwd);
+    return top ? canonicalPath(top) : null;
+}
+/** True only when `cwd` is the repository's actual worktree root. Unlike
+ * `isGitRepo`, this does not accept an ancestor repository discovered by Git's
+ * upward walk. Private overlays use this stronger boundary so a nested
+ * `.hunch-private/.hunch` can never stage or commit into the code repository. */
+export function isGitRepoRoot(cwd) {
+    const raw = gitSafeIsolated(["rev-parse", "--show-toplevel"], cwd);
+    return !!raw && sameFilesystemEntry(raw, cwd);
+}
+function canonicalPath(path) {
+    try {
+        return realpathSync(path);
+    }
+    catch {
+        return resolve(path);
+    }
+}
+export function gitNullDevice() {
+    return process.platform === "win32" ? "NUL" : devNull;
+}
+/** Compare physical directory identity before path text. Git for Windows can
+ * return an 8.3/short or differently-cased spelling for the same top-level
+ * directory that Node reached through its long path. A nonzero file ID keeps
+ * this exact even on case-sensitive Windows directories; canonical text is a
+ * conservative fallback for filesystems that do not expose stable IDs. */
+function sameFilesystemEntry(left, right) {
+    try {
+        const leftStat = statSync(left, { bigint: true });
+        const rightStat = statSync(right, { bigint: true });
+        if (leftStat.ino !== 0n && rightStat.ino !== 0n) {
+            return leftStat.dev === rightStat.dev && leftStat.ino === rightStat.ino;
+        }
+    }
+    catch { /* fall back to canonical path text */ }
+    return canonicalPath(left) === canonicalPath(right);
+}
+/** Whether two paths resolve to the same repository identity. Comparing only
+ * worktree roots is insufficient: linked worktrees have different roots but
+ * share one Git common directory and therefore one publishable history. */
+export function sameGitRepository(left, right) {
+    if (sameFilesystemEntry(left, right))
+        return true;
+    const common = (cwd) => {
+        const value = gitSafeIsolated(["rev-parse", "--git-common-dir"], cwd);
+        return value ? (isAbsolute(value) ? value : resolve(cwd, value)) : "";
+    };
+    const leftCommon = common(left);
+    const rightCommon = common(right);
+    return !!leftCommon && !!rightCommon && sameFilesystemEntry(leftCommon, rightCommon);
+}
+function remoteIdentity(raw, cwd, purpose = "route") {
+    const value = raw.trim();
+    if (!value)
+        return "";
+    const trimRepoSuffix = (path) => path.replace(/[\\/]+$/, "").replace(/\.git$/i, "");
+    // Local repositories are filesystem identities, not provider aliases. Both
+    // `/srv/memory` and `/srv/memory.git` may exist and publish unrelated graphs;
+    // collapsing the conventional suffix is safe only for known network hosts.
+    const normalizeLocalPath = (path) => canonicalPath(path).replace(/[\\/]+$/, "");
+    const normalizeNetworkPath = (host, path) => {
+        const normalized = trimRepoSuffix(path).replace(/^\/+/, "");
+        return host === "github.com" || host === "www.github.com" ? normalized.toLowerCase() : normalized;
+    };
+    const azureDevOpsIdentity = (host, path) => {
+        const segments = trimRepoSuffix(path).replace(/^\/+/, "").split("/");
+        let coordinates = null;
+        if (host === "dev.azure.com" && segments.length === 4 && segments[2].toLowerCase() === "_git") {
+            coordinates = [segments[0], segments[1], segments[3]];
+        }
+        else if ((host === "ssh.dev.azure.com" || host === "vs-ssh.visualstudio.com")
+            && segments.length === 4 && segments[0].toLowerCase() === "v3") {
+            coordinates = [segments[1], segments[2], segments[3]];
+        }
+        else {
+            const legacyHost = host.match(/^([^.]+)\.visualstudio\.com$/);
+            if (legacyHost && segments.length === 3 && segments[1].toLowerCase() === "_git") {
+                coordinates = [legacyHost[1], segments[0], segments[2]];
+            }
+        }
+        if (!coordinates?.every(Boolean))
+            return null;
+        return `provider:azure-devops:${coordinates.map((part) => part.toLowerCase()).join("/")}`;
+    };
+    const networkIdentity = (host, path, pathCaseHost = host, username = "", transport = "ssh") => {
+        const provider = azureDevOpsIdentity(host, path);
+        if (provider)
+            return provider;
+        if (host === "github.com" || host === "www.github.com") {
+            return `provider:github:${normalizeNetworkPath("github.com", path)}`;
+        }
+        // Route proof is deliberately exact for an unknown host: transport and SSH
+        // account can select different namespaces. Preserve username bytes/case.
+        // Publication proof is deliberately conservative in the other direction:
+        // https://host/org/repo and ssh://user@host/org/repo may publish the same
+        // history, so an overlay must not evade the code-remote boundary by changing
+        // transport spelling.
+        const account = purpose === "route" && username ? `${username}@` : "";
+        const route = ["ssh", "git+ssh", "ssh+git"].includes(transport) ? "ssh" : transport;
+        const normalizedPath = normalizeNetworkPath(pathCaseHost, path);
+        return `net:${purpose === "route" ? route : "any"}://${account}${host}/${purpose === "publication" ? normalizedPath.toLowerCase() : normalizedPath}`;
+    };
+    try {
+        if (value.startsWith("file://"))
+            return `file:${normalizeLocalPath(fileURLToPath(value))}`;
+    }
+    catch { /* fall through to the literal URL form */ }
+    if (isAbsolute(value) || value.startsWith("./") || value.startsWith("../")) {
+        return `file:${normalizeLocalPath(resolve(cwd, value))}`;
+    }
+    const scp = value.match(/^(?:([^@/]+)@)?([^:/]+):(.+)$/);
+    if (scp && !value.includes("://")) {
+        const rawHost = scp[2].toLowerCase().replace(/\.$/, "");
+        const host = rawHost === "www.github.com" ? "github.com" : rawHost;
+        return networkIdentity(host, scp[3], host, scp[1] ?? "", "ssh");
+    }
+    if (!value.includes("://"))
+        return `file:${normalizeLocalPath(resolve(cwd, value))}`;
+    try {
+        const url = new URL(value);
+        const rawHostname = url.hostname.toLowerCase().replace(/\.$/, "");
+        const protocol = url.protocol.toLowerCase();
+        const githubSsh443 = rawHostname === "ssh.github.com" && ["ssh:", "git+ssh:", "ssh+git:"].includes(protocol) && url.port === "443";
+        const hostname = rawHostname === "www.github.com" || githubSsh443 ? "github.com" : rawHostname;
+        const defaults = { "ssh:": "22", "git+ssh:": "22", "ssh+git:": "22", "https:": "443", "http:": "80", "git:": "9418" };
+        const port = !githubSsh443 && url.port && url.port !== defaults[protocol] ? `:${url.port}` : "";
+        const host = `${hostname}${port}`;
+        return networkIdentity(host, decodeURIComponent(url.pathname), hostname, decodeURIComponent(url.username), protocol.replace(/:$/, ""));
+    }
+    catch {
+        return `literal:${trimRepoSuffix(value)}`;
+    }
+}
+function localRemotePath(raw, cwd) {
+    const value = raw.trim();
+    if (!value)
+        return null;
+    try {
+        if (value.startsWith("file://"))
+            return canonicalPath(fileURLToPath(value));
+    }
+    catch {
+        return null;
+    }
+    if (isAbsolute(value) || value.startsWith("./") || value.startsWith("../")) {
+        return canonicalPath(resolve(cwd, value));
+    }
+    const scp = value.match(/^(?:[^@/]+@)?[^:/]+:.+$/);
+    if (!value.includes("://") && !scp)
+        return canonicalPath(resolve(cwd, value));
+    return null;
+}
+function repositoriesShareCommitObjects(left, right) {
+    const leftHead = gitSafeIsolated(["rev-parse", "--verify", "HEAD^{commit}"], left);
+    const rightHead = gitSafeIsolated(["rev-parse", "--verify", "HEAD^{commit}"], right);
+    if (!leftHead || !rightHead)
+        return false;
+    if (gitRawSafeIsolated(["cat-file", "-e", `${leftHead}^{commit}`], right) !== null
+        || gitRawSafeIsolated(["cat-file", "-e", `${rightHead}^{commit}`], left) !== null)
+        return true;
+    // Comparing only the tips misses a forked contamination: the code repo and
+    // an overlay can each add a unique commit after sharing an older code
+    // history. Pushing the overlay tip would still publish every reachable code
+    // ancestor. Full repositories that share ancestry share at least one root;
+    // for shallow repositories, also ask whether either visible boundary/root is
+    // present in the other object database.
+    const roots = (cwd) => gitSafeIsolated(["rev-list", "--max-parents=0", "HEAD"], cwd)
+        .split(/\r?\n/)
+        .filter((oid) => /^[0-9a-f]{40,64}$/i.test(oid));
+    const leftRoots = roots(left);
+    const rightRoots = roots(right);
+    if (!leftRoots.length || !rightRoots.length)
+        return false;
+    const rightRootSet = new Set(rightRoots);
+    if (leftRoots.some((oid) => rightRootSet.has(oid)))
+        return true;
+    return leftRoots.some((oid) => gitRawSafeIsolated(["cat-file", "-e", `${oid}^{commit}`], right) !== null)
+        || rightRoots.some((oid) => gitRawSafeIsolated(["cat-file", "-e", `${oid}^{commit}`], left) !== null);
+}
+function localRemoteTargets(cwd) {
+    const out = gitRawSafeIsolated(["remote", "-v"], cwd) ?? "";
+    const targets = new Set();
+    for (const line of out.split("\n")) {
+        const match = line.match(/^[^\t]+\t(.+) \((?:fetch|push)\)$/);
+        if (!match)
+            continue;
+        const target = localRemotePath(match[1], cwd);
+        if (target)
+            targets.add(target);
+    }
+    return [...targets];
+}
+function repositoryTargetMatches(target, repoRoot) {
+    return sameGitRepository(target, repoRoot) || repositoriesShareCommitObjects(target, repoRoot);
+}
+/** Resolve a user-supplied Git remote once, before handing it to commands that
+ * run from different working directories. Git otherwise gives a relative local
+ * URL a different meaning under `git clone` and `git -C <overlay> remote add`,
+ * which can turn a successful preflight into a later privacy-boundary escape. */
+export function canonicalRemoteUrl(raw, cwd) {
+    const value = raw.trim();
+    if (!value)
+        return "";
+    try {
+        if (value.startsWith("file://"))
+            return canonicalPath(fileURLToPath(value));
+    }
+    catch { /* let Git report an invalid URL without weakening the boundary */ }
+    if (isAbsolute(value))
+        return canonicalPath(value);
+    const scp = value.match(/^(?:[^@/]+@)?[^:/]+:.+$/);
+    if (!value.includes("://") && !scp)
+        return canonicalPath(resolve(cwd, value));
+    return value;
+}
+/** Compare two remote spellings in the contexts where Git would interpret
+ * them. This is identity comparison, not brittle string equality. */
+export function sameRemoteUrl(left, leftCwd, right, rightCwd) {
+    const leftIdentity = remoteIdentity(left, leftCwd, "route");
+    return !!leftIdentity && leftIdentity === remoteIdentity(right, rightCwd, "route");
+}
+function gitRemoteIdentities(cwd, direction = "any") {
+    const out = gitRawSafeIsolated(["remote", "-v"], cwd) ?? "";
+    const identities = new Set();
+    for (const line of out.split("\n")) {
+        const match = line.match(/^[^\t]+\t(.+) \((fetch|push)\)$/);
+        if (!match)
+            continue;
+        if (direction !== "any" && match[2] !== direction)
+            continue;
+        const identity = remoteIdentity(match[1], cwd, "publication");
+        if (identity)
+            identities.add(identity);
+    }
+    return identities;
+}
+/** True when two worktrees can publish to the same local Git history OR name
+ * the same configured remote repository. Separate clones of one remote are a
+ * single publication boundary even though their local common dirs differ. */
+export function sameGitPublication(left, right) {
+    if (sameGitRepository(left, right))
+        return true;
+    // A clone of the code repository with its origin removed still carries the
+    // same commit objects. Treat shared history as one publication boundary; a
+    // memory overlay must start from an independent graph history.
+    if (repositoriesShareCommitObjects(left, right))
+        return true;
+    for (const target of localRemoteTargets(left))
+        if (repositoryTargetMatches(target, right))
+            return true;
+    for (const target of localRemoteTargets(right))
+        if (repositoryTargetMatches(target, left))
+            return true;
+    const leftRemotes = gitRemoteIdentities(left);
+    if (!leftRemotes.size)
+        return false;
+    for (const remote of gitRemoteIdentities(right))
+        if (leftRemotes.has(remote))
+            return true;
+    return false;
+}
+/** Preflight a requested overlay URL before clone/attach can mutate a remote. */
+export function repositoryUsesRemote(repoRoot, remoteUrl, remoteCwd = repoRoot) {
+    const localTarget = localRemotePath(remoteUrl, remoteCwd);
+    if (localTarget && repositoryTargetMatches(localTarget, repoRoot))
+        return true;
+    const requested = remoteIdentity(remoteUrl, remoteCwd, "publication");
+    return !!requested && gitRemoteIdentities(repoRoot).has(requested);
+}
 /** The MAIN worktree's root — the stable anchor for an overlay store. A linked worktree
  *  can be `git worktree remove`d, so anything anchored inside it (an overlay clone, an
  *  absolute pointer target) silently dies for every OTHER worktree; the main checkout
@@ -45,42 +426,131 @@ export function mainWorktreeRoot(root) {
     const abs = resolve(root, common);
     return basename(abs) === ".git" ? dirname(abs) : root;
 }
-/** Best-effort: stage ONLY the hunch dir, commit, and push the repo it lives in. Shared by
- *  the post-commit auto-commit (CLI sync --commit), MCP private writes, and `hunch private
- *  --sync`. HUNCH_SYNC=1 stops the created commit from re-triggering the post-commit hook
- *  (no recursion). Stages with a pathspec scoped to `hunchDir`, so it never sweeps unrelated
- *  working-tree changes. Never throws — a non-repo dir / offline push just no-ops.
- *  `push: false` commits WITHOUT merging or pushing — required when hunchDir is the PUBLIC
- *  .hunch/ inside the user's code repo: an automatic pull/push there would merge the remote
- *  into their working branch and publish their unpushed code commits. The memory commit
- *  simply rides the user's next push.
- *  Returns what ACTUALLY happened, so callers never report a commit that was skipped:
- *  "pushed" (commit created and pushed), "committed" (commit created; push not requested,
- *  or the merge/push failed — retry rides the next flush), null (nothing committed: lock
- *  held, backstop refusal, nothing staged, or not a repo). */
-export function commitAndPushHunch(hunchDir, message, opts = {}) {
+/** Stable, privacy-safe repository label for artifacts that must be reusable
+ * across linked worktrees and ordinary clones. Prefer the canonical fetch
+ * remote identity: its SHA-256 digest exposes neither a private URL nor a local
+ * path, ignores mutable remote aliases, and does not depend on clone depth. If
+ * several fetch remotes exist, canonical identity ordering makes the choice
+ * deterministic without privileging a name such as `origin`.
+ *
+ * Remote-less full clones fall back to intrinsic root commits. A remote-less
+ * shallow clone cannot prove a clone-independent repository identity without
+ * fetching missing history or persisting a shared ID, so it retains the local
+ * main-worktree label (which is still stable across linked worktrees). */
+export function stableRepositoryName(root) {
+    const fetchRemote = [...gitRemoteIdentities(root, "fetch")].sort()[0];
+    if (fetchRemote) {
+        const digest = createHash("sha256").update(fetchRemote, "utf8").digest("hex");
+        return `git-remote:sha256:${digest}`;
+    }
+    const shallow = gitSafe(["rev-parse", "--is-shallow-repository"], root) === "true";
+    if (shallow)
+        return basename(mainWorktreeRoot(root));
+    const roots = gitSafeWithoutReplacements(["rev-list", "--max-parents=0", "HEAD"], root)
+        .split(/\s+/)
+        .filter(Boolean)
+        .sort();
+    if (roots.length)
+        return `git:${roots.join("+")}`;
+    return basename(mainWorktreeRoot(root));
+}
+const CAPTURE_REMOTE_TIMEOUT_MS = 15_000;
+const READ_REMOTE_TIMEOUT_MS = 5_000;
+// A capture can spend roughly 90s in commit + bounded merge/push/retry seams.
+// A contending writer waits beyond that proven ceiling, then takes the lock and
+// drains every already-durable JSON write itself. This removes the old "maybe a
+// third capture sweeps it later" liveness hole.
+const CAPTURE_LOCK_HANDOFF_MS = 120_000;
+function unsafeOverlayPublication(hunchDir, protectedRepoRoot) {
+    let currentOverlayRoot = dirname(resolve(hunchDir));
+    try {
+        currentOverlayRoot = dirname(realpathSync(hunchDir));
+    }
+    catch {
+        return true;
+    }
+    const standalone = isGitRepoRoot(currentOverlayRoot);
+    const overlapsCode = standalone ? sameGitPublication(currentOverlayRoot, protectedRepoRoot) : null;
+    const unsafe = !standalone || overlapsCode === true;
+    if (unsafe && process.env.HUNCH_TEAM_CLONE_DEBUG === "1") {
+        process.stderr.write(`[hunch-team-boundary] standalone=${standalone} overlaps_code=${overlapsCode ?? "unchecked"}\n`);
+    }
+    return unsafe;
+}
+export function commitAndPushHunch(hunchDir, message, opts) {
+    // Runtime callers may be older compiled JS even though TypeScript requires the
+    // protected-repository contract. Preserve this helper's never-throw promise and
+    // fail closed instead of dereferencing a missing options object.
+    if (!opts) {
+        console.error(`hunch: refusing to auto-commit memory at "${hunchDir}" — the protected repository identity was not provided. Nothing was staged, committed, or pushed.`);
+        return null;
+    }
+    // A push-capable target is a PRIVATE/SHARED overlay and must live directly
+    // inside its OWN repository. `git -C` otherwise walks upward and may resolve
+    // a nested overlay to the user's code repo. JSON-only private artifacts would
+    // pass the staged-file backstop below, so enforce the repository boundary
+    // before staging even one byte. Public `.hunch/` commits intentionally use
+    // push:false and are allowed to resolve to the enclosing project repository.
+    if (opts.push !== false) {
+        if (unsafeOverlayPublication(hunchDir, opts.protectedRepoRoot)) {
+            console.error(`hunch: refusing to auto-commit private memory at "${hunchDir}" — it is not a standalone Git repository distinct from the protected code repository. Nothing was staged, committed, or pushed. (Run \`hunch private\` or \`hunch shared --repo <url>\` to create a dedicated overlay repository.)`);
+            return null;
+        }
+    }
     // Serialize across worktrees: several worktrees auto-committing the SAME overlay repo
-    // at once would race git's index.lock. An atomic-mkdir lock lets one proceed; the others
-    // skip — safe because each record is already written to disk, so `git add .` here sweeps
-    // up anything a skipped run left pending (eventually-consistent, never lost).
+    // at once would race git's index.lock. A contender whose record is already
+    // durable waits for the live owner to finish, then acquires the lock and
+    // drains anything the owner's exact path snapshot did not include.
     const lock = join(hunchDir, ".hunch-commit.lock");
-    if (!acquireCommitLock(lock))
+    const firstLockAttempt = acquireCommitLock(lock);
+    if (firstLockAttempt.state !== "acquired"
+        && !waitForCommitLockHandoff(lock, firstLockAttempt, CAPTURE_LOCK_HANDOFF_MS))
         return null;
     try {
-        const env = { ...process.env, HUNCH_SYNC: "1" };
+        const env = machineCommitEnv(hunchDir, {
+            ...process.env,
+            HUNCH_SYNC: "1",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_MERGE_AUTOEDIT: "no",
+            GIT_ATTR_NOSYSTEM: "1",
+        });
         const run = (args) => {
             try {
                 execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+                return true;
+            }
+            catch {
+                return false; // best-effort: nothing staged / not a repo / offline
             }
-            catch { /* best-effort: nothing staged / not a repo / offline */ }
         };
-        run(["add", "--", "."]);
+        if (opts.push !== false) {
+            if (!overlayAttributeSourcesAreSafe(hunchDir, env)) {
+                console.error(`hunch: refusing to auto-commit private memory at "${hunchDir}" — an unsafe Git attributes source could transform memory bytes. Nothing was staged, committed, or pushed.`);
+                return null;
+            }
+            const paths = committableOverlayJsonPaths(hunchDir);
+            if (!paths)
+                return null;
+            // Force-add only the exact contained JSON source-of-truth allowlist. A
+            // remote .gitignore, local info/exclude, or ambient excludesFile must not
+            // be able to silently stop the shared graph's heartbeat.
+            for (let index = 0; index < paths.length; index += 128) {
+                if (!run(["-c", `core.attributesFile=${gitNullDevice()}`, "add", "-f", "--", ...paths.slice(index, index + 128)])) {
+                    run(["reset", "-q", "--", "."]);
+                    return null;
+                }
+            }
+        }
+        else {
+            run(["add", "--", "."]);
+        }
         // SAFETY BACKSTOP (critical — bug_overlay_clobber): a memory sync is PURELY ADDITIVE small
         // JSON. If the staged set contains a DELETION, rename, or any non-.json file, hunchDir is NOT
         // a clean overlay store — most dangerously, the overlay was never its own git repo so `git -C`
         // walked UP to the PROJECT repo. Committing/pushing there would overwrite/delete the user's
         // code (we shipped exactly this). Refuse hard: unstage and bail without committing or pushing.
-        if (!stagedIsMemoryOnly(hunchDir, env)) {
+        const memoryPaths = stagedMemoryPaths(hunchDir, env);
+        if (memoryPaths === null) {
             try {
                 execFileSync("git", ["-C", hunchDir, "reset", "-q", "--", "."], { stdio: "ignore", env });
             }
@@ -94,34 +564,74 @@ export function commitAndPushHunch(hunchDir, message, opts = {}) {
             }
             return null;
         }
+        if (memoryPaths.length === 0)
+            return null;
         // Grounding docs refreshed by this capture ride the same memory commit, so committed record
         // counts can never go stale (the refresh-counts treadmill: every capture commit bumped the
         // count and re-staled the docs for the next release-gate clean-tree check). Staged AFTER the
         // memory-only backstop on purpose: alsoStage is a code-controlled list of generated grounding
         // docs the caller verified git-clean BEFORE rewriting, so it can neither weaken the
         // bug_overlay_clobber detection above nor sweep user edits.
-        for (const file of opts.alsoStage ?? [])
-            run(["add", "--", file]);
+        for (const file of opts.alsoStage ?? []) {
+            run(opts.push === false
+                ? ["add", "--", file]
+                : ["-c", `core.attributesFile=${gitNullDevice()}`, "add", "--", file]);
+        }
         // Only sync+push when a memory commit was actually created — never run pull/push against the
         // enclosing repo on an empty stage. Two-way sync: MERGE the remote BEFORE pushing so a push
         // can't be rejected non-fast-forward; the .hunch merge driver resolves same-record conflicts
         // by id. On conflict/offline, mergeRemote aborts to a clean tree and we skip the push.
         let committed = false;
+        // `git commit` without pathspecs commits the ENTIRE index. Even after the
+        // staged-set check, another process (or a pre-staged JSON file) could enter
+        // the index before commit. `--only` makes the mutation boundary mechanical:
+        // commit this Hunch tree plus the caller-vetted grounding files, and leave
+        // every unrelated staged byte untouched.
+        // Commit an exact path allowlist. A hook or concurrent index writer cannot
+        // smuggle local.json (or any other path) into a broad `--only -- .` commit.
+        // Hooks are disabled for this machine-generated commit; user hooks are an
+        // untrusted mutation seam and are unnecessary for JSON memory artifacts.
+        const hooksDir = disabledHooksDir(hunchDir);
+        if (!hooksDir)
+            return null;
+        const commitPaths = [...memoryPaths, ...(opts.alsoStage ?? [])];
         try {
-            execFileSync("git", ["-C", hunchDir, "commit", "-m", message], { stdio: "ignore", env });
+            execFileSync("git", [
+                "-C", hunchDir,
+                "-c", `core.hooksPath=${hooksDir}`,
+                ...(opts.push === false ? [] : ["-c", `core.attributesFile=${gitNullDevice()}`]),
+                "-c", "commit.gpgsign=false",
+                "commit", "--no-gpg-sign", "--only", "-m", message, "--", ...commitPaths,
+            ], { stdio: "ignore", env, timeout: 15_000 });
             committed = true;
         }
         catch { /* nothing staged / not a repo */ }
         if (!committed)
             return null;
-        if (opts.push !== false && mergeRemote(hunchDir, env)) {
+        if (opts.push !== false) {
+            // The overlay remote is mutable process state. Re-prove the publication
+            // boundary after the local commit and BEFORE pull: hooks or another
+            // process may have re-pointed it since the pre-staging check.
+            if (unsafeOverlayPublication(hunchDir, opts.protectedRepoRoot)) {
+                console.error(`hunch: private memory was committed locally, but the overlay publication boundary changed before sync. Nothing was pulled or pushed.`);
+                return "committed";
+            }
+            if (!contractReady(opts.remote)
+                || mergeRemote(hunchDir, env, CAPTURE_REMOTE_TIMEOUT_MS, opts.remote) === "failed")
+                return "committed";
+            // Hooks are disabled in the merge seam, but another process can still
+            // rewrite Git configuration. Check once after merge and once at the
+            // actual push seam; either refusal leaves the private commit local.
+            if (unsafeOverlayPublication(hunchDir, opts.protectedRepoRoot) || !contractReady(opts.remote)) {
+                console.error(`hunch: private memory was committed locally, but the overlay publication boundary changed during sync. Nothing was pushed.`);
+                return "committed";
+            }
             // Push tracked (not via run): a no-upstream/offline/rejected push must report
             // "committed", not overclaim "pushed" — the next flush's merge+push retries.
-            try {
-                execFileSync("git", ["-C", hunchDir, "push"], { stdio: "ignore", env });
+            if (unsafeOverlayPublication(hunchDir, opts.protectedRepoRoot) || !contractReady(opts.remote))
+                return "committed";
+            if (pushWithOneRemoteAdvanceRetry(hunchDir, env, opts.protectedRepoRoot, CAPTURE_REMOTE_TIMEOUT_MS, opts.remote))
                 return "pushed";
-            }
-            catch { /* offline / no upstream */ }
         }
         return "committed";
     }
@@ -136,7 +646,10 @@ export function commitAndPushHunch(hunchDir, message, opts = {}) {
  *  dirty, so a doc the user never committed is never swept into a memory commit). */
 export function isGitCleanPath(root, rel) {
     try {
-        return execFileSync("git", ["-C", root, "status", "--porcelain", "--", rel], { encoding: "utf8" }).trim() === "";
+        return execFileSync("git", ["-C", root, "status", "--porcelain", "--", rel], {
+            encoding: "utf8",
+            env: foreignRepoEnv(process.env),
+        }).trim() === "";
     }
     catch {
         return false;
@@ -146,18 +659,28 @@ export function isGitCleanPath(root, rel) {
  *  The overlay store is entirely JSON (decisions/, bugs/, …, manifest.json). A real memory sync
  *  is purely additive; a DELETION, rename, or any non-.json staged path means hunchDir is NOT a
  *  clean overlay repo (e.g. it resolved to the project repo), so committing there would clobber
- *  code. Empty stage ⇒ false (nothing to commit). The transient mkdir lock is ignored. */
-function stagedIsMemoryOnly(hunchDir, env) {
+ *  code. Empty stage ⇒ [] (nothing to commit); invalid stage ⇒ null. The transient mkdir lock is ignored. */
+function stagedMemoryPaths(hunchDir, env) {
     let out = "";
+    let prefix = "";
     try {
-        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--name-status"], { encoding: "utf8", env });
+        prefix = execFileSync("git", ["-C", hunchDir, "rev-parse", "--show-prefix"], { encoding: "utf8", env }).trim().replace(/\\/g, "/");
     }
     catch {
-        return false;
+        return null;
+    }
+    if (!prefix)
+        return null; // a Hunch layout is a scoped subdirectory, never the whole repository
+    try {
+        out = execFileSync("git", ["-C", hunchDir, "diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-status"], { encoding: "utf8", env });
+    }
+    catch {
+        return null;
     }
     const lines = out.split("\n").map((l) => l.trim()).filter(Boolean);
     if (!lines.length)
-        return false;
+        return [];
+    const memoryPaths = [];
     for (const line of lines) {
         const parts = line.split("\t");
         const status = (parts[0] ?? "").trim();
@@ -165,42 +688,716 @@ function stagedIsMemoryOnly(hunchDir, env) {
         if (path.includes(".hunch-commit.lock"))
             continue; // transient lock dir, never a record
         if (!/^[AM]$/.test(status))
-            return false; // only Add / Modify — any D/R/C/T → not a memory sync
-        if (!path.endsWith(".json"))
-            return false; // the store is entirely JSON records
-    }
-    return true;
-}
-/** Merge the overlay's remote into the local branch (pull, no rebase), leaving a CLEAN tree
- *  whether it succeeds or not. Returns true when the branch is safe to push (merged, or there's
- *  no upstream to merge), false when a conflict was aborted (caller skips the push and retries
- *  on the next write). Never throws. */
-function mergeRemote(hunchDir, env) {
-    const tryGit = (args) => {
+            return null; // only Add / Modify — any D/R/C/T → not a memory sync
+        const normalizedPath = path.replace(/\\/g, "/");
+        if (!normalizedPath.startsWith(prefix))
+            return null; // never bless another staged JSON file
+        const memoryRelativePath = normalizedPath.slice(prefix.length);
+        if (!memoryRelativePath || memoryRelativePath === "local.json")
+            return null; // machine-local overlay pointer; never publish it
+        if (!normalizedPath.endsWith(".json"))
+            return null; // the store is entirely JSON records
+        memoryPaths.push(memoryRelativePath);
+    }
+    return [...new Set(memoryPaths)];
+}
+/** Enumerate ordinary JSON files already contained under an overlay. Push-capable
+ * stores force-add this exact allowlist so remote .gitignore, info/exclude, or an
+ * ambient excludesFile cannot silently stop the memory pump. Public push:false
+ * stores intentionally keep ordinary Git ignore semantics after migration. */
+function committableOverlayJsonPaths(hunchDir) {
+    try {
+        const root = realpathSync(hunchDir);
+        const paths = [];
+        const walk = (dir, prefix = "") => {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                if (!prefix && entry.name === ".hunch-commit.lock")
+                    continue;
+                const absolute = join(dir, entry.name);
+                const relativeName = prefix ? `${prefix}/${entry.name}` : entry.name;
+                const stat = lstatSync(absolute);
+                if (stat.isSymbolicLink())
+                    return false;
+                if (stat.isDirectory()) {
+                    if (!walk(absolute, relativeName))
+                        return false;
+                }
+                else if (!stat.isFile()) {
+                    return false;
+                }
+                else if (relativeName.endsWith(".json") && relativeName !== "local.json") {
+                    const fromRoot = relative(root, realpathSync(absolute));
+                    if (fromRoot === ".." || fromRoot.startsWith(`..${sep}`) || isAbsolute(fromRoot))
+                        return false;
+                    paths.push(relativeName);
+                }
+                else if (relativeName === "local.json") {
+                    return false;
+                }
+                else if (/^[^/]+\.sqlite[^/]*$/i.test(relativeName)
+                    || relativeName.split("/").some((segment) => segment.includes(".tmp"))
+                    || relativeName === "events.log") {
+                    // Known clone-local/derived artifacts are never staged. Everything
+                    // else is a topology violation: a shared graph repository cannot
+                    // quietly carry arbitrary source alongside its JSON memory.
+                    continue;
+                }
+                else {
+                    return false;
+                }
+            }
+            return true;
+        };
+        return walk(root) ? paths.sort() : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** True only when the checked-out Hunch tree has no staged, unstaged, untracked,
+ *  or conflicted memory bytes. Remote sync must never use autostash: applying a
+ *  stash can feed a user's uncommitted record through the structured merge driver
+ *  and replace it with a higher-confidence remote record. */
+function hunchWorktreeClean(hunchDir, env) {
+    try {
+        return execFileSync("git", ["-C", hunchDir, "status", "--porcelain=v1", "--untracked-files=all", "--", "."], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 2_000,
+        }).trim() === "";
+    }
+    catch {
+        return false;
+    }
+}
+function overlayGitTreeIsSafe(hunchDir, revision, env) {
+    if (!/^[0-9a-f]+$/i.test(revision))
+        return false;
+    try {
+        const listing = execFileSync("git", ["-C", hunchDir, "ls-tree", "--full-tree", "-r", "-t", "-z", revision], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 2_000,
+            maxBuffer: 64 * 1024 * 1024,
+        });
+        return hunchTreeAttributesAreSafe(listing, (oid) => {
+            try {
+                return execFileSync("git", ["-C", hunchDir, "cat-file", "blob", oid], {
+                    encoding: "utf8",
+                    stdio: ["ignore", "pipe", "ignore"],
+                    env,
+                    timeout: 2_000,
+                    maxBuffer: 4 * 1024 * 1024,
+                });
+            }
+            catch {
+                return null;
+            }
+        });
+    }
+    catch {
+        return false;
+    }
+}
+const MAX_ATTRIBUTES_BYTES = 4 * 1024 * 1024;
+function boundedAttributesFileIsSafe(file, expectedCanonicalPath) {
+    try {
+        const stat = lstatSync(file);
+        if (stat.isSymbolicLink() || !stat.isFile() || stat.nlink !== 1 || stat.size > MAX_ATTRIBUTES_BYTES)
+            return false;
+        if (!sameFilesystemEntry(file, expectedCanonicalPath))
+            return false;
+        return hunchAttributesAreSafe(readFileSync(file, "utf8"));
+    }
+    catch (error) {
+        return error.code === "ENOENT";
+    }
+}
+function absoluteGitMetadataDir(cwd, env) {
+    try {
+        const raw = execFileSync("git", ["-C", cwd, "rev-parse", "--absolute-git-dir"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 2_000,
+        }).trim();
+        if (!raw)
+            return null;
+        const canonical = realpathSync(raw);
+        const stat = lstatSync(canonical);
+        return !stat.isSymbolicLink() && stat.isDirectory() ? canonical : null;
+    }
+    catch {
+        return null;
+    }
+}
+function overlayGitMetadataDir(hunchDir, env) {
+    try {
+        const overlayRoot = dirname(realpathSync(hunchDir));
+        const expected = realpathSync(join(overlayRoot, ".git"));
+        const actual = absoluteGitMetadataDir(hunchDir, env);
+        return actual && sameFilesystemEntry(actual, expected) ? expected : null;
+    }
+    catch {
+        return null;
+    }
+}
+/** Attribute sources not stored in the fetched tree can still influence Git's
+ * clean/smudge pipeline. Validate the live root and nested Hunch attributes and
+ * the otherwise-unavoidable $GIT_DIR/info/attributes before any add/merge/reset.
+ * Global and system sources are separately disabled on the command itself. */
+function overlayAttributeSourcesAreSafe(hunchDir, env) {
+    try {
+        const canonicalHunch = realpathSync(hunchDir);
+        const overlayRoot = dirname(canonicalHunch);
+        if (canonicalHunch !== join(overlayRoot, ".hunch") || !safeOverlayTree(overlayRoot))
+            return false;
+        const gitDir = overlayGitMetadataDir(hunchDir, env);
+        if (!gitDir)
+            return false;
+        if (!boundedAttributesFileIsSafe(join(overlayRoot, ".gitattributes"), join(overlayRoot, ".gitattributes"))
+            || !boundedAttributesFileIsSafe(join(gitDir, "info", "attributes"), join(gitDir, "info", "attributes"))) {
+            return false;
+        }
+        const walk = (dir) => {
+            for (const entry of readdirSync(dir, { withFileTypes: true })) {
+                if (dir === canonicalHunch && entry.name === ".hunch-commit.lock")
+                    continue;
+                const path = join(dir, entry.name);
+                const stat = lstatSync(path);
+                if (stat.isSymbolicLink())
+                    return false;
+                if (stat.isDirectory()) {
+                    if (!walk(path))
+                        return false;
+                }
+                else if (!stat.isFile()) {
+                    return false;
+                }
+                else if (entry.name === ".gitattributes"
+                    && !boundedAttributesFileIsSafe(path, path)) {
+                    return false;
+                }
+            }
+            return true;
+        };
+        return walk(canonicalHunch);
+    }
+    catch {
+        return false;
+    }
+}
+const TEAM_FETCH_REF = "refs/hunch/team-sync";
+function contractReady(contract) {
+    if (!contract)
+        return true;
+    if (!contract.fetchUrl || !contract.pushUrl || !/^refs\/heads\/[A-Za-z0-9][A-Za-z0-9._/-]*$/.test(contract.ref)) {
+        return false;
+    }
+    try {
+        return contract.verify();
+    }
+    catch {
+        return false;
+    }
+}
+/** Team network operations deliberately ignore process-level Git command/config
+ * injection. Repository-local route overrides are rejected by the contract
+ * verifier; these variables are the remaining ambient way to replace SSH or add
+ * arbitrary `-c` entries between validation and use. */
+function boundedTeamEnv(env) {
+    const bounded = foreignRepoEnv(env);
+    for (const key of Object.keys(bounded)) {
+        if (key === "GIT_SSH" || key === "GIT_SSH_COMMAND" || key === "GIT_CONFIG_PARAMETERS"
+            || key === "GIT_CONFIG_COUNT" || /^GIT_CONFIG_(?:KEY|VALUE)_\d+$/.test(key)) {
+            delete bounded[key];
+        }
+    }
+    bounded.GIT_CONFIG_NOSYSTEM = "1";
+    bounded.GIT_ATTR_NOSYSTEM = "1";
+    bounded.GIT_ALLOW_PROTOCOL = "https:ssh:git:file";
+    bounded.GIT_TERMINAL_PROMPT = "0";
+    return bounded;
+}
+function disabledHooksDir(hunchDir) {
+    try {
+        const gitDir = absoluteGitMetadataDir(hunchDir, foreignRepoEnv(process.env));
+        if (!gitDir)
+            return null;
+        const hooksDir = join(gitDir, "hunch-disabled-hooks");
+        mkdirSync(hooksDir, { recursive: true });
+        const stat = lstatSync(hooksDir);
+        if (stat.isSymbolicLink() || !stat.isDirectory()
+            || relative(gitDir, realpathSync(hooksDir)) !== "hunch-disabled-hooks"
+            || readdirSync(hooksDir).length !== 0)
+            return null;
+        return hooksDir;
+    }
+    catch {
+        return null;
+    }
+}
+/** List every branch on the exact contract URL. A team graph has either zero
+ * branches while bootstrapping or exactly its one canonical branch. */
+function contractRemoteHeads(hunchDir, contract, direction, env, timeoutMs) {
+    if (!contractReady(contract))
+        return null;
+    const url = direction === "fetch" ? contract.fetchUrl : contract.pushUrl;
+    const hooksDir = disabledHooksDir(hunchDir);
+    if (!hooksDir)
+        return null;
+    try {
+        const out = execFileSync("git", [
+            "-C", hunchDir,
+            "-c", `core.hooksPath=${hooksDir}`,
+            "ls-remote", "--refs", "--heads", "--upload-pack=git-upload-pack", url,
+        ], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env: boundedTeamEnv(env),
+            timeout: timeoutMs,
+        });
+        if (!contractReady(contract))
+            return null;
+        const heads = [];
+        for (const line of out.split(/\r?\n/).filter(Boolean)) {
+            const match = line.match(/^([0-9a-f]{40,64})\t(refs\/heads\/.+)$/i);
+            if (!match)
+                return null;
+            heads.push({ oid: match[1], ref: match[2] });
+        }
+        return heads;
+    }
+    catch {
+        return null;
+    }
+}
+function fetchContractRef(hunchDir, contract, env, timeoutMs) {
+    if (!contractReady(contract))
+        return "";
+    const hooksDir = disabledHooksDir(hunchDir);
+    if (!hooksDir)
+        return "";
+    try {
+        execFileSync("git", [
+            "-C", hunchDir,
+            "-c", `core.hooksPath=${hooksDir}`,
+            "fetch", "--no-tags", "--no-write-fetch-head", "--upload-pack=git-upload-pack",
+            contract.fetchUrl, `+${contract.ref}:${TEAM_FETCH_REF}`,
+        ], { stdio: "ignore", env: boundedTeamEnv(env), timeout: timeoutMs });
+        if (!contractReady(contract))
+            return "";
+        const oid = execFileSync("git", ["-C", hunchDir, "rev-parse", "--verify", TEAM_FETCH_REF], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+        return /^[0-9a-f]{40,64}$/i.test(oid) ? oid : "";
+    }
+    catch {
+        return "";
+    }
+}
+function setContractUpstream(hunchDir, contract, env) {
+    try {
+        const branch = execFileSync("git", ["-C", hunchDir, "symbolic-ref", "--quiet", "--short", "HEAD"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+        if (!branch)
+            return false;
+        const remoteBranch = contract.ref.slice("refs/heads/".length);
+        let oid = gitSafeWithEnv(["rev-parse", "--verify", TEAM_FETCH_REF], hunchDir, env);
+        if (!oid)
+            oid = headShaWithEnv(hunchDir, env);
+        if (!oid || !remoteBranch)
+            return false;
+        execFileSync("git", ["-C", hunchDir, "update-ref", `refs/remotes/origin/${remoteBranch}`, oid], {
+            stdio: "ignore", env, timeout: 2_000,
+        });
+        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.remote`, "origin"], { stdio: "ignore", env, timeout: 2_000 });
+        execFileSync("git", ["-C", hunchDir, "config", `branch.${branch}.merge`, contract.ref], { stdio: "ignore", env, timeout: 2_000 });
+        return contractReady(contract);
+    }
+    catch {
+        return false;
+    }
+}
+/** A fresh clone of an empty remote has no HEAD, but auto-wiring creates the
+ * default manifest before another teammate may publish first. That one generated
+ * file is safe to replace with the now-canonical remote tree; any actual record or
+ * other dirty path makes bootstrap fail closed. */
+function unbornBootstrapFingerprint(hunchDir, env) {
+    try {
+        const status = execFileSync("git", ["-C", hunchDir, "status", "--porcelain=v1", "--untracked-files=all", "--", "."], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+        const lines = status ? status.split(/\r?\n/) : [];
+        if (lines.some((line) => !/^\?\? (?:\.hunch\/)?manifest\.json$/.test(line.trim())))
+            return null;
+        let manifest = "";
+        try {
+            manifest = readFileSync(join(hunchDir, "manifest.json"), "utf8");
+            const value = JSON.parse(manifest);
+            if (!value || Array.isArray(value) || typeof value !== "object"
+                || Object.keys(value).some((key) => key !== "schema_version")
+                || typeof value.schema_version !== "number")
+                return null;
+        }
+        catch {
+            if (lines.length)
+                return null;
+        }
+        return createHash("sha256").update(status).update("\0").update(manifest).digest("hex");
+    }
+    catch {
+        return null;
+    }
+}
+function adoptContractHead(hunchDir, fetchedHead, contract, env, fingerprint) {
+    if (unbornBootstrapFingerprint(hunchDir, env) !== fingerprint || !contractReady(contract))
+        return false;
+    const hooksDir = disabledHooksDir(hunchDir);
+    if (!hooksDir)
+        return false;
+    const manifest = join(hunchDir, "manifest.json");
+    const backup = join(hunchDir, ".hunch-commit.lock", "bootstrap-manifest.json");
+    let moved = false;
+    try {
+        try {
+            renameSync(manifest, backup);
+            moved = true;
+        }
+        catch { /* absent default manifest */ }
+        execFileSync("git", [
+            "-C", hunchDir,
+            "-c", `core.hooksPath=${hooksDir}`,
+            "-c", `core.attributesFile=${gitNullDevice()}`,
+            "reset", "--hard", fetchedHead,
+        ], {
+            stdio: "ignore", env, timeout: 5_000,
+        });
+        return overlayGitTreeIsSafe(hunchDir, headShaWithEnv(hunchDir, env), env)
+            && overlayAttributeSourcesAreSafe(hunchDir, env);
+    }
+    catch {
+        if (moved) {
+            try {
+                renameSync(backup, manifest);
+            }
+            catch { /* leave the durable backup under the lock */ }
+        }
+        return false;
+    }
+    finally {
+        if (moved)
+            try {
+                rmSync(backup, { force: true });
+            }
+            catch { /* lock cleanup is the final backstop */ }
+    }
+}
+function mergeRemote(hunchDir, env, timeoutMs, contract, allowUnrelatedHistories = false) {
+    env = machineCommitEnv(hunchDir, env);
+    env.GIT_ATTR_NOSYSTEM = "1";
+    let overlayRoot = "";
+    try {
+        overlayRoot = dirname(realpathSync(hunchDir));
+    }
+    catch {
+        return "failed";
+    }
+    if (!isGitRepoRoot(overlayRoot) || !safeOverlayTree(overlayRoot)
+        || !overlayAttributeSourcesAreSafe(hunchDir, env) || !contractReady(contract)) {
+        return "failed";
+    }
+    const localHead = headShaWithEnv(hunchDir, env);
+    const unbornFingerprint = localHead ? null : unbornBootstrapFingerprint(hunchDir, env);
+    if (localHead ? !hunchWorktreeClean(hunchDir, env) : !unbornFingerprint)
+        return "failed";
+    const hooksDir = disabledHooksDir(hunchDir);
+    if (!hooksDir)
+        return "failed";
+    const tryGit = (args, timeout = timeoutMs) => {
         try {
-            execFileSync("git", ["-C", hunchDir, ...args], { stdio: "ignore", env });
+            execFileSync("git", [
+                "-C", hunchDir,
+                "-c", `core.hooksPath=${hooksDir}`,
+                "-c", `core.attributesFile=${gitNullDevice()}`,
+                "-c", "commit.gpgsign=false",
+                ...args,
+            ], {
+                stdio: "ignore", env, timeout,
+            });
             return true;
         }
         catch {
             return false;
         }
     };
-    if (!tryGit(["rev-parse", "--abbrev-ref", "@{upstream}"]))
-        return true; // no remote/offline → push no-ops
-    if (tryGit(["pull", "--no-edit", "--no-rebase", "--autostash"]))
+    let fetchedHead = "";
+    if (contract) {
+        const heads = contractRemoteHeads(hunchDir, contract, "fetch", env, timeoutMs);
+        if (!heads)
+            return "failed";
+        if (heads.length === 0)
+            return "unconfigured";
+        if (heads.length !== 1 || heads[0].ref !== contract.ref)
+            return "failed";
+        fetchedHead = fetchContractRef(hunchDir, contract, env, timeoutMs);
+    }
+    else {
+        if (!tryGit(["rev-parse", "--abbrev-ref", "@{upstream}"], 2_000))
+            return "unconfigured";
+        if (!tryGit(["fetch", "--no-tags"]))
+            return "failed";
+        fetchedHead = upstreamSha(hunchDir, env);
+    }
+    if (!fetchedHead || !overlayGitTreeIsSafe(hunchDir, fetchedHead, env))
+        return "failed";
+    // Another process need not honor Hunch's lock. Re-prove both the exact local
+    // revision and the filesystem boundary after the network operation, before
+    // Git is permitted to materialize the already-validated fetched tree.
+    if (headShaWithEnv(hunchDir, env) !== localHead
+        || !safeOverlayTree(overlayRoot)
+        || !overlayAttributeSourcesAreSafe(hunchDir, env)
+        || (localHead ? !hunchWorktreeClean(hunchDir, env) : unbornBootstrapFingerprint(hunchDir, env) !== unbornFingerprint)
+        || (localHead && !overlayGitTreeIsSafe(hunchDir, localHead, env))
+        || !contractReady(contract))
+        return "failed";
+    // Canonicalize local branch/upstream metadata before the worktree mutation.
+    // If this fails, the exact fetched tree has not been materialized yet.
+    if (contract && !setContractUpstream(hunchDir, contract, env))
+        return "failed";
+    if (!localHead && contract && unbornFingerprint) {
+        return adoptContractHead(hunchDir, fetchedHead, contract, env, unbornFingerprint) ? "merged" : "failed";
+    }
+    if (tryGit(["merge", "--no-edit", ...(allowUnrelatedHistories ? ["--allow-unrelated-histories"] : []), fetchedHead])) {
+        return safeOverlayTree(overlayRoot)
+            && overlayAttributeSourcesAreSafe(hunchDir, env)
+            && contractReady(contract)
+            && overlayGitTreeIsSafe(hunchDir, headShaWithEnv(hunchDir, env), env)
+            ? "merged"
+            : "failed";
+    }
+    tryGit(["merge", "--abort"], 2_000); // conflict/timeout → restore a clean tree
+    return "failed";
+}
+function upstreamSha(hunchDir, env) {
+    try {
+        return execFileSync("git", ["-C", hunchDir, "rev-parse", "@{upstream}"], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        return "";
+    }
+}
+function tryPush(hunchDir, env, timeoutMs, contract) {
+    if (!contractReady(contract))
+        return false;
+    const hooksDir = disabledHooksDir(hunchDir);
+    if (!hooksDir)
+        return false;
+    try {
+        if (contract && !setContractUpstream(hunchDir, contract, env))
+            return false;
+        const args = contract
+            ? ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push", "--receive-pack=git-receive-pack", contract.pushUrl, `HEAD:${contract.ref}`]
+            : ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push"];
+        execFileSync("git", args, { stdio: "ignore", env: contract ? boundedTeamEnv(env) : env, timeout: timeoutMs });
+        return contractReady(contract);
+    }
+    catch {
+        return false;
+    }
+}
+/** Publish an unborn/untracked local branch to a genuinely empty shared remote
+ *  and establish its upstream. This path is deliberately narrower than a generic
+ *  `push -u`: it selects only an explicit configured push remote (or the sole
+ *  remote), proves that remote has no refs, snapshots its identity across the
+ *  network check, and uses a non-force push so a concurrent first writer wins
+ *  safely instead of being overwritten. */
+function establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract) {
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot)
+        || !hunchWorktreeClean(hunchDir, env)
+        || !contractReady(contract))
+        return false;
+    if (contract) {
+        const heads = contractRemoteHeads(hunchDir, contract, "push", env, timeoutMs);
+        if (!heads || heads.length !== 0 || !contractReady(contract))
+            return false;
+        // Exact URL + exact canonical ref + non-force push. If another teammate wins
+        // the first-writer race after the empty proof, Git rejects this safely and the
+        // bounded retry path fetches/merges that winner.
+        return tryPush(hunchDir, env, timeoutMs, contract);
+    }
+    let branch = "";
+    let remotes = [];
+    let preferred = "";
+    try {
+        branch = execFileSync("git", ["-C", hunchDir, "symbolic-ref", "--quiet", "--short", "HEAD"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+        remotes = execFileSync("git", ["-C", hunchDir, "remote"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).split("\n").map((remote) => remote.trim()).filter(Boolean);
+        preferred = execFileSync("git", ["-C", hunchDir, "config", "--get", "remote.pushDefault"], {
+            encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+        }).trim();
+    }
+    catch {
+        // A missing remote.pushDefault is normal; choose the sole remote below.
+    }
+    const remote = preferred && remotes.includes(preferred)
+        ? preferred
+        : remotes.length === 1 ? remotes[0] : "";
+    if (!branch || !remote)
+        return false;
+    const pushIdentity = () => {
+        try {
+            const url = execFileSync("git", ["-C", hunchDir, "remote", "get-url", "--push", remote], {
+                encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env, timeout: 2_000,
+            }).trim();
+            return remoteIdentity(url, hunchDir);
+        }
+        catch {
+            return "";
+        }
+    };
+    const before = pushIdentity();
+    if (!before)
+        return false;
+    try {
+        const refs = execFileSync("git", ["-C", hunchDir, "ls-remote", "--refs", remote], {
+            encoding: "utf8",
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: timeoutMs,
+        }).trim();
+        if (refs)
+            return false;
+    }
+    catch {
+        return false;
+    }
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot)
+        || !hunchWorktreeClean(hunchDir, env)
+        || pushIdentity() !== before)
+        return false;
+    try {
+        const hooksDir = disabledHooksDir(hunchDir);
+        if (!hooksDir)
+            return false;
+        execFileSync("git", ["-C", hunchDir, "-c", `core.hooksPath=${hooksDir}`, "push", "--set-upstream", remote, `HEAD:refs/heads/${branch}`], {
+            stdio: "ignore",
+            env,
+            timeout: timeoutMs,
+        });
         return true;
-    tryGit(["merge", "--abort"]); // conflict the driver couldn't resolve → restore a clean tree
-    return false;
+    }
+    catch {
+        return false;
+    }
+}
+/** Push once, then retry exactly once only when a bounded pull proves the upstream
+ *  advanced during the first push seam. Offline/auth/hook failures with an unchanged
+ *  upstream never loop, and every remote mutation re-proves the publication boundary. */
+function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeoutMs, contract) {
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
+        return false;
+    const before = contract
+        ? gitSafeWithEnv(["rev-parse", "--verify", TEAM_FETCH_REF], hunchDir, env)
+        : upstreamSha(hunchDir, env);
+    if (!before)
+        return establishEmptyRemoteUpstream(hunchDir, env, protectedRepoRoot, timeoutMs, contract);
+    if (tryPush(hunchDir, env, timeoutMs, contract))
+        return true;
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
+        return false;
+    const merged = mergeRemote(hunchDir, env, timeoutMs, contract);
+    const after = contract
+        ? gitSafeWithEnv(["rev-parse", "--verify", TEAM_FETCH_REF], hunchDir, env)
+        : upstreamSha(hunchDir, env);
+    if (merged !== "merged" || !before || !after || before === after)
+        return false;
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(contract))
+        return false;
+    return tryPush(hunchDir, env, timeoutMs, contract);
+}
+export function pullHunchStatus(hunchDir, opts = {}) {
+    const env = foreignRepoEnv({
+        ...process.env,
+        ...opts.env,
+        HUNCH_SYNC: "1",
+        GIT_TERMINAL_PROMPT: "0",
+        GIT_MERGE_AUTOEDIT: "no",
+    });
+    const before = headShaWithEnv(hunchDir, env);
+    const lock = join(hunchDir, ".hunch-commit.lock");
+    if (acquireCommitLock(lock).state !== "acquired")
+        return "busy";
+    try {
+        const merged = mergeRemote(hunchDir, env, opts.timeoutMs ?? READ_REMOTE_TIMEOUT_MS, opts.remote, opts.allowUnrelatedHistories ?? false);
+        if (merged === "failed" || merged === "unconfigured" || !contractReady(opts.remote)) {
+            return merged === "unconfigured" ? merged : "failed";
+        }
+        return headShaWithEnv(hunchDir, env) !== before ? "updated" : "current";
+    }
+    finally {
+        try {
+            rmSync(lock, { recursive: true, force: true });
+        }
+        catch { /* released best-effort */ }
+    }
 }
-/** Best-effort READ-side sync: merge the overlay's remote into the local branch (e.g. on MCP
- *  server start) so this machine/session sees other machines' memory. Never throws; leaves a
- *  clean tree. Serialized with the commit lock so it can't race a concurrent flush. */
 export function pullHunch(hunchDir) {
+    return pullHunchStatus(hunchDir) === "updated";
+}
+/** Explicit retry path for a clean overlay that already has a local memory commit
+ *  stranded by an earlier offline/rejected push. Unlike commitAndPushHunch this
+ *  creates no commit: it only converges and publishes existing overlay history. */
+export function syncExistingHunch(hunchDir, protectedRepoRoot, timeoutMs = CAPTURE_REMOTE_TIMEOUT_MS, remote) {
+    if (unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(remote))
+        return "failed";
     const lock = join(hunchDir, ".hunch-commit.lock");
-    if (!acquireCommitLock(lock))
-        return;
+    if (acquireCommitLock(lock).state !== "acquired")
+        return "failed";
     try {
-        mergeRemote(hunchDir, { ...process.env, HUNCH_SYNC: "1" });
+        const env = foreignRepoEnv({
+            ...process.env,
+            HUNCH_SYNC: "1",
+            GIT_TERMINAL_PROMPT: "0",
+            GIT_MERGE_AUTOEDIT: "no",
+        });
+        const merged = mergeRemote(hunchDir, env, timeoutMs, remote);
+        if (merged === "failed" || unsafeOverlayPublication(hunchDir, protectedRepoRoot) || !contractReady(remote))
+            return "failed";
+        if (merged === "unconfigured") {
+            return pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeoutMs, remote) ? "pushed" : "failed";
+        }
+        const upstream = remote
+            ? gitSafeWithEnv(["rev-parse", "--verify", TEAM_FETCH_REF], hunchDir, env)
+            : upstreamSha(hunchDir, env);
+        if (!upstream)
+            return "failed";
+        let ahead = false;
+        try {
+            ahead = execFileSync("git", ["-C", hunchDir, "rev-list", "--count", `${upstream}..HEAD`], {
+                encoding: "utf8",
+                stdio: ["ignore", "pipe", "ignore"],
+                env,
+                timeout: 2_000,
+            }).trim() !== "0";
+        }
+        catch {
+            return "failed";
+        }
+        if (!ahead)
+            return "current";
+        return pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeoutMs, remote) ? "pushed" : "failed";
     }
     finally {
         try {
@@ -209,28 +1406,127 @@ export function pullHunch(hunchDir) {
         catch { /* released best-effort */ }
     }
 }
-/** Atomic mkdir lock; reclaims a stale lock (a crashed holder) older than 60s. Returns
- *  false when another live holder owns it — the caller skips rather than blocks. */
-function acquireCommitLock(lock) {
+const UNKNOWN_LOCK_STALE_MS = 10 * 60_000;
+function createOwnedCommitLock(lock) {
+    let created = false;
     try {
+        // mkdir is the exclusive atomic operation here. Renaming a staged directory
+        // is NOT exclusive on POSIX: it may replace an already-existing empty lock
+        // directory, which would steal a fresh legacy/ownerless lock. There is a
+        // harmless ownerless window between these two mkdir calls; contenders treat
+        // it as held until the conservative legacy TTL expires.
         mkdirSync(lock);
+        created = true;
+        // Empty directories are not Git worktree entries, so owner metadata cannot
+        // be staged by the memory-only `git add .` seam.
+        mkdirSync(join(lock, `owner-${process.pid}`));
         return true;
     }
     catch {
-        try {
-            if (Date.now() - statSync(lock).mtimeMs > 60_000) {
+        // If the exclusive mkdir succeeded but owner creation somehow failed, only
+        // this process can have created the still-ownerless directory. Remove it so
+        // a transient local failure does not strand every writer for the full TTL.
+        if (created && !commitLockOwner(lock)) {
+            try {
                 rmSync(lock, { recursive: true, force: true });
-                mkdirSync(lock);
-                return true;
             }
+            catch { /* best effort */ }
+        }
+        return false;
+    }
+}
+function commitLockOwner(lock) {
+    try {
+        for (const name of readdirSync(lock)) {
+            const match = name.match(/^owner-([1-9][0-9]*)$/);
+            if (match)
+                return { name, pid: Number(match[1]) };
+        }
+    }
+    catch { /* vanished or unreadable */ }
+    return null;
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return error.code === "EPERM";
+    }
+}
+/** Atomic directory lock with PID ownership. A dead owner is recoverable
+ * immediately; a legacy owner-less lock is reclaimed only after a TTL safely
+ * above the longest bounded sync. The fixed reclaim directory serializes
+ * competing crash recovery attempts and the owner is re-read after claiming. */
+function acquireCommitLock(lock) {
+    if (createOwnedCommitLock(lock))
+        return { state: "acquired" };
+    const observed = commitLockOwner(lock);
+    if (observed && processIsAlive(observed.pid))
+        return { state: "held-live", ownerPid: observed.pid };
+    let reclaimable = !!observed;
+    if (!observed) {
+        try {
+            reclaimable = Date.now() - statSync(lock).mtimeMs > UNKNOWN_LOCK_STALE_MS;
+        }
+        catch {
+            return createOwnedCommitLock(lock) ? { state: "acquired" } : { state: "held-unknown" };
         }
-        catch { /* lock vanished or races another reclaimer — treat as held */ }
+    }
+    if (!reclaimable)
+        return { state: "held-unknown" };
+    const claim = join(lock, "reclaim");
+    try {
+        mkdirSync(claim);
+    }
+    catch {
+        return { state: "held-unknown" };
+    }
+    const current = commitLockOwner(lock);
+    if ((observed && (!current || current.name !== observed.name || processIsAlive(current.pid)))
+        || (!observed && current)) {
+        try {
+            rmSync(claim, { recursive: true, force: true });
+        }
+        catch { /* best effort */ }
+        return current && processIsAlive(current.pid)
+            ? { state: "held-live", ownerPid: current.pid }
+            : { state: "held-unknown" };
+    }
+    try {
+        rmSync(lock, { recursive: true, force: true });
+    }
+    catch {
+        return { state: "held-unknown" };
+    }
+    return createOwnedCommitLock(lock) ? { state: "acquired" } : { state: "held-unknown" };
+}
+function waitForCommitLockHandoff(lock, first, timeoutMs) {
+    if (first.state !== "held-live" || first.ownerPid === process.pid)
         return false;
+    const deadline = Date.now() + timeoutMs;
+    const sleeper = new Int32Array(new SharedArrayBuffer(4));
+    let attempt = first;
+    while (Date.now() < deadline) {
+        if (attempt.state === "acquired")
+            return true;
+        if (attempt.state !== "held-live" || attempt.ownerPid === process.pid)
+            return false;
+        Atomics.wait(sleeper, 0, 0, Math.min(25, deadline - Date.now()));
+        attempt = acquireCommitLock(lock);
     }
+    return false;
 }
 export function headSha(cwd) {
     return gitSafe(["rev-parse", "HEAD"], cwd);
 }
+/** HEAD for a repository that is not the invocation repository. Unlike
+ * headSha, this deliberately ignores code-repo GIT_DIR/GIT_INDEX_FILE state
+ * inherited from hooks. */
+export function isolatedHeadSha(cwd) {
+    return gitSafeIsolated(["rev-parse", "HEAD"], cwd);
+}
 /** Stop tracking `paths` in git (remove from the INDEX only — keep the working-tree
  *  files). Used by `hunch private --migrate` to un-publish the .hunch memory tree
  *  without deleting it locally. `--ignore-unmatch` makes an already-untracked path a
@@ -319,16 +1615,266 @@ export function pushCurrentBranch(root) {
         return false;
     }
 }
-/** Revert a single memory move locally (no push). Returns true on success. A
- *  conflicting revert is aborted so the working tree is never left half-reverted. */
+const REVERTABLE_RECORD_DIRS = new Set([
+    "components",
+    "edges",
+    "symbols",
+    "decisions",
+    "bugs",
+    "constraints",
+    "runbooks",
+    "evidence",
+    "corpora",
+    "policies",
+    "proofs",
+    "plans",
+    "dispositions",
+    "shadow",
+]);
+const REVERTABLE_AUXILIARY_PATHS = new Set([
+    ".hunch/manifest.json",
+    ".hunch/config.json",
+]);
+const PARTIALLY_MANAGED_GROUNDING_PATHS = new Set([
+    "AGENTS.md",
+    "CLAUDE.md",
+    ".github/copilot-instructions.md",
+]);
+const FULLY_MANAGED_GROUNDING_PATHS = new Set([
+    ".cursor/rules/hunch.mdc",
+    ".windsurf/rules/hunch.md",
+]);
+const HUNCH_GROUNDING_START = Buffer.from("<!-- HUNCH:START — auto-generated, do not edit by hand -->", "utf8");
+const HUNCH_GROUNDING_END = Buffer.from("<!-- HUNCH:END -->", "utf8");
+const HUNCH_GROUNDING_SENTINEL = Buffer.from("\0HUNCH-MANAGED-REGION\0", "utf8");
+const MAX_REVERT_GROUNDING_BYTES = 8 * 1024 * 1024;
+const REVERT_TRANSFORM_ATTRIBUTES = ["filter", "working-tree-encoding", "ident", "eol", "text", "crlf", "merge"];
+function revertGitEnv() {
+    const env = foreignRepoEnv(process.env);
+    // A local refs/replace entry can make a safe-looking SHA behave like an
+    // entirely different commit. Every inspection and the revert itself must see
+    // the literal object graph the user named.
+    env.GIT_NO_REPLACE_OBJECTS = "1";
+    env.GIT_TERMINAL_PROMPT = "0";
+    env.GIT_ATTR_NOSYSTEM = "1";
+    return env;
+}
+function revertGitRaw(args, root, env) {
+    try {
+        return execFileSync("git", ["-C", root, ...args], {
+            encoding: "utf8",
+            maxBuffer: 64 * 1024 * 1024,
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 5_000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+function revertGit(args, root, env) {
+    return revertGitRaw(args, root, env)?.trim() ?? "";
+}
+function regularBlobAt(ref, path, root, env) {
+    const raw = revertGitRaw(["ls-tree", "-z", ref, "--", path], root, env);
+    if (raw == null)
+        return null;
+    const tab = raw.indexOf("\t");
+    if (tab < 0 || raw.slice(tab + 1) !== `${path}\0`)
+        return null;
+    const header = raw.slice(0, tab).match(/^(100644|100755) blob ([a-f0-9]{40,64})$/i);
+    return header ? { mode: header[1], oid: header[2] } : null;
+}
+function blobBytes(oid, root, env) {
+    try {
+        return execFileSync("git", ["-C", root, "cat-file", "blob", oid], {
+            maxBuffer: MAX_REVERT_GROUNDING_BYTES,
+            stdio: ["ignore", "pipe", "ignore"],
+            env,
+            timeout: 5_000,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+/** Preserve every byte outside Hunch's one well-formed managed region. These
+ * documents contain user/team instructions too; reverting a capture must never
+ * roll those bytes back merely because the same commit refreshed Hunch counts. */
+function groundingEnvelope(blob) {
+    const start = blob.indexOf(HUNCH_GROUNDING_START);
+    if (start < 0 || blob.indexOf(HUNCH_GROUNDING_START, start + HUNCH_GROUNDING_START.length) >= 0)
+        return null;
+    const end = blob.indexOf(HUNCH_GROUNDING_END, start + HUNCH_GROUNDING_START.length);
+    if (end < 0 || blob.indexOf(HUNCH_GROUNDING_END, end + HUNCH_GROUNDING_END.length) >= 0)
+        return null;
+    return Buffer.concat([
+        blob.subarray(0, start),
+        HUNCH_GROUNDING_SENTINEL,
+        blob.subarray(end + HUNCH_GROUNDING_END.length),
+    ]);
+}
+function onlyManagedGroundingChanged(before, after, root, env) {
+    if (before.mode !== after.mode)
+        return false;
+    const beforeBytes = blobBytes(before.oid, root, env);
+    const afterBytes = blobBytes(after.oid, root, env);
+    if (!beforeBytes || !afterBytes)
+        return false;
+    const beforeEnvelope = groundingEnvelope(beforeBytes);
+    const afterEnvelope = groundingEnvelope(afterBytes);
+    return !!beforeEnvelope && !!afterEnvelope && beforeEnvelope.equals(afterEnvelope);
+}
+function hunchJsonKind(path) {
+    if (REVERTABLE_AUXILIARY_PATHS.has(path))
+        return "auxiliary";
+    const match = path.match(/^\.hunch\/([^/]+)\/([A-Za-z0-9][A-Za-z0-9._-]*\.json)$/);
+    if (!match || !REVERTABLE_RECORD_DIRS.has(match[1]))
+        return null;
+    if ((match[1] === "symbols" || match[1] === "edges") && match[2] !== "index.json")
+        return null;
+    return "record";
+}
+function pathsHaveTransformAttributes(paths, root, env) {
+    if (!paths.length)
+        return false;
+    const raw = revertGitRaw(["check-attr", "-z", ...REVERT_TRANSFORM_ATTRIBUTES, "--", ...paths], root, env);
+    if (raw == null)
+        return true;
+    const fields = raw.split("\0");
+    if (fields.at(-1) === "")
+        fields.pop();
+    if (fields.length !== paths.length * REVERT_TRANSFORM_ATTRIBUTES.length * 3)
+        return true;
+    for (let index = 0; index < fields.length; index += 3) {
+        const attribute = fields[index + 1];
+        const value = fields[index + 2];
+        if (!attribute || value == null || !REVERT_TRANSFORM_ATTRIBUTES.includes(attribute))
+            return true;
+        if (value !== "unspecified" && value !== "unset")
+            return true;
+    }
+    return false;
+}
+/** Is `sha` one exact, append-only public Hunch move that can be safely
+ * reverted? The timeline is selected with a `.hunch/` pathspec, so a mixed
+ * code+memory commit also appears there; validate the complete commit before
+ * allowing `git revert` to touch the checkout. */
+function revertableMemoryMove(sha, root) {
+    const env = revertGitEnv();
+    // Accept an exact hexadecimal object id/unique abbreviation only. Resolving
+    // HEAD, a branch, a rev expression, or an option-like string is outside the
+    // CLI's `<sha>` contract and would make the selected target mutable/ambiguous.
+    if (!/^[a-f0-9]{7,64}$/i.test(sha))
+        return null;
+    const commit = revertGit(["rev-parse", "--verify", "--quiet", `${sha}^{commit}`], root, env);
+    if (!/^[a-f0-9]{40,64}$/i.test(commit))
+        return null;
+    // Revert is allowed only from a pristine checkout/index. Include untracked
+    // paths: a successful revert followed by a later broad user commit must not
+    // accidentally publish pre-existing local bytes as part of the undo.
+    if (revertGitRaw(["status", "--porcelain=v1", "-z", "--untracked-files=all"], root, env) !== "")
+        return null;
+    const row = revertGit(["rev-list", "--parents", "-n", "1", commit], root, env)
+        .split(/\s+/)
+        .filter(Boolean);
+    if (row[0] !== commit || row.length > 2)
+        return null; // unknown or merge commit
+    const parent = row[1] ?? null;
+    try {
+        execFileSync("git", ["-C", root, "merge-base", "--is-ancestor", commit, "HEAD"], { stdio: "ignore", env, timeout: 5_000 });
+    }
+    catch {
+        return null; // never apply an unrelated/unpublished history fragment
+    }
+    const raw = revertGitRaw(["diff-tree", "--root", "--no-commit-id", "--name-status", "-r", "-z", commit], root, env);
+    if (raw == null)
+        return null;
+    const fields = raw.split("\0").filter((field) => field !== "");
+    let sawMemoryRecord = false;
+    const paths = [];
+    for (let index = 0; index < fields.length;) {
+        const status = fields[index++];
+        // A legitimate automatic memory move has exactly add/modify entries.
+        // Deletions, renames, copies, type changes, and unknown status codes need a
+        // future tombstone-aware protocol rather than an unrestricted Git revert.
+        if (status !== "A" && status !== "M")
+            return null;
+        const path = fields[index++];
+        if (!path)
+            return null;
+        paths.push(path);
+        const parts = path.split("/");
+        if (parts.some((part) => !part || part === "." || part === ".."))
+            return null;
+        const after = regularBlobAt(commit, path, root, env);
+        if (!after)
+            return null;
+        const before = status === "M" && parent ? regularBlobAt(parent, path, root, env) : null;
+        if (status === "M" && !before)
+            return null;
+        const memoryKind = hunchJsonKind(path);
+        if (memoryKind) {
+            sawMemoryRecord ||= memoryKind === "record";
+            continue;
+        }
+        if (FULLY_MANAGED_GROUNDING_PATHS.has(path))
+            continue;
+        if (PARTIALLY_MANAGED_GROUNDING_PATHS.has(path)) {
+            // Newly-created partially managed docs can contain arbitrary user prose
+            // outside the Hunch block. Only a proven managed-region refresh is safe.
+            if (status !== "M" || !before || !onlyManagedGroundingChanged(before, after, root, env))
+                return null;
+            continue;
+        }
+        return null;
+    }
+    // Manifest/config and grounding are auxiliary to a real graph mutation; they
+    // can never make a routing-only or generated-doc-only commit revertable.
+    if (!sawMemoryRecord || pathsHaveTransformAttributes(paths, root, env))
+        return null;
+    return { commit, paths };
+}
+/** Revert one validated memory-only move locally (no push). Returns true on
+ * success. Unsafe targets are refused before mutation; a conflicting revert is
+ * aborted so the working tree is never left half-reverted. */
 export function revertMemoryMove(sha, root) {
+    const target = revertableMemoryMove(sha, root);
+    if (!target)
+        return false;
+    const env = revertGitEnv();
     try {
-        execFileSync("git", ["-C", root, "revert", "--no-edit", sha], { stdio: "ignore" });
+        // Recheck the clean boundary after target inspection to narrow the race
+        // between validation and Git taking its own index lock.
+        if (revertGitRaw(["status", "--porcelain=v1", "-z", "--untracked-files=all"], root, env) !== "")
+            return false;
+        if (pathsHaveTransformAttributes(target.paths, root, env))
+            return false;
+        const hooksDir = disabledHooksDir(root);
+        if (!hooksDir)
+            return false;
+        execFileSync("git", [
+            "-C", root,
+            "-c", `core.hooksPath=${hooksDir}`,
+            "-c", "commit.gpgsign=false",
+            "-c", "core.autocrlf=false",
+            "-c", "core.eol=lf",
+            "-c", "core.safecrlf=false",
+            "revert", "--no-edit", "--no-gpg-sign", target.commit,
+        ], { stdio: "ignore", env, timeout: 15_000 });
         return true;
     }
     catch {
         try {
-            execFileSync("git", ["-C", root, "revert", "--abort"], { stdio: "ignore" });
+            execFileSync("git", [
+                "-C", root,
+                "-c", "commit.gpgsign=false",
+                "-c", "core.autocrlf=false",
+                "-c", "core.eol=lf",
+                "-c", "core.safecrlf=false",
+                "revert", "--abort",
+            ], { stdio: "ignore", env, timeout: 5_000 });
         }
         catch { /* nothing to abort */ }
         return false;
@@ -494,14 +2040,14 @@ export function fileGitMetrics(cwd, want, days = 90) {
 }
 /** Files staged for commit (for `hunch check` pre-commit enforcement). */
 export function stagedFiles(cwd) {
-    const out = gitSafe(["diff", "--cached", "--name-only", "--diff-filter=ACMR"], cwd);
+    const out = gitSafe(["diff", "--cached", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
 /** Files changed anywhere in the working tree compared with HEAD: both staged
  * and unstaged tracked files, plus untracked files. This powers the local,
  * pre-commit Change Gate; it never mutates the index or asks an agent/model. */
 export function workingFiles(cwd) {
-    const changed = gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
+    const changed = gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean);
     const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter(Boolean);
     return [...new Set([...changed, ...untracked])].sort();
 }
@@ -514,7 +2060,7 @@ export function revExists(ref, cwd) {
 /** Files a PR/branch changes vs `base` (3-dot: changes on HEAD since the merge-base,
  *  i.e. exactly the PR's own commits — the CI Constraint Guard's surface). */
 export function rangeFiles(base, cwd, head = "HEAD") {
-    const out = gitSafe(["diff", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
+    const out = gitSafe(["diff", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR", `${base}...${head}`], cwd);
     return out ? out.split("\n").filter(Boolean) : [];
 }
 /** Commit subjects on `head` since `base` (2-dot: commits added by the task),
@@ -526,14 +2072,14 @@ export function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
 /** The PR's unified diff vs `base` (3-dot), for the Regression Guard's structural
  *  analysis. Same noise-exclusion + truncation budget as commit/staged diffs. */
 export function rangeDiff(base, cwd, head = "HEAD", maxBytes = 60_000) {
-    const out = gitSafe(["diff", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
+    const out = gitSafe(["diff", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", `${base}...${head}`, "--", ...DIFF_NOISE], cwd);
     return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
 }
 /** Unified diff of the staged changes (for the Regression Guard's structural
  *  analysis). Excludes machine-generated noise and truncates at the SAME budget as
  *  commitDiff, so the staged and `--commit` guard paths can't diverge on big diffs. */
 export function stagedDiff(cwd, maxBytes = 60_000) {
-    const out = gitSafe(["diff", "--cached", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    const out = gitSafe(["diff", "--cached", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
     return out.length > maxBytes ? out.slice(0, maxBytes) + "\n…(diff truncated)…" : out;
 }
 /** Unified diff of the complete local working tree vs HEAD. Git's normal diff
@@ -542,12 +2088,15 @@ export function stagedDiff(cwd, maxBytes = 60_000) {
  * Binary/unreadable files remain in workingFiles (scope checks still apply) but
  * intentionally contribute no synthetic content to regression analysis. */
 export function workingDiff(cwd, maxBytes = 60_000) {
-    let out = gitSafe(["diff", "HEAD", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
-    const tracked = new Set(gitSafe(["diff", "HEAD", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
+    let out = gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--no-color", "--unified=2", "--", ...DIFF_NOISE], cwd);
+    const tracked = new Set(gitSafe(["diff", "HEAD", "--no-ext-diff", "--no-textconv", "--name-only", "--diff-filter=ACMR"], cwd).split("\n").filter(Boolean));
     const untracked = gitSafe(["ls-files", "--others", "--exclude-standard"], cwd).split("\n").filter((f) => f && !tracked.has(f));
+    const readWorkingFile = createRepoFileReader(cwd);
     for (const file of untracked) {
         try {
-            const text = readFileSync(join(cwd, file), "utf8");
+            const text = readWorkingFile(file);
+            if (text === null)
+                continue;
             if (text.includes("\0"))
                 continue;
             const lines = text.split("\n");