kibi-cli 0.19.0 → 2.0.0

package/dist/report/relative-time.d.ts

@@ -0,0 +1,4 @@
+export declare function parseTimestamp(value: unknown): Date | undefined;
+export declare function formatAbsoluteUtc(date: Date): string;
+export declare function formatRelativeAge(fromMs: number, nowMs: number): string;
+//# sourceMappingURL=relative-time.d.ts.map

package/dist/report/relative-time.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relative-time.d.ts","sourceRoot":"","sources":["../../src/report/relative-time.ts"],"names":[],"mappings":"AAKA,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,IAAI,GAAG,SAAS,CAK/D;AAGD,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CAOpD;AAED,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,CAuBvE"}

package/dist/report/relative-time.js

@@ -0,0 +1,46 @@
+const MINUTE_SECONDS = 60;
+const HOUR_SECONDS = 3_600;
+const DAY_SECONDS = 86_400;
+// implements REQ-kibi-html-health-report
+export function parseTimestamp(value) {
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return value;
+    if (typeof value !== "string" || value.trim() === "")
+        return undefined;
+    const parsed = Date.parse(value);
+    return Number.isFinite(parsed) ? new Date(parsed) : undefined;
+}
+// implements REQ-kibi-html-health-report
+export function formatAbsoluteUtc(date) {
+    const year = date.getUTCFullYear().toString().padStart(4, "0");
+    const month = (date.getUTCMonth() + 1).toString().padStart(2, "0");
+    const day = date.getUTCDate().toString().padStart(2, "0");
+    const hours = date.getUTCHours().toString().padStart(2, "0");
+    const minutes = date.getUTCMinutes().toString().padStart(2, "0");
+    return `${year}-${month}-${day} ${hours}:${minutes} UTC`;
+}
+export function formatRelativeAge(fromMs, nowMs) {
+    if (!Number.isFinite(fromMs) || !Number.isFinite(nowMs)) {
+        return "timestamp unavailable";
+    }
+    const deltaSeconds = Math.floor((nowMs - fromMs) / 1000);
+    if (deltaSeconds < 0)
+        return "in the future";
+    if (deltaSeconds < MINUTE_SECONDS)
+        return "just now";
+    const minutes = Math.floor(deltaSeconds / MINUTE_SECONDS);
+    if (minutes < 60)
+        return `${minutes}m ago`;
+    const hours = Math.floor(deltaSeconds / HOUR_SECONDS);
+    const remainingMinutes = minutes % 60;
+    if (hours < 24) {
+        return remainingMinutes === 0
+            ? `${hours}h ago`
+            : `${hours}h ${remainingMinutes}m ago`;
+    }
+    const days = Math.floor(deltaSeconds / DAY_SECONDS);
+    const remainingHours = hours % 24;
+    if (days < 7 && remainingHours > 0)
+        return `${days}d ${remainingHours}h ago`;
+    return `${days}d ago`;
+}

package/dist/report/report-view.d.ts

@@ -0,0 +1,17 @@
+export declare const REPORT_FILTERS: readonly ["all", "proven", "attention", "stale", "contradiction"];
+export type ReportFilter = (typeof REPORT_FILTERS)[number];
+export declare const PROOF_GATE_KEYS: readonly ["semantic", "scenario", "implementation", "e2e", "evidence"];
+export type ProofGateKey = (typeof PROOF_GATE_KEYS)[number];
+export type RequirementView = Readonly<{
+    text: string;
+    states: readonly string[];
+    earliestGate: ProofGateKey | "proven";
+}>;
+export type ReportViewQuery = Readonly<{
+    query: string;
+    filter: ReportFilter;
+    gate: ProofGateKey | "all";
+}>;
+export declare function matchesReportView(row: RequirementView, view: ReportViewQuery): boolean;
+export declare function reportFilterCounts(rows: readonly RequirementView[]): Readonly<Record<ReportFilter, number>>;
+//# sourceMappingURL=report-view.d.ts.map

package/dist/report/report-view.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"report-view.d.ts","sourceRoot":"","sources":["../../src/report/report-view.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,cAAc,mEAMjB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,cAAc,CAAC,CAAC,MAAM,CAAC,CAAC;AAE3D,eAAO,MAAM,eAAe,wEAMlB,CAAC;AAEX,MAAM,MAAM,YAAY,GAAG,CAAC,OAAO,eAAe,CAAC,CAAC,MAAM,CAAC,CAAC;AAE5D,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,SAAS,MAAM,EAAE,CAAC;IAC1B,YAAY,EAAE,YAAY,GAAG,QAAQ,CAAC;CACvC,CAAC,CAAC;AAEH,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,YAAY,GAAG,KAAK,CAAC;CAC5B,CAAC,CAAC;AAGH,wBAAgB,iBAAiB,CAC/B,GAAG,EAAE,eAAe,EACpB,IAAI,EAAE,eAAe,GACpB,OAAO,CAQT;AAGD,wBAAgB,kBAAkB,CAChC,IAAI,EAAE,SAAS,eAAe,EAAE,GAC/B,QAAQ,CAAC,MAAM,CAAC,YAAY,EAAE,MAAM,CAAC,CAAC,CASxC"}

package/dist/report/report-view.js

@@ -0,0 +1,33 @@
+export const REPORT_FILTERS = [
+    "all",
+    "proven",
+    "attention",
+    "stale",
+    "contradiction",
+];
+export const PROOF_GATE_KEYS = [
+    "semantic",
+    "scenario",
+    "implementation",
+    "e2e",
+    "evidence",
+];
+// implements REQ-kibi-html-health-report
+export function matchesReportView(row, view) {
+    const query = view.query.trim().toLocaleLowerCase();
+    const matchesFilter = view.filter === "all" || row.states.includes(view.filter);
+    const matchesGate = view.gate === "all" || row.earliestGate === view.gate;
+    const matchesQuery = query.length === 0 || row.text.toLocaleLowerCase().includes(query);
+    return matchesFilter && matchesGate && matchesQuery;
+}
+// implements REQ-kibi-html-health-report
+export function reportFilterCounts(rows) {
+    return {
+        all: rows.length,
+        proven: rows.filter((row) => row.states.includes("proven")).length,
+        attention: rows.filter((row) => row.states.includes("attention")).length,
+        stale: rows.filter((row) => row.states.includes("stale")).length,
+        contradiction: rows.filter((row) => row.states.includes("contradiction"))
+            .length,
+    };
+}

package/dist/report/repository.d.ts

@@ -0,0 +1,35 @@
+export type ReportGitRemote = Readonly<{
+    name: string;
+    url: string;
+}>;
+export type ReportRepositoryProvider = "github" | "gitlab" | "unknown";
+export type ReportRepository = Readonly<{
+    identity?: string;
+    webUrl?: string;
+    provider?: ReportRepositoryProvider;
+    commitSha?: string;
+    branch?: string;
+}>;
+export type SourceCoordinate = Readonly<{
+    id?: string;
+    path?: string;
+    line?: number;
+    column?: number;
+    endLine?: number;
+    endColumn?: number;
+}>;
+export declare function parseGitRemote(url: string): Readonly<{
+    identity: string;
+    webUrl: string;
+    provider: ReportRepositoryProvider;
+}> | undefined;
+export declare function resolveReportRepository(input: {
+    remotes?: readonly ReportGitRemote[];
+    commitSha?: string;
+    branch?: string;
+}): ReportRepository;
+export declare function shortCommitSha(sha: string | undefined): string | undefined;
+export declare function commitWebUrl(repository: ReportRepository | undefined): string | undefined;
+export declare function sourceWebUrl(repository: ReportRepository | undefined, coordinate: SourceCoordinate | undefined): string | undefined;
+export declare function formatSourceCoordinate(coordinate: SourceCoordinate | undefined): string | undefined;
+//# sourceMappingURL=repository.d.ts.map

package/dist/report/repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"repository.d.ts","sourceRoot":"","sources":["../../src/report/repository.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,eAAe,GAAG,QAAQ,CAAC;IACrC,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb,CAAC,CAAC;AAEH,MAAM,MAAM,wBAAwB,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAC;AAEvE,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,wBAAwB,CAAC;IACpC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,CAAC,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,QAAQ,CAAC;IACtC,EAAE,CAAC,EAAE,MAAM,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB,CAAC,CAAC;AAWH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GACtC,QAAQ,CAAC;IACP,QAAQ,EAAE,MAAM,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,wBAAwB,CAAC;CACpC,CAAC,GACF,SAAS,CAkEZ;AAED,wBAAgB,uBAAuB,CAAC,KAAK,EAAE;IAC7C,OAAO,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;IACrC,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB,GAAG,gBAAgB,CAqBnB;AAGD,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAI1E;AAuBD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,MAAM,GAAG,SAAS,CASpB;AAGD,wBAAgB,YAAY,CAC1B,UAAU,EAAE,gBAAgB,GAAG,SAAS,EACxC,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,MAAM,GAAG,SAAS,CAkBpB;AAGD,wBAAgB,sBAAsB,CACpC,UAAU,EAAE,gBAAgB,GAAG,SAAS,GACvC,MAAM,GAAG,SAAS,CAYpB"}

package/dist/report/repository.js

@@ -0,0 +1,151 @@
+function firstCapture(match, index) {
+    return match?.[index]?.trim() ?? "";
+}
+function stripGitSuffix(value) {
+    return value.replace(/\.git$/i, "").replace(/\/+$/, "");
+}
+// implements REQ-kibi-html-health-report
+export function parseGitRemote(url) {
+    const trimmed = url.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    const github = trimmed.match(/^(?:https?:\/\/(?:www\.)?|git@|ssh:\/\/(?:git@)?|git:\/\/)github\.com[:/]([^/]+)\/([^/]+?)(?:\.git)?\/?$/i);
+    if (github) {
+        const owner = firstCapture(github, 1);
+        const repo = stripGitSuffix(firstCapture(github, 2));
+        if (!owner || !repo || owner.includes(":") || repo.includes(" ")) {
+            return undefined;
+        }
+        return {
+            identity: `${owner}/${repo}`,
+            webUrl: `https://github.com/${owner}/${repo}`,
+            provider: "github",
+        };
+    }
+    const gitlabHttps = trimmed.match(/^https?:\/\/(?:www\.)?(gitlab\.com)\/(.+?)(?:\.git)?\/?$/i);
+    const gitlabSsh = trimmed.match(/^(?:git@|ssh:\/\/(?:git@)?)(gitlab\.com)[:/](.+?)(?:\.git)?\/?$/i);
+    const gitlab = gitlabHttps ?? gitlabSsh;
+    if (gitlab) {
+        const identity = stripGitSuffix(firstCapture(gitlab, 2));
+        if (!identity || identity.includes(" "))
+            return undefined;
+        return {
+            identity,
+            webUrl: `https://gitlab.com/${identity}`,
+            provider: "gitlab",
+        };
+    }
+    const genericHttps = trimmed.match(/^https?:\/\/([^/]+)\/(.+?)(?:\.git)?\/?$/i);
+    if (genericHttps) {
+        const host = firstCapture(genericHttps, 1).toLowerCase();
+        const identity = stripGitSuffix(firstCapture(genericHttps, 2));
+        if (!host || !identity || identity.includes(" "))
+            return undefined;
+        return {
+            identity,
+            webUrl: `https://${host}/${identity}`,
+            provider: "unknown",
+        };
+    }
+    const genericSsh = trimmed.match(/^(?:git@|ssh:\/\/(?:git@)?)([^:/]+)[:/](.+?)(?:\.git)?\/?$/i);
+    if (genericSsh) {
+        const host = firstCapture(genericSsh, 1).toLowerCase();
+        const identity = stripGitSuffix(firstCapture(genericSsh, 2));
+        if (!host || !identity || identity.includes(" "))
+            return undefined;
+        return {
+            identity,
+            webUrl: `https://${host}/${identity}`,
+            provider: "unknown",
+        };
+    }
+    return undefined;
+}
+export function resolveReportRepository(input) {
+    const remotes = input.remotes ?? [];
+    const parsed = remotes
+        .map((remote) => ({ remote, repo: parseGitRemote(remote.url) }))
+        .filter((entry) => entry.repo !== undefined);
+    const origin = parsed.find((entry) => entry.remote.name === "origin");
+    const selected = origin?.repo ?? parsed[0]?.repo;
+    const commitSha = input.commitSha?.trim() || undefined;
+    const branch = input.branch?.trim() || undefined;
+    return {
+        ...(selected ?? {}),
+        ...(commitSha ? { commitSha } : {}),
+        ...(branch ? { branch } : {}),
+    };
+}
+// implements REQ-kibi-html-health-report
+export function shortCommitSha(sha) {
+    const value = sha?.trim();
+    if (!value)
+        return undefined;
+    return value.length > 12 ? value.slice(0, 12) : value;
+}
+function encodePath(path) {
+    return path
+        .split("/")
+        .filter((segment) => segment.length > 0)
+        .map((segment) => encodeURIComponent(segment))
+        .join("/");
+}
+function lineFragment(coordinate) {
+    const start = coordinate.line;
+    if (typeof start !== "number" || !Number.isInteger(start) || start < 1) {
+        return "";
+    }
+    const end = coordinate.endLine;
+    if (typeof end === "number" && Number.isInteger(end) && end > start) {
+        return `#L${start}-L${end}`;
+    }
+    return `#L${start}`;
+}
+// implements REQ-kibi-html-health-report
+export function commitWebUrl(repository) {
+    const webUrl = repository?.webUrl?.replace(/\/+$/, "");
+    const sha = repository?.commitSha?.trim();
+    if (!repository || !webUrl || !sha)
+        return undefined;
+    if (repository.provider === "github")
+        return `${webUrl}/commit/${encodeURIComponent(sha)}`;
+    if (repository.provider === "gitlab")
+        return `${webUrl}/-/commit/${encodeURIComponent(sha)}`;
+    return undefined;
+}
+// implements REQ-kibi-html-health-report
+export function sourceWebUrl(repository, coordinate) {
+    const path = coordinate?.path?.trim();
+    const webUrl = repository?.webUrl?.replace(/\/+$/, "");
+    if (!repository || !coordinate || !path || !webUrl || path.includes("://")) {
+        return undefined;
+    }
+    const revision = repository.commitSha?.trim() || repository.branch?.trim();
+    if (!revision)
+        return undefined;
+    const encodedPath = encodePath(path);
+    const encodedRev = encodeURIComponent(revision);
+    const fragment = lineFragment(coordinate);
+    if (repository.provider === "github") {
+        return `${webUrl}/blob/${encodedRev}/${encodedPath}${fragment}`;
+    }
+    if (repository.provider === "gitlab") {
+        return `${webUrl}/-/blob/${encodedRev}/${encodedPath}${fragment}`;
+    }
+    return undefined;
+}
+// implements REQ-kibi-html-health-report
+export function formatSourceCoordinate(coordinate) {
+    const path = coordinate?.path?.trim();
+    if (!path)
+        return undefined;
+    const start = coordinate?.line;
+    if (typeof start === "number" && Number.isInteger(start) && start >= 1) {
+        const end = coordinate?.endLine;
+        if (typeof end === "number" && Number.isInteger(end) && end > start) {
+            return `${path}:${start}-${end}`;
+        }
+        return `${path}:${start}`;
+    }
+    return path;
+}

package/dist/runtime/cli-runtime.d.ts

@@ -1,3 +1,5 @@
 import type { OperationRuntime, RuntimeOptions } from "../public/operations/runtime-types.js";
+import { type BranchResolutionError } from "../utils/branch-resolver.js";
+export declare function attachmentFailureMessage(attachment: BranchResolutionError): string;
 export declare function createCliRuntime(options?: RuntimeOptions): OperationRuntime;
 //# sourceMappingURL=cli-runtime.d.ts.map

package/dist/runtime/cli-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAEV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAgC/C,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CA2ElB"}
+{"version":3,"file":"cli-runtime.d.ts","sourceRoot":"","sources":["../../src/runtime/cli-runtime.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAIV,gBAAgB,EAEhB,cAAc,EACf,MAAM,uCAAuC,CAAC;AAC/C,OAAO,EACL,KAAK,qBAAqB,EAE3B,MAAM,6BAA6B,CAAC;AAErC,wBAAgB,wBAAwB,CACtC,UAAU,EAAE,qBAAqB,GAChC,MAAM,CAOR;AA0ED,wBAAgB,gBAAgB,CAC9B,OAAO,GAAE,cAAmB,GAC3B,gBAAgB,CAgHlB"}

package/dist/runtime/cli-runtime.js

@@ -1,7 +1,15 @@
 import path from "node:path";
+import { retryAttachAfterBreakingStaleLock } from "../prolog/store-lock.js";
 import { EngineClient } from "../engine.js";
 import { nodeFilesystem, nodeGit, nodeNetwork, } from "../public/operations/node-ports.js";
-import { resolveActiveBranch } from "../utils/branch-resolver.js";
+import { resolveBranchAttachment, } from "../utils/branch-resolver.js";
+export function attachmentFailureMessage(attachment) {
+    const isNonGitContext = attachment.code === "NOT_A_GIT_REPO" ||
+        attachment.code === "GIT_NOT_AVAILABLE";
+    return isNonGitContext
+        ? "Kibi requires an active Git branch outside a repository; set KIBI_BRANCH explicitly for a standalone workspace."
+        : `Failed to resolve active branch: ${attachment.error}`;
+}
 function createDefaultProlog(root, branch) {
     const engine = new EngineClient({
         workspaceRoot: root,
@@ -21,6 +29,34 @@ function workspaceRoot(options) {
 function quoteProlog(value) {
     return value.replaceAll("'", "''");
 }
+function bindSignal(port, signal) {
+    return new Proxy(port, {
+        get(target, property, receiver) {
+            if (property === "query") {
+                return (goal) => target.query(goal, signal);
+            }
+            if (property === "queryEntities") {
+                return (input) => target.queryEntities?.(input, signal);
+            }
+            if (property === "searchEntities") {
+                return (input) => target.searchEntities?.(input, signal);
+            }
+            if (property === "save") {
+                return () => target.save(signal);
+            }
+            return Reflect.get(target, property, receiver);
+        },
+    });
+}
+function enginePort(port, signal) {
+    const candidate = port;
+    const execute = candidate.execute ?? candidate.command;
+    if (!execute)
+        return undefined;
+    return {
+        execute: (command, commandSignal) => execute.call(port, command, commandSignal ?? signal),
+    };
+}
 // implements REQ-kibi-operation-interface-parity
 export function createCliRuntime(options = {}) {
     const ownedPrologs = new WeakMap();
@@ -43,38 +79,69 @@ export function createCliRuntime(options = {}) {
                 net: merged.net ?? nodeNetwork,
             };
             if (!spec.requiresProlog) {
-                return contextBase;
-            }
-            let branch = process.env.KIBI_BRANCH?.trim();
-            if (!branch) {
-                const resolved = resolveActiveBranch(root);
-                if ("error" in resolved) {
-                    const isNonGitContext = resolved.code === "NOT_A_GIT_REPO" ||
-                        resolved.code === "GIT_NOT_AVAILABLE";
-                    if (isNonGitContext) {
-                        branch = "main";
-                    }
-                    else {
-                        await merged.prolog?.terminate?.();
-                        throw new Error(`Failed to resolve active branch: ${resolved.error}`);
+                // Read-only operations such as status may choose to use an explicitly
+                // supplied test or host Prolog port, but must not force engine startup.
+                // That keeps pre-init and damaged-store diagnostics non-mutating.
+                let lazyProlog = merged.prolog;
+                const lazyContext = {};
+                const ensureProlog = async () => {
+                    if (lazyProlog !== undefined)
+                        return bindSignal(lazyProlog, signal);
+                    const attachment = resolveBranchAttachment(root);
+                    if ("error" in attachment) {
+                        throw new Error(`Failed to resolve active branch: ${attachment.error}`);
                     }
-                }
-                else {
-                    branch = resolved.branch;
-                }
+                    const engine = createDefaultProlog(root, attachment.kbBranch);
+                    await engine.start?.();
+                    lazyProlog = engine;
+                    if (lazyContext.current !== undefined)
+                        ownedPrologs.set(lazyContext.current, engine);
+                    return bindSignal(engine, signal);
+                };
+                const lazyEngine = merged.prolog
+                    ? enginePort(merged.prolog, signal)
+                    : undefined;
+                const context = {
+                    ...contextBase,
+                    ...(merged.prolog
+                        ? { prolog: bindSignal(merged.prolog, signal) }
+                        : {}),
+                    ...(lazyEngine ? { engine: lazyEngine } : {}),
+                    ensureProlog,
+                };
+                lazyContext.current = context;
+                return context;
+            }
+            const attachment = resolveBranchAttachment(root);
+            if ("error" in attachment) {
+                await merged.prolog?.terminate?.();
+                throw new Error(attachmentFailureMessage(attachment));
+            }
+            if (attachment.migrationRequired) {
+                console.warn(`[KIBI] Legacy branch attachment: Git '${attachment.gitBranch}' is reading KB '${attachment.kbBranch}'. Migrate with 'kibi branch migrate --from ${attachment.kbBranch} --to ${attachment.gitBranch} --apply'; writes are blocked until then.`);
             }
             const usesEngine = merged.prolog === undefined;
-            const prolog = merged.prolog ?? createDefaultProlog(root, branch);
+            const rawProlog = merged.prolog ?? createDefaultProlog(root, attachment.kbBranch);
+            const prolog = bindSignal(rawProlog, signal);
             try {
                 await prolog.start?.();
-                const kbPath = path.join(root, ".kb", "branches", branch);
+                const kbPath = attachment.storePath;
                 if (!usesEngine) {
-                    const attached = await prolog.query(`kb_attach('${quoteProlog(kbPath)}')`);
+                    let attached = await prolog.query(`kb_attach('${quoteProlog(kbPath)}')`);
+                    if (!attached.success) {
+                        attached = await retryAttachAfterBreakingStaleLock(prolog, kbPath, attached);
+                    }
                     if (!attached.success) {
                         throw new Error(attached.error ?? "Failed to attach branch KB");
                     }
                 }
-                const context = { ...contextBase, prolog };
+                const attachedEngine = enginePort(rawProlog, signal);
+                const context = {
+                    ...contextBase,
+                    prolog,
+                    ...(attachedEngine ? { engine: attachedEngine } : {}),
+                    branchAttachment: attachment,
+                };
                 ownedPrologs.set(context, prolog);
                 return context;
             }