mustflow 2.22.47 → 2.22.49

package/README.md

@@ -253,8 +253,9 @@ mf run mustflow_update_apply
 | `mf api command-catalog --json` | Print command intent availability and safe `mf run` entrypoints without exposing raw command strings. |
 | `mf api verification-plan --changed --json` | Print a stable, read-only verification plan for changed files without executing commands. |
 | `mf api latest-evidence --json` | Print bounded latest run or verify evidence without raw command output. |
-| `mf api diff-risk --changed --json` | Print a compact changed-file risk and verification summary. |
+| `mf api diff-risk --changed --json` | Print a compact changed-file risk, verification summary, and read-only residual correction signals. |
 | `mf api health --json` | Print a compact workspace health report for quick agent gating. |
+| `mf api locks --json` | Print active `mf run` locks for multi-session coordination. |
 | `mf docs review list` | Show documents still waiting for prose review after agent edits. |
 | `mf docs review add <path>` | Add or refresh a document review queue entry. |
 | `mf docs review comment <path>` | Add multiline review guidance to an existing queue entry. |
@@ -264,6 +265,7 @@ mf run mustflow_update_apply
 | `mf map --stdout` | Print the current mustflow root map to stdout. |
 | `mf map --write` | Create or update `REPO_MAP.md`. |
 | `mf run <intent>` | Run an allowed one-shot command. |
+| `mf run <intent> --wait` | Wait for conflicting active run locks before executing the command. |
 | `mf run <intent> --dry-run --json` | Preview whether an intent is runnable and what command metadata would be used, without executing it. |
 | `mf index` | Build a SQLite index for mustflow docs, skill routes, command rules, command-effect locks, and file fingerprints. Use `--incremental` to reuse a compatible fresh index without rewriting it. |
 | `mf search <query>` | Search docs, skills, skill routes, command rules, and command-effect locks in the SQLite index. |

package/dist/cli/commands/api.js

@@ -1,6 +1,7 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { createClassifyOutput } from './classify.js';
+import { listActiveRunLocks } from '../../core/active-run-locks.js';
 import { createChangeVerificationReport, } from '../../core/change-verification.js';
 import { readUtf8FileInsideWithoutSymlinks } from '../../core/safe-filesystem.js';
 import { createVerificationPlanId } from '../../core/verification-plan-id.js';
@@ -18,8 +19,10 @@ const API_VERIFICATION_PLAN_SCHEMA_VERSION = '1';
 const API_LATEST_EVIDENCE_SCHEMA_VERSION = '1';
 const API_DIFF_RISK_SCHEMA_VERSION = '1';
 const API_HEALTH_SCHEMA_VERSION = '1';
+const API_LOCKS_SCHEMA_VERSION = '1';
 const COMMANDS_RELATIVE_PATH = '.mustflow/config/commands.toml';
 const LATEST_RUN_RELATIVE_PATH = '.mustflow/state/runs/latest.json';
+const LOCKS_RELATIVE_PATH = '.mustflow/state/locks';
 const MUSTFLOW_JSON_MAX_BYTES = 1024 * 1024;
 export function getApiHelp(lang = 'en') {
     return renderHelp({
@@ -50,6 +53,10 @@ export function getApiHelp(lang = 'en') {
                 label: 'health',
                 description: t(lang, 'api.help.action.health'),
             },
+            {
+                label: 'locks',
+                description: t(lang, 'api.help.action.locks'),
+            },
         ],
         options: [
             { label: '--changed', description: t(lang, 'classify.help.option.changed') },
@@ -63,6 +70,7 @@ export function getApiHelp(lang = 'en') {
             'mf api latest-evidence --json',
             'mf api diff-risk --changed --json',
             'mf api health --json',
+            'mf api locks --json',
         ],
         exitCodes: [
             { label: '0', description: t(lang, 'api.help.exit.ok') },
@@ -658,6 +666,150 @@ function getRiskLevel(classification, report) {
     }
     return 'low';
 }
+function uniqueSortedStrings(values) {
+    return [...new Set(values.filter((value) => typeof value === 'string' && value.length > 0))]
+        .sort((left, right) => left.localeCompare(right));
+}
+function readEvidenceRequirements(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.requirements)) {
+        return [];
+    }
+    return parsed.evidence_model.requirements.filter(isRecord);
+}
+function readEvidenceRemainingRisks(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.remaining_risks)) {
+        return [];
+    }
+    return parsed.evidence_model.remaining_risks.filter(isRecord);
+}
+function readEvidenceReceipts(parsed) {
+    if (!isRecord(parsed) || !isRecord(parsed.evidence_model) || !Array.isArray(parsed.evidence_model.receipts)) {
+        return [];
+    }
+    return parsed.evidence_model.receipts.filter(isRecord);
+}
+function affectedReasonsFromLatest(parsed) {
+    return uniqueSortedStrings(readEvidenceRequirements(parsed).map((requirement) => readString(requirement, 'reason')));
+}
+function affectedIntentsFromLatest(parsed) {
+    const requirementIntents = readEvidenceRequirements(parsed).flatMap((requirement) => [
+        ...(Array.isArray(requirement.selected_intents) ? requirement.selected_intents : []),
+        ...(Array.isArray(requirement.skipped_intents) ? requirement.skipped_intents : []),
+    ]);
+    const receiptIntents = readEvidenceReceipts(parsed).map((receipt) => readString(receipt, 'intent'));
+    return uniqueSortedStrings([...requirementIntents, ...receiptIntents]);
+}
+function repeatedFailureConfidence(seenCount, requiresNewEvidence) {
+    if (requiresNewEvidence || seenCount >= 3) {
+        return 'high';
+    }
+    return seenCount >= 2 ? 'medium' : 'low';
+}
+function createResidualPolicy() {
+    return {
+        single_observation_changes_plan: false,
+        minimum_repeated_samples_for_plan_change: 2,
+        automatic_intent_additions_enabled: false,
+    };
+}
+function createEmptyResidualCorrections(status, issues = []) {
+    return {
+        status,
+        mode: 'read_only',
+        grants_command_authority: false,
+        applies_to_current_plan: false,
+        selected_intent_additions: [],
+        suggested_intent_additions: [],
+        recommended_commands: [],
+        signals: [],
+        policy: createResidualPolicy(),
+        issues,
+    };
+}
+function createResidualCorrections(projectRoot, verificationPlanId) {
+    if (!verificationPlanId) {
+        return createEmptyResidualCorrections('not_enough_evidence');
+    }
+    let parsed;
+    try {
+        parsed = readJsonInsideRoot(projectRoot, LATEST_RUN_RELATIVE_PATH);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return message.includes('ENOENT') ? createEmptyResidualCorrections('not_enough_evidence') : createEmptyResidualCorrections('unavailable', [message]);
+    }
+    if (!isRecord(parsed) || parsed.command !== 'verify' || parsed.kind !== 'verify_run_summary') {
+        return createEmptyResidualCorrections('not_enough_evidence');
+    }
+    const latestPlanId = readString(parsed, 'verification_plan_id') ?? null;
+    const appliesToCurrentPlan = latestPlanId === verificationPlanId;
+    const affectedReasons = affectedReasonsFromLatest(parsed);
+    const affectedIntents = affectedIntentsFromLatest(parsed);
+    const completionVerdict = isRecord(parsed.completion_verdict) ? parsed.completion_verdict : null;
+    const completionStatus = completionVerdict ? readString(completionVerdict, 'status') : null;
+    const signals = [];
+    if (appliesToCurrentPlan && completionStatus && completionStatus !== 'verified') {
+        signals.push({
+            kind: 'latest_unresolved_plan',
+            confidence: 'low',
+            evidence_count: 1,
+            source: 'latest-evidence',
+            verification_plan_id: latestPlanId,
+            affected_reasons: affectedReasons,
+            affected_intents: affectedIntents,
+            detail: `Latest verify evidence for this plan ended with completion verdict ${completionStatus}; do not treat the base plan as complete without new evidence.`,
+            recommendation: 'provide_new_evidence',
+        });
+    }
+    const repeatedFailure = isRecord(parsed.repeated_failure_summary) ? parsed.repeated_failure_summary : null;
+    if (appliesToCurrentPlan && repeatedFailure) {
+        const seenCount = typeof repeatedFailure.seen_count === 'number' && Number.isFinite(repeatedFailure.seen_count)
+            ? Math.max(1, Math.floor(repeatedFailure.seen_count))
+            : 1;
+        const requiresNewEvidence = repeatedFailure.requires_new_evidence === true;
+        if (seenCount >= 2 || requiresNewEvidence) {
+            signals.push({
+                kind: 'repeated_failure',
+                confidence: repeatedFailureConfidence(seenCount, requiresNewEvidence),
+                evidence_count: seenCount,
+                source: 'latest-evidence',
+                verification_plan_id: latestPlanId,
+                affected_reasons: affectedReasons,
+                affected_intents: affectedIntents,
+                detail: 'Latest evidence reports repeated unresolved verification for this plan; collect new evidence or narrow the hypothesis before claiming completion.',
+                recommendation: 'provide_new_evidence',
+            });
+        }
+    }
+    if (appliesToCurrentPlan) {
+        for (const risk of readEvidenceRemainingRisks(parsed).slice(0, 5)) {
+            const detail = readString(risk, 'detail') ?? readString(risk, 'code') ?? 'Latest verify evidence has a remaining risk.';
+            signals.push({
+                kind: 'remaining_risk',
+                confidence: 'low',
+                evidence_count: 1,
+                source: 'latest-evidence',
+                verification_plan_id: latestPlanId,
+                affected_reasons: affectedReasons,
+                affected_intents: affectedIntents,
+                detail,
+                recommendation: 'review_remaining_risk',
+            });
+        }
+    }
+    return {
+        status: signals.length > 0 ? 'available' : 'not_enough_evidence',
+        mode: 'read_only',
+        grants_command_authority: false,
+        applies_to_current_plan: appliesToCurrentPlan,
+        selected_intent_additions: [],
+        suggested_intent_additions: [],
+        recommended_commands: signals.length > 0 ? ['mf api latest-evidence --json'] : [],
+        signals,
+        policy: createResidualPolicy(),
+        issues: [],
+    };
+}
 function createDiffRiskOutput() {
     const mustflowRoot = resolveMustflowRoot();
     let classification = null;
@@ -680,21 +832,32 @@ function createDiffRiskOutput() {
             update_policies: [],
             drift_checks: [],
             required_verification: [],
+            residual_corrections: createResidualCorrections(mustflowRoot, null),
             gap_count: 0,
             gaps: [],
             recommended_commands: [],
             issues: [message],
         };
     }
-    let report = null;
     const issues = [];
+    let contract = null;
     try {
-        report = createChangeVerificationReport(classification, readCommandContract(mustflowRoot), mustflowRoot);
+        contract = readCommandContract(mustflowRoot);
     }
     catch (error) {
         issues.push(error instanceof Error ? error.message : String(error));
     }
+    let report = null;
+    if (contract) {
+        try {
+            report = createChangeVerificationReport(classification, contract, mustflowRoot);
+        }
+        catch (error) {
+            issues.push(error instanceof Error ? error.message : String(error));
+        }
+    }
     const requiredVerification = report ? report.schedule.entries.map((entry) => entry.intent) : [];
+    const verificationPlanId = report && contract ? createVerificationPlanId(report, contract) : null;
     return {
         schema_version: API_DIFF_RISK_SCHEMA_VERSION,
         command: 'api diff-risk',
@@ -709,6 +872,7 @@ function createDiffRiskOutput() {
         update_policies: classification.summary.updatePolicies,
         drift_checks: classification.summary.driftChecks,
         required_verification: requiredVerification,
+        residual_corrections: createResidualCorrections(mustflowRoot, verificationPlanId),
         gap_count: report?.gaps.length ?? 0,
         gaps: report?.gaps.map((gap) => ({
             reason: gap.reason,
@@ -757,6 +921,68 @@ function createHealthOutput() {
         recommended_next_commands: workspace.recommended_next_commands,
     };
 }
+function createLocksOutput() {
+    const mustflowRoot = resolveMustflowRoot();
+    try {
+        const state = listActiveRunLocks(mustflowRoot);
+        const activeLocks = state.activeRecords.map((record) => ({
+            run_id: record.run_id,
+            intent: record.intent,
+            pid: record.pid,
+            started_at: record.started_at,
+            command_hash: record.command_hash,
+            effects: record.effects,
+            writes: record.writes,
+        }));
+        const staleLocks = state.staleRecords.map((record) => ({
+            run_id: record.runId,
+            intent: record.intent,
+            pid: record.pid,
+            reason: record.reason,
+        }));
+        const recommendedCommands = activeLocks.length > 0 ? ['mf api locks --json', 'mf run <intent> --wait'] : [];
+        return {
+            schema_version: API_LOCKS_SCHEMA_VERSION,
+            command: 'api locks',
+            mustflow_root: mustflowRoot,
+            status: activeLocks.length > 0 ? 'active' : staleLocks.length > 0 ? 'stale' : 'clear',
+            lock_root: LOCKS_RELATIVE_PATH,
+            active_count: activeLocks.length,
+            stale_count: staleLocks.length,
+            active_locks: activeLocks,
+            stale_locks: staleLocks,
+            policy: {
+                source: 'active-run-locks',
+                conflict_model: 'command_effects_and_writes',
+                direct_commands_bypass_locks: true,
+                wait_entrypoint: 'mf run <intent> --wait',
+            },
+            recommended_commands: recommendedCommands,
+            issues: [],
+        };
+    }
+    catch (error) {
+        return {
+            schema_version: API_LOCKS_SCHEMA_VERSION,
+            command: 'api locks',
+            mustflow_root: mustflowRoot,
+            status: 'unavailable',
+            lock_root: LOCKS_RELATIVE_PATH,
+            active_count: 0,
+            stale_count: 0,
+            active_locks: [],
+            stale_locks: [],
+            policy: {
+                source: 'active-run-locks',
+                conflict_model: 'command_effects_and_writes',
+                direct_commands_bypass_locks: true,
+                wait_entrypoint: 'mf run <intent> --wait',
+            },
+            recommended_commands: [],
+            issues: [error instanceof Error ? error.message : String(error)],
+        };
+    }
+}
 function validateJsonOnlyAction(action, args, reporter, lang) {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getApiHelp(lang));
@@ -837,6 +1063,13 @@ function runHealth(args, reporter, lang) {
     reporter.stdout(JSON.stringify(createHealthOutput(), null, 2));
     return 0;
 }
+function runLocks(args, reporter, lang) {
+    if (!validateJsonOnlyAction('locks', args, reporter, lang)) {
+        return args.includes('--help') || args.includes('-h') ? 0 : 1;
+    }
+    reporter.stdout(JSON.stringify(createLocksOutput(), null, 2));
+    return 0;
+}
 export function runApi(args, reporter, lang = 'en') {
     if (args.includes('--help') || args.includes('-h')) {
         reporter.stdout(getApiHelp(lang));
@@ -869,6 +1102,9 @@ export function runApi(args, reporter, lang = 'en') {
     if (action === 'health') {
         return runHealth(rest, reporter, lang);
     }
+    if (action === 'locks') {
+        return runLocks(rest, reporter, lang);
+    }
     printUsageError(reporter, t(lang, 'api.error.unknownAction', { action }), 'mf api --help', getApiHelp(lang), lang);
     return 1;
 }

package/dist/cli/commands/run.js

@@ -18,6 +18,13 @@ import { getRunStatus, runArgvCommandStreaming, runShellCommandStreaming } from
 import { emitOutput, isOutputLimitExceededError } from './run/output.js';
 import { createPendingTimeoutTermination, getKillMethod, terminateProcessTree } from './run/process-tree.js';
 import { assembleRunReceipt } from './run/receipt.js';
+const DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS = 300;
+const ACTIVE_LOCK_WAIT_POLL_MS = 1_000;
+function delay(milliseconds) {
+    return new Promise((resolve) => {
+        setTimeout(resolve, milliseconds);
+    });
+}
 function getRunPlanDetail(plan, lang, fallbackKey) {
     return plan.detail ?? t(lang, fallbackKey);
 }
@@ -117,6 +124,77 @@ function renderActiveLockConflictMessage(intentName, conflicts, lang) {
         : t(lang, 'run.error.activeLockConflictUnknown');
     return t(lang, 'run.error.activeLockConflict', { intent: intentName, detail });
 }
+function parseRunArguments(args) {
+    const supportedBooleanOptions = new Set(['--json', '--dry-run', '--plan-only', '--wait', ALLOW_UNTRUSTED_ROOT_OPTION]);
+    const supportedValueOptions = new Set(['--wait-timeout']);
+    const positional = [];
+    const unsupported = [];
+    let waitTimeoutSeconds = DEFAULT_ACTIVE_LOCK_WAIT_TIMEOUT_SECONDS;
+    let invalidWaitTimeout = false;
+    for (let index = 0; index < args.length; index += 1) {
+        const arg = args[index];
+        if (supportedBooleanOptions.has(arg)) {
+            continue;
+        }
+        if (supportedValueOptions.has(arg)) {
+            const value = args[index + 1];
+            if (!value || value.startsWith('-')) {
+                invalidWaitTimeout = true;
+                continue;
+            }
+            const parsed = Number(value);
+            if (!Number.isInteger(parsed) || parsed <= 0) {
+                invalidWaitTimeout = true;
+            }
+            else {
+                waitTimeoutSeconds = parsed;
+            }
+            index += 1;
+            continue;
+        }
+        if (arg.startsWith('-')) {
+            unsupported.push(arg);
+            continue;
+        }
+        positional.push(arg);
+    }
+    const [intentName, ...extra] = positional;
+    return {
+        json: args.includes('--json'),
+        dryRun: args.includes('--dry-run'),
+        planOnly: args.includes('--plan-only'),
+        allowUntrustedRoot: args.includes(ALLOW_UNTRUSTED_ROOT_OPTION),
+        wait: args.includes('--wait'),
+        waitTimeoutSeconds,
+        intentName: intentName ?? null,
+        extra,
+        unsupported,
+        invalidWaitTimeout,
+    };
+}
+async function acquireActiveRunLockWithOptionalWait(input) {
+    const startedAt = Date.now();
+    let reportedWait = false;
+    while (true) {
+        const result = acquireActiveRunLock(input.projectRoot, input.contract, input.intentName, { commandHash: input.commandHash });
+        if (result.ok || !input.enabled || result.conflicts.length === 0) {
+            return result;
+        }
+        if (!input.json && !reportedWait) {
+            const [first] = result.conflicts;
+            input.reporter.stderr(t(input.lang, 'run.progress.waitingForActiveLock', {
+                intent: input.intentName,
+                activeIntent: first?.conflictsWithIntent ?? 'unknown',
+                seconds: input.waitTimeoutSeconds,
+            }));
+            reportedWait = true;
+        }
+        if (Date.now() - startedAt >= input.waitTimeoutSeconds * 1000) {
+            return result;
+        }
+        await delay(Math.min(ACTIVE_LOCK_WAIT_POLL_MS, Math.max(1, input.waitTimeoutSeconds * 1000 - (Date.now() - startedAt))));
+    }
+}
 function createRunProgressReporter(input) {
     if (!input.enabled) {
         return () => undefined;
@@ -150,6 +228,8 @@ export function getRunHelp(lang = 'en') {
             { label: '--dry-run', description: t(lang, 'run.help.option.dryRun') },
             { label: '--plan-only', description: t(lang, 'run.help.option.planOnly') },
             { label: '--json', description: t(lang, 'run.help.option.json') },
+            { label: '--wait', description: t(lang, 'run.help.option.wait') },
+            { label: '--wait-timeout <seconds>', description: t(lang, 'run.help.option.waitTimeout') },
             { label: ALLOW_UNTRUSTED_ROOT_OPTION, description: t(lang, 'run.help.option.allowUntrustedRoot') },
             { label: '-h, --help', description: t(lang, 'cli.option.help') },
         ],
@@ -180,23 +260,31 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         reporter.stdout(getRunHelp(lang));
         return 0;
     }
-    const supportedOptions = new Set(['--json', '--dry-run', '--plan-only', ALLOW_UNTRUSTED_ROOT_OPTION]);
-    const unsupported = args.filter((arg) => arg.startsWith('-') && !supportedOptions.has(arg));
+    const parsedArgs = parseRunArguments(args);
+    const unsupported = parsedArgs.unsupported;
     if (unsupported.length > 0) {
         printUsageError(reporter, t(lang, 'cli.error.unknownOption', { option: unsupported[0] }), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
-    const json = args.includes('--json');
-    const dryRun = args.includes('--dry-run');
-    const planOnly = args.includes('--plan-only');
-    const allowUntrustedRoot = args.includes(ALLOW_UNTRUSTED_ROOT_OPTION);
+    if (parsedArgs.invalidWaitTimeout) {
+        printUsageError(reporter, t(lang, 'run.error.invalidWaitTimeout'), 'mf run --help', getRunHelp(lang), lang);
+        return 1;
+    }
+    const json = parsedArgs.json;
+    const dryRun = parsedArgs.dryRun;
+    const planOnly = parsedArgs.planOnly;
+    const allowUntrustedRoot = parsedArgs.allowUntrustedRoot;
     const previewMode = dryRun ? 'dry-run' : planOnly ? 'plan-only' : null;
     if (dryRun && planOnly) {
         printUsageError(reporter, t(lang, 'run.error.conflictingPreviewModes'), 'mf run --help', getRunHelp(lang), lang);
         return 1;
     }
-    const positional = args.filter((arg) => !supportedOptions.has(arg));
-    const [intentName, ...extra] = positional;
+    if (parsedArgs.wait && previewMode) {
+        printUsageError(reporter, t(lang, 'run.error.waitRequiresExecution'), 'mf run --help', getRunHelp(lang), lang);
+        return 1;
+    }
+    const intentName = parsedArgs.intentName;
+    const extra = parsedArgs.extra;
     if (!intentName) {
         printUsageError(reporter, t(lang, 'run.error.missingIntent'), 'mf run --help', getRunHelp(lang), lang);
         return 1;
@@ -243,7 +331,17 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         });
         return 1;
     }
-    const activeRunLock = profiler.measure('active_lock_acquire', () => acquireActiveRunLock(projectRoot, contract, intentName, { commandHash: createPlanCommandHash(plan) }));
+    const activeRunLock = await profiler.measureAsync('active_lock_acquire', () => acquireActiveRunLockWithOptionalWait({
+        enabled: parsedArgs.wait,
+        waitTimeoutSeconds: parsedArgs.waitTimeoutSeconds,
+        projectRoot,
+        contract,
+        intentName,
+        commandHash: createPlanCommandHash(plan),
+        json,
+        reporter,
+        lang,
+    }));
     if (!activeRunLock.ok) {
         reporter.stderr(renderCliError(renderActiveLockConflictMessage(intentName, activeRunLock.conflicts, lang), 'mf run --dry-run --json', lang));
         writeLatestProfile(profiler, options, {

package/dist/cli/i18n/en.js

@@ -94,8 +94,9 @@ export const enMessages = {
     "api.help.action.latestEvidence": "Print bounded latest run or verify evidence for agents",
     "api.help.action.diffRisk": "Print a compact changed-file risk and verification summary",
     "api.help.action.health": "Print a compact workspace health summary",
+    "api.help.action.locks": "Print active mf run locks for multi-session coordination",
     "api.help.exit.ok": "The API report was inspected and printed",
-    "api.error.missingAction": "Specify an api action: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, or health",
+    "api.error.missingAction": "Specify an api action: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health, or locks",
     "api.error.unknownAction": "Unknown api action: {action}",
     "api.error.actionRequiresJson": "{action} requires --json",
     "api.error.actionRequiresChanged": "{action} currently requires --changed",
@@ -674,12 +675,15 @@ Read these files before working:
     "run.help.option.dryRun": "Print a non-executing command plan",
     "run.help.option.planOnly": "Alias for --dry-run",
     "run.help.option.json": "Print the run record or command plan as JSON",
+    "run.help.option.wait": "Wait for conflicting active run locks before executing",
+    "run.help.option.waitTimeout": "Maximum seconds to wait for active run locks. Default: 300",
     "run.help.option.allowUntrustedRoot": "Allow one execution from a root with a missing or invalid manifest lock after manual review",
     "run.help.exit.ok": "The command completed with an allowed exit code",
     "run.help.exit.fail": "The command was invalid, refused, timed out, or failed",
     "run.label.suggestedIntentSnippet": "Suggested command contract snippet",
     "run.progress.started": "Running {intent} (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "Still running {intent}... ({seconds}s elapsed, {percent}% of timeout)",
+    "run.progress.waitingForActiveLock": "Waiting to run {intent}; active intent {activeIntent} holds a conflicting lock (timeout: {seconds}s)",
     "run.error.missingIntent": "Missing command name",
     "run.error.unknownIntent": "Unknown command: {intent}",
     "run.error.statusNotConfigured": 'Command "{intent}" is {status}; only configured commands can be run',
@@ -702,6 +706,8 @@ Read these files before working:
     "run.error.maxOutputBytes": 'Command "{intent}" has invalid max_output_bytes. {detail}',
     "run.error.maxOutputBytesDetail": "The output limit must stay within the allowed maximum.",
     "run.error.conflictingPreviewModes": "Use either --dry-run or --plan-only, not both",
+    "run.error.invalidWaitTimeout": "--wait-timeout must be a positive integer",
+    "run.error.waitRequiresExecution": "--wait can only be used when executing a command, not with --dry-run or --plan-only",
     "run.error.untrustedRootMissing": "Refused to execute commands because {path} is missing. Run mf init/update to install the workflow, or pass --allow-untrusted-root after reviewing AGENTS.md and .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Refused to execute commands because the manifest lock is invalid: {detail}. Restore or regenerate it, or pass --allow-untrusted-root after reviewing AGENTS.md and .mustflow/config/commands.toml.",
     "run.error.timedOut": 'Command "{intent}" timed out after {seconds} seconds',

package/dist/cli/i18n/es.js

@@ -94,8 +94,9 @@ export const esMessages = {
     "api.help.action.latestEvidence": "Imprime evidencia bounded del último run o verify para agentes",
     "api.help.action.diffRisk": "Imprime un resumen compacto de riesgo y verificación para archivos cambiados",
     "api.help.action.health": "Imprime un resumen compacto de salud del workspace",
+    "api.help.action.locks": "Imprime bloqueos mf run activos para coordinar varias sesiones",
     "api.help.exit.ok": "El informe API se inspeccionó e imprimió",
-    "api.error.missingAction": "Especifica una acción api: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk o health",
+    "api.error.missingAction": "Especifica una acción api: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health o locks",
     "api.error.unknownAction": "Acción api desconocida: {action}",
     "api.error.actionRequiresJson": "{action} requiere --json",
     "api.error.actionRequiresChanged": "{action} actualmente requiere --changed",
@@ -674,12 +675,15 @@ Lee estos archivos antes de trabajar:
     "run.help.option.dryRun": "Imprime un plan de comando sin ejecutarlo",
     "run.help.option.planOnly": "Alias de --dry-run",
     "run.help.option.json": "Imprime el registro de ejecución o el plan de comando como JSON",
+    "run.help.option.wait": "Espera bloqueos activos en conflicto antes de ejecutar",
+    "run.help.option.waitTimeout": "Segundos máximos para esperar bloqueos activos. Predeterminado: 300",
     "run.help.option.allowUntrustedRoot": "Permite una ejecución desde una raíz con bloqueo de manifiesto ausente o inválido tras revisión manual",
     "run.help.exit.ok": "El comando se completo con un codigo de salida permitido",
     "run.help.exit.fail": "El comando no era válido, fue rechazado, agotó el tiempo o falló",
     "run.label.suggestedIntentSnippet": "Snippet sugerido para el contrato de comandos",
     "run.progress.started": "Ejecutando {intent} (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} sigue ejecutándose... ({seconds}s transcurridos, {percent}% del timeout)",
+    "run.progress.waitingForActiveLock": "Esperando para ejecutar {intent}; el intent activo {activeIntent} mantiene un bloqueo en conflicto (timeout: {seconds}s)",
     "run.error.missingIntent": "Falta el nombre del comando",
     "run.error.unknownIntent": "Comando desconocido: {intent}",
     "run.error.statusNotConfigured": 'El comando "{intent}" está en estado {status}; sólo se pueden ejecutar comandos configurados',
@@ -702,6 +706,8 @@ Lee estos archivos antes de trabajar:
     "run.error.maxOutputBytes": 'El comando "{intent}" tiene max_output_bytes no válido. {detail}',
     "run.error.maxOutputBytesDetail": "El límite de salida debe permanecer dentro del máximo permitido.",
     "run.error.conflictingPreviewModes": "Usa --dry-run o --plan-only, no ambos",
+    "run.error.invalidWaitTimeout": "--wait-timeout debe ser un entero positivo",
+    "run.error.waitRequiresExecution": "--wait solo se puede usar al ejecutar un comando, no con --dry-run o --plan-only",
     "run.error.untrustedRootMissing": "Se rechazó ejecutar comandos porque falta {path}. Ejecuta mf init/update para instalar el flujo, o usa --allow-untrusted-root tras revisar AGENTS.md y .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Se rechazó ejecutar comandos porque el bloqueo de manifiesto no es válido: {detail}. Restáuralo o regenéralo, o usa --allow-untrusted-root tras revisar AGENTS.md y .mustflow/config/commands.toml.",
     "run.error.timedOut": 'El comando "{intent}" agotó el tiempo después de {seconds} segundos',

package/dist/cli/i18n/fr.js

@@ -94,8 +94,9 @@ export const frMessages = {
     "api.help.action.latestEvidence": "Affiche les dernières preuves bounded de run ou verify pour les agents",
     "api.help.action.diffRisk": "Affiche un résumé compact du risque et de la vérification des fichiers modifiés",
     "api.help.action.health": "Affiche un résumé compact de santé du workspace",
+    "api.help.action.locks": "Affiche les verrous mf run actifs pour coordonner plusieurs sessions",
     "api.help.exit.ok": "Le rapport API a été inspecté et imprimé",
-    "api.error.missingAction": "Indiquez une action api : workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk ou health",
+    "api.error.missingAction": "Indiquez une action api : workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health ou locks",
     "api.error.unknownAction": "Action api inconnue : {action}",
     "api.error.actionRequiresJson": "{action} exige --json",
     "api.error.actionRequiresChanged": "{action} exige actuellement --changed",
@@ -674,12 +675,15 @@ Lisez ces fichiers avant de travailler :
     "run.help.option.dryRun": "Imprime un plan de commande sans l'exécuter",
     "run.help.option.planOnly": "Alias de --dry-run",
     "run.help.option.json": "Imprime l'enregistrement d'exécution ou le plan de commande en JSON",
+    "run.help.option.wait": "Attend les verrous actifs en conflit avant d'exécuter",
+    "run.help.option.waitTimeout": "Nombre maximal de secondes d'attente des verrous actifs. Par défaut : 300",
     "run.help.option.allowUntrustedRoot": "Autorise une seule exécution depuis une racine sans verrou de manifeste valide après revue manuelle",
     "run.help.exit.ok": "La commande s'est terminée avec un code de sortie autorisé",
     "run.help.exit.fail": "La commande était non valide, refusée, expirée ou a échoué",
     "run.label.suggestedIntentSnippet": "Extrait suggéré de contrat de commande",
     "run.progress.started": "Exécution de {intent} (timeout : {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} est toujours en cours... ({seconds}s écoulées, {percent}% du timeout)",
+    "run.progress.waitingForActiveLock": "Attente avant d'exécuter {intent} ; l'intention active {activeIntent} détient un verrou en conflit (timeout : {seconds}s)",
     "run.error.missingIntent": "Nom de commande manquant",
     "run.error.unknownIntent": "Commande inconnue : {intent}",
     "run.error.statusNotConfigured": 'La commande "{intent}" est {status} ; seules les commandes configurées peuvent être exécutées',
@@ -702,6 +706,8 @@ Lisez ces fichiers avant de travailler :
     "run.error.maxOutputBytes": 'La commande "{intent}" a une valeur max_output_bytes non valide. {detail}',
     "run.error.maxOutputBytesDetail": "La limite de sortie doit rester dans le maximum autorisé.",
     "run.error.conflictingPreviewModes": "Utilisez --dry-run ou --plan-only, pas les deux",
+    "run.error.invalidWaitTimeout": "--wait-timeout doit être un entier positif",
+    "run.error.waitRequiresExecution": "--wait ne peut être utilisé que lors de l'exécution d'une commande, pas avec --dry-run ou --plan-only",
     "run.error.untrustedRootMissing": "Exécution refusée car {path} est absent. Lancez mf init/update pour installer le workflow, ou ajoutez --allow-untrusted-root après avoir relu AGENTS.md et .mustflow/config/commands.toml.",
     "run.error.untrustedRootInvalid": "Exécution refusée car le verrou de manifeste est invalide : {detail}. Restaurez-le ou régénérez-le, ou ajoutez --allow-untrusted-root après avoir relu AGENTS.md et .mustflow/config/commands.toml.",
     "run.error.timedOut": 'La commande "{intent}" a expiré après {seconds} secondes',

package/dist/cli/i18n/hi.js

@@ -94,8 +94,9 @@ export const hiMessages = {
     "api.help.action.latestEvidence": "agents के लिए bounded latest run या verify evidence प्रिंट करें",
     "api.help.action.diffRisk": "बदली गई files के लिए compact risk और verification summary प्रिंट करें",
     "api.help.action.health": "workspace health की compact summary प्रिंट करें",
+    "api.help.action.locks": "multi-session coordination के लिए active mf run locks प्रिंट करें",
     "api.help.exit.ok": "API रिपोर्ट जाँची और प्रिंट की गई",
-    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, या health",
+    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health, या locks",
     "api.error.unknownAction": "अज्ञात api action: {action}",
     "api.error.actionRequiresJson": "{action} के लिए --json चाहिए",
     "api.error.actionRequiresChanged": "{action} को अभी --changed चाहिए",
@@ -674,12 +675,15 @@ export const hiMessages = {
     "run.help.option.dryRun": "कमांड चलाए बिना उसका plan प्रिंट करें",
     "run.help.option.planOnly": "--dry-run का alias",
     "run.help.option.json": "Run record या command plan को JSON के रूप में प्रिंट करें",
+    "run.help.option.wait": "चलाने से पहले conflicting active run locks के लिए wait करें",
+    "run.help.option.waitTimeout": "active run locks के लिए wait करने की maximum seconds. Default: 300",
     "run.help.option.allowUntrustedRoot": "Manual review के बाद missing या invalid manifest lock वाली root से एक execution allow करें",
     "run.help.exit.ok": "कमांड अनुमत exit code के साथ पूरी हुई",
     "run.help.exit.fail": "कमांड अमान्य थी, अस्वीकार हुई, timed out हुई या विफल हुई",
     "run.label.suggestedIntentSnippet": "Suggested command contract snippet",
     "run.progress.started": "{intent} चल रहा है (timeout: {seconds}s)...",
     "run.progress.timeoutWarning": "{intent} अभी भी चल रहा है... ({seconds}s बीते, timeout का {percent}%)",
+    "run.progress.waitingForActiveLock": "{intent} चलाने के लिए wait कर रहे हैं; active intent {activeIntent} conflicting lock रखता है (timeout: {seconds}s)",
     "run.error.missingIntent": "कमांड नाम नहीं दिया गया",
     "run.error.unknownIntent": "अज्ञात कमांड: {intent}",
     "run.error.statusNotConfigured": 'कमांड "{intent}" {status} है; केवल configured कमांड चलाई जा सकती हैं',
@@ -702,6 +706,8 @@ export const hiMessages = {
     "run.error.maxOutputBytes": 'कमांड "{intent}" में max_output_bytes अमान्य है। {detail}',
     "run.error.maxOutputBytesDetail": "Output limit अनुमत maximum के अंदर रहनी चाहिए।",
     "run.error.conflictingPreviewModes": "--dry-run या --plan-only में से एक इस्तेमाल करें, दोनों नहीं",
+    "run.error.invalidWaitTimeout": "--wait-timeout positive integer होना चाहिए",
+    "run.error.waitRequiresExecution": "--wait केवल command execute करते समय इस्तेमाल हो सकता है, --dry-run या --plan-only के साथ नहीं",
     "run.error.untrustedRootMissing": "{path} missing है, इसलिए commands execute करने से मना किया गया। Workflow install करने के लिए mf init/update चलाएँ, या AGENTS.md और .mustflow/config/commands.toml review करने के बाद --allow-untrusted-root पास करें।",
     "run.error.untrustedRootInvalid": "Manifest lock invalid है, इसलिए commands execute करने से मना किया गया: {detail}. इसे restore या regenerate करें, या AGENTS.md और .mustflow/config/commands.toml review करने के बाद --allow-untrusted-root पास करें।",
     "run.error.timedOut": 'कमांड "{intent}" {seconds} सेकंड बाद time out हुई',

package/dist/cli/i18n/ko.js

@@ -94,8 +94,9 @@ export const koMessages = {
     "api.help.action.latestEvidence": "에이전트용 bounded 최신 run 또는 verify evidence를 출력합니다",
     "api.help.action.diffRisk": "변경 파일 risk와 verification 요약을 작게 출력합니다",
     "api.help.action.health": "workspace health 요약을 작게 출력합니다",
+    "api.help.action.locks": "여러 세션 조율용 활성 mf run 잠금을 출력합니다",
     "api.help.exit.ok": "API 보고서를 확인하고 출력했습니다",
-    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk 또는 health",
+    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, health 또는 locks",
     "api.error.unknownAction": "알 수 없는 api 작업: {action}",
     "api.error.actionRequiresJson": "{action}에는 --json이 필요합니다",
     "api.error.actionRequiresChanged": "{action}은 현재 --changed가 필요합니다",
@@ -674,12 +675,15 @@ export const koMessages = {
     "run.help.option.dryRun": "실행하지 않고 명령 계획을 출력합니다",
     "run.help.option.planOnly": "--dry-run과 같은 동작입니다",
     "run.help.option.json": "실행 결과 또는 명령 계획을 JSON으로 출력합니다",
+    "run.help.option.wait": "충돌하는 활성 실행 잠금이 풀릴 때까지 기다린 뒤 실행합니다",
+    "run.help.option.waitTimeout": "활성 실행 잠금을 기다릴 최대 초입니다. 기본값: 300",
     "run.help.option.allowUntrustedRoot": "잠금 파일이 없거나 올바르지 않은 루트에서 수동 검토 후 이번 실행만 허용합니다",
     "run.help.exit.ok": "명령이 허용된 종료 코드로 완료되었습니다",
     "run.help.exit.fail": "명령이 잘못되었거나, 거부되었거나, 시간 초과되었거나, 실패했습니다",
     "run.label.suggestedIntentSnippet": "제안 명령 계약 조각",
     "run.progress.started": "{intent} 실행 중(timeout: {seconds}초)...",
     "run.progress.timeoutWarning": "{intent} 계속 실행 중... ({seconds}초 경과, timeout의 {percent}%)",
+    "run.progress.waitingForActiveLock": "{intent} 실행 대기 중; 활성 intent {activeIntent}가 충돌하는 잠금을 보유 중입니다(timeout: {seconds}초)",
     "run.error.missingIntent": "명령 이름이 없습니다",
     "run.error.unknownIntent": "알 수 없는 명령: {intent}",
     "run.error.statusNotConfigured": '명령 "{intent}"의 상태는 {status}입니다. 설정된 상태(configured)인 명령만 실행할 수 있습니다',
@@ -702,6 +706,8 @@ export const koMessages = {
     "run.error.maxOutputBytes": '명령 "{intent}"의 max_output_bytes 값이 올바르지 않습니다. {detail}',
     "run.error.maxOutputBytesDetail": "출력 상한은 허용된 최댓값 안에 있어야 합니다.",
     "run.error.conflictingPreviewModes": "--dry-run과 --plan-only 중 하나만 사용하세요",
+    "run.error.invalidWaitTimeout": "--wait-timeout은 양의 정수여야 합니다",
+    "run.error.waitRequiresExecution": "--wait는 --dry-run 또는 --plan-only가 아닌 실제 명령 실행에만 사용할 수 있습니다",
     "run.error.untrustedRootMissing": "{path}이 없어 명령 실행을 거부했습니다. mf init/update로 워크플로우를 설치하거나, AGENTS.md와 .mustflow/config/commands.toml을 검토한 뒤 --allow-untrusted-root를 붙이세요.",
     "run.error.untrustedRootInvalid": "잠금 파일이 올바르지 않아 명령 실행을 거부했습니다: {detail}. 파일을 복구하거나 다시 생성하거나, AGENTS.md와 .mustflow/config/commands.toml을 검토한 뒤 --allow-untrusted-root를 붙이세요.",
     "run.error.timedOut": '명령 "{intent}"가 {seconds}초 뒤 시간 초과되었습니다',

package/dist/cli/i18n/zh.js

@@ -94,8 +94,9 @@ export const zhMessages = {
     "api.help.action.latestEvidence": "为代理输出 bounded 最新 run 或 verify evidence",
     "api.help.action.diffRisk": "为已变更文件输出紧凑 risk 和 verification 摘要",
     "api.help.action.health": "输出紧凑 workspace health 摘要",
+    "api.help.action.locks": "输出用于多会话协调的活动 mf run 锁",
     "api.help.exit.ok": "已检查并输出 API 报告",
-    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk 或 health",
+    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk、health 或 locks",
     "api.error.unknownAction": "未知 api 操作：{action}",
     "api.error.actionRequiresJson": "{action} 需要 --json",
     "api.error.actionRequiresChanged": "{action} 当前需要 --changed",
@@ -674,12 +675,15 @@ export const zhMessages = {
     "run.help.option.dryRun": "输出命令计划但不执行",
     "run.help.option.planOnly": "--dry-run 的别名",
     "run.help.option.json": "将运行记录或命令计划输出为 JSON",
+    "run.help.option.wait": "执行前等待冲突的活动运行锁释放",
+    "run.help.option.waitTimeout": "等待活动运行锁的最大秒数。默认值：300",
     "run.help.option.allowUntrustedRoot": "人工复核后，允许从缺失或无效清单锁的根目录执行一次命令",
     "run.help.exit.ok": "命令已以允许的退出码完成",
     "run.help.exit.fail": "命令无效、被拒绝、超时或失败",
     "run.label.suggestedIntentSnippet": "建议的命令契约片段",
     "run.progress.started": "正在运行 {intent}（超时：{seconds} 秒）...",
     "run.progress.timeoutWarning": "{intent} 仍在运行...（已用 {seconds} 秒，达到超时的 {percent}%）",
+    "run.progress.waitingForActiveLock": "正在等待运行 {intent}；活动 intent {activeIntent} 持有冲突锁（超时：{seconds} 秒）",
     "run.error.missingIntent": "缺少命令名称",
     "run.error.unknownIntent": "未知命令：{intent}",
     "run.error.statusNotConfigured": '命令 "{intent}" 的状态为 {status}；只能运行已配置的命令',
@@ -702,6 +706,8 @@ export const zhMessages = {
     "run.error.maxOutputBytes": '命令 "{intent}" 的 max_output_bytes 无效。{detail}',
     "run.error.maxOutputBytesDetail": "输出限制必须保持在允许的最大值内。",
     "run.error.conflictingPreviewModes": "只能使用 --dry-run 或 --plan-only，不能同时使用",
+    "run.error.invalidWaitTimeout": "--wait-timeout 必须是正整数",
+    "run.error.waitRequiresExecution": "--wait 只能用于实际执行命令，不能与 --dry-run 或 --plan-only 一起使用",
     "run.error.untrustedRootMissing": "已拒绝执行命令，因为缺少 {path}。请运行 mf init/update 安装工作流，或在检查 AGENTS.md 和 .mustflow/config/commands.toml 后传入 --allow-untrusted-root。",
     "run.error.untrustedRootInvalid": "已拒绝执行命令，因为清单锁无效：{detail}。请恢复或重新生成它，或在检查 AGENTS.md 和 .mustflow/config/commands.toml 后传入 --allow-untrusted-root。",
     "run.error.timedOut": '命令 "{intent}" 在 {seconds} 秒后超时',

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

@@ -268,6 +268,16 @@ export function inspectActiveRunLocks(projectRoot, contract, intentName) {
         staleRecords,
     };
 }
+export function listActiveRunLocks(projectRoot) {
+    const records = readActiveRecords(projectRoot);
+    const staleRecords = records.map(staleRecordFor).filter((record) => record !== null);
+    const activeRecords = records.filter((record) => !staleRecords.some((stale) => stale.runId === record.run_id));
+    return {
+        records,
+        activeRecords,
+        staleRecords,
+    };
+}
 export function acquireActiveRunLock(projectRoot, contract, intentName, options = {}) {
     const effects = normalizeCommandEffects(projectRoot, contract, intentName);
     if (effects.length === 0) {

package/dist/core/public-json-contracts.js

@@ -71,6 +71,14 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         documented: true,
         installedCommand: ['mf', 'api', 'health', '--json'],
     },
+    {
+        id: 'locks',
+        schemaFile: 'locks.schema.json',
+        producer: 'mf api locks --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'api', 'locks', '--json'],
+    },
     {
         id: 'run-receipt',
         schemaFile: 'run-receipt.schema.json',

package/package.json

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

package/schemas/README.md

@@ -14,6 +14,7 @@ Current schemas:
 - `latest-evidence.schema.json`: output of `mf api latest-evidence --json`
 - `diff-risk.schema.json`: output of `mf api diff-risk --changed --json`
 - `health.schema.json`: output of `mf api health --json`
+- `locks.schema.json`: output of `mf api locks --json`
 - `run-receipt.schema.json`: output of `mf run <intent> --json` and `.mustflow/state/runs/latest.json`,
   including bounded declared-write drift metadata, a safe latest-run performance summary, and optional
   structured phase timings and selection summaries

package/schemas/diff-risk.schema.json

@@ -37,6 +37,7 @@
     "update_policies": { "$ref": "#/$defs/stringArray" },
     "drift_checks": { "$ref": "#/$defs/stringArray" },
     "required_verification": { "$ref": "#/$defs/stringArray" },
+    "residual_corrections": { "$ref": "#/$defs/residualCorrections" },
     "gap_count": { "type": "integer", "minimum": 0 },
     "gaps": {
       "type": "array",
@@ -69,6 +70,80 @@
         "surfaces": { "$ref": "#/$defs/stringArray" },
         "detail": { "type": "string" }
       }
+    },
+    "residualCorrections": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "status",
+        "mode",
+        "grants_command_authority",
+        "applies_to_current_plan",
+        "selected_intent_additions",
+        "suggested_intent_additions",
+        "recommended_commands",
+        "signals",
+        "policy",
+        "issues"
+      ],
+      "properties": {
+        "status": { "enum": ["not_enough_evidence", "available", "unavailable"] },
+        "mode": { "const": "read_only" },
+        "grants_command_authority": { "const": false },
+        "applies_to_current_plan": { "type": "boolean" },
+        "selected_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "suggested_intent_additions": { "$ref": "#/$defs/stringArray" },
+        "recommended_commands": { "$ref": "#/$defs/stringArray" },
+        "signals": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/residualSignal" }
+        },
+        "policy": { "$ref": "#/$defs/residualPolicy" },
+        "issues": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "residualPolicy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "single_observation_changes_plan",
+        "minimum_repeated_samples_for_plan_change",
+        "automatic_intent_additions_enabled"
+      ],
+      "properties": {
+        "single_observation_changes_plan": { "const": false },
+        "minimum_repeated_samples_for_plan_change": { "const": 2 },
+        "automatic_intent_additions_enabled": { "const": false }
+      }
+    },
+    "residualSignal": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "kind",
+        "confidence",
+        "evidence_count",
+        "source",
+        "verification_plan_id",
+        "affected_reasons",
+        "affected_intents",
+        "detail",
+        "recommendation"
+      ],
+      "properties": {
+        "kind": { "enum": ["latest_unresolved_plan", "repeated_failure", "remaining_risk"] },
+        "confidence": { "enum": ["low", "medium", "high"] },
+        "evidence_count": { "type": "integer", "minimum": 1 },
+        "source": { "const": "latest-evidence" },
+        "verification_plan_id": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "affected_reasons": { "$ref": "#/$defs/stringArray" },
+        "affected_intents": { "$ref": "#/$defs/stringArray" },
+        "detail": { "type": "string" },
+        "recommendation": { "enum": ["provide_new_evidence", "review_remaining_risk"] }
+      }
     }
   }
 }

package/schemas/locks.schema.json

@@ -0,0 +1,102 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://mustflow.github.io/schemas/locks.schema.json",
+  "title": "mustflow active locks API report",
+  "type": "object",
+  "additionalProperties": false,
+  "required": [
+    "schema_version",
+    "command",
+    "mustflow_root",
+    "status",
+    "lock_root",
+    "active_count",
+    "stale_count",
+    "active_locks",
+    "stale_locks",
+    "policy",
+    "recommended_commands",
+    "issues"
+  ],
+  "properties": {
+    "schema_version": { "const": "1" },
+    "command": { "const": "api locks" },
+    "mustflow_root": { "type": "string" },
+    "status": { "enum": ["clear", "active", "stale", "unavailable"] },
+    "lock_root": { "const": ".mustflow/state/locks" },
+    "active_count": { "type": "integer", "minimum": 0 },
+    "stale_count": { "type": "integer", "minimum": 0 },
+    "active_locks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/activeLock" }
+    },
+    "stale_locks": {
+      "type": "array",
+      "items": { "$ref": "#/$defs/staleLock" }
+    },
+    "policy": { "$ref": "#/$defs/policy" },
+    "recommended_commands": { "$ref": "#/$defs/stringArray" },
+    "issues": { "$ref": "#/$defs/stringArray" }
+  },
+  "$defs": {
+    "stringArray": {
+      "type": "array",
+      "items": { "type": "string" }
+    },
+    "activeLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id", "intent", "pid", "started_at", "command_hash", "effects", "writes"],
+      "properties": {
+        "run_id": { "type": "string" },
+        "intent": { "type": "string" },
+        "pid": { "type": "integer" },
+        "started_at": { "type": "string" },
+        "command_hash": {
+          "type": ["string", "null"],
+          "pattern": "^sha256:[0-9a-f]{64}$"
+        },
+        "effects": {
+          "type": "array",
+          "items": { "$ref": "#/$defs/effect" }
+        },
+        "writes": { "$ref": "#/$defs/stringArray" }
+      }
+    },
+    "effect": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "access", "mode", "path", "lock", "concurrency"],
+      "properties": {
+        "source": { "type": "string" },
+        "access": { "type": "string" },
+        "mode": { "type": "string" },
+        "path": { "type": ["string", "null"] },
+        "lock": { "type": "string" },
+        "concurrency": { "type": "string" }
+      }
+    },
+    "staleLock": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["run_id", "intent", "pid", "reason"],
+      "properties": {
+        "run_id": { "type": "string" },
+        "intent": { "type": "string" },
+        "pid": { "type": "integer" },
+        "reason": { "type": "string" }
+      }
+    },
+    "policy": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["source", "conflict_model", "direct_commands_bypass_locks", "wait_entrypoint"],
+      "properties": {
+        "source": { "const": "active-run-locks" },
+        "conflict_model": { "const": "command_effects_and_writes" },
+        "direct_commands_bypass_locks": { "const": true },
+        "wait_entrypoint": { "const": "mf run <intent> --wait" }
+      }
+    }
+  }
+}

package/templates/default/manifest.toml

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