scripts-orchestrator 2.13.0 → 2.15.0

package/lib/orchestrator.js

@@ -1,8 +1,11 @@
 import fs from 'fs';
+import path from 'path';
+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 {
@@ -33,8 +36,26 @@ 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
+    this.commandStartTimes = new Map(); // command -> ISO start string
+    // A2: events file path derived from jsonResultsPath
+    this.eventsPath = this._deriveEventsPath(jsonResultsPath);
+    // A4: 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)
+    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) {
@@ -58,6 +79,138 @@ export class Orchestrator {
     return [];
   }
 
+  _deriveEventsPath(jsonResultsPath) {
+    if (!jsonResultsPath || jsonResultsPath === '-') return null;
+    return jsonResultsPath.replace(/\.json$/, '') + '-events.ndjson';
+  }
+
+  // A4: write current run state atomically
+  _writeRunState(extra = {}) {
+    if (!this.runStatePath) return;
+    const state = {
+      startedAt: this.runStartedAt ? new Date(this.runStartedAt).toISOString() : new Date().toISOString(),
+      pid: process.pid,
+      ...extra,
+    };
+    const tmp = this.runStatePath + '.tmp';
+    try {
+      fs.mkdirSync(path.dirname(this.runStatePath), { recursive: true });
+      fs.writeFileSync(tmp, JSON.stringify(state, null, 2) + '\n', 'utf8');
+      fs.renameSync(tmp, this.runStatePath);
+    } catch { /* non-fatal */ }
+  }
+
+  // A4: 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
+  _appendEvent(type, data = {}) {
+    if (!this.eventsPath) return;
+    const line = JSON.stringify({ type, timestamp: new Date().toISOString(), ...data });
+    try {
+      fs.appendFileSync(this.eventsPath, line + '\n', 'utf8');
+    } catch {
+      // non-fatal: don't let event logging break the run
+    }
+  }
+
+  // A1: 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';
+
+    const commands = [];
+
+    const buildEntry = (command, phaseName) => {
+      const timing = this.commandTimings.get(command);
+      const startedAt = this.commandStartTimes.get(command);
+      const skipped = this.skippedCommands.includes(command);
+      const done = timing != null || skipped;
+
+      if (!done && startedAt) {
+        return {
+          command,
+          ...(phaseName ? { phase: phaseName } : {}),
+          success: null,
+          startedAt,
+          ...this._logFileField(command),
+        };
+      }
+      if (!done) return null; // not yet started — omit
+
+      const skipReason = skipped ? (this.skipReasons.get(command) ?? null) : null;
+      const success =
+        !this.failedCommands.includes(command) &&
+        (skipReason === null ||
+          skipReason === 'disabled' ||
+          skipReason === 'optional_phase_not_requested' ||
+          skipReason === 'before_start_phase');
+      return {
+        command,
+        ...(phaseName ? { phase: phaseName } : {}),
+        success,
+        ...(startedAt ? { startedAt } : {}),
+        ...(timing?.durationMs != null ? { durationMs: timing.durationMs } : {}),
+        ...(this.metrics.includes('memory') ? { memoryKb: timing?.memoryKb ?? null } : {}),
+        ...this._logFileField(command),
+        ...(skipReason ? { skipReason } : {}),
+      };
+    };
+
+    if (Array.isArray(this.config)) {
+      for (const { command } of this.config) {
+        const entry = buildEntry(command, null);
+        if (entry) commands.push(entry);
+      }
+    } else if (this.config.phases) {
+      for (const phase of this.config.phases) {
+        for (const { command } of (phase.parallel || [])) {
+          const entry = buildEntry(command, phase.name);
+          if (entry) commands.push(entry);
+        }
+      }
+    }
+
+    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 } : {}),
+    };
+
+    const tmpPath = outPath + '.tmp';
+    try {
+      fs.mkdirSync(path.dirname(path.resolve(outPath)), { recursive: true });
+      fs.writeFileSync(tmpPath, JSON.stringify(payload, null, 2), 'utf8');
+      fs.renameSync(tmpPath, outPath);
+    } catch (err) {
+      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;
+    this._writeRunState({
+      activeCommand: inFlight.length === 1 ? inFlight[0] : (inFlight.length > 1 ? inFlight : null),
+      phase: currentPhase,
+    });
+  }
+
   formatDuration(ms) {
     if (ms < 1000) return `${ms}ms`;
     const seconds = Math.floor(ms / 1000);
@@ -69,7 +222,48 @@ export class Orchestrator {
     return `${seconds}s`;
   }
 
-  async executeCommand(commandConfig, visited = new Set()) {
+  // 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,
       dependencies = [],
@@ -88,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 });
     };
@@ -184,6 +382,11 @@ export class Orchestrator {
       }
     }
 
+    // A1/A2: record start and emit event
+    this.commandStartTimes.set(command, new Date().toISOString());
+    this._appendEvent('command_start', { command, phase: phaseName, scope: 'workspace' });
+    this._writePartialResults();
+
     // Execute the main command with retries
     let result = false;
     let commandOutput = '';
@@ -258,6 +461,9 @@ export class Orchestrator {
 
     const totalDurationMs = Date.now() - startTime;
     setTiming(totalDurationMs, lastRunResult?.memoryKb ?? null);
+    // A1/A2: emit completion event and write incremental results
+    this._appendEvent('command_end', { command, phase: phaseName, success: result, durationMs: totalDurationMs });
+    this._writePartialResults();
     visited.delete(command);
     return result;
   }
@@ -288,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)) {
@@ -309,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);
@@ -336,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);
@@ -371,135 +578,31 @@ 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() {
     this.startTime = Date.now();
+    this.runStartedAt = this.startTime;
+    // A4: 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)
       if (!this.force) {
@@ -519,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
@@ -598,7 +708,7 @@ export class Orchestrator {
             // Run commands sequentially
             results = [];
             for (const commandConfig of phase.parallel) {
-              const result = await this.executeCommand(commandConfig);
+              const result = await this.executeCommand(commandConfig, new Set(), phase.name);
               results.push(result);
               if (!result) {
                 // In sequential mode, stop phase execution on first failure
@@ -608,7 +718,7 @@ export class Orchestrator {
           } else {
             // Run commands in parallel
             const tasks = phase.parallel.map((commandConfig) =>
-              this.executeCommand(commandConfig),
+              this.executeCommand(commandConfig, new Set(), phase.name),
             );
             results = await Promise.all(tasks);
           }
@@ -622,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) {
@@ -698,11 +808,25 @@ export class Orchestrator {
         );
       }
 
+      // A2: emit run_end event; A1: 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 } : {}) });
+
       // Write JSON results if requested
       if (this.jsonResultsPath != null) {
         this.writeJsonResults(hasFailures);
       }
 
+      // 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);
+
       // Update git cache on successful execution
       if (!hasFailures) {
         await this.gitCache.updateCache();
@@ -719,6 +843,12 @@ 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();
+
       // Cleanup on error
       try {
         await this.processManager.cleanup();
@@ -729,4 +859,91 @@ export class Orchestrator {
       process.exit(1);
     }
   }
+
+  // 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;
+    this.logger.info(`[post_run] ${this.postRun}`);
+    const result = spawnSync(this.postRun, {
+      shell: true,
+      stdio: 'inherit',
+      cwd: process.cwd(),
+      env: {
+        ...process.env,
+        SCRIPTS_ORCHESTRATOR_SUCCESS: hasFailures ? '0' : '1',
+        SCRIPTS_ORCHESTRATOR_EXIT_CODE: hasFailures ? '1' : '0',
+      },
+    });
+    if (result.status !== 0) {
+      this.logger.warn(`[post_run] hook exited with code ${result.status}`);
+    }
+  }
 }

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)) {

package/lib/process-manager.test.js

@@ -0,0 +1,22 @@
+import path from 'path';
+import { ProcessManager } from './process-manager.js';
+
+describe('ProcessManager.getLogPath', () => {
+  test('resolves the default per-command log path under the log folder', () => {
+    const pm = new ProcessManager();
+    pm.setLogFolder('/tmp/example-logs');
+    const result = pm.getLogPath('build -- --outDir dist');
+    // Uses only the first word of the command for the filename.
+    expect(result).toBe(
+      path.join('/tmp/example-logs', 'scripts-orchestrator-logs', 'build.log'),
+    );
+  });
+
+  test('honors a per-command log file override, resolved against cwd', () => {
+    const pm = new ProcessManager();
+    pm.setLogFolder('/tmp/example-logs');
+    const override = './logs/scripts-orchestrator-logs/custom.log';
+    const result = pm.getLogPath('lint', override);
+    expect(result).toBe(path.resolve(override));
+  });
+});