rea-agents 1.2.0 → 1.3.0

package/dist/application/Uninstall.js

@@ -6,6 +6,13 @@ import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
 import { supportedClients } from "./Setup.js";
+const systemFileSystem = {
+    readText: (path) => readFile(path, "utf8"),
+    copy: (source, destination) => copyFile(source, destination),
+    writeText: (path, contents) => writeFileAtomic(path, contents, { encoding: "utf8" }),
+    stat: (path) => lstat(path),
+    remove: (path) => rm(path, { recursive: true }),
+};
 /** Remove only REA-owned registrations and managed files, optionally including local state. */
 export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
     const items = [];
@@ -27,26 +34,26 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
     };
 };
 /** Create uninstall effects contained to detected client configs and REA-owned paths. */
-export const systemUninstallHost = (home = homedir()) => ({
+export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSystem) => ({
     clients: () => Promise.resolve(supportedClients(home)),
-    removeClient,
-    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill"),
+    removeClient: (client) => removeClient(client, fileSystem),
+    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem),
     purgeData: async () => [
-        await removeManagedPath(join(home, ".rea/cache"), "cache"),
-        await removeManagedPath(join(home, ".rea/state"), "state"),
+        await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
+        await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
     ],
 });
-const removeClient = async (client) => {
+const removeClient = async (client, fileSystem) => {
     if (client.format === "unsupported")
         return item(client.name, "skipped", "This client has no documented local MCP configuration boundary.");
     let original;
     try {
-        original = await readFile(client.configPath, "utf8");
+        original = await fileSystem.readText(client.configPath);
     }
     catch (cause) {
         return isMissing(cause)
             ? item(client.name, "skipped", "Configuration does not exist.")
-            : item(client.name, "failed", "Configuration could not be read.");
+            : item(client.name, "failed", "Configuration could not be read. Check file permissions, then rerun uninstall.");
     }
     let document;
     let key;
@@ -57,7 +64,7 @@ const removeClient = async (client) => {
         servers = optionalObject(document[key]);
     }
     catch {
-        return item(client.name, "failed", "Malformed configuration was preserved without mutation.");
+        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
     }
     const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
     if (registration === undefined)
@@ -69,28 +76,31 @@ const removeClient = async (client) => {
     document[key] = remaining;
     const backupPath = `${client.configPath}.rea.backup`;
     try {
-        await copyFile(client.configPath, backupPath);
+        await fileSystem.copy(client.configPath, backupPath);
     }
     catch {
-        return item(client.name, "failed", "Configuration backup failed; no mutation was attempted.");
+        return item(client.name, "failed", "Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.");
     }
     try {
         const encoded = client.format === "toml"
             ? stringifyToml(document)
             : `${JSON.stringify(document, null, 2)}\n`;
-        await writeFileAtomic(client.configPath, encoded, { encoding: "utf8" });
+        await fileSystem.writeText(client.configPath, encoded);
         const readback = objectSchema.parse(client.format === "toml"
-            ? parseToml(await readFile(client.configPath, "utf8"))
-            : JSON.parse(await readFile(client.configPath, "utf8")));
+            ? parseToml(await fileSystem.readText(client.configPath))
+            : JSON.parse(await fileSystem.readText(client.configPath)));
         if (PRODUCT_IDENTITY.mcpServerKey in optionalObject(readback[key]))
             throw new Error("registration readback mismatch");
         return item(client.name, "removed", `Removed registration from ${client.configPath}.`);
     }
     catch {
-        await writeFileAtomic(client.configPath, original, {
-            encoding: "utf8",
-        }).catch(() => undefined);
-        return item(client.name, "failed", `Configuration update failed; the original was restored and ${backupPath} was retained.`);
+        try {
+            await fileSystem.writeText(client.configPath, original);
+        }
+        catch {
+            return item(client.name, "failed", "Configuration could not be updated or restored. Restore its `.rea.backup` manually, then rerun uninstall.");
+        }
+        return item(client.name, "failed", "Configuration could not be updated. The original was restored and its `.rea.backup` was retained. Repair the configuration or restore the backup, then rerun uninstall.");
     }
 };
 /** Ownership rule for persistent MCP registrations created by REA setup. */
@@ -107,18 +117,18 @@ const isOwnedRegistration = (value) => {
             JSON.stringify(args) ===
                 JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
 };
-const removeManagedPath = async (path, name) => {
+const removeManagedPath = async (path, name, fileSystem) => {
     try {
-        const stats = await lstat(path);
+        const stats = await fileSystem.stat(path);
         if (stats.isSymbolicLink())
-            return item(name, "retained", `Refused to follow symlink ${path}.`);
-        await rm(path, { recursive: true });
+            return item(name, "retained", "REA did not remove this item because its managed path is a symbolic link. Verify the link target before removing it manually.");
+        await fileSystem.remove(path);
         return item(name, "removed", `Removed ${path}.`);
     }
     catch (cause) {
         return isMissing(cause)
             ? item(name, "skipped", `${path} does not exist.`)
-            : item(name, "failed", `${path} could not be removed.`);
+            : item(name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.");
     }
 };
 const item = (name, status, detail) => ({ name, status, detail });

package/dist/application/UnknownEvidence.js

@@ -0,0 +1,33 @@
+import { createEvidence } from "../domain/evidence.js";
+/** Provider identity for analyst-authored residual-unknown mutations. */
+export const UNKNOWN_REGISTRY_PROVIDER = {
+    id: "rea-unknown-registry",
+    name: "REA residual unknown registry",
+    version: "1",
+};
+/** Create immutable evidence for one approved residual-unknown mutation. */
+export const unknownMutationEvidence = (target, input) => createEvidence(target, UNKNOWN_REGISTRY_PROVIDER, {
+    predicateType: "rea.residual-unknown-mutation/v1",
+    operation: "record_unknown",
+    parameters: { domain: input.domain, severity: input.severity },
+    result: {
+        action: "record",
+        question: input.question,
+        required_authority: input.required_authority,
+        required_confidence: input.required_confidence,
+    },
+    confidence: "derived",
+    authority: "analyst-inference",
+    evidenceLinks: unknownEvidenceLinks(input),
+    limitations: [
+        "Registry mutation evidence records analyst intent, not proof of the answer.",
+    ],
+});
+/** Deduplicate evidence links carried by an unknown mutation. */
+export const unknownEvidenceLinks = (input) => [
+    ...input.supporting_evidence_ids,
+    ...input.contradicting_evidence_ids,
+    ...("resolution" in input && input.resolution !== null
+        ? input.resolution.evidence_ids
+        : []),
+].filter((id, index, values) => values.indexOf(id) === index);

package/dist/application/Upgrade.js

@@ -33,7 +33,7 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
             currentVersion,
             latestVersion: latestVersion ?? null,
             reason: "install",
-            remediation: `${UPGRADE_COMMAND} failed.`,
+            remediation: `REA could not update through npm. Check npm registry access and global install permissions, then run: ${UPGRADE_COMMAND}`,
         };
     return {
         status: "upgraded",

package/dist/application/runtime.js

@@ -14,5 +14,5 @@ export const createBinarySession = (config, logger = silentLogger) => {
         new ArtifactProvider(config.artifactNativeMountEnabled),
         new NativeMacOSProvider(),
         new HopperProvider(config, logger),
-    ]));
+    ]), { snapshotsEnabled: config.hopperLoaderArgs.length === 0 });
 };

package/dist/artifacts/ArtifactProvider.js

@@ -5,11 +5,8 @@ import { ARTIFACT_TOOL_CONTRACTS, artifactInventoryInputSchema, artifactExtracti
 import { AnalysisCapabilityUnavailableError, ArtifactOperationError, } from "../domain/errors.js";
 import { err, ok } from "../domain/result.js";
 import { ArtifactReaderFailure, } from "./ArtifactReader.js";
-const IDENTITY = Object.freeze({
-    id: "rea-artifact-graph",
-    name: "REA safe artifact graph provider",
-    version: "1",
-});
+import { ARTIFACT_GRAPH_PROVIDER } from "../application/InvestigationProviders.js";
+const IDENTITY = Object.freeze(ARTIFACT_GRAPH_PROVIDER);
 /** Read-only inventory and exclusively owned extraction provider. */
 export class ArtifactProvider {
     nativeMountEnabled;

package/dist/cli.js

@@ -13,6 +13,9 @@ import { parseConfig } from "./config.js";
 import { importReferenceSource } from "./application/ReferenceSourceImport.js";
 import { registerEvidenceCommands } from "./cliEvidenceCommands.js";
 import { registerProcessCommands } from "./cliProcessCommands.js";
+import { registerInvestigationCommands } from "./cliInvestigationCommands.js";
+import { projectAnalysisError } from "./domain/errors.js";
+import { projectReferenceSourceImportError } from "./application/ReferenceSourceImportTypes.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -24,7 +27,7 @@ export const createCli = () => {
         : parseLogLevel(process.env.REA_LOG_LEVEL));
     const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
         version: process.env.REA_PACKAGE_VERSION ?? "0.0.0-development",
-        description: "Reverse engineer anything from your terminal or coding agent.",
+        description: "Reverse engineer anything from your terminal or agent.",
         mcp: {
             command: PRODUCT_IDENTITY.mcpCommand,
             instructions: "Ask what software, artifact, protocol, or behavior the user wants to understand, then choose the available investigation capabilities that can produce evidence.",
@@ -48,6 +51,7 @@ export const createCli = () => {
     registerCapabilityCommands(cli, logger);
     registerNativeCommands(cli, logger);
     registerArtifactCommands(cli, logger);
+    registerInvestigationCommands(cli, logger);
     registerEvidenceCommands(cli, logger);
     registerReferenceSourceCommand(cli, logger);
     registerProcessCommands(cli, logger);
@@ -57,6 +61,11 @@ const registerCoreCommands = (cli, logger) => {
     const overviewOptions = z.object({
         detail: z.enum(["concise", "detailed"]).default("concise"),
         limit: z.number().int().min(1).max(50).default(10),
+        snapshot: z
+            .string()
+            .min(1)
+            .optional()
+            .describe("Load and update a local analysis snapshot"),
     });
     cli.command("analyze", {
         description: "Get an overview of an app",
@@ -64,7 +73,7 @@ const registerCoreCommands = (cli, logger) => {
             path: z.string().describe("App, program, or Hopper database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+        run: ({ args, options }) => logCliCommand(logger, "analyze", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, { logger, snapshotPath: options.snapshot })),
     });
     cli.command("inspect", {
         description: "Inspect an app overview with evidence",
@@ -72,7 +81,7 @@ const registerCoreCommands = (cli, logger) => {
             path: z.string().describe("App, program, or Hopper database path"),
         }),
         options: overviewOptions,
-        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, logger)),
+        run: ({ args, options }) => logCliCommand(logger, "inspect", () => runDirectAnalysis(args.path, "binary_overview", { detail: options.detail, limit: options.limit }, { logger, snapshotPath: options.snapshot })),
     });
     cli.command("decompile", {
         description: "Read one part of an app as code",
@@ -80,12 +89,13 @@ const registerCoreCommands = (cli, logger) => {
             path: z.string().describe("App or program path"),
             address: z.string().describe("Procedure address"),
         }),
-        run: ({ args }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, logger)),
+        options: z.object({ snapshot: z.string().min(1).optional() }),
+        run: ({ args, options }) => logCliCommand(logger, "decompile", () => runDirectAnalysis(args.path, "procedure_pseudo_code", { procedure: args.address }, { logger, snapshotPath: options.snapshot })),
     });
 };
 const registerSetupCommands = (cli, logger) => {
     cli.command("setup", {
-        description: "Install requirements and configure coding agents",
+        description: "Install requirements and configure agents",
         options: z.object({
             yes: z
                 .boolean()
@@ -153,7 +163,8 @@ const registerXrefsCommand = (cli, logger) => {
             path: z.string().describe("App or program path"),
             address: z.string().describe("Hexadecimal address"),
         }),
-        run: ({ args }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, logger)),
+        options: z.object({ snapshot: z.string().min(1).optional() }),
+        run: ({ args, options }) => logCliCommand(logger, "xrefs", () => runDirectAnalysis(args.path, "xrefs", { address: args.address }, { logger, snapshotPath: options.snapshot })),
     });
 };
 const registerTraceCommand = (cli, logger) => {
@@ -167,6 +178,7 @@ const registerTraceCommand = (cli, logger) => {
             caseSensitive: z.boolean().default(false),
             limit: z.number().int().min(1).max(100).default(20),
             maxOperations: z.number().int().min(1).max(100).default(20),
+            snapshot: z.string().min(1).optional(),
         }),
         alias: {
             caseSensitive: "case-sensitive",
@@ -177,7 +189,7 @@ const registerTraceCommand = (cli, logger) => {
             case_sensitive: options.caseSensitive,
             limit: options.limit,
             max_operations: options.maxOperations,
-        }, logger)),
+        }, { logger, snapshotPath: options.snapshot })),
     });
 };
 const registerCapabilityCommands = (cli, logger) => {
@@ -202,6 +214,7 @@ const registerFunctionCommand = (cli, logger) => {
             limit: z.number().int().min(1).max(500).default(100),
             maxPseudocodeChars: z.number().int().min(1).max(100_000).default(20_000),
             maxInstructions: z.number().int().min(1).max(5_000).default(500),
+            snapshot: z.string().min(1).optional(),
         }),
         alias: {
             includeAssembly: "include-assembly",
@@ -214,7 +227,7 @@ const registerFunctionCommand = (cli, logger) => {
             limit: options.limit,
             max_pseudocode_chars: options.maxPseudocodeChars,
             max_instructions: options.maxInstructions,
-        }, logger)),
+        }, { logger, snapshotPath: options.snapshot })),
     });
 };
 const registerSearchCommand = (cli, logger) => {
@@ -230,6 +243,7 @@ const registerSearchCommand = (cli, logger) => {
             caseSensitive: z.boolean().default(false),
             offset: z.number().int().min(0).default(0),
             limit: z.number().int().min(1).max(100).default(100),
+            snapshot: z.string().min(1).optional(),
         }),
         alias: { caseSensitive: "case-sensitive" },
         run: ({ args, options }) => logCliCommand(logger, "search", () => runDirectAnalysis(args.path, options.kind === "strings" ? "search_strings" : "search_procedures", {
@@ -238,7 +252,7 @@ const registerSearchCommand = (cli, logger) => {
             case_sensitive: options.caseSensitive,
             offset: options.offset,
             limit: options.limit,
-        }, logger)),
+        }, { logger, snapshotPath: options.snapshot })),
     });
 };
 const registerReferenceSourceCommand = (cli, logger) => {
@@ -252,7 +266,10 @@ const registerReferenceSourceCommand = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "import-reference-source", async () => {
             const config = parseConfig(process.env);
             if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
+                return {
+                    error: "Import failed",
+                    ...projectAnalysisError(config.error),
+                };
             const imported = await importReferenceSource({
                 root: args.root,
                 caller: "rea-cli",
@@ -262,7 +279,10 @@ const registerReferenceSourceCommand = (cli, logger) => {
             });
             return imported.ok
                 ? imported.value
-                : { error: imported.error.code, message: imported.error.message };
+                : {
+                    error: "Import failed",
+                    ...projectReferenceSourceImportError(imported.error),
+                };
         }),
     });
 };

package/dist/cliEvidenceCommands.js

@@ -2,6 +2,7 @@ import { Cli, z } from "incur";
 import { compareEvidenceBundlesCommand, exportEvidenceBundleCommand, importEvidenceBundleCommand, } from "./application/EvidenceBundleCommands.js";
 import { parseConfig } from "./config.js";
 import { logCliCommand } from "./cliLogging.js";
+import { projectAnalysisError } from "./domain/errors.js";
 /** Register filesystem-gated Evidence v2 commands. */
 export const registerEvidenceCommands = (cli, logger) => {
     cli.command("evidence-import", {
@@ -12,11 +13,9 @@ export const registerEvidenceCommands = (cli, logger) => {
         run: ({ args }) => logCliCommand(logger, "evidence-import", async () => {
             const config = parseConfig(process.env);
             if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
+                return cliError(config.error);
             const imported = await importEvidenceBundleCommand(args.path, config.value.evidenceFilePolicy);
-            return imported.ok
-                ? imported.value
-                : { error: imported.error._tag, message: imported.error.message };
+            return imported.ok ? imported.value : cliError(imported.error);
         }),
     });
     cli.command("evidence-export", {
@@ -31,11 +30,9 @@ export const registerEvidenceCommands = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, "evidence-export", async () => {
             const config = parseConfig(process.env);
             if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
+                return cliError(config.error);
             const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite, config.value.evidenceFilePolicy);
-            return exported.ok
-                ? exported.value
-                : { error: exported.error._tag, message: exported.error.message };
+            return exported.ok ? exported.value : cliError(exported.error);
         }),
     });
     cli.command("compare", {
@@ -52,7 +49,7 @@ export const registerEvidenceCommands = (cli, logger) => {
         run: ({ args, options }) => logCliCommand(logger, "compare", async () => {
             const config = parseConfig(process.env);
             if (!config.ok)
-                return { error: config.error._tag, message: config.error.message };
+                return cliError(config.error);
             const compared = await compareEvidenceBundlesCommand({
                 leftPath: args.left,
                 rightPath: args.right,
@@ -60,9 +57,11 @@ export const registerEvidenceCommands = (cli, logger) => {
                 limit: options.limit,
                 policy: config.value.evidenceFilePolicy,
             });
-            return compared.ok
-                ? compared.value
-                : { error: compared.error._tag, message: compared.error.message };
+            return compared.ok ? compared.value : cliError(compared.error);
         }),
     });
 };
+const cliError = (error) => ({
+    error: "Analysis failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliInvestigationCommands.js

@@ -0,0 +1,86 @@
+import { Cli, z } from "incur";
+import { runCrossVersionInvestigation } from "./application/CrossVersionInvestigation.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+const investigationOptionsSchema = z.object({
+    yes: z
+        .boolean()
+        .default(false)
+        .describe("Approve persistent workspace writes"),
+    workspaceName: z.string().trim().min(1).max(200).default("default"),
+    expectedRevision: z.number().int().min(1).optional(),
+    maxEntries: z.number().int().min(1).max(50_000).default(10_000),
+    maxTotalBytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(1_073_741_824),
+    maxEntryBytes: z
+        .number()
+        .int()
+        .min(1)
+        .max(Number.MAX_SAFE_INTEGER)
+        .default(268_435_456),
+    pageSize: z.number().int().min(1).max(500).default(500),
+    changeLimit: z.number().int().min(1).max(500).default(500),
+});
+/** Register the persistent cross-version CLI workflow. */
+export const registerInvestigationCommands = (cli, logger) => {
+    cli.command("investigate-versions", {
+        description: "Run or resume a persistent cross-version artifact investigation",
+        args: z.object({
+            leftPath: z.string().describe("Earlier artifact or directory path"),
+            rightPath: z.string().describe("Later artifact or directory path"),
+            workspacePath: z.string().describe("Persistent workspace JSON path"),
+        }),
+        options: investigationOptionsSchema,
+        alias: {
+            workspaceName: "workspace-name",
+            expectedRevision: "expected-revision",
+            maxEntries: "max-entries",
+            maxTotalBytes: "max-total-bytes",
+            maxEntryBytes: "max-entry-bytes",
+            pageSize: "page-size",
+            changeLimit: "change-limit",
+            yes: "y",
+        },
+        run: ({ args, options }) => logCliCommand(logger, "investigate-versions", () => runInvestigation(args, options)),
+    });
+};
+const runInvestigation = async (args, options) => {
+    if (!options.yes)
+        return {
+            error: "ApprovalRequired",
+            message: "Persistent workspace writes require explicit --yes approval.",
+        };
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return { error: config.error._tag, message: config.error.message };
+    const investigated = await runCrossVersionInvestigation({
+        approved: true,
+        workspace_path: args.workspacePath,
+        workspace_name: options.workspaceName,
+        ...(options.expectedRevision === undefined
+            ? {}
+            : { expected_workspace_revision: options.expectedRevision }),
+        left_path: args.leftPath,
+        right_path: args.rightPath,
+        options: {
+            max_entries: options.maxEntries,
+            max_total_bytes: options.maxTotalBytes,
+            max_entry_bytes: options.maxEntryBytes,
+            max_compression_ratio: 1_000,
+            max_depth: 20,
+            max_path_bytes: 4_096,
+            page_size: options.pageSize,
+            change_limit: options.changeLimit,
+        },
+    }, config.value.evidenceFilePolicy, { inputRoots: config.value.investigationInputRoots });
+    return investigated.ok
+        ? investigated.value.evidence
+        : {
+            error: investigated.error._tag,
+            message: investigated.error.message,
+        };
+};

package/dist/cliOutput.js

@@ -0,0 +1,41 @@
+const SAFE_VALIDATION_MESSAGE = "REA could not read the command arguments. Run `rea --help`, correct the arguments, then try again.";
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+const validationError = (value) => {
+    if (!isRecord(value))
+        return undefined;
+    if (value.code === "VALIDATION_ERROR")
+        return value;
+    if (value.ok === false && isRecord(value.error))
+        return value.error.code === "VALIDATION_ERROR" ? value.error : undefined;
+    return undefined;
+};
+/** Remove validator internals from Incur's caller-visible CLI output. */
+export const sanitizeCliOutput = (output) => {
+    const trimmed = output.trimStart();
+    if (trimmed.startsWith("{")) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            const error = validationError(parsed);
+            if (error !== undefined) {
+                const safeError = {
+                    code: "VALIDATION_ERROR",
+                    message: SAFE_VALIDATION_MESSAGE,
+                };
+                if (error === parsed)
+                    return `${JSON.stringify(safeError)}\n`;
+                if (!isRecord(parsed))
+                    return output;
+                return `${JSON.stringify({ ...parsed, error: safeError })}\n`;
+            }
+        }
+        catch {
+            return output;
+        }
+        return output;
+    }
+    if (/^ok: false\r?\nerror:\r?\n  code: VALIDATION_ERROR(?:\r?\n|$)/u.test(trimmed))
+        return `ok: false\nerror:\n  code: VALIDATION_ERROR\n  message: "${SAFE_VALIDATION_MESSAGE}"\n`;
+    if (!/^code: VALIDATION_ERROR(?:\r?\n|$)/u.test(trimmed))
+        return output;
+    return `code: VALIDATION_ERROR\nmessage: "${SAFE_VALIDATION_MESSAGE}"\n`;
+};

package/dist/cliProcessCommands.js

@@ -1,12 +1,22 @@
-import { Cli, z } from "incur";
-import { captureProcessScenarioFile, compareProcessEvidenceFiles, } from "./application/ProcessCli.js";
+import { Cli, Errors, z } from "incur";
+import { captureProcessScenarioFile, compareProcessEvidenceFiles, isProcessCliErrorOutput, } from "./application/ProcessCli.js";
 import { logCliCommand } from "./cliLogging.js";
+const requireProcessCommandSuccess = async (execute) => {
+    const value = await execute();
+    if (isProcessCliErrorOutput(value))
+        throw new Errors.IncurError({
+            code: "PROCESS_COMMAND_FAILED",
+            message: value.message,
+            retryable: false,
+        });
+    return value;
+};
 /** Register Process Capture v4 one-shot commands through shared application services. */
 export const registerProcessCommands = (cli, logger) => {
     cli.command("capture-process", {
         description: "Capture one approved Process Capture v4 JSON scenario",
         args: z.object({ scenario: z.string().describe("Scenario JSON path") }),
-        run: ({ args }) => logCliCommand(logger, "capture-process", () => captureProcessScenarioFile(args.scenario)),
+        run: ({ args }) => logCliCommand(logger, "capture-process", () => requireProcessCommandSuccess(() => captureProcessScenarioFile(args.scenario))),
     });
     cli.command("compare-process-captures", {
         description: "Compare two Process Capture v4 Evidence JSON files",
@@ -14,6 +24,6 @@ export const registerProcessCommands = (cli, logger) => {
             left: z.string().describe("Left capture Evidence JSON path"),
             right: z.string().describe("Right capture Evidence JSON path"),
         }),
-        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => compareProcessEvidenceFiles(args.left, args.right)),
+        run: ({ args }) => logCliCommand(logger, "compare-process-captures", () => requireProcessCommandSuccess(() => compareProcessEvidenceFiles(args.left, args.right))),
     });
 };