mustflow 2.22.17 → 2.22.47

package/dist/cli/commands/dashboard.js

@@ -1,4 +1,4 @@
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, timingSafeEqual } from 'node:crypto';
 import { existsSync, readFileSync, statSync } from 'node:fs';
 import http from 'node:http';
 import path from 'node:path';
@@ -306,8 +306,36 @@ function sendText(response, statusCode, value) {
 function sendBadRequest(response) {
     sendText(response, 400, 'Bad request');
 }
+function isDashboardBadRequestError(error, message) {
+    return (error instanceof SyntaxError ||
+        message === 'Request body is too large.' ||
+        message === 'Invalid review status.' ||
+        message === 'Request body must be a JSON object.' ||
+        message === 'Request body must include an updates array.' ||
+        message === 'Each update must be a JSON object.' ||
+        message === 'Each update must include an id.' ||
+        message === 'Bulk documentation review updates require a separate confirmed flow.' ||
+        message.startsWith('Unknown dashboard preference: ') ||
+        message.endsWith(' is locked in the dashboard.') ||
+        message.endsWith(' is required.') ||
+        message.endsWith(' must be a boolean.') ||
+        message.endsWith(' must be an integer.') ||
+        message.endsWith(' must be a string.') ||
+        message.endsWith(' must not be empty.') ||
+        /^.+ must be at (?:least|most) \d+\.$/u.test(message) ||
+        /^.+ must be one of: .+\.$/u.test(message) ||
+        message.startsWith('status must be ') ||
+        message.startsWith('reviewerKind must be '));
+}
 function isAuthorized(request, token) {
-    return request.headers['x-mustflow-dashboard-token'] === token;
+    const rawToken = request.headers['x-mustflow-dashboard-token'];
+    const candidate = Array.isArray(rawToken) ? rawToken[0] : rawToken;
+    if (typeof candidate !== 'string') {
+        return false;
+    }
+    const expected = Buffer.from(token);
+    const actual = Buffer.from(candidate);
+    return expected.byteLength === actual.byteLength && timingSafeEqual(actual, expected);
 }
 async function readRequestJson(request) {
     const chunks = [];
@@ -841,19 +869,38 @@ export async function runDashboard(args, reporter, lang = 'en') {
             }
             sendText(response, 404, 'Not found');
         }
-        catch {
-            sendBadRequest(response);
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            if (isDashboardBadRequestError(error, message)) {
+                sendBadRequest(response);
+                return;
+            }
+            reporter.stderr(message);
+            sendText(response, 500, 'Internal server error');
         }
     });
+    server.headersTimeout = 10_000;
+    server.requestTimeout = 30_000;
+    server.keepAliveTimeout = 1_000;
     return new Promise((resolve) => {
         let resolved = false;
+        const sockets = new Set();
         const close = () => {
             if (resolved) {
                 return;
             }
             resolved = true;
             server.close(() => resolve(0));
+            for (const socket of sockets) {
+                socket.destroy();
+            }
         };
+        server.on('connection', (socket) => {
+            sockets.add(socket);
+            socket.on('close', () => {
+                sockets.delete(socket);
+            });
+        });
         server.on('error', (error) => {
             if (!resolved) {
                 resolved = true;

package/dist/cli/commands/explain.js

@@ -1,7 +1,8 @@
-import { existsSync, readFileSync } from 'node:fs';
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { printUsageError, renderHelp } from '../lib/cli-output.js';
 import { t } from '../lib/i18n.js';
+import { MUSTFLOW_JSON_MAX_BYTES, readMustflowTextFile } from '../lib/mustflow-read.js';
 import { resolveMustflowRoot } from '../lib/project-root.js';
 import { explainAssetOptimization, explainCommandIntent, } from '../../core/command-explanation.js';
 import { readCommandContract, readMustflowConfigIfExists } from '../../core/config-loading.js';
@@ -225,7 +226,7 @@ function getLatestFailureExplainOutput(projectRoot) {
     }
     let parsed;
     try {
-        parsed = JSON.parse(readFileSync(latestPath, 'utf8'));
+        parsed = JSON.parse(readMustflowTextFile(projectRoot, LATEST_RUN_RECEIPT_RELATIVE_PATH, { maxBytes: MUSTFLOW_JSON_MAX_BYTES }));
     }
     catch {
         return {

package/dist/cli/commands/help.js

@@ -140,6 +140,5 @@ export function runHelp(args, reporter, lang = 'en') {
         return 0;
     }
     reporter.stderr(renderCliError(t(lang, 'help.error.unknownTopic', { topic }), 'mf help --help', lang));
-    reporter.stdout(getHelpHelp(lang));
     return 1;
 }

package/dist/cli/commands/run.js

@@ -117,6 +117,31 @@ function renderActiveLockConflictMessage(intentName, conflicts, lang) {
         : t(lang, 'run.error.activeLockConflictUnknown');
     return t(lang, 'run.error.activeLockConflict', { intent: intentName, detail });
 }
+function createRunProgressReporter(input) {
+    if (!input.enabled) {
+        return () => undefined;
+    }
+    input.reporter.stderr(t(input.lang, 'run.progress.started', { intent: input.intentName, seconds: input.timeoutSeconds }));
+    const timers = [];
+    for (const ratio of [0.5, 0.8]) {
+        const delayMs = Math.max(1, Math.floor(input.timeoutSeconds * 1000 * ratio));
+        const elapsedSeconds = Math.max(1, Math.round(input.timeoutSeconds * ratio));
+        const timer = setTimeout(() => {
+            input.reporter.stderr(t(input.lang, 'run.progress.timeoutWarning', {
+                intent: input.intentName,
+                seconds: elapsedSeconds,
+                percent: Math.round(ratio * 100),
+            }));
+        }, delayMs);
+        timer.unref?.();
+        timers.push(timer);
+    }
+    return () => {
+        for (const timer of timers) {
+            clearTimeout(timer);
+        }
+    };
+}
 export function getRunHelp(lang = 'en') {
     return renderHelp({
         usage: 'mf run <intent> [options]',
@@ -241,13 +266,25 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         let streamedOutput = false;
         const childStartedAtMs = performance.now();
         const startedAt = new Date();
+        const stopRunProgress = createRunProgressReporter({
+            enabled: !json && Boolean(reporter.writeStderr),
+            intentName,
+            timeoutSeconds: plan.timeoutSeconds,
+            reporter,
+            lang,
+        });
         const result = await profiler.measureAsync('child_command', async () => {
-            if (plan.commandArgv) {
+            try {
+                if (plan.commandArgv) {
+                    streamedOutput = !json;
+                    return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+                }
                 streamedOutput = !json;
-                return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+                return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
+            }
+            finally {
+                stopRunProgress();
             }
-            streamedOutput = !json;
-            return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
         });
         const childDurationMs = performance.now() - childStartedAtMs;
         const finishedAt = new Date();

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,18 @@ 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.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.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",
@@ -665,6 +678,8 @@ Read these files before working:
     "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.error.missingIntent": "Missing command name",
     "run.error.unknownIntent": "Unknown command: {intent}",
     "run.error.statusNotConfigured": 'Command "{intent}" is {status}; only configured commands can be run',

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,18 @@ 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.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.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",
@@ -665,6 +678,8 @@ Lee estos archivos antes de trabajar:
     "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.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',

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,18 @@ 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.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.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",
@@ -665,6 +678,8 @@ Lisez ces fichiers avant de travailler :
     "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.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',

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,18 @@ 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.exit.ok": "API रिपोर्ट जाँची और प्रिंट की गई",
+    "api.error.missingAction": "api action बताएँ: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk, या health",
+    "api.error.unknownAction": "अज्ञात api action: {action}",
+    "api.error.actionRequiresJson": "{action} के लिए --json चाहिए",
+    "api.error.actionRequiresChanged": "{action} को अभी --changed चाहिए",
     "label.installed": "इंस्टॉल किया गया",
     "label.mustflowRoot": "mustflow रूट",
     "label.commandContract": "कमांड विनिर्देश",
@@ -665,6 +678,8 @@ export const hiMessages = {
     "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.error.missingIntent": "कमांड नाम नहीं दिया गया",
     "run.error.unknownIntent": "अज्ञात कमांड: {intent}",
     "run.error.statusNotConfigured": 'कमांड "{intent}" {status} है; केवल configured कमांड चलाई जा सकती हैं',

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,18 @@ 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.exit.ok": "API 보고서를 확인하고 출력했습니다",
+    "api.error.missingAction": "api 작업을 지정하세요: workspace-summary, command-catalog, verification-plan, latest-evidence, diff-risk 또는 health",
+    "api.error.unknownAction": "알 수 없는 api 작업: {action}",
+    "api.error.actionRequiresJson": "{action}에는 --json이 필요합니다",
+    "api.error.actionRequiresChanged": "{action}은 현재 --changed가 필요합니다",
     "label.installed": "설치됨",
     "label.mustflowRoot": "mustflow 루트",
     "label.commandContract": "명령 계약",
@@ -665,6 +678,8 @@ export const koMessages = {
     "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.error.missingIntent": "명령 이름이 없습니다",
     "run.error.unknownIntent": "알 수 없는 명령: {intent}",
     "run.error.statusNotConfigured": '명령 "{intent}"의 상태는 {status}입니다. 설정된 상태(configured)인 명령만 실행할 수 있습니다',

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,18 @@ 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.exit.ok": "已检查并输出 API 报告",
+    "api.error.missingAction": "请指定 api 操作：workspace-summary、command-catalog、verification-plan、latest-evidence、diff-risk 或 health",
+    "api.error.unknownAction": "未知 api 操作：{action}",
+    "api.error.actionRequiresJson": "{action} 需要 --json",
+    "api.error.actionRequiresChanged": "{action} 当前需要 --changed",
     "label.installed": "已安装",
     "label.mustflowRoot": "mustflow 根目录",
     "label.commandContract": "命令规范",
@@ -665,6 +678,8 @@ export const zhMessages = {
     "run.help.exit.ok": "命令已以允许的退出码完成",
     "run.help.exit.fail": "命令无效、被拒绝、超时或失败",
     "run.label.suggestedIntentSnippet": "建议的命令契约片段",
+    "run.progress.started": "正在运行 {intent}（超时：{seconds} 秒）...",
+    "run.progress.timeoutWarning": "{intent} 仍在运行...（已用 {seconds} 秒，达到超时的 {percent}%）",
     "run.error.missingIntent": "缺少命令名称",
     "run.error.unknownIntent": "未知命令：{intent}",
     "run.error.statusNotConfigured": '命令 "{intent}" 的状态为 {status}；只能运行已配置的命令',

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/cli-output.js

@@ -32,5 +32,5 @@ export function renderCliError(message, helpCommand, lang = 'en') {
 }
 export function printUsageError(reporter, message, helpCommand, helpText, lang = 'en') {
     reporter.stderr(renderCliError(message, helpCommand, lang));
-    reporter.stdout(helpText);
+    reporter.stderr(helpText);
 }

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/cli/lib/dashboard-html/client-script.js

@@ -146,6 +146,10 @@ function updateSaveState() {
 	document.getElementById("save").disabled = pending.size === 0;
 }
 
+function hasUnsavedChanges() {
+	return pending.size > 0;
+}
+
 function setPending(id, value) {
 	const original = snapshot.settings.find((setting) => setting.id === id)?.value;
 	if (Object.is(original, value)) {
@@ -1899,6 +1903,11 @@ document.getElementById("reload").addEventListener("click", () => {
 document.getElementById("save").addEventListener("click", () => {
 	save().catch((error) => statusText(error.message, "error"));
 });
+window.addEventListener("beforeunload", (event) => {
+	if (!hasUnsavedChanges()) return;
+	event.preventDefault();
+	event.returnValue = "";
+});
 document.getElementById("open-mustflow").addEventListener("click", () => {
 	openMustflowFolder().catch((error) => statusText(error.message, "error"));
 });

package/dist/cli/lib/dashboard-html/styles.js

@@ -9,6 +9,9 @@ export function renderDashboardStyles() {
 	--accent: #8fb4ff;
 	--danger: #ff9a9a;
 	--ok: #9be7ba;
+	--control-bg: #11141a;
+	--control-hover-bg: #171b23;
+	--control-active-bg: #0d1015;
 	--row-bg: rgba(255, 255, 255, 0.018);
 	--row-bg-alt: rgba(255, 255, 255, 0.035);
 	--status-neutral-bg: rgba(174, 182, 197, 0.1);
@@ -16,6 +19,27 @@ export function renderDashboardStyles() {
 	--status-warn-bg: rgba(255, 154, 154, 0.1);
 	font-family: ui-sans-serif, system-ui, -apple-system, BlinkMacSystemFont, "Segoe UI", sans-serif;
 }
+@media (prefers-color-scheme: light) {
+	:root {
+		color-scheme: light;
+		--bg: #f6f8fb;
+		--panel: #ffffff;
+		--line: #d9e0ea;
+		--text: #162033;
+		--muted: #5d6b82;
+		--accent: #285fc2;
+		--danger: #b4232d;
+		--ok: #197a47;
+		--control-bg: #ffffff;
+		--control-hover-bg: #eef3f9;
+		--control-active-bg: #e4ebf5;
+		--row-bg: rgba(40, 95, 194, 0.035);
+		--row-bg-alt: rgba(40, 95, 194, 0.065);
+		--status-neutral-bg: rgba(93, 107, 130, 0.11);
+		--status-ok-bg: rgba(25, 122, 71, 0.11);
+		--status-warn-bg: rgba(180, 35, 45, 0.1);
+	}
+}
 * { box-sizing: border-box; }
 body {
 	margin: 0;
@@ -75,6 +99,11 @@ main {
 	gap: 8px;
 	margin-bottom: 14px;
 	overflow-x: auto;
+	-webkit-overflow-scrolling: touch;
+	scrollbar-width: none;
+}
+.tabs::-webkit-scrollbar {
+	display: none;
 }
 .tab {
 	border-color: transparent;
@@ -120,17 +149,35 @@ input:focus-visible {
 	white-space: nowrap;
 }
 button, select, input {
-	background: #11141a;
+	background: var(--control-bg);
 	border: 1px solid var(--line);
 	border-radius: 6px;
 	color: var(--text);
 	font: inherit;
 	min-height: 38px;
+	transition: background-color 160ms ease, border-color 160ms ease;
 }
 button {
 	cursor: pointer;
 	padding: 0 14px;
 }
+button:not(:disabled):hover,
+select:hover,
+input:hover {
+	background: var(--control-hover-bg);
+	border-color: var(--accent);
+}
+button:not(:disabled):active {
+	background: var(--control-active-bg);
+}
+@media (prefers-reduced-motion: no-preference) {
+	button {
+		transition: background-color 160ms ease, border-color 160ms ease, transform 120ms ease;
+	}
+	button:not(:disabled):active {
+		transform: translateY(1px);
+	}
+}
 button:disabled {
 	cursor: not-allowed;
 	opacity: 0.6;

package/dist/cli/lib/doc-review-ledger.js

@@ -75,7 +75,7 @@ function readLedgerFile(projectRoot) {
     const ledgerPath = path.join(projectRoot, DOC_REVIEW_LEDGER_RELATIVE_PATH);
     const ledgerDirectoryPath = path.dirname(ledgerPath);
     ensureInside(projectRoot, ledgerPath);
-    ensureInsideWithoutSymlinks(projectRoot, ledgerDirectoryPath, { allowMissingLeaf: true });
+    ensureInsideWithoutSymlinks(projectRoot, ledgerDirectoryPath, { allowMissingDescendant: true });
     if (!existsSync(ledgerDirectoryPath)) {
         return { schema_version: '1', documents: [] };
     }