@calltelemetry/ct-lab-mcp 0.8.2 → 0.8.3

package/dist/src/slot/manager.js

@@ -16,7 +16,12 @@ export * from "./types.js";
  */
 export function calculatePureCapacity(host) {
     if (host.maxSlots !== undefined) {
-        return host.maxSlots;
+        if (host.hypervisorType === "esxi" && host.maxSlots === 0 && host.allowEsxiSlots) {
+            // Allow dynamic calculation below for ESXi when unlocked
+        }
+        else {
+            return host.maxSlots;
+        }
     }
     const slotSize = host.slotSizeMb || 8192;
     if (host.totalMemoryMb !== undefined) {
@@ -112,12 +117,14 @@ export class SlotManager {
     hypervisorManager;
     guardrailEngine;
     telemetry;
+    allowEsxiSlots;
     constructor(options = {}) {
         this.defaultDurationMinutes = options.defaultDurationMinutes ?? 120;
         this.proxmoxManager = options.proxmoxManager;
         this.hypervisorManager = options.hypervisorManager;
         this.guardrailEngine = options.guardrailEngine || defaultSafetyGuardrailEngine;
         this.telemetry = options.telemetryRegistry || telemetry;
+        this.allowEsxiSlots = options.allowEsxiSlots ?? (process.env.ALLOW_ESXI_SLOTS === "true");
         const hostConfigs = options.hosts && options.hosts.length > 0
             ? options.hosts
             : [...DEFAULT_HOST_CONFIGS];
@@ -148,7 +155,14 @@ export class SlotManager {
      */
     registerHost(host) {
         const normalizedId = this.normalizeHostId(host.hostId);
-        const pureSlots = calculatePureCapacity(host);
+        let pureSlots = calculatePureCapacity({
+            ...host,
+            allowEsxiSlots: this.allowEsxiSlots
+        });
+        if (normalizedId.startsWith("esxi") && this.allowEsxiSlots && host.maxSlots === 0) {
+            const usableMb = Math.max(0, host.totalMemoryMb - (host.reservedHeadroomMb || 0));
+            pureSlots = Math.floor(usableMb / (host.slotSizeMb || 8192));
+        }
         const normalizedHost = {
             ...host,
             hostId: normalizedId,
@@ -282,20 +296,24 @@ export class SlotManager {
      * Atomically claims an 8GB appliance slot.
      */
     async claimSlot(request) {
-        return this.mutex.runExclusive(async () => {
-            // 1. Reclaim any expired leases first
-            this.sweepExpiredSlotsInternal();
-            const tagInput = request.tag || request.linearIssue || request.requester;
-            if (!tagInput || typeof tagInput !== "string" || tagInput.trim() === "") {
-                throw new InvalidSlotOperationError("A valid non-empty 'tag', 'linearIssue', or 'requester' is required to claim a slot.");
-            }
-            const durationMinutes = request.durationMinutes ?? request.ttlMinutes ?? (request.ttlSeconds ? Math.ceil(request.ttlSeconds / 60) : this.defaultDurationMinutes);
-            if (durationMinutes < 1 || durationMinutes > 1440) {
-                throw new InvalidSlotOperationError(`Claim duration must be between 1 and 1440 minutes (requested: ${durationMinutes}).`);
-            }
-            const rawRequestedHost = request.host || request.targetHost;
-            const requestedHost = rawRequestedHost ? this.normalizeHostId(rawRequestedHost) : undefined;
-            const hypervisorTypePref = request.hypervisorType || "any";
+        return this.mutex.runExclusive(async () => this.claimSlotInternal(request));
+    }
+    async claimSlotInternal(request) {
+        // 1. Reclaim any expired leases first
+        this.sweepExpiredSlotsInternal();
+        const tagInput = request.tag || request.linearIssue || request.requester;
+        if (!tagInput || typeof tagInput !== "string" || tagInput.trim() === "") {
+            throw new InvalidSlotOperationError("A valid non-empty 'tag', 'linearIssue', or 'requester' is required to claim a slot.");
+        }
+        const durationMinutes = request.durationMinutes ?? request.ttlMinutes ?? (request.ttlSeconds ? Math.ceil(request.ttlSeconds / 60) : this.defaultDurationMinutes);
+        if (durationMinutes < 1 || durationMinutes > 1440) {
+            throw new InvalidSlotOperationError(`Claim duration must be between 1 and 1440 minutes (requested: ${durationMinutes}).`);
+        }
+        const rawRequestedHost = request.host || request.targetHost;
+        const requestedHost = rawRequestedHost ? this.normalizeHostId(rawRequestedHost) : undefined;
+        const hypervisorTypePref = request.hypervisorType || "any";
+        const allowEsxi = request.allowEsxiSlots ?? this.allowEsxiSlots;
+        if (!allowEsxi) {
             // 1. Explicit ESXi Host Rejection
             if (requestedHost &&
                 (requestedHost === "esxi-intel-192-168-123-176" ||
@@ -307,213 +325,246 @@ export class SlotManager {
             if (hypervisorTypePref === "esxi") {
                 throw new HypervisorSlotUnsupportedError("Slot leasing is not supported on ESXi hypervisors. Appliance slots are exclusively managed on Proxmox VE (proxmox-lab and proxmox-mini).", requestedHost, "esxi");
             }
-            let targetSlot;
-            if (requestedHost && requestedHost !== "auto") {
-                // Specific host claim
-                const hostConfig = this.hosts.get(requestedHost);
-                if (!hostConfig) {
-                    const validHosts = Array.from(this.hosts.keys()).join(", ");
-                    throw new InvalidSlotOperationError(`Unknown host '${requestedHost}' for slot allocation. Available: [${validHosts}]`);
+        }
+        let targetSlot;
+        if (requestedHost && requestedHost !== "auto") {
+            // Specific host claim
+            const hostConfig = this.hosts.get(requestedHost);
+            if (!hostConfig) {
+                const validHosts = Array.from(this.hosts.keys()).join(", ");
+                throw new InvalidSlotOperationError(`Unknown host '${requestedHost}' for slot allocation. Available: [${validHosts}]`);
+            }
+            // ESXi Datastore check (>= 10GB free required)
+            if (hostConfig.hypervisorType === "esxi") {
+                const freeDisk = hostConfig.freeDiskGb ?? 100;
+                if (freeDisk < 10) {
+                    throw new DatastoreCapacityExceededError(requestedHost, 10, freeDisk);
                 }
-                // ESXi Datastore check (>= 10GB free required)
-                if (hostConfig.hypervisorType === "esxi") {
-                    const freeDisk = hostConfig.freeDiskGb ?? 100;
-                    if (freeDisk < 10) {
-                        throw new DatastoreCapacityExceededError(requestedHost, 10, freeDisk);
-                    }
+            }
+            const hostSlots = Array.from(this.slots.values())
+                .filter((s) => s.hostId === requestedHost)
+                .sort((a, b) => a.slotIndex - b.slotIndex);
+            let availableSlot = hostSlots.find((s) => s.status === "AVAILABLE");
+            // Dynamic slot expansion when box pure capacity exceeds pre-allocated slots
+            if (!availableSlot) {
+                const pureSlots = calculatePureCapacity(hostConfig);
+                if (hostSlots.length < pureSlots) {
+                    const nextIndex = hostSlots.length + 1;
+                    const slotId = `slot-${requestedHost}-${nextIndex}`;
+                    availableSlot = {
+                        slotId,
+                        hostId: requestedHost,
+                        hostName: hostConfig.name,
+                        hypervisorType: hostConfig.hypervisorType,
+                        slotIndex: nextIndex,
+                        memoryMb: hostConfig.slotSizeMb || 8192,
+                        allocatedMemoryMb: hostConfig.slotSizeMb || 8192,
+                        allocatedMemoryBytes: (hostConfig.slotSizeMb || 8192) * 1024 * 1024,
+                        status: "AVAILABLE",
+                        claimId: null,
+                        claimedAt: null,
+                        expiresAt: null,
+                        durationMinutes: null,
+                        ttlMinutes: null,
+                        ttlSeconds: null,
+                        tag: null,
+                        label: null,
+                        workloadType: null,
+                        targetVersion: null,
+                        branch: null,
+                        customTags: [],
+                        requester: null,
+                        linearIssue: null,
+                        sessionId: null,
+                        purpose: null,
+                        vmId: null,
+                        vmName: null,
+                        metadata: {}
+                    };
+                    this.slots.set(slotId, availableSlot);
+                    hostSlots.push(availableSlot);
                 }
-                const hostSlots = Array.from(this.slots.values())
-                    .filter((s) => s.hostId === requestedHost)
-                    .sort((a, b) => a.slotIndex - b.slotIndex);
-                let availableSlot = hostSlots.find((s) => s.status === "AVAILABLE");
-                // Dynamic slot expansion when box pure capacity exceeds pre-allocated slots
-                if (!availableSlot) {
-                    const pureSlots = calculatePureCapacity(hostConfig);
-                    if (hostSlots.length < pureSlots) {
-                        const nextIndex = hostSlots.length + 1;
-                        const slotId = `slot-${requestedHost}-${nextIndex}`;
-                        availableSlot = {
-                            slotId,
-                            hostId: requestedHost,
-                            hostName: hostConfig.name,
-                            hypervisorType: hostConfig.hypervisorType,
-                            slotIndex: nextIndex,
-                            memoryMb: hostConfig.slotSizeMb || 8192,
-                            allocatedMemoryMb: hostConfig.slotSizeMb || 8192,
-                            allocatedMemoryBytes: (hostConfig.slotSizeMb || 8192) * 1024 * 1024,
-                            status: "AVAILABLE",
-                            claimId: null,
-                            claimedAt: null,
-                            expiresAt: null,
-                            durationMinutes: null,
-                            ttlMinutes: null,
-                            ttlSeconds: null,
-                            tag: null,
-                            label: null,
-                            workloadType: null,
-                            targetVersion: null,
-                            branch: null,
-                            customTags: [],
-                            requester: null,
-                            linearIssue: null,
-                            sessionId: null,
-                            purpose: null,
-                            vmId: null,
-                            vmName: null,
-                            metadata: {}
-                        };
-                        this.slots.set(slotId, availableSlot);
-                        hostSlots.push(availableSlot);
-                    }
+            }
+            if (!availableSlot && request.purgeIfFull) {
+                const purgeRes = await this.purgeSlotsInternal({
+                    host: requestedHost,
+                    destroyVms: true,
+                    includeOrphans: true,
+                    dryRun: false
+                });
+                if (purgeRes.purgedSlotsCount > 0 || purgeRes.destroyedVmsCount > 0) {
+                    const recheckedSlots = Array.from(this.slots.values())
+                        .filter((s) => s.hostId === requestedHost)
+                        .sort((a, b) => a.slotIndex - b.slotIndex);
+                    availableSlot = recheckedSlots.find((s) => s.status === "AVAILABLE");
                 }
-                if (!availableSlot) {
-                    const allocatedCount = hostSlots.filter((s) => s.status === "CLAIMED" || s.status === "active").length;
-                    const hostLimit = hostConfig.maxSlots ?? calculatePureCapacity(hostConfig);
-                    if (requestedHost === "proxmox-lab") {
-                        throw new CapacityExceededError(`Host 'proxmox-lab' has reached its hard quota limit of 2 concurrent 8GB slots (16GB allocated). 16GB is strictly reserved for CUCM and core lab infrastructure.`, "proxmox-lab", hostLimit, allocatedCount);
-                    }
-                    else if (requestedHost === "proxmox-mini") {
-                        throw new CapacityExceededError(`Host 'proxmox-mini' has reached its hard quota limit of 4 concurrent 8GB slots (32GB allocated).`, "proxmox-mini", hostLimit, allocatedCount);
-                    }
-                    else {
-                        throw new CapacityExceededError(`Host '${requestedHost}' has reached its hard quota limit of ${hostLimit} concurrent slots.`, requestedHost, hostLimit, allocatedCount);
-                    }
+            }
+            if (!availableSlot) {
+                const allocatedCount = hostSlots.filter((s) => s.status === "CLAIMED" || s.status === "active").length;
+                const hostLimit = hostConfig.maxSlots ?? calculatePureCapacity(hostConfig);
+                if (requestedHost === "proxmox-lab") {
+                    throw new CapacityExceededError(`Host 'proxmox-lab' has reached its hard quota limit of 2 concurrent 8GB slots (16GB allocated). 16GB is strictly reserved for CUCM and core lab infrastructure.`, "proxmox-lab", hostLimit, allocatedCount);
+                }
+                else if (requestedHost === "proxmox-mini") {
+                    throw new CapacityExceededError(`Host 'proxmox-mini' has reached its hard quota limit of 4 concurrent 8GB slots (32GB allocated).`, "proxmox-mini", hostLimit, allocatedCount);
+                }
+                else {
+                    throw new CapacityExceededError(`Host '${requestedHost}' has reached its hard quota limit of ${hostLimit} concurrent slots.`, requestedHost, hostLimit, allocatedCount);
                 }
-                targetSlot = availableSlot;
             }
-            else {
-                // Homogeneous-fleet auto-placement. Every eligible Proxmox host is a
-                // peer at the request boundary; production uses system randomness,
-                // while tests may supply an explicit seed for reproducible placement.
-                // Filter candidate hosts based on hypervisor preference (excluding ESXi and 0-capacity hosts)
-                const candidateHostConfigs = Array.from(this.hosts.values()).filter((h) => {
-                    const pureSlots = calculatePureCapacity(h);
-                    if (h.hypervisorType === "esxi" || pureSlots === 0)
-                        return false;
-                    if (hypervisorTypePref === "proxmox" && h.hypervisorType !== "proxmox")
-                        return false;
-                    return true;
-                });
-                // Evaluate available slots and datastore health per host
-                const hostStats = candidateHostConfigs.map((h) => {
-                    const hostSlots = Array.from(this.slots.values()).filter((s) => s.hostId === h.hostId);
-                    const availableSlots = hostSlots.filter((s) => s.status === "AVAILABLE").length;
-                    const freeDiskGb = h.freeDiskGb ?? 100;
-                    const datastoreOk = h.hypervisorType !== "esxi" || freeDiskGb >= 10;
-                    return { host: h, availableSlots, hostSlots, datastoreOk };
+            targetSlot = availableSlot;
+        }
+        else {
+            // Homogeneous-fleet auto-placement. Every eligible host is a
+            // peer at the request boundary; production uses system randomness,
+            // while tests may supply an explicit seed for reproducible placement.
+            // Filter candidate hosts based on hypervisor preference (excluding ESXi unless allowEsxi)
+            const candidateHostConfigs = Array.from(this.hosts.values()).filter((h) => {
+                const pureSlots = calculatePureCapacity({ ...h, allowEsxiSlots: allowEsxi });
+                if (h.hypervisorType === "esxi" && !allowEsxi)
+                    return false;
+                if (pureSlots === 0 && (!allowEsxi || h.hypervisorType !== "esxi"))
+                    return false;
+                if (hypervisorTypePref === "proxmox" && h.hypervisorType !== "proxmox")
+                    return false;
+                if (hypervisorTypePref === "esxi" && h.hypervisorType !== "esxi")
+                    return false;
+                return true;
+            });
+            // Evaluate available slots and datastore health per host
+            const hostStats = candidateHostConfigs.map((h) => {
+                const hostSlots = Array.from(this.slots.values()).filter((s) => s.hostId === h.hostId);
+                const availableSlots = hostSlots.filter((s) => s.status === "AVAILABLE").length;
+                const freeDiskGb = h.freeDiskGb ?? 100;
+                const datastoreOk = h.hypervisorType !== "esxi" || freeDiskGb >= 10;
+                return { host: h, availableSlots, hostSlots, datastoreOk };
+            });
+            let totalAvailable = hostStats.reduce((sum, h) => sum + (h.datastoreOk ? h.availableSlots : 0), 0);
+            if (totalAvailable <= 0 && request.purgeIfFull) {
+                const purgeRes = await this.purgeSlotsInternal({
+                    destroyVms: true,
+                    includeOrphans: true,
+                    dryRun: false
                 });
-                const totalAvailable = hostStats.reduce((sum, h) => sum + (h.datastoreOk ? h.availableSlots : 0), 0);
-                if (totalAvailable <= 0) {
-                    if (hypervisorTypePref === "proxmox") {
-                        throw new CapacityExceededError("All Proxmox cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", "proxmox-cluster", 6, 6);
+                if (purgeRes.purgedSlotsCount > 0 || purgeRes.destroyedVmsCount > 0) {
+                    for (const h of hostStats) {
+                        const hSlots = Array.from(this.slots.values()).filter((s) => s.hostId === h.host.hostId);
+                        h.availableSlots = hSlots.filter((s) => s.status === "AVAILABLE").length;
+                        h.hostSlots = hSlots;
                     }
-                    throw new GlobalCapacityExceededError("All 6 cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", 6, 6);
+                    totalAvailable = hostStats.reduce((sum, h) => sum + (h.datastoreOk ? h.availableSlots : 0), 0);
                 }
-                const validCandidates = hostStats
-                    .filter((h) => h.datastoreOk && h.availableSlots > 0)
-                    .sort((a, b) => a.host.hostId.localeCompare(b.host.hostId));
-                const candidateIndex = request.placementSeed
-                    ? createHash("sha256")
-                        .update(request.placementSeed)
-                        .digest()
-                        .readUInt32BE(0) % validCandidates.length
-                    : randomInt(validCandidates.length);
-                const winningHostStat = validCandidates[candidateIndex];
-                if (!winningHostStat) {
-                    throw new GlobalCapacityExceededError("All 6 cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", 6, 6);
+            }
+            if (totalAvailable <= 0) {
+                if (hypervisorTypePref === "proxmox") {
+                    throw new CapacityExceededError("All Proxmox cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", "proxmox-cluster", 6, 6);
                 }
-                const availableSlotsOnWinner = winningHostStat.hostSlots
-                    .filter((s) => s.status === "AVAILABLE")
-                    .sort((a, b) => a.slotIndex - b.slotIndex);
-                targetSlot = availableSlotsOnWinner[0];
+                throw new GlobalCapacityExceededError("All 6 cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", 6, 6);
             }
-            if (!targetSlot) {
+            const validCandidates = hostStats
+                .filter((h) => h.datastoreOk && h.availableSlots > 0)
+                .sort((a, b) => a.host.hostId.localeCompare(b.host.hostId));
+            const candidateIndex = request.placementSeed
+                ? createHash("sha256")
+                    .update(request.placementSeed)
+                    .digest()
+                    .readUInt32BE(0) % validCandidates.length
+                : randomInt(validCandidates.length);
+            const winningHostStat = validCandidates[candidateIndex];
+            if (!winningHostStat) {
                 throw new GlobalCapacityExceededError("All 6 cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", 6, 6);
             }
-            // Assign claim details
-            const claimId = `claim-${randomUUID().substring(0, 8)}`;
-            const now = new Date();
-            const claimedAt = now.toISOString();
-            const expiresAt = new Date(now.getTime() + durationMinutes * 60 * 1000).toISOString();
-            const linearIssue = request.linearIssue || (request.tag && request.tag.startsWith("CTUAT-") ? request.tag : null);
-            // Normalize custom tags
-            const customTags = [
-                ...this.normalizeTagsArray(request.customTags),
-                ...this.normalizeTagsArray(request.tags)
-            ];
-            // Deduplicate tags
-            const uniqueTags = Array.from(new Set(customTags));
-            // Auto-assign human readable label if not provided
-            const label = request.label || (linearIssue
-                ? `[${linearIssue}] ${request.workloadType || "workload"}: Slot ${targetSlot.slotIndex}`
-                : request.purpose
-                    ? `${request.purpose} (Slot ${targetSlot.slotIndex})`
-                    : `${request.tag || tagInput} Lease`);
-            targetSlot.status = "CLAIMED";
-            targetSlot.claimId = claimId;
-            targetSlot.claimedAt = claimedAt;
-            targetSlot.expiresAt = expiresAt;
-            targetSlot.durationMinutes = durationMinutes;
-            targetSlot.ttlMinutes = durationMinutes;
-            targetSlot.ttlSeconds = durationMinutes * 60;
-            targetSlot.tag = (request.tag || tagInput).trim();
-            targetSlot.label = label;
-            targetSlot.workloadType = request.workloadType || null;
-            targetSlot.targetVersion = request.targetVersion || null;
-            targetSlot.branch = request.branch || null;
-            targetSlot.customTags = uniqueTags;
-            targetSlot.requester = request.requester || request.tag || null;
-            targetSlot.linearIssue = linearIssue;
-            targetSlot.sessionId = request.sessionId || null;
-            targetSlot.purpose = request.purpose || null;
-            targetSlot.metadata = request.metadata || {};
-            // Emit audit telemetry
-            this.telemetry.emit({
-                event: "slot.claim",
-                actor: targetSlot.requester || targetSlot.sessionId || "unknown",
-                status: "success",
-                linearIssue: linearIssue || undefined,
-                slotId: targetSlot.slotId,
-                claimId,
-                hostId: targetSlot.hostId,
-                hypervisorType: targetSlot.hypervisorType,
-                metadata: {
-                    label: targetSlot.label,
-                    workloadType: targetSlot.workloadType,
-                    targetVersion: targetSlot.targetVersion,
-                    branch: targetSlot.branch,
-                    durationMinutes,
-                    expiresAt
-                }
-            });
-            return {
-                claimId,
-                slotId: targetSlot.slotId,
-                hostId: targetSlot.hostId,
-                hostName: targetSlot.hostName || targetSlot.hostId,
-                hypervisorType: targetSlot.hypervisorType || (targetSlot.hostId.startsWith("esxi") ? "esxi" : "proxmox"),
-                slotIndex: targetSlot.slotIndex,
-                memoryMb: targetSlot.memoryMb,
-                allocatedMemoryMb: targetSlot.memoryMb,
-                allocatedMemoryBytes: targetSlot.memoryMb * 1024 * 1024,
-                tag: targetSlot.tag,
-                label: targetSlot.label || undefined,
-                workloadType: targetSlot.workloadType || undefined,
-                targetVersion: targetSlot.targetVersion || undefined,
-                branch: targetSlot.branch || undefined,
-                customTags: targetSlot.customTags.length > 0 ? targetSlot.customTags : undefined,
-                requester: targetSlot.requester || undefined,
-                linearIssue: targetSlot.linearIssue || undefined,
-                claimedAt,
-                expiresAt,
+            const availableSlotsOnWinner = winningHostStat.hostSlots
+                .filter((s) => s.status === "AVAILABLE")
+                .sort((a, b) => a.slotIndex - b.slotIndex);
+            targetSlot = availableSlotsOnWinner[0];
+        }
+        if (!targetSlot) {
+            throw new GlobalCapacityExceededError("All 6 cluster slots are currently allocated (2/2 on proxmox-lab, 4/4 on proxmox-mini).", 6, 6);
+        }
+        // Assign claim details
+        const claimId = `claim-${randomUUID().substring(0, 8)}`;
+        const now = new Date();
+        const claimedAt = now.toISOString();
+        const expiresAt = new Date(now.getTime() + durationMinutes * 60 * 1000).toISOString();
+        const linearIssue = request.linearIssue || (request.tag && request.tag.startsWith("CTUAT-") ? request.tag : null);
+        // Normalize custom tags
+        const customTags = [
+            ...this.normalizeTagsArray(request.customTags),
+            ...this.normalizeTagsArray(request.tags)
+        ];
+        // Deduplicate tags
+        const uniqueTags = Array.from(new Set(customTags));
+        // Auto-assign human readable label if not provided
+        const label = request.label || (linearIssue
+            ? `[${linearIssue}] ${request.workloadType || "workload"}: Slot ${targetSlot.slotIndex}`
+            : request.purpose
+                ? `${request.purpose} (Slot ${targetSlot.slotIndex})`
+                : `${request.tag || tagInput} Lease`);
+        targetSlot.status = "CLAIMED";
+        targetSlot.claimId = claimId;
+        targetSlot.claimedAt = claimedAt;
+        targetSlot.expiresAt = expiresAt;
+        targetSlot.durationMinutes = durationMinutes;
+        targetSlot.ttlMinutes = durationMinutes;
+        targetSlot.ttlSeconds = durationMinutes * 60;
+        targetSlot.tag = (request.tag || tagInput).trim();
+        targetSlot.label = label;
+        targetSlot.workloadType = request.workloadType || null;
+        targetSlot.targetVersion = request.targetVersion || null;
+        targetSlot.branch = request.branch || null;
+        targetSlot.customTags = uniqueTags;
+        targetSlot.requester = request.requester || request.tag || null;
+        targetSlot.linearIssue = linearIssue;
+        targetSlot.sessionId = request.sessionId || null;
+        targetSlot.purpose = request.purpose || null;
+        targetSlot.metadata = request.metadata || {};
+        // Emit audit telemetry
+        this.telemetry.emit({
+            event: "slot.claim",
+            actor: targetSlot.requester || targetSlot.sessionId || "unknown",
+            status: "success",
+            linearIssue: linearIssue || undefined,
+            slotId: targetSlot.slotId,
+            claimId,
+            hostId: targetSlot.hostId,
+            hypervisorType: targetSlot.hypervisorType,
+            metadata: {
+                label: targetSlot.label,
+                workloadType: targetSlot.workloadType,
+                targetVersion: targetSlot.targetVersion,
+                branch: targetSlot.branch,
                 durationMinutes,
-                ttlMinutes: durationMinutes,
-                ttlSeconds: durationMinutes * 60,
-                status: "active",
-                purpose: targetSlot.purpose || undefined,
-                sessionId: targetSlot.sessionId || undefined
-            };
+                expiresAt
+            }
         });
+        return {
+            claimId,
+            slotId: targetSlot.slotId,
+            hostId: targetSlot.hostId,
+            hostName: targetSlot.hostName || targetSlot.hostId,
+            hypervisorType: targetSlot.hypervisorType || (targetSlot.hostId.startsWith("esxi") ? "esxi" : "proxmox"),
+            slotIndex: targetSlot.slotIndex,
+            memoryMb: targetSlot.memoryMb,
+            allocatedMemoryMb: targetSlot.memoryMb,
+            allocatedMemoryBytes: targetSlot.memoryMb * 1024 * 1024,
+            tag: targetSlot.tag,
+            label: targetSlot.label || undefined,
+            workloadType: targetSlot.workloadType || undefined,
+            targetVersion: targetSlot.targetVersion || undefined,
+            branch: targetSlot.branch || undefined,
+            customTags: targetSlot.customTags.length > 0 ? targetSlot.customTags : undefined,
+            requester: targetSlot.requester || undefined,
+            linearIssue: targetSlot.linearIssue || undefined,
+            claimedAt,
+            expiresAt,
+            durationMinutes,
+            ttlMinutes: durationMinutes,
+            ttlSeconds: durationMinutes * 60,
+            status: "active",
+            purpose: targetSlot.purpose || undefined,
+            sessionId: targetSlot.sessionId || undefined
+        };
     }
     /**
      * Releases one or more slots matching claimId, tag, slotId, requester, or linearIssue.
@@ -971,149 +1022,164 @@ export class SlotManager {
      * Gated by SafetyGuardrailEngine non-bypassable protections.
      */
     async purgeSlots(options = {}) {
-        return this.mutex.runExclusive(async () => {
-            const now = Date.now();
-            const dryRun = options.dryRun ?? false;
-            const destroyVms = options.destroyVms ?? true;
-            const force = options.force ?? false;
-            const includeOrphans = options.includeOrphans ?? false;
-            const targetHost = options.host && options.host !== "all" ? this.normalizeHostId(options.host) : undefined;
-            const targetHypervisor = options.hypervisorType && options.hypervisorType !== "all" && options.hypervisorType !== "any"
-                ? options.hypervisorType
-                : undefined;
-            const matchingSlots = [];
-            const reasons = new Map();
-            for (const slot of this.slots.values()) {
-                if (slot.status !== "CLAIMED" && slot.status !== "active" && slot.status !== "EXPIRED")
-                    continue;
-                if (targetHost && slot.hostId !== targetHost)
-                    continue;
-                if (targetHypervisor && slot.hypervisorType !== targetHypervisor)
-                    continue;
-                let shouldPurge = false;
-                let reason = "manual_purge";
-                const expiresTime = slot.expiresAt ? new Date(slot.expiresAt).getTime() : 0;
-                const claimedTime = slot.claimedAt ? new Date(slot.claimedAt).getTime() : 0;
-                const isExpired = expiresTime > 0 && expiresTime <= now;
-                if (options.linearIssue) {
-                    const matchesLinear = slot.linearIssue === options.linearIssue || slot.tag === options.linearIssue;
-                    if (matchesLinear) {
-                        shouldPurge = true;
-                        reason = isExpired ? "expired" : "linear_match";
-                    }
-                }
-                else if (options.olderThanMinutes !== undefined) {
-                    const ageMinutes = (now - claimedTime) / (60 * 1000);
-                    if (ageMinutes >= options.olderThanMinutes || isExpired) {
-                        shouldPurge = true;
-                        reason = isExpired ? "expired" : "older_than_threshold";
-                    }
-                }
-                else if (isExpired) {
+        return this.mutex.runExclusive(async () => this.purgeSlotsInternal(options));
+    }
+    async purgeSlotsInternal(options = {}) {
+        const now = Date.now();
+        const dryRun = options.dryRun ?? false;
+        const destroyVms = options.destroyVms ?? true;
+        const force = options.force ?? false;
+        const includeOrphans = options.includeOrphans ?? false;
+        const targetHost = options.host && options.host !== "all" ? this.normalizeHostId(options.host) : undefined;
+        const targetHypervisor = options.hypervisorType && options.hypervisorType !== "all" && options.hypervisorType !== "any"
+            ? options.hypervisorType
+            : undefined;
+        const matchingSlots = [];
+        const reasons = new Map();
+        for (const slot of this.slots.values()) {
+            if (slot.status !== "CLAIMED" && slot.status !== "active" && slot.status !== "EXPIRED")
+                continue;
+            if (targetHost && slot.hostId !== targetHost)
+                continue;
+            if (targetHypervisor && slot.hypervisorType !== targetHypervisor)
+                continue;
+            let shouldPurge = false;
+            let reason = "manual_purge";
+            const expiresTime = slot.expiresAt ? new Date(slot.expiresAt).getTime() : 0;
+            const claimedTime = slot.claimedAt ? new Date(slot.claimedAt).getTime() : 0;
+            const isExpired = expiresTime > 0 && expiresTime <= now;
+            if (options.linearIssue) {
+                const matchesLinear = slot.linearIssue === options.linearIssue || slot.tag === options.linearIssue;
+                if (matchesLinear) {
                     shouldPurge = true;
-                    reason = "expired";
+                    reason = isExpired ? "expired" : "linear_match";
                 }
-                else if (force) {
+            }
+            else if (options.olderThanMinutes !== undefined) {
+                const ageMinutes = (now - claimedTime) / (60 * 1000);
+                if (ageMinutes >= options.olderThanMinutes || isExpired) {
                     shouldPurge = true;
-                    reason = "forced";
-                }
-                if (shouldPurge) {
-                    matchingSlots.push(slot);
-                    reasons.set(slot.slotId, reason);
+                    reason = isExpired ? "expired" : "older_than_threshold";
                 }
             }
-            const purgedSlots = [];
-            const destroyedVms = [];
-            let skippedProtectedCount = 0;
-            let reclaimedMemoryMb = 0;
-            for (const slot of matchingSlots) {
-                const reason = reasons.get(slot.slotId) || "manual_purge";
-                const purgedSlot = {
-                    slotId: slot.slotId,
-                    hostId: slot.hostId,
-                    claimId: slot.claimId,
-                    claimedAt: slot.claimedAt,
-                    expiresAt: slot.expiresAt,
-                    linearIssue: slot.linearIssue,
-                    label: slot.label,
-                    workloadType: slot.workloadType,
-                    vmId: slot.vmId,
-                    vmName: slot.vmName,
-                    reason
+            else if (isExpired) {
+                shouldPurge = true;
+                reason = "expired";
+            }
+            else if (force) {
+                shouldPurge = true;
+                reason = "forced";
+            }
+            if (shouldPurge) {
+                matchingSlots.push(slot);
+                reasons.set(slot.slotId, reason);
+            }
+        }
+        const purgedSlots = [];
+        const destroyedVms = [];
+        let skippedProtectedCount = 0;
+        let reclaimedMemoryMb = 0;
+        for (const slot of matchingSlots) {
+            const reason = reasons.get(slot.slotId) || "manual_purge";
+            const purgedSlot = {
+                slotId: slot.slotId,
+                hostId: slot.hostId,
+                claimId: slot.claimId,
+                claimedAt: slot.claimedAt,
+                expiresAt: slot.expiresAt,
+                linearIssue: slot.linearIssue,
+                label: slot.label,
+                workloadType: slot.workloadType,
+                vmId: slot.vmId,
+                vmName: slot.vmName,
+                reason
+            };
+            let canReclaimSlot = true;
+            // Process attached VM cleanup if present
+            if (slot.vmId !== null && slot.vmId !== undefined) {
+                const vmTarget = {
+                    vmid: slot.vmId,
+                    name: slot.vmName || undefined,
+                    isProtected: false
                 };
-                let canReclaimSlot = true;
-                // Process attached VM cleanup if present
-                if (slot.vmId !== null && slot.vmId !== undefined) {
-                    const vmTarget = {
-                        vmid: slot.vmId,
-                        name: slot.vmName || undefined,
-                        isProtected: false
-                    };
-                    // Guardrail safety check
-                    const protCheck = this.guardrailEngine.isProtected(vmTarget);
-                    if (protCheck.protected) {
-                        canReclaimSlot = false;
-                        skippedProtectedCount++;
+                // Guardrail safety check
+                const protCheck = this.guardrailEngine.isProtected(vmTarget);
+                if (protCheck.protected) {
+                    canReclaimSlot = false;
+                    skippedProtectedCount++;
+                    destroyedVms.push({
+                        vmId: slot.vmId,
+                        vmName: slot.vmName || undefined,
+                        hostId: slot.hostId,
+                        hypervisorType: slot.hypervisorType,
+                        status: "skipped_protected",
+                        reason: `Protected infrastructure preserved: ${protCheck.reason}`
+                    });
+                    this.telemetry.emit({
+                        event: "vm.guardrail_blocked",
+                        actor: slot.requester || "system",
+                        status: "blocked",
+                        linearIssue: slot.linearIssue || undefined,
+                        vmId: slot.vmId,
+                        vmName: slot.vmName || undefined,
+                        hostId: slot.hostId,
+                        hypervisorType: slot.hypervisorType,
+                        error: `Guardrail blocked purge destruction: ${protCheck.reason}`
+                    });
+                }
+                else {
+                    if (dryRun) {
                         destroyedVms.push({
                             vmId: slot.vmId,
                             vmName: slot.vmName || undefined,
                             hostId: slot.hostId,
                             hypervisorType: slot.hypervisorType,
-                            status: "skipped_protected",
-                            reason: `Protected infrastructure preserved: ${protCheck.reason}`
-                        });
-                        this.telemetry.emit({
-                            event: "vm.guardrail_blocked",
-                            actor: slot.requester || "system",
-                            status: "blocked",
-                            linearIssue: slot.linearIssue || undefined,
-                            vmId: slot.vmId,
-                            vmName: slot.vmName || undefined,
-                            hostId: slot.hostId,
-                            hypervisorType: slot.hypervisorType,
-                            error: `Guardrail blocked purge destruction: ${protCheck.reason}`
+                            status: "dry_run",
+                            reason: `Would be destroyed during purge (${reason})`
                         });
                     }
-                    else {
-                        if (dryRun) {
+                    else if (destroyVms && this.hypervisorManager) {
+                        try {
+                            await this.hypervisorManager.vmAction({
+                                vmIdOrName: String(slot.vmId),
+                                targetHost: slot.hostId,
+                                action: "destroy",
+                                force: true
+                            });
                             destroyedVms.push({
                                 vmId: slot.vmId,
                                 vmName: slot.vmName || undefined,
                                 hostId: slot.hostId,
                                 hypervisorType: slot.hypervisorType,
-                                status: "dry_run",
-                                reason: `Would be destroyed during purge (${reason})`
+                                status: "destroyed",
+                                reason: `Purged and destroyed attached VM (${reason})`
+                            });
+                            this.telemetry.emit({
+                                event: "vm.purged",
+                                actor: slot.requester || "system",
+                                status: "success",
+                                linearIssue: slot.linearIssue || undefined,
+                                vmId: slot.vmId,
+                                vmName: slot.vmName || undefined,
+                                hostId: slot.hostId,
+                                hypervisorType: slot.hypervisorType,
+                                metadata: { slotId: slot.slotId, reason }
                             });
                         }
-                        else if (destroyVms && this.hypervisorManager) {
-                            try {
-                                await this.hypervisorManager.vmAction({
-                                    vmIdOrName: String(slot.vmId),
-                                    targetHost: slot.hostId,
-                                    action: "destroy",
-                                    force: true
-                                });
+                        catch (err) {
+                            const errMsg = err instanceof Error ? err.message : String(err);
+                            if (errMsg.toLowerCase().includes("not found")) {
+                                canReclaimSlot = true;
                                 destroyedVms.push({
                                     vmId: slot.vmId,
                                     vmName: slot.vmName || undefined,
                                     hostId: slot.hostId,
                                     hypervisorType: slot.hypervisorType,
                                     status: "destroyed",
-                                    reason: `Purged and destroyed attached VM (${reason})`
-                                });
-                                this.telemetry.emit({
-                                    event: "vm.purged",
-                                    actor: slot.requester || "system",
-                                    status: "success",
-                                    linearIssue: slot.linearIssue || undefined,
-                                    vmId: slot.vmId,
-                                    vmName: slot.vmName || undefined,
-                                    hostId: slot.hostId,
-                                    hypervisorType: slot.hypervisorType,
-                                    metadata: { slotId: slot.slotId, reason }
+                                    reason: `Attached VM already absent from hypervisor (${reason})`
                                 });
                             }
-                            catch (err) {
+                            else {
                                 canReclaimSlot = false;
                                 destroyedVms.push({
                                     vmId: slot.vmId,
@@ -1121,145 +1187,458 @@ export class SlotManager {
                                     hostId: slot.hostId,
                                     hypervisorType: slot.hypervisorType,
                                     status: "failed",
-                                    error: err instanceof Error ? err.message : String(err)
+                                    error: errMsg
                                 });
                             }
                         }
-                        else if (!dryRun) {
-                            canReclaimSlot = false;
+                    }
+                    else if (!dryRun) {
+                        canReclaimSlot = false;
+                        destroyedVms.push({
+                            vmId: slot.vmId,
+                            vmName: slot.vmName || undefined,
+                            hostId: slot.hostId,
+                            hypervisorType: slot.hypervisorType,
+                            status: "failed",
+                            error: destroyVms
+                                ? "No hypervisor manager is available to verify VM deletion"
+                                : "VM destruction was disabled; occupied capacity was retained"
+                        });
+                    }
+                }
+            }
+            // Dry-run reports the candidate. A live purge only releases scheduler
+            // capacity after the attached VM is absent or destruction succeeded.
+            if (dryRun || canReclaimSlot) {
+                purgedSlots.push(purgedSlot);
+                reclaimedMemoryMb += slot.memoryMb;
+            }
+            if (!dryRun && canReclaimSlot) {
+                this.telemetry.emit({
+                    event: "slot.purge",
+                    actor: slot.requester || "system",
+                    status: "success",
+                    linearIssue: slot.linearIssue || undefined,
+                    slotId: slot.slotId,
+                    claimId: slot.claimId || undefined,
+                    vmId: slot.vmId || undefined,
+                    vmName: slot.vmName || undefined,
+                    hostId: slot.hostId,
+                    hypervisorType: slot.hypervisorType,
+                    metadata: {
+                        reason,
+                        freedMemoryMb: slot.memoryMb
+                    }
+                });
+                this.resetSlot(slot);
+            }
+        }
+        // Check orphan VMs if requested
+        if (includeOrphans && this.hypervisorManager) {
+            try {
+                const allVms = await this.hypervisorManager.listUnifiedInventory({
+                    includeTemplates: false,
+                    host: targetHost,
+                    hypervisor: targetHypervisor
+                });
+                const activeVmIds = new Set(Array.from(this.slots.values())
+                    .map((s) => s.vmId)
+                    .filter((id) => id !== null && id !== undefined)
+                    .map((id) => String(id)));
+                for (const vm of allVms) {
+                    // Check if VM is an untracked disposable VM without active lease
+                    if (!vm.isTemplate && !vm.isProtected && !activeVmIds.has(String(vm.id))) {
+                        const protCheck = this.guardrailEngine.isProtected({
+                            vmid: vm.id,
+                            name: vm.name,
+                            isProtected: vm.isProtected,
+                            tags: vm.tags
+                        });
+                        if (protCheck.protected) {
+                            skippedProtectedCount++;
                             destroyedVms.push({
-                                vmId: slot.vmId,
-                                vmName: slot.vmName || undefined,
-                                hostId: slot.hostId,
-                                hypervisorType: slot.hypervisorType,
-                                status: "failed",
-                                error: destroyVms
-                                    ? "No hypervisor manager is available to verify VM deletion"
-                                    : "VM destruction was disabled; occupied capacity was retained"
+                                vmId: vm.id,
+                                vmName: vm.name,
+                                hostId: vm.hostName,
+                                hypervisorType: vm.hypervisor,
+                                status: "skipped_protected",
+                                reason: `Protected orphan preserved: ${protCheck.reason}`
                             });
                         }
+                        else {
+                            if (dryRun) {
+                                destroyedVms.push({
+                                    vmId: vm.id,
+                                    vmName: vm.name,
+                                    hostId: vm.hostName,
+                                    hypervisorType: vm.hypervisor,
+                                    status: "dry_run",
+                                    reason: "Orphaned disposable VM with no active slot lease"
+                                });
+                            }
+                            else if (destroyVms) {
+                                try {
+                                    await this.hypervisorManager.vmAction({
+                                        vmIdOrName: String(vm.id),
+                                        targetHost: vm.hostName,
+                                        action: "destroy",
+                                        force: true
+                                    });
+                                    destroyedVms.push({
+                                        vmId: vm.id,
+                                        vmName: vm.name,
+                                        hostId: vm.hostName,
+                                        hypervisorType: vm.hypervisor,
+                                        status: "destroyed",
+                                        reason: "Destroyed orphaned disposable VM with no active slot lease"
+                                    });
+                                }
+                                catch (orphanErr) {
+                                    destroyedVms.push({
+                                        vmId: vm.id,
+                                        vmName: vm.name,
+                                        hostId: vm.hostName,
+                                        hypervisorType: vm.hypervisor,
+                                        status: "failed",
+                                        error: orphanErr instanceof Error ? orphanErr.message : String(orphanErr)
+                                    });
+                                }
+                            }
+                        }
                     }
                 }
-                // Dry-run reports the candidate. A live purge only releases scheduler
-                // capacity after the attached VM is absent or destruction succeeded.
-                if (dryRun || canReclaimSlot) {
-                    purgedSlots.push(purgedSlot);
-                    reclaimedMemoryMb += slot.memoryMb;
-                }
-                if (!dryRun && canReclaimSlot) {
-                    this.telemetry.emit({
-                        event: "slot.purge",
-                        actor: slot.requester || "system",
-                        status: "success",
-                        linearIssue: slot.linearIssue || undefined,
-                        slotId: slot.slotId,
-                        claimId: slot.claimId || undefined,
-                        vmId: slot.vmId || undefined,
-                        vmName: slot.vmName || undefined,
-                        hostId: slot.hostId,
-                        hypervisorType: slot.hypervisorType,
-                        metadata: {
-                            reason,
-                            freedMemoryMb: slot.memoryMb
+            }
+            catch (invErr) {
+                console.error("[purgeSlots] Orphan inventory inspection error:", invErr);
+            }
+        }
+        const destroyedCount = destroyedVms.filter((v) => v.status === "destroyed").length;
+        const reclaimedMemoryBytes = reclaimedMemoryMb * 1024 * 1024;
+        const prefix = dryRun ? "[DRY RUN] " : "";
+        const message = `${prefix}Purged ${purgedSlots.length} slot lease(s), reclaimed ${reclaimedMemoryMb / 1024} GB RAM, processed ${destroyedVms.length} VM(s) (${destroyedCount} destroyed, ${skippedProtectedCount} protected skipped).`;
+        return {
+            purgedSlotsCount: purgedSlots.length,
+            purgedSlots,
+            destroyedVmsCount: destroyedCount,
+            destroyedVms,
+            skippedProtectedVmsCount: skippedProtectedCount,
+            reclaimedMemoryBytes,
+            reclaimedMemoryMb,
+            dryRun,
+            timestamp: new Date(now).toISOString(),
+            message
+        };
+    }
+    /**
+     * Intelligently discovers available slot capacity across all hypervisors,
+     * ranks candidate hosts, and reports reclaimable expired/disposable VMs if fleet is full.
+     * Optionally auto-claims when autoClaim=true, or auto-reclaims and claims when purgeIfFull=true.
+     */
+    async findSlot(params = {}) {
+        return this.mutex.runExclusive(async () => {
+            this.sweepExpiredSlotsInternal();
+            const allowEsxi = params.allowEsxiSlots ?? this.allowEsxiSlots;
+            const targetHost = params.host && params.host !== "all" && params.host !== "auto"
+                ? this.normalizeHostId(params.host)
+                : undefined;
+            const targetHyp = params.hypervisorType && params.hypervisorType !== "all" && params.hypervisorType !== "any"
+                ? params.hypervisorType
+                : undefined;
+            // Sync with live capacity if hypervisorManager is present
+            if (this.hypervisorManager) {
+                try {
+                    const liveCaps = await this.hypervisorManager.listAllHostsCapacity();
+                    for (const cap of liveCaps) {
+                        const hid = this.normalizeHostId(cap.name);
+                        const cfg = this.hosts.get(hid);
+                        if (cfg) {
+                            cfg.totalMemoryMb = Math.round(cap.memoryTotalBytes / (1024 * 1024));
+                            cfg.freeDiskGb = Math.round(cap.storageFreeBytes / (1024 * 1024 * 1024));
                         }
+                    }
+                }
+                catch {
+                    // fallback to registered configs
+                }
+            }
+            // Gather candidate hosts
+            const allCandidates = [];
+            for (const [hid, hostConfig] of this.hosts.entries()) {
+                if (targetHost && hid !== targetHost)
+                    continue;
+                if (targetHyp && hostConfig.hypervisorType !== targetHyp)
+                    continue;
+                if (hostConfig.hypervisorType === "esxi" && !allowEsxi)
+                    continue;
+                const hostSlots = Array.from(this.slots.values()).filter((s) => s.hostId === hid);
+                const availCount = hostSlots.filter((s) => s.status === "AVAILABLE").length;
+                const pureCapacity = calculatePureCapacity({ ...hostConfig, allowEsxiSlots: allowEsxi });
+                const freeDisk = hostConfig.freeDiskGb ?? 100;
+                const totalMem = hostConfig.totalMemoryMb;
+                const reserved = hostConfig.reservedHeadroomMb || 0;
+                const freeMem = Math.max(0, totalMem - reserved - (hostSlots.length - availCount) * (hostConfig.slotSizeMb || 8192));
+                // Score based on available slots, free memory, and datastore space
+                const score = availCount * 100 + Math.floor(freeMem / 1024) * 10 + Math.floor(freeDisk / 100);
+                allCandidates.push({
+                    hostId: hid,
+                    name: hostConfig.name,
+                    hypervisorType: hostConfig.hypervisorType || (hid.startsWith("esxi") ? "esxi" : "proxmox"),
+                    status: "online",
+                    availableSlots: availCount,
+                    totalPureSlots: pureCapacity,
+                    freeMemoryMb: freeMem,
+                    totalMemoryMb: totalMem,
+                    freeDiskGb: freeDisk,
+                    cpuUsedPercent: 0,
+                    runningVms: hostSlots.length - availCount,
+                    score
+                });
+            }
+            // Sort candidates by score descending
+            allCandidates.sort((a, b) => b.score - a.score);
+            const availableSlotsTotal = allCandidates.reduce((sum, c) => sum + c.availableSlots, 0);
+            // If capacity is available
+            if (availableSlotsTotal > 0) {
+                const winningCandidate = allCandidates[0];
+                let claimResult;
+                if (params.autoClaim) {
+                    const tag = params.tag || params.linearIssue || params.requester || "find-slot-claim";
+                    claimResult = await this.claimSlotInternal({
+                        tag,
+                        requester: params.requester || tag,
+                        linearIssue: params.linearIssue,
+                        label: params.label,
+                        workloadType: params.workloadType,
+                        targetVersion: params.targetVersion,
+                        branch: params.branch,
+                        host: winningCandidate.hostId,
+                        durationMinutes: params.durationMinutes,
+                        allowEsxiSlots: allowEsxi,
+                        purpose: `Auto-claimed via find_slot on ${winningCandidate.hostId}`
                     });
-                    this.resetSlot(slot);
+                    return {
+                        status: "auto_claimed",
+                        candidateHost: winningCandidate,
+                        allCandidates,
+                        availableSlotsTotal: availableSlotsTotal - 1,
+                        claim: claimResult,
+                        message: `Found available slot and successfully auto-claimed '${claimResult.slotId}' on host '${winningCandidate.hostId}'.`
+                    };
                 }
+                return {
+                    status: "available",
+                    candidateHost: winningCandidate,
+                    allCandidates,
+                    availableSlotsTotal,
+                    message: `Found ${availableSlotsTotal} available 8GB slot(s) across ${allCandidates.length} eligible host(s). Recommended placement: '${winningCandidate.hostId}' (${winningCandidate.availableSlots} slots available).`
+                };
             }
-            // Check orphan VMs if requested
-            if (includeOrphans && this.hypervisorManager) {
+            // If capacity is NOT available (availableSlotsTotal === 0)
+            // Inspect reclaimable resources (expired leases + untracked disposable VMs)
+            const expiredSlots = Array.from(this.slots.values())
+                .filter((s) => s.status === "EXPIRED" || (s.expiresAt && new Date(s.expiresAt).getTime() <= Date.now()))
+                .map((s) => ({
+                slotId: s.slotId,
+                hostId: s.hostId,
+                claimId: s.claimId,
+                claimedAt: s.claimedAt,
+                expiresAt: s.expiresAt,
+                linearIssue: s.linearIssue,
+                label: s.label,
+                workloadType: s.workloadType,
+                vmId: s.vmId,
+                vmName: s.vmName,
+                reason: "expired"
+            }));
+            const disposableVms = [];
+            if (this.hypervisorManager) {
                 try {
-                    const allVms = await this.hypervisorManager.listUnifiedInventory({
+                    const inv = await this.hypervisorManager.listUnifiedInventory({
                         includeTemplates: false,
                         host: targetHost,
-                        hypervisor: targetHypervisor
+                        hypervisor: targetHyp
                     });
                     const activeVmIds = new Set(Array.from(this.slots.values())
-                        .map((s) => s.vmId)
-                        .filter((id) => id !== null && id !== undefined)
-                        .map((id) => String(id)));
-                    for (const vm of allVms) {
-                        // Check if VM is an untracked disposable VM without active lease
+                        .filter((s) => s.status === "CLAIMED" && s.vmId !== null && s.vmId !== undefined)
+                        .map((s) => String(s.vmId)));
+                    for (const vm of inv) {
                         if (!vm.isTemplate && !vm.isProtected && !activeVmIds.has(String(vm.id))) {
-                            const protCheck = this.guardrailEngine.isProtected({
+                            const prot = this.guardrailEngine.isProtected({
                                 vmid: vm.id,
                                 name: vm.name,
                                 isProtected: vm.isProtected,
                                 tags: vm.tags
                             });
-                            if (protCheck.protected) {
-                                skippedProtectedCount++;
-                                destroyedVms.push({
+                            if (!prot.protected) {
+                                disposableVms.push({
                                     vmId: vm.id,
-                                    vmName: vm.name,
-                                    hostId: vm.hostName,
-                                    hypervisorType: vm.hypervisor,
-                                    status: "skipped_protected",
-                                    reason: `Protected orphan preserved: ${protCheck.reason}`
+                                    name: vm.name,
+                                    hostName: vm.hostName,
+                                    hypervisor: vm.hypervisor,
+                                    status: vm.status,
+                                    memoryMb: Math.round(vm.memoryBytes / (1024 * 1024)),
+                                    linearIssue: vm.linearIssue
                                 });
                             }
-                            else {
-                                if (dryRun) {
-                                    destroyedVms.push({
-                                        vmId: vm.id,
-                                        vmName: vm.name,
-                                        hostId: vm.hostName,
-                                        hypervisorType: vm.hypervisor,
-                                        status: "dry_run",
-                                        reason: "Orphaned disposable VM with no active slot lease"
-                                    });
-                                }
-                                else if (destroyVms) {
-                                    try {
-                                        await this.hypervisorManager.vmAction({
-                                            vmIdOrName: String(vm.id),
-                                            targetHost: vm.hostName,
-                                            action: "destroy",
-                                            force: true
-                                        });
-                                        destroyedVms.push({
-                                            vmId: vm.id,
-                                            vmName: vm.name,
-                                            hostId: vm.hostName,
-                                            hypervisorType: vm.hypervisor,
-                                            status: "destroyed",
-                                            reason: "Destroyed orphaned disposable VM with no active slot lease"
-                                        });
-                                    }
-                                    catch (orphanErr) {
-                                        destroyedVms.push({
-                                            vmId: vm.id,
-                                            vmName: vm.name,
-                                            hostId: vm.hostName,
-                                            hypervisorType: vm.hypervisor,
-                                            status: "failed",
-                                            error: orphanErr instanceof Error ? orphanErr.message : String(orphanErr)
-                                        });
-                                    }
-                                }
-                            }
                         }
                     }
                 }
-                catch (invErr) {
-                    console.error("[purgeSlots] Orphan inventory inspection error:", invErr);
+                catch {
+                    // ignore inventory errors
+                }
+            }
+            const reclaimableSlotsEst = expiredSlots.length + Math.floor(disposableVms.reduce((acc, v) => acc + v.memoryMb, 0) / 8192);
+            const reclaimableMemoryMb = expiredSlots.length * 8192 + disposableVms.reduce((acc, v) => acc + v.memoryMb, 0);
+            const reclaimable = {
+                expiredSlotsCount: expiredSlots.length,
+                expiredSlots,
+                disposableVmsCount: disposableVms.length,
+                disposableVms,
+                reclaimableMemoryMb,
+                reclaimableSlotsEst
+            };
+            // If purgeIfFull is requested and we have reclaimable resources, auto-purge and claim!
+            if (params.purgeIfFull && (expiredSlots.length > 0 || disposableVms.length > 0)) {
+                const purgeRes = await this.purgeSlotsInternal({
+                    host: targetHost,
+                    hypervisorType: targetHyp,
+                    destroyVms: true,
+                    includeOrphans: true,
+                    dryRun: false
+                });
+                if (purgeRes.purgedSlotsCount > 0 || purgeRes.destroyedVmsCount > 0) {
+                    const tag = params.tag || params.linearIssue || params.requester || "find-slot-reclaim";
+                    const claimResult = await this.claimSlotInternal({
+                        tag,
+                        requester: params.requester || tag,
+                        linearIssue: params.linearIssue,
+                        label: params.label,
+                        workloadType: params.workloadType,
+                        targetVersion: params.targetVersion,
+                        branch: params.branch,
+                        host: targetHost || "auto",
+                        durationMinutes: params.durationMinutes,
+                        allowEsxiSlots: allowEsxi,
+                        purpose: `Auto-reclaimed and claimed via find_slot`
+                    });
+                    return {
+                        status: "auto_reclaimed_and_claimed",
+                        candidateHost: allCandidates.find((c) => c.hostId === claimResult.hostId) || allCandidates[0],
+                        allCandidates,
+                        availableSlotsTotal: 0,
+                        claim: claimResult,
+                        reclaimable,
+                        message: `Purged ${purgeRes.purgedSlotsCount} expired slot(s) and ${purgeRes.destroyedVmsCount} disposable VM(s), then successfully claimed '${claimResult.slotId}' on host '${claimResult.hostId}'.`
+                    };
                 }
             }
-            const destroyedCount = destroyedVms.filter((v) => v.status === "destroyed").length;
-            const reclaimedMemoryBytes = reclaimedMemoryMb * 1024 * 1024;
-            const prefix = dryRun ? "[DRY RUN] " : "";
-            const message = `${prefix}Purged ${purgedSlots.length} slot lease(s), reclaimed ${reclaimedMemoryMb / 1024} GB RAM, processed ${destroyedVms.length} VM(s) (${destroyedCount} destroyed, ${skippedProtectedCount} protected skipped).`;
             return {
-                purgedSlotsCount: purgedSlots.length,
-                purgedSlots,
-                destroyedVmsCount: destroyedCount,
-                destroyedVms,
-                skippedProtectedVmsCount: skippedProtectedCount,
-                reclaimedMemoryBytes,
-                reclaimedMemoryMb,
-                dryRun,
-                timestamp: new Date(now).toISOString(),
-                message
+                status: "full",
+                allCandidates,
+                availableSlotsTotal: 0,
+                reclaimable,
+                message: `No slots currently available across ${allCandidates.length} host(s). Found ${expiredSlots.length} expired lease(s) and ${disposableVms.length} disposable VM(s) (~${Math.round(reclaimableMemoryMb / 1024)}GB reclaimable). Use purge_slots or call find_slot with purgeIfFull=true to reclaim capacity.`
+            };
+        });
+    }
+    /**
+     * One-shot purge of old/expired disposable test VM and replacement with fresh slot allocation.
+     */
+    async purgeAndRedeploy(params) {
+        return this.mutex.runExclusive(async () => {
+            if (!this.hypervisorManager) {
+                throw new InvalidSlotOperationError("HypervisorManager is required for purge_and_redeploy operations.");
+            }
+            const linearIssue = params.linearIssue;
+            const targetVmIdOrName = params.targetVmIdOrName;
+            if (!linearIssue && !targetVmIdOrName) {
+                throw new InvalidSlotOperationError("Either 'linearIssue' or 'targetVmIdOrName' is required for purge_and_redeploy.");
+            }
+            // 1. Locate target VM
+            let targetVmidStr = targetVmIdOrName;
+            const matchingSlot = Array.from(this.slots.values()).find((s) => (targetVmIdOrName && (String(s.vmId) === targetVmIdOrName || s.vmName === targetVmIdOrName)) ||
+                (linearIssue && s.linearIssue === linearIssue));
+            if (!targetVmidStr && matchingSlot && matchingSlot.vmId != null) {
+                targetVmidStr = String(matchingSlot.vmId);
+            }
+            const inventory = await this.hypervisorManager.listUnifiedInventory({
+                includeTemplates: false,
+                host: params.host
+            });
+            const targetVm = inventory.find((vm) => {
+                if (targetVmidStr && (String(vm.id) === targetVmidStr || vm.name === targetVmidStr)) {
+                    return true;
+                }
+                if (linearIssue && (vm.linearIssue === linearIssue || vm.name.toLowerCase().includes(linearIssue.toLowerCase()))) {
+                    return true;
+                }
+                return false;
+            });
+            if (!targetVm) {
+                throw new SlotNotFoundError(`No existing VM found matching '${targetVmIdOrName || linearIssue}'.`);
+            }
+            // 2. Safety guardrail check
+            const protCheck = this.guardrailEngine.isProtected({
+                vmid: targetVm.id,
+                name: targetVm.name,
+                isProtected: targetVm.isProtected,
+                tags: targetVm.tags
+            });
+            if (protCheck.protected) {
+                throw new InvalidSlotOperationError(`Refusing to destroy protected VM '${targetVm.name}' (${targetVm.id}): ${protCheck.reason}`);
+            }
+            if (params.dryRun) {
+                return {
+                    success: true,
+                    dryRun: true,
+                    purgedVm: {
+                        vmId: targetVm.id,
+                        name: targetVm.name,
+                        host: targetVm.hostName,
+                        hypervisor: targetVm.hypervisor
+                    },
+                    message: `[Dry-run] Would purge VM '${targetVm.name}' (${targetVm.id}) on '${targetVm.hostName}' and claim fresh slot for redeployment.`
+                };
+            }
+            // 3. Find associated slot if any
+            const slotToRelease = matchingSlot || Array.from(this.slots.values()).find((s) => (s.vmId !== null && String(s.vmId) === String(targetVm.id)) || (linearIssue && s.linearIssue === linearIssue));
+            // 4. Destroy old VM
+            await this.hypervisorManager.vmAction({
+                vmIdOrName: String(targetVm.id),
+                targetHost: targetVm.hostName,
+                action: "destroy",
+                force: true
+            });
+            // 5. Release existing slot if present
+            if (slotToRelease) {
+                this.resetSlot(slotToRelease);
+            }
+            // 6. Claim new slot on the same host (or auto)
+            const targetHost = params.host || targetVm.hostName;
+            const tag = linearIssue || targetVm.name;
+            const newSlot = await this.claimSlotInternal({
+                tag,
+                requester: linearIssue || "purge-and-redeploy",
+                linearIssue,
+                label: `Redeployed ${linearIssue || targetVm.name}`,
+                workloadType: params.workloadType || "uat",
+                targetVersion: params.targetVersion || params.version,
+                branch: params.branch,
+                host: targetHost,
+                durationMinutes: params.durationMinutes || 120,
+                purpose: `Purged old VM ${targetVm.name} and claimed capacity for fresh deployment`
+            });
+            return {
+                success: true,
+                purgedVm: {
+                    vmId: targetVm.id,
+                    name: targetVm.name,
+                    host: targetVm.hostName,
+                    hypervisor: targetVm.hypervisor
+                },
+                reclaimedSlotId: matchingSlot?.slotId,
+                newSlot,
+                message: `Successfully purged old VM '${targetVm.name}' (${targetVm.id}) and claimed fresh slot '${newSlot.slotId}' on host '${newSlot.hostId}'.`
             };
         });
     }