@skillcap/gdh 0.16.0 → 0.17.1

package/node_modules/@gdh/authoring/dist/lsp.js

@@ -1,12 +1,37 @@
-import { spawn } from "node:child_process";
+import { execFile, spawn } from "node:child_process";
 import { createHash, randomUUID } from "node:crypto";
+import { realpathSync } from "node:fs";
 import fs from "node:fs/promises";
 import net from "node:net";
 import path from "node:path";
-import { resolveConfiguredGodotEditorBin } from "@gdh/core";
-const LSP_INSTANCE_SCHEMA_VERSION = 1;
+import { fileURLToPath, pathToFileURL } from "node:url";
+import { GDH_MANAGED_LSP_SURFACE_VERSION, resolveConfiguredGodotEditorBin } from "@gdh/core";
+import { connectGodotLspClient, GdhLspClientError, } from "./lsp-client.js";
+const LSP_INSTANCE_SCHEMA_VERSION = 2;
 const LSP_LEASE_SCHEMA_VERSION = 1;
+const LSP_STATE_LOCK_SCHEMA_VERSION = 1;
 const LSP_LEASE_STALE_AFTER_MS = 5 * 60 * 1000;
+const LSP_STATE_LOCK_STALE_AFTER_MS = 30_000;
+const LSP_STATE_LOCK_ACQUIRE_TIMEOUT_MS = 5_000;
+const LSP_STATE_LOCK_RETRY_DELAY_MS = 25;
+const LSP_INSTANCE_IDLE_AFTER_MS = 30 * 60 * 1000;
+const MANAGED_LSP_HEALTH_TOTAL_TIMEOUT_MS = 30_000;
+const MANAGED_LSP_HEALTH_CONNECT_TIMEOUT_MS = 250;
+const MANAGED_LSP_HEALTH_REQUEST_TIMEOUT_MS = 5_000;
+const MANAGED_LSP_HEALTH_RETRY_DELAY_MS = 100;
+const MANAGED_LSP_DIAGNOSTIC_CONNECT_TIMEOUT_MS = 1_000;
+const MANAGED_LSP_DIAGNOSTIC_REQUEST_TIMEOUT_MS = 1_000;
+const MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS = 10_000;
+class GdhManagedLspStateLockError extends Error {
+    reason;
+    reasons;
+    constructor(reason, reasons) {
+        super(`Managed LSP state lock unavailable: ${reason}`);
+        this.name = "GdhManagedLspStateLockError";
+        this.reason = reason;
+        this.reasons = reasons;
+    }
+}
 const testFakeRegistry = new Map();
 export async function getManagedLspStatus(input) {
     const worktree = resolveWorktreeIdentity(input.targetPath, input.status, input.projectConfig);
@@ -29,48 +54,126 @@ export async function getManagedLspStatus(input) {
     if (lspCapability?.availability === "disabled") {
         return unavailable;
     }
-    return withLease(worktree, input.owner ?? "gdh lsp status", async (lease, activeLeaseCount) => {
-        let cleanedStaleInstance = false;
-        const existing = await readPersistedInstance(worktree);
-        if (existing !== null) {
-            const validation = await validatePersistedInstance(existing.instance);
-            if (validation.reusable) {
-                const reusedInstance = {
-                    ...existing.instance,
-                    lastValidatedAt: new Date().toISOString(),
-                    trust: validation.trust,
-                };
-                await persistInstance(worktree, {
-                    ...existing,
-                    instance: reusedInstance,
-                    rawPayload: validation.rawPayload ?? existing.rawPayload,
+    try {
+        return await withManagedLspStateLock(worktree, input.owner ?? "gdh lsp status", async (stateLock) => await withLease(worktree, input.owner ?? "gdh lsp status", async (lease, activeLeaseCount) => {
+            let cleanedStaleInstance = false;
+            let cleanupReasons = [];
+            const projectPath = path.resolve(input.targetPath, input.status.primaryProjectPath ?? ".");
+            const expectedIdentity = await resolveCurrentManagedLspIdentity(worktree, projectPath);
+            const existing = await readPersistedInstance(worktree);
+            if (existing !== null) {
+                const validation = await validatePersistedInstance(existing.instance, expectedIdentity);
+                if (validation.reusable) {
+                    const reusedInstance = {
+                        ...existing.instance,
+                        lastValidatedAt: new Date().toISOString(),
+                        trust: validation.trust,
+                    };
+                    await persistInstance(worktree, {
+                        ...existing,
+                        instance: reusedInstance,
+                        rawPayload: validation.rawPayload ?? existing.rawPayload,
+                    });
+                    return createStatusResult({
+                        targetPath: input.targetPath,
+                        readiness: input.status.readiness,
+                        availability: "available",
+                        status: validation.trust === "trusted" ? "ready" : "degraded",
+                        validationMode: existing.validationMode,
+                        summary: validation.trust === "trusted"
+                            ? "Reused the managed authoring.lsp instance for this worktree."
+                            : "Reused the managed authoring.lsp instance, but trust is degraded and the instance should be treated cautiously.",
+                        reasons: dedupe([
+                            ...stateLock.recoveredReasons,
+                            ...(validation.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                        ]),
+                        worktree,
+                        lease,
+                        activeLeaseCount,
+                        reusedInstance: true,
+                        cleanedStaleInstance,
+                        instance: reusedInstance,
+                        inventoryObservedAt: input.status.inventoryObservedAt,
+                        projectConfigPresent: input.projectConfig !== null,
+                        rawPayload: validation.rawPayload ?? existing.rawPayload,
+                    });
+                }
+                cleanedStaleInstance = true;
+                cleanupReasons = validation.reasons;
+                await cleanupPersistedInstance(worktree, existing.instance, validation.reason, {
+                    expectedIdentity,
                 });
-                return createStatusResult({
+            }
+            const launchResult = await launchManagedInstance(worktree, projectPath);
+            if ("unavailable" in launchResult) {
+                return createUnavailableStatus({
                     targetPath: input.targetPath,
                     readiness: input.status.readiness,
-                    availability: "available",
-                    status: validation.trust === "trusted" ? "ready" : "degraded",
-                    validationMode: existing.validationMode,
-                    summary: validation.trust === "trusted"
-                        ? "Reused the managed authoring.lsp instance for this worktree."
-                        : "Reused the managed authoring.lsp instance, but trust is degraded and the instance should be treated cautiously.",
-                    reasons: validation.trust === "trusted" ? [] : ["lsp_instance_degraded"],
                     worktree,
+                    inventoryObservedAt: input.status.inventoryObservedAt,
+                    projectConfigPresent: input.projectConfig !== null,
+                    availability: "unavailable",
+                    reasons: [
+                        ...stateLock.recoveredReasons,
+                        ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
+                        ...cleanupReasons,
+                        ...launchResult.unavailable.reasons,
+                    ],
+                    summary: launchResult.unavailable.summary,
                     lease,
                     activeLeaseCount,
-                    reusedInstance: true,
                     cleanedStaleInstance,
-                    instance: reusedInstance,
-                    inventoryObservedAt: input.status.inventoryObservedAt,
-                    projectConfigPresent: input.projectConfig !== null,
-                    rawPayload: validation.rawPayload ?? existing.rawPayload,
+                    rawPayload: launchResult.unavailable.rawPayload,
                 });
             }
-            cleanedStaleInstance = true;
-            await cleanupPersistedInstance(worktree, existing.instance, validation.reason);
-        }
-        const launchResult = await launchManagedInstance(worktree, path.resolve(input.targetPath, input.status.primaryProjectPath ?? "."));
-        if ("unavailable" in launchResult) {
+            const launchedInstance = {
+                instanceId: launchResult.instanceId,
+                launcher: launchResult.launcher,
+                port: launchResult.port,
+                pid: launchResult.pid,
+                projectPath,
+                command: launchResult.command,
+                trust: launchResult.trust,
+                launchedAt: new Date().toISOString(),
+                lastValidatedAt: new Date().toISOString(),
+                identity: launchResult.identity,
+            };
+            await persistInstance(worktree, {
+                schemaVersion: LSP_INSTANCE_SCHEMA_VERSION,
+                instance: launchedInstance,
+                validationMode: launchResult.validationMode,
+                diagnostics: launchResult.diagnostics,
+                rawPayload: launchResult.rawPayload,
+            });
+            return createStatusResult({
+                targetPath: input.targetPath,
+                readiness: input.status.readiness,
+                availability: "available",
+                status: launchResult.trust === "trusted" ? "ready" : "degraded",
+                validationMode: launchResult.validationMode,
+                summary: launchResult.trust === "trusted"
+                    ? "Started a managed authoring.lsp instance for this worktree."
+                    : "Started a managed authoring.lsp instance, but trust is degraded and validation should be treated cautiously.",
+                reasons: dedupe([
+                    ...stateLock.recoveredReasons,
+                    ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
+                    ...cleanupReasons,
+                    ...(launchResult.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                ]),
+                worktree,
+                lease,
+                activeLeaseCount,
+                reusedInstance: false,
+                cleanedStaleInstance,
+                instance: launchedInstance,
+                inventoryObservedAt: input.status.inventoryObservedAt,
+                projectConfigPresent: input.projectConfig !== null,
+                rawPayload: launchResult.rawPayload,
+            });
+        }));
+    }
+    catch (error) {
+        if (error instanceof GdhManagedLspStateLockError) {
             return createUnavailableStatus({
                 targetPath: input.targetPath,
                 readiness: input.status.readiness,
@@ -78,59 +181,297 @@ export async function getManagedLspStatus(input) {
                 inventoryObservedAt: input.status.inventoryObservedAt,
                 projectConfigPresent: input.projectConfig !== null,
                 availability: "unavailable",
-                reasons: [
-                    ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
-                    launchResult.unavailable.reason,
+                reasons: error.reasons,
+                summary: "authoring.lsp state is temporarily unavailable because another process is mutating managed LSP state for this worktree.",
+            });
+        }
+        throw error;
+    }
+}
+export async function checkManagedLsp(input) {
+    const worktree = resolveWorktreeIdentity(input.targetPath, input.status, input.projectConfig);
+    return await withManagedLspLifecycleLock(worktree, "check", "gdh lsp check", async (stateLock) => {
+        const persisted = await readPersistedInstance(worktree);
+        const expectedIdentity = await resolveCurrentManagedLspIdentity(worktree, path.resolve(input.targetPath, input.status.primaryProjectPath ?? "."));
+        if (persisted === null) {
+            return createLifecycleCommandResult({
+                targetPath: input.targetPath,
+                command: "check",
+                status: "not_found",
+                summary: "No persisted managed authoring.lsp instance exists for this worktree.",
+                reasons: dedupe([...stateLock.recoveredReasons, "lsp_instance_not_found"]),
+                worktree,
+                instance: null,
+                transportStatus: "unknown",
+                transportReasons: [],
+                transportRawPayload: null,
+                cleanupStatus: "not_needed",
+                cleanupReason: null,
+                killedPid: false,
+                recommendations: [
+                    "Run `gdh lsp status` or `gdh lsp restart` to launch a managed instance.",
                 ],
-                summary: launchResult.unavailable.summary,
-                lease,
-                activeLeaseCount,
-                cleanedStaleInstance,
+                statusResult: null,
             });
         }
-        const launchedInstance = {
-            instanceId: launchResult.instanceId,
-            launcher: launchResult.launcher,
-            port: launchResult.port,
-            pid: launchResult.pid,
-            projectPath: path.resolve(input.targetPath, input.status.primaryProjectPath ?? "."),
-            command: launchResult.command,
-            trust: launchResult.trust,
-            launchedAt: new Date().toISOString(),
-            lastValidatedAt: new Date().toISOString(),
-        };
-        await persistInstance(worktree, {
-            schemaVersion: LSP_INSTANCE_SCHEMA_VERSION,
-            instance: launchedInstance,
-            validationMode: launchResult.validationMode,
-            diagnostics: launchResult.diagnostics,
-            rawPayload: launchResult.rawPayload,
+        const validation = await validatePersistedInstance(persisted.instance, expectedIdentity);
+        if (validation.reusable) {
+            const cleanupPolicy = classifyManagedLspCleanupPolicy(persisted.instance);
+            if (cleanupPolicy !== null) {
+                return createLifecycleCommandResult({
+                    targetPath: input.targetPath,
+                    command: "check",
+                    status: "degraded",
+                    summary: "The persisted managed authoring.lsp instance is protocol-healthy but should be cleaned up by lifecycle policy.",
+                    reasons: dedupe([...stateLock.recoveredReasons, ...cleanupPolicy.reasons]),
+                    worktree,
+                    instance: persisted.instance,
+                    transportStatus: "healthy",
+                    transportReasons: [],
+                    transportRawPayload: {
+                        ...(validation.rawPayload ?? {}),
+                        cleanupPolicy,
+                    },
+                    cleanupStatus: "recommended",
+                    cleanupReason: cleanupPolicy.reason,
+                    killedPid: false,
+                    recommendations: ["Run `gdh lsp prune` to remove stale managed LSP state."],
+                    statusResult: null,
+                });
+            }
+            const lifecycleStatus = validation.trust === "trusted" ? "ready" : "degraded";
+            return createLifecycleCommandResult({
+                targetPath: input.targetPath,
+                command: "check",
+                status: lifecycleStatus,
+                summary: validation.trust === "trusted"
+                    ? "The persisted managed authoring.lsp instance is protocol-healthy."
+                    : "The persisted managed authoring.lsp instance is reachable, but trust is degraded.",
+                reasons: dedupe([
+                    ...stateLock.recoveredReasons,
+                    ...(validation.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                ]),
+                worktree,
+                instance: persisted.instance,
+                transportStatus: "healthy",
+                transportReasons: [],
+                transportRawPayload: validation.rawPayload,
+                cleanupStatus: "none",
+                cleanupReason: null,
+                killedPid: false,
+                recommendations: [],
+                statusResult: null,
+            });
+        }
+        return createLifecycleCommandResult({
+            targetPath: input.targetPath,
+            command: "check",
+            status: "unavailable",
+            summary: "The persisted managed authoring.lsp instance is not protocol-healthy and should be restarted or pruned.",
+            reasons: dedupe([...stateLock.recoveredReasons, ...validation.reasons]),
+            worktree,
+            instance: persisted.instance,
+            transportStatus: "unhealthy",
+            transportReasons: validation.reasons,
+            transportRawPayload: validation.rawPayload,
+            cleanupStatus: "recommended",
+            cleanupReason: validation.reason,
+            killedPid: false,
+            recommendations: ["Run `gdh lsp restart` to replace the managed instance."],
+            statusResult: null,
+        });
+    });
+}
+export async function stopManagedLsp(input) {
+    const worktree = resolveWorktreeIdentity(input.targetPath, input.status, input.projectConfig);
+    return await withManagedLspLifecycleLock(worktree, "stop", "gdh lsp stop", async (stateLock) => {
+        const persisted = await readPersistedInstance(worktree);
+        const expectedIdentity = await resolveCurrentManagedLspIdentity(worktree, path.resolve(input.targetPath, input.status.primaryProjectPath ?? "."));
+        if (persisted === null) {
+            return createLifecycleCommandResult({
+                targetPath: input.targetPath,
+                command: "stop",
+                status: "not_found",
+                summary: "No persisted managed authoring.lsp instance exists for this worktree.",
+                reasons: dedupe([...stateLock.recoveredReasons, "lsp_instance_not_found"]),
+                worktree,
+                instance: null,
+                transportStatus: "unknown",
+                transportReasons: [],
+                transportRawPayload: null,
+                cleanupStatus: "not_needed",
+                cleanupReason: null,
+                killedPid: false,
+                recommendations: [],
+                statusResult: null,
+            });
+        }
+        const cleanup = await cleanupPersistedInstance(worktree, persisted.instance, "lsp_stop_requested", {
+            killProcess: true,
+            expectedIdentity,
         });
-        return createStatusResult({
+        return createLifecycleCommandResult({
             targetPath: input.targetPath,
-            readiness: input.status.readiness,
-            availability: "available",
-            status: launchResult.trust === "trusted" ? "ready" : "degraded",
-            validationMode: launchResult.validationMode,
-            summary: launchResult.trust === "trusted"
-                ? "Started a managed authoring.lsp instance for this worktree."
-                : "Started a managed authoring.lsp instance, but trust is degraded and validation should be treated cautiously.",
-            reasons: dedupe([
-                ...(cleanedStaleInstance ? ["stale_lsp_instance_cleaned"] : []),
-                ...(launchResult.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
-            ]),
+            command: "stop",
+            status: "stopped",
+            summary: "Stopped the persisted GDH-managed authoring.lsp instance for this worktree.",
+            reasons: stateLock.recoveredReasons,
             worktree,
-            lease,
-            activeLeaseCount,
-            reusedInstance: false,
-            cleanedStaleInstance,
-            instance: launchedInstance,
-            inventoryObservedAt: input.status.inventoryObservedAt,
-            projectConfigPresent: input.projectConfig !== null,
-            rawPayload: launchResult.rawPayload,
+            instance: persisted.instance,
+            transportStatus: "unknown",
+            transportReasons: [],
+            transportRawPayload: persisted.rawPayload,
+            cleanupStatus: "stopped",
+            cleanupReason: "lsp_stop_requested",
+            killedPid: cleanup.killedPid,
+            recommendations: [],
+            statusResult: null,
         });
     });
 }
+export async function restartManagedLsp(input) {
+    const stopped = await stopManagedLsp(input);
+    const statusResult = await getManagedLspStatus({
+        targetPath: input.targetPath,
+        status: input.status,
+        projectConfig: input.projectConfig,
+        owner: input.owner ?? "gdh lsp restart",
+    });
+    return createLifecycleCommandResult({
+        targetPath: input.targetPath,
+        command: "restart",
+        status: statusResult.status === "ready" ? "ready" : statusResult.status,
+        summary: statusResult.status === "ready"
+            ? "Restarted the managed authoring.lsp instance for this worktree."
+            : `Restart attempted, but managed authoring.lsp is ${statusResult.status}.`,
+        reasons: dedupe([...stopped.reasons, ...statusResult.reasons]),
+        worktree: statusResult.worktree,
+        instance: statusResult.instance,
+        transportStatus: statusResult.status === "ready" ? "healthy" : "unhealthy",
+        transportReasons: statusResult.reasons,
+        transportRawPayload: statusResult.provenance.rawPayload,
+        cleanupStatus: stopped.cleanup.status === "stopped" ? "stopped" : "not_needed",
+        cleanupReason: stopped.cleanup.reason,
+        killedPid: stopped.cleanup.killedPid,
+        recommendations: statusResult.status === "ready"
+            ? []
+            : ["Inspect `reasons` and run `gdh lsp doctor` for cleanup guidance."],
+        statusResult,
+    });
+}
+export async function pruneManagedLsp(input) {
+    const worktree = resolveWorktreeIdentity(input.targetPath, input.status, input.projectConfig);
+    return await withManagedLspLifecycleLock(worktree, "prune", "gdh lsp prune", async (stateLock) => {
+        const persisted = await readPersistedInstance(worktree);
+        const expectedIdentity = await resolveCurrentManagedLspIdentity(worktree, path.resolve(input.targetPath, input.status.primaryProjectPath ?? "."));
+        if (persisted === null) {
+            return createLifecycleCommandResult({
+                targetPath: input.targetPath,
+                command: "prune",
+                status: "not_found",
+                summary: "No stale managed authoring.lsp state exists for this worktree.",
+                reasons: dedupe([...stateLock.recoveredReasons, "lsp_instance_not_found"]),
+                worktree,
+                instance: null,
+                transportStatus: "unknown",
+                transportReasons: [],
+                transportRawPayload: null,
+                cleanupStatus: "not_needed",
+                cleanupReason: null,
+                killedPid: false,
+                recommendations: [],
+                statusResult: null,
+            });
+        }
+        const validation = await validatePersistedInstance(persisted.instance, expectedIdentity);
+        if (validation.reusable) {
+            const cleanupPolicy = classifyManagedLspCleanupPolicy(persisted.instance);
+            if (cleanupPolicy !== null) {
+                const cleanup = await cleanupPersistedInstance(worktree, persisted.instance, cleanupPolicy.reason, {
+                    killProcess: true,
+                    expectedIdentity,
+                });
+                return createLifecycleCommandResult({
+                    targetPath: input.targetPath,
+                    command: "prune",
+                    status: "pruned",
+                    summary: "Pruned idle or stale managed authoring.lsp state for this worktree.",
+                    reasons: dedupe([...stateLock.recoveredReasons, ...cleanupPolicy.reasons]),
+                    worktree,
+                    instance: persisted.instance,
+                    transportStatus: "healthy",
+                    transportReasons: [],
+                    transportRawPayload: {
+                        ...(validation.rawPayload ?? {}),
+                        cleanupPolicy,
+                    },
+                    cleanupStatus: "pruned",
+                    cleanupReason: cleanupPolicy.reason,
+                    killedPid: cleanup.killedPid,
+                    recommendations: ["Run `gdh lsp status` when a managed instance is needed again."],
+                    statusResult: null,
+                });
+            }
+            return createLifecycleCommandResult({
+                targetPath: input.targetPath,
+                command: "prune",
+                status: validation.trust === "trusted" ? "ready" : "degraded",
+                summary: "The persisted managed authoring.lsp instance is still reusable; prune did not remove it.",
+                reasons: dedupe([
+                    ...stateLock.recoveredReasons,
+                    ...(validation.trust === "trusted" ? [] : ["lsp_instance_degraded"]),
+                ]),
+                worktree,
+                instance: persisted.instance,
+                transportStatus: "healthy",
+                transportReasons: [],
+                transportRawPayload: validation.rawPayload,
+                cleanupStatus: "none",
+                cleanupReason: null,
+                killedPid: false,
+                recommendations: [],
+                statusResult: null,
+            });
+        }
+        const cleanup = await cleanupPersistedInstance(worktree, persisted.instance, validation.reason, {
+            killProcess: false,
+            expectedIdentity,
+        });
+        return createLifecycleCommandResult({
+            targetPath: input.targetPath,
+            command: "prune",
+            status: "pruned",
+            summary: "Pruned stale managed authoring.lsp state without killing a live process.",
+            reasons: dedupe([...stateLock.recoveredReasons, ...validation.reasons]),
+            worktree,
+            instance: persisted.instance,
+            transportStatus: "unhealthy",
+            transportReasons: validation.reasons,
+            transportRawPayload: validation.rawPayload,
+            cleanupStatus: "pruned",
+            cleanupReason: validation.reason,
+            killedPid: cleanup.killedPid,
+            recommendations: ["Run `gdh lsp status` when a managed instance is needed again."],
+            statusResult: null,
+        });
+    });
+}
+export async function doctorManagedLsp(input) {
+    const checked = await checkManagedLsp(input);
+    return {
+        ...checked,
+        command: "doctor",
+        summary: checked.status === "ready"
+            ? "Managed authoring.lsp lifecycle and transport are healthy. Use `gdh authoring check` to collect validator evidence."
+            : checked.summary,
+        recommendations: checked.status === "ready"
+            ? [
+                "Use `gdh authoring check` to collect GDScript LSP diagnostics and scene/resource validator evidence.",
+                "`gdh lsp status` and `gdh lsp doctor` report lifecycle health only; they are not diagnostic evidence.",
+            ]
+            : checked.recommendations,
+    };
+}
 export async function runManagedAuthoringCheck(input) {
     const pendingImportState = {
         status: "unknown",
@@ -139,9 +480,6 @@ export async function runManagedAuthoringCheck(input) {
         seedPath: null,
         worktreePath: null,
     };
-    const persisted = input.lspStatus.instance
-        ? await readPersistedInstance(input.lspStatus.worktree)
-        : null;
     if (input.lspStatus.status === "unavailable") {
         return {
             targetPath: input.targetPath,
@@ -170,10 +508,16 @@ export async function runManagedAuthoringCheck(input) {
             },
         };
     }
+    const persisted = input.lspStatus.instance
+        ? await readOrCollectPersistedDiagnostics(input)
+        : null;
     const validationMode = persisted?.validationMode ?? "unimplemented";
     const diagnostics = persisted?.diagnostics ?? [];
     const rawPayload = persisted?.rawPayload ?? input.lspStatus.provenance.rawPayload;
     const trust = input.lspStatus.instance?.trust ?? null;
+    const validationFailureReason = rawPayload !== null && typeof rawPayload["failureReason"] === "string"
+        ? rawPayload["failureReason"]
+        : null;
     if (input.lspStatus.status === "degraded" || validationMode === "degraded") {
         return {
             targetPath: input.targetPath,
@@ -187,6 +531,7 @@ export async function runManagedAuthoringCheck(input) {
             reasons: dedupe([
                 ...input.lspStatus.reasons,
                 validationMode === "degraded" ? "lsp_validation_degraded" : "",
+                validationFailureReason ?? "",
             ].filter(Boolean)),
             provenance: {
                 source: "authoring.lsp",
@@ -266,11 +611,11 @@ export async function runManagedAuthoringCheck(input) {
         capability: "authoring.lsp",
         readiness: input.status.readiness,
         status: "degraded",
-        summary: "The managed authoring.lsp instance is ready, but GDH has not implemented Godot diagnostic collection yet.",
+        summary: "The managed authoring.lsp instance is ready, but did not report a supported diagnostic mode.",
         diagnostics: [],
         importState: pendingImportState,
         caveats: [],
-        reasons: ["lsp_transport_not_implemented"],
+        reasons: ["lsp_validation_mode_unimplemented"],
         provenance: {
             source: "authoring.lsp",
             inventoryObservedAt: input.status.inventoryObservedAt,
@@ -288,6 +633,243 @@ export async function runManagedAuthoringCheck(input) {
         },
     };
 }
+async function readOrCollectPersistedDiagnostics(input) {
+    if (input.lspStatus.instance === null) {
+        return null;
+    }
+    try {
+        return await withManagedLspStateLock(input.lspStatus.worktree, "gdh authoring check diagnostics", async () => {
+            const persisted = await readPersistedInstance(input.lspStatus.worktree);
+            if (persisted === null ||
+                input.lspStatus.status !== "ready" ||
+                input.lspStatus.instance === null ||
+                persisted.instance.launcher !== "godot_editor") {
+                return persisted;
+            }
+            const collected = await collectManagedGdscriptDiagnostics({
+                targetPath: input.targetPath,
+                status: input.status,
+                worktree: input.lspStatus.worktree,
+                instance: input.lspStatus.instance,
+                persisted,
+            });
+            await persistInstance(input.lspStatus.worktree, collected);
+            return collected;
+        });
+    }
+    catch (error) {
+        if (error instanceof GdhManagedLspStateLockError) {
+            return {
+                schemaVersion: LSP_INSTANCE_SCHEMA_VERSION,
+                instance: input.lspStatus.instance,
+                validationMode: "degraded",
+                diagnostics: [],
+                rawPayload: {
+                    collection: "gdscript_diagnostics",
+                    diagnosticMethod: "textDocument/publishDiagnostics",
+                    failureReason: error.reason,
+                    reasons: error.reasons,
+                },
+            };
+        }
+        throw error;
+    }
+}
+async function collectManagedGdscriptDiagnostics(input) {
+    const projectPath = path.resolve(input.targetPath, input.status.primaryProjectPath ?? ".");
+    const files = await listGdscriptFiles(projectPath);
+    const checkedFiles = files.map((filePath) => toProjectRelativePath(projectPath, filePath));
+    if (files.length === 0) {
+        return {
+            ...input.persisted,
+            validationMode: "passed",
+            diagnostics: [],
+            rawPayload: {
+                collection: "gdscript_diagnostics",
+                diagnosticMethod: "textDocument/publishDiagnostics",
+                projectPath,
+                checkedFiles,
+                diagnosticCollections: [],
+            },
+        };
+    }
+    try {
+        const client = await connectGodotLspClient({
+            port: input.instance.port,
+            connectTimeoutMs: MANAGED_LSP_DIAGNOSTIC_CONNECT_TIMEOUT_MS,
+            requestTimeoutMs: MANAGED_LSP_DIAGNOSTIC_REQUEST_TIMEOUT_MS,
+        });
+        const diagnosticCollections = [];
+        try {
+            await client.initialize({
+                rootUri: pathToFileURL(projectPath).href,
+            });
+            await client.initialized();
+            for (const filePath of files) {
+                const uri = pathToFileURL(filePath).href;
+                const diagnosticsPromise = client.waitForDiagnostics({
+                    uri,
+                    timeoutMs: resolveManagedLspDiagnosticWaitTimeoutMs(),
+                });
+                await client.didOpen({
+                    uri,
+                    languageId: "gdscript",
+                    version: 1,
+                    text: await fs.readFile(filePath, "utf8"),
+                });
+                diagnosticCollections.push(await diagnosticsPromise);
+            }
+        }
+        finally {
+            await client.close();
+        }
+        const diagnostics = diagnosticCollections.flatMap((collection) => collection.diagnostics.map((diagnostic) => normalizeGdscriptDiagnostic(projectPath, collection.uri, diagnostic)));
+        return {
+            ...input.persisted,
+            validationMode: diagnostics.length > 0 ? "diagnostics" : "passed",
+            diagnostics,
+            rawPayload: {
+                collection: "gdscript_diagnostics",
+                diagnosticMethod: "textDocument/publishDiagnostics",
+                projectPath,
+                checkedFiles,
+                diagnosticCollections: diagnosticCollections.map((collection) => ({
+                    uri: collection.uri,
+                    path: fileUriToProjectRelativePath(projectPath, collection.uri),
+                    diagnosticsCount: collection.diagnostics.length,
+                    diagnostics: collection.diagnostics,
+                })),
+            },
+        };
+    }
+    catch (error) {
+        if (error instanceof GdhLspClientError) {
+            return {
+                ...input.persisted,
+                validationMode: "degraded",
+                diagnostics: [],
+                rawPayload: {
+                    collection: "gdscript_diagnostics",
+                    diagnosticMethod: "textDocument/publishDiagnostics",
+                    projectPath,
+                    checkedFiles,
+                    diagnosticCollections: [],
+                    failureReason: error.reason,
+                    failureDetails: error.details,
+                },
+            };
+        }
+        throw error;
+    }
+}
+async function listGdscriptFiles(projectPath) {
+    const ignoredDirectoryNames = new Set([
+        ".git",
+        ".godot",
+        ".gdh-state",
+        "node_modules",
+        "dist",
+        "coverage",
+    ]);
+    const files = [];
+    const visit = async (directoryPath) => {
+        let entries;
+        try {
+            entries = await fs.readdir(directoryPath, { withFileTypes: true });
+        }
+        catch {
+            return;
+        }
+        for (const entry of entries) {
+            if (entry.isDirectory()) {
+                if (!ignoredDirectoryNames.has(entry.name)) {
+                    await visit(path.join(directoryPath, entry.name));
+                }
+                continue;
+            }
+            if (entry.isFile() && entry.name.endsWith(".gd")) {
+                files.push(path.join(directoryPath, entry.name));
+            }
+        }
+    };
+    await visit(projectPath);
+    return files.sort((a, b) => a.localeCompare(b));
+}
+function normalizeGdscriptDiagnostic(projectPath, uri, diagnostic) {
+    const range = normalizeLspRange(diagnostic.range);
+    return {
+        message: diagnostic.message,
+        path: fileUriToProjectRelativePath(projectPath, uri),
+        line: range.line,
+        column: range.column,
+        endLine: range.endLine,
+        endColumn: range.endColumn,
+        severity: normalizeLspSeverity(diagnostic.severity),
+        source: "godot_lsp",
+        raw: diagnostic.raw,
+    };
+}
+function normalizeLspSeverity(value) {
+    if (value === 1) {
+        return "error";
+    }
+    if (value === 2) {
+        return "warning";
+    }
+    return "info";
+}
+function normalizeLspRange(range) {
+    if (typeof range !== "object" || range === null) {
+        return { line: null, column: null, endLine: null, endColumn: null };
+    }
+    const candidate = range;
+    const startLine = numberOrNull(candidate.start?.line);
+    const startCharacter = numberOrNull(candidate.start?.character);
+    const endLine = numberOrNull(candidate.end?.line);
+    const endCharacter = numberOrNull(candidate.end?.character);
+    return {
+        line: startLine === null ? null : startLine + 1,
+        column: startCharacter === null ? null : startCharacter + 1,
+        endLine: endLine === null ? null : endLine + 1,
+        endColumn: endCharacter === null ? null : endCharacter + 1,
+    };
+}
+function numberOrNull(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+function fileUriToProjectRelativePath(projectPath, uri) {
+    if (!uri.startsWith("file://")) {
+        return null;
+    }
+    try {
+        return toProjectRelativePath(canonicalExistingPath(projectPath), canonicalExistingPath(fileURLToPath(uri)));
+    }
+    catch {
+        return null;
+    }
+}
+function canonicalExistingPath(filePath) {
+    try {
+        return realpathSync.native(filePath);
+    }
+    catch {
+        return path.resolve(filePath);
+    }
+}
+function resolveManagedLspDiagnosticWaitTimeoutMs() {
+    const configured = process.env["GDH_TEST_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS"];
+    if (configured === undefined) {
+        return MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
+    }
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || parsed <= 0) {
+        return MANAGED_LSP_DIAGNOSTIC_WAIT_TIMEOUT_MS;
+    }
+    return parsed;
+}
+function toProjectRelativePath(projectPath, filePath) {
+    return path.relative(projectPath, filePath).split(path.sep).join("/");
+}
 export async function resetManagedLspTestState() {
     testFakeRegistry.clear();
 }
@@ -302,6 +884,209 @@ function resolveWorktreeIdentity(targetPath, status, projectConfig) {
         stateRootPath,
     };
 }
+async function resolveCurrentManagedLspIdentity(worktree, projectPath) {
+    const testMode = process.env["GDH_TEST_LSP_MODE"];
+    if (testMode) {
+        return await createManagedLspInstanceIdentity({
+            worktree,
+            projectPath,
+            launcher: "test_fake",
+            editorBinPath: `test_fake:${normalizeTestMode(testMode)}`,
+            editorVersion: normalizeTestMode(testMode),
+            editorVersionReason: null,
+        });
+    }
+    const godotBin = await resolveConfiguredGodotEditorBin({
+        targetPath: worktree.rootPath,
+        environment: process.env,
+    });
+    const version = godotBin === null ? null : await probeGodotEditorVersion(godotBin);
+    return await createManagedLspInstanceIdentity({
+        worktree,
+        projectPath,
+        launcher: "godot_editor",
+        editorBinPath: godotBin,
+        editorVersion: version?.version ?? null,
+        editorVersionReason: godotBin === null
+            ? "godot_editor_not_configured"
+            : (version?.reason ?? "godot_editor_version_unavailable"),
+    });
+}
+async function createManagedLspInstanceIdentity(input) {
+    const worktreeRootPath = await canonicalizePath(input.worktree.rootPath);
+    const projectRootPath = await canonicalizePath(input.projectPath);
+    const identitySeed = JSON.stringify({
+        worktreeRootPath,
+        projectRootPath,
+        worktreeKey: input.worktree.worktreeKey,
+        projectKey: input.worktree.projectKey,
+        launcher: input.launcher,
+        editorBinPath: input.editorBinPath,
+        editorVersion: input.editorVersion,
+        lspSurfaceVersion: GDH_MANAGED_LSP_SURFACE_VERSION,
+    });
+    return {
+        schemaVersion: GDH_MANAGED_LSP_SURFACE_VERSION,
+        identityKey: hashKey(identitySeed),
+        worktreeRootPath,
+        projectRootPath,
+        worktreeKey: input.worktree.worktreeKey,
+        projectKey: input.worktree.projectKey,
+        launcher: input.launcher,
+        editorBinPath: input.editorBinPath,
+        editorVersion: input.editorVersion,
+        editorVersionReason: input.editorVersionReason,
+        lspSurfaceVersion: GDH_MANAGED_LSP_SURFACE_VERSION,
+    };
+}
+async function canonicalizePath(value) {
+    const resolved = path.resolve(value);
+    return await fs.realpath(resolved).catch(() => resolved);
+}
+async function probeGodotEditorVersion(godotBin) {
+    return await new Promise((resolve) => {
+        const child = execFile(godotBin, ["--version"], { timeout: 1_000 }, (error, stdout) => {
+            if (error) {
+                resolve({
+                    version: null,
+                    reason: "godot_editor_version_probe_failed",
+                });
+                return;
+            }
+            const version = stdout.trim().split(/\s+/)[0] ?? "";
+            resolve({
+                version: version.length > 0 ? version : null,
+                reason: version.length > 0 ? null : "godot_editor_version_empty",
+            });
+        });
+        child.once("error", () => {
+            resolve({
+                version: null,
+                reason: "godot_editor_version_probe_failed",
+            });
+        });
+    });
+}
+async function withManagedLspStateLock(worktree, owner, callback) {
+    const lock = await acquireManagedLspStateLock(worktree, owner);
+    try {
+        return await callback(lock);
+    }
+    finally {
+        await releaseManagedLspStateLock(worktree, lock);
+    }
+}
+async function withManagedLspLifecycleLock(worktree, command, owner, callback) {
+    try {
+        return await withManagedLspStateLock(worktree, owner, callback);
+    }
+    catch (error) {
+        if (error instanceof GdhManagedLspStateLockError) {
+            return createLifecycleCommandResult({
+                targetPath: worktree.rootPath,
+                command,
+                status: "unavailable",
+                summary: "Managed authoring.lsp state is temporarily unavailable because another process is mutating it for this worktree.",
+                reasons: error.reasons,
+                worktree,
+                instance: null,
+                transportStatus: "unknown",
+                transportReasons: error.reasons,
+                transportRawPayload: null,
+                cleanupStatus: "none",
+                cleanupReason: error.reason,
+                killedPid: false,
+                recommendations: ["Retry the LSP lifecycle command after the current mutation finishes."],
+                statusResult: null,
+            });
+        }
+        throw error;
+    }
+}
+async function acquireManagedLspStateLock(worktree, owner) {
+    await fs.mkdir(worktree.stateRootPath, { recursive: true });
+    const lockPath = path.join(worktree.stateRootPath, "lsp.lock");
+    const metadataPath = path.join(lockPath, "metadata.json");
+    const startedAt = Date.now();
+    const recoveredReasons = [];
+    while (Date.now() - startedAt < LSP_STATE_LOCK_ACQUIRE_TIMEOUT_MS) {
+        const acquiredAt = new Date().toISOString();
+        const record = {
+            schemaVersion: LSP_STATE_LOCK_SCHEMA_VERSION,
+            lockId: randomUUID(),
+            owner,
+            pid: process.pid,
+            acquiredAt,
+            staleAfterMs: LSP_STATE_LOCK_STALE_AFTER_MS,
+            acquireTimeoutMs: LSP_STATE_LOCK_ACQUIRE_TIMEOUT_MS,
+        };
+        try {
+            await fs.mkdir(lockPath);
+            await fs.writeFile(metadataPath, JSON.stringify(record, null, 2), "utf8");
+            return {
+                lockId: record.lockId,
+                owner,
+                acquiredAt,
+                recoveredReasons: dedupe(recoveredReasons),
+            };
+        }
+        catch (error) {
+            const code = error.code;
+            if (code !== "EEXIST") {
+                throw error;
+            }
+            const staleReason = await detectManagedLspStateLockStaleReason(metadataPath);
+            if (staleReason !== null) {
+                recoveredReasons.push(staleReason);
+                await fs.rm(lockPath, { recursive: true, force: true });
+                continue;
+            }
+            await sleep(LSP_STATE_LOCK_RETRY_DELAY_MS);
+        }
+    }
+    throw new GdhManagedLspStateLockError("lsp_state_lock_timeout", ["lsp_state_lock_timeout"]);
+}
+async function detectManagedLspStateLockStaleReason(metadataPath) {
+    const content = await fs.readFile(metadataPath, "utf8").catch(() => null);
+    if (content === null) {
+        const lockStats = await fs.stat(path.dirname(metadataPath)).catch(() => null);
+        if (lockStats !== null && Date.now() - lockStats.mtimeMs >= LSP_STATE_LOCK_STALE_AFTER_MS) {
+            return "lsp_state_lock_metadata_invalid";
+        }
+        return null;
+    }
+    let metadata;
+    try {
+        metadata = JSON.parse(content);
+    }
+    catch {
+        return "lsp_state_lock_metadata_invalid";
+    }
+    if (metadata.schemaVersion !== LSP_STATE_LOCK_SCHEMA_VERSION ||
+        typeof metadata.pid !== "number" ||
+        typeof metadata.acquiredAt !== "string") {
+        return "lsp_state_lock_metadata_invalid";
+    }
+    if (!isPidAlive(metadata.pid)) {
+        return "lsp_state_lock_recovered_dead_pid";
+    }
+    const staleAfterMs = typeof metadata.staleAfterMs === "number"
+        ? metadata.staleAfterMs
+        : LSP_STATE_LOCK_STALE_AFTER_MS;
+    if (Date.now() - Date.parse(metadata.acquiredAt) >= staleAfterMs) {
+        return "lsp_state_lock_recovered_expired";
+    }
+    return null;
+}
+async function releaseManagedLspStateLock(worktree, lock) {
+    const lockPath = path.join(worktree.stateRootPath, "lsp.lock");
+    const metadataPath = path.join(lockPath, "metadata.json");
+    const metadata = await readJsonFile(metadataPath);
+    if (metadata?.lockId !== lock.lockId) {
+        return;
+    }
+    await fs.rm(lockPath, { recursive: true, force: true });
+}
 async function withLease(worktree, owner, callback) {
     await fs.mkdir(worktree.stateRootPath, { recursive: true });
     const leasesPath = path.join(worktree.stateRootPath, "lsp-leases.json");
@@ -353,7 +1138,7 @@ async function readPersistedInstance(worktree) {
     const instancePath = path.join(worktree.stateRootPath, "lsp-instance.json");
     const parsed = await readJsonFile(instancePath);
     if (parsed === null ||
-        parsed.schemaVersion !== LSP_INSTANCE_SCHEMA_VERSION ||
+        (parsed.schemaVersion !== 1 && parsed.schemaVersion !== LSP_INSTANCE_SCHEMA_VERSION) ||
         parsed.instance === undefined) {
         return null;
     }
@@ -363,12 +1148,79 @@ async function persistInstance(worktree, record) {
     await fs.mkdir(worktree.stateRootPath, { recursive: true });
     await fs.writeFile(path.join(worktree.stateRootPath, "lsp-instance.json"), JSON.stringify(record, null, 2), "utf8");
 }
-async function validatePersistedInstance(instance) {
+function validatePersistedInstanceIdentity(instance, expectedIdentity) {
+    const identity = instance.identity;
+    if (identity === undefined || identity === null) {
+        return {
+            reusable: false,
+            reason: "lsp_instance_identity_missing",
+            reasons: ["lsp_instance_identity_missing"],
+            rawPayload: {
+                reused: false,
+                instanceId: instance.instanceId,
+                reason: "lsp_instance_identity_missing",
+            },
+        };
+    }
+    const mismatchChecks = [
+        { field: "worktreeRootPath", reason: "lsp_instance_worktree_mismatch" },
+        { field: "projectRootPath", reason: "lsp_instance_project_mismatch" },
+        { field: "projectKey", reason: "lsp_instance_project_mismatch" },
+        { field: "launcher", reason: "lsp_instance_editor_mismatch" },
+        { field: "editorBinPath", reason: "lsp_instance_editor_mismatch" },
+        { field: "editorVersion", reason: "lsp_instance_editor_mismatch" },
+        { field: "lspSurfaceVersion", reason: "lsp_instance_surface_mismatch" },
+    ];
+    for (const check of mismatchChecks) {
+        if (identity[check.field] !== expectedIdentity[check.field]) {
+            return {
+                reusable: false,
+                reason: check.reason,
+                reasons: [check.reason],
+                rawPayload: {
+                    reused: false,
+                    instanceId: instance.instanceId,
+                    reason: check.reason,
+                    field: check.field,
+                    persisted: identity[check.field] ?? null,
+                    expected: expectedIdentity[check.field] ?? null,
+                    persistedIdentity: identity,
+                    expectedIdentity,
+                },
+            };
+        }
+    }
+    return { reusable: true };
+}
+async function validatePersistedInstance(instance, expectedIdentity) {
+    const identityValidation = validatePersistedInstanceIdentity(instance, expectedIdentity);
+    if (!identityValidation.reusable) {
+        return identityValidation;
+    }
     if (instance.launcher === "godot_editor") {
         if (instance.pid === null || !isPidAlive(instance.pid)) {
             return {
                 reusable: false,
                 reason: "lsp_process_not_running",
+                reasons: ["lsp_process_not_running"],
+                rawPayload: {
+                    launcher: "godot_editor",
+                    reused: false,
+                    pid: instance.pid,
+                    reason: "lsp_process_not_running",
+                },
+            };
+        }
+        const health = await checkManagedLspProtocolHealth({
+            port: instance.port,
+            projectPath: instance.projectPath,
+        });
+        if (!health.healthy) {
+            return {
+                reusable: false,
+                reason: "lsp_protocol_health_failed",
+                reasons: health.reasons,
+                rawPayload: health.rawPayload,
             };
         }
         return {
@@ -378,6 +1230,8 @@ async function validatePersistedInstance(instance) {
                 launcher: "godot_editor",
                 reused: true,
                 pid: instance.pid,
+                identity: instance.identity,
+                protocolHealth: health.rawPayload,
             },
         };
     }
@@ -386,21 +1240,77 @@ async function validatePersistedInstance(instance) {
         return {
             reusable: false,
             reason: "test_fake_lsp_registry_missing",
+            reasons: ["test_fake_lsp_registry_missing"],
+            rawPayload: {
+                launcher: "test_fake",
+                reused: false,
+                instanceId: instance.instanceId,
+                reason: "test_fake_lsp_registry_missing",
+            },
         };
     }
     return {
         reusable: true,
         trust: fake.trust,
-        rawPayload: fake.rawPayload,
+        rawPayload: {
+            ...(fake.rawPayload ?? {}),
+            identity: instance.identity,
+        },
     };
 }
-async function cleanupPersistedInstance(worktree, instance, reason) {
-    if (instance.launcher === "godot_editor" && instance.pid !== null) {
-        try {
-            process.kill(instance.pid, "SIGTERM");
-        }
-        catch {
-            // Best-effort cleanup only.
+function classifyManagedLspCleanupPolicy(instance) {
+    const idleAfterMs = resolveManagedLspIdleAfterMs();
+    const lastValidatedAt = typeof instance.lastValidatedAt === "string" ? instance.lastValidatedAt : null;
+    const lastValidatedMs = lastValidatedAt === null ? Number.NaN : Date.parse(lastValidatedAt);
+    if (!Number.isFinite(lastValidatedMs)) {
+        return {
+            reason: "lsp_instance_stale_timestamp",
+            reasons: ["lsp_instance_stale_timestamp"],
+            lastValidatedAt,
+            idleAfterMs,
+            elapsedMs: null,
+        };
+    }
+    const elapsedMs = Date.now() - lastValidatedMs;
+    if (elapsedMs >= idleAfterMs) {
+        return {
+            reason: "lsp_instance_idle",
+            reasons: ["lsp_instance_idle"],
+            lastValidatedAt,
+            idleAfterMs,
+            elapsedMs,
+        };
+    }
+    return null;
+}
+function resolveManagedLspIdleAfterMs() {
+    const configured = process.env["GDH_TEST_LSP_IDLE_AFTER_MS"] ?? process.env["GDH_MANAGED_LSP_IDLE_AFTER_MS"];
+    if (configured === undefined) {
+        return LSP_INSTANCE_IDLE_AFTER_MS;
+    }
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return LSP_INSTANCE_IDLE_AFTER_MS;
+    }
+    return parsed;
+}
+async function cleanupPersistedInstance(worktree, instance, reason, options = {}) {
+    const killProcess = options.killProcess ?? true;
+    let killedPid = false;
+    let killReason = null;
+    if (killProcess && instance.launcher === "godot_editor" && instance.pid !== null) {
+        const identityValidation = options.expectedIdentity === undefined
+            ? { reusable: false }
+            : validatePersistedInstanceIdentity(instance, options.expectedIdentity);
+        if (identityValidation.reusable) {
+            try {
+                process.kill(instance.pid, "SIGTERM");
+                killedPid = true;
+                killReason = reason;
+            }
+            catch {
+                // Best-effort cleanup only.
+            }
         }
     }
     if (instance.launcher === "test_fake") {
@@ -413,12 +1323,15 @@ async function cleanupPersistedInstance(worktree, instance, reason) {
         cleanedAt: new Date().toISOString(),
         reason,
         instanceId: instance.instanceId,
+        killedPid,
+        killReason,
     }, null, 2), "utf8");
+    return { killedPid, killReason };
 }
 async function launchManagedInstance(worktree, projectPath) {
     const testMode = process.env["GDH_TEST_LSP_MODE"];
     if (testMode) {
-        return launchTestFakeLsp(testMode);
+        return await launchTestFakeLsp(testMode, worktree, projectPath);
     }
     const godotBin = await resolveConfiguredGodotEditorBin({
         targetPath: worktree.rootPath,
@@ -428,10 +1341,25 @@ async function launchManagedInstance(worktree, projectPath) {
         return {
             unavailable: {
                 reason: "godot_editor_not_configured",
+                reasons: ["godot_editor_not_configured"],
                 summary: "authoring.lsp is unavailable because no machine-local Godot editor path is configured for this target.",
+                rawPayload: {
+                    launcher: "godot_editor",
+                    projectPath,
+                    reason: "godot_editor_not_configured",
+                },
             },
         };
     }
+    const version = await probeGodotEditorVersion(godotBin);
+    const identity = await createManagedLspInstanceIdentity({
+        worktree,
+        projectPath,
+        launcher: "godot_editor",
+        editorBinPath: godotBin,
+        editorVersion: version.version,
+        editorVersionReason: version.reason,
+    });
     const port = await allocateDynamicPort();
     const command = [
         godotBin,
@@ -447,7 +1375,30 @@ async function launchManagedInstance(worktree, projectPath) {
         stdio: "ignore",
         cwd: projectPath,
     });
-    const launchOutcome = await new Promise((resolve) => {
+    if (child.pid === undefined) {
+        return {
+            unavailable: {
+                reason: "godot_editor_launch_failed",
+                reasons: ["godot_editor_launch_failed"],
+                summary: "authoring.lsp could not launch the configured Godot editor.",
+                rawPayload: {
+                    launcher: "godot_editor",
+                    command,
+                    projectPath,
+                    identity,
+                    reason: "godot_editor_launch_failed",
+                },
+            },
+        };
+    }
+    const launchPayload = {
+        launcher: "godot_editor",
+        command,
+        pid: child.pid,
+        projectPath,
+        identity,
+    };
+    const launchFailure = new Promise((resolve) => {
         let settled = false;
         const settle = (result) => {
             if (!settled) {
@@ -457,25 +1408,73 @@ async function launchManagedInstance(worktree, projectPath) {
         };
         child.once("error", (error) => {
             settle({
-                ok: false,
+                failed: true,
                 reason: "godot_editor_launch_failed",
                 summary: `authoring.lsp could not launch the configured Godot editor: ${error.message}`,
+                rawPayload: {
+                    ...launchPayload,
+                    reason: "godot_editor_launch_failed",
+                    errorMessage: error.message,
+                },
             });
         });
-        setImmediate(() => {
+        child.once("exit", (code, signal) => {
             settle({
-                ok: true,
-                pid: child.pid ?? null,
+                failed: true,
+                reason: "godot_editor_exited_before_lsp_ready",
+                summary: `The configured Godot editor exited before authoring.lsp became protocol-ready (code ${code ?? "null"}, signal ${signal ?? "null"}).`,
+                rawPayload: {
+                    ...launchPayload,
+                    reason: "godot_editor_exited_before_lsp_ready",
+                    exitCode: code,
+                    signal,
+                },
             });
         });
     });
-    if (!launchOutcome.ok || launchOutcome.pid === null) {
+    const health = await Promise.race([
+        checkManagedLspProtocolHealth({ port, projectPath }),
+        launchFailure,
+    ]);
+    if ("failed" in health) {
+        if (health.failed) {
+            return {
+                unavailable: {
+                    reason: health.reason,
+                    reasons: [health.reason],
+                    summary: health.summary,
+                    rawPayload: health.rawPayload,
+                },
+            };
+        }
         return {
             unavailable: {
                 reason: "godot_editor_launch_failed",
-                summary: launchOutcome.ok === false
-                    ? launchOutcome.summary
-                    : "authoring.lsp could not launch the configured Godot editor.",
+                reasons: ["godot_editor_launch_failed"],
+                summary: "authoring.lsp could not launch the configured Godot editor.",
+                rawPayload: {
+                    ...launchPayload,
+                    reason: "godot_editor_launch_failed",
+                },
+            },
+        };
+    }
+    if (!health.healthy) {
+        try {
+            process.kill(child.pid, "SIGTERM");
+        }
+        catch {
+            // Best-effort cleanup only.
+        }
+        return {
+            unavailable: {
+                reason: health.reason,
+                reasons: health.reasons,
+                summary: health.summary,
+                rawPayload: {
+                    ...launchPayload,
+                    protocolHealth: health.rawPayload,
+                },
             },
         };
     }
@@ -484,29 +1483,160 @@ async function launchManagedInstance(worktree, projectPath) {
         instanceId: randomUUID(),
         launcher: "godot_editor",
         port,
-        pid: launchOutcome.pid,
+        pid: child.pid,
         command,
         trust: "trusted",
+        identity,
         validationMode: "unimplemented",
         diagnostics: [],
         rawPayload: {
-            launcher: "godot_editor",
-            command,
-            pid: launchOutcome.pid,
+            ...launchPayload,
+            protocolHealth: health.rawPayload,
+        },
+    };
+}
+async function checkManagedLspProtocolHealth(input) {
+    const startedAt = Date.now();
+    const totalTimeoutMs = input.totalTimeoutMs ?? resolveManagedLspHealthTotalTimeoutMs();
+    const connectTimeoutMs = input.connectTimeoutMs ?? resolveManagedLspHealthConnectTimeoutMs();
+    const requestTimeoutMs = input.requestTimeoutMs ?? resolveManagedLspHealthRequestTimeoutMs();
+    const deadline = startedAt + totalTimeoutMs;
+    let attempts = 0;
+    let lastFailure = null;
+    while (Date.now() < deadline) {
+        attempts += 1;
+        try {
+            const client = await connectGodotLspClient({
+                port: input.port,
+                connectTimeoutMs,
+                requestTimeoutMs,
+            });
+            try {
+                const initialize = await client.initialize({
+                    rootUri: pathToFileURL(input.projectPath).href,
+                });
+                await client.initialized();
+                await client.close();
+                return {
+                    healthy: true,
+                    rawPayload: {
+                        protocol: "lsp",
+                        initialized: true,
+                        port: input.port,
+                        attempts,
+                        elapsedMs: Date.now() - startedAt,
+                        totalTimeoutMs,
+                        connectTimeoutMs,
+                        requestTimeoutMs,
+                        serverInfo: initialize.serverInfo ?? null,
+                        capabilities: initialize.capabilities,
+                    },
+                };
+            }
+            catch (error) {
+                await client.close();
+                throw error;
+            }
+        }
+        catch (error) {
+            const coerced = coerceLspHealthFailure(error);
+            lastFailure = coerced;
+            if (!isRetryableLspHealthFailure(coerced.reason)) {
+                break;
+            }
+            const remainingMs = deadline - Date.now();
+            if (remainingMs <= 0) {
+                break;
+            }
+            await sleep(Math.min(MANAGED_LSP_HEALTH_RETRY_DELAY_MS, remainingMs));
+        }
+    }
+    const reason = lastFailure?.reason ?? "lsp_tcp_timeout";
+    return {
+        healthy: false,
+        reason: "lsp_protocol_health_failed",
+        reasons: dedupe(["lsp_protocol_health_failed", reason]),
+        summary: `authoring.lsp did not become protocol-ready: ${lastFailure?.message ?? "timed out waiting for the LSP endpoint."}`,
+        rawPayload: {
+            protocol: "lsp",
+            initialized: false,
+            port: input.port,
+            attempts,
+            elapsedMs: Date.now() - startedAt,
+            totalTimeoutMs,
+            connectTimeoutMs,
+            requestTimeoutMs,
+            failureReason: reason,
+            failureDetails: lastFailure?.details ?? {},
         },
     };
 }
-async function launchTestFakeLsp(mode) {
+function resolveManagedLspHealthTotalTimeoutMs() {
+    return resolveManagedLspTimeoutMs("GDH_MANAGED_LSP_HEALTH_TOTAL_TIMEOUT_MS", MANAGED_LSP_HEALTH_TOTAL_TIMEOUT_MS);
+}
+function resolveManagedLspHealthConnectTimeoutMs() {
+    return resolveManagedLspTimeoutMs("GDH_MANAGED_LSP_HEALTH_CONNECT_TIMEOUT_MS", MANAGED_LSP_HEALTH_CONNECT_TIMEOUT_MS);
+}
+function resolveManagedLspHealthRequestTimeoutMs() {
+    return resolveManagedLspTimeoutMs("GDH_MANAGED_LSP_HEALTH_REQUEST_TIMEOUT_MS", MANAGED_LSP_HEALTH_REQUEST_TIMEOUT_MS);
+}
+function resolveManagedLspTimeoutMs(envName, fallback) {
+    const configured = process.env[envName];
+    if (configured === undefined) {
+        return fallback;
+    }
+    const parsed = Number(configured);
+    if (!Number.isFinite(parsed) || parsed < 0) {
+        return fallback;
+    }
+    return parsed;
+}
+function coerceLspHealthFailure(error) {
+    if (error instanceof GdhLspClientError) {
+        return {
+            reason: error.reason,
+            message: error.message,
+            details: error.details,
+        };
+    }
+    return {
+        reason: "lsp_connection_closed",
+        message: error instanceof Error ? error.message : "LSP health check failed.",
+        details: {},
+    };
+}
+function isRetryableLspHealthFailure(reason) {
+    return (reason === "lsp_tcp_connection_failed" ||
+        reason === "lsp_tcp_timeout" ||
+        reason === "lsp_initialize_timeout");
+}
+async function sleep(ms) {
+    await new Promise((resolve) => setTimeout(resolve, ms));
+}
+async function launchTestFakeLsp(mode, worktree, projectPath) {
     const normalizedMode = normalizeTestMode(mode);
     const port = await allocateDynamicPort();
     const instanceId = randomUUID();
+    const identity = await createManagedLspInstanceIdentity({
+        worktree,
+        projectPath,
+        launcher: "test_fake",
+        editorBinPath: `test_fake:${normalizedMode}`,
+        editorVersion: normalizedMode,
+        editorVersionReason: null,
+    });
     const diagnostics = normalizedMode === "diagnostics"
         ? [
             {
                 message: "Fake LSP reported a syntax error for integration coverage.",
-                path: "scenes/main.tscn",
+                path: "scripts/fake.gd",
+                line: null,
+                column: null,
+                endLine: null,
+                endColumn: null,
                 severity: "warning",
                 source: "godot_lsp",
+                raw: null,
             },
         ]
         : [];
@@ -528,11 +1658,13 @@ async function launchTestFakeLsp(mode) {
         pid: null,
         command: ["test_fake_lsp", normalizedMode],
         trust: normalizedMode === "degraded" ? "degraded" : "trusted",
+        identity,
         validationMode: normalizedMode,
         diagnostics,
         rawPayload: {
             ...rawPayload,
             testInstanceId: instanceId,
+            identity,
         },
     };
 }
@@ -542,6 +1674,40 @@ function normalizeTestMode(mode) {
     }
     return "passed";
 }
+function createLifecycleCommandResult(input) {
+    return {
+        targetPath: input.targetPath,
+        capability: "authoring.lsp",
+        command: input.command,
+        status: input.status,
+        summary: input.summary,
+        reasons: dedupe(input.reasons),
+        worktree: input.worktree,
+        lifecycle: {
+            status: input.status,
+            instanceId: input.instance?.instanceId ?? null,
+            launcher: input.instance?.launcher ?? null,
+            pid: input.instance?.pid ?? null,
+            port: input.instance?.port ?? null,
+        },
+        transport: {
+            status: input.transportStatus,
+            reasons: dedupe(input.transportReasons),
+            rawPayload: input.transportRawPayload,
+        },
+        diagnostics: {
+            status: "unimplemented",
+            summary: "Real Godot diagnostic collection remains unavailable until GDH opens files and consumes publishDiagnostics.",
+        },
+        cleanup: {
+            status: input.cleanupStatus,
+            reason: input.cleanupReason,
+            killedPid: input.killedPid,
+        },
+        recommendations: input.recommendations,
+        statusResult: input.statusResult,
+    };
+}
 function createStatusResult(input) {
     return {
         targetPath: input.targetPath,
@@ -593,7 +1759,7 @@ function createUnavailableStatus(input) {
             inventoryObservedAt: input.inventoryObservedAt,
             projectConfigPresent: input.projectConfigPresent,
             stateRootPath: input.worktree.stateRootPath,
-            rawPayload: null,
+            rawPayload: input.rawPayload ?? null,
         },
     };
 }