kibi-cli 2.17.0 → 2.19.0

package/src/public/operations/discovery-executors.ts

@@ -21,8 +21,10 @@ import {
   branchStoreReason,
   inspectBranchStore,
   storeLockJournalReason,
+  storeLockTakeoverReason,
   uncompiledBranchStoreReason,
 } from "../../utils/branch-store.js";
+import { confirmSourceNewerReasons } from "../../utils/content-freshness.js";
 import {
   loadEntities,
   loadSearchCandidates,
@@ -40,6 +42,7 @@ import {
 import {
   OperationJsonDecodeError,
   runOperationJsonQuery,
+  toPrologAtom,
 } from "./prolog-json.js";
 import type { OperationContext, PrologPort } from "./runtime-types.js";
 import type { OperationResult } from "./types.js";
@@ -52,13 +55,87 @@ export type QueryInput = {
   readonly sourceFile?: string;
   readonly limit?: number;
   readonly offset?: number;
+  /** Typed fact filters (fact entities only); see `FACT_KINDS`. */
+  readonly factKind?: string;
+  readonly predicate?: string;
+  readonly namespace?: string;
+  readonly where?: Readonly<Record<string, string>>;
+  readonly args?: readonly (string | null)[];
+  readonly polarity?: "assert" | "deny";
+  readonly scope?: "all" | "current_requirements";
+  readonly distinct?: string;
+  readonly subjectKey?: string;
+  readonly propertyKey?: string;
 };
 
+/** A ready-to-run follow-up call the query suggests. */
+export type QueryNextCall = Readonly<{ call: string; why: string }>;
+
+/**
+ * Typed-fact view of a kb_query answer: which predicate, property or fact
+ * kind was asked, the schema that names its arguments, distinct value counts,
+ * the values that do exist when nothing matched, warnings about the question
+ * itself and the follow-up calls that make sense next.
+ */
+export type FactQueryPayload = Readonly<{
+  mode: "predicate" | "property" | "schemas" | "fact_kind";
+  predicate?: Record<string, unknown>;
+  property?: Record<string, unknown>;
+  factKind?: string;
+  schema?: Record<string, unknown> | null;
+  subjectFacts?: readonly string[];
+  distinct?: Record<string, unknown> | null;
+  suggestions?: Record<string, unknown> | null;
+  warnings: readonly string[];
+  next: readonly QueryNextCall[];
+}>;
+
 export type QueryPayload = {
   readonly entities: readonly Record<string, unknown>[];
   readonly count: number;
+  readonly factQuery?: FactQueryPayload;
+};
+
+export const FACT_KINDS = [
+  "subject",
+  "property_value",
+  "predicate",
+  "predicate_schema",
+  "observation",
+  "meta",
+  "rule",
+  "rule_schema",
+] as const;
+
+/** Which typed filters each question mode reads; any other is refused. */
+const MODE_FILTERS: Record<FactQueryPayload["mode"], ReadonlySet<string>> = {
+  schemas: new Set(["factKind", "predicate", "namespace"]),
+  predicate: new Set([
+    "predicate",
+    "namespace",
+    "where",
+    "args",
+    "polarity",
+    "scope",
+    "distinct",
+  ]),
+  property: new Set(["subjectKey", "propertyKey", "scope"]),
+  fact_kind: new Set(["factKind"]),
 };
 
+const TYPED_FACT_FILTERS = [
+  "factKind",
+  "predicate",
+  "namespace",
+  "where",
+  "args",
+  "polarity",
+  "scope",
+  "distinct",
+  "subjectKey",
+  "propertyKey",
+] as const satisfies readonly (keyof QueryInput)[];
+
 export type SearchInput = {
   readonly query: string;
   readonly type?: string;
@@ -78,8 +155,47 @@ export type SearchPayload = {
   readonly truncated?: boolean;
   readonly queryAnalysis?: IntentSearchAnalysis;
   readonly answer?: SearchAnswer;
+  /** The Kibi branch whose store was searched, when the runtime attached one. */
+  readonly branch?: string | null;
+  /** Present when the searched store was never compiled for this branch. */
+  readonly branchStore?: SearchBranchStoreNotice;
+};
+
+export type SearchBranchStoreNotice = {
+  readonly state: "not_compiled";
+  readonly code: typeof BRANCH_STORE_NOT_COMPILED;
+  readonly path: string;
+  readonly detail: string;
+  readonly remediation: Readonly<Record<string, unknown>>;
 };
 
+/**
+ * An empty result from a store that was never compiled says nothing about
+ * the authored requirements, so search reports the store state itself (the
+ * same reason kb_status and kb_check use) instead of a bare "no results".
+ */
+// implements REQ-cli-status-pre-first-sync, REQ-mcp-search-discovery
+function uncompiledSearchNotice(
+  context: OperationContext,
+): SearchBranchStoreNotice | null {
+  const attachment = context.branchAttachment;
+  if (attachment === undefined) return null;
+  const store = inspectBranchStore(context.workspaceRoot, attachment.kbBranch);
+  const reason = uncompiledBranchStoreReason(
+    context.workspaceRoot,
+    store,
+    attachment.kbBranch,
+  );
+  if (reason === null) return null;
+  return {
+    state: "not_compiled",
+    code: BRANCH_STORE_NOT_COMPILED,
+    path: store.path,
+    detail: String(reason.detail),
+    remediation: reason.remediation as Readonly<Record<string, unknown>>,
+  };
+}
+
 export type StatusInput = Readonly<Record<string, never>>;
 
 export type StatusPayload = {
@@ -99,6 +215,8 @@ export type StatusPayload = {
   readonly staleReasons?: readonly Record<string, unknown>[];
   readonly staleReasonCount?: number;
   readonly staleReasonsTruncated?: boolean;
+  /** Informational, non-blocking observations (never make the KB stale). */
+  readonly notices?: readonly Record<string, unknown>[];
   readonly branchAttachment?: {
     readonly gitBranch: string;
     readonly kbBranch: string;
@@ -152,6 +270,400 @@ function isStatusPayload(value: unknown): value is StatusPayload {
   );
 }
 
+function hasTypedFactFilters(input: QueryInput): boolean {
+  return TYPED_FACT_FILTERS.some((key) => input[key] !== undefined);
+}
+
+function requireAtomString(value: unknown, field: string): string {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`${field} must be a non-empty string.`);
+  }
+  return value.trim();
+}
+
+function requireEnum<T extends string>(
+  value: unknown,
+  field: string,
+  allowed: readonly T[],
+): T {
+  if (typeof value !== "string" || !allowed.includes(value as T)) {
+    throw new Error(`${field} must be one of: ${allowed.join(", ")}.`);
+  }
+  return value as T;
+}
+
+/**
+ * Builds the Prolog argument spec of a predicate question. Named `where`
+ * entries are resolved against the predicate's declared argument names in
+ * Prolog; positional `args` use `null` as a wildcard.
+ */
+// implements REQ-kibi-query-fact-filters
+function predicateArgSpec(input: QueryInput): string {
+  if (input.where !== undefined && input.args !== undefined) {
+    throw new Error(
+      "Use either where (named arguments) or args (positional), not both.",
+    );
+  }
+  if (input.where !== undefined) {
+    if (
+      input.where === null ||
+      typeof input.where !== "object" ||
+      Array.isArray(input.where)
+    ) {
+      throw new Error("where must be an object of argument name to value.");
+    }
+    const pairs = Object.entries(input.where).map(([key, value]) => {
+      const name = requireAtomString(key, "where argument name");
+      const atom = requireAtomString(value, `where.${key}`);
+      return `${toPrologAtom(name)}=${toPrologAtom(atom)}`;
+    });
+    return `where([${pairs.join(",")}])`;
+  }
+  if (input.args !== undefined) {
+    if (!Array.isArray(input.args)) {
+      throw new Error("args must be an array of constants (null = any).");
+    }
+    const entries = input.args.map((value, index) =>
+      value === null || value === "*"
+        ? "'$any'"
+        : toPrologAtom(requireAtomString(value, `args[${index}]`)),
+    );
+    return `[${entries.join(",")}]`;
+  }
+  return "[]";
+}
+
+type FactQueryResponse = Readonly<{
+  mode: FactQueryPayload["mode"];
+  rows: readonly Record<string, unknown>[];
+  count: number;
+  warnings?: readonly string[];
+  predicate?: Record<string, unknown>;
+  property?: Record<string, unknown>;
+  factKind?: string;
+  schema?: Record<string, unknown> | null;
+  subjectFacts?: readonly string[];
+  distinct?: Record<string, unknown> | null;
+  suggestions?: Record<string, unknown> | null;
+}>;
+
+function callText(args: Record<string, unknown>): string {
+  return `kb_query(${JSON.stringify(args)})`;
+}
+
+/**
+ * Every typed answer names the exact call that makes sense next, so an
+ * agent never has to guess the follow-up from the shape of the data.
+ */
+// implements REQ-kibi-query-fact-filters
+function factQueryNext(
+  input: QueryInput,
+  response: FactQueryResponse,
+): QueryNextCall[] {
+  const next: QueryNextCall[] = [];
+  const first = response.rows[0];
+  const firstId = typeof first?.id === "string" ? first.id : undefined;
+  switch (response.mode) {
+    case "predicate": {
+      if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text and relationships of one row",
+        });
+      }
+      const filters = {
+        predicate: input.predicate,
+        ...(input.namespace !== undefined
+          ? { namespace: input.namespace }
+          : {}),
+        ...(input.where !== undefined ? { where: input.where } : {}),
+        ...(input.args !== undefined ? { args: input.args } : {}),
+        ...(input.polarity !== undefined ? { polarity: input.polarity } : {}),
+        ...(input.scope !== undefined ? { scope: input.scope } : {}),
+      };
+      const names = Array.isArray(
+        (response.schema as { argumentNames?: unknown } | null)?.argumentNames,
+      )
+        ? (
+            response.schema as { argumentNames: unknown[] }
+          ).argumentNames.filter(
+            (name): name is string => typeof name === "string",
+          )
+        : [];
+      const bound = new Set(Object.keys(input.where ?? {}));
+      const free = names.filter((name) => !bound.has(name));
+      if (
+        input.distinct === undefined &&
+        response.count > 0 &&
+        free.length > 0
+      ) {
+        const argument = free[free.length - 1] ?? free[0];
+        next.push({
+          call: callText({ ...filters, distinct: argument }),
+          why: `count the distinct values of '${argument}' across these facts`,
+        });
+      }
+      if (
+        response.count === 0 &&
+        response.suggestions &&
+        typeof response.suggestions === "object" &&
+        (response.warnings ?? []).length === 0
+      ) {
+        // Suggest a correction only for an argument whose requested value
+        // does not exist; a key whose value exists is not the cause.
+        for (const [key, values] of Object.entries(response.suggestions)) {
+          if (!Array.isArray(values)) continue;
+          const requested = input.where?.[key];
+          if (requested !== undefined && values.includes(requested)) continue;
+          const value = values[0];
+          if (typeof value === "string") {
+            next.push({
+              call: callText({
+                ...filters,
+                where: { ...(input.where ?? {}), [key]: value },
+              }),
+              why: `'${key}' has no fact with that value; '${value}' is one that exists`,
+            });
+            break;
+          }
+        }
+      }
+      if (next.length === 0) {
+        next.push({
+          call: callText({ factKind: "predicate_schema" }),
+          why: "list the predicates this KB can answer about and their argument names",
+        });
+      }
+      break;
+    }
+    case "property": {
+      if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text and relationships of one row",
+        });
+      }
+      if (input.propertyKey !== undefined) {
+        next.push({
+          call: callText({ subjectKey: input.subjectKey }),
+          why: "every property stated about this subject",
+        });
+      } else if (response.count === 0) {
+        next.push({
+          call: callText({ factKind: "subject" }),
+          why: "list the subject keys that exist",
+        });
+      }
+      break;
+    }
+    case "schemas": {
+      const name = typeof first?.name === "string" ? first.name : undefined;
+      if (name !== undefined) {
+        next.push({
+          call: callText({ predicate: name }),
+          why: "every stored fact of the first listed predicate",
+        });
+      }
+      break;
+    }
+    case "fact_kind": {
+      if (input.factKind === "predicate") {
+        next.push({
+          call: callText({ factKind: "predicate_schema" }),
+          why: "argument names and constants for asking by name",
+        });
+      } else if (input.factKind === "property_value" && first) {
+        const subjectKey =
+          typeof first.subject_key === "string" ? first.subject_key : undefined;
+        if (subjectKey !== undefined) {
+          next.push({
+            call: callText({ subjectKey }),
+            why: "the properties of the first listed subject",
+          });
+        }
+      } else if (firstId !== undefined) {
+        next.push({
+          call: callText({ id: firstId }),
+          why: "full fact text of one row",
+        });
+      }
+      break;
+    }
+  }
+  return next;
+}
+
+function factRowSummary(row: Record<string, unknown>): string {
+  const id = String(row.id ?? "");
+  if (typeof row.name === "string" && Array.isArray(row.args)) {
+    const effect = typeof row.effect === "string" ? ` -> ${row.effect}` : "";
+    const polarity = row.polarity === "deny" ? " [deny]" : "";
+    return `${id}: ${row.name}(${row.args.map(String).join(", ")})${effect}${polarity}`;
+  }
+  if (
+    typeof row.subjectKey === "string" &&
+    typeof row.propertyKey === "string"
+  ) {
+    const unit = typeof row.unit === "string" && row.unit ? ` ${row.unit}` : "";
+    return `${id}: ${row.subjectKey} ${row.propertyKey} ${String(row.operator ?? "")} ${String(row.value ?? "")}${unit}`;
+  }
+  if (typeof row.name === "string" && typeof row.arity === "number") {
+    const names = Array.isArray(row.argumentNames)
+      ? row.argumentNames.map(String).join(", ")
+      : "";
+    return `${row.name}(${names})`;
+  }
+  return `${id} (${String(row.title ?? "")})`;
+}
+
+/**
+ * Typed fact questions run as validated Prolog goals in the discovery module;
+ * the executor never forwards caller-written Prolog.
+ */
+// implements REQ-kibi-query-fact-filters
+async function executeFactQuery(
+  input: QueryInput,
+  context: OperationContext,
+  limit: number,
+  offset: number,
+): Promise<OperationResult<QueryPayload>> {
+  if (input.type !== undefined && input.type !== "fact") {
+    throw new Error(
+      "Typed fact filters (factKind, predicate, subjectKey, ...) apply to type 'fact' only.",
+    );
+  }
+  for (const key of ["id", "tags", "sourceFile"] as const) {
+    if (input[key] !== undefined) {
+      throw new Error(
+        `${key} cannot be combined with typed fact filters; run a separate kb_query.`,
+      );
+    }
+  }
+  const prolog = requireProlog(context);
+  if (
+    !Number.isFinite(limit) ||
+    !Number.isFinite(offset) ||
+    limit < 0 ||
+    offset < 0
+  ) {
+    throw new Error("limit and offset must be non-negative numbers.");
+  }
+  const page = `${Math.trunc(limit)}, ${Math.trunc(offset)}`;
+  const namespace =
+    input.namespace === undefined
+      ? "none"
+      : toPrologAtom(requireAtomString(input.namespace, "namespace"));
+  const mode =
+    input.factKind === "predicate_schema"
+      ? "schemas"
+      : input.predicate !== undefined
+        ? "predicate"
+        : input.subjectKey !== undefined
+          ? "property"
+          : input.factKind !== undefined
+            ? "fact_kind"
+            : undefined;
+  if (mode === undefined) {
+    throw new Error(
+      "Typed fact filters need a predicate, a subjectKey or a factKind; where/args/polarity/distinct/propertyKey refine one of those.",
+    );
+  }
+  const unused = TYPED_FACT_FILTERS.filter(
+    (key) => input[key] !== undefined && !MODE_FILTERS[mode].has(key),
+  );
+  if (unused.length > 0) {
+    throw new Error(
+      `${unused.join(", ")} do${unused.length === 1 ? "es" : ""} not apply to a ${mode} question; allowed with it: ${[...MODE_FILTERS[mode]].join(", ")}.`,
+    );
+  }
+  const scope =
+    input.scope === undefined
+      ? "all"
+      : requireEnum(input.scope, "scope", ["all", "current_requirements"]);
+  const factKind =
+    input.factKind === undefined
+      ? undefined
+      : requireEnum(input.factKind, "factKind", FACT_KINDS);
+  let goal: string;
+  if (mode === "schemas") {
+    goal = `discovery:ask_schemas_json(${namespace}, ${input.predicate === undefined ? "none" : toPrologAtom(requireAtomString(input.predicate, "predicate"))}, ${page}, JsonString)`;
+  } else if (mode === "predicate") {
+    const name = requireAtomString(input.predicate, "predicate");
+    const polarity =
+      input.polarity === undefined
+        ? "none"
+        : toPrologAtom(
+            requireEnum(input.polarity, "polarity", ["assert", "deny"]),
+          );
+    const distinct =
+      input.distinct === undefined
+        ? "none"
+        : toPrologAtom(requireAtomString(input.distinct, "distinct"));
+    goal = `discovery:ask_predicate_json(${namespace}, ${toPrologAtom(name)}, ${predicateArgSpec(input)}, ${polarity}, ${scope}, ${distinct}, ${page}, JsonString)`;
+  } else if (mode === "property") {
+    const subject = requireAtomString(input.subjectKey, "subjectKey");
+    const property =
+      input.propertyKey === undefined
+        ? "none"
+        : toPrologAtom(requireAtomString(input.propertyKey, "propertyKey"));
+    goal = `discovery:ask_property_json(${toPrologAtom(subject)}, ${property}, ${scope}, ${page}, JsonString)`;
+  } else {
+    goal = `discovery:ask_fact_kind_json(${toPrologAtom(factKind)}, ${page}, JsonString)`;
+  }
+  const response = await runOperationJsonQuery<FactQueryResponse>(
+    prolog,
+    "discovery.pl",
+    goal,
+    "Query execution",
+    context.signal,
+  );
+  const rows = Array.isArray(response.rows) ? response.rows : [];
+  const count =
+    typeof response.count === "number" ? response.count : rows.length;
+  const warnings = Array.isArray(response.warnings) ? response.warnings : [];
+  const factQuery: FactQueryPayload = {
+    mode: response.mode,
+    ...(response.predicate ? { predicate: response.predicate } : {}),
+    ...(response.property ? { property: response.property } : {}),
+    ...(response.factKind ? { factKind: response.factKind } : {}),
+    ...(response.schema !== undefined ? { schema: response.schema } : {}),
+    ...(response.subjectFacts ? { subjectFacts: response.subjectFacts } : {}),
+    ...(response.distinct !== undefined ? { distinct: response.distinct } : {}),
+    ...(response.suggestions !== undefined
+      ? { suggestions: response.suggestions }
+      : {}),
+    warnings,
+    next: factQueryNext(input, { ...response, rows, count }),
+  };
+  const subject =
+    response.mode === "predicate"
+      ? `${String(input.predicate)} facts`
+      : response.mode === "property"
+        ? `properties of ${String(input.subjectKey)}`
+        : response.mode === "schemas"
+          ? "predicate schemas"
+          : `${String(factKind)} facts`;
+  const lines = [
+    count === 0
+      ? `No ${subject} matched.`
+      : `${count} ${subject}. Showing ${rows.length} (offset ${offset}, limit ${limit}): ${rows.map(factRowSummary).join("; ")}`,
+    ...(factQuery.distinct && typeof factQuery.distinct === "object"
+      ? [
+          `Distinct ${String((factQuery.distinct as { argument?: unknown }).argument)}: ${JSON.stringify((factQuery.distinct as { values?: unknown }).values ?? [])}`,
+        ]
+      : []),
+    ...(factQuery.suggestions && typeof factQuery.suggestions === "object"
+      ? [`Values that exist: ${JSON.stringify(factQuery.suggestions)}`]
+      : []),
+    ...warnings.map((warning) => `Warning: ${warning}`),
+    ...factQuery.next.map((entry) => `Next: ${entry.call} (${entry.why})`),
+  ];
+  return {
+    content: [{ type: "text", text: lines.join("\n") }],
+    structuredContent: { entities: rows, count, factQuery },
+  };
+}
+
 export async function executeQuery(
   input: QueryInput,
   context: OperationContext,
@@ -160,6 +672,9 @@ export async function executeQuery(
   const { type, id, tags, sourceFile, limit = 100, offset = 0 } = input;
   try {
     validateEntityType(type);
+    if (hasTypedFactFilters(input)) {
+      return await executeFactQuery(input, context, limit, offset);
+    }
     const prolog = requireProlog(context);
     const signal = context.signal;
     const pageInput = {
@@ -275,6 +790,15 @@ export async function executeSearch(
   validateEntityType(type);
   try {
     const prolog = requireProlog(context);
+    const branch = context.branchAttachment?.kbBranch ?? null;
+    const storeNotice = uncompiledSearchNotice(context);
+    const branchFields = {
+      branch,
+      ...(storeNotice ? { branchStore: storeNotice } : {}),
+    };
+    const storeNote = storeNotice
+      ? ` Note: ${storeNotice.detail} Run kibi sync before relying on search results.`
+      : "";
     const intentMode =
       rankingMode === "intent-v1" ||
       semanticFacets !== undefined ||
@@ -305,7 +829,7 @@ export async function executeSearch(
           : undefined;
       // The structured payload carries every row; the text is a short
       // human-readable digest instead of a second copy of the results.
-      const text =
+      const text = `${
         intentResult.matches.length === 0
           ? `No intent search results for '${trimmedQuery}' (abstained).`
           : `Found ${intentResult.matches.length} intent search results for '${trimmedQuery}'${intentResult.analysis.ambiguous ? " (top matches are close; confirm before relying on one)" : ""}. Top: ${paginated
@@ -313,7 +837,8 @@ export async function executeSearch(
               .map((match) => String(match.entity.id ?? ""))
               .join(
                 ", ",
-              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`;
+              )}${answerLayer ? `. Governing: ${answerLayer.governing.map((req) => req.id).join(", ") || "none found"}` : ""}.`
+      }${storeNote}`;
       return {
         content: [{ type: "text", text }],
         structuredContent: {
@@ -322,6 +847,7 @@ export async function executeSearch(
           truncated: offset + paginated.length < intentResult.matches.length,
           queryAnalysis: intentResult.analysis,
           ...(answerLayer ? { answer: answerLayer } : {}),
+          ...branchFields,
         },
       };
     }
@@ -342,7 +868,7 @@ export async function executeSearch(
       context.workspaceRoot,
     );
     const paginated = paginateResults(matches, limit, offset);
-    const text =
+    const text = `${
       matches.length === 0
         ? `No search results for '${trimmedQuery}'.`
         : `Found ${matches.length} search results for '${trimmedQuery}'. Showing ${paginated.length} (offset ${offset}, limit ${limit}): ${paginated
@@ -350,13 +876,15 @@ export async function executeSearch(
               (match) =>
                 `${String(match.entity.id ?? "")} [${match.reasons.join(", ")}]`,
             )
-            .join(", ")}`;
+            .join(", ")}`
+    }${storeNote}`;
     return {
       content: [{ type: "text", text }],
       structuredContent: {
         results: await projectMatches(prolog, paginated, fields),
         count: matches.length,
         truncated: offset + paginated.length < matches.length,
+        ...branchFields,
       },
     };
   } catch (error) {
@@ -460,7 +988,25 @@ export async function executeStatus(
         await ownedEngine?.terminate();
       }
     const snapshotEvidence = await readWorkspaceSnapshot(context);
-    const existingReasons = payload.staleReasons ?? [];
+    // implements REQ-cli-status-pre-first-sync
+    // Prolog compares file times only. A fresh clone or a checkout rewrites
+    // every mtime without changing a byte, so confirm each "newer" source
+    // against the content hashes the last compilation recorded.
+    const prologReasons = payload.staleReasons ?? [];
+    const confirmed = confirmSourceNewerReasons(
+      context.workspaceRoot,
+      store.path,
+      prologReasons,
+    );
+    const existingReasons = confirmed.kept;
+    if (
+      confirmed.dropped.length > 0 &&
+      confirmed.kept.length === 0 &&
+      payload.staleReasonsTruncated !== true &&
+      payload.syncState === "stale"
+    ) {
+      payload = { ...payload, syncState: "fresh", dirty: false };
+    }
     // implements REQ-cli-status-pre-first-sync
     // A missing or empty store beside authored sources gets the one reason
     // whose remediation works (kibi sync); `kibi branch ensure` alone would
@@ -473,6 +1019,9 @@ export async function executeStatus(
       ) ?? branchStoreReason(store);
     const storeUncompiled = storeReason?.code === BRANCH_STORE_NOT_COMPILED;
     const lockReason = storeLockJournalReason(store.path);
+    // implements REQ-core-journaled-engine-persistence
+    // A stale-lock takeover heals itself; report it without making the KB stale.
+    const takeoverNotice = storeLockTakeoverReason(store.path);
     const compilerReason = compilerFingerprintReason(store.path);
     const engineReason = engineStatus
       ? {
@@ -514,6 +1063,7 @@ export async function executeStatus(
       ...(storeUncompiled ? { syncState: "stale", dirty: true } : {}),
       branchAttachment: attachment,
       branchStore: store,
+      ...(takeoverNotice ? { notices: [takeoverNotice] } : {}),
       ...(engineStatus ? { engineStatus } : {}),
       staleReasons,
       staleReasonCount: staleReasons.length,
@@ -661,7 +1211,7 @@ export async function executeStatus(
       content: [
         {
           type: "text",
-          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}`,
+          text: `Branch ${payload.branch} is ${enrichedPayload.syncState} (snapshot ${payload.snapshotId}, dirty=${enrichedPayload.dirty}, proofSnapshot=${enrichedPayload.proofSnapshot})${storeUncompiled ? `. Blocking: ${String(storeReason?.detail)} Run kibi sync.` : ""}${takeoverNotice ? `. Note: ${String(takeoverNotice.detail)}` : ""}`,
         },
       ],
       structuredContent: statusWithPlan,