mustflow 2.22.46 → 2.22.49

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/commands/verify.js

@@ -6,6 +6,7 @@ import { readUtf8FileInsideWithoutSymlinks, writeJsonFileInsideWithoutSymlinks }
 import { createVerifyCompletionVerdict, } from '../../core/completion-verdict.js';
 import { createExternalEvidenceRisks, } from '../../core/external-evidence.js';
 import { createRepeatedFailureRisks, createVerificationFailureFingerprint, updateRepeatedFailureState, } from '../../core/repeated-failure.js';
+import { createVerificationPlanId } from '../../core/verification-plan-id.js';
 import { countReproEvidenceVerdictEffects, createReproEvidenceRisks, } from '../../core/repro-evidence.js';
 import { createVerifyEvidenceModel } from '../../core/verification-evidence.js';
 import { createScopeDiffRisks } from '../../core/scope-risk.js';
@@ -24,6 +25,9 @@ import { readLocalCommandEffectGraphs, readLocalPathSurfaces, readLocalSourceAnc
 import { resolveMustflowRoot } from '../lib/project-root.js';
 export { planErrorMessageKey, readInputFromClassificationReport } from './verify/input.js';
 const VERIFY_SCHEMA_VERSION = '1';
+function hashTextSha256(content) {
+    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
+}
 function createBufferedOutput() {
     const stdout = [];
     const stderr = [];
@@ -569,49 +573,6 @@ function readPreviousVerifyLatestSummary(projectRoot) {
         return null;
     }
 }
-function hashTextSha256(content) {
-    return `sha256:${createHash('sha256').update(content).digest('hex')}`;
-}
-function stableJson(value) {
-    if (Array.isArray(value)) {
-        return `[${value.map((entry) => stableJson(entry)).join(',')}]`;
-    }
-    if (value && typeof value === 'object') {
-        const record = value;
-        return `{${Object.keys(record)
-            .sort((left, right) => left.localeCompare(right))
-            .map((key) => `${JSON.stringify(key)}:${stableJson(record[key])}`)
-            .join(',')}}`;
-    }
-    return JSON.stringify(value) ?? 'null';
-}
-function getCandidateIntentNames(report) {
-    return [...new Set(report.candidates.map((candidate) => candidate.intent).filter((intent) => Boolean(intent)))]
-        .sort((left, right) => left.localeCompare(right));
-}
-function createVerificationPlanId(report, contract) {
-    const relatedIntents = Object.fromEntries(getCandidateIntentNames(report).map((intent) => [intent, contract.intents[intent] ?? null]));
-    const fingerprintSource = {
-        schema_version: '1',
-        algorithm: 'mustflow.verify_plan_id.v1',
-        report: {
-            source: report.source,
-            files: report.files,
-            classification_summary: report.classification_summary,
-            requirements: report.requirements,
-            candidates: report.candidates,
-            gaps: report.gaps,
-            schedule: report.schedule,
-            test_selection: report.test_selection,
-        },
-        command_contract: {
-            defaults: contract.defaults,
-            resources: contract.resources,
-            intents: relatedIntents,
-        },
-    };
-    return hashTextSha256(stableJson(fingerprintSource));
-}
 function toParallelismReport(settings) {
     return {
         requested: settings.requested,

package/dist/cli/i18n/en.js

@@ -24,6 +24,7 @@ export const enMessages = {
     "value.missing": "missing",
     "value.passed": "passed",
     "value.failed": "failed",
+    "command.api.summary": "Print stable machine-readable API reports for agents",
     "command.adapters.summary": "Inspect host adapter compatibility without generating adapter files",
     "command.init.summary": "Copy the default mustflow agent workflow",
     "command.check.summary": "Validate mustflow files",
@@ -86,6 +87,19 @@ export const enMessages = {
     "context.help.option.cacheProfile": "Print a prompt-cache profile: stable, task, volatile, or all",
     "context.help.exit.ok": "Context was inspected and printed",
     "context.title": "mustflow context",
+    "api.help.summary": "Print stable machine-readable API reports for the current mustflow root.",
+    "api.help.action.workspaceSummary": "Print a read-only workspace briefing for coding agents",
+    "api.help.action.commandCatalog": "Print command intent availability without exposing raw command execution strings",
+    "api.help.action.verificationPlan": "Print a read-only verification plan for changed files",
+    "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, health, or locks",
+    "api.error.unknownAction": "Unknown api action: {action}",
+    "api.error.actionRequiresJson": "{action} requires --json",
+    "api.error.actionRequiresChanged": "{action} currently requires --changed",
     "label.installed": "Installed",
     "label.mustflowRoot": "mustflow root",
     "label.commandContract": "Command specification",
@@ -661,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',
@@ -689,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

@@ -24,6 +24,7 @@ export const esMessages = {
     "value.missing": "faltante",
     "value.passed": "superado",
     "value.failed": "fallido",
+    "command.api.summary": "Imprime informes API estables legibles por máquinas para agentes",
     "command.adapters.summary": "Inspecciona compatibilidad de adaptadores sin generar archivos",
     "command.init.summary": "Copia el flujo de trabajo de agente mustflow predeterminado",
     "command.check.summary": "Valida los archivos mustflow",
@@ -86,6 +87,19 @@ export const esMessages = {
     "context.help.option.cacheProfile": "Imprime un perfil de caché de prompt: stable, task, volatile o all",
     "context.help.exit.ok": "El contexto se inspeccionó e imprimió",
     "context.title": "contexto mustflow",
+    "api.help.summary": "Imprime informes API estables legibles por máquinas para la raíz mustflow actual.",
+    "api.help.action.workspaceSummary": "Imprime un briefing de workspace de solo lectura para agentes de código",
+    "api.help.action.commandCatalog": "Imprime disponibilidad de intents de comandos sin exponer cadenas de ejecución sin procesar",
+    "api.help.action.verificationPlan": "Imprime un verification plan de solo lectura para archivos cambiados",
+    "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, health o locks",
+    "api.error.unknownAction": "Acción api desconocida: {action}",
+    "api.error.actionRequiresJson": "{action} requiere --json",
+    "api.error.actionRequiresChanged": "{action} actualmente requiere --changed",
     "label.installed": "Instalado",
     "label.mustflowRoot": "raíz mustflow",
     "label.commandContract": "Especificación de comandos",
@@ -661,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',
@@ -689,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

@@ -24,6 +24,7 @@ export const frMessages = {
     "value.missing": "manquant",
     "value.passed": "réussi",
     "value.failed": "échoué",
+    "command.api.summary": "Imprime des rapports API stables lisibles par machine pour les agents",
     "command.adapters.summary": "Inspecte la compatibilité des adaptateurs sans générer de fichiers",
     "command.init.summary": "Copie le flux de travail d'agent mustflow par défaut",
     "command.check.summary": "Valide les fichiers mustflow",
@@ -86,6 +87,19 @@ export const frMessages = {
     "context.help.option.cacheProfile": "Imprime un profil de cache de prompt : stable, task, volatile ou all",
     "context.help.exit.ok": "Le contexte a été inspecté et imprimé",
     "context.title": "contexte mustflow",
+    "api.help.summary": "Imprime des rapports API stables lisibles par machine pour la racine mustflow actuelle.",
+    "api.help.action.workspaceSummary": "Imprime un briefing de workspace en lecture seule pour les agents de code",
+    "api.help.action.commandCatalog": "Affiche la disponibilité des intents de commande sans exposer les chaînes d'exécution brutes",
+    "api.help.action.verificationPlan": "Affiche un verification plan en lecture seule pour les fichiers modifiés",
+    "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, health ou locks",
+    "api.error.unknownAction": "Action api inconnue : {action}",
+    "api.error.actionRequiresJson": "{action} exige --json",
+    "api.error.actionRequiresChanged": "{action} exige actuellement --changed",
     "label.installed": "Installé",
     "label.mustflowRoot": "racine mustflow",
     "label.commandContract": "Spécification des commandes",
@@ -661,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',
@@ -689,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

@@ -24,6 +24,7 @@ export const hiMessages = {
     "value.missing": "गुम",
     "value.passed": "पास",
     "value.failed": "फेल",
+    "command.api.summary": "एजेंटों के लिए स्थिर machine-readable API रिपोर्ट प्रिंट करें",
     "command.adapters.summary": "एडाप्टर फ़ाइलें बनाए बिना होस्ट संगतता जाँचें",
     "command.init.summary": "डिफ़ॉल्ट mustflow एजेंट वर्कफ़्लो कॉपी करें",
     "command.check.summary": "mustflow फ़ाइलों की जाँच करें",
@@ -86,6 +87,19 @@ export const hiMessages = {
     "context.help.option.cacheProfile": "prompt cache profile प्रिंट करें: stable, task, volatile, या all",
     "context.help.exit.ok": "संदर्भ जाँचा और प्रिंट किया गया",
     "context.title": "mustflow संदर्भ",
+    "api.help.summary": "वर्तमान mustflow रूट के लिए स्थिर machine-readable API रिपोर्ट प्रिंट करें।",
+    "api.help.action.workspaceSummary": "कोडिंग एजेंटों के लिए read-only workspace briefing प्रिंट करें",
+    "api.help.action.commandCatalog": "raw command execution strings दिखाए बिना command intent availability प्रिंट करें",
+    "api.help.action.verificationPlan": "बदली गई फ़ाइलों के लिए read-only verification plan प्रिंट करें",
+    "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, या locks",
+    "api.error.unknownAction": "अज्ञात api action: {action}",
+    "api.error.actionRequiresJson": "{action} के लिए --json चाहिए",
+    "api.error.actionRequiresChanged": "{action} को अभी --changed चाहिए",
     "label.installed": "इंस्टॉल किया गया",
     "label.mustflowRoot": "mustflow रूट",
     "label.commandContract": "कमांड विनिर्देश",
@@ -661,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 कमांड चलाई जा सकती हैं',
@@ -689,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

@@ -24,6 +24,7 @@ export const koMessages = {
     "value.missing": "없음",
     "value.passed": "통과",
     "value.failed": "실패",
+    "command.api.summary": "에이전트용 안정적 JSON API 보고서를 출력합니다",
     "command.adapters.summary": "어댑터 파일을 만들지 않고 호스트 호환성을 확인합니다",
     "command.init.summary": "기본 mustflow 에이전트 워크플로우를 복사합니다",
     "command.check.summary": "mustflow 파일을 검사합니다",
@@ -86,6 +87,19 @@ export const koMessages = {
     "context.help.option.cacheProfile": "프롬프트 캐시 프로필을 출력합니다: stable, task, volatile, all",
     "context.help.exit.ok": "맥락을 확인하고 출력했습니다",
     "context.title": "mustflow 맥락",
+    "api.help.summary": "현재 mustflow 루트의 안정적 JSON API 보고서를 출력합니다.",
+    "api.help.action.workspaceSummary": "코딩 에이전트용 읽기 전용 workspace briefing을 출력합니다",
+    "api.help.action.commandCatalog": "원본 실행 문자열을 노출하지 않고 command intent 실행 가능성을 출력합니다",
+    "api.help.action.verificationPlan": "변경 파일에 대한 읽기 전용 verification plan을 출력합니다",
+    "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 또는 locks",
+    "api.error.unknownAction": "알 수 없는 api 작업: {action}",
+    "api.error.actionRequiresJson": "{action}에는 --json이 필요합니다",
+    "api.error.actionRequiresChanged": "{action}은 현재 --changed가 필요합니다",
     "label.installed": "설치됨",
     "label.mustflowRoot": "mustflow 루트",
     "label.commandContract": "명령 계약",
@@ -661,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)인 명령만 실행할 수 있습니다',
@@ -689,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

@@ -24,6 +24,7 @@ export const zhMessages = {
     "value.missing": "缺失",
     "value.passed": "通过",
     "value.failed": "失败",
+    "command.api.summary": "为代理输出稳定的机器可读 API 报告",
     "command.adapters.summary": "不生成适配器文件，检查宿主兼容性",
     "command.init.summary": "复制默认的 mustflow 代理工作流",
     "command.check.summary": "验证 mustflow 文件",
@@ -86,6 +87,19 @@ export const zhMessages = {
     "context.help.option.cacheProfile": "输出提示缓存配置文件：stable、task、volatile 或 all",
     "context.help.exit.ok": "已检查并输出上下文",
     "context.title": "mustflow 上下文",
+    "api.help.summary": "为当前 mustflow 根目录输出稳定的机器可读 API 报告。",
+    "api.help.action.workspaceSummary": "为代码代理输出只读 workspace 简报",
+    "api.help.action.commandCatalog": "输出命令 intent 可用性，但不暴露原始执行字符串",
+    "api.help.action.verificationPlan": "为已变更文件输出只读 verification plan",
+    "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 或 locks",
+    "api.error.unknownAction": "未知 api 操作：{action}",
+    "api.error.actionRequiresJson": "{action} 需要 --json",
+    "api.error.actionRequiresChanged": "{action} 当前需要 --changed",
     "label.installed": "已安装",
     "label.mustflowRoot": "mustflow 根目录",
     "label.commandContract": "命令规范",
@@ -661,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}；只能运行已配置的命令',
@@ -689,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/cli/index.js

@@ -23,6 +23,7 @@ function getTopLevelHelp(lang) {
         ],
         examples: [
             'mf --lang ko help',
+            'mf api workspace-summary --json',
             'mf adapters status --json',
             'mf init --dry-run',
             'mf doctor --json',

package/dist/cli/lib/command-registry.js

@@ -1,4 +1,10 @@
 export const COMMAND_DEFINITIONS = [
+    {
+        id: 'api',
+        usage: 'mf api',
+        summaryKey: 'command.api.summary',
+        loadRunner: async () => (await import('../commands/api.js')).runApi,
+    },
     {
         id: 'adapters',
         usage: 'mf adapters',

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) {