mustflow 2.18.0 → 2.18.2

package/README.md

@@ -124,7 +124,7 @@ mustflow installs and validates an agent workflow for user projects.
 - Classifies changed files, public surfaces, and validation reasons with `mf classify`.
 - Prints execution-free verification plans with `mf verify --plan-only --json`, including a machine-readable verification decision graph and read-only local-index lock explanations when available.
 - Runs only allowed one-shot commands within a timeout via `mf run <intent>` or `mf verify` when the selected intent is runnable.
-- Writes command receipts to `.mustflow/state/runs/latest.json`.
+- Writes command receipts under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`.
 - Generates a concise repository navigation map, `REPO_MAP.md`, with `mf map`.
 - Indexes and searches mustflow docs, skills, skill routes, command rules, command-effect locks, file fingerprints, and opt-in source anchor metadata with SQLite via `mf index` and `mf search`. The local SQLite file is a rebuildable lookup cache, not a memory store, audit log, command transcript store, command-authority source, or source-content database.
 - Tracks agent-created or agent-modified documentation needing prose review with `mf docs review`.
@@ -358,7 +358,7 @@ Development servers, watch modes, browser UIs, interactive commands, and backgro
 
 Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents, command eligibility, remaining gaps, and missing runnable coverage without executing commands. Use `mf run <intent> --dry-run --json` to inspect one resolved command intent without spawning a process or writing a run receipt. Plan-only verification includes a `decision_graph` that connects changed surfaces, classification reasons, command candidates, eligibility checks, effects, and gaps. When `.mustflow/cache/mustflow.sqlite` is fresh, scheduled entries also include read-only `effectGraph` metadata for write locks and lock conflicts. These graph rows are marked `explanation_only` and never grant command authority; `.mustflow/config/commands.toml` remains the only runnable command source.
 
-Each executed command run writes the latest run record to `.mustflow/state/runs/latest.json`. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr.
+Each executed command run writes a run record under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr.
 
 ## Language and profiles
 

package/dist/cli/commands/explain-verify.js

@@ -5,7 +5,7 @@ import { createVerificationPlan, } from '../../core/verification-plan.js';
 import { createVerificationSchedule } from '../../core/verification-scheduler.js';
 import { t } from '../lib/i18n.js';
 import { readLatestLocalVerificationReadModelQueries, readLocalCommandEffectGraphs, } from '../lib/local-index.js';
-import { planErrorMessageKey, readInputFromPlan } from './verify.js';
+import { planErrorMessageKey, readInputFromClassificationReport } from './verify.js';
 export function parseExplainVerifyArgs(args) {
     let reason;
     let fromPlan;
@@ -69,7 +69,7 @@ export function explainVerifyPlanErrorMessage(error, lang) {
     return t(lang, planErrorMessageKey(code));
 }
 export function readExplainVerifyPlanReasons(projectRoot, planPath) {
-    return readInputFromPlan(projectRoot, planPath).reasons;
+    return readInputFromClassificationReport(projectRoot, planPath).reasons;
 }
 export async function getVerifyExplainOutput(schemaVersion, projectRoot, reasons, inputReason, planSource) {
     const contract = readCommandContract(projectRoot);

package/dist/cli/commands/run.js

@@ -10,10 +10,12 @@ import { t } from '../lib/i18n.js';
 import { getPackageVersion } from '../lib/package-info.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { createRunPlan, createRunPreview, isMustflowBuiltinIntent, renderRunPreviewText, } from '../lib/run-plan.js';
-import { createRunReceipt, writeRunReceipt } from '../../core/run-receipt.js';
+import { createRunReceipt, createRunReceiptRelativePath, writeRunReceipt, } from '../../core/run-receipt.js';
 import { recordRunPerformanceHistory } from '../../core/run-performance-history.js';
 import { RunProfiler } from '../../core/run-profile.js';
 import { finishRunWriteTracking, startRunWriteTracking } from '../../core/run-write-drift.js';
+const OUTPUT_LIMIT_ERROR_CODE = 'ENOBUFS';
+const OUTPUT_LIMIT_ERROR_MESSAGE = /\bmaxBuffer\b.*\bexceeded\b/i;
 function emitOutput(reporter, output, stream) {
     if (!output) {
         return;
@@ -103,6 +105,17 @@ function forceTerminateProcessTreeNonBlocking(pid) {
 function getKillMethod() {
     return process.platform === 'win32' ? 'taskkill_process_tree' : 'process_group_sigterm';
 }
+function createPendingTimeoutTermination(method) {
+    return {
+        reason: 'timeout',
+        method,
+        graceful_signal: 'SIGTERM',
+        forced_signal: 'SIGKILL',
+        forced_kill_attempted: true,
+        confirmed: false,
+        cleanup_pending: true,
+    };
+}
 function createBufferedReporter() {
     const stdout = [];
     const stderr = [];
@@ -212,19 +225,6 @@ async function runBuiltinArgvInProcess(commandArgv, cwd, lang) {
         };
     }
 }
-function runArgvCommand(command, cwd, maxOutputBytes, env, timeoutSeconds) {
-    return spawnSync(command?.executable ?? '', command?.args ?? [], {
-        cwd,
-        encoding: 'utf8',
-        input: '',
-        maxBuffer: maxOutputBytes,
-        env,
-        shell: command?.shell ?? false,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: timeoutSeconds * 1000,
-        windowsHide: true,
-    });
-}
 function writeStreamChunk(reporter, stream, chunk) {
     if (stream === 'stdout') {
         if (reporter.writeStdout) {
@@ -240,7 +240,12 @@ function writeStreamChunk(reporter, stream, chunk) {
     }
     reporter.stderr(chunk.toString());
 }
-function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter) {
+function createOutputLimitError(stream, maxOutputBytes) {
+    return Object.assign(new Error(`${stream} exceeded max_output_bytes (${maxOutputBytes})`), {
+        code: OUTPUT_LIMIT_ERROR_CODE,
+    });
+}
+function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
     return new Promise((resolve) => {
         const stdout = new BoundedOutputBuffer(stdoutTailBytes);
         const stderr = new BoundedOutputBuffer(stderrTailBytes);
@@ -248,11 +253,14 @@ function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBy
         let timedOut = false;
         let childError;
         let childPid;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
         let timeout;
-        const child = spawn(command?.executable ?? '', command?.args ?? [], {
+        let termination = null;
+        const child = spawn(command.executable, command.args ?? [], {
             cwd,
             env,
-            shell: command?.shell ?? false,
+            shell: command.shell,
             stdio: ['ignore', 'pipe', 'pipe'],
             windowsHide: true,
             detached: process.platform !== 'win32',
@@ -273,88 +281,40 @@ function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBy
                 stdout: stdout.toSnapshot(),
                 stderr: stderr.toSnapshot(),
                 pid: childPid,
+                termination,
             });
         };
-        child.stdout?.on('data', (chunk) => {
-            stdout.append(chunk);
-            writeStreamChunk(reporter, 'stdout', chunk);
-        });
-        child.stderr?.on('data', (chunk) => {
-            stderr.append(chunk);
-            writeStreamChunk(reporter, 'stderr', chunk);
-        });
-        child.once('error', (error) => {
-            childError = error;
-        });
-        child.once('close', (status, signal) => {
-            finish(status, signal);
-        });
-        timeout = setTimeout(() => {
-            timedOut = true;
+        const stopForOutputLimit = (stream) => {
+            if (settled || childError) {
+                return;
+            }
+            childError = createOutputLimitError(stream, maxOutputBytes);
             child.stdout?.destroy();
             child.stderr?.destroy();
             child.unref();
             terminateProcessTreeNonBlocking(childPid);
             forceTerminateProcessTreeNonBlocking(childPid);
             finish(null, null);
-        }, timeoutSeconds * 1000);
-    });
-}
-function runShellCommand(command, cwd, maxOutputBytes, env, timeoutSeconds) {
-    return spawnSync(command ?? '', {
-        cwd,
-        encoding: 'utf8',
-        input: '',
-        maxBuffer: maxOutputBytes,
-        env,
-        shell: true,
-        stdio: ['ignore', 'pipe', 'pipe'],
-        timeout: timeoutSeconds * 1000,
-        windowsHide: true,
-    });
-}
-function runShellCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter) {
-    return new Promise((resolve) => {
-        const stdout = new BoundedOutputBuffer(stdoutTailBytes);
-        const stderr = new BoundedOutputBuffer(stderrTailBytes);
-        let settled = false;
-        let timedOut = false;
-        let childError;
-        let childPid;
-        let timeout;
-        const child = spawn(command ?? '', {
-            cwd,
-            env,
-            shell: true,
-            stdio: ['ignore', 'pipe', 'pipe'],
-            windowsHide: true,
-            detached: process.platform !== 'win32',
-        });
-        childPid = child.pid;
-        const finish = (status, signal) => {
-            if (settled) {
-                return;
-            }
-            settled = true;
-            if (timeout) {
-                clearTimeout(timeout);
-            }
-            resolve({
-                status: timedOut ? null : status,
-                signal: timedOut ? null : signal,
-                error: timedOut ? Object.assign(new Error('Command timed out'), { code: 'ETIMEDOUT' }) : childError,
-                stdout: stdout.toSnapshot(),
-                stderr: stderr.toSnapshot(),
-                pid: childPid,
-            });
         };
         child.stdout?.on('data', (chunk) => {
             stdout.append(chunk);
-            writeStreamChunk(reporter, 'stdout', chunk);
+            stdoutBytes += chunk.byteLength;
+            if (streamOutput) {
+                writeStreamChunk(reporter, 'stdout', chunk);
+            }
+            if (enforceOutputLimit && stdoutBytes > maxOutputBytes) {
+                stopForOutputLimit('stdout');
+            }
         });
         child.stderr?.on('data', (chunk) => {
             stderr.append(chunk);
-            writeStreamChunk(reporter, 'stderr', chunk);
+            stderrBytes += chunk.byteLength;
+            if (streamOutput) {
+                writeStreamChunk(reporter, 'stderr', chunk);
+            }
+            if (enforceOutputLimit && stderrBytes > maxOutputBytes) {
+                stopForOutputLimit('stderr');
+            }
         });
         child.once('error', (error) => {
             childError = error;
@@ -367,22 +327,39 @@ function runShellCommandStreaming(command, cwd, env, timeoutSeconds, stdoutTailB
             child.stdout?.destroy();
             child.stderr?.destroy();
             child.unref();
+            termination = createPendingTimeoutTermination(getKillMethod());
             terminateProcessTreeNonBlocking(childPid);
             forceTerminateProcessTreeNonBlocking(childPid);
             finish(null, null);
         }, timeoutSeconds * 1000);
     });
 }
+function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
+    return runSpawnedCommandStreaming({ executable: command?.executable ?? '', args: command?.args ?? [], shell: command?.shell ?? false }, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
+}
+function runShellCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
+    return runSpawnedCommandStreaming({ executable: command ?? '', shell: true }, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
+}
 function getRunStatus(error, exitCode, successExitCodes) {
     const errorWithCode = error;
     if (errorWithCode?.code === 'ETIMEDOUT') {
         return 'timed_out';
     }
+    if (isOutputLimitExceededError(error)) {
+        return 'output_limit_exceeded';
+    }
     if (error) {
         return 'start_failed';
     }
     return exitCode !== null && successExitCodes.includes(exitCode) ? 'passed' : 'failed';
 }
+function isOutputLimitExceededError(error) {
+    if (!error) {
+        return false;
+    }
+    const errorWithCode = error;
+    return errorWithCode.code === OUTPUT_LIMIT_ERROR_CODE || OUTPUT_LIMIT_ERROR_MESSAGE.test(error.message);
+}
 function getRunPlanDetail(plan, lang, fallbackKey) {
     return plan.detail ?? t(lang, fallbackKey);
 }
@@ -556,17 +533,11 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
             }
         }
         if (plan.commandArgv) {
-            if (!json) {
-                streamedOutput = true;
-                return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter);
-            }
-            return runArgvCommand(plan.argvCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
+            streamedOutput = !json;
+            return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, json);
         }
-        if (!json) {
-            streamedOutput = true;
-            return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, stdoutTailBytes, stderrTailBytes, reporter);
-        }
-        return runShellCommand(plan.shellCommand, plan.cwd, plan.maxOutputBytes, env, plan.timeoutSeconds);
+        streamedOutput = !json;
+        return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, json);
     });
     const childDurationMs = performance.now() - childStartedAtMs;
     const finishedAt = new Date();
@@ -574,9 +545,13 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
     const exitCode = typeof result.status === 'number' ? result.status : null;
     const runStatus = getRunStatus(result.error, exitCode, plan.successExitCodes);
     let killMethod = null;
+    let termination = null;
     if (runStatus === 'timed_out') {
-        killMethod = getKillMethod();
-        terminateProcessTree(result.pid);
+        termination = result.termination ?? createPendingTimeoutTermination(getKillMethod());
+        killMethod = termination.method;
+        if (!result.termination && result.pid) {
+            terminateProcessTree(result.pid);
+        }
     }
     const receipt = profiler.measure('receipt_create', () => createRunReceipt({
         intent: intentName,
@@ -600,6 +575,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         signal: result.signal,
         error: result.error?.message ?? null,
         killMethod,
+        termination,
         stdout: result.stdout,
         stderr: result.stderr,
         writeDrift,
@@ -614,6 +590,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         },
         stdoutTailBytes: runReceiptPolicy.stdoutTailBytes,
         stderrTailBytes: runReceiptPolicy.stderrTailBytes,
+        receiptPath: createRunReceiptRelativePath(),
     }));
     if (options.writeLatestReceipt !== false) {
         profiler.measure('receipt_write', () => writeRunReceipt(projectRoot, receipt));