mustflow 2.18.3 → 2.18.7

package/README.md

@@ -356,6 +356,8 @@ Runnable work is declared in `.mustflow/config/commands.toml` so agents do not g
 
 Development servers, watch modes, browser UIs, interactive commands, and background processes do not run directly. `mf run` also rejects obvious long-running `argv` shapes, such as shell-wrapper background payloads, interpreter loops, package-manager development scripts, watchers, and development servers declared as one-shot commands.
 
+Command environments remove the project-local `node_modules/.bin` path from `PATH` by default. If an intent needs a project dependency binary such as `eslint`, `tsc`, or `vitest`, declare it through the package manager, for example `npm exec eslint -- ...`, `pnpm exec tsc -- --noEmit`, `bun x eslint ...`, or `yarn exec eslint ...`. `mf check --strict` warns when an agent-runnable intent uses a bare executable name that appears under the project-local `.bin` directory.
+
 Use `mf verify --reason <event> --plan-only --json` to inspect matching verification intents, command eligibility, remaining gaps, and missing runnable coverage without executing commands. Use `mf run <intent> --dry-run --json` to inspect one resolved command intent without spawning a process or writing a run receipt. Plan-only verification includes a `decision_graph` that connects changed surfaces, classification reasons, command candidates, eligibility checks, effects, and gaps. When `.mustflow/cache/mustflow.sqlite` is fresh, scheduled entries also include read-only `effectGraph` metadata for write locks and lock conflicts. These graph rows are marked `explanation_only` and never grant command authority; `.mustflow/config/commands.toml` remains the only runnable command source.
 
 Each executed command run writes a run record under `.mustflow/state/runs/run-*` and atomically updates `.mustflow/state/runs/latest.json`. The record includes the intent name, working directory, timeout, exit code, timeout status, and the tail of stdout and stderr.

package/dist/cli/commands/run/executor.js

@@ -1,8 +1,9 @@
 import { spawn } from 'node:child_process';
 import { BoundedOutputBuffer } from '../../../core/bounded-output.js';
-import { createPendingTimeoutTermination, forceTerminateProcessTreeNonBlocking, getKillMethod, terminateProcessTreeNonBlocking, } from './process-tree.js';
+import { createPendingTimeoutTermination, forceTerminateProcessTree, getKillMethod, terminateProcessTree, } from './process-tree.js';
 import { createOutputLimitError, isOutputLimitExceededError, writeStreamChunk } from './output.js';
-function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
+const TERMINATION_CONFIRMATION_FALLBACK_MS = 1000;
+function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
     return new Promise((resolve) => {
         const stdout = new BoundedOutputBuffer(stdoutTailBytes);
         const stderr = new BoundedOutputBuffer(stderrTailBytes);
@@ -13,6 +14,9 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutput
         let stdoutBytes = 0;
         let stderrBytes = 0;
         let timeout;
+        let forceKillTimeout;
+        let terminationFallbackTimeout;
+        let terminationStarted = false;
         let termination = null;
         const child = spawn(command.executable, command.args ?? [], {
             cwd,
@@ -23,7 +27,7 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutput
             detached: process.platform !== 'win32',
         });
         childPid = child.pid;
-        const finish = (status, signal) => {
+        const finish = (status, signal, terminationConfirmed = true) => {
             if (settled) {
                 return;
             }
@@ -31,6 +35,19 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutput
             if (timeout) {
                 clearTimeout(timeout);
             }
+            if (forceKillTimeout) {
+                clearTimeout(forceKillTimeout);
+            }
+            if (terminationFallbackTimeout) {
+                clearTimeout(terminationFallbackTimeout);
+            }
+            const confirmedTermination = termination ?
+                {
+                    ...termination,
+                    confirmed: terminationConfirmed,
+                    cleanup_pending: !terminationConfirmed,
+                } :
+                null;
             resolve({
                 status: timedOut ? null : status,
                 signal: timedOut ? null : signal,
@@ -38,20 +55,42 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutput
                 stdout: stdout.toSnapshot(),
                 stderr: stderr.toSnapshot(),
                 pid: childPid,
-                termination,
+                termination: confirmedTermination,
             });
         };
+        const beginTermination = () => {
+            if (terminationStarted) {
+                return;
+            }
+            terminationStarted = true;
+            child.stdout?.destroy();
+            child.stderr?.destroy();
+            terminateProcessTree(childPid);
+            const forceAfterMs = killAfterSeconds * 1000;
+            forceKillTimeout = setTimeout(() => {
+                if (termination) {
+                    termination = {
+                        ...termination,
+                        forced_kill_attempted: true,
+                    };
+                }
+                forceTerminateProcessTree(childPid);
+            }, forceAfterMs);
+            terminationFallbackTimeout = setTimeout(() => {
+                child.unref();
+                finish(null, null, false);
+            }, forceAfterMs + TERMINATION_CONFIRMATION_FALLBACK_MS);
+        };
         const stopForOutputLimit = (stream) => {
             if (settled || childError) {
                 return;
             }
             childError = createOutputLimitError(stream, maxOutputBytes);
-            child.stdout?.destroy();
-            child.stderr?.destroy();
-            child.unref();
-            terminateProcessTreeNonBlocking(childPid);
-            forceTerminateProcessTreeNonBlocking(childPid);
-            finish(null, null);
+            if (timeout) {
+                clearTimeout(timeout);
+                timeout = undefined;
+            }
+            beginTermination();
         };
         child.stdout?.on('data', (chunk) => {
             stdout.append(chunk);
@@ -80,22 +119,20 @@ function runSpawnedCommandStreaming(command, cwd, env, timeoutSeconds, maxOutput
             finish(status, signal);
         });
         timeout = setTimeout(() => {
+            if (settled || childError) {
+                return;
+            }
             timedOut = true;
-            child.stdout?.destroy();
-            child.stderr?.destroy();
-            child.unref();
             termination = createPendingTimeoutTermination(getKillMethod());
-            terminateProcessTreeNonBlocking(childPid);
-            forceTerminateProcessTreeNonBlocking(childPid);
-            finish(null, null);
+            beginTermination();
         }, timeoutSeconds * 1000);
     });
 }
-export function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
-    return runSpawnedCommandStreaming({ executable: command?.executable ?? '', args: command?.args ?? [], shell: command?.shell ?? false }, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
+export function runArgvCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
+    return runSpawnedCommandStreaming({ executable: command?.executable ?? '', args: command?.args ?? [], shell: command?.shell ?? false }, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
 }
-export function runShellCommandStreaming(command, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
-    return runSpawnedCommandStreaming({ executable: command ?? '', shell: true }, cwd, env, timeoutSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
+export function runShellCommandStreaming(command, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit) {
+    return runSpawnedCommandStreaming({ executable: command ?? '', shell: true }, cwd, env, timeoutSeconds, killAfterSeconds, maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, streamOutput, enforceOutputLimit);
 }
 export function getRunStatus(error, exitCode, successExitCodes) {
     const errorWithCode = error;

package/dist/cli/commands/run/process-tree.js

@@ -78,13 +78,13 @@ export function forceTerminateProcessTreeNonBlocking(pid) {
 export function getKillMethod() {
     return process.platform === 'win32' ? 'taskkill_process_tree' : 'process_group_sigterm';
 }
-export function createPendingTimeoutTermination(method) {
+export function createPendingTimeoutTermination(method, forcedKillAttempted = false) {
     return {
         reason: 'timeout',
         method,
         graceful_signal: 'SIGTERM',
         forced_signal: 'SIGKILL',
-        forced_kill_attempted: true,
+        forced_kill_attempted: forcedKillAttempted,
         confirmed: false,
         cleanup_pending: true,
     };

package/dist/cli/commands/run.js

@@ -12,7 +12,7 @@ import { RunProfiler } from '../../core/run-profile.js';
 import { finishRunWriteTracking, startRunWriteTracking } from '../../core/run-write-drift.js';
 import { runBuiltinArgvInProcess } from './run/builtin-dispatch.js';
 import { getRunStatus, runArgvCommandStreaming, runShellCommandStreaming } from './run/executor.js';
-import { emitOutput } from './run/output.js';
+import { emitOutput, isOutputLimitExceededError } from './run/output.js';
 import { createPendingTimeoutTermination, getKillMethod, terminateProcessTree } from './run/process-tree.js';
 import { assembleRunReceipt } from './run/receipt.js';
 function getRunPlanDetail(plan, lang, fallbackKey) {
@@ -187,10 +187,10 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
         }
         if (plan.commandArgv) {
             streamedOutput = !json;
-            return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, json);
+            return runArgvCommandStreaming(plan.argvCommand, plan.cwd, env, plan.timeoutSeconds, plan.killAfterSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, true);
         }
         streamedOutput = !json;
-        return runShellCommandStreaming(plan.shellCommand, plan.cwd, env, plan.timeoutSeconds, plan.maxOutputBytes, stdoutTailBytes, stderrTailBytes, reporter, !json, 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();
@@ -247,6 +247,10 @@ export async function runRun(args, reporter, lang = 'en', options = {}) {
             reporter.stderr(t(lang, 'run.error.timedOut', { intent: intentName, seconds: plan.timeoutSeconds }));
             return 1;
         }
+        if (isOutputLimitExceededError(result.error)) {
+            reporter.stderr(t(lang, 'run.error.outputLimitExceeded', { intent: intentName, message: result.error.message }));
+            return 1;
+        }
         reporter.stderr(t(lang, 'run.error.startFailed', { intent: intentName, message: result.error.message }));
         return 1;
     }

package/dist/cli/i18n/en.js

@@ -672,6 +672,7 @@ Read these files before working:
     "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.timedOut": 'Command "{intent}" timed out after {seconds} seconds',
+    "run.error.outputLimitExceeded": 'Command "{intent}" exceeded max_output_bytes: {message}',
     "run.error.startFailed": 'Command "{intent}" failed to start: {message}',
     "search.help.summary": "Search the local SQLite index for the mustflow workflow.",
     "search.help.option.limit": "Set the number of results to print. Default: 10, max: 50",

package/dist/cli/i18n/es.js

@@ -672,6 +672,7 @@ Lee estos archivos antes de trabajar:
     "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.timedOut": 'El comando "{intent}" agotó el tiempo después de {seconds} segundos',
+    "run.error.outputLimitExceeded": 'El comando "{intent}" superó max_output_bytes: {message}',
     "run.error.startFailed": 'No se pudo iniciar el comando "{intent}": {message}',
     "search.help.summary": "Busca en el índice SQLite local del flujo de trabajo mustflow.",
     "search.help.option.limit": "Define la cantidad de resultados que se imprimen. Predeterminado: 10, máximo: 50",

package/dist/cli/i18n/fr.js

@@ -672,6 +672,7 @@ Lisez ces fichiers avant de travailler :
     "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.timedOut": 'La commande "{intent}" a expiré après {seconds} secondes',
+    "run.error.outputLimitExceeded": 'La commande "{intent}" a dépassé max_output_bytes : {message}',
     "run.error.startFailed": 'Impossible de démarrer la commande "{intent}" : {message}',
     "search.help.summary": "Recherche dans l'index SQLite local du flux de travail mustflow.",
     "search.help.option.limit": "Définit le nombre de résultats à imprimer. Par défaut : 10, max : 50",

package/dist/cli/i18n/hi.js

@@ -672,6 +672,7 @@ export const hiMessages = {
     "run.error.maxOutputBytesDetail": "Output limit अनुमत maximum के अंदर रहनी चाहिए।",
     "run.error.conflictingPreviewModes": "--dry-run या --plan-only में से एक इस्तेमाल करें, दोनों नहीं",
     "run.error.timedOut": 'कमांड "{intent}" {seconds} सेकंड बाद time out हुई',
+    "run.error.outputLimitExceeded": 'कमांड "{intent}" ने max_output_bytes सीमा पार की: {message}',
     "run.error.startFailed": 'कमांड "{intent}" शुरू नहीं हो सकी: {message}',
     "search.help.summary": "mustflow वर्कफ़्लो के लिए स्थानीय SQLite इंडेक्स में खोजें।",
     "search.help.option.limit": "प्रिंट किए जाने वाले परिणामों की संख्या सेट करें। डिफ़ॉल्ट: 10, अधिकतम: 50",

package/dist/cli/i18n/ko.js

@@ -672,6 +672,7 @@ export const koMessages = {
     "run.error.maxOutputBytesDetail": "출력 상한은 허용된 최댓값 안에 있어야 합니다.",
     "run.error.conflictingPreviewModes": "--dry-run과 --plan-only 중 하나만 사용하세요",
     "run.error.timedOut": '명령 "{intent}"가 {seconds}초 뒤 시간 초과되었습니다',
+    "run.error.outputLimitExceeded": '명령 "{intent}"가 max_output_bytes 제한을 넘었습니다: {message}',
     "run.error.startFailed": '명령 "{intent}"를 시작하지 못했습니다: {message}',
     "search.help.summary": "로컬 SQLite 색인에서 mustflow 워크플로우를 검색합니다.",
     "search.help.option.limit": "출력할 검색 결과 수를 설정합니다. 기본값: 10, 최대: 50",

package/dist/cli/i18n/zh.js

@@ -672,6 +672,7 @@ export const zhMessages = {
     "run.error.maxOutputBytesDetail": "输出限制必须保持在允许的最大值内。",
     "run.error.conflictingPreviewModes": "只能使用 --dry-run 或 --plan-only，不能同时使用",
     "run.error.timedOut": '命令 "{intent}" 在 {seconds} 秒后超时',
+    "run.error.outputLimitExceeded": '命令 "{intent}" 超过 max_output_bytes：{message}',
     "run.error.startFailed": '命令 "{intent}" 启动失败：{message}',
     "search.help.summary": "搜索本地 SQLite 索引中的 mustflow 工作流。",
     "search.help.option.limit": "设置要输出的结果数量。默认值：10，最大：50",

package/dist/cli/lib/dashboard-export.js

@@ -4,6 +4,7 @@ import { createDashboardCompletionVerdict } from '../../core/completion-verdict.
 import { createDashboardEvidenceModel } from '../../core/verification-evidence.js';
 import { redactSecretLikeText } from '../../core/secret-redaction.js';
 import { ensureFileTargetInsideWithoutSymlinks, ensureInside, toPosixPath, writeUtf8FileInsideWithoutSymlinks, } from './filesystem.js';
+import { safeJsonForInlineScript } from './html-json.js';
 export class DashboardExportPathError extends Error {
     targetPath;
     constructor(targetPath) {
@@ -634,7 +635,7 @@ export function renderDashboardExportHtml(snapshot) {
     const graphSummary = asRecord(harnessVerification.decision_graph_summary);
     const harnessRunHistory = asRecord(harnessReport.run_history);
     const harnessDocsReview = asRecord(harnessReport.docs_review);
-    const embeddedJson = JSON.stringify(snapshot).replace(/</gu, '\\u003c');
+    const embeddedJson = safeJsonForInlineScript(snapshot);
     return `<!doctype html>
 <html lang="en">
 <head>

package/dist/cli/lib/dashboard-html/locale-bootstrap.js

@@ -1,8 +1,9 @@
 import { getDashboardLocaleBundle } from '../dashboard-locale.js';
+import { safeJsonForInlineScript } from '../html-json.js';
 export function createDashboardLocaleBootstrap() {
     const localeBundle = getDashboardLocaleBundle();
     return {
-        serializedLocaleBundle: JSON.stringify(localeBundle),
-        serializedAvailableLocales: JSON.stringify(localeBundle.locales),
+        serializedLocaleBundle: safeJsonForInlineScript(localeBundle),
+        serializedAvailableLocales: safeJsonForInlineScript(localeBundle.locales),
     };
 }

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

@@ -1,3 +1,4 @@
+import { safeJsonForInlineScript } from '../html-json.js';
 import { renderDashboardClientScript } from './client-script.js';
 import { createDashboardLocaleBootstrap } from './locale-bootstrap.js';
 import { renderDashboardStyles } from './styles.js';
@@ -12,10 +13,10 @@ function escapeHtml(value) {
 export function renderDashboardHtml(snapshot, token, statusSnapshot, docReviewSnapshot) {
     const root = escapeHtml(snapshot.projectRoot);
     const preferencesPath = escapeHtml(snapshot.preferencesPath);
-    const serializedSnapshot = JSON.stringify(snapshot);
-    const serializedStatusSnapshot = JSON.stringify(statusSnapshot);
-    const serializedDocReviewSnapshot = JSON.stringify(docReviewSnapshot);
-    const serializedToken = JSON.stringify(token);
+    const serializedSnapshot = safeJsonForInlineScript(snapshot);
+    const serializedStatusSnapshot = safeJsonForInlineScript(statusSnapshot);
+    const serializedDocReviewSnapshot = safeJsonForInlineScript(docReviewSnapshot);
+    const serializedToken = safeJsonForInlineScript(token);
     const { serializedLocaleBundle, serializedAvailableLocales } = createDashboardLocaleBootstrap();
     return `<!doctype html>
 <html lang="en">

package/dist/cli/lib/html-json.js

@@ -0,0 +1,11 @@
+const INLINE_SCRIPT_JSON_ESCAPES = {
+    '<': '\\u003C',
+    '>': '\\u003E',
+    '&': '\\u0026',
+    '\u2028': '\\u2028',
+    '\u2029': '\\u2029',
+};
+export function safeJsonForInlineScript(value) {
+    const json = JSON.stringify(value);
+    return (json ?? 'null').replace(/[<>&\u2028\u2029]/gu, (character) => INLINE_SCRIPT_JSON_ESCAPES[character]);
+}

package/dist/cli/lib/local-index/index.js

@@ -284,7 +284,21 @@ function collectCommandIntents(projectRoot) {
     }
     return intents;
 }
+function normalizeIndexedFileSourceScope(value) {
+    const sourceScope = toSearchString(value);
+    if (sourceScope === 'source_anchor' || sourceScope === 'state') {
+        return sourceScope;
+    }
+    return 'workflow';
+}
 function readIndexedFileRecord(projectRoot, relativePath, sourceScope, contentHash = null) {
+    const metadata = readIndexedFileMetadataRecord(projectRoot, relativePath, sourceScope);
+    return {
+        ...metadata,
+        contentHash: contentHash ?? sha256Bytes(readFileSync(path.join(projectRoot, ...relativePath.split('/')))),
+    };
+}
+function readIndexedFileMetadataRecord(projectRoot, relativePath, sourceScope) {
     const fullPath = path.join(projectRoot, ...relativePath.split('/'));
     const stats = statSync(fullPath);
     return {
@@ -292,7 +306,6 @@ function readIndexedFileRecord(projectRoot, relativePath, sourceScope, contentHa
         sourceScope,
         sizeBytes: stats.size,
         mtimeMs: Math.round(stats.mtimeMs),
-        contentHash: contentHash ?? sha256Bytes(readFileSync(fullPath)),
     };
 }
 function collectIndexedFileRecords(projectRoot, documents, sourceAnchors) {
@@ -305,8 +318,21 @@ function collectIndexedFileRecords(projectRoot, documents, sourceAnchors) {
             records.set(anchorPath, readIndexedFileRecord(projectRoot, anchorPath, 'source_anchor'));
         }
     }
+    if (existsSync(path.join(projectRoot, ...LATEST_RUN_STATE_RELATIVE_PATH.split('/')))) {
+        records.set(LATEST_RUN_STATE_RELATIVE_PATH, readIndexedFileRecord(projectRoot, LATEST_RUN_STATE_RELATIVE_PATH, 'state'));
+    }
     return [...records.values()].sort((left, right) => left.path.localeCompare(right.path));
 }
+function collectFastPreflightIndexedFileMetadataRecords(projectRoot, includeSource) {
+    if (includeSource) {
+        return null;
+    }
+    const records = getExistingIndexablePaths(projectRoot).map((relativePath) => readIndexedFileMetadataRecord(projectRoot, relativePath, 'workflow'));
+    if (existsSync(path.join(projectRoot, ...LATEST_RUN_STATE_RELATIVE_PATH.split('/')))) {
+        records.push(readIndexedFileMetadataRecord(projectRoot, LATEST_RUN_STATE_RELATIVE_PATH, 'state'));
+    }
+    return records.sort((left, right) => left.path.localeCompare(right.path));
+}
 function normalizeSearchText(value) {
     return value.trim().replace(/\s+/g, ' ');
 }
@@ -1948,6 +1974,86 @@ function populateDatabase(database, capabilities, documents, skills, skillRoutes
     populatePathSurfaceReadModel(database);
     populateSearchTables(database, capabilities, documents, skills, skillRoutes, commandIntents, sourceAnchors);
 }
+function readCount(database, tableName) {
+    if (!hasTable(database, tableName)) {
+        return 0;
+    }
+    const [row] = queryRows(database, `SELECT COUNT(*) AS count FROM ${tableName}`);
+    const count = row?.count;
+    return typeof count === 'number' && Number.isFinite(count) ? count : 0;
+}
+function readStoredIndexedPaths(database) {
+    if (!hasTable(database, 'documents')) {
+        return [];
+    }
+    return queryRows(database, 'SELECT path FROM documents ORDER BY path')
+        .map((row) => toSearchString(row.path))
+        .filter(Boolean);
+}
+function createStoredLocalIndexResult(projectRoot, databasePath, dryRun, indexMode, database, capabilities) {
+    return {
+        schema_version: LOCAL_INDEX_SCHEMA_VERSION,
+        command: 'index',
+        ok: true,
+        mustflow_root: path.resolve(projectRoot),
+        database_path: databasePath,
+        dry_run: dryRun,
+        wrote_files: false,
+        index_mode: indexMode,
+        reused_existing: true,
+        rebuild_reason: null,
+        document_count: readCount(database, 'documents'),
+        skill_count: readCount(database, 'skills'),
+        skill_route_count: readCount(database, 'skill_routes'),
+        command_intent_count: readCount(database, 'command_intents'),
+        command_effect_count: readCount(database, 'command_effects'),
+        verification_evidence_summary_count: readCount(database, 'verification_evidence_summaries'),
+        verification_plan_count: readCount(database, 'verification_plans'),
+        acceptance_criteria_count: readCount(database, 'acceptance_criteria'),
+        criterion_coverage_count: readCount(database, 'criterion_coverage'),
+        verification_receipt_summary_count: readCount(database, 'verification_receipt_summaries'),
+        command_receipt_summary_count: readCount(database, 'command_receipt_summaries'),
+        verification_coverage_state_count: readCount(database, 'verification_coverage_states'),
+        verification_risk_signal_count: readCount(database, 'verification_risk_signals'),
+        validation_ratchet_signal_count: readCount(database, 'validation_ratchet_signals'),
+        completion_verdict_summary_count: readCount(database, 'completion_verdict_summaries'),
+        repro_route_count: readCount(database, 'repro_routes'),
+        repro_observation_count: readCount(database, 'repro_observations'),
+        failure_fingerprint_count: readCount(database, 'verification_failure_fingerprints'),
+        source_index_enabled: readMetadataValue(database, 'source_index_enabled') === 'true',
+        source_anchor_count: readCount(database, 'source_anchors'),
+        source_anchor_risk_signal_count: readCount(database, 'source_anchor_risk_signals'),
+        search_backend: capabilities.backend,
+        search_fts5_available: capabilities.fts5Available,
+        content_mode: LOCAL_INDEX_CONTENT_MODE,
+        store_full_content: LOCAL_INDEX_STORE_FULL_CONTENT,
+        max_snippet_bytes_per_document: MAX_SNIPPET_BYTES_PER_DOCUMENT,
+        excluded_raw_data_kinds: [...LOCAL_INDEX_EXCLUDED_RAW_DATA_KINDS],
+        indexed_file_count: readCount(database, 'indexed_files'),
+        indexed_paths: readStoredIndexedPaths(database),
+    };
+}
+function indexedFileMetadataMatch(database, currentFiles) {
+    const rows = queryRows(database, 'SELECT path, source_scope, size_bytes, mtime_ms, parser_version FROM indexed_files ORDER BY path');
+    if (rows.length !== currentFiles.length) {
+        return false;
+    }
+    const currentByPath = new Map(currentFiles.map((file) => [file.path, file]));
+    for (const row of rows) {
+        const storedPath = toSearchString(row.path);
+        const current = currentByPath.get(storedPath);
+        if (!current) {
+            return false;
+        }
+        if (normalizeIndexedFileSourceScope(row.source_scope) !== current.sourceScope ||
+            row.size_bytes !== current.sizeBytes ||
+            row.mtime_ms !== current.mtimeMs ||
+            toSearchString(row.parser_version) !== LOCAL_INDEX_PARSER_VERSION) {
+            return false;
+        }
+    }
+    return true;
+}
 function indexedFilesMatch(database, currentFiles) {
     const rows = queryRows(database, 'SELECT path, source_scope, content_hash, parser_version FROM indexed_files ORDER BY path');
     if (rows.length !== currentFiles.length) {
@@ -1960,7 +2066,7 @@ function indexedFilesMatch(database, currentFiles) {
         if (!current) {
             return false;
         }
-        if (toSearchString(row.source_scope) !== current.sourceScope ||
+        if (normalizeIndexedFileSourceScope(row.source_scope) !== current.sourceScope ||
             toSearchString(row.content_hash) !== current.contentHash ||
             toSearchString(row.parser_version) !== LOCAL_INDEX_PARSER_VERSION) {
             return false;
@@ -1968,6 +2074,44 @@ function indexedFilesMatch(database, currentFiles) {
     }
     return true;
 }
+async function readIncrementalPreflightReuse(SQL, databasePath, projectRoot, currentFiles, sourceScopeHash, dryRun, indexMode) {
+    if (!currentFiles) {
+        return { result: null, rebuildReason: null };
+    }
+    if (!existsSync(databasePath)) {
+        return { result: null, rebuildReason: 'missing_index' };
+    }
+    let database;
+    try {
+        database = new SQL.Database(readFileSync(databasePath));
+        if (readStoredSchemaVersion(database) !== LOCAL_INDEX_SCHEMA_VERSION) {
+            return { result: null, rebuildReason: 'schema_version_mismatch' };
+        }
+        if (readMetadataValue(database, 'parser_version') !== LOCAL_INDEX_PARSER_VERSION) {
+            return { result: null, rebuildReason: 'parser_version_mismatch' };
+        }
+        if (readMetadataValue(database, 'source_scope_hash') !== sourceScopeHash) {
+            return { result: null, rebuildReason: 'source_scope_mismatch' };
+        }
+        if (!hasTable(database, 'indexed_files')) {
+            return { result: null, rebuildReason: 'indexed_files_missing' };
+        }
+        if (!indexedFileMetadataMatch(database, currentFiles)) {
+            return { result: null, rebuildReason: 'file_fingerprint_mismatch' };
+        }
+        const capabilities = readStoredSearchCapabilities(database);
+        return {
+            result: createStoredLocalIndexResult(projectRoot, databasePath, dryRun, indexMode, database, capabilities),
+            rebuildReason: null,
+        };
+    }
+    catch {
+        return { result: null, rebuildReason: 'unreadable_index' };
+    }
+    finally {
+        database?.close();
+    }
+}
 async function readIncrementalReuseDecision(SQL, databasePath, currentFiles, sourceScopeHash) {
     if (!existsSync(databasePath)) {
         return { reusable: false, rebuildReason: 'missing_index', capabilities: null };
@@ -2015,13 +2159,28 @@ export async function createLocalIndex(projectRoot, options = {}) {
     const dryRun = options.dryRun === true;
     const incremental = options.incremental === true;
     const indexMode = incremental ? 'incremental' : 'full';
+    const sourceConfig = readLocalIndexSourceConfig(projectRoot);
+    const includeSource = options.includeSource === true || sourceConfig.enabledByDefault;
+    const sourceScopeHash = getSourceScopeHash(includeSource, sourceConfig);
+    let capabilities = searchCapabilities(false);
+    let reusedExisting = false;
+    let rebuildReason = null;
+    const SQL = await loadSqlJs();
+    const capabilityDatabase = new SQL.Database();
+    capabilities = detectLocalSearchCapabilities(capabilityDatabase);
+    capabilityDatabase.close();
+    if (incremental) {
+        const preflightFiles = collectFastPreflightIndexedFileMetadataRecords(projectRoot, includeSource);
+        const preflightReuse = await readIncrementalPreflightReuse(SQL, databasePath, projectRoot, preflightFiles, sourceScopeHash, dryRun, indexMode);
+        if (preflightReuse.result) {
+            return preflightReuse.result;
+        }
+        rebuildReason = preflightReuse.rebuildReason;
+    }
     const documents = collectDocuments(projectRoot);
     const skills = collectSkills(documents);
     const skillRoutes = collectSkillRoutes(projectRoot);
     const commandIntents = collectCommandIntents(projectRoot);
-    const sourceConfig = readLocalIndexSourceConfig(projectRoot);
-    const includeSource = options.includeSource === true || sourceConfig.enabledByDefault;
-    const sourceScopeHash = getSourceScopeHash(includeSource, sourceConfig);
     const previousSourceAnchors = includeSource
         ? await readPreviousSourceAnchorSnapshots(databasePath).catch(() => [])
         : [];
@@ -2033,17 +2192,10 @@ export async function createLocalIndex(projectRoot, options = {}) {
         : [];
     const verificationEvidence = createVerificationEvidenceIndex(projectRoot);
     const indexedFiles = collectIndexedFileRecords(projectRoot, documents, sourceAnchors);
-    let capabilities = searchCapabilities(false);
-    let reusedExisting = false;
-    let rebuildReason = null;
-    const SQL = await loadSqlJs();
-    const capabilityDatabase = new SQL.Database();
-    capabilities = detectLocalSearchCapabilities(capabilityDatabase);
-    capabilityDatabase.close();
     if (incremental) {
         const reuseDecision = await readIncrementalReuseDecision(SQL, databasePath, indexedFiles, sourceScopeHash);
         reusedExisting = reuseDecision.reusable;
-        rebuildReason = reuseDecision.rebuildReason;
+        rebuildReason = reuseDecision.rebuildReason ?? rebuildReason;
         capabilities = reuseDecision.capabilities ?? capabilities;
     }
     if (!dryRun && !reusedExisting) {
@@ -2110,7 +2262,7 @@ function getStalePaths(projectRoot, database) {
         const indexedPaths = new Set(indexedRows.map((row) => toSearchString(row.path)));
         for (const row of indexedRows) {
             const indexedPath = toSearchString(row.path);
-            const sourceScope = toSearchString(row.source_scope) === 'source_anchor' ? 'source_anchor' : 'workflow';
+            const sourceScope = normalizeIndexedFileSourceScope(row.source_scope);
             try {
                 const current = readIndexedFileRecord(projectRoot, indexedPath, sourceScope);
                 if (current.contentHash !== toSearchString(row.content_hash)) {

package/dist/cli/lib/run-plan.js

@@ -78,6 +78,9 @@ function readEffectiveMaxOutputBytes(contract, intent) {
         readPositiveInteger(contract.defaults, 'max_output_bytes') ??
         DEFAULT_COMMAND_MAX_OUTPUT_BYTES;
 }
+function readEffectiveKillAfterSeconds(contract) {
+    return readPositiveInteger(contract.defaults, 'kill_after_seconds') ?? 5;
+}
 function getMaxOutputBytesLimitDetail(contract, intent) {
     const intentValue = readPositiveInteger(intent, 'max_output_bytes');
     if (intentValue !== undefined) {
@@ -103,6 +106,7 @@ function readRunIntentMetadata(contract, intent) {
         kind: readString(intent, 'kind') ?? null,
         configuredCwd,
         timeoutSeconds: readPositiveInteger(intent, 'timeout_seconds') ?? null,
+        killAfterSeconds: readEffectiveKillAfterSeconds(contract),
         maxOutputBytes: readEffectiveMaxOutputBytes(contract, intent),
         successExitCodes: getSuccessExitCodes(intent),
         commandArgv,
@@ -138,6 +142,7 @@ function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonC
         cwd: null,
         relativeCwd: null,
         timeoutSeconds: metadata?.timeoutSeconds ?? null,
+        killAfterSeconds: metadata?.killAfterSeconds ?? null,
         maxOutputBytes: metadata?.maxOutputBytes ?? null,
         successExitCodes: metadata?.successExitCodes ?? null,
         commandArgv: metadata?.commandArgv,
@@ -199,6 +204,7 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         cwd,
         relativeCwd: getRelativeProjectPath(projectRoot, cwd),
         timeoutSeconds: metadata.timeoutSeconds,
+        killAfterSeconds: metadata.killAfterSeconds,
         maxOutputBytes: metadata.maxOutputBytes,
         successExitCodes: metadata.successExitCodes,
         commandArgv,

package/dist/core/check-issues.js

@@ -15,6 +15,7 @@ const CHECK_ISSUE_ID_RULES = [
     ['mustflow.command_contract.effect_path_escape', /^Strict: Command effect path must stay inside the current root:/u],
     ['mustflow.command_contract.shared_writes_without_effects', /^Strict warning: configured agent-runnable intents .+ share path:.+ through writes without explicit effects or resource locks$/u],
     ['mustflow.command_contract.broad_env_inheritance', /^Strict warning: configured agent-runnable intent [^\s]+ (?:implicitly inherits the host environment|uses env_policy = "inherit")/u],
+    ['mustflow.command_contract.project_local_bin_bare_executable', /^Strict warning: configured agent-runnable intent [^\s]+ uses bare executable "[^"]+" that matches project-local node_modules\/\.bin/u],
     ['mustflow.prompt_cache.required', /^Strict: \[prompt_cache\] table is required$/u],
     ['mustflow.prompt_cache.volatile_in_stable', /^Strict: \[prompt_cache\.layers\.stable\]\.read must not include volatile path /u],
     ['mustflow.refresh.hash_method_required', /^Strict: \[refresh\]\.default_method should be "hash_check" for cache-friendly refresh$/u],

package/dist/core/command-contract-rules.js

@@ -45,9 +45,6 @@ export function commandIntentHasCommandSource(intent) {
 export function shellCommandHasBlockedBackgroundPattern(command) {
     return BACKGROUND_SHELL_PATTERNS.some((pattern) => pattern.test(command));
 }
-export function commandIntentHasBlockedShellBackgroundPattern(intent) {
-    return intent.mode === 'shell' && typeof intent.cmd === 'string' && shellCommandHasBlockedBackgroundPattern(intent.cmd);
-}
 function normalizeExecutableName(value) {
     return path.basename(value).replace(/\.(?:cmd|exe|ps1)$/iu, '').toLowerCase();
 }

package/dist/core/command-contract-validation.js

@@ -1,7 +1,9 @@
-import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, } from './config-loading.js';
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readStringArray, } from './config-loading.js';
 import { COMMAND_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY } from './command-env.js';
 import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
-import { commandIntentBlockedCommandPattern, commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 import { MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage } from './command-output-limits.js';
 function commandContractIssue(message) {
     return { message };
@@ -186,10 +188,10 @@ function validateCommandIntent(intentName, intent, issues) {
     if (!commandIntentHasCommandSource(intent)) {
         issues.push(commandContractIssue(`Configured intent ${intentName} must define argv or mode = "shell" with cmd`));
     }
-    if (commandIntentHasBlockedShellBackgroundPattern(intent)) {
+    const blockedCommandPattern = commandIntentBlockedCommandPattern(intent);
+    if (blockedCommandPattern?.code === 'shell_background_pattern') {
         issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`));
     }
-    const blockedCommandPattern = commandIntentBlockedCommandPattern(intent);
     if (blockedCommandPattern?.code === 'long_running_command_pattern') {
         issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`));
     }
@@ -245,6 +247,41 @@ function validateCommandEnvInheritanceWarnings(commandsToml) {
     }
     return issues;
 }
+function projectLocalBinExecutableExists(projectRoot, executable) {
+    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
+    const executableName = path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '');
+    const candidates = [
+        executableName,
+        `${executableName}.cmd`,
+        `${executableName}.exe`,
+        `${executableName}.ps1`,
+    ];
+    return candidates.some((candidate) => existsSync(path.join(localBinPath, candidate)));
+}
+function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
+    const issues = [];
+    if (!isRecord(commandsToml?.intents)) {
+        return issues;
+    }
+    for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
+        if (!isRecord(intent)) {
+            continue;
+        }
+        if (intent.status !== 'configured' || intent.lifecycle !== 'oneshot' || intent.run_policy !== 'agent_allowed') {
+            continue;
+        }
+        const argv = readStringArray(intent, 'argv');
+        const executable = argv?.[0];
+        if (!executable || executable.includes('/') || executable.includes('\\')) {
+            continue;
+        }
+        if (!projectLocalBinExecutableExists(projectRoot, executable)) {
+            continue;
+        }
+        issues.push(commandContractWarning(`configured agent-runnable intent ${intentName} uses bare executable "${executable}" that matches project-local node_modules/.bin; use a package-manager mediated command such as npm exec, pnpm exec, bun x, or yarn exec`));
+    }
+    return issues;
+}
 /**
  * mf:anchor core.command-contract-validation
  * purpose: Validate command intent declarations that gate agent-executable repository commands.
@@ -287,6 +324,7 @@ export function validateCommandContractStrictDefaults(projectRoot, commandsToml)
         }
     }
     issues.push(...validateCommandEnvInheritanceWarnings(commandsToml));
+    issues.push(...validateProjectLocalBinWarnings(projectRoot, commandsToml));
     issues.push(...validateCommandEffects(projectRoot, commandsToml));
     issues.push(...validateCommandEffectLockWarnings(commandsToml));
     return issues;

package/dist/core/command-intent-eligibility.js

@@ -1,5 +1,5 @@
 import { isRecord, readString } from './config-loading.js';
-import { commandIntentBlockedCommandPattern, commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 export function evaluateCommandIntentEligibility(intentName, rawIntent) {
     if (!commandIntentNameIsSafe(intentName)) {
         return {
@@ -61,14 +61,14 @@ export function evaluateCommandIntentEligibility(intentName, rawIntent) {
             detail: 'Intent does not define argv or shell cmd.',
         };
     }
-    if (commandIntentHasBlockedShellBackgroundPattern(rawIntent)) {
+    const blockedPattern = commandIntentBlockedCommandPattern(rawIntent);
+    if (blockedPattern?.code === 'shell_background_pattern') {
         return {
             ok: false,
             code: 'blocked_shell_background_pattern',
-            detail: 'Shell command contains a blocked long-running or background pattern.',
+            detail: blockedPattern.detail,
         };
     }
-    const blockedPattern = commandIntentBlockedCommandPattern(rawIntent);
     if (blockedPattern?.code === 'long_running_command_pattern') {
         return {
             ok: false,

package/dist/core/contract-lint.js

@@ -2,7 +2,7 @@ import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, readPositiveInteger, readString, readStringArray, } from './config-loading.js';
 import { evaluateCommandIntentEligibility, } from './command-intent-eligibility.js';
-import { commandIntentBlockedCommandPattern, commandIntentHasBlockedShellBackgroundPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 import { MAX_COMMAND_OUTPUT_BYTES } from './command-output-limits.js';
 import { commandEffectsConflict, normalizeCommandEffects } from './command-effects.js';
 import { listChangeClassificationValidationReasons } from './change-classification.js';
@@ -323,10 +323,10 @@ function lintIntent(name, value, issues) {
     if (!commandIntentHasCommandSource(value)) {
         pushIssue(issues, 'error', 'executable_source_missing', name, `Configured intent ${name} must define argv or shell cmd.`);
     }
-    if (commandIntentHasBlockedShellBackgroundPattern(value)) {
+    const blockedCommandPattern = commandIntentBlockedCommandPattern(value);
+    if (blockedCommandPattern?.code === 'shell_background_pattern') {
         pushIssue(issues, 'error', 'shell_background_pattern', name, `Shell intent ${name} contains a blocked long-running or background pattern.`);
     }
-    const blockedCommandPattern = commandIntentBlockedCommandPattern(value);
     if (blockedCommandPattern?.code === 'long_running_command_pattern') {
         pushIssue(issues, 'error', 'long_running_command_pattern', name, `Intent ${name} contains a blocked long-running or background command pattern.`);
     }

package/package.json

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

package/templates/default/manifest.toml

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