kibi-cli 1.0.1 → 2.1.0

package/dist/engine.js

@@ -14,8 +14,9 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { PrologProcess, resolveKbPlPath } from "./prolog.js";
 import { parseEntityFromList, parseListOfLists } from "./prolog/codec.js";
+import { retryAttachAfterBreakingStaleLock } from "./prolog/store-lock.js";
 import { isValidBranchName } from "./utils/branch-resolver.js";
-import { ensureBranchStoreManifest } from "./utils/branch-store-locator.js";
+import { branchStorePath, ensureBranchStoreManifest, } from "./utils/branch-store-locator.js";
 export const ENGINE_PROTOCOL_VERSION = 1;
 export const ENGINE_IDLE_TIMEOUT_MS = 10 * 60 * 1000;
 export const ENGINE_PACKAGE_VERSIONS = process.env.KIBI_PACKAGE_VERSIONS ?? "unknown";
@@ -23,12 +24,95 @@ const ENGINE_QUERY_CACHE_MAX_ENTRIES = 128;
 const ENGINE_QUERY_CACHE_MAX_RESULT_BYTES = 8 * 1024 * 1024;
 const ENGINE_FRESHNESS_CACHE_MS = 100;
 const ENGINE_PUBLICATION_LOCK_STALE_MS = 5_000;
+const ENGINE_WORKSPACE_WATCHDOG_MS = 30_000;
+export function requestEngineSignalShutdown(shutdown) {
+    return () => {
+        void shutdown();
+    };
+}
+export function readJournalGeneration(branchPath) {
+    // implements REQ-core-journaled-engine-persistence
+    const currentPath = path.join(branchPath, "CURRENT");
+    if (!existsSync(currentPath))
+        return "";
+    return readFileSync(currentPath, "utf8").trim();
+}
+export function readEngineAttachmentIdentity(branchPath) {
+    // implements REQ-core-journaled-engine-persistence
+    if (!existsSync(branchPath))
+        return null;
+    const stats = statSync(branchPath);
+    let resolved = path.resolve(branchPath);
+    try {
+        resolved = realpathSync(branchPath);
+    }
+    catch {
+        // The live path may be replaced between stat and realpath.
+    }
+    return {
+        path: resolved,
+        generation: readJournalGeneration(branchPath),
+        dev: stats.dev,
+        ino: stats.ino,
+    };
+}
+export function parseEngineAttachmentIdentity(statusJson) {
+    // implements REQ-core-journaled-engine-persistence
+    if (statusJson === undefined)
+        return null;
+    try {
+        const decoded = JSON.parse(JSON.parse(statusJson));
+        if (typeof decoded.attachedPath !== "string" ||
+            typeof decoded.attachedGeneration !== "string" ||
+            typeof decoded.attachedDev !== "number" ||
+            typeof decoded.attachedIno !== "number") {
+            return null;
+        }
+        return {
+            path: decoded.attachedPath,
+            generation: decoded.attachedGeneration,
+            dev: decoded.attachedDev,
+            ino: decoded.attachedIno,
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function engineAttachmentsMatch(expected, attached) {
+    // implements REQ-core-journaled-engine-persistence
+    if (expected === null || attached === null)
+        return false;
+    if (expected.path !== attached.path)
+        return false;
+    if (expected.ino !== 0 && attached.ino !== 0) {
+        return expected.dev === attached.dev && expected.ino === attached.ino;
+    }
+    return (expected.generation.length > 0 &&
+        expected.generation === attached.generation);
+}
+export function formatEngineAttachmentMismatch(operation, expected, attached) {
+    // implements REQ-core-journaled-engine-persistence
+    return [
+        `operation=${operation}`,
+        `branchStore=${expected?.path ?? "missing"}`,
+        `expectedGeneration=${expected?.generation || "missing"}`,
+        `attachedPath=${attached?.path ?? "missing"}`,
+        `attachedGeneration=${attached?.generation || "missing"}`,
+    ].join(" ");
+}
 function engineIdleTimeoutMs() {
     const configured = Number.parseInt(process.env.KIBI_ENGINE_IDLE_TIMEOUT_MS ?? "", 10);
     return Number.isFinite(configured) && configured >= 100
         ? configured
         : ENGINE_IDLE_TIMEOUT_MS;
 }
+function engineWorkspaceWatchdogMs() {
+    const configured = Number.parseInt(process.env.KIBI_ENGINE_WORKSPACE_WATCHDOG_MS ?? "", 10);
+    return Number.isFinite(configured) && configured >= 100
+        ? configured
+        : ENGINE_WORKSPACE_WATCHDOG_MS;
+}
 function quoteProlog(value) {
     return value.replaceAll("'", "''");
 }
@@ -162,7 +246,7 @@ function parseFrames(buffer, onFrame) {
     }
     return buffer.subarray(cursor);
 }
-function runtimeDirectory() {
+export function runtimeDirectory() {
     const configured = process.env.KIBI_RUNTIME_DIR ??
         process.env.XDG_RUNTIME_DIR ??
         path.join(os.tmpdir(), "kibi-runtime");
@@ -577,6 +661,7 @@ export class EngineClient {
     pending = new Map();
     requestTail = Promise.resolve();
     lastResult = null;
+    replacingStaleDaemon = false;
     constructor(options) {
         if (!isValidBranchName(options.branch)) {
             throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
@@ -593,6 +678,13 @@ export class EngineClient {
         this.allowPublicationLock = options.allowPublicationLock ?? false;
     }
     async start(allowSpawn = true) {
+        const wasConnected = this.socket !== null && !this.socket.destroyed;
+        await this.connect(allowSpawn);
+        if (!wasConnected && this.socket !== null) {
+            await this.reconcileAttachment();
+        }
+    }
+    async connect(allowSpawn = true) {
         if (this.socket !== null && !this.socket.destroyed)
             return;
         const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
@@ -691,16 +783,26 @@ export class EngineClient {
         socket.on("close", () => {
             this.socket = null;
             const error = new Error("Kibi engine connection closed");
-            for (const pending of this.pending.values())
-                pending.reject(error);
+            for (const pending of this.pending.values()) {
+                this.settlePending(pending, () => pending.reject(error));
+            }
             this.pending.clear();
         });
         socket.on("error", (error) => {
-            for (const pending of this.pending.values())
-                pending.reject(error);
+            for (const pending of this.pending.values()) {
+                this.settlePending(pending, () => pending.reject(error));
+            }
             this.pending.clear();
         });
     }
+    /** Settle a pending RPC at most once (abort vs response race-safe). */
+    settlePending(pending, settle) {
+        if (pending.settled)
+            return false;
+        pending.settled = true;
+        settle();
+        return true;
+    }
     handleResponse(value) {
         if (value === null || typeof value !== "object")
             return;
@@ -711,55 +813,20 @@ export class EngineClient {
         if (!pending)
             return;
         this.pending.delete(response.id);
-        if (response.ok)
-            pending.resolve(response.result);
-        else
-            pending.reject(new Error(response.error ?? "Kibi engine request failed"));
+        if (response.ok) {
+            this.settlePending(pending, () => pending.resolve(response.result));
+        }
+        else {
+            this.settlePending(pending, () => pending.reject(new Error(response.error ?? "Kibi engine request failed")));
+        }
     }
     async request(request, signal) {
+        // Connect/reconcile before taking the client queue. Holding requestTail
+        // across start()→reconcileAttachment()→queryStatusJson() deadlocks because
+        // that nested status RPC needs the same queue (see command-first clients).
         await this.start();
-        const socket = this.socket;
-        if (socket === null || socket.destroyed)
-            throw new Error("Kibi engine is not connected");
-        const id = ++this.requestId;
-        const result = new Promise((resolve, reject) => {
-            this.pending.set(id, {
-                resolve: resolve,
-                reject,
-            });
-            try {
-                socket.write(frame({
-                    ...request,
-                    id,
-                    protocolVersion: ENGINE_PROTOCOL_VERSION,
-                    packageVersions: ENGINE_PACKAGE_VERSIONS,
-                    workspaceRoot: this.workspaceRoot,
-                    branch: this.branch,
-                }));
-            }
-            catch (error) {
-                this.pending.delete(id);
-                reject(error instanceof Error ? error : new Error(String(error)));
-                return;
-            }
-            if (signal !== undefined) {
-                const abort = () => {
-                    if (!this.pending.has(id))
-                        return;
-                    this.pending.delete(id);
-                    this.cancel(id);
-                    reject(new Error("Kibi engine request cancelled"));
-                };
-                if (signal.aborted)
-                    abort();
-                else
-                    signal.addEventListener("abort", abort, { once: true });
-            }
-        });
-        return result;
-    }
-    async query(goal, signal) {
-        let result;
+        // Serialize query and command frames on one socket so concurrent MCP
+        // traffic cannot interleave length-prefixed writes/responses.
         const previous = this.requestTail;
         let release;
         this.requestTail = new Promise((resolve) => {
@@ -767,14 +834,59 @@ export class EngineClient {
         });
         await previous;
         try {
-            result = await this.request({ method: "query", goal }, signal);
-            this.lastResult = result;
-            return result;
+            const socket = this.socket;
+            if (socket === null || socket.destroyed)
+                throw new Error("Kibi engine is not connected");
+            const id = ++this.requestId;
+            return await new Promise((resolve, reject) => {
+                this.pending.set(id, {
+                    resolve: resolve,
+                    reject,
+                    settled: false,
+                });
+                try {
+                    socket.write(frame({
+                        ...request,
+                        id,
+                        protocolVersion: ENGINE_PROTOCOL_VERSION,
+                        packageVersions: ENGINE_PACKAGE_VERSIONS,
+                        workspaceRoot: this.workspaceRoot,
+                        branch: this.branch,
+                    }));
+                }
+                catch (error) {
+                    const pending = this.pending.get(id);
+                    this.pending.delete(id);
+                    if (pending) {
+                        this.settlePending(pending, () => reject(error instanceof Error ? error : new Error(String(error))));
+                    }
+                    return;
+                }
+                if (signal !== undefined) {
+                    const abort = () => {
+                        const pending = this.pending.get(id);
+                        if (!pending || pending.settled)
+                            return;
+                        this.pending.delete(id);
+                        this.cancel(id);
+                        this.settlePending(pending, () => reject(new Error("Kibi engine request cancelled")));
+                    };
+                    if (signal.aborted)
+                        abort();
+                    else
+                        signal.addEventListener("abort", abort, { once: true });
+                }
+            });
         }
         finally {
             release();
         }
     }
+    async query(goal, signal) {
+        const result = await this.request({ method: "query", goal }, signal);
+        this.lastResult = result;
+        return result;
+    }
     /** Execute a versioned, goal-free engine command. Raw query remains private
      * compatibility traffic for the in-process Prolog adapter only. */
     async command(command, signal) {
@@ -860,8 +972,8 @@ export class EngineClient {
     async checkpoint() {
         return this.command({ version: 1, kind: "checkpoint" });
     }
-    async queryStatusJson() {
-        return this.command({ version: 1, kind: "status" });
+    async queryStatusJson(signal) {
+        return this.command({ version: 1, kind: "status" }, signal);
     }
     async compact() {
         return this.command({ version: 1, kind: "compact" });
@@ -878,27 +990,36 @@ export class EngineClient {
     isRunning() {
         return this.socket !== null && !this.socket.destroyed;
     }
-    getPid() {
-        const pidPath = enginePidPath(this.workspaceRoot, this.branch);
+    async readAttachedIdentity() {
+        const status = await this.queryStatusJson();
+        if (!status.success)
+            return null;
+        return parseEngineAttachmentIdentity(status.bindings.JsonString);
+    }
+    async reconcileAttachment() {
+        if (this.replacingStaleDaemon || this.socket === null)
+            return;
+        const livePath = branchStorePath(this.workspaceRoot, this.branch);
+        const expected = readEngineAttachmentIdentity(livePath);
+        const attached = await this.readAttachedIdentity();
+        if (engineAttachmentsMatch(expected, attached))
+            return;
+        this.replacingStaleDaemon = true;
         try {
-            return Number.parseInt(readFileSync(pidPath, "utf8").trim(), 10) || 0;
+            await this.shutdownConnectedDaemon();
+            await this.connect(true);
+            const live = readEngineAttachmentIdentity(livePath);
+            const retried = await this.readAttachedIdentity();
+            if (!engineAttachmentsMatch(live, retried)) {
+                throw new Error(`Kibi engine is attached to a stale branch generation: ${formatEngineAttachmentMismatch("attachment-handshake", live, retried)}`);
+            }
         }
-        catch {
-            return 0;
+        finally {
+            this.replacingStaleDaemon = false;
         }
     }
-    async stop(startIfMissing = true) {
+    async shutdownConnectedDaemon() {
         const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
-        if (!this.isRunning()) {
-            try {
-                await this.start(startIfMissing);
-            }
-            catch {
-                if (!startIfMissing)
-                    return;
-                throw new Error("Unable to start Kibi engine for stop request");
-            }
-        }
         if (!this.isRunning()) {
             if (existsSync(socketPath)) {
                 throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
@@ -914,9 +1035,6 @@ export class EngineClient {
         }
         this.socket?.destroy();
         this.socket = null;
-        // The daemon acknowledges stop before its SWI child has flushed and the
-        // listening socket has closed. Do not let a following auto-start attach to
-        // that half-shutdown process.
         const deadline = Date.now() + 5_000;
         while (existsSync(socketPath) && Date.now() < deadline) {
             await new Promise((resolve) => setTimeout(resolve, 25));
@@ -926,6 +1044,35 @@ export class EngineClient {
             throw new Error(`Kibi engine did not stop within 5 seconds${detail}`);
         }
     }
+    getPid() {
+        const pidPath = enginePidPath(this.workspaceRoot, this.branch);
+        try {
+            return Number.parseInt(readFileSync(pidPath, "utf8").trim(), 10) || 0;
+        }
+        catch {
+            return 0;
+        }
+    }
+    async stop(startIfMissing = true) {
+        const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+        if (!this.isRunning()) {
+            try {
+                await this.connect(startIfMissing);
+            }
+            catch {
+                if (!startIfMissing)
+                    return;
+                throw new Error("Unable to start Kibi engine for stop request");
+            }
+        }
+        if (!this.isRunning()) {
+            if (existsSync(socketPath)) {
+                throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
+            }
+            return;
+        }
+        await this.shutdownConnectedDaemon();
+    }
     async terminate() {
         // Closing a client connection releases the engine; the daemon remains
         // available for other operations until its idle timeout expires.
@@ -1149,25 +1296,78 @@ export async function runEngineDaemon(options) {
     const prolog = new PrologProcess({ timeout: 120_000, oneShot: false });
     await prolog.start();
     const attached = await prolog.query(`kb_attach('${quoteProlog(branchPath)}')`);
-    if (!attached.success)
-        throw new Error(attached.error ?? "Failed to attach branch KB");
-    const statusModulePath = path.join(path.dirname(resolveKbPlPath()), "status.pl");
-    const statusLoaded = await prolog.query(`use_module('${quoteProlog(statusModulePath.replaceAll("\\", "/"))}')`);
-    if (!statusLoaded.success) {
-        throw new Error(statusLoaded.error ?? "Failed to load Kibi status module");
+    if (!attached.success) {
+        // The daemon hosts the branch store for every later request, so a
+        // store-locked startup with a provably dead holder is auto-healed here
+        // exactly like the CLI runtime path; live holders abort the startup
+        // with the holder identity surfaced.
+        const recovered = await retryAttachAfterBreakingStaleLock(prolog, branchPath, attached);
+        if (!recovered.success)
+            throw new Error(recovered.error ?? "Failed to attach branch KB");
+    }
+    const attachedIdentity = readEngineAttachmentIdentity(branchPath);
+    const coreModuleDir = path.dirname(resolveKbPlPath());
+    for (const [fileName, label] of [
+        ["status.pl", "status"],
+        ["discovery.pl", "discovery"],
+    ]) {
+        const modulePath = path.join(coreModuleDir, fileName);
+        const loaded = await prolog.query(`use_module('${quoteProlog(modulePath.replaceAll("\\", "/"))}')`);
+        if (!loaded.success) {
+            throw new Error(loaded.error ?? `Failed to load Kibi ${label} module`);
+        }
     }
     mkdirSync(path.dirname(options.socketPath), { recursive: true, mode: 0o700 });
     if (existsSync(options.socketPath)) {
+        const isLivePeerSignal = (error) => {
+            if (error && typeof error === "object") {
+                const code = "code" in error ? String(error.code) : "";
+                if (code === "EPIPE" || code === "ECONNRESET")
+                    return true;
+                const errno = "errno" in error
+                    ? Number(error.errno)
+                    : Number.NaN;
+                // POSIX EPIPE
+                if (errno === -32)
+                    return true;
+            }
+            const message = error instanceof Error ? error.message : String(error);
+            return /\bEPIPE\b|\bECONNRESET\b|broken pipe/i.test(message);
+        };
         let live = false;
         try {
             const existing = await connectSocket(options.socketPath, 100);
-            existing.destroy();
+            // Keep a permanent error sink. Bun 1.4 can surface write EPIPE from
+            // teardown into the caller promise on some CI runners, replacing the
+            // intended live-listener error.
+            existing.on("error", () => undefined);
             live = true;
+            try {
+                existing.destroy();
+            }
+            catch {
+                // Ignore destroy races; live detection already succeeded.
+            }
+            existing.unref?.();
         }
-        catch {
-            // A refused connection means this is a stale filesystem socket.
+        catch (error) {
+            // Bun 1.4 can reject the probe with EPIPE/ECONNRESET against a live
+            // unix listener instead of resolving connect.
+            if (isLivePeerSignal(error)) {
+                live = true;
+            }
+            // Otherwise a refused connection means a stale filesystem socket.
         }
         if (live) {
+            try {
+                await prolog.terminate();
+            }
+            catch (error) {
+                // Best-effort cleanup; Bun may surface late EPIPE here too.
+                if (!isLivePeerSignal(error)) {
+                    // Ignore non-EPIPE terminate failures.
+                }
+            }
             throw new Error(`A Kibi engine is already listening at ${options.socketPath}`);
         }
         try {
@@ -1185,7 +1385,6 @@ export async function runEngineDaemon(options) {
     let idleCompactionQueued = false;
     const queryCache = new Map();
     let freshnessCache = null;
-    const cancelledRequests = new Set();
     const clients = new Set();
     let shuttingDown = false;
     const exactBranchStatus = (result) => {
@@ -1195,6 +1394,12 @@ export async function runEngineDaemon(options) {
         try {
             const decoded = JSON.parse(JSON.parse(result.bindings.JsonString));
             decoded.branch = options.branch;
+            if (attachedIdentity !== null) {
+                decoded.attachedPath = attachedIdentity.path;
+                decoded.attachedGeneration = attachedIdentity.generation;
+                decoded.attachedDev = attachedIdentity.dev;
+                decoded.attachedIno = attachedIdentity.ino;
+            }
             return {
                 ...result,
                 bindings: {
@@ -1207,6 +1412,27 @@ export async function runEngineDaemon(options) {
             return result;
         }
     };
+    // A daemon whose workspace vanished (git worktree remove --force, deleted
+    // checkout) can never serve a request again, but it would keep holding the
+    // branch-store lock and wedge every later operation behind an opaque
+    // "KB locked". Detect the loss and shut down cleanly instead.
+    let workspaceMissingStreak = 0;
+    const workspaceWatchdog = setInterval(() => {
+        if (shuttingDown)
+            return;
+        // Two consecutive misses before giving up: a transient blip (slow
+        // rename, network mount hiccup) must not stop a healthy daemon.
+        if (!existsSync(options.workspaceRoot)) {
+            workspaceMissingStreak += 1;
+            if (workspaceMissingStreak < 2)
+                return;
+            console.error(`[KIBI] workspace ${options.workspaceRoot} no longer exists; stopping engine`);
+            void shutdown();
+            return;
+        }
+        workspaceMissingStreak = 0;
+    }, engineWorkspaceWatchdogMs());
+    workspaceWatchdog.unref();
     const scheduleIdleExit = () => {
         if (activeClients > 0)
             return;
@@ -1230,7 +1456,7 @@ export async function runEngineDaemon(options) {
                 void shutdown();
         }, engineIdleTimeoutMs());
     };
-    const handle = async (request) => {
+    const handle = async (request, cancelledRequests) => {
         if (request.protocolVersion !== ENGINE_PROTOCOL_VERSION) {
             throw new Error(`Kibi engine protocol mismatch: client=${request.protocolVersion ?? "missing"}, server=${ENGINE_PROTOCOL_VERSION}`);
         }
@@ -1493,6 +1719,13 @@ export async function runEngineDaemon(options) {
                 setImmediate(() => void shutdown());
                 return { stopped: true };
             case "cancel":
+                // Best-effort: marks the id so a *queued* request on this connection
+                // is skipped before handle(). A request already inside
+                // `await prolog.query(...)` cannot be interrupted without redesigning
+                // SWI interactive cancellation; the client still rejects locally on
+                // AbortSignal, but the daemon queue remains occupied until that Prolog
+                // call returns. Cancel marks are per-connection. See
+                // docs/mcp-reference.md ("Engine cancellation limits").
                 if (typeof request.cancelOf === "number") {
                     cancelledRequests.add(request.cancelOf);
                 }
@@ -1507,6 +1740,7 @@ export async function runEngineDaemon(options) {
         process.off("SIGINT", requestSignalShutdown);
         if (idleTimer)
             clearTimeout(idleTimer);
+        clearInterval(workspaceWatchdog);
         const saved = await prolog.query("kb_save").catch(() => null);
         if (saved?.success) {
             try {
@@ -1545,14 +1779,15 @@ export async function runEngineDaemon(options) {
     // Detached engines must cross the same durability boundary when a service
     // manager or a test harness terminates them as they do for an RPC stop.
     // implements REQ-test-journaled-engine-harness
-    const requestSignalShutdown = () => {
-        void shutdown();
-    };
+    const requestSignalShutdown = requestEngineSignalShutdown(shutdown);
     process.once("SIGTERM", requestSignalShutdown);
     process.once("SIGINT", requestSignalShutdown);
     server.on("connection", (socket) => {
         clients.add(socket);
         activeClients += 1;
+        // Request ids are per-connection. Cancel marks must not be daemon-global
+        // or Client B's id=1 is poisoned by Client A's cancelOf=1.
+        const cancelledRequests = new Set();
         let buffer = Buffer.alloc(0);
         socket.on("data", (chunk) => {
             try {
@@ -1575,7 +1810,7 @@ export async function runEngineDaemon(options) {
                             return;
                         }
                         try {
-                            const result = await handle(request);
+                            const result = await handle(request, cancelledRequests);
                             writeSocketFrame(socket, {
                                 id: request.id,
                                 ok: true,
@@ -1591,6 +1826,11 @@ export async function runEngineDaemon(options) {
                                 serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
                             });
                         }
+                        finally {
+                            // Drop stale cancel marks for in-flight goals that still ran
+                            // to completion after cancelOf (SWI cannot interrupt them).
+                            cancelledRequests.delete(request.id);
+                        }
                     })
                         .catch(() => undefined);
                 });