kiro-spec-engine 1.47.10 → 1.47.14

package/README.md

@@ -413,6 +413,12 @@ Tip: `kse spec bootstrap|pipeline run|gate run --specs ...` now defaults to this
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
@@ -420,6 +426,7 @@ Tip: `kse spec bootstrap|pipeline run|gate run --specs ...` now defaults to this
 ```
 
 If Codex CLI is globally installed, you can set `"codexCommand": "codex"`.
+Use the `rateLimit*` settings to absorb transient 429/too-many-requests failures without stalling orchestration.
 
 ### Spec-Level Steering & Context Sync 🚀 NEW in v1.44.0
 - **Spec Steering (L4)**: Independent `steering.md` per Spec with constraints, notes, and decisions — zero cross-agent conflict

package/README.zh.md

@@ -367,6 +367,12 @@ kse orchestrate stop
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
@@ -374,6 +380,7 @@ kse orchestrate stop
 ```
 
 如果你已全局安装 Codex CLI，可将 `"codexCommand"` 改为 `"codex"`。
+可通过 `rateLimit*` 配置吸收 429/too-many-requests 等限流抖动，避免编排流程卡死。
 
 ### Spec 级 Steering 与上下文同步 🚀 v1.44.0 新增
 - **Spec Steering (L4)**: 每个 Spec 独立的 `steering.md`，包含约束、注意事项、决策记录 — 跨 Agent 零冲突

package/docs/command-reference.md

@@ -787,12 +787,20 @@ Recommended `.kiro/config/orchestrator.json`:
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitMaxRetries": 6,
+  "rateLimitBackoffBaseMs": 1000,
+  "rateLimitBackoffMaxMs": 30000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 30000,
   "apiKeyEnvVar": "CODEX_API_KEY",
   "codexArgs": ["--skip-git-repo-check"],
   "codexCommand": "npx @openai/codex"
 }
 ```
 
+`rateLimit*` settings provide dedicated retry/backoff and adaptive parallel throttling when providers return 429 / too-many-requests errors.
+
 ### Scene Template Engine
 
 ```bash

package/lib/commands/orchestrate.js

@@ -124,6 +124,9 @@ async function runOrchestration(options = {}, dependencies = {}) {
     'spec:start',
     'spec:complete',
     'spec:failed',
+    'spec:rate-limited',
+    'parallel:throttled',
+    'parallel:recovered',
     'orchestration:complete'
   ];
 
@@ -322,6 +325,17 @@ function _printStatus(status) {
   if (status.currentBatch !== undefined && status.totalBatches !== undefined) {
     console.log(`Batch: ${status.currentBatch} / ${status.totalBatches}`);
   }
+  if (status.parallel) {
+    const effective = status.parallel.effectiveMaxParallel ?? '-';
+    const max = status.parallel.maxParallel ?? '-';
+    const adaptive = status.parallel.adaptive === false ? 'off' : 'on';
+    console.log(`Parallel: ${effective} / ${max} (adaptive: ${adaptive})`);
+  }
+  if (status.rateLimit) {
+    const signals = status.rateLimit.signalCount || 0;
+    const backoff = status.rateLimit.totalBackoffMs || 0;
+    console.log(`Rate-limit: ${signals} signal(s), total backoff ${backoff}ms`);
+  }
   if (status.specs) {
     console.log('');
     for (const [name, info] of Object.entries(status.specs)) {

package/lib/orchestrator/orchestration-engine.js

@@ -16,6 +16,23 @@ const path = require('path');
 const fsUtils = require('../utils/fs-utils');
 
 const SPECS_DIR = '.kiro/specs';
+const DEFAULT_RATE_LIMIT_MAX_RETRIES = 6;
+const DEFAULT_RATE_LIMIT_BACKOFF_BASE_MS = 1000;
+const DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS = 30000;
+const DEFAULT_RATE_LIMIT_ADAPTIVE_PARALLEL = true;
+const DEFAULT_RATE_LIMIT_PARALLEL_FLOOR = 1;
+const DEFAULT_RATE_LIMIT_COOLDOWN_MS = 30000;
+const RATE_LIMIT_BACKOFF_JITTER_RATIO = 0.5;
+const RATE_LIMIT_ERROR_PATTERNS = [
+  /(^|[^0-9])429([^0-9]|$)/i,
+  /too many requests/i,
+  /rate[\s-]?limit/i,
+  /resource exhausted/i,
+  /quota exceeded/i,
+  /exceeded.*quota/i,
+  /requests per minute/i,
+  /tokens per minute/i,
+];
 
 class OrchestrationEngine extends EventEmitter {
   /**
@@ -54,6 +71,28 @@ class OrchestrationEngine extends EventEmitter {
     this._stopped = false;
     /** @type {object|null} execution plan */
     this._executionPlan = null;
+    /** @type {number} max retries for rate-limit failures */
+    this._rateLimitMaxRetries = DEFAULT_RATE_LIMIT_MAX_RETRIES;
+    /** @type {number} base delay for rate-limit retries */
+    this._rateLimitBackoffBaseMs = DEFAULT_RATE_LIMIT_BACKOFF_BASE_MS;
+    /** @type {number} max delay for rate-limit retries */
+    this._rateLimitBackoffMaxMs = DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS;
+    /** @type {boolean} enable adaptive parallel throttling on rate-limit signals */
+    this._rateLimitAdaptiveParallel = DEFAULT_RATE_LIMIT_ADAPTIVE_PARALLEL;
+    /** @type {number} minimum effective parallelism during rate-limit cooldown */
+    this._rateLimitParallelFloor = DEFAULT_RATE_LIMIT_PARALLEL_FLOOR;
+    /** @type {number} cooldown before each adaptive parallel recovery step */
+    this._rateLimitCooldownMs = DEFAULT_RATE_LIMIT_COOLDOWN_MS;
+    /** @type {number|null} configured max parallel for current run */
+    this._baseMaxParallel = null;
+    /** @type {number|null} dynamic effective parallel limit for current run */
+    this._effectiveMaxParallel = null;
+    /** @type {number} timestamp after which recovery can step up */
+    this._rateLimitCooldownUntil = 0;
+    /** @type {() => number} */
+    this._random = typeof options.random === 'function' ? options.random : Math.random;
+    /** @type {() => number} */
+    this._now = typeof options.now === 'function' ? options.now : Date.now;
   }
 
   // ---------------------------------------------------------------------------
@@ -135,8 +174,10 @@ class OrchestrationEngine extends EventEmitter {
 
       // Get config for maxParallel and maxRetries
       const config = await this._orchestratorConfig.getConfig();
+      this._applyRetryPolicyConfig(config);
       const maxParallel = options.maxParallel || config.maxParallel || 3;
       const maxRetries = config.maxRetries || 2;
+      this._initializeAdaptiveParallel(maxParallel);
 
       // Step 5: Execute batches (Req 3.4)
       await this._executeBatches(batches, maxParallel, maxRetries);
@@ -250,7 +291,11 @@ class OrchestrationEngine extends EventEmitter {
     const inFlight = new Map(); // specName → Promise
 
     const launchNext = async () => {
-      while (pending.length > 0 && inFlight.size < maxParallel && !this._stopped) {
+      while (
+        pending.length > 0
+        && inFlight.size < this._getEffectiveMaxParallel(maxParallel)
+        && !this._stopped
+      ) {
         const specName = pending.shift();
         if (this._skippedSpecs.has(specName)) continue;
 
@@ -400,25 +445,53 @@ class OrchestrationEngine extends EventEmitter {
    * @private
    */
   async _handleSpecFailed(specName, agentId, maxRetries, error) {
+    const resolvedError = `${error || 'Unknown error'}`;
     const retryCount = this._retryCounts.get(specName) || 0;
+    const isRateLimitError = this._isRateLimitError(resolvedError);
+    const retryLimit = isRateLimitError
+      ? Math.max(maxRetries, this._rateLimitMaxRetries || DEFAULT_RATE_LIMIT_MAX_RETRIES)
+      : maxRetries;
 
-    if (retryCount < maxRetries && !this._stopped) {
+    if (retryCount < retryLimit && !this._stopped) {
       // Retry (Req 5.2)
       this._retryCounts.set(specName, retryCount + 1);
       this._statusMonitor.incrementRetry(specName);
-      this._statusMonitor.updateSpecStatus(specName, 'pending', null, error);
+      this._statusMonitor.updateSpecStatus(specName, 'pending', null, resolvedError);
+
+      const retryDelayMs = isRateLimitError
+        ? this._calculateRateLimitBackoffMs(retryCount)
+        : 0;
+      if (retryDelayMs > 0) {
+        this._onRateLimitSignal();
+        this._updateStatusMonitorRateLimit({
+          specName,
+          retryCount,
+          retryDelayMs,
+          error: resolvedError,
+        });
+        this.emit('spec:rate-limited', {
+          specName,
+          retryCount,
+          retryDelayMs,
+          error: resolvedError,
+        });
+        await this._sleep(retryDelayMs);
+        if (this._stopped) {
+          return;
+        }
+      }
 
       // Re-execute
       await this._executeSpec(specName, maxRetries);
     } else {
       // Final failure (Req 5.3)
       this._failedSpecs.add(specName);
-      this._statusMonitor.updateSpecStatus(specName, 'failed', agentId, error);
+      this._statusMonitor.updateSpecStatus(specName, 'failed', agentId, resolvedError);
 
       // Sync external status
       await this._syncExternalSafe(specName, 'failed');
 
-      this.emit('spec:failed', { specName, agentId, error, retryCount });
+      this.emit('spec:failed', { specName, agentId, error: resolvedError, retryCount });
 
       // Propagate failure to dependents (Req 3.6)
       this._propagateFailure(specName);
@@ -537,6 +610,315 @@ class OrchestrationEngine extends EventEmitter {
   // Validation & Helpers
   // ---------------------------------------------------------------------------
 
+  /**
+   * Resolve retry-related runtime config with safe defaults.
+   *
+   * @param {object} config
+   * @private
+   */
+  _applyRetryPolicyConfig(config) {
+    this._rateLimitMaxRetries = this._toNonNegativeInteger(
+      config && config.rateLimitMaxRetries,
+      DEFAULT_RATE_LIMIT_MAX_RETRIES
+    );
+
+    const baseMs = this._toPositiveInteger(
+      config && config.rateLimitBackoffBaseMs,
+      DEFAULT_RATE_LIMIT_BACKOFF_BASE_MS
+    );
+    const maxMs = this._toPositiveInteger(
+      config && config.rateLimitBackoffMaxMs,
+      DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS
+    );
+
+    this._rateLimitBackoffBaseMs = Math.min(baseMs, maxMs);
+    this._rateLimitBackoffMaxMs = Math.max(baseMs, maxMs);
+    this._rateLimitAdaptiveParallel = this._toBoolean(
+      config && config.rateLimitAdaptiveParallel,
+      DEFAULT_RATE_LIMIT_ADAPTIVE_PARALLEL
+    );
+    this._rateLimitParallelFloor = this._toPositiveInteger(
+      config && config.rateLimitParallelFloor,
+      DEFAULT_RATE_LIMIT_PARALLEL_FLOOR
+    );
+    this._rateLimitCooldownMs = this._toPositiveInteger(
+      config && config.rateLimitCooldownMs,
+      DEFAULT_RATE_LIMIT_COOLDOWN_MS
+    );
+  }
+
+  /**
+   * @param {number} maxParallel
+   * @private
+   */
+  _initializeAdaptiveParallel(maxParallel) {
+    const boundedMax = this._toPositiveInteger(maxParallel, 1);
+    this._baseMaxParallel = boundedMax;
+    this._effectiveMaxParallel = boundedMax;
+    this._rateLimitCooldownUntil = 0;
+    this._updateStatusMonitorParallelTelemetry({
+      adaptive: this._isAdaptiveParallelEnabled(),
+      maxParallel: boundedMax,
+      effectiveMaxParallel: boundedMax,
+      floor: Math.min(
+        boundedMax,
+        this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
+      ),
+    });
+  }
+
+  /**
+   * @param {number} maxParallel
+   * @returns {number}
+   * @private
+   */
+  _getEffectiveMaxParallel(maxParallel) {
+    const boundedMax = this._toPositiveInteger(maxParallel, 1);
+    const floor = Math.min(
+      boundedMax,
+      this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
+    );
+
+    if (!this._isAdaptiveParallelEnabled()) {
+      this._baseMaxParallel = boundedMax;
+      this._effectiveMaxParallel = boundedMax;
+      this._updateStatusMonitorParallelTelemetry({
+        adaptive: false,
+        maxParallel: boundedMax,
+        effectiveMaxParallel: boundedMax,
+        floor,
+      });
+      return boundedMax;
+    }
+
+    this._baseMaxParallel = boundedMax;
+    this._maybeRecoverParallelLimit(boundedMax);
+
+    const effective = this._toPositiveInteger(this._effectiveMaxParallel, boundedMax);
+    const resolved = Math.max(floor, Math.min(boundedMax, effective));
+    this._updateStatusMonitorParallelTelemetry({
+      adaptive: true,
+      maxParallel: boundedMax,
+      effectiveMaxParallel: resolved,
+      floor,
+    });
+    return resolved;
+  }
+
+  /**
+   * @private
+   */
+  _onRateLimitSignal() {
+    if (!this._isAdaptiveParallelEnabled()) {
+      return;
+    }
+
+    const base = this._toPositiveInteger(this._baseMaxParallel, 1);
+    const current = this._toPositiveInteger(this._effectiveMaxParallel, base);
+    const floor = Math.min(
+      base,
+      this._toPositiveInteger(this._rateLimitParallelFloor, DEFAULT_RATE_LIMIT_PARALLEL_FLOOR)
+    );
+    const next = Math.max(floor, Math.floor(current / 2));
+
+    if (next < current) {
+      this._effectiveMaxParallel = next;
+      this._updateStatusMonitorParallelTelemetry({
+        event: 'throttled',
+        reason: 'rate-limit',
+        adaptive: true,
+        maxParallel: base,
+        effectiveMaxParallel: next,
+        floor,
+      });
+      this.emit('parallel:throttled', {
+        reason: 'rate-limit',
+        previousMaxParallel: current,
+        effectiveMaxParallel: next,
+        floor,
+      });
+    } else {
+      this._effectiveMaxParallel = current;
+    }
+
+    this._rateLimitCooldownUntil = this._getNow() + this._rateLimitCooldownMs;
+  }
+
+  /**
+   * @param {number} maxParallel
+   * @private
+   */
+  _maybeRecoverParallelLimit(maxParallel) {
+    if (!this._isAdaptiveParallelEnabled()) {
+      return;
+    }
+
+    const boundedMax = this._toPositiveInteger(maxParallel, 1);
+    const current = this._toPositiveInteger(this._effectiveMaxParallel, boundedMax);
+    if (current >= boundedMax) {
+      this._effectiveMaxParallel = boundedMax;
+      return;
+    }
+
+    if (this._getNow() < this._rateLimitCooldownUntil) {
+      return;
+    }
+
+    const next = Math.min(boundedMax, current + 1);
+    if (next > current) {
+      this._effectiveMaxParallel = next;
+      this._rateLimitCooldownUntil = this._getNow() + this._rateLimitCooldownMs;
+      this._updateStatusMonitorParallelTelemetry({
+        event: 'recovered',
+        adaptive: true,
+        maxParallel: boundedMax,
+        effectiveMaxParallel: next,
+      });
+      this.emit('parallel:recovered', {
+        previousMaxParallel: current,
+        effectiveMaxParallel: next,
+        maxParallel: boundedMax,
+      });
+    }
+  }
+
+  /**
+   * @returns {boolean}
+   * @private
+   */
+  _isAdaptiveParallelEnabled() {
+    if (typeof this._rateLimitAdaptiveParallel === 'boolean') {
+      return this._rateLimitAdaptiveParallel;
+    }
+    return DEFAULT_RATE_LIMIT_ADAPTIVE_PARALLEL;
+  }
+
+  /**
+   * @returns {number}
+   * @private
+   */
+  _getNow() {
+    return typeof this._now === 'function' ? this._now() : Date.now();
+  }
+
+  /**
+   * @param {any} value
+   * @param {boolean} fallback
+   * @returns {boolean}
+   * @private
+   */
+  _toBoolean(value, fallback) {
+    if (typeof value === 'boolean') {
+      return value;
+    }
+    return fallback;
+  }
+
+  /**
+   * @param {any} value
+   * @param {number} fallback
+   * @returns {number}
+   * @private
+   */
+  _toPositiveInteger(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric <= 0) {
+      return fallback;
+    }
+    return Math.floor(numeric);
+  }
+
+  /**
+   * @param {any} value
+   * @param {number} fallback
+   * @returns {number}
+   * @private
+   */
+  _toNonNegativeInteger(value, fallback) {
+    const numeric = Number(value);
+    if (!Number.isFinite(numeric) || numeric < 0) {
+      return fallback;
+    }
+    return Math.floor(numeric);
+  }
+
+  /**
+   * @param {string} error
+   * @returns {boolean}
+   * @private
+   */
+  _isRateLimitError(error) {
+    return RATE_LIMIT_ERROR_PATTERNS.some(pattern => pattern.test(`${error || ''}`));
+  }
+
+  /**
+   * @param {number} retryCount
+   * @returns {number}
+   * @private
+   */
+  _calculateRateLimitBackoffMs(retryCount) {
+    const exponent = Math.max(0, retryCount);
+    const cappedBaseDelay = Math.min(
+      this._rateLimitBackoffMaxMs || DEFAULT_RATE_LIMIT_BACKOFF_MAX_MS,
+      (this._rateLimitBackoffBaseMs || DEFAULT_RATE_LIMIT_BACKOFF_BASE_MS) * (2 ** exponent)
+    );
+
+    const randomValue = typeof this._random === 'function' ? this._random() : Math.random();
+    const normalizedRandom = Number.isFinite(randomValue)
+      ? Math.min(1, Math.max(0, randomValue))
+      : 0.5;
+    const jitterFactor = (1 - RATE_LIMIT_BACKOFF_JITTER_RATIO)
+      + (normalizedRandom * RATE_LIMIT_BACKOFF_JITTER_RATIO);
+
+    return Math.max(1, Math.round(cappedBaseDelay * jitterFactor));
+  }
+
+  /**
+   * @param {number} ms
+   * @returns {Promise<void>}
+   * @private
+   */
+  _sleep(ms) {
+    if (!ms || ms <= 0) {
+      return Promise.resolve();
+    }
+    return new Promise((resolve) => setTimeout(resolve, ms));
+  }
+
+  /**
+   * Safely update StatusMonitor rate-limit telemetry.
+   *
+   * @param {object} payload
+   * @private
+   */
+  _updateStatusMonitorRateLimit(payload) {
+    const handler = this._statusMonitor && this._statusMonitor.recordRateLimitEvent;
+    if (typeof handler === 'function') {
+      try {
+        handler.call(this._statusMonitor, payload);
+      } catch (_err) {
+        // Non-fatal status telemetry update.
+      }
+    }
+  }
+
+  /**
+   * Safely update StatusMonitor adaptive parallel telemetry.
+   *
+   * @param {object} payload
+   * @private
+   */
+  _updateStatusMonitorParallelTelemetry(payload) {
+    const handler = this._statusMonitor && this._statusMonitor.updateParallelTelemetry;
+    if (typeof handler === 'function') {
+      try {
+        handler.call(this._statusMonitor, payload);
+      } catch (_err) {
+        // Non-fatal status telemetry update.
+      }
+    }
+  }
+
   /**
    * Validate that all spec directories exist (Req 6.4).
    *
@@ -625,6 +1007,9 @@ class OrchestrationEngine extends EventEmitter {
     this._completedSpecs.clear();
     this._executionPlan = null;
     this._stopped = false;
+    this._baseMaxParallel = null;
+    this._effectiveMaxParallel = null;
+    this._rateLimitCooldownUntil = 0;
   }
 }
 

package/lib/orchestrator/orchestrator-config.js

@@ -24,6 +24,12 @@ const KNOWN_KEYS = new Set([
   'maxParallel',
   'timeoutSeconds',
   'maxRetries',
+  'rateLimitMaxRetries',
+  'rateLimitBackoffBaseMs',
+  'rateLimitBackoffMaxMs',
+  'rateLimitAdaptiveParallel',
+  'rateLimitParallelFloor',
+  'rateLimitCooldownMs',
   'apiKeyEnvVar',
   'bootstrapTemplate',
   'codexArgs',
@@ -36,6 +42,12 @@ const DEFAULT_CONFIG = Object.freeze({
   maxParallel: 3,
   timeoutSeconds: 600,
   maxRetries: 2,
+  rateLimitMaxRetries: 6,
+  rateLimitBackoffBaseMs: 1000,
+  rateLimitBackoffMaxMs: 30000,
+  rateLimitAdaptiveParallel: true,
+  rateLimitParallelFloor: 1,
+  rateLimitCooldownMs: 30000,
   apiKeyEnvVar: 'CODEX_API_KEY',
   bootstrapTemplate: null,
   codexArgs: [],

package/lib/orchestrator/status-monitor.js

@@ -56,6 +56,37 @@ class StatusMonitor {
      * @type {Map<string, {status: string, batch: number, agentId: string|null, retryCount: number, error: string|null, turnCount: number}>}
      */
     this._specs = new Map();
+
+    /**
+     * Rate-limit telemetry summary.
+     * @type {{signalCount: number, retryCount: number, totalBackoffMs: number, lastSignalAt: string|null, lastSpecName: string|null, lastRetryCount: number, lastDelayMs: number, lastError: string|null}}
+     */
+    this._rateLimit = {
+      signalCount: 0,
+      retryCount: 0,
+      totalBackoffMs: 0,
+      lastSignalAt: null,
+      lastSpecName: null,
+      lastRetryCount: 0,
+      lastDelayMs: 0,
+      lastError: null,
+    };
+
+    /**
+     * Parallelism telemetry summary.
+     * @type {{adaptive: boolean|null, maxParallel: number|null, effectiveMaxParallel: number|null, floor: number|null, throttledCount: number, recoveredCount: number, lastReason: string|null, lastThrottledAt: string|null, lastRecoveredAt: string|null}}
+     */
+    this._parallel = {
+      adaptive: null,
+      maxParallel: null,
+      effectiveMaxParallel: null,
+      floor: null,
+      throttledCount: 0,
+      recoveredCount: 0,
+      lastReason: null,
+      lastThrottledAt: null,
+      lastRecoveredAt: null,
+    };
   }
 
   // ---------------------------------------------------------------------------
@@ -125,6 +156,80 @@ class StatusMonitor {
     }
   }
 
+  /**
+   * Record a rate-limit retry/backoff signal.
+   *
+   * @param {object} data
+   * @param {string} [data.specName]
+   * @param {number} [data.retryCount]
+   * @param {number} [data.retryDelayMs]
+   * @param {string} [data.error]
+   */
+  recordRateLimitEvent(data = {}) {
+    const delay = Number(data.retryDelayMs);
+    const retryCount = Number(data.retryCount);
+
+    this._rateLimit.signalCount++;
+    this._rateLimit.retryCount++;
+    this._rateLimit.totalBackoffMs += Number.isFinite(delay) && delay > 0 ? Math.round(delay) : 0;
+    this._rateLimit.lastSignalAt = new Date().toISOString();
+
+    if (typeof data.specName === 'string' && data.specName.trim()) {
+      this._rateLimit.lastSpecName = data.specName.trim();
+    }
+    if (Number.isFinite(retryCount) && retryCount >= 0) {
+      this._rateLimit.lastRetryCount = Math.floor(retryCount);
+    }
+    this._rateLimit.lastDelayMs = Number.isFinite(delay) && delay > 0 ? Math.round(delay) : 0;
+    if (data.error !== undefined && data.error !== null) {
+      this._rateLimit.lastError = `${data.error}`;
+    }
+  }
+
+  /**
+   * Update adaptive parallel telemetry.
+   *
+   * @param {object} data
+   * @param {'throttled'|'recovered'} [data.event]
+   * @param {string} [data.reason]
+   * @param {number} [data.maxParallel]
+   * @param {number} [data.effectiveMaxParallel]
+   * @param {number} [data.floor]
+   * @param {boolean} [data.adaptive]
+   */
+  updateParallelTelemetry(data = {}) {
+    if (typeof data.adaptive === 'boolean') {
+      this._parallel.adaptive = data.adaptive;
+    }
+
+    const maxParallel = Number(data.maxParallel);
+    if (Number.isFinite(maxParallel) && maxParallel > 0) {
+      this._parallel.maxParallel = Math.floor(maxParallel);
+    }
+
+    const effective = Number(data.effectiveMaxParallel);
+    if (Number.isFinite(effective) && effective > 0) {
+      this._parallel.effectiveMaxParallel = Math.floor(effective);
+    }
+
+    const floor = Number(data.floor);
+    if (Number.isFinite(floor) && floor > 0) {
+      this._parallel.floor = Math.floor(floor);
+    }
+
+    if (typeof data.reason === 'string' && data.reason.trim()) {
+      this._parallel.lastReason = data.reason.trim();
+    }
+
+    if (data.event === 'throttled') {
+      this._parallel.throttledCount++;
+      this._parallel.lastThrottledAt = new Date().toISOString();
+    } else if (data.event === 'recovered') {
+      this._parallel.recoveredCount++;
+      this._parallel.lastRecoveredAt = new Date().toISOString();
+    }
+  }
+
   /**
    * Set the overall orchestration state.
    *
@@ -219,6 +324,8 @@ class StatusMonitor {
       currentBatch: this._currentBatch,
       totalBatches: this._totalBatches,
       specs,
+      rateLimit: { ...this._rateLimit },
+      parallel: { ...this._parallel },
     };
   }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "kiro-spec-engine",
-  "version": "1.47.10",
+  "version": "1.47.14",
   "description": "kiro-spec-engine (kse) - A CLI tool and npm package for spec-driven development with AI coding assistants. NOT the Kiro IDE desktop application.",
   "main": "index.js",
   "bin": {