bootproof 0.1.0 → 0.4.0

package/dist/run.d.ts

@@ -1,4 +1,4 @@
-import type { Inference, RunPlan, FailureClass, Attestation } from "./types.js";
+import type { Inference, RunPlan, FailureClass, Attestation, PreparationCommand } from "./types.js";
 export interface UpOptions {
     provider: "docker" | "local";
     unsafeLocal: boolean;
@@ -8,6 +8,11 @@ export interface UpOptions {
     timeoutMs: number;
     install: boolean;
     port?: number;
+    environment?: Record<string, string>;
+    additionalPreparationCommands?: PreparationCommand[];
+    command?: string;
+    healthPath?: string;
+    ciOidc?: boolean;
 }
 export interface UpOutcome {
     inference: Inference;

package/dist/run.js

@@ -1,17 +1,91 @@
 import { execFileSync } from "node:child_process";
+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 } 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+))?$/);
@@ -22,11 +96,21 @@ export function packageManagerVersionMatches(expected, actual) {
     const actualParts = actualMatch.slice(1, 1 + expectedParts.length);
     return expectedParts.every((part, index) => part === actualParts[index]);
 }
-function packageManagerVersionEvidence(inference) {
+function commandUsesExecutable(command, executable) {
+    if (!command)
+        return false;
+    const escaped = executable.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+    return new RegExp(`(?:^|&&|\\|\\||;)\\s*${escaped}(?:\\s|$)`).test(command);
+}
+function packageManagerVersionEvidence(inference, plan, env) {
     if (inference.packageManager === "unknown" || !inference.packageManagerVersion)
         return null;
+    if (!plan.steps.some(planned => commandUsesExecutable(planned.command, inference.packageManager)))
+        return null;
     try {
-        const actual = execFileSync(inference.packageManager, ["--version"], { cwd: inference.repoPath, encoding: "utf8" }).trim();
+        const actual = process.platform === "win32"
+            ? execFileSync(process.env.ComSpec ?? "cmd.exe", ["/d", "/s", "/c", `${inference.packageManager} --version`], { cwd: inference.repoPath, encoding: "utf8", env }).trim()
+            : execFileSync(inference.packageManager, ["--version"], { cwd: inference.repoPath, encoding: "utf8", env }).trim();
         if (packageManagerVersionMatches(inference.packageManagerVersion, actual))
             return null;
         return `packageManager field or engines.${inference.packageManager} expected version: ${inference.packageManagerVersion}\nGot: ${actual}`;
@@ -35,17 +119,101 @@ function packageManagerVersionEvidence(inference) {
         return null;
     }
 }
+function commandWithPort(command, port) {
+    return command
+        .replace(/((?:--port(?:=|\s+)|-p\s+))\d{2,5}\b/, `$1${port}`)
+        .replace(/(\bmanage\.py\s+runserver\s+(?:127\.0\.0\.1|localhost):)\d{2,5}\b/, `$1${port}`);
+}
+function unsupportedOrchestrationExplanation(inference) {
+    if (inference.appCommand)
+        return null;
+    const sourceComposeServices = inference.composeApplicationServices.filter(service => service.source === "build");
+    if (sourceComposeServices.length > 1) {
+        return `Detected multiple source-built HTTP services in ${inference.repoComposeFile}: ${sourceComposeServices.map(service => service.name).join(", ")}. BootProof will not treat one responding service as proof that the repository booted. Diagnosis only — no localhost claim.`;
+    }
+    if (sourceComposeServices.length === 1 && inference.composeHealthCandidates.length === 0) {
+        return `Detected source-built service ${sourceComposeServices[0].name} in ${inference.repoComposeFile}, but no unambiguous published HTTP candidate. Diagnosis only — no localhost claim.`;
+    }
+    const backend = inference.stack.includes("go-backend")
+        ? { stack: "go-backend", markers: inference.backendMarkers.filter(marker => marker === "go.mod" || marker === "go.work") }
+        : inference.stack.includes("ruby-backend")
+            ? { stack: "ruby-backend", markers: inference.backendMarkers.filter(marker => marker === "Gemfile" || marker === "config/database.yml") }
+            : inference.stack.includes("make-driven")
+                ? { stack: "make-driven", markers: inference.backendMarkers.filter(marker => marker === "Makefile") }
+                : null;
+    if (!backend)
+        return null;
+    const frontendStack = inference.stack.includes("react-frontend")
+        ? "react-frontend"
+        : inference.stack.includes("node-frontend")
+            ? "node-frontend"
+            : null;
+    const frontendMarker = inference.frontendMarkers.find(marker => marker.endsWith("/package.json"))
+        ?? inference.frontendMarkers.find(marker => marker === "package.json");
+    const frontend = frontendStack && frontendMarker ? ` with ${frontendStack} (${frontendMarker})` : "";
+    return `Detected ${backend.stack} (${backend.markers.join(", ")})${frontend}. BootProof can diagnose this stack but does not yet orchestrate its boot. Diagnosis only — no localhost claim.`;
+}
 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;
+    }
     if (opts.port) {
-        inference.port = opts.port;
-        inference.portEvidence = "set by --port flag";
-        inference.healthCandidates = inference.healthCandidates.map(candidate => candidate.replace(/:\d{2,5}(?=\/)/, `:${opts.port}`));
+        if (inference.appCommand) {
+            inference.port = opts.port;
+            inference.portEvidence = "set by --port flag";
+            inference.appCommand = commandWithPort(inference.appCommand, opts.port);
+            if (inference.backendCommand)
+                inference.backendCommand = commandWithPort(inference.backendCommand, opts.port);
+            inference.healthCandidates = inference.healthCandidates.map(candidate => candidate.replace(/:\d{2,5}(?=\/)/, `:${opts.port}`));
+        }
+        else if (inference.composeHealthCandidates.length) {
+            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 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 };
@@ -63,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 };
@@ -77,62 +247,137 @@ export async function up(repoPath, opts) {
     if (inference.stack.includes("python-backend") && inference.stack.includes("flask") && inference.setupSteps.length > 0) {
         return refuse("python_flask_setup_required", "BootProof detected a Python/Flask + React application with setup steps. This repository requires database migration/init and service orchestration before it can be verified.");
     }
+    const orchestrationExplanation = unsupportedOrchestrationExplanation(inference);
+    if (orchestrationExplanation && !runsSourceComposeApplication) {
+        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.`);
+    }
     if (!opts.workspace && inference.workspaces.length > 1 && !inference.appCommand) {
         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 };
-    if (inference.dependencyInstallRequired && !opts.install) {
-        const skipped = step("install", "install", inference.installCommand ?? undefined, new Date().toISOString(), null, false, "skipped by default — dependency-backed application was not started; pass --install to run dependency installation");
+    if (inference.multiAppCommand) {
+        return refuse("workspace_ambiguous", "BootProof detected a root command that starts multiple workspaces in parallel. Choose a specific application with --workspace <dir>; one responding workspace is not proof that the whole repository booted.");
+    }
+    const preparationSteps = plan.steps.filter(planned => planned.kind === "install" || planned.kind === "build");
+    if (preparationSteps.length > 0 && !opts.install) {
+        const skipped = step(preparationSteps[0].id, preparationSteps[0].kind, preparationSteps[0].command, new Date().toISOString(), null, false, "skipped by default — dependency-backed application was not started; pass --install to run dependency installation");
         return refuse("dependency_install_skipped", "The inferred application command depends on project packages, but dependency installation was not requested. BootProof did not start the partial application pipeline.", [skipped]);
     }
+    const hostExecutionSteps = plan.steps.filter(planned => planned.kind === "install" ||
+        planned.kind === "build" ||
+        planned.kind === "start-app");
+    if (opts.provider === "docker" && !runsSourceComposeApplication && hostExecutionSteps.length > 0) {
+        return refuse("orchestration_not_supported", `Docker provider selected, but the inferred plan contains host commands (${hostExecutionSteps.map(planned => planned.command).filter(Boolean).join("; ")}). BootProof will not silently run them on the host. Use a source-built repository Compose application, or explicitly choose --provider local --unsafe-local after review.`);
+    }
     if (opts.install) {
-        const versionEvidence = packageManagerVersionEvidence(inference);
+        const versionEvidence = packageManagerVersionEvidence(inference, plan, env);
         if (versionEvidence) {
             const observed = step("package-manager-version", "install", `${inference.packageManager} --version`, new Date().toISOString(), 0, false, `declared ${inference.packageManager} ${inference.packageManagerVersion}, but found ${versionEvidence.split("Got: ")[1]}`, versionEvidence);
             return refuse("package_manager_version_mismatch", "The repository declares a package manager version that does not match the version available in the current environment. Enable Corepack or install the required package manager version before rerunning BootProof.", [observed], versionEvidence);
         }
     }
-    if (inference.multiAppCommand) {
-        return refuse("workspace_ambiguous", "BootProof detected a root command that starts multiple workspaces in parallel. Choose a specific application with --workspace <dir>; one responding workspace is not proof that the whole repository booted.");
-    }
     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/")) {
+        fs.mkdirSync(path.join(inference.repoPath, ".bootproof", "runtime"), { recursive: true });
+    }
     const observed = [];
-    const env = minimalEnv({ PORT: String(inference.port) });
-    const fail = (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 });
+    const explanationWithMissingEnv = (failureClass, evidence, explanation) => {
+        if (failureClass !== "missing_env_var")
+            return explanation;
+        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 variable${names.length === 1 ? "" : "s"}: ${names.join(", ")}. BootProof will not invent values.`;
+        return `${explanation} ${suffix}`;
+    };
+    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, healthEvidence, observedHealthCandidates, failureClass, failureEvidence: evidence.slice(-2000), explanation: preciseExplanation, trust });
         writeAttestation(inference.repoPath, att);
         return { inference, plan, writtenFiles, attestation: att, refusal: null };
     };
+    const composeDiagnostics = async () => {
+        if (!inference.repoComposeFile)
+            return "";
+        const commands = [
+            {
+                id: "compose-ps",
+                command: `docker compose -f ${inference.repoComposeFile} ps --all`,
+                observation: "captured repository Compose service state",
+            },
+            {
+                id: "compose-logs",
+                command: `docker compose -f ${inference.repoComposeFile} logs --no-color --tail 200`,
+                observation: "captured repository Compose logs",
+            },
+        ];
+        const evidence = [];
+        for (const diagnostic of commands) {
+            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`, result.exitCode === 0 ? text || undefined : execResultEvidence(result)));
+            if (text)
+                evidence.push(`${diagnostic.command}\n${text}`);
+        }
+        return evidence.join("\n");
+    };
     for (const planned of plan.steps) {
         if (planned.kind === "service" && planned.command) {
             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 ? "services started (docker compose exit 0)" : "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);
             }
         }
-        if (planned.kind === "install" && planned.command) {
+        if ((planned.kind === "install" || planned.kind === "build") && planned.command) {
             if (!opts.install) {
-                observed.push(step(planned.id, "install", planned.command, new Date().toISOString(), null, false, "skipped by default — optional install was not needed for the observed boot"));
+                observed.push(step(planned.id, planned.kind, planned.command, new Date().toISOString(), null, false, "skipped by default — preparation was not authorized"));
                 continue;
             }
             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, "install", planned.command, t, r.exitCode, ok, ok ? "dependencies installed (exit 0)" : r.timedOut ? "install timed out" : `install 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);
@@ -141,41 +386,84 @@ 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;
+            const preciseHealthExplanation = explanationWithMissingEnv(healthClass, `${healthFailureMessage}\n${evidence}`, healthExplanation);
             await app.stop();
             const att = buildAttestation({
                 repo: inference.repoPath,
@@ -185,14 +473,65 @@ 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: healthExplanation,
+                explanation: preciseHealthExplanation,
+                trust,
             });
             writeAttestation(inference.repoPath, att);
             return { inference, plan, writtenFiles, attestation: att, refusal: null };
         }
+        if (planned.kind === "health" && runsSourceComposeApplication) {
+            const ht = new Date().toISOString();
+            const health = await pollHealthCandidates(plan.healthCandidates, opts.timeoutMs);
+            plan.healthCandidates = health.candidates;
+            if (health.url)
+                plan.healthUrl = health.url;
+            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,
+                    observed,
+                    startedAt,
+                    booted: true,
+                    healthVerified: true,
+                    healthObservation: healthObservationSummary(health.evidence),
+                    healthEvidence: health.evidence,
+                    observedHealthCandidates: health.discoveredCandidates,
+                    failureClass: null,
+                    failureEvidence: null,
+                    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 };
+            }
+            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));
+            const diagnostics = await composeDiagnostics();
+            const evidence = [healthFailureMessage, diagnostics].filter(Boolean).join("\n");
+            const classified = classifyFailure(evidence);
+            const failureClass = health.responded && health.status !== null && health.status >= 500
+                ? "health_http_error"
+                : classified.class === "unknown_failure"
+                    ? classifyHealthFailure(healthFailureMessage)
+                    : classified.class;
+            const explanation = failureClass === "health_http_error"
+                ? "The Compose application responded on the configured health URL, but returned HTTP 5xx. BootProof observed a server, but not a verified healthy boot."
+                : 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, health.evidence, health.discoveredCandidates);
+        }
     }
-    return fail("not_an_application", "", "Plan contained no runnable app 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;