@poetic-ai/poetic 1.42.0

package/dist/chunk-L7E6XCRA.js

@@ -0,0 +1,1042 @@
+import {
+  getAvailableMemoryGB,
+  getMemoryPressureLevel
+} from "./chunk-PTH5E5XO.js";
+import {
+  PROVIDER_CONCURRENCY,
+  applyProviderConcurrencyPenalty,
+  getProviderConcurrencyBaseline,
+  getProviderConcurrencyLimit
+} from "./chunk-GHTZSQB7.js";
+import {
+  RESOURCE_ACQUISITION_TIMEOUT_MS
+} from "./chunk-LAMKBTXX.js";
+
+// src/orchestrator/provider-aware-resource-manager.ts
+import { totalmem } from "os";
+
+// src/orchestrator/resource-manager-types.ts
+import * as os from "os";
+function clampInteger(value, min, max) {
+  if (!Number.isFinite(value)) return min;
+  return Math.max(min, Math.min(max, Math.round(value)));
+}
+function captureConcurrencyBackpressureSnapshot(queueDepth, activeConcurrency, currentGlobalConcurrency, configuredGlobalConcurrency, minGlobalConcurrency = 1) {
+  const cpuCount = Math.max(1, os.cpus().length);
+  const load1 = os.loadavg?.()[0] ?? 0;
+  const cpuPercent = Math.max(0, load1 / cpuCount * 100);
+  const availableMemoryGB = getAvailableMemoryGB();
+  const memoryPressure = getMemoryPressureLevel();
+  return {
+    cpuPercent,
+    availableMemoryGB,
+    memoryPressure,
+    queueDepth,
+    activeConcurrency,
+    currentGlobalConcurrency,
+    configuredGlobalConcurrency,
+    minGlobalConcurrency
+  };
+}
+function recommendGlobalConcurrency(snapshot) {
+  const configured = Math.max(1, Math.floor(snapshot.configuredGlobalConcurrency));
+  const minGlobalConcurrency = clampInteger(snapshot.minGlobalConcurrency ?? 1, 1, configured);
+  const current = clampInteger(snapshot.currentGlobalConcurrency, minGlobalConcurrency, configured);
+  const queueDepth = Math.max(0, Math.floor(snapshot.queueDepth));
+  const activeConcurrency = Math.max(0, Math.floor(snapshot.activeConcurrency));
+  const cpuPercent = Math.max(0, snapshot.cpuPercent);
+  const availableMemoryGB = Math.max(0, snapshot.availableMemoryGB);
+  const kernelPressure = snapshot.memoryPressure ?? "unknown";
+  const memLabel = `availMem=${availableMemoryGB.toFixed(1)}GB` + (kernelPressure === "warn" || kernelPressure === "critical" ? ` kernel=${kernelPressure}` : "");
+  let recommended = current;
+  let pressureLevel = "healthy";
+  let reason = "steady concurrency";
+  let backpressureActive = false;
+  const criticalPressure = kernelPressure === "critical" || cpuPercent >= 92 || availableMemoryGB < 1;
+  const elevatedPressure = kernelPressure === "warn" || cpuPercent >= 80 || availableMemoryGB < 2;
+  const moderatePressure = cpuPercent >= 70 || availableMemoryGB < 4;
+  const healthySystem = cpuPercent <= 45 && availableMemoryGB >= 6;
+  if (criticalPressure) {
+    pressureLevel = "critical";
+    backpressureActive = true;
+    recommended = Math.max(minGlobalConcurrency, Math.floor(current / 2));
+    reason = `critical pressure cpu=${cpuPercent.toFixed(1)}% ${memLabel}`;
+  } else if (elevatedPressure) {
+    pressureLevel = "backpressure";
+    backpressureActive = true;
+    const shed = Math.max(2, Math.ceil(current * 0.25));
+    recommended = Math.max(minGlobalConcurrency, current - shed);
+    reason = `high pressure cpu=${cpuPercent.toFixed(1)}% ${memLabel}`;
+  } else if (moderatePressure) {
+    pressureLevel = "watch";
+    backpressureActive = true;
+    recommended = Math.max(minGlobalConcurrency, current - 1);
+    reason = `moderate pressure cpu=${cpuPercent.toFixed(1)}% ${memLabel}`;
+  } else if (healthySystem && queueDepth > 0 && current < configured) {
+    const queueDemand = queueDepth >= Math.max(2, current * 2) || activeConcurrency >= current * 2 ? 2 : 1;
+    recommended = Math.min(configured, current + queueDemand);
+    reason = `healthy system with queueDepth=${queueDepth}`;
+  } else if (!healthySystem && queueDepth > current && current < configured) {
+    recommended = Math.min(configured, current + 1);
+    reason = `recovering with queued work queueDepth=${queueDepth}`;
+  }
+  return {
+    recommendedGlobalConcurrency: recommended,
+    backpressureActive,
+    reason,
+    pressureLevel
+  };
+}
+
+// src/orchestrator/provider-aware-resource-manager.ts
+var ProviderAwareResourceManager = class {
+  configuredGlobalMaxConcurrent;
+  globalMaxConcurrent;
+  fairnessMode;
+  enableTelemetry;
+  telemetryHooks = [];
+  lastBackpressureDecision;
+  lastBackpressureUpdatedAt = Date.now();
+  // Provider-specific baselines (host overlay / CLI overrides replace the shipped default)
+  providerLimits;
+  // Correctness ceilings no override may exceed (see config.providerHardCaps)
+  providerHardCaps;
+  // Current active counts
+  globalActiveCount = 0;
+  providerActiveCounts = /* @__PURE__ */ new Map();
+  // Queue of pending acquisitions (singles and atomic groups)
+  queue = [];
+  // Round-robin state for strict-fair mode
+  lastProviderServiced = null;
+  // Provider usage statistics for weighted-fair mode
+  providerUsageHistory = /* @__PURE__ */ new Map();
+  usageHistoryWindow = 100;
+  // Track last N acquisitions
+  providerAvgHoldMs = /* @__PURE__ */ new Map();
+  globalAvgHoldMs = 6e4;
+  holdTimeEwmaAlpha = 0.2;
+  constructor(config) {
+    if (config.globalMaxConcurrent < 1) {
+      throw new Error("globalMaxConcurrent must be at least 1");
+    }
+    this.configuredGlobalMaxConcurrent = config.globalMaxConcurrent;
+    this.globalMaxConcurrent = config.globalMaxConcurrent;
+    this.fairnessMode = config.fairnessMode ?? "weighted-fair";
+    this.enableTelemetry = config.enableTelemetry ?? true;
+    this.lastBackpressureDecision = {
+      recommendedGlobalConcurrency: config.globalMaxConcurrent,
+      backpressureActive: false,
+      reason: "baseline",
+      pressureLevel: "healthy"
+    };
+    this.providerHardCaps = /* @__PURE__ */ new Map();
+    for (const [provider, cap] of Object.entries(config.providerHardCaps ?? {})) {
+      if (Number.isFinite(cap)) {
+        this.providerHardCaps.set(provider, Math.max(1, Math.floor(cap)));
+      }
+    }
+    this.providerLimits = /* @__PURE__ */ new Map();
+    const providers = new Set(Object.keys(PROVIDER_CONCURRENCY));
+    for (const provider of Object.keys(config.providerLimits ?? {})) {
+      providers.add(provider);
+    }
+    for (const provider of providers) {
+      const generatedBaseline = PROVIDER_CONCURRENCY[provider]?.maxConcurrent;
+      const limit = config.providerLimits?.[provider] ?? generatedBaseline ?? getProviderConcurrencyLimit(provider);
+      this.providerLimits.set(provider, limit);
+      this.providerActiveCounts.set(provider, 0);
+      this.providerUsageHistory.set(provider, 0);
+      this.providerAvgHoldMs.set(provider, 6e4);
+    }
+  }
+  /**
+   * Acquire a resource slot (blocks if at capacity)
+   *
+   * Waits until both constraints are satisfied:
+   * 1. Provider-specific limit not exceeded
+   * 2. Global limit not exceeded
+   *
+   * @param provider - Provider ID requesting the resource
+   * @param signal - Optional AbortSignal for cancellation
+   * @param timeoutMs - Maximum time to wait (default: 60 seconds)
+   * @returns Resource handle with release callback
+   * @throws Error if timeout reached or signal aborted
+   *
+   * @example
+   * ```typescript
+   * const handle = await manager.acquire('gemini', signal);
+   * try {
+   *   await executeTask();
+   * } finally {
+   *   await handle.release();
+   * }
+   * ```
+   */
+  acquire(provider, signal, timeoutMs = RESOURCE_ACQUISITION_TIMEOUT_MS) {
+    if (signal?.aborted) {
+      return Promise.reject(new Error("Acquisition aborted before queuing"));
+    }
+    const immediate = this.tryAcquire(provider);
+    if (immediate) {
+      return Promise.resolve(immediate);
+    }
+    let pendingResolve;
+    let pendingReject;
+    const pending = new Promise((resolve, reject) => {
+      pendingResolve = resolve;
+      pendingReject = reject;
+    });
+    pending.catch(() => {
+    });
+    const queuedAt = Date.now();
+    let timeoutHandle = null;
+    let abortHandler = null;
+    const cleanup = () => {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      if (abortHandler && signal) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+    };
+    const wrappedResolve = (handle) => {
+      cleanup();
+      pendingResolve(handle);
+    };
+    const wrappedReject = (error) => {
+      cleanup();
+      const index = this.queue.findIndex((e) => e.resolve === wrappedResolve);
+      if (index !== -1) {
+        this.queue.splice(index, 1);
+      }
+      queueMicrotask(() => pendingReject(error));
+    };
+    const entry = {
+      provider,
+      resolve: wrappedResolve,
+      reject: wrappedReject,
+      signal,
+      queuedAt,
+      weight: this.calculateWeight(provider)
+    };
+    this.queue.push(entry);
+    timeoutHandle = setTimeout(() => {
+      const waitTimeMs = Date.now() - queuedAt;
+      const error = new Error(
+        `Resource acquisition timeout after ${waitTimeMs}ms (limit: ${timeoutMs}ms). Provider: ${provider}, Active: ${this.globalActiveCount}/${this.globalMaxConcurrent} global, ${this.providerActiveCounts.get(provider)}/${this.getEffectiveProviderLimit(provider)} provider, Queued: ${this.queue.length}. This may indicate resource contention or a leak (release() not called).`
+      );
+      this.emitTelemetry({
+        type: "resource_timeout",
+        provider,
+        waitTimeMs,
+        status: this.getStatus(),
+        timestamp: Date.now(),
+        error
+      });
+      wrappedReject(error);
+    }, timeoutMs);
+    if (signal) {
+      abortHandler = () => {
+        const waitTimeMs = Date.now() - queuedAt;
+        const error = new Error(
+          `Resource acquisition cancelled after ${waitTimeMs}ms for provider ${provider}`
+        );
+        this.emitTelemetry({
+          type: "resource_cancelled",
+          provider,
+          waitTimeMs,
+          status: this.getStatus(),
+          timestamp: Date.now(),
+          error
+        });
+        wrappedReject(error);
+      };
+      signal.addEventListener("abort", abortHandler);
+    }
+    this.processQueue();
+    return pending;
+  }
+  /**
+   * Acquire a group of resource slots via atomic queued reservation.
+   *
+   * Charges **one slot per reserved entry** (duplicate providers each consume a
+   * slot up to baseline). The outer reservation is **capacity-aware**: the
+   * request is clamped to configured baselines so oversized competitions remain
+   * runnable (per provider min(count, baseline), total ≤ configured global max).
+   * Overflow beyond that clamp is left to the caller to serialize.
+   *
+   * The group receives **no handles** until every reserved slot fits current
+   * effective capacity; there are never partial holds. Transient effective
+   * reductions cause a wait (queue), not a hard reject.
+   *
+   * Ordering is owned by the shared manager queue (FIFO / fairness with
+   * single-slot entries).
+   *
+   * @param providers - Providers for each requested slot (order preserved)
+   * @param signal - Optional AbortSignal for cancellation while queued
+   * @param timeoutMs - Max time to wait for the full group (default: RESOURCE_ACQUISITION_TIMEOUT_MS)
+   */
+  acquireMany(providers, signal, timeoutMs = RESOURCE_ACQUISITION_TIMEOUT_MS) {
+    if (providers.length === 0) {
+      return Promise.reject(new Error("acquireMany requires at least one provider slot"));
+    }
+    const reservedProviders = this.clampProvidersToBaselineCapacity(providers);
+    if (reservedProviders.length === 0) {
+      return Promise.reject(
+        new Error(
+          "acquireMany could not reserve any slots: all providers have zero configured baseline capacity"
+        )
+      );
+    }
+    if (signal?.aborted) {
+      return Promise.reject(new Error("Group acquisition aborted before queuing"));
+    }
+    if (this.queue.length === 0) {
+      const immediate = this.tryAcquireGroup(reservedProviders);
+      if (immediate) {
+        return Promise.resolve(immediate);
+      }
+    }
+    let pendingResolve;
+    let pendingReject;
+    const pending = new Promise((resolve, reject) => {
+      pendingResolve = resolve;
+      pendingReject = reject;
+    });
+    pending.catch(() => {
+    });
+    const queuedAt = Date.now();
+    let timeoutHandle = null;
+    let abortHandler = null;
+    const cleanup = () => {
+      if (timeoutHandle) {
+        clearTimeout(timeoutHandle);
+      }
+      if (abortHandler && signal) {
+        signal.removeEventListener("abort", abortHandler);
+      }
+    };
+    const wrappedResolve = (handles) => {
+      cleanup();
+      pendingResolve(handles);
+    };
+    const wrappedReject = (error) => {
+      cleanup();
+      const index = this.queue.findIndex((e) => e.resolveGroup === wrappedResolve);
+      if (index !== -1) {
+        this.queue.splice(index, 1);
+      }
+      queueMicrotask(() => pendingReject(error));
+    };
+    const primaryProvider = reservedProviders[0];
+    const weight = reservedProviders.reduce((sum, provider) => sum + this.calculateWeight(provider), 0) / reservedProviders.length;
+    const entry = {
+      provider: primaryProvider,
+      providers: [...reservedProviders],
+      // Single resolve is unused for groups; provide a no-op to satisfy the type.
+      resolve: () => {
+      },
+      resolveGroup: wrappedResolve,
+      reject: wrappedReject,
+      signal,
+      queuedAt,
+      weight
+    };
+    this.queue.push(entry);
+    timeoutHandle = setTimeout(() => {
+      const waitTimeMs = Date.now() - queuedAt;
+      const error = new Error(
+        `Resource group acquisition timeout after ${waitTimeMs}ms (limit: ${timeoutMs}ms). Providers: [${reservedProviders.join(", ")}], Active: ${this.globalActiveCount}/${this.globalMaxConcurrent} global, Queued: ${this.queue.length}. This may indicate resource contention or a leak (release() not called).`
+      );
+      this.emitTelemetry({
+        type: "resource_timeout",
+        provider: primaryProvider,
+        waitTimeMs,
+        status: this.getStatus(),
+        timestamp: Date.now(),
+        error
+      });
+      wrappedReject(error);
+    }, timeoutMs);
+    if (signal) {
+      abortHandler = () => {
+        const waitTimeMs = Date.now() - queuedAt;
+        const error = new Error(
+          `Resource group acquisition cancelled after ${waitTimeMs}ms for providers [${reservedProviders.join(", ")}]`
+        );
+        this.emitTelemetry({
+          type: "resource_cancelled",
+          provider: primaryProvider,
+          waitTimeMs,
+          status: this.getStatus(),
+          timestamp: Date.now(),
+          error
+        });
+        wrappedReject(error);
+      };
+      signal.addEventListener("abort", abortHandler);
+    }
+    this.processQueue();
+    return pending;
+  }
+  /**
+   * Try to acquire a resource slot (non-blocking)
+   *
+   * Returns immediately with a handle if available, or null if at capacity.
+   * Useful for opportunistic acquisition without blocking.
+   *
+   * @param provider - Provider ID requesting the resource
+   * @returns Resource handle if available, null otherwise
+   *
+   * @example
+   * ```typescript
+   * const handle = manager.tryAcquire('gemini');
+   * if (handle) {
+   *   try {
+   *     await executeTask();
+   *   } finally {
+   *     await handle.release();
+   *   }
+   * } else {
+   *   console.log('At capacity, will queue later');
+   * }
+   * ```
+   */
+  tryAcquire(provider) {
+    const providerLimit = this.getEffectiveProviderLimit(provider);
+    const providerActive = this.providerActiveCounts.get(provider) ?? 0;
+    const canAcquireProvider = providerActive < providerLimit;
+    const canAcquireGlobal = this.globalActiveCount < this.globalMaxConcurrent;
+    if (!canAcquireProvider || !canAcquireGlobal) {
+      if (process.env.DEBUG_ORCHESTRATOR) {
+        console.log(
+          `[DEBUG] At capacity for ${provider}: canAcquireProvider=${canAcquireProvider}, canAcquireGlobal=${canAcquireGlobal}, active=${providerActive}, limit=${providerLimit}, globalActive=${this.globalActiveCount}, globalMax=${this.globalMaxConcurrent}`
+        );
+      }
+      return null;
+    }
+    this.globalActiveCount++;
+    this.providerActiveCounts.set(provider, providerActive + 1);
+    this.updateUsageHistory(provider);
+    const acquiredAt = Date.now();
+    let released = false;
+    const release = async () => {
+      if (released) {
+        return;
+      }
+      released = true;
+      await this.releaseInternal(provider, acquiredAt);
+    };
+    this.emitTelemetry({
+      type: "resource_acquired",
+      provider,
+      waitTimeMs: 0,
+      // Immediate acquisition
+      status: this.getStatus(),
+      timestamp: acquiredAt
+    });
+    return {
+      provider,
+      release,
+      acquiredAt
+    };
+  }
+  /**
+   * Get current resource status
+   *
+   * @returns Current utilization across all providers
+   */
+  getStatus() {
+    const timestamp = Date.now();
+    const providers = {};
+    const providerIds = Array.from(this.providerLimits.keys());
+    for (const provider of providerIds) {
+      const limit = this.getEffectiveProviderLimit(provider);
+      const active = this.providerActiveCounts.get(provider) ?? 0;
+      const queued = this.queue.reduce((count, entry) => {
+        if (entry.providers && entry.providers.length > 0) {
+          return count + entry.providers.filter((p) => p === provider).length;
+        }
+        return count + (entry.provider === provider ? 1 : 0);
+      }, 0);
+      const utilization = limit > 0 ? Math.round(active / limit * 100) : 0;
+      const available = Math.max(0, limit - active);
+      providers[provider] = {
+        provider,
+        active,
+        queued,
+        max: limit,
+        utilization,
+        available
+      };
+    }
+    const globalUtilization = this.globalMaxConcurrent > 0 ? Math.round(this.globalActiveCount / this.globalMaxConcurrent * 100) : 0;
+    const globalAvailable = Math.max(0, this.globalMaxConcurrent - this.globalActiveCount);
+    return {
+      global: {
+        active: this.globalActiveCount,
+        queued: this.queue.length,
+        max: this.globalMaxConcurrent,
+        utilization: globalUtilization,
+        available: globalAvailable,
+        baselineMax: this.configuredGlobalMaxConcurrent
+      },
+      backpressure: {
+        active: this.lastBackpressureDecision.backpressureActive,
+        recommendedGlobalConcurrency: this.lastBackpressureDecision.recommendedGlobalConcurrency,
+        configuredGlobalConcurrency: this.configuredGlobalMaxConcurrent,
+        evaluatedAt: this.lastBackpressureUpdatedAt,
+        reason: this.lastBackpressureDecision.reason,
+        pressureLevel: this.lastBackpressureDecision.pressureLevel
+      },
+      providers,
+      fairnessMode: this.fairnessMode,
+      timestamp
+    };
+  }
+  /**
+   * Get queue depth and estimated wait time for a provider
+   *
+   * Estimates are best-effort and intended for fail-fast routing decisions.
+   */
+  getQueueStatus(provider) {
+    const providerQueued = this.queue.reduce((count, entry) => {
+      if (entry.providers && entry.providers.length > 0) {
+        return count + entry.providers.filter((p) => p === provider).length;
+      }
+      return count + (entry.provider === provider ? 1 : 0);
+    }, 0);
+    const providerActive = this.providerActiveCounts.get(provider) ?? 0;
+    const providerMax = this.getEffectiveProviderLimit(provider);
+    const avgProviderHoldMs = Math.max(1e3, this.providerAvgHoldMs.get(provider) ?? 6e4);
+    const globalQueued = this.queue.length;
+    const globalActive = this.globalActiveCount;
+    const globalMax = this.globalMaxConcurrent;
+    const avgGlobalHoldMs = Math.max(1e3, this.globalAvgHoldMs);
+    const providerWaves = providerQueued <= 0 ? 0 : Math.ceil(providerQueued / Math.max(1, providerMax));
+    const providerWaitMs = providerWaves * Math.ceil(avgProviderHoldMs / Math.max(1, providerMax));
+    const globalWaves = globalQueued <= 0 ? 0 : Math.ceil(globalQueued / Math.max(1, globalMax));
+    const globalWaitMs = globalWaves * Math.ceil(avgGlobalHoldMs / Math.max(1, globalMax));
+    return {
+      provider,
+      queued: providerQueued,
+      active: providerActive,
+      max: providerMax,
+      estimatedWaitMs: Math.max(providerWaitMs, globalWaitMs),
+      globalQueued,
+      globalActive,
+      globalMax
+    };
+  }
+  /**
+   * Update provider-specific concurrency baseline dynamically
+   *
+   * Useful for runtime tuning based on observed performance. The new value is
+   * authoritative in both directions, still bounded by any correctness ceiling
+   * (`providerHardCaps`) and by live rate-limit penalties.
+   *
+   * @param provider - Provider ID
+   * @param newLimit - New concurrency limit (must be >= 1)
+   *
+   * @example
+   * ```typescript
+   * // Raise Cursor capacity after validating host resources
+   * manager.updateProviderLimit('cursor', 3);
+   * ```
+   */
+  updateProviderLimit(provider, newLimit) {
+    if (newLimit < 1) {
+      throw new Error(`Invalid limit for ${provider}: ${newLimit} (must be >= 1)`);
+    }
+    const previousEffective = this.getEffectiveProviderLimit(provider);
+    this.providerLimits.set(provider, newLimit);
+    if (this.getEffectiveProviderLimit(provider) > previousEffective) {
+      this.processQueue();
+    }
+  }
+  /**
+   * Update the global concurrency limit.
+   *
+   * This is intentionally non-preemptive: active work continues, and the new
+   * limit only affects future acquisitions and queue draining.
+   */
+  updateGlobalLimit(newLimit) {
+    if (newLimit < 1) {
+      throw new Error(`Invalid global limit: ${newLimit} (must be >= 1)`);
+    }
+    const nextLimit = Math.max(
+      1,
+      Math.min(this.configuredGlobalMaxConcurrent, Math.floor(newLimit))
+    );
+    const previousLimit = this.globalMaxConcurrent;
+    if (nextLimit === previousLimit) {
+      return;
+    }
+    this.globalMaxConcurrent = nextLimit;
+    this.lastBackpressureUpdatedAt = Date.now();
+    const decision = {
+      recommendedGlobalConcurrency: nextLimit,
+      backpressureActive: nextLimit < this.configuredGlobalMaxConcurrent,
+      reason: nextLimit < previousLimit ? "concurrency reduced by backpressure" : "concurrency increased after recovery",
+      pressureLevel: nextLimit < previousLimit ? nextLimit <= Math.max(1, Math.floor(previousLimit / 2)) ? "critical" : "backpressure" : nextLimit === this.configuredGlobalMaxConcurrent ? "healthy" : "watch"
+    };
+    this.lastBackpressureDecision = decision;
+    if (nextLimit > previousLimit) {
+      this.processQueue();
+    }
+  }
+  /**
+   * Evaluate and apply the current backpressure policy.
+   *
+   * Returns the decision so callers can log or persist the same signal that
+   * was applied to the manager.
+   */
+  applyBackpressure(snapshot) {
+    const decision = recommendGlobalConcurrency(snapshot);
+    const previousLimit = this.globalMaxConcurrent;
+    if (decision.recommendedGlobalConcurrency !== previousLimit) {
+      this.updateGlobalLimit(decision.recommendedGlobalConcurrency);
+      this.lastBackpressureDecision = decision;
+      this.lastBackpressureUpdatedAt = Date.now();
+      this.emitTelemetry({
+        type: decision.backpressureActive ? "backpressure_active" : decision.recommendedGlobalConcurrency === this.configuredGlobalMaxConcurrent ? "backpressure_released" : "concurrency_adjusted",
+        provider: "system",
+        status: this.getStatus(),
+        timestamp: Date.now(),
+        snapshot,
+        previousGlobalConcurrency: previousLimit,
+        recommendedGlobalConcurrency: decision.recommendedGlobalConcurrency,
+        appliedGlobalConcurrency: this.globalMaxConcurrent,
+        reason: decision.reason,
+        backpressureActive: decision.backpressureActive
+      });
+      return decision;
+    }
+    this.lastBackpressureDecision = decision;
+    this.lastBackpressureUpdatedAt = Date.now();
+    return decision;
+  }
+  /**
+   * Register a telemetry hook
+   *
+   * @param hook - Callback function for telemetry events
+   *
+   * @example
+   * ```typescript
+   * manager.onTelemetry((event) => {
+   *   console.log(`[${event.type}] ${event.provider} - wait: ${event.waitTimeMs}ms`);
+   * });
+   * ```
+   */
+  onTelemetry(hook) {
+    this.telemetryHooks.push(hook);
+  }
+  /**
+   * Reset the manager (for testing or recovery)
+   *
+   * WARNING: Only use when you're sure no executions are running
+   */
+  reset() {
+    if (this.globalActiveCount > 0 || this.queue.length > 0) {
+      console.warn(
+        `[ProviderAwareResourceManager] reset() called with ${this.globalActiveCount} active slots and ${this.queue.length} queued requests \u2014 potential race condition`
+      );
+    }
+    const queuedEntries = this.queue.splice(0);
+    for (const entry of queuedEntries) {
+      entry.reject(new Error("Resource acquisition cancelled by manager reset"));
+    }
+    this.globalActiveCount = 0;
+    this.globalMaxConcurrent = this.configuredGlobalMaxConcurrent;
+    this.lastBackpressureUpdatedAt = Date.now();
+    this.lastBackpressureDecision = {
+      recommendedGlobalConcurrency: this.configuredGlobalMaxConcurrent,
+      backpressureActive: false,
+      reason: "reset to baseline",
+      pressureLevel: "healthy"
+    };
+    this.globalAvgHoldMs = 6e4;
+    const providerIds = Array.from(this.providerActiveCounts.keys());
+    for (const provider of providerIds) {
+      this.providerActiveCounts.set(provider, 0);
+      this.providerUsageHistory.set(provider, 0);
+      this.providerAvgHoldMs.set(provider, 6e4);
+    }
+    this.lastProviderServiced = null;
+  }
+  // ============================================================================
+  // Private Methods
+  // ============================================================================
+  /**
+   * Configured baseline max for a provider (not temporary effective/penalty),
+   * bounded by any correctness ceiling.
+   *
+   * The hard cap is applied here — not only in getEffectiveProviderLimit — so
+   * group reservation (clampProvidersToBaselineCapacity) never reserves slots
+   * that acquisition can never grant, which would queue a group until timeout.
+   */
+  getConfiguredProviderBaseline(provider) {
+    const baseline = this.providerLimits.get(provider) ?? getProviderConcurrencyBaseline(provider);
+    const hardCap = this.providerHardCaps.get(provider);
+    return hardCap === void 0 ? baseline : Math.min(baseline, hardCap);
+  }
+  /**
+   * Clamp an outer competition reservation to configured baselines so oversized
+   * variant lists remain runnable. Overflow beyond the clamp is not reserved
+   * (callers serialize that work). Never produces a group larger than baseline
+   * global or per-provider capacity.
+   *
+   * - Per provider: at most configured baseline slots (order preserved)
+   * - Total: at most configured global max
+   * - Each reserved entry keeps its actual provider association
+   */
+  clampProvidersToBaselineCapacity(providers) {
+    const globalMax = this.configuredGlobalMaxConcurrent;
+    const perProviderTaken = /* @__PURE__ */ new Map();
+    const clamped = [];
+    for (const provider of providers) {
+      if (clamped.length >= globalMax) {
+        break;
+      }
+      const baseline = Math.max(0, this.getConfiguredProviderBaseline(provider));
+      const taken = perProviderTaken.get(provider) ?? 0;
+      if (taken >= baseline) {
+        continue;
+      }
+      clamped.push(provider);
+      perProviderTaken.set(provider, taken + 1);
+    }
+    return clamped;
+  }
+  /**
+   * Whether the full group fits current effective capacity without taking any slots.
+   */
+  canGrantGroup(providers) {
+    let simulatedGlobal = this.globalActiveCount;
+    const simulatedProvider = new Map(this.providerActiveCounts);
+    for (const provider of providers) {
+      const providerLimit = this.getEffectiveProviderLimit(provider);
+      const providerActive = simulatedProvider.get(provider) ?? 0;
+      if (providerActive >= providerLimit) {
+        return false;
+      }
+      if (simulatedGlobal >= this.globalMaxConcurrent) {
+        return false;
+      }
+      simulatedProvider.set(provider, providerActive + 1);
+      simulatedGlobal += 1;
+    }
+    return true;
+  }
+  /**
+   * Atomically grant every slot in the group, or return null without holding any.
+   * Never leaves partial holds.
+   */
+  tryAcquireGroup(providers, waitTimeMs = 0) {
+    if (!this.canGrantGroup(providers)) {
+      return null;
+    }
+    const acquiredAt = Date.now();
+    const handles = [];
+    for (const provider of providers) {
+      this.globalActiveCount++;
+      const providerActive = this.providerActiveCounts.get(provider) ?? 0;
+      this.providerActiveCounts.set(provider, providerActive + 1);
+      this.updateUsageHistory(provider);
+      let released = false;
+      const release = async () => {
+        if (released) {
+          return;
+        }
+        released = true;
+        await this.releaseInternal(provider, acquiredAt);
+      };
+      handles.push({
+        provider,
+        release,
+        acquiredAt
+      });
+      this.emitTelemetry({
+        type: "resource_acquired",
+        provider,
+        waitTimeMs,
+        status: this.getStatus(),
+        timestamp: acquiredAt
+      });
+    }
+    return handles;
+  }
+  /**
+   * Internal release implementation
+   */
+  async releaseInternal(provider, acquiredAt) {
+    const currentActive = this.providerActiveCounts.get(provider) ?? 0;
+    if (currentActive <= 0) {
+      throw new Error(
+        `Cannot release ${provider} - no active executions (possible double-release)`
+      );
+    }
+    if (this.globalActiveCount <= 0) {
+      throw new Error("Cannot release - no global active executions (possible double-release)");
+    }
+    this.globalActiveCount--;
+    this.providerActiveCounts.set(provider, currentActive - 1);
+    const holdTimeMs = Date.now() - acquiredAt;
+    this.updateHoldTimeEstimates(provider, holdTimeMs);
+    this.emitTelemetry({
+      type: "resource_released",
+      provider,
+      waitTimeMs: holdTimeMs,
+      status: this.getStatus(),
+      timestamp: Date.now()
+    });
+    this.processQueue();
+  }
+  /**
+   * Effective per-provider capacity for the next acquisition decision.
+   *
+   * Composed rather than minimum-clamped, because the three inputs answer three
+   * different questions and only one of them is an upper bound on operator
+   * intent:
+   *
+   *   baseline  — configured capacity for THIS host (override, else shipped
+   *               default). An override replaces the default in both directions;
+   *               clamping it downward against the default is what previously
+   *               made every host overlay and `--provider-limit` inert.
+   *   hard cap  — correctness ceiling (concurrency would be unsafe, not merely
+   *               expensive). Never raisable by configuration.
+   *   penalty   — live rate-limit throttle, one-way down, decays on its own.
+   *
+   * Penalty is applied to the capped baseline so an operator who raised capacity
+   * is still throttled proportionally by an observed 429 instead of having the
+   * override discarded outright.
+   */
+  getEffectiveProviderLimit(provider) {
+    return applyProviderConcurrencyPenalty(provider, this.getConfiguredProviderBaseline(provider));
+  }
+  /**
+   * Compute a queue-wait ceiling for a stage that is about to be enqueued for
+   * `provider`, given the number of same-provider stages dispatched together in
+   * the same wave (`coDispatchedCount`).
+   *
+   * A flat ceiling (e.g. one variant duration) false-fails the back of a large
+   * same-provider wave: with provider limit N and W co-dispatched stages, a
+   * stage at the back waits up to ceil(W / N) variant durations before it can
+   * even start. This scales the ceiling by that batch depth so a legitimately
+   * queued stage is not failed while earlier stages are still running, while
+   * still bounding the wait so a genuine leak/deadlock is eventually surfaced.
+   *
+   * @param perVariantMs The expected upper bound on a single variant's hold time.
+   * @param coDispatchedCount Number of stages (incl. this one) dispatched together for this provider.
+   * @param totalWaveCount Total stages dispatched together across ALL providers in this wave.
+   *   When omitted, defaults to coDispatchedCount (provider-only sizing).
+   */
+  computeQueueWaitCeilingMs(provider, perVariantMs, coDispatchedCount, totalWaveCount) {
+    const providerLimit = Math.max(1, this.getEffectiveProviderLimit(provider));
+    const globalLimit = Math.max(1, this.globalMaxConcurrent);
+    const providerWidth = Math.min(providerLimit, globalLimit);
+    const providerBatches = Math.ceil(Math.max(1, coDispatchedCount) / providerWidth);
+    const waveCount = Math.max(coDispatchedCount, totalWaveCount ?? coDispatchedCount);
+    const globalBatches = Math.ceil(Math.max(1, waveCount) / globalLimit);
+    const batches = Math.max(1, providerBatches, globalBatches);
+    return perVariantMs * (batches + 1);
+  }
+  updateHoldTimeEstimates(provider, holdTimeMs) {
+    const boundedHoldMs = Math.max(250, Math.min(holdTimeMs, 30 * 60 * 1e3));
+    const currentProviderAvg = this.providerAvgHoldMs.get(provider) ?? 6e4;
+    const nextProviderAvg = Math.round(
+      currentProviderAvg + this.holdTimeEwmaAlpha * (boundedHoldMs - currentProviderAvg)
+    );
+    this.providerAvgHoldMs.set(provider, nextProviderAvg);
+    this.globalAvgHoldMs = Math.round(
+      this.globalAvgHoldMs + this.holdTimeEwmaAlpha * (boundedHoldMs - this.globalAvgHoldMs)
+    );
+  }
+  /**
+   * Process the queue based on fairness mode
+   *
+   * Attempts to satisfy queued acquisitions in priority order.
+   * Single entries use tryAcquire; group entries are granted only when the
+   * full group fits (atomic, no partial holds). Runs synchronously to prevent
+   * race conditions.
+   */
+  processQueue() {
+    if (this.queue.length === 0) {
+      return;
+    }
+    let madeProgress = true;
+    while (madeProgress && this.queue.length > 0) {
+      madeProgress = false;
+      this.sortQueueByFairness();
+      for (let index = 0; index < this.queue.length; ) {
+        const entry = this.queue[index];
+        if (!entry) {
+          this.queue.splice(index, 1);
+          madeProgress = true;
+          continue;
+        }
+        if (entry.signal?.aborted) {
+          this.queue.splice(index, 1);
+          entry.reject(new Error("Acquisition aborted while queued"));
+          madeProgress = true;
+          continue;
+        }
+        if (entry.providers && entry.providers.length > 0 && entry.resolveGroup) {
+          const waitTimeMs = Date.now() - entry.queuedAt;
+          const handles = this.tryAcquireGroup(entry.providers, waitTimeMs);
+          if (handles) {
+            this.queue.splice(index, 1);
+            entry.resolveGroup(handles);
+            madeProgress = true;
+            if (this.globalActiveCount >= this.globalMaxConcurrent) {
+              return;
+            }
+            continue;
+          }
+          index++;
+          continue;
+        }
+        const handle = this.tryAcquire(entry.provider);
+        if (handle) {
+          this.queue.splice(index, 1);
+          entry.resolve(handle);
+          madeProgress = true;
+          if (this.globalActiveCount >= this.globalMaxConcurrent) {
+            return;
+          }
+          continue;
+        }
+        index++;
+      }
+    }
+  }
+  /**
+   * Sort queue based on fairness mode
+   */
+  sortQueueByFairness() {
+    switch (this.fairnessMode) {
+      case "fifo":
+        break;
+      case "weighted-fair": {
+        this.queue.sort((a, b) => {
+          const weightDiff = (a.weight ?? 0) - (b.weight ?? 0);
+          if (weightDiff !== 0) return weightDiff;
+          return a.queuedAt - b.queuedAt;
+        });
+        break;
+      }
+      case "strict-fair": {
+        if (this.lastProviderServiced) {
+          const lastProviderEntries = this.queue.filter(
+            (e) => e.provider === this.lastProviderServiced
+          );
+          const otherEntries = this.queue.filter((e) => e.provider !== this.lastProviderServiced);
+          this.queue.length = 0;
+          this.queue.push(...otherEntries, ...lastProviderEntries);
+        }
+        break;
+      }
+    }
+  }
+  /**
+   * Calculate weight for weighted-fair scheduling
+   *
+   * Lower weight = higher priority
+   * Providers with less recent usage get lower weights (higher priority)
+   */
+  calculateWeight(provider) {
+    const usage = this.providerUsageHistory.get(provider) ?? 0;
+    const totalUsage = Array.from(this.providerUsageHistory.values()).reduce(
+      (sum, count) => sum + count,
+      0
+    );
+    if (totalUsage === 0) return 0;
+    return Math.round(usage / totalUsage * 100);
+  }
+  /**
+   * Update usage history for weighted-fair mode
+   */
+  updateUsageHistory(provider) {
+    const current = this.providerUsageHistory.get(provider) ?? 0;
+    this.providerUsageHistory.set(provider, current + 1);
+    this.lastProviderServiced = provider;
+    const usageCounts = Array.from(this.providerUsageHistory.values());
+    const totalUsage = usageCounts.reduce((sum, count) => sum + count, 0);
+    if (totalUsage > this.usageHistoryWindow) {
+      const providerIds = Array.from(this.providerUsageHistory.keys());
+      for (const p of providerIds) {
+        const count = this.providerUsageHistory.get(p) ?? 0;
+        this.providerUsageHistory.set(
+          p,
+          Math.floor(count * this.usageHistoryWindow / totalUsage)
+        );
+      }
+    }
+  }
+  /**
+   * Emit telemetry event to registered hooks
+   */
+  emitTelemetry(event) {
+    if (!this.enableTelemetry) return;
+    for (const hook of this.telemetryHooks) {
+      try {
+        hook(event);
+      } catch (error) {
+        console.error("[ProviderAwareResourceManager] Telemetry hook error:", error);
+      }
+    }
+  }
+};
+function getDynamicGlobalConcurrency() {
+  const totalMemoryGB = totalmem() / 1024 ** 3;
+  const envTier = process.env.POETIC_RESOURCE_TIER;
+  let tier;
+  if (envTier && ["minimal", "standard", "performance", "power", "ultra"].includes(envTier)) {
+    tier = envTier;
+  } else if (totalMemoryGB < 8) {
+    tier = "minimal";
+  } else if (totalMemoryGB < 16) {
+    tier = "standard";
+  } else if (totalMemoryGB < 32) {
+    tier = "performance";
+  } else if (totalMemoryGB < 64) {
+    tier = "power";
+  } else {
+    tier = "ultra";
+  }
+  const limits = {
+    minimal: 8,
+    standard: 15,
+    performance: 25,
+    power: 40,
+    ultra: 50
+  };
+  return limits[tier];
+}
+function createProviderAwareResourceManager(config) {
+  return new ProviderAwareResourceManager(config);
+}
+function createDynamicResourceManager(configOverrides) {
+  const dynamicGlobalLimit = getDynamicGlobalConcurrency();
+  const config = {
+    globalMaxConcurrent: configOverrides?.globalMaxConcurrent ?? dynamicGlobalLimit,
+    fairnessMode: configOverrides?.fairnessMode ?? "weighted-fair",
+    enableTelemetry: configOverrides?.enableTelemetry ?? true,
+    providerLimits: configOverrides?.providerLimits,
+    // Correctness ceilings must never be silently dropped on the way through a
+    // factory: providerLimits is authoritative, so losing the caps here would
+    // let an override raise a provider past a safety boundary.
+    providerHardCaps: configOverrides?.providerHardCaps
+  };
+  return new ProviderAwareResourceManager(config);
+}
+var DEFAULT_GLOBAL_CONCURRENCY = getDynamicGlobalConcurrency();
+
+export {
+  captureConcurrencyBackpressureSnapshot,
+  ProviderAwareResourceManager,
+  createProviderAwareResourceManager,
+  createDynamicResourceManager,
+  DEFAULT_GLOBAL_CONCURRENCY
+};
+//# sourceMappingURL=chunk-L7E6XCRA.js.map