mustflow 2.18.21 → 2.21.1

package/dist/core/run-write-drift.js

@@ -1,9 +1,14 @@
 import { spawnSync } from 'node:child_process';
-import { lstatSync, readlinkSync, readdirSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, lstatSync, readFileSync, readlinkSync, readdirSync } from 'node:fs';
 import path from 'node:path';
 import { normalizeCommandEffects } from './command-effects.js';
 const MAX_SNAPSHOT_FILES = 20_000;
 const MAX_REPORTED_PATHS = 200;
+const GIT_STATUS_TIMEOUT_MS = 10_000;
+const GIT_STATUS_MAX_BUFFER_BYTES = 16 * 1024 * 1024;
+const GIT_STATUS_UNTRACKED_MODE = 'normal';
+const MAX_HASH_BYTES = 5 * 1024 * 1024;
 const RECURSIVE_SNAPSHOT_ENV = 'MUSTFLOW_WRITE_DRIFT_SNAPSHOT';
 const EXCLUDED_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
 const EXCLUDED_RELATIVE_DIRECTORY_PATHS = new Set(['.mustflow/state/runs']);
@@ -33,6 +38,24 @@ function signatureForPath(fullPath) {
     const type = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
     return `${type}:${stat.size}:${stat.mtimeMs}`;
 }
+function signatureForGitStatusPath(projectRoot, relativePath, status) {
+    const fullPath = path.join(projectRoot, ...relativePath.split('/'));
+    if (!existsSync(fullPath)) {
+        return `git:${status}:missing`;
+    }
+    const stat = lstatSync(fullPath);
+    if (stat.isSymbolicLink()) {
+        return `git:${status}:symlink:${readlinkSync(fullPath)}`;
+    }
+    if (!stat.isFile()) {
+        return `git:${status}:${stat.isDirectory() ? 'directory' : 'other'}:${stat.size}:${stat.mtimeMs}`;
+    }
+    if (stat.size > MAX_HASH_BYTES) {
+        return `git:${status}:file:${stat.size}:${stat.mtimeMs}:unhashed`;
+    }
+    const digest = createHash('sha256').update(readFileSync(fullPath)).digest('hex');
+    return `git:${status}:file:${stat.size}:${digest}`;
+}
 function collectSnapshotEntries(projectRoot, currentPath, entries) {
     const names = readdirSync(currentPath).sort((left, right) => left.localeCompare(right));
     for (const name of names) {
@@ -59,7 +82,7 @@ function captureSnapshot(projectRoot) {
     }
     if (!isRecursiveSnapshotEnabled()) {
         return {
-            ok: false,
+            status: 'unavailable',
             entries: new Map(),
             reason: 'git_status_unavailable_recursive_snapshot_disabled',
             source: 'unavailable',
@@ -68,11 +91,11 @@ function captureSnapshot(projectRoot) {
     try {
         const entries = new Map();
         collectSnapshotEntries(projectRoot, projectRoot, entries);
-        return { ok: true, entries, reason: null, source: 'recursive_snapshot' };
+        return { status: 'checked', entries, reason: null, source: 'recursive_snapshot' };
     }
     catch (error) {
         return {
-            ok: false,
+            status: 'unavailable',
             entries: new Map(),
             reason: error instanceof Error && error.message.length > 0 ? error.message : 'snapshot_unavailable',
             source: 'unavailable',
@@ -80,12 +103,33 @@ function captureSnapshot(projectRoot) {
     }
 }
 function captureGitStatusSnapshot(projectRoot) {
-    const result = spawnSync('git', ['-C', projectRoot, 'status', '--porcelain=v1', '-z', '--untracked-files=all'], {
+    const result = spawnSync('git', ['-C', projectRoot, 'status', '--porcelain=v1', '-z', `--untracked-files=${GIT_STATUS_UNTRACKED_MODE}`], {
         encoding: 'utf8',
         input: '',
+        maxBuffer: GIT_STATUS_MAX_BUFFER_BYTES,
         stdio: ['ignore', 'pipe', 'pipe'],
+        timeout: GIT_STATUS_TIMEOUT_MS,
         windowsHide: true,
     });
+    const errorCode = typeof result.error === 'object' && result.error && 'code' in result.error
+        ? String(result.error.code)
+        : null;
+    if (errorCode === 'ETIMEDOUT') {
+        return {
+            status: 'unavailable',
+            entries: new Map(),
+            reason: 'git_status_timeout',
+            source: 'unavailable',
+        };
+    }
+    if (errorCode === 'ENOBUFS') {
+        return {
+            status: 'unavailable',
+            entries: new Map(),
+            reason: 'git_status_output_limit_exceeded',
+            source: 'unavailable',
+        };
+    }
     if (result.error || result.status !== 0) {
         return null;
     }
@@ -98,15 +142,15 @@ function captureGitStatusSnapshot(projectRoot) {
         if (filePath.length === 0) {
             continue;
         }
-        entries.set(filePath, `git:${status}`);
+        entries.set(filePath, signatureForGitStatusPath(projectRoot, filePath, status));
         if (status.includes('R') || status.includes('C')) {
             index += 1;
         }
     }
     return {
-        ok: true,
+        status: 'partial',
         entries,
-        reason: null,
+        reason: 'git_status_untracked_files_normal',
         source: 'git_status',
     };
 }
@@ -150,7 +194,7 @@ export function startRunWriteTracking(projectRoot, contract, intentName) {
     };
 }
 export function finishRunWriteTracking(tracker) {
-    if (!tracker.before.ok) {
+    if (tracker.before.status === 'unavailable') {
         return {
             status: 'unavailable',
             declared_paths: tracker.declaredPaths,
@@ -165,7 +209,7 @@ export function finishRunWriteTracking(tracker) {
         };
     }
     const after = captureSnapshot(tracker.projectRoot);
-    if (!after.ok) {
+    if (after.status === 'unavailable') {
         return {
             status: 'unavailable',
             declared_paths: tracker.declaredPaths,
@@ -185,8 +229,12 @@ export function finishRunWriteTracking(tracker) {
     const observed = truncatePaths(observedPaths);
     const declaredObserved = truncatePaths(declaredObservedPaths);
     const undeclared = truncatePaths(undeclaredPaths);
+    const status = tracker.before.status === 'partial' || after.status === 'partial' ? 'partial' : 'checked';
+    const reason = status === 'partial'
+        ? tracker.before.reason ?? after.reason ?? 'partial_snapshot'
+        : null;
     return {
-        status: 'checked',
+        status,
         declared_paths: tracker.declaredPaths,
         observed_paths: observed.paths,
         declared_observed_paths: declaredObserved.paths,
@@ -195,6 +243,6 @@ export function finishRunWriteTracking(tracker) {
         undeclared_count: undeclaredPaths.length,
         has_undeclared_changes: undeclaredPaths.length > 0,
         truncated: observed.truncated || declaredObserved.truncated || undeclared.truncated,
-        reason: null,
+        reason,
     };
 }

package/dist/core/safe-filesystem.js

@@ -0,0 +1,155 @@
+import { closeSync, constants, lstatSync, mkdirSync, openSync, readFileSync, renameSync, unlinkSync, writeFileSync, } from 'node:fs';
+import { randomBytes } from 'node:crypto';
+import path from 'node:path';
+const NOFOLLOW_FLAG = typeof constants.O_NOFOLLOW === 'number' ? constants.O_NOFOLLOW : 0;
+function isMissingPathError(error) {
+    return error instanceof Error && 'code' in error && error.code === 'ENOENT';
+}
+function tempFilePath(targetPath) {
+    const suffix = `${process.pid}-${Date.now()}-${randomBytes(6).toString('hex')}`;
+    return path.join(path.dirname(targetPath), `.${path.basename(targetPath)}.${suffix}.tmp`);
+}
+export function ensureInside(parentPath, childPath) {
+    const parent = path.resolve(parentPath);
+    const child = path.resolve(childPath);
+    const relative = path.relative(parent, child);
+    if (relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative))) {
+        return;
+    }
+    throw new Error(`Path escapes allowed directory: ${childPath}`);
+}
+export function ensureInsideWithoutSymlinks(parentPath, childPath, options = {}) {
+    ensureInside(parentPath, childPath);
+    const parent = path.resolve(parentPath);
+    const child = path.resolve(childPath);
+    const relative = path.relative(parent, child);
+    const segments = relative === '' ? [] : relative.split(path.sep).filter((segment) => segment.length > 0);
+    let currentPath = parent;
+    const parentStats = lstatSync(parent);
+    if (parentStats.isSymbolicLink()) {
+        throw new Error(`Path must not contain symlinks: ${childPath}`);
+    }
+    for (const [index, segment] of segments.entries()) {
+        currentPath = path.join(currentPath, segment);
+        const isLeaf = index === segments.length - 1;
+        try {
+            const stats = lstatSync(currentPath);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`Path must not contain symlinks: ${childPath}`);
+            }
+            if (!isLeaf && !stats.isDirectory()) {
+                throw new Error(`Path component is not a directory: ${currentPath}`);
+            }
+        }
+        catch (error) {
+            if (isMissingPathError(error) && options.allowMissingLeaf) {
+                return;
+            }
+            throw error;
+        }
+    }
+}
+function ensureDirectoryInsideWithoutSymlinks(parentPath, directoryPath) {
+    ensureInside(parentPath, directoryPath);
+    const parent = path.resolve(parentPath);
+    const directory = path.resolve(directoryPath);
+    const relative = path.relative(parent, directory);
+    const segments = relative === '' ? [] : relative.split(path.sep).filter((segment) => segment.length > 0);
+    let currentPath = parent;
+    const parentStats = lstatSync(parent);
+    if (parentStats.isSymbolicLink()) {
+        throw new Error(`Path must not contain symlinks: ${directoryPath}`);
+    }
+    for (const segment of segments) {
+        currentPath = path.join(currentPath, segment);
+        try {
+            const stats = lstatSync(currentPath);
+            if (stats.isSymbolicLink()) {
+                throw new Error(`Path must not contain symlinks: ${directoryPath}`);
+            }
+            if (!stats.isDirectory()) {
+                throw new Error(`Path component is not a directory: ${currentPath}`);
+            }
+        }
+        catch (error) {
+            if (!isMissingPathError(error)) {
+                throw error;
+            }
+            mkdirSync(currentPath);
+            const stats = lstatSync(currentPath);
+            if (!stats.isDirectory() || stats.isSymbolicLink()) {
+                throw new Error(`Path component is not a directory: ${currentPath}`);
+            }
+        }
+    }
+}
+export function ensureFileTargetInsideWithoutSymlinks(parentPath, childPath, options = {}) {
+    const absoluteChildPath = path.resolve(childPath);
+    ensureInside(parentPath, absoluteChildPath);
+    ensureInsideWithoutSymlinks(parentPath, path.dirname(absoluteChildPath), { allowMissingLeaf: true });
+    try {
+        const stats = lstatSync(absoluteChildPath);
+        if (stats.isSymbolicLink()) {
+            throw new Error(`Path must not contain symlinks: ${childPath}`);
+        }
+        if (!stats.isFile()) {
+            throw new Error(`Path must be a regular file: ${childPath}`);
+        }
+    }
+    catch (error) {
+        if (isMissingPathError(error) && options.allowMissingLeaf) {
+            return;
+        }
+        throw error;
+    }
+}
+export function readFileInsideWithoutSymlinks(parentPath, childPath) {
+    const absoluteChildPath = path.resolve(childPath);
+    ensureInsideWithoutSymlinks(parentPath, absoluteChildPath);
+    const fileDescriptor = openSync(absoluteChildPath, constants.O_RDONLY | NOFOLLOW_FLAG);
+    try {
+        return readFileSync(fileDescriptor);
+    }
+    finally {
+        closeSync(fileDescriptor);
+    }
+}
+export function writeFileInsideWithoutSymlinks(parentPath, childPath, content) {
+    const absoluteChildPath = path.resolve(childPath);
+    const directoryPath = path.dirname(absoluteChildPath);
+    ensureDirectoryInsideWithoutSymlinks(parentPath, directoryPath);
+    ensureFileTargetInsideWithoutSymlinks(parentPath, absoluteChildPath, { allowMissingLeaf: true });
+    const temporaryPath = tempFilePath(absoluteChildPath);
+    let fileDescriptor = null;
+    try {
+        fileDescriptor = openSync(temporaryPath, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | NOFOLLOW_FLAG);
+        writeFileSync(fileDescriptor, content);
+        closeSync(fileDescriptor);
+        fileDescriptor = null;
+        ensureFileTargetInsideWithoutSymlinks(parentPath, absoluteChildPath, { allowMissingLeaf: true });
+        renameSync(temporaryPath, absoluteChildPath);
+    }
+    catch (error) {
+        if (fileDescriptor !== null) {
+            try {
+                closeSync(fileDescriptor);
+            }
+            catch {
+                // Best-effort cleanup before removing the temporary file.
+            }
+        }
+        try {
+            unlinkSync(temporaryPath);
+        }
+        catch {
+            // Best-effort cleanup for a temporary file that may not have been created.
+        }
+        throw error;
+    }
+}
+export function writeUtf8FileInsideWithoutSymlinks(parentPath, childPath, content) {
+    writeFileInsideWithoutSymlinks(parentPath, childPath, content);
+}
+export function writeJsonFileInsideWithoutSymlinks(parentPath, childPath, value) {
+    writeUtf8FileInsideWithoutSymlinks(parentPath, childPath, `${JSON.stringify(value, null, 2)}\n`);
+}

package/package.json

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

package/schemas/commands.schema.json

@@ -137,6 +137,7 @@
         "cmd": { "type": "string" },
         "cwd": { "type": "string" },
         "timeout_seconds": { "type": "integer" },
+        "kill_after_seconds": { "type": "integer" },
         "stdin": { "type": "string" },
         "success_exit_codes": {
           "type": "array",

package/schemas/doctor-report.schema.json

@@ -13,6 +13,7 @@
     "ok",
     "check",
     "context",
+    "command_environment",
     "effective_policy",
     "state_policy",
     "blocked_actions",
@@ -29,13 +30,18 @@
     "check": {
       "type": "object",
       "additionalProperties": false,
-      "required": ["ok", "issue_count", "issues"],
+      "required": ["ok", "issue_count", "issues", "warning_count", "warnings"],
       "properties": {
         "ok": { "type": "boolean" },
         "issue_count": { "type": "integer" },
         "issues": {
           "type": "array",
           "items": { "type": "string" }
+        },
+        "warning_count": { "type": "integer" },
+        "warnings": {
+          "type": "array",
+          "items": { "type": "string" }
         }
       }
     },
@@ -83,6 +89,21 @@
         "latest_run_exists": { "type": "boolean" }
       }
     },
+    "command_environment": {
+      "type": "object",
+      "additionalProperties": false,
+      "required": ["inherited_intents", "inherited_network_intents"],
+      "properties": {
+        "inherited_intents": {
+          "type": "array",
+          "items": { "type": "string" }
+        },
+        "inherited_network_intents": {
+          "type": "array",
+          "items": { "type": "string" }
+        }
+      }
+    },
     "effective_policy": { "$ref": "#/$defs/effectivePolicy" },
     "state_policy": { "$ref": "#/$defs/statePolicy" },
     "blocked_actions": {
@@ -102,6 +123,7 @@
               "validation",
               "skill_routes",
               "commands",
+              "environment",
               "read_order",
               "optional_read_order",
               "repo_map",

package/schemas/run-receipt.schema.json

@@ -55,7 +55,9 @@
     },
     "cmd": { "type": "string" },
     "timeout_seconds": { "type": "integer" },
+    "kill_after_seconds": { "type": "integer" },
     "max_output_bytes": { "type": "integer" },
+    "max_output_bytes_scope": { "const": "per_stream" },
     "success_exit_codes": {
       "type": "array",
       "items": { "type": "integer" }
@@ -174,8 +176,10 @@
           "properties": {
             "stdout_bytes": { "type": "integer", "minimum": 0 },
             "stderr_bytes": { "type": "integer", "minimum": 0 },
+            "total_bytes": { "type": "integer", "minimum": 0 },
             "stdout_truncated": { "type": "boolean" },
-            "stderr_truncated": { "type": "boolean" }
+            "stderr_truncated": { "type": "boolean" },
+            "max_output_bytes_scope": { "const": "per_stream" }
           }
         },
         "result_summary": {
@@ -256,7 +260,7 @@
         "reason"
       ],
       "properties": {
-        "status": { "enum": ["checked", "unavailable"] },
+        "status": { "enum": ["checked", "partial", "unavailable"] },
         "declared_paths": {
           "type": "array",
           "items": { "type": "string" }

package/templates/default/i18n.toml

@@ -56,13 +56,13 @@ translations = {}
 [documents."skills.index"]
 source = "locales/en/.mustflow/skills/INDEX.md"
 source_locale = "en"
-revision = 60
+revision = 73
 translations = {}
 
 [documents."skill.adapter-boundary"]
 source = "locales/en/.mustflow/skills/adapter-boundary/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 11
 translations = {}
 
 [documents."skill.artifact-integrity-check"]
@@ -104,7 +104,7 @@ translations = {}
 [documents."skill.database-change-safety"]
 source = "locales/en/.mustflow/skills/database-change-safety/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 16
 translations = {}
 
 [documents."skill.dependency-injection"]
@@ -116,7 +116,7 @@ translations = {}
 [documents."skill.dependency-reality-check"]
 source = "locales/en/.mustflow/skills/dependency-reality-check/SKILL.md"
 source_locale = "en"
-revision = 3
+revision = 6
 translations = {}
 
 [documents."skill.line-ending-hygiene"]
@@ -152,13 +152,13 @@ translations = {}
 [documents."skill.command-pattern"]
 source = "locales/en/.mustflow/skills/command-pattern/SKILL.md"
 source_locale = "en"
-revision = 4
+revision = 13
 translations = {}
 
 [documents."skill.command-contract-authoring"]
 source = "locales/en/.mustflow/skills/command-contract-authoring/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 2
 translations = {}
 
 [documents."skill.cross-platform-filesystem-safety"]
@@ -170,13 +170,13 @@ translations = {}
 [documents."skill.pure-core-imperative-shell"]
 source = "locales/en/.mustflow/skills/pure-core-imperative-shell/SKILL.md"
 source_locale = "en"
-revision = 6
+revision = 7
 translations = {}
 
 [documents."skill.result-option"]
 source = "locales/en/.mustflow/skills/result-option/SKILL.md"
 source_locale = "en"
-revision = 2
+revision = 3
 translations = {}
 
 [documents."skill.docs-update"]
@@ -223,7 +223,7 @@ translations = {}
 [documents."skill.migration-safety-check"]
 source = "locales/en/.mustflow/skills/migration-safety-check/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 8
 translations = {}
 
 [documents."skill.multi-agent-work-coordination"]
@@ -241,7 +241,7 @@ translations = {}
 [documents."skill.performance-budget-check"]
 source = "locales/en/.mustflow/skills/performance-budget-check/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 12
 translations = {}
 
 [documents."skill.pattern-scout"]
@@ -271,13 +271,13 @@ translations = {}
 [documents."skill.structure-discovery-gate"]
 source = "locales/en/.mustflow/skills/structure-discovery-gate/SKILL.md"
 source_locale = "en"
-revision = 12
+revision = 26
 translations = {}
 
 [documents."skill.state-machine-pattern"]
 source = "locales/en/.mustflow/skills/state-machine-pattern/SKILL.md"
 source_locale = "en"
-revision = 1
+revision = 4
 translations = {}
 
 [documents."skill.strategy-pattern"]
@@ -325,7 +325,7 @@ translations = {}
 [documents."skill.security-privacy-review"]
 source = "locales/en/.mustflow/skills/security-privacy-review/SKILL.md"
 source_locale = "en"
-revision = 7
+revision = 16
 translations = {}
 
 [documents."skill.security-regression-tests"]