rea-agents 5.0.0 → 6.1.0

package/dist/browser/history/HistoricalCaptureDecoder.js

@@ -0,0 +1,188 @@
+import { historicalCaptureFailure, captureMemoryFailure, } from "./CaptureFailures.js";
+import { projectAnalysisError } from "../../domain/analysisErrorProjection.js";
+import { randomUUID } from "node:crypto";
+import { writeFile } from "node:fs/promises";
+import { join } from "node:path";
+import { z } from "zod";
+import { readStableArtifact } from "../../artifacts/readStableArtifact.js";
+import { ArtifactReaderFailure } from "../../artifacts/ArtifactReader.js";
+import { AnalysisCapabilityUnavailableError, AnalysisCancelledError, AnalysisInputError, AnalysisOutputError, } from "../../domain/analysisErrorCore.js";
+import { ProviderAdapterError } from "../../domain/providerAdapterError.js";
+import { ProviderCleanupError } from "../../domain/providerCleanupError.js";
+import { err, ok } from "../../domain/result.js";
+import { WEB_NETWORK_CAPTURE_LIMITS, webNetworkCaptureSchema, } from "../../domain/webNetworkCapture.js";
+import { runOwnedCommand } from "../../process/OwnedCommand.js";
+import { PrivateRuntimeRoot } from "../../process/PrivateRuntimeRoot.js";
+import { redactExplicitFailure } from "../../domain/explicitSensitiveFailure.js";
+const OPERATION = "inspect_web_network_capture";
+const decodedSchema = webNetworkCaptureSchema.omit({
+    artifact: true,
+    format: true,
+    runtime_attribution: true,
+    limitations: true,
+});
+const replySchema = z.discriminatedUnion("ok", [
+    z.strictObject({ ok: z.literal(true), value: decodedSchema }),
+    z.strictObject({
+        ok: z.literal(false),
+        reason: z.enum([
+            "format",
+            "unsupported",
+            "input-limit",
+            "resource-limit",
+            "decoder",
+            "limit",
+        ]),
+        message: z.string(),
+        pointer: z.string(),
+    }),
+]);
+/** One owned snapshot/process/root lifecycle for replaceable historical format decoders. */
+export class HistoricalCaptureDecoder {
+    adapters;
+    environment;
+    createRuntime;
+    constructor(adapters, environment, createRuntime = () => PrivateRuntimeRoot.create({ prefix: "rea-web-capture-" })) {
+        this.adapters = adapters;
+        this.environment = environment;
+        this.createRuntime = createRuntime;
+    }
+    /** Snapshot the selected artifact, decode it offline, and release private credentials and processes. */
+    async inspect(input, options) {
+        let runtime;
+        let result;
+        let phase = "capture-read";
+        try {
+            const adapter = this.adapters.find((candidate) => candidate.format === input.format);
+            if (adapter === undefined)
+                throw new AnalysisCapabilityUnavailableError(input.format, OPERATION, "No adapter is configured for the selected capture format.");
+            const snapshot = await readStableArtifact(input.capture_path, WEB_NETWORK_CAPTURE_LIMITS.inputBytes, options?.signal);
+            phase = "decoder";
+            runtime = await this.createRuntime();
+            const snapshotPath = join(runtime.path, "capture.snapshot");
+            const requestPath = join(runtime.path, "request.json");
+            const replyPath = join(runtime.path, "reply.json");
+            await writeFile(snapshotPath, snapshot.bytes, {
+                mode: 0o600,
+                flag: "wx",
+                ...(options?.signal === undefined ? {} : { signal: options.signal }),
+            });
+            await writeFile(requestPath, JSON.stringify({
+                snapshot_path: snapshotPath,
+                reply_path: replyPath,
+                sensitive_values: input.sensitive_values,
+            }), { mode: 0o600, flag: "wx" });
+            const command = await adapter.command(requestPath, runtime.path);
+            const environment = {
+                ...this.environment,
+                UV_THREADPOOL_SIZE: "1",
+            };
+            delete environment.NODE_OPTIONS;
+            await runOwnedCommand({
+                ...command,
+                runId: `rea-web-capture-${randomUUID()}`,
+                cwd: runtime.path,
+                hostEnvironment: environment,
+            }, {
+                timeoutMs: WEB_NETWORK_CAPTURE_LIMITS.timeoutMs,
+                diagnosticBytes: 1024 * 1024,
+            }, options?.signal === undefined ? {} : { signal: options.signal });
+            let reply;
+            try {
+                const replyFile = await readStableArtifact(replyPath, WEB_NETWORK_CAPTURE_LIMITS.outputBytes, options?.signal);
+                reply = replySchema.parse(JSON.parse(replyFile.bytes.toString("utf8")));
+            }
+            catch (cause) {
+                if (options?.signal?.aborted)
+                    throw new AnalysisCancelledError(OPERATION);
+                throw new AnalysisOutputError(OPERATION, `Owned capture decoder reply failed for ${input.capture_path}: ${replyFailureReason(cause)}`, { cause });
+            }
+            if (!reply.ok) {
+                if (reply.reason === "format")
+                    throw new AnalysisInputError(OPERATION, undefined, [
+                        {
+                            path: ["capture_path", reply.pointer],
+                            reason: "invalid_format",
+                            message: reply.message,
+                        },
+                    ]);
+                if (reply.reason === "input-limit")
+                    throw new AnalysisInputError(OPERATION, undefined, [
+                        {
+                            path: ["capture_path", reply.pointer],
+                            reason: "out_of_range",
+                            message: reply.message,
+                            expected: {
+                                maximum_capture_nesting: WEB_NETWORK_CAPTURE_LIMITS.depth,
+                            },
+                        },
+                    ]);
+                if (reply.reason === "resource-limit")
+                    throw captureMemoryFailure(input, reply.message);
+                if (reply.reason === "decoder")
+                    throw new ProviderAdapterError(input.format, OPERATION, {
+                        diagnostics: {
+                            phase: "decoder",
+                            failure_kind: reply.reason,
+                            reason: reply.message,
+                            pointer: reply.pointer,
+                        },
+                    });
+                if (reply.reason === "unsupported")
+                    throw new AnalysisCapabilityUnavailableError(input.format, OPERATION, reply.message);
+                throw new AnalysisOutputError(OPERATION, reply.message);
+            }
+            if (reply.value.decoder.id !== adapter.identity.id ||
+                reply.value.decoder.name !== adapter.identity.name ||
+                reply.value.decoder.version !== adapter.identity.version)
+                throw new AnalysisOutputError(OPERATION, "Capture decoder changed the selected upstream profile identity.");
+            result = ok({
+                ...reply.value,
+                artifact: {
+                    path: input.capture_path,
+                    sha256: snapshot.sha256,
+                    bytes: snapshot.bytes.length,
+                },
+                format: input.format,
+                runtime_attribution: "unknown",
+                limitations: [
+                    "This is retained producer evidence, without live browser transaction IDs, scenario provenance, execution attribution or deployment authenticity. Recorded URLs are never fetched.",
+                    "Every record is decoded before selection; no partial success is returned on malformed input or a resource limit.",
+                    "Known authentication headers/cookies and explicitly marked literal values are excluded. Unknown extension names do not establish sensitivity.",
+                    "A 32 MiB input, 96 MiB reply and 64-level nesting budget bound complete evidence. HAR uses a 192 MiB Node old-generation heap; native decoding uses a 768 MiB Linux address-space limit. Each owned command has a 30-second deadline with independent cleanup.",
+                ],
+            });
+        }
+        catch (cause) {
+            result = err(redactExplicitFailure(historicalCaptureFailure(input, cause, phase, options), input.sensitive_values));
+        }
+        if (runtime !== undefined) {
+            try {
+                await runtime.close();
+            }
+            catch (cause) {
+                return err(redactExplicitFailure(new ProviderCleanupError(input.format, [runtime.path], {
+                    capture_path: input.capture_path,
+                    previous_error: result.ok
+                        ? null
+                        : projectAnalysisError(result.error),
+                    reason: cause instanceof Error ? cause.message : String(cause),
+                }, { operation: OPERATION }), input.sensitive_values));
+            }
+        }
+        return result.ok && options?.signal?.aborted
+            ? err(new AnalysisCancelledError(OPERATION))
+            : result;
+    }
+}
+const replyFailureReason = (cause) => {
+    if (cause instanceof ArtifactReaderFailure)
+        return cause.message;
+    if (cause instanceof z.ZodError)
+        return `Reply violates its schema at ${cause.issues[0]?.path.map(String).join(".") ?? "root"}.`;
+    if (cause instanceof SyntaxError)
+        return "Reply is malformed JSON.";
+    if (cause instanceof Error && "code" in cause)
+        return `Reply file could not be read (${String(cause.code)}).`;
+    return "Reply could not be validated.";
+};

package/dist/browser/history/HistoricalCaptureFormatAdapter.js

@@ -0,0 +1 @@
+export {};

package/dist/browser/history/MitmproxyCaptureAdapter.js

@@ -0,0 +1,42 @@
+import { access } from "node:fs/promises";
+import { constants } from "node:fs";
+import { isAbsolute } from "node:path";
+import { fileURLToPath } from "node:url";
+import { AnalysisCapabilityUnavailableError } from "../../domain/analysisErrorCore.js";
+import { MITMPROXY_CAPTURE_PROVIDER_IDENTITY } from "./CaptureRelease.js";
+const OPERATION = "inspect_web_network_capture";
+/** Native mitmproxy decoding is offline and uses only an explicitly configured Linux tool. */
+export class MitmproxyCaptureAdapter {
+    environment;
+    format = "mitmproxy";
+    identity = MITMPROXY_CAPTURE_PROVIDER_IDENTITY;
+    constructor(environment) {
+        this.environment = environment;
+    }
+    async command(requestPath, runtimePath) {
+        const command = this.environment.REA_MITMDUMP_COMMAND;
+        if (process.platform !== "linux" ||
+            command === undefined ||
+            !isAbsolute(command))
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, "Native capture decoding requires Linux and an absolute REA_MITMDUMP_COMMAND path to caller-supplied mitmdump 12.2.3; HAR needs no external engine.");
+        try {
+            await access(command, constants.R_OK | constants.X_OK);
+        }
+        catch (cause) {
+            throw new AnalysisCapabilityUnavailableError("mitmproxy", OPERATION, `Configured mitmdump executable is unavailable: ${command}.`, { cause });
+        }
+        return {
+            command,
+            arguments: [
+                "--no-server",
+                "-q",
+                "--set",
+                `confdir=${runtimePath}`,
+                "--set",
+                `rea_request_path=${requestPath}`,
+                "-s",
+                fileURLToPath(new URL("../../../bridge/mitmproxy/capture.py", import.meta.url)),
+            ],
+        };
+    }
+}

package/dist/cli/analysisSelector.js

@@ -0,0 +1,23 @@
+import { AnalysisInputError } from "../domain/analysisErrorCore.js";
+/** Preserve a CLI selector supplied positionally or through its named option. */
+export const resolveCliAnalysisSelector = (positional, named, option, operation) => {
+    if (positional !== undefined && named !== undefined && positional !== named)
+        throw new AnalysisInputError(operation, undefined, [
+            {
+                path: [option],
+                reason: "invalid_value",
+                message: `The positional selector and --${option} select different objects; supply one selector.`,
+            },
+        ]);
+    const selected = named ?? positional;
+    if (selected === undefined)
+        throw new AnalysisInputError(operation, undefined, [
+            {
+                path: [option],
+                reason: "missing_argument",
+                message: `Supply a positional selector or --${option}=<value>. Use the named option for values beginning with a dash.`,
+                expected: "string",
+            },
+        ]);
+    return selected;
+};

package/dist/cli/applicationCommands.js

@@ -9,7 +9,6 @@ import { buildReconstructionObligationLedgerEvidenceValidated } from "../applica
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { parseCliJsonInput } from "../cliJsonInput.js";
 import { logCliCommand } from "../cliLogging.js";
-import { AnalysisInputError } from "../domain/analysisErrorCore.js";
 import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
 import {} from "../domain/analysisErrorBase.js";
 import { androidApplicationProjectionInputSchema } from "../domain/android/androidApplication.js";
@@ -20,7 +19,7 @@ import { traceJavaScriptSemanticsInputSchema } from "../domain/javascript/javasc
 import { compareApplicationVersionsInputSchema } from "../domain/javascript/javascriptApplicationVersionComparisonSchemas.js";
 import { compareSourceToBundleInputSchema } from "../domain/javascript/sourceToBundleComparisonSchemas.js";
 import { compareJavaScriptExportShapesInputSchema } from "../domain/javascript/javascriptExportShapeComparisonSchemas.js";
-import { projectInputIssues } from "../domain/inputIssueProjection.js";
+import { analysisInputErrorFromIssues } from "../domain/inputIssueProjection.js";
 import { reconstructionObligationLedgerInputSchema } from "../domain/reconstructionObligationLedgerSchemas.js";
 /** Register CLI equivalents of provider-neutral application graph workflows. */
 export const registerApplicationCommands = (cli, logger) => {
@@ -133,7 +132,7 @@ const registerJsonCommand = ({ cli, logger, name, description, inputSchema, work
             if (!parsed.success)
                 return {
                     error: "Application workflow failed",
-                    ...projectAnalysisError(new AnalysisInputError(name, undefined, projectInputIssues(parsed.error.issues, input.value))),
+                    ...projectAnalysisError(analysisInputErrorFromIssues(name, parsed.error.issues, input.value)),
                 };
             const result = workflow(parsed.data);
             return result.ok

package/dist/cli/artifactCommands.js

@@ -1,6 +1,6 @@
 import { z } from "incur";
 import { runProviderAnalysis } from "../composition/directAnalysis.js";
-import { createArtifactExtractionDestination } from "../application/ArtifactExtractionDestination.js";
+import { createArtifactExtractionDestination } from "../application/artifacts/ArtifactExtractionDestination.js";
 import { logCliCommand } from "../cliLogging.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 export const registerArtifactCommands = (cli, logger) => {
@@ -8,6 +8,7 @@ export const registerArtifactCommands = (cli, logger) => {
     registerExtractionCommand(cli, logger);
     registerInterfaceBuilderCommand(cli, logger);
     registerAssetCatalogCommand(cli, logger);
+    registerDylibResolutionCommand(cli, logger);
     cli.command(CLI_COMMANDS.inspectKeyedArchive, {
         description: "Inspect a Foundation keyed archive as an object-reference graph",
         args: z.object({
@@ -41,6 +42,30 @@ export const registerArtifactCommands = (cli, logger) => {
         }, logger)),
     });
 };
+const registerDylibResolutionCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.traceDylibResolution, {
+        description: "Trace dyld load-path resolution for a Mach-O or every executable in an app bundle",
+        args: z.object({
+            path: z.string().describe("Mach-O file or Apple .app bundle path"),
+        }),
+        options: z.object({
+            root: z
+                .array(z.string())
+                .optional()
+                .describe("Process root relative to the bundle or the Mach-O's directory (repeatable)"),
+            architecture: z
+                .enum(["arm64", "arm64e", "x86_64"])
+                .optional()
+                .describe("Trace only this slice of each root"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.traceDylibResolution, () => runProviderAnalysis(args.path, "trace_dylib_resolution", {
+            ...(options.root === undefined ? {} : { roots: options.root }),
+            ...(options.architecture === undefined
+                ? {}
+                : { architecture: options.architecture }),
+        }, logger)),
+    });
+};
 const registerAssetCatalogCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.inspectAssetCatalog, {
         description: "Inspect compiled Apple asset catalog metadata",

package/dist/cli/binaryDiagnosticsCommands.js

@@ -0,0 +1,39 @@
+import { z } from "incur";
+import { resolve } from "node:path";
+import { createRecordedCrashService, createBinaryLayoutService, } from "../composition/binaryDiagnostics.js";
+import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { logCliCommand } from "../cliLogging.js";
+import { projectAnalysisError } from "../domain/analysisErrorProjection.js";
+import { withCommandCancellation } from "./commandCancellation.js";
+/** Inspect operator-selected files through the same shared workflow as MCP. */
+export const registerBinaryDiagnosticsCommands = (cli, logger, environment) => {
+    const service = createBinaryLayoutService(environment);
+    cli.command(CLI_COMMANDS.inspectBinaryLayout, {
+        description: "Inspect binary file/linked layout without executing the selected object",
+        args: z.object({
+            path: z.string().describe("Local ELF binary or relocatable object"),
+        }),
+        run: ({ args }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectBinaryLayout, async () => {
+            const result = await service.inspect({ path: resolve(args.path) }, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        })),
+    });
+    const recorded = createRecordedCrashService(environment);
+    cli.command(CLI_COMMANDS.inspectRecordedCrash, {
+        description: "Inspect supplied core registers/signals and optional debugger mapping evidence",
+        args: z.object({ path: z.string().describe("Local Linux amd64 ELF core") }),
+        options: z.object({
+            debuggerContext: z
+                .boolean()
+                .default(false)
+                .describe("Add BYO core-only GDB/pwndbg mapping candidates"),
+        }),
+        run: ({ args, options }) => withCommandCancellation((signal) => logCliCommand(logger, CLI_COMMANDS.inspectRecordedCrash, async () => {
+            const result = await recorded.inspect({
+                path: resolve(args.path),
+                include_debugger_context: options.debuggerContext,
+            }, { signal });
+            return result.ok ? result.value : projectAnalysisError(result.error);
+        })),
+    });
+};

package/dist/cli/coreAnalysisCommands.js

@@ -1,7 +1,7 @@
 import { registerCoreBinaryCommands } from "./coreBinaryCommands.js";
 import { registerCoreNativeCommands } from "./coreNativeCommands.js";
 /** Register core binary and native deep-analysis CLI commands. */
-export const registerCoreAnalysisCommands = (cli, logger) => {
-    registerCoreBinaryCommands(cli, logger);
+export const registerCoreAnalysisCommands = (cli, logger, resultOutput) => {
+    registerCoreBinaryCommands(cli, logger, resultOutput);
     registerCoreNativeCommands(cli, logger);
 };

package/dist/cli/coreBinaryCommands.js

@@ -1,21 +1,23 @@
 import { z } from "incur";
 import { stat } from "node:fs/promises";
 import { resolve } from "node:path";
+import { resolveCliAnalysisSelector } from "./analysisSelector.js";
 import { runDirectAnalysis } from "../composition/directAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, formatSelectionOption, providerSelectionOption, } from "./options.js";
 import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 /** Register provider-neutral binary overview and procedure CLI commands. */
-export const registerCoreBinaryCommands = (cli, logger) => {
-    registerOverviewCommands(cli, logger);
+export const registerCoreBinaryCommands = (cli, logger, resultOutput) => {
+    registerOverviewCommands(cli, logger, resultOutput);
+    registerDecompileCommand(cli, logger);
     registerFunctionCommand(cli, logger);
     registerInstructionsCommand(cli, logger);
     registerSearchCommand(cli, logger);
     registerXrefsCommand(cli, logger);
     registerTraceCommand(cli, logger);
 };
-const registerOverviewCommands = (cli, logger) => {
+const registerOverviewCommands = (cli, logger, resultOutput) => {
     const overviewOptions = z.object({
         snapshot: z
             .string()
@@ -31,7 +33,9 @@ const registerOverviewCommands = (cli, logger) => {
             path: z.string().describe("App, program, or analysis database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runRoutedOverview(args.path, options, logger)),
+        run: ({ args, options, format }) => logCliCommand(logger, "analyze", () => runRoutedOverview(args.path, options, logger, resultOutput === undefined
+            ? undefined
+            : { output: resultOutput, command: CLI_COMMANDS.analyze, format })),
     });
     cli.command(CLI_COMMANDS.inspect, {
         description: "Inspect an app overview with evidence",
@@ -41,13 +45,24 @@ const registerOverviewCommands = (cli, logger) => {
         options: overviewOptions,
         run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
+};
+const registerDecompileCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.decompile, {
         description: "Read one part of an app as code",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -56,17 +71,17 @@ const registerOverviewCommands = (cli, logger) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", {
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "procedure_pseudo_code"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
-const runRoutedOverview = async (path, options, logger) => {
+const runRoutedOverview = async (path, options, logger, output) => {
     if (options.provider === undefined &&
         options.snapshot === undefined &&
         options["target-format"] === undefined &&
         (await isJavaScriptApplicationPath(path)))
-        return runCliJavaScriptApplicationAnalysis({
-            input_path: resolve(path),
-        });
+        return runCliJavaScriptApplicationAnalysis({ input_path: resolve(path) }, output);
     return runDirectAnalysis(path, "binary_overview", {}, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]));
 };
 const isJavaScriptApplicationPath = async (path) => {
@@ -90,9 +105,14 @@ const registerXrefsCommand = (cli, logger) => {
         description: "List bounded references to an analyzed address",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Hexadecimal address"),
+            address: z.string().min(1).optional().describe("Address or symbol name"),
         }),
         options: z.object({
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Address or symbol name; use --address=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -101,7 +121,9 @@ const registerXrefsCommand = (cli, logger) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", {
+            address: resolveCliAnalysisSelector(args.address, options.address, "address", "xrefs"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
 const registerTraceCommand = (cli, logger) => {
@@ -109,9 +131,14 @@ const registerTraceCommand = (cli, logger) => {
         description: "Trace a literal feature through analyzed references",
         args: z.object({
             path: z.string().describe("App or program path"),
-            query: z.string().min(1).describe("Literal feature query"),
+            query: z.string().min(1).optional().describe("Literal feature query"),
         }),
         options: z.object({
+            query: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Complete literal feature query; use --query=<value> for leading dashes"),
             caseSensitive: z
                 .boolean()
                 .default(false)
@@ -128,7 +155,7 @@ const registerTraceCommand = (cli, logger) => {
             caseSensitive: "case-sensitive",
         },
         run: ({ args, options }) => logCliCommand(logger, "trace", () => runDirectAnalysis(args.path, "trace_feature", {
-            query: args.query,
+            query: resolveCliAnalysisSelector(args.query, options.query, "query", "trace_feature"),
             case_sensitive: options.caseSensitive,
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
@@ -138,9 +165,18 @@ const registerFunctionCommand = (cli, logger) => {
         description: "Analyze one complete function with evidence",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure name or address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -149,7 +185,9 @@ const registerFunctionCommand = (cli, logger) => {
             "target-format": formatSelectionOption,
             provider: providerSelectionOption,
         }),
-        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
+        run: ({ args, options }) => logCliCommand(logger, "function", () => runDirectAnalysis(args.path, "analyze_function", {
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "analyze_function"),
+        }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
 const registerInstructionsCommand = (cli, logger) => {
@@ -157,9 +195,18 @@ const registerInstructionsCommand = (cli, logger) => {
         description: "Read every raw instruction without decompiling",
         args: z.object({
             path: z.string().describe("App or program path"),
-            address: z.string().describe("Procedure name or address"),
+            address: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address"),
         }),
         options: z.object({
+            procedure: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Procedure name or address; use --procedure=<value> for leading dashes"),
             snapshot: z
                 .string()
                 .min(1)
@@ -169,7 +216,7 @@ const registerInstructionsCommand = (cli, logger) => {
             provider: providerSelectionOption,
         }),
         run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.instructions, () => runDirectAnalysis(args.path, "read_function_instructions", {
-            procedure: args.address,
+            procedure: resolveCliAnalysisSelector(args.address, options.procedure, "procedure", "read_function_instructions"),
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),
     });
 };
@@ -178,9 +225,18 @@ const registerSearchCommand = (cli, logger) => {
         description: "Search every analyzed string or procedure name",
         args: z.object({
             path: z.string().describe("App or program path"),
-            pattern: z.string().min(1).describe("Literal text or regex pattern"),
+            pattern: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Literal text or regex pattern"),
         }),
         options: z.object({
+            pattern: z
+                .string()
+                .min(1)
+                .optional()
+                .describe("Complete literal text or regex pattern; use --pattern=<value> for leading dashes"),
             kind: z
                 .enum(["strings", "procedures"])
                 .default("strings")
@@ -203,7 +259,9 @@ const registerSearchCommand = (cli, logger) => {
         }),
         alias: { caseSensitive: "case-sensitive" },
         run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
-            pattern: args.pattern,
+            pattern: resolveCliAnalysisSelector(args.pattern, options.pattern, "pattern", options.kind === "strings"
+                ? "search_strings"
+                : "search_procedures"),
             mode: options.mode,
             case_sensitive: options.caseSensitive,
         }, directAnalysisOptions(logger, options.snapshot, options.provider, options["target-format"]))),