rea-agents 6.4.0 → 6.5.0

package/dist/cutter/CutterBridgeService.js

@@ -0,0 +1,139 @@
+import { jsonValueSchema } from "../domain/jsonValue.js";
+import { AnalysisCancelledError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, } from "../domain/analysisErrorCore.js";
+import { AnalysisError } from "../domain/analysisErrorBase.js";
+import { createEvidence } from "../domain/evidence.js";
+import { err, ok } from "../domain/result.js";
+import { cutterCommandInputSchema } from "../contracts/cutterToolContracts.js";
+import { CutterBridgeClient, } from "./CutterBridgeClient.js";
+import { CUTTER_PROVIDER_IDENTITY } from "./CutterBridgeClient.js";
+/** Shared Cutter bridge workflows used by the MCP adapter and CLI. */
+export class CutterBridgeService {
+    client;
+    #cleanupAttempt;
+    #pendingCleanup = new Map();
+    constructor(client = new CutterBridgeClient()) {
+        this.client = client;
+    }
+    /** Release timed-out work only after producer-owned terminal proof. */
+    retryCleanup() {
+        if (this.#cleanupAttempt !== undefined)
+            return this.#cleanupAttempt;
+        const attempt = this.#retryPendingCleanup().finally(() => {
+            if (this.#cleanupAttempt === attempt)
+                this.#cleanupAttempt = undefined;
+        });
+        this.#cleanupAttempt = attempt;
+        return attempt;
+    }
+    async #retryPendingCleanup() {
+        for (const [requestId, pending] of this.#pendingCleanup) {
+            const confirmCommandCompletion = this.client.confirmCommandCompletion;
+            if (confirmCommandCompletion === undefined)
+                return err(pending.failure);
+            const receipt = await confirmCommandCompletion.call(this.client, pending.sessionId, requestId, pending.completionToken);
+            if (!receipt.ok || !receipt.value)
+                return err(pending.failure);
+            const { failure } = pending;
+            failure.resolveCleanup();
+            this.#pendingCleanup.delete(requestId);
+        }
+        return ok(null);
+    }
+    listSessions() {
+        return this.client.listSessions();
+    }
+    async execute(rawInput, options = {}) {
+        const parsed = cutterCommandInputSchema.safeParse(rawInput);
+        if (!parsed.success)
+            return err(new AnalysisInputError("cutter_command"));
+        if (options.signal?.aborted)
+            return err(new AnalysisCancelledError("cutter_command"));
+        const input = parsed.data;
+        const cleanup = await this.retryCleanup();
+        if (!cleanup.ok)
+            return err(cleanup.error);
+        try {
+            const output = await this.client.execute({
+                sessionId: input.session_id,
+                expectedGeneration: input.expected_generation,
+                command: input.command,
+                json: input.json,
+                ...(options.signal === undefined ? {} : { signal: options.signal }),
+            });
+            const normalizedOutput = jsonValueSchema.parse(output.output);
+            const evidence = createEvidence(undefined, {
+                ...CUTTER_PROVIDER_IDENTITY,
+                version: output.cutterVersion,
+            }, {
+                predicateType: "rea.cutter.command-observation",
+                operation: "cutter_command",
+                parameters: {
+                    session_id: input.session_id,
+                    expected_generation: input.expected_generation,
+                    command: input.command,
+                    json: input.json,
+                },
+                result: {
+                    command: input.command,
+                    output: normalizedOutput,
+                    execution_state: output.executionState,
+                    error: output.error,
+                    message: output.message,
+                    output_truncated: output.outputTruncated,
+                    cutter_version: output.cutterVersion,
+                    current_file: output.currentFile,
+                    document_generation: output.documentGeneration,
+                    identity_status: output.identityStatus,
+                },
+                rawResult: normalizedOutput,
+                subjectUnavailableReason: "Cutter exposes no verified stable identity for the active unsaved document or tab.",
+                limitations: [
+                    "Document identity is partial: the bridge uses a plugin instance UUID and observed generation; a same-path tab switch or reload may not be distinguishable.",
+                    "Cutter command effects depend on the Rizin command and active plugins.",
+                    "The local IPC protocol is implemented by REA and is not an upstream Cutter API.",
+                    ...(output.executionState === "unknown"
+                        ? [
+                            "Command completion or its output could not be confirmed; do not retry automatically because the command may have produced partial or persistent effects.",
+                        ]
+                        : []),
+                    ...(output.outputTruncated
+                        ? [
+                            "The command completed or may have completed, but output exceeded the bridge transport limit and was omitted.",
+                        ]
+                        : []),
+                ],
+            });
+            if (output.executionState === "unknown") {
+                const failure = new AnalysisOutputError("cutter_command", "Cutter command completion is unknown; the bound binary remains unavailable until the UI dispatcher confirms this request reached a terminal state.", {
+                    cleanup: {
+                        reason: "The exact UI dispatcher completion receipt has not arrived; the dispatched command may still be running.",
+                        resources: [`cutter-session:${input.session_id}`],
+                    },
+                    partialObservation: evidence,
+                });
+                this.#pendingCleanup.set(output.requestId, {
+                    sessionId: input.session_id,
+                    ...(output.completionToken === undefined
+                        ? {}
+                        : { completionToken: output.completionToken }),
+                    failure,
+                });
+                return err(failure);
+            }
+            return ok(evidence);
+        }
+        catch (cause) {
+            if (cause instanceof AnalysisError)
+                return err(cause);
+            const message = cause instanceof Error
+                ? cause.message
+                : "Unknown Cutter bridge failure";
+            if (options.signal?.aborted && !message.includes("may have completed"))
+                return err(new AnalysisCancelledError("cutter_command", { cause }));
+            return err(message.includes("generation changed") ||
+                message.includes("unavailable or stale")
+                ? new AnalysisInputError("cutter_command", { cause })
+                : new AnalysisCapabilityUnavailableError("cutter", "cutter_command", message, { cause }));
+        }
+    }
+}

package/dist/doctorRuntime.js

@@ -1,17 +1,29 @@
 import { systemDoctorHost, } from "./application/Doctor.js";
 import { fileURLToPath } from "node:url";
+import { inspectJadxProvider } from "./android/JadxDoctor.js";
 import { inspectSystemGhidraProvider } from "./ghidra/GhidraDoctor.js";
 import { inspectIdaRegistration } from "./ida/IdaDoctor.js";
+import { parseJebMcpEndpoint } from "./jeb/JebMcpEndpoint.js";
 import { selectLinuxPrivateDisplayStrategy } from "./hopper/LinuxPrivateDisplayProbe.js";
 /** Compose provider diagnostics at the outer CLI adapter boundary. */
-export const createSystemDoctorHost = (environment = process.env) => systemDoctorHost({
-    environment,
-    providerInspections: async () => [
-        await inspectSystemGhidraProvider(environment),
-        inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),
-    ],
-    linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),
-});
+export const createSystemDoctorHost = (environment = process.env) => {
+    const selectedJebEndpoint = environment.REA_JEB_MCP_URL;
+    const selectedJebRegistrationEnvironment = selectedJebEndpoint !== undefined &&
+        selectedJebEndpoint.length > 0 &&
+        parseJebMcpEndpoint(selectedJebEndpoint).ok
+        ? { REA_JEB_MCP_URL: selectedJebEndpoint }
+        : {};
+    return systemDoctorHost({
+        environment,
+        providerRegistrationEnvironment: () => selectedJebRegistrationEnvironment,
+        providerInspections: async () => [
+            await inspectSystemGhidraProvider(environment),
+            inspectIdaRegistration(environment.REA_IDA_MCP_CONFIG),
+            await inspectJadxProvider(environment),
+        ],
+        linuxDemoRuntimeCheck: () => inspectLinuxPrivateDisplay(environment),
+    });
+};
 const HOPPER_DEMO_HELPER_PATH = fileURLToPath(new URL("../scripts/hopper-demo-x11.py", import.meta.url));
 const inspectLinuxPrivateDisplay = async (environment) => {
     const selection = await selectLinuxPrivateDisplayStrategy({

package/dist/domain/adb/adbDeviceAnalysis.js

@@ -21,6 +21,23 @@ const packageNameSchema = z
     .min(1)
     .max(256)
     .regex(/^[A-Za-z][A-Za-z0-9_]*(\.[A-Za-z][A-Za-z0-9_]*)*$/u, "Package name must be dot-separated Java identifiers");
+/** Text states emitted by adb's ConnectionState formatter. */
+export const ADB_DEVICE_STATES = [
+    "no permissions",
+    "unauthorized",
+    "authorizing",
+    "offline",
+    "recovery",
+    "sideload",
+    "connecting",
+    "bootloader",
+    "device",
+    "unknown",
+    "host",
+    "rescue",
+    "detached",
+];
+export const adbDeviceStateSchema = z.enum(ADB_DEVICE_STATES);
 const keyStringSchema = z.string().min(1).max(256);
 const keyPattern = /^[A-Za-z0-9._\x2d]+$/u;
 /**
@@ -107,7 +124,7 @@ export const adbInputSchemas = {
             .string()
             .min(1)
             .regex(/^\/[^\x00]*$/u, "Device path must be absolute")
-            .describe("Absolute device directory path to list (ls -la)"),
+            .describe("Absolute device directory path to list, including hidden children"),
     }),
     list_adb_features: z.strictObject({
         serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
@@ -148,7 +165,7 @@ export const adbInputSchemas = {
         replace: z
             .boolean()
             .default(false)
-            .describe("Replace an existing installation and keep its data (adb install -r)"),
+            .describe("Request replacement mode and keep existing app data if present (adb install -r); does not establish whether the app was already installed"),
     }),
     uninstall_adb_package: z.strictObject({
         serial: deviceSerialSchema.describe("Device serial exactly as `adb devices` reports it"),
@@ -311,7 +328,7 @@ const client = z.strictObject({
 });
 const device = z.strictObject({
     serial: z.string().min(1),
-    state: z.string().min(1),
+    state: adbDeviceStateSchema,
     transport: z.enum(["usb", "tcp", "unknown"]),
     product: z.string().nullable(),
     model: z.string().nullable(),
@@ -548,7 +565,8 @@ export const adbResultSchemas = {
         apk_path: z.string().min(1),
         bytes: z.number().int().nonnegative(),
         sha256: z.string().regex(/^[a-f0-9]{64}$/u),
-        replaced: z.boolean(),
+        replace_requested: z.boolean(),
+        replaced: z.boolean().nullable(),
     }),
     uninstall_adb_package: z.strictObject({
         client,
@@ -561,6 +579,8 @@ export const adbResultSchemas = {
         package_name: packageNameSchema,
         component: z.string().min(1),
         started_activity: z.string().nullable(),
+        reported_activity: z.string().nullable().optional(),
+        reported_status: z.string().nullable().optional(),
     }),
     start_adb_activity: z.strictObject({
         client,
@@ -574,6 +594,8 @@ export const adbResultSchemas = {
             value: z.string(),
         })),
         started_activity: z.string().nullable(),
+        reported_activity: z.string().nullable().optional(),
+        reported_status: z.string().nullable().optional(),
     }),
     stop_adb_app: z.strictObject({
         client,

package/dist/domain/analysisErrorBase.js

@@ -30,12 +30,17 @@ const ANALYSIS_ERROR_TAGS = [
 ];
 /** Base class for expected analysis, provider, and session failures. */
 export class AnalysisError extends Error {
+    diagnostics;
     capturedOutput;
     cleanup;
     cleanupIncomplete;
     cleanupResources;
     constructor(message, options) {
         super(message, options);
+        this.diagnostics =
+            options?.diagnostics === undefined
+                ? undefined
+                : structuredClone(options.diagnostics);
         this.capturedOutput =
             options?.capturedOutput === undefined
                 ? undefined
@@ -50,6 +55,21 @@ export class AnalysisError extends Error {
     executionFailure = undefined;
     partialObservation;
     cleanupReport = undefined;
+    /** Retain a later lifecycle failure without replacing the original typed error. */
+    retainSecondaryFailure(failure, diagnostics) {
+        // Secondary resources remain owned by their cleanup lifecycle; preserve
+        // the primary error's live cleanup status and original output.
+        Object.assign(this, {
+            diagnostics: structuredClone({ ...this.diagnostics, ...diagnostics }),
+            cause: new AggregateError(this.cause === undefined ? [failure] : [this.cause, failure], "Analysis failed and a later lifecycle operation also failed.", { cause: this.cause }),
+        });
+        return this;
+    }
+    /** Clear live cleanup status only after its owning resource confirms retry success. */
+    resolveCleanup() {
+        this.cleanupIncomplete = false;
+        return this;
+    }
     /** Retain a completed observation when a later step fails. */
     retainPartialObservation(observation) {
         this.partialObservation ??= observation;

package/dist/domain/analysisErrorCleanup.js

@@ -4,7 +4,7 @@ import { projectAnalysisError } from "./analysisErrorProjection.js";
 export const analysisErrorWithCleanupFailure = (primary, cleanup, operation = "close_binary") => {
     const projected = projectAnalysisError(cleanup);
     return new ProviderAdapterError(cleanup instanceof ProviderAdapterError ? cleanup.providerId : "rea", operation, {
-        cause: primary,
+        cause: new AggregateError([primary, cleanup], "Analysis failed and cleanup remains incomplete.", { cause: primary }),
         userMessage: projectAnalysisError(primary).message,
         ...(primary.capturedOutput === undefined
             ? {}

package/dist/domain/analysisErrorCore.js

@@ -16,6 +16,14 @@ export class AnalysisUnsupportedTargetError extends AnalysisError {
     }
 }
 /** An analysis or transport resource failure, distinct from malformed input or unsupported coverage. */
+export const ANALYSIS_RESOURCE_KINDS = [
+    "memory",
+    "cpu",
+    "file-size",
+    "transport",
+    "capacity",
+];
+/** A measured resource constraint or bounded admission refusal. */
 export class AnalysisResourceConstraintError extends AnalysisError {
     operation;
     resource;
@@ -41,10 +49,12 @@ export class AnalysisInputError extends AnalysisError {
     operation;
     issues;
     _tag = "AnalysisInputError";
+    userMessage;
     constructor(operation, options, issues = []) {
         super(`Invalid analysis input for ${operation}`, options);
         this.operation = operation;
         this.issues = issues;
+        this.userMessage = options?.userMessage;
     }
 }
 /** Provider output failed provider-neutral application parsing. */
@@ -52,10 +62,16 @@ export class AnalysisOutputError extends AnalysisError {
     operation;
     reason;
     _tag = "AnalysisOutputError";
+    userMessage;
+    remediationAction;
+    cleanupOnly;
     constructor(operation, reason, options) {
         super(`Invalid analysis output for ${operation}: ${reason}`, options);
         this.operation = operation;
         this.reason = reason;
+        this.userMessage = options?.userMessage;
+        this.remediationAction = options?.remediationAction;
+        this.cleanupOnly = options?.cleanupOnly ?? false;
     }
 }
 /** Selected provider cannot execute a declared analysis operation. */
@@ -65,12 +81,15 @@ export class AnalysisCapabilityUnavailableError extends AnalysisError {
     reason;
     _tag = "AnalysisCapabilityUnavailableError";
     userMessage;
+    /** Incomplete cleanup must settle before the operation can be retried. */
+    retryable;
     constructor(providerId, operation, reason, options) {
         super(`Provider ${providerId} cannot execute ${operation}: ${reason}`, options);
         this.providerId = providerId;
         this.operation = operation;
         this.reason = reason;
         this.userMessage = options?.userMessage;
+        this.retryable = options?.retryable === true && !this.cleanupIncomplete;
     }
 }
 /** Caller cancellation won before provider-neutral work completed. */

package/dist/domain/analysisErrorPresentation.js

@@ -1,4 +1,4 @@
-import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisInputError, AnalysisUnsupportedTargetError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
+import { AnalysisAccessDeniedError, AnalysisArtifactChangedError, AnalysisCapabilityUnavailableError, AnalysisInputError, AnalysisOutputError, AnalysisUnsupportedTargetError, AnalysisResourceConstraintError, } from "./analysisErrorCore.js";
 import { ArtifactOperationError } from "./artifactOperationError.js";
 import { BinaryTargetError, ConfigurationError, NoBinaryOpenError, } from "./configurationErrors.js";
 import { BrowserObservationError } from "./browserObservationError.js";
@@ -7,9 +7,11 @@ import { HopperRemoteError, HopperProcessError, HopperStartError, HopperTimeoutE
 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 AnalysisCapabilityUnavailableError && error.retryable)
+        return "Review details.reason, then retry the same analysis after the condition clears.";
+    if (error instanceof EvidenceFileError && error.published !== undefined)
+        return "Use the published file at details.published_path and resolve the reported staging cleanup failure.";
     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)
@@ -17,13 +19,15 @@ export const analysisErrorRemediationAction = (error) => {
             "Select a target supported by this operation or choose an operation supporting the reported target format.");
     if (error instanceof AnalysisResourceConstraintError)
         return (error.remediationAction ??
-            (error.resource === "transport"
-                ? "Discover retained records with get_evidence_bundle and detail: summary, then inspect compatible records through inspect_analysis_view using an exact Evidence reference. Export complete retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. 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."));
+            (error.resource === "capacity"
+                ? "Wait for an active analysis to complete, then retry within the reported admission limits."
+                : error.resource === "transport"
+                    ? "Discover retained records with get_evidence_bundle and detail: summary, then inspect compatible records through inspect_analysis_view using an exact Evidence reference. Export complete retained session evidence through export_evidence_bundle to a caller-selected path, or use complete CLI JSON output. 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.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."
@@ -39,12 +43,21 @@ export const analysisErrorRemediationAction = (error) => {
     if (error instanceof HopperRemoteError)
         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.";
+            : "Review the Hopper diagnostic details and correct the request or target; run `rea doctor` if the provider itself is failing. Repeating the unchanged request is not expected to succeed.";
     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 BinaryTargetError &&
+        error.constraint === "load_selection_rejected")
+        return "Correct the reported load argument (--target-format, --architecture, or --entry-point on the CLI; format, architecture, or entry_point through MCP) and retry.";
+    if (error instanceof BinaryTargetError &&
+        error.constraint === "file_format_rejected")
+        return "Review the reported file-format reason and select a supported, well-formed target.";
+    if (error instanceof BinaryTargetError &&
+        error.constraint === "wasm_requires_static_inspection")
+        return `For static inspection, call inspect_wasm_artifact with ${JSON.stringify({ path: error.path })} or run \`rea inspect-wasm-artifact <path> --format json\`. This separate lane requires caller-supplied WABT 1.0.42 via absolute REA_WABT_BIN_DIRECTORY; check its availability in binary_session. REA does not execute WASM or install tools, and the header alone does not establish that the complete module is valid.`;
     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.";
@@ -54,11 +67,23 @@ export const analysisErrorRemediationAction = (error) => {
         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 AnalysisOutputError &&
+        error.remediationAction !== undefined)
+        return error.remediationAction;
     if (error instanceof UnknownRegistryError && error.reason === "not-found")
         return "Check that the unknown_id belongs to this session, then retry.";
     return analysisErrorUserMessage(error);
 };
 export const analysisErrorCategory = (error) => {
+    if (error instanceof AnalysisCapabilityUnavailableError && error.retryable)
+        return "unavailable";
+    if (error instanceof BinaryTargetError &&
+        error.constraint === "load_selection_rejected")
+        return "invalid_input";
+    if (error instanceof BinaryTargetError &&
+        (error.constraint === "wasm_requires_static_inspection" ||
+            error.constraint === "file_format_rejected"))
+        return "unsupported_target";
     if (error instanceof ProviderSelectionError &&
         error.reason === "provider_unavailable")
         return "unavailable";
@@ -79,6 +104,7 @@ export const analysisErrorCategory = (error) => {
     if (error instanceof EvidenceFileError &&
         (error.reason === "missing" ||
             error.reason === "not-file" ||
+            error.reason === "wrong-kind" ||
             error.reason === "exists"))
         return "invalid_input";
     return STATIC_ERROR_CATEGORIES[error._tag] ?? "execution_failure";
@@ -110,6 +136,7 @@ const artifactErrorCategory = (reason) => {
     return "execution_failure";
 };
 const STATIC_ERROR_CATEGORIES = {
+    ConfigurationError: "invalid_input",
     AnalysisInputError: "invalid_input",
     AnalysisAccessDeniedError: "unavailable",
     AnalysisArtifactChangedError: "integrity_mismatch",
@@ -137,12 +164,15 @@ export const analysisErrorUserMessage = (error) => {
     if (error instanceof AnalysisArtifactChangedError)
         return "The selected artifact changed during acquisition; no stable snapshot was decoded.";
     if (error instanceof AnalysisInputError)
-        return "Analysis input is invalid. Check the arguments and try again.";
+        return (error.userMessage ??
+            "Analysis input is invalid. Check the arguments and try again.");
     const hopperMessage = hopperErrorUserMessage(error);
     if (hopperMessage !== undefined)
         return hopperMessage;
     if (error.userMessage !== undefined)
         return error.userMessage;
+    if (error instanceof AnalysisCapabilityUnavailableError && error.retryable)
+        return "Required runtime controls are unavailable for this attempt.";
     const standardMessage = standardErrorMessage(error._tag);
     if (standardMessage !== undefined)
         return standardMessage;
@@ -170,10 +200,16 @@ export const analysisErrorUserMessage = (error) => {
                 .join("; ")}.`;
     if (error instanceof NoBinaryOpenError)
         return error.message;
+    if (error instanceof BinaryTargetError &&
+        error.constraint === "wasm_requires_static_inspection")
+        return `${error.message}. Static WebAssembly inspection uses a separate optional WABT lane, not a native analysis engine.`;
     if (error instanceof BinaryTargetError)
         return error.constraint === "directory_requires_file"
             ? "open_binary accepts files and macOS app bundles. This target is a directory; JavaScript/Electron application directories can be analyzed directly with analyze_javascript_application or `rea analyze <directory>`."
-            : `${error.message}. Check that the path exists, is readable, and points to a supported file.`;
+            : error.constraint === "file_format_rejected" ||
+                error.constraint === "load_selection_rejected"
+                ? `${error.message}.`
+                : `${error.message}. 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.");
@@ -215,8 +251,11 @@ const hopperProcessMessage = (error) => {
         : ` Request id ${String(error.requestId)}.`;
     const startup = error.userMessage === undefined ? "" : ` ${error.userMessage}`;
     if (error.providerState === "exited") {
+        const signal = error.launcherFailure?.signal;
         const exit = error.exitCode === null
-            ? "no exit code was observed"
+            ? signal === undefined || signal === null
+                ? "no exit code was observed"
+                : `signal ${signal}`
             : `exit code ${String(error.exitCode)}`;
         const recovery = error.failureCode === undefined && stage !== "launch"
             ? ` ${RESTART_OWNED_PROVIDER}`
@@ -229,7 +268,7 @@ const hopperProcessMessage = (error) => {
 };
 const standardErrorMessage = (tag) => {
     if (UNREADABLE_OUTPUT_TAGS.has(tag))
-        return "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.";
+        return "Analysis returned an unreadable result. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.";
     if (UNSUPPORTED_PROVIDER_TAGS.has(tag))
         return "This analysis is unavailable for the current target. Choose another analysis or target.";
     if (CANCELLED_TAGS.has(tag))
@@ -237,7 +276,7 @@ const standardErrorMessage = (tag) => {
     if (TIMEOUT_TAGS.has(tag))
         return "Analysis took too long. Try a smaller request, then run `rea doctor` if it continues.";
     if (ADAPTER_FAILURE_TAGS.has(tag))
-        return "Analysis could not complete. Retry once; if it continues, run `rea doctor`.";
+        return "Analysis could not complete. Run `rea doctor` and review the reported details; repeating the unchanged request is not expected to succeed.";
     if (START_FAILURE_TAGS.has(tag))
         return "Analysis could not start or stopped unexpectedly. Run `rea doctor`, then try again.";
     return undefined;
@@ -294,7 +333,9 @@ const artifactMessage = ({ operation, reason, artifactDetails: details, detail,
         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 = ({ operation, reason, }) => {
+const evidenceFileMessage = ({ operation, reason, published, }) => {
+    if (published !== undefined)
+        return "The output file was published, but staging cleanup remains incomplete.";
     if (reason === "missing")
         return operation === "read"
             ? "Evidence file does not exist at the selected path. Check the path and try again."

package/dist/domain/analysisErrorProjection.js

@@ -11,7 +11,6 @@ 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);
@@ -20,6 +19,9 @@ export const projectAnalysisError = (error) => {
     const primaryDetails = errorDetails(error);
     const details = {
         ...primaryDetails,
+        ...(error.diagnostics === undefined
+            ? {}
+            : { diagnostics: error.diagnostics }),
         ...(error.cleanupIncomplete
             ? {
                 cleanup: "incomplete",
@@ -45,7 +47,12 @@ export const projectAnalysisError = (error) => {
         code,
         category: analysisErrorCategory(error),
         message: analysisErrorUserMessage(error),
-        retryable: RETRYABLE_CODES.has(code),
+        retryable: RETRYABLE_CODES.has(code) ||
+            (error instanceof AnalysisCapabilityUnavailableError &&
+                error.retryable) ||
+            (code === "resource_constraint" &&
+                error instanceof AnalysisResourceConstraintError &&
+                error.resource === "capacity"),
         remediation: {
             action: analysisErrorRemediationAction(error),
         },
@@ -67,9 +74,11 @@ const underlyingErrorCode = (error) => {
     if (error instanceof ArtifactOperationError)
         return artifactOperationCode(error);
     if (error instanceof BinaryTargetError)
-        return error.systemCode === undefined
-            ? "target_unavailable"
-            : "access_denied";
+        return error.constraint === "load_selection_rejected"
+            ? "invalid_request"
+            : error.systemCode === undefined
+                ? "target_unavailable"
+                : "access_denied";
     if (error instanceof EvidenceFileError)
         return evidenceFileCode(error.reason);
     if (error instanceof UnknownRegistryError)
@@ -195,7 +204,13 @@ const requestErrorDetails = (error) => {
             boundary: "filesystem-read",
         };
     if (error instanceof AnalysisOutputError)
-        return { operation: error.operation, reason: error.reason };
+        return {
+            operation: error.operation,
+            reason: error.reason,
+            ...(error.diagnostics === undefined
+                ? {}
+                : { diagnostics: error.diagnostics }),
+        };
     if (error instanceof AnalysisInputError && error.issues.length > 0)
         return {
             operation: error.operation,
@@ -241,6 +256,13 @@ const artifactStateErrorDetails = (error) => {
             operation: error.operation,
             reason: error.reason,
             ...(error.path === undefined ? {} : { path: error.path }),
+            ...(error.published === undefined
+                ? {}
+                : {
+                    published: true,
+                    bytes: error.published.bytes,
+                    published_path: error.published.path,
+                }),
         };
     return undefined;
 };
@@ -274,9 +296,6 @@ const providerErrorDetails = (error) => {
                     resources: [...error.cleanupResources],
                 }
                 : {}),
-            ...(error.diagnostics === undefined
-                ? {}
-                : { diagnostics: error.diagnostics }),
         };
     if (error instanceof BrowserObservationError) {
         const primaryReason = primaryBrowserFailureReason(error);
@@ -356,8 +375,8 @@ const lifecycleErrorDetails = (error) => {
     if (error instanceof AnalysisCancelledError)
         return {
             operation: error.operation,
-            cleanup: error.cleanup === undefined ? "complete" : "incomplete",
-            ...(error.cleanup === undefined
+            cleanup: error.cleanupIncomplete ? "incomplete" : "complete",
+            ...(error.cleanup === undefined || !error.cleanupIncomplete
                 ? {}
                 : {
                     cleanup_reason: error.cleanup.reason,
@@ -371,7 +390,7 @@ const lifecycleErrorDetails = (error) => {
         return {
             operation: error.operation,
             timeout_ms: error.timeoutMs,
-            ...(error.cleanup === undefined
+            ...(error.cleanup === undefined || !error.cleanupIncomplete
                 ? {}
                 : {
                     cleanup: "incomplete",