knodin 0.5.1 → 0.7.3

package/dist/src/init.js

@@ -1,11 +1,12 @@
 import child_process from "node:child_process";
+import crypto from "node:crypto";
 import fs from "node:fs";
 import path from "node:path";
 import { configureProjectAgents, } from "./agent-integration.js";
 import { isIndexableSourcePath } from "./engine/source-policy.js";
+import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
-const LEGACY_MANAGED_MARKER = "RECKON-GRAPH MANAGED HOOK";
 const HOOK_NAMES = ["post-commit", "post-checkout", "post-merge", "post-rewrite"];
 const HOOK_LOG_MAX_BYTES = 1_048_576;
 const HOOK_FAILURE_FILE = "last-refresh-failure";
@@ -40,6 +41,203 @@ function runGit(repo, args, encoding = "utf-8") {
         stdio: ["ignore", "pipe", "ignore"],
     });
 }
+const MUTATION_AUDIT_MAX_ENTRIES = 2_048;
+const MUTATION_AUDIT_MAX_FILE_BYTES = 8 * 1_024 * 1_024;
+function boundedDirectoryEntries(directory) {
+    try {
+        const entries = fs.readdirSync(directory, { withFileTypes: true });
+        if (entries.length > MUTATION_AUDIT_MAX_ENTRIES)
+            throw new Error(`${directory}: configure mutation audit exceeds ${MUTATION_AUDIT_MAX_ENTRIES} managed entries`);
+        return entries;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return [];
+        throw error;
+    }
+}
+function configureMutationAuditTargets(repo) {
+    const commonRaw = runGit(repo, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-common-dir",
+    ]).trim();
+    const common = path.isAbsolute(commonRaw) ? commonRaw : path.resolve(repo, commonRaw);
+    const excludeRaw = runGit(repo, [
+        "rev-parse",
+        "--path-format=absolute",
+        "--git-path",
+        "info/exclude",
+    ]).trim();
+    const exclude = path.isAbsolute(excludeRaw) ? excludeRaw : path.resolve(repo, excludeRaw);
+    const effectiveHooks = effectiveHooksDirectory(repo);
+    const targets = new Map();
+    const add = (target) => {
+        const key = path.resolve(target.absolute);
+        if (!targets.has(key))
+            targets.set(key, { ...target, absolute: key });
+    };
+    for (const relative of [
+        "AGENTS.md",
+        "GEMINI.md",
+        ".mcp.json",
+        ".codex",
+        ".codex/config.toml",
+        ".gemini",
+        ".gemini/settings.json",
+        ".agents",
+        ".agents/mcp_config.json",
+        ".gitignore",
+        ".claude",
+        ".claude/hooks",
+        ".claude/hooks/nudge.sh",
+        ".claude/settings.example.json",
+        ".knodin",
+        ".knodin/integration.json",
+        ".knodin/indexer.log",
+        ".knodin/indexer.log.1",
+        "lefthook-local.yml",
+        "lefthook-local.yaml",
+        ".lefthook-local.yml",
+        ".lefthook-local.yaml",
+        ".config/lefthook-local.yml",
+        ".config/lefthook-local.yaml",
+    ])
+        add({ absolute: path.join(repo, relative), label: relative });
+    for (const relative of [
+        ".knodin/hooks",
+        ".knodin/hooks/background-index.sh",
+        ".knodin/hooks/manager-dispatch.sh",
+        ".knodin/hooks/events",
+        ".knodin/hooks/last-refresh-event",
+        ".knodin/hooks/last-refresh-failure",
+        ".knodin/hooks/refresh.lock",
+        ".knodin/hooks/refresh.lock/pid",
+    ])
+        add({ absolute: path.join(repo, relative), label: relative });
+    for (const entry of boundedDirectoryEntries(path.join(repo, ".knodin", "hooks", "events")))
+        add({
+            absolute: path.join(repo, ".knodin", "hooks", "events", entry.name),
+            label: `.knodin/hooks/events/${entry.name}`,
+        });
+    add({ absolute: path.join(common, "config"), label: ".git/config" });
+    add({ absolute: exclude, label: ".git/info/exclude" });
+    add({ absolute: path.join(common, "knodin"), label: ".git/knodin" });
+    add({
+        absolute: path.join(common, "knodin", "worktrees.json"),
+        label: ".git/knodin/worktrees.json",
+    });
+    const defaultHooks = path.join(common, "hooks");
+    const managedHooks = path.join(common, "knodin-hooks");
+    add({ absolute: defaultHooks, label: ".git/hooks" });
+    add({ absolute: managedHooks, label: ".git/knodin-hooks" });
+    const effectiveLabel = path.resolve(effectiveHooks) === path.resolve(defaultHooks)
+        ? ".git/hooks"
+        : path.resolve(effectiveHooks) === path.resolve(managedHooks)
+            ? ".git/knodin-hooks"
+            : "effective-git-hooks";
+    add({ absolute: effectiveHooks, label: effectiveLabel });
+    for (const hookRoot of [
+        { absolute: defaultHooks, label: ".git/hooks" },
+        { absolute: managedHooks, label: ".git/knodin-hooks" },
+        { absolute: effectiveHooks, label: effectiveLabel },
+    ]) {
+        for (const entry of boundedDirectoryEntries(hookRoot.absolute))
+            add({
+                absolute: path.join(hookRoot.absolute, entry.name),
+                label: `${hookRoot.label}/${entry.name}`,
+            });
+    }
+    for (const hookName of HOOK_NAMES) {
+        add({ absolute: path.join(effectiveHooks, hookName), label: `${effectiveLabel}/${hookName}` });
+        add({
+            absolute: path.join(effectiveHooks, `${hookName}.knodin-original`),
+            label: `${effectiveLabel}/${hookName}.knodin-original`,
+        });
+    }
+    for (const hookRoot of [
+        { absolute: defaultHooks, label: ".git/hooks" },
+        { absolute: managedHooks, label: ".git/knodin-hooks" },
+    ]) {
+        for (const hookName of HOOK_NAMES) {
+            add({
+                absolute: path.join(hookRoot.absolute, hookName),
+                label: `${hookRoot.label}/${hookName}`,
+            });
+            add({
+                absolute: path.join(hookRoot.absolute, `${hookName}.knodin-original`),
+                label: `${hookRoot.label}/${hookName}.knodin-original`,
+            });
+        }
+    }
+    const configured = configuredHooksPath(repo);
+    const relativeConfigured = configured ? repoRelativeHooksPath(repo, configured) : null;
+    if (relativeConfigured && hasTrackedHooks(repo, relativeConfigured)) {
+        const configuredRoot = path.join(repo, relativeConfigured);
+        for (const entry of boundedDirectoryEntries(configuredRoot)) {
+            if (!entry.isFile() || HOOK_NAMES.includes(entry.name))
+                continue;
+            const source = path.join(configuredRoot, entry.name);
+            if ((fs.statSync(source).mode & 0o111) === 0)
+                continue;
+            add({
+                absolute: path.join(managedHooks, entry.name),
+                label: `.git/knodin-hooks/${entry.name}`,
+            });
+        }
+    }
+    if (targets.size > MUTATION_AUDIT_MAX_ENTRIES)
+        throw new Error(`configure mutation audit exceeds ${MUTATION_AUDIT_MAX_ENTRIES} managed paths`);
+    return [...targets.values()];
+}
+function fileSignature(filePath, allowOversized = false) {
+    try {
+        const stat = fs.lstatSync(filePath);
+        if (stat.isDirectory())
+            return `directory:${stat.mode & 0o777}`;
+        if (stat.isSymbolicLink()) {
+            const link = fs.readlinkSync(filePath);
+            const resolved = fs.realpathSync(filePath);
+            return `symlink:${stat.mode & 0o777}:${link}:${fileSignature(resolved, allowOversized)}`;
+        }
+        if (!stat.isFile())
+            throw new Error(`${filePath}: unsupported filesystem entry`);
+        if (stat.size > MUTATION_AUDIT_MAX_FILE_BYTES && !allowOversized)
+            throw new Error(`${filePath}: configure mutation audit refuses files larger than ${MUTATION_AUDIT_MAX_FILE_BYTES} bytes`);
+        if (stat.size > MUTATION_AUDIT_MAX_FILE_BYTES)
+            return `oversized-file:${stat.mode & 0o777}:${stat.size}`;
+        const digest = crypto.createHash("sha256").update(fs.readFileSync(filePath)).digest("hex");
+        return `file:${stat.mode & 0o777}:${stat.size}:${digest}`;
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+}
+function mutationSnapshot(targets, allowOversized = false) {
+    const snapshot = new Map();
+    for (const target of targets) {
+        const rootSignature = fileSignature(target.absolute, allowOversized);
+        if (rootSignature !== null)
+            snapshot.set(target.label, rootSignature);
+    }
+    return snapshot;
+}
+function filesystemChanges(before, after) {
+    return [...new Set([...before.keys(), ...after.keys()])].sort().flatMap((changedPath) => {
+        const prior = before.get(changedPath);
+        const current = after.get(changedPath);
+        if (prior === current)
+            return [];
+        return [
+            {
+                path: changedPath,
+                action: prior === undefined ? "created" : current === undefined ? "removed" : "modified",
+            },
+        ];
+    });
+}
 function shellQuote(value) {
     return `'${value.replaceAll("'", `'\\''`)}'`;
 }
@@ -78,14 +276,14 @@ export async function refreshFromGitEvent(repo, event, index) {
             changed = diffPaths(resolvedRepo, event.before, event.after);
         }
         else {
-            const hooksRoot = path.join(resolvedRepo, ".reckon", "hooks");
+            const hooksRoot = path.join(resolvedRepo, ".knodin", "hooks");
             const inputPath = path.resolve(event.inputPath);
             const relativeInput = path.relative(hooksRoot, inputPath);
             if (relativeInput === "" ||
                 relativeInput === ".." ||
                 relativeInput.startsWith(`..${path.sep}`) ||
                 path.isAbsolute(relativeInput)) {
-                throw new Error("knodin hook refresh: rewrite input must be inside .reckon/hooks");
+                throw new Error("knodin hook refresh: rewrite input must be inside .knodin/hooks");
             }
             const [realHooksRoot, realInputPath, inputStat] = await Promise.all([
                 fs.promises.realpath(hooksRoot),
@@ -99,7 +297,7 @@ export async function refreshFromGitEvent(repo, event, index) {
                 realRelativeInput === ".." ||
                 realRelativeInput.startsWith(`..${path.sep}`) ||
                 path.isAbsolute(realRelativeInput)) {
-                throw new Error("knodin hook refresh: rewrite input must be a regular file inside .reckon/hooks");
+                throw new Error("knodin hook refresh: rewrite input must be a regular file inside .knodin/hooks");
             }
             rewriteInputToRemove = inputPath;
             const pairs = (await fs.promises.readFile(inputPath, "utf-8"))
@@ -130,11 +328,11 @@ set -u
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$REPO_ROOT" ] || exit 0
 cd "$REPO_ROOT" || exit 0
-mkdir -p "$REPO_ROOT/.reckon"
-LOCK_DIR="$REPO_ROOT/.reckon/hooks/refresh.lock"
-EVENT_DIR="$REPO_ROOT/.reckon/hooks/events"
-LAST_EVENT_PATH="$REPO_ROOT/.reckon/hooks/last-refresh-event"
-FAILURE_PATH="$REPO_ROOT/.reckon/hooks/${HOOK_FAILURE_FILE}"
+mkdir -p "$REPO_ROOT/.knodin"
+LOCK_DIR="$REPO_ROOT/.knodin/hooks/refresh.lock"
+EVENT_DIR="$REPO_ROOT/.knodin/hooks/events"
+LAST_EVENT_PATH="$REPO_ROOT/.knodin/hooks/last-refresh-event"
+FAILURE_PATH="$REPO_ROOT/.knodin/hooks/${HOOK_FAILURE_FILE}"
 FAILURE_TMP="$FAILURE_PATH.$$"
 mkdir -p "$EVENT_DIR"
 if [ "$#" -gt 0 ]; then
@@ -165,7 +363,7 @@ if ! mkdir "$LOCK_DIR" 2>/dev/null; then
 fi
 printf '%s\\n' "$$" > "$LOCK_DIR/pid"
 trap 'rm -rf "$LOCK_DIR"; rm -f "$FAILURE_TMP"' EXIT HUP INT TERM
-LOG_PATH="$REPO_ROOT/.reckon/indexer.log"
+LOG_PATH="$REPO_ROOT/.knodin/indexer.log"
 if [ -f "$LOG_PATH" ]; then
   LOG_BYTES="$(wc -c < "$LOG_PATH" 2>/dev/null | tr -d '[:space:]')"
   case "$LOG_BYTES" in ''|*[!0-9]*) LOG_BYTES=0 ;; esac
@@ -197,7 +395,7 @@ while :; do
     {
       printf 'knodin background refresh failed with exit code %s.\\n' "$STATUS"
       printf 'Pending event retained at %s.\\n' "$EVENT"
-      printf 'See .reckon/indexer.log for details.\\n'
+      printf 'See .knodin/indexer.log for details.\\n'
     } > "$FAILURE_TMP"
     mv -f "$FAILURE_TMP" "$FAILURE_PATH"
     exit "$STATUS"
@@ -206,7 +404,7 @@ done
 `;
 }
 function queuedLifecycleEvents(repo) {
-    const eventDirectory = path.join(repo, ".reckon", "hooks", "events");
+    const eventDirectory = path.join(repo, ".knodin", "hooks", "events");
     try {
         return fs.readdirSync(eventDirectory).filter((entry) => entry.endsWith(".event"));
     }
@@ -216,7 +414,7 @@ function queuedLifecycleEvents(repo) {
 }
 function refreshProcessorIsRunning(repo) {
     try {
-        const pid = Number(fs.readFileSync(path.join(repo, ".reckon", "hooks", "refresh.lock", "pid"), "utf-8"));
+        const pid = Number(fs.readFileSync(path.join(repo, ".knodin", "hooks", "refresh.lock", "pid"), "utf-8"));
         if (!Number.isInteger(pid) || pid <= 0)
             return false;
         process.kill(pid, 0);
@@ -238,7 +436,7 @@ function drainQueuedLifecycleEvents(repo, backgroundPath) {
     });
     if (result.status !== 0) {
         const detail = result.error?.message || result.stderr.trim() || `exit ${result.status ?? "unknown"}`;
-        throw new Error(`knodin init: queued lifecycle refresh could not be drained (${detail}); run ${backgroundPath} after resolving .reckon/hooks/last-refresh-failure`);
+        throw new Error(`knodin init: queued lifecycle refresh could not be drained (${detail}); run ${backgroundPath} after resolving .knodin/hooks/last-refresh-failure`);
     }
     const remaining = queuedLifecycleEvents(repo);
     if (remaining.length === 0)
@@ -258,7 +456,7 @@ function managedHookScript(hookName, originalPath) {
             : shellQuote(originalPath)
         : "";
     const runOriginal = originalPath
-        ? `${original} "$@"${hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : ""} || ORIGINAL_STATUS=$?`
+        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"${hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : ""} || ORIGINAL_STATUS=$?`
         : ":";
     let trigger = "";
     if (hookName === "post-commit")
@@ -272,14 +470,14 @@ AFTER="$(git rev-parse HEAD 2>/dev/null || true)"
 [ -n "$BEFORE" ] && [ -n "$AFTER" ] && trigger_knodin merge "$BEFORE" "$AFTER"`;
     }
     const rewriteWithoutIndexer = originalPath
-        ? `${original} "$@"
+        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"
   exit $?`
         : "exit 0";
     const rewriteSetup = hookName === "post-rewrite"
         ? `if [ ! -x "$BACKGROUND" ]; then
   ${rewriteWithoutIndexer}
 fi
-REWRITE_INPUT="$(mktemp "$REPO_ROOT/.reckon/hooks/rewrite-input.XXXXXX")" || exit 0
+REWRITE_INPUT="$(mktemp "$REPO_ROOT/.knodin/hooks/rewrite-input.XXXXXX")" || exit 0
 cat > "$REWRITE_INPUT"
 `
         : "";
@@ -289,7 +487,7 @@ cat > "$REWRITE_INPUT"
 # ${MANAGED_MARKER}: ${hookName}
 REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
 [ -n "$REPO_ROOT" ] || exit 0
-BACKGROUND="$REPO_ROOT/.reckon/hooks/background-index.sh"
+BACKGROUND="$REPO_ROOT/.knodin/hooks/background-index.sh"
 ORIGINAL_STATUS=0
 trigger_knodin() {
   [ -x "$BACKGROUND" ] || return 0
@@ -304,7 +502,7 @@ trigger_knodin() {
     EVENT_BEFORE="$(sed -n '1{s/ .*//;p;}' "$2")"
     EVENT_AFTER="$(sed -n '1{s/^[^ ]* //;s/ .*//;p;}' "$2")"
   fi
-  EVENT_DIR="$REPO_ROOT/.reckon/hooks/events"
+  EVENT_DIR="$REPO_ROOT/.knodin/hooks/events"
   mkdir -p "$EVENT_DIR" || return 0
   EVENT_TMP="$EVENT_DIR/$(date +%s).$$.$PPID.tmp"
   EVENT_PATH="$EVENT_TMP.event"
@@ -319,7 +517,7 @@ trigger_knodin() {
       "$EVENT_SEQUENCE" "$EVENT_WORKTREE" "$EVENT_AT" "$EVENT_BEFORE" "$EVENT_AFTER"
   } > "$EVENT_TMP" || return 0
   mv "$EVENT_TMP" "$EVENT_PATH" || return 0
-  if [ "\${RECKON_HOOK_FOREGROUND:-0}" = "1" ]; then
+  if [ "\${KNODIN_HOOK_FOREGROUND:-0}" = "1" ]; then
     "$BACKGROUND"
   else
     nohup "$BACKGROUND" >/dev/null 2>&1 &
@@ -346,13 +544,12 @@ async function installManagedHook(hooksDir, hookName, preservedOriginal = undefi
     let originalPath = preservedOriginal ?? null;
     if (preservedOriginal === undefined && fs.existsSync(hookPath)) {
         const content = await fs.promises.readFile(hookPath, "utf-8");
-        if (content.startsWith(`#!/bin/sh\n# ${MANAGED_MARKER}: ${hookName}\n`) ||
-            content.startsWith(`#!/bin/sh\n# ${LEGACY_MANAGED_MARKER}: ${hookName}\n`)) {
+        if (content.startsWith(`#!/bin/sh\n# ${MANAGED_MARKER}: ${hookName}\n`)) {
             const match = content.match(/^# knodin original: (.+)$/m);
             originalPath = match?.[1] ?? null;
         }
         else {
-            const backupPath = `${hookPath}.reckon-original`;
+            const backupPath = `${hookPath}.knodin-original`;
             const mode = (await fs.promises.stat(hookPath)).mode;
             await fs.promises.copyFile(hookPath, backupPath);
             await fs.promises.rm(hookPath, { force: true });
@@ -365,9 +562,7 @@ async function installManagedHook(hooksDir, hookName, preservedOriginal = undefi
                 if (!fs.existsSync(candidate))
                     break;
                 const candidateContent = await fs.promises.readFile(candidate, "utf-8");
-                if (candidateContent === canonical ||
-                    candidateContent.includes(MANAGED_MARKER) ||
-                    candidateContent.includes(LEGACY_MANAGED_MARKER))
+                if (candidateContent === canonical || candidateContent.includes(MANAGED_MARKER))
                     await fs.promises.rm(candidate, { force: true });
             }
             // Match Git's semantics: preserve inactive hook files as backups, but
@@ -388,7 +583,6 @@ async function installManagedHook(hooksDir, hookName, preservedOriginal = undefi
     await fs.promises.chmod(hookPath, 0o755);
 }
 const ORIGINAL_HOOKS_CONFIG = "knodin.originalHooksPath";
-const LEGACY_ORIGINAL_HOOKS_CONFIG = "reckon.originalHooksPath";
 function effectiveHooksDirectory(repo) {
     let raw;
     try {
@@ -405,15 +599,10 @@ function configuredHooksPath(repo) {
     }
     catch {
         try {
-            return (runGit(repo, ["config", "--local", "--get", LEGACY_ORIGINAL_HOOKS_CONFIG]).trim() || null);
+            return runGit(repo, ["config", "--local", "--get", "core.hooksPath"]).trim() || null;
         }
         catch {
-            try {
-                return runGit(repo, ["config", "--local", "--get", "core.hooksPath"]).trim() || null;
-            }
-            catch {
-                return null;
-            }
+            return null;
         }
     }
 }
@@ -494,10 +683,10 @@ export const SETTINGS_TEMPLATE = `{
   }
 }
 `;
-const RECKON_AGENT_INSTRUCTIONS = `<!-- knodin:start -->
+const KNODIN_AGENT_INSTRUCTIONS = `<!-- knodin:start -->
 ## knodin — Local Code Intelligence
 
-This repository is indexed locally by knodin. Start with \`knodin status\`; if it reports \`repair-needed\`, run \`knodin repair\` before relying on graph evidence.
+This repository is indexed locally by knodin. Start with \`knodin status\`; if it reports \`repair-needed\`, follow its repair steps before relying on graph evidence. Use \`knodin repair\` for graph damage and \`knodin init\` for displaced lifecycle hooks.
 
 - When the single connected knodin MCP tool is available, use it directly. For cold or unfamiliar work, call its \`context\` operation before broad Read/Grep/Glob traversal. Use shell commands only as a fallback when the gateway is unavailable.
 - Before a meaningful edit, call the gateway's \`query\` operation with the \`impact\` pattern (CLI fallback: \`knodin query impact <symbol> --direction upstream\`) and report material risk to the user.
@@ -531,38 +720,50 @@ async function installManagedAgentInstructions(repo, fileName = "AGENTS.md") {
     await assertSafeRepositoryFile(repo, fileName);
     const instructionsPath = path.join(repo, fileName);
     let existing = "";
+    let existed = true;
     try {
         existing = await fs.promises.readFile(instructionsPath, "utf-8");
     }
     catch (error) {
         if (error.code !== "ENOENT")
             throw error;
+        existed = false;
     }
     const canonicalStart = "<!-- knodin:start -->";
     const canonicalEnd = "<!-- knodin:end -->";
-    const legacyStart = "<!-- reckon-graph:start -->";
-    const legacyEnd = "<!-- reckon-graph:end -->";
-    const usesCanonical = existing.includes(canonicalStart);
-    const startMarker = usesCanonical ? canonicalStart : legacyStart;
-    const endMarker = usesCanonical ? canonicalEnd : legacyEnd;
-    const start = existing.indexOf(startMarker);
-    const end = existing.indexOf(endMarker);
+    const start = existing.indexOf(canonicalStart);
+    const end = existing.indexOf(canonicalEnd);
     const next = start >= 0 && end >= start
-        ? `${existing.slice(0, start)}${RECKON_AGENT_INSTRUCTIONS}${existing.slice(end + endMarker.length).replace(/^\r?\n/, "")}`
+        ? `${existing.slice(0, start)}${KNODIN_AGENT_INSTRUCTIONS}${existing.slice(end + canonicalEnd.length).replace(/^\r?\n/, "")}`
         : existing.length > 0
-            ? `${existing.replace(/\s*$/, "")}\n\n${RECKON_AGENT_INSTRUCTIONS}`
-            : RECKON_AGENT_INSTRUCTIONS;
-    if (next !== existing)
-        await fs.promises.writeFile(instructionsPath, next, "utf-8");
+            ? `${existing.trimEnd()}\n\n${KNODIN_AGENT_INSTRUCTIONS}`
+            : KNODIN_AGENT_INSTRUCTIONS;
+    if (next === existing)
+        return null;
+    await fs.promises.writeFile(instructionsPath, next, "utf-8");
+    return { path: fileName, action: existed ? "modified" : "created" };
 }
 async function hasManagedAgentInstructions(repo, fileName = "AGENTS.md") {
     try {
-        return (await fs.promises.readFile(path.join(repo, fileName), "utf-8")).includes(RECKON_AGENT_INSTRUCTIONS);
+        return (await fs.promises.readFile(path.join(repo, fileName), "utf-8")).includes(KNODIN_AGENT_INSTRUCTIONS);
     }
     catch {
         return false;
     }
 }
+function removeManagedAgentBlock(content) {
+    const start = content.indexOf("<!-- knodin:start -->");
+    const end = content.indexOf("<!-- knodin:end -->", start);
+    if (start < 0 || end < start)
+        return null;
+    const prefix = content.slice(0, start);
+    const suffix = content.slice(end + "<!-- knodin:end -->".length);
+    // The canonical marker-only file owns its final line terminator as part of
+    // the generated block. Any other prefix/suffix bytes remain untouched.
+    if (prefix.length === 0 && /^\r?\n$/.test(suffix))
+        return "";
+    return `${prefix}${suffix}`;
+}
 function isTracked(repo, relativePath) {
     try {
         return nulPaths(repo, ["ls-files", "--", relativePath]).length > 0;
@@ -589,9 +790,7 @@ async function excludeUntrackedPaths(repo, candidates) {
     }
     const startMarker = "# knodin:start";
     const endMarker = "# knodin:end";
-    const outside = existing
-        .replace(/(?:^|\n)# knodin:start\n[\s\S]*?\n# knodin:end\n?/, "\n")
-        .replace(/(?:^|\n)# reckon-graph:start\n[\s\S]*?\n# reckon-graph:end\n?/, "\n");
+    const outside = existing.replace(/(?:^|\n)# knodin:start\n[\s\S]*?\n# knodin:end\n?/, "\n");
     const outsideLines = new Set(outside.split(/\r?\n/));
     const owned = safe.filter((candidate) => !outsideLines.has(candidate));
     const prefix = outside && !outside.endsWith("\n") ? `${outside}\n` : outside;
@@ -618,38 +817,35 @@ async function removeManagedExcludes(repo) {
     await fs.promises.writeFile(excludePath, next, "utf-8");
 }
 async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = false) {
+    const changes = [];
     for (const fileName of ["AGENTS.md", "GEMINI.md"]) {
         const instructionsPath = path.join(repo, fileName);
         const tracked = isTracked(repo, fileName);
         try {
+            await assertSafeRepositoryFile(repo, fileName);
             const current = await fs.promises.readFile(instructionsPath, "utf-8");
+            const start = current.indexOf("<!-- knodin:start -->");
+            const end = current.indexOf("<!-- knodin:end -->", start);
+            const without = removeManagedAgentBlock(current);
             if (!tracked) {
-                const start = current.indexOf("<!-- knodin:start -->");
-                const end = current.indexOf("<!-- knodin:end -->");
-                if (start >= 0 && end >= start) {
-                    const without = `${current.slice(0, start)}${current.slice(end + "<!-- knodin:end -->".length)}`
-                        .replace(/\n{3,}/g, "\n\n")
-                        .trim();
-                    if (without)
-                        await fs.promises.writeFile(instructionsPath, `${without}\n`, "utf-8");
-                    else
+                if (without !== null) {
+                    if (without.length > 0) {
+                        await fs.promises.writeFile(instructionsPath, without, "utf-8");
+                        changes.push({ path: fileName, action: "modified" });
+                    }
+                    else {
                         await fs.promises.rm(instructionsPath, { force: true });
+                        changes.push({ path: fileName, action: "removed" });
+                    }
                 }
                 continue;
             }
-            const head = runGit(repo, ["show", `HEAD:${fileName}`]);
-            const start = current.indexOf("<!-- knodin:start -->");
-            const end = current.indexOf("<!-- knodin:end -->");
-            if (allowTrackedTransition && start >= 0 && end >= start) {
-                const without = `${current.slice(0, start)}${current.slice(end + "<!-- knodin:end -->".length)}`
-                    .replace(/\n{3,}/g, "\n\n")
-                    .trimEnd();
-                if (without)
-                    await fs.promises.writeFile(instructionsPath, `${without}\n`, "utf-8");
-                else
-                    await fs.promises.rm(instructionsPath, { force: true });
+            if (allowTrackedTransition && without !== null) {
+                await fs.promises.writeFile(instructionsPath, without, "utf-8");
+                changes.push({ path: fileName, action: "modified" });
                 continue;
             }
+            const head = runGit(repo, ["show", `HEAD:${fileName}`]);
             if (start >= 0 && end >= start && !head.includes("<!-- knodin:start -->")) {
                 const without = `${current.slice(0, start)}${current.slice(end + "<!-- knodin:end -->".length)}`
                     .replace(/\n{3,}/g, "\n\n")
@@ -666,7 +862,7 @@ async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = fal
     try {
         const current = await fs.promises.readFile(gitIgnorePath, "utf-8");
         const next = current
-            .replace(/(?:^|\n)# knodin:start\n\.reckon\/\n# knodin:end\n?/g, "\n")
+            .replace(/(?:^|\n)# knodin:start\n\.knodin\/\n# knodin:end\n?/g, "\n")
             .trim();
         if (isTracked(repo, ".gitignore")) {
             const head = runGit(repo, ["show", "HEAD:.gitignore"]);
@@ -699,10 +895,11 @@ async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = fal
             // Missing or user-modified files are intentionally preserved.
         }
     }
+    return changes;
 }
 export function readRepositoryIntegrationConfig(repo) {
     try {
-        const value = JSON.parse(fs.readFileSync(path.join(repo, ".reckon", "integration.json"), "utf-8"));
+        const value = JSON.parse(fs.readFileSync(path.join(repo, ".knodin", "integration.json"), "utf-8"));
         if ((value.scope === "personal" || value.scope === "team" || value.scope === "cli-only") &&
             Array.isArray(value.agents))
             return { scope: value.scope, agents: value.agents };
@@ -712,6 +909,22 @@ export function readRepositoryIntegrationConfig(repo) {
     }
     return null;
 }
+function hasSafeManagedAgentBlock(repo, relativePath) {
+    try {
+        let current = repo;
+        for (const part of relativePath.split(path.sep)) {
+            current = path.join(current, part);
+            if (fs.lstatSync(current).isSymbolicLink())
+                return false;
+        }
+        const content = fs.readFileSync(path.join(repo, relativePath), "utf-8");
+        const start = content.indexOf("<!-- knodin:start -->");
+        return start >= 0 && content.indexOf("<!-- knodin:end -->", start) >= start;
+    }
+    catch {
+        return false;
+    }
+}
 /** Detect repository-owned client configuration independently of knodin's local receipt. */
 export function inspectRepositoryIntegrationStatus(repo) {
     const receipt = readRepositoryIntegrationConfig(repo);
@@ -720,13 +933,27 @@ export function inspectRepositoryIntegrationStatus(repo) {
         { agent: "codex", path: ".codex/config.toml", marker: 'mcp_servers."knodin"' },
         { agent: "gemini", path: ".gemini/settings.json", marker: '"knodin"' },
         { agent: "antigravity", path: ".agents/mcp_config.json", marker: '"knodin"' },
+        {
+            agent: "codex",
+            path: "AGENTS.md",
+            marker: "<!-- knodin:start -->",
+            managedGuidance: true,
+        },
+        {
+            agent: "gemini",
+            path: "GEMINI.md",
+            marker: "<!-- knodin:start -->",
+            managedGuidance: true,
+        },
     ];
-    const configurations = candidates.map(({ agent, path: relative, marker }) => {
+    const configurations = candidates.map(({ agent, path: relative, marker, managedGuidance }) => {
         try {
             return {
                 agent,
                 path: relative,
-                present: fs.readFileSync(path.join(repo, relative), "utf-8").includes(marker),
+                present: managedGuidance
+                    ? hasSafeManagedAgentBlock(repo, relative)
+                    : fs.readFileSync(path.join(repo, relative), "utf-8").includes(marker),
             };
         }
         catch {
@@ -745,10 +972,10 @@ export function inspectRepositoryIntegrationStatus(repo) {
     };
 }
 async function writeRepositoryIntegrationConfig(repo, config) {
-    await fs.promises.writeFile(path.join(repo, ".reckon", "integration.json"), `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+    await fs.promises.writeFile(path.join(repo, ".knodin", "integration.json"), `${JSON.stringify(config, null, 2)}\n`, "utf-8");
 }
 async function ensureTeamGitIgnore(repo) {
-    if (isTracked(repo, ".reckon"))
+    if (isTracked(repo, ".knodin"))
         return;
     await assertSafeRepositoryFile(repo, ".gitignore");
     const ignorePath = path.join(repo, ".gitignore");
@@ -760,10 +987,10 @@ async function ensureTeamGitIgnore(repo) {
         if (error.code !== "ENOENT")
             throw error;
     }
-    if (existing.split(/\r?\n/).includes(".reckon/"))
+    if (existing.split(/\r?\n/).includes(".knodin/"))
         return;
     const prefix = existing && !existing.endsWith("\n") ? `${existing}\n` : existing;
-    await fs.promises.writeFile(ignorePath, `${prefix}# knodin:start\n.reckon/\n# knodin:end\n`, "utf-8");
+    await fs.promises.writeFile(ignorePath, `${prefix}# knodin:start\n.knodin/\n# knodin:end\n`, "utf-8");
 }
 export function detectTrackedTeamIntegration(repo) {
     const checks = [
@@ -797,12 +1024,16 @@ export async function initializeRepository(repo, options) {
     if (!path.isAbsolute(options.command[0])) {
         throw new Error("knodin init: packaged runtime command must be an absolute path");
     }
+    const mutationTargets = options.auditConfigurationChanges
+        ? configureMutationAuditTargets(resolvedRepo)
+        : [];
+    const beforeMutation = mutationSnapshot(mutationTargets);
     if (scope !== "team" &&
         !options.allowTrackedTransition &&
         detectTrackedTeamIntegration(resolvedRepo)) {
         throw new Error("knodin init: tracked team integration is active; use `knodin configure --scope personal` or `--scope cli-only` for an explicit commit-ready transition");
     }
-    const knodinHooksDir = path.join(resolvedRepo, ".reckon", "hooks");
+    const knodinHooksDir = path.join(resolvedRepo, ".knodin", "hooks");
     const hookInstallation = await prepareHookInstallation(resolvedRepo);
     const hooksDir = hookInstallation.hooksDir;
     await Promise.all([
@@ -815,6 +1046,7 @@ export async function initializeRepository(repo, options) {
         mode: 0o755,
     });
     await fs.promises.chmod(backgroundPath, 0o755);
+    const hookManagerIntegration = installHookManagerIntegration(resolvedRepo);
     for (const hookName of HOOK_NAMES) {
         let preservedOriginal;
         if (hookInstallation.trackedHooksDir) {
@@ -845,12 +1077,16 @@ export async function initializeRepository(repo, options) {
     }
     const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath);
     await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), { force: true });
+    let agentInstructionChanges = [];
     if (scope === "team") {
-        await installManagedAgentInstructions(resolvedRepo, "AGENTS.md");
-        await installManagedAgentInstructions(resolvedRepo, "GEMINI.md");
+        const installed = await Promise.all([
+            installManagedAgentInstructions(resolvedRepo, "AGENTS.md"),
+            installManagedAgentInstructions(resolvedRepo, "GEMINI.md"),
+        ]);
+        agentInstructionChanges = installed.filter((change) => change !== null);
     }
     else {
-        await removeManagedPersonalArtifacts(resolvedRepo, options.allowTrackedTransition);
+        agentInstructionChanges = await removeManagedPersonalArtifacts(resolvedRepo, options.allowTrackedTransition);
     }
     const requestedAgents = options.agents ?? [];
     const projectPathByAgent = {
@@ -859,6 +1095,7 @@ export async function initializeRepository(repo, options) {
         antigravity: ".agents/mcp_config.json",
     };
     const blockedAgents = [];
+    const externalConfigurationOutcomes = [];
     if (scope === "personal" &&
         options.allowTrackedTransition &&
         priorIntegration?.scope === "team") {
@@ -870,6 +1107,11 @@ export async function initializeRepository(repo, options) {
         });
         if (cleanup.failed.length > 0)
             throw new Error(`knodin configure: could not remove tracked team integration: ${cleanup.failed[0]?.message}`);
+        if (cleanup.removed.includes("claude"))
+            externalConfigurationOutcomes.push({
+                system: "claude-local-mcp",
+                state: "removal-attempted",
+            });
     }
     const eligibleAgents = scope === "team"
         ? requestedAgents
@@ -893,6 +1135,18 @@ export async function initializeRepository(repo, options) {
         agents: eligibleAgents,
         run: options.runAgentCommand,
     });
+    if (scope === "personal" && agentIntegration.configured.includes("claude"))
+        externalConfigurationOutcomes.push({
+            system: "claude-local-mcp",
+            state: "configured-or-present",
+        });
+    if (scope === "cli-only" &&
+        agentIntegration.removed.includes("claude") &&
+        !externalConfigurationOutcomes.some(({ system, state }) => system === "claude-local-mcp" && state === "removal-attempted"))
+        externalConfigurationOutcomes.push({
+            system: "claude-local-mcp",
+            state: "removal-attempted",
+        });
     agentIntegration.failed.push(...blockedAgents);
     await writeRepositoryIntegrationConfig(resolvedRepo, {
         scope,
@@ -905,25 +1159,36 @@ export async function initializeRepository(repo, options) {
     else if (scope === "cli-only") {
         await removeManagedExcludes(resolvedRepo);
     }
-    const excluded = scope === "team"
+    let excluded = scope === "team"
         ? []
         : await excludeUntrackedPaths(resolvedRepo, [
-            ...(isTracked(resolvedRepo, ".reckon") ? [] : [".reckon/"]),
+            ...(isTracked(resolvedRepo, ".knodin") ? [] : [".knodin/"]),
             ...agentIntegration.projectFiles,
         ]);
+    if (hookManagerIntegration) {
+        const managerExcludes = await excludeUntrackedPaths(resolvedRepo, [
+            hookManagerIntegration.localConfig,
+        ]);
+        excluded = [...new Set([...excluded, ...managerExcludes])].sort();
+    }
     registerInitializedWorktree(resolvedRepo);
+    const detectedFilesystemChanges = filesystemChanges(beforeMutation, mutationSnapshot(mutationTargets, true));
     return {
         scope,
-        knodin: ".reckon",
-        database: ".reckon/db.sqlite",
-        backgroundIndexer: ".reckon/hooks/background-index.sh",
+        knodin: ".knodin",
+        database: ".knodin/db.sqlite",
+        backgroundIndexer: ".knodin/hooks/background-index.sh",
         hooksDirectory: path.relative(resolvedRepo, hooksDir) || ".",
         gitHooks: [...HOOK_NAMES],
         claudeSettings: null,
         agentInstructions: scope === "team" ? "AGENTS.md" : null,
         agentIntegration,
+        agentInstructionChanges,
+        filesystemChanges: detectedFilesystemChanges,
+        externalConfigurationOutcomes,
         excluded,
         lifecycleRefresh,
+        hookManagerIntegration,
     };
 }
 async function matchesManagedFile(filePath, expected, executable) {
@@ -956,6 +1221,7 @@ export async function isRepositoryInitializationCurrent(repo, command, scope = "
     catch {
         return false;
     }
+    const lefthook = inspectLefthookIntegration(resolvedRepo);
     const managedHooks = await Promise.all(HOOK_NAMES.map(async (hookName) => {
         const hookPath = path.join(hooksDir, hookName);
         try {
@@ -967,7 +1233,9 @@ export async function isRepositoryInitializationCurrent(repo, command, scope = "
             let expected = managedHookScript(hookName, originalPath);
             if (originalPath)
                 expected = expected.replace("\nREPO_ROOT=", `\n# knodin original: ${originalPath}\nREPO_ROOT=`);
-            return stat.isFile() && (stat.mode & 0o111) !== 0 && content === expected;
+            return (stat.isFile() &&
+                (stat.mode & 0o111) !== 0 &&
+                (content === expected || (lefthook.configured && isActiveLefthookHook(content))));
         }
         catch {
             return false;
@@ -979,7 +1247,8 @@ export async function isRepositoryInitializationCurrent(repo, command, scope = "
         ((await hasManagedAgentInstructions(resolvedRepo, "AGENTS.md")) &&
             (await hasManagedAgentInstructions(resolvedRepo, "GEMINI.md")));
     const integrationCurrent = readRepositoryIntegrationConfig(resolvedRepo)?.scope === scope;
-    return ((await matchesManagedFile(path.join(resolvedRepo, ".reckon", "hooks", "background-index.sh"), backgroundScript(command), true)) &&
+    return ((await matchesManagedFile(path.join(resolvedRepo, ".knodin", "hooks", "background-index.sh"), backgroundScript(command), true)) &&
         sharedFilesCurrent &&
-        integrationCurrent);
+        integrationCurrent &&
+        (lefthook.localConfig === null || lefthook.configured));
 }