kibi-mcp 2.3.0 → 3.0.0

package/bin/kibi-mcp

@@ -99,7 +99,8 @@ if (args.includes("-h") || args.includes("--help")) {
 
   if (args.includes("--diagnostic-mode")) {
     globalThis.__KIBI_MCP_DIAGNOSTIC_MODE = true;
-    process.env.KIBI_WORKSPACE ??= process.cwd();
+    process.env.KIBI_WORKSPACE ??=
+      process.env.KIBI_MCP_ATTACH_ROOT?.trim() || process.cwd();
     process.env.KIBI_MCP_DIAGNOSTIC_MODE = "1";
   }
 
@@ -108,6 +109,26 @@ if (args.includes("-h") || args.includes("--help")) {
     process.stderr.write(json);
   }
 
+  // implements REQ-mcp-workspace-routing
+  // Host launchers name the workspace with KIBI_MCP_ATTACH_ROOT rather than
+  // KIBI_WORKSPACE: a pin disables per-call workspace routing. Attach after
+  // runtime resolution (which reads the launch directory) and only when no
+  // operator pin is set.
+  const attachRoot = process.env.KIBI_MCP_ATTACH_ROOT?.trim();
+  const pinned = ["KIBI_WORKSPACE", "KIBI_PROJECT_ROOT", "KIBI_ROOT"].some(
+    (key) => (process.env[key] ?? "").trim().length > 0,
+  );
+  if (attachRoot && !pinned) {
+    try {
+      process.chdir(attachRoot);
+    } catch (error) {
+      process.stderr.write(
+        `[KIBI-MCP] Cannot attach to ${attachRoot}: ${error?.message ?? String(error)}\n`,
+      );
+      process.exit(1);
+    }
+  }
+
   if (result.stale) {
     if (result.projectLocal && process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY !== "1") {
       process.env.KIBI_MCP_PROJECT_LOCAL_REENTRY = "1";

package/dist/diagnostics.js

@@ -179,8 +179,11 @@ function canonicalDiagnosticValue(value) {
         .map(([key, child]) => [key, canonicalDiagnosticValue(child)]));
 }
 function mutationFingerprint(args) {
+    // A kb_upsert dry run must fingerprint like the write it previews, so
+    // validation-before-upsert pairs the two.
+    const { dryRun: _dryRun, ...payload } = args;
     return createHash("sha256")
-        .update(JSON.stringify(canonicalDiagnosticValue(args)))
+        .update(JSON.stringify(canonicalDiagnosticValue(payload)))
         .digest("hex");
 }
 function appendMutationFields(fields, args) {
@@ -311,7 +314,45 @@ function appendContradictionCheckFields(fields, contradictionCheck) {
         fields.semantic_property_key = propertyKey;
     }
 }
-export function deriveDiagnosticFields(toolName, args, telemetry, result) {
+const MODEL_MODE_OPERATIONS = {
+    analyze: "kb_semantic_advisor",
+    requirement: "kb_model_requirement",
+    predicates: "kb_suggest_predicates",
+};
+const SKILL_ACTION_OPERATIONS = {
+    list: "kb_skills_list",
+    load: "kb_skills_load",
+    read: "kb_skills_read",
+};
+/** Composite tools report diagnostics under the operation they routed to. */
+// implements REQ-kibi-mcp-tool-consolidation
+export function routedOperationName(toolName, args) {
+    if (toolName === "kb_model" && typeof args.mode === "string")
+        return MODEL_MODE_OPERATIONS[args.mode] ?? toolName;
+    if (toolName === "kb_skills" && typeof args.action === "string")
+        return SKILL_ACTION_OPERATIONS[args.action] ?? toolName;
+    if (toolName === "kb_upsert" && args.dryRun === true)
+        return "kb_validate_upsert";
+    return toolName;
+}
+/**
+ * The business arguments the routed operation received: the composite's
+ * selector is dropped, so a usage entry matches the narrow CLI route's entry.
+ */
+// implements REQ-kibi-mcp-tool-consolidation
+export function routedBusinessArgs(toolName, args) {
+    if (routedOperationName(toolName, args) === toolName)
+        return args;
+    const selector = toolName === "kb_model"
+        ? "mode"
+        : toolName === "kb_skills"
+            ? "action"
+            : "dryRun";
+    const { [selector]: _selector, ...rest } = args;
+    return rest;
+}
+export function deriveDiagnosticFields(invokedToolName, args, telemetry, result) {
+    const toolName = routedOperationName(invokedToolName, args);
     const fields = {
         telemetry_status: telemetry ? "provided" : "missing",
     };

package/dist/runtime/mcp-runtime.js

@@ -1,4 +1,31 @@
-import { CapabilityRegistryCache, ensureCapabilityRegistry, resolveBranchAttachment, } from "kibi-runtime";
+import { CapabilityRegistryCache, declaresWriteEffect, detachedHeadWriteRefusal, ensureCapabilityRegistry, resolveBranchAttachment, resolveOperationAttachment, } from "kibi-runtime";
+/**
+ * Branch attachment for one MCP operation. A detached HEAD keeps the exact
+ * contract for writes (refused with the way out) while KB reads attach the
+ * read-only snapshot compiled from the checkout, which the shared session
+ * engine then serves.
+ */
+// implements REQ-branch-store-recovery-v4
+function resolveMcpAttachment(workspaceRoot, spec) {
+    // Synchronous unless HEAD is detached: an attached checkout opens its
+    // operation context without extra event-loop turns.
+    const attachment = resolveBranchAttachment(workspaceRoot);
+    if (!("error" in attachment) || attachment.code !== "DETACHED_HEAD") {
+        return attachment;
+    }
+    if (declaresWriteEffect(spec.effects)) {
+        throw new Error(detachedHeadWriteRefusal(spec.name, workspaceRoot));
+    }
+    if (!spec.effects.includes("kb-read"))
+        return attachment;
+    return resolveOperationAttachment(workspaceRoot, spec).catch((error) => {
+        // Status diagnoses a snapshot that failed to compile instead of failing.
+        if (spec.requiresProlog)
+            throw error;
+        console.warn(`[KIBI-MCP] ${error instanceof Error ? error.message : String(error)}`);
+        return attachment;
+    });
+}
 export function attachedContextWithProlog(withAttachment, prolog) {
     return { ...withAttachment, prolog };
 }
@@ -38,7 +65,8 @@ export function createMcpRuntime(session) {
                 ...(git ? { git } : {}),
                 ...(net ? { net } : {}),
             };
-            const attachment = resolveBranchAttachment(context.workspaceRoot);
+            const resolved = resolveMcpAttachment(context.workspaceRoot, spec);
+            const attachment = resolved instanceof Promise ? await resolved : resolved;
             if (!("error" in attachment) && attachment.migrationRequired) {
                 console.warn(`[KIBI-MCP] Legacy branch attachment: Git '${attachment.gitBranch}' is reading KB '${attachment.kbBranch}'. Run 'kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply'; writes are blocked until then.`);
             }

package/dist/server/docs.js

@@ -36,7 +36,7 @@ function renderToolsDoc() {
     lines.push("");
     lines.push("Modeling note: Kibi has eight core entity types grouped into common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).");
     lines.push("Only strict domain facts (`fact_kind: subject` + `property_value`) participate in contradiction inference; use `flag` for runtime/config gates and `fact_kind: observation` or `meta` for bug/workaround notes.");
-    lines.push("Predicate flow: before writing ontology prose, call `kb_suggest_predicates`; apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
+    lines.push("Predicate flow: before writing ontology prose, call `kb_model` (mode `predicates`); apply a suggested `fact_kind: predicate` via `requires_predicate`, or record the returned `review:ontology-gap` observation when no predicate fits.");
     return lines.join("\n");
 }
 export const PROMPTS = [
@@ -54,9 +54,13 @@ export const PROMPTS = [
             "",
             "Inspect `kb_status.bootstrap` and follow its typed `nextAction`. If infrastructure is missing, run `kibi init` before planning.",
             "",
+            "## Source interview",
+            "",
+            "Before planning, list the knowledge sources you can read (your MCP connectors for issue trackers, wikis, and specs, plus in-repo docs) and ask the user which hold product intent and which are authoritative, supporting, or stale. Read the confirmed sources and pass them as `bootstrapContext.knowledgeSources` with cited `bootstrapContext.intentClaims`. Kibi never contacts those sources itself.",
+            "",
             "## Preview and Approval",
             "",
-            "Call `kb_plan_bootstrap` read-only. Ask only the bounded questions returned when its status is `needs_context`; do not invent a questionnaire.",
+            "Call `kb_plan_bootstrap` read-only. After the source interview, ask only the bounded questions returned when its status is `needs_context`.",
             "",
             "Show the exact returned `structuredContent.plan`, its actions, and canonical hash. Get explicit user approval, then pass that plan object unchanged to `kb_apply_plan`.",
             "",
@@ -75,7 +79,7 @@ export const PROMPTS = [
             "Treat this server as a branch-aware knowledge graph interface for software traceability.",
             "",
             "The server exposes a curated public tool surface for KB operations:",
-            "- `kb_search`: Discovery across metadata and markdown body text",
+            "- `kb_search`: Ask a question or search; returns ranked matches plus an answer layer (governing requirements, linked facts, ADRs, scenarios and tests)",
             "- `kb_query`: Exact lookup of entities by type, ID, tags, or source file",
             "- `kb_status`: Branch, snapshot, and freshness inspection",
             "- `kb_find_gaps`: Bulk missing/present relationship analysis",
@@ -88,7 +92,7 @@ export const PROMPTS = [
             "Core modeling principles:",
             "- Kibi has eight entity types: common authoring (req, scenario, test, fact) and supporting/system (adr, flag, event, symbol).",
             "- Encode requirements as linked facts: `req --constrains--> fact` plus `req --requires_property--> fact`.",
-            "- High-confidence `kb_model_requirement` output is deterministic; `/kibi-bootstrap` bootstrap writes still require preview and explicit approval.",
+            "- High-confidence `kb_model` (mode `requirement`) output is deterministic; `/kibi-bootstrap` bootstrap writes still require preview and explicit approval.",
             "- Low-confidence claims (< 0.7) are downgraded to `observation` facts to prevent false-positive contradictions.",
             "- Only strict domain facts participate in contradiction inference; observation and meta facts are non-blocking notes.",
             "- v1 contradictions are limited to exact-value, boolean/enum, numeric range, and polarity conflicts.",
@@ -112,8 +116,8 @@ export const PROMPTS = [
             "2. **Check schema status**: Call `kb_status` to see if a schema migration is required for the branch KB.",
             "3. **Create-before-link**: Create endpoint entities with `kb_upsert` before linking them.",
             "4. **Validate intent**: If creating links, call `kb_query` for both endpoint IDs first to ensure they exist.",
-            "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model_requirement`).",
-            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_suggest_predicates` before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
+            "5. **Model requirements as facts**: For new/updated reqs, create/reuse fact entities first, then express req semantics with `constrains` + `requires_property` (automated via `kb_model` (mode `requirement`)).",
+            "6. **Suggest predicates before prose**: For ontology-lane requirements, spell out the prose claim and call `kb_model` (mode `predicates`) before writing `fact_kind: observation`. Apply the selected `fact_kind: predicate` applyPlan, then attach the returned `relationshipPlan` as `requires_predicate` while preserving existing req metadata; use the returned `review:ontology-gap` observation when no predicate fits.",
             "7. **Plan repairs**: Requirement `kb_coverage` returns `repairPlan`; require `repairPlan.scope.complete`, apply only a batch whose state is `ready`, and treat every batch as non-auto-applicable guidance.",
             "8. **Mutate sequentially**: Query current endpoints, validate each payload, then call `kb_upsert` one at a time or `kb_delete` for explicit removals. Re-run `kb_coverage` after each batch rather than continuing from a stale plan.",
             "9. **Targeted checks**: Run `kb_check` after meaningful mutations; specify only the rules you need so scoped validation stays fast and skips the full-KB advisory scan.",
@@ -187,7 +191,7 @@ function registerDocResources() {
         '5. `kb_check` with `{ "rules": ["required-fields","no-dangling-refs"] }` for targeted validation; supplying `rules` skips the full-KB advisory scan',
         "",
         "## Model requirements as ontology predicates",
-        '1. Spell out the requirement prose and call `kb_suggest_predicates` with `{ "text": "...", "requirementId": "REQ-..." }`',
+        '1. Spell out the requirement prose and call `kb_model` with `{ "mode": "predicates", "text": "...", "requirementId": "REQ-..." }`',
         "2. If candidates are returned, apply the top or user-selected `structuredContent.applyPlan` to create `fact_kind: predicate`, then attach `structuredContent.relationshipPlan` with `requires_predicate` while preserving existing req metadata",
         "3. If no candidate fits, apply or review the returned `review:ontology-gap` observation instead of silently writing prose",
         "",

package/dist/server/session.js

@@ -20,7 +20,7 @@ import { createRequire } from "node:module";
 import process from "node:process";
 import { EngineClient } from "kibi-runtime";
 import { PrologProcess } from "kibi-runtime";
-import { copyCleanSnapshot, ensureBranchStoreManifest, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, resolveBranchAttachment, } from "kibi-runtime";
+import { copyCleanSnapshot, ensureBranchStoreManifest, getBranchDiagnostic, isValidBranchName, resolveActiveBranch, resolveReadBranchAttachment, } from "kibi-runtime";
 import { getBranchOverride, isMcpDebugEnabled } from "../env.js";
 import { resolveKbPath, resolveWorkspaceRoot } from "../workspace.js";
 import { KbRefreshError, describeBranchKbStamp, readBranchKbStamp, sameBranchKbStamp, } from "./kb-freshness.js";
@@ -32,7 +32,9 @@ const defaultSessionDeps = {
     getBranchDiagnostic,
     isValidBranchName,
     resolveActiveBranch,
-    resolveBranchAttachment,
+    // The session engine serves reads; on a detached HEAD it attaches the
+    // checkout's read-only snapshot, and writes are refused before reaching it.
+    resolveBranchAttachment: resolveReadBranchAttachment,
     resolveKbPath,
     resolveWorkspaceRoot,
 };
@@ -48,7 +50,7 @@ const state = {
     isShuttingDown: false,
     shutdownTimeout: null,
 };
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function getPrologProcess() {
     return state.prologProcess;
 }
@@ -56,11 +58,11 @@ export function getPrologProcess() {
 export function getActiveBranchName() {
     return state.activeBranchName;
 }
-// implements REQ-008
+// implements REQ-mcp-kb-freshness
 export function getAttachedBranchKbPath() {
     return state.attachedBranchKbPath;
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function getIsShuttingDown() {
     return state.isShuttingDown;
 }
@@ -70,7 +72,7 @@ export const inFlightRequests = new Map();
 export function updateAttachedBranchStamp(stamp) {
     state.attachedBranchStamp = stamp;
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function resetSessionStateForTests() {
     state.prologProcess = null;
     state.isInitialized = false;
@@ -87,15 +89,15 @@ export function resetSessionStateForTests() {
     }
 }
 export function _setSessionDepsForTests(
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 overrides) {
     sessionDeps = { ...sessionDeps, ...overrides };
 }
 export function _resetSessionDepsForTests() {
-    // implements REQ-008
+    // implements REQ-core-prolog-process-management
     sessionDeps = { ...defaultSessionDeps };
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export function _setPrologProcessForTests(process) {
     state.prologProcess = process;
 }
@@ -105,7 +107,7 @@ function debugLog(...args) {
     }
 }
 export function ensureBranchKbExists(workspaceRoot, branch) {
-    // implements REQ-008
+    // implements REQ-branch-store-recovery-v4
     if (!sessionDeps.isValidBranchName(branch)) {
         throw new Error(`Invalid branch name: ${branch}`);
     }
@@ -175,7 +177,7 @@ export async function initiateGracefulShutdown(exitCode = 0) {
     // Exit
     process.exit(exitCode);
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 export async function resetProlog(reason) {
     debugLog(`[KIBI-MCP] Resetting Prolog worker: ${reason}`);
     state.prologResetGeneration += 1;
@@ -222,7 +224,7 @@ async function refreshAttachedBranchKbWithRetry(prolog, kbPath, currentStamp, as
 function usesBranchKbPath(kbPath) {
     return (kbPath.includes("/.kb/branches/") || kbPath.includes("\\.kb\\branches\\"));
 }
-// implements REQ-008
+// implements REQ-core-prolog-process-management
 async function ensurePrologUnsafe() {
     const generationAtStart = state.prologResetGeneration;
     const workspaceRoot = sessionDeps.resolveWorkspaceRoot();

package/dist/server/tool-registration.js

@@ -1,5 +1,6 @@
 import { getSpec, statusSpec } from "kibi-runtime";
-import { executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, validateUpsertSpec, } from "kibi-runtime";
+import { MODEL_ROUTES, SKILL_ROUTES, dispatchComposite, executeApplyPlan, executeCompileIntent, executeDelete, executeIngestProof, executeUpsert, } from "kibi-runtime";
+import { OPTIONAL_TOOL_NAMES, enabledOptionalTools } from "../tools-config.js";
 import { startJob } from "./jobs.js";
 // implements REQ-002, REQ-013
 export function registerConfiguredTools(server, runtime, registerTool) {
@@ -21,6 +22,12 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         prolog: prologFor(context),
     });
     const register = ({ name, execute }) => {
+        // Optional tools (kb_sparql_remote) are registered only when enabled;
+        // every other configured tool must have a definition.
+        if (OPTIONAL_TOOL_NAMES.includes(name) &&
+            !runtime.tools.some((tool) => tool.name === name)) {
+            return;
+        }
         const definition = toolDef(name);
         const publicSpec = getSpec(name);
         const spec = {
@@ -55,16 +62,21 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         statusSpec.execute(args, context),
     });
     register({
-        name: "kb_skills_list",
-        execute: async (_context, args) => runtime.handleKbSkillsList(args),
-    });
-    register({
-        name: "kb_skills_load",
-        execute: async (_context, args) => runtime.handleKbSkillsLoad(args),
-    });
-    register({
-        name: "kb_skills_read",
-        execute: async (_context, args) => runtime.handleKbSkillsRead(args),
+        name: "kb_skills",
+        execute: async (context, args) => dispatchComposite("action", {
+            list: {
+                ...SKILL_ROUTES.list,
+                execute: async (input) => runtime.handleKbSkillsList(input),
+            },
+            load: {
+                ...SKILL_ROUTES.load,
+                execute: async (input) => runtime.handleKbSkillsLoad(input),
+            },
+            read: {
+                ...SKILL_ROUTES.read,
+                execute: async (input) => runtime.handleKbSkillsRead(input),
+            },
+        }, args, context),
     });
     register({
         name: "kb_find_gaps",
@@ -83,17 +95,26 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         execute: async (context, args) => runtime.handleSparql(args, context),
     });
     register({
-        name: "kb_semantic_advisor",
-        execute: async (context, args) => runtime.handleKbSemanticAdvisor(args, context),
+        name: "kb_model",
+        execute: async (context, args) => dispatchComposite("mode", {
+            analyze: {
+                ...MODEL_ROUTES.analyze,
+                execute: async (input) => runtime.handleKbSemanticAdvisor(input, context),
+            },
+            requirement: {
+                ...MODEL_ROUTES.requirement,
+                execute: async (input) => runtime.handleKbModelRequirement(prologFor(context), input, withSessionProlog(context)),
+            },
+            predicates: {
+                ...MODEL_ROUTES.predicates,
+                execute: async (input) => runtime.handleKbSuggestPredicates(prologFor(context), input, withSessionProlog(context)),
+            },
+        }, args, context),
     });
     register({
         name: "kb_upsert",
         execute: async (context, args) => executeUpsert(args, withSessionProlog(context)),
     });
-    register({
-        name: "kb_validate_upsert",
-        execute: async (context, args) => validateUpsertSpec.execute(args, withSessionProlog(context)),
-    });
     register({
         name: "kb_delete",
         execute: async (context, args) => executeDelete(args, withSessionProlog(context)),
@@ -102,7 +123,9 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         name: "kb_check",
         execute: async (context, args) => {
             const { async: asyncMode, ...checkArgs } = args;
-            if (asyncMode !== true) {
+            // Without a registered kb_job_status nothing could poll the receipt,
+            // so async falls back to a synchronous check.
+            if (asyncMode !== true || !enabledOptionalTools().has("kb_job_status")) {
                 return runtime.handleKbCheck(prologFor(context), args);
             }
             // Long-KB full checks can exceed the tool timeout. Detach into a job
@@ -115,14 +138,6 @@ export function registerConfiguredTools(server, runtime, registerTool) {
         name: "kb_prepare_impact_review",
         execute: async (context, args) => getSpec("kb_prepare_impact_review").execute(args, context),
     });
-    register({
-        name: "kb_model_requirement",
-        execute: async (context, args) => runtime.handleKbModelRequirement(prologFor(context), args, withSessionProlog(context)),
-    });
-    register({
-        name: "kb_suggest_predicates",
-        execute: async (context, args) => runtime.handleKbSuggestPredicates(prologFor(context), args, withSessionProlog(context)),
-    });
     register({
         name: "kb_plan_bootstrap",
         execute: async (context, args) => runtime.handleKbPlanBootstrap(args, context),

package/dist/server/tools-runtime.js

@@ -25,7 +25,7 @@ const defaultToolsServerDeps = {
 };
 let sessionModulePromise = null;
 const prologPorts = new WeakMap();
-// implements REQ-008
+// implements REQ-002
 export function _setToolsServerDepsForTests(deps, resetPromise = false) {
     defaultToolsServerDeps.getSessionModule =
         deps.getSessionModule ?? defaultToolsServerDeps.getSessionModule;

package/dist/server/tools.js

@@ -16,14 +16,17 @@
  along with this program.  If not, see <https://www.gnu.org/licenses/>.
  */
 import process from "node:process";
-import { executeOperation } from "kibi-runtime";
+import { QUERY_LIMIT_EXCEEDED_CODE, detachedReadOnlyDiagnostic, executeOperation, queryLimitExceededOf, } from "kibi-runtime";
 import { operationData, toKibiResult } from "kibi-runtime";
+import { routedBusinessArgs, routedOperationName } from "../diagnostics.js";
 import { isMcpDebugEnabled } from "../env.js";
+import { enabledOptionalTools } from "../tools-config.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";
+import { WORKSPACE_ROOT_ARGUMENT, getWorkspaceRouter, } from "./workspace-router.js";
 export { jsonSchemaToZod } from "./json-schema-to-zod.js";
 export { _resetSessionModulePromise, _setToolsServerDepsForTests };
 const DEFAULT_TOOL_TIMEOUT_MS = 90_000;
@@ -54,7 +57,7 @@ function withAgentVisibleText(content, data) {
     const text = summary.length > 0 ? `${payload}\n${summary}` : payload;
     return [{ type: "text", text }, ...nonTextParts];
 }
-// implements REQ-008
+// implements REQ-002
 function debugLog(...args) {
     if (isMcpDebugEnabled()) {
         console.error(...args);
@@ -115,23 +118,93 @@ async function withToolTimeout(toolName, operation, onTimeout) {
         }
     }
 }
+/**
+ * A module that vanished after startup means the package was upgraded or
+ * reinstalled under a running server; only a restart loads the new install.
+ */
+function staleInstallHint(error) {
+    const code = error.code;
+    const missingModule = code === "ERR_MODULE_NOT_FOUND" ||
+        code === "MODULE_NOT_FOUND" ||
+        /Cannot find (module|package)/.test(error.message);
+    return missingModule
+        ? " — this Kibi MCP server is running from files that are no longer installed (Kibi was likely upgraded or reinstalled after it started). Restart the Kibi MCP server; the project-local kibi CLI works in the meantime."
+        : "";
+}
+/**
+ * The decision when no workspace router is installed (unit tests, embedded
+ * use): every call is local, and `workspaceRoot` is dropped so handlers never
+ * see a routing-only argument. kb_check keeps it: there it also names the
+ * tree to inspect for impact diagnostics.
+ */
+function localDecision(name, args) {
+    if (!(WORKSPACE_ROOT_ARGUMENT in args) || name === "kb_check") {
+        return { kind: "local", args };
+    }
+    const { [WORKSPACE_ROOT_ARGUMENT]: _ignored, ...rest } = args;
+    return { kind: "local", args: rest };
+}
+/** A result's diagnostics carry a routing or detached-HEAD notice when one applies. */
+function withWorkspaceNotice(envelope, notice) {
+    if (!notice)
+        return envelope;
+    return { ...envelope, diagnostics: [...envelope.diagnostics, notice] };
+}
+/**
+ * Observe the context an operation opens so its envelope can say when a
+ * detached HEAD answered from the read-only snapshot, and which store.
+ */
+// implements REQ-branch-store-recovery-v4
+function observeDetachedReads(base) {
+    let notice;
+    return {
+        runtime: {
+            // Read the attachment at close (success or error) so opening the
+            // context costs no extra event-loop turn.
+            open: (spec, options) => base.open(spec, options),
+            afterSuccess: (spec, context) => base.afterSuccess(spec, context),
+            close: (context, outcome) => {
+                notice = detachedReadOnlyDiagnostic(context.branchAttachment);
+                return base.close(context, outcome);
+            },
+        },
+        notice: () => notice,
+    };
+}
 // 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, spec, annotations, outputSchema) {
-    const wrappedHandler = async (args) => {
+    const wrappedHandler = async (rawArgs) => {
         const startedAt = new Date();
         const diagnosticModeEnabled = runtime.diagnosticModeEnabled();
-        const { businessArgs, telemetry } = diagnosticModeEnabled
-            ? runtime.extractToolCallPayload(args)
-            : { businessArgs: args, telemetry: null };
+        let args = rawArgs;
+        let workspaceNotice;
+        let businessArgs = rawArgs;
+        let telemetry = null;
         try {
             // Validate that args is a valid object
             if (typeof args !== "object" || args === null) {
                 throw new Error(`Invalid arguments for tool ${name}: expected object, got ${typeof args}`);
             }
+            // Answer from the workspace the caller is working in. A call routed to
+            // another workspace's kibi-mcp returns that server's result as is; the
+            // child logs its own usage and the parent records nothing for it.
+            // Without a router the decision is synchronous, so a plain call reaches
+            // its handler without an extra microtask.
+            const router = getWorkspaceRouter();
+            const routing = router
+                ? await router.route(name, args)
+                : localDecision(name, args);
+            if (routing.kind === "remote")
+                return routing.result;
+            args = routing.args;
+            workspaceNotice = routing.notice;
+            ({ businessArgs, telemetry } = diagnosticModeEnabled
+                ? runtime.extractToolCallPayload(args)
+                : { businessArgs: args, telemetry: null });
             // Check if shutting down before processing
             if (await runtime.isShuttingDown()) {
                 throw new Error(`Tool ${name} rejected: server is shutting down`);
@@ -154,7 +227,8 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                 requiresProlog: false,
                 execute: async (input, _context) => handler(input),
             };
-            const handlerPromise = executeOperation(runtime.operationRuntime, operationSpec, businessArgs, { signal: controller.signal });
+            const observed = observeDetachedReads(runtime.operationRuntime);
+            const handlerPromise = executeOperation(observed.runtime, operationSpec, businessArgs, { signal: controller.signal });
             trackedRequests.set(requestId, handlerPromise);
             let resetAttempted = false;
             let resetSucceeded = false;
@@ -189,15 +263,18 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     }
                 });
                 const data = operationData(result);
-                const envelope = toKibiResult(operationSpec, data);
+                const envelope = withWorkspaceNotice(withWorkspaceNotice(toKibiResult(operationSpec, data), workspaceNotice), observed.notice());
                 // Log usage in diagnostic mode
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticSuccessUsage({
                         runtime,
-                        toolName: name,
+                        // Usage evidence records the routed operation (kb_model mode
+                        // predicates logs as kb_suggest_predicates) so telemetry
+                        // acceptance keeps reading one operation per entry.
+                        toolName: routedOperationName(name, businessArgs),
                         requestId,
                         args,
-                        businessArgs,
+                        businessArgs: routedBusinessArgs(name, businessArgs),
                         telemetry,
                         startedAt,
                         result: envelope,
@@ -227,10 +304,13 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                 if (diagnosticModeEnabled) {
                     await appendDiagnosticErrorUsage({
                         runtime,
-                        toolName: name,
+                        // Usage evidence records the routed operation (kb_model mode
+                        // predicates logs as kb_suggest_predicates) so telemetry
+                        // acceptance keeps reading one operation per entry.
+                        toolName: routedOperationName(name, businessArgs),
                         requestId,
                         args,
-                        businessArgs,
+                        businessArgs: routedBusinessArgs(name, businessArgs),
                         telemetry,
                         startedAt,
                         error,
@@ -238,7 +318,9 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                     });
                 }
                 if (isToolTimeoutError(error) &&
-                    isMutationEffect(operationSpec.effects)) {
+                    isMutationEffect(operationSpec.effects) &&
+                    // A kb_upsert dry run writes nothing, so its outcome is known.
+                    !(name === "kb_upsert" && businessArgs.dryRun === true)) {
                     const recoveryActions = [
                         {
                             operation: "kb_status",
@@ -279,6 +361,25 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
                         structuredContent: envelope,
                     };
                 }
+                const limitExceeded = queryLimitExceededOf(error);
+                if (error instanceof Error && limitExceeded !== null) {
+                    // A read stopped at its engine limit has no answer: say which
+                    // limit stopped it rather than failing like a broken tool.
+                    const envelope = withWorkspaceNotice(withWorkspaceNotice(toKibiResult(operationSpec, null, {
+                        status: "error",
+                        error: {
+                            code: QUERY_LIMIT_EXCEEDED_CODE,
+                            message: error.message,
+                            retryable: false,
+                            details: { limitExceeded },
+                        },
+                    }), workspaceNotice), observed.notice());
+                    return {
+                        content: [{ type: "text", text: JSON.stringify(envelope) }],
+                        structuredContent: envelope,
+                        isError: true,
+                    };
+                }
                 throw error;
             }
             finally {
@@ -292,7 +393,7 @@ runtime = DEFAULT_TOOLS_RUNTIME, spec, annotations, outputSchema) {
             if (err.stack) {
                 debugLog(`[KIBI-MCP] Tool ${name} stack:`, err.stack);
             }
-            throw new Error(`Tool ${name} failed: ${err.message}`, { cause: err });
+            throw new Error(`Tool ${name} failed: ${err.message}${staleInstallHint(err)}`, { cause: err });
         }
     };
     server.registerTool(name, {
@@ -307,7 +408,9 @@ export function registerAllTools(server,
 // INTENTIONAL: same generic bridge cast as addTool — see comment there.
 runtime = DEFAULT_TOOLS_RUNTIME) {
     registerConfiguredTools(server, runtime, addTool);
-    registerJobStatusTool(server);
+    if (enabledOptionalTools().has("kb_job_status")) {
+        registerJobStatusTool(server);
+    }
 }
 /**
  * kb_job_status polls background jobs started by long-running operations