scripts-orchestrator 3.0.0 → 3.7.0

package/README.md

@@ -26,6 +26,7 @@ npm install --save-dev scripts-orchestrator
 ## Features
 
 - **Parallel Execution**: Runs multiple commands concurrently for faster execution
+- **Concurrency cap**: Bound how many commands a phase runs at once with `max_concurrency` / `--max-concurrency` (defaults to `auto` = CPU count − 1) so smaller machines aren't asked to host every command's toolchain simultaneously (v3.6+). A single phase can pin its own cap with a phase-level `max_concurrency` — e.g. `1` to serialise just that phase's commands while continuing past failures (v3.7+)
 - **Sequential Mode**: Option to run all commands sequentially for low CPU machines
 - **Dependency Management**: Handles command dependencies and ensures proper execution order
 - **Background Processes**: Supports running commands in the background with health checks
@@ -41,6 +42,7 @@ npm install --save-dev scripts-orchestrator
 - **Post-run hook**: Run a shell command after results are written via `post_run` config (v2.14+)
 - **Run-state file**: Library-owned in-progress indicator for live dashboard integration (v2.14+)
 - **Phase recommendations**: Memory-aware `--recommend` mode that proposes an optimal phase layout from a run's time/memory metrics (advisory, v2.15+)
+- **npm workspace aggregation**: First-class workspace roll-up that discovers the npm workspaces in a repo and rolls each workspace's results JSON — plus the root run's global checks — into a single report. Drive it declaratively with the `aggregate` config key (in-process; v3.2+) or via the standalone `--aggregate` CLI mode (v3.1+)
 
 ## Configuration
 
@@ -416,6 +418,73 @@ This is particularly useful for:
 - Debugging individual command failures
 - Avoiding resource contention between commands
 
+### Limiting Concurrency (`max_concurrency`)
+
+Sequential mode is all-or-nothing. When a phase declares many parallel commands, running *every* one at once can overwhelm a smaller machine (each command may spin up its own Node/toolchain), while `--sequential` over-corrects by dropping to one at a time. `max_concurrency` is the middle ground: it caps how many of a phase's commands run **at once** without serialising everything.
+
+- **`'auto'` (the default)** resolves to `max(1, cpuCount - 1)`, leaving one core for the OS/editor.
+- **A positive integer** pins the cap to that exact number.
+- **`0`, negative, or unparseable** values fall back to `auto`.
+
+When the cap is greater than or equal to a phase's command count, behaviour is identical to unbounded parallel execution — so well-provisioned machines see no change. As each command finishes, the next queued one starts, keeping at most `max_concurrency` in flight. `--sequential` still wins (it is equivalent to a cap of 1).
+
+#### Configuration
+
+```js
+export default {
+  max_concurrency: 'auto', // or a number like 4
+  phases: [
+    {
+      name: 'quality checks',
+      parallel: [
+        { command: 'lint' },
+        { command: 'typecheck' },
+        { command: 'test' },
+        // ...more commands than the machine can run at once
+      ],
+    },
+  ],
+};
+```
+
+#### CLI override
+
+The `--max-concurrency` flag overrides the configured value for a single run:
+
+```bash
+# Run at most 3 commands per phase concurrently
+npm run scripts-orchestrator -- --max-concurrency 3
+
+# Force the auto cap (CPU count - 1) regardless of config
+npm run scripts-orchestrator -- --max-concurrency auto
+```
+
+At the start of a parallel run the orchestrator logs the resolved cap, e.g. `🧮 Max concurrency: 3 (of 8 CPUs)`.
+
+#### Per-phase override
+
+A single phase can pin its own cap by setting `max_concurrency` on the phase itself. This is the right tool when one phase's commands share a single resource — a dev server, a GPU, a port — and must run one at a time, while every other phase keeps the global cap and its parallelism. The phase value resolves the same way as the global one (`'auto'` and invalid values fall back to CPU count − 1), and overrides both the configured global cap and any `--max-concurrency` flag for that phase only.
+
+```js
+export default {
+  max_concurrency: 'auto', // global default for every phase
+  phases: [
+    { name: 'quality checks', parallel: [/* runs at the global cap */] },
+    {
+      name: 'browser suites',
+      max_concurrency: 1, // serialise just this phase (one shared dev server)
+      parallel: [
+        { command: 'e2e:group-a' },
+        { command: 'e2e:group-b' },
+        // ...each runs in turn; a failed group does NOT abort the others
+      ],
+    },
+  ],
+};
+```
+
+A serial phase (`max_concurrency: 1`) still runs through the parallel path, so it **continues past a failed command** rather than stopping on the first failure — unlike the global `--sequential` flag, which both serialises everything and stops the phase at its first failure. When a phase's cap differs from the global one the orchestrator logs the override, e.g. `↳ phase concurrency: 1 (phase "browser suites" overrides the 3 default)`.
+
 ## Error Handling
 
 - The script tracks failed and skipped commands
@@ -528,11 +597,76 @@ The hook receives two environment variables:
 The hook runs synchronously and its exit code is logged but does not change the orchestrator's
 own exit code.
 
-**Typical use case:** trigger a monorepo rollup report after each workspace finishes:
+**Typical use case:** roll up a monorepo report after each workspace finishes (see
+**npm workspace aggregation** below):
 ```javascript
-post_run: 'node ../../scripts/merge-orchestrator-report.js'
+post_run: 'npx scripts-orchestrator --aggregate ../../scripts-orchestrator-aggregate.config.js'
 ```
 
+## npm workspace aggregation (v3.1+)
+
+In a monorepo, each npm workspace can run its own orchestrator gate (writing its own
+`json_results`), and a root run can run repo-wide "global" checks. The aggregator rolls all of
+these into one report — no per-repo merge script required. Drive it the easy way with the
+declarative [`aggregate` config key](#declarative-aggregate-config-key-recommended-v32) below, or
+invoke the [`--aggregate` CLI mode](#--aggregate-cli-mode) directly.
+
+It reads only artifacts the library itself writes — each scope's `json_results` and the
+**run-state file** (`.scripts-orchestrator-run.json`) — so it needs no log scraping. The
+run-state file tells it whether the run is still in flight (live report with auto-refresh) or
+finished (static report). Each workspace section is classified as **OK / FAIL / RUNNING /
+PENDING / STALE / INTERRUPTED / N/A** from its own results JSON and the run window.
+
+### Declarative `aggregate` config key (recommended, v3.2+)
+
+Rather than wiring a `periodic_hook` / `post_run` that shells out to `--aggregate`, set the
+**`aggregate`** key in your orchestrator config and the library drives the roll-up **in-process** —
+no subprocess spawned every interval, no dependency on `npx`/PATH resolution:
+
+```javascript
+// root run config — roll up periodically while running + once, static, at the end
+aggregate: './scripts-orchestrator-aggregate.config.js',  // or `true` for the built-in defaults
+periodic_interval_ms: 45000,                              // cadence for the in-process roll-up
+
+// each workspace gate config — refresh the roll-up as that workspace finishes
+aggregate: '../../scripts-orchestrator-aggregate.config.js',
+```
+
+The value may be `true` (use defaults), a path to a config module (its `default` export is used as
+the options below), or an options object inline. The library auto-detects whether the current run is
+the **repo-root run** (it owns the periodic cadence and writes the final static report) or a
+**fanned-out workspace run** (it refreshes the roll-up once, as that workspace finishes, leaving the
+report in-progress because the root run is still live). On interrupt, the orchestrator writes one
+final static roll-up itself.
+
+### `--aggregate` CLI mode
+
+The same roll-up is available as a standalone CLI mode (used internally by the declarative key, and
+handy for manual/one-off rendering or legacy hook wiring). It is safe to fire repeatedly:
+
+```bash
+scripts-orchestrator --aggregate                                   # use the built-in defaults
+scripts-orchestrator --aggregate ./scripts-orchestrator-aggregate.config.js   # override paths/title
+```
+
+The optional config module's `default` export may override any of these (all paths are
+resolved against the auto-detected repo root unless absolute):
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `title` | `Workspaces Quality Report` | Report heading |
+| `outJson` / `outHtml` | `logs/monorepo-quality-report.{json,html}` | Where the roll-up is written |
+| `runStateFile` | `logs/.scripts-orchestrator-run.json` | Run-state file used to detect in-progress + run start |
+| `rootResults` | `logs/scripts-orchestrator-logs/scripts-orchestrator-results.json` | Root run's results (source of global-check rows) |
+| `globalResults` | `logs/scripts-orchestrator-logs/scripts-orchestrator-global-results.json` | Fallback source of global-check rows |
+| `workspaceResults` | `logs/scripts-orchestrator-logs/scripts-orchestrator-results.json` | Per-workspace results path (relative to each workspace) |
+| `globalPhase` / `workspacePhase` | `global quality checks` / `workspace quality gates` | Phase names used to split global rows from the fan-out row |
+| `refreshSecs` | `5` | Auto-refresh cadence injected while the run is in progress |
+| `exclude` | `[]` | Workspace directories (repo-root-relative) to omit |
+
+The library also exports the building blocks for programmatic use:
+`findRepoRoot`, `discoverWorkspaceDirs`, `aggregateWorkspacesReport`, `writeAggregateReport`.
+
 ## Git-Based Caching
 
 The orchestrator automatically tracks the git commit hash and repository state to optimize execution:

package/index.js

@@ -35,6 +35,11 @@ const argv = yargs(hideBin(process.argv))
     type: 'boolean',
     description: 'Run all commands sequentially instead of in parallel (for low CPU machines)',
   })
+  .option('max-concurrency', {
+    type: 'string',
+    description:
+      'Cap how many commands a phase runs at once: a positive integer, or \'auto\' (cpuCount - 1). Overrides config max_concurrency. Ignored under --sequential.',
+  })
   .option('force', {
     type: 'boolean',
     description: 'Force execution even if git state is unchanged',
@@ -60,6 +65,11 @@ const argv = yargs(hideBin(process.argv))
     description:
       'Analyse an existing results JSON and print a memory-aware phase recommendation (no run).',
   })
+  .option('aggregate', {
+    type: 'string',
+    description:
+      'Aggregate every npm workspace\'s results JSON into one roll-up report (no run). Pass an optional config path to override the default paths/title.',
+  })
   .option('fanout', {
     type: 'number',
     description: 'Workspace fan-out (parallel gates sharing the host) used to size the --recommend budget. Default 1.',
@@ -148,6 +158,47 @@ if (argv.recommend != null) {
   process.exit(0);
 }
 
+// --aggregate mode: roll up every npm workspace's results JSON (plus the root run's global
+// checks) into a single report. Advisory of nothing — it just renders state already on disk, so
+// it is safe to fire repeatedly (e.g. from the periodic_hook while the run is in flight, or once
+// at the end). No orchestration run happens here.
+if (argv.aggregate != null) {
+  const { writeAggregateReport } = await import('./lib/index.js');
+  let options = {};
+  const cfgArg = argv.aggregate;
+  if (cfgArg && cfgArg !== '-') {
+    const cfgPath = path.resolve(process.cwd(), cfgArg);
+    if (!fs.existsSync(cfgPath)) {
+      log.error(`Error: --aggregate config not found at ${cfgPath}`);
+      process.exit(1);
+    }
+    try {
+      options = (await import(new URL(`file://${cfgPath}`).href)).default ?? {};
+    } catch (err) {
+      log.error(`Error: failed to load --aggregate config: ${err.message}`);
+      process.exit(1);
+    }
+  }
+  // The orchestrator fires this hook a final time AFTER clearing its run-state, tagging it with
+  // SCRIPTS_ORCHESTRATOR_PERIODIC=final. Honour that as an explicit "run is over" signal so the
+  // final report is static (no auto-refresh) even if a stray marker lingers.
+  if (process.env.SCRIPTS_ORCHESTRATOR_PERIODIC === 'final') {
+    options = { ...options, inProgress: false };
+  }
+  try {
+    const { jsonPath, htmlPath } = writeAggregateReport(options);
+    if (process.env.ORCHESTRATOR_MERGE_QUIET !== '1') {
+      log.info(
+        `📄 Aggregated workspace report → ${path.relative(process.cwd(), jsonPath)} (+ ${path.basename(htmlPath)})`,
+      );
+    }
+  } catch (err) {
+    log.error(`Error: failed to aggregate workspace report: ${err.message}`);
+    process.exit(1);
+  }
+  process.exit(0);
+}
+
 // Extract arguments
 const args = argv._;
 const configPath = args[0] || './scripts-orchestrator.config.js';
@@ -207,6 +258,14 @@ const htmlResultsPath =
 // post-run hook — shell command run after json_results written
 const postRun = commandsConfig.post_run ?? null;
 
+// Memory heat thresholds for the HTML report — fractions (0–1) of the run's peak memory above which
+// a command is coloured amber (mid) / red (high). Config: `memory_heat: { mid: 0.33, high: 0.66 }`.
+const memoryHeat = commandsConfig.memory_heat ?? null;
+
+// Duration heat thresholds for the HTML report — fractions (0–1) of the run's slowest command above
+// which a command is coloured amber (mid) / red (high). Config: `duration_heat: { mid: 0.33, high: 0.66 }`.
+const durationHeat = commandsConfig.duration_heat ?? null;
+
 // Periodic hook — shell command run on an interval WHILE the run is in flight (e.g. to roll up
 // results into an aggregate report). Library owns only the cadence; the command is project-specific.
 const periodicHook = commandsConfig.periodic_hook ?? null;
@@ -214,6 +273,34 @@ const periodicIntervalMs = Number(commandsConfig.periodic_interval_ms) > 0
   ? Number(commandsConfig.periodic_interval_ms)
   : 45000;
 
+// Declarative npm-workspace roll-up. `aggregate: true` uses library defaults; a string loads that
+// config module's default export as writeAggregateReport options; an object is used verbatim. When
+// set, the library drives the workspace aggregate IN-PROCESS — the repo-root run rolls up on the
+// periodic cadence + once at the end (static), and a fanned-out workspace run rolls up once as it
+// finishes. This is the declarative replacement for wiring periodic_hook / post_run to shell out
+// to `scripts-orchestrator --aggregate`.
+let aggregateOptions = null;
+const aggregateCfg = commandsConfig.aggregate;
+if (aggregateCfg != null && aggregateCfg !== false) {
+  if (aggregateCfg === true) {
+    aggregateOptions = {};
+  } else if (typeof aggregateCfg === 'string') {
+    const aggCfgPath = path.resolve(process.cwd(), aggregateCfg);
+    if (!fs.existsSync(aggCfgPath)) {
+      log.error(`Error: aggregate config not found at ${aggCfgPath}`);
+      process.exit(1);
+    }
+    try {
+      aggregateOptions = (await import(new URL(`file://${aggCfgPath}`).href)).default ?? {};
+    } catch (err) {
+      log.error(`Error: failed to load aggregate config: ${err.message}`);
+      process.exit(1);
+    }
+  } else if (typeof aggregateCfg === 'object') {
+    aggregateOptions = aggregateCfg;
+  }
+}
+
 // Set the log folder for the main orchestrator logs if specified
 if (logFolder) {
   log.setLogFolder(logFolder);
@@ -233,9 +320,18 @@ const orchestrator = new Orchestrator(
 );
 // wire post-run hook from config
 orchestrator.postRun = postRun;
+// wire memory heat thresholds from config (HTML report colouring)
+orchestrator.memoryHeat = memoryHeat;
+orchestrator.durationHeat = durationHeat;
 // Wire periodic hook (cadence owned by the library)
 orchestrator.periodicHook = periodicHook;
 orchestrator.periodicIntervalMs = periodicIntervalMs;
+// Wire declarative in-process workspace roll-up (takes the in-process path when set)
+orchestrator.aggregateOptions = aggregateOptions;
+// CLI --max-concurrency overrides the config's max_concurrency (resolved to a concrete cap).
+if (argv.maxConcurrency != null && argv.maxConcurrency !== '') {
+  orchestrator.maxConcurrency = orchestrator._resolveMaxConcurrency(argv.maxConcurrency);
+}
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {
@@ -248,6 +344,11 @@ const handleSignal = async (signal) => {
   }
   // clear run-state so dashboards know the run ended
   orchestrator._clearRunState();
+  // Write one final static workspace roll-up so an interrupted run leaves a non-refreshing report
+  // (only when the declarative in-process aggregate is configured; a no-op otherwise).
+  if (orchestrator.aggregateOptions) {
+    orchestrator._firePeriodicHookFinal();
+  }
   process.exit(1);
 };
 

package/lib/index.js

@@ -13,6 +13,12 @@ import {
   observedTimeline,
   packPhases,
 } from './recommend-phases.js';
+import {
+  findRepoRoot,
+  discoverWorkspaceDirs,
+  aggregateWorkspacesReport,
+  writeAggregateReport,
+} from './workspaces.js';
 
 export {
   Orchestrator,
@@ -28,5 +34,9 @@ export {
   usableSteps,
   observedTimeline,
   packPhases,
+  findRepoRoot,
+  discoverWorkspaceDirs,
+  aggregateWorkspacesReport,
+  writeAggregateReport,
 };
 export default Orchestrator;

package/lib/orchestrator.aggregate.test.js

@@ -0,0 +1,83 @@
+import { Orchestrator } from './orchestrator.js';
+
+const baseConfig = (extra = {}) => ({
+  phases: [{ name: 'p', parallel: [{ command: 'build' }] }],
+  ...extra,
+});
+
+// Build an orchestrator with the in-process aggregate wired, and stub the seams that would
+// otherwise spawn processes / touch disk so we can assert the decision logic in isolation.
+function makeOrch({ aggregateOptions = {}, periodicHook = null, isRoot = true } = {}) {
+  const orch = new Orchestrator(baseConfig());
+  orch.aggregateOptions = aggregateOptions;
+  orch.periodicHook = periodicHook;
+  orch._isRepoRootRun = () => isRoot;
+  // Capture aggregate fires instead of writing a report.
+  orch._fireAggregateCalls = [];
+  orch._fireAggregate = (inProgress) => orch._fireAggregateCalls.push(inProgress);
+  return orch;
+}
+
+// Minimal call-counter so the suite stays dependency-free (no jest globals under the ESM runner).
+function counter() {
+  const fn = (...args) => { fn.calls.push(args); };
+  fn.calls = [];
+  return fn;
+}
+
+describe('Orchestrator in-process workspace aggregate', () => {
+  test('no aggregate configured: periodic machinery is inert', () => {
+    const orch = new Orchestrator(baseConfig());
+    const fireSpy = counter();
+    orch._firePeriodicTick = fireSpy;
+    orch._startPeriodicHook();
+    expect(orch._periodicTimer).toBeNull();
+    expect(fireSpy.calls).toHaveLength(0);
+  });
+
+  test('root run with aggregate: starts cadence with a prompt first roll-up', () => {
+    const orch = makeOrch({ isRoot: true });
+    const tickSpy = counter();
+    orch._firePeriodicTick = tickSpy;
+    orch._startPeriodicHook();
+    expect(tickSpy.calls).toHaveLength(1); // prompt first roll-up
+    expect(orch._periodicTimer).not.toBeNull();
+    orch._stopPeriodicHook(); // avoid a dangling interval
+    expect(orch._periodicTimer).toBeNull();
+  });
+
+  test('fanned-out workspace run with aggregate: no periodic cadence', () => {
+    const orch = makeOrch({ isRoot: false });
+    const tickSpy = counter();
+    orch._firePeriodicTick = tickSpy;
+    orch._startPeriodicHook();
+    expect(tickSpy.calls).toHaveLength(0);
+    expect(orch._periodicTimer).toBeNull();
+  });
+
+  test('periodic tick rolls up with auto-detected inProgress (undefined)', () => {
+    const orch = makeOrch({ isRoot: true });
+    orch._firePeriodicTick();
+    expect(orch._fireAggregateCalls).toEqual([undefined]);
+  });
+
+  test('final fire on the root run forces a static (inProgress=false) report', () => {
+    const orch = makeOrch({ isRoot: true });
+    orch._firePeriodicHookFinal();
+    expect(orch._fireAggregateCalls).toEqual([false]);
+  });
+
+  test('final fire on a workspace run leaves inProgress auto-detected (root still running)', () => {
+    const orch = makeOrch({ isRoot: false });
+    orch._firePeriodicHookFinal();
+    expect(orch._fireAggregateCalls).toEqual([undefined]);
+  });
+
+  test('a legacy periodic_hook takes precedence over the in-process aggregate', () => {
+    const orch = makeOrch({ isRoot: true, periodicHook: 'echo hi' });
+    // With a shell hook configured, the tick must NOT take the in-process path.
+    orch._periodicRunning = true; // make the shell path a no-op without spawning
+    orch._firePeriodicTick();
+    expect(orch._fireAggregateCalls).toEqual([]);
+  });
+});

package/lib/orchestrator.concurrency.test.js

@@ -0,0 +1,112 @@
+import os from 'os';
+import { Orchestrator } from './orchestrator.js';
+
+const baseConfig = (extra = {}) => ({
+  phases: [{ name: 'p', parallel: [{ command: 'build' }] }],
+  ...extra,
+});
+
+const cpuAuto = () => Math.max(1, os.cpus().length - 1);
+
+describe('Orchestrator max concurrency resolution', () => {
+  test('defaults to auto (cpuCount - 1) when nothing is configured', () => {
+    const orch = new Orchestrator(baseConfig());
+    expect(orch.maxConcurrency).toBe(cpuAuto());
+  });
+
+  test('config max_concurrency: \'auto\' resolves to cpuCount - 1', () => {
+    const orch = new Orchestrator(baseConfig({ max_concurrency: 'auto' }));
+    expect(orch.maxConcurrency).toBe(cpuAuto());
+  });
+
+  test('a positive integer is used verbatim (floored)', () => {
+    expect(new Orchestrator(baseConfig({ max_concurrency: 4 })).maxConcurrency).toBe(4);
+    expect(new Orchestrator(baseConfig({ max_concurrency: 3.9 })).maxConcurrency).toBe(3);
+    expect(new Orchestrator(baseConfig({ max_concurrency: '6' })).maxConcurrency).toBe(6);
+  });
+
+  test('zero, negative, and unparseable values fall back to auto', () => {
+    expect(new Orchestrator(baseConfig({ max_concurrency: 0 })).maxConcurrency).toBe(cpuAuto());
+    expect(new Orchestrator(baseConfig({ max_concurrency: -2 })).maxConcurrency).toBe(cpuAuto());
+    expect(new Orchestrator(baseConfig({ max_concurrency: 'lots' })).maxConcurrency).toBe(cpuAuto());
+  });
+
+  test('legacy array config still resolves a cap (no max_concurrency key available)', () => {
+    const orch = new Orchestrator([{ command: 'a' }, { command: 'b' }]);
+    expect(orch.maxConcurrency).toBe(cpuAuto());
+  });
+});
+
+describe('Orchestrator._runWithConcurrency', () => {
+  test('preserves input order in the results array', async () => {
+    const orch = new Orchestrator(baseConfig());
+    const items = [10, 20, 30, 40];
+    const out = await orch._runWithConcurrency(items, 2, async (n) => n * 2);
+    expect(out).toEqual([20, 40, 60, 80]);
+  });
+
+  test('never exceeds the concurrency limit and still runs every item', async () => {
+    const orch = new Orchestrator(baseConfig());
+    let inFlight = 0;
+    let peak = 0;
+    const limit = 3;
+    const items = Array.from({ length: 12 }, (_, i) => i);
+    const worker = async (i) => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      // Yield a couple of microtasks so overlap actually happens.
+      await Promise.resolve();
+      await Promise.resolve();
+      inFlight -= 1;
+      return i;
+    };
+    const out = await orch._runWithConcurrency(items, limit, worker);
+    expect(out).toEqual(items);
+    expect(peak).toBeLessThanOrEqual(limit);
+    expect(peak).toBeGreaterThan(1); // proves it actually parallelised
+  });
+
+  test('limit >= item count behaves like Promise.all (all start immediately)', async () => {
+    const orch = new Orchestrator(baseConfig());
+    let inFlight = 0;
+    let peak = 0;
+    const items = [1, 2, 3];
+    await orch._runWithConcurrency(items, 10, async (n) => {
+      inFlight += 1;
+      peak = Math.max(peak, inFlight);
+      await Promise.resolve();
+      inFlight -= 1;
+      return n;
+    });
+    expect(peak).toBe(items.length);
+  });
+
+  test('empty input resolves to an empty array', async () => {
+    const orch = new Orchestrator(baseConfig());
+    await expect(orch._runWithConcurrency([], 4, async (n) => n)).resolves.toEqual([]);
+  });
+});
+
+describe('Orchestrator._phaseConcurrency (per-phase override)', () => {
+  test('falls back to the global cap when a phase has no max_concurrency', () => {
+    const orch = new Orchestrator(baseConfig({ max_concurrency: 5 }));
+    expect(orch._phaseConcurrency({ name: 'p', parallel: [] })).toBe(5);
+  });
+
+  test('a phase max_concurrency overrides the global cap (both directions)', () => {
+    const orch = new Orchestrator(baseConfig({ max_concurrency: 5 }));
+    expect(orch._phaseConcurrency({ name: 'serial', max_concurrency: 1 })).toBe(1);
+    expect(orch._phaseConcurrency({ name: 'wider', max_concurrency: 8 })).toBe(8);
+  });
+
+  test('a phase\'s \'auto\' resolves to cpuCount - 1 regardless of the global cap', () => {
+    const orch = new Orchestrator(baseConfig({ max_concurrency: 1 }));
+    expect(orch._phaseConcurrency({ name: 'p', max_concurrency: 'auto' })).toBe(cpuAuto());
+  });
+
+  test('an invalid phase value falls back to auto, not to the global cap', () => {
+    const orch = new Orchestrator(baseConfig({ max_concurrency: 5 }));
+    expect(orch._phaseConcurrency({ name: 'p', max_concurrency: 0 })).toBe(cpuAuto());
+    expect(orch._phaseConcurrency({ name: 'p', max_concurrency: 'lots' })).toBe(cpuAuto());
+  });
+});