rea-agents 6.0.0 → 6.2.0

package/dist/contracts/webScriptToolContracts.js

@@ -1,7 +1,7 @@
 import { exportWebScriptsInputSchema, webScriptExportResultSchema, } from "../domain/webScriptExport.js";
 import { webModuleTraceInputSchema, webModuleTraceResultSchema, } from "../domain/webModuleTrace.js";
 import { toolContractMetadata } from "./toolEffects.js";
-import { evidenceResultOf } from "./toolOutputSchemas.js";
+import { evidenceResultOf } from "./toolOutputSchemaPrimitives.js";
 import { webSourceLocationInputSchema, webSourceLocationResultSchema, } from "../domain/webSourceLocation.js";
 /** Local captured-script publication contracts shared by CLI and MCP. */
 export const WEB_SCRIPT_TOOL_CONTRACTS = [

package/dist/doctorRuntime.js

@@ -4,17 +4,19 @@ import { inspectSystemGhidraProvider } from "./ghidra/GhidraDoctor.js";
 import { inspectIdaRegistration } from "./ida/IdaDoctor.js";
 import { selectLinuxPrivateDisplayStrategy } from "./hopper/LinuxPrivateDisplayProbe.js";
 /** Compose provider diagnostics at the outer CLI adapter boundary. */
-export const createSystemDoctorHost = () => systemDoctorHost({
+export const createSystemDoctorHost = (environment = process.env) => systemDoctorHost({
+    environment,
     providerInspections: async () => [
-        await inspectSystemGhidraProvider(),
-        inspectIdaRegistration(process.env.REA_IDA_MCP_CONFIG),
+        await inspectSystemGhidraProvider(environment),
+        inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),
     ],
-    linuxDemoRuntimeCheck: inspectLinuxPrivateDisplay,
+    linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),
 });
 const HOPPER_DEMO_HELPER_PATH = fileURLToPath(new URL("../scripts/hopper-demo-x11.py", import.meta.url));
-const inspectLinuxPrivateDisplay = async () => {
+const inspectLinuxPrivateDisplay = async (environment) => {
     const selection = await selectLinuxPrivateDisplayStrategy({
         helperPath: HOPPER_DEMO_HELPER_PATH,
+        environment,
     });
     const value = selection.diagnostic;
     const detail = [

package/dist/domain/analysisErrorBase.js

@@ -31,18 +31,23 @@ const ANALYSIS_ERROR_TAGS = [
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
     capturedOutput;
+    cleanup;
+    cleanupIncomplete;
+    cleanupResources;
     constructor(message, options) {
         super(message, options);
         this.capturedOutput =
             options?.capturedOutput === undefined
                 ? undefined
                 : { ...options.capturedOutput };
+        this.cleanup = options?.cleanup;
+        this.cleanupIncomplete = options?.cleanup !== undefined;
+        this.cleanupResources = options?.cleanup?.resources ?? [];
+        this.partialObservation = options?.partialObservation;
     }
     userMessage = undefined;
     userCategory = undefined;
-    cleanupIncomplete = false;
-    cleanupResources = [];
     executionFailure = undefined;
-    partialObservation = undefined;
+    partialObservation;
     cleanupReport = undefined;
 }

package/dist/domain/analysisErrorCore.js

@@ -5,26 +5,31 @@ export class AnalysisUnsupportedTargetError extends AnalysisError {
     path;
     reason;
     _tag = "AnalysisUnsupportedTargetError";
+    /** Refusal-specific recovery, when the producer knows an available workflow. */
+    remediationAction;
     constructor(operation, path, reason, options) {
         super(`Unsupported target for ${operation} at ${path}: ${reason}`, options);
         this.operation = operation;
         this.path = path;
         this.reason = reason;
+        this.remediationAction = options?.remediationAction;
     }
 }
-/** Provider reported a resource failure, distinct from malformed input or unsupported coverage. */
+/** An analysis or transport resource failure, distinct from malformed input or unsupported coverage. */
 export class AnalysisResourceConstraintError extends AnalysisError {
     operation;
     resource;
     reason;
     reportedLimits;
     _tag = "AnalysisResourceConstraintError";
+    remediationAction;
     constructor(operation, resource, reason, reportedLimits, options) {
         super(`Resource constraint during ${operation}: ${reason}`, options);
         this.operation = operation;
         this.resource = resource;
         this.reason = reason;
         this.reportedLimits = reportedLimits;
+        this.remediationAction = options?.remediationAction;
     }
 }
 /** Provider-neutral invalid analysis input or output at an application boundary. */

package/dist/domain/analysisErrorPresentation.js

@@ -2,42 +2,56 @@ import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputE
 import { ArtifactOperationError } from "./artifactOperationError.js";
 import { BinaryTargetError, ConfigurationError, NoBinaryOpenError, } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
-import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, } from "./evidenceErrors.js";
+import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, AnalysisSnapshotMismatchError, } from "./evidenceErrors.js";
 import { HopperRemoteError, HopperProcessError, HopperStartError, HopperTimeoutError, } from "./hopperErrors.js";
 import { ProviderSelectionError } from "./providerSelectionError.js";
 import { UnknownRegistryError } from "./unknownRegistryError.js";
+import { providerRetryAction } from "./providerOperationHealth.js";
 import {} from "./analysisErrorBase.js";
 import {} from "./analysisErrorProjection.js";
 export const analysisErrorRemediationAction = (error) => {
+    if (error instanceof AnalysisSnapshotMismatchError)
+        return "Run analysis without this snapshot, then save a fresh snapshot using the intended artifact, provider, and analysis profile.";
     if (error instanceof AnalysisUnsupportedTargetError)
-        return "Select a target supported by this operation or choose an operation supporting the reported target format.";
+        return (error.remediationAction ??
+            "Select a target supported by this operation or choose an operation supporting the reported target format.");
     if (error instanceof AnalysisResourceConstraintError)
-        return error.resource === "cpu"
-            ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
-            : error.resource === "file-size"
-                ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
-                : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits.";
+        return (error.remediationAction ??
+            (error.resource === "transport"
+                ? "Export retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. Tools that accept retained-evidence references can inspect compatible records. The connection remains usable."
+                : error.resource === "cpu"
+                    ? "Review the reported worker CPU limits and observed signal. Retry with sufficient CPU time or a smaller artifact; REA retains tighter inherited limits."
+                    : error.resource === "file-size"
+                        ? "Review the reported worker file-size limits and write failure. Retry with a sufficient file-size allowance for the evidence reply; REA retains tighter inherited limits."
+                        : "Review the reported worker memory limits and available host memory. Retry with sufficient memory or a smaller artifact; REA retains tighter inherited limits."));
     if (error instanceof HopperTimeoutError)
-        return error.providerState === "busy"
-            ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
-            : "Check binary_session for Hopper health, then retry the operation.";
+        return error.operation === undefined
+            ? "Inspect Hopper for a loader or license dialog and review details.launcher. Correct the loader configuration or complete Hopper setup, then open the target again."
+            : error.providerState === "busy"
+                ? "Check binary_session.analysis_activity, wait for the active Hopper request to finish, then retry."
+                : "Check binary_session for Hopper health, then retry the operation.";
     if (error instanceof HopperProcessError)
-        return "Check binary_session provider health. Restart the owned Hopper process only when it has stopped.";
+        return hopperProcessRemediation(error);
     if (error instanceof HopperStartError)
         return error.ownerRunId === undefined
             ? "Check the Hopper launcher and target details, then retry opening the target."
             : `Use the active REA session ${error.ownerRunId} or close it before opening this target again.`;
     if (error instanceof HopperRemoteError)
-        return "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
+        return error.diagnosticType === "invalid_request"
+            ? "Correct the reported address, document, or arguments and retry."
+            : "Review the Hopper diagnostic details; correct the request or retry if the failure was transient.";
     if (error instanceof EvidenceReferenceError)
         return "Use an exact Evidence reference retained by this session, supply the complete inline Evidence, re-run its producer, or import its Evidence bundle. close_binary clears retained records.";
     if (error instanceof BinaryTargetError &&
         error.constraint === "directory_requires_file")
         return "For a JavaScript/Electron application directory, call analyze_javascript_application with input_path or run `rea analyze <directory>`. For binary analysis, select its executable file.";
-    if (error instanceof AnalysisAccessDeniedError)
+    if (error instanceof AnalysisAccessDeniedError ||
+        (error instanceof BinaryTargetError && error.systemCode !== undefined))
         return "Check the current process's read access to the selected path. Retry with a readable local file.";
     if (error instanceof AnalysisArtifactChangedError)
-        return "Wait until the selected file is stable, then retry this operation.";
+        return "Wait until the selected file is stable. For an active binary session, reopen the target with open_binary before retrying so REA acquires its current identity; for a CLI command or target-free tool, rerun the operation.";
+    if (error instanceof ConfigurationError && error.settings.length > 0)
+        return `Correct ${[...new Set(error.settings.map(({ setting }) => setting))].join(", ")} in the environment that starts REA (your shell or the MCP client's registration), then rerun.`;
     if (error instanceof AnalysisInputError)
         return "Correct the listed arguments and retry.";
     if (error instanceof UnknownRegistryError && error.reason === "not-found")
@@ -51,7 +65,10 @@ export const analysisErrorCategory = (error) => {
     if (error._tag === "ProcessCaptureError")
         return error.userCategory ?? "execution_failure";
     if (error instanceof BrowserObservationError)
-        return browserErrorCategory(error.reason);
+        return error.userCategory ?? browserErrorCategory(error.reason);
+    if (error instanceof HopperRemoteError &&
+        error.diagnosticType === "invalid_request")
+        return "invalid_input";
     if (error instanceof HopperRemoteError &&
         error.diagnosticType === "authorization")
         return "unavailable";
@@ -59,9 +76,18 @@ export const analysisErrorCategory = (error) => {
         return "unavailable";
     if (error instanceof ArtifactOperationError)
         return artifactErrorCategory(error.reason);
+    if (error instanceof EvidenceFileError &&
+        (error.reason === "missing" ||
+            error.reason === "not-file" ||
+            error.reason === "exists"))
+        return "invalid_input";
     return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
 };
 const browserErrorCategory = (reason) => {
+    if (reason === "cancelled")
+        return "cancelled";
+    if (reason === "timeout")
+        return "timeout";
     if (reason === "payload_limit")
         return "truncated";
     if (reason === "target_not_found" ||
@@ -100,6 +126,8 @@ const STATIC_ERROR_CATEGORIES = {
     BinaryTargetError: "unavailable",
 };
 export const analysisErrorUserMessage = (error) => {
+    if (error instanceof AnalysisSnapshotMismatchError)
+        return error.message;
     if (error instanceof AnalysisUnsupportedTargetError)
         return error.message;
     if (error instanceof AnalysisResourceConstraintError)
@@ -127,13 +155,19 @@ export const analysisErrorUserMessage = (error) => {
     if (error instanceof EvidenceIntegrityError)
         return "Evidence is invalid or has changed. Recreate or re-import it, then try again.";
     if (error instanceof EvidenceFileError)
-        return evidenceFileMessage(error.reason);
+        return evidenceFileMessage(error);
     if (error instanceof UnknownRegistryError && error.reason === "not-found")
         return "The requested residual unknown does not exist in this session. Check the unknown_id and try again.";
     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.";
+        return error.settings.length === 0
+            ? "REA configuration is invalid. Run `rea doctor` and fix the reported setting."
+            : `REA configuration is invalid: ${error.settings
+                .map(({ setting, constraint }) => constraint.includes(setting)
+                ? constraint.replace(/\.$/u, "")
+                : `${setting}: ${constraint}`)
+                .join("; ")}.`;
     if (error instanceof NoBinaryOpenError)
         return error.message;
     if (error instanceof BinaryTargetError)
@@ -147,13 +181,15 @@ export const analysisErrorUserMessage = (error) => {
 };
 const hopperErrorUserMessage = (error) => {
     if (error instanceof HopperTimeoutError) {
-        const request = error.operation ?? "startup";
+        if (error.operation === undefined)
+            return "REA timed out waiting for Hopper bridge readiness. Hopper may be waiting for a loader or license dialog; inspect its window and the captured launcher outcome before retrying.";
+        const request = error.operation;
         return error.providerState === "busy"
             ? `Hopper timed out during ${request} while the provider remained busy. Check binary_session.analysis_activity, wait for the active request to finish, then retry.`
             : `Hopper timed out during ${request} before it started. Check binary_session for provider health, then retry.`;
     }
     if (error instanceof HopperProcessError)
-        return `Hopper stopped during ${error.operation ?? "connection"}${error.exitCode === null ? "; its exit was not observed" : ` with exit code ${String(error.exitCode)}`}.${error.userMessage === undefined ? "" : ` ${error.userMessage}`} Check binary_session provider health before retrying.`;
+        return hopperProcessMessage(error);
     if (error instanceof HopperStartError)
         return (error.userMessage ??
             "Hopper could not start. Check the launcher and target details, then retry opening the target.");
@@ -161,6 +197,36 @@ const hopperErrorUserMessage = (error) => {
         return `Hopper ${error.operation ?? "analysis"} failed (${String(error.code)}, ${error.diagnosticType}): ${error.safeMessage}`;
     return undefined;
 };
+const RESTART_OWNED_PROVIDER = "Restart the owned provider by calling close_binary, then open the target again and retry.";
+const hopperProcessRemediation = (error) => {
+    if (error.failureCode !== undefined && error.userMessage !== undefined)
+        return error.userMessage;
+    if (error.stage === "launch")
+        return "Review the captured launcher diagnostics and Hopper setup, then retry opening the target.";
+    if (providerRetryAction(error.providerState) === "restart_provider")
+        return RESTART_OWNED_PROVIDER;
+    return "Read binary_session.provider_operation_health for this request before retrying or restarting the owned provider.";
+};
+const hopperProcessMessage = (error) => {
+    const stage = error.stage;
+    const where = error.operation ?? stage;
+    const request = error.requestId === undefined
+        ? ""
+        : ` Request id ${String(error.requestId)}.`;
+    const startup = error.userMessage === undefined ? "" : ` ${error.userMessage}`;
+    if (error.providerState === "exited") {
+        const exit = error.exitCode === null
+            ? "no exit code was observed"
+            : `exit code ${String(error.exitCode)}`;
+        const recovery = error.failureCode === undefined && stage !== "launch"
+            ? ` ${RESTART_OWNED_PROVIDER}`
+            : "";
+        return `Hopper exited during ${where} (${exit}).${startup}${recovery}${request}`;
+    }
+    if (error.providerState === "unreachable")
+        return `Hopper became unreachable during ${where}; its process exit was not observed. ${RESTART_OWNED_PROVIDER}${startup}${request}`;
+    return `Hopper failed during ${where} and REA could not determine whether the provider is busy, exited, or unreachable.${startup} Read binary_session.provider_operation_health for this request before retrying or restarting.${request}`;
+};
 const standardErrorMessage = (tag) => {
     if (UNREADABLE_OUTPUT_TAGS.has(tag))
         return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
@@ -214,7 +280,11 @@ const artifactMessage = (reason) => {
         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) => {
+const evidenceFileMessage = ({ operation, reason, }) => {
+    if (reason === "missing")
+        return operation === "read"
+            ? "Evidence file does not exist at the selected path. Check the path and try again."
+            : "Evidence output directory does not exist. Choose an existing directory and try again.";
     if (reason === "not-file")
         return "Evidence path does not point to a regular file. Choose a file and try again.";
     if (reason === "exists")

package/dist/domain/analysisErrorProjection.js

@@ -2,22 +2,42 @@ import { jsonValueSchema } from "./jsonValue.js";
 import { analysisErrorCategory, analysisErrorRemediationAction, analysisErrorUserMessage, assertKnownAnalysisErrorTag, } from "./analysisErrorPresentation.js";
 import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisUnsupportedTargetError, AnalysisInputError, AnalysisOutputError, AnalysisTimeoutError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
-import { BinaryTargetError } from "./configurationErrors.js";
+import { BinaryTargetError, ConfigurationError, } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
-import { EvidenceFileError, EvidenceReferenceError } from "./evidenceErrors.js";
-import { HopperCancelledError, HopperProcessError, HopperRemoteError, HopperTimeoutError, } from "./hopperErrors.js";
+import { EvidenceFileError, EvidenceIntegrityError, EvidenceReferenceError, } from "./evidenceErrors.js";
+import { HopperCancelledError, HopperProcessError, HopperRemoteError, HopperStartError, HopperTimeoutError, } from "./hopperErrors.js";
 import { ProviderAdapterError } from "./providerAdapterError.js";
 import { ProviderSelectionError } from "./providerSelectionError.js";
 import { UnknownRegistryError } from "./unknownRegistryError.js";
+import { providerRetryAction } from "./providerOperationHealth.js";
 import {} from "./analysisErrorBase.js";
 /** Project expected failures into exhaustive, secret-safe caller fields. */
 export const projectAnalysisError = (error) => {
     assertKnownAnalysisErrorTag(error._tag);
-    const code = errorCode(error);
+    const underlyingCode = underlyingErrorCode(error);
+    const code = error.cleanupIncomplete ? "cleanup_incomplete" : underlyingCode;
     const primaryDetails = errorDetails(error);
-    const details = error.capturedOutput === undefined
-        ? primaryDetails
-        : { ...primaryDetails, captured_output: { ...error.capturedOutput } };
+    const details = {
+        ...primaryDetails,
+        ...(error.cleanupIncomplete
+            ? {
+                cleanup: "incomplete",
+                resources: [...error.cleanupResources],
+                ...(error.cleanup === undefined
+                    ? {}
+                    : { cleanup_reason: error.cleanup.reason }),
+                execution_failure: primaryDetails?.execution_failure ?? underlyingCode,
+            }
+            : {}),
+        ...(error.capturedOutput === undefined
+            ? {}
+            : { captured_output: { ...error.capturedOutput } }),
+        ...(error.partialObservation === undefined
+            ? {}
+            : {
+                partial_observation: jsonValueSchema.parse(error.partialObservation),
+            }),
+    };
     return {
         code,
         category: analysisErrorCategory(error),
@@ -26,20 +46,27 @@ export const projectAnalysisError = (error) => {
         remediation: {
             action: analysisErrorRemediationAction(error),
         },
-        ...(details === undefined ? {} : { details }),
+        ...(Object.keys(details).length === 0 ? {} : { details }),
     };
 };
-const errorCode = (error) => {
-    if (error.cleanupIncomplete)
-        return "cleanup_incomplete";
+const underlyingErrorCode = (error) => {
+    if (error instanceof HopperRemoteError &&
+        error.diagnosticType === "invalid_request")
+        return "invalid_request";
     if (error instanceof ProviderSelectionError)
         return error.reason === "provider_unavailable"
             ? "provider_unavailable"
             : "capability_unavailable";
     if (error instanceof BrowserObservationError)
-        return browserErrorCode(error.reason);
+        return error.userCategory === "cancelled"
+            ? "cancelled"
+            : browserErrorCode(error.reason);
     if (error instanceof ArtifactOperationError)
         return artifactOperationCode(error);
+    if (error instanceof BinaryTargetError)
+        return error.systemCode === undefined
+            ? "target_unavailable"
+            : "access_denied";
     if (error instanceof EvidenceFileError)
         return evidenceFileCode(error.reason);
     if (error instanceof UnknownRegistryError)
@@ -49,6 +76,10 @@ const errorCode = (error) => {
     return staticErrorCode(error._tag);
 };
 const browserErrorCode = (reason) => {
+    if (reason === "cancelled")
+        return "cancelled";
+    if (reason === "timeout")
+        return "provider_timeout";
     if (reason === "payload_limit")
         return "truncated";
     if (reason === "target_not_found" ||
@@ -68,9 +99,14 @@ const artifactOperationCode = (error) => {
         return "cancelled";
     return "artifact_operation_failed";
 };
-const evidenceFileCode = (reason) => reason === "invalid-json"
-    ? "evidence_integrity_mismatch"
-    : "execution_failure";
+const evidenceFileCode = (reason) => {
+    if (reason === "invalid-json")
+        return "evidence_integrity_mismatch";
+    // A missing, non-file or already-existing path is the caller's selection.
+    if (reason === "io")
+        return "execution_failure";
+    return "invalid_request";
+};
 const unknownRegistryCode = (reason) => {
     if (reason === "revision-conflict" || reason === "already-exists")
         return "revision_conflict";
@@ -105,7 +141,6 @@ const STATIC_ERROR_CODES = {
     HopperStartError: "provider_unavailable",
     ConfigurationError: "configuration_invalid",
     NoBinaryOpenError: "target_unavailable",
-    BinaryTargetError: "target_unavailable",
     EvidenceIntegrityError: "evidence_integrity_mismatch",
     ProviderAdapterError: "execution_failure",
     HopperRemoteError: "execution_failure",
@@ -113,6 +148,7 @@ const STATIC_ERROR_CODES = {
 const staticErrorCode = (tag) => {
     switch (tag) {
         case "ArtifactOperationError":
+        case "BinaryTargetError":
         case "BrowserObservationError":
         case "EvidenceFileError":
         case "ProcessCaptureError":
@@ -176,6 +212,8 @@ const requestErrorDetails = (error) => {
             expected: error.expected,
             actual: error.actual,
         };
+    if (error instanceof EvidenceIntegrityError)
+        return { reason: error.message };
     return undefined;
 };
 const artifactStateErrorDetails = (error) => {
@@ -196,7 +234,11 @@ const artifactStateErrorDetails = (error) => {
     if (error instanceof UnknownRegistryError)
         return { reason: error.reason };
     if (error instanceof EvidenceFileError)
-        return { operation: error.operation, reason: error.reason };
+        return {
+            operation: error.operation,
+            reason: error.reason,
+            ...(error.path === undefined ? {} : { path: error.path }),
+        };
     return undefined;
 };
 const providerErrorDetails = (error) => {
@@ -257,10 +299,13 @@ const providerErrorDetails = (error) => {
             ...(error.operation === undefined ? {} : { operation: error.operation }),
             ...(error.requestId === undefined ? {} : { request_id: error.requestId }),
         };
-    if (error instanceof HopperProcessError)
+    if (error instanceof HopperProcessError) {
+        const stage = error.stage;
         return {
             exit_code: error.exitCode,
-            stage: error.operation === undefined ? "connection" : "analysis",
+            stage,
+            provider_state: error.providerState,
+            retry_action: providerRetryAction(error.providerState, error.failureCode !== undefined || error.stage === "launch"),
             ...(error.failureCode === undefined
                 ? {}
                 : { failure_code: error.failureCode }),
@@ -269,6 +314,22 @@ const providerErrorDetails = (error) => {
             ...(error.diagnostic === undefined
                 ? {}
                 : { diagnostics: { ...error.diagnostic } }),
+            ...(error.launcherFailure === undefined
+                ? {}
+                : { launcher: error.launcherFailure }),
+        };
+    }
+    if (error instanceof HopperStartError)
+        return {
+            stage: "launch",
+            provider_state: "unknown",
+            retry_action: error.ownerRunId === undefined ? "retry" : "unknown",
+            ...(error.ownerRunId === undefined
+                ? {}
+                : { owner_run_id: error.ownerRunId }),
+            ...(error.launcherFailure === undefined
+                ? {}
+                : { launcher: error.launcherFailure }),
         };
     return undefined;
 };
@@ -290,16 +351,40 @@ const primaryBrowserFailureReason = (error) => {
 };
 const lifecycleErrorDetails = (error) => {
     if (error instanceof AnalysisCancelledError)
-        return { operation: error.operation, cleanup: "complete" };
+        return {
+            operation: error.operation,
+            cleanup: error.cleanup === undefined ? "complete" : "incomplete",
+            ...(error.cleanup === undefined
+                ? {}
+                : {
+                    cleanup_reason: error.cleanup.reason,
+                    resources: [...error.cleanup.resources],
+                    execution_failure: "cancelled",
+                }),
+        };
     if (error instanceof HopperCancelledError)
         return { operation: "hopper", cleanup: "complete" };
     if (error instanceof AnalysisTimeoutError)
-        return { operation: error.operation, timeout_ms: error.timeoutMs };
+        return {
+            operation: error.operation,
+            timeout_ms: error.timeoutMs,
+            ...(error.cleanup === undefined
+                ? {}
+                : {
+                    cleanup: "incomplete",
+                    cleanup_reason: error.cleanup.reason,
+                    resources: [...error.cleanup.resources],
+                }),
+        };
     if (error instanceof HopperTimeoutError)
         return {
-            stage: error.operation === undefined ? "startup" : "analysis",
+            stage: error.operation === undefined ? "startup" : error.stage,
             timeout_ms: error.timeoutMs,
+            ...(error.launcherOutcome === undefined
+                ? {}
+                : { launcher: error.launcherOutcome }),
             provider_state: error.providerState,
+            retry_action: error.providerState === "busy" ? "wait" : "retry",
             ...(error.operation === undefined ? {} : { operation: error.operation }),
             ...(error.requestId === undefined ? {} : { request_id: error.requestId }),
         };
@@ -313,18 +398,28 @@ const lifecycleErrorDetails = (error) => {
             ...(error.executionFailure === undefined
                 ? {}
                 : { execution_failure: error.executionFailure }),
-            ...(error.partialObservation === undefined
+        };
+    if (error._tag === "ProcessCaptureError") {
+        const details = {
+            ...(error.userCategory === "cancelled"
+                ? { operation: "process_capture", cleanup: "complete" }
+                : {}),
+            ...(error.cleanupReport === undefined
                 ? {}
-                : {
-                    partial_observation: jsonValueSchema.parse(error.partialObservation),
-                }),
+                : { cleanup_report: jsonValueSchema.parse(error.cleanupReport) }),
+            ...(error.executionFailure === undefined
+                ? {}
+                : { execution_failure: error.executionFailure }),
+        };
+        return Object.keys(details).length === 0 ? undefined : details;
+    }
+    if (error instanceof ConfigurationError && error.settings.length > 0)
+        return {
+            settings: error.settings.map(({ setting, constraint }) => ({
+                setting,
+                constraint,
+            })),
         };
-    if (error._tag === "ProcessCaptureError" &&
-        error.userCategory === "cancelled")
-        return { operation: "process_capture", cleanup: "complete" };
-    if (error._tag === "ProcessCaptureError" &&
-        error.executionFailure !== undefined)
-        return { execution_failure: error.executionFailure };
     if (error instanceof BinaryTargetError)
         return {
             path: error.path,
@@ -332,6 +427,9 @@ const lifecycleErrorDetails = (error) => {
             ...(error.constraint === undefined
                 ? {}
                 : { constraint: error.constraint }),
+            ...(error.systemCode === undefined
+                ? {}
+                : { system_code: error.systemCode, boundary: "filesystem-read" }),
         };
     return undefined;
 };