rea-agents 1.2.0 → 1.4.0

package/dist/application/LinuxHopper.js

@@ -1,14 +1,31 @@
 import { createHash } from "node:crypto";
 import { execFile } from "node:child_process";
+import { createReadStream } from "node:fs";
 import { access, mkdtemp, readFile, rm, writeFile } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join } from "node:path";
 import { promisify } from "node:util";
-import { z } from "zod";
 const execFileAsync = promisify(execFile);
-const RELEASES_URL = "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
 const MAX_PACKAGE_BYTES = 100_000_000;
+const SUPPORTED_HOPPER_SHA256 = "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded";
+const SUPPORTED_RELEASES = {
+    deb: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.deb`,
+        file_length: "35755772",
+        file_hash: "e4f79dff602648a8ff4a88b773875b6bfac0dc65",
+    },
+    rpm: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.rpm`,
+        file_length: "32264475",
+        file_hash: "b9a65f2f583a386d440d4401d9140aef3bf305de",
+    },
+    arch: {
+        filename: `${DOWNLOAD_PREFIX}Hopper-6.4.2-Linux-demo.pkg.tar.xz`,
+        file_length: "29405968",
+        file_hash: "92d780b61cab38eda95dc4112dee4fbeb0920f46",
+    },
+};
 /** Parse an os-release document without executing its shell syntax. */
 export const parseLinuxDistribution = (text) => {
     const fields = new Map();
@@ -57,15 +74,7 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         return { status: "failed", reason: "unsupported_host" };
     let temporary;
     try {
-        const metadataDownload = await host.download(RELEASES_URL, options);
-        if (!metadataDownload.ok)
-            return { status: "failed", reason: "release_metadata" };
-        const releases = parseReleases(metadataDownload.bytes);
-        if (releases === undefined)
-            return { status: "failed", reason: "release_metadata" };
-        const release = releases[releaseKey(distribution.packageFamily)];
-        if (!release.filename.startsWith(DOWNLOAD_PREFIX))
-            return { status: "failed", reason: "release_metadata" };
+        const release = (options.releases ?? SUPPORTED_RELEASES)[distribution.packageFamily];
         const archiveDownload = await host.download(release.filename, options);
         if (!archiveDownload.ok)
             return { status: "failed", reason: "download" };
@@ -77,8 +86,12 @@ export const installLinuxHopper = async (host = systemLinuxHopperInstallHost(),
         if (!(await host.installPackage(distribution.packageFamily, archive)))
             return { status: "failed", reason: "authorization_or_package_manager" };
         const launcherPath = "/opt/hopper/bin/Hopper";
-        if (!(await host.launcherReady(launcherPath)))
-            return { status: "failed", reason: "launcher_missing" };
+        const launcherStatus = await host.launcherStatus(launcherPath);
+        if (launcherStatus !== "ready")
+            return {
+                status: "failed",
+                reason: launcherStatus === "missing" ? "launcher_missing" : launcherStatus,
+            };
         return { status: "installed", launcherPath };
     }
     catch (cause) {
@@ -108,24 +121,40 @@ const systemLinuxHopperInstallHost = () => ({
     createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
     writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
     installPackage: installSystemPackage,
-    async launcherReady(path) {
+    async launcherStatus(path) {
         try {
             await access(path);
             const linked = await execFileAsync("ldd", [path]);
-            return linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`);
+            if (!linuxSharedLibrariesAvailable(`${linked.stdout}\n${linked.stderr}`))
+                return "runtime_dependencies";
+            return (await linuxHopperBinarySupported(path))
+                ? "ready"
+                : "unsupported_hopper_build";
         }
         catch {
-            return false;
+            return "missing";
         }
     },
     cleanup: (path) => rm(path, { recursive: true, force: true }),
 });
+/** Match the Linux Hopper build validated by the packaged demo-dialog adapter. */
+export const linuxHopperBinarySupported = async (path) => {
+    try {
+        const hash = createHash("sha256");
+        for await (const chunk of createReadStream(path))
+            hash.update(chunk);
+        return hash.digest("hex") === SUPPORTED_HOPPER_SHA256;
+    }
+    catch {
+        return false;
+    }
+};
 /** Interpret ldd output conservatively so a present but broken launcher is unhealthy. */
 export const linuxSharedLibrariesAvailable = (output) => !/(?:=>\s+not found|error while loading shared libraries)/iu.test(output);
 const installSystemPackage = async (family, archive) => {
     try {
-        const command = linuxPackageManagerCommand(family, archive, process.getuid?.() === 0);
-        await execFileAsync(command.executable, command.args);
+        for (const command of linuxPackageManagerCommands(family, archive, process.getuid?.() === 0))
+            await execFileAsync(command.executable, command.args);
         return true;
     }
     catch {
@@ -133,26 +162,32 @@ const installSystemPackage = async (family, archive) => {
     }
 };
 /** Select the native package manager and authorization boundary without shell evaluation. */
-export const linuxPackageManagerCommand = (family, archive, isRoot) => {
-    const command = family === "deb"
-        ? ["apt-get", "install", "-y", archive]
+export const linuxPackageManagerCommands = (family, archive, isRoot) => {
+    const runtimeDependencies = family === "deb"
+        ? ["xvfb", "xauth", "python3", "libx11-6", "libxtst6"]
         : family === "rpm"
-            ? ["dnf", "install", "-y", archive]
-            : ["pacman", "-U", "--noconfirm", archive];
-    const executable = isRoot ? command[0] : "pkexec";
-    if (executable === undefined)
-        throw new Error("package command is empty");
-    return { executable, args: isRoot ? command.slice(1) : command };
-};
-const parseReleases = (bytes) => {
-    try {
-        const parsed = JSON.parse(new TextDecoder().decode(bytes));
-        const result = releasesSchema.safeParse(parsed);
-        return result.success ? result.data : undefined;
-    }
-    catch {
-        return undefined;
-    }
+            ? [
+                "xorg-x11-server-Xvfb",
+                "xorg-x11-xauth",
+                "python3",
+                "libX11",
+                "libXtst",
+            ]
+            : ["xorg-server-xvfb", "xorg-xauth", "python", "libx11", "libxtst"];
+    const commands = family === "deb"
+        ? [["apt-get", "install", "-y", archive, ...runtimeDependencies]]
+        : family === "rpm"
+            ? [["dnf", "install", "-y", archive, ...runtimeDependencies]]
+            : [
+                ["pacman", "-S", "--needed", "--noconfirm", ...runtimeDependencies],
+                ["pacman", "-U", "--noconfirm", archive],
+            ];
+    return commands.map((command) => {
+        const executable = isRoot ? command[0] : "pkexec";
+        if (executable === undefined)
+            throw new Error("package command is empty");
+        return { executable, args: isRoot ? command.slice(1) : command };
+    });
 };
 const packageIntegrityMatches = (bytes, release) => bytes.byteLength === Number(release.file_length) &&
     bytes.byteLength <= MAX_PACKAGE_BYTES &&
@@ -172,15 +207,4 @@ const packageFamilyFor = (id, idLike) => {
 };
 const versionAtLeast = (version, minimum) => version !== undefined &&
     Number.parseInt(version.split(".")[0] ?? "0", 10) >= minimum;
-const releaseKey = (family) => family === "deb" ? "Ubuntu / Mint" : family === "rpm" ? "Fedora" : "Arch";
 const isAbortCause = (cause) => cause instanceof Error && cause.name === "AbortError";
-const releaseSchema = z.object({
-    filename: z.string().url(),
-    file_length: z.string().regex(/^\d+$/u),
-    file_hash: z.string().regex(/^[a-f0-9]{40}$/u),
-});
-const releasesSchema = z.object({
-    "Ubuntu / Mint": releaseSchema,
-    Fedora: releaseSchema,
-    Arch: releaseSchema,
-});

package/dist/application/PermissionAuthority.js

@@ -0,0 +1,183 @@
+import { realpath } from "node:fs/promises";
+import { basename, dirname, join, resolve } from "node:path";
+import { consumePermission, clearSessionPermissions, createPermissionPolicy, evaluatePermission, grantPermission, reloadPermissionCeilings, revokePermission, } from "../domain/permissionPolicy.js";
+import { PermissionRequiredError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+/** Failure to establish a filesystem object's canonical authorization identity. */
+export class PermissionPathError extends Error {
+    path;
+    reason;
+    _tag = "PermissionPathError";
+    constructor(path, reason, options) {
+        super(`Cannot canonicalize permission path: ${path}`, options);
+        this.path = path;
+        this.reason = reason;
+    }
+}
+/** Canonicalize administrator ceilings before they become authorization state. */
+export const canonicalizePermissionCeilings = async (ceilings) => {
+    const normalized = [];
+    for (const ceiling of ceilings) {
+        const canonical = await canonicalizeScope(ceiling, "read");
+        if (!canonical.ok)
+            return canonical;
+        normalized.push(canonical.value);
+    }
+    return ok(normalized);
+};
+/** Canonicalize one exact operation request before subset evaluation. */
+export const canonicalizePermissionRequest = async (request, access) => {
+    const canonical = await canonicalizeScope(request, access);
+    return canonical.ok
+        ? ok({ ...canonical.value, operation_identity: request.operation_identity })
+        : canonical;
+};
+const canonicalizeScope = async (scope, access) => {
+    const roots = await canonicalizePaths(scope.roots, access);
+    if (!roots.ok)
+        return roots;
+    const executables = await canonicalizePaths(scope.executables, "read");
+    if (!executables.ok)
+        return executables;
+    return ok({ ...scope, roots: roots.value, executables: executables.value });
+};
+const canonicalizePaths = async (paths, access) => {
+    const canonical = [];
+    for (const path of paths) {
+        const result = await canonicalizePath(path, access);
+        if (!result.ok)
+            return result;
+        canonical.push(result.value);
+    }
+    return ok(canonical);
+};
+const canonicalizePath = async (path, access) => {
+    const requested = resolve(path);
+    try {
+        return ok(await realpath(requested));
+    }
+    catch (cause) {
+        if (access !== "write" || !isNotFound(cause))
+            return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+    try {
+        const parent = await realpath(dirname(requested));
+        return ok(join(parent, basename(requested)));
+    }
+    catch (cause) {
+        return err(new PermissionPathError(path, errorReason(cause), { cause }));
+    }
+};
+const isNotFound = (error) => error instanceof Error && "code" in error && error.code === "ENOENT";
+const errorReason = (error) => isNotFound(error) ? "not_found" : "io";
+/** Stateful owner for permission evaluation, consumption, reload, and revoke. */
+export class PermissionAuthority {
+    policy;
+    constructor(policy) {
+        this.policy = policy;
+    }
+    /** Canonicalize and authorize one exact operation before its side effect. */
+    async authorize(request, access, options = {}) {
+        const evaluated = await this.explain(request, access, options);
+        if (!evaluated.ok)
+            return evaluated;
+        const decision = evaluated.value;
+        this.policy = consumePermission(this.policy, decision);
+        return ok(decision);
+    }
+    /** Dry-run the exact shared evaluation without consuming a once grant. */
+    async explain(request, access, options = {}) {
+        const canonical = await canonicalizePermissionRequest(request, access);
+        if (!canonical.ok)
+            return canonical;
+        const decision = evaluatePermission(this.policy, canonical.value);
+        if (!decision.allowed)
+            return err(new PermissionRequiredError(canonical.value, decision.missing, ceilingFor(this.policy, canonical.value.capability), options.elicitationSupported ?? false, options.restartRequired ?? false));
+        return ok(decision);
+    }
+    /** Add authority beneath the administrator ceiling. */
+    grant(grant) {
+        const result = grantPermission(this.policy, grant);
+        if (result.ok)
+            this.policy = result.value;
+        return result;
+    }
+    /** Revoke authority immediately for subsequent operations. */
+    revoke(grantId) {
+        this.policy = revokePermission(this.policy, grantId);
+    }
+    /** Drop once/session authority when its owning connection ends. */
+    clearSessionGrants() {
+        this.policy = clearSessionPermissions(this.policy);
+    }
+    /** Atomically replace optional persisted project grants. */
+    async replaceProjectGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "project"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
+    /** Replace grants derived from the currently loaded administrator ceiling. */
+    async replaceAdministratorGrants(grants) {
+        let candidate = {
+            ...this.policy,
+            grants: this.policy.grants.filter(({ lifetime }) => lifetime !== "administrator"),
+        };
+        for (const grant of grants) {
+            const canonical = await canonicalizeGrant(grant);
+            if (!canonical.ok)
+                return canonical;
+            const added = grantPermission(candidate, canonical.value);
+            if (!added.ok)
+                return err(new PermissionPathError(grant.grant_id, "io", {
+                    cause: added.error,
+                }));
+            candidate = added.value;
+        }
+        this.policy = candidate;
+        return ok(null);
+    }
+    /** Replace ceilings without restarting the MCP process. */
+    async reload(ceilings) {
+        const canonical = await canonicalizePermissionCeilings(ceilings);
+        if (!canonical.ok)
+            return canonical;
+        this.policy = reloadPermissionCeilings(this.policy, canonical.value);
+        return ok(null);
+    }
+}
+/** Create one canonical policy and optional grants at the composition root. */
+export const createPermissionAuthority = async (ceilings, grants = []) => {
+    const canonical = await canonicalizePermissionCeilings(ceilings);
+    if (!canonical.ok)
+        return canonical;
+    let policy = createPermissionPolicy(canonical.value);
+    for (const grant of grants) {
+        const canonicalGrant = await canonicalizeGrant(grant);
+        if (!canonicalGrant.ok)
+            return canonicalGrant;
+        const added = grantPermission(policy, canonicalGrant.value);
+        if (!added.ok)
+            return err(new PermissionPathError(grant.grant_id, "io", { cause: added.error }));
+        policy = added.value;
+    }
+    return ok(new PermissionAuthority(policy));
+};
+const canonicalizeGrant = async (grant) => {
+    const scope = await canonicalizeScope(grant, "read");
+    return scope.ok ? ok({ ...grant, ...scope.value }) : scope;
+};
+const ceilingFor = (policy, capability) => policy.ceilings.find((ceiling) => ceiling.capability === capability) ?? null;

package/dist/application/PermissionConfiguration.js

@@ -0,0 +1,26 @@
+import { ConfigurationError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { createPermissionAuthority, } from "./PermissionAuthority.js";
+import { readProjectPermissionStore } from "./ProjectPermissionStore.js";
+/** Load the same administrator and optional project policy for CLI and MCP. */
+export const loadConfiguredPermissionAuthority = async (config) => {
+    const authority = await createPermissionAuthority(config.permissionCeilings, config.administratorPermissionGrants);
+    if (!authority.ok)
+        return err(new ConfigurationError("Permission policy could not be loaded", {
+            cause: authority.error,
+        }));
+    if (config.permissionProjectRoot === undefined ||
+        config.permissionProjectStore === undefined)
+        return ok(authority.value);
+    const project = await readProjectPermissionStore(config.permissionProjectStore, config.permissionProjectRoot);
+    if (!project.ok)
+        return err(new ConfigurationError("Project permission policy could not be loaded", {
+            cause: project.error,
+        }));
+    const replaced = await authority.value.replaceProjectGrants(project.value?.grants ?? []);
+    return replaced.ok
+        ? ok(authority.value)
+        : err(new ConfigurationError("Project permission policy could not be applied", {
+            cause: replaced.error,
+        }));
+};

package/dist/application/ProcessCaptureAuthority.js

@@ -1,5 +1,5 @@
 import { realpath } from "node:fs/promises";
-import { ProcessCaptureError } from "./ProcessCaptureError.js";
+import { ProcessCaptureError, processCaptureCancelled, } from "./ProcessCaptureError.js";
 const isWithin = (candidate, root) => candidate === root ||
     candidate.startsWith(`${root.endsWith("/") ? root.slice(0, -1) : root}/`);
 export const assertRealPathAuthority = async (scenario, policy) => {
@@ -20,6 +20,6 @@ export const assertRealPathAuthority = async (scenario, policy) => {
 /** Expected refusal or runtime failure from the process capture adapter. */
 export const assertNotCancelled = (signal) => {
     if (signal?.aborted === true)
-        throw new ProcessCaptureError("process capture was cancelled");
+        throw processCaptureCancelled();
 };
 /** Runtime availability of the native PTY adapter on this host. */

package/dist/application/ProcessCaptureError.js

@@ -2,4 +2,29 @@ import { AnalysisError } from "../domain/errors.js";
 /** Typed application failure produced by controlled process capture. */
 export class ProcessCaptureError extends AnalysisError {
     _tag = "ProcessCaptureError";
+    userMessage;
+    userCategory;
+    reason;
+    cleanupIncomplete;
+    cleanupResources;
+    constructor(message, options) {
+        super(message, options);
+        this.userMessage = options?.userMessage;
+        this.userCategory = options?.userCategory;
+        this.reason =
+            options?.reason ??
+                (options?.userCategory === "permission_required"
+                    ? "permission_required"
+                    : options?.userCategory === "cancelled"
+                        ? "cancelled"
+                        : "capture_failed");
+        this.cleanupIncomplete = this.reason === "cleanup_incomplete";
+        this.cleanupResources = options?.cleanupResources ?? [];
+    }
 }
+/** Caller-visible cancellation without exposing capture implementation state. */
+export const processCaptureCancelled = () => new ProcessCaptureError("process capture was cancelled", {
+    userCategory: "cancelled",
+    reason: "cancelled",
+    userMessage: "Process capture was cancelled. Start it again when ready.",
+});

package/dist/application/ProcessCaptureLifecycle.js

@@ -249,7 +249,9 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
             cause: executionFailure,
         });
     if (cleanupFailure !== undefined)
-        throw new ProcessCaptureError(cleanupFailure);
+        throw new ProcessCaptureError(cleanupFailure, {
+            reason: "cleanup_incomplete",
+        });
     if (capture === undefined)
         throw new ProcessCaptureError("process capture produced no result");
     return capture;
@@ -257,7 +259,10 @@ export const resolveProcessResult = (capture, executionFailure, cleanupFailure)
 export const prepareProcessCapture = async (scenario, policy, signal) => {
     const decision = authorizeProcessScenario(scenario, policy);
     if (!decision.allowed)
-        throw new ProcessCaptureError(decision.reason);
+        throw new ProcessCaptureError(decision.reason, {
+            userCategory: "permission_required",
+            userMessage: processPolicyMessage(decision.reason),
+        });
     await assertRealPathAuthority(scenario, policy);
     assertNotCancelled(signal);
     const before = await snapshotRoots(scenario, signal);
@@ -267,3 +272,18 @@ export const prepareProcessCapture = async (scenario, policy, signal) => {
     await import("node:fs/promises").then(({ mkdir }) => mkdir(home));
     return { temporaryRoot, runId, home, before };
 };
+const processPolicyMessage = (reason) => {
+    if (reason === "process capture is disabled")
+        return "Process capture is disabled. Set `REA_PROCESS_CAPTURE_ENABLED=true`, configure approved roots, then restart REA.";
+    if (reason === "host network access is not approved by operator policy")
+        return "This capture requests host network access, but policy does not allow it. Use replayed network access or ask the operator to enable external network capture.";
+    if (reason === "executable is outside approved roots")
+        return "The executable is outside the approved capture directories. Choose an approved executable or add its directory to `REA_PROCESS_EXECUTABLE_ROOTS_JSON`.";
+    if (reason === "working directory is outside approved roots")
+        return "The working directory is outside the approved capture directories. Choose an approved directory or add it to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "filesystem root is outside approved roots")
+        return "A requested filesystem root is outside the approved capture directories. Remove it or add its directory to `REA_PROCESS_WORKING_ROOTS_JSON`.";
+    if (reason === "scenario requests an environment variable not allowed by policy")
+        return "The capture requests an environment variable that policy does not allow. Remove it or add its name to `REA_PROCESS_ALLOWED_ENV_JSON`.";
+    return reason;
+};

package/dist/application/ProcessCli.js

@@ -1,42 +1,82 @@
 import { readFile } from "node:fs/promises";
 import { parseConfig } from "../config.js";
+import { AnalysisError, AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "../domain/errors.js";
 import { createEvidence, parseEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
 import { compareProcessCaptures, LEGACY_PROCESS_CAPTURE_MESSAGE, parseProcessScenario, parseProcessCapture, } from "../domain/processCapture.js";
 import { captureProcessScenario } from "./ProcessHarness.js";
 import { PROCESS_PROVIDER, createProcessCaptureEvidence, } from "./ProcessEvidence.js";
+import { loadConfiguredPermissionAuthority } from "./PermissionConfiguration.js";
 const MAX_INPUT_BYTES = 64 * 1024 * 1024;
 /** Capture one JSON scenario through the same policy and evidence contract as MCP. */
 export const captureProcessScenarioFile = async (path) => {
-    const scenario = parseProcessScenario(await readJson(path));
-    const config = parseConfig(process.env);
-    if (!config.ok)
-        throw config.error;
-    const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
-    if (!captured.ok)
-        throw captured.error;
-    return createProcessCaptureEvidence(scenario, captured.value);
+    try {
+        const input = await readJson(path);
+        let scenario;
+        try {
+            scenario = parseProcessScenario(input);
+        }
+        catch {
+            throw new ProcessCliFailure("invalid_input", "Process scenario is invalid. Check its required fields and limits, then try again.");
+        }
+        const config = parseConfig(process.env);
+        if (!config.ok)
+            return cliAnalysisError(config.error);
+        const authority = await loadConfiguredPermissionAuthority(config.value);
+        if (!authority.ok)
+            return cliAnalysisError(authority.error);
+        const authorized = await authority.value.authorize({
+            capability: "process_capture",
+            roots: [scenario.working_directory, ...scenario.filesystem_roots],
+            executables: [scenario.executable],
+            environment_names: [
+                ...Object.keys(scenario.environment),
+                ...scenario.inherit_environment,
+            ],
+            network: scenario.network_access === "host" ? "external" : "none",
+            mount: false,
+            operation_identity: `capture_process_scenario:${scenario.executable}`,
+        }, "read");
+        if (!authorized.ok)
+            return cliAnalysisError(authorized.error instanceof PermissionRequiredError
+                ? authorized.error
+                : new AnalysisProtocolError(authorized.error.message, {
+                    cause: authorized.error,
+                }));
+        const captured = await captureProcessScenario(scenario, config.value.processExecutionPolicy);
+        if (!captured.ok)
+            return cliAnalysisError(captured.error);
+        return createProcessCaptureEvidence(scenario, captured.value);
+    }
+    catch (cause) {
+        return projectProcessCliError(cause);
+    }
 };
 /** Compare two capture Evidence files and emit derived comparison Evidence. */
 export const compareProcessEvidenceFiles = async (leftPath, rightPath) => {
-    const left = parseCaptureEvidence(await readJson(leftPath));
-    const right = parseCaptureEvidence(await readJson(rightPath));
-    const comparison = compareProcessCaptures(left.capture, right.capture);
-    return createEvidence(undefined, PROCESS_PROVIDER, {
-        predicateType: "rea.process-comparison/v3",
-        operation: "compare_process_captures",
-        parameters: {
-            left_evidence_id: left.id,
-            right_evidence_id: right.id,
-            left_normalization: left.capture.normalization,
-            right_normalization: right.capture.normalization,
-        },
-        result: jsonValueSchema.parse(comparison),
-        confidence: "derived",
-        authority: "analyst-inference",
-        limitations: comparison.limitations,
-        evidenceLinks: [left.id, right.id],
-    });
+    try {
+        const left = parseCaptureEvidence(await readJson(leftPath));
+        const right = parseCaptureEvidence(await readJson(rightPath));
+        const comparison = compareProcessCaptures(left.capture, right.capture);
+        return createEvidence(undefined, PROCESS_PROVIDER, {
+            predicateType: "rea.process-comparison/v3",
+            operation: "compare_process_captures",
+            parameters: {
+                left_evidence_id: left.id,
+                right_evidence_id: right.id,
+                left_normalization: left.capture.normalization,
+                right_normalization: right.capture.normalization,
+            },
+            result: jsonValueSchema.parse(comparison),
+            confidence: "derived",
+            authority: "analyst-inference",
+            limitations: comparison.limitations,
+            evidenceLinks: [left.id, right.id],
+        });
+    }
+    catch (cause) {
+        return projectProcessCliError(cause);
+    }
 };
 const parseCaptureEvidence = (input) => {
     const evidence = parseEvidence(input);
@@ -45,8 +85,8 @@ const parseCaptureEvidence = (input) => {
         evidence.provider.id !== PROCESS_PROVIDER.id ||
         evidence.provider.version !== PROCESS_PROVIDER.version) {
         if (evidence.predicate_type === "rea.process-capture/v3")
-            throw new TypeError(LEGACY_PROCESS_CAPTURE_MESSAGE);
-        throw new TypeError("Expected REA Process Capture v4 Evidence");
+            throw new ProcessCliFailure("invalid_input", LEGACY_PROCESS_CAPTURE_MESSAGE);
+        throw new ProcessCliFailure("invalid_input", "Capture evidence is not from the current process-capture workflow. Create new capture evidence, then try again.");
     }
     return {
         id: evidence.evidence_id,
@@ -54,8 +94,48 @@ const parseCaptureEvidence = (input) => {
     };
 };
 const readJson = async (path) => {
-    const bytes = await readFile(path);
+    let bytes;
+    try {
+        bytes = await readFile(path);
+    }
+    catch {
+        throw new ProcessCliFailure("invalid_input", "Process input file could not be read. Check that the path exists and is readable.");
+    }
     if (bytes.length > MAX_INPUT_BYTES)
-        throw new TypeError("Process JSON input exceeds byte limit");
-    return JSON.parse(bytes.toString("utf8"));
+        throw new ProcessCliFailure("truncated", "Process input file is too large. Reduce it below 64 MiB, then try again.");
+    try {
+        return JSON.parse(bytes.toString("utf8"));
+    }
+    catch {
+        throw new ProcessCliFailure("invalid_input", "Process input file is not valid JSON. Repair the file, then try again.");
+    }
+};
+class ProcessCliFailure extends Error {
+    category;
+    userMessage;
+    constructor(category, userMessage) {
+        super(userMessage);
+        this.category = category;
+        this.userMessage = userMessage;
+    }
+}
+const cliAnalysisError = (error) => ({
+    error: "Process command failed",
+    ...projectAnalysisError(error),
+});
+/** Project any process CLI failure without exposing its cause. */
+export const projectProcessCliError = (cause) => {
+    if (cause instanceof ProcessCliFailure)
+        return {
+            error: "Process command failed",
+            category: cause.category,
+            message: cause.userMessage,
+        };
+    if (cause instanceof AnalysisError)
+        return cliAnalysisError(cause);
+    return {
+        error: "Process command failed",
+        category: "execution_failure",
+        message: "Process command could not complete. Check the input files and run `rea doctor`, then try again.",
+    };
 };