rea-agents 1.2.0 → 1.4.0

package/dist/domain/errors.js

@@ -1,5 +1,7 @@
+import { hopperStartupFailure, } from "./hopperStartupFailure.js";
+export { hopperStartupFailure };
 /** Stable tags exposed by safe analysis-error projections. */
-export const ANALYSIS_ERROR_TAGS = [
+const ANALYSIS_ERROR_TAGS = [
     "AnalysisProtocolError",
     "AnalysisInputError",
     "AnalysisOutputError",
@@ -13,6 +15,7 @@ export const ANALYSIS_ERROR_TAGS = [
     "EvidenceIntegrityError",
     "EvidenceLimitError",
     "EvidenceFileError",
+    "InvestigationWorkspaceError",
     "UnknownRegistryError",
     "HopperTimeoutError",
     "HopperCancelledError",
@@ -23,9 +26,14 @@ export const ANALYSIS_ERROR_TAGS = [
     "ConfigurationError",
     "NoBinaryOpenError",
     "BinaryTargetError",
+    "PermissionRequiredError",
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
+    userMessage = undefined;
+    userCategory = undefined;
+    cleanupIncomplete = false;
+    cleanupResources = [];
 }
 /** Base class for failures produced specifically by the Hopper provider. */
 export class HopperError extends AnalysisError {
@@ -148,6 +156,17 @@ export class EvidenceFileError extends AnalysisError {
         this.reason = reason;
     }
 }
+/** Persistent investigation workspace access or CAS validation failed. */
+export class InvestigationWorkspaceError extends AnalysisError {
+    operation;
+    reason;
+    _tag = "InvestigationWorkspaceError";
+    constructor(operation, reason, options) {
+        super(`Investigation workspace ${operation} failed: ${reason}`, options);
+        this.operation = operation;
+        this.reason = reason;
+    }
+}
 /** Residual-unknown mutation failed a lifecycle, reference, or CAS invariant. */
 export class UnknownRegistryError extends AnalysisError {
     reason;
@@ -194,9 +213,14 @@ export class HopperRemoteError extends HopperError {
 export class HopperProcessError extends HopperError {
     exitCode;
     _tag = "HopperProcessError";
+    failureCode;
+    userMessage;
     constructor(exitCode) {
         super(`Hopper bridge stopped unexpectedly with code ${String(exitCode)}`);
         this.exitCode = exitCode;
+        const failure = hopperStartupFailure(exitCode);
+        this.failureCode = failure?.code;
+        this.userMessage = failure?.message;
     }
 }
 /** Hopper or the repository bridge could not be started. */
@@ -226,57 +250,383 @@ export class BinaryTargetError extends AnalysisError {
         this.path = path;
     }
 }
+/** Exact denied authority used by both CLI and MCP remediation. */
+export class PermissionRequiredError extends AnalysisError {
+    requested;
+    missing;
+    ceiling;
+    elicitationSupported;
+    restartRequired;
+    _tag = "PermissionRequiredError";
+    constructor(requested, missing, ceiling, elicitationSupported, restartRequired) {
+        super(`Permission required for ${requested.capability}`);
+        this.requested = requested;
+        this.missing = missing;
+        this.ceiling = ceiling;
+        this.elicitationSupported = elicitationSupported;
+        this.restartRequired = restartRequired;
+    }
+}
 /** Project expected failures into exhaustive, secret-safe caller fields. */
 export const projectAnalysisError = (error) => {
     assertKnownTag(error._tag);
+    const code = errorCode(error);
+    const details = errorDetails(error);
     return {
-        tag: error._tag,
-        message: error.message,
-        details: safeDetails(error),
+        code,
+        category: errorCategory(error),
+        message: userMessage(error),
+        retryable: RETRYABLE_CODES.has(code),
+        remediation: {
+            action: remediationAction(error),
+            restart_required: error instanceof PermissionRequiredError && error.restartRequired,
+            ...(error instanceof PermissionRequiredError
+                ? { elicitation_supported: error.elicitationSupported }
+                : {}),
+        },
+        ...(details === undefined ? {} : { details }),
     };
 };
-const safeDetails = (error) => {
-    if (error instanceof AnalysisInputError)
-        return { operation: error.operation };
-    if (error instanceof AnalysisOutputError)
-        return { operation: error.operation, reason: error.reason };
-    if (error instanceof AnalysisCapabilityUnavailableError)
+const errorCode = (error) => {
+    if (error instanceof PermissionRequiredError)
+        return "permission_required";
+    if (error instanceof ArtifactOperationError)
+        return error.reason === "integrity" && error.artifactDetails !== undefined
+            ? "artifact_integrity_mismatch"
+            : error.reason === "limit"
+                ? "truncated"
+                : error.reason === "cancelled"
+                    ? "cancelled"
+                    : "artifact_operation_failed";
+    if (error instanceof EvidenceFileError)
+        return error.reason === "outside-root"
+            ? "outside_approved_root"
+            : error.reason === "too-large"
+                ? "truncated"
+                : error.reason === "disabled"
+                    ? "capability_unavailable"
+                    : "execution_failure";
+    if (error instanceof InvestigationWorkspaceError) {
+        if (error.reason === "revision-conflict" ||
+            error.reason === "name-conflict")
+            return "revision_conflict";
+        if (error.reason === "too-large")
+            return "truncated";
+        if (error.reason === "disabled")
+            return "capability_unavailable";
+        if (error.reason === "outside-root")
+            return "outside_approved_root";
+        if (error.reason === "integrity" || error.reason === "invalid-json")
+            return "evidence_integrity_mismatch";
+        return "execution_failure";
+    }
+    if (error instanceof UnknownRegistryError)
+        return error.reason === "revision-conflict" ||
+            error.reason === "already-exists"
+            ? "revision_conflict"
+            : error.reason === "limit"
+                ? "truncated"
+                : error.reason === "integrity"
+                    ? "evidence_integrity_mismatch"
+                    : "execution_failure";
+    if (error._tag === "ProcessCaptureError")
+        return error.cleanupIncomplete
+            ? "cleanup_incomplete"
+            : error.userCategory === "cancelled"
+                ? "cancelled"
+                : error.userCategory === "permission_required"
+                    ? "permission_required"
+                    : "process_capture_failed";
+    switch (error._tag) {
+        case "AnalysisProtocolError":
+        case "AnalysisOutputError":
+        case "HopperProtocolError":
+            return "unreadable_output";
+        case "AnalysisInputError":
+            return "invalid_request";
+        case "AnalysisCapabilityUnavailableError":
+        case "ProviderSelectionError":
+            return "capability_unavailable";
+        case "AnalysisCancelledError":
+        case "HopperCancelledError":
+            return "cancelled";
+        case "AnalysisTimeoutError":
+        case "HopperTimeoutError":
+            return "provider_timeout";
+        case "HopperProcessError":
+        case "HopperStartError":
+            return "provider_unavailable";
+        case "ConfigurationError":
+            return "configuration_invalid";
+        case "NoBinaryOpenError":
+        case "BinaryTargetError":
+            return "target_unavailable";
+        case "EvidenceIntegrityError":
+            return "evidence_integrity_mismatch";
+        case "EvidenceLimitError":
+            return "truncated";
+        case "ProviderAdapterError":
+        case "HopperRemoteError":
+            return "execution_failure";
+        case "ArtifactOperationError":
+        case "EvidenceFileError":
+        case "InvestigationWorkspaceError":
+        case "UnknownRegistryError":
+        case "PermissionRequiredError":
+            throw new TypeError("Unhandled specialized analysis error");
+    }
+};
+const errorDetails = (error) => {
+    if (error instanceof PermissionRequiredError)
         return {
-            providerId: error.providerId,
-            operation: error.operation,
-            reason: error.reason,
+            capability: error.requested.capability,
+            requested: scopeDetails(error.requested),
+            missing: missingScopeDetails(error.missing),
+            ceiling: error.ceiling === null ? null : scopeDetails(error.ceiling),
+        };
+    if (error instanceof ArtifactOperationError && error.artifactDetails)
+        return {
+            logical_path: error.artifactDetails.logicalPath,
+            declared_sha256: error.artifactDetails.declaredSha256,
+            calculated_sha256: error.artifactDetails.calculatedSha256,
+            unpacked: error.artifactDetails.unpacked,
         };
-    if (error instanceof AnalysisCancelledError)
-        return { operation: error.operation };
-    if (error instanceof AnalysisTimeoutError)
-        return { operation: error.operation, timeoutMs: error.timeoutMs };
-    if (error instanceof ProviderSelectionError)
-        return { operation: error.operation };
-    if (error instanceof ProviderAdapterError)
-        return { providerId: error.providerId, operation: error.operation };
     if (error instanceof ArtifactOperationError)
         return {
             operation: error.operation,
             reason: error.reason,
-            ...error.artifactDetails,
+            ...(error.reason === "limit" ? { truncated: true } : {}),
         };
+    if (error instanceof AnalysisCancelledError)
+        return { operation: error.operation, cleanup: "complete" };
+    if (error instanceof HopperCancelledError)
+        return { operation: "hopper", cleanup: "complete" };
+    if (error instanceof AnalysisTimeoutError)
+        return { operation: error.operation, timeout_ms: error.timeoutMs };
+    if (error instanceof HopperTimeoutError)
+        return { operation: "hopper", timeout_ms: error.timeoutMs };
     if (error instanceof EvidenceLimitError)
-        return { limit: error.limit, maximum: error.maximum };
-    if (error instanceof EvidenceFileError)
+        return { limit: error.limit, maximum: error.maximum, truncated: true };
+    if (error instanceof InvestigationWorkspaceError)
         return { operation: error.operation, reason: error.reason };
     if (error instanceof UnknownRegistryError)
         return { reason: error.reason };
-    if (error instanceof HopperTimeoutError)
-        return { timeoutMs: error.timeoutMs };
+    if (error instanceof EvidenceFileError)
+        return { operation: error.operation, reason: error.reason };
+    if (error instanceof AnalysisCapabilityUnavailableError)
+        return { provider_id: error.providerId, operation: error.operation };
+    if (error instanceof ProviderAdapterError)
+        return { provider_id: error.providerId, operation: error.operation };
     if (error instanceof HopperRemoteError)
+        return { provider_code: error.code, diagnostic_type: error.diagnosticType };
+    if (error instanceof HopperProcessError && error.failureCode !== undefined)
+        return { failure_code: error.failureCode, exit_code: error.exitCode };
+    if (error._tag === "ProcessCaptureError" && error.cleanupIncomplete)
         return {
-            code: error.code,
-            safeMessage: error.safeMessage,
-            diagnosticType: error.diagnosticType,
+            cleanup: "incomplete",
+            resources: [...error.cleanupResources],
         };
-    if (error instanceof HopperProcessError)
-        return { exitCode: error.exitCode };
-    return {};
+    if (error._tag === "ProcessCaptureError" &&
+        error.userCategory === "cancelled")
+        return { operation: "process_capture", cleanup: "complete" };
+    if (error instanceof BinaryTargetError)
+        return { path: error.path };
+    return undefined;
+};
+const scopeDetails = (scope) => ({
+    capability: scope.capability,
+    roots: [...scope.roots],
+    executables: [...scope.executables],
+    environment_names: [...scope.environment_names],
+    network: scope.network,
+    mount: scope.mount,
+});
+const missingScopeDetails = (scope) => ({
+    ...(scope.roots === undefined ? {} : { roots: [...scope.roots] }),
+    ...(scope.executables === undefined
+        ? {}
+        : { executables: [...scope.executables] }),
+    ...(scope.environment_names === undefined
+        ? {}
+        : { environment_names: [...scope.environment_names] }),
+    ...(scope.network === undefined ? {} : { network: scope.network }),
+    ...(scope.mount === undefined ? {} : { mount: scope.mount }),
+});
+const RETRYABLE_CODES = new Set([
+    "provider_timeout",
+    "cancelled",
+    "revision_conflict",
+    "provider_unavailable",
+]);
+const remediationAction = (error) => {
+    if (error instanceof PermissionRequiredError)
+        return error.elicitationSupported
+            ? "Approve the exact missing scope, then retry the operation."
+            : "Add the exact missing scope beneath the administrator ceiling, then retry.";
+    return userMessage(error);
+};
+const errorCategory = (error) => {
+    if (error instanceof PermissionRequiredError)
+        return "permission_required";
+    if (error._tag === "ProcessCaptureError")
+        return error.userCategory ?? "execution_failure";
+    if (error instanceof HopperRemoteError &&
+        error.diagnosticType === "authorization")
+        return "permission_required";
+    if (error instanceof ArtifactOperationError)
+        return artifactErrorCategory(error.reason);
+    if (error instanceof EvidenceFileError && error.reason === "disabled")
+        return "unavailable";
+    if (error instanceof InvestigationWorkspaceError)
+        return investigationWorkspaceCategory(error.reason);
+    return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
+};
+const investigationWorkspaceCategory = (reason) => {
+    if (reason === "disabled" ||
+        reason === "outside-root" ||
+        reason === "not-file")
+        return "unavailable";
+    if (reason === "too-large")
+        return "truncated";
+    if (reason === "invalid-json" || reason === "integrity")
+        return "integrity_mismatch";
+    return "execution_failure";
+};
+const artifactErrorCategory = (reason) => {
+    if (reason === "integrity")
+        return "integrity_mismatch";
+    if (reason === "limit")
+        return "truncated";
+    if (reason === "cancelled")
+        return "cancelled";
+    if (reason === "unavailable")
+        return "unavailable";
+    return "execution_failure";
+};
+const STATIC_ERROR_CATEGORIES = {
+    AnalysisInputError: "invalid_input",
+    AnalysisCapabilityUnavailableError: "unsupported_provider",
+    ProviderSelectionError: "unsupported_provider",
+    EvidenceIntegrityError: "integrity_mismatch",
+    EvidenceLimitError: "truncated",
+    AnalysisCancelledError: "cancelled",
+    HopperCancelledError: "cancelled",
+    AnalysisTimeoutError: "timeout",
+    HopperTimeoutError: "timeout",
+    NoBinaryOpenError: "unavailable",
+    BinaryTargetError: "unavailable",
+};
+const userMessage = (error) => {
+    if (error instanceof PermissionRequiredError)
+        return "This operation needs additional local permission. Review the requested scope and remediation.";
+    if (error instanceof AnalysisInputError)
+        return "Analysis input is invalid. Check the arguments and try again.";
+    if (error.userMessage !== undefined)
+        return error.userMessage;
+    if (UNREADABLE_OUTPUT_TAGS.has(error._tag))
+        return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+    if (UNSUPPORTED_PROVIDER_TAGS.has(error._tag))
+        return "This analysis is unavailable for the current target. Choose another analysis or target.";
+    if (CANCELLED_TAGS.has(error._tag))
+        return "Analysis was cancelled. Start it again when ready.";
+    if (TIMEOUT_TAGS.has(error._tag))
+        return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
+    if (ADAPTER_FAILURE_TAGS.has(error._tag))
+        return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+    if (START_FAILURE_TAGS.has(error._tag))
+        return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
+    if (error instanceof ArtifactOperationError)
+        return artifactMessage(error.reason);
+    if (error instanceof EvidenceIntegrityError)
+        return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
+    if (error instanceof EvidenceLimitError)
+        return "Evidence is too large for this session. Reduce the evidence set and try again.";
+    if (error instanceof EvidenceFileError)
+        return evidenceFileMessage(error.reason);
+    if (error instanceof InvestigationWorkspaceError)
+        return investigationWorkspaceMessage(error.reason);
+    if (error instanceof UnknownRegistryError)
+        return "Evidence state changed before the update completed. Refresh the current state and try again.";
+    if (error instanceof ConfigurationError)
+        return "REA configuration is invalid. Run `rea doctor` and fix the reported setting.";
+    if (error instanceof NoBinaryOpenError)
+        return error.message;
+    if (error instanceof BinaryTargetError)
+        return "REA could not open that app or binary. Check that the path exists, is readable, and points to a supported file.";
+    if (error._tag === "ProcessCaptureError")
+        return (error.userMessage ??
+            "Process capture could not complete. Run `rea doctor`, then review capture policy and try again.");
+    return "Analysis could not complete. Run `rea doctor`, then try again.";
+};
+const UNREADABLE_OUTPUT_TAGS = new Set([
+    "AnalysisProtocolError",
+    "AnalysisOutputError",
+    "HopperProtocolError",
+]);
+const UNSUPPORTED_PROVIDER_TAGS = new Set([
+    "AnalysisCapabilityUnavailableError",
+    "ProviderSelectionError",
+]);
+const CANCELLED_TAGS = new Set([
+    "AnalysisCancelledError",
+    "HopperCancelledError",
+]);
+const TIMEOUT_TAGS = new Set([
+    "AnalysisTimeoutError",
+    "HopperTimeoutError",
+]);
+const ADAPTER_FAILURE_TAGS = new Set([
+    "ProviderAdapterError",
+    "HopperRemoteError",
+]);
+const START_FAILURE_TAGS = new Set([
+    "HopperProcessError",
+    "HopperStartError",
+]);
+const artifactMessage = (reason) => {
+    if (reason === "cancelled")
+        return "Artifact operation was cancelled. Start it again when ready.";
+    if (reason === "limit")
+        return "Artifact is too large to process safely. Narrow the requested path or use a smaller artifact.";
+    if (reason === "path")
+        return "Artifact path is not allowed. Choose a path inside the artifact and try again.";
+    if (reason === "unavailable")
+        return "Artifact format is not available on this system. Choose another artifact or supported environment.";
+    if (reason === "format" || reason === "integrity")
+        return "Artifact is invalid or has changed. Get a fresh copy and try again.";
+    return "Artifact could not be read or written. Check file access and try again.";
+};
+const evidenceFileMessage = (reason) => {
+    if (reason === "disabled")
+        return "Evidence file access is disabled. Enable an evidence directory or use inline evidence.";
+    if (reason === "outside-root")
+        return "Evidence path is outside the allowed directory. Choose a path inside the configured evidence directory.";
+    if (reason === "not-file")
+        return "Evidence path does not point to a file. Choose an evidence file and try again.";
+    if (reason === "too-large")
+        return "Evidence file is too large. Reduce its size and try again.";
+    if (reason === "exists")
+        return "Evidence file already exists. Choose another path or allow overwrite.";
+    if (reason === "invalid-json")
+        return "Evidence file is not valid JSON. Repair or recreate the file and try again.";
+    return "Evidence file could not be accessed. Check file permissions and try again.";
+};
+const investigationWorkspaceMessage = (reason) => {
+    if (reason === "disabled")
+        return "Investigation workspace access is disabled. Configure a workspace directory and try again.";
+    if (reason === "outside-root")
+        return "Investigation workspace is outside the allowed directory. Choose a configured workspace directory and try again.";
+    if (reason === "not-file")
+        return "Investigation workspace path is not a file. Choose a workspace file and try again.";
+    if (reason === "too-large")
+        return "Investigation workspace is too large. Reduce its size and try again.";
+    if (reason === "invalid-json" || reason === "integrity")
+        return "Investigation workspace is invalid or has changed. Recreate or repair it, then try again.";
+    if (reason === "locked")
+        return "Another investigation update is in progress. Try again when it finishes.";
+    if (reason === "revision-conflict" || reason === "name-conflict")
+        return "Investigation workspace state changed. Refresh the current state and try again.";
+    return "Investigation workspace could not be accessed. Check file permissions and try again.";
 };
 const KNOWN_ERROR_TAGS = {
     AnalysisProtocolError: true,
@@ -292,6 +642,7 @@ const KNOWN_ERROR_TAGS = {
     EvidenceIntegrityError: true,
     EvidenceLimitError: true,
     EvidenceFileError: true,
+    InvestigationWorkspaceError: true,
     UnknownRegistryError: true,
     HopperTimeoutError: true,
     HopperCancelledError: true,
@@ -302,6 +653,7 @@ const KNOWN_ERROR_TAGS = {
     ConfigurationError: true,
     NoBinaryOpenError: true,
     BinaryTargetError: true,
+    PermissionRequiredError: true,
 };
 const assertKnownTag = (tag) => {
     if (KNOWN_ERROR_TAGS[tag] !== true)

package/dist/domain/evidence.js

@@ -3,7 +3,8 @@ import canonicalize from "canonicalize";
 import { z } from "zod";
 import { jsonValueSchema } from "./jsonValue.js";
 const digestSchema = z.string().regex(/^[a-f0-9]{64}$/u);
-const providerSchema = z.object({
+/** Provider identity schema shared by evidence-bearing persistence formats. */
+export const providerSchema = z.object({
     id: z.string().min(1),
     name: z.string().min(1),
     version: z.string().nullable(),
@@ -36,7 +37,8 @@ const subjectSchema = z.object({
     local_path: z.string(),
 });
 /** Source location attached to an evidence observation. */
-const evidenceLocationSchema = z.discriminatedUnion("kind", [
+/** Source-location schema shared by evidence-bearing persistence formats. */
+export const evidenceLocationSchema = z.discriminatedUnion("kind", [
     z.object({ kind: z.literal("address"), address: z.string().min(1) }),
     z.object({
         kind: z.literal("address-range"),

package/dist/domain/evidenceBundle.js

@@ -66,6 +66,34 @@ export const createEvidenceBundle = (records, unknowns = []) => {
         records: sortedRecords,
     };
 };
+/** Restrict a bundle to records and complete unknown histories for one artifact. */
+export const evidenceBundleForTarget = (bundle, sha256) => {
+    const recordsById = new Map(bundle.records.map((record) => [record.evidence_id, record]));
+    let unknowns = bundle.unknowns.filter(({ scope_digest: scopeDigest }) => scopeDigest === sha256);
+    let changed = true;
+    while (changed) {
+        const ids = new Set(unknowns.map(({ unknown_id: id }) => id));
+        const retained = unknowns.filter((unknown) => unknown.relationships.every(({ unknown_id: id }) => ids.has(id)) &&
+            referencedEvidenceIds(unknown).every((id) => {
+                const record = recordsById.get(id);
+                return (record?.subject?.digest.sha256 === sha256 ||
+                    (unknown.mutation_evidence_ids.includes(id) &&
+                        record?.subject === null &&
+                        record.predicate_type === "rea.residual-unknown-mutation/v1"));
+            }));
+        changed = retained.length !== unknowns.length;
+        unknowns = retained;
+    }
+    const mutationIds = new Set(unknowns.flatMap(({ mutation_evidence_ids: ids }) => ids));
+    return createEvidenceBundle(bundle.records.filter((record) => record.subject?.digest.sha256 === sha256 ||
+        mutationIds.has(record.evidence_id)), unknowns);
+};
+const referencedEvidenceIds = (unknown) => [
+    ...unknown.supporting_evidence_ids,
+    ...unknown.contradicting_evidence_ids,
+    ...unknown.mutation_evidence_ids,
+    ...(unknown.resolution?.evidence_ids ?? []),
+];
 /** Parse records, verify semantic IDs, and reject inconsistent manifests. */
 export const parseEvidenceBundle = (input) => {
     const parsed = evidenceBundleSchema.parse(input);

package/dist/domain/hopperStartupFailure.js

@@ -0,0 +1,55 @@
+const failures = [
+    [
+        70,
+        "private_display_unavailable",
+        "REA could not start its private Linux display. Install Xvfb, then rerun rea doctor.",
+    ],
+    [
+        71,
+        "x11_authorization_failed",
+        "REA could not authorize its private Linux display. Install xauth, then rerun rea doctor.",
+    ],
+    [
+        72,
+        "unsupported_hopper_build",
+        "This Hopper build is not supported for unattended Linux analysis. Unset HOPPER_LAUNCHER_PATH and rerun rea setup --yes --install-hopper, or update REA.",
+    ],
+    [
+        73,
+        "invalid_launch_command",
+        "REA refused an unexpected Hopper launch command. Check HOPPER_LAUNCHER_PATH and rerun rea doctor.",
+    ],
+    [
+        74,
+        "process_ownership_mismatch",
+        "REA could not verify ownership of the launched Hopper process and stopped safely. Close other Hopper sessions and retry.",
+    ],
+    [
+        75,
+        "hopper_exited_during_startup",
+        "Hopper exited before the REA bridge was ready. Run rea doctor and retry the analysis.",
+    ],
+    [
+        76,
+        "unsupported_demo_dialog",
+        "This Hopper demo dialog is not supported for unattended Linux analysis. Update REA or use a supported Hopper build.",
+    ],
+    [
+        77,
+        "unexpected_display_geometry",
+        "REA's private Linux display did not match the validated layout. Close custom display overrides and retry.",
+    ],
+    [
+        78,
+        "x11_input_failed",
+        "REA could not activate Hopper's validated demo control. Install the XTEST runtime, then rerun rea doctor.",
+    ],
+    [
+        79,
+        "runtime_dependency_unavailable",
+        "A Linux demo-session dependency is unavailable. Rerun rea setup --yes --install-hopper, then rea doctor.",
+    ],
+];
+const HOPPER_STARTUP_FAILURES = new Map(failures.map(([exitCode, code, message]) => [exitCode, { code, message }]));
+/** Return the stable public failure associated with a Linux demo adapter exit. */
+export const hopperStartupFailure = (exitCode) => exitCode === null ? undefined : HOPPER_STARTUP_FAILURES.get(exitCode);