mustflow 1.18.16 → 1.30.0

package/dist/core/handoff-record.js

@@ -0,0 +1,376 @@
+const HANDOFF_SCHEMA_VERSION = '1';
+export const MAX_HANDOFF_RECORD_BYTES = 256 * 1024;
+const MAX_STRING_LENGTH = 2_000;
+const MAX_ARRAY_ITEMS = 100;
+const MAX_OBJECT_DEPTH = 8;
+const ALLOWED_TOP_LEVEL_KEYS = new Set([
+    'schema_version',
+    'kind',
+    'task_id',
+    'goal',
+    'scope',
+    'non_goals',
+    'acceptance_criteria',
+    'source_refs',
+    'changed_surfaces',
+    'verification_plan',
+    'coverage',
+    'remaining_risks',
+    'next_restart_point',
+]);
+const ALLOWED_VERIFICATION_PLAN_KEYS = new Set([
+    'intent',
+    'reason',
+    'status',
+    'receipt_path',
+    'skip_reason',
+]);
+const ALLOWED_COVERAGE_KEYS = new Set(['status', 'requirement', 'evidence', 'gap']);
+const RECORD_KINDS = new Set(['work_item', 'handoff']);
+const COVERAGE_STATUSES = new Set(['covered', 'partial', 'missing', 'blocked']);
+const VERIFICATION_STATUSES = new Set(['planned', 'run', 'skipped']);
+const FORBIDDEN_KEY_RULES = [
+    {
+        code: 'forbidden_transcript_or_log_field',
+        pattern: /^(?:transcript|raw_transcript|chat|conversation|messages|terminal_log|command_log|logs?|stdout|stderr|raw_output|full_output)$/iu,
+        message: 'Handoff records must not store raw chats, transcripts, terminal logs, or command output.',
+    },
+    {
+        code: 'forbidden_secret_field',
+        pattern: /(?:secret|password|token|api[_-]?key|credential|private[_-]?key)/iu,
+        message: 'Handoff records must not store secrets, credentials, tokens, or key material.',
+    },
+    {
+        code: 'forbidden_hidden_reasoning_field',
+        pattern: /(?:reasoning|chain[_-]?of[_-]?thought|hidden[_-]?thoughts?)/iu,
+        message: 'Handoff records must not store hidden reasoning or chain-of-thought content.',
+    },
+    {
+        code: 'forbidden_memory_field',
+        pattern: /(?:memory|memory[_-]?summary|broad[_-]?summary)/iu,
+        message: 'Handoff records must not become broad memory summaries.',
+    },
+    {
+        code: 'forbidden_worker_state_field',
+        pattern: /(?:worker[_-]?state|autonomous[_-]?loop|background[_-]?process|persona|agent[_-]?state)/iu,
+        message: 'Handoff records must not store autonomous worker state or background-loop state.',
+    },
+    {
+        code: 'forbidden_command_authority_field',
+        pattern: /^(?:argv|cmd|run_policy|lifecycle|stdin|timeout_seconds|writes|network|destructive|required_after|skip_validation|agent_action|command_authority)$/iu,
+        message: 'Handoff records must not include command-authority fields that bypass commands.toml.',
+    },
+];
+const SECRET_VALUE_RULES = [
+    {
+        code: 'secret_like_private_key',
+        pattern: /-----BEGIN [A-Z ]*PRIVATE KEY-----/u,
+        message: 'Value looks like private key material.',
+    },
+    {
+        code: 'secret_like_token',
+        pattern: /\b(?:sk-[A-Za-z0-9_-]{12,}|ghp_[A-Za-z0-9_]{12,}|github_pat_[A-Za-z0-9_]{12,}|xox[abprs]-[A-Za-z0-9-]{12,})\b/u,
+        message: 'Value looks like an API token or service token.',
+    },
+    {
+        code: 'secret_like_aws_access_key',
+        pattern: /\bAKIA[0-9A-Z]{16}\b/u,
+        message: 'Value looks like an AWS access key.',
+    },
+    {
+        code: 'secret_like_assignment',
+        pattern: /\b(?:password|token|secret|api[_-]?key)\s*[:=]\s*\S+/iu,
+        message: 'Value looks like an inline secret assignment.',
+    },
+];
+function isRecord(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+function isString(value) {
+    return typeof value === 'string';
+}
+function normalizeKey(value) {
+    return value.replaceAll('-', '_').toLowerCase();
+}
+function makeEmptySummary() {
+    return {
+        scope_count: 0,
+        acceptance_criteria_count: 0,
+        source_ref_count: 0,
+        verification_plan_count: 0,
+        coverage_count: 0,
+        remaining_risk_count: 0,
+    };
+}
+function countArray(value) {
+    return Array.isArray(value) ? value.length : 0;
+}
+function getSummary(value) {
+    if (!isRecord(value)) {
+        return makeEmptySummary();
+    }
+    return {
+        scope_count: countArray(value.scope),
+        acceptance_criteria_count: countArray(value.acceptance_criteria),
+        source_ref_count: countArray(value.source_refs),
+        verification_plan_count: countArray(value.verification_plan),
+        coverage_count: countArray(value.coverage),
+        remaining_risk_count: countArray(value.remaining_risks),
+    };
+}
+function getRecordKind(value) {
+    if (!isRecord(value) || !isString(value.kind) || !RECORD_KINDS.has(value.kind)) {
+        return null;
+    }
+    return value.kind;
+}
+function getTaskId(value) {
+    return isRecord(value) && isString(value.task_id) ? value.task_id : null;
+}
+function pushIssue(issues, severity, code, path, message) {
+    issues.push({ severity, code, path, message });
+}
+function validateString(issues, value, pointer, label, options) {
+    if (value === undefined) {
+        if (options.required) {
+            pushIssue(issues, 'error', 'missing_required_field', pointer, `${label} is required.`);
+        }
+        return;
+    }
+    if (!isString(value)) {
+        pushIssue(issues, 'error', 'invalid_string', pointer, `${label} must be a string.`);
+        return;
+    }
+    if (options.nonEmpty && value.trim().length === 0) {
+        pushIssue(issues, 'error', 'empty_string', pointer, `${label} must not be empty.`);
+    }
+    if (value.length > MAX_STRING_LENGTH) {
+        pushIssue(issues, 'error', 'string_too_long', pointer, `${label} is too long for a restart pointer record.`);
+    }
+}
+function validateStringArray(issues, value, pointer, label, options) {
+    if (value === undefined) {
+        if (options.required) {
+            pushIssue(issues, 'error', 'missing_required_field', pointer, `${label} is required.`);
+        }
+        return;
+    }
+    if (!Array.isArray(value)) {
+        pushIssue(issues, 'error', 'invalid_array', pointer, `${label} must be an array.`);
+        return;
+    }
+    if (options.nonEmpty && value.length === 0) {
+        pushIssue(issues, 'error', 'empty_array', pointer, `${label} must include at least one entry.`);
+    }
+    if (value.length > MAX_ARRAY_ITEMS) {
+        pushIssue(issues, 'error', 'array_too_large', pointer, `${label} has too many entries for a restart pointer.`);
+    }
+    value.forEach((item, index) => {
+        validateString(issues, item, `${pointer}[${index}]`, `${label} item`, {
+            required: true,
+            nonEmpty: true,
+        });
+    });
+}
+function validateAllowedKeys(issues, record, allowedKeys, pointer) {
+    for (const key of Object.keys(record)) {
+        if (!allowedKeys.has(key)) {
+            pushIssue(issues, 'error', 'unknown_field', `${pointer}.${key}`, `Field is not part of the handoff record contract.`);
+        }
+    }
+}
+function validateVerificationPlan(issues, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        pushIssue(issues, 'error', 'invalid_array', '$.verification_plan', 'verification_plan must be an array.');
+        return;
+    }
+    if (value.length > MAX_ARRAY_ITEMS) {
+        pushIssue(issues, 'error', 'array_too_large', '$.verification_plan', 'verification_plan has too many entries for a restart pointer.');
+    }
+    value.forEach((entry, index) => {
+        const pointer = `$.verification_plan[${index}]`;
+        if (!isRecord(entry)) {
+            pushIssue(issues, 'error', 'invalid_object', pointer, 'verification_plan entries must be objects.');
+            return;
+        }
+        validateAllowedKeys(issues, entry, ALLOWED_VERIFICATION_PLAN_KEYS, pointer);
+        validateString(issues, entry.intent, `${pointer}.intent`, 'intent', { required: true, nonEmpty: true });
+        validateString(issues, entry.reason, `${pointer}.reason`, 'reason', { required: true, nonEmpty: true });
+        if (!isString(entry.status) || !VERIFICATION_STATUSES.has(entry.status)) {
+            pushIssue(issues, 'error', 'invalid_verification_status', `${pointer}.status`, 'status must be one of planned, run, or skipped.');
+        }
+        validateString(issues, entry.receipt_path, `${pointer}.receipt_path`, 'receipt_path', {
+            required: false,
+            nonEmpty: true,
+        });
+        validateString(issues, entry.skip_reason, `${pointer}.skip_reason`, 'skip_reason', {
+            required: false,
+            nonEmpty: true,
+        });
+        if (entry.status === 'skipped' && entry.skip_reason === undefined) {
+            pushIssue(issues, 'error', 'missing_skip_reason', `${pointer}.skip_reason`, 'Skipped verification must explain why it was skipped.');
+        }
+        if (entry.status !== 'run' && entry.receipt_path !== undefined) {
+            pushIssue(issues, 'error', 'unrun_verification_receipt_claim', `${pointer}.receipt_path`, 'Only verification entries with status run may include a receipt_path.');
+        }
+        if (entry.status !== 'skipped' && entry.skip_reason !== undefined) {
+            pushIssue(issues, 'warning', 'unused_skip_reason', `${pointer}.skip_reason`, 'skip_reason is meaningful only when status is skipped.');
+        }
+    });
+}
+function validateCoverage(issues, value) {
+    if (value === undefined) {
+        return;
+    }
+    if (!Array.isArray(value)) {
+        pushIssue(issues, 'error', 'invalid_array', '$.coverage', 'coverage must be an array.');
+        return;
+    }
+    if (value.length > MAX_ARRAY_ITEMS) {
+        pushIssue(issues, 'error', 'array_too_large', '$.coverage', 'coverage has too many entries for a restart pointer.');
+    }
+    value.forEach((entry, index) => {
+        const pointer = `$.coverage[${index}]`;
+        if (!isRecord(entry)) {
+            pushIssue(issues, 'error', 'invalid_object', pointer, 'coverage entries must be objects.');
+            return;
+        }
+        validateAllowedKeys(issues, entry, ALLOWED_COVERAGE_KEYS, pointer);
+        if (!isString(entry.status) || !COVERAGE_STATUSES.has(entry.status)) {
+            pushIssue(issues, 'error', 'invalid_coverage_status', `${pointer}.status`, 'coverage status must be one of covered, partial, missing, or blocked.');
+        }
+        validateString(issues, entry.requirement, `${pointer}.requirement`, 'requirement', {
+            required: false,
+            nonEmpty: true,
+        });
+        validateStringArray(issues, entry.evidence, `${pointer}.evidence`, 'evidence', {
+            required: false,
+            nonEmpty: false,
+        });
+        validateString(issues, entry.gap, `${pointer}.gap`, 'gap', { required: false, nonEmpty: true });
+        if (entry.status === 'covered' && (!Array.isArray(entry.evidence) || entry.evidence.length === 0)) {
+            pushIssue(issues, 'warning', 'covered_without_evidence', `${pointer}.evidence`, 'covered entries should name the guard, file, or receipt that supports the claim.');
+        }
+    });
+}
+function scanForbiddenKeysAndValues(issues, value, pointer, depth = 0) {
+    if (depth > MAX_OBJECT_DEPTH) {
+        pushIssue(issues, 'error', 'record_too_deep', pointer, 'Handoff records must stay shallow restart pointers.');
+        return;
+    }
+    if (isString(value)) {
+        for (const rule of SECRET_VALUE_RULES) {
+            if (rule.pattern.test(value)) {
+                pushIssue(issues, 'error', rule.code, pointer, rule.message);
+            }
+        }
+        if (/[A-Z]:\\Users\\/u.test(value) || /\/home\/[^/\s]+/u.test(value)) {
+            pushIssue(issues, 'warning', 'personal_path_candidate', pointer, 'Value looks like a personal local path; use repository-relative paths when possible.');
+        }
+        return;
+    }
+    if (Array.isArray(value)) {
+        value.forEach((item, index) => scanForbiddenKeysAndValues(issues, item, `${pointer}[${index}]`, depth + 1));
+        return;
+    }
+    if (!isRecord(value)) {
+        return;
+    }
+    for (const [key, nestedValue] of Object.entries(value)) {
+        const nestedPointer = pointer === '$' ? `$.${key}` : `${pointer}.${key}`;
+        const normalizedKey = normalizeKey(key);
+        for (const rule of FORBIDDEN_KEY_RULES) {
+            if (rule.pattern.test(normalizedKey)) {
+                pushIssue(issues, 'error', rule.code, nestedPointer, rule.message);
+            }
+        }
+        scanForbiddenKeysAndValues(issues, nestedValue, nestedPointer, depth + 1);
+    }
+}
+function validateRecordShape(issues, value) {
+    if (!isRecord(value)) {
+        pushIssue(issues, 'error', 'invalid_record', '$', 'Handoff record must be a JSON object.');
+        return;
+    }
+    validateAllowedKeys(issues, value, ALLOWED_TOP_LEVEL_KEYS, '$');
+    if (value.schema_version !== HANDOFF_SCHEMA_VERSION) {
+        pushIssue(issues, 'error', 'invalid_schema_version', '$.schema_version', 'schema_version must be "1".');
+    }
+    if (!isString(value.kind) || !RECORD_KINDS.has(value.kind)) {
+        pushIssue(issues, 'error', 'invalid_kind', '$.kind', 'kind must be work_item or handoff.');
+    }
+    validateString(issues, value.task_id, '$.task_id', 'task_id', { required: true, nonEmpty: true });
+    validateString(issues, value.goal, '$.goal', 'goal', { required: true, nonEmpty: true });
+    validateStringArray(issues, value.scope, '$.scope', 'scope', { required: true, nonEmpty: true });
+    validateStringArray(issues, value.non_goals, '$.non_goals', 'non_goals', { required: false, nonEmpty: false });
+    validateStringArray(issues, value.acceptance_criteria, '$.acceptance_criteria', 'acceptance_criteria', {
+        required: true,
+        nonEmpty: true,
+    });
+    validateStringArray(issues, value.source_refs, '$.source_refs', 'source_refs', {
+        required: true,
+        nonEmpty: true,
+    });
+    validateStringArray(issues, value.changed_surfaces, '$.changed_surfaces', 'changed_surfaces', {
+        required: false,
+        nonEmpty: false,
+    });
+    validateVerificationPlan(issues, value.verification_plan);
+    validateCoverage(issues, value.coverage);
+    validateStringArray(issues, value.remaining_risks, '$.remaining_risks', 'remaining_risks', {
+        required: false,
+        nonEmpty: false,
+    });
+    validateString(issues, value.next_restart_point, '$.next_restart_point', 'next_restart_point', {
+        required: true,
+        nonEmpty: true,
+    });
+}
+export function validateHandoffRecord(value, options) {
+    const issues = [];
+    validateRecordShape(issues, value);
+    scanForbiddenKeysAndValues(issues, value, '$');
+    const hasErrors = issues.some((issue) => issue.severity === 'error');
+    return {
+        schema_version: HANDOFF_SCHEMA_VERSION,
+        command: 'handoff_validate',
+        ok: !hasErrors,
+        mustflow_root: options.mustflowRoot,
+        path: options.path,
+        record_kind: getRecordKind(value),
+        task_id: getTaskId(value),
+        summary: getSummary(value),
+        issues,
+    };
+}
+export function validateHandoffRecordJson(content, options) {
+    let parsed;
+    try {
+        parsed = JSON.parse(content);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            schema_version: HANDOFF_SCHEMA_VERSION,
+            command: 'handoff_validate',
+            ok: false,
+            mustflow_root: options.mustflowRoot,
+            path: options.path,
+            record_kind: null,
+            task_id: null,
+            summary: makeEmptySummary(),
+            issues: [
+                {
+                    severity: 'error',
+                    code: 'invalid_json',
+                    path: '$',
+                    message: `Handoff record must be valid JSON: ${message}`,
+                },
+            ],
+        };
+    }
+    return validateHandoffRecord(parsed, options);
+}

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

@@ -1,4 +1,12 @@
 const PUBLIC_JSON_SCHEMA_CONTRACTS = [
+    {
+        id: 'adapter-compatibility-report',
+        schemaFile: 'adapter-compatibility-report.schema.json',
+        producer: 'mf adapters status --json',
+        packaged: true,
+        documented: true,
+        installedCommand: ['mf', 'adapters', 'status', '--json'],
+    },
     {
         id: 'doctor-report',
         schemaFile: 'doctor-report.schema.json',
@@ -63,6 +71,14 @@ const PUBLIC_JSON_SCHEMA_CONTRACTS = [
         installedCommand: ['mf', 'line-endings', 'check', '--json'],
         expectedExitCodes: [0, 1],
     },
+    {
+        id: 'handoff-validation-report',
+        schemaFile: 'handoff-validation-report.schema.json',
+        producer: 'mf handoff validate <path> --json',
+        packaged: true,
+        documented: true,
+        expectedExitCodes: [0, 1],
+    },
     {
         id: 'version-sources-report',
         schemaFile: 'version-sources-report.schema.json',

package/dist/core/run-receipt.js

@@ -1,6 +1,7 @@
 import { mkdirSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { DEFAULT_RUN_RECEIPT_TAIL_BYTES } from './retention-policy.js';
+import { redactSecretLikeText } from './secret-redaction.js';
 const RUN_RECEIPT_SCHEMA_VERSION = '1';
 const RUN_RECEIPT_DIR = path.join('.mustflow', 'state', 'runs');
 const LATEST_RUN_RECEIPT = 'latest.json';
@@ -17,22 +18,45 @@ function truncateTextByBytes(text, maxBytes) {
         truncated: true,
     };
 }
-function summarizeOutput(output, maxOutputBytes, tailBytes) {
+function recordRedaction(state, field, result) {
+    if (!result.redacted) {
+        return;
+    }
+    state.fields.add(field);
+    state.count += result.redactionCount;
+    for (const kind of result.redactionKinds) {
+        state.kinds.add(kind);
+    }
+}
+function redactReceiptString(value, field, state) {
+    const redaction = redactSecretLikeText(value);
+    recordRedaction(state, field, redaction);
+    return redaction.text;
+}
+function summarizeOutput(output, maxOutputBytes, tailBytes, field, state) {
     if (!output) {
         return {
             bytes: 0,
             truncated: false,
             tail: '',
+            redacted: false,
+            redaction_count: 0,
+            redaction_kinds: [],
         };
     }
     const text = output.toString();
     const bytes = Buffer.byteLength(text, 'utf8');
     const tailLimit = Math.min(tailBytes, maxOutputBytes);
     const tail = truncateTextByBytes(text, tailLimit);
+    const redaction = redactSecretLikeText(tail.text);
+    recordRedaction(state, `${field}.tail`, redaction);
     return {
         bytes,
         truncated: tail.truncated,
-        tail: tail.text,
+        tail: redaction.text,
+        redacted: redaction.redacted,
+        redaction_count: redaction.redactionCount,
+        redaction_kinds: redaction.redactionKinds,
     };
 }
 function getReceiptRelativePath() {
@@ -42,6 +66,12 @@ export function createRunReceipt(input) {
     const relativeCwd = path.relative(input.projectRoot, input.cwd);
     const stdoutTailBytes = input.stdoutTailBytes ?? DEFAULT_RUN_RECEIPT_TAIL_BYTES;
     const stderrTailBytes = input.stderrTailBytes ?? DEFAULT_RUN_RECEIPT_TAIL_BYTES;
+    const redactionState = { fields: new Set(), kinds: new Set(), count: 0 };
+    const argv = input.argv?.map((value, index) => redactReceiptString(value, `argv.${index}`, redactionState));
+    const cmd = input.cmd ? redactReceiptString(input.cmd, 'cmd', redactionState) : undefined;
+    const error = input.error ? redactReceiptString(input.error, 'error', redactionState) : null;
+    const stdout = summarizeOutput(input.stdout, input.maxOutputBytes, stdoutTailBytes, 'stdout', redactionState);
+    const stderr = summarizeOutput(input.stderr, input.maxOutputBytes, stderrTailBytes, 'stderr', redactionState);
     return {
         schema_version: RUN_RECEIPT_SCHEMA_VERSION,
         command: 'run',
@@ -55,17 +85,26 @@ export function createRunReceipt(input) {
         lifecycle: input.lifecycle,
         run_policy: input.runPolicy,
         mode: input.mode,
-        argv: input.argv,
-        cmd: input.cmd,
+        argv,
+        cmd,
+        env_policy: input.envPolicy,
+        env_allowlist: input.envAllowlist,
         timeout_seconds: input.timeoutSeconds,
         max_output_bytes: input.maxOutputBytes,
         success_exit_codes: input.successExitCodes,
         exit_code: input.exitCode,
         signal: input.signal,
-        error: input.error,
+        error,
         kill_method: input.killMethod,
-        stdout: summarizeOutput(input.stdout, input.maxOutputBytes, stdoutTailBytes),
-        stderr: summarizeOutput(input.stderr, input.maxOutputBytes, stderrTailBytes),
+        stdout,
+        stderr,
+        write_drift: input.writeDrift,
+        redaction: {
+            redacted: redactionState.count > 0,
+            redaction_count: redactionState.count,
+            redaction_kinds: [...redactionState.kinds].sort(),
+            fields: [...redactionState.fields].sort(),
+        },
         receipt_path: getReceiptRelativePath(),
     };
 }

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

@@ -0,0 +1,180 @@
+import { spawnSync } from 'node:child_process';
+import { lstatSync, 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 EXCLUDED_DIRECTORY_NAMES = new Set(['.git', 'node_modules']);
+const EXCLUDED_RELATIVE_DIRECTORY_PATHS = new Set(['.mustflow/state/runs']);
+function toPosixPath(value) {
+    return value.split(path.sep).join('/');
+}
+function normalizeRelativePath(value) {
+    return toPosixPath(value).replace(/^\.\/+/u, '').replace(/\/+$/u, '') || '.';
+}
+function pathKey(value) {
+    const normalized = normalizeRelativePath(value);
+    return process.platform === 'win32' ? normalized.toLowerCase() : normalized;
+}
+function isExcludedDirectory(relativePath, basename) {
+    const normalized = normalizeRelativePath(relativePath);
+    return EXCLUDED_DIRECTORY_NAMES.has(basename) || EXCLUDED_RELATIVE_DIRECTORY_PATHS.has(normalized);
+}
+function signatureForPath(fullPath) {
+    const stat = lstatSync(fullPath);
+    if (stat.isSymbolicLink()) {
+        return `symlink:${readlinkSync(fullPath)}`;
+    }
+    const type = stat.isDirectory() ? 'directory' : stat.isFile() ? 'file' : 'other';
+    return `${type}:${stat.size}:${stat.mtimeMs}`;
+}
+function collectSnapshotEntries(projectRoot, currentPath, entries) {
+    const names = readdirSync(currentPath).sort((left, right) => left.localeCompare(right));
+    for (const name of names) {
+        const fullPath = path.join(currentPath, name);
+        const relativePath = normalizeRelativePath(path.relative(projectRoot, fullPath));
+        const stat = lstatSync(fullPath);
+        if (stat.isDirectory()) {
+            if (isExcludedDirectory(relativePath, name)) {
+                continue;
+            }
+            collectSnapshotEntries(projectRoot, fullPath, entries);
+            continue;
+        }
+        if (entries.size >= MAX_SNAPSHOT_FILES) {
+            throw new Error('snapshot_file_limit_exceeded');
+        }
+        entries.set(relativePath, signatureForPath(fullPath));
+    }
+}
+function captureSnapshot(projectRoot) {
+    const gitSnapshot = captureGitStatusSnapshot(projectRoot);
+    if (gitSnapshot) {
+        return gitSnapshot;
+    }
+    try {
+        const entries = new Map();
+        collectSnapshotEntries(projectRoot, projectRoot, entries);
+        return { ok: true, entries, reason: null };
+    }
+    catch (error) {
+        return {
+            ok: false,
+            entries: new Map(),
+            reason: error instanceof Error && error.message.length > 0 ? error.message : 'snapshot_unavailable',
+        };
+    }
+}
+function captureGitStatusSnapshot(projectRoot) {
+    const result = spawnSync('git', ['-C', projectRoot, 'status', '--porcelain=v1', '-z', '--untracked-files=all'], {
+        encoding: 'utf8',
+        input: '',
+        stdio: ['ignore', 'pipe', 'pipe'],
+        windowsHide: true,
+    });
+    if (result.error || result.status !== 0) {
+        return null;
+    }
+    const entries = new Map();
+    const parts = result.stdout.split('\0').filter((part) => part.length > 0);
+    for (let index = 0; index < parts.length; index += 1) {
+        const entry = parts[index] ?? '';
+        const status = entry.slice(0, 2);
+        const filePath = normalizeRelativePath(entry.slice(3));
+        if (filePath.length === 0) {
+            continue;
+        }
+        entries.set(filePath, `git:${status}`);
+        if (status.includes('R') || status.includes('C')) {
+            index += 1;
+        }
+    }
+    return {
+        ok: true,
+        entries,
+        reason: null,
+    };
+}
+function listDeclaredWritePaths(projectRoot, contract, intentName) {
+    const paths = normalizeCommandEffects(projectRoot, contract, intentName)
+        .filter((effect) => effect.access === 'write')
+        .map((effect) => effect.path);
+    return [...new Set(paths.map(normalizeRelativePath))].sort((left, right) => left.localeCompare(right));
+}
+function listObservedChangedPaths(before, after) {
+    const paths = new Set([...before.keys(), ...after.keys()]);
+    const changed = [];
+    for (const filePath of paths) {
+        if (before.get(filePath) !== after.get(filePath)) {
+            changed.push(filePath);
+        }
+    }
+    return changed.sort((left, right) => left.localeCompare(right));
+}
+function declaredPathCoversObservedPath(declaredPath, observedPath) {
+    const declaredKey = pathKey(declaredPath);
+    const observedKey = pathKey(observedPath);
+    return declaredKey === '.' || observedKey === declaredKey || observedKey.startsWith(`${declaredKey}/`);
+}
+function truncatePaths(paths) {
+    if (paths.length <= MAX_REPORTED_PATHS) {
+        return { paths, truncated: false };
+    }
+    return { paths: paths.slice(0, MAX_REPORTED_PATHS), truncated: true };
+}
+export function startRunWriteTracking(projectRoot, contract, intentName) {
+    return {
+        projectRoot,
+        declaredPaths: listDeclaredWritePaths(projectRoot, contract, intentName),
+        before: captureSnapshot(projectRoot),
+    };
+}
+export function finishRunWriteTracking(tracker) {
+    if (!tracker.before.ok) {
+        return {
+            status: 'unavailable',
+            declared_paths: tracker.declaredPaths,
+            observed_paths: [],
+            declared_observed_paths: [],
+            undeclared_paths: [],
+            observed_count: 0,
+            undeclared_count: 0,
+            has_undeclared_changes: false,
+            truncated: false,
+            reason: tracker.before.reason,
+        };
+    }
+    const after = captureSnapshot(tracker.projectRoot);
+    if (!after.ok) {
+        return {
+            status: 'unavailable',
+            declared_paths: tracker.declaredPaths,
+            observed_paths: [],
+            declared_observed_paths: [],
+            undeclared_paths: [],
+            observed_count: 0,
+            undeclared_count: 0,
+            has_undeclared_changes: false,
+            truncated: false,
+            reason: after.reason,
+        };
+    }
+    const observedPaths = listObservedChangedPaths(tracker.before.entries, after.entries);
+    const declaredObservedPaths = observedPaths.filter((observedPath) => tracker.declaredPaths.some((declaredPath) => declaredPathCoversObservedPath(declaredPath, observedPath)));
+    const undeclaredPaths = observedPaths.filter((observedPath) => !tracker.declaredPaths.some((declaredPath) => declaredPathCoversObservedPath(declaredPath, observedPath)));
+    const observed = truncatePaths(observedPaths);
+    const declaredObserved = truncatePaths(declaredObservedPaths);
+    const undeclared = truncatePaths(undeclaredPaths);
+    return {
+        status: 'checked',
+        declared_paths: tracker.declaredPaths,
+        observed_paths: observed.paths,
+        declared_observed_paths: declaredObserved.paths,
+        undeclared_paths: undeclared.paths,
+        observed_count: observedPaths.length,
+        undeclared_count: undeclaredPaths.length,
+        has_undeclared_changes: undeclaredPaths.length > 0,
+        truncated: observed.truncated || declaredObserved.truncated || undeclared.truncated,
+        reason: null,
+    };
+}