kibi-mcp 0.6.0 → 0.7.0

package/dist/diagnostics.js

@@ -33,19 +33,24 @@ let diagnosticUsageLogPath = null;
  * Initialize diagnostic mode: set up usage.log path.
  * Called once during server startup.
  */
-export function initializeDiagnosticMode() {
-    if (DIAGNOSTIC_MODE_ENABLED) {
-        const workspaceRoot = resolveWorkspaceRoot();
-        diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
-        process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
+// implements REQ-008
+export function initializeDiagnosticMode(enabled = DIAGNOSTIC_MODE_ENABLED) {
+    diagnosticUsageLogPath = null;
+    if (!enabled) {
+        Reflect.deleteProperty(process.env, "KIBI_MCP_DIAGNOSTIC_MODE");
+        return;
     }
+    const workspaceRoot = resolveWorkspaceRoot();
+    diagnosticUsageLogPath = path.join(workspaceRoot, ".kb", "usage.log");
+    process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
 }
 /**
  * Append a JSON line to the usage.log file.
  * No-op if diagnostic mode is not enabled.
  */
+// implements REQ-008
 export function appendUsageLogLine(entry) {
-    if (!DIAGNOSTIC_MODE_ENABLED || !diagnosticUsageLogPath) {
+    if (!diagnosticUsageLogPath) {
         return;
     }
     const logDir = path.dirname(diagnosticUsageLogPath);

package/dist/env.js

@@ -18,8 +18,38 @@
 import fs from "node:fs";
 import { resolveEnvFilePath, resolveWorkspaceRoot } from "./workspace.js";
 const DEFAULT_ENV_FILE = ".env";
+function getEnvValue(key) {
+    const value = process.env[key];
+    return typeof value === "string" ? value : undefined;
+}
+function getTrimmedEnvValue(key) {
+    const value = getEnvValue(key)?.trim();
+    return value ? value : undefined;
+}
+export function getEnvFileName() {
+    // implements REQ-002
+    return getTrimmedEnvValue("KIBI_ENV_FILE") ?? DEFAULT_ENV_FILE;
+}
+export function isMcpDebugEnabled() {
+    // implements REQ-002
+    return Boolean(getEnvValue("KIBI_MCP_DEBUG"));
+}
+export function getBranchOverride() {
+    // implements REQ-002
+    return getTrimmedEnvValue("KIBI_BRANCH");
+}
+export function getKbPlPathOverride() {
+    // implements REQ-002
+    return getEnvValue("KIBI_KB_PL_PATH");
+}
+export function getCoreModulePathOverride(fileName) {
+    // implements REQ-002
+    const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
+    return getEnvValue(envKey);
+}
 export function loadDefaultEnvFile() {
-    const envFileName = process.env.KIBI_ENV_FILE ?? DEFAULT_ENV_FILE;
+    // implements REQ-002
+    const envFileName = getEnvFileName();
     const workspaceRoot = resolveWorkspaceRoot();
     return loadEnvFile({ envFileName, workspaceRoot });
 }

package/dist/server/docs.js

@@ -16,6 +16,9 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import { TOOLS } from "../tools-config.js";
+// INTENTIONAL: TOOLS is imported as a Zod-inferred schema type; ToolConfig is the runtime
+// interface with looser Record<string, unknown> inputSchema. The cast is safe because the
+// tool definitions are statically authored and validated at startup.
 const ACTIVE_TOOLS = TOOLS;
 function renderToolsDoc() {
     const lines = [

package/dist/server/session.js

@@ -20,7 +20,20 @@ import { createRequire } from "node:module";
 import process from "node:process";
 import { PrologProcess } from "kibi-cli/prolog";
 import { copyCleanSnapshot, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, } from "kibi-cli/public/branch-resolver";
+import { getBranchOverride, isMcpDebugEnabled } from "../env.js";
 import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
+const defaultSessionDeps = {
+    PrologProcess,
+    copyCleanSnapshot,
+    createRequire,
+    fs,
+    getBranchDiagnostic,
+    isValidBranchName,
+    resolveActiveBranch,
+    resolveKbPath,
+    resolveWorkspaceRoot,
+};
+let sessionDeps = { ...defaultSessionDeps };
 export let prologProcess = null;
 let isInitialized = false;
 export let activeBranchName = "develop";
@@ -28,32 +41,55 @@ let ensurePrologTail = Promise.resolve();
 export let isShuttingDown = false;
 let shutdownTimeout = null;
 export const inFlightRequests = new Map();
+// implements REQ-008
+export function resetSessionStateForTests() {
+    prologProcess = null;
+    isInitialized = false;
+    activeBranchName = "develop";
+    ensurePrologTail = Promise.resolve();
+    isShuttingDown = false;
+    inFlightRequests.clear();
+    if (shutdownTimeout) {
+        clearTimeout(shutdownTimeout);
+        shutdownTimeout = null;
+    }
+}
+export function _setSessionDepsForTests(
+// implements REQ-008
+overrides) {
+    sessionDeps = { ...sessionDeps, ...overrides };
+}
+export function _resetSessionDepsForTests() {
+    // implements REQ-008
+    sessionDeps = { ...defaultSessionDeps };
+}
 function debugLog(...args) {
-    if (process.env.KIBI_MCP_DEBUG) {
+    if (isMcpDebugEnabled()) {
         console.error(...args);
     }
 }
 export function ensureBranchKbExists(workspaceRoot, branch) {
-    if (!isValidBranchName(branch)) {
+    // implements REQ-008
+    if (!sessionDeps.isValidBranchName(branch)) {
         throw new Error(`Invalid branch name: ${branch}`);
     }
-    const branchPath = resolveKbPath(workspaceRoot, branch);
-    if (fs.existsSync(branchPath)) {
+    const branchPath = sessionDeps.resolveKbPath(workspaceRoot, branch);
+    if (sessionDeps.fs.existsSync(branchPath)) {
         return;
     }
     // Try to copy from the previously active branch if available
     const previousBranch = activeBranchName;
-    const previousBranchPath = resolveKbPath(workspaceRoot, previousBranch);
+    const previousBranchPath = sessionDeps.resolveKbPath(workspaceRoot, previousBranch);
     if (previousBranch !== branch &&
         previousBranch !== "develop" &&
-        fs.existsSync(previousBranchPath)) {
+        sessionDeps.fs.existsSync(previousBranchPath)) {
         // Copy from previous branch for continuity
-        copyCleanSnapshot(previousBranchPath, branchPath);
+        sessionDeps.copyCleanSnapshot(previousBranchPath, branchPath);
         debugLog(`[KIBI-MCP] Created branch KB for '${branch}' from '${previousBranch}'`);
         return;
     }
     // No previous branch available - create empty KB
-    fs.mkdirSync(branchPath, { recursive: true });
+    sessionDeps.fs.mkdirSync(branchPath, { recursive: true });
     debugLog(`[KIBI-MCP] Created empty branch KB for '${branch}'`);
 }
 export async function initiateGracefulShutdown(exitCode = 0) {
@@ -103,22 +139,22 @@ export async function initiateGracefulShutdown(exitCode = 0) {
 }
 // implements REQ-008
 async function ensurePrologUnsafe() {
-    const workspaceRoot = resolveWorkspaceRoot();
+    const workspaceRoot = sessionDeps.resolveWorkspaceRoot();
     // Determine target branch: respect KIBI_BRANCH override or resolve from git
-    const envBranch = process.env.KIBI_BRANCH?.trim();
+    const envBranch = getBranchOverride();
     let targetBranch;
     if (envBranch) {
         // KIBI_BRANCH override is set - use it without re-resolving from git
-        if (!isValidBranchName(envBranch)) {
+        if (!sessionDeps.isValidBranchName(envBranch)) {
             throw new Error(`Invalid branch name from KIBI_BRANCH: '${envBranch}'`);
         }
         targetBranch = envBranch;
     }
     else {
         // No override - resolve active branch from git (may change between requests)
-        const branchResult = resolveActiveBranch(workspaceRoot);
+        const branchResult = sessionDeps.resolveActiveBranch(workspaceRoot);
         if ("error" in branchResult) {
-            const diagnostic = getBranchDiagnostic(undefined, branchResult.error);
+            const diagnostic = sessionDeps.getBranchDiagnostic(undefined, branchResult.error);
             console.error(`[KIBI-MCP] ${diagnostic}`);
             throw new Error(`Failed to resolve active branch: ${branchResult.error}`);
         }
@@ -144,7 +180,7 @@ async function ensurePrologUnsafe() {
         }
         // Ensure new branch KB exists
         ensureBranchKbExists(workspaceRoot, targetBranch);
-        const newKbPath = resolveKbPath(workspaceRoot, targetBranch);
+        const newKbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
         // Attach to new branch KB
         const attachResult = await prologProcess.query(`kb_attach('${newKbPath}')`);
         if (!attachResult.success) {
@@ -157,13 +193,13 @@ async function ensurePrologUnsafe() {
     }
     // First initialization
     debugLog("[KIBI-MCP] Initializing Prolog process...");
-    prologProcess = new PrologProcess({ timeout: 120000 });
+    prologProcess = new sessionDeps.PrologProcess({ timeout: 120000 });
     await prologProcess.start();
     // Startup debug: resolve which kibi-cli is being used and its version (best-effort).
     // Gate all output under KIBI_MCP_DEBUG and write only to stderr via debugLog.
-    if (process.env.KIBI_MCP_DEBUG) {
+    if (isMcpDebugEnabled()) {
         try {
-            const req = createRequire(import.meta.url);
+            const req = sessionDeps.createRequire(import.meta.url);
             try {
                 const resolved = req.resolve("kibi-cli/prolog");
                 debugLog(`[KIBI-MCP] require.resolve('kibi-cli/prolog') -> ${resolved}`);
@@ -193,11 +229,11 @@ async function ensurePrologUnsafe() {
         }
     }
     debugLog("[KIBI-MCP] Branch selection:");
-    debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${process.env.KIBI_BRANCH || "not set"}`);
+    debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${envBranch || "not set"}`);
     debugLog(`[KIBI-MCP]   Resolved branch: ${targetBranch}`);
     activeBranchName = targetBranch;
     ensureBranchKbExists(workspaceRoot, targetBranch);
-    const kbPath = resolveKbPath(workspaceRoot, targetBranch);
+    const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
     const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
     if (!attachResult.success) {
         throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);

package/dist/server/tools.js

@@ -1,23 +1,6 @@
-/*
- Kibi — repo-local, per-branch, queryable long-term memory for software projects
- Copyright (C) 2026 Piotr Franczyk
-
- This program is free software: you can redistribute it and/or modify
- it under the terms of the GNU Affero General Public License as published by
- the Free Software Foundation, either version 3 of the License, or
- (at your option) any later version.
-
- This program is distributed in the hope that it will be useful,
- but WITHOUT ANY WARRANTY; without even the implied warranty of
- MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
- GNU Affero General Public License for more details.
-
- You should have received a copy of the GNU Affero General Public License
- along with this program.  If not, see <https://www.gnu.org/licenses/>.
- */
-import process from "node:process";
 import { z } from "zod";
 import { DIAGNOSTIC_MODE_ENABLED, appendUsageLogLine, deriveDiagnosticFields, extractToolCallPayload, } from "../diagnostics.js";
+import { isMcpDebugEnabled } from "../env.js";
 import { TOOLS } from "../tools-config.js";
 import { handleKbCheck } from "../tools/check.js";
 import { handleKbCoverage } from "../tools/coverage.js";
@@ -28,13 +11,60 @@ import { handleKbQuery } from "../tools/query.js";
 import { handleKbSearch } from "../tools/search.js";
 import { handleKbStatus } from "../tools/status.js";
 import { handleKbUpsert } from "../tools/upsert.js";
-import { activeBranchName, ensureProlog, inFlightRequests, isShuttingDown, prologProcess, } from "./session.js";
-const ACTIVE_TOOLS = TOOLS;
+const defaultToolsServerDeps = {
+    getSessionModule: () => import("./session.js"),
+};
+// implements REQ-008
+export function _setToolsServerDepsForTests(deps, resetPromise = false) {
+    defaultToolsServerDeps.getSessionModule =
+        deps.getSessionModule ?? defaultToolsServerDeps.getSessionModule;
+    if (resetPromise) {
+        sessionModulePromise = null;
+    }
+}
+// implements REQ-012
+export function _resetSessionModulePromise() {
+    sessionModulePromise = null;
+}
+let sessionModulePromise = null;
+/* v8 ignore next (3 lines) — lazy async module loader; body only executes once per process
+ * when DEFAULT_TOOLS_RUNTIME.activeBranchName/ensureProlog/etc. are first called.
+ * Cannot be re-triggered without process restart (sessionModulePromise is module-level). */
+async function getSessionModule() {
+    sessionModulePromise ??= defaultToolsServerDeps.getSessionModule();
+    return sessionModulePromise;
+}
+const DEFAULT_TOOLS_RUNTIME = {
+    diagnosticModeEnabled: () => DIAGNOSTIC_MODE_ENABLED,
+    appendUsageLogLine,
+    deriveDiagnosticFields,
+    extractToolCallPayload,
+    // INTENTIONAL: TOOLS is imported as a Zod-inferred schema type; ToolConfig is the
+    // runtime interface with looser Record<string, unknown> inputSchema. The cast is safe
+    // because the tool definitions are statically authored and validated at startup.
+    tools: TOOLS,
+    activeBranchName: async () => (await getSessionModule()).activeBranchName,
+    ensureProlog: async () => (await getSessionModule()).ensureProlog(),
+    inFlightRequests: async () => (await getSessionModule()).inFlightRequests,
+    isShuttingDown: async () => (await getSessionModule()).isShuttingDown,
+    prologProcess: async () => (await getSessionModule()).prologProcess,
+    handleKbCheck,
+    handleKbCoverage,
+    handleKbDelete,
+    handleKbFindGaps,
+    handleKbGraph,
+    handleKbQuery,
+    handleKbSearch,
+    handleKbStatus,
+    handleKbUpsert,
+};
+// implements REQ-008
 function debugLog(...args) {
-    if (process.env.KIBI_MCP_DEBUG) {
+    if (isMcpDebugEnabled()) {
         console.error(...args);
     }
 }
+// implements REQ-002
 export function jsonSchemaToZod(schema) {
     if (!schema || typeof schema !== "object") {
         return z.any();
@@ -52,6 +82,9 @@ export function jsonSchemaToZod(schema) {
         const literalSchemas = literals.map((value) => z.literal(value));
         if (literalSchemas.length === 1) {
             const single = literalSchemas[0];
+            if (!single) {
+                return description ? z.any().describe(description) : z.any();
+            }
             return description ? single.describe(description) : single;
         }
         const union = z.union(literalSchemas);
@@ -71,10 +104,9 @@ export function jsonSchemaToZod(schema) {
                 const propSchema = jsonSchemaToZod(value);
                 shape[key] = required.has(key) ? propSchema : propSchema.optional();
             }
-            let objectSchema = z.object(shape);
-            if (obj.additionalProperties !== false) {
-                objectSchema = objectSchema.passthrough();
-            }
+            const objectSchema = obj.additionalProperties === false
+                ? z.object(shape)
+                : z.looseObject(shape);
             const description = typeof obj.description === "string" ? obj.description : undefined;
             return description ? objectSchema.describe(description) : objectSchema;
         }
@@ -135,12 +167,17 @@ export function jsonSchemaToZod(schema) {
         }
     }
 }
-function addTool(server, name, description, inputSchema, handler) {
+// implements REQ-002
+export function addTool(server, name, description, inputSchema, handler, 
+// INTENTIONAL: DEFAULT_TOOLS_RUNTIME is typed as ToolsRuntime<PrologProcess>; the
+// generic TProlog parameter exists so tests can inject a mock type. The cast is safe
+// because the runtime object satisfies the full ToolsRuntime contract at runtime.
+runtime = DEFAULT_TOOLS_RUNTIME) {
     const wrappedHandler = async (args) => {
         const startedAt = new Date();
-        // Extract telemetry in diagnostic mode
-        const { businessArgs, telemetry } = DIAGNOSTIC_MODE_ENABLED
-            ? extractToolCallPayload(args)
+        const diagnosticModeEnabled = runtime.diagnosticModeEnabled();
+        const { businessArgs, telemetry } = diagnosticModeEnabled
+            ? runtime.extractToolCallPayload(args)
             : { businessArgs: args, telemetry: null };
         try {
             // Validate that args is a valid object
@@ -148,7 +185,7 @@ function addTool(server, name, description, inputSchema, handler) {
                 throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
             }
             // Check if shutting down before processing
-            if (isShuttingDown) {
+            if (await runtime.isShuttingDown()) {
                 throw new Error(`Tool ${name} rejected: server is shutting down`);
             }
             // Extract or generate requestId from args
@@ -157,20 +194,23 @@ function addTool(server, name, description, inputSchema, handler) {
                 ? requestIdArg
                 : `${name}-${Date.now()}-${Math.random().toString(36).slice(2, 11)}`;
             // Log tool call for debugging (to stderr to avoid breaking stdio protocol)
-            if (process.env.KIBI_MCP_DEBUG) {
+            if (isMcpDebugEnabled()) {
                 console.error(`[KIBI-MCP] Tool called: ${name} (requestId: ${requestId}) with args:`, JSON.stringify(businessArgs));
             }
             // Track the handler promise in inFlightRequests Map
+            const trackedRequests = await runtime.inFlightRequests();
             const handlerPromise = handler(businessArgs);
-            inFlightRequests.set(requestId, handlerPromise);
+            trackedRequests.set(requestId, handlerPromise);
             try {
                 // Execute handler
                 const result = await handlerPromise;
                 // Log usage in diagnostic mode
-                if (DIAGNOSTIC_MODE_ENABLED) {
+                if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
-                    const diagnosticFields = deriveDiagnosticFields(name, businessArgs, telemetry, result);
-                    appendUsageLogLine({
+                    const diagnosticFields = runtime.deriveDiagnosticFields(name, businessArgs, telemetry, result);
+                    const processHandle = await runtime.prologProcess();
+                    const branchName = await runtime.activeBranchName();
+                    runtime.appendUsageLogLine({
                         timestamp: finishedAt.toISOString(),
                         request_id: requestId,
                         tool: name,
@@ -180,8 +220,8 @@ function addTool(server, name, description, inputSchema, handler) {
                         started_at: startedAt.toISOString(),
                         finished_at: finishedAt.toISOString(),
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
-                        prolog_pid: prologProcess?.getPid() ?? null,
-                        active_branch: activeBranchName,
+                        prolog_pid: processHandle?.getPid() ?? null,
+                        active_branch: branchName,
                         ...diagnosticFields,
                     });
                 }
@@ -189,10 +229,12 @@ function addTool(server, name, description, inputSchema, handler) {
             }
             catch (error) {
                 // Log error in diagnostic mode
-                if (DIAGNOSTIC_MODE_ENABLED) {
+                if (diagnosticModeEnabled) {
                     const finishedAt = new Date();
                     const err = error instanceof Error ? error : new Error(String(error));
-                    appendUsageLogLine({
+                    const processHandle = await runtime.prologProcess();
+                    const branchName = await runtime.activeBranchName();
+                    runtime.appendUsageLogLine({
                         timestamp: finishedAt.toISOString(),
                         request_id: requestId,
                         tool: name,
@@ -202,8 +244,8 @@ function addTool(server, name, description, inputSchema, handler) {
                         started_at: startedAt.toISOString(),
                         finished_at: finishedAt.toISOString(),
                         duration_ms: finishedAt.getTime() - startedAt.getTime(),
-                        prolog_pid: prologProcess?.getPid() ?? null,
-                        active_branch: activeBranchName,
+                        prolog_pid: processHandle?.getPid() ?? null,
+                        active_branch: branchName,
                         error_message: err.message,
                     });
                 }
@@ -211,7 +253,7 @@ function addTool(server, name, description, inputSchema, handler) {
             }
             finally {
                 // Always clean up from Map when done (success or failure)
-                inFlightRequests.delete(requestId);
+                trackedRequests.delete(requestId);
             }
         }
         catch (error) {
@@ -226,47 +268,53 @@ function addTool(server, name, description, inputSchema, handler) {
     server.registerTool(name, { description, inputSchema: jsonSchemaToZod(inputSchema) }, wrappedHandler);
 }
 // implements REQ-002, REQ-013
-export function registerAllTools(server) {
+export function registerAllTools(server, 
+// INTENTIONAL: same generic bridge cast as addTool — see comment there.
+runtime = DEFAULT_TOOLS_RUNTIME) {
     const toolDef = (name) => {
-        const t = ACTIVE_TOOLS.find((t) => t.name === name);
+        const t = runtime.tools.find((tool) => tool.name === name);
         if (!t)
             throw new Error(`Unknown tool: ${name}`);
         return t;
     };
+    // INTENTIONAL ARGUMENT CASTS: The `args as (unknown as)? XyzArgs` casts below
+    // bridge the generic ToolHandler (which receives Record<string, unknown>) to the
+    // specific handler argument types. Argument shapes are validated by Zod schemas
+    // (via jsonSchemaToZod) before the handler is invoked, so the casts are safe at runtime.
     addTool(server, "kb_query", toolDef("kb_query").description, toolDef("kb_query").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbQuery(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbQuery(prolog, args);
+    }, runtime);
     addTool(server, "kb_search", toolDef("kb_search").description, toolDef("kb_search").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbSearch(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbSearch(prolog, args);
+    }, runtime);
     addTool(server, "kb_status", toolDef("kb_status").description, toolDef("kb_status").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbStatus(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbStatus(prolog, args);
+    }, runtime);
     addTool(server, "kb_find_gaps", toolDef("kb_find_gaps").description, toolDef("kb_find_gaps").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbFindGaps(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbFindGaps(prolog, args);
+    }, runtime);
     addTool(server, "kb_coverage", toolDef("kb_coverage").description, toolDef("kb_coverage").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbCoverage(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbCoverage(prolog, args);
+    }, runtime);
     addTool(server, "kb_graph", toolDef("kb_graph").description, toolDef("kb_graph").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbGraph(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbGraph(prolog, args);
+    }, runtime);
     addTool(server, "kb_upsert", toolDef("kb_upsert").description, toolDef("kb_upsert").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbUpsert(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbUpsert(prolog, args);
+    }, runtime);
     addTool(server, "kb_delete", toolDef("kb_delete").description, toolDef("kb_delete").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbDelete(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbDelete(prolog, args);
+    }, runtime);
     addTool(server, "kb_check", toolDef("kb_check").description, toolDef("kb_check").inputSchema, async (args) => {
-        const prolog = await ensureProlog();
-        return handleKbCheck(prolog, args);
-    });
+        const prolog = await runtime.ensureProlog();
+        return runtime.handleKbCheck(prolog, args);
+    }, runtime);
 }

package/dist/server/transport.js

@@ -16,9 +16,10 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import process from "node:process";
+import { isMcpDebugEnabled } from "../env.js";
 import { initiateGracefulShutdown } from "./session.js";
 function debugLog(...args) {
-    if (process.env.KIBI_MCP_DEBUG) {
+    if (isMcpDebugEnabled()) {
         console.error(...args);
     }
 }

package/dist/tools/check.js

@@ -15,7 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
-import { existsSync, readFileSync } from "node:fs";
+import { readFile } from "node:fs/promises";
 import * as path from "node:path";
 import { DEFAULT_CHECKS_CONFIG, RULE_NAMES, } from "kibi-cli/public/check-types";
 import { resolveWorkspaceRoot } from "../workspace.js";
@@ -25,8 +25,8 @@ function formatDiagnosticsForMcp(diagnostics) {
         category: d.category,
         severity: d.severity,
         message: d.message,
-        file: d.file,
-        suggestion: d.suggestion,
+        ...(d.file !== undefined ? { file: d.file } : {}),
+        ...(d.suggestion !== undefined ? { suggestion: d.suggestion } : {}),
     }));
 }
 function formatViolationText(violations) {
@@ -48,13 +48,10 @@ function formatViolationText(violations) {
     return `${violations.length} violations found\n${details.join("\n")}`;
 }
 // implements REQ-002
-function loadChecksConfig(workspaceRoot) {
+async function loadChecksConfig(workspaceRoot) {
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
-    if (!existsSync(configPath)) {
-        return DEFAULT_CHECKS_CONFIG;
-    }
     try {
-        const content = readFileSync(configPath, "utf8");
+        const content = await readFile(configPath, "utf8");
         const parsed = JSON.parse(content);
         const parsedRules = parsed.checks?.rules;
         const normalizedRules = {
@@ -104,10 +101,10 @@ function getEffectiveRules(configRules, requestedRules) {
  */
 // implements REQ-002
 export async function handleKbCheck(prolog, args) {
-    const { rules } = args;
+    const { rules, workspaceRoot: workspaceOverride } = args;
     try {
-        const workspaceRoot = resolveWorkspaceRoot();
-        const checksConfig = loadChecksConfig(workspaceRoot);
+        const workspaceRoot = workspaceOverride ?? resolveWorkspaceRoot();
+        const checksConfig = await loadChecksConfig(workspaceRoot);
         const rulesAllowlist = getEffectiveRules(checksConfig.rules, rules);
         if (rulesAllowlist.size === 0) {
             return {
@@ -126,8 +123,8 @@ export async function handleKbCheck(prolog, args) {
             category: "SYNC_ERROR",
             severity: "error",
             message: v.description,
-            file: v.source,
-            suggestion: v.suggestion,
+            ...(v.source !== undefined ? { file: v.source } : {}),
+            ...(v.suggestion !== undefined ? { suggestion: v.suggestion } : {}),
         }));
         const summary = formatViolationText(aggregatedViolations);
         return {
@@ -189,8 +186,8 @@ async function runAggregatedChecks(prolog, rulesAllowlist, requireAdr) {
                     rule: v.rule,
                     entityId: v.entityId,
                     description: v.description,
-                    suggestion: v.suggestion || undefined,
-                    source: v.source || undefined,
+                    ...(v.suggestion ? { suggestion: v.suggestion } : {}),
+                    ...(v.source ? { source: v.source } : {}),
                 });
             }
         }

package/dist/tools/core-module.js

@@ -1,20 +1,21 @@
-import { existsSync } from "node:fs";
 import path from "node:path";
 import { PrologProcess, resolveKbPlPath } from "kibi-cli/prolog";
 import { escapeAtomContent } from "kibi-cli/prolog/codec";
+import { getCoreModulePathOverride, getKbPlPathOverride } from "../env.js";
 // implements REQ-002, REQ-013
 export function resolveCorePlPath(fileName) {
-    const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
-    const override = process.env[envKey];
-    if (override && existsSync(override)) {
+    const override = getCoreModulePathOverride(fileName);
+    if (override) {
         return override;
     }
-    const kbPlPath = resolveKbPlPath();
-    const sibling = path.join(path.dirname(kbPlPath), fileName);
-    if (existsSync(sibling)) {
-        return sibling;
+    // Fall back to the generic KB_PL override so test fixtures
+    // (which set only KIBI_KB_PL_PATH) can still resolve sibling modules.
+    const genericOverride = getKbPlPathOverride();
+    if (genericOverride) {
+        return path.join(path.dirname(genericOverride), fileName);
     }
-    throw new Error(`Root-consistency error: resolveKbPlPath() resolved to '${kbPlPath}' but sibling '${fileName}' not found at '${sibling}'`);
+    const kbPlPath = resolveKbPlPath();
+    return path.join(path.dirname(kbPlPath), fileName);
 }
 // implements REQ-002, REQ-013
 export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {
@@ -34,6 +35,11 @@ export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {
         }
         return mockedParsed;
     }
+    // NOTE: useOneShotMode is an internal optimization flag on PrologProcess that
+    // forces single-query mode (start → query → terminate per call) instead of the
+    // default interactive session. It is not exposed in the public PrologProcess type
+    // because callers should not set it directly — only internal discovery helpers
+    // use it for lightweight one-shot queries that don't need session state.
     const oneShotCapable = prolog;
     prolog.invalidateCache();
     const result = oneShotCapable.useOneShotMode

package/dist/tools/coverage.js

@@ -18,7 +18,7 @@ export async function handleKbCoverage(prolog, args) {
                     text: `Coverage summary: ${fullyCovered} fully covered out of ${total}.`,
                 },
             ],
-            structuredContent: payload,
+            ...(payload !== undefined ? { structuredContent: payload } : {}),
         };
     }
     catch (error) {

package/dist/tools/find-gaps.js

@@ -19,7 +19,7 @@ export async function handleKbFindGaps(prolog, args) {
                             .join(", ")}`,
                 },
             ],
-            structuredContent: payload,
+            ...(payload !== undefined ? { structuredContent: payload } : {}),
         };
     }
     catch (error) {

package/dist/tools/graph.js

@@ -17,7 +17,7 @@ export async function handleKbGraph(prolog, args) {
                         : `Graph traversal returned ${nodes.length} nodes and ${(payload?.edges ?? []).length} edges from ${args.seedIds.join(", ")}.`,
                 },
             ],
-            structuredContent: payload,
+            ...(payload !== undefined ? { structuredContent: payload } : {}),
         };
     }
     catch (error) {

package/dist/tools/prolog-list.js

@@ -37,7 +37,11 @@ export function parsePairList(raw) {
     for (const row of rows) {
         const parts = splitTopLevel(row, ",").map((part) => stripQuotes(part.trim()));
         if (parts.length >= 2) {
-            pairs.push([parts[0], parts[1]]);
+            const first = parts[0];
+            const second = parts[1];
+            if (first !== undefined && second !== undefined) {
+                pairs.push([first, second]);
+            }
         }
     }
     return pairs;

package/dist/tools/query.js

@@ -7,7 +7,13 @@ export { VALID_ENTITY_TYPES } from "./entity-query.js";
 export async function handleKbQuery(prolog, args) {
     const { type, id, tags, sourceFile, limit = 100, offset = 0 } = args;
     try {
-        const results = await loadEntities(prolog, { type, id, tags, sourceFile });
+        const queryArgs = {
+            ...(type !== undefined ? { type } : {}),
+            ...(id !== undefined ? { id } : {}),
+            ...(tags !== undefined ? { tags } : {}),
+            ...(sourceFile !== undefined ? { sourceFile } : {}),
+        };
+        const results = await loadEntities(prolog, queryArgs);
         const paginated = paginateResults(results, limit, offset);
         // Build human-readable text with entity IDs and titles
         let text;

package/dist/tools/search.js

@@ -11,7 +11,9 @@ export async function handleKbSearch(prolog, args) {
     validateEntityType(type);
     try {
         const workspaceRoot = resolveWorkspaceRoot();
-        const entities = await loadEntities(prolog, { type });
+        const entities = await loadEntities(prolog, {
+            ...(type !== undefined ? { type } : {}),
+        });
         const matches = await rankEntities(entities, trimmedQuery, workspaceRoot);
         const paginated = paginateResults(matches, limit, offset);
         const text = matches.length === 0

package/dist/tools/symbols.js

@@ -15,7 +15,7 @@
  You should have received a copy of the GNU Affero General Public License
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
-import { existsSync, readFileSync, writeFileSync } from "node:fs";
+import { access, readFile, writeFile } from "node:fs/promises";
 import path from "node:path";
 import { dump as dumpYAML, load as parseYAML } from "js-yaml";
 import { enrichSymbolCoordinates, } from "kibi-cli/extractors/symbols-coordinator";
@@ -47,9 +47,9 @@ const SOURCE_EXTENSIONS = new Set([
 export async function handleKbSymbolsRefresh(args) {
     // implements REQ-vscode-traceability
     const dryRun = args.dryRun === true;
-    const workspaceRoot = resolveWorkspaceRoot();
-    const manifestPath = resolveManifestPath(workspaceRoot);
-    const rawContent = readFileSync(manifestPath, "utf8");
+    const workspaceRoot = args.workspaceRoot ?? resolveWorkspaceRoot();
+    const manifestPath = await resolveManifestPath(workspaceRoot);
+    const rawContent = await readFile(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
     if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
         throw new Error(`Invalid symbols manifest at ${manifestPath}`);
@@ -63,13 +63,14 @@ export async function handleKbSymbolsRefresh(args) {
         title: typeof entry.title === "string" ? entry.title : "",
     }));
     const enriched = await enrichSymbolCoordinates(entriesForEnrichment, workspaceRoot);
-    parsed.symbols = enriched;
+    const finalized = await Promise.all(enriched.map((entry, index) => fillMissingCoordinates(original[index] ?? {}, entry, workspaceRoot)));
+    parsed.symbols = finalized;
     let refreshed = 0;
     let failed = 0;
     let unchanged = 0;
     for (let i = 0; i < original.length; i++) {
         const before = original[i] ?? {};
-        const after = enriched[i] ?? before;
+        const after = finalized[i] ?? before;
         const changed = GENERATED_COORD_FIELDS.some((field) => before[field] !== after[field]);
         if (changed) {
             refreshed++;
@@ -80,7 +81,7 @@ export async function handleKbSymbolsRefresh(args) {
             : typeof before.sourceFile === "string"
                 ? before.sourceFile
                 : undefined;
-        const eligible = isEligible(source, workspaceRoot);
+        const eligible = await isEligible(source, workspaceRoot);
         if (eligible && !hasGeneratedCoordinates(after)) {
             failed++;
         }
@@ -95,7 +96,7 @@ export async function handleKbSymbolsRefresh(args) {
     });
     const nextContent = `${COMMENT_BLOCK}${dumped}`;
     if (!dryRun && rawContent !== nextContent) {
-        writeFileSync(manifestPath, nextContent, "utf8");
+        await writeFile(manifestPath, nextContent, "utf8");
     }
     return {
         content: [
@@ -114,8 +115,8 @@ export async function handleKbSymbolsRefresh(args) {
 }
 export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = resolveWorkspaceRoot()) {
     // implements REQ-vscode-traceability
-    const manifestPath = resolveManifestPath(workspaceRoot);
-    const rawContent = readFileSync(manifestPath, "utf8");
+    const manifestPath = await resolveManifestPath(workspaceRoot);
+    const rawContent = await readFile(manifestPath, "utf8");
     const parsed = parseYAML(rawContent);
     if (!isRecord(parsed) || !Array.isArray(parsed.symbols)) {
         return { refreshed: false, found: false };
@@ -138,9 +139,10 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
             : "",
     };
     const [enriched] = await enrichSymbolCoordinates([singleEntry], workspaceRoot);
-    symbols[index] = enriched ?? original;
+    const finalized = await fillMissingCoordinates(original, enriched ?? singleEntry, workspaceRoot);
+    symbols[index] = finalized;
     parsed.symbols = symbols;
-    const refreshed = GENERATED_COORD_FIELDS.some((field) => original[field] !== symbols[index][field]);
+    const refreshed = GENERATED_COORD_FIELDS.some((field) => original[field] !== finalized[field]);
     const dumped = dumpYAML(parsed, {
         lineWidth: -1,
         noRefs: true,
@@ -148,38 +150,41 @@ export async function refreshCoordinatesForSymbolId(symbolId, workspaceRoot = re
     });
     const nextContent = `${COMMENT_BLOCK}${dumped}`;
     if (rawContent !== nextContent) {
-        writeFileSync(manifestPath, nextContent, "utf8");
+        await writeFile(manifestPath, nextContent, "utf8");
     }
     return { refreshed, found: true };
 }
-export function resolveManifestPath(workspaceRoot) {
+export async function resolveManifestPath(workspaceRoot) {
     // implements REQ-002, REQ-013
     const configPath = path.join(workspaceRoot, ".kb", "config.json");
-    if (existsSync(configPath)) {
-        try {
-            const config = JSON.parse(readFileSync(configPath, "utf8"));
-            // Prefer paths.symbols (new standard) over symbolsManifest (legacy)
-            if (config.paths?.symbols) {
-                return path.isAbsolute(config.paths.symbols)
-                    ? config.paths.symbols
-                    : path.resolve(workspaceRoot, config.paths.symbols);
-            }
-            // Backward compatibility: check legacy symbolsManifest field
-            if (config.symbolsManifest) {
-                return path.isAbsolute(config.symbolsManifest)
-                    ? config.symbolsManifest
-                    : path.resolve(workspaceRoot, config.symbolsManifest);
-            }
+    try {
+        const config = JSON.parse(await readFile(configPath, "utf8"));
+        // Prefer paths.symbols (new standard) over symbolsManifest (legacy)
+        if (config.paths?.symbols) {
+            return path.isAbsolute(config.paths.symbols)
+                ? config.paths.symbols
+                : path.resolve(workspaceRoot, config.paths.symbols);
         }
-        catch {
-            // config file missing or malformed; fall through to defaults
+        // Backward compatibility: check legacy symbolsManifest field
+        if (config.symbolsManifest) {
+            return path.isAbsolute(config.symbolsManifest)
+                ? config.symbolsManifest
+                : path.resolve(workspaceRoot, config.symbolsManifest);
         }
     }
+    catch {
+        // config file missing or malformed; fall through to defaults
+    }
     const candidates = [
         path.join(workspaceRoot, "symbols.yaml"),
         path.join(workspaceRoot, "symbols.yml"),
     ];
-    return candidates.find((candidate) => existsSync(candidate)) ?? candidates[0];
+    for (const candidate of candidates) {
+        if (await fileExists(candidate)) {
+            return candidate;
+        }
+    }
+    return candidates[0] ?? path.join(workspaceRoot, "symbols.yaml");
 }
 function hasGeneratedCoordinates(entry) {
     return (typeof entry.sourceLine === "number" &&
@@ -189,16 +194,72 @@ function hasGeneratedCoordinates(entry) {
         typeof entry.coordinatesGeneratedAt === "string" &&
         entry.coordinatesGeneratedAt.length > 0);
 }
-function isEligible(sourceFile, workspaceRoot) {
+async function isEligible(sourceFile, workspaceRoot) {
     if (!sourceFile)
         return false;
     const absolute = path.isAbsolute(sourceFile)
         ? sourceFile
         : path.resolve(workspaceRoot, sourceFile);
-    if (!existsSync(absolute))
+    if (!(await fileExists(absolute)))
         return false;
     return SOURCE_EXTENSIONS.has(path.extname(absolute).toLowerCase());
 }
+async function fileExists(filePath) {
+    try {
+        await access(filePath);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function fillMissingCoordinates(before, after, workspaceRoot) {
+    if (hasGeneratedCoordinates(after)) {
+        return after;
+    }
+    const sourceFile = typeof after.sourceFile === "string"
+        ? after.sourceFile
+        : typeof before.sourceFile === "string"
+            ? before.sourceFile
+            : undefined;
+    const title = typeof after.title === "string"
+        ? after.title
+        : typeof before.title === "string"
+            ? before.title
+            : undefined;
+    if (!sourceFile || !title) {
+        return after;
+    }
+    const absolutePath = path.isAbsolute(sourceFile)
+        ? sourceFile
+        : path.resolve(workspaceRoot, sourceFile);
+    try {
+        const content = await readFile(absolutePath, "utf8");
+        const escapedTitle = title.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+        const pattern = new RegExp(`\\b${escapedTitle}\\b`);
+        const lines = content.split(/\r?\n/);
+        for (let index = 0; index < lines.length; index++) {
+            const line = lines[index];
+            if (!line)
+                continue;
+            const match = pattern.exec(line);
+            if (!match || match.index < 0)
+                continue;
+            return {
+                ...after,
+                sourceLine: index + 1,
+                sourceColumn: match.index,
+                sourceEndLine: index + 1,
+                sourceEndColumn: match.index + title.length,
+                coordinatesGeneratedAt: new Date().toISOString(),
+            };
+        }
+    }
+    catch {
+        return after;
+    }
+    return after;
+}
 function isRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/dist/tools/upsert.js

@@ -19,6 +19,7 @@ import Ajv from "ajv";
 import { escapeAtom, toPrologAtom, toPrologString, } from "kibi-cli/prolog/codec";
 import entitySchema from "kibi-cli/schemas/entity";
 import relationshipSchema from "kibi-cli/schemas/relationship";
+import { isMcpDebugEnabled } from "../env.js";
 import { refreshCoordinatesForSymbolId } from "./symbols.js";
 let refreshCoordinatesForSymbolIdImpl = refreshCoordinatesForSymbolId;
 const ajv = new Ajv({ strict: false });
@@ -160,7 +161,7 @@ export async function handleKbUpsert(prolog, args) {
             }
             catch (error) {
                 const message = error instanceof Error ? error.message : String(error);
-                if (process.env.KIBI_MCP_DEBUG) {
+                if (isMcpDebugEnabled()) {
                     console.warn(`[KIBI-MCP] Symbol coordinate auto-refresh failed for ${id}: ${message}`);
                 }
             }
@@ -361,6 +362,9 @@ function formatUpsertError(entityId, rawError) {
     if (contradictionMatch) {
         // Extract individual conflict details from the list
         const details = contradictionMatch[1];
+        if (!details) {
+            return `Contradiction detected for entity ${entityId}: This requirement conflicts with existing requirements. Add a supersedes relationship to the conflicting requirement, or deprecate the old requirement before creating the new one.`;
+        }
         // Parse out readable parts - each entry is like 'Reason'-'ReqId'
         const conflicts = [];
         const conflictRegex = /'([^']+)'-'([^']+)'/g;
@@ -368,7 +372,9 @@ function formatUpsertError(entityId, rawError) {
         while (execResult !== null) {
             const reason = execResult[1];
             const otherReq = execResult[2];
-            conflicts.push(`  - Conflicts with ${otherReq}: ${reason}`);
+            if (reason !== undefined && otherReq !== undefined) {
+                conflicts.push(`  - Conflicts with ${otherReq}: ${reason}`);
+            }
             execResult = conflictRegex.exec(details);
         }
         if (conflicts.length > 0) {

package/dist/tools-config.js

@@ -316,6 +316,7 @@ const BASE_TOOLS = [
                                     "validates",
                                     "implements",
                                     "covered_by",
+                                    "executable_for",
                                     "constrained_by",
                                     "constrains",
                                     "requires_property",
@@ -325,7 +326,7 @@ const BASE_TOOLS = [
                                     "supersedes",
                                     "relates_to",
                                 ],
-                                description: "Relationship type enum. Use only supported values. Direction semantics follow KB model (e.g., implements symbol->req, verified_by req->test).",
+                                description: "Relationship type enum. Use only supported values. Direction semantics follow KB model (e.g., implements symbol->req, verified_by req/scenario->test, executable_for symbol->test).",
                             },
                             from: {
                                 type: "string",
@@ -386,6 +387,9 @@ const BASE_TOOLS = [
 ];
 /**
  * Inject _diagnostic_telemetry schema into tool inputs when diagnostic mode is enabled.
+ * TODO: This function is compile-time guarded by DIAGNOSTIC_MODE_ENABLED and only
+ * executes when the server starts with the --diagnostic-mode flag. It cannot be
+ * covered without a CLI integration test.
  */
 function withDiagnosticTelemetrySchema(tools) {
     return tools.map((tool) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
     "ajv": "^8.18.0",
@@ -9,8 +9,8 @@
     "fast-glob": "^3.2.12",
     "gray-matter": "^4.0.3",
     "js-yaml": "^4.1.0",
-    "kibi-cli": "^0.5.0",
-    "kibi-core": "^0.4.0",
+    "kibi-cli": "^0.6.0",
+    "kibi-core": "^0.5.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -27,10 +27,7 @@
     "build": "tsc -p tsconfig.json",
     "prepack": "npm run build"
   },
-  "files": [
-    "dist",
-    "bin"
-  ],
+  "files": ["dist", "bin"],
   "engines": {
     "node": ">=18",
     "bun": ">=1.0"