bootproof 0.3.0 → 0.4.0

package/dist/run.d.ts

@@ -10,6 +10,9 @@ export interface UpOptions {
     port?: number;
     environment?: Record<string, string>;
     additionalPreparationCommands?: PreparationCommand[];
+    command?: string;
+    healthPath?: string;
+    ciOidc?: boolean;
 }
 export interface UpOutcome {
     inference: Inference;

package/dist/run.js

@@ -3,17 +3,89 @@ import fs from "node:fs";
 import path from "node:path";
 import { inferRepo } from "./infer.js";
 import { buildPlan, writePlanFiles } from "./plan.js";
-import { runToCompletion, superviseApp, pollHealthCandidates, minimalEnv } from "./exec.js";
-import { classifyFailure, extractMissingEnvNames } from "./taxonomy.js";
-import { buildAttestation, writeAttestation } from "./proof.js";
+import { buildExecutionEnv, detectHealthCandidatePortMismatch, execResultEvidence, extractHealthCandidates, healthCandidatePortMismatchEvidence, processEvidenceText, runToCompletion, superviseApp, pollHealthCandidates, probeHealthCandidatesOnce, } from "./exec.js";
+import { classifyFailure, extractMissingEnvNames, safeLocalEnvValue } from "./taxonomy.js";
+import { buildAttestation, writeAttestation, resolveTrust } from "./proof.js";
+import { redactText } from "./redact.js";
 function classifyHealthFailure(evidence) {
     if (/(only HTTP 5\d\d observed|HTTP 5\d\d|status\s*5\d\d|returned 5\d\d)/i.test(evidence)) {
         return "health_http_error";
     }
     return "health_check_timeout";
 }
-function step(id, kind, command, startedAt, exitCode, ok, observation, evidenceTail) {
-    return { id, kind, command, startedAt, finishedAt: new Date().toISOString(), exitCode, ok, observation, evidenceTail };
+/**
+ * Augment the app_exited_early explanation with the last ~10 lines of captured
+ * process output (stdout and stderr are combined at capture time). The evidence
+ * is already stored in the attestation; this only surfaces it in the explanation
+ * field. Redaction is applied by buildAttestation before persistence.
+ */
+function appExitedEarlyExplanation(classExplanation, processEvidence) {
+    const tailLines = processEvidence.evidenceTail
+        .split(/\r?\n/)
+        .map(line => line.trim())
+        .filter(line => line.length > 0)
+        .slice(-10);
+    if (!tailLines.length)
+        return classExplanation;
+    return `${classExplanation}\n\nLast process output (stdout and stderr combined):\n${tailLines.join("\n")}`;
+}
+function healthStatusLabel(evidence) {
+    const status = `HTTP ${evidence.statusCode}${evidence.statusText ? ` ${evidence.statusText}` : ""}`;
+    return evidence.redirectLocation ? `${status} → ${evidence.redirectLocation}` : status;
+}
+function healthObservationSummary(evidence) {
+    if (evidence.redirectLocation)
+        return `${healthStatusLabel(evidence)} at ${evidence.requestedUrl}`;
+    return `HTTP ${evidence.statusCode} at ${evidence.requestedUrl}`;
+}
+function healthPort(url) {
+    try {
+        const parsed = new URL(url);
+        const port = Number(parsed.port || (parsed.protocol === "https:" ? 443 : 80));
+        return Number.isInteger(port) ? port : null;
+    }
+    catch {
+        return null;
+    }
+}
+function recordHealthPort(inference, plan, url, source) {
+    const port = healthPort(url);
+    if (port === null)
+        return;
+    inference.observedPort = port;
+    inference.healthCandidateSource = source;
+    plan.observedPort = port;
+    plan.healthCandidateSource = source;
+    if (source === "observed") {
+        inference.port = port;
+        inference.portEvidence = `observed healthy HTTP response at ${url}`;
+    }
+}
+function packageScriptFailureContext(inference) {
+    if (!inference.selectedPackageScriptName || !inference.selectedPackageScriptCommand)
+        return "";
+    return [
+        "Package script context",
+        `scriptName: ${inference.selectedPackageScriptName}`,
+        `scriptCommand: ${redactText(inference.selectedPackageScriptCommand).text}`,
+        `packageManager: ${inference.packageManager}`,
+        inference.stack.includes("python-backend") && inference.stack.includes("node-frontend")
+            ? "projectContext: python-node-hybrid"
+            : "",
+    ].filter(Boolean).join("\n");
+}
+function step(id, kind, command, startedAt, exitCode, ok, observation, evidence) {
+    return {
+        id,
+        kind,
+        command,
+        startedAt,
+        finishedAt: new Date().toISOString(),
+        exitCode,
+        ok,
+        observation,
+        ...(typeof evidence === "string" ? { evidenceTail: evidence } : evidence),
+    };
 }
 export function packageManagerVersionMatches(expected, actual) {
     const expectedMatch = expected.trim().match(/^v?(\d+)(?:\.(\d+))?(?:\.(\d+))?$/);
@@ -84,6 +156,17 @@ function unsupportedOrchestrationExplanation(inference) {
 export async function up(repoPath, opts) {
     const startedAt = new Date().toISOString();
     const inference = inferRepo(repoPath, { workspace: opts.workspace });
+    if (opts.command) {
+        inference.appCommand = opts.command;
+        inference.appCommandSource = "--command override";
+        inference.selectedPackageScriptName = null;
+        inference.selectedPackageScriptCommand = null;
+        inference.projectCliCommand = null;
+        inference.projectCliReady = null;
+        inference.commandScope = "explicit --command override";
+        inference.incompleteAppCommand = false;
+        inference.multiAppCommand = false;
+    }
     if (opts.additionalPreparationCommands?.length) {
         inference.preparationCommands.push(...opts.additionalPreparationCommands);
         inference.dependencyInstallRequired = true;
@@ -101,13 +184,36 @@ export async function up(repoPath, opts) {
             inference.portEvidence = `repository Compose published port retained; --port ${opts.port} was not applied`;
         }
     }
+    if (opts.healthPath) {
+        // Override the health endpoint path. Rewrites the path component of every
+        // health candidate URL. This resolves the case where an app answers on
+        // /health but returns 404 at / — the receipt then honestly signs a clean
+        // 200 instead of an honest-but-confusing 404 at the root.
+        const rewritePath = (url, newPath) => {
+            try {
+                const parsed = new URL(url);
+                parsed.pathname = newPath;
+                parsed.search = "";
+                return parsed.toString();
+            }
+            catch {
+                // Not a parseable URL; leave it alone rather than corrupting evidence.
+                return url;
+            }
+        };
+        inference.healthCandidates = inference.healthCandidates.map(candidate => rewritePath(candidate, opts.healthPath));
+        inference.composeHealthCandidates = inference.composeHealthCandidates.map(candidate => rewritePath(candidate, opts.healthPath));
+        inference.healthCandidateSource = "observed";
+        inference.portEvidence = `${inference.portEvidence}; health path set by --health-path flag`;
+    }
     const plan = buildPlan(inference, opts.provider);
-    const env = minimalEnv({ PORT: String(inference.port), ...opts.environment });
+    const trust = await resolveTrust({ ciOidc: opts.ciOidc });
+    const env = buildExecutionEnv({ PORT: String(inference.port), ...opts.environment });
     const runsSourceComposeApplication = opts.provider === "docker" &&
         Boolean(inference.repoComposeFile) &&
         inference.composeHealthCandidates.length > 0;
     const base = { inference, plan, writtenFiles: [] };
-    const refuse = (failureClass, explanation, observed = [], failureEvidence = explanation) => {
+    const refuse = (failureClass, explanation, observed = [], failureEvidence = explanation, healthEvidence = null, observedHealthCandidates = []) => {
         const refusal = { failureClass, explanation };
         if (opts.dryRun)
             return { ...base, attestation: null, refusal };
@@ -125,10 +231,12 @@ export async function up(repoPath, opts) {
             booted: false,
             healthVerified: false,
             healthObservation: null,
-            observedHealthCandidates: [],
+            healthEvidence,
+            observedHealthCandidates,
             failureClass,
             failureEvidence: failureEvidence.slice(-2000),
             explanation,
+            trust,
         });
         writeAttestation(inference.repoPath, attestation);
         return { inference, plan: refusalPlan, writtenFiles: [], attestation, refusal };
@@ -141,7 +249,10 @@ export async function up(repoPath, opts) {
     }
     const orchestrationExplanation = unsupportedOrchestrationExplanation(inference);
     if (orchestrationExplanation && !runsSourceComposeApplication) {
-        return refuse("orchestration_not_supported", orchestrationExplanation);
+        const failureClass = inference.stack.includes("go-backend")
+            ? "go_service_orchestration_not_supported"
+            : "orchestration_not_supported";
+        return refuse(failureClass, orchestrationExplanation);
     }
     if (!inference.appCommand && inference.composeHealthCandidates.length > 0 && opts.provider !== "docker") {
         return refuse("orchestration_not_supported", `Detected a source-built application in ${inference.repoComposeFile} with published HTTP candidates, but repository Compose requires --provider docker. Diagnosis only — no localhost claim.`);
@@ -150,10 +261,10 @@ export async function up(repoPath, opts) {
         return refuse("workspace_ambiguous", `This is a monorepo with ${inference.workspaces.length} workspace candidates. Choose one with --workspace <dir> instead of letting bootproof guess.`);
     }
     if (opts.remoteSource && !opts.dryRun && (opts.provider !== "local" || !opts.unsafeLocal)) {
-        return refuse("unknown_failure", `BootProof cloned ${opts.remoteSource} for inspection but will not execute remote repository code without --provider local --unsafe-local.`);
+        return refuse("host_execution_not_acknowledged", `BootProof cloned ${opts.remoteSource} for inspection but will not execute remote repository code without --provider local --unsafe-local.`);
     }
     if (opts.provider === "local" && !opts.unsafeLocal) {
-        return refuse("unknown_failure", "Local provider runs repository code directly on your machine. Re-run with --unsafe-local to acknowledge this, or use --provider docker.");
+        return refuse("host_execution_not_acknowledged", "Local provider runs repository code directly on your machine. Re-run with --unsafe-local to acknowledge this, or use --provider docker.");
     }
     if (opts.dryRun)
         return { ...base, attestation: null, refusal: null };
@@ -179,7 +290,20 @@ export async function up(repoPath, opts) {
         }
     }
     if (inference.incompleteAppCommand) {
-        return refuse("unknown_failure", "BootProof detected a hybrid backend/frontend repository, but the inferred command starts only the frontend development pipeline. Complete application orchestration is not implemented, so no boot was attempted.");
+        return refuse("orchestration_not_supported", "BootProof detected a hybrid backend/frontend repository, but the inferred command starts only the frontend development pipeline. Complete application orchestration is not implemented, so no boot was attempted.");
+    }
+    const localStartStep = opts.provider === "local"
+        ? plan.steps.find(planned => planned.kind === "start-app" && planned.command)
+        : undefined;
+    if (localStartStep && plan.healthCandidates.length > 0) {
+        const preflightStartedAt = new Date().toISOString();
+        const preflight = await probeHealthCandidatesOnce(plan.healthCandidates);
+        if (preflight.responded && preflight.evidence) {
+            const url = preflight.evidence.requestedUrl;
+            const explanation = `A service was already responding at ${url} before BootProof started anything, so a health response cannot be attributed to this repository. If you intended to verify an already-running service, use: bootproof verify-url ${url} (or bootproof up . --external-health ${url}).`;
+            const preflightObservation = step("health-preflight", "health", undefined, preflightStartedAt, null, false, `pre-existing service responded ${healthStatusLabel(preflight.evidence)} at ${url}; application was not started`);
+            return refuse("health_preoccupied", explanation, [preflightObservation], explanation, preflight.evidence, [url]);
+        }
     }
     const writtenFiles = writePlanFiles(inference, inference.repoPath);
     if (inference.appCommand?.includes(".bootproof/runtime/")) {
@@ -192,15 +316,19 @@ export async function up(repoPath, opts) {
         const names = extractMissingEnvNames(evidence);
         if (!names.length)
             return explanation;
+        const safeValue = names.length === 1 ? safeLocalEnvValue(names[0]) : null;
+        if (safeValue) {
+            return `${explanation} Missing variable: ${names[0]}. Safe local value: ${safeValue}.`;
+        }
         const generatedExample = path.join(inference.repoPath, ".env.bootproof.example");
         const suffix = fs.existsSync(generatedExample)
             ? `Missing: ${names.join(", ")} — see .env.bootproof.example; bootproof will not invent values.`
-            : `Missing: ${names.join(", ")}; bootproof will not invent values.`;
+            : `Missing variable${names.length === 1 ? "" : "s"}: ${names.join(", ")}. BootProof will not invent values.`;
         return `${explanation} ${suffix}`;
     };
-    const fail = (failureClass, evidence, explanation) => {
+    const fail = (failureClass, evidence, explanation, healthEvidence = null, observedHealthCandidates = []) => {
         const preciseExplanation = explanationWithMissingEnv(failureClass, evidence, explanation);
-        const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: false, healthVerified: false, healthObservation: null, observedHealthCandidates: [], failureClass, failureEvidence: evidence.slice(-2000), explanation: preciseExplanation });
+        const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: false, healthVerified: false, healthObservation: null, healthEvidence, observedHealthCandidates, failureClass, failureEvidence: evidence.slice(-2000), explanation: preciseExplanation, trust });
         writeAttestation(inference.repoPath, att);
         return { inference, plan, writtenFiles, attestation: att, refusal: null };
     };
@@ -224,7 +352,7 @@ export async function up(repoPath, opts) {
             const t = new Date().toISOString();
             const result = await runToCompletion(diagnostic.command, inference.repoPath, 30_000, env);
             const text = [result.stdout, result.stderr].filter(Boolean).join("\n");
-            observed.push(step(diagnostic.id, "service", diagnostic.command, t, result.exitCode, result.exitCode === 0, result.exitCode === 0 ? diagnostic.observation : `${diagnostic.observation} failed`, text || undefined));
+            observed.push(step(diagnostic.id, "service", diagnostic.command, t, result.exitCode, result.exitCode === 0, result.exitCode === 0 ? diagnostic.observation : `${diagnostic.observation} failed`, result.exitCode === 0 ? text || undefined : execResultEvidence(result)));
             if (text)
                 evidence.push(`${diagnostic.command}\n${text}`);
         }
@@ -235,7 +363,7 @@ export async function up(repoPath, opts) {
             const t = new Date().toISOString();
             const r = await runToCompletion(planned.command, inference.repoPath, 120_000, env);
             const ok = r.exitCode === 0;
-            observed.push(step(planned.id, "service", planned.command, t, r.exitCode, ok, ok ? "docker compose accepted the start request (exit 0); HTTP health not yet verified" : "docker compose failed", r.stderr || r.stdout));
+            observed.push(step(planned.id, "service", planned.command, t, r.exitCode, ok, ok ? "docker compose accepted the start request (exit 0); HTTP health not yet verified" : "docker compose failed", ok ? r.stderr || r.stdout : execResultEvidence(r)));
             if (!ok) {
                 const c = classifyFailure(r.stderr + r.stdout);
                 return fail(c.class, r.stderr + r.stdout, c.explanation);
@@ -249,7 +377,7 @@ export async function up(repoPath, opts) {
             const t = new Date().toISOString();
             const r = await runToCompletion(planned.command, inference.repoPath, 600_000, env);
             const ok = r.exitCode === 0 && !r.timedOut;
-            observed.push(step(planned.id, planned.kind, planned.command, t, r.exitCode, ok, ok ? `${planned.kind === "install" ? "dependency preparation" : "build"} completed (exit 0)` : r.timedOut ? `${planned.kind} timed out` : `${planned.kind} failed (exit ${r.exitCode})`, ok ? undefined : r.stderr || r.stdout));
+            observed.push(step(planned.id, planned.kind, planned.command, t, r.exitCode, ok, ok ? `${planned.kind === "install" ? "dependency preparation" : "build"} completed (exit 0)` : r.timedOut ? `${planned.kind} timed out` : `${planned.kind} failed (exit ${r.exitCode})`, ok ? undefined : execResultEvidence(r)));
             if (!ok) {
                 const c = classifyFailure(r.stderr + r.stdout);
                 return fail(c.class === "unknown_failure" ? "install_failed" : c.class, r.stderr + r.stdout, c.explanation);
@@ -258,38 +386,80 @@ export async function up(repoPath, opts) {
         if (planned.kind === "start-app" && planned.command) {
             const t = new Date().toISOString();
             const app = superviseApp(planned.command, inference.repoPath, env);
-            const health = await pollHealthCandidates(plan.healthCandidates, opts.timeoutMs, app.output);
+            const inferredHealthUrl = plan.healthUrl;
+            const inferredHealthCandidates = new Set(plan.healthCandidates);
+            const health = await pollHealthCandidates(plan.healthCandidates, opts.timeoutMs, app.output, 1000, () => app.exited() !== null);
+            await new Promise(resolve => setImmediate(resolve));
+            const advertisedHealthUrls = extractHealthCandidates(app.output());
+            for (const advertisedHealthUrl of advertisedHealthUrls) {
+                if (!health.candidates.includes(advertisedHealthUrl)) {
+                    health.candidates.push(advertisedHealthUrl);
+                }
+                if (!inferredHealthCandidates.has(advertisedHealthUrl)
+                    && !health.discoveredCandidates.includes(advertisedHealthUrl)) {
+                    health.discoveredCandidates.push(advertisedHealthUrl);
+                }
+            }
             plan.healthCandidates = health.candidates;
+            const processOutputHealthUrl = advertisedHealthUrls[0] ?? health.discoveredCandidates[0];
+            if (processOutputHealthUrl) {
+                recordHealthPort(inference, plan, processOutputHealthUrl, "process_output");
+            }
             if (health.url)
                 plan.healthUrl = health.url;
+            const portMismatch = detectHealthCandidatePortMismatch(inferredHealthUrl, health.discoveredCandidates, planned.command);
+            const portMismatchEvidence = healthCandidatePortMismatchEvidence(portMismatch);
+            const packageScriptContext = packageScriptFailureContext(inference);
             const exit = app.exited();
-            if (exit && !health.responded) {
-                observed.push(step(planned.id, "start-app", planned.command, t, exit.code, false, `app process exited (code ${exit.code}) before responding`, app.output()));
-                const c = classifyFailure(app.output());
+            if (exit) {
+                const processEvidence = app.evidence();
+                const unattributedHealthEvidence = health.evidence?.acceptedAsHealthy
+                    ? `An accepted ${healthStatusLabel(health.evidence)} response was observed at ${health.evidence.requestedUrl}, but the supervised process had already exited, so BootProof did not attribute that response to this repository.`
+                    : "";
+                const evidence = [
+                    processEvidenceText(processEvidence),
+                    unattributedHealthEvidence,
+                    portMismatchEvidence,
+                    packageScriptContext,
+                ].filter(Boolean).join("\n");
+                const observation = health.evidence?.acceptedAsHealthy
+                    ? `app process exited (code ${exit.code}) before the accepted health response could be attributed to it`
+                    : `app process exited (code ${exit.code}) before responding`;
+                observed.push(step(planned.id, "start-app", planned.command, t, exit.code, false, observation, processEvidence));
+                const c = classifyFailure(evidence);
                 await app.stop();
-                return fail(c.class === "unknown_failure" ? "app_exited_early" : c.class, app.output(), c.explanation);
+                const finalExplanation = c.class === "unknown_failure"
+                    ? appExitedEarlyExplanation(c.explanation, processEvidence)
+                    : c.explanation;
+                return fail(c.class === "unknown_failure" ? "app_exited_early" : c.class, evidence, finalExplanation, health.evidence, health.discoveredCandidates);
             }
             observed.push(step(planned.id, "start-app", planned.command, t, null, true, "app process started and was supervised"));
             const ht = new Date().toISOString();
-            if (health.responded && health.status !== null && health.status < 500) {
-                const observedUrl = health.url ?? plan.healthUrl;
-                observed.push(step("health", "health", undefined, ht, null, true, `observed HTTP ${health.status} at ${observedUrl} after ${health.elapsedMs}ms (${health.attempts} attempts)`));
+            if (health.evidence?.acceptedAsHealthy) {
+                recordHealthPort(inference, plan, health.evidence.requestedUrl, "observed");
+                const healthStep = health.evidence.redirectLocation
+                    ? healthStatusLabel(health.evidence)
+                    : `observed HTTP ${health.evidence.statusCode} at ${health.evidence.requestedUrl} after ${health.elapsedMs}ms (${health.attempts} attempts)`;
+                observed.push(step("health", "health", undefined, ht, null, true, healthStep));
                 await app.stop();
-                const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: true, healthVerified: true, healthObservation: `HTTP ${health.status} at ${observedUrl}`, observedHealthCandidates: health.discoveredCandidates, failureClass: null, failureEvidence: null, explanation: `Verified: ${observedUrl} responded HTTP ${health.status}. This attestation records what was observed, not a guarantee the app is fully functional.` });
+                const att = buildAttestation({ repo: inference.repoPath, plan, observed, startedAt, booted: true, healthVerified: true, healthObservation: healthObservationSummary(health.evidence), healthEvidence: health.evidence, observedHealthCandidates: health.discoveredCandidates, failureClass: null, failureEvidence: null, explanation: `Verified: ${health.evidence.requestedUrl} responded ${healthStatusLabel(health.evidence)}. This attestation records what was observed, not a guarantee the app is fully functional.`, trust });
                 writeAttestation(inference.repoPath, att);
                 return { inference, plan, writtenFiles, attestation: att, refusal: null };
             }
-            const evidence = app.output();
+            const processEvidence = app.evidence();
+            const evidence = [processEvidenceText(processEvidence), portMismatchEvidence, packageScriptContext].filter(Boolean).join("\n");
             const healthFailureMessage = health.responded
                 ? `only HTTP ${health.status} observed at ${health.url ?? plan.healthUrl}`
                 : `no HTTP response at candidates ${health.candidates.join(", ")} within ${opts.timeoutMs}ms`;
-            observed.push(step("health", "health", undefined, ht, null, false, healthFailureMessage, evidence));
+            observed.push(step("health", "health", undefined, ht, null, false, healthFailureMessage, processEvidence));
             const c = classifyFailure(`${healthFailureMessage}\n${evidence}`);
-            const healthClass = health.responded && health.status !== null && health.status >= 500
-                ? "health_http_error"
-                : c.class === "unknown_failure"
-                    ? classifyHealthFailure(healthFailureMessage)
-                    : c.class;
+            const healthClass = portMismatch
+                ? "health_candidate_port_mismatch"
+                : health.responded && health.status !== null && health.status >= 500
+                    ? "health_http_error"
+                    : c.class === "unknown_failure"
+                        ? classifyHealthFailure(healthFailureMessage)
+                        : c.class;
             const healthExplanation = healthClass === "health_http_error"
                 ? "The app responded on the configured health URL, but returned HTTP 5xx. BootProof observed a running server, but not a verified healthy boot."
                 : c.explanation;
@@ -303,10 +473,12 @@ export async function up(repoPath, opts) {
                 booted: false,
                 healthVerified: false,
                 healthObservation: null,
+                healthEvidence: health.evidence,
                 observedHealthCandidates: health.discoveredCandidates,
                 failureClass: healthClass,
                 failureEvidence: `${healthFailureMessage}\n${evidence}`.slice(-2000),
                 explanation: preciseHealthExplanation,
+                trust,
             });
             writeAttestation(inference.repoPath, att);
             return { inference, plan, writtenFiles, attestation: att, refusal: null };
@@ -317,9 +489,12 @@ export async function up(repoPath, opts) {
             plan.healthCandidates = health.candidates;
             if (health.url)
                 plan.healthUrl = health.url;
-            if (health.responded && health.status !== null && health.status < 500) {
-                const observedUrl = health.url ?? plan.healthUrl;
-                observed.push(step("health", "health", undefined, ht, null, true, `observed HTTP ${health.status} at ${observedUrl} after ${health.elapsedMs}ms (${health.attempts} attempts)`));
+            if (health.evidence?.acceptedAsHealthy) {
+                recordHealthPort(inference, plan, health.evidence.requestedUrl, "observed");
+                const healthStep = health.evidence.redirectLocation
+                    ? healthStatusLabel(health.evidence)
+                    : `observed HTTP ${health.evidence.statusCode} at ${health.evidence.requestedUrl} after ${health.elapsedMs}ms (${health.attempts} attempts)`;
+                observed.push(step("health", "health", undefined, ht, null, true, healthStep));
                 const att = buildAttestation({
                     repo: inference.repoPath,
                     plan,
@@ -327,11 +502,13 @@ export async function up(repoPath, opts) {
                     startedAt,
                     booted: true,
                     healthVerified: true,
-                    healthObservation: `HTTP ${health.status} at ${observedUrl}`,
+                    healthObservation: healthObservationSummary(health.evidence),
+                    healthEvidence: health.evidence,
                     observedHealthCandidates: health.discoveredCandidates,
                     failureClass: null,
                     failureEvidence: null,
-                    explanation: `Verified: repository Compose started and ${observedUrl} responded HTTP ${health.status}. This proves the observed web boot, not every service or feature.`,
+                    explanation: `Verified: repository Compose started and ${health.evidence.requestedUrl} responded ${healthStatusLabel(health.evidence)}. This proves the observed web boot, not every service or feature.`,
+                    trust,
                 });
                 writeAttestation(inference.repoPath, att);
                 return { inference, plan, writtenFiles, attestation: att, refusal: null };
@@ -353,8 +530,8 @@ export async function up(repoPath, opts) {
                 : failureClass === "health_check_timeout"
                     ? "Repository Compose accepted the start request, but no HTTP response was observed. Compose service state and logs are preserved in the attestation."
                     : classified.explanation;
-            return fail(failureClass, evidence, explanation);
+            return fail(failureClass, evidence, explanation, health.evidence, health.discoveredCandidates);
         }
     }
-    return fail("unknown_failure", "", "Inference identified an application, but the plan contained no supported runnable app or source-built Compose health step.");
+    return fail("orchestration_not_supported", "", "Inference identified an application, but the plan contained no supported runnable app or source-built Compose health step.");
 }

package/dist/sbom.d.ts

@@ -0,0 +1,22 @@
+export type SbomFormat = "cyclonedx-json";
+export interface SbomResult {
+    schema: "bootproof/sbom-result/v1";
+    format: SbomFormat;
+    path: string;
+    componentCount: number;
+    components: Array<{
+        name: string;
+        version: string;
+        purl: string;
+    }>;
+}
+/**
+ * Export a Software Bill of Materials from a repository's dependency manifest.
+ * Currently supports npm (package-lock.json) and emits CycloneDX JSON.
+ *
+ * This is a minimal, honest SBOM: it reads the lockfile that already exists,
+ * classifies each dependency as a library component, and emits a CycloneDX
+ * document. It does not resolve transitive dependencies that aren't in the
+ * lockfile, and it does not claim to — the output states what it found.
+ */
+export declare function exportSbom(repoPath: string, format?: SbomFormat): SbomResult;

package/dist/sbom.js

@@ -0,0 +1,99 @@
+import fs from "node:fs";
+import path from "node:path";
+import { TOOL_ID } from "./proof.js";
+/**
+ * Export a Software Bill of Materials from a repository's dependency manifest.
+ * Currently supports npm (package-lock.json) and emits CycloneDX JSON.
+ *
+ * This is a minimal, honest SBOM: it reads the lockfile that already exists,
+ * classifies each dependency as a library component, and emits a CycloneDX
+ * document. It does not resolve transitive dependencies that aren't in the
+ * lockfile, and it does not claim to — the output states what it found.
+ */
+export function exportSbom(repoPath, format = "cyclonedx-json") {
+    if (format !== "cyclonedx-json") {
+        throw new Error(`Unsupported SBOM format: ${format}. Currently supported: cyclonedx-json.`);
+    }
+    const lockfile = path.join(repoPath, "package-lock.json");
+    if (!fs.existsSync(lockfile)) {
+        throw new Error(`No package-lock.json found at ${repoPath}. SBOM export currently supports npm repositories with a committed lockfile.`);
+    }
+    const lock = JSON.parse(fs.readFileSync(lockfile, "utf8"));
+    // package-lock.json v2/v3 uses "packages" with keys like "node_modules/express".
+    // v1 uses "dependencies" with package names as keys.
+    const components = [];
+    const seen = new Set();
+    if (lock.packages) {
+        for (const [key, info] of Object.entries(lock.packages)) {
+            // Skip the root package (empty string key) and nested node_modules paths
+            // (we want the top-level resolved version, not nested dedupes).
+            if (key === "")
+                continue;
+            const name = key.startsWith("node_modules/") ? key.slice("node_modules/".length) : key;
+            // Skip scoped nested paths like node_modules/foo/node_modules/bar
+            if (name.includes("node_modules/"))
+                continue;
+            if (!info.version)
+                continue;
+            const id = `${name}@${info.version}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            components.push({
+                name,
+                version: info.version,
+                purl: `pkg:npm/${name}@${info.version}`,
+            });
+        }
+    }
+    else if (lock.dependencies) {
+        for (const [name, info] of Object.entries(lock.dependencies)) {
+            if (!info.version)
+                continue;
+            const id = `${name}@${info.version}`;
+            if (seen.has(id))
+                continue;
+            seen.add(id);
+            components.push({
+                name,
+                version: info.version,
+                purl: `pkg:npm/${name}@${info.version}`,
+            });
+        }
+    }
+    const appName = lock.name ?? path.basename(path.resolve(repoPath));
+    const appVersion = lock.version ?? "unknown";
+    const bom = {
+        bomFormat: "CycloneDX",
+        specVersion: "1.5",
+        version: 1,
+        metadata: {
+            timestamp: new Date().toISOString(),
+            tools: [{ vendor: "bootproof", name: "bootproof", version: TOOL_ID.replace(/^bootproof@/, "") }],
+            component: {
+                type: "application",
+                "bom-ref": `pkg:npm/${appName}@${appVersion}`,
+                name: appName,
+                version: appVersion,
+            },
+        },
+        components: components.map(c => ({
+            type: "library",
+            "bom-ref": c.purl,
+            name: c.name,
+            version: c.version,
+            purl: c.purl,
+        })),
+    };
+    const outDir = path.join(repoPath, ".bootproof");
+    fs.mkdirSync(outDir, { recursive: true });
+    const outFile = path.join(outDir, "sbom.cdx.json");
+    fs.writeFileSync(outFile, JSON.stringify(bom, null, 2) + "\n");
+    return {
+        schema: "bootproof/sbom-result/v1",
+        format,
+        path: outFile,
+        componentCount: components.length,
+        components,
+    };
+}

package/dist/taxonomy.d.ts

@@ -1,7 +1,12 @@
 import type { FailureClass } from "./types.js";
-export declare function extractMissingEnvNames(evidence: string): string[];
-export declare function classifyFailure(evidence: string): {
+export type FailureMetadata = Record<string, string | string[]>;
+export interface FailureClassification {
     class: FailureClass;
     explanation: string;
-};
+    metadata?: FailureMetadata;
+    safeNextStep?: string;
+}
+export declare function extractMissingEnvNames(evidence: string): string[];
+export declare function safeLocalEnvValue(name: string): string | null;
+export declare function classifyFailure(evidence: string): FailureClassification;
 export declare const TAXONOMY_DOC_CLASSES: FailureClass[];