bootproof 0.3.0 → 0.4.1

package/dist/repair.js

@@ -1,14 +1,21 @@
 import crypto from "node:crypto";
+import { spawn } from "node:child_process";
 import fs from "node:fs";
 import net from "node:net";
 import os from "node:os";
 import path from "node:path";
 import { parse, stringify } from "yaml";
-import { minimalEnv, runToCompletion } from "./exec.js";
+import { buildExecutionEnv, runToCompletion } from "./exec.js";
 import { REPAIRED_GENERATED_COMPOSE_MARKER, repoComposeRepairFile } from "./plan.js";
-import { attestationPath, buildAttestation, gitInfo, signDetached, TOOL_ID, verifyDetached, verifySignature, writeAttestation, } from "./proof.js";
+import { redactText } from "./redact.js";
+import { attestationPath, buildAttestation, evaluateDetachedSignature, gitInfo, signDetached, TOOL_ID, verifyDetached, verifySignature, writeAttestation, } from "./proof.js";
 import { up } from "./run.js";
 import { inferRepo } from "./infer.js";
+import { buildExternalHealthAttestation } from "./external-health.js";
+import { buildRepairAction, buildRepairReceiptBase, createRepairCommand, validateRepairAction, } from "./repair-safety.js";
+import { deterministicRepairCandidateFor, repairProgressed, } from "./repair-playbooks.js";
+export * from "./repair-safety.js";
+export * from "./repair-playbooks.js";
 const LOCKFILE = /^(?:package-lock\.json|npm-shrinkwrap\.json|pnpm-lock\.yaml|yarn\.lock|bun\.lockb?|Gemfile\.lock|go\.sum)$/;
 const ENV_EXAMPLE = /^\.env(?:\.[^/]+)?\.example$/;
 const BOOTPROOF_FILE = /(^|\/)[^/]*\.bootproof\.[^/]+$/;
@@ -45,6 +52,8 @@ export function assertRepairScope(changes) {
         const file = normalizedRelative(change.path);
         const base = path.posix.basename(file);
         const allowed = file === "package.json" ||
+            file === "config/database.yml" ||
+            file === "config/gitlab.yml" ||
             LOCKFILE.test(base) ||
             BOOTPROOF_FILE.test(file) ||
             ENV_EXAMPLE.test(base) ||
@@ -74,6 +83,9 @@ export function verifyRepairReceipt(receipt) {
         return false;
     return verifyDetached(canonicalReceipt(receipt), receipt.signature, receipt.signer.publicKey);
 }
+export function evaluateRepairReceiptSignature(receipt) {
+    return evaluateDetachedSignature(canonicalReceipt(receipt), receipt.signature, receipt.signer?.publicKey);
+}
 export function sha256Attestation(attestation) {
     return crypto.createHash("sha256").update(JSON.stringify(attestation)).digest("hex");
 }
@@ -237,6 +249,8 @@ async function remapConflictingServicePort(context) {
             preconditions: [{ path: repoCompose, content: source }],
             planDelta: `Create ${repairFile} as a complete repaired copy of ${repoCompose}. Use service step: ${command}`,
             envDelta: null,
+            mutationScope: "repo_only",
+            riskLevel: "low",
         };
     }
     const generatedPath = path.join(context.sandbox, composeFile);
@@ -260,6 +274,8 @@ async function remapConflictingServicePort(context) {
         preconditions: [],
         planDelta: null,
         envDelta: null,
+        mutationScope: "repo_only",
+        riskLevel: "low",
     };
 }
 export function packageManagerActivationCommand(packageManager, version) {
@@ -274,7 +290,7 @@ async function activatePackageManager(context) {
         return null;
     const corepackHome = path.join(context.sandbox, ".bootproof", "corepack");
     const environment = { COREPACK_HOME: corepackHome };
-    const result = await runToCompletion(command, context.sandbox, 120_000, minimalEnv(environment));
+    const result = await runToCompletion(command, context.sandbox, 120_000, buildExecutionEnv(environment));
     if (result.exitCode !== 0 || result.timedOut) {
         throw new Error(`environment remediation failed: ${command}\n${result.stderr || result.stdout}`);
     }
@@ -290,6 +306,9 @@ async function activatePackageManager(context) {
         planDelta: null,
         envDelta: command,
         environment,
+        mutationScope: "project_cache",
+        riskLevel: "medium",
+        command: createRepairCommand("corepack", ["prepare", `${packageManager}@${packageManagerVersion}`, "--activate"]),
     };
 }
 export function prismaRepairCommand(repo) {
@@ -308,6 +327,10 @@ function readPackageJson(repo) {
 function hasAnyFile(repo, files) {
     return files.find(file => fs.existsSync(path.join(repo, file))) ?? null;
 }
+function structuredPlaybookCommand(command) {
+    const [executable, ...args] = command.split(" ");
+    return createRepairCommand(executable, args);
+}
 export function migrationRepairFor(repo, evidence) {
     const pkg = readPackageJson(repo);
     const dependencies = { ...(pkg?.dependencies ?? {}), ...(pkg?.devDependencies ?? {}) };
@@ -400,6 +423,9 @@ async function deployFrameworkMigrations(context) {
         planDelta: `Insert after dependency installation and before application start: ${migration.command}`,
         envDelta: null,
         additionalPreparationCommands: [preparation],
+        mutationScope: "database",
+        riskLevel: "high",
+        command: structuredPlaybookCommand(migration.command),
     };
 }
 const REGISTRY = {
@@ -462,6 +488,43 @@ function persistFailureAttestation(repo, source, extraEvidence = null) {
     writeAttestation(repo, attestation);
     return attestation;
 }
+function proposedActionFor(applied) {
+    if (applied.fileChanges.length) {
+        const patch = applied.patch ?? applied.diff;
+        if (!patch)
+            throw new Error("repair file changes require an exact patch");
+        return buildRepairAction({
+            actionType: "patch",
+            mutationScope: "repo_only",
+            riskLevel: applied.riskLevel,
+            patch: {
+                format: "unified-diff",
+                content: patch,
+                files: applied.fileChanges.map(change => normalizedRelative(change.path)),
+            },
+            explanation: applied.description,
+            evidenceRefs: [".bootproof/attestation.json"],
+        });
+    }
+    if (applied.command) {
+        return buildRepairAction({
+            actionType: "command",
+            mutationScope: applied.mutationScope,
+            riskLevel: applied.riskLevel,
+            command: applied.command,
+            explanation: applied.description,
+            evidenceRefs: [".bootproof/attestation.json"],
+        });
+    }
+    return buildRepairAction({
+        actionType: "instruction",
+        mutationScope: "none",
+        riskLevel: applied.riskLevel,
+        instruction: applied.description,
+        explanation: applied.description,
+        evidenceRefs: [".bootproof/attestation.json"],
+    });
+}
 function buildRepairReceipt(repo, before, after, applied, startedAt) {
     if (before.result.booted ||
         before.result.healthVerified ||
@@ -478,8 +541,29 @@ function buildRepairReceipt(repo, before, after, applied, startedAt) {
     const beforeHash = sha256Attestation(before);
     const afterHash = sha256Attestation(after);
     const info = gitInfo(repo);
+    const finishedAt = new Date().toISOString();
+    const proposedAction = proposedActionFor(applied);
+    const base = buildRepairReceiptBase({
+        repairId: applied.id,
+        createdAt: finishedAt,
+        bootproofVersion: TOOL_ID.replace(/^bootproof@/, ""),
+        beforeFailureClass: before.result.failureClass,
+        beforeEvidenceHash: sha256Text(before.result.failureEvidence ?? ""),
+        proposedAction,
+        appliedAt: finishedAt,
+        applyResult: {
+            status: "applied",
+            exitCode: 0,
+            filesChanged: applied.filesChanged.map(normalizedRelative),
+            evidence: null,
+        },
+        progressed: true,
+        verified: true,
+        explanation: applied.description,
+        redactionsApplied: [],
+    });
     const receipt = {
-        schema: "bootproof/repair-receipt/v1",
+        ...base,
         tool: TOOL_ID,
         repo: { remote: info.remote, commit: info.commit, dirty: info.dirty },
         environment: { os: `${os.platform()} ${os.release()}`, arch: os.arch(), node: process.version },
@@ -512,12 +596,13 @@ function buildRepairReceipt(repo, before, after, applied, startedAt) {
             },
             after: {
                 booted: true,
+                bootproofOrchestrated: true,
                 healthObservation: after.result.healthObservation,
                 attestationSha256: afterHash,
             },
         },
         startedAt,
-        finishedAt: new Date().toISOString(),
+        finishedAt,
         signer: null,
         signature: null,
     };
@@ -572,6 +657,605 @@ function signedFailedAttestation(repo, requestedProvider) {
         return null;
     }
 }
+export function latestDeterministicRepairCandidate(repoPath, requestedProvider) {
+    const repo = path.resolve(repoPath);
+    const attestation = signedFailedAttestation(repo, requestedProvider);
+    if (!attestation)
+        return null;
+    const candidate = deterministicRepairCandidateFor(attestation, { repoPath: repo });
+    return candidate ? { attestation, candidate } : null;
+}
+export function latestFailedAttestation(repoPath, requestedProvider) {
+    return signedFailedAttestation(path.resolve(repoPath), requestedProvider);
+}
+async function runStructuredRepairCommand(command, cwd, timeoutMs = 600_000) {
+    return await new Promise(resolve => {
+        const child = spawn(command.executable, command.args, {
+            cwd,
+            shell: false,
+            env: buildExecutionEnv(),
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        let output = "";
+        let settled = false;
+        const finish = (exitCode, extra = "") => {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            const redacted = redactText(`${output}${extra}`.slice(-4000));
+            resolve({
+                exitCode,
+                evidence: redacted.text,
+                redactionsApplied: redacted.applied,
+            });
+        };
+        const capture = (chunk) => {
+            output = `${output}${String(chunk)}`.slice(-4000);
+        };
+        child.stdout?.on("data", capture);
+        child.stderr?.on("data", capture);
+        child.on("close", code => finish(code));
+        child.on("error", error => finish(null, `\n${error.message}`));
+        const timer = setTimeout(() => {
+            child.kill("SIGTERM");
+            finish(null, "\nrepair command timed out");
+        }, timeoutMs);
+    });
+}
+function buildLifecycleRepairReceipt(input) {
+    const after = input.after ?? null;
+    const verified = Boolean(after?.result.healthVerified &&
+        (after.result.booted || after.verificationMode === "external-health"));
+    const progressed = repairProgressed(input.candidate.failureClass, after);
+    const info = gitInfo(input.repo);
+    const redactedRemote = redactText(info.remote ?? "");
+    const redactionsApplied = [...new Set([
+            ...(input.redactionsApplied ?? []),
+            ...redactedRemote.applied,
+        ])];
+    const base = buildRepairReceiptBase({
+        repairId: input.candidate.id,
+        createdAt: input.createdAt,
+        bootproofVersion: TOOL_ID.replace(/^bootproof@/, ""),
+        beforeFailureClass: input.candidate.failureClass,
+        beforeEvidenceHash: sha256Text(input.before.result.failureEvidence ?? ""),
+        proposedAction: input.candidate.action,
+        ...(input.approvedAt ? { approvedAt: input.approvedAt } : {}),
+        ...(input.appliedAt ? { appliedAt: input.appliedAt } : {}),
+        applyResult: input.applyResult,
+        ...(after?.result.failureClass ? { afterFailureClass: after.result.failureClass } : {}),
+        progressed,
+        verified,
+        explanation: input.explanation,
+        redactionsApplied,
+    });
+    const receipt = {
+        ...base,
+        tool: TOOL_ID,
+        repo: {
+            remote: info.remote === null ? null : redactedRemote.text,
+            commit: info.commit,
+            dirty: info.dirty,
+        },
+        environment: { os: `${os.platform()} ${os.release()}`, arch: os.arch(), node: process.version },
+        failure: {
+            class: input.candidate.failureClass,
+            beforeAttestationSha256: sha256Attestation(input.before),
+        },
+        startedAt: input.createdAt,
+        finishedAt: new Date().toISOString(),
+        ...(verified && after?.result.healthObservation
+            ? {
+                verification: {
+                    before: {
+                        booted: false,
+                        failureClass: input.candidate.failureClass,
+                        attestationSha256: sha256Attestation(input.before),
+                    },
+                    after: {
+                        booted: after.result.booted,
+                        bootproofOrchestrated: after.bootproofOrchestrated,
+                        healthObservation: after.result.healthObservation,
+                        attestationSha256: sha256Attestation(after),
+                    },
+                },
+            }
+            : {}),
+        ...(input.aiRepair
+            ? {
+                aiEvidence: {
+                    provider: input.aiRepair.provider,
+                    model: input.aiRepair.model,
+                    context: input.aiRepair.context,
+                    suggestion: input.aiRepair.suggestion,
+                },
+            }
+            : {}),
+        signer: null,
+        signature: null,
+    };
+    const signed = signDetached(canonicalReceipt(receipt));
+    receipt.signature = signed.signature;
+    receipt.signer = { publicKey: signed.publicKeyPem, algorithm: "ed25519" };
+    return receipt;
+}
+function writeLifecycleRepairReceipt(repo, receipt) {
+    const file = receiptPath(repo);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(receipt, null, 2) + "\n");
+    return file;
+}
+async function executeDeterministicRepairCandidate(repo, before, candidate, options) {
+    const startedAt = new Date().toISOString();
+    cleanPreviousRepairOutputs(repo);
+    const result = (receipt, explanation, afterFile = null, patchFile = null) => {
+        const receiptFile = writeLifecycleRepairReceipt(repo, receipt);
+        return {
+            schema: "bootproof/repair-result/v1",
+            repaired: receipt.verified,
+            failureClass: candidate.failureClass,
+            repairId: candidate.id,
+            receiptPath: relativeOutput(repo, receiptFile),
+            patchPath: relativeOutput(repo, patchFile),
+            afterAttestationPath: relativeOutput(repo, afterFile),
+            explanation,
+        };
+    };
+    const safetyErrors = [candidate.action, ...(candidate.followUpActions ?? [])]
+        .flatMap(action => validateRepairAction(action).errors);
+    if (safetyErrors.length) {
+        const explanation = `Deterministic repair candidate was blocked by the safety validator: ${[...new Set(safetyErrors)].join("; ")}`;
+        return result(buildLifecycleRepairReceipt({
+            repo,
+            before,
+            candidate,
+            createdAt: startedAt,
+            applyResult: { status: "failed", exitCode: null, filesChanged: [], evidence: explanation },
+            explanation,
+        }), explanation);
+    }
+    const provider = options.provider ?? before.plan.provider;
+    if (candidate.action.actionType === "instruction") {
+        const explanation = `Deterministic instruction recorded: ${candidate.action.instruction}`;
+        return result(buildLifecycleRepairReceipt({
+            repo,
+            before,
+            candidate,
+            createdAt: startedAt,
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+        }), explanation);
+    }
+    if (candidate.action.actionType === "patch") {
+        const patch = candidate.action.patch;
+        if (!patch || !candidate.fileChanges?.length) {
+            throw new Error("validated patch repair is missing its exact file changes");
+        }
+        const patchFile = path.join(repo, ".bootproof", `repair-${candidate.id}.patch`);
+        fs.mkdirSync(path.dirname(patchFile), { recursive: true });
+        fs.writeFileSync(patchFile, patch.content);
+        if (provider === "local" && !options.unsafeLocal) {
+            const explanation = "The repair patch was not tested because the required BootProof rerun would execute repository code locally; rerun with --unsafe-local after review.";
+            return result(buildLifecycleRepairReceipt({
+                repo,
+                before,
+                candidate,
+                createdAt: startedAt,
+                applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+                explanation,
+            }), explanation, null, patchFile);
+        }
+        if (options.actionApproved !== true) {
+            const explanation = "Repair patch was not approved. The working tree was not modified.";
+            return result(buildLifecycleRepairReceipt({
+                repo,
+                before,
+                candidate,
+                createdAt: startedAt,
+                applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+                explanation,
+            }), explanation, null, patchFile);
+        }
+        const approvedAt = new Date().toISOString();
+        const { root, sandbox, composeProjectName } = copyToSandbox(repo);
+        let patchApplied = false;
+        let afterOutcome = null;
+        let rerunError = "";
+        try {
+            for (const change of candidate.fileChanges) {
+                const target = path.join(sandbox, normalizedRelative(change.path));
+                const current = fs.existsSync(target) ? fs.readFileSync(target, "utf8") : null;
+                if (current !== change.before) {
+                    throw new Error(`repair patch preimage changed for ${change.path}`);
+                }
+            }
+            writeChanges(sandbox, candidate.fileChanges);
+            patchApplied = true;
+            afterOutcome = await up(sandbox, {
+                provider,
+                unsafeLocal: options.unsafeLocal,
+                dryRun: false,
+                timeoutMs: options.timeoutMs,
+                install: true,
+                port: options.port,
+                remoteSource: options.remoteSource,
+                environment: { COMPOSE_PROJECT_NAME: composeProjectName },
+            });
+        }
+        catch (error) {
+            rerunError = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            await cleanupServices(afterOutcome, buildExecutionEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        const after = afterOutcome?.attestation ?? null;
+        let afterFile = null;
+        if (after) {
+            afterFile = afterAttestationPath(repo);
+            fs.mkdirSync(path.dirname(afterFile), { recursive: true });
+            fs.writeFileSync(afterFile, JSON.stringify(after, null, 2) + "\n");
+        }
+        const verified = Boolean(after?.result.booted && after.result.healthVerified);
+        const progressed = repairProgressed(candidate.failureClass, after);
+        const redactedError = redactText(rerunError);
+        const explanation = !patchApplied
+            ? `Repair patch could not be applied in the sandbox: ${redactedError.text || "unknown failure"}.`
+            : verified
+                ? `Repair patch was tested in the sandbox and BootProof observed verified health: ${after.result.healthObservation}.`
+                : progressed
+                    ? `Repair patch was tested in the sandbox; BootProof progressed from ${candidate.failureClass} to ${after.result.failureClass}.`
+                    : "Repair patch was tested in the sandbox, but the BootProof rerun did not verify boot or reach a different failure class.";
+        return result(buildLifecycleRepairReceipt({
+            repo,
+            before,
+            candidate,
+            createdAt: startedAt,
+            approvedAt,
+            ...(patchApplied ? { appliedAt: new Date().toISOString() } : {}),
+            applyResult: {
+                status: patchApplied ? "applied" : "failed",
+                exitCode: patchApplied ? 0 : null,
+                filesChanged: patchApplied ? candidate.fileChanges.map(change => change.path) : [],
+                evidence: redactedError.text || null,
+            },
+            after,
+            explanation,
+            redactionsApplied: redactedError.applied,
+        }), explanation, afterFile, patchFile);
+    }
+    const command = candidate.action.command;
+    if (!command)
+        throw new Error("validated command repair is missing its exact command");
+    if (provider === "local" && !options.unsafeLocal) {
+        const explanation = "The repair command was not run because the required BootProof rerun would execute repository code locally; rerun with --unsafe-local after review.";
+        return result(buildLifecycleRepairReceipt({
+            repo,
+            before,
+            candidate,
+            createdAt: startedAt,
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+        }), explanation);
+    }
+    if (options.actionApproved !== true && options.commandApproved !== true) {
+        const explanation = "Repair command was not approved. No command was executed.";
+        return result(buildLifecycleRepairReceipt({
+            repo,
+            before,
+            candidate,
+            createdAt: startedAt,
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+        }), explanation);
+    }
+    const approvedAt = new Date().toISOString();
+    const commandResult = await runStructuredRepairCommand(command, repo);
+    const { root, sandbox, composeProjectName } = copyToSandbox(repo);
+    let afterOutcome = null;
+    let rerunError = "";
+    try {
+        afterOutcome = await up(sandbox, {
+            provider,
+            unsafeLocal: options.unsafeLocal,
+            dryRun: false,
+            timeoutMs: options.timeoutMs,
+            install: true,
+            port: options.port,
+            remoteSource: options.remoteSource,
+            environment: { COMPOSE_PROJECT_NAME: composeProjectName },
+        });
+    }
+    catch (error) {
+        rerunError = error instanceof Error ? error.message : String(error);
+    }
+    finally {
+        await cleanupServices(afterOutcome, buildExecutionEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    const after = afterOutcome?.attestation ?? null;
+    let afterFile = null;
+    if (after) {
+        afterFile = afterAttestationPath(repo);
+        fs.mkdirSync(path.dirname(afterFile), { recursive: true });
+        fs.writeFileSync(afterFile, JSON.stringify(after, null, 2) + "\n");
+    }
+    const commandApplied = commandResult.exitCode === 0;
+    const verified = Boolean(after?.result.booted && after.result.healthVerified);
+    const progressed = repairProgressed(candidate.failureClass, after);
+    const redactedEvidence = redactText([commandResult.evidence, rerunError].filter(Boolean).join("\n"));
+    const explanation = verified
+        ? commandApplied
+            ? `Repair command applied and BootProof observed verified health: ${after.result.healthObservation}.`
+            : `Repair command failed with exit ${commandResult.exitCode ?? "unknown"}, but the BootProof rerun observed verified health: ${after.result.healthObservation}.`
+        : progressed
+            ? commandApplied
+                ? `Repair command applied; BootProof progressed from ${candidate.failureClass} to ${after.result.failureClass}.`
+                : `Repair command failed with exit ${commandResult.exitCode ?? "unknown"}, but BootProof progressed from ${candidate.failureClass} to ${after.result.failureClass}.`
+            : commandApplied
+                ? "Repair command completed, but the BootProof rerun did not verify boot or reach a different failure class."
+                : `Repair command failed with exit ${commandResult.exitCode ?? "unknown"}; the BootProof rerun did not verify boot or reach a different failure class.`;
+    const receipt = buildLifecycleRepairReceipt({
+        repo,
+        before,
+        candidate,
+        createdAt: startedAt,
+        approvedAt,
+        ...(commandApplied ? { appliedAt: new Date().toISOString() } : {}),
+        applyResult: {
+            status: commandApplied ? "applied" : "failed",
+            exitCode: commandResult.exitCode,
+            filesChanged: [],
+            evidence: redactedEvidence.text || null,
+        },
+        after,
+        explanation,
+        redactionsApplied: [...new Set([
+                ...commandResult.redactionsApplied,
+                ...redactedEvidence.applied,
+            ])],
+    });
+    return result(receipt, explanation, afterFile);
+}
+function verifiedAfterRepair(attestation) {
+    return Boolean(attestation?.result.healthVerified &&
+        (attestation.result.booted || attestation.verificationMode === "external-health"));
+}
+function writeRepairAfterAttestation(repo, attestation) {
+    if (!attestation)
+        return null;
+    const file = afterAttestationPath(repo);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(attestation, null, 2) + "\n");
+    return file;
+}
+async function rerunAfterAiRepair(sandbox, before, provider, options, composeProjectName) {
+    try {
+        if (before.verificationMode === "external-health" && before.externalHealthUrl) {
+            const after = await buildExternalHealthAttestation(sandbox, before.externalHealthUrl, options.timeoutMs);
+            return { after, outcome: null, error: "" };
+        }
+        const outcome = await up(sandbox, {
+            provider,
+            unsafeLocal: options.unsafeLocal,
+            dryRun: false,
+            timeoutMs: options.timeoutMs,
+            install: true,
+            port: options.port,
+            remoteSource: options.remoteSource,
+            environment: { COMPOSE_PROJECT_NAME: composeProjectName },
+        });
+        return { after: outcome.attestation, outcome, error: "" };
+    }
+    catch (error) {
+        return {
+            after: null,
+            outcome: null,
+            error: error instanceof Error ? error.message : String(error),
+        };
+    }
+}
+export async function executeAiSuggestedRepair(repoPath, before, action, options) {
+    const repo = path.resolve(repoPath);
+    const startedAt = new Date().toISOString();
+    const failureClass = before.result.failureClass;
+    if (!failureClass || before.result.healthVerified || before.result.booted || !verifySignature(before)) {
+        throw new Error("AI repair requires a signature-valid classified failed attestation.");
+    }
+    if (action.source !== "ai_suggested" || action.deterministic) {
+        throw new Error("AI repair execution requires an ai_suggested action.");
+    }
+    const validation = validateRepairAction(action);
+    if (!validation.valid) {
+        throw new Error(`AI suggestion was blocked by BootProof safety policy: ${validation.errors.join("; ")}`);
+    }
+    cleanPreviousRepairOutputs(repo);
+    const candidate = {
+        id: `ai-suggested-${failureClass}-${sha256Text(JSON.stringify(action)).slice(0, 12)}`,
+        failureClass,
+        action,
+    };
+    const result = (receipt, explanation, afterFile = null, patchFile = null) => {
+        const receiptFile = writeLifecycleRepairReceipt(repo, receipt);
+        return {
+            schema: "bootproof/repair-result/v1",
+            repaired: receipt.verified,
+            failureClass,
+            repairId: candidate.id,
+            receiptPath: relativeOutput(repo, receiptFile),
+            patchPath: relativeOutput(repo, patchFile),
+            afterAttestationPath: relativeOutput(repo, afterFile),
+            explanation,
+        };
+    };
+    const receiptFor = (input) => buildLifecycleRepairReceipt({
+        repo,
+        before,
+        candidate,
+        createdAt: startedAt,
+        aiRepair: options.aiRepair ?? null,
+        ...input,
+    });
+    const provider = options.provider ?? before.plan.provider;
+    const localRerunRequiresAcknowledgement = before.verificationMode !== "external-health" &&
+        provider === "local" &&
+        !options.unsafeLocal;
+    if (action.actionType === "instruction") {
+        const approved = options.actionApproved === true;
+        const explanation = approved
+            ? `AI-suggested instruction was approved for manual use but was not executed: ${action.instruction}`
+            : "AI-suggested instruction was not approved. No command or patch was executed.";
+        return result(receiptFor({
+            ...(approved ? { approvedAt: new Date().toISOString() } : {}),
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+            redactionsApplied: [],
+        }), explanation);
+    }
+    if (action.actionType === "patch") {
+        const patch = action.patch;
+        if (!patch)
+            throw new Error("validated AI patch suggestion is missing its exact patch");
+        const patchFile = path.join(repo, ".bootproof", `repair-${candidate.id}.patch`);
+        if (localRerunRequiresAcknowledgement) {
+            const explanation = "The AI-suggested patch was not tested because the required BootProof rerun would execute repository code locally; rerun with --unsafe-local after review.";
+            return result(receiptFor({
+                applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+                explanation,
+                redactionsApplied: [],
+            }), explanation);
+        }
+        if (options.actionApproved !== true) {
+            const explanation = "AI-suggested patch was not approved. The working tree was not modified.";
+            return result(receiptFor({
+                applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+                explanation,
+                redactionsApplied: [],
+            }), explanation);
+        }
+        const approvedAt = new Date().toISOString();
+        fs.mkdirSync(path.dirname(patchFile), { recursive: true });
+        fs.writeFileSync(patchFile, patch.content);
+        const { root, sandbox, composeProjectName } = copyToSandbox(repo);
+        const sandboxPatch = path.join(root, "ai-suggested.patch");
+        fs.writeFileSync(sandboxPatch, patch.content);
+        let patchResult = {
+            exitCode: null,
+            evidence: "",
+            redactionsApplied: [],
+        };
+        let after = null;
+        let outcome = null;
+        let rerunError = "";
+        try {
+            for (const file of patch.files)
+                assertRepairTargetPath(sandbox, file);
+            const check = await runStructuredRepairCommand(createRepairCommand("git", ["apply", "--check", sandboxPatch]), sandbox);
+            patchResult = check.exitCode === 0
+                ? await runStructuredRepairCommand(createRepairCommand("git", ["apply", sandboxPatch]), sandbox)
+                : check;
+            if (patchResult.exitCode === 0) {
+                const rerun = await rerunAfterAiRepair(sandbox, before, provider, options, composeProjectName);
+                after = rerun.after;
+                outcome = rerun.outcome;
+                rerunError = rerun.error;
+            }
+        }
+        catch (error) {
+            rerunError = error instanceof Error ? error.message : String(error);
+        }
+        finally {
+            await cleanupServices(outcome, buildExecutionEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
+            fs.rmSync(root, { recursive: true, force: true });
+        }
+        const afterFile = writeRepairAfterAttestation(repo, after);
+        const patchApplied = patchResult.exitCode === 0;
+        const progressed = repairProgressed(failureClass, after);
+        const redacted = redactText([patchResult.evidence, rerunError].filter(Boolean).join("\n"));
+        const explanation = verifiedAfterRepair(after)
+            ? `AI-suggested patch was tested in a sandbox and BootProof independently verified health: ${after.result.healthObservation}.`
+            : progressed
+                ? `AI-suggested patch was tested in a sandbox; BootProof progressed from ${failureClass} to ${after.result.failureClass}.`
+                : patchApplied
+                    ? "AI-suggested patch was tested in a sandbox, but BootProof did not verify boot or reach a different failure class."
+                    : `AI-suggested patch was blocked or failed in the sandbox: ${redacted.text || "git apply failed"}.`;
+        return result(receiptFor({
+            approvedAt,
+            ...(patchApplied ? { appliedAt: new Date().toISOString() } : {}),
+            applyResult: {
+                status: patchApplied ? "applied" : "failed",
+                exitCode: patchResult.exitCode,
+                filesChanged: patchApplied ? patch.files : [],
+                evidence: redacted.text || null,
+            },
+            after,
+            explanation,
+            redactionsApplied: [...new Set([...patchResult.redactionsApplied, ...redacted.applied])],
+        }), explanation, afterFile, patchFile);
+    }
+    const command = action.command;
+    if (!command)
+        throw new Error("validated AI command suggestion is missing its exact command");
+    if (localRerunRequiresAcknowledgement) {
+        const explanation = "The AI-suggested command was not run because the required BootProof rerun would execute repository code locally; rerun with --unsafe-local after review.";
+        return result(receiptFor({
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+            redactionsApplied: [],
+        }), explanation);
+    }
+    if (options.actionApproved !== true) {
+        const explanation = "AI-suggested command was not approved. No command was executed.";
+        return result(receiptFor({
+            applyResult: { status: "not_applied", exitCode: null, filesChanged: [], evidence: null },
+            explanation,
+            redactionsApplied: [],
+        }), explanation);
+    }
+    const approvedAt = new Date().toISOString();
+    const commandResult = await runStructuredRepairCommand(command, repo);
+    const { root, sandbox, composeProjectName } = copyToSandbox(repo);
+    let after = null;
+    let outcome = null;
+    let rerunError = "";
+    try {
+        const rerun = await rerunAfterAiRepair(sandbox, before, provider, options, composeProjectName);
+        after = rerun.after;
+        outcome = rerun.outcome;
+        rerunError = rerun.error;
+    }
+    finally {
+        await cleanupServices(outcome, buildExecutionEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
+        fs.rmSync(root, { recursive: true, force: true });
+    }
+    const afterFile = writeRepairAfterAttestation(repo, after);
+    const commandApplied = commandResult.exitCode === 0;
+    const progressed = repairProgressed(failureClass, after);
+    const redacted = redactText([commandResult.evidence, rerunError].filter(Boolean).join("\n"));
+    const explanation = verifiedAfterRepair(after)
+        ? commandApplied
+            ? `AI-suggested command completed and BootProof independently verified health: ${after.result.healthObservation}.`
+            : `AI-suggested command failed with exit ${commandResult.exitCode ?? "unknown"}, but BootProof independently verified health: ${after.result.healthObservation}.`
+        : progressed
+            ? `AI-suggested command ${commandApplied ? "completed" : "failed"}; BootProof progressed from ${failureClass} to ${after.result.failureClass}.`
+            : commandApplied
+                ? "AI-suggested command completed, but BootProof did not verify boot or reach a different failure class."
+                : `AI-suggested command failed with exit ${commandResult.exitCode ?? "unknown"}; BootProof did not verify boot or reach a different failure class.`;
+    return result(receiptFor({
+        approvedAt,
+        ...(commandApplied ? { appliedAt: new Date().toISOString() } : {}),
+        applyResult: {
+            status: commandApplied ? "applied" : "failed",
+            exitCode: commandResult.exitCode,
+            filesChanged: [],
+            evidence: redacted.text || null,
+        },
+        after,
+        explanation,
+        redactionsApplied: [...new Set([...commandResult.redactionsApplied, ...redacted.applied])],
+    }), explanation, afterFile);
+}
 async function cleanupServices(outcome, env) {
     if (!outcome)
         return;
@@ -609,6 +1293,12 @@ export function applyVerifiedRepair(repoPath, receiptFile = path.join(repoPath,
     if (receipt.schema !== "bootproof/repair-receipt/v1" || !verifyRepairReceipt(receipt)) {
         return fail("repair receipt signature is invalid; no files were written");
     }
+    if (!receipt.verified) {
+        return fail("repair receipt is not verified; no repository files were written");
+    }
+    if (!receipt.repair) {
+        return fail("repair receipt contains no verified repository file changes to apply");
+    }
     const changes = receipt.repair.fileChanges;
     if (!Array.isArray(changes) || changes.length === 0) {
         return fail("verified repair has no repository file changes to apply");
@@ -708,6 +1398,25 @@ export async function repairRepo(repoPath, options) {
     const existingBefore = signedFailedAttestation(repo, options.provider);
     const freshBefore = freshFailedAttestation(repo, options.provider);
     const provider = options.provider ?? existingBefore?.plan.provider ?? "docker";
+    if (existingBefore) {
+        const candidate = deterministicRepairCandidateFor(existingBefore, { repoPath: repo });
+        if (candidate) {
+            return await executeDeterministicRepairCandidate(repo, existingBefore, candidate, options);
+        }
+        if (!(REGISTRY[existingBefore.result.failureClass] ?? []).length) {
+            const failureClass = existingBefore.result.failureClass;
+            return {
+                schema: "bootproof/repair-result/v1",
+                repaired: false,
+                failureClass,
+                repairId: null,
+                receiptPath: null,
+                patchPath: null,
+                afterAttestationPath: null,
+                explanation: `No verified deterministic remediation is known for ${failureClass} yet.`,
+            };
+        }
+    }
     if (provider === "local" && !options.unsafeLocal) {
         return {
             schema: "bootproof/repair-result/v1",
@@ -773,7 +1482,7 @@ export async function repairRepo(repoPath, options) {
                 receiptPath: null,
                 patchPath: null,
                 afterAttestationPath: null,
-                explanation: `no verified remediation is known for ${failureClass} yet`,
+                explanation: `No verified deterministic remediation is known for ${failureClass} yet.`,
             };
         }
         let attemptedId = null;
@@ -851,7 +1560,7 @@ export async function repairRepo(repoPath, options) {
         };
     }
     finally {
-        await cleanupServices(lastOutcome, minimalEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
+        await cleanupServices(lastOutcome, buildExecutionEnv({ COMPOSE_PROJECT_NAME: composeProjectName }));
         fs.rmSync(root, { recursive: true, force: true });
     }
 }