kibi-cli 2.12.0 → 2.14.0

package/dist/commands/doctor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AA+EA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAgG/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}
+{"version":3,"file":"doctor.d.ts","sourceRoot":"","sources":["../../src/commands/doctor.ts"],"names":[],"mappings":"AAiFA,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;CAC3B;AAGD,wBAAsB,aAAa,CACjC,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC;IAAE,QAAQ,EAAE,MAAM,CAAA;CAAE,CAAC,CAoG/B;AAED,wBAAsB,4BAA4B,CAChD,IAAI,GAAE,MAAM,OAAO,CAAC;IAAE,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,CACT,GACxC,OAAO,CAAC,OAAO,CAAC,CAOlB;AAED,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;;;;;;;;;;;;;;;;MAkE3C;AAkGD,wBAAgB,qBAAqB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAGzE;AAED,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,EAChB,IAAI,EAAE,MAAM,GACX,MAAM,GAAG,SAAS,CAepB"}

package/dist/commands/doctor.js

@@ -21,9 +21,11 @@ import { createRequire } from "node:module";
 import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { bootstrapKibiEnvironment, secretSourceFromBootstrap, } from "../env/bootstrap.js";
+import { kibiPackageVersions } from "../package-versions.js";
 import { describeConfiguredCapabilityPlugins, readProjectKibiConfig, } from "../plugins/project-config.js";
 import { SwiplResolutionError, inspectSwiplBundle, probeRequiredLibraries, resolveSwipl, } from "../prolog/swipl-resolver.js";
 import { buildMigrationPlan, migrationAction, } from "../public/operations/migration-plan.js";
+import { resolveReadBranchAttachment } from "../utils/branch-resolver.js";
 import { resolveGitRepository, } from "../utils/git-repository-context.js";
 import { readKbManifestStatus } from "../utils/kb-manifest.js";
 import { hasManagedHooks, outdatedManagedHooks } from "./init-helpers.js";
@@ -86,6 +88,10 @@ export async function doctorCommand(options = {}) {
             name: "Capability plugins",
             check: checkCapabilityPlugins,
         },
+        {
+            name: "Engine daemon",
+            check: checkEngineDaemon,
+        },
     ];
     const results = [];
     for (const { name, check } of checks) {
@@ -227,7 +233,7 @@ async function runtimeProvenance() {
         mcpCliRange: mcp.dependencies?.["kibi-cli"] ?? "unknown",
         executeApplyPlanExported,
         entrypoint: process.argv[1] ?? "unknown",
-        packageVersions: process.env.KIBI_PACKAGE_VERSIONS ?? "unknown",
+        packageVersions: kibiPackageVersions(),
         locations: {
             cli: packagePath,
             cliEntrypoint: process.argv[1] ?? "unknown",
@@ -494,6 +500,75 @@ function formatJevStaticConfigParts(env = process.env) {
     }
     return [`jev.model=${model}`, `jev.timeoutMs=${String(timeoutMs)}`];
 }
+/**
+ * The package versions and SWI-Prolog of the engine daemon serving this
+ * workspace and branch, read through its handshake without starting one. A
+ * daemon with other versions is replaced by the next Kibi command, so it is
+ * reported, not failed.
+ */
+// implements REQ-engine-daemon-package-versions
+async function checkEngineDaemon() {
+    const workspaceRoot = path.resolve(process.env.KIBI_WORKSPACE ??
+        process.env.KIBI_PROJECT_ROOT ??
+        process.env.KIBI_ROOT ??
+        process.cwd());
+    const expected = kibiPackageVersions();
+    const attachment = resolveReadBranchAttachment(workspaceRoot);
+    if ("error" in attachment) {
+        return {
+            passed: true,
+            message: "Not checked: no branch to address the engine daemon",
+            details: { running: false, expectedPackageVersions: expected },
+        };
+    }
+    const { EngineClient } = await import("../engine.js");
+    const client = new EngineClient({
+        workspaceRoot,
+        branch: attachment.kbBranch,
+    });
+    let daemon = null;
+    try {
+        daemon = await client.inspectLiveDaemon();
+    }
+    catch (error) {
+        return {
+            passed: true,
+            message: `Not reachable: ${error instanceof Error ? error.message : String(error)}`,
+            details: { running: false, expectedPackageVersions: expected },
+        };
+    }
+    finally {
+        await client.terminate();
+    }
+    if (daemon === null) {
+        return {
+            passed: true,
+            message: "Not running",
+            details: { running: false, expectedPackageVersions: expected },
+        };
+    }
+    const details = {
+        running: true,
+        pid: client.getPid(),
+        branch: attachment.kbBranch,
+        packageVersions: daemon.packageVersions,
+        prologIdentity: daemon.prologIdentity,
+        expectedPackageVersions: expected,
+    };
+    if (daemon.packageVersions === expected) {
+        return {
+            passed: true,
+            message: `Running ${daemon.packageVersions}`,
+            details,
+        };
+    }
+    return {
+        passed: true,
+        message: `Running ${daemon.packageVersions ?? "a daemon that reports no package versions"}, not this CLI's ${expected}; the next Kibi command replaces it`,
+        remediation: "Run: kibi engine stop",
+        details,
+    };
+}
 function checkKbDirectory() {
     const kbDir = path.join(process.cwd(), ".kb");
     if (!existsSync(kbDir)) {

package/dist/engine.d.ts

@@ -8,6 +8,14 @@ export { EngineQueryLimitError, QUERY_LIMIT_EXCEEDED_CODE, queryLimitExceededOf,
 export type { EngineLimitExceeded, EngineQueryLimits, } from "./engine-limits.js";
 export declare const ENGINE_PROTOCOL_VERSION = 1;
 export declare const ENGINE_IDLE_TIMEOUT_MS: number;
+/**
+ * Package versions this engine build carries (KIBI_PACKAGE_VERSIONS when
+ * set). The client sends them on every request and the daemon reports its
+ * own in the handshake; a daemon with other versions is replaced, never
+ * reused.
+ */
+export declare function enginePackageVersions(): string;
+/** @deprecated The versions at module load; call enginePackageVersions(). */
 export declare const ENGINE_PACKAGE_VERSIONS: string;
 /**
  * Identity of the SWI-Prolog this process would launch (`<bin>@<version>`).
@@ -43,6 +51,11 @@ export type EnginePublicationLease = Readonly<{
     readonly release: () => void;
 }>;
 export declare function acquireEnginePublicationLease(workspaceRoot: string, branch: string): EnginePublicationLease;
+/** What a live daemon reports in its handshake. */
+export type EngineDaemonIdentity = Readonly<{
+    prologIdentity: string | null;
+    packageVersions: string | null;
+}>;
 export type EngineClientOptions = {
     readonly workspaceRoot: string;
     readonly branch: string;
@@ -99,11 +112,21 @@ export declare class EngineClient {
     invalidateCache(): void;
     isRunning(): boolean;
     private readAttachedIdentity;
-    private daemonRuntimeMatches;
+    /** The live daemon's handshake: its SWI-Prolog and package versions. */
+    private daemonHandshake;
+    /**
+     * The identity a live daemon reports, without starting one; null when no
+     * daemon serves this workspace and branch. The connection is closed again.
+     */
+    inspectLiveDaemon(): Promise<EngineDaemonIdentity | null>;
+    /** Why the live daemon may not serve this client, or null when it may. */
+    private daemonRuntimeMismatch;
     /**
-     * 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
+     * A live daemon keeps the SWI-Prolog and the package versions 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) or carries other package versions (a daemon left
+     * by another install, for example one a git hook started), the daemon is
      * stopped and replaced; it is never reused.
      */
     private reconcileRuntime;

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAgCA,OAAO,EAEL,KAAK,iBAAiB,EAMvB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,KAAK,EACV,wBAAwB,EACxB,eAAe,EAEhB,MAAM,mBAAmB,CAAC;AAG3B,OAAO,EAAE,aAAa,EAAmB,MAAM,aAAa,CAAC;AAK7D,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,sCAAsC,CAAC;AAC9E,OAAO,KAAK,EACV,sBAAsB,EACtB,uBAAuB,EACvB,sBAAsB,EACtB,uBAAuB,EACxB,MAAM,sCAAsC,CAAC;AAQ9C,YAAY,EACV,wBAAwB,EACxB,eAAe,EACf,aAAa,GACd,MAAM,mBAAmB,CAAC;AAC3B,OAAO,EACL,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,GACrB,MAAM,oBAAoB,CAAC;AAC5B,YAAY,EACV,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,oBAAoB,CAAC;AAU5B,eAAO,MAAM,uBAAuB,IAAI,CAAC;AACzC,eAAO,MAAM,sBAAsB,QAAiB,CAAC;AAErD;;;;;GAKG;AAEH,wBAAgB,qBAAqB,IAAI,MAAM,CAE9C;AAED,6EAA6E;AAC7E,eAAO,MAAM,uBAAuB,QAAwB,CAAC;AAE7D;;;;GAIG;AAEH,wBAAgB,mBAAmB,IAAI,MAAM,CAE5C;AAQD,wBAAgB,2BAA2B,CACzC,QAAQ,EAAE,MAAM,OAAO,GACtB,MAAM,IAAI,CAIZ;AAED,wBAAgB,qBAAqB,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,CAKhE;AAED,wBAAgB,4BAA4B,CAC1C,UAAU,EAAE,MAAM,GACjB,wBAAwB,GAAG,IAAI,CAgBjC;AAED,wBAAgB,6BAA6B,CAC3C,UAAU,EAAE,MAAM,GAAG,SAAS,GAC7B,wBAAwB,GAAG,IAAI,CAyBjC;AAED,wBAAgB,sBAAsB,CACpC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,EACzC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,GACxC,OAAO,CAWT;AAED,wBAAgB,8BAA8B,CAC5C,SAAS,EAAE,MAAM,EACjB,QAAQ,EAAE,wBAAwB,GAAG,IAAI,EACzC,QAAQ,EAAE,wBAAwB,GAAG,IAAI,GACxC,MAAM,CASR;AA8LD,wBAAgB,gBAAgB,IAAI,MAAM,CAgFzC;AAaD;;;;;GAKG;AAEH,wBAAgB,yBAAyB,CAAC,UAAU,EAAE,MAAM,GAAG,IAAI,CAuBlE;AAGD,wBAAgB,gBAAgB,CAC9B,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAYR;AAED,wBAAgB,aAAa,CAAC,aAAa,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAW3E;AAED,wBAAgB,mBAAmB,CACjC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAUR;AAED;;;;GAIG;AACH,wBAAgB,yBAAyB,CACvC,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,MAAM,CAER;AA2DD,MAAM,MAAM,sBAAsB,GAAG,QAAQ,CAAC;IAC5C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B,CAAC,CAAC;AAEH,wBAAgB,6BAA6B,CAC3C,aAAa,EAAE,MAAM,EACrB,MAAM,EAAE,MAAM,GACb,sBAAsB,CAuDxB;AAwLD,mDAAmD;AACnD,MAAM,MAAM,oBAAoB,GAAG,QAAQ,CAAC;IAC1C,cAAc,EAAE,MAAM,GAAG,IAAI,CAAC;IAC9B,eAAe,EAAE,MAAM,GAAG,IAAI,CAAC;CAChC,CAAC,CAAC;AAEH,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,8EAA8E;IAC9E,QAAQ,CAAC,oBAAoB,CAAC,EAAE,OAAO,CAAC;IACxC;;;;OAIG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,iBAAiB,GAAG,IAAI,CAAC;CAChD,CAAC;AAEF,2EAA2E;AAE3E,qBAAa,YAAY;IACvB,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAS;IACvC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,oBAAoB,CAAU;IAC/C,OAAO,CAAC,QAAQ,CAAC,UAAU,CAAgC;IAC3D,OAAO,CAAC,MAAM,CAA2B;IACzC,OAAO,CAAC,MAAM,CAA6B;IAC3C,OAAO,CAAC,WAAW,CAA4C;IAC/D,OAAO,CAAC,SAAS,CAAK;IACtB,OAAO,CAAC,OAAO,CAAqC;IACpD,OAAO,CAAC,WAAW,CAAoC;IACvD,OAAO,CAAC,UAAU,CAAkC;IACpD,OAAO,CAAC,oBAAoB,CAAS;gBAEzB,OAAO,EAAE,mBAAmB;IAclC,KAAK,CAAC,UAAU,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;YA4B/B,OAAO;IAiHrB,OAAO,CAAC,YAAY;IAkCpB,uEAAuE;IACvE,OAAO,CAAC,aAAa;IAOrB,OAAO,CAAC,cAAc;YAkBR,OAAO;IA+Ef,KAAK,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAS3E;uEACmE;IAC7D,OAAO,CAAC,CAAC,GAAG,iBAAiB,EACjC,OAAO,EAAE,eAAe,EACxB,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,CAAC,CAAC;IAIP,UAAU,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAKhE,aAAa,CACjB,KAAK,EAAE,sBAAsB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC;YASrB,gBAAgB;IAgCxB,cAAc,CAClB,KAAK,EAAE,sBAAsB,EAC7B,MAAM,CAAC,EAAE,WAAW,GACnB,OAAO,CAAC,uBAAuB,CAAC;IAyBnC,qDAAqD;IACrD,MAAM,CAAC,SAAS,EAAE,MAAM,GAAG,IAAI;IAmBzB,YAAY,IAAI,OAAO,CAAC,iBAAiB,GAAG,IAAI,CAAC;IAMjD,IAAI,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAItD,aAAa,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAI3C,UAAU,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIxC,eAAe,CAAC,MAAM,CAAC,EAAE,WAAW,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOjE,OAAO,IAAI,OAAO,CAAC,iBAAiB,CAAC;IAIrC,aAAa,CAAC,eAAe,EAAE,MAAM,GAAG,OAAO,CAAC,iBAAiB,CAAC;IAOxE,eAAe,IAAI,IAAI;IAIvB,SAAS,IAAI,OAAO;YAIN,oBAAoB;IAMlC,wEAAwE;YAC1D,eAAe;IAgB7B;;;OAGG;IAEG,iBAAiB,IAAI,OAAO,CAAC,oBAAoB,GAAG,IAAI,CAAC;IAW/D,0EAA0E;YAC5D,qBAAqB;IAUnC;;;;;;;OAOG;YAEW,gBAAgB;YAkBhB,mBAAmB;YA0BnB,uBAAuB;IA0CrC,MAAM,IAAI,MAAM;IASV,IAAI,CAAC,cAAc,UAAO,GAAG,OAAO,CAAC,IAAI,CAAC;IAkB1C,SAAS,IAAI,OAAO,CAAC,IAAI,CAAC;CASjC;AAGD,wBAAsB,+BAA+B,CACnD,UAAU,EAAE,MAAM,GACjB,OAAO,CAAC,IAAI,CAAC,CAoJf;AAsGD;;;;;;GAMG;AAEH,qBAAa,aAAa;IAItB,OAAO,CAAC,QAAQ,CAAC,MAAM;IACvB,OAAO,CAAC,QAAQ,CAAC,UAAU;IAJ7B,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAyC;gBAG9C,MAAM,EAAE,aAAa,EACrB,UAAU,EAAE,MAAM;IAY/B,IAAI,IAAI,OAAO,CAAC,IAAI,CAAC;IA0B3B,yEAAyE;IACzE,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,iBAAiB,GAAG,IAAI;IAW/D,YAAY,IAAI,OAAO;IAIvB;;;OAGG;IACG,UAAU,IAAI,OAAO,CAAC,OAAO,CAAC;CAgBrC;AAGD,wBAAsB,eAAe,CAAC,gBAAgB,EAAE;IACtD,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,sEAAsE;IACtE,QAAQ,CAAC,cAAc,CAAC,EAAE,MAAM,CAAC;CAClC,GAAG,OAAO,CAAC,IAAI,CAAC,CAuuBhB"}

package/dist/engine.js

@@ -14,6 +14,7 @@ import * as path from "node:path";
 import { performance } from "node:perf_hooks";
 import { fileURLToPath } from "node:url";
 import { BOUNDED_READ_HELPER_DEFINITION, assertWithinQueryLimits, boundedReadGoal, normalizeQueryLimits, queryLimitsFromEnv, settleBoundedRead, } from "./engine-limits.js";
+import { kibiPackageVersions } from "./package-versions.js";
 import { writePerformanceTraceEvent } from "./performance-trace.js";
 import { PrologProcess, resolveKbPlPath } from "./prolog.js";
 import { parseEntityFromList, parseListOfLists } from "./prolog/codec.js";
@@ -33,7 +34,18 @@ const READ_LIMITED_METHODS = new Set([
 ]);
 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";
+/**
+ * Package versions this engine build carries (KIBI_PACKAGE_VERSIONS when
+ * set). The client sends them on every request and the daemon reports its
+ * own in the handshake; a daemon with other versions is replaced, never
+ * reused.
+ */
+// implements REQ-engine-daemon-package-versions
+export function enginePackageVersions() {
+    return kibiPackageVersions();
+}
+/** @deprecated The versions at module load; call enginePackageVersions(). */
+export const ENGINE_PACKAGE_VERSIONS = kibiPackageVersions();
 /**
  * Identity of the SWI-Prolog this process would launch (`<bin>@<version>`).
  * The daemon and every client compare it; a daemon running a different
@@ -864,6 +876,10 @@ export class EngineClient {
                             env: {
                                 ...process.env,
                                 KIBI_ENGINE_PROTOCOL: String(ENGINE_PROTOCOL_VERSION),
+                                // The daemon reports the versions of the client that
+                                // started it, so this client and its own daemon agree even
+                                // when the daemon entry is resolved from a bundled host.
+                                KIBI_PACKAGE_VERSIONS: enginePackageVersions(),
                             },
                         });
                         await new Promise((resolve, reject) => {
@@ -978,7 +994,7 @@ export class EngineClient {
                         ...limits,
                         id,
                         protocolVersion: ENGINE_PROTOCOL_VERSION,
-                        packageVersions: ENGINE_PACKAGE_VERSIONS,
+                        packageVersions: enginePackageVersions(),
                         prologIdentity: engineSwiplIdentity(),
                         workspaceRoot: this.workspaceRoot,
                         branch: this.branch,
@@ -1092,7 +1108,7 @@ export class EngineClient {
             method: "cancel",
             cancelOf: requestId,
             protocolVersion: ENGINE_PROTOCOL_VERSION,
-            packageVersions: ENGINE_PACKAGE_VERSIONS,
+            packageVersions: enginePackageVersions(),
             prologIdentity: engineSwiplIdentity(),
             workspaceRoot: this.workspaceRoot,
             branch: this.branch,
@@ -1136,30 +1152,68 @@ export class EngineClient {
             return null;
         return parseEngineAttachmentIdentity(status.bindings.JsonString);
     }
-    async daemonRuntimeMatches() {
+    /** The live daemon's handshake: its SWI-Prolog and package versions. */
+    async daemonHandshake() {
         const reply = await this.request({
             method: "handshake",
         });
-        return reply?.prologIdentity === engineSwiplIdentity();
+        return {
+            prologIdentity: typeof reply?.prologIdentity === "string" ? reply.prologIdentity : null,
+            packageVersions: typeof reply?.packageVersions === "string"
+                ? reply.packageVersions
+                : null,
+        };
+    }
+    /**
+     * The identity a live daemon reports, without starting one; null when no
+     * daemon serves this workspace and branch. The connection is closed again.
+     */
+    // implements REQ-engine-daemon-package-versions
+    async inspectLiveDaemon() {
+        const wasConnected = this.isRunning();
+        if (!wasConnected)
+            await this.connect(false);
+        if (!this.isRunning())
+            return null;
+        try {
+            return await this.daemonHandshake();
+        }
+        finally {
+            if (!wasConnected)
+                await this.terminate();
+        }
+    }
+    /** Why the live daemon may not serve this client, or null when it may. */
+    async daemonRuntimeMismatch() {
+        const daemon = await this.daemonHandshake();
+        const packageVersions = enginePackageVersions();
+        if (daemon.packageVersions !== packageVersions)
+            return `Kibi engine is running other package versions (${daemon.packageVersions ?? "not reported"}) than this client (${packageVersions})`;
+        if (daemon.prologIdentity !== engineSwiplIdentity())
+            return `Kibi engine is running a different SWI-Prolog than this client resolved (${engineSwiplIdentity()})`;
+        return null;
     }
     /**
-     * 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
+     * A live daemon keeps the SWI-Prolog and the package versions 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) or carries other package versions (a daemon left
+     * by another install, for example one a git hook started), the daemon is
      * stopped and replaced; it is never reused.
      */
-    // implements REQ-prolog-daemon-runtime-identity
+    // implements REQ-prolog-daemon-runtime-identity, REQ-engine-daemon-package-versions
     async reconcileRuntime() {
         if (this.replacingStaleDaemon || this.socket === null)
             return;
-        if (await this.daemonRuntimeMatches())
+        if ((await this.daemonRuntimeMismatch()) === null)
             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`);
+            const mismatch = await this.daemonRuntimeMismatch();
+            if (mismatch !== null) {
+                throw new Error(`${mismatch} after replacing it; run 'kibi engine stop' and retry`);
             }
         }
         finally {
@@ -1577,6 +1631,7 @@ export async function runEngineDaemon(requestedOptions) {
     await session.boot();
     let attachedIdentity = readEngineAttachmentIdentity(branchPath);
     const serverPrologIdentity = engineSwiplIdentity();
+    const serverPackageVersions = enginePackageVersions();
     mkdirSync(path.dirname(options.socketPath), { recursive: true, mode: 0o700 });
     if (existsSync(options.socketPath)) {
         const isLivePeerSignal = (error) => {
@@ -1739,23 +1794,22 @@ export async function runEngineDaemon(requestedOptions) {
         if (request.protocolVersion !== ENGINE_PROTOCOL_VERSION) {
             throw new Error(`Kibi engine protocol mismatch: client=${request.protocolVersion ?? "missing"}, server=${ENGINE_PROTOCOL_VERSION}`);
         }
-        const expectedPackages = process.env.KIBI_PACKAGE_VERSIONS;
-        if (expectedPackages !== undefined &&
-            request.packageVersions !== expectedPackages) {
-            throw new Error(`Kibi engine package-version mismatch: client=${request.packageVersions ?? "missing"}, server=${expectedPackages}`);
-        }
         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
+        // A client from another install (other package versions) or one that
+        // resolved a different Prolog must not be served by this daemon.
+        // Handshake reports both identities 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 (request.method !== "handshake" && request.method !== "stop") {
+            if (request.packageVersions !== serverPackageVersions) {
+                throw new Error(`Kibi engine package-version mismatch: client=${request.packageVersions ?? "missing"}, server=${serverPackageVersions}`);
+            }
+            if (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
@@ -2037,7 +2091,10 @@ export async function runEngineDaemon(requestedOptions) {
                     throw new Error("export.targetDirectory is required");
                 return prolog.query(`kb_storage_export('${quoteProlog(request.targetDirectory)}')`);
             case "handshake":
-                return { prologIdentity: serverPrologIdentity };
+                return {
+                    prologIdentity: serverPrologIdentity,
+                    packageVersions: serverPackageVersions,
+                };
             case "stop":
                 setImmediate(() => void shutdown());
                 return { stopped: true };
@@ -2134,7 +2191,7 @@ export async function runEngineDaemon(requestedOptions) {
                             id: request.id,
                             ok: false,
                             error: "Kibi engine is shutting down; request was not executed",
-                            serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
+                            serverPackageVersions,
                         });
                         return;
                     }
@@ -2149,7 +2206,7 @@ export async function runEngineDaemon(requestedOptions) {
                                 id: request.id,
                                 ok: false,
                                 error: "Kibi engine request cancelled",
-                                serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
+                                serverPackageVersions,
                             });
                             return;
                         }
@@ -2159,7 +2216,7 @@ export async function runEngineDaemon(requestedOptions) {
                                 id: request.id,
                                 ok: true,
                                 result,
-                                serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
+                                serverPackageVersions,
                             });
                         }
                         catch (error) {
@@ -2167,7 +2224,7 @@ export async function runEngineDaemon(requestedOptions) {
                                 id: request.id,
                                 ok: false,
                                 error: error instanceof Error ? error.message : String(error),
-                                serverPackageVersions: ENGINE_PACKAGE_VERSIONS,
+                                serverPackageVersions,
                             });
                         }
                         finally {

package/dist/intent-search.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"intent-search.d.ts","sourceRoot":"","sources":["../src/intent-search.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"intent-search.d.ts","sourceRoot":"","sources":["../src/intent-search.ts"],"names":[],"mappings":"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"}

package/dist/intent-search.js

@@ -1,6 +1,7 @@
 import path from "node:path";
 import { bodySnippetLine } from "./entity-body-context.js";
 import { escapeAtom, normalizeEntityId, parseTriples } from "./prolog/codec.js";
+import { isProvenanceStub } from "./provenance-stub.js";
 import { listSearchCandidates, loadEntityRows, loadSearchCandidates, } from "./public/operations/discovery-entities.js";
 import { loadMarkdownBody } from "./search-ranking.js";
 const GRAPH_RELATIONSHIPS = [
@@ -108,6 +109,9 @@ const NON_GOVERNING_STATUSES = new Set([
     "archived",
 ]);
 const NON_GOVERNING_FACTOR = 0.5;
+// A bootstrap provenance stub states no claim: it is demoted and, whatever
+// its score, sorted after every match that is not a stub.
+const PROVENANCE_STUB_FACTOR = 0.25;
 const AMBIGUOUS_MARGIN = 0.05;
 const MAX_CANDIDATES = 10_000;
 const MAX_GRAPH_SEEDS = 5;
@@ -280,7 +284,7 @@ function entityTokens(entity, body) {
     ENTITY_TOKENS.set(entity, computed);
     return computed;
 }
-function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence, documentFrequency, documentCount, body, superseded = false) {
+function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence, documentFrequency, documentCount, body, superseded = false, provenanceStub = false) {
     const { title: titleTokens, metadata: metadataTokens, bodyTokens, } = entityTokens(entity, body);
     const allSignalTokens = Array.from(new Set(queryTokens));
     // BM25-style inverse document frequency over title, metadata and body:
@@ -335,10 +339,14 @@ function scoreEntity(entity, queryTokens, facets, sourceEvidence, graphEvidence,
     const score = Math.min(1, lexicalScore * 0.58 +
         facetScore * 0.17 +
         sourceScore * 0.2 +
-        graphScore * 0.05) * (nonGoverning ? NON_GOVERNING_FACTOR : 1);
+        graphScore * 0.05) *
+        (nonGoverning ? NON_GOVERNING_FACTOR : 1) *
+        (provenanceStub ? PROVENANCE_STUB_FACTOR : 1);
     const reasons = [];
     if (nonGoverning)
         reasons.push(superseded ? "demoted: superseded" : `demoted: ${status}`);
+    if (provenanceStub)
+        reasons.push("demoted: provenance stub");
     if (lexicalScore > 0)
         reasons.push("intent token match");
     if (matchedFacets.length > 0)
@@ -380,7 +388,7 @@ async function readBodies(entities, workspaceRoot, cache) {
         cache.get(String(entity.source ?? "")) ?? null,
     ]));
 }
-// implements REQ-kibi-intent-aware-source-discovery
+// implements REQ-kibi-intent-aware-source-discovery, REQ-bootstrap-provenance-stubs
 export async function rankIntentEntities(entities, options, workspaceRoot, graphEdges = [], bodyCache = new Map()) {
     const queryTokens = tokens(options.query);
     const facets = facetValues(options.semanticFacets);
@@ -416,7 +424,7 @@ export async function rankIntentEntities(entities, options, workspaceRoot, graph
         // already capped; unbounded parallel paths only add noise to receipts.
         const graphEvidence = (graphByEntity.get(entityId) ?? []).slice(0, 8);
         const body = bodies.get(entity) ?? null;
-        const scored = scoreEntity(entity, allTokens, facets, sourceEvidence, graphEvidence, documentFrequency, entities.length, body, supersededIds.has(entityId));
+        const scored = scoreEntity(entity, allTokens, facets, sourceEvidence, graphEvidence, documentFrequency, entities.length, body, supersededIds.has(entityId), isProvenanceStub(entity));
         if (scored.score < minScore)
             continue;
         const snippet = body === null
@@ -439,6 +447,10 @@ export async function rankIntentEntities(entities, options, workspaceRoot, graph
         });
     }
     ranked.sort((left, right) => {
+        const stubOrder = Number(isProvenanceStub(left.entity)) -
+            Number(isProvenanceStub(right.entity));
+        if (stubOrder !== 0)
+            return stubOrder;
         if (right.score !== left.score)
             return right.score - left.score;
         const typeOrder = String(left.entity.type ?? "").localeCompare(String(right.entity.type ?? ""));

package/dist/operations/bootstrap/candidate-helpers.d.ts

@@ -23,6 +23,11 @@ export declare function withDocumentBody(step: Readonly<Record<string, unknown>>
 export declare function bootstrapProvenance(provider: string, location: string, confidence: number): string;
 /** Body for a non-requirement entity: its title, then its provenance. */
 export declare function provenanceBody(title: string, provenance: string): string;
+/**
+ * Body for a provenance stub: the title, the provenance, and a sentence that
+ * says the entry is a stub so a reader never mistakes it for a claim.
+ */
+export declare function provenanceStubBody(title: string, provenance: string): string;
 /**
  * Body for a requirement found in prose: the statement, the provenance as
  * its Context and the quoted statement with its location as its Source.

package/dist/operations/bootstrap/candidate-helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidate-helpers.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidate-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAMtD;AAED,wBAAgB,MAAM,CACpB,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,EAE5D,MAAM,EAAE,CAAC,EACT,aAAa,GAAE,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,EAAO,GACP,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQnC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,cAAc,GACvB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CA0C9C;AAED;;;GAGG;AAEH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnC;AAED;;;;GAIG;AAEH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED,yEAAyE;AAEzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;GAGG;AAEH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR"}
+{"version":3,"file":"candidate-helpers.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidate-helpers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,gCAAgC,CAAC;AAIrE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEpD;AAED,wBAAgB,IAAI,CAAC,KAAK,EAAE,MAAM,EAAE,KAAK,SAAK,GAAG,MAAM,CAMtD;AAED,wBAAgB,MAAM,CACpB,CAAC,SAAS;IAAE,QAAQ,CAAC,IAAI,CAAC,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,EAAE,CAAC,EAAE,OAAO,CAAA;CAAE,EAE5D,MAAM,EAAE,CAAC,EACT,aAAa,GAAE,SAAS;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;CACrB,EAAO,GACP,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAQnC;AAED,wBAAgB,UAAU,CACxB,QAAQ,EAAE,cAAc,GACvB,SAAS,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EAAE,CA0C9C;AAED;;;GAGG;AAEH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,EACvC,IAAI,EAAE,MAAM,GACX,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC,CAEnC;AAED;;;;GAIG;AAEH,wBAAgB,mBAAmB,CACjC,QAAQ,EAAE,MAAM,EAChB,QAAQ,EAAE,MAAM,EAChB,UAAU,EAAE,MAAM,GACjB,MAAM,CAER;AAED,yEAAyE;AAEzE,wBAAgB,cAAc,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAExE;AAED;;;GAGG;AAEH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,GAAG,MAAM,CAE5E;AAED;;;GAGG;AAEH,wBAAgB,yBAAyB,CACvC,SAAS,EAAE,MAAM,EACjB,UAAU,EAAE,MAAM,EAClB,SAAS,EAAE,MAAM,GAChB,MAAM,CAMR"}

package/dist/operations/bootstrap/candidate-helpers.js

@@ -83,6 +83,14 @@ export function bootstrapProvenance(provider, location, confidence) {
 export function provenanceBody(title, provenance) {
     return `${title.trim()}\n\n${provenance}\n`;
 }
+/**
+ * Body for a provenance stub: the title, the provenance, and a sentence that
+ * says the entry is a stub so a reader never mistakes it for a claim.
+ */
+// implements REQ-bootstrap-provenance-stubs
+export function provenanceStubBody(title, provenance) {
+    return `${title.trim()}\n\n${provenance} This entry is a provenance stub: the provider found the source but no claim about it, so it is tagged bootstrap:provenance-stub, ranked after every other search match and not counted as knowledge by gap or coverage reports.\n`;
+}
 /**
  * Body for a requirement found in prose: the statement, the provenance as
  * its Context and the quoted statement with its location as its Source.

package/dist/operations/bootstrap/candidates.d.ts

@@ -1,5 +1,16 @@
 import { type CandidateBuildResult } from "./markdown-candidates.js";
 import type { SubjectKeyRegistry } from "./requirement-claims.js";
-import type { BootstrapEvidence } from "./types.js";
+import type { BootstrapEvidence, Candidate } from "./types.js";
+/**
+ * The claim a provider states about its source, or undefined when the
+ * provider found only that the file exists. A provider candidate without a
+ * claim is a provenance stub: its body would be nothing but the provenance
+ * template, so it is written as a `meta` fact tagged
+ * `bootstrap:provenance-stub` instead of an observation that search, gap and
+ * coverage reports would otherwise read as knowledge.
+ */
+export declare function providerClaim(item: BootstrapEvidence): string | undefined;
+/** Whether a planned candidate writes a provenance stub. */
+export declare function isProvenanceStubCandidate(candidate: Candidate): boolean;
 export declare function buildBootstrapCandidates(evidence: readonly BootstrapEvidence[], existingIds: ReadonlySet<string>, minConfidence: number, includeGenericMarkdown: boolean, subjectKeys?: SubjectKeyRegistry): CandidateBuildResult;
 //# sourceMappingURL=candidates.d.ts.map

package/dist/operations/bootstrap/candidates.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAYA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EACV,iBAAiB,EAGlB,MAAM,YAAY,CAAC;AAuHpB,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,EAC/B,WAAW,CAAC,EAAE,kBAAkB,GAC/B,oBAAoB,CAiEtB"}
+{"version":3,"file":"candidates.d.ts","sourceRoot":"","sources":["../../../src/operations/bootstrap/candidates.ts"],"names":[],"mappings":"AAcA,OAAO,EACL,KAAK,oBAAoB,EAE1B,MAAM,0BAA0B,CAAC;AAClC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,yBAAyB,CAAC;AAClE,OAAO,KAAK,EACV,iBAAiB,EACjB,SAAS,EAEV,MAAM,YAAY,CAAC;AA8CpB;;;;;;;GAOG;AAEH,wBAAgB,aAAa,CAAC,IAAI,EAAE,iBAAiB,GAAG,MAAM,GAAG,SAAS,CAIzE;AAED,4DAA4D;AAE5D,wBAAgB,yBAAyB,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO,CAOvE;AAgFD,wBAAgB,wBAAwB,CACtC,QAAQ,EAAE,SAAS,iBAAiB,EAAE,EACtC,WAAW,EAAE,WAAW,CAAC,MAAM,CAAC,EAChC,aAAa,EAAE,MAAM,EACrB,sBAAsB,EAAE,OAAO,EAC/B,WAAW,CAAC,EAAE,kBAAkB,GAC/B,oBAAoB,CAiEtB"}