scripts-orchestrator 2.15.0 → 3.0.0

package/README.md

@@ -48,12 +48,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 +72,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:
@@ -451,7 +491,7 @@ Alongside `json_results`, the library writes one NDJSON line per event to
 Dashboard tools can `tail -f` this file or watch it with `fs.watch` to get real-time updates
 without parsing human-readable log lines.
 
-### Run-state file (A4)
+### Run-state file
 
 When `--logFolder` is specified, the library writes `{logFolder}/.scripts-orchestrator-run.json`
 at run start and removes it on run end:
@@ -468,7 +508,7 @@ at run start and removes it on run end:
 This file is the authoritative in-progress signal for live dashboards. Its absence means the run
 has finished (or never started).
 
-### Post-run hook (A7)
+### Post-run hook
 
 Add `post_run` to your config to run a shell command **after** `json_results` is written and the
 run-state file is cleared, but **before** `process.exit()`:
@@ -526,13 +566,16 @@ This is useful when you want to:
 ## Phase Recommendations (advisory)
 
 When a run is executed with `metrics: ['time', 'memory']`, the results JSON records each command's
-`durationMs` and peak `memoryKb`. The `--recommend` mode reads that JSON and prints a **memory-aware
-phase recommendation**: it never runs anything and writes no files.
+`durationMs` and peak `memoryKb`. The `--recommend` mode reads that JSON and reports a **memory-aware
+phase recommendation**: it never runs anything and changes no run state.
 
 ```bash
-# Analyse an existing results JSON and print a suggested phase layout
+# Analyse an existing results JSON and print a suggested phase layout to the console
 scripts-orchestrator --recommend ./logs/scripts-orchestrator-results.json
 
+# Write the report to a plain-text log file instead of the console (only a pointer line is printed)
+scripts-orchestrator --recommend ./logs/results.json --recommend-out ./logs/recommendation.log
+
 # Size the budget for a machine running N gates in parallel (each gets 1/N of RAM and cores)
 scripts-orchestrator --recommend ./logs/scripts-orchestrator-results.json --fanout 3
 
@@ -541,7 +584,7 @@ scripts-orchestrator --recommend ./logs/results.json --budget-mb 8192
 scripts-orchestrator --recommend ./logs/results.json --mem-safety 0.7
 ```
 
-It reports two things:
+It reports three things:
 
 1. **Observed timeline** — each phase's wall-clock (the longest step in it) and the concurrent peak
    memory (Σ of member peaks), flagging any phase whose concurrent peak exceeds the host budget.
@@ -551,6 +594,9 @@ It reports two things:
    `coreShare = (cores − 2) ÷ fanout`. Long steps seed phases; short steps fill the gaps beneath them,
    so the estimated makespan stays near the theoretical floor (the single longest step) without
    oversubscribing RAM.
+3. **Verdict** — a single yes/no line: whether re-grouping is worth it (it must trim ≥5% and ≥5s off
+   the makespan), or — when one step is ≥95% of the makespan — that the only remaining lever is to
+   split that step into smaller commands the orchestrator can schedule separately.
 
 The same logic is exported for programmatic use:
 
@@ -560,9 +606,12 @@ import { recommendPhases, formatRecommendationReport } from 'scripts-orchestrato
 const payload = JSON.parse(fs.readFileSync('./logs/results.json', 'utf8'));
 const rec = recommendPhases(payload, { fanout: 3 });
 console.log(formatRecommendationReport(rec));
-// rec.recommended.bins, rec.observed, rec.observedMakespanMs, rec.budgetBytes, …
+// rec.verdict.worthwhile, rec.verdict.reason, rec.recommended.bins, rec.observed, rec.budgetBytes, …
 ```
 
+A natural place to wire it is the `post_run` config hook, so each run prints a recommendation for its
+own results JSON when it finishes.
+
 This is advisory only — the budget is conservative (per-process peaks summed as if they coincide) and
 the packing does not model inter-phase data dependencies, so validate any suggested layout against a
 real run before adopting it.

package/index.js

@@ -58,7 +58,7 @@ const argv = yargs(hideBin(process.argv))
   .option('recommend', {
     type: 'string',
     description:
-      'Analyse an existing results JSON and print a memory-aware phase recommendation (R12, no run).',
+      'Analyse an existing results JSON and print a memory-aware phase recommendation (no run).',
   })
   .option('fanout', {
     type: 'number',
@@ -72,6 +72,10 @@ const argv = yargs(hideBin(process.argv))
     type: 'number',
     description: 'Override the --recommend memory budget with a fixed value in MB.',
   })
+  .option('recommend-out', {
+    type: 'string',
+    description: 'Write the --recommend report to this file (plain text) instead of the console.',
+  })
   .help()
   .alias('h', 'help')
   .parse();
@@ -108,7 +112,8 @@ if (argv.render != null) {
 }
 
 // --recommend mode: analyse an existing results JSON and print a memory-aware phase
-// recommendation (R12). Advisory only — no orchestration run, no files written.
+// recommendation. Advisory only — no orchestration run. Output goes to the console, or to a
+// plain-text log file when --recommend-out is given.
 if (argv.recommend != null) {
   const { recommendPhases, formatRecommendationReport } = await import('./lib/index.js');
   const srcPath = path.resolve(process.cwd(), argv.recommend);
@@ -128,7 +133,18 @@ if (argv.recommend != null) {
     memSafety: argv.memSafety,
     budgetMb: argv.budgetMb,
   });
-  console.log(formatRecommendationReport(rec, { sourcePath: path.relative(process.cwd(), srcPath) }));
+  const report = formatRecommendationReport(rec, { sourcePath: path.relative(process.cwd(), srcPath) });
+  if (argv.recommendOut != null && argv.recommendOut !== '-') {
+    // Strip ANSI colour codes so the log file stays plain text. The escape char is built at runtime
+    // so the regex carries no literal control character (keeps eslint's no-control-regex happy).
+    const ansi = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g');
+    const outPath = path.resolve(process.cwd(), argv.recommendOut);
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(outPath, report.replace(ansi, '') + '\n', 'utf8');
+    log.info(`📄 Phase recommendation written to ${path.relative(process.cwd(), outPath)}`);
+  } else {
+    console.log(report);
+  }
   process.exit(0);
 }
 
@@ -188,7 +204,7 @@ const htmlResultsPath =
     ? argv.htmlResults
     : (commandsConfig.html_results ?? commandsConfig.html_results_path ?? null);
 
-// A7: post-run hook — shell command run after json_results written
+// post-run hook — shell command run after json_results written
 const postRun = commandsConfig.post_run ?? null;
 
 // Periodic hook — shell command run on an interval WHILE the run is in flight (e.g. to roll up
@@ -215,7 +231,7 @@ const orchestrator = new Orchestrator(
   jsonResultsPath,
   htmlResultsPath,
 );
-// A7: wire post-run hook from config
+// wire post-run hook from config
 orchestrator.postRun = postRun;
 // Wire periodic hook (cadence owned by the library)
 orchestrator.periodicHook = periodicHook;
@@ -230,7 +246,7 @@ const handleSignal = async (signal) => {
   } catch (error) {
     log.error(`Cleanup failed: ${error.message}`);
   }
-  // A4: clear run-state so dashboards know the run ended
+  // clear run-state so dashboards know the run ended
   orchestrator._clearRunState();
   process.exit(1);
 };

package/lib/index.js

@@ -6,6 +6,7 @@ import { GitCache } from './git-cache.js';
 import { renderReportHtml } from './report-html.js';
 import {
   recommendPhases,
+  decideVerdict,
   formatRecommendationReport,
   computeBudget,
   usableSteps,
@@ -21,6 +22,7 @@ export {
   GitCache,
   renderReportHtml,
   recommendPhases,
+  decideVerdict,
   formatRecommendationReport,
   computeBudget,
   usableSteps,

package/lib/orchestrator.js

@@ -27,6 +27,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;
@@ -39,15 +45,15 @@ export class Orchestrator {
     this.commandLogPaths = new Map(); // command -> resolved destination log file (absolute)
     this.phaseResults = []; // { name, success, durationMs } per phase run
     this.gitCache = new GitCache(logFolder);
-    // A1: track per-command start times for incremental JSON
+    // track per-command start times for incremental JSON
     this.commandStartTimes = new Map(); // command -> ISO start string
-    // A2: events file path derived from jsonResultsPath
+    // events file path derived from jsonResultsPath
     this.eventsPath = this._deriveEventsPath(jsonResultsPath);
-    // A4: library-owned run-state file
+    // library-owned run-state file
     this.runStatePath = logFolder
       ? path.join(path.resolve(logFolder), '.scripts-orchestrator-run.json')
       : null;
-    // A7: post-run hook command (shell string)
+    // post-run hook command (shell string)
     this.postRun = null; // set from config in index.js
     // 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).
@@ -84,7 +90,7 @@ export class Orchestrator {
     return jsonResultsPath.replace(/\.json$/, '') + '-events.ndjson';
   }
 
-  // A4: write current run state atomically
+  // write current run state atomically
   _writeRunState(extra = {}) {
     if (!this.runStatePath) return;
     const state = {
@@ -100,13 +106,13 @@ export class Orchestrator {
     } catch { /* non-fatal */ }
   }
 
-  // A4: remove run-state file on run end
+  // remove run-state file on run end
   _clearRunState() {
     if (!this.runStatePath) return;
     try { fs.unlinkSync(this.runStatePath); } catch { /* ignore */ }
   }
 
-  // A2: append a structured NDJSON event
+  // append a structured NDJSON event
   _appendEvent(type, data = {}) {
     if (!this.eventsPath) return;
     const line = JSON.stringify({ type, timestamp: new Date().toISOString(), ...data });
@@ -117,7 +123,7 @@ export class Orchestrator {
     }
   }
 
-  // A1: atomically write current run state (completed + in-flight commands) to json_results
+  // atomically write current run state (completed + in-flight commands) to json_results
   _writePartialResults() {
     if (this.jsonResultsPath == null || this.jsonResultsPath === '-') return;
     const outPath = this.jsonResultsPath || './scripts-orchestrator-results.json';
@@ -202,7 +208,7 @@ export class Orchestrator {
       }
     }
 
-    // A4: keep run-state file in sync with current active commands and phase
+    // keep run-state file in sync with current active commands and phase
     const inFlight = commands.filter(c => c.success === null).map(c => c.command);
     const currentPhase = commands.length > 0 ? (commands[commands.length - 1].phase ?? null) : null;
     this._writeRunState({
@@ -263,6 +269,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 +310,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 +334,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 +367,7 @@ export class Orchestrator {
           startedByScript: false,
           process_tracking,
           kill_command,
+          prefix,
         });
         setTiming(Date.now() - startTime);
         visited.delete(command);
@@ -382,7 +414,7 @@ export class Orchestrator {
       }
     }
 
-    // A1/A2: record start and emit event
+    // record start and emit event
     this.commandStartTimes.set(command, new Date().toISOString());
     this._appendEvent('command_start', { command, phase: phaseName, scope: 'workspace' });
     this._writePartialResults();
@@ -411,6 +443,7 @@ export class Orchestrator {
         env,
         reportTime: this.metrics.includes('time'),
         reportMemory: this.metrics.includes('memory'),
+        prefix,
       });
       lastRunResult = runResult;
       const { success, output } = runResult;
@@ -461,7 +494,7 @@ export class Orchestrator {
 
     const totalDurationMs = Date.now() - startTime;
     setTiming(totalDurationMs, lastRunResult?.memoryKb ?? null);
-    // A1/A2: emit completion event and write incremental results
+    // emit completion event and write incremental results
     this._appendEvent('command_end', { command, phase: phaseName, success: result, durationMs: totalDurationMs });
     this._writePartialResults();
     visited.delete(command);
@@ -601,7 +634,7 @@ export class Orchestrator {
   async run() {
     this.startTime = Date.now();
     this.runStartedAt = this.startTime;
-    // A4: write initial run-state at start
+    // write initial run-state at start
     this._writeRunState({ phase: null, activeCommand: null });
     try {
       // Check if we should skip execution based on git state (unless forced)
@@ -808,7 +841,7 @@ export class Orchestrator {
         );
       }
 
-      // A2: emit run_end event; A1: final JSON written by writeJsonResults (replaces partial)
+      // emit run_end event; final JSON written by writeJsonResults (replaces partial)
       const runDurationMs = this.startTime ? Date.now() - this.startTime : undefined;
       this._appendEvent('run_end', { success: !hasFailures, ...(runDurationMs != null ? { durationMs: runDurationMs } : {}) });
 
@@ -817,14 +850,14 @@ export class Orchestrator {
         this.writeJsonResults(hasFailures);
       }
 
-      // A4: clear run-state file — run is done
+      // clear run-state file — run is done
       this._clearRunState();
 
       // Final roll-up (synchronous) AFTER run-state is cleared, so the aggregate reflects the
       // finished run (an in-flight marker would otherwise make the final report read as running).
       this._firePeriodicHookFinal();
 
-      // A7: run post_run hook after results are written
+      // run post_run hook after results are written
       this._runPostRunHook(hasFailures);
 
       // Update git cache on successful execution
@@ -846,7 +879,7 @@ export class Orchestrator {
       // Stop periodic ticks on error.
       this._stopPeriodicHook();
 
-      // A4: clear run-state on error too
+      // clear run-state on error too
       this._clearRunState();
 
       // Cleanup on error
@@ -928,7 +961,7 @@ export class Orchestrator {
     }
   }
 
-  // A7: run user-configured post_run shell command
+  // run user-configured post_run shell command
   _runPostRunHook(hasFailures) {
     if (!this.postRun) return;
     this.logger.info(`[post_run] ${this.postRun}`);

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('');
+  });
+});

package/lib/process-manager.js

@@ -46,6 +46,7 @@ export class ProcessManager {
     startedByScript,
     process_tracking,
     kill_command,
+    prefix = 'npm run',
   }) {
     this.logger.verbose(`Adding background process: ${command} (${url})`);
     this.backgroundProcessesDetails.push({
@@ -54,6 +55,7 @@ export class ProcessManager {
       startedByScript,
       process_tracking,
       kill_command,
+      prefix,
     });
   }
 
@@ -93,7 +95,13 @@ export class ProcessManager {
     env = null,
     reportTime = false,
     reportMemory = false,
+    prefix = 'npm run',
   }) {
+    // Resolve how the command is invoked. A non-empty prefix (e.g. 'npm run') is
+    // prepended to the command name; an empty/false prefix runs the command verbatim
+    // as a regular shell command. `displayCmd` is what we surface in logs.
+    const commandPrefix = prefix ? String(prefix).trim() : '';
+    const displayCmd = commandPrefix ? `${commandPrefix} ${cmd}` : cmd;
     const baseDir = this.logFolder
       ? path.resolve(this.logFolder)
       : process.cwd();
@@ -131,12 +139,12 @@ export class ProcessManager {
       const startTime = Date.now();
       let timeOutputPath = null;
       // Build command with environment variables if provided
-      let fullCommand = `npm run ${cmd}`;
+      let fullCommand = displayCmd;
       if (env && Object.keys(env).length > 0) {
         const envStr = Object.entries(env)
           .map(([key, value]) => `${key}=${value}`)
           .join(' ');
-        fullCommand = `${envStr} npm run ${cmd}`;
+        fullCommand = `${envStr} ${displayCmd}`;
       }
       const useTimeWrapper =
         reportMemory && !background && (process.platform === 'linux' || process.platform === 'darwin');
@@ -286,6 +294,7 @@ export class ProcessManager {
                   url: healthCheck?.url,
                   startedByScript: true,
                   kill_command,
+                  prefix: commandPrefix,
                 });
 
                 this.logger.verbose(`Unreferencing process ${processGroupId}`);
@@ -293,7 +302,7 @@ export class ProcessManager {
 
                 this.logger.stopTask(cmd);
                 this.logger.verbose(
-                  `Background process started: npm run ${cmd} (PGID: ${processGroupId})`,
+                  `Background process started: ${displayCmd} (PGID: ${processGroupId})`,
                 );
                 return {
                   success: true,
@@ -304,7 +313,7 @@ export class ProcessManager {
               } catch (error) {
                 if (attempt === maxAttempts) {
                   this.logger.error(
-                    `Failed to start background process: npm run ${cmd}`,
+                    `Failed to start background process: ${displayCmd}`,
                   );
                   this.logger.verbose(
                     `Final verification attempt failed: ${error.message}`,
@@ -382,7 +391,7 @@ export class ProcessManager {
 
             if (code !== 0) {
               this.logger.error(
-                `Failed: npm run ${cmd} ❌${durationStr} (exit code: ${code})`,
+                `Failed: ${displayCmd} ❌${durationStr} (exit code: ${code})`,
               );
               this.logger.verbose(`Process output: ${output}`);
               resolve({
@@ -392,7 +401,7 @@ export class ProcessManager {
                 memoryKb,
               });
             } else {
-              this.logger.success(`Completed: npm run ${cmd} ✅${durationStr}`);
+              this.logger.success(`Completed: ${displayCmd} ✅${durationStr}`);
               resolve({
                 success: true,
                 output,
@@ -507,13 +516,14 @@ export class ProcessManager {
     );
 
     const killPromises = commandProcesses.map(
-      async ({ command, pgid, url, startedByScript, kill_command }) => {
+      async ({ command, pgid, url, startedByScript, kill_command, prefix }) => {
         await this.cleanupProcess({
           command,
           pgid,
           url,
           startedByScript,
           kill_command,
+          prefix,
         });
       },
     );
@@ -529,7 +539,7 @@ export class ProcessManager {
     );
   }
 
-  async cleanupProcess({ command, pgid, url, startedByScript, kill_command }) {
+  async cleanupProcess({ command, pgid, url, startedByScript, kill_command, prefix = 'npm run' }) {
     if (!startedByScript) {
       this.logger.verbose(
         `- Skipping cleanup for ${command} (${url}) as it was not started by this script`,
@@ -544,13 +554,15 @@ export class ProcessManager {
     // Try custom kill command first if specified
     if (kill_command) {
       try {
+        const killDisplay = prefix ? `${String(prefix).trim()} ${kill_command}` : kill_command;
         this.logger.verbose(
-          `- Using custom kill command: npm run ${kill_command}`,
+          `- Using custom kill command: ${killDisplay}`,
         );
         const result = await this.runCommand({
           cmd: kill_command,
           logFile: null,
           background: false,
+          prefix,
         });
         if (result.success) {
           this.logger.verbose(

package/lib/process-manager.test.js

@@ -1,4 +1,6 @@
 import path from 'path';
+import fs from 'fs';
+import os from 'os';
 import { ProcessManager } from './process-manager.js';
 
 describe('ProcessManager.getLogPath', () => {
@@ -20,3 +22,59 @@ describe('ProcessManager.getLogPath', () => {
     expect(result).toBe(path.resolve(override));
   });
 });
+
+describe('ProcessManager.runCommand prefix handling', () => {
+  let tmpDir;
+  let prevCwd;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), 'so-prefix-'));
+    prevCwd = process.cwd();
+    process.chdir(tmpDir);
+  });
+
+  afterEach(() => {
+    process.chdir(prevCwd);
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  test('runs a regular bash command verbatim when prefix is disabled', async () => {
+    const pm = new ProcessManager();
+    pm.setLogFolder(tmpDir);
+    const marker = 'orchestrator-raw-bash-ok';
+    const result = await pm.runCommand({
+      cmd: `echo ${marker}`,
+      background: false,
+      prefix: '',
+    });
+    expect(result.success).toBe(true);
+    const logPath = pm.getLogPath(`echo ${marker}`);
+    expect(fs.readFileSync(logPath, 'utf8')).toContain(marker);
+  });
+
+  test('honors a custom prefix by invoking it (failure surfaces a non-zero exit)', async () => {
+    const pm = new ProcessManager();
+    pm.setLogFolder(tmpDir);
+    // With prefix 'npm run' and no package.json script, the command must fail —
+    // proving the prefix is actually prepended rather than the command run raw.
+    const result = await pm.runCommand({
+      cmd: 'definitely-not-a-script',
+      background: false,
+      prefix: 'npm run',
+    });
+    expect(result.success).toBe(false);
+  });
+
+  test('supports multi-token shell commands (pipes, &&) when run raw', async () => {
+    const pm = new ProcessManager();
+    pm.setLogFolder(tmpDir);
+    const result = await pm.runCommand({
+      cmd: 'printf "a\\nb\\nc\\n" | grep b',
+      background: false,
+      prefix: '',
+    });
+    expect(result.success).toBe(true);
+    const logPath = pm.getLogPath('printf');
+    expect(fs.readFileSync(logPath, 'utf8').trim()).toBe('b');
+  });
+});

package/lib/recommend-phases.js

@@ -1,11 +1,11 @@
 /**
  * @file recommend-phases.js
- * @description R12 — memory-aware phase recommender (advisory).
+ * @description Memory-aware phase recommender (advisory).
  *
  * Reads a results JSON (the same payload the orchestrator writes via `metrics: ['time','memory']`)
  * and proposes a phase layout that keeps each phase's concurrent peak memory under a per-host
- * budget while letting long-running steps overlap. This is the "advisory" first step of R12:
- * it only reports — it does not change how a run is scheduled.
+ * budget while letting long-running steps overlap. It only reports — it does not change how a
+ * run is scheduled.
  *
  * Algorithm: First-Fit-Decreasing bin-packing by step duration. Steps are sorted longest-first
  * and each is placed into the earliest phase where adding it keeps Σ(concurrent peak memory) ≤ budget
@@ -26,8 +26,8 @@ const GB = 1024 * 1024 * 1024;
  * budget = totalmem × memSafety ÷ fanout   (overridable wholesale via budgetMb)
  * coreShare = (cores − 2) ÷ fanout         (≥ 1)
  *
- * `fanout` models the workspace-level parallelism (R1's `--parallel=N`): when N workspaces gate
- * concurrently they share the host, so each gets 1/N of RAM and cores.
+ * `fanout` models the workspace-level parallelism: when N workspaces gate concurrently they share
+ * the host, so each gets 1/N of RAM and cores.
  */
 export function computeBudget(opts = {}) {
   const totalMemBytes = opts.totalMemBytes != null ? Number(opts.totalMemBytes) : os.totalmem();
@@ -143,6 +143,18 @@ export function recommendPhases(payload, opts = {}) {
   const observedMakespanMs = observed.reduce((sum, p) => sum + p.wallclockMs, 0);
   const recommendedMakespanMs = bins.reduce((sum, b) => sum + b.wallclockMs, 0);
   const optimalMakespanMs = steps.length ? Math.max(...steps.map((s) => s.durationMs)) : 0;
+  const longestStep = steps.length
+    ? steps.reduce((a, b) => (b.durationMs > a.durationMs ? b : a))
+    : null;
+
+  const verdict = decideVerdict({
+    steps,
+    observedMakespanMs,
+    recommendedMakespanMs,
+    optimalMakespanMs,
+    longestStep,
+    binCount: bins.length,
+  });
 
   return {
     ...budget,
@@ -151,10 +163,70 @@ export function recommendPhases(payload, opts = {}) {
     observedMakespanMs,
     recommended: { bins, makespanMs: recommendedMakespanMs },
     optimalMakespanMs,
+    verdict,
     warnings,
   };
 }
 
+/**
+ * Reduce the numbers to a single yes/no answer: "is re-grouping these phases worth it?".
+ *
+ * Re-grouping helps only when packing meaningfully beats the observed makespan. It cannot beat the
+ * single longest step (the theoretical floor), so when one step dominates the makespan the honest
+ * answer is "no — splitting that step is the only lever left", not "re-group".
+ *
+ * Returns `{ worthwhile, savedMs, reason }`. Thresholds are deliberately conservative so the advice
+ * stays quiet unless there's a real, non-trivial win.
+ */
+export function decideVerdict({
+  steps,
+  observedMakespanMs,
+  recommendedMakespanMs,
+  optimalMakespanMs,
+  longestStep,
+  binCount,
+}) {
+  if (!steps.length) {
+    return { worthwhile: false, savedMs: 0, reason: 'No timed steps to analyse.' };
+  }
+
+  const savedMs = observedMakespanMs - recommendedMakespanMs;
+  const savedFraction = observedMakespanMs > 0 ? savedMs / observedMakespanMs : 0;
+  const dominantFraction = observedMakespanMs > 0 ? optimalMakespanMs / observedMakespanMs : 0;
+
+  // A real win: packing trims at least 5% AND at least 5s off the observed makespan.
+  const significant = savedMs >= 5000 && savedFraction >= 0.05;
+  if (significant) {
+    return {
+      worthwhile: true,
+      savedMs,
+      reason:
+        `Re-grouping into ${binCount} phase(s) could trim ~${fmtDuration(savedMs)} ` +
+        `(${Math.round(savedFraction * 100)}%) off the makespan.`,
+    };
+  }
+
+  // One step is ≥95% of the makespan: nothing else matters until it's broken up.
+  if (dominantFraction >= 0.95 && longestStep) {
+    return {
+      worthwhile: false,
+      savedMs,
+      reason:
+        `One step ("${longestStep.command}", ${fmtDuration(optimalMakespanMs)}) is ` +
+        `~${Math.round(dominantFraction * 100)}% of the makespan, so re-grouping the rest cannot help. ` +
+        'To go faster, split that step into smaller commands the orchestrator can schedule separately.',
+    };
+  }
+
+  return {
+    worthwhile: false,
+    savedMs,
+    reason:
+      `The current layout is already within ~${fmtDuration(Math.max(0, savedMs))} of the packed ` +
+      'optimum — re-grouping is not worth it.',
+  };
+}
+
 // ---- formatting helpers ---------------------------------------------------
 
 export function fmtDuration(ms) {
@@ -185,7 +257,7 @@ export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
   const c = chalk;
   const L = [];
 
-  L.push(c.bold('🧮 Scripts-Orchestrator — memory-aware phase recommendation (R12, advisory)'));
+  L.push(c.bold('🧮 Scripts-Orchestrator — memory-aware phase recommendation (advisory)'));
   if (sourcePath) L.push(c.dim(`   Source: ${sourcePath}`));
   L.push(
     `   Budget: ${c.yellow(fmtMemKb(rec.budgetBytes / KB))} ` +
@@ -194,7 +266,11 @@ export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
   );
 
   for (const w of rec.warnings) L.push(c.yellow(`   ⚠ ${w}`));
-  if (rec.steps.length === 0) return L.join('\n');
+  if (rec.steps.length === 0) {
+    L.push('');
+    L.push(`${c.bold('Verdict:')} ${verdictLine(rec.verdict)}`);
+    return L.join('\n');
+  }
 
   // Observed timeline
   L.push('');
@@ -239,6 +315,11 @@ export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
         : c.dim('(no change)');
   L.push(`  recommended (packed):         ${fmtDuration(rec.recommended.makespanMs)}  ${delta}`);
   L.push(`  theoretical floor (∞ RAM):    ${fmtDuration(rec.optimalMakespanMs)}`);
+
+  // Verdict — the one-line yes/no the reader actually wants.
+  L.push('');
+  L.push(`${c.bold('Verdict:')} ${verdictLine(rec.verdict)}`);
+
   L.push('');
   L.push(
     c.dim(
@@ -249,3 +330,11 @@ export function formatRecommendationReport(rec, { sourcePath = null } = {}) {
 
   return L.join('\n');
 }
+
+/** Render the verdict as a colored ✅/❌ one-liner. */
+function verdictLine(verdict) {
+  if (!verdict) return '';
+  return verdict.worthwhile
+    ? `${chalk.green('✅ Yes')} — ${verdict.reason}`
+    : `${chalk.yellow('❌ No')} — ${verdict.reason}`;
+}

package/lib/recommend-phases.test.js

@@ -4,6 +4,7 @@ import {
   observedTimeline,
   packPhases,
   recommendPhases,
+  decideVerdict,
   formatRecommendationReport,
 } from './recommend-phases.js';
 
@@ -104,4 +105,60 @@ describe('recommendPhases', () => {
     expect(rec.warnings.join(' ')).toMatch(/nothing to recommend/i);
     expect(() => formatRecommendationReport(rec)).not.toThrow();
   });
+
+  test('attaches a verdict object to the recommendation', () => {
+    const rec = recommendPhases(payload, { totalMemBytes: 16 * 1024 ** 3, cores: 10, fanout: 1 });
+    expect(rec.verdict).toBeDefined();
+    expect(typeof rec.verdict.worthwhile).toBe('boolean');
+    expect(typeof rec.verdict.reason).toBe('string');
+  });
+});
+
+describe('decideVerdict', () => {
+  const longest = { command: 'build', durationMs: 600000 };
+
+  test('says yes when packing trims a meaningful chunk off the makespan', () => {
+    const v = decideVerdict({
+      steps: [{}, {}, {}],
+      observedMakespanMs: 100000,
+      recommendedMakespanMs: 70000, // 30s / 30% saved
+      optimalMakespanMs: 60000,
+      longestStep: longest,
+      binCount: 2,
+    });
+    expect(v.worthwhile).toBe(true);
+    expect(v.savedMs).toBe(30000);
+  });
+
+  test('says no — and points at the monolith — when one step dominates', () => {
+    const v = decideVerdict({
+      steps: [{}, {}],
+      observedMakespanMs: 610000,
+      recommendedMakespanMs: 610000,
+      optimalMakespanMs: 600000, // ~98% of makespan
+      longestStep: longest,
+      binCount: 1,
+    });
+    expect(v.worthwhile).toBe(false);
+    expect(v.reason).toMatch(/split that step/i);
+    expect(v.reason).toContain('build');
+  });
+
+  test('says no when the saving is below the threshold', () => {
+    const v = decideVerdict({
+      steps: [{}, {}, {}, {}],
+      observedMakespanMs: 100000,
+      recommendedMakespanMs: 98000, // only 2% / 2s
+      optimalMakespanMs: 40000,
+      longestStep: longest,
+      binCount: 2,
+    });
+    expect(v.worthwhile).toBe(false);
+    expect(v.reason).toMatch(/isn't worth it|within/i);
+  });
+
+  test('handles the no-steps case', () => {
+    const v = decideVerdict({ steps: [], observedMakespanMs: 0, recommendedMakespanMs: 0, optimalMakespanMs: 0, longestStep: null, binCount: 0 });
+    expect(v.worthwhile).toBe(false);
+  });
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "scripts-orchestrator",
-  "version": "2.15.0",
+  "version": "3.0.0",
   "description": "A powerful script orchestrator for running parallel commands with dependency management, background processes, and health checks",
   "main": "lib/index.js",
   "type": "module",

package/scripts-orchestrator.config.js

@@ -1,4 +1,8 @@
 export default {
+  // Optional: prefix prepended to every command. Defaults to 'npm run'.
+  // Set to '' (or false/null) to run commands verbatim as regular shell commands,
+  // or to another runner like 'pnpm run'. Per-command `shell: true` / `prefix` override this.
+  // command_prefix: 'npm run',
   // Optional: metrics to report (time, memory). CLI --metrics overrides.
   // metrics: ['time'],
   // Optional: path for JSON results, or '-' for stdout. CLI --json-results overrides.