scene-capability-engine 3.3.16 → 3.3.17

package/CHANGELOG.md

@@ -7,6 +7,27 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [3.3.17] - 2026-02-26
+
+### Added
+- Orchestrator rate-limit profile management commands:
+  - `sce orchestrate profile list`
+  - `sce orchestrate profile show`
+  - `sce orchestrate profile set <conservative|balanced|aggressive> [--reset-overrides]`
+- Runtime one-shot profile override:
+  - `sce orchestrate run --rate-limit-profile <profile>`
+- New anti-429 regression shortcut:
+  - `npm run test:orchestrator-429`
+- Added default orchestrator baseline config files:
+  - `.sce/config/orchestrator.json`
+  - `template/.sce/config/orchestrator.json`
+- Added profile runbook:
+  - `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
+
+### Changed
+- Orchestration engine now supports runtime config overrides for one execution without mutating persisted config.
+- Command reference updated with profile workflow and recommended anti-429 usage.
+
 ## [3.3.16] - 2026-02-26
 
 ### Added

package/README.md

@@ -775,6 +775,6 @@ A deep conversation about AI development trends, Neo-Confucian philosophy, and s
 
 ---
 
-**Version**: 3.3.16  
+**Version**: 3.3.17  
 **Last Updated**: 2026-02-26
 

package/README.zh.md

@@ -636,7 +636,7 @@ sce spec bootstrap --name 01-00-my-first-feature --non-interactive
 
 ---
 
-**版本**：3.3.16  
+**版本**：3.3.17  
 **最后更新**：2026-02-26
 
 

package/docs/agent-runtime/orchestrator-rate-limit-profiles.md

@@ -0,0 +1,66 @@
+# Orchestrator Rate-Limit Profiles
+
+This document defines the default anti-429 presets used by SCE multi-agent orchestration.
+
+## Profiles
+
+| Profile | Positioning | Best for |
+|---|---|---|
+| `conservative` | strongest throttling, safest | unstable provider quota windows, repeated `429` spikes |
+| `balanced` | default baseline | normal daily multi-agent runs |
+| `aggressive` | higher throughput, lower safety margin | stable quota windows with strict delivery deadlines |
+
+## Effective Preset Values
+
+| Key | conservative | balanced | aggressive |
+|---|---:|---:|---:|
+| `rateLimitMaxRetries` | 10 | 8 | 6 |
+| `rateLimitBackoffBaseMs` | 2200 | 1500 | 1000 |
+| `rateLimitBackoffMaxMs` | 90000 | 60000 | 30000 |
+| `rateLimitCooldownMs` | 60000 | 45000 | 20000 |
+| `rateLimitLaunchBudgetPerMinute` | 4 | 8 | 16 |
+| `rateLimitSignalWindowMs` | 45000 | 30000 | 20000 |
+| `rateLimitSignalThreshold` | 2 | 3 | 4 |
+| `rateLimitSignalExtraHoldMs` | 5000 | 3000 | 2000 |
+| `rateLimitDynamicBudgetFloor` | 1 | 1 | 2 |
+
+## Usage
+
+Persistent (writes `.sce/config/orchestrator.json`):
+
+```bash
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
+```
+
+One-shot for a single run (does not change file):
+
+```bash
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+```
+
+Inspect current effective state:
+
+```bash
+sce orchestrate profile show --json
+```
+
+## Validation Checklist
+
+Run anti-429 regression:
+
+```bash
+npm run test:orchestrator-429
+```
+
+Run full suite before release:
+
+```bash
+npm test -- --runInBand
+```
+
+Release readiness criteria:
+
+1. No failing test in orchestrator/rate-limit scope.
+2. `orchestrate profile show --json` returns expected profile and effective values.
+3. Multi-agent run no longer stalls under sustained `429`; launch budget and hold telemetry progress over time.

package/docs/command-reference.md

@@ -295,15 +295,29 @@ sce repo health [--json]
 # Start orchestration for multiple specs
 sce orchestrate run --specs "spec-a,spec-b,spec-c" --max-parallel 3
 
+# One-shot anti-429 profile override (without editing orchestrator.json)
+sce orchestrate run --specs "spec-a,spec-b,spec-c" --rate-limit-profile conservative
+
 # Show orchestration status
 sce orchestrate status [--json]
 
 # Stop all running sub-agents
 sce orchestrate stop
+
+# List/show/set persistent rate-limit profile
+sce orchestrate profile list
+sce orchestrate profile show --json
+sce orchestrate profile set conservative
+sce orchestrate profile set balanced --reset-overrides
 ```
 
 When you pass `--specs` to `sce spec bootstrap|pipeline run|gate run`, sce now defaults to this orchestrate mode automatically.
 
+Rate-limit profiles:
+- `conservative`: strongest anti-429 throttling (recommended for unstable quota windows)
+- `balanced`: default profile for normal multi-agent runs
+- `aggressive`: higher throughput with lower protection margins
+
 ### Studio Workflow
 
 ```bash
@@ -408,6 +422,7 @@ Contract/baseline files:
 - `docs/agent-runtime/capability-mapping-report.schema.json`
 - `docs/agent-runtime/agent-result-summary-contract.schema.json`
 - `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`
+- `docs/agent-runtime/orchestrator-rate-limit-profiles.md`
 
 Multi-agent merge governance default:
 - `sce orchestrate run` loads `docs/agent-runtime/multi-agent-coordination-policy-baseline.json`.
@@ -1327,6 +1342,7 @@ Recommended `.sce/config/orchestrator.json`:
   "maxParallel": 3,
   "timeoutSeconds": 900,
   "maxRetries": 2,
+  "rateLimitProfile": "balanced",
   "rateLimitMaxRetries": 8,
   "rateLimitBackoffBaseMs": 1500,
   "rateLimitBackoffMaxMs": 60000,
@@ -1335,13 +1351,25 @@ Recommended `.sce/config/orchestrator.json`:
   "rateLimitCooldownMs": 45000,
   "rateLimitLaunchBudgetPerMinute": 8,
   "rateLimitLaunchBudgetWindowMs": 60000,
+  "rateLimitSignalWindowMs": 30000,
+  "rateLimitSignalThreshold": 3,
+  "rateLimitSignalExtraHoldMs": 3000,
+  "rateLimitDynamicBudgetFloor": 1,
   "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. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). `orchestrate stop` now interrupts pending retry waits immediately so long backoff does not look like a deadlock.
+`rateLimitProfile` applies preset anti-429 behavior (`conservative|balanced|aggressive`). Any explicit `rateLimit*` field in `orchestrator.json` overrides the selected profile value.
+
+`rateLimit*` settings provide dedicated retry/backoff and adaptive throttling when providers return 429 / too-many-requests errors. Engine retry honors `Retry-After` / `try again in ...` hints from provider error messages and clamps final retry waits by `rateLimitBackoffMaxMs` to avoid unbounded pause windows. During active backoff windows, new pending spec launches are paused to reduce request bursts (launch hold remains active even if adaptive parallel throttling is disabled). Sustained 429 spikes are additionally controlled by:
+- `rateLimitSignalWindowMs`: rolling signal window for spike detection
+- `rateLimitSignalThreshold`: signals required inside window before escalation
+- `rateLimitSignalExtraHoldMs`: extra launch hold per escalation unit
+- `rateLimitDynamicBudgetFloor`: lowest dynamic launch budget allowed during sustained pressure
+
+`orchestrate stop` interrupts pending retry waits immediately so long backoff windows do not look like deadlocks.
 
 Codex sub-agent permission defaults:
 - `--sandbox danger-full-access` is always injected by orchestrator runtime.

package/lib/commands/orchestrate.js

@@ -13,6 +13,26 @@ const fs = require('fs-extra');
 
 const SPECS_DIR = '.sce/specs';
 const STATUS_FILE = '.sce/config/orchestration-status.json';
+const ORCHESTRATOR_CONFIG_FILE = '.sce/config/orchestrator.json';
+const FALLBACK_RATE_LIMIT_PROFILE_PRESETS = Object.freeze({
+  conservative: true,
+  balanced: true,
+  aggressive: true,
+});
+const RATE_LIMIT_FIELD_KEYS = Object.freeze([
+  'rateLimitMaxRetries',
+  'rateLimitBackoffBaseMs',
+  'rateLimitBackoffMaxMs',
+  'rateLimitAdaptiveParallel',
+  'rateLimitParallelFloor',
+  'rateLimitCooldownMs',
+  'rateLimitLaunchBudgetPerMinute',
+  'rateLimitLaunchBudgetWindowMs',
+  'rateLimitSignalWindowMs',
+  'rateLimitSignalThreshold',
+  'rateLimitSignalExtraHoldMs',
+  'rateLimitDynamicBudgetFloor',
+]);
 
 /**
  * Run orchestration programmatically.
@@ -21,6 +41,7 @@ const STATUS_FILE = '.sce/config/orchestration-status.json';
  * @param {string} [options.specs] - Comma separated spec names
  * @param {string[]} [options.specNames] - Explicit spec names array
  * @param {number} [options.maxParallel]
+ * @param {string} [options.rateLimitProfile]
  * @param {boolean} [options.json]
  * @param {boolean} [options.silent]
  * @param {object} dependencies
@@ -42,12 +63,21 @@ async function runOrchestration(options = {}, dependencies = {}) {
     throw new Error('--max-parallel must be >= 1');
   }
 
+  const rawRateLimitProfile = options.rateLimitProfile === undefined || options.rateLimitProfile === null
+    ? null
+    : `${options.rateLimitProfile}`.trim().toLowerCase();
+
   const missing = await _validateSpecs(workspaceRoot, specNames);
   if (missing.length > 0) {
     throw new Error(`Specs not found: ${missing.join(', ')}`);
   }
 
-  const { OrchestratorConfig } = require('../orchestrator/orchestrator-config');
+  const orchestratorConfigModule = require('../orchestrator/orchestrator-config');
+  const {
+    OrchestratorConfig,
+    RATE_LIMIT_PROFILE_PRESETS,
+    buildRateLimitProfileConfig
+  } = orchestratorConfigModule;
   const { BootstrapPromptBuilder } = require('../orchestrator/bootstrap-prompt-builder');
   const { AgentSpawner } = require('../orchestrator/agent-spawner');
   const { StatusMonitor } = require('../orchestrator/status-monitor');
@@ -69,6 +99,20 @@ async function runOrchestration(options = {}, dependencies = {}) {
 
   const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
   const config = await orchestratorConfig.getConfig();
+  const availableProfiles = Object.keys(
+    RATE_LIMIT_PROFILE_PRESETS || FALLBACK_RATE_LIMIT_PROFILE_PRESETS
+  );
+  const selectedRateLimitProfile = rawRateLimitProfile || null;
+  if (selectedRateLimitProfile && !availableProfiles.includes(selectedRateLimitProfile)) {
+    throw new Error(
+      `--rate-limit-profile must be one of: ${availableProfiles.join(', ')}`
+    );
+  }
+  const runtimeRateLimitOverrides = selectedRateLimitProfile
+    ? (typeof buildRateLimitProfileConfig === 'function'
+      ? buildRateLimitProfileConfig(selectedRateLimitProfile)
+      : { rateLimitProfile: selectedRateLimitProfile })
+    : null;
   const effectiveMaxParallel = maxParallel || config.maxParallel;
 
   const bootstrapPromptBuilder = new BootstrapPromptBuilder(workspaceRoot, orchestratorConfig);
@@ -98,7 +142,7 @@ async function runOrchestration(options = {}, dependencies = {}) {
   if (!options.silent && !options.json) {
     console.log(
       chalk.blue('🚀'),
-      `Starting orchestration for ${specNames.length} spec(s) (max-parallel: ${effectiveMaxParallel})...`
+      `Starting orchestration for ${specNames.length} spec(s) (max-parallel: ${effectiveMaxParallel})${selectedRateLimitProfile ? `, rate-limit-profile: ${selectedRateLimitProfile}` : ''}...`
     );
   }
 
@@ -146,7 +190,10 @@ async function runOrchestration(options = {}, dependencies = {}) {
 
   let result;
   try {
-    result = await engine.start(specNames, { maxParallel: effectiveMaxParallel });
+    result = await engine.start(specNames, {
+      maxParallel: effectiveMaxParallel,
+      configOverrides: runtimeRateLimitOverrides
+    });
   } finally {
     clearInterval(statusTimer);
     await persistStatus();
@@ -189,6 +236,10 @@ function registerOrchestrateCommands(program) {
     .description('Start orchestration for specified Specs')
     .requiredOption('--specs <specs>', 'Comma-separated list of Spec names')
     .option('--max-parallel <n>', 'Maximum parallel agents', parseInt)
+    .option(
+      '--rate-limit-profile <profile>',
+      'Rate-limit profile (conservative|balanced|aggressive)'
+    )
     .option('--json', 'Output in JSON format')
     .action(async (options) => {
       try {
@@ -256,6 +307,157 @@ function registerOrchestrateCommands(program) {
         process.exit(1);
       }
     });
+
+  // ── sce orchestrate profile * ────────────────────────────────────
+  const profile = orchestrate
+    .command('profile')
+    .description('Manage orchestrator rate-limit profiles');
+
+  profile
+    .command('list')
+    .description('List available rate-limit profiles')
+    .option('--json', 'Output in JSON format')
+    .action(async (options) => {
+      try {
+        const orchestratorConfigModule = require('../orchestrator/orchestrator-config');
+        const presets = orchestratorConfigModule.RATE_LIMIT_PROFILE_PRESETS || FALLBACK_RATE_LIMIT_PROFILE_PRESETS;
+        const profiles = Object.keys(presets);
+
+        if (options.json) {
+          console.log(JSON.stringify({ profiles }, null, 2));
+          return;
+        }
+
+        console.log(chalk.bold('Rate-limit profiles'));
+        for (const item of profiles) {
+          console.log(`  - ${item}`);
+        }
+      } catch (err) {
+        _errorAndExit(err.message, options.json);
+      }
+    });
+
+  profile
+    .command('show')
+    .description('Show active rate-limit profile and effective anti-429 settings')
+    .option('--json', 'Output in JSON format')
+    .action(async (options) => {
+      try {
+        const workspaceRoot = process.cwd();
+        const orchestratorConfigModule = require('../orchestrator/orchestrator-config');
+        const { OrchestratorConfig, RATE_LIMIT_PROFILE_PRESETS, resolveRateLimitProfileName } = orchestratorConfigModule;
+        const presets = RATE_LIMIT_PROFILE_PRESETS || FALLBACK_RATE_LIMIT_PROFILE_PRESETS;
+        const availableProfiles = Object.keys(presets);
+
+        const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
+        const effectiveConfig = await orchestratorConfig.getConfig();
+        const rawConfig = await _readRawOrchestratorConfig(workspaceRoot);
+        const activeProfile = typeof resolveRateLimitProfileName === 'function'
+          ? resolveRateLimitProfileName(effectiveConfig.rateLimitProfile, 'balanced')
+          : `${effectiveConfig.rateLimitProfile || 'balanced'}`;
+        const preset = presets[activeProfile] || {};
+        const overrides = [];
+        for (const field of RATE_LIMIT_FIELD_KEYS) {
+          if (
+            Object.prototype.hasOwnProperty.call(rawConfig, field) &&
+            Object.prototype.hasOwnProperty.call(preset, field) &&
+            rawConfig[field] !== preset[field]
+          ) {
+            overrides.push(field);
+          }
+        }
+        const effectiveRateLimit = {};
+        for (const field of RATE_LIMIT_FIELD_KEYS) {
+          effectiveRateLimit[field] = effectiveConfig[field];
+        }
+
+        const payload = {
+          profile: activeProfile,
+          available_profiles: availableProfiles,
+          explicit_overrides: overrides,
+          effective: effectiveRateLimit,
+        };
+
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+
+        console.log(chalk.bold(`Active rate-limit profile: ${activeProfile}`));
+        if (overrides.length > 0) {
+          console.log(chalk.yellow(`Explicit overrides: ${overrides.join(', ')}`));
+        } else {
+          console.log(chalk.gray('Explicit overrides: none'));
+        }
+        for (const field of RATE_LIMIT_FIELD_KEYS) {
+          console.log(`  ${field}: ${effectiveRateLimit[field]}`);
+        }
+      } catch (err) {
+        _errorAndExit(err.message, options.json);
+      }
+    });
+
+  profile
+    .command('set')
+    .description('Set persistent rate-limit profile in .sce/config/orchestrator.json')
+    .argument('<profile>', 'Profile name (conservative|balanced|aggressive)')
+    .option('--reset-overrides', 'Reset explicit rateLimit* overrides to profile defaults')
+    .option('--json', 'Output in JSON format')
+    .action(async (profileName, options) => {
+      try {
+        const workspaceRoot = process.cwd();
+        const orchestratorConfigModule = require('../orchestrator/orchestrator-config');
+        const {
+          OrchestratorConfig,
+          RATE_LIMIT_PROFILE_PRESETS,
+          resolveRateLimitProfileName,
+          buildRateLimitProfileConfig
+        } = orchestratorConfigModule;
+        const presets = RATE_LIMIT_PROFILE_PRESETS || FALLBACK_RATE_LIMIT_PROFILE_PRESETS;
+        const availableProfiles = Object.keys(presets);
+        const normalizedInput = `${profileName || ''}`.trim().toLowerCase();
+        if (!availableProfiles.includes(normalizedInput)) {
+          throw new Error(`profile must be one of: ${availableProfiles.join(', ')}`);
+        }
+
+        const resolvedProfile = typeof resolveRateLimitProfileName === 'function'
+          ? resolveRateLimitProfileName(normalizedInput, 'balanced')
+          : normalizedInput;
+        const orchestratorConfig = new OrchestratorConfig(workspaceRoot);
+        let updated;
+
+        if (options.resetOverrides && typeof buildRateLimitProfileConfig === 'function') {
+          updated = await orchestratorConfig.updateConfig(buildRateLimitProfileConfig(resolvedProfile));
+        } else {
+          updated = await orchestratorConfig.updateConfig({ rateLimitProfile: resolvedProfile });
+        }
+
+        const payload = {
+          profile: resolvedProfile,
+          reset_overrides: !!options.resetOverrides,
+          config_file: ORCHESTRATOR_CONFIG_FILE,
+          effective: RATE_LIMIT_FIELD_KEYS.reduce((acc, key) => {
+            acc[key] = updated[key];
+            return acc;
+          }, {})
+        };
+
+        if (options.json) {
+          console.log(JSON.stringify(payload, null, 2));
+          return;
+        }
+
+        console.log(chalk.green(`Set rate-limit profile: ${resolvedProfile}`));
+        if (options.resetOverrides) {
+          console.log(chalk.gray('Explicit rateLimit* overrides reset to profile defaults.'));
+        } else {
+          console.log(chalk.gray('Existing explicit rateLimit* overrides (if any) are preserved.'));
+        }
+        console.log(chalk.gray(`Config updated: ${ORCHESTRATOR_CONFIG_FILE}`));
+      } catch (err) {
+        _errorAndExit(err.message, options.json);
+      }
+    });
 }
 
 // ── Helpers ──────────────────────────────────────────────────────────
@@ -303,6 +505,24 @@ async function _writeStatus(workspaceRoot, status) {
   await fs.writeJson(statusPath, status, { spaces: 2 });
 }
 
+/**
+ * Read raw orchestrator config file (without default merge).
+ * @param {string} workspaceRoot
+ * @returns {Promise<object>}
+ */
+async function _readRawOrchestratorConfig(workspaceRoot) {
+  const configPath = path.join(workspaceRoot, ORCHESTRATOR_CONFIG_FILE);
+  try {
+    const payload = await fs.readJson(configPath);
+    if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+      return {};
+    }
+    return payload;
+  } catch (_err) {
+    return {};
+  }
+}
+
 /**
  * Print a human-readable orchestration result.
  * @param {object} result

package/lib/orchestrator/orchestration-engine.js

@@ -132,6 +132,10 @@ class OrchestrationEngine extends EventEmitter {
     this._rateLimitSignalWindowMs = DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS;
     /** @type {number} number of rate-limit signals inside window that triggers escalation */
     this._rateLimitSignalThreshold = DEFAULT_RATE_LIMIT_SIGNAL_THRESHOLD;
+    /** @type {number} additional launch hold applied per escalation step */
+    this._rateLimitSignalExtraHoldMs = DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS;
+    /** @type {number} minimum dynamic launch budget floor under sustained pressure */
+    this._rateLimitDynamicBudgetFloor = DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR;
     /** @type {number[]} timestamps (ms) of recent spec launches for rolling budget accounting */
     this._rateLimitLaunchTimestamps = [];
     /** @type {number} last launch-budget hold telemetry emission timestamp (ms) */
@@ -172,6 +176,7 @@ class OrchestrationEngine extends EventEmitter {
    * @param {string[]} specNames - Specs to orchestrate
    * @param {object} [options]
    * @param {number} [options.maxParallel] - Override max parallel from config
+   * @param {object} [options.configOverrides] - Runtime config overrides for this execution only
    * @returns {Promise<object>} OrchestrationResult
    */
   async start(specNames, options = {}) {
@@ -235,11 +240,18 @@ class OrchestrationEngine extends EventEmitter {
 
       // Get config for maxParallel and maxRetries
       const config = await this._orchestratorConfig.getConfig();
-      this._applyRetryPolicyConfig(config);
-      await this._applyCoordinationPolicyConfig(config);
-      this._agentWaitTimeoutMs = this._resolveAgentWaitTimeoutMs(config);
-      const maxParallel = options.maxParallel || config.maxParallel || 3;
-      const maxRetries = config.maxRetries || 2;
+      const configOverrides = options && typeof options.configOverrides === 'object' && !Array.isArray(options.configOverrides)
+        ? options.configOverrides
+        : null;
+      const effectiveConfig = configOverrides
+        ? { ...config, ...configOverrides }
+        : config;
+
+      this._applyRetryPolicyConfig(effectiveConfig);
+      await this._applyCoordinationPolicyConfig(effectiveConfig);
+      this._agentWaitTimeoutMs = this._resolveAgentWaitTimeoutMs(effectiveConfig);
+      const maxParallel = options.maxParallel || effectiveConfig.maxParallel || 3;
+      const maxRetries = effectiveConfig.maxRetries || 2;
       this._initializeAdaptiveParallel(maxParallel);
 
       // Step 5: Execute batches (Req 3.4)
@@ -1063,6 +1075,22 @@ class OrchestrationEngine extends EventEmitter {
       config && config.rateLimitLaunchBudgetWindowMs,
       DEFAULT_RATE_LIMIT_LAUNCH_BUDGET_WINDOW_MS
     );
+    this._rateLimitSignalWindowMs = this._toPositiveInteger(
+      config && config.rateLimitSignalWindowMs,
+      DEFAULT_RATE_LIMIT_SIGNAL_WINDOW_MS
+    );
+    this._rateLimitSignalThreshold = this._toPositiveInteger(
+      config && config.rateLimitSignalThreshold,
+      DEFAULT_RATE_LIMIT_SIGNAL_THRESHOLD
+    );
+    this._rateLimitSignalExtraHoldMs = this._toPositiveInteger(
+      config && config.rateLimitSignalExtraHoldMs,
+      DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS
+    );
+    this._rateLimitDynamicBudgetFloor = this._toPositiveInteger(
+      config && config.rateLimitDynamicBudgetFloor,
+      DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR
+    );
   }
 
   /**
@@ -1570,7 +1598,10 @@ class OrchestrationEngine extends EventEmitter {
     const escalationUnits = signalCount - threshold + 1;
     const extraHoldMs = Math.min(
       maxHoldMs,
-      escalationUnits * DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS
+      escalationUnits * this._toPositiveInteger(
+        this._rateLimitSignalExtraHoldMs,
+        DEFAULT_RATE_LIMIT_SIGNAL_EXTRA_HOLD_MS
+      )
     );
     if (extraHoldMs > 0) {
       const currentHoldUntil = this._toNonNegativeInteger(this._rateLimitLaunchHoldUntil, 0);
@@ -1593,7 +1624,13 @@ class OrchestrationEngine extends EventEmitter {
     );
     const budgetFloor = Math.max(
       1,
-      Math.min(configuredBudget, DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR)
+      Math.min(
+        configuredBudget,
+        this._toPositiveInteger(
+          this._rateLimitDynamicBudgetFloor,
+          DEFAULT_RATE_LIMIT_DYNAMIC_BUDGET_FLOOR
+        )
+      )
     );
     const nextBudget = Math.max(budgetFloor, Math.floor(currentBudget / 2));
     if (nextBudget >= currentBudget) {

package/lib/orchestrator/orchestrator-config.js

@@ -24,6 +24,7 @@ const KNOWN_KEYS = new Set([
   'maxParallel',
   'timeoutSeconds',
   'maxRetries',
+  'rateLimitProfile',
   'rateLimitMaxRetries',
   'rateLimitBackoffBaseMs',
   'rateLimitBackoffMaxMs',
@@ -32,18 +33,85 @@ const KNOWN_KEYS = new Set([
   'rateLimitCooldownMs',
   'rateLimitLaunchBudgetPerMinute',
   'rateLimitLaunchBudgetWindowMs',
+  'rateLimitSignalWindowMs',
+  'rateLimitSignalThreshold',
+  'rateLimitSignalExtraHoldMs',
+  'rateLimitDynamicBudgetFloor',
   'apiKeyEnvVar',
   'bootstrapTemplate',
   'codexArgs',
   'codexCommand',
 ]);
 
+const RATE_LIMIT_PROFILE_PRESETS = Object.freeze({
+  conservative: Object.freeze({
+    rateLimitMaxRetries: 10,
+    rateLimitBackoffBaseMs: 2200,
+    rateLimitBackoffMaxMs: 90000,
+    rateLimitAdaptiveParallel: true,
+    rateLimitParallelFloor: 1,
+    rateLimitCooldownMs: 60000,
+    rateLimitLaunchBudgetPerMinute: 4,
+    rateLimitLaunchBudgetWindowMs: 60000,
+    rateLimitSignalWindowMs: 45000,
+    rateLimitSignalThreshold: 2,
+    rateLimitSignalExtraHoldMs: 5000,
+    rateLimitDynamicBudgetFloor: 1,
+  }),
+  balanced: Object.freeze({
+    rateLimitMaxRetries: 8,
+    rateLimitBackoffBaseMs: 1500,
+    rateLimitBackoffMaxMs: 60000,
+    rateLimitAdaptiveParallel: true,
+    rateLimitParallelFloor: 1,
+    rateLimitCooldownMs: 45000,
+    rateLimitLaunchBudgetPerMinute: 8,
+    rateLimitLaunchBudgetWindowMs: 60000,
+    rateLimitSignalWindowMs: 30000,
+    rateLimitSignalThreshold: 3,
+    rateLimitSignalExtraHoldMs: 3000,
+    rateLimitDynamicBudgetFloor: 1,
+  }),
+  aggressive: Object.freeze({
+    rateLimitMaxRetries: 6,
+    rateLimitBackoffBaseMs: 1000,
+    rateLimitBackoffMaxMs: 30000,
+    rateLimitAdaptiveParallel: true,
+    rateLimitParallelFloor: 1,
+    rateLimitCooldownMs: 20000,
+    rateLimitLaunchBudgetPerMinute: 16,
+    rateLimitLaunchBudgetWindowMs: 60000,
+    rateLimitSignalWindowMs: 20000,
+    rateLimitSignalThreshold: 4,
+    rateLimitSignalExtraHoldMs: 2000,
+    rateLimitDynamicBudgetFloor: 2,
+  }),
+});
+
+function resolveRateLimitProfileName(profileName, fallback = 'balanced') {
+  const normalized = `${profileName || ''}`.trim().toLowerCase();
+  if (normalized && Object.prototype.hasOwnProperty.call(RATE_LIMIT_PROFILE_PRESETS, normalized)) {
+    return normalized;
+  }
+  return fallback;
+}
+
+function buildRateLimitProfileConfig(profileName) {
+  const resolvedProfile = resolveRateLimitProfileName(profileName, 'balanced');
+  const preset = RATE_LIMIT_PROFILE_PRESETS[resolvedProfile] || RATE_LIMIT_PROFILE_PRESETS.balanced;
+  return {
+    ...preset,
+    rateLimitProfile: resolvedProfile,
+  };
+}
+
 /** @type {import('./orchestrator-config').OrchestratorConfigData} */
 const DEFAULT_CONFIG = Object.freeze({
   agentBackend: 'codex',
   maxParallel: 3,
   timeoutSeconds: 600,
   maxRetries: 2,
+  rateLimitProfile: 'balanced',
   rateLimitMaxRetries: 8,
   rateLimitBackoffBaseMs: 1500,
   rateLimitBackoffMaxMs: 60000,
@@ -52,6 +120,10 @@ const DEFAULT_CONFIG = Object.freeze({
   rateLimitCooldownMs: 45000,
   rateLimitLaunchBudgetPerMinute: 8,
   rateLimitLaunchBudgetWindowMs: 60000,
+  rateLimitSignalWindowMs: 30000,
+  rateLimitSignalThreshold: 3,
+  rateLimitSignalExtraHoldMs: 3000,
+  rateLimitDynamicBudgetFloor: 1,
   apiKeyEnvVar: 'CODEX_API_KEY',
   bootstrapTemplate: null,
   codexArgs: [],
@@ -142,7 +214,17 @@ class OrchestratorConfig {
    */
   _mergeWithDefaults(data) {
     const filtered = this._filterKnownKeys(data);
-    return { ...DEFAULT_CONFIG, ...filtered };
+    const rateLimitProfile = resolveRateLimitProfileName(
+      filtered.rateLimitProfile,
+      DEFAULT_CONFIG.rateLimitProfile
+    );
+    const profileDefaults = buildRateLimitProfileConfig(rateLimitProfile);
+    return {
+      ...DEFAULT_CONFIG,
+      ...profileDefaults,
+      ...filtered,
+      rateLimitProfile,
+    };
   }
 
   /**
@@ -170,4 +252,11 @@ class OrchestratorConfig {
   }
 }
 
-module.exports = { OrchestratorConfig, DEFAULT_CONFIG, KNOWN_KEYS };
+module.exports = {
+  OrchestratorConfig,
+  DEFAULT_CONFIG,
+  KNOWN_KEYS,
+  RATE_LIMIT_PROFILE_PRESETS,
+  resolveRateLimitProfileName,
+  buildRateLimitProfileConfig,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scene-capability-engine",
-  "version": "3.3.16",
+  "version": "3.3.17",
   "description": "SCE (Scene Capability Engine) - A CLI tool and npm package for spec-driven development with AI coding assistants.",
   "main": "index.js",
   "bin": {
@@ -30,6 +30,7 @@
     "test:unit": "npx jest tests/unit",
     "test:integration": "npx jest tests/integration",
     "test:properties": "npx jest tests/properties",
+    "test:orchestrator-429": "npx jest tests/orchestrator/orchestration-engine.test.js tests/orchestrator/orchestrate-command.status-events.test.js --runInBand",
     "test:handles": "npx jest --config=jest.config.js --runInBand --detectOpenHandles",
     "test:interactive-loop-smoke": "node scripts/interactive-loop-smoke.js --json",
     "test:interactive-flow-smoke": "node scripts/interactive-flow-smoke.js --json",

package/template/.sce/config/orchestrator.json

@@ -0,0 +1,24 @@
+{
+  "agentBackend": "codex",
+  "maxParallel": 3,
+  "timeoutSeconds": 900,
+  "maxRetries": 2,
+  "rateLimitProfile": "balanced",
+  "rateLimitMaxRetries": 8,
+  "rateLimitBackoffBaseMs": 1500,
+  "rateLimitBackoffMaxMs": 60000,
+  "rateLimitAdaptiveParallel": true,
+  "rateLimitParallelFloor": 1,
+  "rateLimitCooldownMs": 45000,
+  "rateLimitLaunchBudgetPerMinute": 8,
+  "rateLimitLaunchBudgetWindowMs": 60000,
+  "rateLimitSignalWindowMs": 30000,
+  "rateLimitSignalThreshold": 3,
+  "rateLimitSignalExtraHoldMs": 3000,
+  "rateLimitDynamicBudgetFloor": 1,
+  "apiKeyEnvVar": "CODEX_API_KEY",
+  "codexArgs": [
+    "--skip-git-repo-check"
+  ],
+  "codexCommand": "npx @openai/codex"
+}