mustflow 2.27.0 → 2.28.0

package/README.md

@@ -307,9 +307,9 @@ Runnable work is declared in `.mustflow/config/commands.toml` so agents do not g
 - `run_policy = "agent_allowed"`
 - `stdin = "closed"`
 
-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.
+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. If a bounded one-shot command has a name that matches a common long-running pattern, the intent can explicitly acknowledge that with `allow_long_running_command_patterns = true`; background shell patterns remain blocked.
 
-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.
+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, except for names listed in `defaults.allow_project_local_bin_bare_executables`. `mf run` may resolve those allowed names directly from the local `.bin` directory without exposing every local binary through `PATH`. The installed template allows `mf` and `mustflow` by default. Intent-level `allow_env_inheritance_risks = true` is available when a command intentionally uses `env_policy = "inherit"`.
 
 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.
 

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

@@ -1,7 +1,7 @@
 import path from 'node:path';
 import { isMustflowBinName } from '../../core/command-classification.js';
 import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
-import { resolveCommandEnv } from '../../core/command-env.js';
+import { readProjectLocalBinBareExecutableAllowlist, resolveAllowedProjectLocalBinExecutable, resolveCommandEnv, } from '../../core/command-env.js';
 import { getCommandMaxOutputBytesLimitDetail, readEffectiveCommandCwd, readEffectiveCommandMaxOutputBytes, } from '../../core/command-run-constraints.js';
 import { evaluateCommandIntentEligibility, } from '../../core/command-intent-eligibility.js';
 import { inspectActiveRunLocks, } from '../../core/active-run-locks.js';
@@ -56,7 +56,7 @@ function resolveCurrentCliEntrypoint() {
     const entrypoint = process.argv[1];
     return entrypoint ? path.resolve(entrypoint) : undefined;
 }
-function resolveArgvCommand(intent, commandArgv) {
+function resolveArgvCommand(projectRoot, contract, intent, commandArgv) {
     const [command = '', ...args] = commandArgv;
     if (isMustflowBuiltinIntent(intent) && isMustflowBinName(command)) {
         const entrypoint = resolveCurrentCliEntrypoint();
@@ -68,6 +68,14 @@ function resolveArgvCommand(intent, commandArgv) {
             };
         }
     }
+    const localBinExecutable = resolveAllowedProjectLocalBinExecutable(projectRoot, command, readProjectLocalBinBareExecutableAllowlist(contract));
+    if (localBinExecutable) {
+        return {
+            executable: localBinExecutable,
+            args,
+            shell: shouldUseShellForArgvExecutable(localBinExecutable),
+        };
+    }
     return {
         executable: command,
         args,
@@ -212,7 +220,7 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         commandArgv,
         shellCommand: metadata.shellCommand,
         mode: metadata.mode,
-        argvCommand: commandArgv ? resolveArgvCommand(rawIntent, commandArgv) : undefined,
+        argvCommand: commandArgv ? resolveArgvCommand(projectRoot, contract, rawIntent, commandArgv) : undefined,
         writes: metadata.writes,
         effects: metadata.effects,
         network: metadata.network,

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

@@ -1,7 +1,6 @@
-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_ENV_POLICIES, DEFAULT_COMMAND_ENV_POLICY, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, normalizeCommandExecutableName, readProjectLocalBinBareExecutableAllowlist, resolveAllowedProjectLocalBinExecutable, } from './command-env.js';
 import { COMMAND_EFFECT_CONCURRENCY, COMMAND_EFFECT_MODES, COMMAND_EFFECT_TYPES, validateCommandEffectLockWarnings, validateCommandEffects, } from './command-effects.js';
 import { COMMAND_PRECONDITION_KINDS } from './command-preconditions.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
@@ -13,6 +12,8 @@ const COMMAND_ARGV_PLACEHOLDER_PATTERN = /^\{([a-z][a-z0-9_]*)\}$/u;
 const COMMAND_ARGV_MIXED_PLACEHOLDER_PATTERN = /\{([a-z][a-z0-9_]*)\}/u;
 const WINDOWS_RESERVED_PATH_SEGMENTS = /^(?:con|prn|aux|nul|com[1-9]|lpt[1-9])(?:\..*)?$/iu;
 const SAFE_PATH_EXTENSION_PATTERN = /^\.[A-Za-z0-9][A-Za-z0-9._-]*$/u;
+const ALLOW_ENV_INHERITANCE_RISKS_KEY = 'allow_env_inheritance_risks';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function commandContractIssue(message, id) {
     return id ? { id, message } : { message };
 }
@@ -257,6 +258,7 @@ function validateCommandDefaults(commandsToml, issues) {
     validateStringField(defaults, 'on_timeout', '[commands.defaults].on_timeout', issues);
     validateAllowedStringField(defaults, 'env_policy', '[commands.defaults].env_policy', COMMAND_ENV_POLICIES, issues);
     validateStringArrayField(defaults, 'env_allowlist', '[commands.defaults].env_allowlist', issues);
+    validateStringArrayField(defaults, PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY, `[commands.defaults].${PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY}`, issues);
     validatePositiveIntegerField(defaults, 'default_timeout_seconds', '[commands.defaults].default_timeout_seconds', issues);
     validateMaxOutputBytesField(defaults, 'max_output_bytes', '[commands.defaults].max_output_bytes', issues);
     validatePositiveIntegerField(defaults, 'kill_after_seconds', '[commands.defaults].kill_after_seconds', issues);
@@ -337,6 +339,8 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     validateAllowedStringField(intent, 'env_policy', `[commands.intents.${intentName}].env_policy`, COMMAND_ENV_POLICIES, issues);
     validateBooleanField(intent, 'allow_shell', `[commands.intents.${intentName}].allow_shell`, issues);
     validateStringArrayField(intent, 'env_allowlist', `[commands.intents.${intentName}].env_allowlist`, issues);
+    validateBooleanField(intent, ALLOW_ENV_INHERITANCE_RISKS_KEY, `[commands.intents.${intentName}].${ALLOW_ENV_INHERITANCE_RISKS_KEY}`, issues);
+    validateBooleanField(intent, ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY, `[commands.intents.${intentName}].${ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY}`, issues);
     validateMaxOutputBytesField(intent, 'max_output_bytes', `[commands.intents.${intentName}].max_output_bytes`, issues);
     validatePositiveIntegerField(intent, 'kill_after_seconds', `[commands.intents.${intentName}].kill_after_seconds`, issues);
     validateCommandIntentSelection(intentName, intent, issues);
@@ -375,7 +379,7 @@ function validateCommandIntent(intentName, intent, allIntents, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         issues.push(commandContractIssue(`Shell intent ${intentName} contains a blocked long-running or background pattern`, 'mustflow.command_contract.shell_background_pattern'));
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && intent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         issues.push(commandContractIssue(`Intent ${intentName} contains a blocked long-running or background command pattern`, 'mustflow.command_contract.long_running_command_pattern'));
     }
     if (hasOwn(intent, 'success_exit_codes')) {
@@ -419,6 +423,9 @@ export function findCommandEnvInheritanceWarnings(commandsToml) {
         if (envPolicy.policy !== 'inherit') {
             continue;
         }
+        if (intent[ALLOW_ENV_INHERITANCE_RISKS_KEY] === true) {
+            continue;
+        }
         const reasons = readCommandEnvInheritanceRiskReasons(intent);
         warnings.push({
             intentName,
@@ -465,21 +472,14 @@ 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)));
+    return resolveAllowedProjectLocalBinExecutable(projectRoot, executable, new Set([normalizeCommandExecutableName(executable)])) !== null;
 }
 function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
     const issues = [];
     if (!isRecord(commandsToml?.intents)) {
         return issues;
     }
+    const allowedBareExecutables = readProjectLocalBinBareExecutableAllowlist(commandsToml);
     for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
         if (!isRecord(intent)) {
             continue;
@@ -492,6 +492,9 @@ function validateProjectLocalBinWarnings(projectRoot, commandsToml) {
         if (!executable || executable.includes('/') || executable.includes('\\')) {
             continue;
         }
+        if (allowedBareExecutables.has(normalizeCommandExecutableName(executable))) {
+            continue;
+        }
         if (!projectLocalBinExecutableExists(projectRoot, executable)) {
             continue;
         }

package/dist/core/command-env.js

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { readString, readStringArray } from './config-loading.js';
 export const COMMAND_ENV_POLICIES = new Set(['inherit', 'minimal', 'allowlist']);
@@ -25,6 +26,8 @@ const BASE_MINIMAL_ENV_KEYS = [
     'WINDIR',
     'windir',
 ];
+export const PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY = 'allow_project_local_bin_bare_executables';
+export const DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST = new Set(['mf', 'mustflow']);
 function getPathEnvKey(env) {
     return Object.keys(env).find((key) => key.toLowerCase() === 'path') ?? 'PATH';
 }
@@ -48,6 +51,46 @@ function readEnvPolicy(table) {
 function readEnvAllowlist(table) {
     return table ? (readStringArray(table, 'env_allowlist') ?? []) : [];
 }
+export function normalizeCommandExecutableName(executable) {
+    return path.basename(executable).replace(/\.(?:cmd|exe|ps1)$/iu, '').toLowerCase();
+}
+export function readProjectLocalBinBareExecutableAllowlist(contractOrCommands) {
+    const defaults = contractOrCommands && typeof contractOrCommands === 'object' && 'defaults' in contractOrCommands
+        ? contractOrCommands.defaults
+        : undefined;
+    const configuredAllowlist = defaults && typeof defaults === 'object'
+        ? defaults[PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST_KEY]
+        : undefined;
+    if (!Array.isArray(configuredAllowlist)) {
+        return DEFAULT_PROJECT_LOCAL_BIN_BARE_EXECUTABLE_ALLOWLIST;
+    }
+    return new Set(configuredAllowlist
+        .filter((entry) => typeof entry === 'string' && entry.trim().length > 0)
+        .map((entry) => normalizeCommandExecutableName(entry)));
+}
+export function resolveAllowedProjectLocalBinExecutable(projectRoot, executable, allowlist) {
+    if (executable.includes('/') || executable.includes('\\')) {
+        return null;
+    }
+    const executableName = normalizeCommandExecutableName(executable);
+    if (!allowlist.has(executableName)) {
+        return null;
+    }
+    const localBinPath = path.join(projectRoot, 'node_modules', '.bin');
+    const candidates = [
+        executableName,
+        `${executableName}.cmd`,
+        `${executableName}.exe`,
+        `${executableName}.ps1`,
+    ];
+    for (const candidate of candidates) {
+        const candidatePath = path.join(localBinPath, candidate);
+        if (existsSync(candidatePath)) {
+            return candidatePath;
+        }
+    }
+    return null;
+}
 function pickEnv(source, names) {
     const output = {};
     for (const name of names) {

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

@@ -1,5 +1,6 @@
 import { isRecord, readString } from './config-loading.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 export const COMMAND_INTENT_INELIGIBILITY_CODES = [
     'intent_not_table',
     'status_not_configured',
@@ -83,7 +84,7 @@ export function evaluateCommandIntentEligibility(intentName, rawIntent) {
             detail: blockedPattern.detail,
         };
     }
-    if (blockedPattern?.code === 'long_running_command_pattern') {
+    if (blockedPattern?.code === 'long_running_command_pattern' && rawIntent[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         return {
             ok: false,
             code: 'blocked_long_running_command_pattern',

package/dist/core/contract-lint.js

@@ -58,6 +58,7 @@ const AGENT_WORKFLOW_PATH = '.mustflow/docs/agent-workflow.md';
 const PACKAGE_SCRIPT_RUNNERS = new Set(['bun', 'npm', 'pnpm', 'yarn']);
 const MAKEFILE_CANDIDATES = ['Makefile', 'makefile'];
 const JUSTFILE_CANDIDATES = ['justfile', 'Justfile'];
+const ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY = 'allow_long_running_command_patterns';
 function uniqueSorted(values) {
     return [...new Set(values)].sort((left, right) => left.localeCompare(right));
 }
@@ -333,7 +334,7 @@ function lintIntent(name, value, issues) {
     if (blockedCommandPattern?.code === 'shell_background_pattern') {
         pushIssue(issues, 'error', 'shell_background_pattern', name, `Shell intent ${name} contains a blocked long-running or background pattern.`);
     }
-    if (blockedCommandPattern?.code === 'long_running_command_pattern') {
+    if (blockedCommandPattern?.code === 'long_running_command_pattern' && value[ALLOW_LONG_RUNNING_COMMAND_PATTERNS_KEY] !== true) {
         pushIssue(issues, 'error', 'long_running_command_pattern', name, `Intent ${name} contains a blocked long-running or background command pattern.`);
     }
     if (!successExitCodesAreValid(value)) {

package/package.json

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

package/schemas/commands.schema.json

@@ -36,7 +36,8 @@
         "on_timeout": { "type": "string" },
         "kill_after_seconds": { "type": "integer" },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
-        "env_allowlist": { "$ref": "#/$defs/stringArray" }
+        "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_project_local_bin_bare_executables": { "$ref": "#/$defs/stringArray" }
       }
     },
     "intents": {
@@ -172,6 +173,7 @@
         },
         "cmd": { "type": "string" },
         "allow_shell": { "type": "boolean" },
+        "allow_long_running_command_patterns": { "type": "boolean" },
         "cwd": { "type": "string" },
         "timeout_seconds": { "type": "integer" },
         "kill_after_seconds": { "type": "integer" },
@@ -185,6 +187,7 @@
         },
         "env_policy": { "$ref": "#/$defs/envPolicy" },
         "env_allowlist": { "$ref": "#/$defs/stringArray" },
+        "allow_env_inheritance_risks": { "type": "boolean" },
         "manual_start_hint": { "type": "string" },
         "health_check_url": { "type": "string" },
         "stop_instruction": { "type": "string" },

package/templates/default/common/.mustflow/config/commands.toml

@@ -18,6 +18,7 @@ on_timeout = "terminate_process_tree"
 kill_after_seconds = 5
 env_policy = "minimal"
 env_allowlist = []
+allow_project_local_bin_bare_executables = ["mf", "mustflow"]
 
 [resources.local_index_cache]
 description = "Generated mustflow SQLite local index under .mustflow/cache/."

package/templates/default/manifest.toml

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