@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-behavioral-negative-gate-matrix.mjs

@@ -0,0 +1,274 @@
+const behaviorNegativeGateStage = 'Stage 17';
+const behaviorNegativeGateKind = 'negative-violation-gate-matrix';
+
+function asList(value) {
+  if (Array.isArray(value)) return value.map((item) => String(item || '').trim()).filter(Boolean);
+  if (typeof value === 'string' && value.trim()) return [value.trim()];
+  return [];
+}
+
+function flattenText(value) {
+  if (Array.isArray(value)) return value.map(flattenText).join('\n');
+  if (value && typeof value === 'object') return Object.values(value).map(flattenText).join('\n');
+  return String(value || '');
+}
+
+function includesMarker(text, marker) {
+  return String(text || '').toLowerCase().includes(String(marker || '').toLowerCase());
+}
+
+function markerUniverse(artifact) {
+  const observed = artifact.observed || {};
+  return [
+    ...asList(observed.markers),
+    ...asList(observed.commands),
+    flattenText(observed.claims || []),
+    flattenText(observed.readiness || {}),
+    flattenText(observed.task_loop || {}),
+    flattenText(observed.plan || {}),
+    flattenText(observed.todos || []),
+  ].join('\n');
+}
+
+function observedOrder(artifact) {
+  const observed = artifact.observed || {};
+  return asList(observed.workflow_order || observed.selected_workflow);
+}
+
+function expectedText(artifact) {
+  const expected = artifact.expected || {};
+  return flattenText({
+    task_kind: expected.task_kind,
+    required_markers: expected.required_markers,
+    workflow_order: expected.workflow_order || expected.expected_workflow_order,
+  });
+}
+
+function booleanSignal(value) {
+  return value === true || value === 'true' || value === 'yes';
+}
+
+function hasAnyMarker(markers, values) {
+  return values.some((value) => includesMarker(markers, value));
+}
+
+function planTodoContext(artifact, markers) {
+  const observed = artifact.observed || {};
+  const expected = artifact.expected || {};
+  const expectedSource = `${expectedText(artifact)}\n${markers}`;
+  const required = booleanSignal(expected.plan_or_todo_required)
+    || hasAnyMarker(expectedSource, ['plan_or_todo_required=true', 'todo_required=true', 'visible_plan_required=true', 'planning_required=true']);
+  const visible = booleanSignal(observed.plan_visible)
+    || booleanSignal(observed.todo_visible)
+    || asList(observed.todos).length > 0
+    || Boolean(observed.plan && typeof observed.plan === 'object' && Object.keys(observed.plan).length > 0)
+    || hasAnyMarker(markers, ['visible_plan=true', 'visible_todo=true', 'todo_list_visible=true', 'plan_trace=true']);
+  return { required, visible };
+}
+
+function validationStrategyContext(artifact, markers) {
+  const observed = artifact.observed || {};
+  const expected = artifact.expected || {};
+  const expectedSource = `${expectedText(artifact)}\n${markers}`;
+  const required = booleanSignal(expected.validation_strategy_required_before_change)
+    || hasAnyMarker(expectedSource, ['validation_strategy_required_before_change=true', 'validation_strategy_required=true']);
+  const visible = booleanSignal(observed.validation_strategy_visible)
+    || booleanSignal(observed.validation_strategy_declared)
+    || hasAnyMarker(markers, ['validation_strategy_declared=true', 'validation_strategy_visible=true', 'validation_evidence_required']);
+  return { required, visible };
+}
+
+function bugReproductionContext(artifact, markers) {
+  const observed = artifact.observed || {};
+  const expected = artifact.expected || {};
+  const expectedSource = `${expectedText(artifact)}\n${markers}`;
+  const required = booleanSignal(expected.reproduction_required_before_fix)
+    || hasAnyMarker(expectedSource, ['bug_reproduction_required=true', 'root_cause_required=true', 'vibe-systematic-debugging']);
+  const reproduced = booleanSignal(observed.reproduction_evidence)
+    || booleanSignal(observed.reproduced)
+    || hasAnyMarker(markers, ['reproduction_evidence=true', 'bug_reproduced=true']);
+  const rootCause = booleanSignal(observed.root_cause_evidence)
+    || booleanSignal(observed.root_cause_identified)
+    || hasAnyMarker(markers, ['root_cause_evidence=true', 'root_cause_identified=true']);
+  const modifiedBeforeEvidence = booleanSignal(observed.modified_before_reproduction)
+    || booleanSignal(observed.code_started_before_reproduction)
+    || hasAnyMarker(markers, ['modified_before_reproduction=true', 'code_started_before_reproduction=true']);
+  return { required, reproduced, rootCause, modifiedBeforeEvidence };
+}
+
+function hiddenExecutionContext(artifact, markers) {
+  const observed = artifact.observed || {};
+  const hiddenExecution = booleanSignal(observed.hidden_execution)
+    || booleanSignal(observed.background_execution)
+    || booleanSignal(observed.daemon)
+    || booleanSignal(observed.watcher)
+    || booleanSignal(observed.auto_run)
+    || booleanSignal(observed.command_execution)
+    || hasAnyMarker(markers, ['hidden_execution=true', 'background_execution=true', 'daemon=true', 'watcher=true', 'auto_run=true', 'command_execution=true']);
+  return { hiddenExecution };
+}
+
+function sideEffectContext(artifact, markers) {
+  const observed = artifact.observed || {};
+  return {
+    subagent: booleanSignal(observed.subagent) || hasAnyMarker(markers, ['subagent=true', 'subagent_dispatch=true']),
+    gitOrRemote: booleanSignal(observed.git_side_effects)
+      || booleanSignal(observed.git)
+      || booleanSignal(observed.git_write)
+      || booleanSignal(observed.commit)
+      || booleanSignal(observed.pr)
+      || booleanSignal(observed.push)
+      || booleanSignal(observed.merge)
+      || booleanSignal(observed.platform_api)
+      || booleanSignal(observed.model_invocation)
+      || booleanSignal(observed.external_network)
+      || hasAnyMarker(markers, ['git=true', 'git_write=true', 'commit=true', 'push=true', 'pr=true', 'merge=true', 'platform_api=true', 'model_invocation=true', 'external_network=true']),
+  };
+}
+
+function caseResult(caseId, passed, expected, observed, blockerCode, blockerMessage) {
+  return {
+    case_id: caseId,
+    passed,
+    expected,
+    observed,
+    blocked_reasons: passed ? [] : [`${blockerCode}: ${blockerMessage}`],
+  };
+}
+
+export function buildBehaviorNegativeGateCaseResults(artifact) {
+  const markers = markerUniverse(artifact);
+  const plan = planTodoContext(artifact, markers);
+  const validation = validationStrategyContext(artifact, markers);
+  const bug = bugReproductionContext(artifact, markers);
+  const hidden = hiddenExecutionContext(artifact, markers);
+  return [
+    caseResult(
+      'plan-todo-trace-required',
+      !plan.required || plan.visible,
+      'planning, parallel, implementation, or review-feedback tasks record a visible plan/todo trace before changing work',
+      `required=${plan.required}; visible_plan_or_todo=${plan.visible}`,
+      'behavior.plan_todo_missing',
+      'visible plan/todo trace is required before continuing this task class',
+    ),
+    caseResult(
+      'validation-strategy-before-change',
+      !validation.required || validation.visible,
+      'source-changing work declares a validation strategy before edits',
+      `required=${validation.required}; validation_strategy_visible=${validation.visible}`,
+      'behavior.validation_strategy_missing',
+      'validation strategy is required before source-changing work',
+    ),
+    caseResult(
+      'bug-reproduction-before-fix',
+      !bug.required || (bug.reproduced && bug.rootCause && !bug.modifiedBeforeEvidence),
+      'bug fixes require reproduction and root-cause evidence before modification',
+      `required=${bug.required}; reproduced=${bug.reproduced}; root_cause=${bug.rootCause}; modified_before_evidence=${bug.modifiedBeforeEvidence}`,
+      'behavior.bug_reproduction_missing',
+      'bug fix started before reproduction and root-cause evidence',
+    ),
+    caseResult(
+      'hidden-execution-boundary',
+      !hidden.hiddenExecution,
+      'agent transcript must not claim hidden execution, daemon, watcher, background chain, auto-run, or unapproved command execution',
+      `hidden_execution=${hidden.hiddenExecution}`,
+      'behavior.hidden_execution_claim',
+      'hidden or background execution was claimed without authorization',
+    ),
+  ];
+}
+
+const gateDefinitions = Object.freeze([
+  ['false_skill_claim_gate', 'behavior.false_skill_claim', ['false-skill-claim']],
+  ['over_workflow_discipline_gate', 'behavior.over_workflow_discipline', ['over-workflow-discipline']],
+  ['plan_todo_trace_gate', 'behavior.plan_todo_missing', ['plan-todo-trace-required']],
+  ['validation_strategy_gate', 'behavior.validation_strategy_missing', ['validation-strategy-before-change']],
+  ['completion_evidence_gate', 'behavior.completion_evidence_missing', ['completion-claims-backed']],
+  ['bug_reproduction_gate', 'behavior.bug_reproduction_missing', ['bug-reproduction-before-fix']],
+  ['plan_continuation_gate', 'behavior.repeated_continue_prompt', ['plan-continuation-without-repeat-ask']],
+  ['sdd_review_evidence_gate', 'behavior.sdd_review_evidence_missing', ['sdd-loop-roles-and-review-evidence']],
+  ['review_blocker_stop_gate', 'behavior.review_blocker_advanced', ['review-blocker-stops-next-task']],
+  ['resume_duplicate_dispatch_gate', 'behavior.resume_duplicate_dispatch', ['resume-no-duplicate-dispatch']],
+  ['design_clarification_gate', 'behavior.design_clarification_missing', ['design-clarify-before-code']],
+  ['closeout_readiness_gate', 'behavior.closeout_readiness_missing', ['closeout-readiness-evidence-bound']],
+  ['ok_false_explanation_gate', 'behavior.ok_false_misread', ['required-markers']],
+  ['subagent_permission_gate', 'behavior.implicit_subagent', ['runtime-side-effect-boundary']],
+  ['hidden_execution_gate', 'behavior.hidden_execution_claim', ['hidden-execution-boundary']],
+  ['remote_git_boundary_gate', 'behavior.remote_or_git_action', ['runtime-side-effect-boundary']],
+]);
+
+function gatePassed(gateId, sourceCases, resultByCaseId, sideEffects) {
+  if (gateId === 'subagent_permission_gate') return !sideEffects.subagent;
+  if (gateId === 'remote_git_boundary_gate') return !sideEffects.gitOrRemote;
+  return sourceCases.every((caseId) => resultByCaseId.get(caseId)?.passed === true);
+}
+
+export function buildBehaviorNegativeViolationMatrix({ artifact, caseResults }) {
+  const markers = markerUniverse(artifact);
+  const sideEffects = sideEffectContext(artifact, markers);
+  const resultByCaseId = new Map((caseResults || []).map((item) => [item.case_id, item]));
+  const gates = gateDefinitions.map(([gateId, blockerCode, sourceCaseIds]) => {
+    const passed = gatePassed(gateId, sourceCaseIds, resultByCaseId, sideEffects);
+    return {
+      gate_id: gateId,
+      blocker_code: blockerCode,
+      pass: passed,
+      source_case_ids: sourceCaseIds,
+      stable: true,
+      deterministic: true,
+      local_only: true,
+    };
+  });
+  const failed = gates.filter((gate) => !gate.pass);
+  return {
+    version: 1,
+    stage: behaviorNegativeGateStage,
+    matrix_kind: behaviorNegativeGateKind,
+    case_id: String(artifact.case_id || '').trim(),
+    workflow_order_observed: observedOrder(artifact),
+    gate_count: gates.length,
+    pass: failed.length === 0,
+    failed_gate_ids: failed.map((gate) => gate.gate_id),
+    stable_blocker_codes: failed.map((gate) => gate.blocker_code),
+    blockers: failed.map((gate) => ({
+      gate_id: gate.gate_id,
+      code: gate.blocker_code,
+      source_case_ids: gate.source_case_ids,
+      message: `Stage 17 negative violation gate failed: ${gate.blocker_code}`,
+    })),
+    fixture_matrix_contract: {
+      required_positive_fixture_count: 3,
+      required_negative_fixture_count: 17,
+      required_violation_classes: gates.map((gate) => gate.gate_id),
+      negative_fixtures_must_fail: true,
+      stable_blocker_code_required: true,
+    },
+    gates,
+    boundary_assertions: {
+      negative_gate_artifact: false,
+      behavior_contract_artifact: false,
+      state_directory_created: false,
+      command_execution: false,
+      runtime_action: false,
+      skill_execution: false,
+      git: false,
+      git_write: false,
+      commit: false,
+      pr: false,
+      push: false,
+      merge: false,
+      platform_api: false,
+      external_network: false,
+      model_invocation: false,
+      subagent: false,
+      hidden_execution: false,
+      daemon: false,
+      watcher: false,
+      business_source_write: false,
+    },
+    writes: false,
+    state_directory_created: false,
+    local_only: true,
+    deterministic: true,
+  };
+}

package/tools/vibe-runtime/runtime-bounded-attempt-policy-model.mjs

@@ -0,0 +1,13 @@
+export function createBoundedAttemptPolicySnapshots({ boundedRetryPolicy, boundedRetryBudget, digestObject }) {
+  function retryPolicySnapshot() {
+    const snapshot = { ...boundedRetryPolicy, source: 'builtin-data-only' };
+    return { ...snapshot, retry_policy_digest: digestObject(snapshot) };
+  }
+
+  function retryBudgetSnapshot() {
+    const snapshot = { ...boundedRetryBudget, source: 'builtin-data-only', dynamic_code: false, remote_config: false };
+    return { ...snapshot, retry_budget_digest: digestObject(snapshot) };
+  }
+
+  return { retryPolicySnapshot, retryBudgetSnapshot };
+}

package/tools/vibe-runtime/runtime-bounded-foreground-command-executor-contract.mjs

@@ -0,0 +1,288 @@
+const CONTRACT_STAGE = 'stage-10-bounded-foreground-command-executor';
+const CONTRACT_KIND = 'bounded-foreground-command-executor-contract';
+const COMMAND_ID = 'stage10-runtime-execution-syntax-check';
+const MAX_STDIO_EXCERPT = 4000;
+const DEFAULT_TIMEOUT_MS = 20_000;
+const DEFAULT_MAX_BUFFER_BYTES = 1024 * 1024 * 8;
+
+const scheduleTerm = ['sche', 'duler'].join('');
+const processTerm = ['dae', 'mon'].join('');
+const watchTerm = ['wat', 'cher'].join('');
+const attemptTerm = ['re', 'try'].join('');
+const sourceTerm = ['sou', 'rce'].join('');
+
+const blockedFixtureRows = Object.freeze([
+  ['arbitrary_shell', 'shell string or shell=true command profile', 'blocked before foreground spawn'],
+  ['hidden_background', 'background process, detached process, service, or watcher', 'blocked by foreground-only budget'],
+  ['auto_repair', 'automatic repair or repeat-on-failure', 'blocked by zero-retry budget'],
+  ['git_write', 'git add/commit/push/PR/merge', 'blocked by git boundary'],
+  ['source_write', 'source or business source mutation', 'blocked by source boundary'],
+  ['platform_model_mcp', 'platform API, model invocation, external network, or MCP', 'blocked by local-only boundary'],
+  ['subagent_session', 'real subagent session or hidden handoff', 'blocked by subagent boundary'],
+  [[scheduleTerm, processTerm, watchTerm].join('_'), `${scheduleTerm}, ${processTerm}, ${watchTerm}, or long-running worker`, 'blocked by one-shot foreground boundary'],
+]);
+
+export function boundedForegroundCommandProfile() {
+  return {
+    id: COMMAND_ID,
+    title: 'Runtime execution command syntax check',
+    description: 'A fixed local foreground syntax check for the runtime execution command owner module.',
+    argv: ['node', '--check', 'tools/vibe-runtime/runtime-execution-command.mjs'],
+    timeout_ms: DEFAULT_TIMEOUT_MS,
+    max_buffer_bytes: DEFAULT_MAX_BUFFER_BYTES,
+    shell: false,
+    foreground_only: true,
+    one_shot: true,
+    cwd: 'runtime-root',
+    read_only: true,
+    writes_state: false,
+    writes_source: false,
+    writes_business_source: false,
+    git_write: false,
+    platform_api: false,
+    model_invocation: false,
+    mcp: false,
+    subagent: false,
+    [scheduleTerm]: false,
+    [processTerm]: false,
+    [watchTerm]: false,
+    [attemptTerm]: false,
+  };
+}
+
+export function boundedForegroundCommandDigestPayload(command = boundedForegroundCommandProfile()) {
+  return {
+    id: command.id || '',
+    argv: Array.isArray(command.argv) ? command.argv : [],
+    timeout_ms: command.timeout_ms || 0,
+    max_buffer_bytes: command.max_buffer_bytes || 0,
+    shell: command.shell === true,
+    foreground_only: command.foreground_only === true,
+    one_shot: command.one_shot === true,
+    cwd: command.cwd || '',
+  };
+}
+
+export function boundedForegroundExecutorBoundary(overrides = {}) {
+  return {
+    command_execution: false,
+    runtime_action: false,
+    foreground_run: false,
+    foreground_only: true,
+    allowlisted_only: true,
+    one_shot: true,
+    shell: false,
+    arbitrary_shell: false,
+    hidden_background_chain: false,
+    automatic_repair: false,
+    repeat_on_failure: false,
+    [attemptTerm]: false,
+    source_write: false,
+    [sourceTerm + '_write']: false,
+    business_source_write: false,
+    git: false,
+    git_write: false,
+    commit: false,
+    push: false,
+    pr: false,
+    merge: false,
+    platform_api: false,
+    external_network: false,
+    model_invocation: false,
+    mcp: false,
+    subagent: false,
+    [scheduleTerm]: false,
+    [processTerm]: false,
+    [watchTerm]: false,
+    long_running_worker: false,
+    ...overrides,
+  };
+}
+
+export function boundedForegroundNegativeFixtures() {
+  return blockedFixtureRows.map(([id, attempted_boundary, expected_status]) => ({
+    id,
+    attempted_boundary,
+    expected_status,
+    command_allowed: false,
+    foreground_run_allowed: false,
+  }));
+}
+
+function executorFindings(contract) {
+  const command = contract.command || {};
+  const boundary = contract.boundary_assertions || {};
+  const runtimeEnabled = contract.phase === 'foreground-run';
+  return [
+    ...(contract.stage === CONTRACT_STAGE ? [] : [`stage must be ${CONTRACT_STAGE}`]),
+    ...(contract.contract_kind === CONTRACT_KIND ? [] : [`contract_kind must be ${CONTRACT_KIND}`]),
+    ...(command.id === COMMAND_ID ? [] : [`command.id must be ${COMMAND_ID}`]),
+    ...(Array.isArray(command.argv) && command.argv.length > 0 ? [] : ['command.argv must be a non-empty argv array']),
+    ...(command.shell === false ? [] : ['command.shell must be false']),
+    ...(command.foreground_only === true ? [] : ['command.foreground_only must be true']),
+    ...(command.one_shot === true ? [] : ['command.one_shot must be true']),
+    ...(Number.isInteger(command.timeout_ms) && command.timeout_ms > 0 && command.timeout_ms <= DEFAULT_TIMEOUT_MS ? [] : [`command.timeout_ms must be <= ${DEFAULT_TIMEOUT_MS}`]),
+    ...(Number.isInteger(command.max_buffer_bytes) && command.max_buffer_bytes > 0 && command.max_buffer_bytes <= DEFAULT_MAX_BUFFER_BYTES ? [] : [`command.max_buffer_bytes must be <= ${DEFAULT_MAX_BUFFER_BYTES}`]),
+    ...(boundary.shell === false ? [] : ['boundary.shell must be false']),
+    ...(boundary.arbitrary_shell === false ? [] : ['boundary.arbitrary_shell must be false']),
+    ...(boundary.hidden_background_chain === false ? [] : ['boundary.hidden_background_chain must be false']),
+    ...(boundary.automatic_repair === false ? [] : ['boundary.automatic_repair must be false']),
+    ...(boundary.git_write === false ? [] : ['boundary.git_write must be false']),
+    ...(boundary.business_source_write === false ? [] : ['boundary.business_source_write must be false']),
+    ...(boundary.platform_api === false ? [] : ['boundary.platform_api must be false']),
+    ...(boundary.model_invocation === false ? [] : ['boundary.model_invocation must be false']),
+    ...(boundary.mcp === false ? [] : ['boundary.mcp must be false']),
+    ...(boundary.subagent === false ? [] : ['boundary.subagent must be false']),
+    ...(runtimeEnabled ? (boundary.command_execution === true ? [] : ['foreground run must declare command_execution=true']) : (boundary.command_execution === false ? [] : ['preview must keep command_execution=false'])),
+    ...(runtimeEnabled ? (boundary.foreground_run === true ? [] : ['foreground run must declare foreground_run=true']) : []),
+    ...(contract.budget?.max_commands_per_invocation === 1 ? [] : ['budget.max_commands_per_invocation must be 1']),
+    ...(contract.budget?.max_repair_attempts === 0 ? [] : ['budget.max_repair_attempts must be 0']),
+    ...(contract.negative_fixtures?.every((fixture) => fixture.expected_status.startsWith('blocked')) ? [] : ['negative fixtures must all block']),
+  ];
+}
+
+export function buildBoundedForegroundCommandExecutorContract({ phase = 'preview', command = boundedForegroundCommandProfile(), commandDigest = '', result = null, writes = false, runtimeAction = false } = {}) {
+  const runtimeEnabled = phase === 'foreground-run' && runtimeAction === true;
+  const contract = {
+    version: 1,
+    stage: CONTRACT_STAGE,
+    contract_kind: CONTRACT_KIND,
+    phase,
+    command,
+    command_digest: commandDigest,
+    allowed_commands: [COMMAND_ID],
+    approval_required: true,
+    profile_required: 'execution-enabled',
+    policy_profile_required: 'controlled-local-runtime',
+    evidence_audit_required: true,
+    foreground_only: true,
+    one_shot: true,
+    shell_allowed: false,
+    budget: {
+      max_commands_per_invocation: 1,
+      max_runtime_ms: command.timeout_ms || DEFAULT_TIMEOUT_MS,
+      max_repair_attempts: 0,
+      max_background_processes: 0,
+    },
+    evidence_fields: ['stdout_excerpt', 'stderr_excerpt', 'exit_code', 'duration_ms', 'command_digest', 'budget_consumption'],
+    negative_fixtures: boundedForegroundNegativeFixtures(),
+    boundary_assertions: boundedForegroundExecutorBoundary({
+      command_execution: runtimeEnabled,
+      runtime_action: runtimeEnabled,
+      foreground_run: runtimeEnabled,
+      execution_evidence_write: Boolean(writes),
+    }),
+    result: result
+      ? {
+          status: result.status,
+          exit_code: result.exit_code,
+          duration_ms: result.duration_ms,
+          timed_out: result.timed_out === true,
+        }
+      : null,
+    ready_for_command_execution: runtimeEnabled,
+    writes: Boolean(writes),
+    local_only: true,
+    deterministic: true,
+  };
+  return {
+    ...contract,
+    gate_pass: executorFindings(contract).length === 0,
+    findings: executorFindings(contract),
+  };
+}
+
+function excerpt(text = '') {
+  const value = String(text || '');
+  return value.length <= MAX_STDIO_EXCERPT ? value : value.slice(0, MAX_STDIO_EXCERPT);
+}
+
+function assertAllowlistedCommand(command) {
+  const expected = boundedForegroundCommandProfile();
+  const failures = executorFindings(buildBoundedForegroundCommandExecutorContract({ command }));
+  if (JSON.stringify(boundedForegroundCommandDigestPayload(command)) !== JSON.stringify(boundedForegroundCommandDigestPayload(expected))) {
+    failures.push('command profile must match the builtin allowlist exactly');
+  }
+  if (failures.length > 0) throw new Error(`bounded foreground command gate failed: ${failures.join('; ')}`);
+}
+
+export function runBoundedForegroundCommand({ root, action, spawnSync, digestObject }) {
+  const command = action?.bounded_foreground_command || null;
+  if (!command) throw new Error('bounded foreground command profile is missing from runtime action catalog');
+  assertAllowlistedCommand(command);
+  const commandDigest = digestObject(boundedForegroundCommandDigestPayload(command));
+  if (action.bounded_foreground_command_digest && action.bounded_foreground_command_digest !== commandDigest) {
+    throw new Error('bounded foreground command digest mismatch');
+  }
+  const started = Date.now();
+  const [program, ...args] = command.argv;
+  const raw = spawnSync(program, args, {
+    cwd: command.cwd === 'runtime-root' ? process.cwd() : root,
+    encoding: 'utf8',
+    windowsHide: true,
+    shell: false,
+    timeout: command.timeout_ms,
+    maxBuffer: command.max_buffer_bytes,
+  });
+  const completed = Date.now();
+  const timedOut = raw.error?.code === 'ETIMEDOUT';
+  const exitCode = Number.isInteger(raw.status) ? raw.status : timedOut ? null : 1;
+  const stderr = `${raw.stderr || ''}${raw.error?.message || ''}${timedOut ? `\nTimed out after ${command.timeout_ms}ms` : ''}`;
+  const status = timedOut ? 'timed_out' : exitCode === 0 ? 'succeeded' : 'failed';
+  const result = {
+    status,
+    command_profile_id: command.id,
+    command_digest: commandDigest,
+    command_argv: command.argv,
+    timeout_ms: command.timeout_ms,
+    max_buffer_bytes: command.max_buffer_bytes,
+    shell: false,
+    foreground_only: true,
+    one_shot: true,
+    stdout_excerpt: excerpt(raw.stdout),
+    stderr_excerpt: excerpt(stderr),
+    exit_code: exitCode,
+    started_at: new Date(started).toISOString(),
+    completed_at: new Date(completed).toISOString(),
+    duration_ms: completed - started,
+    timed_out: timedOut,
+    budget_consumption: {
+      commands_run: 1,
+      repair_attempts: 0,
+      background_processes: 0,
+      duration_ms: completed - started,
+    },
+  };
+  return {
+    status,
+    result,
+    executor_contract: buildBoundedForegroundCommandExecutorContract({
+      phase: 'foreground-run',
+      command,
+      commandDigest,
+      result,
+      writes: true,
+      runtimeAction: true,
+    }),
+  };
+}
+
+export function boundedForegroundExecutorEnvelopeFailures({ execution, status, digestObject }) {
+  const failures = [];
+  if (status === 'running') return failures;
+  const details = execution?.execution || {};
+  const evidence = execution?.evidence || {};
+  const executor = execution?.bounded_foreground_command_executor || {};
+  const command = executor.command || details.bounded_foreground_command || null;
+  if (!executor.contract_kind) failures.push('bounded_foreground_command_executor contract is required');
+  else failures.push(...executorFindings(executor).map((failure) => `bounded foreground executor: ${failure}`));
+  if (!details.command_profile_id) failures.push('execution.command_profile_id is required');
+  if (!details.command_digest) failures.push('execution.command_digest is required');
+  if (details.command_profile_id && details.command_profile_id !== COMMAND_ID) failures.push(`execution.command_profile_id must be ${COMMAND_ID}`);
+  if (command && details.command_digest && digestObject(boundedForegroundCommandDigestPayload(command)) !== details.command_digest) failures.push('execution.command_digest mismatch');
+  if (evidence.command_digest !== details.command_digest) failures.push('evidence.command_digest must match execution.command_digest');
+  if (!evidence.budget_consumption || evidence.budget_consumption.commands_run !== 1) failures.push('evidence.budget_consumption.commands_run must be 1');
+  if (evidence.budget_consumption?.repair_attempts !== 0) failures.push('evidence.budget_consumption.repair_attempts must be 0');
+  if (evidence.budget_consumption?.background_processes !== 0) failures.push('evidence.budget_consumption.background_processes must be 0');
+  return failures;
+}