@davesheffer/hunch 1.42.0 → 1.44.0

package/dist/extractors/git.js

@@ -1607,6 +1607,12 @@ function pushWithOneRemoteAdvanceRetry(hunchDir, env, protectedRepoRoot, timeout
         return false;
     return tryPush(hunchDir, env, timeoutMs, contract, observe);
 }
+/** A strict guard may pass only on a pull that proved this clone's memory matches the
+ *  advertised remote: it advanced, was already current, or both are provably empty (a
+ *  brand-new shared memory repo before its first capture, #427). */
+export function teamPullIsFresh(status) {
+    return status === "updated" || status === "current" || status === "empty";
+}
 export function pullHunchStatus(hunchDir, opts = {}) {
     const env = foreignRepoEnv({
         ...process.env,
@@ -1622,7 +1628,13 @@ export function pullHunchStatus(hunchDir, opts = {}) {
     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";
+            if (merged !== "unconfigured" || !contractReady(opts.remote))
+                return "failed";
+            // The advertised remote has no branch yet AND this clone never committed memory:
+            // both sides are empty, so there is nothing to be stale against (#427). A clone
+            // WITH memory against an empty remote stays "unconfigured" (unpublished, or the
+            // remote lost its history) so strict guards keep failing closed on it.
+            return opts.remote && !before && !headShaWithEnv(hunchDir, env) ? "empty" : merged;
         }
         return headShaWithEnv(hunchDir, env) !== before ? "updated" : "current";
     }
@@ -2612,6 +2624,51 @@ export function commitRepairStatus(commit, ref, cwd) {
         return e.status === 1 ? "orphaned" : "unknown";
     }
 }
+/** commitRepairStatus against several tips: "orphaned" only when NO ref
+ *  reaches the commit. A historical `--range old..new` must not make a commit
+ *  that HEAD still reaches look orphaned just because it is newer than `new`
+ *  (#450). The first non-orphaned answer wins, so "unknown" is never upgraded. */
+export function commitRepairStatusAgainst(commit, refs, cwd) {
+    for (const ref of new Set(refs)) {
+        const status = commitRepairStatus(commit, ref, cwd);
+        if (status !== "orphaned")
+            return status;
+    }
+    return "orphaned";
+}
+/** `git patch-id --stable` of each commit, keyed by the sha exactly as given
+ *  (full or abbreviated). Same diff flags as the workspace ledger's squash
+ *  check. A merge or empty commit, an unknown sha, or any git failure leaves
+ *  no entry: a missing patch-id is never a match. One `git log` + one
+ *  `git patch-id` process for all of them. */
+export function commitPatchIds(shas, cwd) {
+    const out = new Map();
+    // Only shas that resolve: one unknown sha (a withheld queue entry) would make `git log`
+    // fail outright and drop every patch-id. Fed on stdin, so no argv length limit applies.
+    const exists = commitsExist([...new Set(shas)], cwd);
+    const valid = exists ? [...exists] : [];
+    if (!valid.length)
+        return out;
+    let ids;
+    try {
+        const log = execFileSync("git", ["-C", cwd, "log", "--stdin", "--no-walk=unsorted", "--format=%H", "-p", "--no-merges", "--binary", "--full-index", "--no-renames", "--no-ext-diff", "--no-textconv", "--"], { input: valid.join("\n") + "\n", maxBuffer: 256 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+        if (!log.byteLength)
+            return out;
+        ids = execFileSync("git", ["-C", cwd, "patch-id", "--stable"], { input: log, encoding: "utf8", maxBuffer: 16 * 1024 * 1024, timeout: 30_000, stdio: ["pipe", "pipe", "ignore"] });
+    }
+    catch {
+        return out;
+    }
+    for (const line of ids.split("\n")) {
+        const [patchId = "", commit = ""] = line.trim().split(/\s+/);
+        if (!/^[0-9a-f]{40,64}$/.test(patchId))
+            continue;
+        for (const sha of valid)
+            if (commit.startsWith(sha.toLowerCase()))
+                out.set(sha, patchId);
+    }
+    return out;
+}
 /** Machine-generated paths that carry no design "why" — lockfiles, build output,
  *  vendored deps, snapshots, source maps. Excluded from synthesis diffs via git
  *  pathspec BEFORE git assembles/orders the patch: a huge lockfile sorts ahead of
@@ -2713,9 +2770,23 @@ export function firstCommitForFile(file, cwd) {
         return added;
     return gitSafe(["log", "--reverse", "--format=%H", "--", file], cwd).split("\n").find(Boolean) ?? "";
 }
-/** ISO author-date of the most recent commit touching a file ("" if none). */
-export function lastChangeDate(file, cwd) {
-    return gitSafe(["log", "-1", "--format=%aI", "--", file], cwd);
+/** ISO author-date of the most recent commit touching a file ("" if none), as of `rev`
+ *  (default HEAD). */
+export function lastChangeDate(file, cwd, rev) {
+    return gitSafe(["log", "-1", "--format=%aI", ...(rev ? [rev] : []), "--", file], cwd);
+}
+/** The revision a checked change starts from, so freshness is judged WITHOUT the change
+ *  itself: a committed change under review must not make its own guarding record stale
+ *  (#426). `--base` diffs are 3-dot, so the merge-base; `--commit` is its parent;
+ *  staged/working changes are not committed yet, so HEAD (undefined). `--commit` judges
+ *  one commit in isolation, so an earlier commit of the same branch can still age the
+ *  record; `--base` (the CI guard) judges the whole branch and is the authoritative gate. */
+export function checkFreshnessRevision(source, cwd) {
+    if (source.commit)
+        return `${source.commit}^`;
+    if (source.base)
+        return gitSafe(["merge-base", source.base, "HEAD"], cwd) || source.base;
+    return undefined;
 }
 /**
  * Newest author date for every changed path selected by a bounded set of repository-relative
@@ -2841,11 +2912,17 @@ export function revExists(ref, cwd) {
 export function rangeFiles(base, cwd, head = "HEAD") {
     return nulPaths(gitOutputOrNull(["-c", "core.quotePath=false", "diff", "--no-ext-diff", "--no-textconv", "--name-only", "-z", "--diff-filter=ACMR", `${base}...${head}`], cwd));
 }
-/** Commit subjects on `head` since `base` (2-dot: commits added by the task),
- *  oldest-first, for distilling a runbook's ordered steps (roadmap #5). */
-export function rangeSubjects(base, cwd, head = "HEAD", max = 50) {
-    const out = gitSafe(["log", "--reverse", `-n${max}`, "--format=%s", `${base}..${head}`], cwd);
-    return out ? out.split("\n").filter(Boolean) : [];
+/** Commits on `head` since `base` (2-dot: commits added by the task), oldest-first, each
+ *  with its subject and the files it changed, for distilling a runbook's ordered steps
+ *  (roadmap #5); `runbookDraft` uses the files to tell Hunch's own captures from the work. */
+export function rangeCommits(base, cwd, head = "HEAD", max = 50) {
+    const out = gitSafe(["-c", "core.quotePath=false", "log", "--reverse", `-n${max}`, "--format=%x1e%s", "--name-only", `${base}..${head}`], cwd);
+    if (!out)
+        return [];
+    return out.split("\x1e").filter(Boolean).map((block) => {
+        const [subject = "", ...files] = block.split("\n");
+        return { subject: subject.trim(), files: files.map((f) => f.trim()).filter(Boolean) };
+    });
 }
 /** Complete gating diff of a PR vs `base` (3-dot: the CI Constraint Guard's surface). */
 export function rangeGateDiff(base, cwd, head = "HEAD") {

package/dist/extractors/indexer.js

@@ -13,7 +13,7 @@ import { dirname, join, posix } from "node:path";
 import { parseSource, attributeCalls, attributeRelations, MAX_BODY_TEXT_CHARS } from "./parse.js";
 import { isParserLoadError } from "./nativeTreeSitter.js";
 import { extractHelmDirectives } from "./helm.js";
-import { extractK8sManifest, namespacesCompatible } from "./k8sManifest.js";
+import { extractK8sManifest, extractKustomization, isKustomizationFile, kustomizeNamespaces, namespacesCompatible } from "./k8sManifest.js";
 import { symbolId, componentId, edgeId, sha1 } from "../core/ids.js";
 import { externalImportNodeId, externalPackage } from "../core/externalImports.js";
 import { resolveRelativeImport } from "../core/relativeImports.js";
@@ -143,9 +143,25 @@ export function scanRepo(store, root, opts = {}) {
     }
     const gitMeta = useGit ? fileGitMetrics(root, rels, opts.churn === false ? 0 : 90) : null;
     let skipped = 0;
+    // Kustomize namespace transformers must be known before any manifest is
+    // extracted, so kustomization files are read up front (their reads are
+    // reused by the main loop below, not repeated).
+    const preRead = new Map();
+    const kustomizations = new Map();
     for (const file of files) {
-        const rel = file.path;
+        if (!isKustomizationFile(file.path))
+            continue;
         const read = file.read();
+        preRead.set(file.path, read);
+        if (!read.absent && read.source !== null) {
+            const dir = posix.dirname(file.path);
+            kustomizations.set(dir === "." ? "" : dir, extractKustomization(read.source));
+        }
+    }
+    const kustomizeNamespaceFor = kustomizeNamespaces(kustomizations, new Set(rels));
+    for (const file of files) {
+        const rel = file.path;
+        const read = preRead.get(rel) ?? file.read();
         if (read.absent) {
             sourceFingerprint.push({ path: rel, mode: read.mode, content: "absent" });
             continue;
@@ -227,20 +243,41 @@ export function scanRepo(store, root, opts = {}) {
         // otherwise be indistinguishable by offset alone, and the wrong (Helm)
         // symbol id could get recorded instead of the K8s one.
         const k8sSymbolObjects = new Set();
+        // Identity name a K8s symbol's id is derived from when its kind/name is
+        // NOT unique in this file (issue #382). Absent for the common unique case,
+        // so that id is exactly what it always was; a same-kind/name pair in
+        // different namespaces gets kind/name@namespace for EVERY member, never a
+        // document-order ordinal, so reordering documents can't rename them. The
+        // file path is already in every symbol id, so the same resource repeated
+        // across overlay dirs is distinct by path without any extra disambiguator.
+        const k8sIdNames = new Map();
         if (languageFor(rel)?.id === "yaml") {
-            k8sDocs = extractK8sManifest(src);
-            const k8sSymbols = k8sDocs
-                .filter((d) => d.resource !== null)
+            k8sDocs = kustomizeNamespaceFor.has(rel)
+                ? extractK8sManifest(src, { namespace: kustomizeNamespaceFor.get(rel) })
+                : extractK8sManifest(src);
+            const resourceDocs = k8sDocs
+                .filter((d) => d.resource !== null);
+            const nameCounts = new Map();
+            for (const d of resourceDocs) {
+                const name = `${d.resource.kind}/${displayNameText(d.resource.name)}`;
+                nameCounts.set(name, (nameCounts.get(name) ?? 0) + 1);
+            }
+            const k8sSymbols = resourceDocs
                 // k8sManifest.ts's own offsets are named *Char; mapped here into the
                 // shared startByte/endByte fields, same as the Helm merge above.
-                .map((d) => ({
-                name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
-                kind: "variable",
-                startByte: d.resource.startChar,
-                endByte: d.resource.endChar,
-                loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
-                bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
-            }));
+                .map((d) => {
+                const sym = {
+                    name: `${d.resource.kind}/${displayNameText(d.resource.name)}`,
+                    kind: "variable",
+                    startByte: d.resource.startChar,
+                    endByte: d.resource.endChar,
+                    loc: src.slice(d.resource.startChar, d.resource.endChar).split("\n").length,
+                    bodyText: src.slice(d.resource.startChar, d.resource.endChar).slice(0, MAX_BODY_TEXT_CHARS),
+                };
+                if ((nameCounts.get(sym.name) ?? 0) > 1)
+                    k8sIdNames.set(sym, `${sym.name}@${d.resource.namespace ?? ""}`);
+                return sym;
+            });
             for (const s of k8sSymbols)
                 k8sSymbolObjects.add(s);
             parsed.symbols = [...parsed.symbols, ...k8sSymbols].sort((a, b) => a.startByte - b.startByte);
@@ -253,10 +290,12 @@ export function scanRepo(store, root, opts = {}) {
         const idCounts = new Map(); // disambiguate same (file,name,kind)
         const k8sSymbolIdByStartByte = new Map();
         for (const [index, ps] of parsed.symbols.entries()) {
-            const base = symbolId(rel, ps.name, ps.kind);
+            const base = symbolId(rel, k8sIdNames.get(ps) ?? ps.name, ps.kind);
             const n = idCounts.get(base) ?? 0;
             idCounts.set(base, n + 1);
             // parse() returns symbols sorted by start byte, so the ordinal is stable
+            // (for K8s resources it is only reached by two documents with the SAME
+            // kind, namespace and name in one file -- indistinguishable by identity)
             const id = n === 0 ? base : `${base}_${n}`;
             idsInFile.push(id);
             symbolIndexId.set(index, id);

package/dist/extractors/k8sManifest.d.ts

@@ -68,5 +68,35 @@ export declare function namespacesCompatible(a: string | null, b: string | null)
  *  paths below aren't hand-duplicated per kind. */
 export declare const POD_SPEC_PATH_BY_KIND: Record<string, string>;
 export declare const LABELS_PATH_BY_KIND: Record<string, string>;
-export declare function extractK8sManifest(source: string): K8sManifestDocument[];
+/** `namespace` is a Kustomize transformer namespace for this file (from
+ *  kustomizeNamespaces): undefined = no transformer, null = UNKNOWN (two
+ *  kustomizations render this file into different namespaces). */
+export declare function extractK8sManifest(source: string, opts?: {
+    namespace?: string | null;
+}): K8sManifestDocument[];
+export interface KustomizationInfo {
+    /** Top-level `namespace:` when it is a valid literal namespace, else null. */
+    namespace: string | null;
+    /** `resources:` entries exactly as written (paths relative to the kustomization's directory). */
+    resources: string[];
+}
+export declare function isKustomizationFile(path: string): boolean;
+/** Reads only the two top-level fields the namespace transformer needs:
+ *  `namespace:` and the `resources:` list (block `- item` lines or a one-line
+ *  flow `[a, b]`). One linear pass; everything else in the file is ignored. */
+export declare function extractKustomization(source: string): KustomizationInfo;
+/** The Kustomize namespace each manifest file is rendered into, keyed by repo
+ *  path. `kustomizations` is keyed by the kustomization's DIRECTORY ("" for
+ *  the repo root); `files` is the indexed file set.
+ *
+ *  A `resources:` entry naming a file applies the namespace to that file; an
+ *  entry naming a directory that holds its own kustomization is a base, and
+ *  the referring (outer) kustomization's namespace wins over the base's, as
+ *  Kustomize applies the overlay transformer to the base's output. Only
+ *  kustomizations no other kustomization references are rendered as roots.
+ *  A file rendered into two different namespaces (one base shared by dev and
+ *  prod overlays, the common layout) maps to null = UNKNOWN; a file rendered
+ *  only without any transformer is absent. Not modelled: remote resources,
+ *  `components:`, the deprecated `bases:` field, and globs. */
+export declare function kustomizeNamespaces(kustomizations: ReadonlyMap<string, KustomizationInfo>, files: ReadonlySet<string>): Map<string, string | null>;
 export {};

package/dist/extractors/k8sManifest.js

@@ -1,4 +1,5 @@
-import { sourceLines } from "../core/eol.js";
+import { posix } from "node:path";
+import { eolLengthAt, sourceLines } from "../core/eol.js";
 // ReplicaSet is included alongside the pod-spec-embedding/networking kinds
 // specifically because it's the dominant real-world bearer of
 // ownerReferences (Deployment -> ReplicaSet -> Pod is the common chain) --
@@ -606,7 +607,16 @@ function extractLiteralLabelMap(prefix, entries, unresolvedContainers, valueless
     }
     return pairs.length > 0 ? Object.fromEntries(pairs) : null;
 }
-function buildDocument(text, docStartChar, entries, unresolvedContainers, valuelessKeyParents) {
+/** Cluster-scoped kinds Kustomize's namespace transformer leaves alone. None
+ *  of them is in ALLOWED_KINDS today, so this is a guard for the override in
+ *  buildDocument rather than a live branch: an allowlist widening must not
+ *  start stamping a namespace onto a resource that cannot have one. */
+const CLUSTER_SCOPED_KINDS = new Set([
+    "Namespace", "Node", "PersistentVolume", "StorageClass", "CustomResourceDefinition",
+    "ClusterRole", "ClusterRoleBinding", "PriorityClass", "IngressClass", "RuntimeClass",
+    "MutatingWebhookConfiguration", "ValidatingWebhookConfiguration", "APIService",
+]);
+function buildDocument(text, docStartChar, entries, unresolvedContainers, valuelessKeyParents, namespaceOverride) {
     const kindEntry = findEntry(entries, "kind");
     const kind = kindEntry?.value.form === "literal" ? kindEntry.value.value : null;
     if (!kind || !ALLOWED_KINDS.has(kind))
@@ -615,8 +625,13 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers, valuel
     // scanner's quote-stripping, comment-stripping and CRLF tolerance for free.
     // Read OUTSIDE the `resource` branch below: a document with no
     // metadata.name still emits references, and those references carry this
-    // document's namespace.
-    const namespace = namespaceAt(entries, "metadata.namespace");
+    // document's namespace. A Kustomize namespace transformer (see
+    // kustomizeNamespaces) REPLACES metadata.namespace on every namespaced
+    // resource, explicit or not, so it wins here; an explicit backendRefs
+    // namespace sibling is not rewritten and keeps its own.
+    const namespace = namespaceOverride !== undefined && !CLUSTER_SCOPED_KINDS.has(kind)
+        ? namespaceOverride
+        : namespaceAt(entries, "metadata.namespace");
     const nameEntry = findEntry(entries, "metadata.name");
     const resource = nameEntry
         ? { kind, name: nameEntry.value, namespace, startChar: docStartChar, endChar: docStartChar + text.length }
@@ -643,12 +658,18 @@ function buildDocument(text, docStartChar, entries, unresolvedContainers, valuel
 // and it still isn't here: the dashes must be followed by whitespace or end
 // of line.
 const DOC_SEPARATOR = /^(?:---(?:[ \t]+.*)?|\.\.\.)[ \t]*$/;
-export function extractK8sManifest(source) {
+/** `namespace` is a Kustomize transformer namespace for this file (from
+ *  kustomizeNamespaces): undefined = no transformer, null = UNKNOWN (two
+ *  kustomizations render this file into different namespaces). */
+export function extractK8sManifest(source, opts = {}) {
     const docs = [];
     const boundaries = [];
     for (const line of sourceLines(source)) {
-        if (DOC_SEPARATOR.test(line.content))
-            boundaries.push(line.start, line.end);
+        if (!DOC_SEPARATOR.test(line.content))
+            continue;
+        // The next document starts AFTER the separator's line terminator, so the
+        // same document text has the same span wherever it sits (#451).
+        boundaries.push(line.start, line.end + eolLengthAt(source, line.end));
     }
     const starts = [0, ...boundaries.filter((_, i) => i % 2 === 1)];
     const ends = [...boundaries.filter((_, i) => i % 2 === 0), source.length];
@@ -657,8 +678,112 @@ export function extractK8sManifest(source) {
         const end = ends[i];
         const text = source.slice(start, end);
         const { entries, unresolvedContainers, valuelessKeyParents } = scanFieldPaths(text, start);
-        docs.push(buildDocument(text, start, entries, unresolvedContainers, valuelessKeyParents));
+        docs.push(buildDocument(text, start, entries, unresolvedContainers, valuelessKeyParents, opts.namespace));
     }
     return docs;
 }
+const KUSTOMIZATION_FILE = /(?:^|\/)(?:kustomization\.ya?ml|Kustomization)$/;
+export function isKustomizationFile(path) {
+    return KUSTOMIZATION_FILE.test(path);
+}
+/** Reads only the two top-level fields the namespace transformer needs:
+ *  `namespace:` and the `resources:` list (block `- item` lines or a one-line
+ *  flow `[a, b]`). One linear pass; everything else in the file is ignored. */
+export function extractKustomization(source) {
+    let namespace = null;
+    const resources = [];
+    let inResources = false;
+    for (const { content } of sourceLines(source)) {
+        const line = stripTrailingComment(content).trimEnd();
+        if (line.trim() === "")
+            continue;
+        const item = /^\s*-\s+(.+)$/.exec(line);
+        if (inResources && item) {
+            resources.push(stripQuotes(item[1].trim()));
+            continue;
+        }
+        if (/^\s/.test(line))
+            continue; // nested content of some other top-level key
+        inResources = false;
+        const top = /^([A-Za-z]+):[ \t]*(.*)$/.exec(line);
+        if (!top)
+            continue;
+        const value = top[2].trim();
+        if (top[1] === "namespace") {
+            const ns = stripQuotes(value);
+            namespace = DNS_LABEL.test(ns) && ns !== "null" ? ns : null;
+        }
+        else if (top[1] === "resources") {
+            if (value === "")
+                inResources = true;
+            else if (value.startsWith("[") && value.endsWith("]")) {
+                for (const part of value.slice(1, -1).split(","))
+                    if (part.trim())
+                        resources.push(stripQuotes(part.trim()));
+            }
+        }
+    }
+    return { namespace, resources };
+}
+/** The Kustomize namespace each manifest file is rendered into, keyed by repo
+ *  path. `kustomizations` is keyed by the kustomization's DIRECTORY ("" for
+ *  the repo root); `files` is the indexed file set.
+ *
+ *  A `resources:` entry naming a file applies the namespace to that file; an
+ *  entry naming a directory that holds its own kustomization is a base, and
+ *  the referring (outer) kustomization's namespace wins over the base's, as
+ *  Kustomize applies the overlay transformer to the base's output. Only
+ *  kustomizations no other kustomization references are rendered as roots.
+ *  A file rendered into two different namespaces (one base shared by dev and
+ *  prod overlays, the common layout) maps to null = UNKNOWN; a file rendered
+ *  only without any transformer is absent. Not modelled: remote resources,
+ *  `components:`, the deprecated `bases:` field, and globs. */
+export function kustomizeNamespaces(kustomizations, files) {
+    const KEEP = "\0keep";
+    const childFiles = new Map();
+    const childDirs = new Map();
+    const referenced = new Set();
+    for (const [dir, k] of kustomizations) {
+        for (const entry of k.resources) {
+            let p = posix.normalize(posix.join(dir, entry)).replace(/\/+$/, "");
+            if (p === ".")
+                p = "";
+            if (p === ".." || p.startsWith("../"))
+                continue;
+            if (files.has(p))
+                (childFiles.get(dir) ?? childFiles.set(dir, []).get(dir)).push(p);
+            else if (p !== dir && kustomizations.has(p)) {
+                (childDirs.get(dir) ?? childDirs.set(dir, []).get(dir)).push(p);
+                referenced.add(p);
+            }
+        }
+    }
+    const seen = new Map();
+    const visited = new Set();
+    const render = (dir, outer) => {
+        const ns = outer ?? kustomizations.get(dir).namespace;
+        const key = `${dir}\0${ns ?? KEEP}`;
+        if (visited.has(key))
+            return; // memoised per (dir, namespace); also breaks cycles
+        visited.add(key);
+        for (const f of childFiles.get(dir) ?? [])
+            (seen.get(f) ?? seen.set(f, new Set()).get(f)).add(ns ?? KEEP);
+        for (const child of childDirs.get(dir) ?? [])
+            render(child, ns);
+    };
+    for (const dir of [...kustomizations.keys()].sort())
+        if (!referenced.has(dir))
+            render(dir, null);
+    const out = new Map();
+    for (const [file, set] of seen) {
+        if (set.size > 1)
+            out.set(file, null);
+        else {
+            const only = [...set][0];
+            if (only !== KEEP)
+                out.set(file, only);
+        }
+    }
+    return out;
+}
 //# sourceMappingURL=k8sManifest.js.map

package/dist/integrations/claudemd.d.ts

@@ -1,5 +1,7 @@
 import type { HunchStore } from "../store/hunchStore.js";
 import { groundingTemplate } from "../core/groundingLag.js";
+export declare const HUNCH_START = "<!-- HUNCH:START \u2014 auto-generated, do not edit by hand -->";
+export declare const HUNCH_END = "<!-- HUNCH:END -->";
 /** Version of the block's PROSE. Bump it whenever renderHunchSection's wording
  *  changes. A block without the stamp is template 1. */
 export declare const GROUNDING_TEMPLATE = 2;

package/dist/integrations/claudemd.js

@@ -9,8 +9,10 @@ import { basename, join, dirname } from "node:path";
 import { wikiSummary } from "../wiki/wiki.js";
 import { PolicyRepository } from "../constitution/repository.js";
 import { renderCountsMatch, parseGroundingCounts, groundingTemplate } from "../core/groundingLag.js";
-const START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
-const END = "<!-- HUNCH:END -->";
+export const HUNCH_START = "<!-- HUNCH:START — auto-generated, do not edit by hand -->";
+export const HUNCH_END = "<!-- HUNCH:END -->";
+const START = HUNCH_START;
+const END = HUNCH_END;
 /** Version of the block's PROSE. Bump it whenever renderHunchSection's wording
  *  changes. A block without the stamp is template 1. */
 export const GROUNDING_TEMPLATE = 2;

package/dist/integrations/gitignore.d.ts

@@ -39,3 +39,10 @@ export interface ManagedGitignoreUpgrade {
 export declare function upgradeManagedGitignore(root: string): ManagedGitignoreUpgrade;
 /** Output lines describing what an upgrade changed; empty when nothing did. */
 export declare function describeGitignoreUpgrade(upgrade: ManagedGitignoreUpgrade): string[];
+/** `.gitignore` text with both managed Hunch blocks removed (markers inclusive),
+ *  every other byte kept, for `hunch uninstall --purge` (#449). `damaged` when a
+ *  marker line has no matching end line: the block is never guessed at. */
+export declare function stripManagedGitignore(text: string): {
+    next: string;
+    damaged: boolean;
+};

package/dist/integrations/gitignore.js

@@ -231,4 +231,22 @@ export function describeGitignoreUpgrade(upgrade) {
     }
     return out;
 }
+/** `.gitignore` text with both managed Hunch blocks removed (markers inclusive),
+ *  every other byte kept, for `hunch uninstall --purge` (#449). `damaged` when a
+ *  marker line has no matching end line: the block is never guessed at. */
+export function stripManagedGitignore(text) {
+    let lines = text.split("\n");
+    let damaged = false;
+    for (const [mark, end] of [[MARK, END], [MEM_MARK, MEM_END]]) {
+        if (!lines.some((l) => cleanLine(l) === mark))
+            continue;
+        const span = findBlock(lines, mark, end);
+        if (!span) {
+            damaged = true;
+            continue;
+        }
+        lines = [...lines.slice(0, span.start), ...lines.slice(span.end + 1)];
+    }
+    return { next: lines.join("\n"), damaged };
+}
 //# sourceMappingURL=gitignore.js.map

package/dist/integrations/hooks.d.ts

@@ -144,6 +144,21 @@ export declare function hookStatus(root: string): {
     postMerge: boolean;
     postCheckout: boolean;
 };
+/** One git hook file `hunch uninstall` would change. `next === null` deletes the
+ *  file (only a shebang was left); a `reason` means nothing is edited and the
+ *  user removes the block by hand. */
+export interface HookRemoval {
+    path: string;
+    hookName: string;
+    next?: string | null;
+    reason?: string;
+}
+/** Plan the removal of every Hunch-managed block from the hooks git runs (#449).
+ *  Read-only. Only a hook file Hunch itself writes (manager "none", or an
+ *  exec/exit file whose block it appended) is edited, and only a block with both
+ *  markers; a hook manager's file, a tracked hooks dir, or an unclosed block is
+ *  reported instead — the same lines Hunch refuses to write on install. */
+export declare function planHookRemoval(root: string): HookRemoval[];
 /** Doctor lines for where each installed/stale hook points (issue #315): hooks
  *  sharing one invocation share one line, and a line whose invocation is not the
  *  Hunch currently running says so. Informational — a hook may legitimately

package/dist/integrations/hooks.js

@@ -20,7 +20,7 @@ import { homedir } from "node:os";
 import { hooksDir, gitCommonDir, isLinkedWorktree, mainWorktreeRoot } from "../extractors/git.js";
 import { initiatorChildEnv } from "../synthesis/initiator.js";
 import { HUNCH_NPX_PACKAGE_SPEC, HUNCH_PACKAGE_NAME } from "../core/version.js";
-import { normalizeEol } from "../core/eol.js";
+import { eolLengthAt, normalizeEol } from "../core/eol.js";
 const MARK = "# >>> hunch post-commit >>>";
 const ENDMARK = "# <<< hunch post-commit <<<";
 const GIT_CONTEXT = { checkoutType: "$3", portable: false };
@@ -942,6 +942,54 @@ export function hookStatus(root) {
         postCheckout: r.postCheckout.state === "installed",
     };
 }
+/** Plan the removal of every Hunch-managed block from the hooks git runs (#449).
+ *  Read-only. Only a hook file Hunch itself writes (manager "none", or an
+ *  exec/exit file whose block it appended) is edited, and only a block with both
+ *  markers; a hook manager's file, a tracked hooks dir, or an unclosed block is
+ *  reported instead — the same lines Hunch refuses to write on install. */
+export function planHookRemoval(root) {
+    const ends = {
+        [MARK]: ENDMARK, [PRE_MARK]: PRE_END, [GROUNDING_MERGE_MARK]: GROUNDING_MERGE_END,
+        [REPAIR_MERGE_MARK]: REPAIR_MERGE_END, [CHECKOUT_MARK]: CHECKOUT_END,
+    };
+    const byHook = new Map();
+    for (const [hookName, mark] of managedBlocks())
+        byHook.set(hookName, [...(byHook.get(hookName) ?? []), mark]);
+    const out = [];
+    for (const [hookName, marks] of byHook) {
+        const t = resolveHookTarget(root, hookName, marks[0]);
+        if (t.manager !== "none" && t.manager !== "exec-exit") {
+            const owner = readText(t.ownerFile);
+            if (owner !== null && marks.some((m) => owner.includes(m))) {
+                out.push({ path: t.ownerFile, hookName, reason: `${t.manager} owns this hook; remove the Hunch block from it by hand` });
+            }
+            continue;
+        }
+        const cur = readText(t.hookPath);
+        if (cur === null || !marks.some((m) => cur.includes(m)))
+            continue;
+        let next = cur;
+        let damaged = false;
+        for (const mark of marks) {
+            if (!next.includes(mark))
+                continue;
+            const m = new RegExp(`${escapeRe(mark)}[\\s\\S]*?${escapeRe(ends[mark])}`).exec(next);
+            if (!m) {
+                damaged = true;
+                continue;
+            }
+            const end = m.index + m[0].length;
+            next = next.slice(0, m.index) + next.slice(end + eolLengthAt(next, end));
+        }
+        if (damaged) {
+            out.push({ path: t.hookPath, hookName, reason: "a Hunch block here has no closing marker; remove it by hand" });
+            continue;
+        }
+        const body = normalizeEol(next).split("\n").filter((l, i) => !(i === 0 && l.startsWith("#!")));
+        out.push({ path: t.hookPath, hookName, next: body.every((l) => l.trim() === "") ? null : next });
+    }
+    return out;
+}
 /** Doctor lines for where each installed/stale hook points (issue #315): hooks
  *  sharing one invocation share one line, and a line whose invocation is not the
  *  Hunch currently running says so. Informational — a hook may legitimately

package/dist/integrations/mergeDriver.d.ts

@@ -1,3 +1,5 @@
+export declare const ATTR_LINES: readonly string[];
+export declare function targetRepositoryEnv(): NodeJS.ProcessEnv;
 export declare function installMergeDriver(root: string, invShell: string): {
     action: string;
 };

package/dist/integrations/mergeDriver.js

@@ -20,12 +20,12 @@ import { GROUNDING_DOC_PATHS } from "./providers.js";
 //
 // The five generated grounding docs get the OTHER driver — narrower in scope
 // (it only ever touches a hard conflict confined to the counts sentence).
-const ATTR_LINES = [
+export const ATTR_LINES = [
     ".hunch/**/*.json merge=hunch",
     ".hunch/manifest.json merge=text",
     ...GROUNDING_DOC_PATHS.map((f) => `${f} merge=hunch-grounding`),
 ];
-function targetRepositoryEnv() {
+export function targetRepositoryEnv() {
     const env = { ...process.env };
     for (const key of [
         "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_CONFIG", "GIT_CONFIG_PARAMETERS", "GIT_CONFIG_COUNT",

package/dist/integrations/providers.d.ts

@@ -1,5 +1,10 @@
 import type { HunchStore } from "../store/hunchStore.js";
 import type { Invocation } from "./scaffold.js";
+/** Read a JSON/JSONC object. Returns {} only for an ABSENT or empty file. A
+ *  non-empty file we cannot parse THROWS — overwriting it would silently wipe the
+ *  user's other MCP servers. */
+export declare function readJsonObj(file: string): Record<string, unknown>;
+export declare function isHunchProviderHook(entry: unknown): boolean;
 /** Cursor: .cursor/mcp.json — same `mcpServers` shape as Claude Desktop/Code. */
 export declare function writeCursorMcp(root: string, inv: Invocation): string;
 /** VS Code (Copilot agent mode): .vscode/mcp.json — root key is `servers`, and
@@ -20,6 +25,8 @@ export declare function writeAntigravityMcp(inv: Invocation, home?: string): str
  * committed with the repository, so every clone gets the same private/local
  * Hunch server without touching a user's home directory. */
 export declare function writeAntigravityWorkspaceMcp(root: string, inv: Invocation): string;
+export declare const TOML_START = "# >>> hunch mcp (managed) >>>";
+export declare const TOML_END = "# <<< hunch mcp <<<";
 /** Codex CLI: .codex/config.toml — `[mcp_servers.hunch]` stdio entry. We own only
  *  a marker-delimited block; any other TOML the user has is preserved. Paths use
  *  TOML single-quote LITERAL strings so Windows backslashes need no escaping. */