knodin 0.7.6 → 0.8.3

package/dist/src/init.js

@@ -0,0 +1,1295 @@
+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 { compareBytes } from "./compare.js";
+import { isIndexableSourcePath } from "./engine/source-policy.js";
+import { lookupMirror } from "./engine/state-paths.js";
+import { inspectLefthookIntegration, installHookManagerIntegration, isActiveLefthookHook, } from "./hook-manager-integration.js";
+import { registerInitializedWorktree } from "./worktree-lifecycle.js";
+const MANAGED_MARKER = "KNODIN 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";
+export class InitializationHealthError extends Error {
+    indexResult;
+    constructor(indexResult) {
+        const firstIssue = indexResult.verification.missing.files[0] ?? indexResult.verification.missing.records[0];
+        const detail = firstIssue ? ` First issue: ${firstIssue}.` : "";
+        super(`knodin init: lifecycle hooks were installed, but ${indexResult.verification.issueCount.toLocaleString()} graph issue(s) remain.${detail} Run \`knodin repair\`.`);
+        this.name = "InitializationHealthError";
+        this.indexResult = indexResult;
+    }
+}
+function isIndexResult(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const candidate = value;
+    const verification = candidate.verification;
+    return (Array.isArray(candidate.indexed) &&
+        Array.isArray(candidate.unchanged) &&
+        typeof verification === "object" &&
+        verification !== null &&
+        typeof verification.status === "string" &&
+        typeof verification.issueCount === "number" &&
+        Array.isArray(verification.missing?.files) &&
+        Array.isArray(verification.missing?.records));
+}
+function runGit(repo, args, encoding = "utf-8") {
+    return child_process.execFileSync("git", args, {
+        cwd: repo,
+        encoding,
+        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 resolvedEffectiveHooks = path.resolve(effectiveHooks);
+    let effectiveLabel = "effective-git-hooks";
+    if (resolvedEffectiveHooks === path.resolve(defaultHooks))
+        effectiveLabel = ".git/hooks";
+    else if (resolvedEffectiveHooks === path.resolve(managedHooks))
+        effectiveLabel = ".git/knodin-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(compareBytes)
+        .flatMap((changedPath) => {
+        const prior = before.get(changedPath);
+        const current = after.get(changedPath);
+        if (prior === current)
+            return [];
+        let action = "modified";
+        if (prior === undefined)
+            action = "created";
+        else if (current === undefined)
+            action = "removed";
+        return [{ path: changedPath, action }];
+    });
+}
+const SHELL_QUOTE_ESCAPE = String.raw `'\''`;
+function shellQuote(value) {
+    return `'${value.replaceAll("'", SHELL_QUOTE_ESCAPE)}'`;
+}
+function nulPaths(repo, args) {
+    const separator = args.indexOf("--");
+    const nulArgs = separator < 0 ? [...args, "-z"] : [...args.slice(0, separator), "-z", ...args.slice(separator)];
+    const output = runGit(repo, nulArgs, "utf-8");
+    return output.split("\0").filter(Boolean);
+}
+function diffPaths(repo, before, after) {
+    if (!/^[0-9a-fA-F]{40,64}$/.test(before) || !/^[0-9a-fA-F]{40,64}$/.test(after)) {
+        throw new Error("knodin hook refresh: invalid Git object id");
+    }
+    return nulPaths(repo, ["diff", "--name-only", before, after, "--"]);
+}
+/**
+ * Resolve changed paths from a Git lifecycle event and incrementally reconcile
+ * exactly the candidates accepted by the engine's full-repository policy.
+ */
+export async function refreshFromGitEvent(repo, event, index) {
+    const resolvedRepo = path.resolve(repo);
+    let changed = [];
+    let rewriteInputToRemove;
+    try {
+        if (event.kind === "commit") {
+            changed = nulPaths(resolvedRepo, [
+                "diff-tree",
+                "--root",
+                "--no-commit-id",
+                "--name-only",
+                "-r",
+                "HEAD",
+            ]);
+        }
+        else if (event.kind === "checkout" || event.kind === "merge") {
+            changed = diffPaths(resolvedRepo, event.before, event.after);
+        }
+        else {
+            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 .knodin/hooks");
+            }
+            const [realHooksRoot, realInputPath, inputStat] = await Promise.all([
+                fs.promises.realpath(hooksRoot),
+                fs.promises.realpath(inputPath),
+                fs.promises.lstat(inputPath),
+            ]);
+            const realRelativeInput = path.relative(realHooksRoot, realInputPath);
+            if (inputStat.isSymbolicLink() ||
+                !inputStat.isFile() ||
+                realRelativeInput === "" ||
+                realRelativeInput === ".." ||
+                realRelativeInput.startsWith(`..${path.sep}`) ||
+                path.isAbsolute(realRelativeInput)) {
+                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"))
+                .split(/\r?\n/)
+                .map((line) => line.trim().split(/\s+/))
+                .filter((pair) => pair.length >= 2);
+            for (const [before, after] of pairs) {
+                changed.push(...diffPaths(resolvedRepo, before, after));
+            }
+        }
+        const eligible = [...new Set(changed.map((file) => file.replaceAll("\\", "/")))]
+            .filter(isIndexableSourcePath)
+            .sort(compareBytes);
+        if (eligible.length > 0)
+            await index(resolvedRepo, eligible);
+        return eligible;
+    }
+    finally {
+        if (rewriteInputToRemove)
+            await fs.promises.rm(rewriteInputToRemove, { force: true });
+    }
+}
+function backgroundScript(command) {
+    const invocation = command.map(shellQuote).join(" ");
+    return String.raw `#!/bin/sh
+# knodin packaged background refresh. Generated by knodin init.
+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/.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
+  EVENT_TMP="$EVENT_DIR/$(date +%s).$$.$PPID.compat.tmp"
+  EVENT_SEQUENCE="$(date +%s).$$.$PPID"
+  EVENT_WORKTREE="$REPO_ROOT"
+  EVENT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  {
+    for EVENT_ARG in "$@"; do
+      printf '%s\n' "$EVENT_ARG"
+    done
+    printf 'sequence=%s\nworktree=%s\nat=%s\n' "$EVENT_SEQUENCE" "$EVENT_WORKTREE" "$EVENT_AT"
+  } > "$EVENT_TMP"
+  mv "$EVENT_TMP" "$EVENT_TMP.event"
+fi
+if ! mkdir "$LOCK_DIR" 2>/dev/null; then
+  if [ -f "$LOCK_DIR/pid" ]; then
+    LOCK_PID="$(cat "$LOCK_DIR/pid" 2>/dev/null || true)"
+    if [ -n "$LOCK_PID" ] && ! kill -0 "$LOCK_PID" 2>/dev/null; then
+      rm -rf "$LOCK_DIR"
+      mkdir "$LOCK_DIR" 2>/dev/null || exit 0
+    else
+      exit 0
+    fi
+  else
+    exit 0
+  fi
+fi
+printf '%s\n' "$$" > "$LOCK_DIR/pid"
+trap 'rm -rf "$LOCK_DIR"; rm -f "$FAILURE_TMP"' EXIT HUP INT TERM
+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
+  if [ "$LOG_BYTES" -ge ${HOOK_LOG_MAX_BYTES} ]; then
+    mv -f "$LOG_PATH" "$LOG_PATH.1"
+  fi
+fi
+while :; do
+  EVENT="$(find "$EVENT_DIR" -type f -name '*.event' -print 2>/dev/null | LC_ALL=C sort | head -n 1)"
+  [ -n "$EVENT" ] || break
+  KIND="$(sed -n '1p' "$EVENT")"
+  ARG1="$(sed -n '2p' "$EVENT")"
+  ARG2="$(sed -n '3p' "$EVENT")"
+  if [ "$KIND" = "commit" ]; then
+    ${invocation} --repo "$REPO_ROOT" hook-refresh commit --json >> "$LOG_PATH" 2>&1
+  elif [ "$KIND" = "checkout" ] || [ "$KIND" = "merge" ]; then
+    ${invocation} --repo "$REPO_ROOT" hook-refresh "$KIND" "$ARG1" "$ARG2" --json >> "$LOG_PATH" 2>&1
+  elif [ "$KIND" = "rewrite" ]; then
+    ${invocation} --repo "$REPO_ROOT" hook-refresh rewrite "$ARG1" --json >> "$LOG_PATH" 2>&1
+  else
+    printf 'knodin background refresh: invalid queued event %s\n' "$KIND" >> "$LOG_PATH"
+    false
+  fi
+  STATUS=$?
+  if [ "$STATUS" -eq 0 ]; then
+    cp "$EVENT" "$LAST_EVENT_PATH"
+    rm -f "$EVENT" "$FAILURE_PATH"
+  else
+    {
+      printf 'knodin background refresh failed with exit code %s.\n' "$STATUS"
+      printf 'Pending event retained at %s.\n' "$EVENT"
+      printf 'See .knodin/indexer.log for details.\n'
+    } > "$FAILURE_TMP"
+    mv -f "$FAILURE_TMP" "$FAILURE_PATH"
+    exit "$STATUS"
+  fi
+done
+`;
+}
+function queuedLifecycleEvents(repo) {
+    const eventDirectory = path.join(repo, ".knodin", "hooks", "events");
+    try {
+        return fs.readdirSync(eventDirectory).filter((entry) => entry.endsWith(".event"));
+    }
+    catch {
+        return [];
+    }
+}
+function refreshProcessorIsRunning(repo) {
+    try {
+        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);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function drainQueuedLifecycleEvents(repo, backgroundPath) {
+    const before = queuedLifecycleEvents(repo);
+    if (before.length === 0)
+        return { state: "fresh", queuedEvents: 0 };
+    const result = child_process.spawnSync(backgroundPath, [], {
+        cwd: repo,
+        encoding: "utf-8",
+        stdio: ["ignore", "pipe", "pipe"],
+        timeout: 30_000,
+    });
+    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 .knodin/hooks/last-refresh-failure`);
+    }
+    const remaining = queuedLifecycleEvents(repo);
+    if (remaining.length === 0)
+        return { state: "fresh", queuedEvents: 0 };
+    if (refreshProcessorIsRunning(repo)) {
+        return { state: "running", queuedEvents: remaining.length };
+    }
+    if (remaining.length > 0) {
+        throw new Error("knodin init: queued lifecycle events remain after refresh; run `knodin wait --fresh`, then retry initialization");
+    }
+    return { state: "fresh", queuedEvents: 0 };
+}
+function managedHookScript(hookName, originalPath) {
+    let original = "";
+    if (originalPath)
+        original = originalPath.startsWith("repo:")
+            ? `"$REPO_ROOT"/${shellQuote(originalPath.slice("repo:".length))}`
+            : shellQuote(originalPath);
+    const rewriteRedirect = hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : "";
+    const runOriginal = originalPath
+        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"${rewriteRedirect} || ORIGINAL_STATUS=$?`
+        : ":";
+    let trigger = "";
+    if (hookName === "post-commit")
+        trigger = "trigger_knodin commit";
+    if (hookName === "post-checkout") {
+        trigger = `[ "\${3:-0}" = "1" ] && trigger_knodin checkout "\${1:-}" "\${2:-}"`;
+    }
+    if (hookName === "post-merge") {
+        trigger = `BEFORE="$(git rev-parse ORIG_HEAD 2>/dev/null || true)"
+AFTER="$(git rev-parse HEAD 2>/dev/null || true)"
+[ -n "$BEFORE" ] && [ -n "$AFTER" ] && trigger_knodin merge "$BEFORE" "$AFTER"`;
+    }
+    const rewriteWithoutIndexer = originalPath
+        ? `KNODIN_WRAPPER_ACTIVE=1 ${original} "$@"
+  exit $?`
+        : "exit 0";
+    const rewriteSetup = hookName === "post-rewrite"
+        ? `if [ ! -x "$BACKGROUND" ]; then
+  ${rewriteWithoutIndexer}
+fi
+REWRITE_INPUT="$(mktemp "$REPO_ROOT/.knodin/hooks/rewrite-input.XXXXXX")" || exit 0
+cat > "$REWRITE_INPUT"
+`
+        : "";
+    if (hookName === "post-rewrite")
+        trigger = 'trigger_knodin rewrite "$REWRITE_INPUT"';
+    return `#!/bin/sh
+# ${MANAGED_MARKER}: ${hookName}
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$REPO_ROOT" ] || exit 0
+BACKGROUND="$REPO_ROOT/.knodin/hooks/background-index.sh"
+ORIGINAL_STATUS=0
+trigger_knodin() {
+  [ -x "$BACKGROUND" ] || return 0
+  EVENT_KIND="\${1:-}"
+  EVENT_BEFORE="\${2:-}"
+  EVENT_AFTER="\${3:-}"
+  if [ "$EVENT_KIND" = "commit" ]; then
+    EVENT_BEFORE="$(git rev-parse HEAD^ 2>/dev/null || true)"
+    EVENT_AFTER="$(git rev-parse HEAD 2>/dev/null || true)"
+    set -- commit "$EVENT_BEFORE" "$EVENT_AFTER"
+  elif [ "$EVENT_KIND" = "rewrite" ] && [ -f "\${2:-}" ]; then
+    EVENT_BEFORE="$(sed -n '1{s/ .*//;p;}' "$2")"
+    EVENT_AFTER="$(sed -n '1{s/^[^ ]* //;s/ .*//;p;}' "$2")"
+  fi
+  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"
+  EVENT_SEQUENCE="$(date +%s).$$.$PPID"
+  EVENT_WORKTREE="$REPO_ROOT"
+  EVENT_AT="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
+  {
+    for EVENT_ARG in "$@"; do
+      printf '%s\\n' "$EVENT_ARG"
+    done
+    printf 'sequence=%s\\nworktree=%s\\nat=%s\\nbefore=%s\\nafter=%s\\n' \\
+      "$EVENT_SEQUENCE" "$EVENT_WORKTREE" "$EVENT_AT" "$EVENT_BEFORE" "$EVENT_AFTER"
+  } > "$EVENT_TMP" || return 0
+  mv "$EVENT_TMP" "$EVENT_PATH" || return 0
+  if [ "\${KNODIN_HOOK_FOREGROUND:-0}" = "1" ]; then
+    "$BACKGROUND"
+  else
+    nohup "$BACKGROUND" >/dev/null 2>&1 &
+  fi
+}
+${rewriteSetup}${runOriginal}
+${trigger}
+exit "$ORIGINAL_STATUS"
+`;
+}
+async function preventLefthookAutoInstall(hookPath) {
+    if (!fs.existsSync(hookPath))
+        return;
+    const content = await fs.promises.readFile(hookPath, "utf-8");
+    if (!content.includes("call_lefthook()"))
+        return;
+    const invocation = content.match(/^call_lefthook run "([^"\r\n]+)" "\$@"$/m);
+    if (!invocation)
+        return;
+    await fs.promises.writeFile(hookPath, content.replace(invocation[0], `call_lefthook run "${invocation[1]}" --no-auto-install "$@"`), "utf-8");
+}
+async function installManagedHook(hooksDir, hookName, preservedOriginal = undefined) {
+    const hookPath = path.join(hooksDir, hookName);
+    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`)) {
+            const match = content.match(/^# knodin original: (.+)$/m);
+            originalPath = match?.[1] ?? null;
+        }
+        else {
+            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 });
+            // Older releases appended a new backup on every displacement. Remove
+            // only copies that are provably redundant: another knodin wrapper or
+            // byte-identical to the authoritative current hook backup.
+            const canonical = await fs.promises.readFile(backupPath, "utf-8");
+            for (let suffix = 1;; suffix++) {
+                const candidate = `${backupPath}.${suffix}`;
+                if (!fs.existsSync(candidate))
+                    break;
+                const candidateContent = await fs.promises.readFile(candidate, "utf-8");
+                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
+            // never begin executing one merely because knodin installed a wrapper.
+            if ((mode & 0o111) !== 0)
+                originalPath = backupPath;
+        }
+    }
+    if (originalPath)
+        await preventLefthookAutoInstall(originalPath);
+    let content = managedHookScript(hookName, originalPath);
+    if (originalPath)
+        content = content.replace("\nREPO_ROOT=", `\n# knodin original: ${originalPath}\nREPO_ROOT=`);
+    await fs.promises.writeFile(hookPath, content, {
+        encoding: "utf-8",
+        mode: 0o755,
+    });
+    await fs.promises.chmod(hookPath, 0o755);
+}
+const ORIGINAL_HOOKS_CONFIG = "knodin.originalHooksPath";
+function effectiveHooksDirectory(repo) {
+    let raw;
+    try {
+        raw = runGit(repo, ["rev-parse", "--path-format=absolute", "--git-path", "hooks"]).trim();
+    }
+    catch {
+        raw = runGit(repo, ["rev-parse", "--git-path", "hooks"]).trim();
+    }
+    return path.isAbsolute(raw) ? raw : path.resolve(repo, raw);
+}
+function configuredHooksPath(repo) {
+    try {
+        return runGit(repo, ["config", "--local", "--get", ORIGINAL_HOOKS_CONFIG]).trim() || null;
+    }
+    catch {
+        try {
+            return runGit(repo, ["config", "--local", "--get", "core.hooksPath"]).trim() || null;
+        }
+        catch {
+            return null;
+        }
+    }
+}
+function repoRelativeHooksPath(repo, configured) {
+    const absolute = path.isAbsolute(configured) ? configured : path.resolve(repo, configured);
+    const relative = path.relative(repo, absolute).replaceAll("\\", "/");
+    if (!relative || relative === ".." || relative.startsWith("../") || path.isAbsolute(relative))
+        return null;
+    return relative;
+}
+function hasTrackedHooks(repo, relativeHooksDir) {
+    try {
+        return nulPaths(repo, ["ls-files", "--", relativeHooksDir]).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+function passthroughHookScript(relativeHookPath) {
+    return `#!/bin/sh
+# ${MANAGED_MARKER}: tracked-hook passthrough
+REPO_ROOT="$(git rev-parse --show-toplevel 2>/dev/null || true)"
+[ -n "$REPO_ROOT" ] || exit 0
+ORIGINAL="$REPO_ROOT"/${shellQuote(relativeHookPath)}
+[ -x "$ORIGINAL" ] || exit 0
+exec "$ORIGINAL" "$@"
+`;
+}
+async function prepareHookInstallation(repo) {
+    const configured = configuredHooksPath(repo);
+    const relative = configured ? repoRelativeHooksPath(repo, configured) : null;
+    if (!configured || !relative || !hasTrackedHooks(repo, relative)) {
+        return { hooksDir: effectiveHooksDirectory(repo), trackedHooksDir: null };
+    }
+    const commonGitDirRaw = runGit(repo, ["rev-parse", "--git-common-dir"]).trim();
+    const commonGitDir = path.isAbsolute(commonGitDirRaw)
+        ? commonGitDirRaw
+        : path.resolve(repo, commonGitDirRaw);
+    const hooksDir = path.join(commonGitDir, "knodin-hooks");
+    await fs.promises.mkdir(hooksDir, { recursive: true });
+    runGit(repo, ["config", "--local", ORIGINAL_HOOKS_CONFIG, configured]);
+    runGit(repo, ["config", "--local", "core.hooksPath", hooksDir]);
+    const sourceDir = path.join(repo, relative);
+    for (const entry of await fs.promises.readdir(sourceDir, {
+        withFileTypes: true,
+    })) {
+        if (!entry.isFile() || HOOK_NAMES.includes(entry.name))
+            continue;
+        const source = path.join(sourceDir, entry.name);
+        const stat = await fs.promises.stat(source);
+        if ((stat.mode & 0o111) === 0)
+            continue;
+        const target = path.join(hooksDir, entry.name);
+        await fs.promises.writeFile(target, passthroughHookScript(`${relative}/${entry.name}`), {
+            encoding: "utf-8",
+            mode: 0o755,
+        });
+        await fs.promises.chmod(target, 0o755);
+    }
+    return { hooksDir, trackedHooksDir: relative };
+}
+const NUDGE_SCRIPT = String.raw `#!/bin/sh
+# Example Claude Code hook: suggest local graph context for broad manual searches.
+read -r INPUT_PAYLOAD
+case "$INPUT_PAYLOAD" in
+  *grep*|*find*|*Glob*|*ReadFile*) REASON="For cold or unfamiliar work, call the connected knodin MCP gateway's context or explain operation before broad traversal; use the CLI only as a fallback." ;;
+  *) REASON="Proceeding with tool execution." ;;
+esac
+printf '{"hookSpecificOutput":{"hookEventName":"PreToolUse","permissionDecision":"allow","permissionDecisionReason":"%s"}}\n' "$REASON"
+`;
+export const SETTINGS_TEMPLATE = `{
+  "comment": "Template only: opt in to local knodin context nudges.",
+  "hooks": {
+    "PreToolUse": [{
+      "matcher": "Bash|Read|Glob",
+      "hooks": [{"type": "command", "command": "./.claude/hooks/nudge.sh", "timeout": 5}]
+    }]
+  }
+}
+`;
+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\`, 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.
+- Use gateway operations \`explain\`, \`review\`, and \`query\` for source-evidenced context. CLI fallbacks are \`knodin explain\`, \`knodin review --scope compare\`, and \`knodin rename\`.
+- Direct reads are appropriate for files just authored in the current session; do not force a graph round trip when the agent already has fresh source context.
+- Run \`knodin index <changed-files>\` while working when you need immediately fresh graph evidence. Managed Git hooks installed by \`knodin init\` refresh the graph after commits, checkouts, merges, and rewrites.
+- Keep output truthful: local graph evidence can be stale or ambiguous; say so and repair/reindex instead of claiming certainty.
+
+<!-- knodin:end -->
+`;
+async function assertSafeRepositoryFile(repo, relativePath) {
+    const target = path.resolve(repo, relativePath);
+    const relative = path.relative(repo, target);
+    if (relative.startsWith("..") || path.isAbsolute(relative))
+        throw new Error(`${relativePath}: managed file must stay inside the repository`);
+    let current = repo;
+    for (const part of relative.split(path.sep)) {
+        current = path.join(current, part);
+        try {
+            if ((await fs.promises.lstat(current)).isSymbolicLink())
+                throw new Error(`${relativePath}: refusing to follow a symbolic link`);
+        }
+        catch (error) {
+            if (error.code === "ENOENT")
+                break;
+            throw error;
+        }
+    }
+}
+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 start = existing.indexOf(canonicalStart);
+    const end = existing.indexOf(canonicalEnd);
+    let next = KNODIN_AGENT_INSTRUCTIONS;
+    if (start >= 0 && end >= start)
+        next = `${existing.slice(0, start)}${KNODIN_AGENT_INSTRUCTIONS}${existing.slice(end + canonicalEnd.length).replace(/^\r?\n/, "")}`;
+    else if (existing.length > 0)
+        next = `${existing.trimEnd()}\n\n${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(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;
+    }
+    catch {
+        return false;
+    }
+}
+const EXCLUDE_BLOCK_START = "# knodin:start\n";
+const EXCLUDE_BLOCK_END = "\n# knodin:end";
+/**
+ * Drop the first knodin-owned exclude block, replacing it with the single
+ * newline the block's leading line terminator contributed. A literal scan keeps
+ * this linear: a start marker with no following end marker can never be rescued
+ * by a later start marker, because every later body begins further right.
+ */
+function withoutManagedExcludeBlock(content) {
+    let start = content.indexOf(EXCLUDE_BLOCK_START);
+    while (start > 0 && content[start - 1] !== "\n")
+        start = content.indexOf(EXCLUDE_BLOCK_START, start + 1);
+    if (start < 0)
+        return content;
+    const end = content.indexOf(EXCLUDE_BLOCK_END, start + EXCLUDE_BLOCK_START.length);
+    if (end < 0)
+        return content;
+    let after = end + EXCLUDE_BLOCK_END.length;
+    if (content[after] === "\n")
+        after += 1;
+    return `${content.slice(0, start > 0 ? start - 1 : 0)}\n${content.slice(after)}`;
+}
+async function excludeUntrackedPaths(repo, candidates) {
+    const safe = [...new Set(candidates)]
+        .filter((candidate) => !isTracked(repo, candidate))
+        .sort(compareBytes);
+    if (safe.length === 0)
+        return [];
+    const rawExcludePath = runGit(repo, ["rev-parse", "--git-path", "info/exclude"]).trim();
+    const excludePath = path.isAbsolute(rawExcludePath)
+        ? rawExcludePath
+        : path.resolve(repo, rawExcludePath);
+    let existing = "";
+    try {
+        existing = await fs.promises.readFile(excludePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    const startMarker = "# knodin:start";
+    const endMarker = "# knodin:end";
+    const outside = withoutManagedExcludeBlock(existing);
+    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;
+    const block = owned.length > 0 ? `${startMarker}\n${owned.join("\n")}\n${endMarker}\n` : "";
+    await fs.promises.mkdir(path.dirname(excludePath), { recursive: true });
+    await fs.promises.writeFile(excludePath, `${prefix}${block}`, "utf-8");
+    return owned;
+}
+async function removeManagedExcludes(repo) {
+    const rawExcludePath = runGit(repo, ["rev-parse", "--git-path", "info/exclude"]).trim();
+    const excludePath = path.isAbsolute(rawExcludePath)
+        ? rawExcludePath
+        : path.resolve(repo, rawExcludePath);
+    let existing;
+    try {
+        existing = await fs.promises.readFile(excludePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return;
+        throw error;
+    }
+    const next = withoutManagedExcludeBlock(existing);
+    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) {
+                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;
+            }
+            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")
+                    .trimEnd();
+                if (without === head.trimEnd())
+                    await fs.promises.writeFile(instructionsPath, head);
+            }
+        }
+        catch {
+            // A missing HEAD version or unrelated working-tree edits are ambiguous.
+        }
+    }
+    const gitIgnorePath = path.join(repo, ".gitignore");
+    try {
+        const current = await fs.promises.readFile(gitIgnorePath, "utf-8");
+        const next = current
+            .replace(/(?:^|\n)# knodin:start\n\.knodin\/\n# knodin:end\n?/g, "\n")
+            .trim();
+        if (isTracked(repo, ".gitignore")) {
+            const head = runGit(repo, ["show", "HEAD:.gitignore"]);
+            if (allowTrackedTransition)
+                await fs.promises.writeFile(gitIgnorePath, next ? `${next}\n` : "");
+            else if (next === head.trim())
+                await fs.promises.writeFile(gitIgnorePath, head, "utf-8");
+        }
+        else if (next)
+            await fs.promises.writeFile(gitIgnorePath, `${next}\n`, "utf-8");
+        else
+            await fs.promises.rm(gitIgnorePath, { force: true });
+    }
+    catch {
+        // Missing or user-modified files are intentionally preserved.
+    }
+    for (const relative of [".claude/hooks/nudge.sh", ".claude/settings.example.json"]) {
+        if (isTracked(repo, relative))
+            continue;
+        const target = path.join(repo, relative);
+        try {
+            const content = await fs.promises.readFile(target, "utf-8");
+            if ((relative.endsWith("nudge.sh") && content === NUDGE_SCRIPT) ||
+                (relative.endsWith("settings.example.json") && content === SETTINGS_TEMPLATE))
+                await fs.promises.rm(target, { force: true });
+        }
+        catch {
+            // Missing or user-modified files are intentionally preserved.
+        }
+    }
+    return changes;
+}
+export function readRepositoryIntegrationConfig(repo) {
+    try {
+        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 };
+    }
+    catch {
+        // Missing or invalid local state is reported as unconfigured.
+    }
+    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);
+    const candidates = [
+        { agent: "claude", path: ".mcp.json", marker: '"knodin"' },
+        { 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, managedGuidance }) => {
+        try {
+            return {
+                agent,
+                path: relative,
+                present: managedGuidance
+                    ? hasSafeManagedAgentBlock(repo, relative)
+                    : fs.readFileSync(path.join(repo, relative), "utf-8").includes(marker),
+            };
+        }
+        catch {
+            return { agent, path: relative, present: false };
+        }
+    });
+    const detected = configurations.filter(({ present }) => present).map(({ agent }) => agent);
+    const agents = [...new Set([...(receipt?.agents ?? []), ...detected])];
+    if (!receipt && agents.length === 0)
+        return null;
+    return {
+        scope: receipt?.scope ?? "repository-detected",
+        agents,
+        receiptPresent: receipt !== null,
+        configurations,
+    };
+}
+async function writeRepositoryIntegrationConfig(repo, config) {
+    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, ".knodin"))
+        return;
+    await assertSafeRepositoryFile(repo, ".gitignore");
+    const ignorePath = path.join(repo, ".gitignore");
+    let existing = "";
+    try {
+        existing = await fs.promises.readFile(ignorePath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    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.knodin/\n# knodin:end\n`, "utf-8");
+}
+export function detectTrackedTeamIntegration(repo) {
+    const checks = [
+        ["AGENTS.md", "<!-- knodin:start -->"],
+        ["GEMINI.md", "<!-- knodin:start -->"],
+        [".gitignore", "# knodin:start"],
+        [".mcp.json", '"knodin"'],
+        [".codex/config.toml", "# knodin:start"],
+        [".gemini/settings.json", '"knodin"'],
+        [".agents/mcp_config.json", '"knodin"'],
+    ];
+    return checks.some(([relative, marker]) => {
+        if (!isTracked(repo, relative))
+            return false;
+        try {
+            return fs.readFileSync(path.join(repo, relative), "utf-8").includes(marker);
+        }
+        catch {
+            return false;
+        }
+    });
+}
+/** Install lifecycle hooks and initialize the local graph in a real Git worktree. */
+export async function initializeRepository(repo, options) {
+    const resolvedRepo = path.resolve(repo);
+    const scope = options.scope ?? "personal";
+    const priorIntegration = readRepositoryIntegrationConfig(resolvedRepo);
+    if (runGit(resolvedRepo, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true") {
+        throw new Error(`knodin init: not a Git worktree: ${resolvedRepo}`);
+    }
+    // A mirror is a shallow clone, so the worktree check above PASSES for one and
+    // init would go on to write .gitignore and install lifecycle hooks into a tree
+    // that is supposed to stay byte-identical to the remote. `knodin remote list`
+    // prints the clone path, which makes cd-ing there and running init a natural
+    // mistake rather than a contrived one. The next refresh hard-resets the clone
+    // and silently discards whatever was installed, leaving hooks that point at
+    // files which no longer exist.
+    const mirror = lookupMirror(resolvedRepo);
+    if (mirror) {
+        throw new Error(`knodin init: ${resolvedRepo} is a read-only mirror of ${mirror.url}, not a checkout. Mirrors carry no lifecycle hooks by design — their graph is built by \`knodin remote add\`/\`refresh\` and stored outside the clone. Nothing to initialize here.`);
+    }
+    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, ".knodin", "hooks");
+    const hookInstallation = await prepareHookInstallation(resolvedRepo);
+    const hooksDir = hookInstallation.hooksDir;
+    await Promise.all([
+        fs.promises.mkdir(knodinHooksDir, { recursive: true }),
+        fs.promises.mkdir(hooksDir, { recursive: true }),
+    ]);
+    const backgroundPath = path.join(knodinHooksDir, "background-index.sh");
+    await fs.promises.writeFile(backgroundPath, backgroundScript(options.command), {
+        encoding: "utf-8",
+        mode: 0o755,
+    });
+    await fs.promises.chmod(backgroundPath, 0o755);
+    const hookManagerIntegration = installHookManagerIntegration(resolvedRepo);
+    for (const hookName of HOOK_NAMES) {
+        let preservedOriginal;
+        if (hookInstallation.trackedHooksDir) {
+            const relativeHook = `${hookInstallation.trackedHooksDir}/${hookName}`;
+            const sourceHook = path.join(resolvedRepo, relativeHook);
+            try {
+                const stat = await fs.promises.stat(sourceHook);
+                preservedOriginal =
+                    stat.isFile() && (stat.mode & 0o111) !== 0 ? `repo:${relativeHook}` : null;
+            }
+            catch {
+                preservedOriginal = null;
+            }
+        }
+        await installManagedHook(hooksDir, hookName, preservedOriginal);
+    }
+    for (const entry of await fs.promises.readdir(hooksDir, {
+        withFileTypes: true,
+    })) {
+        if (entry.isFile())
+            await preventLefthookAutoInstall(path.join(hooksDir, entry.name));
+    }
+    const indexResult = await options.index(resolvedRepo, {
+        onProgress: options.onProgress,
+    });
+    if (isIndexResult(indexResult) && indexResult.verification.status !== "healthy") {
+        throw new InitializationHealthError(indexResult);
+    }
+    const lifecycleRefresh = drainQueuedLifecycleEvents(resolvedRepo, backgroundPath);
+    await fs.promises.rm(path.join(knodinHooksDir, HOOK_FAILURE_FILE), { force: true });
+    let agentInstructionChanges = [];
+    if (scope === "team") {
+        const installed = await Promise.all([
+            installManagedAgentInstructions(resolvedRepo, "AGENTS.md"),
+            installManagedAgentInstructions(resolvedRepo, "GEMINI.md"),
+        ]);
+        agentInstructionChanges = installed.filter((change) => change !== null);
+    }
+    else {
+        agentInstructionChanges = await removeManagedPersonalArtifacts(resolvedRepo, options.allowTrackedTransition);
+    }
+    const requestedAgents = options.agents ?? [];
+    const projectPathByAgent = {
+        codex: ".codex/config.toml",
+        gemini: ".gemini/settings.json",
+        copilot: ".vscode/mcp.json",
+        antigravity: ".agents/mcp_config.json",
+    };
+    const blockedAgents = [];
+    const externalConfigurationOutcomes = [];
+    if (scope === "personal" &&
+        options.allowTrackedTransition &&
+        priorIntegration?.scope === "team") {
+        const cleanup = configureProjectAgents({
+            repo: resolvedRepo,
+            scope: "cli-only",
+            agents: ["claude", "codex", "gemini", "copilot", "antigravity"],
+            run: options.runAgentCommand,
+        });
+        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
+        : requestedAgents.filter((agent) => {
+            const projectPath = agent === "claude" ? ".mcp.json" : projectPathByAgent[agent];
+            if (!projectPath ||
+                !isTracked(resolvedRepo, projectPath) ||
+                (scope === "cli-only" && options.allowTrackedTransition))
+                return true;
+            if (options.allowTrackedTransition && priorIntegration?.scope === "team")
+                return false;
+            blockedAgents.push({
+                agent,
+                message: `${projectPath} is tracked; personal mode left it unchanged and did not exclude it`,
+            });
+            return false;
+        });
+    const agentIntegration = configureProjectAgents({
+        repo: resolvedRepo,
+        scope,
+        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,
+        agents: agentIntegration.configured,
+    });
+    if (scope === "team") {
+        await ensureTeamGitIgnore(resolvedRepo);
+        await removeManagedExcludes(resolvedRepo);
+    }
+    else if (scope === "cli-only") {
+        await removeManagedExcludes(resolvedRepo);
+    }
+    let excluded = scope === "team"
+        ? []
+        : await excludeUntrackedPaths(resolvedRepo, [
+            ...(isTracked(resolvedRepo, ".knodin") ? [] : [".knodin/"]),
+            ...agentIntegration.projectFiles,
+        ]);
+    if (hookManagerIntegration) {
+        const managerExcludes = await excludeUntrackedPaths(resolvedRepo, [
+            hookManagerIntegration.localConfig,
+        ]);
+        excluded = [...new Set([...excluded, ...managerExcludes])].sort(compareBytes);
+    }
+    registerInitializedWorktree(resolvedRepo);
+    const detectedFilesystemChanges = filesystemChanges(beforeMutation, mutationSnapshot(mutationTargets, true));
+    return {
+        scope,
+        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) {
+    try {
+        const [content, stat] = await Promise.all([
+            fs.promises.readFile(filePath, "utf-8"),
+            fs.promises.stat(filePath),
+        ]);
+        return stat.isFile() && content === expected && (!executable || (stat.mode & 0o111) !== 0);
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Read-only installation probe used by repository bootstrap. Existing user hooks may
+ * be referenced through knodin's wrapper, so hook currency is established by a
+ * single managed marker while generated files are compared byte-for-byte.
+ */
+export async function isRepositoryInitializationCurrent(repo, command, scope = "personal") {
+    const resolvedRepo = path.resolve(repo);
+    if (!path.isAbsolute(command[0]))
+        return false;
+    let hooksDir;
+    try {
+        if (runGit(resolvedRepo, ["rev-parse", "--is-inside-work-tree"]).trim() !== "true")
+            return false;
+        hooksDir = effectiveHooksDirectory(resolvedRepo);
+    }
+    catch {
+        return false;
+    }
+    const lefthook = inspectLefthookIntegration(resolvedRepo);
+    const managedHooks = await Promise.all(HOOK_NAMES.map(async (hookName) => {
+        const hookPath = path.join(hooksDir, hookName);
+        try {
+            const [content, stat] = await Promise.all([
+                fs.promises.readFile(hookPath, "utf-8"),
+                fs.promises.stat(hookPath),
+            ]);
+            const originalPath = content.match(/^# knodin original: (.+)$/m)?.[1] ?? null;
+            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 || (lefthook.configured && isActiveLefthookHook(content))));
+        }
+        catch {
+            return false;
+        }
+    }));
+    if (managedHooks.some((current) => !current))
+        return false;
+    const sharedFilesCurrent = scope !== "team" ||
+        ((await hasManagedAgentInstructions(resolvedRepo, "AGENTS.md")) &&
+            (await hasManagedAgentInstructions(resolvedRepo, "GEMINI.md")));
+    const integrationCurrent = readRepositoryIntegrationConfig(resolvedRepo)?.scope === scope;
+    return ((await matchesManagedFile(path.join(resolvedRepo, ".knodin", "hooks", "background-index.sh"), backgroundScript(command), true)) &&
+        sharedFilesCurrent &&
+        integrationCurrent &&
+        (lefthook.localConfig === null || lefthook.configured));
+}