scripts-orchestrator 2.14.0 → 2.15.0

package/README.md

@@ -40,6 +40,7 @@ npm install --save-dev scripts-orchestrator
 - **NDJSON event stream**: Machine-readable per-command events for dashboards (v2.14+)
 - **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+)
 
 ## Configuration
 
@@ -522,6 +523,50 @@ This is useful when you want to:
 - Debug issues without modifying the codebase
 - Override the cache in CI/CD pipelines
 
+## 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.
+
+```bash
+# Analyse an existing results JSON and print a suggested phase layout
+scripts-orchestrator --recommend ./logs/scripts-orchestrator-results.json
+
+# 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
+
+# Override the memory budget explicitly (MB) or change the RAM safety fraction
+scripts-orchestrator --recommend ./logs/results.json --budget-mb 8192
+scripts-orchestrator --recommend ./logs/results.json --mem-safety 0.7
+```
+
+It reports two 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.
+2. **Recommended layout** — a [First-Fit-Decreasing](https://en.wikipedia.org/wiki/Bin_packing_problem)
+   bin-packing by duration that groups steps into sequential phases so each phase's concurrent peak
+   memory stays under `budget = totalmem × memSafety ÷ fanout` and its step count stays under
+   `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.
+
+The same logic is exported for programmatic use:
+
+```js
+import { recommendPhases, formatRecommendationReport } from 'scripts-orchestrator';
+
+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, …
+```
+
+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.
+
 ## Exit Codes
 
 - `0`: All commands executed successfully
@@ -535,6 +580,7 @@ See [versions](./docs/versions.md)
 - Better UX to indicate what is happening
 - Tests to avoid regression
 - Run any shell command rather than assume the command is specified in package.json (? tentative)
+- Promote the advisory `--recommend` phase recommender into an opt-in automatic scheduler that packs each phase under a per-host memory budget at run time
 
 
 ## Disclaimer

package/index.js

@@ -51,10 +51,87 @@ const argv = yargs(hideBin(process.argv))
     type: 'string',
     description: 'Write HTML report to this path; use "-" for stdout only',
   })
+  .option('render', {
+    type: 'string',
+    description: 'Render an existing results JSON file to HTML (no run). Use with --html-results.',
+  })
+  .option('recommend', {
+    type: 'string',
+    description:
+      'Analyse an existing results JSON and print a memory-aware phase recommendation (R12, no run).',
+  })
+  .option('fanout', {
+    type: 'number',
+    description: 'Workspace fan-out (parallel gates sharing the host) used to size the --recommend budget. Default 1.',
+  })
+  .option('mem-safety', {
+    type: 'number',
+    description: 'Fraction of total RAM the --recommend budget may use (default 0.8).',
+  })
+  .option('budget-mb', {
+    type: 'number',
+    description: 'Override the --recommend memory budget with a fixed value in MB.',
+  })
   .help()
   .alias('h', 'help')
   .parse();
 
+// --render mode: turn an existing results JSON into HTML and exit (no orchestration run).
+// Keeps all HTML rendering in the library so consumers never reimplement it.
+if (argv.render != null) {
+  const { renderReportHtml } = await import('./lib/index.js');
+  const srcPath = path.resolve(process.cwd(), argv.render);
+  if (!fs.existsSync(srcPath)) {
+    log.error(`Error: --render source not found at ${srcPath}`);
+    process.exit(1);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
+  } catch (err) {
+    log.error(`Error: failed to parse --render JSON: ${err.message}`);
+    process.exit(1);
+  }
+  const html = renderReportHtml(payload);
+  const out = argv.htmlResults ?? null;
+  if (out == null || out === '-') {
+    console.log(html);
+  } else {
+    const outPath = path.resolve(process.cwd(), out);
+    const tmpPath = outPath + '.tmp';
+    fs.mkdirSync(path.dirname(outPath), { recursive: true });
+    fs.writeFileSync(tmpPath, html, 'utf8');
+    fs.renameSync(tmpPath, outPath);
+    log.info(`📄 Rendered ${path.relative(process.cwd(), srcPath)} → ${path.relative(process.cwd(), outPath)}`);
+  }
+  process.exit(0);
+}
+
+// --recommend mode: analyse an existing results JSON and print a memory-aware phase
+// recommendation (R12). Advisory only — no orchestration run, no files written.
+if (argv.recommend != null) {
+  const { recommendPhases, formatRecommendationReport } = await import('./lib/index.js');
+  const srcPath = path.resolve(process.cwd(), argv.recommend);
+  if (!fs.existsSync(srcPath)) {
+    log.error(`Error: --recommend source not found at ${srcPath}`);
+    process.exit(1);
+  }
+  let payload;
+  try {
+    payload = JSON.parse(fs.readFileSync(srcPath, 'utf8'));
+  } catch (err) {
+    log.error(`Error: failed to parse --recommend JSON: ${err.message}`);
+    process.exit(1);
+  }
+  const rec = recommendPhases(payload, {
+    fanout: argv.fanout,
+    memSafety: argv.memSafety,
+    budgetMb: argv.budgetMb,
+  });
+  console.log(formatRecommendationReport(rec, { sourcePath: path.relative(process.cwd(), srcPath) }));
+  process.exit(0);
+}
+
 // Extract arguments
 const args = argv._;
 const configPath = args[0] || './scripts-orchestrator.config.js';
@@ -114,6 +191,13 @@ const htmlResultsPath =
 // A7: 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
+// results into an aggregate report). Library owns only the cadence; the command is project-specific.
+const periodicHook = commandsConfig.periodic_hook ?? null;
+const periodicIntervalMs = Number(commandsConfig.periodic_interval_ms) > 0
+  ? Number(commandsConfig.periodic_interval_ms)
+  : 45000;
+
 // Set the log folder for the main orchestrator logs if specified
 if (logFolder) {
   log.setLogFolder(logFolder);
@@ -133,10 +217,14 @@ const orchestrator = new Orchestrator(
 );
 // A7: wire post-run hook from config
 orchestrator.postRun = postRun;
+// Wire periodic hook (cadence owned by the library)
+orchestrator.periodicHook = periodicHook;
+orchestrator.periodicIntervalMs = periodicIntervalMs;
 
 // Enhanced signal handlers
 const handleSignal = async (signal) => {
   log.warn(`\nReceived ${signal} signal. Cleaning up...`);
+  orchestrator._stopPeriodicHook();
   try {
     await orchestrator.processManager.cleanup();
   } catch (error) {

package/lib/index.js

@@ -3,6 +3,28 @@ import { ProcessManager } from './process-manager.js';
 import { HealthCheck } from './health-check.js';
 import { Logger } from './logger.js';
 import { GitCache } from './git-cache.js';
+import { renderReportHtml } from './report-html.js';
+import {
+  recommendPhases,
+  formatRecommendationReport,
+  computeBudget,
+  usableSteps,
+  observedTimeline,
+  packPhases,
+} from './recommend-phases.js';
 
-export { Orchestrator, ProcessManager, HealthCheck, Logger, GitCache };
-export default Orchestrator; 
+export {
+  Orchestrator,
+  ProcessManager,
+  HealthCheck,
+  Logger,
+  GitCache,
+  renderReportHtml,
+  recommendPhases,
+  formatRecommendationReport,
+  computeBudget,
+  usableSteps,
+  observedTimeline,
+  packPhases,
+};
+export default Orchestrator;

package/lib/orchestrator.js

@@ -1,10 +1,11 @@
 import fs from 'fs';
 import path from 'path';
-import { spawnSync } from 'child_process';
+import { spawn, spawnSync } from 'child_process';
 import { processManager } from './process-manager.js';
 import { healthCheck } from './health-check.js';
 import { log } from './logger.js';
 import { GitCache } from './git-cache.js';
+import { renderReportHtml } from './report-html.js';
 import chalk from 'chalk';
 
 export class Orchestrator {
@@ -35,6 +36,7 @@ export class Orchestrator {
     this.skippedCommands = [];
     this.skipReasons = new Map(); // Track why commands were skipped
     this.commandTimings = new Map(); // command -> { durationMs, memoryKb? }
+    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
@@ -47,6 +49,13 @@ export class Orchestrator {
       : null;
     // A7: 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).
+    this.periodicHook = null;
+    this.periodicIntervalMs = 45000;
+    this._periodicTimer = null;
+    this._periodicRunning = false;
+    this._periodicChild = null;
 
     // Set the log folder in process manager
     if (logFolder) {
@@ -122,7 +131,13 @@ export class Orchestrator {
       const done = timing != null || skipped;
 
       if (!done && startedAt) {
-        return { command, ...(phaseName ? { phase: phaseName } : {}), success: null, startedAt };
+        return {
+          command,
+          ...(phaseName ? { phase: phaseName } : {}),
+          success: null,
+          startedAt,
+          ...this._logFileField(command),
+        };
       }
       if (!done) return null; // not yet started — omit
 
@@ -137,8 +152,10 @@ export class Orchestrator {
         command,
         ...(phaseName ? { phase: phaseName } : {}),
         success,
-        ...(timing?.durationMs != null && this.metrics.includes('time') ? { durationMs: timing.durationMs } : {}),
+        ...(startedAt ? { startedAt } : {}),
+        ...(timing?.durationMs != null ? { durationMs: timing.durationMs } : {}),
         ...(this.metrics.includes('memory') ? { memoryKb: timing?.memoryKb ?? null } : {}),
+        ...this._logFileField(command),
         ...(skipReason ? { skipReason } : {}),
       };
     };
@@ -160,6 +177,7 @@ export class Orchestrator {
     const payload = {
       success: null, // in-progress sentinel; replaced by writeJsonResults on completion
       timestamp: new Date().toISOString(),
+      ...(this.startTime ? { overallDurationMs: Date.now() - this.startTime } : {}), // elapsed so far
       commands,
       ...(this.config.phases && this.phaseResults.length > 0 ? { phases: this.phaseResults } : {}),
     };
@@ -173,6 +191,17 @@ export class Orchestrator {
       this.logger.verbose(`Partial results write failed: ${err.message}`);
     }
 
+    // Incrementally refresh the HTML report too (like merge-report:live), so a live,
+    // up-to-date report exists from the first command onward and survives interruption.
+    // Skip the stdout sink ('-') to avoid spamming the console on every update.
+    if (this.htmlResultsPath != null && this.htmlResultsPath !== '-') {
+      try {
+        this.writeHtmlResults(payload);
+      } catch (err) {
+        this.logger.verbose(`Partial HTML write failed: ${err.message}`);
+      }
+    }
+
     // A4: 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;
@@ -193,6 +222,47 @@ export class Orchestrator {
     return `${seconds}s`;
   }
 
+  // Resolve a command's destination log file as a path relative to cwd (absolute if outside),
+  // returned as a spreadable object so callers can inline it into result entries.
+  _logFileField(command) {
+    const p = this.commandLogPaths.get(command);
+    if (!p) return {};
+    let rel = p;
+    try {
+      const r = path.relative(process.cwd(), p);
+      if (r && !r.startsWith('..')) rel = r;
+    } catch {
+      // keep absolute path on any failure
+    }
+    return { logFile: rel };
+  }
+
+  // The important output files this run produces, as [label, absolutePath] pairs.
+  // Excludes stdout sinks ('-'). Used to announce report locations in the logs.
+  _reportFiles() {
+    const files = [];
+    if (this.jsonResultsPath != null && this.jsonResultsPath !== '-') {
+      files.push(['JSON results', path.resolve(this.jsonResultsPath || './scripts-orchestrator-results.json')]);
+    }
+    if (this.htmlResultsPath != null && this.htmlResultsPath !== '-') {
+      files.push(['HTML report', path.resolve(this.htmlResultsPath || './scripts-orchestrator-results.html')]);
+    }
+    if (this.eventsPath) {
+      files.push(['Events (NDJSON)', path.resolve(this.eventsPath)]);
+    }
+    return files;
+  }
+
+  // Announce report file locations in the logs (prefix e.g. 'Live reports' / 'Reports written').
+  _announceReportFiles(prefix) {
+    const files = this._reportFiles();
+    if (files.length === 0) return;
+    this.logger.info(`📄 ${prefix}:`);
+    for (const [label, file] of files) {
+      this.logger.info(`   • ${label}: ${file}`);
+    }
+  }
+
   async executeCommand(commandConfig, visited = new Set(), phaseName = null) {
     const {
       command,
@@ -212,6 +282,10 @@ export class Orchestrator {
 
     const startTime = Date.now();
 
+    // Record the destination log file for this command (honors per-command override).
+    // Done early so even disabled/skipped commands report where output would land.
+    this.commandLogPaths.set(command, this.processManager.getLogPath(command, log || logFile));
+
     const setTiming = (durationMs, memoryKb = null) => {
       this.commandTimings.set(command, { durationMs, memoryKb });
     };
@@ -420,10 +494,7 @@ export class Orchestrator {
   }
 
   writeJsonResults(hasFailures) {
-    const overallDurationMs =
-      this.metrics.includes('time') && this.startTime
-        ? Date.now() - this.startTime
-        : undefined;
+    const overallDurationMs = this.startTime ? Date.now() - this.startTime : undefined;
 
     const commands = [];
     if (Array.isArray(this.config)) {
@@ -441,12 +512,14 @@ export class Orchestrator {
         const entry = {
           command,
           success,
-          ...(timing?.durationMs != null && this.metrics.includes('time')
-            ? { durationMs: timing.durationMs }
+          ...(this.commandStartTimes.has(command)
+            ? { startedAt: this.commandStartTimes.get(command) }
             : {}),
+          ...(timing?.durationMs != null ? { durationMs: timing.durationMs } : {}),
           ...(this.metrics.includes('memory')
             ? { memoryKb: timing?.memoryKb ?? null }
             : {}),
+          ...this._logFileField(command),
           ...(skipReason ? { skipReason } : {}),
         };
         commands.push(entry);
@@ -468,12 +541,14 @@ export class Orchestrator {
             command,
             phase: phase.name,
             success,
-            ...(timing?.durationMs != null && this.metrics.includes('time')
-              ? { durationMs: timing.durationMs }
+            ...(this.commandStartTimes.has(command)
+              ? { startedAt: this.commandStartTimes.get(command) }
               : {}),
+            ...(timing?.durationMs != null ? { durationMs: timing.durationMs } : {}),
             ...(this.metrics.includes('memory')
               ? { memoryKb: timing?.memoryKb ?? null }
               : {}),
+            ...this._logFileField(command),
             ...(skipReason ? { skipReason } : {}),
           };
           commands.push(entry);
@@ -503,131 +578,24 @@ export class Orchestrator {
     if (this.htmlResultsPath != null) {
       this.writeHtmlResults(payload);
     }
-  }
 
-  formatMs(ms) {
-    if (ms == null || ms === 0) return '—';
-    if (ms < 1000) return `${ms}ms`;
-    const s = (ms / 1000).toFixed(1);
-    return `${s}s`;
+    // Announce the important output files so they're easy to find in the logs.
+    this._announceReportFiles('Reports written');
   }
 
   writeHtmlResults(payload) {
-    const escapeHtml = (s) => {
-      if (s == null) return '';
-      return String(s)
-        .replace(/&/g, '&amp;')
-        .replace(/</g, '&lt;')
-        .replace(/>/g, '&gt;')
-        .replace(/"/g, '&quot;');
-    };
-    const { success, timestamp, overallDurationMs, commands = [], phases = [] } = payload;
-    const maxDuration = Math.max(0, ...commands.map((c) => c.durationMs || 0), ...phases.map((p) => p.durationMs || 0));
-    const maxMemory = Math.max(0, ...commands.map((c) => c.memoryKb || 0));
-
-    const row = (c) => {
-      const durationPct = maxDuration > 0 && c.durationMs != null ? (c.durationMs / maxDuration) * 100 : 0;
-      const memoryPct = maxMemory > 0 && c.memoryKb != null ? (c.memoryKb / maxMemory) * 100 : 0;
-      const statusClass = c.success ? 'ok' : 'fail';
-      const statusLabel = c.success ? 'OK' : (c.skipReason || 'Failed');
-      return `
-        <tr class="${statusClass}">
-          <td><code>${escapeHtml(c.command)}</code></td>
-          <td>${c.phase != null ? escapeHtml(c.phase) : '—'}</td>
-          <td><span class="badge ${statusClass}">${escapeHtml(statusLabel)}</span></td>
-          <td>${this.formatMs(c.durationMs)}</td>
-          <td>${c.memoryKb != null ? `${(c.memoryKb / 1024).toFixed(1)} MB` : '—'}</td>
-          <td class="bar-cell"><div class="bar" style="width:${durationPct}%"></div></td>
-          <td class="bar-cell"><div class="bar mem" style="width:${memoryPct}%"></div></td>
-        </tr>`;
-    };
-
-    const phaseRow = (p) => {
-      const durationPct = maxDuration > 0 && p.durationMs != null ? (p.durationMs / maxDuration) * 100 : 0;
-      const statusClass = p.success ? 'ok' : 'fail';
-      return `
-        <tr class="${statusClass}">
-          <td>${escapeHtml(p.name)}</td>
-          <td><span class="badge ${statusClass}">${p.success ? 'OK' : 'Failed'}</span></td>
-          <td>${this.formatMs(p.durationMs)}</td>
-          <td class="bar-cell"><div class="bar" style="width:${durationPct}%"></div></td>
-        </tr>`;
-    };
-
-    const html = `<!DOCTYPE html>
-<html lang="en">
-<head>
-  <meta charset="utf-8">
-  <title>Scripts Orchestrator Report</title>
-  <style>
-    * { box-sizing: border-box; }
-    body { font-family: system-ui, sans-serif; margin: 1rem 2rem; background: #1a1a1a; color: #e0e0e0; }
-    h1 { font-size: 1.5rem; margin-bottom: 0.5rem; }
-    .summary { display: flex; gap: 1.5rem; flex-wrap: wrap; margin-bottom: 1.5rem; }
-    .summary .card { background: #2a2a2a; padding: 1rem 1.25rem; border-radius: 8px; min-width: 140px; }
-    .summary .card.success { border-left: 4px solid #22c55e; }
-    .summary .card.fail { border-left: 4px solid #ef4444; }
-    .summary .label { font-size: 0.75rem; text-transform: uppercase; color: #888; }
-    .summary .value { font-size: 1.25rem; font-weight: 600; }
-    section { margin-bottom: 1.5rem; }
-    section h2 { font-size: 1.1rem; color: #a0a0a0; margin-bottom: 0.5rem; }
-    table { width: 100%; border-collapse: collapse; background: #2a2a2a; border-radius: 8px; overflow: hidden; }
-    th, td { padding: 0.5rem 0.75rem; text-align: left; }
-    th { background: #333; color: #888; font-weight: 600; font-size: 0.8rem; }
-    tr.fail { background: rgba(239,68,68,0.08); }
-    .badge { padding: 0.2rem 0.5rem; border-radius: 4px; font-size: 0.8rem; }
-    .badge.ok { background: #22c55e; color: #0f0f0f; }
-    .badge.fail { background: #ef4444; color: #fff; }
-    .bar-cell { width: 120px; }
-    .bar { height: 8px; background: #3b82f6; border-radius: 4px; min-width: 2px; }
-    .bar.mem { background: #8b5cf6; }
-    code { font-size: 0.9em; background: #333; padding: 0.1rem 0.3rem; border-radius: 4px; }
-  </style>
-</head>
-<body>
-  <h1>Scripts Orchestrator Report</h1>
-  <div class="summary">
-    <div class="card ${success ? 'success' : 'fail'}">
-      <div class="label">Status</div>
-      <div class="value">${success ? 'Success' : 'Failed'}</div>
-    </div>
-    <div class="card">
-      <div class="label">Timestamp</div>
-      <div class="value" style="font-size:0.9rem">${escapeHtml(timestamp)}</div>
-    </div>
-    ${overallDurationMs != null ? `
-    <div class="card">
-      <div class="label">Total time</div>
-      <div class="value">${this.formatMs(overallDurationMs)}</div>
-    </div>` : ''}
-  </div>
-
-  ${phases.length > 0 ? `
-  <section>
-    <h2>Phases</h2>
-    <table>
-      <thead><tr><th>Phase</th><th>Status</th><th>Duration</th><th></th></tr></thead>
-      <tbody>${phases.map(phaseRow).join('')}</tbody>
-    </table>
-  </section>` : ''}
-
-  <section>
-    <h2>Commands</h2>
-    <table>
-      <thead><tr><th>Command</th><th>Phase</th><th>Status</th><th>Duration</th><th>Memory</th><th>Time</th><th>Memory</th></tr></thead>
-      <tbody>${commands.map(row).join('')}</tbody>
-    </table>
-  </section>
-</body>
-</html>`;
-
+    const html = renderReportHtml(payload);
     if (this.htmlResultsPath === '-') {
       console.log(html);
-    } else {
-      const outPath = this.htmlResultsPath || './scripts-orchestrator-results.html';
-      fs.writeFileSync(outPath, html, 'utf8');
-      this.logger.verbose(`Wrote HTML report to ${outPath}`);
+      return;
     }
+    const outPath = this.htmlResultsPath || './scripts-orchestrator-results.html';
+    // Atomic write so live reloaders (incremental refresh) never read a half-written file.
+    const tmpPath = outPath + '.tmp';
+    fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+    fs.writeFileSync(tmpPath, html, 'utf8');
+    fs.renameSync(tmpPath, outPath);
+    this.logger.verbose(`Wrote HTML report to ${outPath}`);
   }
 
   async run() {
@@ -654,6 +622,13 @@ export class Orchestrator {
       let phaseFailed = false;
       let startPhaseFound = false;
 
+      // Announce where the live report files will be written (they update incrementally,
+      // so they can be opened to watch progress while the run is in flight).
+      this._announceReportFiles('Live reports (updated as the run progresses)');
+
+      // Start the periodic roll-up hook (no-op unless configured).
+      this._startPeriodicHook();
+
       // Handle both old array format and new phases format
       if (Array.isArray(this.config)) {
         // Legacy: Run all commands in parallel or sequential based on flag
@@ -757,7 +732,7 @@ export class Orchestrator {
           this.phaseResults.push({
             name: phase.name,
             success: !phaseHasFailures,
-            durationMs: this.metrics.includes('time') ? phaseDurationMs : undefined,
+            durationMs: phaseDurationMs,
           });
 
           if (phaseHasFailures) {
@@ -845,6 +820,10 @@ export class Orchestrator {
       // A4: 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
       this._runPostRunHook(hasFailures);
 
@@ -864,6 +843,9 @@ export class Orchestrator {
     } catch (error) {
       this.logger.error(`Orchestrator failed: ${error.message}`);
 
+      // Stop periodic ticks on error.
+      this._stopPeriodicHook();
+
       // A4: clear run-state on error too
       this._clearRunState();
 
@@ -878,6 +860,74 @@ export class Orchestrator {
     }
   }
 
+  // Periodic hook: start the interval timer (fires once promptly, then every interval).
+  _startPeriodicHook() {
+    if (!this.periodicHook || this._periodicTimer) return;
+    this.logger.info(
+      `⏱️  Periodic report hook every ${Math.round(this.periodicIntervalMs / 1000)}s: ${this.periodicHook}`,
+    );
+    this._firePeriodicTick(); // prompt first roll-up so an initial aggregate exists
+    this._periodicTimer = setInterval(() => this._firePeriodicTick(), this.periodicIntervalMs);
+    if (this._periodicTimer.unref) this._periodicTimer.unref();
+  }
+
+  // Fire the periodic hook asynchronously, with an overlap guard so slow hooks don't pile up.
+  _firePeriodicTick() {
+    if (!this.periodicHook || this._periodicRunning) {
+      if (this._periodicRunning) {
+        this.logger.verbose('[periodic_hook] previous invocation still running; skipping tick');
+      }
+      return;
+    }
+    this._periodicRunning = true;
+    try {
+      const child = spawn(this.periodicHook, {
+        shell: true,
+        stdio: 'ignore',
+        cwd: process.cwd(),
+        env: { ...process.env, SCRIPTS_ORCHESTRATOR_PERIODIC: '1' },
+      });
+      this._periodicChild = child;
+      child.on('exit', (code) => {
+        this._periodicRunning = false;
+        this._periodicChild = null;
+        if (code && code !== 0) this.logger.verbose(`[periodic_hook] exited with code ${code}`);
+      });
+      child.on('error', (err) => {
+        this._periodicRunning = false;
+        this._periodicChild = null;
+        this.logger.warn(`[periodic_hook] failed: ${err.message}`);
+      });
+    } catch (err) {
+      this._periodicRunning = false;
+      this.logger.warn(`[periodic_hook] error: ${err.message}`);
+    }
+  }
+
+  // Stop scheduling further periodic ticks.
+  _stopPeriodicHook() {
+    if (this._periodicTimer) {
+      clearInterval(this._periodicTimer);
+      this._periodicTimer = null;
+    }
+  }
+
+  // Final synchronous fire so the aggregate reflects the finished run before the process exits.
+  _firePeriodicHookFinal() {
+    if (!this.periodicHook) return;
+    this._stopPeriodicHook();
+    try {
+      spawnSync(this.periodicHook, {
+        shell: true,
+        stdio: 'ignore',
+        cwd: process.cwd(),
+        env: { ...process.env, SCRIPTS_ORCHESTRATOR_PERIODIC: 'final' },
+      });
+    } catch (err) {
+      this.logger.warn(`[periodic_hook] final invocation failed: ${err.message}`);
+    }
+  }
+
   // A7: run user-configured post_run shell command
   _runPostRunHook(hasFailures) {
     if (!this.postRun) return;

package/lib/process-manager.js

@@ -28,7 +28,9 @@ export class ProcessManager {
     this.logger.verbose(`Log folder set to: ${logFolder}`);
   }
 
-  getLogPath(command) {
+  getLogPath(command, logFileOverride = null) {
+    // A per-command 'log'/'logFile' override wins, resolved against cwd.
+    if (logFileOverride) return path.resolve(logFileOverride);
     const baseDir = this.logFolder
       ? path.resolve(this.logFolder)
       : process.cwd();
@@ -98,7 +100,8 @@ export class ProcessManager {
     const LOGS_DIR = path.join(baseDir, 'scripts-orchestrator-logs');
     // Use only the first word of the command for the log filename
     const logName = cmd.split(/\s+/)[0];
-    const LOG_FILE = logFile || path.join(LOGS_DIR, `${logName}.log`);
+    // Single source of truth for the destination log path (honors per-command override).
+    const LOG_FILE = this.getLogPath(cmd, logFile);
 
     try {
       if (!fs.existsSync(LOGS_DIR)) {