kibi-cli 2.1.0 → 2.3.0

package/dist/engine.js

@@ -6,20 +6,34 @@
  * the local socket; Prolog itself never crosses the process boundary.
  */
 import { spawn } from "node:child_process";
-import { createHash } from "node:crypto";
-import { chmodSync, closeSync, existsSync, fsyncSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
+import { createHash, randomUUID } from "node:crypto";
+import { chmodSync, closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, statSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as net from "node:net";
 import * as os from "node:os";
 import * as path from "node:path";
+import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
+import { writePerformanceTraceEvent } from "./performance-trace.js";
 import { PrologProcess, resolveKbPlPath } from "./prolog.js";
 import { parseEntityFromList, parseListOfLists } from "./prolog/codec.js";
 import { retryAttachAfterBreakingStaleLock } from "./prolog/store-lock.js";
+import { resolveSwipl, swiplIdentity } from "./prolog/swipl-resolver.js";
+import { queryEntityChunks } from "./public/operations/discovery-entities.js";
 import { isValidBranchName } from "./utils/branch-resolver.js";
 import { branchStorePath, ensureBranchStoreManifest, } from "./utils/branch-store-locator.js";
+import { canonicalFilesystemPath } from "./utils/canonical-path.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";
+/**
+ * Identity of the SWI-Prolog this process would launch (`<bin>@<version>`).
+ * The daemon and every client compare it; a daemon running a different
+ * resolved Prolog is replaced, never reused.
+ */
+// implements REQ-prolog-daemon-runtime-identity
+export function engineSwiplIdentity() {
+    return swiplIdentity(resolveSwipl());
+}
 const ENGINE_QUERY_CACHE_MAX_ENTRIES = 128;
 const ENGINE_QUERY_CACHE_MAX_RESULT_BYTES = 8 * 1024 * 1024;
 const ENGINE_FRESHNESS_CACHE_MS = 100;
@@ -219,11 +233,19 @@ function frame(value) {
     header.writeUInt32BE(payload.byteLength, 0);
     return Buffer.concat([header, payload]);
 }
+/**
+ * Swallow a write failure for a peer that is already gone.
+ *
+ * A socket write reports EPIPE/ECONNRESET asynchronously, so a surrounding
+ * try/catch cannot see it and Node raises it as an unhandled error. Passing a
+ * callback keeps the failure local to this write.
+ */
+function ignoreWriteFailure() { }
 function writeSocketFrame(socket, value) {
     if (socket.destroyed || !socket.writable)
         return;
     try {
-        socket.write(frame(value));
+        socket.write(frame(value), ignoreWriteFailure);
     }
     catch {
         // A client may disconnect while a queued request is finishing. The
@@ -250,17 +272,75 @@ export function runtimeDirectory() {
     const configured = process.env.KIBI_RUNTIME_DIR ??
         process.env.XDG_RUNTIME_DIR ??
         path.join(os.tmpdir(), "kibi-runtime");
-    const candidates = [configured, path.join(os.tmpdir(), "kibi-runtime")];
+    // Windows named pipes have no Unix socket pathname budget. Preserve its
+    // filesystem location policy for the associated pid files.
+    if (process.platform === "win32") {
+        for (const candidate of [
+            configured,
+            path.join(os.tmpdir(), "kibi-runtime"),
+        ]) {
+            try {
+                mkdirSync(candidate, { recursive: true, mode: 0o700 });
+                const probe = path.join(candidate, `.kibi-write-${process.pid}`);
+                writeFileSync(probe, "", { mode: 0o600 });
+                unlinkSync(probe);
+                return candidate;
+            }
+            catch {
+                // Try the existing system-temp fallback.
+            }
+        }
+        throw new Error("Unable to create a writable Kibi engine runtime directory");
+    }
+    const euid = process.geteuid?.();
+    if (euid === undefined)
+        throw new Error("Kibi engine runtime euid unavailable");
+    let configuredIdentity;
+    try {
+        configuredIdentity = canonicalFilesystemPath(configured);
+    }
+    catch {
+        // An inaccessible or dangling configured path remains a distinct identity;
+        // it is never accepted as the socket directory below.
+        configuredIdentity = path.resolve(configured);
+    }
+    const configuredKey = createHash("sha256")
+        .update(configuredIdentity)
+        .digest("hex")
+        .slice(0, 32);
+    const candidates = [
+        configured,
+        path.join("/tmp", `kb-${euid}-${configuredKey}`),
+    ];
+    const maximumBytes = process.platform === "linux" ? 107 : 103;
+    const socketName = `kibi-${"0".repeat(32)}.sock`;
     for (const candidate of candidates) {
         try {
+            try {
+                if (lstatSync(candidate).isSymbolicLink())
+                    continue;
+            }
+            catch (error) {
+                if (error.code !== "ENOENT")
+                    throw error;
+            }
             mkdirSync(candidate, { recursive: true, mode: 0o700 });
+            const directory = lstatSync(candidate);
+            if (!directory.isDirectory() ||
+                directory.uid !== euid ||
+                (directory.mode & 0o077) !== 0)
+                continue;
+            const canonical = canonicalFilesystemPath(candidate);
+            if (Buffer.byteLength(path.join(canonical, socketName), "utf8") >
+                maximumBytes)
+                continue;
             // XDG_RUNTIME_DIR can exist but be mounted read-only (for example in a
             // constrained container). Probe the directory before using it for the
             // socket, start lock, and pid files so auto-start fails over cleanly.
-            const probe = path.join(candidate, `.kibi-write-${process.pid}`);
-            writeFileSync(probe, "", { mode: 0o600 });
+            const probe = path.join(canonical, `.kibi-write-${randomUUID()}`);
+            writeFileSync(probe, "", { mode: 0o600, flag: "wx" });
             unlinkSync(probe);
-            return candidate;
+            return canonical;
         }
         catch {
             // Try the private system-temp fallback below.
@@ -318,18 +398,11 @@ export function fsyncJournaledBranchStore(branchPath) {
 }
 // implements REQ-core-journaled-engine-persistence
 export function engineSocketPath(workspaceRoot, branch) {
-    const canonicalRoot = (() => {
-        try {
-            return realpathSync(workspaceRoot);
-        }
-        catch {
-            return path.resolve(workspaceRoot);
-        }
-    })();
+    const canonicalRoot = canonicalFilesystemPath(workspaceRoot);
     const key = createHash("sha256")
         .update(`${canonicalRoot}\0${branch}`)
-        // 128 bits keeps collision risk negligible while staying below the
-        // roughly 108-byte sockaddr_un limit even in a nested XDG runtime path.
+        // Retain 128 bits of workspace/branch identity; runtimeDirectory budgets
+        // the complete pathname rather than shortening this identity.
         .digest("hex")
         .slice(0, 32);
     if (process.platform === "win32") {
@@ -666,22 +739,36 @@ export class EngineClient {
         if (!isValidBranchName(options.branch)) {
             throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
         }
-        const resolvedWorkspaceRoot = path.resolve(options.workspaceRoot);
-        try {
-            this.workspaceRoot = realpathSync(resolvedWorkspaceRoot);
-        }
-        catch {
-            this.workspaceRoot = resolvedWorkspaceRoot;
-        }
+        this.workspaceRoot = canonicalFilesystemPath(options.workspaceRoot);
         this.branch = options.branch;
         this.timeout = options.timeout ?? 120_000;
         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();
+        for (let attempt = 0;; attempt += 1) {
+            await this.connect(allowSpawn);
+            if (wasConnected || this.socket === null)
+                return;
+            try {
+                await this.reconcileRuntime();
+                await this.reconcileAttachment();
+                return;
+            }
+            catch (error) {
+                // A listener can begin draining after the kernel accepts a connection
+                // but before the read-only runtime and attachment handshakes finish.
+                // Retry those handshakes once; request() never retries an application
+                // RPC.
+                if (attempt > 0 ||
+                    !allowSpawn ||
+                    !(error instanceof Error) ||
+                    error.message !== "Kibi engine connection closed" ||
+                    (this.socket !== null && !this.socket.destroyed))
+                    throw error;
+                this.socket?.destroy();
+                this.socket = null;
+            }
         }
     }
     async connect(allowSpawn = true) {
@@ -720,6 +807,22 @@ export class EngineClient {
                     }
                 }
                 if (this.socket === null) {
+                    // A draining daemon removes its listener before saving, but retains
+                    // its PID until the branch lock is released. Do not start a second
+                    // writer while that process is still completing shutdown.
+                    const existingPid = this.getPid();
+                    if (existingPid > 0) {
+                        let alive = false;
+                        try {
+                            process.kill(existingPid, 0);
+                            alive = true;
+                        }
+                        catch { }
+                        if (alive) {
+                            await new Promise((resolve) => setTimeout(resolve, 50));
+                            continue;
+                        }
+                    }
                     lock = tryAcquireStartLock(lockPath);
                     if (lock === null) {
                         await new Promise((resolve) => setTimeout(resolve, 50));
@@ -771,7 +874,10 @@ export class EngineClient {
         this.attachSocket(this.socket);
     }
     attachSocket(socket) {
+        this.inputBuffer = Buffer.alloc(0);
         socket.on("data", (chunk) => {
+            if (this.socket !== socket)
+                return;
             try {
                 const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
                 this.inputBuffer = parseFrames(Buffer.concat([this.inputBuffer, bytes]), (value) => this.handleResponse(value));
@@ -781,6 +887,8 @@ export class EngineClient {
             }
         });
         socket.on("close", () => {
+            if (this.socket !== socket)
+                return;
             this.socket = null;
             const error = new Error("Kibi engine connection closed");
             for (const pending of this.pending.values()) {
@@ -789,6 +897,8 @@ export class EngineClient {
             this.pending.clear();
         });
         socket.on("error", (error) => {
+            if (this.socket !== socket)
+                return;
             for (const pending of this.pending.values()) {
                 this.settlePending(pending, () => pending.reject(error));
             }
@@ -850,9 +960,10 @@ export class EngineClient {
                         id,
                         protocolVersion: ENGINE_PROTOCOL_VERSION,
                         packageVersions: ENGINE_PACKAGE_VERSIONS,
+                        prologIdentity: engineSwiplIdentity(),
                         workspaceRoot: this.workspaceRoot,
                         branch: this.branch,
-                    }));
+                    }), ignoreWriteFailure);
                 }
                 catch (error) {
                     const pending = this.pending.get(id);
@@ -897,6 +1008,11 @@ export class EngineClient {
         return this.query(`rdf_transaction((${normalized.join(", ")}))`);
     }
     async queryEntities(input, signal) {
+        // Full entities carry receipt histories; a caller-sized page (up to 100k
+        // rows) is split into bounded engine requests.
+        return queryEntityChunks((chunk) => this.queryEntityChunk(chunk, signal), input);
+    }
+    async queryEntityChunk(input, signal) {
         const result = await this.command({
             version: 1,
             kind: "entities",
@@ -954,9 +1070,10 @@ export class EngineClient {
             cancelOf: requestId,
             protocolVersion: ENGINE_PROTOCOL_VERSION,
             packageVersions: ENGINE_PACKAGE_VERSIONS,
+            prologIdentity: engineSwiplIdentity(),
             workspaceRoot: this.workspaceRoot,
             branch: this.branch,
-        }));
+        }), ignoreWriteFailure);
     }
     async nextSolution() {
         const result = this.lastResult;
@@ -996,6 +1113,36 @@ export class EngineClient {
             return null;
         return parseEngineAttachmentIdentity(status.bindings.JsonString);
     }
+    async daemonRuntimeMatches() {
+        const reply = await this.request({
+            method: "handshake",
+        });
+        return reply?.prologIdentity === engineSwiplIdentity();
+    }
+    /**
+     * A live daemon keeps the SWI-Prolog it was started with. When this client
+     * resolves a different executable or version (KIBI_SWIPL changed, the
+     * bundled package was upgraded, a pre-handshake daemon), the daemon is
+     * stopped and replaced; it is never reused.
+     */
+    // implements REQ-prolog-daemon-runtime-identity
+    async reconcileRuntime() {
+        if (this.replacingStaleDaemon || this.socket === null)
+            return;
+        if (await this.daemonRuntimeMatches())
+            return;
+        this.replacingStaleDaemon = true;
+        try {
+            await this.shutdownConnectedDaemon();
+            await this.connect(true);
+            if (!(await this.daemonRuntimeMatches())) {
+                throw new Error(`Kibi engine is running a different SWI-Prolog than this client resolved (${engineSwiplIdentity()}); run 'kibi engine stop' and retry`);
+            }
+        }
+        finally {
+            this.replacingStaleDaemon = false;
+        }
+    }
     async reconcileAttachment() {
         if (this.replacingStaleDaemon || this.socket === null)
             return;
@@ -1020,26 +1167,40 @@ export class EngineClient {
     }
     async shutdownConnectedDaemon() {
         const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+        let requestError;
         if (!this.isRunning()) {
             if (existsSync(socketPath)) {
                 throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
             }
-            return;
-        }
-        let requestError;
-        try {
-            await this.request({ method: "stop" });
+            const existingPid = this.getPid();
+            if (existingPid <= 0)
+                return;
+            try {
+                process.kill(existingPid, 0);
+            }
+            catch {
+                return;
+            }
+            // An already-draining daemon can have no listener while its durability
+            // save still owns the store. A stop caller must wait for that handoff.
         }
-        catch (error) {
-            requestError = error;
+        else {
+            try {
+                await this.request({ method: "stop" });
+            }
+            catch (error) {
+                requestError = error;
+            }
+            this.socket?.destroy();
+            this.socket = null;
         }
-        this.socket?.destroy();
-        this.socket = null;
+        const pidPath = enginePidPath(this.workspaceRoot, this.branch);
         const deadline = Date.now() + 5_000;
-        while (existsSync(socketPath) && Date.now() < deadline) {
+        while ((existsSync(socketPath) || existsSync(pidPath)) &&
+            Date.now() < deadline) {
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
-        if (existsSync(socketPath)) {
+        if (existsSync(socketPath) || existsSync(pidPath)) {
             const detail = requestError instanceof Error ? `: ${requestError.message}` : "";
             throw new Error(`Kibi engine did not stop within 5 seconds${detail}`);
         }
@@ -1065,11 +1226,8 @@ export class EngineClient {
                 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;
+        if (!this.isRunning() && existsSync(socketPath)) {
+            throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
         }
         await this.shutdownConnectedDaemon();
     }
@@ -1286,37 +1444,116 @@ function recoverInterruptedGeneration(branchPath) {
         }
     }
 }
-// implements REQ-core-journaled-engine-lifecycle
-export async function runEngineDaemon(options) {
-    if (!isValidBranchName(options.branch)) {
-        throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
+function isEngineLifecycleRequest(request) {
+    if (request.method === "stop" ||
+        request.method === "cancel" ||
+        request.method === "handshake")
+        return true;
+    const kind = request.command?.kind;
+    return (request.method === "command" &&
+        (kind === "stop" || kind === "cancel" || kind === "lifecycle"));
+}
+const ENGINE_PRELOADED_MODULES = [
+    ["status.pl", "status"],
+    ["discovery.pl", "discovery"],
+];
+const USE_MODULE_GOAL = /^use_module\('(?:[^']|'')*'\)$/u;
+/**
+ * Owns the daemon's interactive SWI session: the attached branch store plus
+ * every module loaded into it. An overflow or timeout terminates the SWI
+ * child; the next request recycles the session (restart, reattach, reload
+ * modules) instead of letting the port degrade into isolated one-shot
+ * processes that have lost the attachment and module state.
+ */
+// implements REQ-core-journaled-engine-persistence
+export class EngineSession {
+    prolog;
+    branchPath;
+    modules = [];
+    constructor(prolog, branchPath) {
+        this.prolog = prolog;
+        this.branchPath = branchPath;
+        const coreModuleDir = path.dirname(resolveKbPlPath());
+        for (const [fileName, label] of ENGINE_PRELOADED_MODULES) {
+            const modulePath = path.join(coreModuleDir, fileName);
+            this.modules.push({
+                goal: `use_module('${quoteProlog(modulePath.replaceAll("\\", "/"))}')`,
+                label,
+            });
+        }
     }
-    const branchPath = ensureBranchStoreManifest(options.workspaceRoot, options.branch);
-    await ensureJournaledBranchStoreAsync(branchPath);
-    const prolog = new PrologProcess({ timeout: 120_000, oneShot: false });
-    await prolog.start();
-    const attached = await prolog.query(`kb_attach('${quoteProlog(branchPath)}')`);
-    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`);
+    async boot() {
+        await this.prolog.start();
+        const attached = await this.prolog.query(`kb_attach('${quoteProlog(this.branchPath)}')`);
+        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(this.prolog, this.branchPath, attached);
+            if (!recovered.success)
+                throw new Error(recovered.error ?? "Failed to attach branch KB");
+        }
+        for (const { goal, label } of this.modules) {
+            const loaded = await this.prolog.query(goal);
+            if (!loaded.success) {
+                throw new Error(loaded.error ?? `Failed to load Kibi ${label} module`);
+            }
         }
     }
+    /** Remember a successful client module load so a recycle restores it. */
+    recordModuleLoad(goal, result) {
+        const normalized = goal.trim().replace(/\.+\s*$/u, "");
+        if (result.success &&
+            USE_MODULE_GOAL.test(normalized) &&
+            !this.modules.some((module) => module.goal === normalized)) {
+            this.modules.push({ goal: normalized, label: "client-loaded" });
+        }
+    }
+    needsRecycle() {
+        return this.prolog.needsRestart();
+    }
+    /**
+     * Restart a lost interactive session. Returns true when a recycle ran. A
+     * failed recycle leaves the process stopped so the next request retries.
+     */
+    async ensureLive() {
+        if (!this.prolog.needsRestart())
+            return false;
+        console.error("[KIBI] engine Prolog session was lost (output overflow, timeout, or crash); restarting and reattaching the branch store");
+        try {
+            await this.boot();
+        }
+        catch (error) {
+            await this.prolog.terminate().catch(() => undefined);
+            const message = error instanceof Error ? error.message : String(error);
+            throw new Error(`Kibi engine failed to recycle its Prolog session: ${message}`);
+        }
+        return true;
+    }
+}
+// implements REQ-core-journaled-engine-persistence
+export async function runEngineDaemon(requestedOptions) {
+    if (!isValidBranchName(requestedOptions.branch)) {
+        throw new Error(`Invalid Kibi engine branch name: ${requestedOptions.branch}`);
+    }
+    const options = {
+        ...requestedOptions,
+        workspaceRoot: canonicalFilesystemPath(requestedOptions.workspaceRoot),
+    };
+    const branchPath = ensureBranchStoreManifest(options.workspaceRoot, options.branch);
+    await ensureJournaledBranchStoreAsync(branchPath);
+    const prolog = new PrologProcess({
+        timeout: 120_000,
+        oneShot: false,
+        ...(options.maxOutputBytes === undefined
+            ? {}
+            : { maxOutputBytes: options.maxOutputBytes }),
+    });
+    const session = new EngineSession(prolog, branchPath);
+    await session.boot();
+    let attachedIdentity = readEngineAttachmentIdentity(branchPath);
+    const serverPrologIdentity = engineSwiplIdentity();
     mkdirSync(path.dirname(options.socketPath), { recursive: true, mode: 0o700 });
     if (existsSync(options.socketPath)) {
         const isLivePeerSignal = (error) => {
@@ -1387,6 +1624,10 @@ export async function runEngineDaemon(options) {
     let freshnessCache = null;
     const clients = new Set();
     let shuttingDown = false;
+    let finishShutdown;
+    const shutdownFinished = new Promise((resolve) => {
+        finishShutdown = resolve;
+    });
     const exactBranchStatus = (result) => {
         if (!result.success || typeof result.bindings.JsonString !== "string") {
             return result;
@@ -1434,13 +1675,14 @@ export async function runEngineDaemon(options) {
     }, engineWorkspaceWatchdogMs());
     workspaceWatchdog.unref();
     const scheduleIdleExit = () => {
-        if (activeClients > 0)
+        if (shuttingDown || activeClients > 0)
             return;
         if (!idleCompactionQueued) {
             idleCompactionQueued = true;
             queue = queue
                 .then(async () => {
-                if (activeClients === 0) {
+                // A lost session is recycled by the next request, not by idle work.
+                if (activeClients === 0 && !session.needsRecycle()) {
                     await prolog.query("kb_storage_compact_if_needed");
                 }
             })
@@ -1465,11 +1707,26 @@ export async function runEngineDaemon(options) {
             request.packageVersions !== expectedPackages) {
             throw new Error(`Kibi engine package-version mismatch: client=${request.packageVersions ?? "missing"}, server=${expectedPackages}`);
         }
-        if (path.resolve(request.workspaceRoot ?? "") !==
-            path.resolve(options.workspaceRoot) ||
+        if (canonicalFilesystemPath(request.workspaceRoot ?? "") !==
+            options.workspaceRoot ||
             request.branch !== options.branch) {
             throw new Error("Kibi engine workspace identity mismatch");
         }
+        // A client that resolved a different Prolog must not be served by this
+        // daemon. Handshake reports the identity and stop must still work so the
+        // client can replace the daemon.
+        if (request.method !== "handshake" &&
+            request.method !== "stop" &&
+            request.prologIdentity !== serverPrologIdentity) {
+            throw new Error(`Kibi engine SWI-Prolog mismatch: client=${request.prologIdentity ?? "missing"}, server=${serverPrologIdentity}`);
+        }
+        if (!isEngineLifecycleRequest(request) && (await session.ensureLive())) {
+            // A recycled session re-read the store; nothing cached from the lost
+            // session may be served, and the attachment identity may have moved.
+            queryCache.clear();
+            freshnessCache = null;
+            attachedIdentity = readEngineAttachmentIdentity(branchPath);
+        }
         switch (request.method) {
             case "entities": {
                 const limit = request.limit ?? 100;
@@ -1653,8 +1910,15 @@ export async function runEngineDaemon(options) {
                 }
             }
             case "kbStatus": {
+                const freshnessCacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance.now() : null;
                 if (freshnessCache !== null &&
                     Date.now() - freshnessCache.capturedAt <= ENGINE_FRESHNESS_CACHE_MS) {
+                    if (freshnessCacheLookupStartedAt !== null) {
+                        writePerformanceTraceEvent({
+                            kind: "engine-freshness-cache-hit",
+                            durationMs: performance.now() - freshnessCacheLookupStartedAt,
+                        });
+                    }
                     return freshnessCache.result;
                 }
                 const result = exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
@@ -1674,11 +1938,20 @@ export async function runEngineDaemon(options) {
                     freshnessCache = null;
                 }
                 if (cacheableEngineGoal(request.goal)) {
+                    const queryCacheLookupStartedAt = process.env.KIBI_PERF_TIMINGS === "1" ? performance.now() : null;
                     const cached = queryCache.get(request.goal);
-                    if (cached !== undefined)
+                    if (cached !== undefined) {
+                        if (queryCacheLookupStartedAt !== null) {
+                            writePerformanceTraceEvent({
+                                kind: "engine-query-cache-hit",
+                                durationMs: performance.now() - queryCacheLookupStartedAt,
+                            });
+                        }
                         return cached;
+                    }
                 }
                 const result = await prolog.query(request.goal);
+                session.recordModuleLoad(request.goal, result);
                 if (result.success && mutatingEngineGoal(request.goal)) {
                     fsyncJournaledBranchStore(branchPath);
                 }
@@ -1715,6 +1988,8 @@ export async function runEngineDaemon(options) {
                 if (typeof request.targetDirectory !== "string")
                     throw new Error("export.targetDirectory is required");
                 return prolog.query(`kb_storage_export('${quoteProlog(request.targetDirectory)}')`);
+            case "handshake":
+                return { prologIdentity: serverPrologIdentity };
             case "stop":
                 setImmediate(() => void shutdown());
                 return { stopped: true };
@@ -1741,7 +2016,13 @@ export async function runEngineDaemon(options) {
         if (idleTimer)
             clearTimeout(idleTimer);
         clearInterval(workspaceWatchdog);
-        const saved = await prolog.query("kb_save").catch(() => null);
+        // Stop accepting clients before the first asynchronous durability step.
+        // Keep the PID published until Prolog releases the branch-store lock.
+        server.close();
+        await queue.catch(() => undefined);
+        const saved = session.needsRecycle()
+            ? null
+            : await prolog.query("kb_save").catch(() => null);
         if (saved?.success) {
             try {
                 fsyncJournaledBranchStore(branchPath);
@@ -1754,7 +2035,6 @@ export async function runEngineDaemon(options) {
         await prolog.terminate().catch(() => undefined);
         for (const client of clients)
             client.destroy();
-        server.close();
         // A close callback can remain pending on older Node releases when a
         // client disconnects during `server.close()`. The daemon has already
         // removed its socket/pid and has no useful work left, so do not keep the
@@ -1775,6 +2055,7 @@ export async function runEngineDaemon(options) {
         // gone, force the final event-loop exit rather than retaining a stale
         // detached Node process on platform-specific server bookkeeping.
         setTimeout(() => process.exit(0), 50).unref();
+        finishShutdown();
     };
     // 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.
@@ -1783,6 +2064,12 @@ export async function runEngineDaemon(options) {
     process.once("SIGTERM", requestSignalShutdown);
     process.once("SIGINT", requestSignalShutdown);
     server.on("connection", (socket) => {
+        // A peer may disappear while the daemon refuses or drains its socket.
+        socket.on("error", () => undefined);
+        if (shuttingDown) {
+            socket.destroy();
+            return;
+        }
         clients.add(socket);
         activeClients += 1;
         // Request ids are per-connection. Cancel marks must not be daemon-global
@@ -1794,6 +2081,15 @@ export async function runEngineDaemon(options) {
                 const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk;
                 buffer = parseFrames(Buffer.concat([buffer, bytes]), (value) => {
                     const request = value;
+                    if (shuttingDown) {
+                        writeSocketFrame(socket, {
+                            id: request.id,
+                            ok: false,
+                            error: "Kibi engine is shutting down; request was not executed",
+                            serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
+                        });
+                        return;
+                    }
                     if (request.method === "cancel" &&
                         typeof request.cancelOf === "number") {
                         cancelledRequests.add(request.cancelOf);
@@ -1862,4 +2158,5 @@ export async function runEngineDaemon(options) {
     await new Promise((resolve) => {
         server.once("close", resolve);
     });
+    await shutdownFinished;
 }