kibi-cli 2.7.0 → 2.10.0

package/dist/operations/modeling/suggest-predicates.js

@@ -1,3 +1,5 @@
+import { escapeAtom } from "../../prolog/codec.js";
+import { parsePrologList } from "../mutation/serialization.js";
 import { analyzeSemanticAdvisorInput } from "../semantic-advisor/analyze-prose.js";
 import { semanticClaimKey } from "../semantic-advisor/clauses.js";
 import { composeOntologyCatalogForOperation } from "../semantic-advisor/plugin-orchestration.js";
@@ -143,6 +145,50 @@ function withMarginRejection(candidates) {
         };
     });
 }
+const GROUNDING_RELATIONSHIP_TYPES = [
+    "requires_property",
+    "requires_predicate",
+    "requires_rule",
+];
+function unquoted(value) {
+    return typeof value === "string" ? value.replace(/^['"]|['"]$/g, "") : "";
+}
+/**
+ * The logical grounding relationships an existing requirement already has for
+ * this claim. A modeled claim takes exactly one grounding relationship, so a
+ * second link (for example requires_predicate beside a bootstrap
+ * requires_property) fails the proposition-complete rule.
+ */
+// implements REQ-model-predicates-grounding-aware-v2
+async function existingClaimGrounding(prolog, requirementId, claimKey, warnings) {
+    if (prolog === null || !requirementId)
+        return [];
+    const found = [];
+    try {
+        for (const type of GROUNDING_RELATIONSHIP_TYPES) {
+            const targets = await prolog.query(`findall(To, kb_relationship(${type}, '${escapeAtom(requirementId)}', To), Targets)`);
+            if (!targets.success)
+                continue;
+            for (const target of parsePrologList(targets.bindings.Targets ?? "[]")) {
+                const fact = await prolog.query(`once((kb_entity('${escapeAtom(target)}', fact, _GroundProps), memberchk(claim_key=_GroundClaimRaw, _GroundProps), normalize_term_atom(_GroundClaimRaw, ClaimKey), (memberchk(fact_kind=_GroundKindRaw, _GroundProps) -> normalize_term_atom(_GroundKindRaw, FactKind) ; FactKind = '')))`);
+                if (!fact.success)
+                    continue;
+                if (unquoted(fact.bindings.ClaimKey) !== claimKey)
+                    continue;
+                found.push({
+                    relationship: { type, from: requirementId, to: target },
+                    factId: target,
+                    factKind: unquoted(fact.bindings.FactKind) || null,
+                    claimKey,
+                });
+            }
+        }
+    }
+    catch (error) {
+        warnings.push(`Existing grounding of ${requirementId} could not be read (${error instanceof Error ? error.message : String(error)}); check its requires_property, requires_predicate and requires_rule links before linking a predicate.`);
+    }
+    return found;
+}
 // implements REQ-mcp-suggest-predicates
 export async function handleKbSuggestPredicates(prolog, args, context) {
     const text = normalizeText(args.text);
@@ -235,32 +281,72 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
     }
     // Stage 3/4: bind only after eligibility, then decide conservatively.
     const unavailableSchema = Boolean(args.schemaId && selectedSchemas.length === 0);
+    const claimKey = semanticClaimKey(text);
+    const existingGrounding = await existingClaimGrounding(prolog, args.requirementId, claimKey, warnings);
+    const alreadyGrounded = existingGrounding.length > 0;
+    const completeCandidate = recommendedCandidate && recommendedCandidate.binding_status === "complete"
+        ? recommendedCandidate
+        : undefined;
+    // The action names the predicate state; existingGrounding (non-empty) is
+    // the separate "already grounded" signal. A complete candidate for a claim
+    // that is already grounded becomes a replacement, never a second link.
     const recommendedAction = !recommendedCandidate
         ? unavailableSchema
             ? "resolve_schema_reference"
             : "record_ontology_gap"
-        : recommendedCandidate.binding_status === "complete"
-            ? "apply_requires_predicate"
+        : completeCandidate
+            ? alreadyGrounded
+                ? "replace_grounding"
+                : "apply_requires_predicate"
             : "provide_argument_bindings";
-    const applyPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete"
-        ? buildPredicateApplyPlan(recommendedCandidate, args)
+    const predicatePlan = completeCandidate
+        ? buildPredicateApplyPlan(completeCandidate, args)
+        : [];
+    // An already grounded claim gets no predicate write plan: a second
+    // grounding link would fail the proposition-complete rule, so the
+    // replacement plan below swaps the grounding instead. The ontology-gap
+    // observation is not a grounding relationship, so it is planned either way.
+    const applyPlan = completeCandidate
+        ? alreadyGrounded
+            ? []
+            : predicatePlan
         : !recommendedCandidate && !unavailableSchema
             ? buildGapApplyPlan(text, args)
             : [];
-    const relationshipPlan = recommendedCandidate && recommendedCandidate.binding_status === "complete"
-        ? buildRelationshipPlan(String(applyPlan[0]?.id ?? ""), args.requirementId, text, args.existingLogicClaims)
+    const plannedFactId = typeof predicatePlan[0]?.id === "string" ? predicatePlan[0].id : null;
+    const relationshipPlan = completeCandidate && !alreadyGrounded
+        ? buildRelationshipPlan(plannedFactId ?? "", args.requirementId, text, args.existingLogicClaims)
+        : null;
+    const replacementPlan = alreadyGrounded && plannedFactId !== null && args.requirementId
+        ? buildGroundingReplacementPlan(args.requirementId, plannedFactId, predicatePlan, existingGrounding)
+        : null;
+    const relationshipTarget = relationshipPlan !== null || replacementPlan !== null
+        ? plannedFactId
         : null;
+    const groundingSummary = existingGrounding
+        .map((row) => `${row.relationship.type} -> ${row.factId}`)
+        .join(", ");
+    if (alreadyGrounded) {
+        warnings.push(`${args.requirementId} already grounds this claim (${claimKey}) through ${groundingSummary}. A modeled claim takes exactly one logical grounding relationship, so adding requires_predicate beside it fails the proposition-complete rule. ${replacementPlan ? "Keep the existing grounding, or follow replacementPlan to swap it for the predicate." : "Keep the existing grounding; no predicate replacement is available yet."}`);
+    }
     const recommendedPredicateSchema = !recommendedCandidate && !unavailableSchema
         ? buildPredicateSchemaDraft(text, subject)
         : null;
-    const textSummary = recommendedCandidate && recommendedCandidate.binding_status === "complete"
-        ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${recommendedCandidate.predicate_name}. Apply structured predicate facts before falling back to prose.`
-        : recommendedCandidate
-            ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. No apply plan was generated.`
-            : unavailableSchema
-                ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
-                : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.";
-    const claimKey = semanticClaimKey(text);
+    const groundedPrefix = alreadyGrounded
+        ? `${args.requirementId} already grounds this claim through ${groundingSummary}. `
+        : "";
+    const textSummary = groundedPrefix +
+        (replacementPlan
+            ? `To use ${completeCandidate?.predicate_name} instead, follow replacementPlan and link requires_predicate to ${plannedFactId}; otherwise keep the existing grounding.`
+            : completeCandidate
+                ? `Suggested ${candidates.length} predicate candidate(s). Top applicable match: ${completeCandidate.predicate_name}. Apply the predicate fact ${plannedFactId}, then link requires_predicate to that fact id (not a candidate id).`
+                : recommendedCandidate
+                    ? `Matched ${recommendedCandidate.predicate_name}, but exact reviewed values are still required for: ${recommendedCandidate.unbound_arguments.join(", ")}. No apply plan was generated.`
+                    : unavailableSchema
+                        ? `Requested predicate schema ${args.schemaId} is unavailable or semantically inapplicable. No apply plan was generated.`
+                        : alreadyGrounded
+                            ? "No predicate candidate passed the semantic applicability gate; keep the existing grounding and record the ontology-gap observation in applyPlan so the missing schema stays visible."
+                            : "No predicate candidate passed the semantic applicability gate; record an ontology gap and review the generated schema draft instead of silently writing prose.");
     const logicClaims = Array.from(new Set([...(args.existingLogicClaims ?? []), claimKey]));
     return {
         content: [{ type: "text", text: textSummary }],
@@ -276,11 +362,51 @@ export async function handleKbSuggestPredicates(prolog, args, context) {
             recommendedPredicateSchema,
             applyPlan,
             relationshipPlan,
+            relationshipTarget,
+            existingGrounding,
+            replacementPlan,
             warnings,
         },
         applyPlan,
     };
 }
+/**
+ * Ordered steps that swap an existing grounding for the planned predicate
+ * fact while keeping one grounding relationship per modeled claim: write the
+ * fact, retract the old grounding link, then link requires_predicate.
+ */
+// implements REQ-model-predicates-grounding-aware-v2
+function buildGroundingReplacementPlan(requirementId, factId, predicatePlan, existing) {
+    return {
+        relationshipTarget: factId,
+        steps: [
+            {
+                operation: "kb_upsert",
+                input: predicatePlan[0],
+                reason: "Write the predicate fact that will ground the claim.",
+            },
+            {
+                operation: "kb_delete",
+                input: {
+                    relationships: existing.map((row) => row.relationship),
+                },
+                reason: "Retract the existing grounding link so the claim keeps exactly one logical grounding relationship.",
+            },
+            {
+                operation: "kb_upsert",
+                input: {
+                    type: "req",
+                    id: requirementId,
+                    relationships: [
+                        { type: "requires_predicate", from: requirementId, to: factId },
+                    ],
+                },
+                reason: `Link requires_predicate to ${factId}; upsert the requirement with its stored title and status and this relationship only.`,
+            },
+        ],
+        instructions: `Only replace the grounding when the predicate states the claim at least as precisely as ${existing.map((row) => row.factId).join(", ")}. Run kb_check after the last step.`,
+    };
+}
 export async function executeSuggestPredicates(args, context) {
     return handleKbSuggestPredicates(context.prolog ?? null, args, context);
 }

package/dist/operations/mutation/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AA6F/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA4DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/validation.ts"],"names":[],"mappings":"AAKA,OAAO,EAEL,0BAA0B,EAC3B,MAAM,oCAAoC,CAAC;AAO5C,OAAO,KAAK,EAAE,WAAW,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAqI/D,wBAAgB,mBAAmB,CACjC,KAAK,EAAE,WAAW,EAClB,GAAG,EAAE,IAAI,GACR,eAAe,CA4DjB;AAED,OAAO,EAAE,0BAA0B,EAAE,CAAC"}

package/dist/operations/mutation/validation.js

@@ -48,6 +48,23 @@ const ALIASES = new Map([
     ["canonicalKey", "canonical_key"],
     ["closedWorld", "closed_world"],
 ]);
+/** Property names agents use for entity prose that belongs in document.body. */
+const DOCUMENT_TEXT_PROPERTIES = new Set([
+    "body",
+    "text",
+    "description",
+    "content",
+    "markdown",
+    "prose",
+    "summary",
+    "details",
+]);
+/** Every top-level entity key the upsert entity schema does not define. */
+function unknownEntityProperties(entity) {
+    const known = upsertEntitySchema.properties;
+    return Object.keys(entity).filter((key) => !Object.hasOwn(known, key));
+}
+// implements REQ-upsert-unknown-field-guidance
 function formatEntityErrors(entity, errors) {
     const messages = errors.map((error) => {
         const params = error.params;
@@ -61,6 +78,19 @@ function formatEntityErrors(entity, errors) {
             if (canonical) {
                 return `${path}: unknown property '${property}'. Did you mean '${canonical}'? kb_upsert.properties uses snake_case typed fact fields.`;
             }
+            if (path === "root" && DOCUMENT_TEXT_PROPERTIES.has(property)) {
+                const others = unknownEntityProperties(entity).filter((key) => key !== property);
+                return `${path}: unknown property '${property}' (${error.message}). Entity prose (scenario, requirement, test, ADR or observation text) belongs in kb_upsert.document.body, not in kb_upsert.properties.${others.length > 0 ? ` Other unknown properties: ${others.map((key) => `'${key}'`).join(", ")}.` : ""}`;
+            }
+            if (path === "root") {
+                const unknown = unknownEntityProperties(entity);
+                const listed = unknown.length > 0 ? unknown : [property];
+                const proseHint = listed.some((key) => DOCUMENT_TEXT_PROPERTIES.has(key))
+                    ? " Entity prose belongs in kb_upsert.document.body."
+                    : "";
+                return `${path}: unknown propert${listed.length === 1 ? "y" : "ies"} ${listed.map((key) => `'${key}'`).join(", ")} (${error.message}). Remove ${listed.length === 1 ? "it" : "them"} from kb_upsert.properties or use fields the ${String(entity.type ?? "entity")} schema defines.${proseHint}`;
+            }
+            return `${path}: unknown property '${property}' (${error.message}).`;
         }
         if (error.keyword === "enum" && params.allowedValues) {
             return `${path}: ${error.message}. Allowed values: ${params.allowedValues.map(String).join(", ")}`;

package/dist/operations/mutation/workspace-mutation-lock.d.ts

@@ -9,6 +9,8 @@ export interface WorkspaceMutationLockFileSystem {
     }) => void;
     readonly unlinkSync: (target: string) => void;
     readonly rmdirSync: (target: string) => void;
+    /** Atomic rename; required to reclaim a lock from a dead holder. */
+    readonly renameSync?: (from: string, to: string) => void;
 }
 export interface WorkspaceMutationLockOptions {
     readonly lockFileRelative?: string;
@@ -17,6 +19,24 @@ export interface WorkspaceMutationLockOptions {
     readonly sleep?: (ms: number) => Promise<void>;
     readonly fileSystem?: WorkspaceMutationLockFileSystem;
     readonly isProcessAlive?: (pid: number) => boolean;
+    /**
+     * Decide whether a lock whose holder pid is verifiably not alive may be
+     * reclaimed instead of failing closed with operator recovery. Called only
+     * for a readable owner record whose pid is dead; a live, unverifiable,
+     * corrupt or missing owner always keeps the fail-closed refusal.
+     */
+    readonly reclaimDeadHolder?: (holder: DeadLockHolder) => boolean;
+}
+/** The owner record of a lock whose holder process is no longer alive. */
+export interface DeadLockHolder {
+    readonly pid: number;
+    readonly token: string;
+    readonly acquiredAt: number;
+}
+/** A dead holder's lock this acquisition reclaimed. */
+export interface WorkspaceMutationLockReclaim extends DeadLockHolder {
+    readonly reclaimedAt: number;
+    readonly reclaimedByPid: number;
 }
 export declare class WorkspaceMutationLockError extends Error {
     readonly name = "WorkspaceMutationLockError";
@@ -30,6 +50,8 @@ export interface WorkspaceMutationLockHandle {
      * removes a different owner token.
      */
     readonly release: () => void;
+    /** Dead holders this acquisition reclaimed the lock from, oldest first. */
+    readonly reclaimed?: readonly WorkspaceMutationLockReclaim[];
 }
 export declare function releaseWorkspaceMutationLock(handle: WorkspaceMutationLockHandle | undefined, operationFailure?: {
     readonly error: unknown;

package/dist/operations/mutation/workspace-mutation-lock.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"workspace-mutation-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/workspace-mutation-lock.ts"],"names":[],"mappings":"AA6BA,MAAM,WAAW,+BAA+B;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAClB,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE;QAAE,QAAQ,CAAC,SAAS,CAAC,EAAE,OAAO,CAAA;KAAE,KACvC,IAAI,CAAC;IACV,QAAQ,CAAC,YAAY,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,MAAM,CAAC;IAClD,QAAQ,CAAC,aAAa,EAAE,CACtB,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE;QAAE,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAA;KAAE,KACxD,IAAI,CAAC;IACV,QAAQ,CAAC,UAAU,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;IAC9C,QAAQ,CAAC,SAAS,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,IAAI,CAAC;CAC9C;AAeD,MAAM,WAAW,4BAA4B;IAC3C,QAAQ,CAAC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/C,QAAQ,CAAC,UAAU,CAAC,EAAE,+BAA+B,CAAC;IACtD,QAAQ,CAAC,cAAc,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,OAAO,CAAC;CACpD;AAGD,qBAAa,0BAA2B,SAAQ,KAAK;IACnD,SAAkB,IAAI,gCAAgC;CACvD;AAwMD,MAAM,WAAW,2BAA2B;IAC1C;;;;;;OAMG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,IAAI,CAAC;CAC9B;AAGD,wBAAgB,4BAA4B,CAC1C,MAAM,EAAE,2BAA2B,GAAG,SAAS,EAC/C,gBAAgB,CAAC,EAAE;IAAE,QAAQ,CAAC,KAAK,EAAE,OAAO,CAAA;CAAE,EAC9C,SAAS,UAAQ,GAChB,IAAI,CAoBN;AAED;;;;;GAKG;AACH,wBAAgB,6BAA6B,CAC3C,SAAS,EAAE,MAAM,EACjB,KAAK,EAAE,OAAO,EACd,SAAS,EAAE,OAAO,GACjB,OAAO,CAWT;AAED;;;;GAIG;AAEH,wBAAsB,4BAA4B,CAChD,aAAa,EAAE,MAAM,EACrB,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,2BAA2B,CAAC,CA4KtC;AAED;;;;;;;;GAQG;AAEH,wBAAsB,yBAAyB,CAAC,CAAC,EAC/C,aAAa,EAAE,MAAM,EACrB,SAAS,EAAE,MAAM,OAAO,CAAC,CAAC,CAAC,EAC3B,OAAO,GAAE,4BAAiC,GACzC,OAAO,CAAC,CAAC,CAAC,CAWZ"}
+{"version":3,"file":"workspace-mutation-lock.d.ts","sourceRoot":"","sources":["../../../src/operations/mutation/workspace-mutation-lock.ts"],"names":[],"mappings":"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"}

package/dist/operations/mutation/workspace-mutation-lock.js

@@ -1,4 +1,4 @@
-import { mkdirSync, readFileSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import { mkdirSync, readFileSync, renameSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
 import * as path from "node:path";
 import { InputError, OperationError } from "../../cli-errors.js";
 /**
@@ -23,6 +23,7 @@ const NODE_FILE_SYSTEM = {
     },
     unlinkSync: (target) => unlinkSync(target),
     rmdirSync: (target) => rmdirSync(target),
+    renameSync: (from, to) => renameSync(from, to),
 };
 // implements REQ-generated-coordinate-persistence
 export class WorkspaceMutationLockError extends Error {
@@ -156,8 +157,52 @@ function observeExistingLock(fileSystem, target, ownerPath, isProcessAlive) {
     return {
         kind: "recovery",
         description: `holder pid ${record.pid} is not live`,
+        // Legacy file locks are never reclaimed automatically.
+        ...(source === "lock owner metadata" ? { deadHolder: record } : {}),
     };
 }
+/**
+ * Move a dead holder's lock directory aside atomically, confirm the moved
+ * owner is still that dead holder, then delete it. A concurrent reclaimer
+ * loses the rename and simply retries acquisition. If another writer replaced
+ * the lock between observation and rename, the lock is put back and the
+ * acquisition fails closed.
+ */
+function reclaimDeadLock(fileSystem, target, holder, token) {
+    const rename = fileSystem.renameSync;
+    if (rename === undefined)
+        return "changed";
+    const tombstone = `${target}.reclaimed-${token}`;
+    try {
+        rename(target, tombstone);
+    }
+    catch (error) {
+        const code = errorCode(error);
+        if (code === "ENOENT" || code === "EEXIST" || code === "ENOTEMPTY")
+            return "changed";
+        throw new WorkspaceMutationLockError(`failed to reclaim workspace mutation lock at ${target} from dead pid ${holder.pid}: ${errorDetail(error)}`);
+    }
+    const tombstoneOwner = path.join(tombstone, OWNER_FILE);
+    let moved = null;
+    try {
+        moved = readLockRecord(fileSystem.readFileSync(tombstoneOwner));
+    }
+    catch {
+        moved = null;
+    }
+    if (moved === null || moved.token !== holder.token) {
+        try {
+            rename(tombstone, target);
+        }
+        catch {
+            // The original path was taken again; the tombstone stays for an operator.
+        }
+        throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} changed owner while it was reclaimed from dead pid ${holder.pid}. Quiesce all Kibi and source-mutating writers, then verify ${target} and ${tombstone} before removing either`, false);
+    }
+    removeLockOwner(fileSystem, tombstone, tombstoneOwner, true);
+    removeLockDirectory(fileSystem, tombstone);
+    return "reclaimed";
+}
 function defaultIsProcessAlive(pid) {
     try {
         process.kill(pid, 0);
@@ -228,6 +273,7 @@ export async function acquireWorkspaceMutationLock(workspaceRoot, options = {})
         throw new WorkspaceMutationLockError(`failed to create workspace mutation lock parent at ${parentPath} after ${parentResult.attempts} attempt(s): ${errorDetail(parentResult.error)}`);
     }
     let acquired = false;
+    const reclaimed = [];
     let lastBlocker = "unknown";
     let lastObservationMissing = false;
     let missingOwnerRereads = 0;
@@ -257,6 +303,25 @@ export async function acquireWorkspaceMutationLock(workspaceRoot, options = {})
             }
             throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} requires operator recovery: ${observation.description} after ${missingOwnerRereads} reread(s). Quiesce all Kibi and source-mutating writers, then manually verify the owner metadata and remove the lock only after confirming no operation is active`, false);
         }
+        if (observation.kind === "recovery" &&
+            observation.deadHolder !== undefined &&
+            fileSystem.renameSync !== undefined &&
+            options.reclaimDeadHolder?.(observation.deadHolder) === true) {
+            const holder = observation.deadHolder;
+            if (reclaimDeadLock(fileSystem, target, holder, token) === "reclaimed") {
+                reclaimed.push({
+                    pid: holder.pid,
+                    token: holder.token,
+                    acquiredAt: holder.acquiredAt,
+                    reclaimedAt: now(),
+                    reclaimedByPid: process.pid,
+                });
+            }
+            else {
+                await sleep(RETRY_INTERVAL_MS);
+            }
+            continue;
+        }
         if (observation.kind === "recovery") {
             throw new OperationError("SOURCE_MUTATION_LOCK_RECOVERY_REQUIRED", `workspace mutation lock at ${target} requires operator recovery: ${observation.description}. Quiesce all Kibi and source-mutating writers, then manually verify the owner metadata and remove the lock only after confirming no operation is active`, false);
         }
@@ -312,6 +377,7 @@ export async function acquireWorkspaceMutationLock(workspaceRoot, options = {})
     }
     let releaseState = "owned";
     return {
+        ...(reclaimed.length > 0 ? { reclaimed } : {}),
         release: () => {
             if (releaseState === "released")
                 return;

package/dist/operations/planning/apply-plan.d.ts

@@ -9,6 +9,14 @@ export declare function assertBootstrapRecoveryDependencies(remaining: readonly
     dependsOn?: readonly string[];
 }[], applied: ReadonlySet<string>): void;
 export declare function orderBootstrapActions(actions: readonly BootstrapAction[], completed?: Set<string>): BootstrapAction[];
+/**
+ * Checks a plan-bearing kb_apply_plan call can start: the approved hash, the
+ * plan shape and canonical hash, and for a bootstrap plan its live snapshots.
+ * Writes nothing. An MCP async apply runs it before returning the job
+ * receipt, so input and stale-plan errors fail the call instead of the job.
+ * The apply itself repeats every check under the workspace lock.
+ */
+export declare function preflightApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<void>;
 export declare function executeApplyPlan(args: ApplyPlanArgs, context: OperationContext): Promise<{
     content: Array<{
         type: "text";

package/dist/operations/planning/apply-plan.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AAQlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AA8D/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AA6xED,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CA6BD"}
+{"version":3,"file":"apply-plan.d.ts","sourceRoot":"","sources":["../../../src/operations/planning/apply-plan.ts"],"names":[],"mappings":"AAoBA,OAAO,KAAK,EAEV,gBAAgB,EAGjB,MAAM,0CAA0C,CAAC;AAQlD,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,uBAAuB,CAAC;AA+D/B,OAAO,KAAK,EACV,aAAa,EACb,eAAe,EAGhB,MAAM,uBAAuB,CAAC;AAE/B,YAAY,EACV,aAAa,EACb,eAAe,EACf,kBAAkB,GACnB,MAAM,uBAAuB,CAAC;AAG/B,eAAO,MAAM,yBAAyB,EAAG,2BAAoC,CAAC;AA6G9E,wBAAgB,iCAAiC,CAC/C,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE,MAAM,EAChB,SAAS,EAAE,MAAM,GAChB,IAAI,CAMN;AAED,wBAAgB,mCAAmC,CACjD,SAAS,EAAE,SAAS;IAAE,EAAE,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,SAAS,MAAM,EAAE,CAAA;CAAE,EAAE,EACnE,OAAO,EAAE,WAAW,CAAC,MAAM,CAAC,GAC3B,IAAI,CAaN;AAED,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,SAAS,eAAe,EAAE,EACnC,SAAS,cAAoB,GAC5B,eAAe,EAAE,CA2CnB;AA8zBD;;;;;;GAMG;AAEH,wBAAsB,kBAAkB,CACtC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC,IAAI,CAAC,CAiCf;AAyqDD,wBAAsB,gBAAgB,CACpC,IAAI,EAAE,aAAa,EACnB,OAAO,EAAE,gBAAgB,GACxB,OAAO,CAAC;IACT,OAAO,EAAE,KAAK,CAAC;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,CAAC,CAAC;IAC/C,iBAAiB,EAAE,eAAe,CAAC;CACpC,CAAC,CAkDD"}