rea-agents 3.2.0 → 4.0.0

package/dist/application/SetupPlan.js

@@ -1,9 +1,134 @@
 import { homedir } from "node:os";
 import { join } from "node:path";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
 import { macHopperInstallDisclosure } from "./MacHopper.js";
-/** Build the complete setup mutation plan before approval. */
+/** Discover supported clients and current registrations without mutation. */
+export const discoverSetupState = async (input) => {
+    const initialDoctor = await input.host.doctor(input.doctorScope);
+    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
+        (name === "hopper-demo-runtime" ||
+            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
+    const linuxDistribution = input.host.platform === "linux"
+        ? await input.host.linuxDistribution()
+        : undefined;
+    const hopperInstallSupported = (input.host.platform === "darwin" &&
+        majorVersion((await input.host.macosVersion()) ?? "0") >= 12) ||
+        (input.host.platform === "linux" && linuxDistribution?.supported === true);
+    const installHopper = input.forceHopperInstall ||
+        (hopperInstallSupported &&
+            input.proposeHopper &&
+            (Object.keys(input.providerEnvironment).length === 0 ||
+                linuxHopperRepairNeeded));
+    const [clients, detectedClients, skillNeedsInstall] = await Promise.all([
+        input.host.supportedClients?.() ?? input.host.detectedClients(),
+        input.host.detectedClients(),
+        input.host.skillNeedsInstall(),
+    ]);
+    const detectedIds = new Set(detectedClients.map(({ name }) => name));
+    const registrations = initialDoctor.identity?.registrations ?? [];
+    const registrationByClient = new Map(registrations.map((registration) => [registration.client, registration]));
+    const clientStates = clients.map((client) => {
+        const registration = registrationByClient.get(client.name);
+        const ownedRegistration = (registration?.state === "aligned" || registration?.state === "stale") &&
+            isOwnedClientRegistrationCommand(registration.command);
+        const configured = ownedRegistration;
+        const status = registration?.state === "invalid"
+            ? "invalid"
+            : ownedRegistration && registration.state === "aligned"
+                ? "configured"
+                : ownedRegistration && registration.state === "stale"
+                    ? "needs_configuration"
+                    : detectedIds.has(client.name)
+                        ? "needs_configuration"
+                        : "missing";
+        return {
+            client,
+            detected: detectedIds.has(client.name),
+            configured,
+            status,
+        };
+    });
+    const defaultClientIds = registrations
+        .filter((registration) => (registration.state === "aligned" || registration.state === "stale") &&
+        isOwnedClientRegistrationCommand(registration.command))
+        .map(({ client }) => client);
+    return {
+        initialDoctor,
+        installHopper,
+        skillNeedsInstall,
+        clients,
+        detectedClientIds: [...detectedIds],
+        defaultClientIds,
+        clientStates,
+        ...(linuxDistribution?.packageFamily === undefined
+            ? {}
+            : { linuxPackageFamily: linuxDistribution.packageFamily }),
+    };
+};
+/** Preflight exactly the selected clients and produce their concrete actions. */
+export const planSetupActions = async (input) => {
+    const byId = new Map(input.discovery.clients.map((client) => [client.name, client]));
+    const unknownClient = input.clientIds.find((id) => !byId.has(id));
+    if (unknownClient !== undefined) {
+        return {
+            plannedActions: [],
+            selectedClients: [],
+            clientsToConfigure: [],
+            blocker: `Unsupported setup client: ${unknownClient}.`,
+        };
+    }
+    const selectedClients = input.clientIds.flatMap((id) => {
+        const client = byId.get(id);
+        return client === undefined ? [] : [client];
+    });
+    const inspections = await Promise.all(selectedClients.map(async (client) => ({
+        client,
+        inspection: (await input.host.inspectClientConfiguration?.(client, input.providerEnvironment, input.command)) ?? { status: "update" },
+    })));
+    const invalid = inspections.find(({ inspection }) => inspection.status === "invalid");
+    if (invalid?.inspection.status === "invalid") {
+        return {
+            plannedActions: [],
+            selectedClients,
+            clientsToConfigure: [],
+            blocker: `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`,
+        };
+    }
+    const clientPlans = inspections.flatMap(({ client, inspection }) => inspection.status === "create" ||
+        inspection.status === "update" ||
+        (input.discovery.installHopper && inspection.status === "already_current")
+        ? [
+            {
+                client,
+                operation: inspection.status === "already_current"
+                    ? "update"
+                    : inspection.status,
+                ...(inspection.status !== "already_current" &&
+                    inspection.backupPath !== undefined
+                    ? { backupPath: inspection.backupPath }
+                    : {}),
+            },
+        ]
+        : []);
+    return {
+        plannedActions: setupPlan({
+            platform: input.host.platform,
+            installHopper: input.discovery.installHopper,
+            installSkill: input.installSkill,
+            clients: clientPlans,
+            providerEnvironment: input.providerEnvironment,
+            ...(input.discovery.linuxPackageFamily === undefined
+                ? {}
+                : { linuxPackageFamily: input.discovery.linuxPackageFamily }),
+            command: input.command,
+        }),
+        selectedClients,
+        clientsToConfigure: selectedClients.filter((client) => clientPlans.some(({ client: planned }) => planned.name === client.name)),
+    };
+};
+/** Describe every selected setup mutation before user approval. */
 const setupPlan = (input) => [
     ...(input.installHopper
         ? [
@@ -37,7 +162,7 @@ const setupPlan = (input) => [
         kind: "configure_client",
         label: client.displayName ?? client.name,
         target: client.configPath,
-        detail: clientConfigurationDetail(client.displayName ?? client.name, input.providerEnvironment),
+        detail: clientConfigurationDetail(client.displayName ?? client.name, input.command, input.providerEnvironment, input.installHopper),
         external: false,
         operation,
         ...(backupPath === undefined ? {} : { backupPath }),
@@ -56,87 +181,6 @@ const setupPlan = (input) => [
         ]
         : []),
 ];
-/** Discover and preflight the complete set of selectable setup actions. */
-export const discoverSetupActions = async (input) => {
-    const { host, providerEnvironment, command } = input;
-    const initialDoctor = await host.doctor(input.doctorScope);
-    const linuxHopperRepairNeeded = initialDoctor.checks.some(({ name, ok, detail }) => !ok &&
-        (name === "hopper-demo-runtime" ||
-            (name === "hopper-version" && detail === "/opt/hopper/bin/Hopper")));
-    const installHopper = input.forceHopperInstall ||
-        (input.proposeHopper &&
-            (Object.keys(providerEnvironment).length === 0 ||
-                linuxHopperRepairNeeded));
-    const [allDetectedClients, skillNeedsInstall] = await Promise.all([
-        host.detectedClients(),
-        host.skillNeedsInstall(),
-    ]);
-    const selectedClientIdSet = input.selectedClientIds === undefined
-        ? undefined
-        : new Set(input.selectedClientIds);
-    const detectedClients = allDetectedClients.filter(({ name }) => selectedClientIdSet === undefined || selectedClientIdSet.has(name));
-    const installSkill = input.installSkillSelection === false ? false : skillNeedsInstall;
-    const clients = installHopper
-        ? detectedClients
-        : await filterClientsNeedingConfigure({
-            host,
-            clients: detectedClients,
-            providerEnvironment,
-            command,
-        });
-    const inspections = await inspectClients({
-        host,
-        clients,
-        providerEnvironment,
-        command,
-    });
-    const invalid = inspections.find(({ inspection }) => inspection.status === "invalid");
-    const blocker = invalid?.inspection.status === "invalid"
-        ? `${invalid.client.displayName ?? invalid.client.name}: ${invalid.inspection.remediation}`
-        : undefined;
-    const clientPlans = inspections.flatMap(({ client, inspection }) => inspection.status === "create" ||
-        inspection.status === "update" ||
-        (installHopper && inspection.status === "already_current")
-        ? [
-            {
-                client,
-                operation: inspection.status === "already_current"
-                    ? "update"
-                    : inspection.status,
-                ...(inspection.status !== "already_current" &&
-                    inspection.backupPath !== undefined
-                    ? { backupPath: inspection.backupPath }
-                    : {}),
-            },
-        ]
-        : []);
-    const linuxDistribution = host.platform === "linux" ? await host.linuxDistribution() : undefined;
-    return {
-        initialDoctor,
-        installHopper,
-        installSkill,
-        detectedClients: clientPlans.map(({ client }) => client),
-        plannedActions: setupPlan({
-            platform: host.platform,
-            installHopper,
-            installSkill,
-            clients: clientPlans,
-            providerEnvironment,
-            ...(linuxDistribution?.packageFamily === undefined
-                ? {}
-                : { linuxPackageFamily: linuxDistribution.packageFamily }),
-        }),
-        blocker,
-    };
-};
-const inspectClients = async (input) => Promise.all(input.clients.map(async (client) => ({
-    client,
-    inspection: (await input.host.inspectClientConfiguration?.(client, input.providerEnvironment, input.command)) ?? { status: "update" },
-})));
-const filterClientsNeedingConfigure = async (input) => {
-    const needs = await Promise.all(input.clients.map((client) => input.host.clientNeedsConfigure(client, input.providerEnvironment, input.command)));
-    return input.clients.filter((_, index) => needs[index]);
-};
 const linuxDisclosure = (family) => {
     const disclosure = linuxHopperInstallDisclosure(family, process.getuid?.() === 0);
     return {
@@ -145,10 +189,18 @@ const linuxDisclosure = (family) => {
         integrity: `${String(disclosure.expectedBytes)} bytes · SHA-1 ${disclosure.expectedSha1}`,
     };
 };
-const clientConfigurationDetail = (client, environment) => {
+const majorVersion = (version) => Number.parseInt(version.split(".")[0] ?? "0", 10);
+const clientConfigurationDetail = (client, command, environment, installHopper) => {
     const entries = Object.entries(environment)
         .sort(([left], [right]) => left.localeCompare(right))
         .map(([name, value]) => `${name}=${value}`);
-    const suffix = entries.length === 0 ? "" : ` Environment: ${entries.join(", ")}.`;
-    return `Add the REA MCP registration for ${client}; preserve unrelated configuration.${suffix}`;
+    const environmentDetail = entries.length === 0
+        ? " No additional environment variables."
+        : ` Environment: ${entries.join(", ")}.`;
+    const hopperDetail = installHopper
+        ? environment.HOPPER_LAUNCHER_PATH === undefined
+            ? " If this plan installs Hopper, REA will add HOPPER_LAUNCHER_PATH using the launcher path reported by that installation."
+            : " The HOPPER_LAUNCHER_PATH value shown above is the current fallback; if this plan installs Hopper, REA will replace it with the launcher path reported by that installation."
+        : "";
+    return `Add the REA MCP registration for ${client}; preserve unrelated configuration. Command: ${command.map((part) => JSON.stringify(part)).join(" ")}.${environmentDetail}${hopperDetail}`;
 };

package/dist/application/SetupSkill.js

@@ -8,7 +8,6 @@ const SKILL_FILES = [
     "references/javascript-applications.md",
     "references/runtime-observation.md",
     "references/evidence-workflows.md",
-    "references/controlled-replay.md",
 ];
 const skillRoot = (home) => join(home, ".agents/skills", PRODUCT_IDENTITY.skillName);
 const readOptionalText = async (path) => {

package/dist/application/SupportedClients.js

@@ -1,30 +1,72 @@
 import { join } from "node:path";
+import { lstatSync } from "node:fs";
+const vscodeUserDirectory = ({ home, platform, env, }) => {
+    if (platform === "win32")
+        return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "Code", "User");
+    if (platform === "darwin")
+        return join(home, "Library", "Application Support", "Code", "User");
+    return join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "Code", "User");
+};
+const claudeDesktopDirectory = ({ home, platform, env, }) => {
+    if (platform === "win32")
+        return join(env.APPDATA ?? join(home, "AppData", "Roaming"), "Claude");
+    if (platform === "linux")
+        return join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "Claude");
+    return join(home, "Library", "Application Support", "Claude");
+};
+const claudeCodeConfigDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? home;
+const claudeCodeMarkerDirectory = ({ home, env }) => env.CLAUDE_CONFIG_DIR ?? join(home, ".claude");
+const codexDirectory = ({ home, env }) => env.CODEX_HOME ?? join(home, ".codex");
+const copilotDirectory = ({ home, env }) => env.COPILOT_HOME ?? join(home, ".copilot");
+const opencodeDirectory = ({ home, env }) => join(env.XDG_CONFIG_HOME ?? join(home, ".config"), "opencode");
+const existingOpenCodeConfigPath = (context) => {
+    if (context.env.OPENCODE_CONFIG !== undefined)
+        return context.env.OPENCODE_CONFIG;
+    const directory = opencodeDirectory(context);
+    const candidates = [
+        "opencode.json",
+        "opencode.jsonc",
+        ".opencode.json",
+        ".opencode.jsonc",
+    ].map((filename) => join(directory, filename));
+    return (candidates.find((path) => {
+        try {
+            lstatSync(path);
+            return true;
+        }
+        catch (cause) {
+            return !(cause instanceof Error &&
+                "code" in cause &&
+                cause.code === "ENOENT");
+        }
+    }) ??
+        candidates[0] ??
+        join(directory, "opencode.json"));
+};
+const devinDirectory = ({ home, platform, env }) => platform === "win32"
+    ? join(env.APPDATA ?? join(home, "AppData", "Roaming"), "devin")
+    : join(home, ".config", "devin");
 /** Stable product metadata used to derive setup discovery and documentation. */
 export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "claude_code",
         displayName: "Claude Code",
-        configPath: [".claude.json"],
-        markerPath: [".claude"],
+        configPath: (context) => join(claudeCodeConfigDirectory(context), ".claude.json"),
+        markerPath: claudeCodeMarkerDirectory,
         format: "json",
     },
     {
         name: "claude_desktop",
         displayName: "Claude Desktop",
-        configPath: [
-            "Library",
-            "Application Support",
-            "Claude",
-            "claude_desktop_config.json",
-        ],
-        markerPath: ["Library", "Application Support", "Claude"],
+        configPath: (context) => join(claudeDesktopDirectory(context), "claude_desktop_config.json"),
+        markerPath: claudeDesktopDirectory,
         format: "json",
     },
     {
         name: "codex",
         displayName: "Codex",
-        configPath: [".codex", "config.toml"],
-        markerPath: [".codex"],
+        configPath: (context) => join(codexDirectory(context), "config.toml"),
+        markerPath: codexDirectory,
         format: "toml",
     },
     {
@@ -51,16 +93,55 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
     {
         name: "devin",
         displayName: "Devin",
-        configPath: [".devin"],
-        markerPath: [".devin"],
-        format: "unsupported",
+        configPath: ({ home, platform, env }) => join(devinDirectory({ home, platform, env }), "mcp_config.json"),
+        markerPath: devinDirectory,
+        format: "json",
+    },
+    {
+        name: "opencode",
+        displayName: "OpenCode",
+        configPath: existingOpenCodeConfigPath,
+        markerPath: opencodeDirectory,
+        format: "opencode",
+    },
+    {
+        name: "antigravity",
+        displayName: "Antigravity",
+        configPath: [".gemini", "config", "mcp_config.json"],
+        markerPath: [".gemini", "config"],
+        format: "json",
+    },
+    {
+        name: "copilot_cli",
+        displayName: "GitHub Copilot CLI",
+        configPath: (context) => join(copilotDirectory(context), "mcp-config.json"),
+        markerPath: copilotDirectory,
+        format: "copilot_cli",
+    },
+    {
+        name: "vscode",
+        displayName: "VS Code",
+        configPath: (context) => join(vscodeUserDirectory(context), "mcp.json"),
+        markerPath: vscodeUserDirectory,
+        format: "vscode",
     },
 ];
+const resolvePath = (path, context) => typeof path === "function" ? path(context) : join(context.home, ...path);
 /** Describe every client location that setup, doctor, or uninstall may inspect. */
-export const supportedClients = (home) => SUPPORTED_CLIENT_DEFINITIONS.map((definition) => ({
-    name: definition.name,
-    displayName: definition.displayName,
-    configPath: join(home, ...definition.configPath),
-    markerPath: join(home, ...definition.markerPath),
-    format: definition.format,
-}));
+export const supportedClients = (home, platform = process.platform, env = {
+    APPDATA: process.env.APPDATA,
+    CLAUDE_CONFIG_DIR: process.env.CLAUDE_CONFIG_DIR,
+    CODEX_HOME: process.env.CODEX_HOME,
+    COPILOT_HOME: process.env.COPILOT_HOME,
+    OPENCODE_CONFIG: process.env.OPENCODE_CONFIG,
+    XDG_CONFIG_HOME: process.env.XDG_CONFIG_HOME,
+}) => {
+    const context = { home, platform, env };
+    return SUPPORTED_CLIENT_DEFINITIONS.map((definition) => ({
+        name: definition.name,
+        displayName: definition.displayName,
+        configPath: resolvePath(definition.configPath, context),
+        markerPath: resolvePath(definition.markerPath, context),
+        format: definition.format,
+    }));
+};

package/dist/application/Uninstall.js

@@ -1,10 +1,11 @@
 import { parseClientConfiguration, serializeClientConfiguration, } from "./ClientConfigurationDocument.js";
 import { copyFile, lstat, readFile, realpath, rm } from "node:fs/promises";
 import { homedir } from "node:os";
-import { basename, isAbsolute, join } from "node:path";
+import { join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 import { PRODUCT_IDENTITY } from "../identity.js";
+import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 import { supportedClients } from "./SupportedClients.js";
 const systemFileSystem = {
@@ -15,6 +16,20 @@ const systemFileSystem = {
     realpath: (path) => realpath(path),
     remove: (path) => rm(path, { recursive: true }),
 };
+/** Whether any requested REA-owned uninstall action failed. */
+export const isUninstallFailure = (result) => {
+    const status = result.status;
+    switch (status) {
+        case "complete":
+            return false;
+        case "failed":
+            return true;
+        default: {
+            const exhaustive = status;
+            throw new TypeError(`Unhandled uninstall result status: ${String(exhaustive)}`);
+        }
+    }
+};
 /** Remove only REA-owned registrations and managed files, optionally including local state. */
 export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
     const items = [];
@@ -72,12 +87,12 @@ const removeClient = async (client, fileSystem) => {
         } = parseClientConfiguration(original, client.format));
     }
     catch {
-        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
+        return item(client.name, "failed", `Configuration is not valid ${client.format === "toml" ? "TOML" : client.format === "opencode" ? "JSONC" : "JSON"} and was not changed. Repair it, then rerun uninstall.`);
     }
     const registration = servers[PRODUCT_IDENTITY.mcpServerKey];
     if (registration === undefined)
         return item(client.name, "skipped", "REA registration is absent.");
-    if (!isOwnedRegistration(registration))
+    if (!isOwnedRegistration(registration, client))
         return item(client.name, "retained", "The rea-named registration is not REA-owned.");
     const remaining = { ...servers };
     delete remaining[PRODUCT_IDENTITY.mcpServerKey];
@@ -90,7 +105,7 @@ const removeClient = async (client, fileSystem) => {
         return item(client.name, "failed", "Configuration could not be backed up, so no change was made. Check file permissions, then rerun uninstall.");
     }
     try {
-        await fileSystem.writeText(transactionPath, serializeClientConfiguration(document, client.format));
+        await fileSystem.writeText(transactionPath, serializeClientConfiguration(document, client.format, original, PRODUCT_IDENTITY.mcpServerKey));
         const readback = parseClientConfiguration(await fileSystem.readText(transactionPath), client.format);
         if (PRODUCT_IDENTITY.mcpServerKey in readback.servers)
             throw new Error("registration readback mismatch");
@@ -114,26 +129,22 @@ const resolveUninstallConfigPath = async (client, fileSystem) => {
         item(client.name, "failed", "Configuration path could not be safely verified. Check its permissions and, if it is a symbolic link, verify that the link resolves to a regular file owned by the current user, then rerun uninstall."));
 };
 /** Ownership rule for persistent MCP registrations created by REA setup. */
-const isOwnedRegistration = (value) => {
+const isOwnedRegistration = (value, client) => {
+    if (client.format === "opencode") {
+        const parsed = z
+            .object({ type: z.literal("local"), command: z.array(z.string()).min(1) })
+            .passthrough()
+            .safeParse(value);
+        if (!parsed.success)
+            return false;
+        const command = parsed.data.command;
+        return isOwnedClientRegistrationCommand(command);
+    }
     const parsed = registrationSchema.safeParse(value);
     if (!parsed.success)
         return false;
     const { command, args } = parsed.data;
-    return (((command === "rea" ||
-        (isAbsolute(command) && basename(command) === "rea")) &&
-        args.length === 1 &&
-        args[0] === "mcp") ||
-        (command === "npx" &&
-            (JSON.stringify(args) ===
-                JSON.stringify([
-                    "-y",
-                    PRODUCT_IDENTITY.registrationPackageSpecifier,
-                    "mcp",
-                ]) ||
-                JSON.stringify(args) ===
-                    JSON.stringify(["-y", PRODUCT_IDENTITY.packageSpecifier, "mcp"]) ||
-                JSON.stringify(args) ===
-                    JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"]))));
+    return isOwnedClientRegistrationCommand([command, ...args]);
 };
 const removeManagedPath = async (path, name, fileSystem) => {
     try {

package/dist/application/Update.js

@@ -0,0 +1,93 @@
+import { gt, valid } from "semver";
+import { PRODUCT_IDENTITY } from "../identity.js";
+/** Whether the update command left the requested release unapplied. */
+export const isUpdateFailure = (result) => {
+    const status = result.status;
+    switch (status) {
+        case "current":
+        case "updated":
+            return false;
+        case "failed":
+            return true;
+        default: {
+            const exhaustive = status;
+            throw new TypeError(`Unhandled update result status: ${String(exhaustive)}`);
+        }
+    }
+};
+/** Resolve the exact npm command for the identified prefix and release. */
+export const updateInstallCommand = (installation, version) => [
+    "npm",
+    "install",
+    "--global",
+    "--ignore-scripts",
+    "--prefix",
+    installation.prefix,
+    `${PRODUCT_IDENTITY.packageName}@${version}`,
+];
+/** Identify, resolve, install, and verify REA without applying setup changes. */
+export const runUpdate = async (currentVersion, host, output = "human") => {
+    const installation = await host.installation();
+    const release = await host.latestVersion(installation);
+    const latestVersion = release.ok ? release.value : null;
+    const targetVersion = release.ok ? valid(release.value) : null;
+    if (!release.ok || valid(currentVersion) === null || targetVersion === null)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion,
+            reason: "version-check",
+            remediation: release.ok
+                ? "REA received invalid version metadata. Check the installed version and npm registry, then rerun rea update."
+                : `REA could not resolve the latest release: ${release.error}. Retry rea update when registry access is available.`,
+        };
+    if (!gt(targetVersion, currentVersion))
+        return {
+            status: "current",
+            currentVersion,
+            latestVersion: targetVersion,
+            installMethod: installation === undefined ? "unknown" : "npm",
+        };
+    if (installation === undefined)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: targetVersion,
+            reason: "unknown-install-method",
+            remediation: "Update this installation with the package manager or source checkout that owns it. For a one-off latest invocation, use npx rea-agents@latest.",
+        };
+    const installed = await host.installVersion(installation, targetVersion, output);
+    if (!installed.ok)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: targetVersion,
+            reason: "install",
+            remediation: `REA could not install ${targetVersion} in ${installation.prefix}: ${installed.error}. Repair this npm installation, then rerun rea update.`,
+        };
+    const verified = await host.installedVersion(installation);
+    if (!verified.ok || verified.value !== targetVersion)
+        return {
+            status: "failed",
+            currentVersion,
+            latestVersion: targetVersion,
+            reason: "verification",
+            ...(verified.ok ? { installedVersion: verified.value } : {}),
+            remediation: `npm completed, but REA could not verify ${targetVersion} in ${installation.packageRoot}: ${verified.ok ? `the executable reported ${verified.value}` : verified.error}. The installation may have changed; repair it before retrying.`,
+        };
+    const maintenance = await host.planMaintenance(installation);
+    return {
+        status: "updated",
+        previousVersion: currentVersion,
+        latestVersion: targetVersion,
+        installedVersion: verified.value,
+        installMethod: "npm",
+        command: updateInstallCommand(installation, targetVersion),
+        maintenance,
+        remediation: maintenance.status === "planned"
+            ? "REA is updated. Run the maintenance command to review and approve changes to existing REA integrations, then restart affected agents."
+            : maintenance.status === "unavailable"
+                ? "REA is updated. Integration maintenance could not be planned; inspect the maintenance diagnostic before changing configuration."
+                : "REA is updated. Restart agents running this installation to load the new version.",
+    };
+};