mustflow 2.74.0 → 2.74.1

package/README.md

@@ -334,7 +334,7 @@ Command environments remove the project-local `node_modules/.bin` path from `PAT
 
 Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents, command eligibility, risk-priced evidence requirements, 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 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.
+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. `latest.json` is a root-scoped convenience pointer, not session-scoped proof; in multi-agent or multi-terminal workflows, use the per-run `receipt_path` or `mf run <intent> --json` output as the evidence for a specific run.
 
 ## Language and profiles
 

package/dist/cli/commands/check.js

@@ -1,4 +1,5 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, GENERATED_SURFACE_READ_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -43,36 +44,47 @@ export function runCheck(args, reporter, lang = 'en') {
         return 1;
     }
     const strict = hasParsedCliOption(options, '--strict');
-    const report = checkMustflowProjectReport(resolveMustflowRoot(), { strict });
-    const issues = report.issues;
-    const warnings = report.warnings;
-    const ok = issues.length === 0;
-    if (hasParsedCliOption(options, '--json')) {
-        reporter.stdout(JSON.stringify({
-            ok,
-            strict,
-            issueCount: issues.length,
-            issues,
-            warningCount: warnings.length,
-            warnings,
-            issueDetails: report.issueDetails,
-        }, null, 2));
-        return ok ? 0 : 1;
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = acquireActiveCommandLock(projectRoot, 'mf check', GENERATED_SURFACE_READ_EFFECTS);
+    if (!activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf check', activeLock.conflicts, 'mf check --help', lang);
+        return 1;
     }
-    if (ok) {
-        for (const warning of warnings) {
-            reporter.stderr(warning);
+    try {
+        const report = checkMustflowProjectReport(projectRoot, { strict });
+        const issues = report.issues;
+        const warnings = report.warnings;
+        const ok = issues.length === 0;
+        if (hasParsedCliOption(options, '--json')) {
+            reporter.stdout(JSON.stringify({
+                ok,
+                strict,
+                issueCount: issues.length,
+                issues,
+                warningCount: warnings.length,
+                warnings,
+                issueDetails: report.issueDetails,
+            }, null, 2));
+            return ok ? 0 : 1;
         }
-        if (strict) {
-            reporter.stdout(t(lang, 'check.result.strictPassed'));
+        if (ok) {
+            for (const warning of warnings) {
+                reporter.stderr(warning);
+            }
+            if (strict) {
+                reporter.stdout(t(lang, 'check.result.strictPassed'));
+                return 0;
+            }
+            reporter.stdout(t(lang, 'check.result.passed'));
             return 0;
         }
-        reporter.stdout(t(lang, 'check.result.passed'));
-        return 0;
+        for (const issue of issues) {
+            reporter.stderr(issue);
+        }
+        reporter.stderr(t(lang, 'check.result.failed', { count: issues.length }));
+        return 1;
     }
-    for (const issue of issues) {
-        reporter.stderr(issue);
+    finally {
+        activeLock.handle.release();
     }
-    reporter.stderr(t(lang, 'check.result.failed', { count: issues.length }));
-    return 1;
 }

package/dist/cli/commands/doctor.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, GENERATED_SURFACE_READ_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { getAgentContext, } from '../lib/agent-context.js';
 import { t } from '../lib/i18n.js';
 import { getLocalIndexDatabasePath } from '../lib/local-index.js';
@@ -278,11 +279,22 @@ export function runDoctor(args, reporter, lang = 'en') {
         printUsageError(reporter, formatCliOptionParseError(options.error, lang), 'mf doctor --help', getDoctorHelp(lang), lang);
         return 1;
     }
-    const output = createDoctorOutput(hasParsedCliOption(options, '--strict'));
-    if (hasParsedCliOption(options, '--json')) {
-        reporter.stdout(JSON.stringify(output, null, 2));
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = acquireActiveCommandLock(projectRoot, 'mf doctor', GENERATED_SURFACE_READ_EFFECTS);
+    if (!activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf doctor', activeLock.conflicts, 'mf doctor --help', lang);
+        return 1;
+    }
+    try {
+        const output = createDoctorOutput(hasParsedCliOption(options, '--strict'));
+        if (hasParsedCliOption(options, '--json')) {
+            reporter.stdout(JSON.stringify(output, null, 2));
+            return output.ok ? 0 : 1;
+        }
+        reporter.stdout(renderDoctorOutput(output, lang));
         return output.ok ? 0 : 1;
     }
-    reporter.stdout(renderDoctorOutput(output, lang));
-    return output.ok ? 0 : 1;
+    finally {
+        activeLock.handle.release();
+    }
 }

package/dist/cli/commands/index.js

@@ -1,4 +1,5 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, LOCAL_INDEX_WRITE_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { createLocalIndex } from '../lib/local-index.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
@@ -83,15 +84,29 @@ export async function runIndex(args, reporter, lang = 'en') {
         printUsageError(reporter, formatCliOptionParseError(parsed.error, lang), 'mf index --help', getIndexHelp(lang), lang);
         return 1;
     }
-    const result = await createLocalIndex(resolveMustflowRoot(), {
-        dryRun: hasParsedCliOption(parsed, '--dry-run'),
-        includeSource: hasParsedCliOption(parsed, '--source'),
-        incremental: hasParsedCliOption(parsed, '--incremental'),
-    });
-    if (hasParsedCliOption(parsed, '--json')) {
-        reporter.stdout(JSON.stringify(result, null, 2));
+    const dryRun = hasParsedCliOption(parsed, '--dry-run');
+    const projectRoot = resolveMustflowRoot();
+    const activeLock = dryRun ? null : acquireActiveCommandLock(projectRoot, 'mf index', LOCAL_INDEX_WRITE_EFFECTS);
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf index', activeLock.conflicts, 'mf index --help', lang);
+        return 1;
+    }
+    try {
+        const result = await createLocalIndex(projectRoot, {
+            dryRun,
+            includeSource: hasParsedCliOption(parsed, '--source'),
+            incremental: hasParsedCliOption(parsed, '--incremental'),
+        });
+        if (hasParsedCliOption(parsed, '--json')) {
+            reporter.stdout(JSON.stringify(result, null, 2));
+            return 0;
+        }
+        reporter.stdout(renderIndexSummary(result, lang));
         return 0;
     }
-    reporter.stdout(renderIndexSummary(result, lang));
-    return 0;
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
+    }
 }

package/dist/cli/commands/map.js

@@ -1,5 +1,6 @@
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
+import { acquireActiveCommandLock, REPO_MAP_WRITE_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { formatCliOptionParseError, getParsedCliStringOption, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { generateRepoMap, writeRepoMap } from '../lib/repo-map.js';
@@ -71,13 +72,25 @@ export function runMap(args, reporter, lang = 'en') {
         shouldPrint = true;
     }
     const projectRoot = resolveMustflowRoot();
-    const content = generateRepoMap(projectRoot, { depth, includeNested });
-    if (shouldWrite) {
-        writeRepoMap(projectRoot, content);
-        reporter.stdout(t(lang, 'map.wrote'));
+    const activeLock = shouldWrite ? acquireActiveCommandLock(projectRoot, 'mf map --write', REPO_MAP_WRITE_EFFECTS) : null;
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf map --write', activeLock.conflicts, 'mf map --help', lang);
+        return 1;
+    }
+    try {
+        const content = generateRepoMap(projectRoot, { depth, includeNested });
+        if (shouldWrite) {
+            writeRepoMap(projectRoot, content);
+            reporter.stdout(t(lang, 'map.wrote'));
+        }
+        if (shouldPrint) {
+            reporter.stdout(content);
+        }
+        return 0;
     }
-    if (shouldPrint) {
-        reporter.stdout(content);
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
     }
-    return 0;
 }

package/dist/cli/commands/run.js

@@ -1,6 +1,6 @@
 import { createHash } from 'node:crypto';
 import { performance } from 'node:perf_hooks';
-import { acquireActiveRunLock } from '../../core/active-run-locks.js';
+import { ACTIVE_RUN_LOCK_ID_ENV, acquireActiveRunLock } from '../../core/active-run-locks.js';
 import { createCommandEnv } from '../../core/command-env.js';
 import { createCorrelationId } from '../../core/correlation-id.js';
 import { printUsageError, renderCliError, renderHelp } from '../lib/cli-output.js';
@@ -360,6 +360,7 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
     try {
         const runReceiptPolicy = profiler.measure('retention_policy', () => resolveRunReceiptRetentionPolicy(readMustflowConfigIfExists(projectRoot)));
         const env = profiler.measure('environment', () => createCommandEnv(projectRoot, { policy: plan.envPolicy, allowlist: plan.envAllowlist }));
+        env[ACTIVE_RUN_LOCK_ID_ENV] = activeRunLock.handle.record.run_id;
         const writeTracker = profiler.measure('write_drift_before', () => startRunWriteTracking(projectRoot, contract, intentName, {
             additionalDeclaredPaths: options.additionalDeclaredWritePaths,
             env,

package/dist/cli/commands/update.js

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { copyFileInsideWithoutSymlinks, ensureFileTargetInsideWithoutSymlinks, ensureInside, writeUtf8FileInsideWithoutSymlinks, } from '../lib/filesystem.js';
 import { MANIFEST_LOCK_RELATIVE_PATH, readManifestLock, sha256File } from '../lib/manifest-lock.js';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
+import { acquireActiveCommandLock, MUSTFLOW_UPDATE_APPLY_EFFECTS, reportActiveCommandLockConflict, } from '../lib/active-command-lock.js';
 import { t } from '../lib/i18n.js';
 import { formatCliOptionParseError, hasCliOptionToken, hasParsedCliOption, parseCliOptions, } from '../lib/option-parser.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
@@ -430,53 +431,65 @@ export function runUpdate(args, reporter, lang = 'en') {
         return 1;
     }
     const projectRoot = resolveMustflowRoot();
-    const plan = createUpdatePlan(projectRoot);
-    if (plan.error) {
-        if (wantsJson) {
-            reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), plan.error, false), requestedMode), null, 2));
-            return 1;
-        }
-        reporter.stderr(plan.error);
+    const activeLock = wantsApply ? acquireActiveCommandLock(projectRoot, 'mf update --apply', MUSTFLOW_UPDATE_APPLY_EFFECTS) : null;
+    if (activeLock && !activeLock.ok) {
+        reportActiveCommandLockConflict(reporter, 'mf update --apply', activeLock.conflicts, 'mf update --help', lang);
         return 1;
     }
-    const outputItems = wantsDiff ? withDiffPreviews(projectRoot, plan.items) : publicPlanItems(plan.items);
-    const dryRunOutput = withMode(planOutput(outputItems, undefined, false), requestedMode);
-    if (wantsDryRun) {
-        if (wantsJson) {
-            reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+    try {
+        const plan = createUpdatePlan(projectRoot);
+        if (plan.error) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), plan.error, false), requestedMode), null, 2));
+                return 1;
+            }
+            reporter.stderr(plan.error);
+            return 1;
+        }
+        const outputItems = wantsDiff ? withDiffPreviews(projectRoot, plan.items) : publicPlanItems(plan.items);
+        const dryRunOutput = withMode(planOutput(outputItems, undefined, false), requestedMode);
+        if (wantsDryRun) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+                return dryRunOutput.ok ? 0 : 1;
+            }
+            printPlan(dryRunOutput, reporter, lang);
+            if (wantsDiff) {
+                printDiffPreviews(dryRunOutput.items, reporter, lang);
+            }
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
             return dryRunOutput.ok ? 0 : 1;
         }
-        printPlan(dryRunOutput, reporter, lang);
-        if (wantsDiff) {
-            printDiffPreviews(dryRunOutput.items, reporter, lang);
+        if (!dryRunOutput.ok) {
+            if (wantsJson) {
+                reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
+                return 1;
+            }
+            printPlan(dryRunOutput, reporter, lang);
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
+            return 1;
         }
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return dryRunOutput.ok ? 0 : 1;
-    }
-    if (!dryRunOutput.ok) {
         if (wantsJson) {
-            reporter.stdout(JSON.stringify(dryRunOutput, null, 2));
-            return 1;
+            const applicableItems = plan.items.filter((item) => item.action === 'create' || item.action === 'update');
+            const applyResult = applyUpdate(projectRoot, applicableItems, {
+                stdout: () => undefined,
+                stderr: (message) => reporter.stderr(message),
+            }, lang);
+            reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), undefined, applyResult.wroteFiles), 'apply'), null, 2));
+            return 0;
         }
-        printPlan(dryRunOutput, reporter, lang);
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return 1;
-    }
-    if (wantsJson) {
-        const applicableItems = plan.items.filter((item) => item.action === 'create' || item.action === 'update');
-        const applyResult = applyUpdate(projectRoot, applicableItems, {
-            stdout: () => undefined,
-            stderr: (message) => reporter.stderr(message),
-        }, lang);
-        reporter.stdout(JSON.stringify(withMode(planOutput(publicPlanItems(plan.items), undefined, applyResult.wroteFiles), 'apply'), null, 2));
+        const applyResult = applyUpdate(projectRoot, plan.items, reporter, lang);
+        if (!applyResult.wroteFiles) {
+            reporter.stdout(t(lang, 'update.plan.noUpdates'));
+            reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
+            return 0;
+        }
+        reporter.stdout(t(lang, 'update.complete', { updated: applyResult.updated, created: applyResult.created }));
         return 0;
     }
-    const applyResult = applyUpdate(projectRoot, plan.items, reporter, lang);
-    if (!applyResult.wroteFiles) {
-        reporter.stdout(t(lang, 'update.plan.noUpdates'));
-        reporter.stdout(t(lang, 'update.plan.noFilesWritten'));
-        return 0;
+    finally {
+        if (activeLock?.ok) {
+            activeLock.handle.release();
+        }
     }
-    reporter.stdout(t(lang, 'update.complete', { updated: applyResult.updated, created: applyResult.created }));
-    return 0;
 }

package/dist/cli/lib/active-command-lock.js

@@ -0,0 +1,96 @@
+import { ACTIVE_RUN_LOCK_ID_ENV, acquireActiveRunLock, } from '../../core/active-run-locks.js';
+import { renderCliError } from './cli-output.js';
+import { t } from './i18n.js';
+export const REPO_MAP_WRITE_EFFECTS = [
+    { type: 'write', mode: 'replace', path: 'REPO_MAP.md', concurrency: 'exclusive' },
+];
+export const LOCAL_INDEX_WRITE_EFFECTS = [
+    {
+        type: 'write',
+        mode: 'replace',
+        path: '.mustflow/cache/**',
+        lock: 'local_index_cache',
+        concurrency: 'exclusive',
+    },
+];
+export const MUSTFLOW_UPDATE_APPLY_EFFECTS = [
+    { type: 'write', mode: 'replace', path: 'AGENTS.md', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/manifest.lock.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/commands.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/mustflow.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/config/preferences.toml', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/context/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/docs/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/skills/**', concurrency: 'exclusive' },
+    { type: 'write', mode: 'replace', path: '.mustflow/backups/**', concurrency: 'exclusive' },
+];
+export const GENERATED_SURFACE_READ_EFFECTS = [
+    { type: 'read', mode: 'read', path: 'REPO_MAP.md', concurrency: 'shared' },
+    { type: 'read', mode: 'read', path: '.mustflow/config/manifest.lock.toml', concurrency: 'shared' },
+    {
+        type: 'read',
+        mode: 'read',
+        path: '.mustflow/cache/**',
+        lock: 'local_index_cache',
+        concurrency: 'shared',
+    },
+];
+function effectToToml(effect) {
+    const output = {
+        type: effect.type,
+    };
+    if (effect.mode) {
+        output.mode = effect.mode;
+    }
+    if (effect.path) {
+        output.path = effect.path;
+    }
+    if (effect.paths) {
+        output.paths = [...effect.paths];
+    }
+    if (effect.lock) {
+        output.lock = effect.lock;
+    }
+    if (effect.concurrency) {
+        output.concurrency = effect.concurrency;
+    }
+    return output;
+}
+function createSyntheticCommandContract(intentName, effects) {
+    return {
+        defaults: { default_cwd: '.' },
+        resources: {},
+        intents: {
+            [intentName]: {
+                cwd: '.',
+                writes: [],
+                effects: effects.map(effectToToml),
+            },
+        },
+    };
+}
+function parentRunId() {
+    const value = process.env[ACTIVE_RUN_LOCK_ID_ENV]?.trim();
+    return value && value.length > 0 ? value : null;
+}
+export function acquireActiveCommandLock(projectRoot, displayName, effects) {
+    return acquireActiveRunLock(projectRoot, createSyntheticCommandContract(displayName, effects), displayName, {
+        commandHash: null,
+        ignoreRunId: parentRunId(),
+        ignorePid: process.ppid,
+    });
+}
+export function renderActiveCommandLockConflictMessage(displayName, conflicts, lang) {
+    const [first] = conflicts;
+    const detail = first
+        ? t(lang, 'run.error.activeLockConflictDetail', {
+            lock: first.lock,
+            intent: first.conflictsWithIntent,
+            pid: first.conflictsWithPid,
+        })
+        : t(lang, 'run.error.activeLockConflictUnknown');
+    return t(lang, 'run.error.activeLockConflict', { intent: displayName, detail });
+}
+export function reportActiveCommandLockConflict(reporter, displayName, conflicts, helpCommand, lang) {
+    reporter.stderr(renderCliError(renderActiveCommandLockConflictMessage(displayName, conflicts, lang), helpCommand, lang));
+}

package/dist/core/active-run-locks.js

@@ -6,6 +6,7 @@ import { readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks,
 const ACTIVE_LOCK_SCHEMA_VERSION = '1';
 const ACTIVE_LOCK_KIND = 'active_run_lock';
 const LOCK_ROOT_RELATIVE_PATH = '.mustflow/state/locks';
+export const ACTIVE_RUN_LOCK_ID_ENV = 'MUSTFLOW_ACTIVE_RUN_LOCK_ID';
 const LOCK_MUTEX_STALE_MS = 30_000;
 const LOCK_MUTEX_WAIT_MS = 1_000;
 const LOCK_MUTEX_SLEEP_MS = 25;
@@ -462,7 +463,12 @@ export function acquireActiveRunLock(projectRoot, contract, intentName, options
             }
         }
         const staleRecordIds = new Set(staleRecords.map((stale) => stale.runId));
-        const liveRecords = records.filter((record) => !staleRecordIds.has(record.run_id));
+        const liveRecords = records.filter((record) => {
+            if (staleRecordIds.has(record.run_id)) {
+                return false;
+            }
+            return record.run_id !== options.ignoreRunId || record.pid !== options.ignorePid;
+        });
         const conflicts = findConflicts(intentName, effects, liveRecords);
         if (conflicts.length > 0) {
             return { ok: false, conflicts, recoveredStaleRecords: staleRecords };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mustflow",
-  "version": "2.74.0",
+  "version": "2.74.1",
   "description": "Agent workflow documents and CLI for mustflow repository roots.",
   "type": "module",
   "license": "MIT-0",

package/templates/default/manifest.toml

@@ -1,6 +1,6 @@
 id = "default"
 name = "default"
-version = "2.74.0"
+version = "2.74.1"
 description = "Minimal workflow for LLM agents to read, edit, and verify their work in a repository."
 common_root = "common"
 locales_root = "locales"