kibi-cli 0.19.0 → 2.0.0

package/dist/engine.js

@@ -14,19 +14,105 @@ 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 { 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";
 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("'", "''");
 }
@@ -48,15 +134,84 @@ function cacheableEngineGoal(goal) {
 function mutatingEngineGoal(goal) {
     return /(?:kb_(?:assert|retract|commit|save|delete)|rdf_transaction|rdf_assert|rdf_retract)/.test(goal);
 }
+function maskPrologData(goal) {
+    const chars = [...goal];
+    let quote = null;
+    let lineComment = false;
+    let blockComment = false;
+    for (let index = 0; index < chars.length; index += 1) {
+        const current = chars[index];
+        const next = chars[index + 1];
+        if (lineComment) {
+            if (current === "\n")
+                lineComment = false;
+            else
+                chars[index] = " ";
+            continue;
+        }
+        if (blockComment) {
+            if (current === "*" && next === "/") {
+                chars[index] = " ";
+                chars[index + 1] = " ";
+                index += 1;
+                blockComment = false;
+            }
+            else if (current !== "\n") {
+                chars[index] = " ";
+            }
+            continue;
+        }
+        if (quote !== null) {
+            if (current === "\\") {
+                chars[index] = " ";
+                if (index + 1 < chars.length) {
+                    chars[index + 1] = " ";
+                    index += 1;
+                }
+            }
+            else if (current === quote) {
+                if (next === quote) {
+                    chars[index] = " ";
+                    chars[index + 1] = " ";
+                    index += 1;
+                }
+                else {
+                    chars[index] = " ";
+                    quote = null;
+                }
+            }
+            else if (current !== "\n") {
+                chars[index] = " ";
+            }
+            continue;
+        }
+        if (current === "%") {
+            chars[index] = " ";
+            lineComment = true;
+        }
+        else if (current === "/" && next === "*") {
+            chars[index] = " ";
+            chars[index + 1] = " ";
+            index += 1;
+            blockComment = true;
+        }
+        else if (current === "'" || current === '"' || current === "`") {
+            chars[index] = " ";
+            quote = current;
+        }
+    }
+    return chars.join("");
+}
 function safeEngineGoal(goal) {
     // The socket is a local capability boundary, not a general-purpose SWI
     // console. Public clients may compose the typed Kibi predicates needed by
-    // the 18 operation contracts, but process/filesystem/network escape hatches
+    // the typed operation contracts, but process/filesystem/network escape hatches
     // are rejected before they reach Prolog.
-    if (/\b(?:halt|abort|shell|system|process_create|consult|load_files|open|close|delete_file|rename_file|make_directory|thread_create|rdf_attach_db|rdf_load|rdf_save|assertz|asserta|retractall)\s*\(/.test(goal)) {
+    const executable = maskPrologData(goal);
+    if (/\b(?:halt|abort|shell|system|process_create|consult|load_files|open|close|delete_file|rename_file|make_directory|thread_create|rdf_attach_db|rdf_load|rdf_save|assertz|asserta|retractall|set_prolog_flag)\s*\(/.test(executable)) {
         return false;
     }
-    return /(?:^|[(:,\s])(?:kb_|checks:|status:|discovery:|requirement_proof:|findall\(|aggregate_all\(|rdf_transaction\(|set_prolog_flag\(|use_module\(|atom_json_dict\(|member\(|once\(|true\b|fail\b)/.test(goal.trim());
+    return /(?:^|[(:,\s])(?:kb_|checks:|status:|discovery:|requirement_proof:|findall\(|aggregate_all\(|rdf_transaction\(|use_module\(|atom_json_dict\(|member\(|once\(|true\b|fail\b)/.test(goal.trim());
 }
 function frame(value) {
     const payload = Buffer.from(JSON.stringify(value), "utf8");
@@ -91,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");
@@ -199,6 +354,127 @@ export function engineStartLockPath(workspaceRoot, branch) {
     }
     return `${engineSocketPath(workspaceRoot, branch)}.start.lock`;
 }
+/**
+ * A generation publisher holds this lease from the existing daemon shutdown
+ * through the atomic branch-store cutover. Engine clients honor the lease so
+ * another process cannot auto-start a writer in the stop-to-publish gap.
+ */
+export function enginePublicationLockPath(workspaceRoot, branch) {
+    return `${engineSocketPath(workspaceRoot, branch)}.publish.lock`;
+}
+function publicationLockOwner(lockPath) {
+    try {
+        const [pidText, createdText] = readFileSync(lockPath, "utf8")
+            .trim()
+            .split(":");
+        const pid = Number.parseInt(pidText ?? "", 10);
+        const createdAt = Number.parseInt(createdText ?? "", 10);
+        if (!Number.isInteger(pid) || pid <= 1 || !Number.isFinite(createdAt)) {
+            return null;
+        }
+        return { pid, createdAt };
+    }
+    catch {
+        return null;
+    }
+}
+function processIsAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+function clearStalePublicationLock(lockPath) {
+    if (!existsSync(lockPath))
+        return true;
+    const owner = publicationLockOwner(lockPath);
+    let age = 0;
+    try {
+        age = Date.now() - statSync(lockPath).mtimeMs;
+    }
+    catch {
+        return false;
+    }
+    if ((owner === null || !processIsAlive(owner.pid)) &&
+        age > ENGINE_PUBLICATION_LOCK_STALE_MS) {
+        try {
+            unlinkSync(lockPath);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    }
+    return false;
+}
+function publicationLockIsActive(lockPath) {
+    if (!existsSync(lockPath))
+        return false;
+    if (clearStalePublicationLock(lockPath))
+        return false;
+    return existsSync(lockPath);
+}
+export function acquireEnginePublicationLease(workspaceRoot, branch) {
+    const lockPath = enginePublicationLockPath(workspaceRoot, branch);
+    mkdirSync(path.dirname(lockPath), { recursive: true, mode: 0o700 });
+    let descriptor = null;
+    try {
+        descriptor = openSync(lockPath, "wx", 0o600);
+    }
+    catch {
+        if (clearStalePublicationLock(lockPath)) {
+            try {
+                descriptor = openSync(lockPath, "wx", 0o600);
+            }
+            catch {
+                // Fall through to the stable fail-closed error below.
+            }
+        }
+    }
+    if (descriptor === null) {
+        throw new Error(`Kibi engine publication is already in progress: ${lockPath}`);
+    }
+    try {
+        writeFileSync(lockPath, `${process.pid}:${Date.now()}\n`, { flag: "w" });
+    }
+    catch (error) {
+        closeSync(descriptor);
+        unlinkSync(lockPath);
+        throw error;
+    }
+    const startLockPath = engineStartLockPath(workspaceRoot, branch);
+    const startDescriptor = tryAcquireStartLock(startLockPath);
+    if (startDescriptor === null) {
+        closeSync(descriptor);
+        unlinkSync(lockPath);
+        throw new Error(`Kibi engine publication cannot acquire the engine start lease: ${startLockPath}`);
+    }
+    let released = false;
+    return {
+        path: lockPath,
+        release: () => {
+            if (released)
+                return;
+            released = true;
+            try {
+                closeSync(descriptor);
+            }
+            catch {
+                // The descriptor may already have been closed during process cleanup.
+            }
+            releaseStartLock(startLockPath, startDescriptor);
+            try {
+                unlinkSync(lockPath);
+            }
+            catch {
+                // A subsequent publisher may have replaced a stale lock after a crash.
+            }
+        },
+    };
+}
 function tryAcquireStartLock(lockPath) {
     try {
         const descriptor = openSync(lockPath, "wx", 0o600);
@@ -377,6 +653,7 @@ export class EngineClient {
     workspaceRoot;
     branch;
     timeout;
+    allowPublicationLock;
     socket = null;
     daemon = null;
     inputBuffer = Buffer.alloc(0);
@@ -384,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}`);
@@ -397,11 +675,24 @@ export class EngineClient {
         }
         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();
+        }
+    }
+    async connect(allowSpawn = true) {
         if (this.socket !== null && !this.socket.destroyed)
             return;
         const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+        const publicationLockPath = enginePublicationLockPath(this.workspaceRoot, this.branch);
+        if (!this.allowPublicationLock &&
+            publicationLockIsActive(publicationLockPath)) {
+            throw new Error(`Kibi engine publication is in progress: ${publicationLockPath}`);
+        }
         try {
             if (existsSync(socketPath)) {
                 this.socket = await connectWithRetry(socketPath, 150);
@@ -576,22 +867,28 @@ export class EngineClient {
             release();
         }
     }
+    /** Execute a versioned, goal-free engine command. Raw query remains private
+     * compatibility traffic for the in-process Prolog adapter only. */
+    async command(command, signal) {
+        return this.request({ method: "command", command }, signal);
+    }
     async queryBatch(goals) {
         const normalized = goals.map((goal) => goal.trim().replace(/\.+\s*$/, ""));
         return this.query(`rdf_transaction((${normalized.join(", ")}))`);
     }
-    async queryEntities(input) {
-        const result = await this.request({
-            method: "entities",
+    async queryEntities(input, signal) {
+        const result = await this.command({
+            version: 1,
+            kind: "entities",
             ...(input.type !== undefined ? { type: input.type } : {}),
-            ...(input.id !== undefined ? { entityId: input.id } : {}),
+            ...(input.id !== undefined ? { id: input.id } : {}),
             ...(input.tags !== undefined ? { tags: input.tags } : {}),
             ...(input.sourceFile !== undefined
                 ? { sourceFile: input.sourceFile }
                 : {}),
             limit: input.limit,
             offset: input.offset,
-        });
+        }, signal);
         if (!result.success) {
             throw new Error(result.error ?? "Indexed entity query failed");
         }
@@ -604,14 +901,15 @@ export class EngineClient {
             count: Number.isFinite(count) ? count : rows.length,
         };
     }
-    async searchEntities(input) {
-        const result = await this.request({
-            method: "search",
-            searchQuery: input.query,
+    async searchEntities(input, signal) {
+        const result = await this.command({
+            version: 1,
+            kind: "search",
+            query: input.query,
             ...(input.type !== undefined ? { type: input.type } : {}),
             limit: input.limit,
             offset: input.offset,
-        });
+        }, signal);
         if (!result.success) {
             throw new Error(result.error ?? "Indexed search candidate query failed");
         }
@@ -645,20 +943,20 @@ export class EngineClient {
         this.lastResult = null;
         return result;
     }
-    async save() {
-        return this.query("kb_save");
+    async save(signal) {
+        return this.query("kb_save", signal);
     }
     async storageStatus() {
         return this.request({ method: "status" });
     }
     async checkpoint() {
-        return this.request({ method: "checkpoint" });
+        return this.command({ version: 1, kind: "checkpoint" });
     }
     async queryStatusJson() {
-        return this.request({ method: "kbStatus" });
+        return this.command({ version: 1, kind: "status" });
     }
     async compact() {
-        return this.request({ method: "compact" });
+        return this.command({ version: 1, kind: "compact" });
     }
     async exportStorage(targetDirectory) {
         return this.request({
@@ -672,6 +970,60 @@ export class EngineClient {
     isRunning() {
         return this.socket !== null && !this.socket.destroyed;
     }
+    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 {
+            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)}`);
+            }
+        }
+        finally {
+            this.replacingStaleDaemon = false;
+        }
+    }
+    async shutdownConnectedDaemon() {
+        const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
+        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" });
+        }
+        catch (error) {
+            requestError = error;
+        }
+        this.socket?.destroy();
+        this.socket = null;
+        const deadline = Date.now() + 5_000;
+        while (existsSync(socketPath) && Date.now() < deadline) {
+            await new Promise((resolve) => setTimeout(resolve, 25));
+        }
+        if (existsSync(socketPath)) {
+            const detail = requestError instanceof Error ? `: ${requestError.message}` : "";
+            throw new Error(`Kibi engine did not stop within 5 seconds${detail}`);
+        }
+    }
     getPid() {
         const pidPath = enginePidPath(this.workspaceRoot, this.branch);
         try {
@@ -685,7 +1037,7 @@ export class EngineClient {
         const socketPath = engineSocketPath(this.workspaceRoot, this.branch);
         if (!this.isRunning()) {
             try {
-                await this.start(startIfMissing);
+                await this.connect(startIfMissing);
             }
             catch {
                 if (!startIfMissing)
@@ -693,18 +1045,13 @@ export class EngineClient {
                 throw new Error("Unable to start Kibi engine for stop request");
             }
         }
-        if (!this.isRunning())
+        if (!this.isRunning()) {
+            if (existsSync(socketPath)) {
+                throw new Error(`Kibi engine socket remains present but is not reachable: ${socketPath}`);
+            }
             return;
-        await this.request({ method: "stop" }).catch(() => undefined);
-        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));
         }
+        await this.shutdownConnectedDaemon();
     }
     async terminate() {
         // Closing a client connection releases the engine; the daemon remains
@@ -924,17 +1271,31 @@ export async function runEngineDaemon(options) {
     if (!isValidBranchName(options.branch)) {
         throw new Error(`Invalid Kibi engine branch name: ${options.branch}`);
     }
-    await ensureJournaledBranchStoreAsync(path.join(options.workspaceRoot, ".kb", "branches", options.branch));
+    const branchPath = ensureBranchStoreManifest(options.workspaceRoot, options.branch);
+    await ensureJournaledBranchStoreAsync(branchPath);
     const prolog = new PrologProcess({ timeout: 120_000, oneShot: false });
     await prolog.start();
-    const branchPath = path.join(options.workspaceRoot, ".kb", "branches", options.branch);
     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)) {
@@ -968,6 +1329,52 @@ export async function runEngineDaemon(options) {
     const cancelledRequests = new Set();
     const clients = new Set();
     let shuttingDown = false;
+    const exactBranchStatus = (result) => {
+        if (!result.success || typeof result.bindings.JsonString !== "string") {
+            return result;
+        }
+        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: {
+                    ...result.bindings,
+                    JsonString: JSON.stringify(JSON.stringify(decoded)),
+                },
+            };
+        }
+        catch {
+            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;
@@ -1057,12 +1464,142 @@ export async function runEngineDaemon(options) {
                 }
                 return result;
             }
+            case "command": {
+                const command = request.command;
+                if (command === undefined || command.version !== 1) {
+                    throw new Error("engine.command must use version 1");
+                }
+                switch (command.kind) {
+                    case "status":
+                        return exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
+                    case "checkpoint": {
+                        queryCache.clear();
+                        freshnessCache = null;
+                        const result = await prolog.query("kb_sync_checkpoint");
+                        if (result.success)
+                            fsyncJournaledBranchStore(branchPath);
+                        return result;
+                    }
+                    case "compact": {
+                        const result = await prolog.query("kb_storage_compact");
+                        if (result.success)
+                            fsyncJournaledBranchStore(branchPath);
+                        return result;
+                    }
+                    case "save": {
+                        const result = await prolog.query("kb_save");
+                        if (result.success)
+                            fsyncJournaledBranchStore(branchPath);
+                        return result;
+                    }
+                    case "check": {
+                        if (command.rule !== undefined &&
+                            !/^[a-z][a-z0-9_]*$/.test(command.rule)) {
+                            throw new Error("engine.check.rule must be a lowercase rule name");
+                        }
+                        // Rule selection is intentionally resolved inside the engine. A
+                        // caller never supplies a Prolog goal over the command boundary.
+                        return prolog.query("checks:check_all_json(JsonString)");
+                    }
+                    case "relationship": {
+                        if (!command.type || !command.from || !command.to) {
+                            throw new Error("engine.relationship requires type, from, and to");
+                        }
+                        const type = quoteProlog(command.type);
+                        const from = quoteProlog(command.from);
+                        const to = quoteProlog(command.to);
+                        const goal = command.action === "assert"
+                            ? `kb_assert_relationship('${type}', '${from}', '${to}', [])`
+                            : `kb_retract_relationship('${type}', '${from}', '${to}')`;
+                        const result = await prolog.query(goal);
+                        if (result.success) {
+                            queryCache.clear();
+                            freshnessCache = null;
+                            fsyncJournaledBranchStore(branchPath);
+                        }
+                        return result;
+                    }
+                    case "persistence": {
+                        const goal = command.action === "checkpoint"
+                            ? "kb_sync_checkpoint"
+                            : command.action === "compact"
+                                ? "kb_storage_compact"
+                                : command.action === "save"
+                                    ? "kb_save"
+                                    : command.targetDirectory
+                                        ? `kb_storage_export('${quoteProlog(command.targetDirectory)}')`
+                                        : null;
+                        if (goal === null) {
+                            throw new Error("engine.persistence.export requires targetDirectory");
+                        }
+                        const result = await prolog.query(goal);
+                        if (result.success)
+                            fsyncJournaledBranchStore(branchPath);
+                        return result;
+                    }
+                    case "lifecycle": {
+                        if (command.action === "stop") {
+                            setImmediate(() => void shutdown());
+                            return { stopped: true };
+                        }
+                        if (!Number.isInteger(command.requestId)) {
+                            throw new Error("engine.lifecycle.cancel requires requestId");
+                        }
+                        const requestId = command.requestId;
+                        cancelledRequests.add(requestId);
+                        return { cancelled: requestId };
+                    }
+                    case "stop":
+                        setImmediate(() => void shutdown());
+                        return { stopped: true };
+                    case "cancel":
+                        cancelledRequests.add(command.requestId);
+                        return { cancelled: command.requestId };
+                    case "entities": {
+                        if (!Number.isInteger(command.limit) ||
+                            !Number.isInteger(command.offset) ||
+                            command.limit < 0 ||
+                            command.offset < 0 ||
+                            command.limit > 100_000) {
+                            throw new Error("engine.entities.limit/offset must be bounded integers");
+                        }
+                        const type = command.type === undefined
+                            ? "none"
+                            : `'${quoteProlog(command.type)}'`;
+                        const id = command.id === undefined
+                            ? "none"
+                            : `'${quoteProlog(command.id)}'`;
+                        const tags = `[${(command.tags ?? []).map((tag) => `'${quoteProlog(tag)}'`).join(",")}]`;
+                        const source = command.sourceFile === undefined
+                            ? "none"
+                            : `'${quoteProlog(command.sourceFile)}'`;
+                        return prolog.query(`kb_query_entities(${type}, ${id}, ${tags}, ${source}, ${command.limit}, ${command.offset}, Rows, Count)`);
+                    }
+                    case "search": {
+                        if (!command.query.trim())
+                            throw new Error("engine.search.query must be non-empty");
+                        if (!Number.isInteger(command.limit) ||
+                            !Number.isInteger(command.offset) ||
+                            command.limit < 0 ||
+                            command.offset < 0 ||
+                            command.limit > 100_000) {
+                            throw new Error("engine.search.limit/offset must be bounded integers");
+                        }
+                        const type = command.type === undefined
+                            ? "none"
+                            : `'${quoteProlog(command.type)}'`;
+                        return prolog.query(`kb_search_entities(${type}, '${quoteProlog(command.query)}', ${command.limit}, ${command.offset}, Rows, Count)`);
+                    }
+                    default:
+                        throw new Error("engine.command kind is unsupported");
+                }
+            }
             case "kbStatus": {
                 if (freshnessCache !== null &&
                     Date.now() - freshnessCache.capturedAt <= ENGINE_FRESHNESS_CACHE_MS) {
                     return freshnessCache.result;
                 }
-                const result = await prolog.query("status:kb_status_json(JsonString)");
+                const result = exactBranchStatus(await prolog.query("status:kb_status_json(JsonString)"));
                 if (result.success) {
                     freshnessCache = { capturedAt: Date.now(), result };
                 }
@@ -1138,6 +1675,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 {
@@ -1176,9 +1714,7 @@ 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) => {