rea-agents 1.2.0 → 1.4.0

package/dist/server/registerSessionTools.js

@@ -2,12 +2,13 @@ import { z } from "zod";
 import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
-import { ok } from "../domain/result.js";
+import { err, ok } from "../domain/result.js";
 import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
 import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
 import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
-import { UnknownRegistryError } from "../domain/errors.js";
+import { readAnalysisSnapshot, writeAnalysisSnapshot, } from "../application/AnalysisSnapshotFiles.js";
+import { AnalysisProtocolError, PermissionRequiredError, UnknownRegistryError, } from "../domain/errors.js";
 import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, } from "./sessionToolPolicies.js";
 import { createProcessCaptureEvidence } from "../application/ProcessEvidence.js";
 import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
@@ -15,13 +16,25 @@ import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool
 import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
 import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
 import { registerInvestigationTools } from "./registerInvestigationTools.js";
+import { closeBinaryInputSchema, openBinaryInputSchema, } from "../contracts/sessionLifecycleInputs.js";
+import { registerSessionStatusTool } from "./registerSessionStatusTool.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+const permissionFailure = (failure) => {
+    if (failure.ok)
+        return err(new AnalysisProtocolError("Expected a denied permission"));
+    return err(failure.error instanceof PermissionRequiredError
+        ? failure.error
+        : new AnalysisProtocolError(failure.error.message, {
+            cause: failure.error,
+        }));
+};
 const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) => {
     if (scenario.unknown_registry_approved !== true)
         return ok(null);
     for (const residual of residuals) {
         const unknown = session.recordUnknown({
             approved: true,
-            question: `${residual.scope}: ${residual.reason}`,
+            question: `Was ${residual.scope} behavior fully observed during capture?`,
             severity: "medium",
             domain: `process-${residual.scope}`,
             supporting_evidence_ids: [evidence.evidence_id],
@@ -44,7 +57,7 @@ const recordProcessResidualUnknowns = (session, scenario, evidence, residuals) =
     }
     return ok(null);
 };
-const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, }) => {
+const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, permissionAuthority, }) => {
     server.registerTool(captureContract.name, {
         description: captureContract.description,
         inputSchema: captureContract.inputSchema,
@@ -52,7 +65,37 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         annotations: captureContract.annotations,
     }, async (input, context) => {
         const scenario = processScenarioSchema.parse(input);
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.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 toCallToolResult(permissionFailure(authorized), captureContract);
+        }
+        const progress = mcpProgressReporter(context);
+        await progress.report({
+            phase: captureContract.name,
+            completed: 0,
+            total: 1,
+            message: "started",
+        });
         const captured = await logToolExecution(logger, captureContract.name, () => captureProcessScenario(scenario, processPolicy, context.mcpReq.signal));
+        await progress.report({
+            phase: captureContract.name,
+            completed: 1,
+            total: 1,
+            message: captured.ok ? "completed" : "failed",
+            terminal: true,
+        });
         if (!captured.ok)
             return toCallToolResult(captured, captureContract);
         const evidence = createProcessCaptureEvidence(scenario, captured.value);
@@ -65,7 +108,7 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         return toCallToolResult(ok(evidence), captureContract);
     });
 };
-const registerEvidenceTools = ({ server, session, exportContract, importContract, filePolicy, }) => {
+const registerEvidenceTools = ({ server, session, exportContract, importContract, filePolicy, permissionAuthority, }) => {
     server.registerTool(exportContract.name, {
         description: exportContract.description,
         inputSchema: exportContract.inputSchema,
@@ -81,6 +124,19 @@ const registerEvidenceTools = ({ server, session, exportContract, importContract
         const bundle = session.exportEvidenceBundle();
         if (parsed.path === undefined)
             return toCallToolResult(ok(bundle), exportContract);
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "evidence_write",
+                roots: [parsed.path],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `export_evidence:${parsed.path}`,
+            }, "write");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), exportContract);
+        }
         const written = await writeEvidenceBundle(bundle, parsed.path, parsed.overwrite, filePolicy);
         return written.ok
             ? toCallToolResult(ok({
@@ -97,6 +153,19 @@ const registerEvidenceTools = ({ server, session, exportContract, importContract
         annotations: importContract.annotations,
     }, async (input) => {
         const path = z.object({ path: z.string().min(1) }).parse(input).path;
+        if (permissionAuthority !== undefined) {
+            const authorized = await permissionAuthority.authorize({
+                capability: "evidence_read",
+                roots: [path],
+                executables: [],
+                environment_names: [],
+                network: "none",
+                mount: false,
+                operation_identity: `import_evidence:${path}`,
+            }, "read");
+            if (!authorized.ok)
+                return toCallToolResult(permissionFailure(authorized), importContract);
+        }
         const loaded = await readEvidenceBundle(path, filePolicy);
         if (!loaded.ok)
             return toCallToolResult(loaded, importContract);
@@ -163,7 +232,7 @@ const registerUnknownTools = ({ server, session, contracts: [listContract, recor
         return toCallToolResult(session.verifyUnknownResolution(unknownId), verifyContract);
     });
 };
-const registerLifecycleTools = (server, session, logger, contracts) => {
+const registerLifecycleTools = ({ server, session, logger, contracts, snapshotFilePolicy, startedAt, availabilityPolicy, permissionAuthority, }) => {
     const [openContract, closeContract, statusContract] = contracts;
     server.registerTool(openContract.name, {
         description: openContract.description,
@@ -171,8 +240,33 @@ const registerLifecycleTools = (server, session, logger, contracts) => {
         outputSchema: openContract.outputSchema,
         annotations: openContract.annotations,
     }, async (input, context) => {
-        const parsed = z.object({ path: z.string().min(1) }).parse(input);
-        const opened = await logToolExecution(logger, openContract.name, () => session.open(parsed.path, { signal: context.mcpReq.signal }));
+        const parsed = openBinaryInputSchema.parse(input);
+        let snapshot;
+        if (parsed.snapshot_path !== undefined) {
+            if (permissionAuthority !== undefined) {
+                const authorized = await permissionAuthority.authorize({
+                    capability: "snapshot_read",
+                    roots: [parsed.snapshot_path],
+                    executables: [],
+                    environment_names: [],
+                    network: "none",
+                    mount: false,
+                    operation_identity: `open_binary:snapshot:${parsed.snapshot_path}`,
+                }, "read");
+                if (!authorized.ok)
+                    return toCallToolResult(permissionFailure(authorized), openContract);
+            }
+            const loaded = await readAnalysisSnapshot(parsed.snapshot_path, snapshotFilePolicy);
+            if (!loaded.ok)
+                return toCallToolResult(loaded, openContract);
+            snapshot = loaded.value;
+        }
+        const opened = await logToolExecution(logger, openContract.name, () => session.open(parsed.path, {
+            signal: context.mcpReq.signal,
+            ...(snapshot === undefined ? {} : { snapshot }),
+        }));
+        if (opened.ok)
+            server.sendToolListChanged();
         return opened.ok
             ? toCallToolResult({
                 ok: true,
@@ -192,29 +286,76 @@ const registerLifecycleTools = (server, session, logger, contracts) => {
         inputSchema: closeContract.inputSchema,
         outputSchema: closeContract.outputSchema,
         annotations: closeContract.annotations,
-    }, async () => toCallToolResult(await logToolExecution(logger, closeContract.name, () => session.close()), closeContract));
-    server.registerTool(statusContract.name, {
-        description: statusContract.description,
-        inputSchema: statusContract.inputSchema,
-        outputSchema: statusContract.outputSchema,
-        annotations: statusContract.annotations,
-    }, () => toCallToolResult({ ok: true, value: session.status() }, statusContract));
+    }, async (input) => {
+        const parsed = closeBinaryInputSchema.parse(input);
+        if (parsed.snapshot_path !== undefined) {
+            if (permissionAuthority !== undefined) {
+                const authorized = await permissionAuthority.authorize({
+                    capability: "snapshot_write",
+                    roots: [parsed.snapshot_path],
+                    executables: [],
+                    environment_names: [],
+                    network: "none",
+                    mount: false,
+                    operation_identity: `close_binary:snapshot:${parsed.snapshot_path}`,
+                }, "write");
+                if (!authorized.ok)
+                    return toCallToolResult(permissionFailure(authorized), closeContract);
+            }
+            const snapshot = session.exportAnalysisSnapshot();
+            if (!snapshot.ok)
+                return toCallToolResult(snapshot, closeContract);
+            const written = await writeAnalysisSnapshot(snapshot.value, parsed.snapshot_path, parsed.overwrite, snapshotFilePolicy);
+            if (!written.ok)
+                return toCallToolResult(written, closeContract);
+            const closed = await logToolExecution(logger, closeContract.name, () => session.close());
+            if (closed.ok)
+                server.sendToolListChanged();
+            return closed.ok
+                ? toCallToolResult(ok({
+                    path: written.value.path,
+                    bytes: written.value.bytes,
+                    entries: snapshot.value.entries.length,
+                }), closeContract)
+                : toCallToolResult(closed, closeContract);
+        }
+        const closed = await logToolExecution(logger, closeContract.name, () => session.close());
+        if (closed.ok)
+            server.sendToolListChanged();
+        return toCallToolResult(closed, closeContract);
+    });
+    registerSessionStatusTool(server, session, statusContract, startedAt, availabilityPolicy);
 };
 export const registerSessionTools = (server, session, logger, options = {}) => {
     const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
     const evidenceFilePolicy = options.evidenceFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
+    const analysisSnapshotFilePolicy = options.analysisSnapshotFilePolicy ?? DENY_EVIDENCE_FILE_POLICY;
     const [openContract, closeContract, statusContract, exportContract, importContract, captureContract, compareContract, compareArtifactsContract, compareFunctionsContract, compareBundlesContract, changedBehaviorContract, callPathContract, staticRuntimeContract, reconstructionContract, listUnknownContract, recordUnknownContract, updateUnknownContract, verifyUnknownContract,] = SESSION_TOOL_CONTRACTS;
-    registerLifecycleTools(server, session, logger, [
-        openContract,
-        closeContract,
-        statusContract,
-    ]);
+    registerLifecycleTools({
+        server,
+        session,
+        logger,
+        contracts: [openContract, closeContract, statusContract],
+        snapshotFilePolicy: analysisSnapshotFilePolicy,
+        startedAt: options.startedAt ?? new Date().toISOString(),
+        availabilityPolicy: options.availabilityPolicy ??
+            (() => ({
+                processCaptureEnabled: processPolicy.enabled,
+                evidenceFileRoots: evidenceFilePolicy.roots.length,
+            })),
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
+    });
     registerEvidenceTools({
         server,
         session,
         exportContract,
         importContract,
         filePolicy: evidenceFilePolicy,
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerProcessTools({
         server,
@@ -222,17 +363,32 @@ export const registerSessionTools = (server, session, logger, options = {}) => {
         logger,
         processPolicy,
         captureContract,
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
     });
     registerProcessComparisonTool(server, session, compareContract);
     registerArtifactComparisonTool(server, session, compareArtifactsContract);
     registerFunctionComparisonTool(server, session, compareFunctionsContract);
     registerBundleComparisonTool(server, session, compareBundlesContract);
-    registerInvestigationTools(server, session, [
+    const investigationContracts = [
         changedBehaviorContract,
         callPathContract,
         staticRuntimeContract,
         reconstructionContract,
-    ]);
+    ];
+    registerInvestigationTools(server, session, investigationContracts, {
+        evidenceFiles: evidenceFilePolicy,
+        inputRoots: options.investigationInputRoots ?? [],
+        ...(options.artifactIntegrityContinueEnabled === undefined
+            ? {}
+            : {
+                integrityContinueEnabled: options.artifactIntegrityContinueEnabled,
+            }),
+        ...(options.permissionAuthority === undefined
+            ? {}
+            : { permissionAuthority: options.permissionAuthority }),
+    });
     registerUnknownTools({
         server,
         session,

package/dist/server/runDerivedOperation.js

@@ -0,0 +1,35 @@
+import { setImmediate } from "node:timers/promises";
+import { AnalysisCancelledError } from "../domain/errors.js";
+import { err, ok } from "../domain/result.js";
+import { mcpProgressReporter } from "./mcpProgress.js";
+/** Run synchronous derived work with transport yields and a publication guard. */
+export const runDerivedOperation = async (context, operation, compute) => {
+    const progress = mcpProgressReporter(context);
+    await progress.report({
+        phase: "prepare",
+        completed: 0,
+        total: 2,
+        message: `Preparing ${operation}`,
+    });
+    await setImmediate();
+    if (context.mcpReq.signal.aborted)
+        return err(new AnalysisCancelledError(operation));
+    const value = compute();
+    await progress.report({
+        phase: "compute",
+        completed: 1,
+        total: 2,
+        message: `Computed ${operation}`,
+    });
+    await setImmediate();
+    if (context.mcpReq.signal.aborted)
+        return err(new AnalysisCancelledError(operation));
+    await progress.report({
+        phase: "complete",
+        completed: 2,
+        total: 2,
+        message: `Completed ${operation}`,
+        terminal: true,
+    });
+    return ok(value);
+};

package/dist/server/sessionEvidence.js

@@ -9,7 +9,7 @@ export const resolveSessionEvidence = (session, input) => {
     for (const item of supplied) {
         const parsed = parseEvidence(item);
         const owned = session.evidenceById(parsed.evidence_id);
-        if (owned === undefined || canonicalJson(owned) !== canonicalJson(parsed))
+        if (owned === undefined || canonicalize(owned) !== canonicalize(parsed))
             return err(new EvidenceIntegrityError("Comparison input does not match its session-owned Evidence"));
         authoritative.push(owned);
     }
@@ -18,11 +18,5 @@ export const resolveSessionEvidence = (session, input) => {
 /** Check exact ownership for a single Evidence record. */
 export const isSessionEvidence = (session, input) => {
     const owned = session.evidenceById(input.evidence_id);
-    return owned !== undefined && canonicalJson(owned) === canonicalJson(input);
-};
-const canonicalJson = (value) => {
-    const encoded = canonicalize(value);
-    if (encoded === undefined)
-        throw new TypeError("Evidence could not be canonicalized");
-    return encoded;
+    return owned !== undefined && canonicalize(owned) === canonicalize(input);
 };

package/dist/server/sessionToolPolicies.js

@@ -15,45 +15,4 @@ export const DENY_EVIDENCE_FILE_POLICY = {
     maxNodes: 1_000_000,
 };
 export { PROCESS_PROVIDER } from "../application/ProcessEvidence.js";
-/** Provider identity for deterministic cross-artifact comparisons. */
-export const ARTIFACT_COMPARISON_PROVIDER = {
-    id: "rea-artifact-comparison",
-    name: "REA artifact comparison",
-    version: "1",
-};
-/** Provider identity for deterministic cross-function comparisons. */
-export const FUNCTION_COMPARISON_PROVIDER = {
-    id: "rea-function-comparison",
-    name: "REA function comparison",
-    version: "1",
-};
-/** Provider identity for deterministic Evidence bundle comparisons. */
-export const BUNDLE_COMPARISON_PROVIDER = {
-    id: "rea-bundle-comparison",
-    name: "REA Evidence bundle comparison",
-    version: "1",
-};
-/** Provider identity for comparison-Evidence behavior aggregation. */
-export const CHANGED_BEHAVIOR_PROVIDER = {
-    id: "rea-changed-behavior",
-    name: "REA changed behavior investigation",
-    version: "1",
-};
-/** Provider identity for Evidence-backed call-path reconstruction. */
-export const CALL_PATH_PROVIDER = {
-    id: "rea-call-path",
-    name: "REA call path reconstruction",
-    version: "1",
-};
-/** Provider identity for explicit static/runtime hypothesis correlation. */
-export const STATIC_RUNTIME_PROVIDER = {
-    id: "rea-static-runtime-correlation",
-    name: "REA static/runtime correlation",
-    version: "1",
-};
-/** Provider identity for finite reconstruction specification verification. */
-export const RECONSTRUCTION_PROVIDER = {
-    id: "rea-reconstruction-verifier",
-    name: "REA reconstruction verifier",
-    version: "1",
-};
+export { ARTIFACT_COMPARISON_PROVIDER, BUNDLE_COMPARISON_PROVIDER, CALL_PATH_PROVIDER, CHANGED_BEHAVIOR_PROVIDER, FUNCTION_COMPARISON_PROVIDER, RECONSTRUCTION_PROVIDER, STATIC_RUNTIME_PROVIDER, } from "../application/InvestigationProviders.js";

package/dist/server/toolResult.js

@@ -1,23 +1,26 @@
-import { projectAnalysisError } from "../domain/errors.js";
+import { AnalysisOutputError, projectAnalysisError, } from "../domain/errors.js";
 /**
  * Translate an application result into MCP text content.
  * Error tags and safe messages remain visible while underlying causes, process
  * output, and other potentially sensitive details stay private.
  */
-export const toCallToolResult = (result, contract) => result.ok ? successResult(result.value, contract) : errorResult(result.error);
+export const toCallToolResult = (result, contract, options = {}) => result.ok
+    ? successResult(result.value, contract, options)
+    : errorResult(result.error);
 const errorResult = (error) => {
     const projected = projectAnalysisError(error);
     return {
         content: [
             {
                 type: "text",
-                text: `${projected.tag}: ${projected.message}`,
+                text: projected.message,
             },
         ],
+        structuredContent: { error: projected },
         isError: true,
     };
 };
-const successResult = (value, contract) => {
+const successResult = (value, contract, options) => {
     const candidate = contract.kind === "session" ? { result: value } : value;
     const parsed = contract.outputSchema.safeParse(candidate);
     if (!parsed.success) {
@@ -25,17 +28,42 @@ const successResult = (value, contract) => {
             content: [
                 {
                     type: "text",
-                    text: "AnalysisOutputError: Analysis output does not match the tool contract",
+                    text: "Analysis returned an unreadable result. Retry once; if it continues, run `rea doctor`.",
                 },
             ],
+            structuredContent: {
+                error: projectAnalysisError(new AnalysisOutputError(contract.name, "output does not match the tool contract")),
+            },
             isError: true,
         };
     }
     return {
-        content: [{ type: "text", text: formatValue(value) }],
+        content: [
+            { type: "text", text: formatValue(value) },
+            ...evidenceResourceLinks(value, contract.kind === "session" ||
+                options.evidenceResourcesAvailable === true),
+        ],
         structuredContent: candidate,
     };
 };
+const evidenceResourceLinks = (value, available) => {
+    if (!available ||
+        typeof value !== "object" ||
+        value === null ||
+        Array.isArray(value) ||
+        typeof value.evidence_id !== "string" ||
+        !/^ev_[a-f0-9]{64}$/u.test(value.evidence_id))
+        return [];
+    return [
+        {
+            type: "resource_link",
+            uri: `rea://evidence/${value.evidence_id}`,
+            name: value.evidence_id,
+            description: "Session-owned Evidence v2 record",
+            mimeType: "application/json",
+        },
+    ];
+};
 const formatValue = (value) => {
     if (value === null)
         return "OK";

package/dist/serverIdentity.js

@@ -0,0 +1,70 @@
+import { dirname, basename, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CATALOG_IDENTITY } from "./catalogIdentity.js";
+import { PRODUCT_IDENTITY, SDK_IDENTITY } from "./identity.js";
+const packageRoot = () => {
+    const moduleDirectory = dirname(fileURLToPath(import.meta.url));
+    return basename(moduleDirectory) === "src" &&
+        basename(dirname(moduleDirectory)) === "dist"
+        ? resolve(moduleDirectory, "../..")
+        : resolve(moduleDirectory, "..");
+};
+/** Build one runtime identity without claiming alignment from absent observations. */
+export const createServerIdentity = (input) => {
+    const serverPath = resolve(process.argv[1] ?? "unknown");
+    const reasons = [];
+    if (input.expected?.package_version !== undefined &&
+        input.expected.package_version !== PRODUCT_IDENTITY.packageVersion)
+        reasons.push("package_version_mismatch");
+    if (input.expected?.catalog_digest !== undefined &&
+        input.expected.catalog_digest !== CATALOG_IDENTITY.digests.combined_sha256)
+        reasons.push("catalog_digest_mismatch");
+    if (input.expected?.server_path !== undefined &&
+        resolve(input.expected.server_path) !== serverPath)
+        reasons.push("registration_path_mismatch");
+    const observedExpectation = input.expected !== undefined &&
+        Object.values(input.expected).some((value) => value !== undefined);
+    return {
+        package: {
+            name: PRODUCT_IDENTITY.packageName,
+            version: PRODUCT_IDENTITY.packageVersion,
+            root_path: packageRoot(),
+            build_commit: process.env.REA_BUILD_COMMIT ?? null,
+        },
+        server: {
+            name: PRODUCT_IDENTITY.mcpServerKey,
+            version: PRODUCT_IDENTITY.packageVersion,
+            started_at: input.startedAt,
+            command_path: serverPath,
+        },
+        sdk: SDK_IDENTITY,
+        negotiated_protocol_version: input.protocolVersion ?? null,
+        client: input.client === undefined
+            ? null
+            : { name: input.client.name, version: input.client.version },
+        skill: {
+            name: PRODUCT_IDENTITY.skillName,
+            expected_version: PRODUCT_IDENTITY.skillVersion,
+        },
+        catalog: CATALOG_IDENTITY,
+        protocol_features: {
+            progress: true,
+            cancellation: true,
+            evidence_resources: true,
+            elicitation: false,
+        },
+        alignment: {
+            state: reasons.length > 0
+                ? "mcp_server_restart_required"
+                : observedExpectation
+                    ? "aligned"
+                    : "unknown",
+            reasons,
+            remediation: reasons.length > 0
+                ? "Restart the registered MCP server/client, then compare identity again."
+                : observedExpectation
+                    ? null
+                    : "Supply expected package, catalog, or registration identity to compare the live server.",
+        },
+    };
+};

package/install.sh

@@ -17,7 +17,7 @@ usage() {
   cat <<'EOF'
 Usage: install.sh [--version VERSION] [--dry-run] [--no-setup] [--no-prompt] [--verbose]
 
-Installs only the REA CLI. Run `rea setup` separately to configure Hopper and coding agents.
+Installs only the REA CLI. Run `rea setup` separately to configure Hopper and agents.
 EOF
 }
 
@@ -54,13 +54,13 @@ fi
 
 platform="$(uname -s)"
 [[ "$platform" == "Darwin" || "$platform" == "Linux" ]] || fail "REA supports macOS and selected 64-bit Linux distributions."
-command -v curl >/dev/null 2>&1 || fail "curl is required."
+command -v curl >/dev/null 2>&1 || fail "curl is required. Install curl, then rerun this installer."
 command -v node >/dev/null 2>&1 || fail "Node.js 22.19+ or 24.11+ is required; install it from https://nodejs.org and retry."
 command -v npm >/dev/null 2>&1 || fail "npm is required; install it with Node.js and retry."
 
 node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
 IFS=. read -r node_major node_minor _node_patch <<<"$node_version"
-[[ "$node_major" =~ ^[0-9]+$ && "$node_minor" =~ ^[0-9]+$ ]] || fail "could not determine the active Node.js version."
+[[ "$node_major" =~ ^[0-9]+$ && "$node_minor" =~ ^[0-9]+$ ]] || fail "the active Node.js version could not be read. Check that node works and is on PATH, then retry."
 if ! ((node_major == 22 && node_minor >= 19 || node_major >= 24)); then
   fail "Node.js $node_version is unsupported; use Node.js 22.19+ or 24.11+."
 fi
@@ -71,9 +71,9 @@ fi
 if [[ -n "$version" ]]; then
   [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || fail "version must be an exact semantic version."
 else
-  release_json="$(curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "could not resolve the latest GitHub release."
-  tag="$(printf '%s' "$release_json" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const v=JSON.parse(s).tag_name;if(typeof v!=="string")process.exit(1);process.stdout.write(v)})')" || fail "GitHub returned malformed release metadata."
-  [[ "$tag" =~ ^rea-agents-([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$ ]] || fail "latest release tag is not a valid rea-agents release."
+  release_json="$(curl -fsSL --proto '=https' --tlsv1.2 --retry 3 -H 'Accept: application/vnd.github+json' "https://api.github.com/repos/$REPOSITORY/releases/latest")" || fail "the latest REA release could not be resolved. Check network access or pass --version VERSION, then retry."
+  tag="$(printf '%s' "$release_json" | node -e 'let s="";process.stdin.on("data",c=>s+=c).on("end",()=>{const v=JSON.parse(s).tag_name;if(typeof v!=="string")process.exit(1);process.stdout.write(v)})' 2>/dev/null)" || fail "the release response was invalid. Retry later or pass --version VERSION."
+  [[ "$tag" =~ ^rea-agents-([0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?)$ ]] || fail "the latest release tag was invalid. Retry later or pass --version VERSION."
   version="${BASH_REMATCH[1]}"
 fi
 
@@ -82,7 +82,7 @@ if [[ "$platform" == "Linux" ]]; then
   prefix_args=(--prefix "$HOME/.local")
   install_bin="$HOME/.local/bin/rea"
 else
-  npm_prefix="$(npm prefix --global)" || fail "could not determine the npm global prefix."
+  npm_prefix="$(npm prefix --global)" || fail "the npm global prefix could not be read. Repair the npm configuration, then retry."
   install_bin="$npm_prefix/bin/rea"
 fi
 
@@ -99,9 +99,9 @@ if [[ "$dry_run" == true ]]; then
 fi
 
 printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
-npm install --global "${prefix_args[@]}" "$PACKAGE@$version" || fail "npm package installation failed."
-[[ -x "$install_bin" ]] || fail "the rea command was not installed at $install_bin."
-installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "could not read the installed REA version."
+npm install --global "${prefix_args[@]}" "$PACKAGE@$version" || fail "npm could not install REA. Check registry access and npm permissions, then retry."
+[[ -x "$install_bin" ]] || fail "npm completed without installing the rea command. Check the npm global bin directory and PATH, then retry."
+installed_version="$("$install_bin" --version 2>/dev/null | tr -d '[:space:]')" || fail "the installed REA version could not be read. Reinstall the requested version, then retry."
 [[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version."
 
 printf 'REA %s is installed.\n' "$version"
@@ -109,5 +109,5 @@ if [[ "$start_setup" == true && -r /dev/tty && -w /dev/tty && -t 1 ]]; then
   printf 'Starting REA setup...\n'
   "$install_bin" setup </dev/tty >/dev/tty
 else
-  printf 'Run %s setup to configure Hopper and coding agents.\n' "$install_bin"
+  printf 'Run %s setup to configure Hopper and agents.\n' "$install_bin"
 fi