rea-agents 1.3.0 → 1.4.0

package/README.md

@@ -420,6 +420,27 @@ rea mcp
 
 REA accepts a Mac `.app` folder directly. If an agent cannot find an app by name, tell it where the app is installed.
 
+### CLI exit status
+
+| Status    | Meaning                                                                                                                                                                                                                                                                  |
+| --------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
+| `0`       | The requested operation completed. Truthful unknowns, warnings, and bounded or truncated evidence remain successful results.                                                                                                                                             |
+| `1`       | Arguments, policy, permission, provider analysis, integrity checking, cancellation, timeout, setup, diagnostics, update, uninstall, output encoding, or output writing prevented completion. Structured output identifies the failure category when REA could encode it. |
+| `128 + N` | The process ended from signal `N`, where the shell or runtime preserves the conventional signal-derived status.                                                                                                                                                          |
+
+`setup` returns `1` for `planned`, `needs_confirmation`, or `needs_human`
+because configuration is not ready; rerun it after approval or remediation.
+`doctor` returns `1` when any check is unhealthy. Output format, full envelopes,
+filters, and token controls never change the operation status.
+
+When REA feeds a shell pipeline, enable `pipefail` so a downstream formatter
+cannot hide its failure:
+
+```bash
+set -o pipefail
+rea inventory-artifact ./app.asar --json | jq . > inventory.json
+```
+
 ## Current Hopper provider
 
 REA starts Hopper when needed; Hopper does not need to be running first. Hopper's launcher internally activates the application, so opening a target may bring Hopper to the foreground. REA asks macOS to start Hopper hidden and in the background when possible, but cannot guarantee that it will remain behind the current application.

package/bridge/hopper_bridge.py

@@ -628,16 +628,23 @@ def _dispatch(method, params):
     global _selected_document
     if method == "health":
         return {"name": "REA Hopper bridge", "version": "1.0.0", "run_id": REA_RUN_ID}
-    if method == "shutdown":
+    if method in ("shutdown", "shutdown_document"):
         document = _session_document()
         if document is None:
             return {"shutdown": True, "analysis_stopped": True, "document_closed": True}
         if document.backgroundProcessActive():
             document.requestBackgroundProcessStop()
+        if method == "shutdown" and REA_OWNS_PROCESS_LIFETIME:
+            return {
+                "shutdown": True,
+                "analysis_stopped": not document.backgroundProcessActive(),
+                "document_closed": False,
+                "cleanup_required": True,
+            }
         if document.backgroundProcessActive():
             document.waitForBackgroundProcessToEnd()
-        analysis_stopped = not document.backgroundProcessActive()
         document.closeDocument()
+        analysis_stopped = not document.backgroundProcessActive()
         document_closed = _session_document() is None
         return {
             "shutdown": True,
@@ -806,7 +813,9 @@ def _serve_connection(connection):
             if not isinstance(request["token"], str) or not hmac.compare_digest(request["token"], REA_TOKEN):
                 raise PermissionError("Invalid bridge capability")
             result = _dispatch(request["method"], request["params"])
-            should_stop = request["method"] == "shutdown"
+            should_stop = request["method"] == "shutdown_document" or (
+                request["method"] == "shutdown" and not result.get("cleanup_required", False)
+            )
             response = {"id": request_id, "result": _json_safe(result)}
         except Exception as error:
             response = {"id": request_id if isinstance(request_id, int) else 0, "error": {"code": -32000, "message": str(error)[:512], "type": _diagnostic_type(error)}}

package/dist/application/ArtifactGraphConstruction.js

@@ -83,7 +83,7 @@ export const createArtifactNode = (input) => ({
     architecture: null,
     executable: input.executable,
     content_state: input.contentState,
-    limitations: [],
+    limitations: [...(input.limitations ?? [])],
 });
 export const rootOccurrenceFor = (node, declaredSize) => ({
     occurrence_id: `occ_${digestCanonical({ root: node.artifact_id })}`,

package/dist/application/ArtifactInventory.js

@@ -15,19 +15,28 @@ const NATIVE_MOUNT_DISABLED = {
     nativeMountApproved: false,
     nativeMountEnabled: false,
 };
+const STRICT_INTEGRITY_POLICY = {
+    mode: "fail",
+    approved: false,
+    enabled: false,
+    maxMismatches: 1,
+};
 /** Inventory one local artifact without extracting or mounting it. */
 export const inventoryArtifact = async (inputPath, limits, page, options = {}) => {
-    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED);
+    const snapshot = await scanArtifactInventory(inputPath, limits, options.signal, options.nativeMount ?? NATIVE_MOUNT_DISABLED, options.integrity ?? STRICT_INTEGRITY_POLICY);
     return paginateArtifactInventory(snapshot, page);
 };
 /** Scan an artifact once and retain the complete immutable graph for projection. */
-export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
+export const scanArtifactInventory = async (inputPath, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
     abortIfNeeded(signal);
     const path = await realpath(inputPath);
-    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount);
+    return scanCanonicalArtifactInventory(path, limits, signal, nativeMount, integrity);
 };
 /** Scan one already-canonical artifact path without resolving it again. */
-export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED) => {
+export const scanCanonicalArtifactInventory = async (path, limits, signal, nativeMount = NATIVE_MOUNT_DISABLED, integrity = STRICT_INTEGRITY_POLICY) => {
+    if (integrity.mode === "record-and-continue" &&
+        (!integrity.approved || !integrity.enabled))
+        throw new ArtifactReaderFailure("unavailable", "Integrity continuation requires explicit approval and operator policy");
     const metadata = await lstat(path);
     const rootFormat = await classifyRoot(path, metadata.isDirectory());
     const rootDigest = metadata.isDirectory()
@@ -35,7 +44,7 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
         : await hashReadable(createReadStream(path), limits.maxTotalBytes, signal);
     const reader = await createReader(path, rootFormat, nativeMount, signal);
     try {
-        const { nodes, occurrences } = await scanReader(reader, limits, signal);
+        const { nodes, occurrences, pendingContradictions } = await scanReader(reader, limits, signal, integrity);
         materializeDirectoryNodes(occurrences, nodes);
         const rootNode = createRootNode({
             path,
@@ -51,6 +60,36 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             if (occurrence.parent_occurrence_id === null)
                 occurrence.parent_occurrence_id = rootOccurrence.occurrence_id;
         occurrences.unshift(rootOccurrence);
+        const occurrenceById = new Map(occurrences.map((occurrence) => [occurrence.occurrence_id, occurrence]));
+        const integrityContradictions = pendingContradictions.map((contradiction) => {
+            const occurrence = occurrences.find(({ logical_path: path }) => path === contradiction.logicalPath);
+            if (occurrence === undefined)
+                throw new ArtifactReaderFailure("integrity", "Integrity contradiction lost its graph occurrence");
+            const parent = occurrence.parent_occurrence_id === null
+                ? undefined
+                : occurrenceById.get(occurrence.parent_occurrence_id);
+            const parentArtifactId = parent?.artifact_id ?? rootNode.artifact_id;
+            return {
+                contradiction_id: `ic_${digestCanonical({
+                    root_artifact_id: rootNode.artifact_id,
+                    logical_path: contradiction.logicalPath,
+                    declared_sha256: contradiction.declaredSha256,
+                    observed_sha256: contradiction.observedSha256,
+                })}`,
+                occurrence_id: occurrence.occurrence_id,
+                parent_artifact_id: parentArtifactId,
+                logical_path: contradiction.logicalPath,
+                declared_sha256: contradiction.declaredSha256,
+                observed_sha256: contradiction.observedSha256,
+                entry_kind: contradiction.entryKind,
+                unpacked: contradiction.unpacked,
+                trust: "observed-untrusted",
+                provenance: "container-integrity-metadata-versus-observed-bytes",
+                limitations: [
+                    "Observed bytes contradict declared integrity metadata and cannot support equivalence.",
+                ],
+            };
+        });
         const edges = createArtifactEdges(rootNode.artifact_id, occurrences, reader?.provenance()[0]);
         const orderedNodes = [...nodes.values()].sort((left, right) => left.artifact_id.localeCompare(right.artifact_id));
         const orderedOccurrences = occurrences.sort((left, right) => left.logical_path.localeCompare(right.logical_path, "en"));
@@ -65,6 +104,7 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             nodes: orderedNodes,
             occurrences: orderedOccurrences,
             edges: orderedEdges,
+            integrity_contradictions: integrityContradictions,
         });
         const manifestId = `agm_${digestCanonical({
             schema_version: 1,
@@ -88,7 +128,15 @@ export const scanCanonicalArtifactInventory = async (path, limits, signal, nativ
             edges: orderedEdges,
             limits: toOutputLimits(limits),
             provenance: reader?.provenance() ?? [],
-            limitations: inventoryLimitations(rootFormat, reader),
+            integrity_contradictions: integrityContradictions,
+            limitations: [
+                ...inventoryLimitations(rootFormat, reader),
+                ...(integrityContradictions.length === 0
+                    ? []
+                    : [
+                        `${String(integrityContradictions.length)} integrity contradiction(s) were recorded; mismatched content is observed-untrusted.`,
+                    ]),
+            ],
         };
     }
     finally {
@@ -149,11 +197,11 @@ const visitNestedAsar = async (adapterKey, logicalPath, visit) => {
 const isExpandableAsar = (entry, logicalPath) => entry.kind === "file" &&
     logicalPath.toLowerCase().endsWith(".asar") &&
     entry.adapterKey.startsWith("/");
-const emptyScan = () => ({ nodes: new Map(), occurrences: [] });
-const scanReader = async (reader, limits, signal) => {
-    const { nodes, occurrences } = emptyScan();
+const emptyScan = () => ({ nodes: new Map(), occurrences: [], pendingContradictions: [] });
+const scanReader = async (reader, limits, signal, integrity = STRICT_INTEGRITY_POLICY) => {
+    const { nodes, occurrences, pendingContradictions } = emptyScan();
     if (reader === undefined)
-        return { nodes, occurrences };
+        return { nodes, occurrences, pendingContradictions };
     const occurrenceByPath = new Map();
     const registry = new ArtifactPathRegistry();
     let totalBytes = 0;
@@ -167,24 +215,44 @@ const scanReader = async (reader, limits, signal) => {
             throw new ArtifactReaderFailure("limit", "Declared artifact bytes exceed remaining cumulative limit");
         const digest = await hashReadable(await currentReader.open(entry, signal), Math.min(limits.maxEntryBytes, remainingBytes), signal);
         totalBytes += digest.bytes;
-        if (entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256)
+        const mismatched = entry.declaredSha256 !== null && entry.declaredSha256 !== digest.sha256;
+        if (mismatched && integrity.mode === "fail")
             throw new ArtifactReaderFailure("integrity", `Artifact integrity metadata disagrees with content: ${logicalPath}`, undefined, {
                 logicalPath,
                 declaredSha256: entry.declaredSha256,
                 calculatedSha256: digest.sha256,
                 unpacked: entry.unpacked,
             });
+        if (mismatched && entry.declaredSha256 !== null) {
+            if (pendingContradictions.length >= integrity.maxMismatches)
+                throw new ArtifactReaderFailure("limit", "Artifact integrity mismatch limit exceeded");
+            pendingContradictions.push({
+                logicalPath,
+                declaredSha256: entry.declaredSha256,
+                observedSha256: digest.sha256,
+                entryKind: entry.kind,
+                unpacked: entry.unpacked,
+            });
+        }
         const classified = entry.kind === "slice"
             ? { kind: "universal-slice", format: "mach-o" }
             : classifyArtifactContent(logicalPath, digest.prefix);
-        return createArtifactNode({
-            sha256: digest.sha256,
-            size: digest.bytes,
-            kind: classified.kind,
-            format: classified.format,
-            executable: entry.executable,
-            contentState: "embedded",
-        });
+        return {
+            node: createArtifactNode({
+                sha256: digest.sha256,
+                size: digest.bytes,
+                kind: classified.kind,
+                format: classified.format,
+                executable: entry.executable,
+                contentState: "embedded",
+                limitations: mismatched
+                    ? [
+                        "Observed content contradicts declared integrity metadata and is untrusted.",
+                    ]
+                    : [],
+            }),
+            mismatched,
+        };
     };
     const visit = async (currentReader, prefix) => {
         for await (const entry of currentReader.entries(signal)) {
@@ -196,20 +264,24 @@ const scanReader = async (reader, limits, signal) => {
             preflightEntry(entry, limits);
             const parent = nearestParent(logicalPath, occurrenceByPath);
             const occurrence = createOccurrence(entry, logicalPath, parent?.occurrence_id ?? null);
-            const node = await digestEntry(currentReader, entry, logicalPath);
-            if (node !== undefined) {
-                nodes.set(node.artifact_id, node);
-                occurrence.artifact_id = node.artifact_id;
-                occurrence.hash_status = "verified";
+            const digested = await digestEntry(currentReader, entry, logicalPath);
+            if (digested !== undefined) {
+                nodes.set(digested.node.artifact_id, digested.node);
+                occurrence.artifact_id = digested.node.artifact_id;
+                occurrence.hash_status = digested.mismatched
+                    ? "mismatched"
+                    : "verified";
+                if (digested.mismatched)
+                    occurrence.limitations.push("Declared integrity metadata contradicts observed bytes.");
             }
             occurrences.push(occurrence);
             occurrenceByPath.set(logicalPath, occurrence);
-            if (expandableAsar)
+            if (expandableAsar && digested?.mismatched !== true)
                 await visitNestedAsar(entry.adapterKey, logicalPath, visit);
         }
     };
     await visit(reader, "");
-    return { nodes, occurrences };
+    return { nodes, occurrences, pendingContradictions };
 };
 const classifyRoot = async (path, directory) => {
     if (directory)

package/dist/application/AuthorizedArtifactInventory.js

@@ -3,7 +3,7 @@ import { ArtifactReaderFailure } from "../artifacts/ArtifactReader.js";
 import { withinRoot } from "../reference/ReferenceSourceReaderPaths.js";
 import { scanCanonicalArtifactInventory, } from "./ArtifactInventory.js";
 /** Resolve, authorize, and scan one artifact without a second path resolution. */
-export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal) => {
+export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits, signal, integrity) => {
     if (roots.length === 0)
         throw new ArtifactReaderFailure("path", "Artifact input roots are disabled");
     const [path, approved] = await Promise.all([
@@ -12,5 +12,5 @@ export const scanAuthorizedArtifactInventory = async (inputPath, roots, limits,
     ]);
     if (!approved.some((root) => withinRoot(root, path)))
         throw new ArtifactReaderFailure("path", "Artifact path is outside approved input roots");
-    return scanCanonicalArtifactInventory(path, limits, signal);
+    return scanCanonicalArtifactInventory(path, limits, signal, undefined, integrity);
 };

package/dist/application/BinarySession.js

@@ -10,6 +10,7 @@ import { OFFICIAL_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { snapshotMatchesTarget } from "../domain/analysisSnapshot.js";
 import { AnalysisSnapshotCache, isSnapshotCacheable, } from "./AnalysisSnapshotCache.js";
 import { UNKNOWN_REGISTRY_PROVIDER, unknownEvidenceLinks, unknownMutationEvidence, } from "./UnknownEvidence.js";
+import { parseInvestigationWorkspace, } from "../domain/investigationWorkspace.js";
 const OFFICIAL_OPERATIONS = new Set(OFFICIAL_TOOL_CONTRACTS.map(({ name }) => name));
 /**
  * Owns the single active target shared by CLI and MCP adapters.
@@ -32,6 +33,9 @@ export class BinarySession {
         maxBytes: 64 * 1024 * 1024,
     });
     #snapshot = new AnalysisSnapshotCache();
+    #investigationWorkspaces = new Map();
+    #runtimeAvailability = new Map();
+    #availabilityListeners = new Set();
     #snapshotsEnabled;
     #snapshotInvalidated = false;
     constructor(provider, options = {}) {
@@ -73,6 +77,11 @@ export class BinarySession {
         }
         return this.#providerIdentity;
     }
+    /** Observe runtime provider-health changes that affect discovery metadata. */
+    onAvailabilityChanged(listener) {
+        this.#availabilityListeners.add(listener);
+        return () => this.#availabilityListeners.delete(listener);
+    }
     /** Add one successful public observation to the session ledger. */
     recordEvidence(evidence) {
         return this.#evidence.record(evidence);
@@ -110,6 +119,24 @@ export class BinarySession {
             return err(new EvidenceIntegrityError("Analysis snapshots are unavailable with custom Hopper loader arguments"));
         return this.#snapshot.import(snapshot, this.#active?.target, (bundle) => this.#evidence.import(bundle));
     }
+    /** Retain one validated immutable workspace revision for session resources. */
+    retainInvestigationWorkspace(workspace) {
+        const parsed = parseInvestigationWorkspace(workspace);
+        const key = `${parsed.workspace_id}:${String(parsed.revision)}`;
+        if (this.#investigationWorkspaces.has(key))
+            return "duplicate";
+        this.#investigationWorkspaces.set(key, parsed);
+        return "added";
+    }
+    /** Read one session-retained immutable workspace revision. */
+    investigationWorkspace(workspaceId, revision) {
+        return this.#investigationWorkspaces.get(`${workspaceId}:${String(revision)}`);
+    }
+    /** List retained workspace revisions in canonical identity order. */
+    investigationWorkspaces() {
+        return [...this.#investigationWorkspaces.values()].sort((left, right) => left.workspace_id.localeCompare(right.workspace_id) ||
+            left.revision - right.revision);
+    }
     /** Create an approved residual unknown and immutable mutation evidence. */
     recordUnknown(input) {
         const evidence = unknownMutationEvidence(this.#active?.target, input);
@@ -189,6 +216,7 @@ export class BinarySession {
                 return err(new AnalysisCancelledError("open_binary"));
             }
             this.#active = { target: parsed.value, client };
+            this.#clearRuntimeAvailability();
             this.#snapshot.select(parsed.value);
             if (options.snapshot !== undefined) {
                 const imported = this.importAnalysisSnapshot(options.snapshot);
@@ -213,6 +241,7 @@ export class BinarySession {
             this.#evidence.clear();
             this.#snapshot.clear();
             this.#snapshotInvalidated = false;
+            this.#clearRuntimeAvailability();
             return ok(null);
         });
     }
@@ -237,6 +266,10 @@ export class BinarySession {
             ? []
             : [...this.#capabilities.values()]
                 .sort((left, right) => left.operation.localeCompare(right.operation))
+                .map((descriptor) => ({
+                ...descriptor,
+                ...this.#runtimeAvailability.get(descriptor.operation),
+            }))
                 .map((descriptor) => ({
                 operation: descriptor.operation,
                 available: descriptor.available,
@@ -304,6 +337,7 @@ export class BinarySession {
         this.#calls.add(call);
         try {
             const result = await call;
+            this.#observeRuntimeAvailability(name, result);
             if (result.ok && cacheable)
                 this.#snapshot.record(active.target, name, arguments_, result.value);
             else if (result.ok && capability?.effects.mutatesArtifact === true) {
@@ -316,6 +350,55 @@ export class BinarySession {
             this.#calls.delete(call);
         }
     }
+    #observeRuntimeAvailability(operation, result) {
+        if (result.ok) {
+            if (this.#setRuntimeAvailability(operation, true, null))
+                this.#emitAvailabilityChanged();
+            return;
+        }
+        if (result.error._tag === "AnalysisCapabilityUnavailableError") {
+            if (this.#setRuntimeAvailability(operation, false, result.error.message))
+                this.#emitAvailabilityChanged();
+            return;
+        }
+        if ([
+            "ProviderAdapterError",
+            "HopperProcessError",
+            "HopperStartError",
+            "HopperRemoteError",
+        ].includes(result.error._tag)) {
+            const providerId = this.#capabilities?.get(operation)?.provider.id;
+            let changed = false;
+            for (const descriptor of this.#capabilities?.values() ?? [])
+                if (providerId !== undefined && descriptor.provider.id === providerId)
+                    changed =
+                        this.#setRuntimeAvailability(descriptor.operation, false, "Provider became unavailable during this session.") || changed;
+            if (changed)
+                this.#emitAvailabilityChanged();
+        }
+    }
+    #setRuntimeAvailability(operation, available, reason) {
+        const current = this.#runtimeAvailability.get(operation);
+        if (current?.available === available && current.reason === reason)
+            return false;
+        if (available && current === undefined)
+            return false;
+        if (available)
+            this.#runtimeAvailability.delete(operation);
+        else
+            this.#runtimeAvailability.set(operation, { available, reason });
+        return true;
+    }
+    #clearRuntimeAvailability() {
+        if (this.#runtimeAvailability.size === 0)
+            return;
+        this.#runtimeAvailability.clear();
+        this.#emitAvailabilityChanged();
+    }
+    #emitAvailabilityChanged() {
+        for (const listener of this.#availabilityListeners)
+            listener();
+    }
     #serialize(operation) {
         const result = this.#transition.then(operation, operation);
         this.#transition = result.then(() => undefined, () => undefined);

package/dist/application/CapabilityInventory.js

@@ -0,0 +1,127 @@
+import { z } from "zod";
+import { TOOL_CONTRACTS } from "../contracts/toolContracts.js";
+const statusSchema = z.object({
+    open: z.boolean(),
+    kind: z.enum(["executable", "database", "archive", "artifact"]).optional(),
+    format: z.string().optional(),
+    capabilities: z.array(z.object({
+        operation: z.string(),
+        available: z.boolean(),
+        reason: z.string().nullable(),
+    })),
+});
+const ENHANCED_REQUIREMENTS = {
+    swift_classes: ["list_procedures"],
+    get_objc_classes: ["list_names"],
+    get_objc_protocols: ["list_names"],
+    batch_decompile: ["procedure_pseudo_code"],
+    get_call_graph: ["procedure_callees", "procedure_callers"],
+    analyze_swift_types: ["list_procedures"],
+    find_xrefs_to_name: ["list_names", "xrefs"],
+    binary_overview: [
+        "list_segments",
+        "list_documents",
+        "list_procedures",
+        "list_strings",
+    ],
+    analyze_function: ["analyze_function"],
+    trace_feature: [
+        "list_strings",
+        "list_procedures",
+        "xrefs",
+        "resolve_containing_procedure",
+    ],
+};
+/** Build stable per-operation availability without hiding familiar tools. */
+export const buildCapabilityInventory = (sessionStatus, policy) => {
+    const status = statusSchema.parse(sessionStatus);
+    const descriptors = new Map(status.capabilities.map((descriptor) => [descriptor.operation, descriptor]));
+    return TOOL_CONTRACTS.map((contract) => {
+        const availability = availabilityFor(contract.name, contract.kind, status.open, status.kind, descriptors, policy);
+        return {
+            name: contract.name,
+            surface: contract.kind,
+            available: availability.reason === "available",
+            reason: availability.reason,
+            remediation: availability.remediation,
+            annotations: {
+                read_only: contract.annotations.readOnlyHint ?? false,
+                destructive: contract.annotations.destructiveHint ?? false,
+                idempotent: contract.annotations.idempotentHint ?? false,
+                open_world: contract.annotations.openWorldHint ?? true,
+            },
+        };
+    }).sort((left, right) => left.name.localeCompare(right.name));
+};
+const availabilityFor = (name, kind, targetOpen, targetKind, descriptors, policy) => {
+    if (name === "capture_process_scenario" && !policy.processCaptureEnabled)
+        return {
+            reason: "policy_disabled",
+            remediation: "Enable or grant process_capture within the administrator ceiling.",
+        };
+    if (name === "import_evidence_bundle" && policy.evidenceFileRoots === 0)
+        return {
+            reason: "policy_disabled",
+            remediation: "Configure or grant an evidence_read root.",
+        };
+    if (kind === "session")
+        return { reason: "available", remediation: null };
+    if (!targetOpen)
+        return {
+            reason: "target_required",
+            remediation: "Call open_binary with a supported local target.",
+        };
+    if (targetKind !== undefined &&
+        targetKind !== "executable" &&
+        targetKind !== "database" &&
+        (kind === "official-proxy" || kind === "enhanced"))
+        return {
+            reason: "target_unsupported",
+            remediation: "Inventory or extract a native executable, then call open_binary on that executable.",
+        };
+    if (kind === "enhanced")
+        return composedAvailability(name, descriptors);
+    const descriptor = descriptors.get(name);
+    if (descriptor === undefined)
+        return {
+            reason: "provider_missing",
+            remediation: "Install or configure a provider that declares this operation.",
+        };
+    if (!descriptor.available &&
+        descriptor.reason?.toLowerCase().includes("require macos") === true)
+        return {
+            reason: "unsupported_host",
+            remediation: descriptor.reason,
+        };
+    return descriptor.available
+        ? { reason: "available", remediation: null }
+        : {
+            reason: "provider_unavailable",
+            remediation: descriptor.reason ?? "Choose another target or configured provider.",
+        };
+};
+const composedAvailability = (name, descriptors) => {
+    const requirements = ENHANCED_REQUIREMENTS[name];
+    if (requirements === undefined)
+        return {
+            reason: "provider_missing",
+            remediation: "No provider composition is declared for this operation.",
+        };
+    const missing = requirements.find((operation) => !descriptors.has(operation));
+    if (missing !== undefined)
+        return {
+            reason: "provider_missing",
+            remediation: `Configure a provider for required operation ${missing}.`,
+        };
+    const unavailable = requirements
+        .map((operation) => descriptors.get(operation))
+        .find((descriptor) => descriptor?.available === false);
+    if (unavailable !== undefined)
+        return {
+            reason: unavailable.reason?.toLowerCase().includes("require macos") === true
+                ? "unsupported_host"
+                : "provider_unavailable",
+            remediation: unavailable.reason ?? "Choose another target or configured provider.",
+        };
+    return { reason: "available", remediation: null };
+};

package/dist/application/ClientRegistrationStatus.js

@@ -0,0 +1,69 @@
+import { access, readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { parse as parseToml } from "smol-toml";
+import { z } from "zod";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { supportedClients } from "./SupportedClients.js";
+const objectSchema = z.record(z.string(), z.unknown());
+const registrationSchema = z
+    .object({ command: z.string().min(1), args: z.array(z.string()).default([]) })
+    .passthrough();
+/** Inspect supported client registrations without reading their environment. */
+export const readClientRegistrationStatuses = async (home, currentCommandPath = resolve(process.argv[1] ?? "unknown")) => {
+    const statuses = [];
+    for (const client of supportedClients(home)) {
+        if (client.format === "unsupported" || !(await exists(client.markerPath)))
+            continue;
+        try {
+            const content = await readFile(client.configPath, "utf8");
+            const document = objectSchema.parse(client.format === "toml" ? parseToml(content) : JSON.parse(content));
+            const servers = objectSchema.parse(document[client.format === "toml" ? "mcp_servers" : "mcpServers"] ?? {});
+            const raw = servers[PRODUCT_IDENTITY.mcpServerKey];
+            if (raw === undefined) {
+                statuses.push(status(client.name, client.configPath, [], "missing"));
+                continue;
+            }
+            const registration = registrationSchema.parse(raw);
+            const command = [registration.command, ...registration.args];
+            statuses.push(status(client.name, client.configPath, command, registrationAligned(command, currentCommandPath)
+                ? "aligned"
+                : "stale"));
+        }
+        catch (cause) {
+            statuses.push(status(client.name, client.configPath, [], isMissing(cause) ? "missing" : "invalid"));
+        }
+    }
+    return statuses.sort((left, right) => left.client.localeCompare(right.client));
+};
+const registrationAligned = (command, currentCommandPath) => {
+    if (command.length === 4 &&
+        command[0] === "npx" &&
+        command[1] === "-y" &&
+        command[2] === PRODUCT_IDENTITY.packageName &&
+        command[3] === "mcp")
+        return true;
+    return (command.length === 2 &&
+        command[1] === "mcp" &&
+        resolve(command[0] ?? "") === currentCommandPath);
+};
+const status = (client, configPath, command, state) => ({
+    client,
+    config_path: configPath,
+    command,
+    state,
+    remediation: state === "aligned"
+        ? null
+        : "Run rea setup to refresh this registration, then restart the client.",
+});
+const exists = async (path) => {
+    if (path === undefined)
+        return false;
+    try {
+        await access(path);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";