knodin 0.8.7 → 0.9.0

package/dist/src/init.js

@@ -7,6 +7,7 @@ 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 { acquireRepairLease } from "./repair-lease.js";
 import { installKnodinSkills, removeKnodinSkills } from "./skill-management.js";
 import { registerInitializedWorktree } from "./worktree-lifecycle.js";
 const MANAGED_MARKER = "KNODIN MANAGED HOOK";
@@ -153,7 +154,10 @@ function configureMutationAuditTargets(repo) {
             });
     }
     for (const hookName of HOOK_NAMES) {
-        add({ absolute: path.join(effectiveHooks, hookName), label: `${effectiveLabel}/${hookName}` });
+        add({
+            absolute: path.join(effectiveHooks, hookName),
+            label: `${effectiveLabel}/${hookName}`,
+        });
         add({
             absolute: path.join(effectiveHooks, `${hookName}.knodin-original`),
             label: `${effectiveLabel}/${hookName}.knodin-original`,
@@ -385,11 +389,11 @@ while :; do
   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
+    ${invocation} --repo "$REPO_ROOT" hook-refresh commit --json >> "$LOG_PATH" 2>> "$LOG_PATH.stderr"
   elif [ "$KIND" = "checkout" ] || [ "$KIND" = "merge" ]; then
-    ${invocation} --repo "$REPO_ROOT" hook-refresh "$KIND" "$ARG1" "$ARG2" --json >> "$LOG_PATH" 2>&1
+    ${invocation} --repo "$REPO_ROOT" hook-refresh "$KIND" "$ARG1" "$ARG2" --json >> "$LOG_PATH" 2>> "$LOG_PATH.stderr"
   elif [ "$KIND" = "rewrite" ]; then
-    ${invocation} --repo "$REPO_ROOT" hook-refresh rewrite "$ARG1" --json >> "$LOG_PATH" 2>&1
+    ${invocation} --repo "$REPO_ROOT" hook-refresh rewrite "$ARG1" --json >> "$LOG_PATH" 2>> "$LOG_PATH.stderr"
   else
     printf 'knodin background refresh: invalid queued event %s\n' "$KIND" >> "$LOG_PATH"
     false
@@ -701,6 +705,7 @@ This repository is indexed locally by knodin. Start with \`knodin status\`; if i
 - 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.
+- When indexing is active, run \`knodin wait --fresh\` and recheck status before falling back to direct traversal.
 - Keep output truthful: local graph evidence can be stale or ambiguous; say so and repair/reindex instead of claiming certainty.
 
 <!-- knodin:end -->
@@ -960,9 +965,17 @@ 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: "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: "antigravity",
+            path: ".agents/mcp_config.json",
+            marker: '"knodin"',
+        },
         {
             agent: "codex",
             path: "AGENTS.md",
@@ -1047,6 +1060,7 @@ export function detectTrackedTeamIntegration(repo) {
 export async function initializeRepository(repo, options) {
     const resolvedRepo = path.resolve(repo);
     const scope = options.scope ?? "personal";
+    const configureIntegration = options.configureIntegration ?? true;
     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}`);
@@ -1065,188 +1079,217 @@ export async function initializeRepository(repo, options) {
     if (!path.isAbsolute(options.command[0])) {
         throw new Error("knodin init: packaged runtime command must be an absolute path");
     }
-    const mutationTargets = options.auditConfigurationChanges
-        ? configureMutationAuditTargets(resolvedRepo)
-        : [];
-    const beforeMutation = mutationSnapshot(mutationTargets);
-    if (scope !== "team" &&
-        !options.allowTrackedTransition &&
-        detectTrackedTeamIntegration(resolvedRepo)) {
-        throw new Error("knodin init: tracked team integration is active; use `knodin configure --scope personal` or `--scope cli-only` for an explicit commit-ready transition");
-    }
-    const knodinHooksDir = path.join(resolvedRepo, ".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;
-            }
+    const lifecycleLease = acquireRepairLease(resolvedRepo, options.configureIntegration ? "configure" : "init");
+    try {
+        const mutationTargets = options.auditConfigurationChanges
+            ? configureMutationAuditTargets(resolvedRepo)
+            : [];
+        const beforeMutation = mutationSnapshot(mutationTargets);
+        if (configureIntegration &&
+            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");
         }
-        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"),
+        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 }),
         ]);
-        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,
+        const backgroundPath = path.join(knodinHooksDir, "background-index.sh");
+        await fs.promises.writeFile(backgroundPath, backgroundScript(options.command), {
+            encoding: "utf-8",
+            mode: 0o755,
         });
-        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",
+        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));
+        }
+        let agentInstructionChanges = [];
+        let agentIntegration = {
+            configured: [],
+            removed: [],
+            failed: [],
+            projectFiles: [],
+        };
+        const externalConfigurationOutcomes = [];
+        let excluded = [];
+        if (configureIntegration && scope === "team") {
+            const installed = await Promise.all([
+                installManagedAgentInstructions(resolvedRepo, "AGENTS.md"),
+                installManagedAgentInstructions(resolvedRepo, "GEMINI.md"),
+            ]);
+            agentInstructionChanges = installed.filter((change) => change !== null);
+        }
+        else if (configureIntegration) {
+            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 = [];
+        if (configureIntegration) {
+            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;
+                });
+            agentIntegration = configureProjectAgents({
+                repo: resolvedRepo,
+                scope,
+                agents: eligibleAgents,
+                run: options.runAgentCommand,
             });
-    }
-    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`,
+            const skillClients = (scope === "team"
+                ? ["codex", "claude", "gemini"]
+                : agentIntegration.configured.filter((agent) => ["codex", "claude", "gemini"].includes(agent)));
+            const skillIntegration = scope === "cli-only"
+                ? removeKnodinSkills({
+                    repo: resolvedRepo,
+                    scope: "team",
+                    clients: ["codex", "claude", "gemini"],
+                })
+                : installKnodinSkills({
+                    repo: resolvedRepo,
+                    scope,
+                    clients: skillClients,
+                });
+            for (const issue of skillIntegration.issues)
+                agentIntegration.failed.push({
+                    agent: skillClients.find((client) => issue.path.includes(`.${client}`)) ?? "codex",
+                    message: `${issue.path}: ${issue.message}`,
+                });
+            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,
             });
-            return false;
-        });
-    const agentIntegration = configureProjectAgents({
-        repo: resolvedRepo,
-        scope,
-        agents: eligibleAgents,
-        run: options.runAgentCommand,
-    });
-    const skillClients = (scope === "team"
-        ? ["codex", "claude", "gemini"]
-        : agentIntegration.configured.filter((agent) => ["codex", "claude", "gemini"].includes(agent)));
-    const skillIntegration = scope === "cli-only"
-        ? removeKnodinSkills({
-            repo: resolvedRepo,
-            scope: "team",
-            clients: ["codex", "claude", "gemini"],
-        })
-        : installKnodinSkills({ repo: resolvedRepo, scope, clients: skillClients });
-    for (const issue of skillIntegration.issues)
-        agentIntegration.failed.push({
-            agent: skillClients.find((client) => issue.path.includes(`.${client}`)) ?? "codex",
-            message: `${issue.path}: ${issue.message}`,
-        });
-    if (scope === "personal" && agentIntegration.configured.includes("claude"))
-        externalConfigurationOutcomes.push({
-            system: "claude-local-mcp",
-            state: "configured-or-present",
+            if (scope === "team") {
+                await ensureTeamGitIgnore(resolvedRepo);
+                await removeManagedExcludes(resolvedRepo);
+            }
+            else if (scope === "cli-only") {
+                await removeManagedExcludes(resolvedRepo);
+            }
+            excluded =
+                scope === "team"
+                    ? []
+                    : await excludeUntrackedPaths(resolvedRepo, [
+                        ...(isTracked(resolvedRepo, ".knodin") ? [] : [".knodin/"]),
+                        ...agentIntegration.projectFiles,
+                    ]);
+        }
+        if (!configureIntegration && !isTracked(resolvedRepo, ".knodin")) {
+            excluded = await excludeUntrackedPaths(resolvedRepo, [".knodin/"]);
+        }
+        if (hookManagerIntegration) {
+            const managerExcludes = await excludeUntrackedPaths(resolvedRepo, [
+                hookManagerIntegration.localConfig,
+            ]);
+            excluded = [...new Set([...excluded, ...managerExcludes])].sort(compareBytes);
+        }
+        registerInitializedWorktree(resolvedRepo);
+        // Configuration is graph-visible, so explicit configuration must complete
+        // before the final index and health verification. Plain init reaches this
+        // point without touching agent instructions, MCP files, skills, or receipts.
+        const indexResult = await options.index(resolvedRepo, {
+            onProgress: options.onProgress,
         });
-    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",
+        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,
         });
-    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 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,
+        };
     }
-    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);
+    finally {
+        lifecycleLease.release();
     }
-    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 {