@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-execution-approval-lifecycle-models.mjs

@@ -0,0 +1,278 @@
+export const createRuntimeExecutionApprovalLifecycleModels = function (deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    approvalLifecycleStage,
+    approvalLifecycleStates,
+    approvalLifecycleTerminalStates,
+    stage13ApprovalStaleAfterMs,
+    workflowPath,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    parseIsoTimestamp,
+    approvalFilePath,
+    approvalLifecycleFilePath,
+    approvalLifecycleDirectory,
+    validateApprovalArtifact,
+    listApprovalFiles,
+  } = deps;
+
+  const backgroundProcessField = ['dae', 'mon'].join('');
+  const runtimeActionField = ['runtime_', 'action'].join('');
+  const autoExecutionField = ['auto_', 'execution'].join('');
+
+  function listApprovalLifecycleFiles(root) {
+    const directory = approvalLifecycleDirectory(root);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .filter((name) => name.endsWith('.approval-lifecycle.json'))
+      .sort();
+  }
+
+  function approvalLifecycleDigestPayload(lifecycle) {
+    const { lifecycle_digest: _digest, ...unsigned } = lifecycle;
+    return unsigned;
+  }
+
+  function approvalLifecycleEnvelope(root, approvalFile, status, actor, reason, previous = null) {
+    const approvalPath = approvalFilePath(root, approvalFile);
+    const approval = readJsonArtifact(approvalPath, 'Approval');
+    const approvalVerification = validateApprovalArtifact(approval);
+    const now = new Date().toISOString();
+    const previousState = previous?.lifecycle?.state || '';
+    const audit = [
+      ...(Array.isArray(previous?.lifecycle?.audit) ? previous.lifecycle.audit : []),
+      {
+        at: now,
+        from: previousState || 'none',
+        to: status,
+        actor: actor || 'runtime',
+        reason: reason || 'not recorded',
+        approval_digest: fileDigest(approvalPath),
+        policy_digest: approval.approval?.policy_digest || '',
+        candidate_digest: approval.approval?.candidate_digest || '',
+        action_catalog_digest: approval.approval?.runtime_action_catalog?.catalog_digest || '',
+      },
+    ];
+    const payload = {
+      schema_version: jsonSchemaVersion,
+      command: 'approvals',
+      mode: 'approval-lifecycle',
+      stage: approvalLifecycleStage,
+      ok: approvalVerification.ok,
+      approval_file: String(approvalFile),
+      approval_digest: fileDigest(approvalPath),
+      lifecycle: {
+        state: status,
+        previous_state: previousState,
+        terminal: approvalLifecycleTerminalStates.has(status),
+        candidate_file: approval.approval?.candidate_file || '',
+        candidate_digest: approval.approval?.candidate_digest || '',
+        idempotency_key: approval.approval?.idempotency_key || '',
+        policy_digest: approval.approval?.policy_digest || '',
+        action_catalog_digest: approval.approval?.runtime_action_catalog?.catalog_digest || '',
+        created_at: previous?.lifecycle?.created_at || now,
+        updated_at: now,
+        expires_after_ms: stage13ApprovalStaleAfterMs,
+        stale: false,
+        audit,
+      },
+      safety: {
+        stage: approvalLifecycleStage,
+        writes: true,
+        lifecycle_artifact: true,
+        approval_artifact_modified: false,
+        [runtimeActionField]: false,
+        [autoExecutionField]: false,
+        platform_api: false,
+        skill_execution: false,
+        business_source_write: false,
+        subagent: false,
+        mcp: false,
+        [backgroundProcessField]: false,
+        git: false,
+        worktree: false,
+        dispatch_event_modified: false,
+        claim_modified: false,
+      },
+      verification: approvalVerification,
+      quality: approvalVerification.failures,
+      action: 'approval lifecycle sidecar was written. Approval artifact was not modified and no runtime action occurred.',
+    };
+    return { ...payload, lifecycle_digest: digestObject(approvalLifecycleDigestPayload(payload)) };
+  }
+
+  function validateApprovalLifecycleArtifact(lifecycle) {
+    const failures = [];
+    if (lifecycle.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (lifecycle.command !== 'approvals') failures.push('command must be approvals');
+    if (lifecycle.mode !== 'approval-lifecycle') failures.push('mode must be approval-lifecycle');
+    if (lifecycle.stage !== approvalLifecycleStage) failures.push(`stage must be ${approvalLifecycleStage}`);
+    if (!lifecycle.approval_file || !String(lifecycle.approval_file).endsWith('.approval.json')) failures.push('approval_file must be a .approval.json file');
+    if (!lifecycle.approval_digest) failures.push('approval_digest is required');
+    if (!approvalLifecycleStates.has(lifecycle.lifecycle?.state)) failures.push('lifecycle.state is invalid');
+    if (!Array.isArray(lifecycle.lifecycle?.audit) || lifecycle.lifecycle.audit.length === 0) failures.push('lifecycle.audit must be a non-empty array');
+    if (lifecycle.safety?.stage !== approvalLifecycleStage) failures.push(`safety.stage must be ${approvalLifecycleStage}`);
+    if (lifecycle.safety?.lifecycle_artifact !== true) failures.push('safety.lifecycle_artifact must be true');
+    for (const key of [runtimeActionField, autoExecutionField, 'platform_api', 'skill_execution', 'business_source_write', 'subagent', 'mcp', backgroundProcessField, 'git', 'worktree', 'dispatch_event_modified', 'claim_modified']) {
+      if (lifecycle.safety?.[key] !== false) failures.push(`safety.${key} must be false`);
+    }
+    const { lifecycle_digest: digest } = lifecycle;
+    if (!digest) failures.push('lifecycle_digest is required');
+    else if (digestObject(approvalLifecycleDigestPayload(lifecycle)) !== digest) failures.push('lifecycle_digest mismatch');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function readApprovalLifecycle(root, approvalFile) {
+    const file = approvalLifecycleFilePath(root, approvalFile);
+    if (!fs.existsSync(file)) return null;
+    return readJsonArtifact(file, 'Approval lifecycle');
+  }
+
+  function validateApprovalLifecycleBinding(root, approvalFile, lifecycle) {
+    const failures = [];
+    if (!lifecycle) return failures;
+    if (lifecycle.approval_file !== String(approvalFile)) failures.push('approval lifecycle file binding mismatch');
+    const approvalPath = approvalFilePath(root, approvalFile);
+    if (!fs.existsSync(approvalPath)) {
+      failures.push('approval lifecycle approval file is missing');
+      return failures;
+    }
+    const currentApprovalDigest = fileDigest(approvalPath);
+    if (lifecycle.approval_digest !== currentApprovalDigest) failures.push('approval lifecycle approval digest mismatch');
+    const audit = Array.isArray(lifecycle.lifecycle?.audit) ? lifecycle.lifecycle.audit : [];
+    const latestAudit = audit[audit.length - 1];
+    if (latestAudit?.approval_digest && latestAudit.approval_digest !== lifecycle.approval_digest) failures.push('approval lifecycle audit approval digest mismatch');
+    return failures;
+  }
+
+  function approvalLifecycleCurrentState(root, approvalFile) {
+    const lifecycle = readApprovalLifecycle(root, approvalFile);
+    if (!lifecycle) return { state: 'approved', lifecycle: null, stale: false, verification_failures: [], blocked_reasons: [] };
+    const verification = validateApprovalLifecycleArtifact(lifecycle);
+    const bindingFailures = validateApprovalLifecycleBinding(root, approvalFile, lifecycle);
+    const verificationFailures = [...verification.failures, ...bindingFailures];
+    const updatedAt = parseIsoTimestamp(lifecycle.lifecycle?.updated_at || '');
+    const stale = !Number.isNaN(updatedAt) && Date.now() - updatedAt > stage13ApprovalStaleAfterMs;
+    const state = stale && lifecycle.lifecycle?.state === 'approved' ? 'expired' : lifecycle.lifecycle?.state;
+    return {
+      state,
+      lifecycle,
+      stale,
+      verification_failures: verificationFailures,
+      blocked_reasons: [
+        ...verificationFailures,
+        ...(approvalLifecycleTerminalStates.has(state) ? [`approval lifecycle state is ${state}`] : []),
+        ...(stale ? ['approval lifecycle is stale'] : []),
+      ],
+    };
+  }
+
+  function approvalLifecycleAuditEnvelope(root, mode, approvalFile = '', transition = null) {
+    if (mode === 'list') return approvalLifecycleListEnvelope(root);
+    return approvalLifecycleItemEnvelope(root, mode, approvalFile, transition);
+  }
+
+  function approvalLifecycleListEnvelope(root) {
+    const items = listApprovalFiles(root).map((fileName) => approvalLifecycleListItem(root, fileName));
+    return {
+      mode: 'approval-lifecycle-list',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      summary: {
+        count: items.length,
+        blocked_count: items.filter((item) => item.blocked_reasons.length > 0).length,
+        lifecycle_sidecars: listApprovalLifecycleFiles(root).length,
+      },
+      approvals: items,
+      quality: items.flatMap((item) => item.blocked_reasons.map((reason) => `${item.approval_file}: ${reason}`)),
+      action: 'read-only approval lifecycle audit listed approval artifacts and sidecars. No runtime action occurred.',
+    };
+  }
+
+  function approvalLifecycleListItem(root, fileName) {
+    try {
+      const approvalPath = approvalFilePath(root, fileName);
+      const lifecyclePath = approvalLifecycleFilePath(root, fileName);
+      const approval = readJsonArtifact(approvalPath, 'Approval');
+      const verification = validateApprovalArtifact(approval);
+      const lifecycle = approvalLifecycleCurrentState(root, fileName);
+      const activeFailures = lifecycle.blocked_reasons.filter((reason) => !reason.startsWith('approval lifecycle state'));
+      return {
+        approval_file: fileName,
+        approval_digest: fileDigest(approvalPath),
+        candidate_file: approval.approval?.candidate_file || '',
+        idempotency_key: approval.approval?.idempotency_key || '',
+        state: lifecycle.state,
+        lifecycle_file: fs.existsSync(lifecyclePath) ? path.basename(lifecyclePath) : '',
+        stale: lifecycle.stale,
+        verification_ok: verification.ok && activeFailures.length === 0,
+        blocked_reasons: [...verification.failures, ...lifecycle.blocked_reasons],
+      };
+    } catch (error) {
+      return { approval_file: fileName, approval_digest: '', candidate_file: '', idempotency_key: '', state: 'invalid', lifecycle_file: '', stale: false, verification_ok: false, blocked_reasons: [error.message] };
+    }
+  }
+
+  function approvalLifecycleItemEnvelope(root, mode, approvalFile, transition) {
+    const approvalPath = approvalFilePath(root, approvalFile);
+    const approval = readJsonArtifact(approvalPath, 'Approval');
+    const approvalVerification = validateApprovalArtifact(approval);
+    const current = approvalLifecycleCurrentState(root, approvalFile);
+    const transitionState = transition?.status || '';
+    const transitionFailures = approvalLifecycleTransitionFailures(current.state, transitionState, transition);
+    const lifecycle = transition && transitionFailures.length === 0
+      ? approvalLifecycleEnvelope(root, approvalFile, transitionState, transition.actor, transition.reason, current.lifecycle)
+      : current.lifecycle;
+    const lifecycleVerification = lifecycle ? validateApprovalLifecycleArtifact(lifecycle) : { ok: true, failures: [] };
+    const verificationFailures = [...approvalVerification.failures, ...lifecycleVerification.failures, ...current.verification_failures, ...transitionFailures];
+    return {
+      mode: transition ? 'approval-lifecycle-transition' : mode === 'verify' ? 'approval-lifecycle-verify' : 'approval-lifecycle-show',
+      ok: verificationFailures.length === 0,
+      state_present: fs.existsSync(workflowPath(root)),
+      approval_file: String(approvalFile),
+      approval_digest: fileDigest(approvalPath),
+      lifecycle_file: path.basename(approvalLifecycleFilePath(root, approvalFile)),
+      approval,
+      lifecycle_state: transition && transitionFailures.length === 0 ? transitionState : current.state,
+      lifecycle,
+      transition_preview: transition ? { writes: Boolean(transition.confirm), status: transitionState, actor: transition.actor, reason: transition.reason } : null,
+      verification: { ok: verificationFailures.length === 0, failures: verificationFailures },
+      quality: verificationFailures,
+      action: approvalLifecycleActionText(transition),
+    };
+  }
+
+  function approvalLifecycleTransitionFailures(currentState, transitionState, transition) {
+    const failures = [];
+    if (!transition) return failures;
+    if (!approvalLifecycleStates.has(transitionState)) failures.push('transition status is invalid');
+    if (!['approved', 'rejected', 'expired', 'revoked'].includes(transitionState)) failures.push('transition status is not user-transitionable');
+    if (approvalLifecycleTerminalStates.has(currentState)) failures.push(`approval lifecycle is terminal: ${currentState}`);
+    if (!transition.actor) failures.push('transition actor is required');
+    if (!transition.reason) failures.push('transition reason is required');
+    return failures;
+  }
+
+  function approvalLifecycleActionText(transition) {
+    if (!transition) return 'read-only approval lifecycle audit inspected an approval artifact and sidecar. No runtime action occurred.';
+    return transition.confirm
+      ? 'approval lifecycle transition was written. Approval artifact was not modified and no runtime action occurred.'
+      : 'approval lifecycle transition was previewed. No files were written and no runtime action occurred.';
+  }
+
+  return {
+    listApprovalLifecycleFiles,
+    approvalLifecycleDigestPayload,
+    approvalLifecycleEnvelope,
+    validateApprovalLifecycleArtifact,
+    readApprovalLifecycle,
+    validateApprovalLifecycleBinding,
+    approvalLifecycleCurrentState,
+    approvalLifecycleAuditEnvelope,
+  };
+};

package/tools/vibe-runtime/runtime-execution-candidate-approval-artifacts.mjs

@@ -0,0 +1,227 @@
+export const createRuntimeExecutionCandidateApprovalArtifacts = function (deps) {
+  const { fs, path, crypto, jsonSchemaVersion, stateDirectoryName, executionCandidatesDirectoryName, executionsDirectoryName, stage11RuntimeActionName, runtimeActionCatalogStage, runtimeActionCatalogVersion, stage12CandidateStaleAfterMs, stage13ApprovalStaleAfterMs, forbiddenDispatchActions, workflowPath, fileDigest, readJsonArtifact, stateArtifactWriter, candidateFilePath, approvalFilePath, executionCandidatesDirectory, executionApprovalsDirectory, executionPreflightEnvelope, supervisedRunBaseEnvelope, executionHistorySummary, executionPolicySnapshot, policyEvaluationEnvelope, policyProfileSnapshot, evaluateRuntimeActionCatalog, runtimeActionCatalogDigest, candidateProfileBinding, approvalProfileBinding, controlledForegroundBinding, executionEnabledPreflight, approvalLifecycleCurrentState, approvalLifecycleEnvelope, writeApprovalLifecycle, assertAutoRunLock, parseIsoTimestamp, validateCandidateArtifact, validateApprovalArtifact, candidateSafety, approvalSafety, autoRunSafety } = deps;
+const executionCandidateEnvelope = function (root, eventFile, actor = '', { persist = false } = {}) {
+  const preflight = executionPreflightEnvelope(root, eventFile, actor);
+  const history = executionHistorySummary(root, preflight.execution.idempotency_key);
+  const runtimeActionEvaluation = evaluateRuntimeActionCatalog(stage11RuntimeActionName, policyProfileSnapshot('controlled-local-runtime'));
+  const policyEvaluation = policyEvaluationEnvelope({ ...preflight.execution, risk_profile: { runtime_action: false, auto_execution: false, business_source_write: false, git: false, worktree: false, platform_api: false, subagent: false, mcp: false, daemon: false, skill_execution: false } });
+  const profileBinding = candidateProfileBinding({ profilePreflight: preflight.execution_enabled_preflight, policyDigest: policyEvaluation.policy_digest, actionCatalogDigest: runtimeActionEvaluation.catalog_digest });
+  const blockedReasons = [...preflight.quality, ...runtimeActionEvaluation.blocked_reasons, ...policyEvaluation.blocked_reasons, ...profileBinding.blocked_reasons];
+  if (history.active_count > 0) blockedReasons.push('active execution already exists for idempotency key');
+  const ready = preflight.ok && blockedReasons.length === 0;
+  return {
+    mode: 'execution-candidate',
+    ok: true,
+    state_present: preflight.state_present,
+    candidate: {
+      source: {
+        dispatch_event: String(eventFile),
+        event_sha256: preflight.execution.event_sha256,
+        claim_status: preflight.claim?.status || 'not_claimed',
+        workflow_state_present: preflight.state_present,
+      },
+      event_file: String(eventFile),
+      event_sha256: preflight.execution.event_sha256,
+      actor: preflight.execution.actor,
+      from_skill: preflight.execution.from_skill,
+      target_skill: preflight.execution.target_skill,
+      idempotency_key: preflight.execution.idempotency_key,
+      runtime_action: stage11RuntimeActionName,
+      profile_binding: profileBinding,
+      runtime_action_catalog: {
+        stage: runtimeActionCatalogStage,
+        version: runtimeActionCatalogVersion,
+        catalog_digest: runtimeActionEvaluation.catalog_digest,
+        action_id: stage11RuntimeActionName,
+        known: runtimeActionEvaluation.known,
+        allowed: runtimeActionEvaluation.allowed,
+        blocked_reasons: runtimeActionEvaluation.blocked_reasons,
+      },
+      ready_for_simulation: ready,
+      readiness_gates: preflight.gates,
+      blocked_reasons: blockedReasons,
+      history,
+      stale_after_ms: stage12CandidateStaleAfterMs,
+    },
+    policy: preflight.policy,
+    policy_evaluation: policyEvaluation,
+    controlled_execution_gate: preflight.controlled_execution_gate,
+    risk_profile: {
+      writes_state: Boolean(persist),
+      runtime_action: false,
+      auto_execution: false,
+      platform_api: false,
+      skill_execution: false,
+      business_source_write: false,
+      git: false,
+      worktree: false,
+    },
+    write_boundary: {
+      expected_writes: persist ? [path.join(stateDirectoryName, executionCandidatesDirectoryName, '<timestamp>-<dispatch-hash>.candidate.json').replace(/\\/g, '/')] : [],
+      forbidden_actions: forbiddenDispatchActions,
+    },
+    safety: candidateSafety({ writes: persist }),
+    quality: blockedReasons,
+    action: persist
+      ? 'execution candidate artifact was written. No runtime action, auto execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.'
+      : 'execution candidate was previewed. No files were written and no runtime action occurred.',
+  };
+}
+
+const candidateArtifactPath = function (root, eventFile) {
+  const digest = crypto.createHash('sha256').update(String(eventFile || '')).digest('hex').slice(0, 16);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(executionCandidatesDirectory(root), `${timestamp}-${digest}.candidate.json`);
+}
+
+function approvalArtifactPath(root, candidateFile) {
+  const digest = crypto.createHash('sha256').update(String(candidateFile || '')).digest('hex').slice(0, 16);
+  const timestamp = new Date().toISOString().replace(/[:.]/g, '-');
+  return path.join(executionApprovalsDirectory(root), `${timestamp}-${digest}.approval.json`);
+}
+
+function executionApprovalEnvelope(root, candidateFile, { persist = false } = {}) {
+  const candidatePath = candidateFilePath(root, candidateFile);
+  const candidate = readJsonArtifact(candidatePath, 'Candidate');
+  const candidateVerification = validateCandidateArtifact(candidate);
+  if (!candidateVerification.ok) throw new Error(`candidate verification failed: ${candidateVerification.failures.join('; ')}`);
+  const candidateDigest = fileDigest(candidatePath);
+  const requestedAction = candidate.candidate?.runtime_action || stage11RuntimeActionName;
+  const runtimeActionEvaluation = evaluateRuntimeActionCatalog(requestedAction, policyProfileSnapshot('controlled-local-runtime'));
+  const policyEvaluation = policyEvaluationEnvelope({ target_skill: candidate.candidate?.target_skill, runtime_action: requestedAction, risk_profile: candidate.risk_profile || {} });
+  const profileBinding = approvalProfileBinding({ candidate, candidateDigest, policyEvaluation, runtimeActionEvaluation });
+  const ready = Boolean(candidate.candidate?.ready_for_simulation && candidate.candidate?.blocked_reasons?.length === 0 && runtimeActionEvaluation.allowed && policyEvaluation.allowed && !profileBinding.drift_blocked);
+  const blockedReasons = ready ? [] : ['candidate is not ready for approval', ...runtimeActionEvaluation.blocked_reasons, ...policyEvaluation.blocked_reasons, ...profileBinding.blocked_reasons];
+  return {
+    mode: 'execution-approval',
+    ok: true,
+    state_present: fs.existsSync(workflowPath(root)),
+    approval: {
+      candidate_file: String(candidateFile),
+      candidate_digest: candidateDigest,
+      policy_digest: policyEvaluation.policy_digest,
+      profile_binding: profileBinding,
+      runtime_action_catalog: {
+        stage: runtimeActionCatalogStage,
+        version: runtimeActionCatalogVersion,
+        catalog_digest: runtimeActionEvaluation.catalog_digest,
+        action_id: requestedAction,
+        known: runtimeActionEvaluation.known,
+        allowed: runtimeActionEvaluation.allowed,
+        blocked_reasons: runtimeActionEvaluation.blocked_reasons,
+      },
+      idempotency_key: candidate.candidate.idempotency_key,
+      ready_for_auto_run: ready,
+      blocked_reasons: blockedReasons,
+      manual_approval_required: true,
+      approval_text: 'Human approval is required before controlled auto-run. This approval package is not an execution result.',
+      stale_after_ms: stage13ApprovalStaleAfterMs,
+    },
+    simulation: {
+      runtime_action: requestedAction,
+      invoked: false,
+      expected_input: candidate.candidate.source,
+      expected_output: {
+        artifact_type: 'supervised-handoff-package',
+        writes_business_source: false,
+        executes_workflow_skill: false,
+      },
+      expected_writes: [path.join(stateDirectoryName, executionsDirectoryName, '<timestamp>-<dispatch-hash>.execution.json').replace(/\\/g, '/')],
+      evidence_completeness: ready ? 'ready' : 'blocked',
+    },
+    recovery: {
+      automatic_retry: false,
+      retry_allowed: false,
+      stale_detection: true,
+      manual_action: 'Use executions audit to inspect stale or terminal records before any retry.',
+    },
+    policy: executionPolicySnapshot(),
+    policy_evaluation: policyEvaluation,
+    controlled_execution_gate: candidate.controlled_execution_gate,
+    safety: approvalSafety({ writes: persist }),
+    quality: blockedReasons,
+    action: persist
+      ? 'execution approval artifact was written. No runtime action, auto execution, platform API, subagent, MCP, daemon, git, worktree, or business source write occurred.'
+      : 'execution approval package was simulated. No files were written and no runtime action occurred.',
+  };
+}
+
+function writeCandidateArtifact(root, eventFile, envelope) {
+  const file = candidateArtifactPath(root, eventFile);
+  return stateArtifactWriter(path.dirname(file), path.basename(file), { schema_version: jsonSchemaVersion, command: 'execute', ...envelope });
+}
+
+function writeApprovalArtifact(root, candidateFile, envelope) {
+  const file = approvalArtifactPath(root, candidateFile);
+  const approvalFile = stateArtifactWriter(path.dirname(file), path.basename(file), { schema_version: jsonSchemaVersion, command: 'execute', ...envelope });
+  const lifecycle = approvalLifecycleEnvelope(root, path.basename(approvalFile), 'approved', 'runtime', 'approval package persisted with explicit confirm', null);
+  writeApprovalLifecycle(root, path.basename(approvalFile), lifecycle);
+  return approvalFile;
+}
+
+function readApprovalForAutoRun(root, approvalFile) {
+  const file = approvalFilePath(root, approvalFile);
+  const approval = readJsonArtifact(file, 'Approval');
+  const verification = validateApprovalArtifact(approval);
+  if (!verification.ok) throw new Error(`approval verification failed: ${verification.failures.join('; ')}`);
+  if (!approval.approval?.ready_for_auto_run) throw new Error('approval is not ready for controlled auto-run');
+  const candidateFile = approval.approval.candidate_file;
+  const candidatePath = candidateFilePath(root, candidateFile);
+  const candidateDigest = fileDigest(candidatePath);
+  const approvalDigest = fileDigest(file);
+  if (approval.approval.candidate_digest !== candidateDigest) throw new Error('approval candidate digest mismatch');
+  const candidate = readJsonArtifact(candidatePath, 'Candidate');
+  const candidateVerification = validateCandidateArtifact(candidate);
+  if (!candidateVerification.ok) throw new Error(`candidate verification failed: ${candidateVerification.failures.join('; ')}`);
+  const actionId = approval.simulation?.runtime_action || candidate.candidate?.runtime_action || stage11RuntimeActionName;
+  const catalogEvaluation = evaluateRuntimeActionCatalog(actionId, policyProfileSnapshot('controlled-local-runtime'));
+  if (!catalogEvaluation.allowed) throw new Error(`approval runtime action catalog gate failed: ${catalogEvaluation.blocked_reasons.join('; ')}`);
+  if (candidate.candidate?.runtime_action_catalog?.catalog_digest !== runtimeActionCatalogDigest()) throw new Error('candidate runtime action catalog digest mismatch');
+  if (approval.approval?.runtime_action_catalog?.catalog_digest !== runtimeActionCatalogDigest()) throw new Error('approval runtime action catalog digest mismatch');
+  const lifecycleState = approvalLifecycleCurrentState(root, approvalFile);
+  if (lifecycleState.blocked_reasons.length > 0) throw new Error(`approval lifecycle gate failed: ${lifecycleState.blocked_reasons.join('; ')}`);
+  const currentPolicy = executionPolicySnapshot();
+  if (!approval.approval.policy_digest) throw new Error('approval policy digest is required');
+  if (approval.approval.policy_digest !== currentPolicy.policy_digest) throw new Error('approval policy digest mismatch');
+  const updatedAt = parseIsoTimestamp(fs.statSync(file).mtime.toISOString());
+  if (!Number.isNaN(updatedAt) && Date.now() - updatedAt > stage13ApprovalStaleAfterMs) throw new Error('approval package is stale');
+  return { approval, approvalFile: file, approvalDigest, candidateFile, candidate, candidateDigest };
+}
+
+function controlledAutoRunEnvelope(root, eventFile, actor, approvalFile) {
+  if (!approvalFile) throw new Error('execute --auto-run requires --approval <approval-file>');
+  const { approval, approvalFile: approvalPath, approvalDigest, candidateFile, candidate, candidateDigest } = readApprovalForAutoRun(root, approvalFile);
+  const base = supervisedRunBaseEnvelope(root, eventFile, actor);
+  if (base.execution.idempotency_key !== approval.approval.idempotency_key) throw new Error('approval idempotency key mismatch');
+  const policyDigest = executionPolicySnapshot().policy_digest;
+  const actionCatalogDigest = runtimeActionCatalogDigest();
+  const profileBinding = controlledForegroundBinding({ approval, approvalDigest, candidate, candidateDigest, profilePreflight: executionEnabledPreflight(root), policyDigest, actionCatalogDigest });
+  if (profileBinding.blocked_reasons.length > 0) throw new Error(`controlled foreground profile gate failed: ${profileBinding.blocked_reasons.join('; ')}`);
+  const { lockFile, lock } = assertAutoRunLock(root, base.execution.idempotency_key);
+  return {
+    ...base,
+    mode: 'controlled-auto-run',
+    execution: {
+      ...base.execution,
+      auto_controlled: true,
+      foreground_controlled: true,
+      candidate_file: candidateFile,
+      candidate_digest: candidateDigest,
+      approval_file: String(approvalFile),
+      approval_digest: fileDigest(approvalPath),
+      policy_digest: policyDigest,
+      action_catalog_digest: actionCatalogDigest,
+      profile_binding: profileBinding,
+      lock_file: path.basename(lockFile),
+      lock_digest: fileDigest(lockFile),
+      recovery: { automatic_retry: false, retry_allowed: false, manual_action: 'Inspect execution and approval artifacts before any manual retry.' },
+    },
+    approval: { file: String(approvalFile), digest: fileDigest(approvalPath) },
+    lock,
+    safety: autoRunSafety(),
+    action: 'controlled auto-run bounded foreground command is running under explicit approval, policy snapshot, and local lock. No arbitrary shell, platform API, subagent, MCP, background process, git, worktree, or business source write occurred.',
+  };
+}
+
+  return { executionCandidateEnvelope, candidateArtifactPath, writeCandidateArtifact, approvalArtifactPath, executionApprovalEnvelope, writeApprovalArtifact, readApprovalForAutoRun, controlledAutoRunEnvelope };
+};