mustflow 2.22.13 → 2.22.14

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

@@ -3,9 +3,11 @@ import { isMustflowBinName } from '../../core/command-classification.js';
 import { resolveSafeProjectCwd } from '../../core/command-cwd.js';
 import { resolveCommandEnv } from '../../core/command-env.js';
 import { evaluateCommandIntentEligibility, } from '../../core/command-intent-eligibility.js';
+import { inspectActiveRunLocks, } from '../../core/active-run-locks.js';
 import { isRecord, readPositiveInteger, readString, readStringArray, } from '../../core/config-loading.js';
 import { DEFAULT_COMMAND_MAX_OUTPUT_BYTES, COMMAND_OUTPUT_LIMIT_SCOPE, MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage, } from '../../core/command-output-limits.js';
 import { normalizeSuccessExitCodes } from '../../core/success-exit-codes.js';
+import { evaluateCommandPreconditions, } from '../../core/command-preconditions.js';
 import { t } from './i18n.js';
 function getSuccessExitCodes(intent) {
     return normalizeSuccessExitCodes(intent.success_exit_codes);
@@ -124,7 +126,7 @@ function readRunIntentMetadata(contract, intent) {
         relatedOneshotChecks: readStringArray(intent, 'related_oneshot_checks') ?? [],
     };
 }
-function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonCode, detail) {
+function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonCode, detail, preconditions = []) {
     const metadata = intent ? readRunIntentMetadata(contract, intent) : null;
     return {
         intentName,
@@ -160,6 +162,9 @@ function createBlockedRunPlan(contract, intentName, intent, eligibility, reasonC
         healthCheckUrl: metadata?.healthCheckUrl ?? null,
         stopInstruction: metadata?.stopInstruction ?? null,
         relatedOneshotChecks: metadata?.relatedOneshotChecks ?? [],
+        preconditions,
+        activeLockConflicts: [],
+        staleActiveLocks: [],
     };
 }
 export function createRunPlan(projectRoot, contract, intentName, options = {}) {
@@ -168,25 +173,27 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
     if (!isRecord(rawIntent)) {
         return createBlockedRunPlan(contract, intentName, undefined, eligibility, 'intent_not_table', eligibility.detail);
     }
+    const preconditions = evaluateCommandPreconditions(projectRoot, contract, intentName);
+    const activeLocks = inspectActiveRunLocks(projectRoot, contract, intentName);
     if (!eligibility.ok) {
-        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, eligibility.code, eligibility.detail);
+        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, eligibility.code, eligibility.detail, preconditions);
     }
     const metadata = readRunIntentMetadata(contract, rawIntent);
     const maxOutputBytesLimitDetail = getMaxOutputBytesLimitDetail(contract, rawIntent);
     if (maxOutputBytesLimitDetail) {
-        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, 'max_output_bytes_exceeds_limit', maxOutputBytesLimitDetail);
+        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, 'max_output_bytes_exceeds_limit', maxOutputBytesLimitDetail, preconditions);
     }
     let cwd;
     try {
         cwd = resolveSafeProjectCwd(projectRoot, metadata.configuredCwd);
     }
     catch (error) {
-        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, 'cwd_outside_project', error instanceof Error ? error.message : String(error));
+        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, 'cwd_outside_project', error instanceof Error ? error.message : String(error), preconditions);
     }
     const testTargets = commandAcceptsTestTargets(rawIntent) ? normalizeTestTargets(options.testTargets) : [];
     const commandArgv = metadata.commandArgv && testTargets.length > 0 ? [...metadata.commandArgv, ...testTargets] : metadata.commandArgv;
     if (!metadata.timeoutSeconds || !metadata.mode) {
-        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, !metadata.timeoutSeconds ? 'missing_timeout' : 'missing_command_source', !metadata.timeoutSeconds ? 'Intent timeout_seconds is missing or invalid.' : 'Intent does not define argv or shell cmd.');
+        return createBlockedRunPlan(contract, intentName, rawIntent, eligibility, !metadata.timeoutSeconds ? 'missing_timeout' : 'missing_command_source', !metadata.timeoutSeconds ? 'Intent timeout_seconds is missing or invalid.' : 'Intent does not define argv or shell cmd.', preconditions);
     }
     return {
         intentName,
@@ -222,6 +229,9 @@ export function createRunPlan(projectRoot, contract, intentName, options = {}) {
         healthCheckUrl: metadata.healthCheckUrl,
         stopInstruction: metadata.stopInstruction,
         relatedOneshotChecks: metadata.relatedOneshotChecks,
+        preconditions,
+        activeLockConflicts: activeLocks.conflicts,
+        staleActiveLocks: activeLocks.staleRecords,
     };
 }
 function formatTomlString(value) {
@@ -303,6 +313,9 @@ export function createRunPreview(plan, previewMode) {
         health_check_url: plan.healthCheckUrl,
         stop_instruction: plan.stopInstruction,
         related_oneshot_checks: plan.relatedOneshotChecks,
+        preconditions: plan.preconditions,
+        active_lock_conflicts: plan.activeLockConflicts,
+        stale_active_locks: plan.staleActiveLocks,
     };
 }
 export function renderRunPreviewText(plan, previewMode, lang = 'en') {
@@ -334,6 +347,19 @@ export function renderRunPreviewText(plan, previewMode, lang = 'en') {
     lines.push(`Cwd: ${plan.relativeCwd}`);
     lines.push(`Timeout: ${plan.timeoutSeconds}s`);
     lines.push(`Environment: ${plan.envPolicy}${plan.envAllowlist.length > 0 ? ` (${plan.envAllowlist.join(', ')})` : ''}`);
+    if (plan.preconditions.length > 0) {
+        lines.push('Preconditions:');
+        for (const precondition of plan.preconditions) {
+            const target = precondition.path ?? precondition.artifact ?? precondition.label ?? precondition.kind;
+            lines.push(`- ${precondition.kind} ${target}: ${precondition.status}`);
+        }
+    }
+    if (plan.activeLockConflicts.length > 0) {
+        lines.push('Active lock conflicts:');
+        for (const conflict of plan.activeLockConflicts) {
+            lines.push(`- ${conflict.lock}: ${conflict.detail}`);
+        }
+    }
     if (plan.commandArgv) {
         lines.push(`Argv: ${plan.commandArgv.join(' ')}`);
     }

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

@@ -0,0 +1,294 @@
+import { createHash } from 'node:crypto';
+import { existsSync, mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync, } from 'node:fs';
+import path from 'node:path';
+import { commandEffectsConflict, normalizeCommandEffects, } from './command-effects.js';
+const ACTIVE_LOCK_SCHEMA_VERSION = '1';
+const ACTIVE_LOCK_KIND = 'active_run_lock';
+const LOCK_ROOT_RELATIVE_PATH = '.mustflow/state/locks';
+const LOCK_MUTEX_STALE_MS = 30_000;
+const LOCK_MUTEX_WAIT_MS = 1_000;
+const LOCK_MUTEX_SLEEP_MS = 25;
+function sleep(milliseconds) {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, milliseconds);
+}
+function sha256(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function activeLockRoot(projectRoot) {
+    return path.join(projectRoot, ...LOCK_ROOT_RELATIVE_PATH.split('/'));
+}
+function activeLockDirectory(projectRoot) {
+    return path.join(activeLockRoot(projectRoot), 'active');
+}
+function activeLockMutexDirectory(projectRoot) {
+    return path.join(activeLockRoot(projectRoot), 'mutex');
+}
+function normalizeEffect(effect) {
+    return {
+        source: effect.source,
+        access: effect.access,
+        mode: effect.mode,
+        path: effect.path,
+        lock: effect.lock,
+        concurrency: effect.concurrency,
+    };
+}
+function isProcessLive(pid) {
+    if (!Number.isInteger(pid) || pid <= 0) {
+        return false;
+    }
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        const code = error && typeof error === 'object' && 'code' in error ? String(error.code) : '';
+        return code === 'EPERM';
+    }
+}
+function commandEffectsFromRecord(record) {
+    return record.effects.map((effect) => ({
+        intent: record.intent,
+        source: effect.source === 'writes' ? 'writes' : 'effects',
+        access: effect.access === 'read' ? 'read' : 'write',
+        mode: effect.mode === 'read' ? 'read' :
+            effect.mode === 'append' ? 'append' :
+                effect.mode === 'replace' ? 'replace' :
+                    effect.mode === 'delete_recreate' ? 'delete_recreate' :
+                        'write',
+        path: effect.path,
+        lock: effect.lock,
+        concurrency: effect.concurrency === 'shared' ? 'shared' : 'exclusive',
+    }));
+}
+function activeLockRecordPath(projectRoot, runId) {
+    return path.join(activeLockDirectory(projectRoot), `${sha256(runId)}.json`);
+}
+function parseRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return null;
+    }
+    const record = value;
+    if (record.schema_version !== ACTIVE_LOCK_SCHEMA_VERSION ||
+        record.kind !== ACTIVE_LOCK_KIND ||
+        typeof record.run_id !== 'string' ||
+        typeof record.intent !== 'string' ||
+        !Number.isInteger(record.pid) ||
+        typeof record.started_at !== 'string' ||
+        typeof record.root_hash !== 'string' ||
+        !(typeof record.command_hash === 'string' || record.command_hash === null) ||
+        !Array.isArray(record.effects) ||
+        !Array.isArray(record.writes)) {
+        return null;
+    }
+    const effects = record.effects.filter((effect) => {
+        if (!effect || typeof effect !== 'object' || Array.isArray(effect)) {
+            return false;
+        }
+        const candidate = effect;
+        return (typeof candidate.source === 'string' &&
+            typeof candidate.access === 'string' &&
+            typeof candidate.mode === 'string' &&
+            (typeof candidate.path === 'string' || candidate.path === null) &&
+            typeof candidate.lock === 'string' &&
+            typeof candidate.concurrency === 'string');
+    });
+    const writes = record.writes.filter((write) => typeof write === 'string');
+    if (effects.length !== record.effects.length || writes.length !== record.writes.length) {
+        return null;
+    }
+    return {
+        schema_version: ACTIVE_LOCK_SCHEMA_VERSION,
+        kind: ACTIVE_LOCK_KIND,
+        run_id: record.run_id,
+        intent: record.intent,
+        pid: Number(record.pid),
+        started_at: record.started_at,
+        root_hash: record.root_hash,
+        command_hash: record.command_hash,
+        effects,
+        writes,
+    };
+}
+function readActiveRecords(projectRoot) {
+    const directory = activeLockDirectory(projectRoot);
+    if (!existsSync(directory)) {
+        return [];
+    }
+    const records = [];
+    for (const name of readdirSync(directory).filter((entry) => entry.endsWith('.json')).sort()) {
+        try {
+            const record = parseRecord(JSON.parse(readFileSync(path.join(directory, name), 'utf8')));
+            if (record) {
+                records.push(record);
+            }
+        }
+        catch {
+            // Unreadable lock records are ignored until a later cleanup can inspect them safely.
+        }
+    }
+    return records;
+}
+function staleRecordFor(record) {
+    if (isProcessLive(record.pid)) {
+        return null;
+    }
+    return {
+        runId: record.run_id,
+        intent: record.intent,
+        pid: record.pid,
+        reason: 'process_not_live',
+    };
+}
+function removeRecord(projectRoot, record) {
+    rmSync(activeLockRecordPath(projectRoot, record.run_id), { force: true });
+}
+function conflictDetail(current, active) {
+    return `lock "${current.lock}" conflicts with active intent "${active.intent}"`;
+}
+function findConflicts(intentName, effects, records) {
+    const conflicts = [];
+    for (const record of records) {
+        for (const activeEffect of commandEffectsFromRecord(record)) {
+            for (const effect of effects) {
+                if (!commandEffectsConflict(effect, activeEffect)) {
+                    continue;
+                }
+                conflicts.push({
+                    intent: intentName,
+                    pid: process.pid,
+                    lock: effect.lock,
+                    path: effect.path,
+                    mode: effect.mode,
+                    concurrency: effect.concurrency,
+                    conflictsWithIntent: record.intent,
+                    conflictsWithPid: record.pid,
+                    conflictsWithMode: activeEffect.mode,
+                    detail: conflictDetail(effect, activeEffect),
+                });
+            }
+        }
+    }
+    return conflicts;
+}
+function createRecord(projectRoot, intentName, effects, commandHash) {
+    const startedAt = new Date().toISOString();
+    const writes = effects
+        .filter((effect) => effect.access === 'write' && effect.path !== null)
+        .map((effect) => effect.path)
+        .sort((left, right) => left.localeCompare(right));
+    const runId = `${process.pid}:${startedAt}:${intentName}:${sha256(JSON.stringify(effects))}`;
+    return {
+        schema_version: ACTIVE_LOCK_SCHEMA_VERSION,
+        kind: ACTIVE_LOCK_KIND,
+        run_id: runId,
+        intent: intentName,
+        pid: process.pid,
+        started_at: startedAt,
+        root_hash: sha256(path.resolve(projectRoot)),
+        command_hash: commandHash,
+        effects: effects.map(normalizeEffect),
+        writes: [...new Set(writes)],
+    };
+}
+function acquireMutex(projectRoot) {
+    const root = activeLockRoot(projectRoot);
+    const mutex = activeLockMutexDirectory(projectRoot);
+    mkdirSync(root, { recursive: true });
+    const startedAt = Date.now();
+    while (true) {
+        try {
+            mkdirSync(mutex);
+            writeFileSync(path.join(mutex, 'owner.json'), JSON.stringify({ pid: process.pid, started_at: new Date().toISOString() }, null, 2));
+            return () => rmSync(mutex, { recursive: true, force: true });
+        }
+        catch (error) {
+            if (!error || typeof error !== 'object' || !('code' in error) || error.code !== 'EEXIST') {
+                throw error;
+            }
+            if (Date.now() - startedAt > LOCK_MUTEX_WAIT_MS) {
+                const ownerPath = path.join(mutex, 'owner.json');
+                try {
+                    const owner = JSON.parse(readFileSync(ownerPath, 'utf8'));
+                    const ownerPid = Number(owner.pid);
+                    const ownerStartedAt = typeof owner.started_at === 'string' ? Date.parse(owner.started_at) : Number.NaN;
+                    const staleByAge = Number.isFinite(ownerStartedAt) && Date.now() - ownerStartedAt > LOCK_MUTEX_STALE_MS;
+                    if (!isProcessLive(ownerPid) || staleByAge) {
+                        rmSync(mutex, { recursive: true, force: true });
+                        continue;
+                    }
+                }
+                catch {
+                    rmSync(mutex, { recursive: true, force: true });
+                    continue;
+                }
+                throw new Error('active_run_lock_mutex_busy');
+            }
+            sleep(LOCK_MUTEX_SLEEP_MS);
+        }
+    }
+}
+export function inspectActiveRunLocks(projectRoot, contract, intentName) {
+    const effects = normalizeCommandEffects(projectRoot, contract, intentName);
+    const records = readActiveRecords(projectRoot);
+    const staleRecords = records.map(staleRecordFor).filter((record) => record !== null);
+    const liveRecords = records.filter((record) => !staleRecords.some((stale) => stale.runId === record.run_id));
+    return {
+        conflicts: findConflicts(intentName, effects, liveRecords),
+        staleRecords,
+    };
+}
+export function acquireActiveRunLock(projectRoot, contract, intentName, options = {}) {
+    const effects = normalizeCommandEffects(projectRoot, contract, intentName);
+    if (effects.length === 0) {
+        const emptyRecord = createRecord(projectRoot, intentName, [], options.commandHash ?? null);
+        return {
+            ok: true,
+            handle: {
+                record: emptyRecord,
+                recoveredStaleRecords: [],
+                release() {
+                    // No declared effects means no active lock record was written.
+                },
+            },
+        };
+    }
+    mkdirSync(activeLockDirectory(projectRoot), { recursive: true });
+    const releaseMutex = acquireMutex(projectRoot);
+    try {
+        const records = readActiveRecords(projectRoot);
+        const staleRecords = records.map(staleRecordFor).filter((record) => record !== null);
+        for (const stale of staleRecords) {
+            const staleRecord = records.find((record) => record.run_id === stale.runId);
+            if (staleRecord) {
+                removeRecord(projectRoot, staleRecord);
+            }
+        }
+        const liveRecords = records.filter((record) => !staleRecords.some((stale) => stale.runId === record.run_id));
+        const conflicts = findConflicts(intentName, effects, liveRecords);
+        if (conflicts.length > 0) {
+            return { ok: false, conflicts, recoveredStaleRecords: staleRecords };
+        }
+        const record = createRecord(projectRoot, intentName, effects, options.commandHash ?? null);
+        const recordPath = activeLockRecordPath(projectRoot, record.run_id);
+        writeFileSync(recordPath, JSON.stringify(record, null, 2));
+        let released = false;
+        return {
+            ok: true,
+            handle: {
+                record,
+                recoveredStaleRecords: staleRecords,
+                release() {
+                    if (released) {
+                        return;
+                    }
+                    released = true;
+                    rmSync(recordPath, { force: true });
+                },
+            },
+        };
+    }
+    finally {
+        releaseMutex();
+    }
+}

package/dist/core/check-issues.js

@@ -15,6 +15,14 @@ const CHECK_ISSUE_ID_RULES = [
         'mustflow.command_contract.success_exit_codes_invalid',
         /^\[commands\.intents\.[^\]]+\]\.success_exit_codes must be a non-empty integer array with values from 0 through 255$/u,
     ],
+    [
+        'mustflow.command_contract.inputs_invalid',
+        /^(?:Configured intent [^\s]+ must not declare inputs|\[commands\.intents\..+\.inputs(?:\.|\])|Command input [^\s]+ name must|Command argv token "[^"]+" (?:references undeclared input|must use a whole-token typed input placeholder))/u,
+    ],
+    [
+        'mustflow.command_contract.preconditions_invalid',
+        /^\[commands\.intents\..+\.preconditions(?:\.|\]|\s)/u,
+    ],
     ['mustflow.command_contract.effects_invalid', /^(?:Strict: )?(?:\[commands\.(?:resources|intents\.[^\]]+\.effects)[^\]]*\]|Command effect for intent [^\s]+ must define path, paths, or lock)/u],
     ['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],

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

@@ -3,9 +3,16 @@ 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 { COMMAND_PRECONDITION_KINDS } from './command-preconditions.js';
 import { commandIntentBlockedCommandPattern, commandIntentHasCommandSource, commandIntentNameIsSafe, } from './command-contract-rules.js';
 import { MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage } from './command-output-limits.js';
 import { SUCCESS_EXIT_CODES_CONTRACT_DESCRIPTION, successExitCodesAreValid } from './success-exit-codes.js';
+const COMMAND_INPUT_TYPES = new Set(['path', 'enum', 'boolean', 'integer', 'literal']);
+const COMMAND_INPUT_NAME_PATTERN = /^[a-z][a-z0-9_]*$/u;
+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;
 function commandContractIssue(message, id) {
     return id ? { id, message } : { message };
 }
@@ -18,6 +25,9 @@ function hasOwn(table, key) {
 function isPositiveInteger(value) {
     return Number.isInteger(value) && Number(value) > 0;
 }
+function isInteger(value) {
+    return Number.isInteger(value);
+}
 function validateTable(config, tableName, issues) {
     if (!hasOwn(config, tableName)) {
         return undefined;
@@ -53,6 +63,11 @@ function validatePositiveIntegerField(table, key, label, issues) {
         issues.push(commandContractIssue(`${label} must be a positive integer`));
     }
 }
+function validateIntegerField(table, key, label, issues, id) {
+    if (hasOwn(table, key) && !isInteger(table[key])) {
+        issues.push(commandContractIssue(`${label} must be an integer`, id));
+    }
+}
 function validateMaxOutputBytesField(table, key, label, issues) {
     validatePositiveIntegerField(table, key, label, issues);
     if (isPositiveInteger(table[key]) && Number(table[key]) > MAX_COMMAND_OUTPUT_BYTES) {
@@ -67,6 +82,166 @@ function validateAllowedStringField(table, key, label, allowedValues, issues) {
         issues.push(commandContractIssue(`${label} must be ${Array.from(allowedValues).map((value) => `"${value}"`).join(' or ')}`));
     }
 }
+function normalizeContractPath(value) {
+    return value.trim().replace(/\\/gu, '/');
+}
+function contractPathIsUnsafe(value) {
+    const normalized = normalizeContractPath(value);
+    const segments = normalized.split('/').filter((segment) => segment.length > 0);
+    return (normalized.length === 0 ||
+        normalized.includes('\0') ||
+        normalized.startsWith('/') ||
+        path.win32.isAbsolute(value) ||
+        path.posix.isAbsolute(value) ||
+        segments.some((segment) => segment === '.' || segment === '..' || WINDOWS_RESERVED_PATH_SEGMENTS.test(segment)));
+}
+function validateSafeRelativePathArrayField(table, key, label, issues) {
+    validateStringArrayField(table, key, label, issues);
+    if (!Array.isArray(table[key])) {
+        return;
+    }
+    for (const entry of table[key]) {
+        if (typeof entry === 'string' && contractPathIsUnsafe(entry)) {
+            issues.push(commandContractIssue(`${label} entry "${entry}" must be a normalized repository-relative path without traversal or reserved device names`, 'mustflow.command_contract.inputs_invalid'));
+        }
+    }
+}
+function validateAllowedExtensionsField(table, key, label, issues) {
+    validateStringArrayField(table, key, label, issues);
+    if (!Array.isArray(table[key])) {
+        return;
+    }
+    for (const entry of table[key]) {
+        if (typeof entry === 'string' && !SAFE_PATH_EXTENSION_PATTERN.test(entry)) {
+            issues.push(commandContractIssue(`${label} entry "${entry}" must start with "." and contain only letters, numbers, dots, underscores, or hyphens`, 'mustflow.command_contract.inputs_invalid'));
+        }
+    }
+}
+function validateCommandInputDefinition(intentName, inputName, input, issues) {
+    const label = `[commands.intents.${intentName}.inputs.${inputName}]`;
+    if (!COMMAND_INPUT_NAME_PATTERN.test(inputName)) {
+        issues.push(commandContractIssue(`Command input ${intentName}.${inputName} name must start with a lowercase letter and contain only lowercase letters, numbers, and underscores`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    validateAllowedStringField(input, 'type', `${label}.type`, COMMAND_INPUT_TYPES, issues);
+    validateBooleanField(input, 'required', `${label}.required`, issues);
+    validateBooleanField(input, 'secret', `${label}.secret`, issues);
+    validateStringField(input, 'description', `${label}.description`, issues);
+    validateStringField(input, 'placeholder', `${label}.placeholder`, issues);
+    validateStringArrayField(input, 'allowed_values', `${label}.allowed_values`, issues);
+    validateSafeRelativePathArrayField(input, 'allowed_roots', `${label}.allowed_roots`, issues);
+    validateAllowedExtensionsField(input, 'allowed_extensions', `${label}.allowed_extensions`, issues);
+    validateIntegerField(input, 'min', `${label}.min`, issues, 'mustflow.command_contract.inputs_invalid');
+    validateIntegerField(input, 'max', `${label}.max`, issues, 'mustflow.command_contract.inputs_invalid');
+    if (input.type === 'path' && (!Array.isArray(input.allowed_roots) || input.allowed_roots.length === 0)) {
+        issues.push(commandContractIssue(`${label}.allowed_roots must define at least one repository-relative root for path inputs`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (input.type === 'enum' && (!Array.isArray(input.allowed_values) || input.allowed_values.length === 0)) {
+        issues.push(commandContractIssue(`${label}.allowed_values must define at least one value for enum inputs`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (input.type === 'literal' && !hasOwn(input, 'value')) {
+        issues.push(commandContractIssue(`${label}.value must be defined for literal inputs`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (hasOwn(input, 'value') && !['string', 'number', 'boolean'].includes(typeof input.value)) {
+        issues.push(commandContractIssue(`${label}.value must be a string, number, or boolean`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (isInteger(input.min) && isInteger(input.max) && Number(input.min) > Number(input.max)) {
+        issues.push(commandContractIssue(`${label}.min must be less than or equal to ${label}.max`, 'mustflow.command_contract.inputs_invalid'));
+    }
+}
+function validateCommandIntentInputs(intentName, intent, issues) {
+    if (!hasOwn(intent, 'inputs')) {
+        return;
+    }
+    if (!isRecord(intent.inputs)) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}.inputs] must be a TOML table`, 'mustflow.command_contract.inputs_invalid'));
+        return;
+    }
+    if (intent.status === 'configured') {
+        issues.push(commandContractIssue(`Configured intent ${intentName} must not declare inputs until typed input execution is implemented`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (intent.mode === 'shell' || hasOwn(intent, 'cmd')) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}.inputs] requires argv command mode; shell-string interpolation is not allowed`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    if (!Array.isArray(intent.argv)) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}.inputs] requires argv so typed input placeholders remain argument-bound`, 'mustflow.command_contract.inputs_invalid'));
+    }
+    const inputNames = new Set();
+    for (const [inputName, input] of Object.entries(intent.inputs)) {
+        inputNames.add(inputName);
+        if (!isRecord(input)) {
+            issues.push(commandContractIssue(`[commands.intents.${intentName}.inputs.${inputName}] must be a TOML table`, 'mustflow.command_contract.inputs_invalid'));
+            continue;
+        }
+        validateCommandInputDefinition(intentName, inputName, input, issues);
+    }
+    const argv = readStringArray(intent, 'argv');
+    if (!argv) {
+        return;
+    }
+    for (const token of argv) {
+        const exactMatch = COMMAND_ARGV_PLACEHOLDER_PATTERN.exec(token);
+        if (exactMatch) {
+            const inputName = exactMatch[1];
+            if (!inputNames.has(inputName)) {
+                issues.push(commandContractIssue(`Command argv token "${token}" references undeclared input ${intentName}.${inputName}`, 'mustflow.command_contract.inputs_invalid'));
+            }
+            continue;
+        }
+        if (COMMAND_ARGV_MIXED_PLACEHOLDER_PATTERN.test(token)) {
+            issues.push(commandContractIssue(`Command argv token "${token}" must use a whole-token typed input placeholder instead of string interpolation`, 'mustflow.command_contract.inputs_invalid'));
+        }
+    }
+}
+function validateSafeRelativePathField(table, key, label, issues) {
+    validateStringField(table, key, label, issues);
+    if (typeof table[key] === 'string' && contractPathIsUnsafe(table[key])) {
+        issues.push(commandContractIssue(`${label} must be a normalized repository-relative path without traversal or reserved device names`, 'mustflow.command_contract.preconditions_invalid'));
+    }
+}
+function validateSafeRelativePathPatternArrayField(table, key, label, issues) {
+    validateStringArrayField(table, key, label, issues);
+    if (!Array.isArray(table[key])) {
+        return;
+    }
+    for (const entry of table[key]) {
+        if (typeof entry === 'string' && contractPathIsUnsafe(entry.replace(/\*/gu, 'wildcard'))) {
+            issues.push(commandContractIssue(`${label} entry "${entry}" must be a normalized repository-relative path pattern without traversal or reserved device names`, 'mustflow.command_contract.preconditions_invalid'));
+        }
+    }
+}
+function validateCommandIntentPreconditions(intentName, intent, allIntents, issues) {
+    if (!hasOwn(intent, 'preconditions')) {
+        return;
+    }
+    if (!Array.isArray(intent.preconditions) || intent.preconditions.some((entry) => !isRecord(entry))) {
+        issues.push(commandContractIssue(`[commands.intents.${intentName}].preconditions must be an array of tables`, 'mustflow.command_contract.preconditions_invalid'));
+        return;
+    }
+    for (const [index, precondition] of intent.preconditions.entries()) {
+        const preconditionTable = precondition;
+        const label = `[commands.intents.${intentName}.preconditions.${index}]`;
+        validateAllowedStringField(preconditionTable, 'kind', `${label}.kind`, COMMAND_PRECONDITION_KINDS, issues);
+        validateStringField(preconditionTable, 'label', `${label}.label`, issues);
+        validateSafeRelativePathField(preconditionTable, 'path', `${label}.path`, issues);
+        validateSafeRelativePathField(preconditionTable, 'artifact', `${label}.artifact`, issues);
+        validateSafeRelativePathPatternArrayField(preconditionTable, 'sources', `${label}.sources`, issues);
+        validateStringField(preconditionTable, 'satisfy_intent', `${label}.satisfy_intent`, issues);
+        if (preconditionTable.kind === 'path_exists' && !hasOwn(preconditionTable, 'path')) {
+            issues.push(commandContractIssue(`${label}.path is required for kind = "path_exists"`, 'mustflow.command_contract.preconditions_invalid'));
+        }
+        if (preconditionTable.kind === 'artifact_freshness') {
+            if (!hasOwn(preconditionTable, 'artifact')) {
+                issues.push(commandContractIssue(`${label}.artifact is required for kind = "artifact_freshness"`, 'mustflow.command_contract.preconditions_invalid'));
+            }
+            if (!Array.isArray(preconditionTable.sources) || preconditionTable.sources.length === 0) {
+                issues.push(commandContractIssue(`${label}.sources must define at least one source path pattern for kind = "artifact_freshness"`, 'mustflow.command_contract.preconditions_invalid'));
+            }
+        }
+        if (typeof preconditionTable.satisfy_intent === 'string' && !isRecord(allIntents[preconditionTable.satisfy_intent])) {
+            issues.push(commandContractIssue(`${label}.satisfy_intent references unknown intent "${preconditionTable.satisfy_intent}"`, 'mustflow.command_contract.preconditions_invalid'));
+        }
+    }
+}
 function validateCommandDefaults(commandsToml, issues) {
     const defaults = validateTable(commandsToml, 'defaults', issues);
     if (!defaults) {
@@ -152,7 +327,7 @@ function validateCommandIntentSelection(intentName, intent, issues) {
         issues.push(commandContractIssue(`[commands.intents.${intentName}.selection].accepts_test_targets requires argv command mode`));
     }
 }
-function validateCommandIntent(intentName, intent, issues) {
+function validateCommandIntent(intentName, intent, allIntents, issues) {
     if (!commandIntentNameIsSafe(intentName)) {
         issues.push(commandContractIssue(`Intent ${intentName} name must contain only letters, numbers, underscores, and hyphens`));
     }
@@ -165,6 +340,8 @@ function validateCommandIntent(intentName, intent, 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);
+    validateCommandIntentInputs(intentName, intent, issues);
+    validateCommandIntentPreconditions(intentName, intent, allIntents, issues);
     if (intent.status !== 'configured') {
         return;
     }
@@ -346,7 +523,7 @@ export function validateCommandContractConfig(commandsToml) {
             issues.push(commandContractIssue(`Intent ${intentName} must be a TOML table`, 'mustflow.command_contract.intent_not_table'));
             continue;
         }
-        validateCommandIntent(intentName, intent, issues);
+        validateCommandIntent(intentName, intent, commandsToml.intents, issues);
     }
     return issues;
 }