rea-agents 6.3.0 → 6.5.0

package/dist/android/JadxProvider.js

@@ -8,9 +8,11 @@ import { ProviderAdapterError } from "../domain/providerAdapterError.js";
 import { ProviderCleanupError } from "../domain/providerCleanupError.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import { err, ok } from "../domain/result.js";
-import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
-import { snapshotAndroidEngine, hashAndroidFile, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
-import { inspectJadxAvailability, resolveJadxConfiguration, } from "./JadxConfiguration.js";
+import { createJadxWorkspaceRoot, } from "./JadxWorkspaceRoot.js";
+import { snapshotAndroidEngine, snapshotAndroidTarget, } from "./AndroidTargetSnapshot.js";
+import { hashStableFile } from "../filesystem/StableFileHash.js";
+import { RegularFileChangedError } from "../filesystem/RegularFile.js";
+import { inspectJadxAvailability, resolveJadxConfigurationInputs, validateJadxConfiguration, } from "./JadxConfiguration.js";
 import { JadxSession } from "./JadxSession.js";
 const OPERATION_TIMEOUT_MS = 120_000;
 const BRIDGE_SOURCE = fileURLToPath(new URL("../../bridge/android/ReaJadxBridge.java", import.meta.url));
@@ -60,6 +62,26 @@ const executionError = (context) => {
         },
     });
 };
+const androidTargetChanged = (operation, path, cause) => new AnalysisInputError(operation, cause === undefined ? undefined : { cause }, [
+    {
+        path: ["path"],
+        reason: "invalid_value",
+        message: `APK bytes changed after admission at ${path}; retry against a stable file.`,
+    },
+]);
+const androidSourceChanged = (operation, source, cause) => new AnalysisCapabilityUnavailableError("jadx", operation, `Selected JADX input bytes changed during admission at ${source}; retry with a stable installation.`, cause === undefined ? undefined : { cause });
+const hashAndroidSource = async (path, operation, signal) => {
+    try {
+        return (await hashStableFile(path, signal)).sha256;
+    }
+    catch (cause) {
+        if (signal.aborted)
+            throw cause;
+        if (cause instanceof RegularFileChangedError)
+            throw androidSourceChanged(operation, path, cause);
+        throw cause;
+    }
+};
 const cleanup = async (resources) => {
     const { session, root, previousError } = resources;
     const diagnostics = {
@@ -90,10 +112,13 @@ const cleanup = async (resources) => {
         resources.root = undefined;
     }
     catch (cause) {
-        return err(new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
+        const error = new ProviderCleanupError("jadx", [root?.path ?? "unknown"], {
             ...diagnostics,
             reason: cause instanceof Error ? cause.message : String(cause),
-        }, { cause: previousError ?? cause }));
+        }, { cause: previousError ?? cause });
+        if (previousError?.partialObservation !== undefined)
+            error.retainPartialObservation(previousError.partialObservation);
+        return err(error);
     }
     return ok(undefined);
 };
@@ -202,18 +227,23 @@ export class JadxProvider {
         try {
             if (target.format !== "apk")
                 throw new AnalysisCapabilityUnavailableError("jadx", request.operation, `Target ${target.path} is ${target.format}; provide one standalone APK.`);
-            const configuration = await resolveJadxConfiguration(this.environment, request.operation, signal);
+            const configuration = await resolveJadxConfigurationInputs(this.environment, request.operation, signal);
             signal.throwIfAborted();
-            const jarHash = await hashAndroidFile(configuration.jar);
-            const bridgeHash = await hashAndroidFile(BRIDGE_SOURCE);
-            if ((await hashAndroidFile(target.path)) !== target.sha256)
-                throw new AnalysisInputError(request.operation, undefined, [
-                    {
-                        path: ["path"],
-                        reason: "invalid_value",
-                        message: "APK bytes changed after admission; retry against a stable file.",
-                    },
-                ]);
+            const jarHash = await hashAndroidSource(configuration.jar, request.operation, signal);
+            const bridgeHash = await hashAndroidSource(BRIDGE_SOURCE, request.operation, signal);
+            let targetHash;
+            try {
+                targetHash = (await hashStableFile(target.path, signal)).sha256;
+            }
+            catch (cause) {
+                if (signal.aborted)
+                    throw cause;
+                if (cause instanceof RegularFileChangedError)
+                    throw androidTargetChanged(request.operation, target.path, cause);
+                throw cause;
+            }
+            if (targetHash !== target.sha256)
+                throw androidTargetChanged(request.operation, target.path);
             const key = JSON.stringify({
                 path: target.path,
                 sha256: target.sha256,
@@ -237,15 +267,20 @@ export class JadxProvider {
             }
             let retained = this.#retained;
             if (retained === undefined) {
-                root = await PrivateRuntimeRoot.create({ prefix: "rea-android-" });
-                const engine = await snapshotAndroidEngine(configuration.jar, jarHash, root.path, request.operation);
-                const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation);
+                await validateJadxConfiguration(configuration, this.environment, request.operation, signal);
+                root = await createJadxWorkspaceRoot();
+                const workspaceSignal = root.failureSignal === undefined
+                    ? signal
+                    : AbortSignal.any([signal, root.failureSignal]);
+                const engine = await snapshotAndroidEngine(configuration.jar, jarHash, root.path, request.operation, workspaceSignal);
+                const snapshot = await snapshotAndroidTarget(target.path, target.sha256, root.path, request.operation, workspaceSignal);
                 const bridge = join(root.path, "ReaJadxBridge.java");
                 await copyFile(BRIDGE_SOURCE, bridge);
                 await chmod(bridge, 0o400);
-                if ((await hashAndroidFile(bridge)) !== bridgeHash)
-                    throw new AnalysisCapabilityUnavailableError("jadx", request.operation, "REA Android bridge bytes changed during admission; retry with a stable installation.");
-                signal.throwIfAborted();
+                const copiedBridgeHash = await hashAndroidSource(bridge, request.operation, workspaceSignal);
+                if (copiedBridgeHash !== bridgeHash)
+                    throw androidSourceChanged(request.operation, BRIDGE_SOURCE, undefined);
+                workspaceSignal.throwIfAborted();
                 session = new JadxSession({
                     command: configuration.java,
                     arguments: [
@@ -256,7 +291,7 @@ export class JadxProvider {
                     ],
                     cwd: root.path,
                     hostEnvironment: this.environment,
-                    signal,
+                    signal: workspaceSignal,
                 }, this.launcher);
                 retained = {
                     key,
@@ -269,6 +304,9 @@ export class JadxProvider {
             }
             root = retained.root;
             session = retained.session;
+            const activeSignal = root.failureSignal === undefined
+                ? signal
+                : AbortSignal.any([signal, root.failureSignal]);
             const { snapshot } = retained;
             const outcome = ok(await session.execute({
                 request,
@@ -276,9 +314,9 @@ export class JadxProvider {
                 snapshot,
                 jarHash: retained.jarHash,
                 bridgeHash: retained.bridgeHash,
-                signal,
+                signal: activeSignal,
             }));
-            signal.throwIfAborted();
+            activeSignal.throwIfAborted();
             this.#retained = retained;
             return outcome;
         }

package/dist/android/JadxRelease.js

@@ -12,6 +12,16 @@ export const JADX_BRIDGE_IDENTITY = Object.freeze({
 });
 /** Remediation when `REA_JADX_MCP_JAR` is missing or not an absolute path. */
 export const JADX_JAR_CONFIGURATION_REMEDIATION = `Set REA_JADX_MCP_JAR to the absolute path of a caller-supplied jadx-headless-mcp ${JADX_RELEASE.version} JAR. REA does not download or install it.`;
+/** Remediation when the selected Java runtime cannot satisfy the JADX bridge. */
+export const JADX_JAVA_RUNTIME_REMEDIATION = "Select a full JDK including jdk.compiler via JAVA_HOME or PATH, then verify it with java --list-modules. REA does not install Java.";
+/** Remediation when a JADX JVM resource override is malformed. */
+export const JADX_JVM_OPTIONS_REMEDIATION = "Set REA_JADX_HEAP_MIB to a positive integer (heap size in MiB) and REA_JADX_ACTIVE_PROCESSOR_COUNT to a positive integer within the JVM's signed 32-bit range.";
+/** Remediation when the host cannot run the Android JADX subprocess. */
+export const JADX_UNSUPPORTED_HOST_REMEDIATION = "Use Linux, macOS, or Windows x64 with its bundled native controls for Android JADX analysis.";
+/** Remediation when the Windows native backend cannot take process ownership. */
+export const JADX_WINDOWS_NATIVE_REMEDIATION = "Use a matching current Windows x64 REA package with its bundled native controls. The native failure above identifies the failed constraint; Java installation or registration changes cannot enable a missing native backend.";
+/** Remediation when the Java module-listing probe cannot establish the runtime. */
+export const JADX_JAVA_PROBE_REMEDIATION = "Verify the selected Java launcher with java --list-modules: it must start promptly and emit a concise module listing including a parseable java.base version. REA does not install Java.";
 /** Producing engine identity used by Evidence and the generated product catalog. */
 export const JADX_PROVIDER_IDENTITY = Object.freeze({
     id: "jadx",
@@ -21,7 +31,8 @@ export const JADX_PROVIDER_IDENTITY = Object.freeze({
 /** Audited engine coverage, kept outside portable Android semantics. */
 export const JADX_LIMITATIONS = [
     "Static decompiler observations do not establish runtime behavior; the APK is never executed.",
-    "Method signatures use provider display types; exact DEX descriptors and instruction offsets are unavailable. Overload indices are local to this engine and artifact.",
+    "Method signatures use provider display types; DEX prototypes come from frozen JADX metadata. Display names may be aliases, and overload indices are local to this engine and artifact.",
     "Class inventories use parsed metadata before code generation, including synthetic members that may be omitted from decompiled source. Source positions remain unknown.",
+    "Incoming reference totals count JADX using nodes. Direct invoke entries within a using method report raw DEX code-unit offsets and method indexes, but coverage is limited to those nodes and directly matched invokes; it does not establish every possible dynamic or reflective call site.",
     "Manifest summary fields are extracted by the upstream engine; decoded XML is retained for verification. APK signatures, split APKs, native libraries and Android runtime capture are not verified by this provider.",
 ];

package/dist/android/JadxWorkspaceRoot.js

@@ -0,0 +1,157 @@
+import { spawn } from "node:child_process";
+import { lstat } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { win32 } from "node:path";
+import { fileURLToPath } from "node:url";
+import { z } from "zod";
+import { PrivateRuntimeRoot } from "../process/PrivateRuntimeRoot.js";
+/** Match the native owner's ordinary spelling only for extended local drive paths. */
+const localDrivePath = (path) => path.replace(/^\\\\\?\\(?=[A-Za-z]:\\)/u, "");
+const guardianSource = fileURLToPath(new URL("../../scripts/rea-android-workspace-guardian.mjs", import.meta.url));
+const readySchema = z.strictObject({
+    path: z.string(),
+    volumeSerial: z.string().regex(/^[a-f0-9]{16}$/u),
+    fileId: z.string().regex(/^[a-f0-9]{32}$/u),
+    privateDacl: z.literal(true),
+});
+const boundedWait = async (promise, milliseconds, label) => {
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_resolve, reject) => {
+                timer = setTimeout(() => reject(new Error(label)), milliseconds);
+            }),
+        ]);
+    }
+    finally {
+        clearTimeout(timer);
+    }
+};
+/** A detached guardian retains native cleanup ownership without keeping its caller alive. */
+const releaseGuardianReferences = (child) => {
+    child.stdin.destroy();
+    child.stdout.destroy();
+    child.stderr.destroy();
+    child.unref();
+};
+class WindowsJadxWorkspaceRoot {
+    path;
+    #failure = new AbortController();
+    failureSignal = this.#failure.signal;
+    #child;
+    #exit;
+    #diagnostics;
+    #closing = false;
+    #closePromise;
+    constructor(path, child, exit, diagnostics) {
+        this.path = path;
+        this.#child = child;
+        this.#exit = exit;
+        this.#diagnostics = diagnostics;
+        void this.#exit.then((result) => {
+            if (!this.#closing)
+                this.#failure.abort(new Error(`Android workspace guardian exited before cleanup: ${result.error?.message ?? result.code ?? result.signal ?? "unknown"}`));
+        });
+    }
+    static async create() {
+        const parent = tmpdir();
+        const child = spawn(process.execPath, [guardianSource, parent], {
+            detached: true,
+            windowsHide: true,
+            stdio: ["pipe", "pipe", "pipe"],
+            env: {
+                SystemRoot: process.env.SystemRoot,
+                WINDIR: process.env.WINDIR,
+                TEMP: parent,
+                TMP: parent,
+            },
+        });
+        let diagnostics = "";
+        child.stderr.on("data", (chunk) => {
+            diagnostics = (diagnostics + chunk.toString()).slice(-8192);
+        });
+        const exit = new Promise((resolve) => {
+            child.once("error", (error) => resolve({ code: null, signal: null, error }));
+            child.once("close", (code, signal) => resolve({ code, signal }));
+        });
+        const ready = new Promise((resolve, reject) => {
+            let frame = "";
+            child.stdout.on("data", (chunk) => {
+                frame += chunk.toString();
+                if (frame.length > 4096) {
+                    reject(new Error("Android workspace guardian readiness exceeded 4 KiB"));
+                    return;
+                }
+                const end = frame.indexOf("\n");
+                if (end !== -1)
+                    resolve(frame.slice(0, end));
+            });
+            child.stdout.once("error", reject);
+        });
+        try {
+            const line = await boundedWait(Promise.race([
+                ready,
+                exit.then((result) => {
+                    throw new Error(`Android workspace guardian exited during startup: ${result.error?.message ?? result.code ?? result.signal ?? "unknown"}; ${diagnostics}`);
+                }),
+            ]), 15000, "Android workspace guardian startup timed out");
+            const observation = readySchema.parse(JSON.parse(line));
+            if (win32.dirname(localDrivePath(observation.path)).toLowerCase() !==
+                localDrivePath(win32.resolve(parent)).toLowerCase() ||
+                !/^rea-android-[a-f0-9]{32}$/u.test(win32.basename(observation.path)))
+                throw new Error("Android workspace guardian returned an unexpected root");
+            child.stdout.resume();
+            return new WindowsJadxWorkspaceRoot(observation.path, child, exit, () => diagnostics);
+        }
+        catch (cause) {
+            if (!child.stdin.destroyed)
+                child.stdin.end();
+            try {
+                await boundedWait(exit, 30000, "Android workspace guardian did not settle after startup failure");
+            }
+            catch (cleanupFailure) {
+                throw new AggregateError([cause, cleanupFailure], "Android workspace guardian startup and cleanup failed");
+            }
+            finally {
+                releaseGuardianReferences(child);
+            }
+            throw cause;
+        }
+    }
+    close() {
+        this.#closing = true;
+        this.#closePromise ??= this.#finish().catch((cause) => {
+            this.#closePromise = undefined;
+            throw cause;
+        });
+        return this.#closePromise;
+    }
+    async #finish() {
+        if (!this.#child.stdin.destroyed)
+            this.#child.stdin.end();
+        let result;
+        try {
+            result = await boundedWait(this.#exit, 120000, `Android workspace guardian cleanup timed out for ${this.path}`);
+        }
+        catch (cause) {
+            releaseGuardianReferences(this.#child);
+            throw cause;
+        }
+        if (result.error !== undefined || result.code !== 0)
+            throw new Error(`Android workspace guardian cleanup failed for ${this.path}: ${result.error?.message ?? result.code ?? result.signal ?? "unknown"}; ${this.#diagnostics()}`);
+        try {
+            await lstat(this.path);
+        }
+        catch (cause) {
+            if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+                return;
+            throw cause;
+        }
+        throw new Error(`Android workspace guardian exited but retained ${this.path}`);
+    }
+}
+/** POSIX retains its in-process root; Windows keeps a detached native owner. */
+export const createJadxWorkspaceRoot = () => process.platform === "win32"
+    ? WindowsJadxWorkspaceRoot.create()
+    : PrivateRuntimeRoot.create({ prefix: "rea-android-" });

package/dist/apktool/ApktoolConfiguration.js

@@ -0,0 +1,227 @@
+import { AnalysisCancelledError, AnalysisTimeoutError, } from "../domain/analysisErrorCore.js";
+import { isAbsolute, win32 } from "node:path";
+import { stat } from "node:fs/promises";
+import { snapshotEnvironment } from "../process/snapshotEnvironment.js";
+import { ABORTED, waitForAbortable } from "../process/AbortablePromise.js";
+import { ProviderStartupDeadline } from "../process/ProviderDeadline.js";
+import { execFileOutput, execFileOutputFailure, } from "../process/ExecFileOutput.js";
+import { gte, valid } from "semver";
+import { isWindowsBatchFile, windowsBatchCommand, WindowsBatchCommandError, } from "../process/WindowsBatchCommand.js";
+/** Environment key selecting the caller's apktool launcher. */
+export const APKTOOL_COMMAND_ENV = "REA_APKTOOL_COMMAND";
+const VERSION_TIMEOUT_MS = 20_000;
+const VERSION_MAX_OUTPUT_BYTES = 64 * 1024;
+/**
+ * Preserve an explicit launcher, or resolve the default Windows command before
+ * choosing native versus batch process creation. POSIX keeps execFile's PATH
+ * lookup. The resolved selection is reused for the version and decode runs.
+ */
+export const resolveApktoolCommand = async (environment, platform = process.platform, signal) => {
+    if (signal?.aborted === true)
+        throw new AnalysisCancelledError("inspect_apktool_client");
+    const selectedEnvironment = snapshotEnvironment(environment, platform);
+    const configured = selectedEnvironment[APKTOOL_COMMAND_ENV];
+    if (configured !== undefined && configured.trim() !== "") {
+        if (!(platform === "win32"
+            ? win32.isAbsolute(configured)
+            : isAbsolute(configured)))
+            throw new ApktoolConfigurationFailure("not_absolute", `${APKTOOL_COMMAND_ENV} must be an absolute path to the apktool launcher`, { configured_command: configured });
+        return { command: configured, commandSource: "environment" };
+    }
+    if (platform !== "win32")
+        return { command: "apktool", commandSource: "path" };
+    const extensions = (selectedEnvironment.PATHEXT ?? ".EXE;.COM;.BAT;.CMD")
+        .split(";")
+        .filter((extension) => extension !== "");
+    for (const extension of extensions)
+        if (!extension.startsWith(".") || /[\\/:\0]/u.test(extension))
+            throw new ApktoolConfigurationFailure("command_unresolved", "Windows PATHEXT must contain filename extensions, not paths", {
+                selected_command: "apktool",
+                command_source: "path",
+                invalid_extension: extension,
+            });
+    const directories = (selectedEnvironment.PATH ?? "")
+        .split(";")
+        .filter((directory) => directory !== "");
+    if (selectedEnvironment.NODEFAULTCURRENTDIRECTORYINEXEPATH === undefined)
+        directories.unshift(process.cwd());
+    // A single deadline owns the whole PATH search, including filesystem waits.
+    const deadline = new ProviderStartupDeadline(VERSION_TIMEOUT_MS, signal);
+    const lookupInterruption = () => deadline.interruption === "cancelled"
+        ? new AnalysisCancelledError("inspect_apktool_client")
+        : new AnalysisTimeoutError("inspect_apktool_client", VERSION_TIMEOUT_MS, {
+            diagnostics: { phase: "windows_path_lookup" },
+        });
+    try {
+        for (const entry of directories) {
+            const directory = entry.startsWith('"') && entry.endsWith('"')
+                ? entry.slice(1, -1)
+                : entry;
+            for (const extension of extensions) {
+                if (deadline.interruption !== undefined)
+                    throw lookupInterruption();
+                const candidate = win32.resolve(directory, `apktool${extension}`);
+                try {
+                    const metadata = await waitForAbortable(stat(candidate), deadline.signal);
+                    if (metadata === ABORTED || deadline.interruption !== undefined)
+                        throw lookupInterruption();
+                    if (metadata.isFile())
+                        return { command: candidate, commandSource: "path" };
+                }
+                catch (cause) {
+                    if (deadline.interruption !== undefined)
+                        throw lookupInterruption();
+                    const code = typeof cause === "object" && cause !== null
+                        ? Reflect.get(cause, "code")
+                        : undefined;
+                    if (code === "ENOENT" || code === "ENOTDIR")
+                        continue;
+                    throw new ApktoolConfigurationFailure("command_unresolved", `The PATH-selected apktool launcher could not be inspected: ${candidate}`, {
+                        selected_command: "apktool",
+                        command_source: "path",
+                        candidate_path: candidate,
+                        ...(typeof code === "string" ? { filesystem_error: code } : {}),
+                    }, { cause });
+                }
+            }
+        }
+    }
+    finally {
+        deadline.dispose();
+    }
+    throw new ApktoolConfigurationFailure("command_missing", "The apktool launcher was not found on the selected Windows PATH/PATHEXT", {
+        selected_command: "apktool",
+        command_source: "path",
+        remediation: `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher, or add its directory and extension to PATH and PATHEXT`,
+    });
+};
+export class ApktoolConfigurationFailure extends Error {
+    code;
+    diagnostics;
+    constructor(code, message, diagnostics = {}, options) {
+        super(message, options);
+        this.code = code;
+        this.diagnostics = diagnostics;
+    }
+}
+/**
+ * Run the selected launcher directly, or through cmd.exe when Windows can
+ * only execute it there (the Chocolatey `apktool.bat` and `java -jar`
+ * wrapper scripts). Throws WindowsBatchCommandError when a token cannot be
+ * passed to cmd.exe safely.
+ */
+export const apktoolInvocation = (selection, arguments_, environment, platform = process.platform) => platform === "win32" && isWindowsBatchFile(selection.command)
+    ? {
+        ...windowsBatchCommand({
+            environment,
+            batchPath: selection.command,
+            arguments: arguments_,
+        }),
+        windowsVerbatimArguments: true,
+    }
+    : {
+        command: selection.command,
+        arguments: arguments_,
+        windowsVerbatimArguments: false,
+    };
+/** Read the version from Apktool's single-line `--version` response. */
+export const parseApktoolVersionOutput = (stdout) => {
+    const line = stdout
+        .split(/\r?\n/u)
+        .map((entry) => entry.trim())
+        .find((entry) => entry !== "");
+    if (line === undefined || valid(line) === null)
+        return { version: null, reportedVersion: line ?? null };
+    return { version: line };
+};
+const supportsDocumentedApktoolVersion = (version) => {
+    // Debian's verified 2.7.0-dirty build is a downstream build marker, not a
+    // prerelease. Treat only that known marker as build metadata for the floor.
+    const comparisonVersion = version.replace(/-dirty$/u, "+dirty");
+    const parsedVersion = valid(comparisonVersion);
+    return parsedVersion !== null && gte(parsedVersion, "2.7.0");
+};
+/** Probe the selected apktool launcher without decoding anything. */
+export const inspectApktoolClient = async (selection, signal, environment = process.env, platform = process.platform) => {
+    const hostEnvironment = snapshotEnvironment(environment, platform);
+    let invocation;
+    try {
+        invocation = apktoolInvocation(selection, ["--version"], hostEnvironment, platform);
+    }
+    catch (cause) {
+        if (!(cause instanceof WindowsBatchCommandError))
+            throw cause;
+        throw new ApktoolConfigurationFailure("launcher_unsupported", `The selected apktool launcher cannot be run through cmd.exe: ${cause.message}`, {
+            selected_command: selection.command,
+            command_source: selection.commandSource,
+            remediation: `Set ${APKTOOL_COMMAND_ENV} to a launcher path without cmd.exe metacharacters (" % ^ ! & | < >), or to a native apktool executable`,
+        }, { cause });
+    }
+    let stdout;
+    let stderr;
+    try {
+        ({ stdout, stderr } = await execFileOutput(invocation.command, invocation.arguments, {
+            windowsVerbatimArguments: invocation.windowsVerbatimArguments,
+            timeout: VERSION_TIMEOUT_MS,
+            stopSignal: "SIGTERM",
+            maxBuffer: VERSION_MAX_OUTPUT_BYTES,
+            env: hostEnvironment,
+            ...(signal === undefined ? {} : { signal }),
+        }));
+    }
+    catch (cause) {
+        const failure = execFileOutputFailure(cause);
+        if (signal?.aborted || failure?.code === "ABORT_ERR")
+            throw new AnalysisCancelledError("inspect_apktool_client", { cause });
+        if (failure?.code === "ENOENT")
+            throw new ApktoolConfigurationFailure("command_missing", `The selected apktool launcher was not found: ${selection.command}`, {
+                selected_command: selection.command,
+                command_source: selection.commandSource,
+                remediation: `Set ${APKTOOL_COMMAND_ENV} to an absolute apktool launcher (the upstream wrapper or a java -jar script)`,
+            }, { cause });
+        throw new ApktoolConfigurationFailure("version_unresolved", "The selected apktool launcher did not report a usable version", {
+            selected_command: selection.command,
+            ...(failure === undefined
+                ? {}
+                : {
+                    exit_code: failure.code,
+                    stderr_excerpt: failure.stderr.slice(0, 512),
+                }),
+        }, { cause });
+    }
+    const identity = parseApktoolVersionOutput(stdout);
+    if (identity.version === null)
+        throw new ApktoolConfigurationFailure("version_unresolved", "The selected apktool launcher exited successfully but did not report a recognizable version", {
+            selected_command: selection.command,
+            command_source: selection.commandSource,
+            version_probe: "unrecognized_output",
+            reported_version: identity.reportedVersion,
+            stdout,
+            stderr,
+        });
+    if (!supportsDocumentedApktoolVersion(identity.version))
+        throw new ApktoolConfigurationFailure("unsupported_version", `The selected Apktool version ${identity.version} is older than the supported minimum 2.7.0`, {
+            selected_command: selection.command,
+            command_source: selection.commandSource,
+            reported_version: identity.version,
+            minimum_version: "2.7.0",
+            remediation: `Use Apktool 2.7.0 or newer; see docs/apktool-resource-analysis.md.`,
+        });
+    return identity;
+};
+/** Availability in the shape shared by every provider. */
+const rejectionCodeOf = (code) => code === "command_missing"
+    ? "executable_missing"
+    : code === "not_absolute" ||
+        code === "launcher_unsupported" ||
+        code === "command_unresolved"
+        ? "not_configured"
+        : code === "unsupported_version"
+            ? "unsupported_version"
+            : "version_unresolved";
+export const apktoolConfigurationAvailability = (cause) => ({
+    status: "unavailable",
+    code: rejectionCodeOf(cause.code),
+    reason: cause.message,
+    diagnostics: { ...cause.diagnostics },
+});