kibi-mcp 1.0.0 → 2.1.0

package/dist/diagnostics.js

@@ -140,12 +140,12 @@ function appendMutationFields(fields, args) {
     fields.mutation_target = `${type}:${id}`;
 }
 const RECEIPT_GAP_CODES = new Set([
-    "missing_verification_receipt",
-    "stale_verification_receipt",
-    "failed_verification_receipt",
-    "invalid_verification_receipt",
-    "verification_contract_mismatch",
-    "verification_snapshot_unavailable",
+    "missing_proof_receipt",
+    "stale_proof_receipt",
+    "failed_proof_receipt",
+    "invalid_proof_receipt",
+    "proof_contract_mismatch",
+    "proof_snapshot_unavailable",
 ]);
 const MAX_COVERAGE_RECEIPT_GAPS = 50;
 function coverageReceiptGapDetails(rows) {
@@ -214,8 +214,8 @@ function appendCoverageFields(fields, args, structuredContent) {
     const metadata = isRecord(structuredContent.meta)
         ? structuredContent.meta
         : undefined;
-    if (typeof metadata?.verificationSnapshot === "string") {
-        fields.coverage_verification_snapshot = metadata.verificationSnapshot;
+    if (typeof metadata?.proofSnapshot === "string") {
+        fields.coverage_proof_snapshot = metadata.proofSnapshot;
     }
 }
 function appendPredicateSuggestionFields(fields, structuredContent) {

package/dist/env.js

@@ -16,8 +16,7 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
 */
 import fs from "node:fs";
-import { resolveEnvFilePath, resolveWorkspaceRoot } from "./workspace.js";
-const DEFAULT_ENV_FILE = ".env";
+import { KIBI_PROJECT_ENV_FILE, bootstrapKibiEnvironment, inspectSecretSource, parseEnvContent, resolveEnvFilePath, resolveKibiProjectEnvPath, resolveKibiWorkspaceRoot, } from "kibi-runtime";
 function getEnvValue(key) {
     const value = process.env[key];
     return typeof value === "string" ? value : undefined;
@@ -26,9 +25,10 @@ function getTrimmedEnvValue(key) {
     const value = getEnvValue(key)?.trim();
     return value ? value : undefined;
 }
+/** Preferred project env file name (`.env.kibi` or `KIBI_ENV_FILE` override). */
 export function getEnvFileName() {
     // implements REQ-002
-    return getTrimmedEnvValue("KIBI_ENV_FILE") ?? DEFAULT_ENV_FILE;
+    return getTrimmedEnvValue("KIBI_ENV_FILE") ?? KIBI_PROJECT_ENV_FILE;
 }
 export function isMcpDebugEnabled() {
     // implements REQ-002
@@ -51,12 +51,26 @@ export function getCoreModulePathOverride(fileName) {
     const envKey = `KIBI_${fileName.replace(/\W/g, "_").toUpperCase()}_PATH`;
     return getEnvValue(envKey);
 }
+/**
+ * Harness-independent bootstrap: process → project `.env.kibi`/`KIBI_ENV_FILE`
+ * → user `~/.config/kibi/env`, plus legacy `.env` gap-fill.
+ * Prefer calling from `startServer()` only.
+ */
 export function loadDefaultEnvFile() {
     // implements REQ-002
-    const envFileName = getEnvFileName();
-    const workspaceRoot = resolveWorkspaceRoot();
-    return loadEnvFile({ envFileName, workspaceRoot });
+    const result = bootstrapKibiEnvironment();
+    const keysLoaded = [
+        ...result.keysLoadedFromUser,
+        ...result.keysLoadedFromProject,
+        ...result.keysLoadedFromLegacy,
+    ];
+    return {
+        loaded: keysLoaded.length > 0,
+        envFilePath: result.projectEnvPath,
+        keysLoaded,
+    };
 }
+/** @deprecated Prefer bootstrapKibiEnvironment; kept for targeted file tests. */
 export function loadEnvFile(options) {
     const { envFileName, workspaceRoot } = options;
     const envFilePath = resolveEnvFilePath(envFileName, workspaceRoot);
@@ -80,27 +94,4 @@ export function loadEnvFile(options) {
         return { loaded: false, envFilePath, keysLoaded };
     }
 }
-function parseEnvContent(content) {
-    const lines = content.split(/\r?\n/);
-    const entries = [];
-    for (const rawLine of lines) {
-        const line = rawLine.trim();
-        if (!line || line.startsWith("#")) {
-            continue;
-        }
-        const eqIndex = line.indexOf("=");
-        if (eqIndex <= 0) {
-            continue;
-        }
-        const key = line.substring(0, eqIndex).trim();
-        let value = line.substring(eqIndex + 1).trim();
-        if (value.startsWith('"') && value.endsWith('"')) {
-            value = value.slice(1, -1);
-        }
-        else if (value.startsWith("'") && value.endsWith("'")) {
-            value = value.slice(1, -1);
-        }
-        entries.push({ key, value });
-    }
-    return entries;
-}
+export { resolveEnvFilePath, resolveKibiProjectEnvPath, resolveKibiWorkspaceRoot, inspectSecretSource, };

package/dist/runtime/mcp-runtime.js

@@ -1,16 +1,38 @@
-import { resolveBranchAttachment } from "kibi-runtime";
+import { CapabilityRegistryCache, ensureCapabilityRegistry, resolveBranchAttachment, } from "kibi-runtime";
+export function attachedContextWithProlog(withAttachment, prolog) {
+    return { ...withAttachment, prolog };
+}
+function resolvePluginsOption(plugins) {
+    if (plugins === undefined)
+        return undefined;
+    if (typeof plugins === "function")
+        return plugins;
+    return async () => plugins;
+}
 // implements REQ-kibi-operation-interface-parity
 export function createMcpRuntime(session) {
     const sessionPrologs = new WeakMap();
+    // Per-runtime cache — not a process-global singleton.
+    const pluginCache = new CapabilityRegistryCache();
     return {
         open: async (spec, options = {}) => {
             const fs = options.fs ?? session.fs;
             const git = options.git ?? session.git;
             const net = options.net ?? session.net;
+            const pluginsOption = options.plugins ?? session.plugins;
+            const injectedPlugins = resolvePluginsOption(pluginsOption);
+            const workspaceRoot = options.workspaceRoot ?? session.workspaceRoot;
+            const ensurePlugins = async () => {
+                if (injectedPlugins)
+                    return injectedPlugins();
+                return ensureCapabilityRegistry(workspaceRoot, { cache: pluginCache });
+            };
             const context = {
-                workspaceRoot: options.workspaceRoot ?? session.workspaceRoot,
+                workspaceRoot,
                 signal: options.signal ?? session.signal ?? new AbortController().signal,
                 clock: options.clock ?? session.clock ?? (() => new Date()),
+                ensurePlugins,
+                ...(pluginsOption !== undefined ? { plugins: pluginsOption } : {}),
                 ...(fs ? { fs } : {}),
                 ...(fs ? { sourceFirst: true } : {}),
                 ...(git ? { git } : {}),
@@ -51,7 +73,7 @@ export function createMcpRuntime(session) {
                 throw new Error(`Legacy branch attachment requires explicit migration before '${spec.name}'; run kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply`);
             }
             if (options.prolog) {
-                return { ...withAttachment, prolog: options.prolog };
+                return attachedContextWithProlog(withAttachment, options.prolog);
             }
             const sessionProlog = await session.ensureProlog();
             const operationContext = {

package/dist/server/jobs.js

@@ -0,0 +1,107 @@
+/*
+ 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";
+const MAX_FINISHED_JOBS = 32;
+const jobs = new Map();
+let jobCounter = 0;
+function nextJobId(tool) {
+    jobCounter += 1;
+    const random = Math.random().toString(36).slice(2, 10);
+    return `job-${tool}-${jobCounter.toString(36)}-${random}`;
+}
+function evictOldestFinished() {
+    for (const [id, record] of jobs) {
+        if (jobs.size <= MAX_FINISHED_JOBS)
+            break;
+        if (record.status !== "running") {
+            jobs.delete(id);
+        }
+    }
+}
+/**
+ * Start a background job for `tool`. The factory's promise runs detached;
+ * callers return the `kibi.job.v1` receipt immediately so the MCP request is
+ * never held open for the duration of the operation.
+ */
+// implements REQ-002
+export function startJob(tool, factory) {
+    const jobId = nextJobId(tool);
+    const record = {
+        jobId,
+        tool,
+        startedAt: new Date().toISOString(),
+        status: "running",
+    };
+    jobs.set(jobId, record);
+    void (async () => {
+        try {
+            const result = await factory();
+            record.status = "succeeded";
+            record.finishedAt = new Date().toISOString();
+            record.result =
+                result !== null && typeof result === "object"
+                    ? result
+                    : { value: result };
+        }
+        catch (error) {
+            record.status = "failed";
+            record.finishedAt = new Date().toISOString();
+            record.error = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            evictOldestFinished();
+        }
+    })().catch((error) => {
+        // Defensive: the internal bookkeeping above must never crash the server
+        // process via an unhandled rejection.
+        process.stderr.write(`[kibi-mcp] job bookkeeping error for ${jobId}: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    return {
+        kibiProtocol: 1,
+        jobVersion: "kibi.job.v1",
+        jobId,
+        tool,
+        status: "running",
+        pollWith: "kb_job_status",
+    };
+}
+// implements REQ-002
+export function getJob(jobId) {
+    return jobs.get(jobId);
+}
+/** Public JSON shape for kb_job_status responses. */
+// implements REQ-002
+export function jobSnapshot(job) {
+    return {
+        kibiProtocol: 1,
+        jobVersion: "kibi.job.v1",
+        jobId: job.jobId,
+        tool: job.tool,
+        status: job.status,
+        startedAt: job.startedAt,
+        ...(job.finishedAt === undefined ? {} : { finishedAt: job.finishedAt }),
+        ...(job.result === undefined ? {} : { result: job.result }),
+        ...(job.error === undefined ? {} : { error: job.error }),
+    };
+}
+/** Test seam: drop all job state. */
+// implements REQ-002
+export function resetJobsForTests() {
+    jobs.clear();
+    jobCounter = 0;
+}

package/dist/server/json-schema-to-zod.js

@@ -1,4 +1,18 @@
 import { z } from "zod";
+export function firstDefined(items) {
+    return items[0];
+}
+export function describedAnySchema(description) {
+    const anySchema = z.any();
+    return description ? anySchema.describe(description) : anySchema;
+}
+export function singleLiteralOrAny(literalSchemas, description) {
+    const single = firstDefined(literalSchemas);
+    if (!single) {
+        return describedAnySchema(description);
+    }
+    return description ? single.describe(description) : single;
+}
 function hasRequiredProperties(value, schema) {
     if (schema === null || typeof schema !== "object")
         return false;
@@ -64,11 +78,7 @@ 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;
+            return singleLiteralOrAny(literalSchemas, description);
         }
         const union = z.union(literalSchemas);
         return description ? union.describe(description) : union;
@@ -78,6 +88,20 @@ export function jsonSchemaToZod(schema) {
         : typeof obj.type === "string"
             ? [obj.type]
             : [];
+    // JSON Schema anyOf unions become real Zod unions so MCP output
+    // validation enforces the declared alternatives instead of silently
+    // degrading to z.any() — e.g. kb_check's synchronous payload versus its
+    // kibi.job.v1 async receipt. oneOf is intentionally left degrading: its
+    // required-guard branches carry no properties and would loosen input
+    // validation instead of tightening it.
+    const anyOfVariants = Array.isArray(obj.anyOf) ? obj.anyOf : [];
+    if (anyOfVariants.length > 0) {
+        const variants = anyOfVariants.map((variant) => jsonSchemaToZod(variant));
+        const union = z.union(variants);
+        return typeof obj.description === "string"
+            ? union.describe(obj.description)
+            : union;
+    }
     // JSON Schema nullable fields are represented as a type union in the
     // catalog. Build a real Zod union so MCP publishes and validates the same
     // nullability instead of silently degrading the field to z.any().
@@ -195,10 +219,7 @@ export function jsonSchemaToZod(schema) {
             const description = typeof obj.description === "string" ? obj.description : undefined;
             return description ? n.describe(description) : n;
         }
-        default: {
-            const anySchema = z.any();
-            const description = typeof obj.description === "string" ? obj.description : undefined;
-            return description ? anySchema.describe(description) : anySchema;
-        }
+        default:
+            return describedAnySchema(typeof obj.description === "string" ? obj.description : undefined);
     }
 }

package/dist/server/session.js

@@ -37,35 +37,53 @@ const defaultSessionDeps = {
     resolveWorkspaceRoot,
 };
 let sessionDeps = { ...defaultSessionDeps };
-export let prologProcess = null;
-let isInitialized = false;
-export let activeBranchName = "develop";
-let ensurePrologTail = Promise.resolve();
-let prologResetGeneration = 0;
-export let attachedBranchKbPath = null;
-let attachedBranchStamp = null;
+const state = {
+    prologProcess: null,
+    isInitialized: false,
+    activeBranchName: "develop",
+    ensurePrologTail: Promise.resolve(),
+    prologResetGeneration: 0,
+    attachedBranchKbPath: null,
+    attachedBranchStamp: null,
+    isShuttingDown: false,
+    shutdownTimeout: null,
+};
+// implements REQ-008
+export function getPrologProcess() {
+    return state.prologProcess;
+}
+// implements REQ-mcp-kb-freshness
+export function getActiveBranchName() {
+    return state.activeBranchName;
+}
+// implements REQ-008
+export function getAttachedBranchKbPath() {
+    return state.attachedBranchKbPath;
+}
+// implements REQ-008
+export function getIsShuttingDown() {
+    return state.isShuttingDown;
+}
+export const inFlightRequests = new Map();
 // implements REQ-mcp-kb-freshness
 // covered_by TEST-mcp-kb-freshness
 export function updateAttachedBranchStamp(stamp) {
-    attachedBranchStamp = stamp;
+    state.attachedBranchStamp = stamp;
 }
-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();
-    prologResetGeneration = 0;
-    attachedBranchKbPath = null;
-    attachedBranchStamp = null;
-    isShuttingDown = false;
+    state.prologProcess = null;
+    state.isInitialized = false;
+    state.activeBranchName = "develop";
+    state.ensurePrologTail = Promise.resolve();
+    state.prologResetGeneration = 0;
+    state.attachedBranchKbPath = null;
+    state.attachedBranchStamp = null;
+    state.isShuttingDown = false;
     inFlightRequests.clear();
-    if (shutdownTimeout) {
-        clearTimeout(shutdownTimeout);
-        shutdownTimeout = null;
+    if (state.shutdownTimeout) {
+        clearTimeout(state.shutdownTimeout);
+        state.shutdownTimeout = null;
     }
 }
 export function _setSessionDepsForTests(
@@ -77,6 +95,10 @@ export function _resetSessionDepsForTests() {
     // implements REQ-008
     sessionDeps = { ...defaultSessionDeps };
 }
+// implements REQ-008
+export function _setPrologProcessForTests(process) {
+    state.prologProcess = process;
+}
 function debugLog(...args) {
     if (isMcpDebugEnabled()) {
         console.error(...args);
@@ -108,13 +130,13 @@ export function ensureBranchKbExists(workspaceRoot, branch) {
     return true;
 }
 export async function initiateGracefulShutdown(exitCode = 0) {
-    if (isShuttingDown) {
+    if (state.isShuttingDown) {
         return;
     }
-    isShuttingDown = true;
+    state.isShuttingDown = true;
     debugLog(`[KIBI-MCP] Initiating graceful shutdown (exit code: ${exitCode})`);
-    const currentProlog = prologProcess;
-    prologProcess = null;
+    const currentProlog = state.prologProcess;
+    state.prologProcess = null;
     if (currentProlog?.isRunning()) {
         debugLog("[KIBI-MCP] Cancelling active Prolog work...");
         try {
@@ -129,7 +151,7 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     if (inFlightRequests.size > 0) {
         debugLog(`[KIBI-MCP] Waiting for ${inFlightRequests.size} in-flight requests to complete...`);
         const timeoutPromise = new Promise((_, reject) => {
-            shutdownTimeout = setTimeout(() => {
+            state.shutdownTimeout = setTimeout(() => {
                 reject(new Error("Shutdown timeout"));
             }, 10000); // 10 second timeout
         });
@@ -144,9 +166,9 @@ export async function initiateGracefulShutdown(exitCode = 0) {
             console.error("[KIBI-MCP] Shutdown timeout reached, forcing exit");
         }
         finally {
-            if (shutdownTimeout) {
-                clearTimeout(shutdownTimeout);
-                shutdownTimeout = null;
+            if (state.shutdownTimeout) {
+                clearTimeout(state.shutdownTimeout);
+                state.shutdownTimeout = null;
             }
         }
     }
@@ -156,12 +178,12 @@ export async function initiateGracefulShutdown(exitCode = 0) {
 // implements REQ-008
 export async function resetProlog(reason) {
     debugLog(`[KIBI-MCP] Resetting Prolog worker: ${reason}`);
-    prologResetGeneration += 1;
-    const current = prologProcess;
-    prologProcess = null;
-    isInitialized = false;
-    attachedBranchKbPath = null;
-    attachedBranchStamp = null;
+    state.prologResetGeneration += 1;
+    const current = state.prologProcess;
+    state.prologProcess = null;
+    state.isInitialized = false;
+    state.attachedBranchKbPath = null;
+    state.attachedBranchStamp = null;
     if (current) {
         try {
             await current.terminate();
@@ -202,14 +224,14 @@ function usesBranchKbPath(kbPath) {
 }
 // implements REQ-008
 async function ensurePrologUnsafe() {
-    const generationAtStart = prologResetGeneration;
+    const generationAtStart = state.prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();
     const useEngine = sessionDeps.PrologProcess === defaultSessionDeps.PrologProcess;
     const assertGeneration = async () => {
-        if (generationAtStart !== prologResetGeneration) {
-            const current = prologProcess;
-            prologProcess = null;
-            isInitialized = false;
+        if (generationAtStart !== state.prologResetGeneration) {
+            const current = state.prologProcess;
+            state.prologProcess = null;
+            state.isInitialized = false;
             if (current) {
                 await current.terminate().catch((error) => {
                     console.error("[KIBI-MCP] Error terminating stale Prolog after reset generation change:", error);
@@ -240,22 +262,22 @@ async function ensurePrologUnsafe() {
         targetBranch = branchResult.kbBranch;
     }
     // Check if we need to switch branches
-    if (isInitialized && useEngine && prologProcess?.isRunning()) {
+    if (state.isInitialized && useEngine && state.prologProcess?.isRunning()) {
         const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
-        if (targetBranch === activeBranchName) {
-            attachedBranchKbPath = kbPath;
-            attachedBranchStamp = await readBranchKbStamp(kbPath);
-            return prologProcess;
+        if (targetBranch === state.activeBranchName) {
+            state.attachedBranchKbPath = kbPath;
+            state.attachedBranchStamp = await readBranchKbStamp(kbPath);
+            return state.prologProcess;
         }
-        await prologProcess.terminate();
-        prologProcess = null;
-        isInitialized = false;
-        attachedBranchKbPath = null;
-        attachedBranchStamp = null;
+        await state.prologProcess.terminate();
+        state.prologProcess = null;
+        state.isInitialized = false;
+        state.attachedBranchKbPath = null;
+        state.attachedBranchStamp = null;
     }
-    if (isInitialized && prologProcess?.isRunning()) {
+    if (state.isInitialized && state.prologProcess?.isRunning()) {
         const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
-        if (targetBranch === activeBranchName) {
+        if (targetBranch === state.activeBranchName) {
             const currentStamp = await readBranchKbStamp(kbPath);
             if (usesBranchKbPath(kbPath) &&
                 (currentStamp.rdfMissing ||
@@ -263,29 +285,29 @@ async function ensurePrologUnsafe() {
                     currentStamp.errorMessage !== null)) {
                 throw new KbRefreshError(`KB refresh failed: branch KB snapshot is unstable: ${describeBranchKbStamp(currentStamp)}`);
             }
-            const shouldRefresh = attachedBranchKbPath === kbPath &&
-                attachedBranchStamp !== null &&
+            const shouldRefresh = state.attachedBranchKbPath === kbPath &&
+                state.attachedBranchStamp !== null &&
                 usesBranchKbPath(kbPath) &&
-                !sameBranchKbStamp(currentStamp, attachedBranchStamp);
+                !sameBranchKbStamp(currentStamp, state.attachedBranchStamp);
             if (shouldRefresh) {
-                attachedBranchStamp = await refreshAttachedBranchKbWithRetry(prologProcess, kbPath, currentStamp, assertGeneration);
+                state.attachedBranchStamp = await refreshAttachedBranchKbWithRetry(state.prologProcess, kbPath, currentStamp, assertGeneration);
             }
             else {
-                attachedBranchKbPath = kbPath;
-                attachedBranchStamp = currentStamp;
+                state.attachedBranchKbPath = kbPath;
+                state.attachedBranchStamp = currentStamp;
             }
-            attachedBranchKbPath = kbPath;
-            return prologProcess;
+            state.attachedBranchKbPath = kbPath;
+            return state.prologProcess;
         }
         // Branch changed - need to detach and re-attach
-        debugLog(`[KIBI-MCP] Branch changed: ${activeBranchName} -> ${targetBranch}`);
+        debugLog(`[KIBI-MCP] Branch changed: ${state.activeBranchName} -> ${targetBranch}`);
         // Persist and detach from old KB
-        const saveResult = await prologProcess.query("kb_save");
+        const saveResult = await state.prologProcess.query("kb_save");
         await assertGeneration();
         if (!saveResult.success) {
             throw new Error(`Failed to save old KB before detach: ${saveResult.error || "Unknown error"}`);
         }
-        const detachResult = await prologProcess.query("kb_detach");
+        const detachResult = await state.prologProcess.query("kb_detach");
         await assertGeneration();
         if (!detachResult.success) {
             debugLog(`[KIBI-MCP] Warning: failed to detach from old KB: ${detachResult.error || "Unknown error"}`);
@@ -294,35 +316,35 @@ async function ensurePrologUnsafe() {
         // Ensure new branch KB exists
         const createdEmptyBranch = ensureBranchKbExists(workspaceRoot, targetBranch);
         // Attach to new branch KB
-        const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
+        const attachResult = await state.prologProcess.query(`kb_attach('${kbPath}')`);
         await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach to new branch KB: ${attachResult.error || "Unknown error"}`);
         }
         if (createdEmptyBranch) {
-            const initialSaveResult = await prologProcess.query("kb_save");
+            const initialSaveResult = await state.prologProcess.query("kb_save");
             await assertGeneration();
             if (!initialSaveResult.success) {
                 throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
             }
         }
-        activeBranchName = targetBranch;
-        attachedBranchKbPath = kbPath;
-        attachedBranchStamp = await readBranchKbStamp(kbPath);
+        state.activeBranchName = targetBranch;
+        state.attachedBranchKbPath = kbPath;
+        state.attachedBranchStamp = await readBranchKbStamp(kbPath);
         debugLog(`[KIBI-MCP] Re-attached to branch: ${targetBranch}`);
         debugLog(`[KIBI-MCP] KB path: ${kbPath}`);
-        return prologProcess;
+        return state.prologProcess;
     }
     // First initialization
     debugLog("[KIBI-MCP] Initializing Prolog process...");
-    prologProcess = useEngine
+    state.prologProcess = useEngine
         ? new EngineClient({
             workspaceRoot,
             branch: targetBranch,
             timeout: 120000,
         })
         : new sessionDeps.PrologProcess({ timeout: 120000 });
-    await prologProcess.start();
+    await state.prologProcess.start();
     await assertGeneration();
     // Adapters report the package that owns runtime execution. Do not resolve
     // CLI implementation paths from the MCP process; the runtime package is
@@ -332,34 +354,34 @@ async function ensurePrologUnsafe() {
     debugLog("[KIBI-MCP] Branch selection:");
     debugLog(`[KIBI-MCP]   KIBI_BRANCH env: ${envBranch || "not set"}`);
     debugLog(`[KIBI-MCP]   Resolved branch: ${targetBranch}`);
-    activeBranchName = targetBranch;
+    state.activeBranchName = targetBranch;
     const createdEmptyBranch = ensureBranchKbExists(workspaceRoot, targetBranch);
     const kbPath = sessionDeps.resolveKbPath(workspaceRoot, targetBranch);
     if (!useEngine) {
-        const attachResult = await prologProcess.query(`kb_attach('${kbPath}')`);
+        const attachResult = await state.prologProcess.query(`kb_attach('${kbPath}')`);
         await assertGeneration();
         if (!attachResult.success) {
             throw new Error(`Failed to attach KB: ${attachResult.error || "Unknown error"}`);
         }
         if (createdEmptyBranch) {
-            const initialSaveResult = await prologProcess.query("kb_save");
+            const initialSaveResult = await state.prologProcess.query("kb_save");
             await assertGeneration();
             if (!initialSaveResult.success) {
                 throw new Error(`Failed to initialize empty branch KB: ${initialSaveResult.error || "Unknown error"}`);
             }
         }
     }
-    attachedBranchKbPath = kbPath;
-    attachedBranchStamp = await readBranchKbStamp(kbPath);
-    isInitialized = true;
-    debugLog(`[KIBI-MCP] Prolog process started (PID: ${prologProcess.getPid()})`);
+    state.attachedBranchKbPath = kbPath;
+    state.attachedBranchStamp = await readBranchKbStamp(kbPath);
+    state.isInitialized = true;
+    debugLog(`[KIBI-MCP] Prolog process started (PID: ${state.prologProcess.getPid()})`);
     debugLog(`[KIBI-MCP] KB attached: ${kbPath}`);
-    return prologProcess;
+    return state.prologProcess;
 }
 export async function ensureProlog() {
-    const previous = ensurePrologTail;
+    const previous = state.ensurePrologTail;
     let release;
-    ensurePrologTail = new Promise((resolve) => {
+    state.ensurePrologTail = new Promise((resolve) => {
         release = resolve;
     });
     await previous;