kibi-cli 1.0.1 → 2.1.0

package/dist/prolog/error-terms.js

@@ -0,0 +1,334 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+*/
+import { splitTopLevelGeneral } from "./codec.js";
+/**
+ * Structured transport for Prolog errors.
+ *
+ * kb.pl throws ISO-style terms (`error(permission_error(save, kb,
+ * stale_snapshot), Context)`). The query wrappers in prolog.ts write the
+ * thrown term — quoted, depth-bounded — to stderr behind this sentinel so
+ * TypeScript can classify the term structurally instead of re-parsing SWI's
+ * human-readable print_message output. Text heuristics remain only as a
+ * fallback for errors that never pass through a wrapper (startup failures,
+ * older kibi-core versions).
+ */
+// implements REQ-core-prolog-process-management
+export const PROLOG_ERROR_TERM_PREFIX = "__KIBI_ERROR__:";
+/** Extract the first structured error term line from raw stderr text. */
+// implements REQ-core-prolog-process-management
+export function extractPrologErrorRecord(text) {
+    const match = text.match(/^__KIBI_ERROR__:(.+)$/m);
+    const term = match?.[1];
+    if (term === undefined)
+        return null;
+    return parsePrologErrorTerm(term);
+}
+/** Parse a written error term such as `error(permission_error(...), Context)`. */
+// implements REQ-core-prolog-process-management
+export function parsePrologErrorTerm(termText) {
+    const trimmed = termText.trim();
+    const formalMatch = trimmed.match(/^error\((.*)\)$/s);
+    const formalAndContext = formalMatch?.[1];
+    if (formalAndContext === undefined)
+        return null;
+    const [formalRaw, contextRaw] = splitTopLevelGeneral(formalAndContext, ",");
+    if (!formalRaw)
+        return null;
+    const context = contextRaw ? parseContextTerm(contextRaw) : null;
+    const parsed = parseFormalTerm(formalRaw);
+    if (!parsed)
+        return null;
+    switch (parsed.kind) {
+        case "invalid_relationship": {
+            const formatted = contextRaw
+                ? parseInvalidRelationshipContext(contextRaw)
+                : null;
+            const relationship = formatted !== null
+                ? substituteRelationshipArgs(formatted.formatTemplate, formatted.formatArgs)
+                : null;
+            if (relationship === null) {
+                return {
+                    code: "invalid_relationship",
+                    message: "Invalid relationship type or direction",
+                };
+            }
+            return {
+                code: "invalid_relationship",
+                relationship,
+                message: `Invalid relationship: ${relationship.relType} from ${relationship.fromType} to ${relationship.toType}`,
+            };
+        }
+        case "stale_snapshot":
+            return {
+                code: "stale_snapshot",
+                message: "KB snapshot is stale; reattach or refresh the runtime before retrying (stale_snapshot)",
+            };
+        case "audit_locked":
+            return {
+                code: "audit_locked",
+                message: "Audit journal is locked by another Kibi runtime; restart the stale MCP/CLI session before retrying",
+            };
+        case "store_locked": {
+            const detail = parseStoreLockedContext(contextRaw);
+            const holder = detail.owner;
+            const holderSummary = holder === null
+                ? "an unidentified holder"
+                : `pid ${holder.pid ?? "?"}${holder.workspaceRoot !== undefined ? ` for ${holder.workspaceRoot}` : ""}${holder.startedAt !== undefined ? ` since ${holder.startedAt}` : ""}`;
+            return {
+                code: "permission_denied",
+                storeLocked: detail,
+                message: `Branch store is locked by ${holderSummary}; close that session or, if it is dead, retry so Kibi can break the stale lock (store_locked)`,
+            };
+        }
+        case "permission_denied":
+            return {
+                code: "permission_denied",
+                message: "Access denied or KB locked",
+            };
+        case "entity_not_found": {
+            const entityId = unquoteAtom(parsed.entityId);
+            const role = parseEntityRole(context?.message);
+            const verb = role === "source"
+                ? "Source entity"
+                : role === "target"
+                    ? "Target entity"
+                    : "Entity";
+            const record = {
+                code: "entity_not_found",
+                entityId,
+                message: `${verb} does not exist: ${entityId}`,
+            };
+            return role === undefined ? record : { ...record, role };
+        }
+        case "contradiction": {
+            const conflicts = parsed.pairs.map((pair) => ({
+                reason: pair[0],
+                otherId: pair[1],
+            }));
+            return {
+                code: "contradiction",
+                conflicts,
+                message: context?.message ??
+                    "Contradiction detected: conflicting requirements without a supersedes relationship",
+            };
+        }
+        case "validation_error":
+            return {
+                code: "validation_error",
+                message: parsed.message,
+            };
+    }
+}
+function parseContextTerm(contextRaw) {
+    const contextMatch = contextRaw.trim().match(/^context\((.*)\)$/s);
+    if (contextMatch?.[1] === undefined) {
+        const message = unquoteAtom(contextRaw.trim());
+        return message === "" ? null : { message };
+    }
+    const parts = splitTopLevelGeneral(contextMatch[1], ",");
+    if (parts.length === 0)
+        return null;
+    const predicate = parts[0]?.trim();
+    const message = parts[1] ? unquoteAtom(parts[1].trim()) : "";
+    return {
+        ...(predicate ? { predicate } : {}),
+        ...(message ? { message } : {}),
+    };
+}
+/**
+ * Parse the context of a store-locked error thrown by kb.pl:
+ * `kb_store_locked('<owner-json>', '<persistency-directory>')`. The owner JSON
+ * is best-effort: any malformed content yields a null owner while the lock
+ * directory is still surfaced.
+ */
+// implements REQ-core-journaled-engine-persistence
+function parseStoreLockedContext(contextRaw) {
+    const empty = {
+        owner: null,
+        lockDirectory: "",
+    };
+    if (!contextRaw)
+        return empty;
+    const inner = contextRaw.trim().match(/^kb_store_locked\((.*)\)$/s)?.[1];
+    if (inner === undefined)
+        return empty;
+    const parts = splitTopLevelGeneral(inner, ",");
+    const ownerRaw = parts[0]?.trim();
+    const lockRaw = parts[1]?.trim();
+    const lockDirectory = lockRaw ? unquoteAtom(lockRaw) : "";
+    // kb.pl preserves the original attach failure so nothing is masked by the
+    // store_locked re-brand (e.g. a permissions problem vs a lock clash).
+    const originalRaw = parts[2]?.trim();
+    const originalError = originalRaw ? unquoteAtom(originalRaw) : "";
+    if (!ownerRaw || ownerRaw === '""' || ownerRaw === "''") {
+        return {
+            owner: null,
+            lockDirectory,
+            ...(originalError !== "" ? { originalError } : {}),
+        };
+    }
+    try {
+        const parsed = JSON.parse(unquoteAtom(ownerRaw));
+        if (parsed === null || typeof parsed !== "object") {
+            return {
+                owner: null,
+                lockDirectory,
+                ...(originalError !== "" ? { originalError } : {}),
+            };
+        }
+        return {
+            owner: {
+                ...(typeof parsed.pid === "number" ? { pid: parsed.pid } : {}),
+                ...(typeof parsed.workspaceRoot === "string"
+                    ? { workspaceRoot: parsed.workspaceRoot }
+                    : {}),
+                ...(typeof parsed.bootId === "string" ? { bootId: parsed.bootId } : {}),
+                ...(typeof parsed.startedAt === "string"
+                    ? { startedAt: parsed.startedAt }
+                    : {}),
+            },
+            lockDirectory,
+            ...(originalError !== "" ? { originalError } : {}),
+        };
+    }
+    catch {
+        return {
+            owner: null,
+            lockDirectory,
+            ...(originalError !== "" ? { originalError } : {}),
+        };
+    }
+}
+function parseFormalTerm(formalRaw) {
+    const formal = formalRaw.trim();
+    const functorMatch = formal.match(/^([a-z][A-Za-z0-9_]*)\((.*)\)$/s);
+    if (functorMatch?.[1] === undefined || functorMatch[2] === undefined) {
+        return null;
+    }
+    const functor = functorMatch[1];
+    const args = functorMatch[2].trim()
+        ? splitTopLevelGeneral(functorMatch[2], ",")
+        : [];
+    if (functor === "permission_error") {
+        const operation = args[0]?.trim();
+        const resource = args[1]?.trim();
+        const detail = args[2]?.trim();
+        if (detail === "stale_snapshot")
+            return { kind: "stale_snapshot" };
+        if (operation === "lock" && resource === "audit_log") {
+            return { kind: "audit_locked" };
+        }
+        if (operation === "attach" && resource === "kb_store") {
+            return { kind: "store_locked" };
+        }
+        return { kind: "permission_denied" };
+    }
+    if (functor === "existence_error" && args[0]?.trim() === "entity") {
+        const entityId = args[1]?.trim();
+        if (entityId === undefined)
+            return null;
+        return { kind: "entity_not_found", entityId: unquoteAtom(entityId) };
+    }
+    if (functor === "type_error" && args[0]?.trim() === "relationship") {
+        return { kind: "invalid_relationship" };
+    }
+    if (functor === "kb_contradiction") {
+        const listText = args[0]?.trim() ?? "[]";
+        const pairs = parseContradictionPairs(listText);
+        return { kind: "contradiction", pairs };
+    }
+    if (functor === "validation_error") {
+        const message = args[0]?.trim();
+        if (message === undefined)
+            return null;
+        return { kind: "validation_error", message: unquoteAtom(message) };
+    }
+    return null;
+}
+/** Fill the relationship triple from a `'...~w...'-[Rel, From, To]` context. */
+function parseInvalidRelationshipContext(contextRaw) {
+    const contextMatch = contextRaw.trim().match(/^context\((.*)\)$/s);
+    const inner = contextMatch?.[1];
+    if (inner === undefined)
+        return null;
+    const parts = splitTopLevelGeneral(inner, ",");
+    const formatted = parts[1]?.trim();
+    if (formatted === undefined)
+        return null;
+    const formatMatch = formatted.match(/^(.*)-\[(.*)\]$/s);
+    const template = formatMatch?.[1];
+    const argsText = formatMatch?.[2];
+    if (template === undefined || argsText === undefined)
+        return null;
+    const formatArgs = argsText.trim()
+        ? splitTopLevelGeneral(argsText, ",").map((arg) => unquoteAtom(arg.trim()))
+        : [];
+    return { formatTemplate: unquoteAtom(template.trim()), formatArgs };
+}
+function substituteRelationshipArgs(template, args) {
+    if (template === null || args === null || args.length < 3)
+        return null;
+    const substituted = template
+        .split("~w")
+        .map((chunk, index) => index === 0 ? chunk : `${args[index - 1] ?? ""}${chunk}`)
+        .join("");
+    const match = substituted.match(/^Invalid relationship:\s*(\S+)\s+from\s+(\S+)\s+to\s+(\S+)\s*$/);
+    if (!match?.[1] || !match[2] || !match[3])
+        return null;
+    return {
+        relType: match[1],
+        fromType: match[2],
+        toType: match[3],
+    };
+}
+function parseContradictionPairs(listText) {
+    const trimmed = listText.trim();
+    if (!trimmed.startsWith("[") || !trimmed.endsWith("]"))
+        return [];
+    const inner = trimmed.slice(1, -1).trim();
+    if (inner === "")
+        return [];
+    return splitTopLevelGeneral(inner, ",")
+        .map((item) => splitTopLevelGeneral(item.trim(), "-"))
+        .map((pair) => {
+        const reason = pair[0] ?? "";
+        const otherId = pair[1] ?? "";
+        return [unquoteAtom(reason.trim()), unquoteAtom(otherId.trim())];
+    })
+        .filter((pair) => pair[0] !== "" && pair[1] !== "");
+}
+function parseEntityRole(message) {
+    if (message?.includes("Source entity does not exist"))
+        return "source";
+    if (message?.includes("Target entity does not exist"))
+        return "target";
+    return undefined;
+}
+/** Strip SWI quoted-atom quoting and unescape standard character escapes. */
+function unquoteAtom(value) {
+    const trimmed = value.trim();
+    if (trimmed.length >= 2 && trimmed.startsWith("'") && trimmed.endsWith("'")) {
+        const inner = trimmed.slice(1, -1);
+        return inner
+            .replace(/\\'/g, "'")
+            .replace(/\\\\/g, "\\")
+            .replace(/\\n/g, "\n")
+            .replace(/\\t/g, "\t");
+    }
+    return trimmed;
+}

package/dist/prolog/janitor.d.ts

@@ -0,0 +1,50 @@
+import { type StoreLockHolderState } from "./store-lock.js";
+/**
+ * Orphan janitor for engine daemons and branch-store locks.
+ *
+ * Kibi's lock stewardship records who holds a branch store, but recorded
+ * state alone still needs a sweep: daemons killed outright leave sockets and
+ * pid files, worktree removals strand daemons whose workspace is gone, and
+ * crashed engines leave journals behind. The janitor classifies each piece
+ * of evidence and cleans only what is provably stale.
+ */
+export interface StoreLockFinding {
+    readonly kind: "store-lock";
+    readonly storePath: string;
+    readonly workspaceRoot?: string;
+    readonly pid?: number;
+    readonly startedAt?: string;
+    readonly holderState: StoreLockHolderState;
+    readonly workspaceExists: boolean;
+    readonly action: "clean" | "kill-and-clean" | "keep";
+}
+export interface SocketFinding {
+    readonly kind: "socket";
+    readonly socketPath: string;
+    readonly pid?: number;
+    readonly holderState: StoreLockHolderState;
+    readonly action: "clean" | "keep";
+}
+export type JanitorFinding = StoreLockFinding | SocketFinding;
+export interface JanitorOptions {
+    /** Branch stores live under <workspaceRoot>/.kb/branches. */
+    readonly workspaceRoot: string;
+    /** Runtime directory holding daemon sockets and pid files. */
+    readonly runtimeDirectory: string;
+    /** Also sweep runtime-directory sockets from other workspaces. */
+    readonly all?: boolean;
+    /** Execute cleanups; when false the scan only reports (dry run). */
+    readonly apply?: boolean;
+}
+/** Scan one branch store's ownership journal and clean stale artifacts. */
+export declare function sweepStoreLock(storePath: string, apply: boolean): StoreLockFinding | null;
+/** Scan all branch stores under <workspaceRoot>/.kb/branches. */
+export declare function sweepWorkspaceStoreLocks(options: JanitorOptions): StoreLockFinding[];
+/**
+ * Sweep runtime-directory daemon sockets. A socket is stale when its pid
+ * file records a dead process or a connect attempt is refused.
+ */
+export declare function sweepRuntimeSockets(options: JanitorOptions): SocketFinding[];
+/** Full janitor sweep across branch stores and (optionally) runtime sockets. */
+export declare function runJanitor(options: JanitorOptions): JanitorFinding[];
+//# sourceMappingURL=janitor.d.ts.map

package/dist/prolog/janitor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"janitor.d.ts","sourceRoot":"","sources":["../../src/prolog/janitor.ts"],"names":[],"mappings":"AAoBA,OAAO,EACL,KAAK,oBAAoB,EAK1B,MAAM,iBAAiB,CAAC;AAEzB;;;;;;;;GAQG;AAGH,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,aAAa,CAAC,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,gBAAgB,GAAG,MAAM,CAAC;CACtD;AAED,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IACxB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,oBAAoB,CAAC;IAC3C,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,MAAM,CAAC;CACnC;AAED,MAAM,MAAM,cAAc,GAAG,gBAAgB,GAAG,aAAa,CAAC;AAE9D,MAAM,WAAW,cAAc;IAC7B,6DAA6D;IAC7D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,CAAC;IACvB,oEAAoE;IACpE,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,2EAA2E;AAE3E,wBAAgB,cAAc,CAC5B,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,GACb,gBAAgB,GAAG,IAAI,CA+CzB;AAED,iEAAiE;AAEjE,wBAAgB,wBAAwB,CACtC,OAAO,EAAE,cAAc,GACtB,gBAAgB,EAAE,CAepB;AAED;;;GAGG;AAEH,wBAAgB,mBAAmB,CAAC,OAAO,EAAE,cAAc,GAAG,aAAa,EAAE,CA8C5E;AAED,gFAAgF;AAEhF,wBAAgB,UAAU,CAAC,OAAO,EAAE,cAAc,GAAG,cAAc,EAAE,CAKpE"}

package/dist/prolog/janitor.js

@@ -0,0 +1,154 @@
+/*
+ Kibi — repo-local, per-branch, queryable long-term memory for software projects
+ Copyright (C) 2026 Piotr Franczyk
+
+ This program is free software: you can redistribute it and/or modify
+ it under the terms of the GNU Affero General Public License as published by
+ the Free Software Foundation, either version 3 of the License, or
+ (at your option) any later version.
+
+ This program is distributed in the hope that it will be useful,
+ but WITHOUT ANY WARRANTY; without even the implied warranty of
+ MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+ GNU Affero General Public License for more details.
+
+ You should have received a copy of the GNU Affero General Public License
+ along with this program.  If not, see <https://www.gnu.org/licenses/>.
+ */
+import { existsSync, readFileSync, readdirSync, rmSync } from "node:fs";
+import { join } from "node:path";
+import { breakStoreLock, classifyStoreLockHolder, isProcessAlive, readStoreLockOwner, } from "./store-lock.js";
+/** Scan one branch store's ownership journal and clean stale artifacts. */
+// implements REQ-core-journaled-engine-persistence
+export function sweepStoreLock(storePath, apply) {
+    const journal = readStoreLockOwner(storePath);
+    if (journal === null)
+        return null;
+    const owner = journal.owner;
+    const holderState = classifyStoreLockHolder(owner);
+    const workspaceRoot = owner.workspaceRoot;
+    const workspaceExists = workspaceRoot !== undefined && existsSync(workspaceRoot);
+    const workspaceVerifiablyGone = workspaceRoot !== undefined && !workspaceExists;
+    let action;
+    if (holderState === "dead") {
+        action = "clean";
+    }
+    else if ((holderState === "alive" || holderState === "self") &&
+        workspaceVerifiablyGone) {
+        // A live daemon whose workspace is verifiably gone can never serve
+        // again; the watchdog should have stopped it already — this is the
+        // backstop. A journal without workspaceRoot stays hands-off: absence of
+        // evidence is not evidence of a removed workspace.
+        action = "kill-and-clean";
+    }
+    else {
+        action = "keep";
+    }
+    if (apply && action !== "keep") {
+        if (action === "kill-and-clean" && typeof owner.pid === "number") {
+            try {
+                process.kill(owner.pid, "SIGTERM");
+            }
+            catch {
+                // Already gone — fall through to artifact cleanup.
+            }
+        }
+        // Same artifact sweep as the attach-takeover path, so the janitor and
+        // the takeover agree on what stale artifacts exist.
+        breakStoreLock(join(storePath, "rdf"));
+    }
+    return {
+        kind: "store-lock",
+        storePath,
+        ...(workspaceRoot !== undefined ? { workspaceRoot } : {}),
+        ...(owner.pid !== undefined ? { pid: owner.pid } : {}),
+        ...(owner.startedAt !== undefined ? { startedAt: owner.startedAt } : {}),
+        holderState,
+        workspaceExists,
+        action,
+    };
+}
+/** Scan all branch stores under <workspaceRoot>/.kb/branches. */
+// implements REQ-core-journaled-engine-persistence
+export function sweepWorkspaceStoreLocks(options) {
+    const branchesDir = join(options.workspaceRoot, ".kb", "branches");
+    if (!existsSync(branchesDir))
+        return [];
+    const findings = [];
+    for (const entry of readdirSync(branchesDir)) {
+        const storePath = join(branchesDir, entry);
+        try {
+            if (!existsSync(join(storePath, "storage.json")))
+                continue;
+        }
+        catch {
+            continue;
+        }
+        const finding = sweepStoreLock(storePath, options.apply === true);
+        if (finding !== null)
+            findings.push(finding);
+    }
+    return findings;
+}
+/**
+ * Sweep runtime-directory daemon sockets. A socket is stale when its pid
+ * file records a dead process or a connect attempt is refused.
+ */
+// implements REQ-core-journaled-engine-persistence
+export function sweepRuntimeSockets(options) {
+    if (!options.all)
+        return [];
+    if (!existsSync(options.runtimeDirectory))
+        return [];
+    const findings = [];
+    for (const entry of readdirSync(options.runtimeDirectory)) {
+        if (!entry.endsWith(".sock"))
+            continue;
+        const socketPath = join(options.runtimeDirectory, entry);
+        const pidPath = `${socketPath}.pid`;
+        let pid;
+        if (existsSync(pidPath)) {
+            try {
+                const parsed = Number.parseInt(readFileSync(pidPath, "utf8").trim(), 10);
+                if (Number.isInteger(parsed) && parsed > 0)
+                    pid = parsed;
+            }
+            catch {
+                // The daemon being swept removed its pid file mid-scan; leave the
+                // pid unknown rather than failing the whole run.
+            }
+        }
+        const holderState = pid === undefined ? "unknown" : isProcessAlive(pid) ? "alive" : "dead";
+        if (holderState === "dead") {
+            if (options.apply === true) {
+                rmSync(socketPath, { force: true });
+                rmSync(pidPath, { force: true });
+            }
+            findings.push({
+                kind: "socket",
+                socketPath,
+                ...(pid !== undefined ? { pid } : {}),
+                holderState,
+                action: "clean",
+            });
+        }
+        else {
+            findings.push({
+                kind: "socket",
+                socketPath,
+                ...(pid !== undefined ? { pid } : {}),
+                holderState,
+                action: "keep",
+            });
+        }
+    }
+    return findings;
+}
+/** Full janitor sweep across branch stores and (optionally) runtime sockets. */
+// implements REQ-core-journaled-engine-persistence
+export function runJanitor(options) {
+    return [
+        ...sweepWorkspaceStoreLocks(options),
+        ...sweepRuntimeSockets(options),
+    ];
+}

package/dist/prolog/store-lock.d.ts

@@ -0,0 +1,45 @@
+import type { QueryResult } from "../prolog.js";
+import type { PrologStoreLockOwner } from "./error-terms.js";
+/** Linux boot id; guards against PID reuse across reboots. Null elsewhere. */
+export declare function currentBootId(): string | null;
+export declare function isProcessAlive(pid: number): boolean;
+export type StoreLockHolderState = "self" | "alive" | "dead" | "unknown";
+export declare function classifyStoreLockHolder(owner: PrologStoreLockOwner | null): StoreLockHolderState;
+/**
+ * Read an ownership journal from a branch store. Older builds kept the
+ * journal beside the rdf lock; the store-root location wins when both exist.
+ * Shared by the janitor sweep and the status stale-reason surfacing so both
+ * classify the same evidence with the same boot-id-aware semantics.
+ */
+export declare function readStoreLockOwner(storePath: string): {
+    owner: PrologStoreLockOwner;
+    journalPath: string;
+} | null;
+/**
+ * Remove the stale lock artifacts so a fresh attach can take the store.
+ * The rdf lock lives inside the persistency directory; the ownership journal
+ * lives at the branch-store root (older builds kept it beside the lock).
+ */
+export declare function breakStoreLock(rdfDirectory: string): void;
+export interface StoreLockTakeoverDecision {
+    readonly action: "break" | "surface";
+    readonly reason: string;
+}
+/**
+ * Decide whether a store-locked failure may be auto-healed. Only a provably
+ * dead holder (or a holder from a previous boot) is broken; live or unknown
+ * holders are surfaced so the operator can close the real session.
+ */
+export declare function decideStoreLockTakeover(owner: PrologStoreLockOwner | null): StoreLockTakeoverDecision;
+export interface StoreLockRetryContext {
+    readonly query: (goal: string) => Promise<QueryResult>;
+}
+/**
+ * A store-locked attach failure with a provably dead holder (crashed or
+ * killed engine, removed worktree) is safe to auto-heal: break the stale
+ * lock artifacts and retry once on the same port. Live or unverifiable
+ * holders are surfaced with the holder identity and remediation. Shared by
+ * the CLI runtime and the engine daemon attach paths.
+ */
+export declare function retryAttachAfterBreakingStaleLock(prolog: StoreLockRetryContext, kbPath: string, failed: QueryResult): Promise<QueryResult>;
+//# sourceMappingURL=store-lock.d.ts.map

package/dist/prolog/store-lock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store-lock.d.ts","sourceRoot":"","sources":["../../src/prolog/store-lock.ts"],"names":[],"mappings":"AAqBA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAEhD,OAAO,KAAK,EAAqB,oBAAoB,EAAE,MAAM,kBAAkB,CAAC;AAgBhF,8EAA8E;AAC9E,wBAAgB,aAAa,IAAI,MAAM,GAAG,IAAI,CAa7C;AAED,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAUnD;AAED,MAAM,MAAM,oBAAoB,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,GAAG,SAAS,CAAC;AAEzE,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,oBAAoB,GAAG,IAAI,GACjC,oBAAoB,CAYtB;AAED;;;;;GAKG;AAEH,wBAAgB,kBAAkB,CAChC,SAAS,EAAE,MAAM,GAChB;IAAE,KAAK,EAAE,oBAAoB,CAAC;IAAC,WAAW,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CA4B7D;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,YAAY,EAAE,MAAM,GAAG,IAAI,CAWzD;AAED,MAAM,WAAW,yBAAyB;IACxC,QAAQ,CAAC,MAAM,EAAE,OAAO,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CACrC,KAAK,EAAE,oBAAoB,GAAG,IAAI,GACjC,yBAAyB,CAoB3B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,OAAO,CAAC,WAAW,CAAC,CAAC;CACxD;AAED;;;;;;GAMG;AAEH,wBAAsB,iCAAiC,CACrD,MAAM,EAAE,qBAAqB,EAC7B,MAAM,EAAE,MAAM,EACd,MAAM,EAAE,WAAW,GAClB,OAAO,CAAC,WAAW,CAAC,CA4BtB"}