scripts-orchestrator 2.15.1 → 3.5.0

package/README.md

@@ -41,6 +41,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
 
@@ -48,12 +49,14 @@ Create a configuration file (default: `scripts-orchestrator.config.js`) that def
 
 ```javascript
 {
-  command: 'command_name',           // The npm script to run
+  command: 'command_name',           // The command to run (see "Command prefix" below)
   description: 'Description',        // Optional description
   status: 'enabled',                 // 'enabled' or 'disabled'
   attempts: 1,                       // Number of retry attempts
   dependencies: [],                 // Array of dependent commands
   background: false,                // Whether to run in background
+  shell: false,                     // true => run `command` verbatim as a shell command (no prefix)
+  prefix: 'npm run',                // Optional per-command prefix override ('' to disable)
   env: {                            // Optional environment variables
     PORT: 3000,
     NODE_ENV: 'production'
@@ -70,6 +73,44 @@ Create a configuration file (default: `scripts-orchestrator.config.js`) that def
 }
 ```
 
+### Command prefix (`npm run` is optional)
+
+By default every `command` is run as an npm script — the orchestrator prepends `npm run`,
+so `command: 'build'` executes `npm run build`. This prefix is configurable:
+
+- **Global default** — set `command_prefix` at the top level of the config. Use it to point at a
+  different runner (`'pnpm run'`, `'yarn'`) or to disable prefixing entirely so commands run as
+  regular shell commands:
+
+  ```javascript
+  export default {
+    command_prefix: '',              // '' / false / null => run commands verbatim (plain shell)
+    phases: [
+      { name: 'checks', parallel: [
+        { command: 'eslint . --max-warnings 0' },   // runs as-is, supports args/pipes/&&
+        { command: './scripts/verify.sh' },
+      ]},
+    ],
+  };
+  ```
+
+- **Per command** — `shell: true` forces a single command to run verbatim as a shell command
+  (ignoring any global prefix), and `prefix: '...'` overrides the prefix for just that command:
+
+  ```javascript
+  {
+    phases: [{ name: 'mixed', parallel: [
+      { command: 'build' },                          // -> npm run build (global default)
+      { command: 'docker compose up -d', shell: true }, // raw shell command
+      { command: 'release', prefix: 'yarn' },        // -> yarn release
+    ]}],
+  }
+  ```
+
+Precedence per command: `shell: true` (raw) → per-command `prefix` → global `command_prefix`
+→ the built-in `npm run` default. Existing configs are unaffected — omitting all of these keeps
+the original `npm run` behaviour.
+
 ### Phase Configuration
 
 When using the phases format, each phase can have the following properties:
@@ -488,11 +529,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

@@ -60,6 +60,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 +153,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 +253,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 +268,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 +315,14 @@ 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;
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {
@@ -248,6 +335,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.js

@@ -6,6 +6,7 @@ import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
 import { GitCache } from './git-cache.js';
 import { renderReportHtml } from './report-html.js';
+import { findRepoRoot, writeAggregateReport } from './workspaces.js';
 import chalk from 'chalk';
 
 export class Orchestrator {
@@ -27,6 +28,12 @@ export class Orchestrator {
     this.sequential = sequential;
     this.force = force;
     this.metrics = Array.isArray(metrics) ? metrics : [];
+    // Global command prefix. Defaults to 'npm run' so existing configs keep working.
+    // Set `command_prefix` to '' / false / null in the config to run commands verbatim
+    // as regular shell commands. Per-command `shell: true` or `prefix` overrides this.
+    this.commandPrefix = Object.prototype.hasOwnProperty.call(config ?? {}, 'command_prefix')
+      ? this._normalizePrefix(config.command_prefix)
+      : 'npm run';
     this.jsonResultsPath = jsonResultsPath ?? null;
     this.htmlResultsPath = htmlResultsPath ?? null;
     this.processManager = processManager;
@@ -49,9 +56,21 @@ export class Orchestrator {
       : null;
     // post-run hook command (shell string)
     this.postRun = null; // set from config in index.js
+    // Memory heat thresholds for the HTML report (fractions of the run's peak). Set from config in
+    // index.js; embedded into the results payload so the renderer (and --render) honour them.
+    this.memoryHeat = null;
+    // Duration heat thresholds for the HTML report (fractions of the run's slowest command). Set from
+    // config in index.js; embedded into the results payload so the renderer (and --render) honour them.
+    this.durationHeat = null;
     // Periodic hook: shell command fired on an interval while the run is in flight (set in index.js).
     // The library owns only the cadence; the command itself is project-specific (e.g. roll-up render).
     this.periodicHook = null;
+    // Declarative npm-workspace roll-up (set from config in index.js). When non-null, the library
+    // drives the workspace aggregate IN-PROCESS — no shell-out — using these writeAggregateReport
+    // options: the repo-root run owns the periodic cadence + final static report, while a fanned-out
+    // workspace run refreshes the roll-up once when it finishes. Replaces wiring a periodic_hook /
+    // post_run that shells out to `scripts-orchestrator --aggregate`.
+    this.aggregateOptions = null;
     this.periodicIntervalMs = 45000;
     this._periodicTimer = null;
     this._periodicRunning = false;
@@ -180,6 +199,8 @@ export class Orchestrator {
       ...(this.startTime ? { overallDurationMs: Date.now() - this.startTime } : {}), // elapsed so far
       commands,
       ...(this.config.phases && this.phaseResults.length > 0 ? { phases: this.phaseResults } : {}),
+      ...(this.memoryHeat ? { memoryHeat: this.memoryHeat } : {}),
+      ...(this.durationHeat ? { durationHeat: this.durationHeat } : {}),
     };
 
     const tmpPath = outPath + '.tmp';
@@ -263,6 +284,29 @@ export class Orchestrator {
     }
   }
 
+  // Normalize a prefix value into a clean string. false/null/'' all mean "no prefix"
+  // (run the command verbatim); any string is trimmed.
+  _normalizePrefix(value) {
+    if (value === false || value === null || value === undefined) return '';
+    return String(value).trim();
+  }
+
+  // Resolve the effective prefix for a single command.
+  // Precedence: per-command `shell: true` (raw) > per-command `prefix` > global commandPrefix.
+  _resolvePrefix(commandConfig = {}) {
+    if (commandConfig.shell === true) return '';
+    if (Object.prototype.hasOwnProperty.call(commandConfig, 'prefix')) {
+      return this._normalizePrefix(commandConfig.prefix);
+    }
+    return this.commandPrefix;
+  }
+
+  // Format a command for display, honoring its resolved prefix.
+  _displayCommand(command, commandConfig = {}) {
+    const prefix = this._resolvePrefix(commandConfig);
+    return prefix ? `${prefix} ${command}` : command;
+  }
+
   async executeCommand(commandConfig, visited = new Set(), phaseName = null) {
     const {
       command,
@@ -281,6 +325,8 @@ export class Orchestrator {
     } = commandConfig;
 
     const startTime = Date.now();
+    // Effective invocation prefix for this command ('' => run verbatim as a shell command).
+    const prefix = this._resolvePrefix(commandConfig);
 
     // Record the destination log file for this command (honors per-command override).
     // Done early so even disabled/skipped commands report where output would land.
@@ -303,7 +349,7 @@ export class Orchestrator {
 
     // Skip execution if the command is disabled
     if (status === 'disabled') {
-      this.logger.warn(`Skipping: npm run ${command} (status: disabled)`);
+      this.logger.warn(`Skipping: ${this._displayCommand(command, commandConfig)} (status: disabled)`);
       this.skippedCommands.push(command);
       this.skipReasons.set(command, 'disabled');
       setTiming(Date.now() - startTime);
@@ -336,6 +382,7 @@ export class Orchestrator {
           startedByScript: false,
           process_tracking,
           kill_command,
+          prefix,
         });
         setTiming(Date.now() - startTime);
         visited.delete(command);
@@ -411,6 +458,7 @@ export class Orchestrator {
         env,
         reportTime: this.metrics.includes('time'),
         reportMemory: this.metrics.includes('memory'),
+        prefix,
       });
       lastRunResult = runResult;
       const { success, output } = runResult;
@@ -564,6 +612,8 @@ export class Orchestrator {
       ...(this.config.phases && this.phaseResults.length > 0
         ? { phases: this.phaseResults }
         : {}),
+      ...(this.memoryHeat ? { memoryHeat: this.memoryHeat } : {}),
+      ...(this.durationHeat ? { durationHeat: this.durationHeat } : {}),
     };
 
     const json = JSON.stringify(payload, null, 2);
@@ -860,11 +910,43 @@ export class Orchestrator {
     }
   }
 
+  // Is this process the repo-root orchestrator run (vs. a fanned-out workspace run)? The root run
+  // owns the periodic roll-up cadence and the final static report; a workspace run only refreshes
+  // the aggregate once as it finishes (mirrors the old root periodic_hook / workspace post_run split).
+  _isRepoRootRun() {
+    try {
+      const root = findRepoRoot(process.cwd());
+      return root != null && path.resolve(process.cwd()) === root;
+    } catch {
+      return false;
+    }
+  }
+
+  // Roll up every workspace's results into the aggregate report, in-process. inProgress is left
+  // undefined (auto-detected from the root run-state file) except for the root run's final fire.
+  _fireAggregate(inProgress) {
+    try {
+      const opts = inProgress == null
+        ? this.aggregateOptions
+        : { ...this.aggregateOptions, inProgress };
+      const { jsonPath } = writeAggregateReport(opts);
+      this.logger.verbose(`[aggregate] rolled up workspaces → ${jsonPath}`);
+    } catch (err) {
+      this.logger.warn(`[aggregate] roll-up failed: ${err.message}`);
+    }
+  }
+
   // Periodic hook: start the interval timer (fires once promptly, then every interval).
   _startPeriodicHook() {
-    if (!this.periodicHook || this._periodicTimer) return;
+    if (this._periodicTimer) return;
+    if (!this.periodicHook && !this.aggregateOptions) return;
+    // In-process aggregate: only the repo-root run drives the periodic cadence. A fanned-out
+    // workspace run refreshes the roll-up just once, at the end (see _firePeriodicHookFinal).
+    if (this.aggregateOptions && !this.periodicHook && !this._isRepoRootRun()) return;
     this.logger.info(
-      `⏱️  Periodic report hook every ${Math.round(this.periodicIntervalMs / 1000)}s: ${this.periodicHook}`,
+      this.periodicHook
+        ? `⏱️  Periodic report hook every ${Math.round(this.periodicIntervalMs / 1000)}s: ${this.periodicHook}`
+        : `⏱️  Periodic workspace roll-up every ${Math.round(this.periodicIntervalMs / 1000)}s (in-process)`,
     );
     this._firePeriodicTick(); // prompt first roll-up so an initial aggregate exists
     this._periodicTimer = setInterval(() => this._firePeriodicTick(), this.periodicIntervalMs);
@@ -873,6 +955,11 @@ export class Orchestrator {
 
   // Fire the periodic hook asynchronously, with an overlap guard so slow hooks don't pile up.
   _firePeriodicTick() {
+    // In-process aggregate path: synchronous, so no overlap guard needed.
+    if (this.aggregateOptions && !this.periodicHook) {
+      this._fireAggregate(undefined);
+      return;
+    }
     if (!this.periodicHook || this._periodicRunning) {
       if (this._periodicRunning) {
         this.logger.verbose('[periodic_hook] previous invocation still running; skipping tick');
@@ -914,6 +1001,14 @@ export class Orchestrator {
 
   // Final synchronous fire so the aggregate reflects the finished run before the process exits.
   _firePeriodicHookFinal() {
+    // In-process aggregate path: the repo-root run owns the "run complete" signal, so it forces a
+    // static (non-refresh) report. A fanned-out workspace run must NOT — the root run is still in
+    // flight, so leave inProgress auto-detected from the (still-present) root run-state file.
+    if (this.aggregateOptions && !this.periodicHook) {
+      this._stopPeriodicHook();
+      this._fireAggregate(this._isRepoRootRun() ? false : undefined);
+      return;
+    }
     if (!this.periodicHook) return;
     this._stopPeriodicHook();
     try {

package/lib/orchestrator.prefix.test.js

@@ -0,0 +1,60 @@
+import { Orchestrator } from './orchestrator.js';
+
+const baseConfig = (extra = {}) => ({
+  phases: [{ name: 'p', parallel: [{ command: 'build' }] }],
+  ...extra,
+});
+
+describe('Orchestrator command prefix resolution', () => {
+  test('defaults to "npm run" when no command_prefix is configured', () => {
+    const orch = new Orchestrator(baseConfig());
+    expect(orch.commandPrefix).toBe('npm run');
+    expect(orch._resolvePrefix({ command: 'build' })).toBe('npm run');
+    expect(orch._displayCommand('build', { command: 'build' })).toBe('npm run build');
+  });
+
+  test('global command_prefix can be disabled with empty string', () => {
+    const orch = new Orchestrator(baseConfig({ command_prefix: '' }));
+    expect(orch.commandPrefix).toBe('');
+    expect(orch._resolvePrefix({ command: 'ls -la' })).toBe('');
+    expect(orch._displayCommand('ls -la', { command: 'ls -la' })).toBe('ls -la');
+  });
+
+  test('global command_prefix can be disabled with false or null', () => {
+    expect(new Orchestrator(baseConfig({ command_prefix: false })).commandPrefix).toBe('');
+    expect(new Orchestrator(baseConfig({ command_prefix: null })).commandPrefix).toBe('');
+  });
+
+  test('global command_prefix can be set to a custom runner', () => {
+    const orch = new Orchestrator(baseConfig({ command_prefix: 'pnpm run' }));
+    expect(orch._resolvePrefix({ command: 'build' })).toBe('pnpm run');
+    expect(orch._displayCommand('build', { command: 'build' })).toBe('pnpm run build');
+  });
+
+  test('per-command shell:true runs verbatim as a bash command (overrides global)', () => {
+    const orch = new Orchestrator(baseConfig({ command_prefix: 'npm run' }));
+    const cmd = { command: 'echo hello && ls', shell: true };
+    expect(orch._resolvePrefix(cmd)).toBe('');
+    expect(orch._displayCommand('echo hello && ls', cmd)).toBe('echo hello && ls');
+  });
+
+  test('per-command prefix string overrides the global prefix', () => {
+    const orch = new Orchestrator(baseConfig({ command_prefix: 'npm run' }));
+    const cmd = { command: 'build', prefix: 'yarn' };
+    expect(orch._resolvePrefix(cmd)).toBe('yarn');
+    expect(orch._displayCommand('build', cmd)).toBe('yarn build');
+  });
+
+  test('per-command empty prefix runs verbatim even when global prefix is set', () => {
+    const orch = new Orchestrator(baseConfig({ command_prefix: 'npm run' }));
+    const cmd = { command: 'make build', prefix: '' };
+    expect(orch._resolvePrefix(cmd)).toBe('');
+    expect(orch._displayCommand('make build', cmd)).toBe('make build');
+  });
+
+  test('shell:true takes precedence over an explicit prefix', () => {
+    const orch = new Orchestrator(baseConfig());
+    const cmd = { command: 'echo hi', shell: true, prefix: 'yarn' };
+    expect(orch._resolvePrefix(cmd)).toBe('');
+  });
+});