mustflow 1.30.0 → 2.11.0

package/dist/core/run-performance-history.js

@@ -0,0 +1,307 @@
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+const PERFORMANCE_HISTORY_SCHEMA_VERSION = '1';
+const PERFORMANCE_HISTORY_DIR = path.join('.mustflow', 'state', 'perf');
+const PERFORMANCE_SAMPLES_FILE = 'samples.json';
+const PERFORMANCE_SUMMARY_FILE = 'summary.json';
+const MAX_AGE_DAYS = 30;
+const MAX_TOTAL_KB = 256;
+const MAX_TOTAL_BYTES = MAX_TOTAL_KB * 1024;
+const MAX_SAMPLES_TOTAL = 500;
+const MAX_SAMPLES_PER_INTENT = 40;
+const MAX_SAMPLES_PER_INTENT_FINGERPRINT = 20;
+const MAX_FAILED_SAMPLES_PER_INTENT = 5;
+const MAX_FINGERPRINTS_PER_INTENT = 3;
+const EWMA_ALPHA = 0.3;
+function getRetention() {
+    return {
+        max_age_days: MAX_AGE_DAYS,
+        max_total_kb: MAX_TOTAL_KB,
+        max_samples_total: MAX_SAMPLES_TOTAL,
+        max_samples_per_intent: MAX_SAMPLES_PER_INTENT,
+        max_samples_per_intent_fingerprint: MAX_SAMPLES_PER_INTENT_FINGERPRINT,
+        max_failed_samples_per_intent: MAX_FAILED_SAMPLES_PER_INTENT,
+        max_fingerprints_per_intent: MAX_FINGERPRINTS_PER_INTENT,
+        timestamp_granularity: 'day',
+        stores_output_tails: false,
+        stores_command_line: false,
+        stores_environment_values: false,
+        stores_absolute_paths: false,
+        stores_test_names: false,
+    };
+}
+function toObservedDay(value) {
+    return value.slice(0, 10);
+}
+function toDayIndex(day) {
+    const time = Date.parse(`${day}T00:00:00.000Z`);
+    return Math.floor(time / 86_400_000);
+}
+function getRunnerBucket(runner) {
+    return `${runner.kind}/${runner.platform_family}/${runner.arch_family}/${runner.runtime}@${runner.runtime_major}`;
+}
+function createSample(receipt) {
+    if (!receipt.performance.quality.usable_for_history) {
+        return null;
+    }
+    if (receipt.performance.result_summary.status !== 'passed' && receipt.performance.result_summary.status !== 'failed') {
+        return null;
+    }
+    return {
+        observed_day: toObservedDay(receipt.finished_at),
+        intent: receipt.intent,
+        intent_fingerprint: receipt.performance.intent_fingerprint,
+        command_fingerprint: receipt.performance.command_fingerprint,
+        contract_fingerprint: receipt.performance.contract_fingerprint,
+        runner_bucket: getRunnerBucket(receipt.performance.runner),
+        duration_ms: receipt.performance.duration_ms,
+        ...(typeof receipt.performance.executor_overhead_ms === 'number'
+            ? { executor_overhead_ms: receipt.performance.executor_overhead_ms }
+            : {}),
+        timeout_ratio: receipt.performance.timeout_ratio,
+        status: receipt.performance.result_summary.status,
+        exit_code_class: receipt.performance.result_summary.exit_code_class,
+        timed_out: false,
+        error_kind: receipt.performance.result_summary.error_kind,
+        stdout_bytes: receipt.performance.output_summary.stdout_bytes,
+        stderr_bytes: receipt.performance.output_summary.stderr_bytes,
+        ...(receipt.performance.phases && receipt.performance.phases.length > 0
+            ? { phase_durations_ms: toPhaseDurations(receipt.performance.phases) }
+            : {}),
+        ...(receipt.performance.selection
+            ? {
+                selection_strategy: receipt.performance.selection.strategy,
+                changed_file_count: receipt.performance.selection.changed_file_count,
+                changed_surface_counts: receipt.performance.selection.changed_surface_counts,
+                selected_target_count: receipt.performance.selection.selected_target_count,
+                fallback_used: receipt.performance.selection.fallback_used,
+            }
+            : {}),
+    };
+}
+function toPhaseDurations(phases) {
+    const durations = {};
+    for (const phase of phases) {
+        durations[phase.name] = phase.duration_ms;
+    }
+    return durations;
+}
+function readSamples(samplesPath) {
+    if (!existsSync(samplesPath)) {
+        return [];
+    }
+    try {
+        const parsed = JSON.parse(readFileSync(samplesPath, 'utf8'));
+        return Array.isArray(parsed.samples) ? parsed.samples.filter(isRunPerformanceSample) : [];
+    }
+    catch {
+        return [];
+    }
+}
+function isRunPerformanceSample(value) {
+    if (!value || typeof value !== 'object') {
+        return false;
+    }
+    const sample = value;
+    return (typeof sample.observed_day === 'string' &&
+        typeof sample.intent === 'string' &&
+        typeof sample.intent_fingerprint === 'string' &&
+        typeof sample.command_fingerprint === 'string' &&
+        typeof sample.contract_fingerprint === 'string' &&
+        typeof sample.runner_bucket === 'string' &&
+        typeof sample.duration_ms === 'number' &&
+        typeof sample.timeout_ratio === 'number' &&
+        (sample.status === 'passed' || sample.status === 'failed') &&
+        typeof sample.stdout_bytes === 'number' &&
+        typeof sample.stderr_bytes === 'number' &&
+        (sample.selection_strategy === undefined || typeof sample.selection_strategy === 'string') &&
+        (sample.changed_file_count === undefined || isNonNegativeNumber(sample.changed_file_count)) &&
+        (sample.changed_surface_counts === undefined || isChangedSurfaceCounts(sample.changed_surface_counts)) &&
+        (sample.selected_target_count === undefined || isNonNegativeNumber(sample.selected_target_count)) &&
+        (sample.fallback_used === undefined || typeof sample.fallback_used === 'boolean'));
+}
+function isNonNegativeNumber(value) {
+    return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+}
+function isChangedSurfaceCounts(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return false;
+    }
+    return Object.entries(value).every(([surface, count]) => /^[a-z][a-z0-9_]*$/.test(surface) && isNonNegativeNumber(count));
+}
+function keepMostRecentByLimit(items, limit, key) {
+    const counts = new Map();
+    const kept = [];
+    for (let index = items.length - 1; index >= 0; index -= 1) {
+        const item = items[index];
+        const itemKey = key(item);
+        const count = counts.get(itemKey) ?? 0;
+        if (count < limit) {
+            kept.push(item);
+            counts.set(itemKey, count + 1);
+        }
+    }
+    return kept.reverse();
+}
+function keepMostRecentFailuresByIntent(samples) {
+    const failures = new Map();
+    const keepIndexes = new Set();
+    for (let index = samples.length - 1; index >= 0; index -= 1) {
+        const sample = samples[index];
+        if (sample.status === 'passed') {
+            keepIndexes.add(index);
+            continue;
+        }
+        const count = failures.get(sample.intent) ?? 0;
+        if (count < MAX_FAILED_SAMPLES_PER_INTENT) {
+            keepIndexes.add(index);
+            failures.set(sample.intent, count + 1);
+        }
+    }
+    return samples.filter((_, index) => keepIndexes.has(index));
+}
+function keepRecentFingerprintsByIntent(samples) {
+    const latestByIntent = new Map();
+    for (const sample of samples) {
+        const byFingerprint = latestByIntent.get(sample.intent) ?? new Map();
+        byFingerprint.set(sample.intent_fingerprint, Math.max(byFingerprint.get(sample.intent_fingerprint) ?? 0, toDayIndex(sample.observed_day)));
+        latestByIntent.set(sample.intent, byFingerprint);
+    }
+    const allowed = new Map();
+    for (const [intent, fingerprints] of latestByIntent.entries()) {
+        const allowedFingerprints = [...fingerprints.entries()]
+            .sort((left, right) => right[1] - left[1] || left[0].localeCompare(right[0]))
+            .slice(0, MAX_FINGERPRINTS_PER_INTENT)
+            .map(([fingerprint]) => fingerprint);
+        allowed.set(intent, new Set(allowedFingerprints));
+    }
+    return samples.filter((sample) => allowed.get(sample.intent)?.has(sample.intent_fingerprint) ?? false);
+}
+function pruneSamples(samples, today) {
+    const todayIndex = toDayIndex(today);
+    let pruned = samples.filter((sample) => todayIndex - toDayIndex(sample.observed_day) < MAX_AGE_DAYS);
+    pruned = keepRecentFingerprintsByIntent(pruned);
+    pruned = keepMostRecentByLimit(pruned, MAX_SAMPLES_PER_INTENT_FINGERPRINT, (sample) => `${sample.intent}\0${sample.intent_fingerprint}`);
+    pruned = keepMostRecentByLimit(pruned, MAX_SAMPLES_PER_INTENT, (sample) => sample.intent);
+    pruned = keepMostRecentFailuresByIntent(pruned);
+    return pruned.slice(Math.max(0, pruned.length - MAX_SAMPLES_TOTAL));
+}
+function percentile(values, percentileValue) {
+    if (values.length === 0) {
+        return 0;
+    }
+    const sorted = [...values].sort((left, right) => left - right);
+    const index = Math.ceil((percentileValue / 100) * sorted.length) - 1;
+    return sorted[Math.max(0, Math.min(sorted.length - 1, index))] ?? 0;
+}
+function calculateEwma(values) {
+    if (values.length === 0) {
+        return 0;
+    }
+    let current = values[0] ?? 0;
+    for (const value of values.slice(1)) {
+        current = EWMA_ALPHA * value + (1 - EWMA_ALPHA) * current;
+    }
+    return Math.round(current);
+}
+function summarizeRunnerBuckets(samples) {
+    const buckets = {};
+    const groups = groupBy(samples, (sample) => sample.runner_bucket);
+    for (const [bucket, bucketSamples] of groups.entries()) {
+        const durations = bucketSamples.map((sample) => sample.duration_ms);
+        buckets[bucket] = {
+            sample_count: bucketSamples.length,
+            p50_duration_ms: percentile(durations, 50),
+        };
+    }
+    return buckets;
+}
+function summarizeFingerprint(samples) {
+    const durations = samples.map((sample) => sample.duration_ms);
+    const successes = samples.filter((sample) => sample.status === 'passed');
+    const failures = samples.filter((sample) => sample.status !== 'passed');
+    const lastSuccess = successes.at(-1);
+    return {
+        sample_count: samples.length,
+        success_count: successes.length,
+        timeout_count: samples.filter((sample) => sample.timed_out).length,
+        failure_count: failures.length,
+        p50_duration_ms: percentile(durations, 50),
+        p75_duration_ms: percentile(durations, 75),
+        p95_duration_ms: percentile(durations, 95),
+        min_duration_ms: Math.min(...durations),
+        max_duration_ms: Math.max(...durations),
+        ewma_duration_ms: calculateEwma(durations),
+        last_success_duration_ms: lastSuccess?.duration_ms ?? null,
+        last_observed_day: samples.at(-1)?.observed_day ?? '',
+        runner_buckets: summarizeRunnerBuckets(samples),
+    };
+}
+function createSummary(samples, generatedDay) {
+    const intents = {};
+    const byIntent = groupBy(samples, (sample) => sample.intent);
+    for (const [intent, intentSamples] of byIntent.entries()) {
+        const fingerprints = {};
+        const byFingerprint = groupBy(intentSamples, (sample) => sample.intent_fingerprint);
+        for (const [fingerprint, fingerprintSamples] of byFingerprint.entries()) {
+            fingerprints[fingerprint] = summarizeFingerprint(fingerprintSamples);
+        }
+        intents[intent] = { fingerprints };
+    }
+    return {
+        schema_version: PERFORMANCE_HISTORY_SCHEMA_VERSION,
+        generated_day: generatedDay,
+        retention: getRetention(),
+        intents,
+    };
+}
+function groupBy(items, keyFor) {
+    const groups = new Map();
+    for (const item of items) {
+        const key = keyFor(item);
+        const group = groups.get(key) ?? [];
+        group.push(item);
+        groups.set(key, group);
+    }
+    return groups;
+}
+function createSamplesFile(samples) {
+    return {
+        schema_version: PERFORMANCE_HISTORY_SCHEMA_VERSION,
+        retention: getRetention(),
+        samples,
+    };
+}
+function serialize(value) {
+    return `${JSON.stringify(value, null, 2)}\n`;
+}
+function enforceSizeLimit(samples, today) {
+    let pruned = [...samples];
+    let summary = createSummary(pruned, today);
+    while (pruned.length > 0 &&
+        Buffer.byteLength(serialize(createSamplesFile(pruned)), 'utf8') + Buffer.byteLength(serialize(summary), 'utf8') > MAX_TOTAL_BYTES) {
+        pruned = pruned.slice(1);
+        summary = createSummary(pruned, today);
+    }
+    return pruned;
+}
+export function recordRunPerformanceHistory(projectRoot, receipt) {
+    const sample = createSample(receipt);
+    if (!sample) {
+        return;
+    }
+    try {
+        const historyDir = path.join(projectRoot, PERFORMANCE_HISTORY_DIR);
+        const samplesPath = path.join(historyDir, PERFORMANCE_SAMPLES_FILE);
+        const summaryPath = path.join(historyDir, PERFORMANCE_SUMMARY_FILE);
+        const samples = enforceSizeLimit(pruneSamples([...readSamples(samplesPath), sample], sample.observed_day), sample.observed_day);
+        const samplesFile = createSamplesFile(samples);
+        const summaryFile = createSummary(samples, sample.observed_day);
+        mkdirSync(historyDir, { recursive: true });
+        writeFileSync(samplesPath, serialize(samplesFile));
+        writeFileSync(summaryPath, serialize(summaryFile));
+    }
+    catch {
+        // Performance history is a local optimization hint. A write failure must not affect command execution.
+    }
+}

package/dist/core/run-profile.js

@@ -0,0 +1,87 @@
+import { mkdirSync, writeFileSync } from 'node:fs';
+import { performance } from 'node:perf_hooks';
+import path from 'node:path';
+const RUN_PROFILE_SCHEMA_VERSION = '1';
+const RUN_PROFILE_ENV = 'MUSTFLOW_RUN_PROFILE';
+const RUN_PROFILE_DIR = path.join('.mustflow', 'state', 'runs');
+const LATEST_RUN_PROFILE = 'latest.profile.json';
+function isRunProfileEnabled() {
+    const value = process.env[RUN_PROFILE_ENV];
+    return value === '1' || value?.toLowerCase() === 'true';
+}
+function roundDurationMs(durationMs) {
+    return Math.max(0, Math.round(durationMs * 1000) / 1000);
+}
+function getProfileRelativePath() {
+    return path.join(RUN_PROFILE_DIR, LATEST_RUN_PROFILE).split(path.sep).join('/');
+}
+export class RunProfiler {
+    enabled;
+    startedAt;
+    startedAtMs;
+    phases = [];
+    constructor(enabled = isRunProfileEnabled()) {
+        this.enabled = enabled;
+        this.startedAt = new Date();
+        this.startedAtMs = performance.now();
+    }
+    measure(name, callback) {
+        if (!this.enabled) {
+            return callback();
+        }
+        const startedAtMs = performance.now();
+        try {
+            return callback();
+        }
+        finally {
+            this.recordPhase(name, startedAtMs);
+        }
+    }
+    async measureAsync(name, callback) {
+        if (!this.enabled) {
+            return callback();
+        }
+        const startedAtMs = performance.now();
+        try {
+            return await callback();
+        }
+        finally {
+            this.recordPhase(name, startedAtMs);
+        }
+    }
+    getReceiptPhases() {
+        if (!this.enabled) {
+            return [];
+        }
+        return [...this.phases];
+    }
+    writeLatest(input) {
+        if (!this.enabled) {
+            return;
+        }
+        const finishedAt = new Date();
+        const profile = {
+            schema_version: RUN_PROFILE_SCHEMA_VERSION,
+            command: 'run',
+            profile: true,
+            profile_window: 'run_command_handler',
+            intent: input.intent,
+            status: input.status,
+            preview_mode: input.previewMode,
+            started_at: this.startedAt.toISOString(),
+            finished_at: finishedAt.toISOString(),
+            duration_ms: roundDurationMs(performance.now() - this.startedAtMs),
+            phases: [...this.phases],
+            profile_path: getProfileRelativePath(),
+        };
+        const profilePath = path.join(input.projectRoot, RUN_PROFILE_DIR, LATEST_RUN_PROFILE);
+        mkdirSync(path.dirname(profilePath), { recursive: true });
+        writeFileSync(profilePath, `${JSON.stringify(profile, null, 2)}\n`);
+    }
+    recordPhase(name, startedAtMs) {
+        this.phases.push({
+            name,
+            duration_ms: roundDurationMs(performance.now() - startedAtMs),
+        });
+    }
+}

package/dist/core/run-receipt.js

@@ -1,4 +1,5 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
+import { createHash } from 'node:crypto';
 import path from 'node:path';
 import { DEFAULT_RUN_RECEIPT_TAIL_BYTES } from './retention-policy.js';
 import { redactSecretLikeText } from './secret-redaction.js';
@@ -44,15 +45,17 @@ function summarizeOutput(output, maxOutputBytes, tailBytes, field, state) {
             redaction_kinds: [],
         };
     }
-    const text = output.toString();
-    const bytes = Buffer.byteLength(text, 'utf8');
     const tailLimit = Math.min(tailBytes, maxOutputBytes);
+    const text = typeof output === 'object' && 'tail' in output && 'bytes' in output ? output.tail : output.toString();
+    const bytes = typeof output === 'object' && 'tail' in output && 'bytes' in output
+        ? output.bytes
+        : Buffer.byteLength(text, 'utf8');
     const tail = truncateTextByBytes(text, tailLimit);
     const redaction = redactSecretLikeText(tail.text);
     recordRedaction(state, `${field}.tail`, redaction);
     return {
         bytes,
-        truncated: tail.truncated,
+        truncated: tail.truncated || bytes > Buffer.byteLength(tail.text, 'utf8'),
         tail: redaction.text,
         redacted: redaction.redacted,
         redaction_count: redaction.redactionCount,
@@ -62,6 +65,146 @@ function summarizeOutput(output, maxOutputBytes, tailBytes, field, state) {
 function getReceiptRelativePath() {
     return toPosixPath(path.join(RUN_RECEIPT_DIR, LATEST_RUN_RECEIPT));
 }
+function stableJson(value) {
+    if (Array.isArray(value)) {
+        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
+    }
+    if (value && typeof value === 'object') {
+        const entries = Object.entries(value).sort(([left], [right]) => left.localeCompare(right));
+        return `{${entries.map(([key, entry]) => `${JSON.stringify(key)}:${stableJson(entry)}`).join(',')}}`;
+    }
+    return JSON.stringify(value);
+}
+function fingerprint(value) {
+    return `sha256:${createHash('sha256').update(stableJson(value)).digest('hex')}`;
+}
+function getRuntimeMajor() {
+    const version = getBunRuntimeVersion() ?? process.versions.node;
+    const major = Number.parseInt(version.split('.')[0] ?? '', 10);
+    return Number.isFinite(major) ? major : 0;
+}
+function getBunRuntimeVersion() {
+    const versions = process.versions;
+    return versions.bun;
+}
+function getExitCodeClass(status, exitCode) {
+    if (exitCode === null) {
+        return 'no_exit_code';
+    }
+    return status === 'passed' ? 'success' : 'failure';
+}
+function getErrorKind(status, exitCode) {
+    if (status === 'timed_out') {
+        return 'timeout';
+    }
+    if (status === 'start_failed') {
+        return 'start_failed';
+    }
+    if (status === 'failed' && exitCode !== null) {
+        return 'exit_code';
+    }
+    return null;
+}
+function createPerformanceSummary(input) {
+    const contractIdentity = {
+        cwd: input.cwd,
+        env_allowlist: input.envAllowlist,
+        env_policy: input.envPolicy,
+        lifecycle: input.lifecycle,
+        max_output_bytes: input.maxOutputBytes,
+        mode: input.mode,
+        run_policy: input.runPolicy,
+        success_exit_codes: input.successExitCodes,
+        timeout_seconds: input.timeoutSeconds,
+    };
+    const commandIdentity = {
+        argv: input.argv ?? null,
+        cmd: input.cmd ?? null,
+        mode: input.mode,
+    };
+    const timeoutBudgetMs = input.timeoutSeconds * 1000;
+    const timeoutRatio = timeoutBudgetMs > 0 ? input.durationMs / timeoutBudgetMs : 0;
+    const phaseTimings = sanitizePhaseTimings(input.phaseTimings ?? []);
+    const selection = sanitizeSelectionSummary(input.selectionSummary);
+    return {
+        schema_version: '1',
+        measurement: 'wall_clock',
+        duration_ms: input.durationMs,
+        ...(typeof input.executorOverheadMs === 'number' ? { executor_overhead_ms: input.executorOverheadMs } : {}),
+        ...(phaseTimings.length > 0 ? { phases: phaseTimings } : {}),
+        ...(selection ? { selection } : {}),
+        timeout_ratio: Number(timeoutRatio.toFixed(6)),
+        command_fingerprint: fingerprint(commandIdentity),
+        intent_fingerprint: fingerprint({ intent: input.intent, ...contractIdentity }),
+        contract_fingerprint: fingerprint(contractIdentity),
+        runner: {
+            kind: 'local',
+            platform_family: process.platform,
+            arch_family: process.arch,
+            runtime: getBunRuntimeVersion() ? 'bun' : 'node',
+            runtime_major: getRuntimeMajor(),
+        },
+        output_summary: {
+            stdout_bytes: input.stdout.bytes,
+            stderr_bytes: input.stderr.bytes,
+            stdout_truncated: input.stdout.truncated,
+            stderr_truncated: input.stderr.truncated,
+        },
+        result_summary: {
+            status: input.status,
+            exit_code_class: getExitCodeClass(input.status, input.exitCode),
+            timed_out: input.timedOut,
+            error_kind: getErrorKind(input.status, input.exitCode),
+        },
+        quality: {
+            phase_timings_source: phaseTimings.length > 0 ? 'structured_report' : 'none',
+            target_timings_source: 'none',
+            usable_for_history: input.status === 'passed' || input.status === 'failed',
+        },
+    };
+}
+function isSafePerformanceKey(value) {
+    return /^[a-z][a-z0-9_]*$/.test(value);
+}
+function toNonNegativeInteger(value) {
+    if (!Number.isFinite(value) || value < 0) {
+        return null;
+    }
+    return Math.trunc(value);
+}
+function sanitizeSelectionSummary(selection) {
+    if (!selection || !isSafePerformanceKey(selection.strategy) || typeof selection.fallback_used !== 'boolean') {
+        return undefined;
+    }
+    const changedFileCount = toNonNegativeInteger(selection.changed_file_count);
+    const selectedTargetCount = toNonNegativeInteger(selection.selected_target_count);
+    if (changedFileCount === null || selectedTargetCount === null) {
+        return undefined;
+    }
+    const changedSurfaceCounts = {};
+    for (const [surface, count] of Object.entries(selection.changed_surface_counts).sort(([left], [right]) => left.localeCompare(right))) {
+        const sanitizedCount = toNonNegativeInteger(count);
+        if (!isSafePerformanceKey(surface) || sanitizedCount === null) {
+            return undefined;
+        }
+        changedSurfaceCounts[surface] = sanitizedCount;
+    }
+    return {
+        strategy: selection.strategy,
+        changed_file_count: changedFileCount,
+        changed_surface_counts: changedSurfaceCounts,
+        selected_target_count: selectedTargetCount,
+        fallback_used: selection.fallback_used,
+    };
+}
+function sanitizePhaseTimings(phases) {
+    return phases
+        .filter((phase) => isSafePerformanceKey(phase.name) && Number.isFinite(phase.duration_ms) && phase.duration_ms >= 0)
+        .map((phase) => ({
+        name: phase.name,
+        duration_ms: Math.round(phase.duration_ms * 1000) / 1000,
+    }));
+}
 export function createRunReceipt(input) {
     const relativeCwd = path.relative(input.projectRoot, input.cwd);
     const stdoutTailBytes = input.stdoutTailBytes ?? DEFAULT_RUN_RECEIPT_TAIL_BYTES;
@@ -72,6 +215,7 @@ export function createRunReceipt(input) {
     const error = input.error ? redactReceiptString(input.error, 'error', redactionState) : null;
     const stdout = summarizeOutput(input.stdout, input.maxOutputBytes, stdoutTailBytes, 'stdout', redactionState);
     const stderr = summarizeOutput(input.stderr, input.maxOutputBytes, stderrTailBytes, 'stderr', redactionState);
+    const durationMs = input.finishedAt.getTime() - input.startedAt.getTime();
     return {
         schema_version: RUN_RECEIPT_SCHEMA_VERSION,
         command: 'run',
@@ -80,7 +224,7 @@ export function createRunReceipt(input) {
         timed_out: input.timedOut,
         started_at: input.startedAt.toISOString(),
         finished_at: input.finishedAt.toISOString(),
-        duration_ms: input.finishedAt.getTime() - input.startedAt.getTime(),
+        duration_ms: durationMs,
         cwd: relativeCwd.length > 0 ? toPosixPath(relativeCwd) : '.',
         lifecycle: input.lifecycle,
         run_policy: input.runPolicy,
@@ -99,6 +243,29 @@ export function createRunReceipt(input) {
         stdout,
         stderr,
         write_drift: input.writeDrift,
+        performance: createPerformanceSummary({
+            intent: input.intent,
+            status: input.status,
+            timedOut: input.timedOut,
+            durationMs,
+            executorOverheadMs: input.executorOverheadMs,
+            mode: input.mode,
+            argv,
+            cmd,
+            cwd: relativeCwd.length > 0 ? toPosixPath(relativeCwd) : '.',
+            lifecycle: input.lifecycle,
+            runPolicy: input.runPolicy,
+            envPolicy: input.envPolicy,
+            envAllowlist: input.envAllowlist,
+            timeoutSeconds: input.timeoutSeconds,
+            maxOutputBytes: input.maxOutputBytes,
+            successExitCodes: input.successExitCodes,
+            exitCode: input.exitCode,
+            stdout,
+            stderr,
+            phaseTimings: input.phaseTimings,
+            selectionSummary: input.selectionSummary,
+        }),
         redaction: {
             redacted: redactionState.count > 0,
             redaction_count: redactionState.count,

package/dist/core/run-write-drift.js

@@ -4,8 +4,13 @@ import path from 'node:path';
 import { normalizeCommandEffects } from './command-effects.js';
 const MAX_SNAPSHOT_FILES = 20_000;
 const MAX_REPORTED_PATHS = 200;
+const RECURSIVE_SNAPSHOT_ENV = 'MUSTFLOW_WRITE_DRIFT_SNAPSHOT';
 const EXCLUDED_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
 const EXCLUDED_RELATIVE_DIRECTORY_PATHS = new Set(['.mustflow/state/runs']);
+function isRecursiveSnapshotEnabled() {
+    const value = process.env[RECURSIVE_SNAPSHOT_ENV];
+    return value === '1' || value?.toLowerCase() === 'true';
+}
 function toPosixPath(value) {
     return value.split(path.sep).join('/');
 }
@@ -52,16 +57,25 @@ function captureSnapshot(projectRoot) {
     if (gitSnapshot) {
         return gitSnapshot;
     }
+    if (!isRecursiveSnapshotEnabled()) {
+        return {
+            ok: false,
+            entries: new Map(),
+            reason: 'git_status_unavailable_recursive_snapshot_disabled',
+            source: 'unavailable',
+        };
+    }
     try {
         const entries = new Map();
         collectSnapshotEntries(projectRoot, projectRoot, entries);
-        return { ok: true, entries, reason: null };
+        return { ok: true, entries, reason: null, source: 'recursive_snapshot' };
     }
     catch (error) {
         return {
             ok: false,
             entries: new Map(),
             reason: error instanceof Error && error.message.length > 0 ? error.message : 'snapshot_unavailable',
+            source: 'unavailable',
         };
     }
 }
@@ -93,12 +107,14 @@ function captureGitStatusSnapshot(projectRoot) {
         ok: true,
         entries,
         reason: null,
+        source: 'git_status',
     };
 }
 function listDeclaredWritePaths(projectRoot, contract, intentName) {
     const paths = normalizeCommandEffects(projectRoot, contract, intentName)
         .filter((effect) => effect.access === 'write')
-        .map((effect) => effect.path);
+        .map((effect) => effect.path)
+        .filter((effectPath) => typeof effectPath === 'string');
     return [...new Set(paths.map(normalizeRelativePath))].sort((left, right) => left.localeCompare(right));
 }
 function listObservedChangedPaths(before, after) {