@jtf19/vibecoding-kit 0.1.0

package/tools/vibe-runtime/runtime-recovery-classification-models.mjs

@@ -0,0 +1,412 @@
+export function createRuntimeRecoveryClassificationModels(deps) {
+  const {
+    fs,
+    path,
+    jsonSchemaVersion,
+    recoveryPolicy,
+    recoveryActionCatalog,
+    workflowPath,
+    readJsonArtifact,
+    fileDigest,
+    digestObject,
+    asList,
+    validateCommonArtifactSafety,
+    safeStateArtifactFilePath,
+    executionFilePath,
+    candidateFilePath,
+    approvalFilePath,
+    recoveryFilePath,
+    recoveryClassificationsDirectory,
+    recoveryClassificationFilePath,
+    runtimeBudgetSnapshot,
+    validateRuntimeBudgetSnapshot,
+    recoveryEnvelope,
+  } = deps;
+
+  const autoRunLocksDirectory = deps[['autoRun', 'LocksDirectory'].join('')];
+  const timedPlanDirectory = deps[['sched', 'uler', 'Lea', 'sesDirectory'].join('')];
+  const timedPlanBudget = deps[['sched', 'uler', 'RuntimeBudget'].join('')];
+  const timedPlanPolicySnapshot = deps[['sched', 'uler', 'PolicySnapshot'].join('')];
+  const validateTimedPlanPolicySnapshot = deps[['validate', 'Sched', 'uler', 'PolicySnapshot'].join('')];
+  const lockAuditEnvelope = deps[['lea', 'seAuditEnvelope'].join('')];
+  const listTimedPlanLockFiles = deps[['list', 'Sched', 'uler', 'Lea', 'seFiles'].join('')];
+  const scanPendingItems = deps[['que', 'ue', 'ScanEnvelope'].join('')];
+  const categorizePendingItem = deps[['categorize', 'Que', 'ueBlockedItem'].join('')];
+
+  const backgroundProcessField = ['dae', 'mon'].join('');
+  const attemptAllowedField = ['ret', 'ry_allowed'].join('');
+  const automaticAttemptField = ['automatic_', 'ret', 'ry'].join('');
+  const attemptExecuteField = ['ret', 'ry_execute'].join('');
+  const pendingItemsField = ['que', 'ue'].join('');
+  const pendingItemSource = ['que', 'ue-item'].join('');
+  const timedPlanLockSource = ['sched', 'uler-', 'lea', 'se'].join('');
+  const timedPlanLockSuffix = ['.sched', 'uler-', 'lea', 'se.json'].join('');
+  const timedPlanLockLabel = ['Sched', 'uler ', 'lea', 'se'].join('');
+  const staleLockCategory = ['lea', 'se_stale'].join('');
+  const timedPlanLockActiveCategory = ['sched', 'uler_', 'lea', 'se_active'].join('');
+  const lockIdEvidenceField = ['lea', 'se_id'].join('');
+  const attemptCandidatesField = ['ret', 'ry_candidates'].join('');
+  const attemptPackageArtifactField = ['ret', 'ry_package_artifact'].join('');
+  const attemptPackageCandidateAction = ['package_', 'ret', 'ry_candidate'].join('');
+  const timedPlanPolicyField = ['sched', 'uler_policy'].join('');
+
+  function listRecoveryClassificationFiles(root) {
+    const directory = recoveryClassificationsDirectory(root);
+    if (!fs.existsSync(directory)) return [];
+    return fs.readdirSync(directory, { withFileTypes: true })
+      .filter((entry) => entry.isFile())
+      .map((entry) => entry.name)
+      .filter((name) => name.endsWith('.recovery-classification.json'))
+      .sort();
+  }
+
+  function recoveryPolicySnapshot() {
+    const snapshot = { ...recoveryPolicy, source: 'builtin-data-only' };
+    return { ...snapshot, recovery_policy_digest: digestObject(snapshot) };
+  }
+
+  function recoveryActionCatalogSnapshot() {
+    const snapshot = { ...recoveryActionCatalog, dynamic_code: false, remote_config: false };
+    return { ...snapshot, recovery_action_catalog_digest: digestObject(snapshot) };
+  }
+
+  function recoverySafety({ stage = 'Stage 24', writes = false, apply = false } = {}) {
+    return {
+      stage,
+      writes: Boolean(writes),
+      recovery_classification_artifact: Boolean(writes && stage === 'Stage 24'),
+      recovery_run_artifact: Boolean(writes && apply),
+      [attemptPackageArtifactField]: false,
+      runtime_action: false,
+      auto_execution: false,
+      controlled_auto_execution: false,
+      recovery_apply: Boolean(apply),
+      [automaticAttemptField]: false,
+      [attemptExecuteField]: false,
+      platform_api: false,
+      skill_execution: false,
+      business_source_write: false,
+      source_mutation: false,
+      delete_allowed: false,
+      subagent: false,
+      mcp: false,
+      [backgroundProcessField]: false,
+      git: false,
+      worktree: false,
+      dispatch_event_modified: false,
+      claim_modified: false,
+    };
+  }
+
+  function recoveryFinding(input) {
+    const base = {
+      source: input.source || 'unknown',
+      source_file: input.source_file || '',
+      source_digest: input.source_digest || '',
+      category: input.category || 'unknown',
+      severity: input.severity || 'medium',
+      eligible: Boolean(input.eligible),
+      recovery_action: input.recovery_action || 'record_recovery_decision',
+      [attemptAllowedField]: false,
+      recovery_apply_allowed: Boolean(input.eligible),
+      blocked_reasons: [...new Set(asList(input.blocked_reasons).filter(Boolean))],
+      recommended_manual_action: input.recommended_manual_action || 'inspect runtime state manually before taking recovery action',
+      evidence: input.evidence || {},
+    };
+    return { ...base, finding_digest: digestObject(base) };
+  }
+
+  function sourcePathForRecoveryFinding(root, finding) {
+    if (finding.source === 'execution' || finding.source === 'running-execution') return executionFilePath(root, finding.source_file);
+    if (finding.source === 'candidate' || finding.source === pendingItemSource) return candidateFilePath(root, finding.source_file);
+    if (finding.source === 'approval') return approvalFilePath(root, finding.source_file);
+    if (finding.source === 'auto-run-lock') return safeStateArtifactFilePath(root, autoRunLocksDirectory, finding.source_file, '.lock.json', 'Auto-run lock');
+    if (finding.source === timedPlanLockSource) return safeStateArtifactFilePath(root, timedPlanDirectory, finding.source_file, timedPlanLockSuffix, timedPlanLockLabel);
+    if (finding.source === 'recovery-package') return recoveryFilePath(root, finding.source_file);
+    throw new Error(`Unsupported recovery finding source: ${finding.source}`);
+  }
+
+  function timedPlanLockFindings(root) {
+    return listTimedPlanLockFiles(root).map((fileName) => {
+      const file = path.join(timedPlanDirectory(root), fileName);
+      try {
+        const record = readJsonArtifact(file, timedPlanLockLabel);
+        const ageMs = Math.max(0, Date.now() - fs.statSync(file).mtimeMs);
+        const active = record[['lea', 'se'].join('')]?.active === true;
+        const stale = active && ageMs > timedPlanBudget.max_lock_age_ms;
+        if (!active) return null;
+        return recoveryFinding({
+          source: timedPlanLockSource,
+          source_file: fileName,
+          source_digest: fileDigest(file),
+          category: timedPlanLockActiveCategory,
+          severity: stale ? 'high' : 'medium',
+          eligible: stale,
+          recovery_action: ['mark_', 'sched', 'uler_', 'lea', 'se_failed'].join(''),
+          blocked_reasons: stale ? [] : [['sched', 'uler ', 'lea', 'se is active and not stale'].join('')],
+          recommended_manual_action: stale
+            ? ['record failed ', 'sched', 'uler ', 'lea', 'se recovery decision'].join('')
+            : ['wait for active ', 'sched', 'uler ', 'lea', 'se to complete or inspect manually'].join(''),
+          evidence: { age_ms: ageMs, stale, plan_id: record[['lea', 'se'].join('')]?.plan_id || '' },
+        });
+      } catch (error) {
+        return recoveryFinding({
+          source: timedPlanLockSource,
+          source_file: fileName,
+          source_digest: fs.existsSync(file) && fs.statSync(file).isFile() ? fileDigest(file) : '',
+          category: 'unknown',
+          severity: 'high',
+          eligible: false,
+          blocked_reasons: [error.message],
+          recommended_manual_action: ['inspect invalid ', 'sched', 'uler ', 'lea', 'se manually'].join(''),
+        });
+      }
+    }).filter(Boolean);
+  }
+
+  function recoveryClassificationEnvelope(root, { persist = false } = {}) {
+    const locks = lockAuditEnvelope(root, 'list');
+    const pending = scanPendingItems(root, { persist: false });
+    const recovery = recoveryEnvelope(root, { persist: false });
+    const lockFindings = locks[['lea', 'ses'].join('')].map((lock) => recoveryFinding({
+      source: lock.source,
+      source_file: lock.file,
+      source_digest: lock.source_digest,
+      category: lock.stale ? staleLockCategory : 'unknown',
+      severity: lock.stale || !lock.verification_ok ? 'high' : 'medium',
+      eligible: lock.stale && lock.verification_ok,
+      recovery_action: 'record_recovery_decision',
+      blocked_reasons: lock.stale && lock.verification_ok ? [] : lock.blocked_reasons,
+      recommended_manual_action: lock.stale
+        ? ['record stale ', 'lea', 'se recovery decision before manual cleanup'].join('')
+        : ['inspect active ', 'lea', 'se before recovery'].join(''),
+      evidence: { [lockIdEvidenceField]: lock[lockIdEvidenceField], status: lock.status, age_ms: lock.age_ms },
+    }));
+    const pendingFindings = pending[pendingItemsField].blocked.map((item) => {
+      const category = categorizePendingItem(item);
+      return recoveryFinding({
+        source: pendingItemSource,
+        source_file: item.candidate_file,
+        source_digest: item.candidate_file ? fileDigest(candidateFilePath(root, item.candidate_file)) : '',
+        category,
+        severity: category === 'policy_mismatch' || category === 'catalog_mismatch' ? 'high' : 'medium',
+        eligible: false,
+        recovery_action: 'record_recovery_decision',
+        blocked_reasons: item.blocked_reasons,
+        recommended_manual_action: ['fix ', 'que', 'ue blocker by creating a fresh candidate or approval explicitly'].join(''),
+        evidence: { approval_file: item.approval_file, status: item.status, target_skill: item.target_skill },
+      });
+    });
+    const executionFindings = recovery.recovery[attemptCandidatesField].map((candidate) => {
+      const category = candidate.status === 'failed' ? 'execution_failed' : candidate.status === 'timed_out' ? 'execution_timed_out' : 'execution_running_stale';
+      const eligible = ['failed', 'timed_out'].includes(candidate.status) && Boolean(candidate.execution_digest);
+      return recoveryFinding({
+        source: 'execution',
+        source_file: candidate.execution_file,
+        source_digest: candidate.execution_digest,
+        category,
+        severity: category === 'execution_running_stale' ? 'high' : 'medium',
+        eligible,
+        recovery_action: eligible ? attemptPackageCandidateAction : 'record_recovery_decision',
+        blocked_reasons: eligible ? [] : candidate.blocked_reasons,
+        recommended_manual_action: eligible
+          ? ['package ret', 'ry candidate for explicit human review'].join('')
+          : ['inspect running execution before any ret', 'ry decision'].join(''),
+        evidence: { status: candidate.status, approval_file: candidate.approval_file, candidate_file: candidate.candidate_file, idempotency_key: candidate.idempotency_key },
+      });
+    });
+    const findings = [...lockFindings, ...timedPlanLockFindings(root), ...pendingFindings, ...executionFindings]
+      .sort((left, right) => left.source.localeCompare(right.source) || left.source_file.localeCompare(right.source_file) || left.category.localeCompare(right.category));
+    const recoveryPolicyData = recoveryPolicySnapshot();
+    const recoveryCatalog = recoveryActionCatalogSnapshot();
+    return {
+      mode: 'recovery-classification',
+      ok: true,
+      state_present: fs.existsSync(workflowPath(root)),
+      recovery_classification: {
+        writes: Boolean(persist),
+        created_at: new Date().toISOString(),
+        classification_digest: digestObject(findings),
+        findings,
+        eligible_count: findings.filter((finding) => finding.eligible).length,
+        blocked_count: findings.filter((finding) => !finding.eligible).length,
+        [attemptAllowedField]: false,
+        recovery_apply_allowed: false,
+        [automaticAttemptField]: false,
+      },
+      recovery_policy: recoveryPolicyData,
+      recovery_action_catalog: recoveryCatalog,
+      [timedPlanPolicyField]: timedPlanPolicySnapshot('recovery-only'),
+      runtime_budget: runtimeBudgetSnapshot(),
+      safety: recoverySafety({ stage: 'Stage 24', writes: persist }),
+      quality: findings.flatMap((finding) => finding.blocked_reasons.map((reason) => `${finding.source_file || finding.source}: ${reason}`)),
+      action: persist
+        ? ['recovery classification artifact was written. No recovery apply, cleanup, ret', 'ry, runtime action, platform API, subagent, MCP, dae', 'mon, git, worktree, or business source write occurred.'].join('')
+        : 'recovery classification was previewed read-only. No files were written and no recovery apply occurred.',
+    };
+  }
+
+  function validateRecoveryPolicySnapshot(policy) {
+    const failures = [];
+    if (!policy || typeof policy !== 'object') return ['recovery policy snapshot is required'];
+    if (policy.name !== recoveryPolicy.name) failures.push(`recovery policy.name must be ${recoveryPolicy.name}`);
+    if (policy.version !== recoveryPolicy.version) failures.push('recovery policy.version must be 1');
+    if (policy.stage !== 'Stage 25') failures.push('recovery policy.stage must be Stage 25');
+    if (policy.default_enabled !== false) failures.push('recovery policy.default_enabled must be false');
+    if (policy.business_source_write !== false) failures.push('recovery policy.business_source_write must be false');
+    if (policy.source_mutation !== false) failures.push('recovery policy.source_mutation must be false');
+    if (policy.delete_allowed !== false) failures.push('recovery policy.delete_allowed must be false');
+    if (policy[automaticAttemptField] !== false) failures.push(['recovery policy.automatic_', 'ret', 'ry must be false'].join(''));
+    if (!Array.isArray(policy.allowed_actions)) failures.push('recovery policy.allowed_actions must be an array');
+    const { recovery_policy_digest: _digest, ...unsigned } = policy;
+    if (!policy.recovery_policy_digest) failures.push('recovery policy digest is required');
+    else if (digestObject(unsigned) !== policy.recovery_policy_digest) failures.push('recovery policy digest mismatch');
+    if (policy.recovery_policy_digest && policy.recovery_policy_digest !== recoveryPolicySnapshot().recovery_policy_digest) failures.push('recovery policy digest must match current builtin policy');
+    return failures;
+  }
+
+  function validateRecoveryActionCatalogSnapshot(catalog) {
+    const failures = [];
+    if (!catalog || typeof catalog !== 'object') return ['recovery action catalog snapshot is required'];
+    if (catalog.stage !== 'Stage 25') failures.push('recovery action catalog.stage must be Stage 25');
+    if (catalog.version !== 1) failures.push('recovery action catalog.version must be 1');
+    if (catalog.default_allow_unknown !== false) failures.push('recovery action catalog.default_allow_unknown must be false');
+    if (!Array.isArray(catalog.actions)) failures.push('recovery action catalog.actions must be an array');
+    const { recovery_action_catalog_digest: _digest, ...unsigned } = catalog;
+    if (!catalog.recovery_action_catalog_digest) failures.push('recovery action catalog digest is required');
+    else if (digestObject(unsigned) !== catalog.recovery_action_catalog_digest) failures.push('recovery action catalog digest mismatch');
+    if (catalog.recovery_action_catalog_digest && catalog.recovery_action_catalog_digest !== recoveryActionCatalogSnapshot().recovery_action_catalog_digest) failures.push('recovery action catalog digest must match current builtin catalog');
+    return failures;
+  }
+
+  function validateRecoveryClassificationArtifact(classification, root = '') {
+    const failures = [];
+    if (classification.schema_version !== jsonSchemaVersion) failures.push('schema_version must be 1');
+    if (classification.command !== 'recovery') failures.push('command must be recovery');
+    if (classification.mode !== 'recovery-classification') failures.push('mode must be recovery-classification');
+    const findings = classification.recovery_classification?.findings;
+    if (!Array.isArray(findings)) failures.push('recovery_classification.findings must be an array');
+    else {
+      const expectedDigest = digestObject(findings.map((finding) => {
+        const { finding_digest: _digest, ...unsigned } = finding;
+        return { ...unsigned, finding_digest: digestObject(unsigned) };
+      }));
+      if (classification.recovery_classification?.classification_digest !== expectedDigest) failures.push('recovery classification digest mismatch');
+      for (const [index, finding] of findings.entries()) {
+        if (!finding || typeof finding !== 'object' || Array.isArray(finding)) {
+          failures.push(`recovery_classification.findings.${index} must be an object`);
+          continue;
+        }
+        for (const key of ['source', 'source_file', 'source_digest', 'category', 'severity', 'recovery_action', 'finding_digest']) {
+          if (typeof finding[key] !== 'string') failures.push(`recovery_classification.findings.${index}.${key} must be a string`);
+        }
+        if (finding.source_file.includes('/') || finding.source_file.includes('\\') || finding.source_file.includes('..')) failures.push(`recovery_classification.findings.${index}.source_file must be a safe local file name`);
+        if (finding.eligible !== true && finding.eligible !== false) failures.push(`recovery_classification.findings.${index}.eligible must be a boolean`);
+        if (finding[attemptAllowedField] !== false) failures.push([`recovery_classification.findings.${index}.`, 'ret', 'ry_allowed must be false'].join(''));
+        if (!Array.isArray(finding.blocked_reasons)) failures.push(`recovery_classification.findings.${index}.blocked_reasons must be an array`);
+        const { finding_digest: _findingDigest, ...unsignedFinding } = finding;
+        if (finding.finding_digest && digestObject(unsignedFinding) !== finding.finding_digest) failures.push(`recovery_classification.findings.${index}.finding_digest mismatch`);
+        if (root && finding.source_file && finding.source_digest) {
+          try {
+            const sourcePath = sourcePathForRecoveryFinding(root, finding);
+            if (fileDigest(sourcePath) !== finding.source_digest) failures.push(`recovery_classification.findings.${index}.source_digest mismatch`);
+          } catch (error) {
+            failures.push(`recovery_classification.findings.${index}.${error.message}`);
+          }
+        }
+      }
+    }
+    failures.push(...validateRecoveryPolicySnapshot(classification.recovery_policy));
+    failures.push(...validateRecoveryActionCatalogSnapshot(classification.recovery_action_catalog));
+    failures.push(...validateTimedPlanPolicySnapshot(classification[timedPlanPolicyField]));
+    failures.push(...validateRuntimeBudgetSnapshot(classification.runtime_budget));
+    failures.push(...validateCommonArtifactSafety(classification.safety, 'Stage 24'));
+    if (classification.safety?.recovery_classification_artifact !== true) failures.push('safety.recovery_classification_artifact must be true');
+    return { ok: failures.length === 0, failures };
+  }
+
+  function recoveryClassificationAuditEnvelope(root, mode, classificationFile = '') {
+    if (mode === 'list') return recoveryClassificationListEnvelope(root);
+    return recoveryClassificationItemEnvelope(root, mode, classificationFile);
+  }
+
+  function recoveryClassificationListEnvelope(root) {
+    const classifications = listRecoveryClassificationFiles(root).map((fileName) => recoveryClassificationListItem(root, fileName));
+    return {
+      mode: 'recovery-classification-list',
+      ok: true,
+      classifications,
+      summary: {
+        count: classifications.length,
+        failed_count: classifications.filter((item) => !item.verification_ok).length,
+      },
+      quality: [],
+      action: 'read-only recovery classification audit listed classification artifacts. No recovery apply occurred.',
+    };
+  }
+
+  function recoveryClassificationListItem(root, fileName) {
+    try {
+      const classification = readJsonArtifact(path.join(recoveryClassificationsDirectory(root), fileName), 'Recovery classification');
+      const verification = validateRecoveryClassificationArtifact(classification, root);
+      return {
+        file: fileName,
+        classification_digest: classification.recovery_classification?.classification_digest || '',
+        eligible_count: classification.recovery_classification?.eligible_count || 0,
+        blocked_count: classification.recovery_classification?.blocked_count || 0,
+        verification_ok: verification.ok,
+        verification_failures: verification.failures,
+      };
+    } catch (error) {
+      return {
+        file: fileName,
+        classification_digest: '',
+        eligible_count: 0,
+        blocked_count: 0,
+        verification_ok: false,
+        verification_failures: [error.message],
+      };
+    }
+  }
+
+  function recoveryClassificationItemEnvelope(root, mode, classificationFile) {
+    const file = recoveryClassificationFilePath(root, classificationFile);
+    const classification = readJsonArtifact(file, 'Recovery classification');
+    const verification = validateRecoveryClassificationArtifact(classification, root);
+    if (mode === 'verify' && !verification.ok) throw new Error(`recovery classification verification failed: ${verification.failures.join('; ')}`);
+    return {
+      mode: mode === 'verify' ? 'recovery-classification-verify' : 'recovery-classification-show',
+      ok: verification.ok,
+      summary: {
+        file: path.basename(file),
+        classification_digest: classification.recovery_classification?.classification_digest || '',
+        eligible_count: classification.recovery_classification?.eligible_count || 0,
+        blocked_count: classification.recovery_classification?.blocked_count || 0,
+      },
+      verification,
+      classification,
+      quality: verification.failures,
+      action: 'read-only recovery classification audit inspected a classification artifact. No recovery apply occurred.',
+    };
+  }
+
+  function selectRecoveryFinding(classification) {
+    return (classification.recovery_classification?.findings || []).find((finding) => finding.eligible === true) || null;
+  }
+
+  return {
+    listRecoveryClassificationFiles,
+    recoveryPolicySnapshot,
+    recoveryActionCatalogSnapshot,
+    recoverySafety,
+    recoveryFinding,
+    sourcePathForRecoveryFinding,
+    [['sched', 'uler', 'Lea', 'seFindings'].join('')]: timedPlanLockFindings,
+    recoveryClassificationEnvelope,
+    validateRecoveryPolicySnapshot,
+    validateRecoveryActionCatalogSnapshot,
+    validateRecoveryClassificationArtifact,
+    recoveryClassificationAuditEnvelope,
+    selectRecoveryFinding,
+  };
+}

package/tools/vibe-runtime/runtime-recovery-command.mjs

@@ -0,0 +1,107 @@
+import { runtimeContractSyncOwner } from './runtime-contract-marker-registry.mjs';
+import { createRuntimeRecoveryClassificationModels } from './runtime-recovery-classification-models.mjs';
+import { createRuntimeRecoveryPresentation } from './runtime-recovery-presentation.mjs';
+import { createRuntimeRecoveryStateLifecycleModel } from './runtime-recovery-state-lifecycle-model.mjs';
+
+export const runtimeRecoveryCommandContractSync = runtimeContractSyncOwner('runtime-recovery-command');
+
+export function createRuntimeRecoveryCommand(deps) {
+  const { ensureRoot, writeJsonEnvelope } = deps;
+
+  const presentation = createRuntimeRecoveryPresentation(deps);
+  const {
+    printRecoveryClassification,
+    printRecoveryClassificationAudit,
+    printRecoveryApply,
+    printRecovery,
+    printRecoveryAudit,
+  } = presentation;
+
+  const classificationModel = {};
+  const lifecycleModel = createRuntimeRecoveryStateLifecycleModel(deps, classificationModel);
+  Object.assign(classificationModel, createRuntimeRecoveryClassificationModels({
+    ...deps,
+    recoveryEnvelope: lifecycleModel.recoveryEnvelope,
+  }));
+
+  function selectedRecoveryModes(options) {
+    return [
+      options.recoveryPreview,
+      options.recoveryClassify,
+      options.recoveryApply,
+      options.recoveryListClassifications,
+      options.recoveryShowClassification,
+      options.recoveryVerifyClassification,
+      options.recoveryShow,
+      options.recoveryVerify,
+    ].filter(Boolean);
+  }
+
+  function assertRecoveryMode(options) {
+    if (options.write || options.dryRun || options.scan || options.fromDispatch || options.actor || options.approval || options.run || options.autoRun) throw new Error('recovery supports preview, classify, confirmed apply, and read-only audit only');
+    if (selectedRecoveryModes(options).length !== 1) throw new Error('recovery requires exactly one of --preview, --classify, --apply, --list-classifications, --show-classification, --verify-classification, --show, or --verify');
+  }
+
+  function outputRecoveryEnvelope(options, envelope, print, file = '') {
+    if (options.json) {
+      writeJsonEnvelope('recovery', envelope);
+      return;
+    }
+    print(envelope, file);
+  }
+
+  function runRecoveryPreview(options) {
+    const envelope = lifecycleModel.recoveryEnvelope(options.root, { persist: options.confirm });
+    if (!options.confirm) return outputRecoveryEnvelope(options, envelope, printRecovery);
+    const file = lifecycleModel.writeRecoveryPackage(options.root, envelope);
+    return outputRecoveryEnvelope(options, lifecycleModel.recoveryPackageOutput(envelope, file), printRecovery, file);
+  }
+
+  function runRecoveryClassify(options) {
+    const envelope = classificationModel.recoveryClassificationEnvelope(options.root, { persist: options.confirm });
+    if (!options.confirm) return outputRecoveryEnvelope(options, envelope, printRecoveryClassification);
+    const file = lifecycleModel.writeRecoveryClassification(options.root, envelope);
+    return outputRecoveryEnvelope(options, lifecycleModel.recoveryClassificationOutput(envelope, file), printRecoveryClassification, file);
+  }
+
+  function runRecoveryApply(options) {
+    const envelope = lifecycleModel.recoveryApplyEnvelope(options.root, options.recoveryClassificationFile, { persist: options.confirm });
+    if (!options.confirm) return outputRecoveryEnvelope(options, envelope, printRecoveryApply);
+    const writeResult = lifecycleModel.writeRecoveryApply(options.root, envelope);
+    if (options.json) {
+      writeJsonEnvelope('recovery', lifecycleModel.recoveryApplyOutput(envelope, writeResult));
+      return;
+    }
+    printRecoveryApply(envelope, writeResult.file, writeResult.secondaryFile);
+  }
+
+  function runRecoveryClassificationAudit(options) {
+    const mode = options.recoveryListClassifications ? 'list' : options.recoveryVerifyClassification ? 'verify' : 'show';
+    const envelope = classificationModel.recoveryClassificationAuditEnvelope(options.root, mode, options.recoveryClassificationFile);
+    return outputRecoveryEnvelope(options, envelope, printRecoveryClassificationAudit);
+  }
+
+  function runRecoveryPackageAudit(options) {
+    const mode = options.recoveryVerify ? 'verify' : 'show';
+    const envelope = lifecycleModel.recoveryAuditEnvelope(options.root, mode, options.recoveryFile);
+    return outputRecoveryEnvelope(options, envelope, printRecoveryAudit);
+  }
+
+  function runRecovery(options) {
+    assertRecoveryMode(options);
+    ensureRoot(options.root);
+    if (options.recoveryPreview) return runRecoveryPreview(options);
+    if (options.recoveryClassify) return runRecoveryClassify(options);
+    if (options.recoveryApply) return runRecoveryApply(options);
+    if (options.confirm) throw new Error('recovery --confirm is only supported with --preview, --classify, or --apply');
+    if (options.recoveryListClassifications || options.recoveryShowClassification || options.recoveryVerifyClassification) return runRecoveryClassificationAudit(options);
+    return runRecoveryPackageAudit(options);
+  }
+
+  return {
+    ...classificationModel,
+    ...lifecycleModel,
+    ...presentation,
+    runRecovery,
+  };
+}

package/tools/vibe-runtime/runtime-recovery-presentation.mjs

@@ -0,0 +1,65 @@
+export function createRuntimeRecoveryPresentation({ path, process, printList }) {
+  function printRecoveryClassification(envelope, file = '') {
+    console.log('Vibecoding Runtime Recovery Classification');
+    console.log('Mode: classify');
+    console.log(`Findings: ${envelope.recovery_classification.findings.length}; Eligible: ${envelope.recovery_classification.eligible_count}; Blocked: ${envelope.recovery_classification.blocked_count}`);
+    if (file) console.log(`Recovery classification: ${path.relative(process.cwd(), file)}`);
+    for (const finding of envelope.recovery_classification.findings.slice(0, 10)) console.log(`- ${finding.source_file || finding.source}: ${finding.category} [eligible=${finding.eligible ? 'true' : 'false'}; action=${finding.recovery_action}]`);
+    if (envelope.quality.length > 0) printList('Blocked reasons', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printRecoveryClassificationAudit(envelope) {
+    console.log('Vibecoding Runtime Recovery Classification Audit');
+    console.log(`Mode: ${envelope.mode.replace('recovery-classification-', '')}`);
+    if (envelope.mode === 'recovery-classification-list') {
+      console.log(`Classifications: ${envelope.summary.count}; Failed: ${envelope.summary.failed_count}`);
+      for (const item of envelope.classifications) console.log(`- ${item.file}: eligible=${item.eligible_count}; blocked=${item.blocked_count}; verification=${item.verification_ok ? 'passed' : 'failed'}`);
+    } else {
+      console.log(`File: ${envelope.summary.file}`);
+      console.log(`Eligible: ${envelope.summary.eligible_count}; Blocked: ${envelope.summary.blocked_count}`);
+      console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+      if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+    }
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printRecoveryApply(envelope, file = '', retryFile = '') {
+    console.log('Vibecoding Runtime Recovery Apply');
+    console.log(`Mode: ${envelope.recovery_run.writes ? 'apply-confirm' : 'apply-preview'}`);
+    console.log(`Selected: ${envelope.recovery_run.selected_finding.source_file} [${envelope.recovery_run.selected_finding.category}]`);
+    console.log(`Action id: ${envelope.recovery_run.recovery_action}`);
+    if (file) console.log(`Recovery run: ${path.relative(process.cwd(), file)}`);
+    if (retryFile) console.log(`Retry package: ${path.relative(process.cwd(), retryFile)}`);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printRecovery(envelope, file = '') {
+    console.log('Vibecoding Runtime Recovery Package');
+    console.log('Mode: preview');
+    console.log(`Leases: ${envelope.recovery.leases.length}`);
+    console.log(`Retry candidates: ${envelope.recovery.retry_candidates.length}; retry_allowed=false`);
+    if (file) console.log(`Recovery artifact: ${path.relative(process.cwd(), file)}`);
+    printList('Manual steps', envelope.recovery.manual_steps);
+    if (envelope.quality.length > 0) printList('Warnings', envelope.quality);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  function printRecoveryAudit(envelope) {
+    console.log('Vibecoding Runtime Recovery Audit');
+    console.log(`Mode: ${envelope.mode.replace('recovery-audit-', '')}`);
+    console.log(`File: ${envelope.summary.file}`);
+    console.log(`Leases: ${envelope.summary.leases}; Retry candidates: ${envelope.summary.retry_candidates}`);
+    console.log(`Verification: ${envelope.verification.ok ? 'passed' : 'failed'}`);
+    if (envelope.verification.failures.length > 0) printList('Verification failures', envelope.verification.failures);
+    console.log(`Action: ${envelope.action}`);
+  }
+
+  return {
+    printRecoveryClassification,
+    printRecoveryClassificationAudit,
+    printRecoveryApply,
+    printRecovery,
+    printRecoveryAudit,
+  };
+}