knodin 0.5.0

package/dist/src/init.js

@@ -0,0 +1,985 @@
+import child_process from "node:child_process";
+import fs from "node:fs";
+import path from "node:path";
+import { configureProjectAgents, } from "./agent-integration.js";
+import { isIndexableSourcePath } from "./engine/source-policy.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";
+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"],
+    });
+}
+function shellQuote(value) {
+    return `'${value.replaceAll("'", `'\\''`)}'`;
+}
+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, ".reckon", "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");
+            }
+            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 .reckon/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();
+        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 `#!/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/.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}"
+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/.reckon/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 .reckon/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, ".reckon", "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, ".reckon", "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 .reckon/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) {
+    const original = originalPath
+        ? originalPath.startsWith("repo:")
+            ? `"$REPO_ROOT"/${shellQuote(originalPath.slice("repo:".length))}`
+            : shellQuote(originalPath)
+        : "";
+    const runOriginal = originalPath
+        ? `${original} "$@"${hookName === "post-rewrite" ? ' < "$REWRITE_INPUT"' : ""} || 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
+        ? `${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
+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/.reckon/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/.reckon/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 [ "\${RECKON_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`) ||
+            content.startsWith(`#!/bin/sh\n# ${LEGACY_MANAGED_MARKER}: ${hookName}\n`)) {
+            const match = content.match(/^# knodin original: (.+)$/m);
+            originalPath = match?.[1] ?? null;
+        }
+        else {
+            const backupPath = `${hookPath}.reckon-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) ||
+                    candidateContent.includes(LEGACY_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";
+const LEGACY_ORIGINAL_HOOKS_CONFIG = "reckon.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", LEGACY_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 = `#!/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 RECKON_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.
+
+- 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 = "";
+    try {
+        existing = await fs.promises.readFile(instructionsPath, "utf-8");
+    }
+    catch (error) {
+        if (error.code !== "ENOENT")
+            throw error;
+    }
+    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 next = start >= 0 && end >= start
+        ? `${existing.slice(0, start)}${RECKON_AGENT_INSTRUCTIONS}${existing.slice(end + endMarker.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");
+}
+async function hasManagedAgentInstructions(repo, fileName = "AGENTS.md") {
+    try {
+        return (await fs.promises.readFile(path.join(repo, fileName), "utf-8")).includes(RECKON_AGENT_INSTRUCTIONS);
+    }
+    catch {
+        return false;
+    }
+}
+function isTracked(repo, relativePath) {
+    try {
+        return nulPaths(repo, ["ls-files", "--", relativePath]).length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+async function excludeUntrackedPaths(repo, candidates) {
+    const safe = [...new Set(candidates)].filter((candidate) => !isTracked(repo, candidate)).sort();
+    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 = 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 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 = existing.replace(/(?:^|\n)# knodin:start\n[\s\S]*?\n# knodin:end\n?/, "\n");
+    await fs.promises.writeFile(excludePath, next, "utf-8");
+}
+async function removeManagedPersonalArtifacts(repo, allowTrackedTransition = false) {
+    for (const fileName of ["AGENTS.md", "GEMINI.md"]) {
+        const instructionsPath = path.join(repo, fileName);
+        const tracked = isTracked(repo, fileName);
+        try {
+            const current = await fs.promises.readFile(instructionsPath, "utf-8");
+            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
+                        await fs.promises.rm(instructionsPath, { force: true });
+                }
+                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 });
+                continue;
+            }
+            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\.reckon\/\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.
+        }
+    }
+}
+export function readRepositoryIntegrationConfig(repo) {
+    try {
+        const value = JSON.parse(fs.readFileSync(path.join(repo, ".reckon", "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;
+}
+/** 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"' },
+    ];
+    const configurations = candidates.map(({ agent, path: relative, marker }) => {
+        try {
+            return {
+                agent,
+                path: relative,
+                present: 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, ".reckon", "integration.json"), `${JSON.stringify(config, null, 2)}\n`, "utf-8");
+}
+async function ensureTeamGitIgnore(repo) {
+    if (isTracked(repo, ".reckon"))
+        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(".reckon/"))
+        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");
+}
+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}`);
+    }
+    if (!path.isAbsolute(options.command[0])) {
+        throw new Error("knodin init: packaged runtime command must be an absolute path");
+    }
+    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 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);
+    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 });
+    if (scope === "team") {
+        await installManagedAgentInstructions(resolvedRepo, "AGENTS.md");
+        await installManagedAgentInstructions(resolvedRepo, "GEMINI.md");
+    }
+    else {
+        await removeManagedPersonalArtifacts(resolvedRepo, options.allowTrackedTransition);
+    }
+    const requestedAgents = options.agents ?? [];
+    const projectPathByAgent = {
+        codex: ".codex/config.toml",
+        gemini: ".gemini/settings.json",
+        antigravity: ".agents/mcp_config.json",
+    };
+    const blockedAgents = [];
+    if (scope === "personal" &&
+        options.allowTrackedTransition &&
+        priorIntegration?.scope === "team") {
+        const cleanup = configureProjectAgents({
+            repo: resolvedRepo,
+            scope: "cli-only",
+            agents: ["claude", "codex", "gemini", "antigravity"],
+            run: options.runAgentCommand,
+        });
+        if (cleanup.failed.length > 0)
+            throw new Error(`knodin configure: could not remove tracked team integration: ${cleanup.failed[0]?.message}`);
+    }
+    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,
+    });
+    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);
+    }
+    const excluded = scope === "team"
+        ? []
+        : await excludeUntrackedPaths(resolvedRepo, [
+            ...(isTracked(resolvedRepo, ".reckon") ? [] : [".reckon/"]),
+            ...agentIntegration.projectFiles,
+        ]);
+    registerInitializedWorktree(resolvedRepo);
+    return {
+        scope,
+        knodin: ".reckon",
+        database: ".reckon/db.sqlite",
+        backgroundIndexer: ".reckon/hooks/background-index.sh",
+        hooksDirectory: path.relative(resolvedRepo, hooksDir) || ".",
+        gitHooks: [...HOOK_NAMES],
+        claudeSettings: null,
+        agentInstructions: scope === "team" ? "AGENTS.md" : null,
+        agentIntegration,
+        excluded,
+        lifecycleRefresh,
+    };
+}
+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 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;
+        }
+        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, ".reckon", "hooks", "background-index.sh"), backgroundScript(command), true)) &&
+        sharedFilesCurrent &&
+        integrationCurrent);
+}