rea-agents 2.2.0 → 2.3.0

package/dist/cli/coreAnalysisCommands.js

@@ -1,8 +1,11 @@
 import { z } from "incur";
+import { stat } from "node:fs/promises";
+import { resolve } from "node:path";
 import { runDirectAnalysis } from "../application/DirectAnalysis.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
 import { logCliCommand } from "../cliLogging.js";
 import { directAnalysisOptions, providerSelectionOption } from "./options.js";
+import { runCliJavaScriptApplicationAnalysis } from "./javascriptApplicationAnalysis.js";
 export const registerCoreAnalysisCommands = (cli, logger) => {
     registerCoreCommands(cli, logger);
     registerFunctionCommand(cli, logger);
@@ -30,13 +33,19 @@ const registerCoreCommands = (cli, logger) => {
             .describe("Load and update a local analysis snapshot"),
         provider: providerSelectionOption,
     });
+    const analyzeOptions = overviewOptions.extend({
+        approved: z
+            .boolean()
+            .default(false)
+            .describe("Approve static analysis when the path is a JavaScript directory or ASAR"),
+    });
     cli.command(CLI_COMMANDS.analyze, {
         description: "Get an overview of an app",
         args: z.object({
             path: z.string().describe("App, program, or analysis database path"),
         }),
-        options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, directAnalysisOptions(logger, options.snapshot, options.provider))),
+        options: analyzeOptions,
+        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runRoutedOverview(args.path, options, logger)),
     });
     cli.command(CLI_COMMANDS.inspect, {
         description: "Inspect an app overview with evidence",
@@ -63,6 +72,29 @@ const registerCoreCommands = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, directAnalysisOptions(logger, options.snapshot, options.provider))),
     });
 };
+const runRoutedOverview = async (path, options, logger) => {
+    if (options.provider === undefined &&
+        options.snapshot === undefined &&
+        (await isJavaScriptApplicationPath(path)))
+        return runCliJavaScriptApplicationAnalysis({
+            input_path: resolve(path),
+            approved: options.approved,
+        });
+    return runDirectAnalysis(path, "binary_overview", { detail: options.detail, limit: options.limit }, directAnalysisOptions(logger, options.snapshot, options.provider));
+};
+const isJavaScriptApplicationPath = async (path) => {
+    const lower = path.toLowerCase();
+    if (lower.endsWith(".asar"))
+        return true;
+    if (lower.endsWith(".app"))
+        return false;
+    try {
+        return (await stat(path)).isDirectory();
+    }
+    catch {
+        return false;
+    }
+};
 const registerXrefsCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.xrefs, {
         description: "List bounded references to an analyzed address",

package/dist/cli/javascriptApplicationAnalysis.js

@@ -0,0 +1,19 @@
+import { analyzeJavaScriptApplication } from "../application/JavaScriptApplicationService.js";
+import { loadConfiguredPermissionAuthority } from "../application/PermissionConfiguration.js";
+import { parseConfig } from "../config.js";
+import { projectAnalysisError } from "../domain/errors.js";
+/** Execute the shared one-shot CLI boundary for static JavaScript analysis. */
+export const runCliJavaScriptApplicationAnalysis = async (input) => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return cliError(config.error);
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    if (!authority.ok)
+        return cliError(authority.error);
+    const result = await analyzeJavaScriptApplication(authority.value, input);
+    return result.ok ? result.value : cliError(result.error);
+};
+const cliError = (error) => ({
+    error: "JavaScript application analysis failed",
+    ...projectAnalysisError(error),
+});

package/dist/cli/setupCommands.js

@@ -1,6 +1,6 @@
 import { z } from "incur";
-import { runDoctor } from "../application/Doctor.js";
-import { runSetup, systemSetupHost } from "../application/Setup.js";
+import { DOCTOR_PROVIDER_IDS, runDoctor, } from "../application/Doctor.js";
+import { runSetup, systemSetupHost, } from "../application/Setup.js";
 import { runUninstall } from "../application/Uninstall.js";
 import { runUpgrade, systemUpgradeHost } from "../application/Upgrade.js";
 import { conciseSetupResult, confirmInteractiveSetup, renderInteractiveSetupResult, renderSetupProgress, } from "../cliSetup.js";
@@ -8,7 +8,19 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 import { logCliCommand } from "../cliLogging.js";
 import { createSystemDoctorHost } from "../doctorRuntime.js";
 import { CLI_COMMANDS } from "../cliCommandNames.js";
+import { SUPPORTED_CLIENT_DEFINITIONS } from "../application/SupportedClients.js";
+import { projectDoctorReport } from "../application/DoctorProjection.js";
+const supportedClientIds = SUPPORTED_CLIENT_DEFINITIONS.map(({ name }) => name);
+const supportedClientSchema = z
+    .string()
+    .refine((candidate) => supportedClientIds.some((name) => name === candidate), "Unsupported agent integration");
+/** Register setup, doctor, uninstall, and upgrade CLI commands. */
 export const registerSetupCommands = (cli, logger) => {
+    registerSetupCommand(cli, logger);
+    registerDoctorCommand(cli, logger);
+    registerMaintenanceCommands(cli, logger);
+};
+const registerSetupCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.setup, {
         description: "Install requirements and configure agents",
         outputPolicy: "agent-only",
@@ -22,14 +34,7 @@ export const registerSetupCommands = (cli, logger) => {
                 .default(false)
                 .describe("Also approve Hopper installation with --yes"),
             client: z
-                .array(z.enum([
-                "claude_code",
-                "claude_desktop",
-                "codex",
-                "cursor",
-                "gemini_cli",
-                "windsurf",
-            ]))
+                .array(supportedClientSchema)
                 .default([])
                 .describe("Agent integration to configure; repeat for multiple agents"),
             allDetected: z
@@ -48,17 +53,41 @@ export const registerSetupCommands = (cli, logger) => {
                 .boolean()
                 .default(false)
                 .describe("Use sequential accessible setup prompts"),
+            detail: z
+                .enum(["summary", "full"])
+                .default("summary")
+                .describe("Summary or complete setup and doctor diagnostics"),
         }),
         alias: { yes: "y" },
-        run: ({ options, formatExplicit, agent }) => logCliCommand(logger, "setup", () => runSetupCommand({ options, formatExplicit, agent })),
+        run: ({ options, formatExplicit }) => logCliCommand(logger, "setup", () => runSetupCommand({ options, formatExplicit })),
     });
+};
+const registerDoctorCommand = (cli, logger) => {
     cli.command(CLI_COMMANDS.doctor, {
         description: "Check whether REA is ready",
         options: z.object({
             target: z.string().optional().describe("Optional app path to check"),
+            client: z
+                .array(supportedClientSchema)
+                .default([])
+                .describe("Agent registration whose readiness is required; repeatable"),
+            provider: z
+                .array(z.enum(DOCTOR_PROVIDER_IDS))
+                .default([])
+                .describe("Deep-analysis provider whose readiness is required"),
+            skill: z
+                .boolean()
+                .optional()
+                .describe("Require the installed REA skill identity to be aligned"),
+            detail: z
+                .enum(["summary", "full"])
+                .default("summary")
+                .describe("Summary or complete doctor diagnostics"),
         }),
-        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost())),
+        run: ({ options }) => logCliCommand(logger, "doctor", () => runDoctor(options.target, createSystemDoctorHost(), doctorScope(options)).then((report) => projectDoctorReport(report, options.detail))),
     });
+};
+const registerMaintenanceCommands = (cli, logger) => {
     cli.command(CLI_COMMANDS.uninstall, {
         description: "Remove REA-owned agent configuration and skill files",
         options: z.object({
@@ -77,37 +106,57 @@ export const registerSetupCommands = (cli, logger) => {
 };
 const runSetupCommand = async (input) => {
     const { options } = input;
-    const interactive = !options.yes &&
-        !options.dryRun &&
-        !input.formatExplicit &&
-        process.stdin.isTTY === true &&
-        process.stderr.isTTY === true;
+    const interactive = setupIsInteractive(options, input.formatExplicit);
     const hasExplicitScope = setupHasExplicitScope(options);
     if (options.yes && !hasExplicitScope)
         process.stderr.write("!  Implicit `rea setup --yes` scope is deprecated; use `--all-detected` to retain it.\n");
+    const result = await runSetup(setupRunOptions(input, interactive, hasExplicitScope), systemSetupHost(createSystemDoctorHost()), interactive
+        ? (actions) => confirmInteractiveSetup(actions, options.accessible)
+        : undefined);
+    if (interactive)
+        renderInteractiveSetupResult(result);
+    return options.detail === "full" ? result : conciseSetupResult(result);
+};
+const setupRunOptions = (input, interactive, hasExplicitScope) => {
+    const { options } = input;
     const agentIntegrationSelected = options.allDetected || options.client.length > 0;
-    const result = await runSetup({
+    const hasSelectedClients = hasExplicitScope && !options.allDetected;
+    return {
         approved: options.yes && !options.dryRun,
         installHopper: options.installHopper,
         structured: input.formatExplicit || options.dryRun,
         proposeHopper: !hasExplicitScope || options.installHopper,
-        ...(!hasExplicitScope || options.allDetected
-            ? {}
-            : { clientIds: options.client }),
-        ...(!hasExplicitScope
-            ? {}
-            : {
-                installSkill: options.skill ?? agentIntegrationSelected,
-            }),
+        ...(hasSelectedClients ? { clientIds: options.client } : {}),
+        ...(hasExplicitScope
+            ? { installSkill: options.skill ?? agentIntegrationSelected }
+            : {}),
         ...(interactive ? { onProgress: renderSetupProgress } : {}),
-    }, systemSetupHost(createSystemDoctorHost()), interactive
-        ? (actions) => confirmInteractiveSetup(actions, options.accessible)
-        : undefined);
-    if (interactive)
-        renderInteractiveSetupResult(result);
-    return input.formatExplicit ? result : conciseSetupResult(result);
+        ...(hasSelectedClients
+            ? {
+                readinessScope: {
+                    clients: options.client,
+                    providers: options.installHopper ? ["hopper"] : [],
+                    skill: options.skill ?? agentIntegrationSelected,
+                },
+            }
+            : {}),
+    };
 };
+const setupIsInteractive = (options, formatExplicit) => !options.yes &&
+    !options.dryRun &&
+    !formatExplicit &&
+    process.stdin.isTTY === true &&
+    process.stderr.isTTY === true;
 const setupHasExplicitScope = (options) => options.allDetected ||
     options.client.length > 0 ||
     options.skill !== undefined ||
     options.installHopper;
+const doctorScope = (options) => options.client.length === 0 &&
+    options.provider.length === 0 &&
+    options.skill === undefined
+    ? undefined
+    : {
+        clients: options.client,
+        providers: options.provider,
+        skill: options.skill === true,
+    };

package/dist/cli/utilityCommands.js

@@ -1,5 +1,5 @@
 import { z } from "incur";
-import { runProviderAnalysis, runSessionStatus, } from "../application/DirectAnalysis.js";
+import { runCapabilityStatus, runProviderAnalysis, runProviderStatus, } from "../application/DirectAnalysis.js";
 import { importReferenceSource } from "../application/ReferenceSourceImport.js";
 import { projectReferenceSourceImportError } from "../application/ReferenceSourceImportTypes.js";
 import { loadConfiguredPermissionAuthority } from "../application/PermissionConfiguration.js";
@@ -22,7 +22,15 @@ const registerCapabilityCommands = (cli, logger) => {
             description: command === "capabilities"
                 ? "List provider capabilities and side effects"
                 : "List configured analysis providers",
-            run: () => logCliCommand(logger, command, () => runSessionStatus(logger)),
+            options: z.object({
+                detail: z
+                    .enum(["summary", "full"])
+                    .default("summary")
+                    .describe("Summary or complete provider descriptors"),
+            }),
+            run: ({ options }) => logCliCommand(logger, command, () => command === CLI_COMMANDS.providers
+                ? runProviderStatus(logger, options.detail)
+                : runCapabilityStatus(logger, options.detail)),
         });
     }
 };

package/dist/cliApplicationCommands.js

@@ -1,5 +1,8 @@
 import { Cli, z } from "incur";
-import { compareApplicationVersionsEvidence, traceApplicationFeatureEvidence, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { compareApplicationVersionsEvidenceValidated, compareJavaScriptExportShapesEvidenceValidated, traceApplicationFeatureEvidenceValidated, } from "./application/JavaScriptApplicationWorkflowService.js";
+import { traceJavaScriptSemanticsEvidenceValidated } from "./application/JavaScriptSemanticTraceService.js";
+import { resolveCompareApplicationVersionsRequest, resolveCompareJavaScriptExportShapesRequest, resolveTraceApplicationFeatureRequest, resolveTraceJavaScriptSemanticsRequest, } from "./application/ApplicationWorkflowEvidenceResolver.js";
+import { readEvidenceBundle } from "./application/EvidenceBundleFiles.js";
 import { runControlledReplay } from "./application/JavaScriptReplayService.js";
 import { executeNodeCharacterization, prepareNodeCharacterization, } from "./application/NodeRuntimeCharacterizationService.js";
 import { commitReconstructionCoverage, queryReconstructionCoverage, reconstructionCoverageCommitInputSchema, reconstructionCoverageQueryInputSchema, } from "./application/ReconstructionCoverageService.js";
@@ -19,14 +22,32 @@ export const registerApplicationCommands = (cli, logger) => {
         logger,
         name: CLI_COMMANDS.traceApplicationFeature,
         description: "Trace a typed seed through authenticated application Evidence JSON",
-        workflow: traceApplicationFeatureEvidence,
+        resolveInput: resolveTraceApplicationFeatureRequest,
+        workflow: traceApplicationFeatureEvidenceValidated,
+    });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.traceJavaScriptSemantics,
+        description: "Trace bounded static semantic relations through authenticated application Evidence",
+        resolveInput: resolveTraceJavaScriptSemanticsRequest,
+        workflow: traceJavaScriptSemanticsEvidenceValidated,
     });
     registerJsonCommand({
         cli,
         logger,
         name: CLI_COMMANDS.compareApplicationVersions,
         description: "Compare two authenticated JavaScript Application Graph versions",
-        workflow: compareApplicationVersionsEvidence,
+        resolveInput: resolveCompareApplicationVersionsRequest,
+        workflow: compareApplicationVersionsEvidenceValidated,
+    });
+    registerJsonCommand({
+        cli,
+        logger,
+        name: CLI_COMMANDS.compareJavaScriptExportShapes,
+        description: "Compare exact static JavaScript export return shapes without execution",
+        resolveInput: resolveCompareJavaScriptExportShapesRequest,
+        workflow: compareJavaScriptExportShapesEvidenceValidated,
     });
     cli.command(CLI_COMMANDS.runControlledReplay, {
         description: "Plan or execute an approved extracted-module replay in the Linux sandbox",
@@ -138,13 +159,10 @@ const registerCoverageCommands = (cli, logger) => {
     });
 };
 const configuredAuthority = async () => {
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        return { ok: false, error: projectAnalysisError(config.error) };
-    const authority = await loadConfiguredPermissionAuthority(config.value);
-    return authority.ok
-        ? { ok: true, config: config.value, authority: authority.value }
-        : { ok: false, error: projectAnalysisError(authority.error) };
+    const configured = await loadConfiguredAuthority();
+    return configured.ok
+        ? configured
+        : { ok: false, error: projectAnalysisError(configured.error) };
 };
 const replayDependencies = (config, authority) => ({
     policy: config.javascriptReplayPolicy,
@@ -152,25 +170,70 @@ const replayDependencies = (config, authority) => ({
     runner: new LinuxJavaScriptReplayRunner(),
     authority,
 });
-const registerJsonCommand = ({ cli, logger, name, description, workflow, }) => {
+const registerJsonCommand = ({ cli, logger, name, description, resolveInput, workflow, }) => {
     cli.command(name, {
         description,
         args: z.object({
             inputJson: z.string().describe("Inline workflow JSON or JSON file path"),
         }),
-        run: ({ args }) => logCliCommand(logger, name, async () => {
+        options: z.object({
+            evidenceBundle: z
+                .string()
+                .optional()
+                .describe("Authorized Evidence bundle used to resolve Evidence IDs"),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, name, async () => {
             const input = await parseCliJsonInput(args.inputJson, name);
             if (!input.ok)
                 return input.error;
-            const result = workflow(input.value);
+            const lookup = await loadEvidenceLookup(options.evidenceBundle, name);
+            if (!lookup.ok)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(lookup.error),
+                };
+            const resolved = resolveInput(input.value, lookup.value);
+            if (!resolved.ok)
+                return {
+                    error: "Application workflow failed",
+                    ...projectAnalysisError(resolved.error),
+                };
+            const result = workflow(resolved.value);
             return result.ok
                 ? result.value
                 : {
                     error: "Application workflow failed",
-                    ...projectAnalysisError(result.error instanceof AnalysisInputError
-                        ? result.error
-                        : new AnalysisInputError(name)),
+                    ...projectAnalysisError(result.error),
                 };
         }),
     });
 };
+const loadEvidenceLookup = async (bundlePath, operation) => {
+    if (bundlePath === undefined)
+        return { ok: true, value: undefined };
+    const configured = await loadConfiguredAuthority();
+    if (!configured.ok)
+        return configured;
+    const authorized = await authorizeRootPermission(configured.authority, {
+        capability: "evidence_read",
+        roots: [bundlePath],
+        access: "read",
+        operation,
+    });
+    if (!authorized.ok)
+        return authorized;
+    const loaded = await readEvidenceBundle(bundlePath, configured.config.evidenceFilePolicy);
+    if (!loaded.ok)
+        return loaded;
+    const records = new Map(loaded.value.records.map((record) => [record.evidence_id, record]));
+    return { ok: true, value: (evidenceId) => records.get(evidenceId) };
+};
+const loadConfiguredAuthority = async () => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return config;
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    return authority.ok
+        ? { ok: true, config: config.value, authority: authority.value }
+        : authority;
+};

package/dist/cliCommandNames.js

@@ -49,7 +49,10 @@ export const CLI_COMMANDS = Object.freeze({
     analyzeJavaScriptApplication: "analyze-javascript-application",
     reconcileJavaScriptRuntime: "reconcile-javascript-runtime",
     traceApplicationFeature: "trace-application-feature",
+    traceJavaScriptSemantics: "trace-javascript-semantics",
     compareApplicationVersions: "compare-application-versions",
+    compareJavaScriptExportShapes: "compare-javascript-export-shapes",
+    runReplayMachine: "run-replay-machine",
     runControlledReplay: "run-controlled-replay",
     prepareNodeCharacterization: "prepare-node-characterization",
     executeNodeCharacterization: "execute-node-characterization",

package/dist/cliElectronCommands.js

@@ -1,17 +1,16 @@
 import { Cli, z } from "incur";
 import { inspectElectronPage, listElectronTargets, } from "./application/ElectronObservationService.js";
-import { analyzeJavaScriptApplication } from "./application/JavaScriptApplicationService.js";
 import { reconcileJavaScriptRuntimeEvidence } from "./application/JavaScriptRuntimeReconciliationService.js";
 import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 import { CdpElectronProvider } from "./browser/CdpElectronProvider.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
 import { inspectElectronPageInputSchema, listElectronTargetsInputSchema, } from "./domain/electronObservation.js";
-import { analyzeJavaScriptApplicationInputSchema } from "./domain/javascriptApplicationAnalysis.js";
 import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
 import { parseCliJsonInput } from "./cliJsonInput.js";
 import { electronPageInspectionOptions, javascriptApplicationOptions, } from "./cliObservationOptions.js";
+import { runCliJavaScriptApplicationAnalysis } from "./cli/javascriptApplicationAnalysis.js";
 const scopeOptions = {
     allowedFileRoots: z
         .array(z.string().min(1))
@@ -134,37 +133,28 @@ const registerJavaScriptApplicationCommand = (cli, logger) => {
             path: z.string().describe("Absolute ASAR or extracted application path"),
         }),
         options: javascriptApplicationOptions,
-        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, async () => {
-            const context = await electronContext();
-            if (!context.ok)
-                return context.error;
-            const parsed = analyzeJavaScriptApplicationInputSchema.safeParse({
-                input_path: args.path,
-                approved: options.approved,
-                format: options.format,
-                source_map_read_approved: options.sourceMapReadApproved,
-                limits: {
-                    max_entries: options.maxEntries,
-                    max_total_artifact_bytes: options.maxTotalArtifactBytes,
-                    max_artifact_entry_bytes: options.maxArtifactEntryBytes,
-                    max_compression_ratio: options.maxCompressionRatio,
-                    max_depth: options.maxDepth,
-                    max_path_bytes: options.maxPathBytes,
-                    max_text_files: options.maxTextFiles,
-                    max_total_text_bytes: options.maxTotalTextBytes,
-                    max_text_file_bytes: options.maxTextFileBytes,
-                    max_ast_nodes: options.maxAstNodes,
-                    max_findings: options.maxFindings,
-                    max_modules: options.maxModules,
-                    max_source_map_sources: options.maxSourceMapSources,
-                    max_parse_milliseconds: options.maxParseMilliseconds,
-                },
-            });
-            if (!parsed.success)
-                return inputError("analyze_javascript_application");
-            const result = await analyzeJavaScriptApplication(context.authority, parsed.data);
-            return result.ok ? result.value : cliError(result.error);
-        }),
+        run: ({ args, options }) => logCliCommand(logger, CLI_COMMANDS.analyzeJavaScriptApplication, () => runCliJavaScriptApplicationAnalysis({
+            input_path: args.path,
+            approved: options.approved,
+            format: options.artifactFormat,
+            source_map_read_approved: options.sourceMapReadApproved,
+            limits: {
+                max_entries: options.maxEntries,
+                max_total_artifact_bytes: options.maxTotalArtifactBytes,
+                max_artifact_entry_bytes: options.maxArtifactEntryBytes,
+                max_compression_ratio: options.maxCompressionRatio,
+                max_depth: options.maxDepth,
+                max_path_bytes: options.maxPathBytes,
+                max_text_files: options.maxTextFiles,
+                max_total_text_bytes: options.maxTotalTextBytes,
+                max_text_file_bytes: options.maxTextFileBytes,
+                max_ast_nodes: options.maxAstNodes,
+                max_findings: options.maxFindings,
+                max_modules: options.maxModules,
+                max_source_map_sources: options.maxSourceMapSources,
+                max_parse_milliseconds: options.maxParseMilliseconds,
+            },
+        })),
     });
 };
 const electronContext = async () => {

package/dist/cliObservationOptions.js

@@ -108,7 +108,7 @@ export const javascriptApplicationOptions = z.object({
         .boolean()
         .default(false)
         .describe("Approve reading the application artifact"),
-    format: z
+    artifactFormat: z
         .enum(["auto", "asar", "directory"])
         .default("auto")
         .describe("Application artifact format"),

package/dist/cliOutput.js

@@ -1,4 +1,5 @@
 const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `rea --help`, correct the arguments, then try again.";
+const UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE = "Token windows cannot preserve structured output. Remove --token-limit/--token-offset and use --filter-output or command pagination.";
 const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
 const validationError = (value) => {
     if (!isRecord(value))
@@ -9,6 +10,61 @@ const validationError = (value) => {
         return value.error.code === "VALIDATION_ERROR" ? value.error : undefined;
     return undefined;
 };
+/** Reject text-window controls that would corrupt a structured document. */
+export const validateCliOutputArguments = (arguments_) => {
+    let format = "toon";
+    let tokenWindow = false;
+    for (let index = 0; index < arguments_.length; index += 1) {
+        const argument = arguments_[index];
+        if (argument === "--")
+            break;
+        if (argument === "--json") {
+            format = "json";
+            continue;
+        }
+        if (argument === "--format") {
+            const value = arguments_[index + 1];
+            if (value !== undefined) {
+                format = value;
+                index += 1;
+            }
+            continue;
+        }
+        if (argument?.startsWith("--format=")) {
+            format = argument.slice("--format=".length);
+            continue;
+        }
+        if (argument === "--token-limit" || argument === "--token-offset") {
+            if (arguments_[index + 1] !== undefined) {
+                tokenWindow = true;
+                index += 1;
+            }
+            continue;
+        }
+        if (argument?.startsWith("--token-limit=") ||
+            argument?.startsWith("--token-offset="))
+            tokenWindow = true;
+    }
+    if (tokenWindow &&
+        (format === "json" || format === "jsonl" || format === "yaml"))
+        return {
+            ok: false,
+            format,
+            code: "UNSUPPORTED_OUTPUT_COMBINATION",
+            message: UNSUPPORTED_OUTPUT_COMBINATION_MESSAGE,
+        };
+    return { ok: true };
+};
+/** Render one complete structured error before command execution. */
+export const renderCliOutputArgumentError = (error) => {
+    const value = {
+        ok: false,
+        error: { code: error.code, message: error.message },
+    };
+    if (error.format === "yaml")
+        return `ok: false\nerror:\n  code: ${error.code}\n  message: ${JSON.stringify(error.message)}\n`;
+    return `${JSON.stringify(value)}\n`;
+};
 /** Remove validator internals from Incur's caller-visible CLI output. */
 export const sanitizeCliOutput = (output) => {
     const trimmed = output.trimStart();

package/dist/cliProcessCommands.js

@@ -2,8 +2,13 @@ import { Cli, z } from "incur";
 import { captureProcessScenarioFile, compareProcessEvidenceFiles, } from "./application/ProcessCli.js";
 import { logCliCommand } from "./cliLogging.js";
 import { CLI_COMMANDS } from "./cliCommandNames.js";
+import { parseCliJsonInput } from "./cliJsonInput.js";
+import { replayMachineRunInputSchema, runReplayMachine, } from "./domain/replayMachineRun.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+import { projectInputIssues } from "./domain/inputIssueProjection.js";
 /** Register Process Capture v4 one-shot commands through shared application services. */
 export const registerProcessCommands = (cli, logger) => {
+    registerReplayMachineCommand(cli, logger);
     cli.command(CLI_COMMANDS.captureProcess, {
         description: "Capture one approved Process Capture v4 JSON scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
@@ -14,7 +19,33 @@ export const registerProcessCommands = (cli, logger) => {
         args: z.object({
             left: z.string().describe("Left capture Evidence JSON path"),
             right: z.string().describe("Right capture Evidence JSON path"),
+            traceSpec: z
+                .string()
+                .optional()
+                .describe("Optional partial-order or finite-trace specification path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right, args.traceSpec)),
+    });
+};
+const registerReplayMachineCommand = (cli, logger) => {
+    cli.command(CLI_COMMANDS.runReplayMachine, {
+        description: "Run ordered protocol events directly through a finite replay machine",
+        args: z.object({
+            inputJson: z.string().describe("Inline replay JSON or JSON file path"),
+        }),
+        run: ({ args }) => logCliCommand(logger, CLI_COMMANDS.runReplayMachine, async () => {
+            const input = await parseCliJsonInput(args.inputJson, CLI_COMMANDS.runReplayMachine);
+            if (!input.ok)
+                return input.error;
+            const parsed = replayMachineRunInputSchema.safeParse(input.value);
+            return parsed.success
+                ? runReplayMachine(parsed.data)
+                : {
+                    error: "Process command failed",
+                    ...projectAnalysisError(new AnalysisInputError(CLI_COMMANDS.runReplayMachine, {
+                        cause: parsed.error,
+                    }, projectInputIssues(parsed.error.issues, input.value))),
+                };
         }),
-        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right)),
     });
 };