rea-agents 0.3.0 → 0.4.0

package/dist/server/registerSessionTools.js

@@ -2,24 +2,57 @@ import { z } from "zod";
 import { SESSION_TOOL_CONTRACTS } from "../contracts/toolContracts.js";
 import { toCallToolResult } from "./toolResult.js";
 import { logToolExecution } from "./toolLogging.js";
-import { err, ok } from "../domain/result.js";
-import { EvidenceLedgerError } from "../domain/errors.js";
-import { compareProcessCaptures, processCaptureSchema, processScenarioSchema, } from "../domain/processCapture.js";
+import { ok } from "../domain/result.js";
+import { processScenarioSchema } from "../domain/processCapture.js";
 import { captureProcessScenario } from "../application/ProcessHarness.js";
 import { createEvidence } from "../domain/evidence.js";
 import { jsonValueSchema } from "../domain/jsonValue.js";
-const DENY_PROCESS_POLICY = {
-    enabled: false,
-    executableRoots: [],
-    workingRoots: [],
-    allowedEnvironment: [],
-};
-const PROCESS_PROVIDER = {
-    id: "rea-process",
-    name: "REA deterministic process harness",
-    version: "1",
+import { recordUnknownInputSchema, updateUnknownInputSchema, } from "../domain/residualUnknown.js";
+import { readEvidenceBundle, writeEvidenceBundle, } from "../application/EvidenceBundleFiles.js";
+import { UnknownRegistryError } from "../domain/errors.js";
+import { DENY_EVIDENCE_FILE_POLICY, DENY_PROCESS_POLICY, PROCESS_PROVIDER, } from "./sessionToolPolicies.js";
+import { registerProcessComparisonTool } from "./registerProcessComparisonTool.js";
+import { registerArtifactComparisonTool } from "./registerArtifactComparisonTool.js";
+import { registerFunctionComparisonTool } from "./registerFunctionComparisonTool.js";
+import { registerBundleComparisonTool } from "./registerBundleComparisonTool.js";
+import { registerInvestigationTools } from "./registerInvestigationTools.js";
+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}`,
+            severity: "medium",
+            domain: `process-${residual.scope}`,
+            supporting_evidence_ids: [evidence.evidence_id],
+            contradicting_evidence_ids: [],
+            required_authority: "controlled-replay",
+            required_confidence: "observed",
+            required_environment: evidence.environment,
+            recommended_probes: [
+                {
+                    operation: "capture_process_scenario",
+                    rationale: "Repeat with a scenario that observes the missing behavior.",
+                },
+            ],
+            relationships: [],
+        });
+        if (!unknown.ok &&
+            !(unknown.error instanceof UnknownRegistryError &&
+                unknown.error.reason === "already-exists"))
+            return unknown;
+    }
+    return ok(null);
 };
-const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, compareContract, }) => {
+const processEvidenceParameters = (scenario) => ({
+    executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,
+    argument_count: scenario.arguments.length,
+    event_count: scenario.events.length,
+    filesystem_root_count: scenario.filesystem_roots.length,
+    normalization: scenario.normalization,
+});
+const registerProcessTools = ({ server, session, logger, processPolicy, captureContract, }) => {
     server.registerTool(captureContract.name, {
         description: captureContract.description,
         inputSchema: captureContract.inputSchema,
@@ -31,14 +64,9 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
         if (!captured.ok)
             return toCallToolResult(captured, captureContract);
         const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-capture/v1",
+            predicateType: "rea.process-capture/v2",
             operation: captureContract.name,
-            parameters: {
-                executable_name: scenario.executable.split("/").at(-1) ?? scenario.executable,
-                argument_count: scenario.arguments.length,
-                event_count: scenario.events.length,
-                filesystem_root_count: scenario.filesystem_roots.length,
-            },
+            parameters: processEvidenceParameters(scenario),
             result: jsonValueSchema.parse(captured.value),
             confidence: "observed",
             authority: "controlled-replay",
@@ -50,69 +78,115 @@ const registerProcessTools = ({ server, session, logger, processPolicy, captureC
             },
             limitations: captured.value.limitations,
         });
-        session.recordEvidence(evidence);
+        const recorded = session.recordEvidence(evidence);
+        if (!recorded.ok)
+            return toCallToolResult(recorded, captureContract);
+        const unknowns = recordProcessResidualUnknowns(session, scenario, evidence, captured.value.residual_unknowns);
+        if (!unknowns.ok)
+            return toCallToolResult(unknowns, captureContract);
         return toCallToolResult(ok(evidence), captureContract);
     });
-    server.registerTool(compareContract.name, {
-        description: compareContract.description,
-        inputSchema: compareContract.inputSchema,
-        outputSchema: compareContract.outputSchema,
-        annotations: compareContract.annotations,
-    }, (input) => {
-        const parsed = z
-            .object({
-            left_evidence_id: z.string(),
-            left: processCaptureSchema,
-            right_evidence_id: z.string(),
-            right: processCaptureSchema,
-        })
-            .parse(input);
-        const comparison = compareProcessCaptures(parsed.left, parsed.right);
-        const evidence = createEvidence(undefined, PROCESS_PROVIDER, {
-            predicateType: "rea.process-comparison/v1",
-            operation: compareContract.name,
-            parameters: {},
-            result: jsonValueSchema.parse(comparison),
-            confidence: "derived",
-            authority: "analyst-inference",
-            limitations: comparison.limitations,
-            evidenceLinks: [parsed.left_evidence_id, parsed.right_evidence_id],
-        });
-        session.recordEvidence(evidence);
-        return toCallToolResult(ok(evidence), compareContract);
-    });
 };
-const registerEvidenceTools = ({ server, session, exportContract, importContract, }) => {
+const registerEvidenceTools = ({ server, session, exportContract, importContract, filePolicy, }) => {
     server.registerTool(exportContract.name, {
         description: exportContract.description,
         inputSchema: exportContract.inputSchema,
         outputSchema: exportContract.outputSchema,
         annotations: exportContract.annotations,
-    }, () => toCallToolResult(ok(session.exportEvidenceBundle()), exportContract));
+    }, async (input) => {
+        const parsed = z
+            .object({
+            path: z.string().min(1).optional(),
+            overwrite: z.boolean().default(false),
+        })
+            .parse(input);
+        const bundle = session.exportEvidenceBundle();
+        if (parsed.path === undefined)
+            return toCallToolResult(ok(bundle), exportContract);
+        const written = await writeEvidenceBundle(bundle, parsed.path, parsed.overwrite, filePolicy);
+        return written.ok
+            ? toCallToolResult(ok({
+                path: written.value.path,
+                bytes: written.value.bytes,
+                records: bundle.records.length,
+            }), exportContract)
+            : toCallToolResult(written, exportContract);
+    });
     server.registerTool(importContract.name, {
         description: importContract.description,
         inputSchema: importContract.inputSchema,
         outputSchema: importContract.outputSchema,
         annotations: importContract.annotations,
-    }, (input) => {
-        try {
-            const bundle = z.object({ bundle: z.unknown() }).parse(input).bundle;
-            const imported = session.importEvidenceBundle(bundle);
-            return toCallToolResult(ok({
-                imported,
+    }, async (input) => {
+        const path = z.object({ path: z.string().min(1) }).parse(input).path;
+        const loaded = await readEvidenceBundle(path, filePolicy);
+        if (!loaded.ok)
+            return toCallToolResult(loaded, importContract);
+        const imported = session.importEvidenceBundle(loaded.value);
+        return imported.ok
+            ? toCallToolResult(ok({
+                imported: imported.value,
                 total: session.exportEvidenceBundle().records.length,
-            }), importContract);
-        }
-        catch (cause) {
-            return toCallToolResult(err(new EvidenceLedgerError("Evidence bundle validation failed", {
-                cause,
-            })), importContract);
-        }
+            }), importContract)
+            : toCallToolResult(imported, importContract);
+    });
+};
+const registerUnknownTools = ({ server, session, contracts: [listContract, recordContract, updateContract, verifyContract], }) => {
+    server.registerTool(listContract.name, {
+        description: listContract.description,
+        inputSchema: listContract.inputSchema,
+        outputSchema: listContract.outputSchema,
+        annotations: listContract.annotations,
+    }, (input) => {
+        const filters = z
+            .object({
+            status: z
+                .enum([
+                "open",
+                "investigating",
+                "blocked",
+                "contradicted",
+                "resolved",
+            ])
+                .optional(),
+            severity: z.enum(["low", "medium", "high", "critical"]).optional(),
+            domain: z.string().trim().min(1).max(100).optional(),
+        })
+            .parse(input);
+        return toCallToolResult(ok(session.listUnknowns({
+            ...(filters.status === undefined ? {} : { status: filters.status }),
+            ...(filters.severity === undefined
+                ? {}
+                : { severity: filters.severity }),
+            ...(filters.domain === undefined ? {} : { domain: filters.domain }),
+        })), listContract);
+    });
+    server.registerTool(recordContract.name, {
+        description: recordContract.description,
+        inputSchema: recordContract.inputSchema,
+        outputSchema: recordContract.outputSchema,
+        annotations: recordContract.annotations,
+    }, (input) => toCallToolResult(session.recordUnknown(recordUnknownInputSchema.parse(input)), recordContract));
+    server.registerTool(updateContract.name, {
+        description: updateContract.description,
+        inputSchema: updateContract.inputSchema,
+        outputSchema: updateContract.outputSchema,
+        annotations: updateContract.annotations,
+    }, (input) => toCallToolResult(session.updateUnknown(updateUnknownInputSchema.parse(input)), updateContract));
+    server.registerTool(verifyContract.name, {
+        description: verifyContract.description,
+        inputSchema: verifyContract.inputSchema,
+        outputSchema: verifyContract.outputSchema,
+        annotations: verifyContract.annotations,
+    }, (input) => {
+        const unknownId = z
+            .object({ unknown_id: z.string().regex(/^unk_[a-f0-9]{64}$/u) })
+            .parse(input).unknown_id;
+        return toCallToolResult(session.verifyUnknownResolution(unknownId), verifyContract);
     });
 };
-/** Register MCP-only target lifecycle operations on a long-lived session. */
-export const registerSessionTools = (server, session, logger, processPolicy = DENY_PROCESS_POLICY) => {
-    const [openContract, closeContract, statusContract, exportContract, importContract, captureContract, compareContract,] = SESSION_TOOL_CONTRACTS;
+const registerLifecycleTools = (server, session, logger, contracts) => {
+    const [openContract, closeContract, statusContract] = contracts;
     server.registerTool(openContract.name, {
         description: openContract.description,
         inputSchema: openContract.inputSchema,
@@ -147,13 +221,48 @@ export const registerSessionTools = (server, session, logger, processPolicy = DE
         outputSchema: statusContract.outputSchema,
         annotations: statusContract.annotations,
     }, () => toCallToolResult({ ok: true, value: session.status() }, statusContract));
-    registerEvidenceTools({ server, session, exportContract, importContract });
+};
+export const registerSessionTools = (server, session, logger, options = {}) => {
+    const processPolicy = options.processPolicy ?? DENY_PROCESS_POLICY;
+    const evidenceFilePolicy = options.evidenceFilePolicy ?? 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,
+    ]);
+    registerEvidenceTools({
+        server,
+        session,
+        exportContract,
+        importContract,
+        filePolicy: evidenceFilePolicy,
+    });
     registerProcessTools({
         server,
         session,
         logger,
         processPolicy,
         captureContract,
-        compareContract,
+    });
+    registerProcessComparisonTool(server, session, compareContract);
+    registerArtifactComparisonTool(server, session, compareArtifactsContract);
+    registerFunctionComparisonTool(server, session, compareFunctionsContract);
+    registerBundleComparisonTool(server, session, compareBundlesContract);
+    registerInvestigationTools(server, session, [
+        changedBehaviorContract,
+        callPathContract,
+        staticRuntimeContract,
+        reconstructionContract,
+    ]);
+    registerUnknownTools({
+        server,
+        session,
+        contracts: [
+            listUnknownContract,
+            recordUnknownContract,
+            updateUnknownContract,
+            verifyUnknownContract,
+        ],
     });
 };

package/dist/server/sessionEvidence.js

@@ -0,0 +1,28 @@
+import canonicalize from "canonicalize";
+import { EvidenceIntegrityError } from "../domain/errors.js";
+import { parseEvidence } from "../domain/evidence.js";
+import { err, ok } from "../domain/result.js";
+/** Resolve caller-supplied records to their immutable session-owned values. */
+export const resolveSessionEvidence = (session, input) => {
+    const supplied = Array.isArray(input) ? input : [input];
+    const authoritative = [];
+    for (const item of supplied) {
+        const parsed = parseEvidence(item);
+        const owned = session.evidenceById(parsed.evidence_id);
+        if (owned === undefined || canonicalJson(owned) !== canonicalJson(parsed))
+            return err(new EvidenceIntegrityError("Comparison input does not match its session-owned Evidence"));
+        authoritative.push(owned);
+    }
+    return ok(authoritative);
+};
+/** 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;
+};

package/dist/server/sessionToolPolicies.js

@@ -0,0 +1,64 @@
+/** Fail-closed process policy used when operator configuration is absent. */
+export const DENY_PROCESS_POLICY = {
+    enabled: false,
+    executableRoots: [],
+    workingRoots: [],
+    allowedEnvironment: [],
+    allowExternalNetwork: false,
+};
+/** Fail-closed evidence filesystem policy used without approved roots. */
+export const DENY_EVIDENCE_FILE_POLICY = {
+    roots: [],
+    maxBytes: 64 * 1024 * 1024,
+    maxDepth: 64,
+    maxStringLength: 1024 * 1024,
+    maxNodes: 1_000_000,
+};
+/** Provider identity for controlled process-capture evidence. */
+export const PROCESS_PROVIDER = {
+    id: "rea-process",
+    name: "REA deterministic process harness",
+    version: "1",
+};
+/** 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",
+};

package/dist/server/toolRegistrationOptions.js

@@ -0,0 +1,7 @@
+/** Project the public contract fields accepted by MCP tool registration. */
+export const toolRegistrationOptions = (contract) => ({
+    description: contract.description,
+    inputSchema: contract.inputSchema,
+    outputSchema: contract.outputSchema,
+    annotations: contract.annotations,
+});

package/dist/server/toolResult.js

@@ -1,19 +1,22 @@
+import { 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)
-    : {
+export const toCallToolResult = (result, contract) => result.ok ? successResult(result.value, contract) : errorResult(result.error);
+const errorResult = (error) => {
+    const projected = projectAnalysisError(error);
+    return {
         content: [
             {
                 type: "text",
-                text: `${result.error._tag}: ${result.error.message}`,
+                text: `${projected.tag}: ${projected.message}`,
             },
         ],
         isError: true,
     };
+};
 const successResult = (value, contract) => {
     const candidate = contract.kind === "session" ? { result: value } : value;
     const parsed = contract.outputSchema.safeParse(candidate);
@@ -22,7 +25,7 @@ const successResult = (value, contract) => {
             content: [
                 {
                     type: "text",
-                    text: "HopperProtocolError: Analysis output does not match the tool contract",
+                    text: "AnalysisOutputError: Analysis output does not match the tool contract",
                 },
             ],
             isError: true,

package/install.sh

@@ -0,0 +1,198 @@
+#!/bin/bash
+set -euo pipefail
+
+PACKAGE="rea-agents"
+REPOSITORY="morluto/rea"
+NODE_FORMULA="node@24"
+NODE_VERSION="24.18.0"
+temporary_directory=""
+node_destination=""
+node_stage=""
+node_backup=""
+node_version=""
+
+cleanup() {
+  if [[ -n "$temporary_directory" && -d "$temporary_directory" ]]; then
+    rm -rf -- "$temporary_directory"
+  fi
+  if [[ -n "$node_stage" && -e "$node_stage" ]]; then
+    rm -rf -- "$node_stage"
+  fi
+  if [[ -n "$node_backup" && -e "$node_backup" && ! -e "$node_destination" ]]; then
+    mv -- "$node_backup" "$node_destination"
+  fi
+}
+trap cleanup EXIT HUP INT TERM
+
+fail() {
+  printf 'REA installation failed: %s\n' "$1" >&2
+  exit 1
+}
+
+version_at_least() {
+  local actual="$1" required_major="$2" required_minor="$3"
+  local major minor
+  major="${actual%%.*}"
+  minor="${actual#*.}"
+  minor="${minor%%.*}"
+  [[ "$major" =~ ^[0-9]+$ && "$minor" =~ ^[0-9]+$ ]] || return 1
+  ((major > required_major || (major == required_major && minor >= required_minor)))
+}
+
+platform="$(uname -s)"
+if [[ "$platform" == "Darwin" ]]; then
+  macos_version="$(sw_vers -productVersion 2>/dev/null)" || fail "could not determine the macOS version."
+  macos_major="${macos_version%%.*}"
+  [[ "$macos_major" =~ ^[0-9]+$ && "$macos_major" -ge 12 ]] || fail "macOS 12 or newer is required."
+elif [[ "$platform" == "Linux" ]]; then
+  [[ "$(uname -m)" == "x86_64" || "$(uname -m)" == "aarch64" ]] || fail "64-bit x86 or ARM Linux is required."
+  [[ -r /etc/os-release ]] || fail "could not identify the Linux distribution."
+  linux_id="$(sed -n 's/^ID=//p' /etc/os-release | tr -d '"')"
+  linux_version="$(sed -n 's/^VERSION_ID=//p' /etc/os-release | tr -d '"')"
+  case "$linux_id" in
+    ubuntu) [[ "${linux_version%%.*}" -ge 24 ]] || fail "Ubuntu 24.04 or newer is required." ;;
+    fedora) [[ "${linux_version%%.*}" -ge 41 ]] || fail "Fedora 41 or newer is required." ;;
+    arch) ;;
+    *) fail "supported Linux distributions are Ubuntu 24.04+, Fedora 41+, and Arch Linux." ;;
+  esac
+else
+  fail "REA supports macOS and selected 64-bit Linux distributions."
+fi
+command -v curl >/dev/null 2>&1 || fail "curl is required."
+command -v shasum >/dev/null 2>&1 || command -v sha256sum >/dev/null 2>&1 || fail "shasum or sha256sum is required."
+
+if [[ "$platform" == "Darwin" ]] && ! command -v brew >/dev/null 2>&1; then
+  printf 'Installing Homebrew prerequisite...\n'
+  NONINTERACTIVE=1 /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)" || fail "Homebrew installation did not complete."
+  if [[ -x /opt/homebrew/bin/brew ]]; then
+    PATH="/opt/homebrew/bin:$PATH"
+  elif [[ -x /usr/local/bin/brew ]]; then
+    PATH="/usr/local/bin:$PATH"
+  fi
+fi
+if [[ "$platform" == "Darwin" ]]; then
+  command -v brew >/dev/null 2>&1 || fail "Homebrew is not available after installation."
+fi
+
+node_compatible=false
+if command -v node >/dev/null 2>&1; then
+  node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
+fi
+if version_at_least "$node_version" 24 18 && [[ "$node_version" =~ ^24\. ]]; then
+  node_compatible=true
+fi
+if [[ "$node_compatible" != true ]]; then
+  if [[ "$platform" == "Darwin" ]]; then
+    brew install "$NODE_FORMULA" || fail "Node.js 24 installation failed."
+    node_prefix="$(brew --prefix "$NODE_FORMULA")" || fail "could not locate Node.js 24."
+    PATH="$node_prefix/bin:$PATH"
+  else
+    machine="$(uname -m)"
+    node_arch="$([[ "$machine" == "x86_64" ]] && printf 'x64' || printf 'arm64')"
+    node_archive="node-v${NODE_VERSION}-linux-${node_arch}.tar.xz"
+    node_base="https://nodejs.org/dist/v${NODE_VERSION}"
+    temporary_directory="$(mktemp -d "${TMPDIR:-/tmp}/rea-install.XXXXXX")" || fail "could not create a temporary directory."
+    curl -fsSL "$node_base/$node_archive" -o "$temporary_directory/$node_archive" || fail "Node.js download failed."
+    curl -fsSL "$node_base/SHASUMS256.txt" -o "$temporary_directory/SHASUMS256.txt" || fail "Node.js checksum download failed."
+    expected_checksum="$(awk -v archive="$node_archive" '$2 == archive { print $1 }' "$temporary_directory/SHASUMS256.txt")"
+    [[ "$expected_checksum" =~ ^[a-f0-9]{64}$ ]] || fail "Node.js checksum metadata was malformed."
+    if command -v shasum >/dev/null 2>&1; then
+      actual_checksum="$(shasum -a 256 "$temporary_directory/$node_archive" | awk '{ print $1 }')"
+    else
+      actual_checksum="$(sha256sum "$temporary_directory/$node_archive" | awk '{ print $1 }')"
+    fi
+    [[ "$actual_checksum" == "$expected_checksum" ]] || fail "Node.js checksum verification failed."
+    node_destination="$HOME/.local/share/rea/node"
+    node_stage="$HOME/.local/share/rea/node.new.$$"
+    node_backup="$HOME/.local/share/rea/node.backup.$$"
+    [[ ! -L "$node_destination" ]] || fail "refusing to replace a symlinked Node.js installation."
+    mkdir -p "$HOME/.local/share/rea"
+    rm -rf -- "$node_stage" "$node_backup"
+    mkdir "$node_stage"
+    tar -xJf "$temporary_directory/$node_archive" --strip-components=1 -C "$node_stage" || fail "Node.js extraction failed."
+    if [[ -e "$node_destination" ]]; then
+      mv -- "$node_destination" "$node_backup"
+    fi
+    if ! mv -- "$node_stage" "$node_destination"; then
+      [[ ! -e "$node_backup" ]] || mv -- "$node_backup" "$node_destination"
+      fail "Node.js installation replacement failed."
+    fi
+    node_stage=""
+    rm -rf -- "$node_backup"
+    node_backup=""
+    PATH="$node_destination/bin:$PATH"
+  fi
+fi
+node_version="$(node -p 'process.versions.node' 2>/dev/null || true)"
+if ! command -v node >/dev/null 2>&1 || ! version_at_least "$node_version" 24 18 || [[ ! "$node_version" =~ ^24\. ]]; then
+  fail "Node.js 24.18 or newer is not active on PATH."
+fi
+command -v npm >/dev/null 2>&1 || fail "npm is missing from the Node.js installation."
+npm_version="$(npm --version)"
+if [[ ! "$npm_version" =~ ^11\. ]] || ! version_at_least "$npm_version" 11 16; then
+  if [[ "$platform" == "Linux" ]]; then
+    npm install --global --prefix "$HOME/.local" npm@11 || fail "npm 11 installation failed."
+  else
+    npm install --global npm@11 || fail "npm 11 installation failed."
+  fi
+fi
+npm_version="$(npm --version)"
+if [[ ! "$npm_version" =~ ^11\. ]] || ! version_at_least "$npm_version" 11 16; then
+  fail "npm 11.16 or newer is not active on PATH."
+fi
+if [[ -n "$temporary_directory" ]]; then
+  rm -rf -- "$temporary_directory"
+  temporary_directory=""
+fi
+
+if [[ -n "${REA_VERSION:-}" ]]; then
+  version="$REA_VERSION"
+  [[ "$version" =~ ^[0-9]+\.[0-9]+\.[0-9]+(-[0-9A-Za-z.-]+)?$ ]] || fail "REA_VERSION must be an exact semantic version."
+else
+  release_json="$(curl -fsSL -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."
+  version="${BASH_REMATCH[1]}"
+fi
+
+printf 'Installing %s@%s...\n' "$PACKAGE" "$version"
+if [[ "$platform" == "Linux" ]]; then
+  mkdir -p "$HOME/.local/bin"
+  PATH="$HOME/.local/bin:$PATH"
+  npm install --global --prefix "$HOME/.local" "$PACKAGE@$version" || fail "npm package installation failed."
+else
+  npm install --global "$PACKAGE@$version" || fail "npm package installation failed."
+fi
+command -v rea >/dev/null 2>&1 || fail "the rea command is not available after installation."
+installed_version="$(rea --version 2>/dev/null | tr -d '[:space:]')" || fail "could not read the installed REA version."
+[[ "$installed_version" == "$version" ]] || fail "installed version $installed_version does not match $version."
+
+temporary_directory="$(mktemp -d "${TMPDIR:-/tmp}/rea-install.XXXXXX")" || fail "could not create a temporary directory."
+setup_output="$temporary_directory/setup.json"
+doctor_output="$temporary_directory/doctor.json"
+rea setup --yes --json >"$setup_output" || fail "REA setup command failed."
+rea doctor --json >"$doctor_output" || fail "REA doctor command failed."
+result="$(node - "$setup_output" "$doctor_output" <<'NODE'
+const fs = require("node:fs");
+const [setupPath, doctorPath] = process.argv.slice(2);
+try {
+  const setup = JSON.parse(fs.readFileSync(setupPath, "utf8"));
+  const doctor = JSON.parse(fs.readFileSync(doctorPath, "utf8"));
+  if (!Array.isArray(doctor.checks) || typeof doctor.healthy !== "boolean") process.exit(2);
+  if (setup.status !== "ready" && setup.status !== "needs_human") process.exit(2);
+  const activation = setup.actions.includes("installed_hopper");
+  if (!doctor.healthy && !activation) process.exit(3);
+  process.stdout.write(activation ? "activation" : "ready");
+} catch { process.exit(2); }
+NODE
+)" || fail "setup or doctor reported an unhealthy required component or malformed output."
+
+if [[ "$result" == "activation" ]]; then
+  printf 'REA %s is installed and coding agents are configured.\n' "$version"
+  printf 'One user action remains: open Hopper, complete its activation, then run: rea doctor --json\n'
+else
+  printf 'REA %s is installed and ready. Run rea doctor --json at any time.\n' "$version"
+fi
+if [[ "$platform" == "Linux" ]]; then
+  printf 'Add %s to PATH to run rea from future shells.\n' "$HOME/.local/bin"
+fi