rea-agents 1.3.0 → 1.5.0

package/dist/catalogIdentity.js

@@ -0,0 +1,123 @@
+import { createHash } from "node:crypto";
+import canonicalize from "canonicalize";
+import { z } from "zod";
+import { PROMPT_CONTRACTS } from "./contracts/promptContracts.js";
+import { TOOL_CONTRACTS } from "./contracts/toolContracts.js";
+/** Explicit CLI command inventory, kept separate from MCP tool counts. */
+export const CLI_COMMAND_NAMES = [
+    "analyze",
+    "inspect",
+    "decompile",
+    "setup",
+    "doctor",
+    "uninstall",
+    "upgrade",
+    "xrefs",
+    "trace",
+    "capabilities",
+    "providers",
+    "function",
+    "search",
+    "import-reference-source",
+    "inventory-artifact",
+    "extract-artifact",
+    "inspect-macho",
+    "inspect-signature",
+    "list-architectures",
+    "inspect-plist",
+    "demangle-swift",
+    "evidence-import",
+    "evidence-export",
+    "compare",
+    "investigate-versions",
+    "capture-process",
+    "compare-process-captures",
+    "policy",
+    "list-browser-targets",
+    "inspect-web-page",
+];
+const toolCatalog = TOOL_CONTRACTS.map((contract) => ({
+    name: contract.name,
+    surface: contract.kind,
+    description: contract.description,
+    annotations: contract.annotations,
+    input_schema: z.toJSONSchema(contract.inputSchema, {
+        unrepresentable: "any",
+    }),
+    output_schema: z.toJSONSchema(contract.outputSchema, {
+        unrepresentable: "any",
+    }),
+})).sort((left, right) => left.name.localeCompare(right.name));
+const promptCatalog = PROMPT_CONTRACTS.map((contract) => ({
+    name: contract.name,
+    title: contract.title,
+    description: contract.description,
+    arguments: contract.arguments,
+    steps: contract.steps,
+})).sort((left, right) => left.name.localeCompare(right.name));
+const resourceCatalog = [
+    { name: "server-identity", uri: "rea://server/identity" },
+    { name: "active-residual-unknowns", uri: "rea://unknowns/active" },
+];
+const resourceTemplateCatalog = [
+    { name: "session-evidence", uri_template: "rea://evidence/{evidenceId}" },
+    {
+        name: "evidence-section",
+        uri_template: "rea://evidence/{evidenceId}/section/{section}",
+    },
+    { name: "residual-unknown", uri_template: "rea://unknown/{unknownId}" },
+    {
+        name: "analysis-snapshot",
+        uri_template: "rea://snapshot/{snapshotDigest}",
+    },
+    {
+        name: "artifact-page",
+        uri_template: "rea://artifact/{manifestId}/{collection}",
+    },
+    {
+        name: "function-dossier",
+        uri_template: "rea://function/{targetSha256}/{address}",
+    },
+    {
+        name: "investigation-workspace-revision",
+        uri_template: "rea://workspace/{workspaceId}/revision/{revision}",
+    },
+];
+const digest = (value) => {
+    const encoded = canonicalize(value);
+    if (encoded === undefined)
+        throw new TypeError("Catalog is not canonical JSON");
+    return createHash("sha256").update(encoded).digest("hex");
+};
+/** Stable, schema-sensitive identity for every public REA surface. */
+export const CATALOG_IDENTITY = {
+    counts: {
+        cli_commands: CLI_COMMAND_NAMES.length,
+        mcp_tools: toolCatalog.length,
+        mcp_prompts: promptCatalog.length,
+        mcp_resources: resourceCatalog.length,
+        mcp_resource_templates: resourceTemplateCatalog.length,
+    },
+    digests: {
+        tools_sha256: digest(toolCatalog),
+        prompts_sha256: digest(promptCatalog),
+        resources_sha256: digest({ resourceCatalog, resourceTemplateCatalog }),
+        combined_sha256: digest({
+            cli: CLI_COMMAND_NAMES,
+            tools: toolCatalog,
+            prompts: promptCatalog,
+            resources: resourceCatalog,
+            resource_templates: resourceTemplateCatalog,
+        }),
+    },
+    tools: toolCatalog.map(({ name, surface, annotations }) => ({
+        name,
+        surface,
+        annotations: {
+            read_only: annotations.readOnlyHint ?? false,
+            destructive: annotations.destructiveHint ?? false,
+            idempotent: annotations.idempotentHint ?? false,
+            open_world: annotations.openWorldHint ?? true,
+        },
+    })),
+};

package/dist/cli.js

@@ -14,8 +14,11 @@ 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 { AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "./domain/errors.js";
 import { projectReferenceSourceImportError } from "./application/ReferenceSourceImportTypes.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { registerPolicyCommands } from "./cliPolicyCommands.js";
+import { registerBrowserCommands } from "./cliBrowserCommands.js";
 /**
  * Build the one-shot Incur CLI without starting Hopper at import time.
  * Analysis commands acquire and close their own sessions; bare `mcp` and
@@ -26,7 +29,7 @@ export const createCli = () => {
         ? "silent"
         : parseLogLevel(process.env.REA_LOG_LEVEL));
     const cli = Cli.create(PRODUCT_IDENTITY.cliBinary, {
-        version: process.env.REA_PACKAGE_VERSION ?? "0.0.0-development",
+        version: PRODUCT_IDENTITY.packageVersion,
         description: "Reverse engineer anything from your terminal or agent.",
         mcp: {
             command: PRODUCT_IDENTITY.mcpCommand,
@@ -55,6 +58,8 @@ export const createCli = () => {
     registerEvidenceCommands(cli, logger);
     registerReferenceSourceCommand(cli, logger);
     registerProcessCommands(cli, logger);
+    registerPolicyCommands(cli, logger);
+    registerBrowserCommands(cli, logger);
     return cli;
 };
 const registerCoreCommands = (cli, logger) => {
@@ -135,7 +140,7 @@ const registerSetupCommands = (cli, logger) => {
     });
     cli.command("upgrade", {
         description: "Upgrade a global npm installation to the latest REA release",
-        run: ({ formatExplicit }) => logCliCommand(logger, "upgrade", () => runUpgrade(process.env.REA_PACKAGE_VERSION ?? "0.0.0-development", systemUpgradeHost(), formatExplicit ? "structured" : "human")),
+        run: ({ formatExplicit }) => logCliCommand(logger, "upgrade", () => runUpgrade(PRODUCT_IDENTITY.packageVersion, systemUpgradeHost(), formatExplicit ? "structured" : "human")),
     });
 };
 const confirmSetup = async (actions) => {
@@ -270,6 +275,32 @@ const registerReferenceSourceCommand = (cli, logger) => {
                     error: "Import failed",
                     ...projectAnalysisError(config.error),
                 };
+            const authority = await loadConfiguredPermissionAuthority(config.value);
+            if (!authority.ok)
+                return {
+                    error: "Import failed",
+                    ...projectAnalysisError(authority.error),
+                };
+            const authorized = await authority.value.authorize({
+                capability: "reference_read",
+                roots: [args.root],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `import_reference_source:${args.root}`,
+            }, "read");
+            if (!authorized.ok) {
+                const error = authorized.error instanceof PermissionRequiredError
+                    ? authorized.error
+                    : new AnalysisProtocolError(authorized.error.message, {
+                        cause: authorized.error,
+                    });
+                return {
+                    error: "Import failed",
+                    ...projectAnalysisError(error),
+                };
+            }
             const imported = await importReferenceSource({
                 root: args.root,
                 caller: "rea-cli",
@@ -295,7 +326,17 @@ const registerArtifactCommands = (cli, logger) => {
         options: z.object({
             offset: z.number().int().min(0).default(0),
             limit: z.number().int().min(1).max(500).default(100),
+            integrityPolicy: z.enum(["fail", "record-and-continue"]).default("fail"),
+            integrityContinueApproved: z.boolean().default(false),
+            maxIntegrityMismatches: z.number().int().min(1).max(100).default(10),
+            nativeMountApproved: z.boolean().default(false),
         }),
+        alias: {
+            integrityPolicy: "integrity-policy",
+            integrityContinueApproved: "integrity-continue-approved",
+            maxIntegrityMismatches: "max-integrity-mismatches",
+            nativeMountApproved: "native-mount-approved",
+        },
         run: ({ args, options }) => logCliCommand(logger, "inventory-artifact", () => runProviderAnalysis(args.path, "inventory_artifact", {
             node_offset: options.offset,
             node_limit: options.limit,
@@ -303,6 +344,10 @@ const registerArtifactCommands = (cli, logger) => {
             occurrence_limit: options.limit,
             edge_offset: options.offset,
             edge_limit: options.limit,
+            integrity_policy: options.integrityPolicy,
+            integrity_continue_approved: options.integrityContinueApproved,
+            max_integrity_mismatches: options.maxIntegrityMismatches,
+            native_mount_approved: options.nativeMountApproved,
         }, logger)),
     });
     cli.command("extract-artifact", {

package/dist/cliBrowserCommands.js

@@ -0,0 +1,136 @@
+import { Cli, z } from "incur";
+import { inspectWebPage, listBrowserTargets, } from "./application/BrowserObservationService.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { CdpBrowserProvider } from "./browser/CdpBrowserProvider.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import { inspectWebPageInputSchema, listBrowserTargetsInputSchema, } from "./domain/browserObservation.js";
+import { AnalysisInputError, projectAnalysisError } from "./domain/errors.js";
+const browserScopeOptions = {
+    allowedOrigins: z
+        .array(z.string().min(1))
+        .optional()
+        .describe("Exact origins to observe; defaults to REA_BROWSER_ALLOWED_ORIGINS_JSON"),
+    approved: z.boolean().default(false).describe("Approve passive observation"),
+};
+/** Register CLI equivalents of the passive browser MCP tools. */
+export const registerBrowserCommands = (cli, logger) => {
+    registerTargetList(cli, logger);
+    registerPageInspection(cli, logger);
+};
+const registerTargetList = (cli, logger) => {
+    cli.command("list-browser-targets", {
+        description: "List approved pages from a user-owned loopback CDP browser",
+        args: z.object({
+            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+        }),
+        options: z.object({
+            ...browserScopeOptions,
+            offset: z.number().int().min(0).default(0),
+            limit: z.number().int().min(1).max(200).default(100),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "list-browser-targets", async () => {
+            const context = await browserContext();
+            if (!context.ok)
+                return context.error;
+            const parsed = listBrowserTargetsInputSchema.safeParse({
+                cdp_endpoint: args.endpoint,
+                allowed_origins: options.allowedOrigins ?? context.allowedBrowserOrigins,
+                approved: options.approved,
+                offset: options.offset,
+                limit: options.limit,
+            });
+            if (!parsed.success)
+                return cliError(new AnalysisInputError("list_browser_targets"));
+            const result = await listBrowserTargets(context.provider, context.authority, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
+const registerPageInspection = (cli, logger) => {
+    cli.command("inspect-web-page", {
+        description: "Passively inspect one approved page through CDP",
+        args: z.object({
+            endpoint: z.string().describe("Configured loopback CDP HTTP endpoint"),
+            targetId: z.string().describe("Target ID from list-browser-targets"),
+        }),
+        options: z.object({
+            ...browserScopeOptions,
+            observationMs: z.number().int().min(0).max(10_000).default(500),
+            includeScriptSources: z.boolean().default(false),
+            includeStorageKeys: z.boolean().default(false),
+            maxFrames: z.number().int().min(1).max(1_000).default(200),
+            maxDomNodes: z.number().int().min(1).max(10_000).default(2_000),
+            maxAxNodes: z.number().int().min(1).max(10_000).default(2_000),
+            maxScripts: z.number().int().min(1).max(1_000).default(200),
+            maxResources: z.number().int().min(1).max(10_000).default(2_000),
+            maxWorkers: z.number().int().min(1).max(5_000).default(500),
+            maxStorageKeys: z.number().int().min(1).max(10_000).default(1_000),
+            maxScriptSourceBytes: z
+                .number()
+                .int()
+                .min(1)
+                .max(4 * 1_024 * 1_024)
+                .default(1_024 * 1_024),
+            maxTotalScriptSourceBytes: z
+                .number()
+                .int()
+                .min(1)
+                .max(16 * 1_024 * 1_024)
+                .default(4 * 1_024 * 1_024),
+            maxNetworkEvents: z.number().int().min(1).max(10_000).default(1_000),
+            maxConsoleEvents: z.number().int().min(1).max(2_000).default(200),
+            maxWebsocketEvents: z.number().int().min(1).max(5_000).default(500),
+        }),
+        run: ({ args, options }) => logCliCommand(logger, "inspect-web-page", async () => {
+            const context = await browserContext();
+            if (!context.ok)
+                return context.error;
+            const parsed = inspectWebPageInputSchema.safeParse({
+                cdp_endpoint: args.endpoint,
+                allowed_origins: options.allowedOrigins ?? context.allowedBrowserOrigins,
+                approved: options.approved,
+                target_id: args.targetId,
+                observation_ms: options.observationMs,
+                include_script_sources: options.includeScriptSources,
+                include_storage_keys: options.includeStorageKeys,
+                limits: {
+                    max_frames: options.maxFrames,
+                    max_dom_nodes: options.maxDomNodes,
+                    max_ax_nodes: options.maxAxNodes,
+                    max_scripts: options.maxScripts,
+                    max_resources: options.maxResources,
+                    max_workers: options.maxWorkers,
+                    max_storage_keys: options.maxStorageKeys,
+                    max_script_source_bytes: options.maxScriptSourceBytes,
+                    max_total_script_source_bytes: options.maxTotalScriptSourceBytes,
+                    max_network_events: options.maxNetworkEvents,
+                    max_console_events: options.maxConsoleEvents,
+                    max_websocket_events: options.maxWebsocketEvents,
+                },
+            });
+            if (!parsed.success)
+                return cliError(new AnalysisInputError("inspect_web_page"));
+            const result = await inspectWebPage(context.provider, context.authority, parsed.data);
+            return result.ok ? result.value : cliError(result.error);
+        }),
+    });
+};
+const browserContext = async () => {
+    const config = parseConfig(process.env);
+    if (!config.ok)
+        return { ok: false, error: cliError(config.error) };
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    if (!authority.ok)
+        return { ok: false, error: cliError(authority.error) };
+    return {
+        ok: true,
+        authority: authority.value,
+        provider: new CdpBrowserProvider(),
+        allowedBrowserOrigins: config.value.browserAllowedOrigins,
+    };
+};
+const cliError = (error) => ({
+    error: "Browser observation failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliEvidenceCommands.js

@@ -2,7 +2,8 @@ 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";
+import { AnalysisProtocolError, PermissionRequiredError, projectAnalysisError, } from "./domain/errors.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
 /** Register filesystem-gated Evidence v2 commands. */
 export const registerEvidenceCommands = (cli, logger) => {
     cli.command("evidence-import", {
@@ -14,6 +15,11 @@ export const registerEvidenceCommands = (cli, logger) => {
             const config = parseConfig(process.env);
             if (!config.ok)
                 return cliError(config.error);
+            const denied = await authorizeEvidence(config.value, [
+                { capability: "evidence_read", path: args.path, access: "read" },
+            ]);
+            if (denied !== undefined)
+                return cliError(denied);
             const imported = await importEvidenceBundleCommand(args.path, config.value.evidenceFilePolicy);
             return imported.ok ? imported.value : cliError(imported.error);
         }),
@@ -31,6 +37,12 @@ export const registerEvidenceCommands = (cli, logger) => {
             const config = parseConfig(process.env);
             if (!config.ok)
                 return cliError(config.error);
+            const denied = await authorizeEvidence(config.value, [
+                { capability: "evidence_read", path: args.source, access: "read" },
+                { capability: "evidence_write", path: args.output, access: "write" },
+            ]);
+            if (denied !== undefined)
+                return cliError(denied);
             const exported = await exportEvidenceBundleCommand(args.source, args.output, options.overwrite, config.value.evidenceFilePolicy);
             return exported.ok ? exported.value : cliError(exported.error);
         }),
@@ -50,6 +62,12 @@ export const registerEvidenceCommands = (cli, logger) => {
             const config = parseConfig(process.env);
             if (!config.ok)
                 return cliError(config.error);
+            const denied = await authorizeEvidence(config.value, [
+                { capability: "evidence_read", path: args.left, access: "read" },
+                { capability: "evidence_read", path: args.right, access: "read" },
+            ]);
+            if (denied !== undefined)
+                return cliError(denied);
             const compared = await compareEvidenceBundlesCommand({
                 leftPath: args.left,
                 rightPath: args.right,
@@ -61,6 +79,29 @@ export const registerEvidenceCommands = (cli, logger) => {
         }),
     });
 };
+const authorizeEvidence = async (config, requests) => {
+    const authority = await loadConfiguredPermissionAuthority(config);
+    if (!authority.ok)
+        return authority.error;
+    for (const request of requests) {
+        const result = await authority.value.authorize({
+            capability: request.capability,
+            roots: [request.path],
+            executables: [],
+            environment_names: [],
+            network: "none",
+            mount: false,
+            operation_identity: `cli:${request.capability}:${request.path}`,
+        }, request.access);
+        if (!result.ok)
+            return result.error instanceof PermissionRequiredError
+                ? result.error
+                : new AnalysisProtocolError(result.error.message, {
+                    cause: result.error,
+                });
+    }
+    return undefined;
+};
 const cliError = (error) => ({
     error: "Analysis failed",
     ...projectAnalysisError(error),

package/dist/cliInvestigationCommands.js

@@ -2,6 +2,9 @@ import { Cli, z } from "incur";
 import { runCrossVersionInvestigation } from "./application/CrossVersionInvestigation.js";
 import { logCliCommand } from "./cliLogging.js";
 import { parseConfig } from "./config.js";
+import { projectAnalysisError } from "./domain/errors.js";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { authorizeFileReadWithDeferredWrite, authorizeRootPermission, } from "./application/DeferredFileAuthorization.js";
 const investigationOptionsSchema = z.object({
     yes: z
         .boolean()
@@ -24,6 +27,9 @@ const investigationOptionsSchema = z.object({
         .default(268_435_456),
     pageSize: z.number().int().min(1).max(500).default(500),
     changeLimit: z.number().int().min(1).max(500).default(500),
+    integrityPolicy: z.enum(["fail", "record-and-continue"]).default("fail"),
+    integrityContinueApproved: z.boolean().default(false),
+    maxIntegrityMismatches: z.number().int().min(1).max(100).default(10),
 });
 /** Register the persistent cross-version CLI workflow. */
 export const registerInvestigationCommands = (cli, logger) => {
@@ -43,6 +49,9 @@ export const registerInvestigationCommands = (cli, logger) => {
             maxEntryBytes: "max-entry-bytes",
             pageSize: "page-size",
             changeLimit: "change-limit",
+            integrityPolicy: "integrity-policy",
+            integrityContinueApproved: "integrity-continue-approved",
+            maxIntegrityMismatches: "max-integrity-mismatches",
             yes: "y",
         },
         run: ({ args, options }) => logCliCommand(logger, "investigate-versions", () => runInvestigation(args, options)),
@@ -56,7 +65,26 @@ const runInvestigation = async (args, options) => {
         };
     const config = parseConfig(process.env);
     if (!config.ok)
-        return { error: config.error._tag, message: config.error.message };
+        return cliError(config.error);
+    const authority = await loadConfiguredPermissionAuthority(config.value);
+    if (!authority.ok)
+        return cliError(authority.error);
+    const workspaceAuthorization = await authorizeFileReadWithDeferredWrite(authority.value, {
+        path: args.workspacePath,
+        readCapability: "investigation_workspace_read",
+        writeCapability: "investigation_workspace_write",
+        operation: "investigate_versions",
+    });
+    if (!workspaceAuthorization.ok)
+        return cliError(workspaceAuthorization.error);
+    const inputAuthorization = await authorizeRootPermission(authority.value, {
+        capability: "investigation_input",
+        roots: [args.leftPath, args.rightPath],
+        access: "read",
+        operation: "investigate_versions",
+    });
+    if (!inputAuthorization.ok)
+        return cliError(inputAuthorization.error);
     const investigated = await runCrossVersionInvestigation({
         approved: true,
         workspace_path: args.workspacePath,
@@ -66,6 +94,9 @@ const runInvestigation = async (args, options) => {
             : { expected_workspace_revision: options.expectedRevision }),
         left_path: args.leftPath,
         right_path: args.rightPath,
+        integrity_policy: options.integrityPolicy,
+        integrity_continue_approved: options.integrityContinueApproved,
+        max_integrity_mismatches: options.maxIntegrityMismatches,
         options: {
             max_entries: options.maxEntries,
             max_total_bytes: options.maxTotalBytes,
@@ -76,11 +107,16 @@ const runInvestigation = async (args, options) => {
             page_size: options.pageSize,
             change_limit: options.changeLimit,
         },
-    }, config.value.evidenceFilePolicy, { inputRoots: config.value.investigationInputRoots });
+    }, config.value.evidenceFilePolicy, {
+        inputRoots: config.value.investigationInputRoots,
+        integrityContinueEnabled: config.value.artifactIntegrityContinueEnabled,
+        authorizeWorkspaceWrite: workspaceAuthorization.value.authorizeWrite,
+    });
     return investigated.ok
         ? investigated.value.evidence
-        : {
-            error: investigated.error._tag,
-            message: investigated.error.message,
-        };
+        : cliError(investigated.error);
 };
+const cliError = (error) => ({
+    error: "Analysis failed",
+    ...projectAnalysisError(error),
+});

package/dist/cliLogging.js

@@ -1,13 +1,30 @@
+const isRecord = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+/** Identify caller-visible CLI outcomes that mean the requested operation failed. */
+export const isCliOperationFailure = (value) => {
+    if (!isRecord(value))
+        return false;
+    if (typeof value.error === "string")
+        return true;
+    if (value.healthy === false)
+        return true;
+    return (value.status === "failed" ||
+        value.status === "needs_confirmation" ||
+        value.status === "needs_human" ||
+        value.status === "planned");
+};
 /** Log one CLI command with duration and a stable success or failure status. */
 export const logCliCommand = async (logger, command, execute) => {
     const startedAt = performance.now();
     try {
         const value = await execute();
-        logger.info({
+        const failed = isCliOperationFailure(value);
+        logger[failed ? "error" : "info"]({
             command,
             durationMs: Math.round((performance.now() - startedAt) * 100) / 100,
-            status: "ok",
-        }, "CLI command completed");
+            status: failed ? "error" : "ok",
+        }, failed ? "CLI command failed" : "CLI command completed");
+        if (failed)
+            process.exitCode = 1;
         return value;
     }
     catch (cause) {

package/dist/cliPolicyCommands.js

@@ -0,0 +1,118 @@
+import { Cli, z } from "incur";
+import { loadConfiguredPermissionAuthority } from "./application/PermissionConfiguration.js";
+import { readProjectPermissionStore, revokeProjectPermissionGrant, } from "./application/ProjectPermissionStore.js";
+import { logCliCommand } from "./cliLogging.js";
+import { parseConfig } from "./config.js";
+import { PermissionRequiredError, projectAnalysisError, } from "./domain/errors.js";
+const capabilitySchema = z.enum([
+    "process_capture",
+    "browser_observe",
+    "evidence_read",
+    "evidence_write",
+    "investigation_input",
+    "investigation_workspace_read",
+    "investigation_workspace_write",
+    "snapshot_read",
+    "snapshot_write",
+    "artifact_extract",
+    "native_mount",
+    "reference_read",
+]);
+/** Register inspectable, dry-run, and revocation policy UX for the CLI. */
+export const registerPolicyCommands = (cli, logger) => {
+    cli.command("policy", {
+        description: "Inspect, explain, or revoke unified local permission grants",
+        args: z.object({
+            action: z.enum(["status", "list", "explain", "revoke"]),
+            value: z.string().optional(),
+        }),
+        options: z.object({
+            root: z.string().optional(),
+            executable: z.string().optional(),
+            environmentNames: z.array(z.string()).default([]),
+            origins: z.array(z.string()).default([]),
+            network: z.enum(["none", "loopback", "external"]).default("none"),
+            mount: z.boolean().default(false),
+            write: z.boolean().default(false),
+        }),
+        alias: { environmentNames: "environment-names" },
+        run: ({ args, options }) => logCliCommand(logger, "policy", async () => {
+            const config = parseConfig(process.env);
+            if (!config.ok)
+                return failure(config.error);
+            if (args.action === "status")
+                return {
+                    reload: "SIGHUP",
+                    restart_required: false,
+                    administrator_ceilings: config.value.permissionCeilings,
+                    project_store: config.value.permissionProjectStore ?? null,
+                };
+            if (args.action === "list")
+                return readProjectGrants(config.value).then((result) => result.ok ? { grants: result.grants } : result.error);
+            if (args.action === "revoke") {
+                if (args.value === undefined)
+                    return { error: "Grant ID is required for policy revoke" };
+                const { permissionProjectRoot, permissionProjectStore } = config.value;
+                if (permissionProjectRoot === undefined ||
+                    permissionProjectStore === undefined)
+                    return { error: "Project policy is not configured" };
+                const revoked = await revokeProjectPermissionGrant(permissionProjectStore, permissionProjectRoot, args.value);
+                return revoked.ok && revoked.value
+                    ? {
+                        revoked: args.value,
+                        reload: "Send SIGHUP to the REA MCP process",
+                    }
+                    : revoked.ok
+                        ? { error: "Grant was not found", grant_id: args.value }
+                        : { error: revoked.error.message };
+            }
+            const capability = capabilitySchema.safeParse(args.value);
+            if (!capability.success)
+                return {
+                    error: "A registered capability is required for policy explain",
+                };
+            return explain(config.value, capability.data, options);
+        }),
+    });
+};
+const explain = async (config, capability, options) => {
+    const authority = await loadConfiguredPermissionAuthority(config);
+    if (!authority.ok)
+        return failure(authority.error);
+    const evaluated = await authority.value.explain({
+        capability,
+        roots: options.root === undefined ? [] : [options.root],
+        executables: options.executable === undefined ? [] : [options.executable],
+        environment_names: options.environmentNames,
+        origins: options.origins,
+        network: options.network,
+        mount: options.mount,
+        operation_identity: `policy_explain:${capability}`,
+    }, options.write ? "write" : "read");
+    return evaluated.ok
+        ? { allowed: true, grant_id: evaluated.value.grant_id }
+        : evaluated.error instanceof PermissionRequiredError
+            ? { allowed: false, error: projectAnalysisError(evaluated.error) }
+            : { allowed: false, error: evaluated.error.message };
+};
+const readProjectGrants = async (config) => {
+    if (config.permissionProjectRoot === undefined ||
+        config.permissionProjectStore === undefined)
+        return {
+            ok: false,
+            error: { error: "Project policy is not configured" },
+        };
+    const store = await readProjectPermissionStore(config.permissionProjectStore, config.permissionProjectRoot);
+    return store.ok
+        ? {
+            ok: true,
+            grants: store.value?.grants ?? [],
+            path: config.permissionProjectStore,
+            root: config.permissionProjectRoot,
+        }
+        : { ok: false, error: { error: store.error.message } };
+};
+const failure = (error) => ({
+    error: "Policy command failed",
+    ...projectAnalysisError(error),
+});