mustflow 2.18.0 → 2.18.2

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

@@ -1,11 +1,14 @@
 import { COMMAND_LIFECYCLES, COMMAND_RUN_POLICIES, LONG_RUNNING_LIFECYCLES, isRecord, } from './config-loading.js';
-import { COMMAND_ENV_POLICIES } from './command-env.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 { MAX_COMMAND_OUTPUT_BYTES, commandMaxOutputBytesLimitMessage } from './command-output-limits.js';
 function commandContractIssue(message) {
     return { message };
 }
+function commandContractWarning(message) {
+    return { message, severity: 'warning' };
+}
 function hasOwn(table, key) {
     return Object.prototype.hasOwnProperty.call(table, key);
 }
@@ -198,6 +201,50 @@ function validateCommandIntent(intentName, intent, issues) {
     }
     validateCommandIntentEffects(intentName, intent, issues);
 }
+function readValidCommandEnvPolicy(table) {
+    if (!table || !hasOwn(table, 'env_policy')) {
+        return undefined;
+    }
+    const value = table.env_policy;
+    return typeof value === 'string' && COMMAND_ENV_POLICIES.has(value)
+        ? value
+        : undefined;
+}
+function getEffectiveCommandEnvPolicy(defaults, intent) {
+    const intentPolicy = readValidCommandEnvPolicy(intent);
+    if (intentPolicy) {
+        return { policy: intentPolicy, source: 'intent' };
+    }
+    const defaultPolicy = readValidCommandEnvPolicy(defaults);
+    if (defaultPolicy) {
+        return { policy: defaultPolicy, source: 'defaults' };
+    }
+    return { policy: DEFAULT_COMMAND_ENV_POLICY, source: 'implicit' };
+}
+function validateCommandEnvInheritanceWarnings(commandsToml) {
+    const issues = [];
+    if (!commandsToml || !isRecord(commandsToml.intents)) {
+        return issues;
+    }
+    const defaults = isRecord(commandsToml.defaults) ? commandsToml.defaults : undefined;
+    for (const [intentName, intent] of Object.entries(commandsToml.intents)) {
+        if (!isRecord(intent) || intent.status !== 'configured' || intent.run_policy !== 'agent_allowed') {
+            continue;
+        }
+        const envPolicy = getEffectiveCommandEnvPolicy(defaults, intent);
+        if (envPolicy.policy !== 'inherit') {
+            continue;
+        }
+        const networkScope = intent.network === true ? ' with network = true' : '';
+        const migration = 'set env_policy = "minimal" or "allowlist" unless broad host state is required';
+        if (envPolicy.source === 'implicit') {
+            issues.push(commandContractWarning(`configured agent-runnable intent ${intentName} implicitly inherits the host environment${networkScope}; ${migration}`));
+            continue;
+        }
+        issues.push(commandContractWarning(`configured agent-runnable intent ${intentName} uses env_policy = "inherit"${networkScope}; ${migration}`));
+    }
+    return issues;
+}
 /**
  * mf:anchor core.command-contract-validation
  * purpose: Validate command intent declarations that gate agent-executable repository commands.
@@ -228,15 +275,18 @@ export function validateCommandContractConfig(commandsToml) {
 }
 export function validateCommandContractStrictDefaults(projectRoot, commandsToml) {
     const issues = [];
-    if (!commandsToml || !isRecord(commandsToml.defaults)) {
+    if (!commandsToml) {
         return issues;
     }
-    if (!hasOwn(commandsToml.defaults, 'max_output_bytes')) {
-        issues.push(commandContractIssue('[commands.defaults].max_output_bytes is required'));
-    }
-    if (!hasOwn(commandsToml.defaults, 'on_timeout')) {
-        issues.push(commandContractIssue('[commands.defaults].on_timeout is required'));
+    if (isRecord(commandsToml.defaults)) {
+        if (!hasOwn(commandsToml.defaults, 'max_output_bytes')) {
+            issues.push(commandContractIssue('[commands.defaults].max_output_bytes is required'));
+        }
+        if (!hasOwn(commandsToml.defaults, 'on_timeout')) {
+            issues.push(commandContractIssue('[commands.defaults].on_timeout is required'));
+        }
     }
+    issues.push(...validateCommandEnvInheritanceWarnings(commandsToml));
     issues.push(...validateCommandEffects(projectRoot, commandsToml));
     issues.push(...validateCommandEffectLockWarnings(commandsToml));
     return issues;

package/dist/core/completion-verdict.js

@@ -244,7 +244,8 @@ export function createDashboardCompletionVerdict(input) {
     const receiptBinding = input.receiptBinding ?? emptyReceiptBindingEvidence();
     const latestRunFailed = input.latestRunStatus === 'failed' ||
         input.latestRunStatus === 'timed_out' ||
-        input.latestRunStatus === 'start_failed';
+        input.latestRunStatus === 'start_failed' ||
+        input.latestRunStatus === 'output_limit_exceeded';
     let status = 'unverified';
     let primaryReason = 'dashboard_does_not_execute_verification';
     const blockers = [];

package/dist/core/public-json-contracts.js

@@ -135,7 +135,7 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
     {
         id: 'verify-run-manifest',
         schemaFile: 'verify-run-manifest.schema.json',
-        producer: '.mustflow/state/runs/verify-latest/manifest.json',
+        producer: '.mustflow/state/runs/verify-*/manifest.json',
         packaged: true,
         documented: true,
     },

package/dist/core/run-receipt.js

@@ -1,6 +1,7 @@
-import { mkdirSync, writeFileSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import path from 'node:path';
+import { atomicWriteJsonFile, createStateRunId } from './atomic-state-write.js';
+import { decodeUtf8Tail } from './bounded-output.js';
 import { DEFAULT_RUN_RECEIPT_TAIL_BYTES } from './retention-policy.js';
 import { redactSecretLikeText } from './secret-redaction.js';
 const RUN_RECEIPT_SCHEMA_VERSION = '1';
@@ -11,13 +12,7 @@ function toPosixPath(value) {
 }
 function truncateTextByBytes(text, maxBytes) {
     const buffer = Buffer.from(text, 'utf8');
-    if (buffer.byteLength <= maxBytes) {
-        return { text, truncated: false };
-    }
-    return {
-        text: buffer.subarray(buffer.byteLength - maxBytes).toString('utf8'),
-        truncated: true,
-    };
+    return decodeUtf8Tail(buffer, maxBytes);
 }
 function recordRedaction(state, field, result) {
     if (!result.redacted) {
@@ -62,8 +57,11 @@ function summarizeOutput(output, maxOutputBytes, tailBytes, field, state) {
         redaction_kinds: redaction.redactionKinds,
     };
 }
-function getReceiptRelativePath() {
-    return toPosixPath(path.join(RUN_RECEIPT_DIR, LATEST_RUN_RECEIPT));
+export function createRunReceiptRelativePath() {
+    return toPosixPath(path.join(RUN_RECEIPT_DIR, createStateRunId('run'), 'receipt.json'));
+}
+function getReceiptRelativePath(receiptPath) {
+    return receiptPath ?? toPosixPath(path.join(RUN_RECEIPT_DIR, LATEST_RUN_RECEIPT));
 }
 function stableJson(value) {
     if (Array.isArray(value)) {
@@ -100,6 +98,9 @@ function getErrorKind(status, exitCode) {
     if (status === 'start_failed') {
         return 'start_failed';
     }
+    if (status === 'output_limit_exceeded') {
+        return 'output_limit_exceeded';
+    }
     if (status === 'failed' && exitCode !== null) {
         return 'exit_code';
     }
@@ -240,6 +241,7 @@ export function createRunReceipt(input) {
         signal: input.signal,
         error,
         kill_method: input.killMethod,
+        ...(input.termination ? { termination: input.termination } : {}),
         stdout,
         stderr,
         write_drift: input.writeDrift,
@@ -272,12 +274,17 @@ export function createRunReceipt(input) {
             redaction_kinds: [...redactionState.kinds].sort(),
             fields: [...redactionState.fields].sort(),
         },
-        receipt_path: getReceiptRelativePath(),
+        receipt_path: getReceiptRelativePath(input.receiptPath),
     };
 }
 export function writeRunReceipt(projectRoot, receipt) {
     const receiptDir = path.join(projectRoot, RUN_RECEIPT_DIR);
     const latestPath = path.join(receiptDir, LATEST_RUN_RECEIPT);
-    mkdirSync(receiptDir, { recursive: true });
-    writeFileSync(latestPath, `${JSON.stringify(receipt, null, 2)}\n`);
+    const receiptPath = path.resolve(projectRoot, receipt.receipt_path);
+    const relativeToRunDir = path.relative(receiptDir, receiptPath);
+    if (relativeToRunDir.startsWith('..') || path.isAbsolute(relativeToRunDir)) {
+        throw new Error(`Run receipt path must stay inside ${RUN_RECEIPT_DIR}`);
+    }
+    atomicWriteJsonFile(receiptPath, receipt);
+    atomicWriteJsonFile(latestPath, receipt);
 }

package/dist/core/source-anchors.js

@@ -1,4 +1,4 @@
-import { existsSync, readdirSync, readFileSync, statSync } from 'node:fs';
+import { existsSync, readdirSync, readFileSync, realpathSync, statSync } from 'node:fs';
 import path from 'node:path';
 import { SECRET_LIKE_PATTERNS, textContainsSecretLike } from './secret-redaction.js';
 export const SOURCE_ANCHOR_EXTENSIONS = new Set(['.cjs', '.go', '.js', '.jsx', '.mjs', '.py', '.rs', '.ts', '.tsx']);
@@ -49,23 +49,94 @@ export const SOURCE_ANCHOR_SECRET_LIKE_PATTERNS = SECRET_LIKE_PATTERNS;
 function toPosixPath(value) {
     return value.split(path.sep).join('/');
 }
-function listFilesRecursive(root, ignoredDirectoryNames, current = root) {
+function pathIsInsideRoot(rootRealPath, candidateRealPath) {
+    const relative = path.relative(rootRealPath, candidateRealPath);
+    return relative.length === 0 || (!relative.startsWith('..') && !path.isAbsolute(relative));
+}
+function shouldIncludeSourceAnchorFile(relativePath, options) {
+    if (!options.allowedExtensions.has(path.posix.extname(relativePath))) {
+        return false;
+    }
+    if (options.excludeGeneratedOrVendor && sourceAnchorPathIsGeneratedOrVendor(relativePath)) {
+        return false;
+    }
+    if (options.include.length > 0 && !matchesAnyGlob(relativePath, options.include)) {
+        return false;
+    }
+    if (options.exclude.length > 0 && matchesAnyGlob(relativePath, options.exclude)) {
+        return false;
+    }
+    return true;
+}
+function fileIsWithinSizeLimit(filePath, maxFileBytes) {
+    if (typeof maxFileBytes !== 'number' || !Number.isFinite(maxFileBytes) || maxFileBytes <= 0) {
+        return true;
+    }
+    try {
+        return statSync(filePath).size <= maxFileBytes;
+    }
+    catch {
+        return false;
+    }
+}
+function listFilesRecursive(root, options, current = root) {
     if (!existsSync(current)) {
         return [];
     }
+    const currentRealPath = realpathSync(current);
+    if (!pathIsInsideRoot(options.rootRealPath, currentRealPath) || options.visitedRealDirectories.has(currentRealPath)) {
+        return [];
+    }
+    options.visitedRealDirectories.add(currentRealPath);
     const files = [];
-    for (const entry of readdirSync(current)) {
-        const entryPath = path.join(current, entry);
-        const stat = statSync(entryPath);
-        if (stat.isDirectory()) {
-            if (ignoredDirectoryNames.has(entry)) {
+    const entries = readdirSync(current, { withFileTypes: true }).sort((left, right) => left.name.localeCompare(right.name));
+    for (const entry of entries) {
+        const entryPath = path.join(current, entry.name);
+        if (options.ignoredDirectoryNames.has(entry.name)) {
+            continue;
+        }
+        if (entry.isDirectory()) {
+            files.push(...listFilesRecursive(root, options, entryPath));
+            continue;
+        }
+        if (entry.isSymbolicLink()) {
+            if (!options.followSymlinks) {
                 continue;
             }
-            files.push(...listFilesRecursive(root, ignoredDirectoryNames, entryPath));
+            let realPath;
+            try {
+                realPath = realpathSync(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (!pathIsInsideRoot(options.rootRealPath, realPath)) {
+                continue;
+            }
+            let stat;
+            try {
+                stat = statSync(entryPath);
+            }
+            catch {
+                continue;
+            }
+            if (stat.isDirectory()) {
+                files.push(...listFilesRecursive(root, options, entryPath));
+                continue;
+            }
+            if (stat.isFile()) {
+                const relativePath = toPosixPath(path.relative(root, entryPath));
+                if (shouldIncludeSourceAnchorFile(relativePath, options) && fileIsWithinSizeLimit(entryPath, options.maxFileBytes)) {
+                    files.push(relativePath);
+                }
+            }
             continue;
         }
-        if (stat.isFile()) {
-            files.push(path.relative(root, entryPath));
+        if (entry.isFile()) {
+            const relativePath = toPosixPath(path.relative(root, entryPath));
+            if (shouldIncludeSourceAnchorFile(relativePath, options) && fileIsWithinSizeLimit(entryPath, options.maxFileBytes)) {
+                files.push(relativePath);
+            }
         }
     }
     return files.sort((left, right) => left.localeCompare(right));
@@ -127,25 +198,26 @@ function normalizeAllowedExtensions(allowedExtensions) {
 function mergeIgnoredDirectoryNames(ignoredDirectoryNames) {
     return new Set([...(ignoredDirectoryNames ?? []), ...SOURCE_ANCHOR_DEFAULT_EXCLUDED_PATH_PARTS]);
 }
-function fileIsWithinSizeLimit(root, relativePath, maxFileBytes) {
-    if (typeof maxFileBytes !== 'number' || !Number.isFinite(maxFileBytes) || maxFileBytes <= 0) {
-        return true;
-    }
-    const filePath = path.join(root, ...relativePath.split('/'));
-    return statSync(filePath).size <= maxFileBytes;
-}
 export function listSourceAnchorFiles(root, options = {}) {
+    if (!existsSync(root)) {
+        return [];
+    }
     const ignoredDirectoryNames = mergeIgnoredDirectoryNames(options.ignoredDirectoryNames);
     const allowedExtensions = normalizeAllowedExtensions(options.allowedExtensions);
     const include = (options.include ?? []).map((pattern) => globToRegExp(pattern));
     const exclude = (options.exclude ?? []).map((pattern) => globToRegExp(pattern));
-    return listFilesRecursive(root, ignoredDirectoryNames)
-        .map((relativePath) => toPosixPath(relativePath))
-        .filter((relativePath) => allowedExtensions.has(path.posix.extname(relativePath)))
-        .filter((relativePath) => options.excludeGeneratedOrVendor !== true || !sourceAnchorPathIsGeneratedOrVendor(relativePath))
-        .filter((relativePath) => include.length === 0 || matchesAnyGlob(relativePath, include))
-        .filter((relativePath) => exclude.length === 0 || !matchesAnyGlob(relativePath, exclude))
-        .filter((relativePath) => fileIsWithinSizeLimit(root, relativePath, options.maxFileBytes));
+    const rootRealPath = realpathSync(root);
+    return listFilesRecursive(root, {
+        ignoredDirectoryNames,
+        allowedExtensions,
+        include,
+        exclude,
+        excludeGeneratedOrVendor: options.excludeGeneratedOrVendor === true,
+        maxFileBytes: options.maxFileBytes,
+        followSymlinks: options.followSymlinks === true,
+        rootRealPath,
+        visitedRealDirectories: new Set(),
+    });
 }
 export function stripSourceAnchorCommentPrefix(line) {
     return line

package/dist/core/verification-evidence.js

@@ -28,7 +28,10 @@ function resultForIntent(results, intent) {
 function requirementOutcome(input) {
     if (input.selectedIntents.some((intent) => {
         const result = resultForIntent(input.results, intent);
-        return result?.status === 'failed' || result?.status === 'timed_out' || result?.status === 'start_failed';
+        return (result?.status === 'failed' ||
+            result?.status === 'timed_out' ||
+            result?.status === 'start_failed' ||
+            result?.status === 'output_limit_exceeded');
     })) {
         return 'contradicted';
     }

package/package.json

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

package/schemas/README.md

@@ -37,7 +37,7 @@ Current schemas:
 - `verify-report.schema.json`: output of `mf verify --reason <event> --json`, including an
   explicit execution aggregate, evidence-based completion verdict, and evidence model with a
   conservative coverage matrix for the selected receipts and skipped checks
-- `verify-run-manifest.schema.json`: `.mustflow/state/runs/verify-latest/manifest.json`, including
+- `verify-run-manifest.schema.json`: `.mustflow/state/runs/verify-*/manifest.json`, including
   the same execution aggregate, completion verdict, evidence model, and coverage matrix as the verify report
 - `change-verification-report.schema.json`: output of `mf verify --reason <event> --plan-only --json` and  
   `mf verify --from-classification <classify-report.json> --plan-only --json`, including the `decision_graph` that links

package/schemas/run-receipt.schema.json

@@ -35,7 +35,7 @@
     "schema_version": { "const": "1" },
     "command": { "const": "run" },
     "intent": { "type": "string" },
-    "status": { "enum": ["passed", "failed", "timed_out", "start_failed"] },
+    "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "output_limit_exceeded"] },
     "timed_out": { "type": "boolean" },
     "started_at": { "type": "string", "format": "date-time" },
     "finished_at": { "type": "string", "format": "date-time" },
@@ -64,6 +64,7 @@
     "signal": { "type": ["string", "null"] },
     "error": { "type": ["string", "null"] },
     "kill_method": { "type": ["string", "null"] },
+    "termination": { "$ref": "#/$defs/termination" },
     "stdout": { "$ref": "#/$defs/output" },
     "stderr": { "$ref": "#/$defs/output" },
     "write_drift": { "$ref": "#/$defs/writeDrift" },
@@ -182,10 +183,10 @@
           "additionalProperties": false,
           "required": ["status", "exit_code_class", "timed_out", "error_kind"],
           "properties": {
-            "status": { "enum": ["passed", "failed", "timed_out", "start_failed"] },
+            "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "output_limit_exceeded"] },
             "exit_code_class": { "enum": ["success", "failure", "no_exit_code"] },
             "timed_out": { "type": "boolean" },
-            "error_kind": { "enum": ["timeout", "start_failed", "exit_code", null] }
+            "error_kind": { "enum": ["timeout", "start_failed", "output_limit_exceeded", "exit_code", null] }
           }
         },
         "quality": {
@@ -200,6 +201,28 @@
         }
       }
     },
+    "termination": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": [
+        "reason",
+        "method",
+        "graceful_signal",
+        "forced_signal",
+        "forced_kill_attempted",
+        "confirmed",
+        "cleanup_pending"
+      ],
+      "properties": {
+        "reason": { "const": "timeout" },
+        "method": { "type": "string" },
+        "graceful_signal": { "type": ["string", "null"] },
+        "forced_signal": { "type": ["string", "null"] },
+        "forced_kill_attempted": { "type": "boolean" },
+        "confirmed": { "type": "boolean" },
+        "cleanup_pending": { "type": "boolean" }
+      }
+    },
     "redaction": {
       "type": "object",
       "additionalProperties": false,

package/schemas/verify-report.schema.json

@@ -88,7 +88,7 @@
         ],
         "properties": {
           "intent": { "type": ["string", "null"] },
-          "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "skipped"] },
+          "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "output_limit_exceeded", "skipped"] },
           "skipped": { "type": "boolean" },
           "reason": { "type": ["string", "null"] },
           "detail": { "type": ["string", "null"] },

package/schemas/verify-run-manifest.schema.json

@@ -265,7 +265,7 @@
       ],
       "properties": {
         "intent": { "type": ["string", "null"] },
-        "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "skipped"] },
+        "status": { "enum": ["passed", "failed", "timed_out", "start_failed", "output_limit_exceeded", "skipped"] },
         "skipped": { "type": "boolean" },
         "verification_plan_id": {
           "type": ["string", "null"],

package/templates/default/manifest.toml

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