rea-agents 2.0.0 → 2.2.0

package/dist/application/SetupClientConfiguration.js

@@ -0,0 +1,224 @@
+import { constants as fsConstants } from "node:fs";
+import { copyFile, mkdir, readFile, rm, writeFile } from "node:fs/promises";
+import { dirname } from "node:path";
+import { z } from "zod";
+import writeFileAtomic from "write-file-atomic";
+import { parse as parseToml, stringify as stringifyToml } from "smol-toml";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
+const defaultCommand = () => [
+    "npx",
+    "-y",
+    PRODUCT_IDENTITY.registrationPackageSpecifier,
+    "mcp",
+];
+const CODEX_STARTUP_TIMEOUT_SECONDS = 30;
+/** Back up, atomically update, and semantically read back one JSON MCP configuration. */
+export const configureJsonClient = async (client, environment = {}, command = defaultCommand()) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
+    let document = {};
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+        document = parseObject(original);
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcpServers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
+    if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return { status: "unchanged" };
+    let backupPath;
+    if (original !== undefined) {
+        backupPath = `${client.configPath}.rea.backup`;
+        if (!(await preserveConfigBackup(transactionPath, backupPath)))
+            return { status: "failed", reason: "backup" };
+    }
+    document.mcpServers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(transactionPath, `${JSON.stringify(document, null, 2)}\n`, {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+    }
+    catch {
+        return { status: "failed", reason: "write" };
+    }
+    try {
+        const readback = parseObject(await readFile(transactionPath, "utf8"));
+        if (!sameConfiguration(parseOptionalObject(readback.mcpServers)[PRODUCT_IDENTITY.mcpServerKey], desired)) {
+            await restoreConfig(transactionPath, original);
+            return { status: "failed", reason: "readback" };
+        }
+    }
+    catch {
+        await restoreConfig(transactionPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Back up, atomically update, and semantically read back Codex TOML configuration. */
+export const configureTomlClient = async (client, environment = {}, command = defaultCommand()) => {
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return { status: "failed", reason: "path" };
+    let document = {};
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+        document = objectSchema.parse(parseToml(original));
+    }
+    catch (cause) {
+        if (!isMissing(cause))
+            return { status: "failed", reason: "readback" };
+    }
+    let servers;
+    try {
+        servers = parseOptionalObject(document.mcp_servers);
+    }
+    catch {
+        return { status: "failed", reason: "readback" };
+    }
+    const desired = clientConfigurationDesired(client, normalizeProviderEnvironment(environment), command);
+    if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+        return { status: "unchanged" };
+    const backupPath = original === undefined ? undefined : `${client.configPath}.rea.backup`;
+    if (backupPath !== undefined &&
+        !(await preserveConfigBackup(transactionPath, backupPath)))
+        return { status: "failed", reason: "backup" };
+    document.mcp_servers = {
+        ...servers,
+        [PRODUCT_IDENTITY.mcpServerKey]: desired,
+    };
+    try {
+        await mkdir(dirname(client.configPath), { recursive: true });
+        await writeFileAtomic(transactionPath, stringifyToml(document), {
+            encoding: "utf8",
+            mode: 0o600,
+        });
+        const readback = objectSchema.parse(parseToml(await readFile(transactionPath, "utf8")));
+        if (!sameConfiguration(parseOptionalObject(readback.mcp_servers)[PRODUCT_IDENTITY.mcpServerKey], desired))
+            throw new Error("TOML readback mismatch");
+    }
+    catch {
+        await restoreConfig(transactionPath, original);
+        return { status: "failed", reason: "readback" };
+    }
+    return {
+        status: "configured",
+        ...(backupPath === undefined ? {} : { backupPath }),
+    };
+};
+/** Determine whether an existing client configuration matches the desired registration. */
+export const clientConfigurationAligned = async (client, providerEnvironment, command) => {
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
+    try {
+        const original = await readFile(client.configPath, "utf8");
+        const document = client.format === "toml"
+            ? objectSchema.parse(parseToml(original))
+            : parseObject(original);
+        const servers = parseOptionalObject(client.format === "toml" ? document.mcp_servers : document.mcpServers);
+        return sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired);
+    }
+    catch {
+        return false;
+    }
+};
+/** Preflight one client configuration before setup presents any mutations. */
+export const inspectClientConfiguration = async (client, providerEnvironment, command) => {
+    if (client.format === "unsupported")
+        return { status: "already_current" };
+    const transactionPath = await resolveClientConfigTransactionPath(client.configPath);
+    if (transactionPath === undefined)
+        return {
+            status: "invalid",
+            remediation: "The configuration path is unsafe or unresolved. Check ownership and symbolic links before rerunning setup.",
+        };
+    let original;
+    try {
+        original = await readFile(transactionPath, "utf8");
+    }
+    catch (cause) {
+        if (isMissing(cause))
+            return { status: "create" };
+        return {
+            status: "invalid",
+            remediation: "The configuration file could not be read. Check its permissions before rerunning setup.",
+        };
+    }
+    const desired = clientConfigurationDesired(client, providerEnvironment, command);
+    try {
+        const document = client.format === "toml"
+            ? objectSchema.parse(parseToml(original))
+            : parseObject(original);
+        const servers = parseOptionalObject(client.format === "toml" ? document.mcp_servers : document.mcpServers);
+        if (sameConfiguration(servers[PRODUCT_IDENTITY.mcpServerKey], desired))
+            return { status: "already_current" };
+    }
+    catch {
+        return {
+            status: "invalid",
+            remediation: "The existing configuration is malformed. Repair it before setup applies any other changes.",
+        };
+    }
+    return {
+        status: "update",
+        backupPath: `${client.configPath}.rea.backup`,
+    };
+};
+const objectSchema = z.record(z.string(), z.unknown());
+const parseOptionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);
+const parseObject = (text) => objectSchema.parse(JSON.parse(text));
+const isMissing = (cause) => cause instanceof Error && "code" in cause && cause.code === "ENOENT";
+const sameConfiguration = (left, right) => JSON.stringify(left) === JSON.stringify(right);
+const preserveConfigBackup = async (source, destination) => {
+    try {
+        await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+        return true;
+    }
+    catch (cause) {
+        return cause instanceof Error && "code" in cause && cause.code === "EEXIST";
+    }
+};
+const restoreConfig = async (path, original) => {
+    try {
+        if (original === undefined)
+            await rm(path, { force: true });
+        else
+            await writeFile(path, original, { encoding: "utf8", mode: 0o600 });
+    }
+    catch {
+        // The backup remains available for the remediation reported by setup.
+    }
+};
+const clientConfigurationDesired = (client, providerEnvironment, command) => {
+    const environment = Object.fromEntries(Object.entries(providerEnvironment).sort(([left], [right]) => left.localeCompare(right)));
+    return {
+        command: command[0] ?? PRODUCT_IDENTITY.cliBinary,
+        args: command.slice(1),
+        ...(client.name === "codex"
+            ? { startup_timeout_sec: CODEX_STARTUP_TIMEOUT_SECONDS }
+            : {}),
+        ...(Object.keys(environment).length === 0 ? {} : { env: environment }),
+    };
+};
+const normalizeProviderEnvironment = (environment) => typeof environment === "string"
+    ? { HOPPER_LAUNCHER_PATH: environment }
+    : environment;

package/dist/application/SetupClients.js

@@ -11,12 +11,34 @@ const failedConfigurationMessage = (reason) => {
 export const configureDetectedClients = async (options) => {
     let failure;
     for (const client of options.detectedClients) {
+        const actionId = `configure_client:${client.name}`;
+        const label = client.displayName ?? client.name;
+        options.onProgress?.({ actionId, label, state: "started" });
         const result = await options.host.configureClient(client, options.providerEnvironment, options.command);
         options.clients[client.name] = result;
-        if (result.status === "failed")
+        if (result.status === "failed") {
             failure ??= failedConfigurationMessage(result.reason);
-        else if (result.status === "configured")
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "failed",
+                detail: failedConfigurationMessage(result.reason),
+            });
+        }
+        else if (result.status === "configured") {
             options.appliedActions.push(`configured_${client.name}`);
+            options.onProgress?.({ actionId, label, state: "completed" });
+        }
+        else {
+            options.onProgress?.({
+                actionId,
+                label,
+                state: "warning",
+                detail: result.status === "unchanged"
+                    ? "Already current"
+                    : "Manual configuration required",
+            });
+        }
     }
     return failure;
 };

package/dist/application/SetupPlan.js

@@ -1,38 +1,150 @@
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { PRODUCT_IDENTITY } from "../identity.js";
+import { linuxHopperInstallDisclosure, } from "./LinuxHopper.js";
+import { macHopperInstallDisclosure } from "./MacHopper.js";
 /** Build the complete setup mutation plan before approval. */
-export const setupPlan = (platform, installHopper, installSkill, clients, providerEnvironment) => [
-    ...(installHopper
+const setupPlan = (input) => [
+    ...(input.installHopper
         ? [
             {
+                id: "install_hopper",
                 kind: "install_hopper",
-                target: platform === "darwin"
-                    ? "~/Applications/Hopper Disassembler.app"
+                label: "Hopper deep-analysis provider",
+                target: input.platform === "darwin"
+                    ? join(homedir(), "Applications/Hopper Disassembler.app")
                     : "system package manager",
-                detail: platform === "linux"
+                detail: input.platform === "linux"
                     ? "Download, verify, and install Hopper plus its Xvfb demo-session dependencies. For the supported demo build, REA uses a private display and selects Hopper's offered demo mode for each analysis session."
                     : "Download the official Hopper package, verify it, and install it. Hopper may show its demo or license prompt when first opened.",
                 external: true,
+                operation: "install",
+                ...(input.platform === "linux"
+                    ? input.linuxPackageFamily === undefined
+                        ? {}
+                        : linuxDisclosure(input.linuxPackageFamily)
+                    : {
+                        networkOrigins: macHopperInstallDisclosure.networkOrigins,
+                        commands: macHopperInstallDisclosure.commands,
+                    }),
             },
         ]
         : []),
-    ...clients
-        .filter(({ format }) => format !== "unsupported")
-        .map((client) => ({
+    ...input.clients
+        .filter(({ client }) => client.format !== "unsupported")
+        .map(({ client, operation, backupPath }) => ({
+        id: `configure_client:${client.name}`,
         kind: "configure_client",
+        label: client.displayName ?? client.name,
         target: client.configPath,
-        detail: clientConfigurationDetail(client.name, providerEnvironment),
+        detail: clientConfigurationDetail(client.displayName ?? client.name, input.providerEnvironment),
         external: false,
+        operation,
+        ...(backupPath === undefined ? {} : { backupPath }),
     })),
-    ...(installSkill
+    ...(input.installSkill
         ? [
             {
+                id: "install_skill",
                 kind: "install_skill",
-                target: "~/.agents/skills/rea-analysis/SKILL.md",
-                detail: "Install or update the bundled REA analysis skill.",
+                label: "REA reverse-engineering skill",
+                target: join(homedir(), ".agents/skills", PRODUCT_IDENTITY.skillName),
+                detail: "Install or update the bundled REA reverse-engineering skill and on-demand references.",
                 external: false,
+                operation: "install",
             },
         ]
         : []),
 ];
+/** 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();
+    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 {
+        networkOrigins: [disclosure.downloadUrl],
+        commands: disclosure.commands,
+        integrity: `${String(disclosure.expectedBytes)} bytes · SHA-1 ${disclosure.expectedSha1}`,
+    };
+};
 const clientConfigurationDetail = (client, environment) => {
     const entries = Object.entries(environment)
         .sort(([left], [right]) => left.localeCompare(right))

package/dist/application/SetupSkill.js

@@ -2,59 +2,77 @@ import { mkdir, readFile, rm } from "node:fs/promises";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 import { PRODUCT_IDENTITY } from "../identity.js";
-const canonicalSkillFiles = async (home) => ({
-    destination: join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
-    content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/SKILL.md`, import.meta.url), "utf8"),
-});
-/** Report whether setup would change the managed REA skill. */
+const SKILL_FILES = [
+    "SKILL.md",
+    "references/native-and-artifacts.md",
+    "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) => {
+    try {
+        return await readFile(path, "utf8");
+    }
+    catch (cause) {
+        if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+            return undefined;
+        throw cause;
+    }
+};
+const canonicalSkillFiles = async (home) => Promise.all(SKILL_FILES.map(async (relativePath) => {
+    const destination = join(skillRoot(home), relativePath);
+    return {
+        destination,
+        content: await readFile(new URL(`../../skills/${PRODUCT_IDENTITY.skillName}/${relativePath}`, import.meta.url), "utf8"),
+        original: await readOptionalText(destination),
+    };
+}));
+/** Report whether setup would change any file in the managed REA skill bundle. */
 export const canonicalSkillNeedsInstall = async (home) => {
     try {
-        const { content, destination } = await canonicalSkillFiles(home);
-        return (await readFile(destination, "utf8")) !== content;
+        return (await canonicalSkillFiles(home)).some(({ content, original }) => original !== content);
     }
     catch {
         return true;
     }
 };
-/** Transactionally install or upgrade the versioned canonical REA skill. */
+const writeText = (path, content) => writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
+const restoreSkillFiles = async (changed) => {
+    for (const { destination, original } of [...changed].reverse()) {
+        if (original === undefined)
+            await rm(destination, { force: true });
+        else
+            await writeText(destination, original);
+    }
+};
+/** Transactionally install or upgrade the canonical REA skill and references. */
 export const installCanonicalSkill = async (home) => {
-    let destination = join(home, ".agents/skills", PRODUCT_IDENTITY.skillName, "SKILL.md");
-    let backup = `${destination}.rea.backup`;
-    let original;
+    let changed = [];
     try {
         const canonical = await canonicalSkillFiles(home);
-        destination = canonical.destination;
-        backup = `${destination}.rea.backup`;
-        const { content } = canonical;
-        original = await readFile(destination, "utf8").catch(() => undefined);
-        if (original === content)
+        changed = canonical.filter(({ content, original }) => original !== content);
+        if (changed.length === 0)
             return "unchanged";
-        await mkdir(dirname(destination), { recursive: true });
-        if (original !== undefined)
-            await writeFileAtomic(backup, original, {
-                encoding: "utf8",
-                mode: 0o600,
-            });
-        await writeFileAtomic(destination, content, {
-            encoding: "utf8",
-            mode: 0o600,
-        });
-        if ((await readFile(destination, "utf8")) !== content)
-            throw new Error("skill readback mismatch");
+        for (const { destination, original } of changed) {
+            await mkdir(dirname(destination), { recursive: true });
+            if (original !== undefined)
+                await writeText(`${destination}.rea.backup`, original);
+        }
+        for (const { destination, content } of changed)
+            await writeText(destination, content);
+        for (const { destination, content } of changed)
+            if ((await readFile(destination, "utf8")) !== content)
+                throw new Error(`skill readback mismatch: ${destination}`);
         return "installed";
     }
     catch {
         try {
-            if (original === undefined)
-                await rm(destination, { force: true });
-            else
-                await writeFileAtomic(destination, original, {
-                    encoding: "utf8",
-                    mode: 0o600,
-                });
+            await restoreSkillFiles(changed);
         }
         catch {
-            // The backup remains beside the skill for explicit operator recovery.
+            // Per-file backups remain beside changed files for operator recovery.
         }
         return "failed";
     }

package/dist/application/SupportedClients.js

@@ -59,6 +59,7 @@ export const SUPPORTED_CLIENT_DEFINITIONS = [
 /** 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,

package/dist/application/Uninstall.js

@@ -39,7 +39,7 @@ export const runUninstall = async (purgeData, host = systemUninstallHost()) => {
 export const systemUninstallHost = (home = homedir(), fileSystem = systemFileSystem) => ({
     clients: () => Promise.resolve(supportedClients(home)),
     removeClient: (client) => removeClient(client, fileSystem),
-    removeSkill: () => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem),
+    removeSkill: () => removeManagedSkills(home, fileSystem),
     purgeData: async () => [
         await removeManagedPath(join(home, ".rea/cache"), "cache", fileSystem),
         await removeManagedPath(join(home, ".rea/state"), "state", fileSystem),
@@ -127,8 +127,16 @@ const isOwnedRegistration = (value) => {
         args.length === 1 &&
         args[0] === "mcp") ||
         (command === "npx" &&
-            JSON.stringify(args) ===
-                JSON.stringify(["-y", PRODUCT_IDENTITY.packageName, "mcp"])));
+            (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"]))));
 };
 const removeManagedPath = async (path, name, fileSystem) => {
     try {
@@ -144,6 +152,7 @@ const removeManagedPath = async (path, name, fileSystem) => {
             : item(name, "failed", "This item could not be removed. Check file permissions, then rerun uninstall.");
     }
 };
+const removeManagedSkills = async (home, fileSystem) => removeManagedPath(join(home, ".agents/skills", PRODUCT_IDENTITY.skillName), "skill", fileSystem);
 const item = (name, status, detail) => ({ name, status, detail });
 const objectSchema = z.record(z.string(), z.unknown());
 const optionalObject = (value) => value === undefined ? {} : objectSchema.parse(value);

package/dist/application/Upgrade.js

@@ -9,6 +9,7 @@ import { PRODUCT_IDENTITY } from "../identity.js";
 const execFileAsync = promisify(execFile);
 const registryResponseSchema = z.object({ version: z.string().min(1) });
 const UPGRADE_COMMAND = "npm install --global rea-agents@latest";
+const CLI_SCRIPT_PATH = fileURLToPath(new URL("../../scripts/rea.mjs", import.meta.url));
 /** Check the npm registry and update the same global REA installation. */
 export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), output = "human") => {
     const latestVersion = await host.latestVersion();
@@ -46,6 +47,12 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
             reason: "install",
             remediation: `REA could not update through npm. Check npm registry access and global install permissions, then run: ${UPGRADE_COMMAND}`,
         };
+    const integrationSyncResult = await host.syncAgentIntegration(output);
+    const integrationSync = integrationSyncResult === undefined
+        ? "deferred"
+        : integrationSyncResult
+            ? "setup_invoked"
+            : "failed";
     return {
         status: "upgraded",
         previousVersion: currentVersion,
@@ -53,8 +60,11 @@ export const runUpgrade = async (currentVersion, host = systemUpgradeHost(), out
         versionCheck: "available",
         installMethod: "npm",
         command: UPGRADE_COMMAND,
+        integrationSync,
         clientRestartRequired: true,
-        remediation: "Rerun rea setup to refresh registrations and the skill, then restart clients that may retain an older MCP server.",
+        remediation: integrationSync === "setup_invoked"
+            ? "The updated setup journey was opened to align registrations and the skill. Restart clients whose approved registration changed."
+            : "Run rea setup --all-detected to align registrations and the skill, then restart clients that may retain an older MCP server.",
     };
 };
 /** Create the npm registry and subprocess effects for a production upgrade. */
@@ -79,6 +89,11 @@ export const systemUpgradeHost = () => ({
         prefix,
         `${PRODUCT_IDENTITY.packageName}@latest`,
     ], output),
+    syncAgentIntegration: (output) => output === "structured" ||
+        process.stdin.isTTY !== true ||
+        process.stderr.isTTY !== true
+        ? Promise.resolve(undefined)
+        : runCommand(process.execPath, [CLI_SCRIPT_PATH, "setup", "--all-detected"], "human"),
 });
 const systemNpmInstallationHost = {
     canonicalPath: realpath,