kibi-mcp 1.0.0 → 2.0.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/runtime/mcp-runtime.js

@@ -1,4 +1,7 @@
 import { resolveBranchAttachment } from "kibi-runtime";
+export function attachedContextWithProlog(withAttachment, prolog) {
+    return { ...withAttachment, prolog };
+}
 // implements REQ-kibi-operation-interface-parity
 export function createMcpRuntime(session) {
     const sessionPrologs = new WeakMap();
@@ -51,7 +54,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;
@@ -195,10 +205,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;

package/dist/server/tool-registration.js

@@ -1,5 +1,6 @@
 import { getSpec, statusSpec } from "kibi-runtime";
-import { executeApplyPlan, executeCompileIntent, executeDelete, executeIngestVerification, executeUpsert, validateUpsertSpec, } from "kibi-runtime";
+import { executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, validateUpsertSpec, } from "kibi-runtime";
+import { startJob } from "./jobs.js";
 // implements REQ-002, REQ-013
 export function registerConfiguredTools(server, runtime, registerTool) {
     const toolDef = (name) => {
@@ -96,7 +97,16 @@ export function registerConfiguredTools(server, runtime, registerTool) {
     });
     register({
         name: "kb_check",
-        execute: async (context, args) => runtime.handleKbCheck(prologFor(context), args),
+        execute: async (context, args) => {
+            const { async: asyncMode, ...checkArgs } = args;
+            if (asyncMode !== true) {
+                return runtime.handleKbCheck(prologFor(context), args);
+            }
+            // Long-KB full checks can exceed the tool timeout. Detach into a job
+            // and return the kibi.job.v1 receipt immediately; the agent polls
+            // kb_job_status for the terminal state and full result.
+            return startJob("kb_check", () => runtime.handleKbCheck(prologFor(context), checkArgs));
+        },
     });
     register({
         name: "kb_model_requirement",
@@ -123,9 +133,9 @@ export function registerConfiguredTools(server, runtime, registerTool) {
             : executeApplyPlan(args, context),
     });
     register({
-        name: "kb_ingest_verification",
-        execute: async (context, args) => runtime.handleKbIngestVerification
-            ? runtime.handleKbIngestVerification(args, context)
-            : executeIngestVerification(args, context),
+        name: "kb_ingest_proof",
+        execute: async (context, args) => runtime.handleKbIngestProof
+            ? runtime.handleKbIngestProof(args, context)
+            : executeIngestProof(args, context),
     });
 }

package/dist/server/tools-runtime.js

@@ -91,8 +91,8 @@ function adaptProlog(prolog) {
 }
 const operationRuntime = createMcpRuntime({
     workspaceRoot: resolveWorkspaceRoot(),
-    activeBranchName: async () => (await getSessionModule()).activeBranchName,
-    attachedBranchKbPath: async () => (await getSessionModule()).attachedBranchKbPath,
+    activeBranchName: async () => (await getSessionModule()).getActiveBranchName(),
+    attachedBranchKbPath: async () => (await getSessionModule()).getAttachedBranchKbPath(),
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
     adaptProlog,
     fs: nodeFilesystem,
@@ -100,7 +100,7 @@ const operationRuntime = createMcpRuntime({
     net: { fetch: (input, init) => globalThis.fetch(input, init) },
     refreshAttachedBranchStamp: async () => {
         const session = await getSessionModule();
-        const kbPath = session.attachedBranchKbPath;
+        const kbPath = session.getAttachedBranchKbPath();
         if (kbPath) {
             try {
                 session.updateAttachedBranchStamp(await readBranchKbStamp(kbPath));
@@ -124,12 +124,12 @@ export const DEFAULT_TOOLS_RUNTIME = {
     // 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,
+    activeBranchName: async () => (await getSessionModule()).getActiveBranchName(),
     ensureProlog: async () => (await getSessionModule()).ensureProlog(),
     resetProlog: async (reason) => (await getSessionModule()).resetProlog(reason),
     inFlightRequests: async () => (await getSessionModule()).inFlightRequests,
-    isShuttingDown: async () => (await getSessionModule()).isShuttingDown,
-    prologProcess: async () => (await getSessionModule()).prologProcess,
+    isShuttingDown: async () => (await getSessionModule()).getIsShuttingDown(),
+    prologProcess: async () => (await getSessionModule()).getPrologProcess(),
     operationRuntime,
     handleKbCheck,
     handleKbCoverage,

package/dist/server/tools.js

@@ -20,6 +20,7 @@ import { executeOperation } from "kibi-runtime";
 import { operationData, toKibiResult } from "kibi-runtime";
 import { isMcpDebugEnabled } from "../env.js";
 import { appendDiagnosticErrorUsage, appendDiagnosticSuccessUsage, } from "./diagnostic-usage.js";
+import { getJob, jobSnapshot } from "./jobs.js";
 import { jsonSchemaToZod } from "./json-schema-to-zod.js";
 import { registerConfiguredTools } from "./tool-registration.js";
 import { DEFAULT_TOOLS_RUNTIME, _resetSessionModulePromise, _setToolsServerDepsForTests, } from "./tools-runtime.js";
@@ -263,4 +264,60 @@ export function registerAllTools(server,
 // INTENTIONAL: same generic bridge cast as addTool — see comment there.
 runtime = DEFAULT_TOOLS_RUNTIME) {
     registerConfiguredTools(server, runtime, addTool);
+    registerJobStatusTool(server);
+}
+/**
+ * kb_job_status polls background jobs started by long-running operations
+ * (currently `kb_check` with `async: true`). This is an MCP-server-native
+ * companion to the job receipts, not part of the canonical CLI operation
+ * catalog: jobs live in the server process and have no CLI counterpart.
+ */
+function registerJobStatusTool(server) {
+    addTool(server, "kb_job_status", "Poll a background job started with async:true (e.g. kb_check async jobs). Returns the kibi.job.v1 state: running, succeeded (with the full result), or failed (with the error).", {
+        type: "object",
+        properties: {
+            jobId: {
+                type: "string",
+                description: "The jobId from the kibi.job.v1 receipt.",
+            },
+        },
+        required: ["jobId"],
+    }, async (args) => {
+        const jobId = typeof args.jobId === "string" ? args.jobId : "";
+        const job = jobId === "" ? undefined : getJob(jobId);
+        if (job === undefined) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({
+                            kibiProtocol: 1,
+                            jobVersion: "kibi.job.v1",
+                            jobId,
+                            status: "unknown",
+                            error: "No such job. Jobs are process-local and dropped on server restart; check the jobId or re-run the operation with async:true.",
+                        }),
+                    },
+                ],
+                structuredContent: {
+                    kibiProtocol: 1,
+                    jobVersion: "kibi.job.v1",
+                    jobId,
+                    status: "unknown",
+                    error: "No such job. Jobs are process-local and dropped on server restart; check the jobId or re-run the operation with async:true.",
+                },
+            };
+        }
+        const snapshot = jobSnapshot(job);
+        return {
+            content: [{ type: "text", text: JSON.stringify(snapshot) }],
+            structuredContent: snapshot,
+        };
+    }, undefined, undefined, undefined, {
+        title: "Poll a Kibi background job",
+        readOnlyHint: true,
+        destructiveHint: false,
+        idempotentHint: true,
+        openWorldHint: false,
+    });
 }

package/dist/startup-resolution.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, realpathSync } from "node:fs";
+import * as fs from "node:fs";
 import { createRequire } from "node:module";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
@@ -28,35 +28,33 @@ function toEntrypointPath(entrypointUrl) {
     return path.resolve(entrypointUrl);
 }
 function readJson(filePath) {
-    return JSON.parse(readFileSync(filePath, "utf8"));
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+}
+export function nextAncestorDirectory(current) {
+    const parent = path.dirname(current);
+    return parent === current ? undefined : parent;
 }
 function nearestPackageJson(startPath) {
     let current = path.dirname(startPath);
-    while (true) {
+    while (current !== undefined) {
         const candidate = path.join(current, "package.json");
-        if (existsSync(candidate)) {
+        if (fs.existsSync(candidate)) {
             return candidate;
         }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            throw new Error(`Unable to find package.json for ${startPath}`);
-        }
-        current = parent;
+        current = nextAncestorDirectory(current);
     }
+    throw new Error(`Unable to find package.json for ${startPath}`);
 }
 function nearestPackageJsonFromDirectory(startPath) {
     let current = path.resolve(startPath);
-    while (true) {
+    while (current !== undefined) {
         const candidate = path.join(current, "package.json");
-        if (existsSync(candidate)) {
+        if (fs.existsSync(candidate)) {
             return candidate;
         }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
+        current = nextAncestorDirectory(current);
     }
+    return null;
 }
 function packageInfoFromEntrypoint(entrypoint) {
     const normalizedEntrypoint = path.resolve(entrypoint);
@@ -82,7 +80,7 @@ export function resolveProjectLocalMcp(cwd) {
         }
         const projectRequire = createRequire(projectPackageJson);
         const resolved = projectRequire.resolve(PACKAGE_NAME);
-        const entrypoint = realpathSync.native?.(resolved) ?? realpathSync(resolved);
+        const entrypoint = fs.realpathSync.native?.(resolved) ?? fs.realpathSync(resolved);
         return packageInfoFromEntrypoint(entrypoint);
     }
     catch (error) {

package/dist/tools/core-module.js

@@ -2,6 +2,13 @@ import path from "node:path";
 import { PrologProcess, resolveKbPlPath } from "kibi-runtime";
 import { escapeAtomContent } from "kibi-runtime";
 import { getCoreModulePathOverride, getKbPlPathOverride } from "../env.js";
+export function parseMaybeDoubleEncodedJson(rawJson) {
+    let parsed = JSON.parse(rawJson);
+    if (typeof parsed === "string") {
+        parsed = JSON.parse(parsed);
+    }
+    return parsed;
+}
 function isPrologProcess(value) {
     return (value instanceof PrologProcess ||
         (value !== null &&
@@ -60,11 +67,7 @@ export async function runJsonModuleQuery(prolog, fileName, goal, errorLabel) {
     if (!rawJson) {
         throw new Error(`${errorLabel} query returned no JsonString binding`);
     }
-    let parsed = JSON.parse(rawJson);
-    if (typeof parsed === "string") {
-        parsed = JSON.parse(parsed);
-    }
-    return parsed;
+    return parseMaybeDoubleEncodedJson(rawJson);
 }
 async function runInteractiveModuleQuery(prolog, modulePath, goal, errorLabel) {
     const loadResult = await prolog.query(`use_module('${modulePath}')`);

package/dist/tools-config.js

@@ -38,7 +38,7 @@ const MCP_TOOL_ORDER = [
     "kb_plan_bootstrap",
     "kb_compile_intent",
     "kb_apply_plan",
-    "kb_ingest_verification",
+    "kb_ingest_proof",
 ];
 // implements REQ-002
 const TOOL_ANNOTATIONS = {
@@ -134,8 +134,8 @@ const TOOL_ANNOTATIONS = {
         idempotentHint: false,
         openWorldHint: false,
     },
-    kb_ingest_verification: {
-        title: "Ingest contracted verification evidence",
+    kb_ingest_proof: {
+        title: "Ingest proof-run evidence",
         readOnlyHint: false,
         destructiveHint: false,
         idempotentHint: false,

package/dist/workspace.js

@@ -68,19 +68,20 @@ function readFirstEnv(keys) {
     }
     return null;
 }
+export function nextAncestorDirectory(current) {
+    const parent = path.dirname(current);
+    return parent === current ? undefined : parent;
+}
 function findUpwards(startDir, marker) {
     let current = path.resolve(startDir);
-    while (true) {
+    while (current !== undefined) {
         const candidate = path.join(current, marker);
         if (fs.existsSync(candidate)) {
             return current;
         }
-        const parent = path.dirname(current);
-        if (parent === current) {
-            return null;
-        }
-        current = parent;
+        current = nextAncestorDirectory(current);
     }
+    return null;
 }
 function isBranchPath(p) {
     const parent = path.basename(path.dirname(p));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kibi-mcp",
-  "version": "1.0.0",
+  "version": "2.0.0",
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.30.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-runtime": "^1.0.1",
-    "kibi-core": "^0.11.0",
+    "kibi-runtime": "^2.0.0",
+    "kibi-core": "^0.12.0",
     "mcpcat": "^0.1.12",
     "ts-morph": "^23.0.0",
     "zod": "^4.3.6"
@@ -24,7 +24,8 @@
   "scripts": {
     "test": "bun test",
     "dev": "bun run bin/kibi-mcp",
-    "build": "tsc -p tsconfig.json",
+    "clean": "rm -rf dist",
+    "build": "npm run clean && tsc -p tsconfig.json",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "prepack": "npm run build && node ../../scripts/verify-package-contract.mjs kibi-mcp"
   },