mustflow 2.18.0 → 2.18.3

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/builtin-dispatch.js

@@ -0,0 +1,92 @@
+import { canRunMustflowBuiltinInProcess, isMustflowBinName } from '../../../core/command-classification.js';
+import { getPackageVersion } from '../../lib/package-info.js';
+import { createBufferedReporter } from './output.js';
+/**
+ * mf:anchor cli.run.builtin-inprocess
+ * purpose: Dispatch selected mustflow built-in commands without spawning a nested CLI process.
+ * search: builtin intent, in-process command, nested mf run, run receipt
+ * invariant: Only commands classified by command-classification can use this path.
+ * risk: config, state
+ */
+async function runKnownBuiltinCommand(args, reporter, lang) {
+    const [command, ...commandArgs] = args;
+    if ((command === '--version' || command === '-v' || command === 'version') && commandArgs.length === 0) {
+        reporter.stdout(getPackageVersion());
+        return 0;
+    }
+    if (!canRunMustflowBuiltinInProcess(command)) {
+        return undefined;
+    }
+    if (command === 'check') {
+        return (await import('../check.js')).runCheck(commandArgs, reporter, lang);
+    }
+    if (command === 'classify') {
+        return (await import('../classify.js')).runClassify(commandArgs, reporter, lang);
+    }
+    if (command === 'context') {
+        return (await import('../context.js')).runContext(commandArgs, reporter, lang);
+    }
+    if (command === 'doctor') {
+        return (await import('../doctor.js')).runDoctor(commandArgs, reporter, lang);
+    }
+    if (command === 'help') {
+        return (await import('../help.js')).runHelp(commandArgs, reporter, lang);
+    }
+    if (command === 'impact') {
+        return (await import('../impact.js')).runImpact(commandArgs, reporter, lang);
+    }
+    if (command === 'line-endings') {
+        return (await import('../line-endings.js')).runLineEndings(commandArgs, reporter, lang);
+    }
+    if (command === 'map') {
+        return (await import('../map.js')).runMap(commandArgs, reporter, lang);
+    }
+    if (command === 'status') {
+        return (await import('../status.js')).runStatus(commandArgs, reporter, lang);
+    }
+    if (command === 'update') {
+        return (await import('../update.js')).runUpdate(commandArgs, reporter, lang);
+    }
+    if (command === 'version-sources') {
+        return (await import('../version-sources.js')).runVersionSources(commandArgs, reporter, lang);
+    }
+    return undefined;
+}
+async function withWorkingDirectory(cwd, callback) {
+    const previousCwd = process.cwd();
+    process.chdir(cwd);
+    try {
+        return await callback();
+    }
+    finally {
+        process.chdir(previousCwd);
+    }
+}
+export async function runBuiltinArgvInProcess(commandArgv, cwd, lang) {
+    const [command = '', ...builtinArgs] = commandArgv;
+    if (!isMustflowBinName(command)) {
+        return undefined;
+    }
+    const output = createBufferedReporter();
+    try {
+        const status = await withWorkingDirectory(cwd, () => runKnownBuiltinCommand(builtinArgs, output.reporter, lang));
+        if (status === undefined) {
+            return undefined;
+        }
+        return {
+            status,
+            signal: null,
+            stdout: output.stdout(),
+            stderr: output.stderr(),
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            status: 1,
+            signal: null,
+            stdout: output.stdout(),
+            stderr: `${output.stderr()}${message}\n`,
+        };
+    }
+}

package/dist/cli/commands/run/executor.js

@@ -0,0 +1,112 @@
+import { spawn } from 'node:child_process';
+import { BoundedOutputBuffer } from '../../../core/bounded-output.js';
+import { createPendingTimeoutTermination, forceTerminateProcessTreeNonBlocking, getKillMethod, terminateProcessTreeNonBlocking, } from './process-tree.js';
+import { createOutputLimitError, isOutputLimitExceededError, writeStreamChunk } from './output.js';
+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);
+        let settled = false;
+        let timedOut = false;
+        let childError;
+        let childPid;
+        let stdoutBytes = 0;
+        let stderrBytes = 0;
+        let timeout;
+        let termination = null;
+        const child = spawn(command.executable, command.args ?? [], {
+            cwd,
+            env,
+            shell: command.shell,
+            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,
+                termination,
+            });
+        };
+        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);
+        };
+        child.stdout?.on('data', (chunk) => {
+            stdout.append(chunk);
+            stdoutBytes += chunk.byteLength;
+            if (streamOutput) {
+                writeStreamChunk(reporter, 'stdout', chunk);
+            }
+            if (enforceOutputLimit && stdoutBytes > maxOutputBytes) {
+                stopForOutputLimit('stdout');
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr.append(chunk);
+            stderrBytes += chunk.byteLength;
+            if (streamOutput) {
+                writeStreamChunk(reporter, 'stderr', chunk);
+            }
+            if (enforceOutputLimit && stderrBytes > maxOutputBytes) {
+                stopForOutputLimit('stderr');
+            }
+        });
+        child.once('error', (error) => {
+            childError = error;
+        });
+        child.once('close', (status, signal) => {
+            finish(status, signal);
+        });
+        timeout = setTimeout(() => {
+            timedOut = true;
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            child.unref();
+            termination = createPendingTimeoutTermination(getKillMethod());
+            terminateProcessTreeNonBlocking(childPid);
+            forceTerminateProcessTreeNonBlocking(childPid);
+            finish(null, null);
+        }, timeoutSeconds * 1000);
+    });
+}
+export 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);
+}
+export 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);
+}
+export 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';
+}

package/dist/cli/commands/run/output.js

@@ -0,0 +1,59 @@
+const OUTPUT_LIMIT_ERROR_CODE = 'ENOBUFS';
+const OUTPUT_LIMIT_ERROR_MESSAGE = /\bmaxBuffer\b.*\bexceeded\b/i;
+export function emitOutput(reporter, output, stream) {
+    if (!output) {
+        return;
+    }
+    const text = (typeof output === 'object' && 'tail' in output ? output.tail : output.toString()).trimEnd();
+    if (text.length === 0) {
+        return;
+    }
+    reporter[stream](text);
+}
+export function createBufferedReporter() {
+    const stdout = [];
+    const stderr = [];
+    return {
+        reporter: {
+            stdout(message) {
+                stdout.push(`${message}\n`);
+            },
+            stderr(message) {
+                stderr.push(`${message}\n`);
+            },
+        },
+        stdout() {
+            return stdout.join('');
+        },
+        stderr() {
+            return stderr.join('');
+        },
+    };
+}
+export function writeStreamChunk(reporter, stream, chunk) {
+    if (stream === 'stdout') {
+        if (reporter.writeStdout) {
+            reporter.writeStdout(chunk);
+            return;
+        }
+        reporter.stdout(chunk.toString());
+        return;
+    }
+    if (reporter.writeStderr) {
+        reporter.writeStderr(chunk);
+        return;
+    }
+    reporter.stderr(chunk.toString());
+}
+export function createOutputLimitError(stream, maxOutputBytes) {
+    return Object.assign(new Error(`${stream} exceeded max_output_bytes (${maxOutputBytes})`), {
+        code: OUTPUT_LIMIT_ERROR_CODE,
+    });
+}
+export function isOutputLimitExceededError(error) {
+    if (!error) {
+        return false;
+    }
+    const errorWithCode = error;
+    return errorWithCode.code === OUTPUT_LIMIT_ERROR_CODE || OUTPUT_LIMIT_ERROR_MESSAGE.test(error.message);
+}

package/dist/cli/commands/run/process-tree.js

@@ -0,0 +1,91 @@
+import { spawn, spawnSync } from 'node:child_process';
+function signalProcessTree(pid, signal) {
+    if (!pid || pid <= 0) {
+        return;
+    }
+    if (process.platform === 'win32') {
+        spawnSync('taskkill', ['/PID', String(pid), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+        });
+        if (signal === 'SIGKILL') {
+            try {
+                process.kill(pid, signal);
+            }
+            catch {
+                // taskkill may already have terminated the direct child.
+            }
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // The child may already be gone after Node's spawn timeout handling.
+        }
+    }
+}
+function signalProcessTreeNonBlocking(pid, signal) {
+    if (!pid || pid <= 0) {
+        return;
+    }
+    if (process.platform === 'win32') {
+        const killer = spawn('taskkill', ['/PID', String(pid), '/T', '/F'], {
+            stdio: 'ignore',
+            windowsHide: true,
+            detached: true,
+        });
+        killer.unref();
+        if (signal === 'SIGKILL') {
+            try {
+                process.kill(pid, signal);
+            }
+            catch {
+                // taskkill may already have terminated the direct child.
+            }
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // The child may already be gone after the timeout fired.
+        }
+    }
+}
+export function terminateProcessTree(pid) {
+    signalProcessTree(pid, 'SIGTERM');
+}
+export function forceTerminateProcessTree(pid) {
+    signalProcessTree(pid, 'SIGKILL');
+}
+export function terminateProcessTreeNonBlocking(pid) {
+    signalProcessTreeNonBlocking(pid, 'SIGTERM');
+}
+export function forceTerminateProcessTreeNonBlocking(pid) {
+    signalProcessTreeNonBlocking(pid, 'SIGKILL');
+}
+export function getKillMethod() {
+    return process.platform === 'win32' ? 'taskkill_process_tree' : 'process_group_sigterm';
+}
+export function createPendingTimeoutTermination(method) {
+    return {
+        reason: 'timeout',
+        method,
+        graceful_signal: 'SIGTERM',
+        forced_signal: 'SIGKILL',
+        forced_kill_attempted: true,
+        confirmed: false,
+        cleanup_pending: true,
+    };
+}

package/dist/cli/commands/run/receipt.js

@@ -0,0 +1,42 @@
+import { createRunReceipt, createRunReceiptRelativePath, } from '../../../core/run-receipt.js';
+export function assembleRunReceipt(input) {
+    return createRunReceipt({
+        intent: input.intentName,
+        status: input.runStatus,
+        timedOut: input.runStatus === 'timed_out',
+        startedAt: input.startedAt,
+        finishedAt: input.finishedAt,
+        projectRoot: input.projectRoot,
+        cwd: input.plan.cwd,
+        lifecycle: input.plan.lifecycle ?? 'oneshot',
+        runPolicy: input.plan.runPolicy ?? 'agent_allowed',
+        mode: input.plan.mode,
+        argv: input.plan.commandArgv,
+        cmd: input.plan.shellCommand,
+        envPolicy: input.plan.envPolicy,
+        envAllowlist: input.plan.envAllowlist,
+        timeoutSeconds: input.plan.timeoutSeconds,
+        maxOutputBytes: input.plan.maxOutputBytes,
+        successExitCodes: input.plan.successExitCodes,
+        exitCode: input.exitCode,
+        signal: input.result.signal,
+        error: input.result.error?.message ?? null,
+        killMethod: input.killMethod,
+        termination: input.termination,
+        stdout: input.result.stdout,
+        stderr: input.result.stderr,
+        writeDrift: input.writeDrift,
+        executorOverheadMs: input.executorOverheadMs,
+        phaseTimings: input.phaseTimings,
+        selectionSummary: {
+            strategy: input.plan.testTargets.length > 0 ? 'project_test_selection' : 'direct_intent',
+            changed_file_count: 0,
+            changed_surface_counts: {},
+            selected_target_count: Math.max(1, input.plan.testTargets.length),
+            fallback_used: false,
+        },
+        stdoutTailBytes: input.stdoutTailBytes,
+        stderrTailBytes: input.stderrTailBytes,
+        receiptPath: createRunReceiptRelativePath(),
+    });
+}