fix(setup): preserve recovery backups and retain installer cleanup

Validation: integrated changes passed formatting, typecheck, lint, resolved module-boundary verification and git diff --check. Tests and real-provider workflows were not run.

src/application/HopperDownload.ts

@@ -0,0 +1,43 @@
+/** Maximum admitted vendor response bytes, shared by Hopper setup adapters. */
+export const HOPPER_DOWNLOAD_BYTES = 100_000_000;
+
+/** Bound observed response bytes before retaining them, including chunked bodies. */
+export const downloadHopperPackage = async (
+  url: string,
+  options: { readonly signal?: AbortSignal } = {},
+): Promise<{ readonly ok: boolean; readonly bytes: Uint8Array }> => {
+  const deadline = AbortSignal.timeout(120_000);
+  const response = await fetch(url, {
+    headers: { accept: "application/json", "user-agent": "rea-installer" },
+    signal:
+      options.signal === undefined
+        ? deadline
+        : AbortSignal.any([options.signal, deadline]),
+  });
+  const refused = { ok: false, bytes: new Uint8Array() };
+  if (
+    !response.ok ||
+    Number(response.headers.get("content-length")) > HOPPER_DOWNLOAD_BYTES
+  ) {
+    await response.body?.cancel();
+    return refused;
+  }
+  if (response.body === null) return { ok: true, bytes: new Uint8Array() };
+  const reader = response.body.getReader();
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    while (true) {
+      const chunk = await reader.read();
+      if (chunk.done) return { ok: true, bytes: Buffer.concat(chunks, bytes) };
+      if (chunk.value.byteLength > HOPPER_DOWNLOAD_BYTES - bytes) {
+        await reader.cancel();
+        return refused;
+      }
+      chunks.push(chunk.value);
+      bytes += chunk.value.byteLength;
+    }
+  } finally {
+    reader.releaseLock();
+  }
+};

src/application/LinuxHopper.ts

@@ -7,10 +7,13 @@ import { join } from "node:path";
 import { promisify } from "node:util";
 
 import { execFileOutput } from "../process/ExecFileOutput.js";
+import {
+  downloadHopperPackage,
+  HOPPER_DOWNLOAD_BYTES,
+} from "./HopperDownload.js";
 
 const execFileAsync = promisify(execFile);
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
-const MAX_PACKAGE_BYTES = 100_000_000;
 const SUPPORTED_HOPPER_SHA256 = new Set([
   "0294ced141cc373468ee22d8343e7dac41980cb05a937994ca81c9f09afe7ded",
   "1339f9e58377442b0c6fcb0dfc3cec20d593cc557408521fad9a00dbc6b8da13",
@@ -231,16 +234,7 @@ export const systemLinuxHopperInstallHost = (
   environment: Readonly<NodeJS.ProcessEnv>,
 ): LinuxHopperInstallHost => ({
   distribution: readLinuxDistribution,
-  async download(url, options) {
-    const response = await fetch(url, {
-      headers: { accept: "application/json", "user-agent": "rea-installer" },
-      ...(options.signal === undefined ? {} : { signal: options.signal }),
-    });
-    return {
-      ok: response.ok,
-      bytes: new Uint8Array(await response.arrayBuffer()),
-    };
-  },
+  download: downloadHopperPackage,
   createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-")),
   writeArchive: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
   installPackage: (family, archive) =>
@@ -350,7 +344,7 @@ const packageIntegrityMatches = (
   release: LinuxHopperRelease,
 ): boolean =>
   bytes.byteLength === Number(release.file_length) &&
-  bytes.byteLength <= MAX_PACKAGE_BYTES &&
+  bytes.byteLength <= HOPPER_DOWNLOAD_BYTES &&
   createHash("sha1").update(bytes).digest("hex") === release.file_hash;
 
 const packageFamilyFor = (

src/application/MacHopper.ts

@@ -15,12 +15,15 @@ import { promisify } from "node:util";
 
 import { z } from "zod";
 import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+import {
+  downloadHopperPackage,
+  HOPPER_DOWNLOAD_BYTES,
+} from "./HopperDownload.js";
 
 const execFileAsync = promisify(execFile);
 const RELEASES_URL =
   "https://www.hopperapp.com/include/files-api.php?request=releases&public=true";
 const DOWNLOAD_PREFIX = "https://www.hopperapp.com:443/downloader/public/";
-const MAX_PACKAGE_BYTES = 100_000_000;
 const BUNDLE_IDENTIFIER = "com.cryptic-apps.hopper-web-4";
 
 /** Stable network and command effects disclosed before macOS Hopper setup. */
@@ -36,7 +39,11 @@ export const macHopperInstallDisclosure = {
 
 /** Result of installing the official Hopper macOS application. */
 export type MacHopperInstallResult =
-  | { readonly status: "installed"; readonly launcherPath: string }
+  | {
+      readonly status: "installed";
+      readonly launcherPath: string;
+      readonly cleanupFailure?: string;
+    }
   | {
       readonly status: "failed";
       readonly reason:
@@ -48,6 +55,7 @@ export type MacHopperInstallResult =
         | "destination_exists"
         | "copy"
         | "launcher_missing";
+      readonly cleanupFailure?: string;
     };
 
 /** External effects used by the bounded macOS Hopper installer. */
@@ -72,6 +80,8 @@ export interface MacHopperInstallHost {
   launcherReady(path: string): Promise<boolean>;
   openApplication(path: string): Promise<void>;
   cleanup(path: string): Promise<void>;
+  /** Retain the cleanup capability until the owning setup host retries it. */
+  retainCleanup?(cleanup: () => Promise<void>): void;
   destination(): string;
 }
 
@@ -85,187 +95,221 @@ export const installMacHopper = async (
 ): Promise<MacHopperInstallResult> => {
   let temporary: string | undefined;
   let mounted = false;
+  let result: MacHopperInstallResult;
   try {
-    const metadata = await host.download(RELEASES_URL);
-    if (!metadata.ok) return { status: "failed", reason: "release_metadata" };
-    const parsed = releasesSchema.safeParse(parseJson(metadata.bytes));
-    if (!parsed.success)
-      return { status: "failed", reason: "release_metadata" };
-    const release = parsed.data["OS X"];
-    if (!release.filename.startsWith(DOWNLOAD_PREFIX))
-      return { status: "failed", reason: "release_metadata" };
-    const archive = await host.download(release.filename);
-    if (!archive.ok) return { status: "failed", reason: "download" };
-    if (!integrityMatches(archive.bytes, release))
-      return { status: "failed", reason: "integrity" };
+    result = await (async (): Promise<MacHopperInstallResult> => {
+      const metadata = await host.download(RELEASES_URL);
+      if (!metadata.ok) return { status: "failed", reason: "release_metadata" };
+      const parsed = releasesSchema.safeParse(parseJson(metadata.bytes));
+      if (!parsed.success)
+        return { status: "failed", reason: "release_metadata" };
+      const release = parsed.data["OS X"];
+      if (!release.filename.startsWith(DOWNLOAD_PREFIX))
+        return { status: "failed", reason: "release_metadata" };
+      const archive = await host.download(release.filename);
+      if (!archive.ok) return { status: "failed", reason: "download" };
+      if (!integrityMatches(archive.bytes, release))
+        return { status: "failed", reason: "integrity" };
 
-    const destination = host.destination();
-    const destinationExists = await host.destinationExists(destination);
-    if (destinationExists && options.replaceExisting !== true)
-      return { status: "failed", reason: "destination_exists" };
-    temporary = await host.createTemporaryDirectory();
-    const packagePath = join(temporary, "hopper.dmg");
-    const mountPath = join(temporary, "mounted");
-    await host.createMountDirectory(mountPath);
-    await host.writePackage(packagePath, archive.bytes);
-    if (!(await host.mount(packagePath, mountPath)))
-      return { status: "failed", reason: "mount" };
-    mounted = true;
-    const source = await host.appBundle(mountPath);
-    if (source === undefined || !(await host.validBundle(source)))
-      return { status: "failed", reason: "bundle" };
-    const stage = `${destination}.rea-stage`;
-    if (
-      !(await host.installBundle(source, destination, stage, destinationExists))
-    )
-      return { status: "failed", reason: "copy" };
-    const launcherPath = join(destination, "Contents/MacOS/hopper");
-    if (!(await host.launcherReady(launcherPath)))
-      return { status: "failed", reason: "launcher_missing" };
-    await host.openApplication(destination);
-    return { status: "installed", launcherPath };
+      const destination = host.destination();
+      const destinationExists = await host.destinationExists(destination);
+      if (destinationExists && options.replaceExisting !== true)
+        return { status: "failed", reason: "destination_exists" };
+      temporary = await host.createTemporaryDirectory();
+      const packagePath = join(temporary, "hopper.dmg");
+      const mountPath = join(temporary, "mounted");
+      await host.createMountDirectory(mountPath);
+      await host.writePackage(packagePath, archive.bytes);
+      if (!(await host.mount(packagePath, mountPath)))
+        return { status: "failed", reason: "mount" };
+      mounted = true;
+      const source = await host.appBundle(mountPath);
+      if (source === undefined || !(await host.validBundle(source)))
+        return { status: "failed", reason: "bundle" };
+      const stage = `${destination}.rea-stage`;
+      if (
+        !(await host.installBundle(
+          source,
+          destination,
+          stage,
+          destinationExists,
+        ))
+      )
+        return { status: "failed", reason: "copy" };
+      const launcherPath = join(destination, "Contents/MacOS/hopper");
+      if (!(await host.launcherReady(launcherPath)))
+        return { status: "failed", reason: "launcher_missing" };
+      await host.openApplication(destination);
+      return { status: "installed", launcherPath };
+    })();
   } catch (cause: unknown) {
     // Install-stage failures share the download reason; the stage is cleaned below.
     void cause;
-    return { status: "failed", reason: "download" };
-  } finally {
-    if (temporary !== undefined) {
-      const mountPath = join(temporary, "mounted");
-      if (mounted) await host.unmount(mountPath);
-      await host.cleanup(temporary);
+    result = { status: "failed", reason: "download" };
+  }
+
+  let cleanupFailure: string | undefined;
+  if (temporary !== undefined) {
+    const temporaryPath = temporary;
+    const mountPath = join(temporary, "mounted");
+    const cleanup = async (): Promise<void> => {
+      if (mounted) {
+        await host.unmount(mountPath);
+        mounted = false;
+      }
+      await host.cleanup(temporaryPath);
+    };
+    try {
+      await cleanup();
+    } catch (cause: unknown) {
+      cleanupFailure = `Hopper DMG cleanup failed: ${failureMessage(cause)}`;
+      host.retainCleanup?.(cleanup);
     }
   }
+
+  return cleanupFailure === undefined ? result : { ...result, cleanupFailure };
 };
 
 /** Compose installer paths and subprocesses from one selected caller context. */
 export const systemMacHopperInstallHost = (
   homeDirectory: string,
   environment: Readonly<NodeJS.ProcessEnv>,
-): MacHopperInstallHost => ({
-  download: downloadPackage,
-  createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
-  createMountDirectory: (path) => mkdir(path),
-  writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
-  async mount(packagePath, mountPath) {
-    return commandSucceeds(
-      "hdiutil",
-      [
-        "attach",
-        "-readonly",
-        "-nobrowse",
-        "-mountpoint",
-        mountPath,
-        packagePath,
-      ],
-      environment,
-    );
-  },
-  async unmount(mountPath) {
-    await commandSucceeds(
-      "hdiutil",
-      ["detach", mountPath, "-force"],
-      environment,
-    );
-  },
-  async appBundle(mountPath) {
-    const entries = await readdir(mountPath, { withFileTypes: true });
-    const app = entries.find(
-      (entry) => entry.isDirectory() && /^Hopper.*\.app$/iu.test(entry.name),
-    );
-    return app === undefined ? undefined : join(mountPath, app.name);
-  },
-  async validBundle(appPath) {
-    if (
-      !(await commandSucceeds(
-        "codesign",
-        ["--verify", "--deep", "--strict", appPath],
+): MacHopperInstallHost & { close(): Promise<string | undefined> } => {
+  const pendingCleanup = new Set<() => Promise<void>>();
+  return {
+    download: downloadHopperPackage,
+    createTemporaryDirectory: () => mkdtemp(join(tmpdir(), "rea-hopper-mac-")),
+    createMountDirectory: (path) => mkdir(path),
+    writePackage: (path, bytes) => writeFile(path, bytes, { mode: 0o600 }),
+    async mount(packagePath, mountPath) {
+      return commandSucceeds(
+        "hdiutil",
+        [
+          "attach",
+          "-readonly",
+          "-nobrowse",
+          "-mountpoint",
+          mountPath,
+          packagePath,
+        ],
         environment,
-      ))
-    )
-      return false;
-    try {
-      const identifier = (
-        await execFileAsync(
-          "/usr/libexec/PlistBuddy",
-          [
-            "-c",
-            "Print :CFBundleIdentifier",
-            join(appPath, "Contents/Info.plist"),
-          ],
-          { env: environment },
-        )
-      ).stdout.trim();
-      return identifier === BUNDLE_IDENTIFIER;
-    } catch (cause: unknown) {
-      // best-effort cleanup: optional bundle probing; unreadable means invalid.
-      void cause;
-      return false;
-    }
-  },
-  async destinationExists(path) {
-    try {
-      await access(path);
-      return true;
-    } catch (cause: unknown) {
-      // best-effort cleanup: optional existence probing; absence means missing.
-      void cause;
-      return false;
-    }
-  },
-  async installBundle(source, destination, stage, replaceExisting) {
-    const previous = `${stage}-previous`;
-    try {
-      await mkdir(join(homeDirectory, "Applications"), { recursive: true });
-      await rm(stage, { recursive: true, force: true });
-      await rm(previous, { recursive: true, force: true });
-      await execFileAsync("ditto", [source, stage], { env: environment });
-      await access(join(stage, "Contents/MacOS/hopper"));
-      if (replaceExisting) await rename(destination, previous);
-      await rename(stage, destination);
-      if (replaceExisting) await rm(previous, { recursive: true, force: true });
-      return true;
-    } catch (cause: unknown) {
-      // Install failure rolls back below; the false return reports it.
-      void cause;
-      await rm(stage, { recursive: true, force: true });
-      if (replaceExisting) {
+      );
+    },
+    async unmount(mountPath) {
+      if (
+        !(await commandSucceeds(
+          "hdiutil",
+          ["detach", mountPath, "-force"],
+          environment,
+        ))
+      )
+        throw new Error(
+          `hdiutil detach failed for ${JSON.stringify(mountPath)}`,
+        );
+    },
+    async appBundle(mountPath) {
+      const entries = await readdir(mountPath, { withFileTypes: true });
+      const app = entries.find(
+        (entry) => entry.isDirectory() && /^Hopper.*\.app$/iu.test(entry.name),
+      );
+      return app === undefined ? undefined : join(mountPath, app.name);
+    },
+    async validBundle(appPath) {
+      if (
+        !(await commandSucceeds(
+          "codesign",
+          ["--verify", "--deep", "--strict", appPath],
+          environment,
+        ))
+      )
+        return false;
+      try {
+        const identifier = (
+          await execFileAsync(
+            "/usr/libexec/PlistBuddy",
+            [
+              "-c",
+              "Print :CFBundleIdentifier",
+              join(appPath, "Contents/Info.plist"),
+            ],
+            { env: environment },
+          )
+        ).stdout.trim();
+        return identifier === BUNDLE_IDENTIFIER;
+      } catch (cause: unknown) {
+        // best-effort cleanup: optional bundle probing; unreadable means invalid.
+        void cause;
+        return false;
+      }
+    },
+    async destinationExists(path) {
+      try {
+        await access(path);
+        return true;
+      } catch (cause: unknown) {
+        // best-effort cleanup: optional existence probing; absence means missing.
+        void cause;
+        return false;
+      }
+    },
+    async installBundle(source, destination, stage, replaceExisting) {
+      const previous = `${stage}-previous`;
+      try {
+        await mkdir(join(homeDirectory, "Applications"), { recursive: true });
+        await rm(stage, { recursive: true, force: true });
+        await rm(previous, { recursive: true, force: true });
+        await execFileAsync("ditto", [source, stage], { env: environment });
+        await access(join(stage, "Contents/MacOS/hopper"));
+        if (replaceExisting) await rename(destination, previous);
+        await rename(stage, destination);
+        if (replaceExisting)
+          await rm(previous, { recursive: true, force: true });
+        return true;
+      } catch (cause: unknown) {
+        // Install failure rolls back below; the false return reports it.
+        void cause;
+        await rm(stage, { recursive: true, force: true });
+        if (replaceExisting) {
+          try {
+            await rename(previous, destination);
+          } catch (rollbackCause: unknown) {
+            // The original destination was not moved, or rollback is impossible.
+            void rollbackCause;
+          }
+        }
+        return false;
+      }
+    },
+    async launcherReady(path) {
+      try {
+        await access(path);
+        return true;
+      } catch (cause: unknown) {
+        // best-effort cleanup: optional launcher probing; absence means not ready.
+        void cause;
+        return false;
+      }
+    },
+    async openApplication(path) {
+      await execFileAsync("open", [path], { env: environment });
+    },
+    cleanup: (path) => rm(path, { recursive: true, force: true }),
+    retainCleanup: (cleanup) => pendingCleanup.add(cleanup),
+    async close() {
+      let failure: string | undefined;
+      for (const cleanup of pendingCleanup) {
         try {
-          await rename(previous, destination);
-        } catch (rollbackCause: unknown) {
-          // The original destination was not moved, or rollback is impossible.
-          void rollbackCause;
+          await cleanup();
+          pendingCleanup.delete(cleanup);
+        } catch (cause: unknown) {
+          failure ??= `Hopper DMG cleanup remains incomplete: ${failureMessage(cause)}`;
         }
       }
-      return false;
-    }
-  },
-  async launcherReady(path) {
-    try {
-      await access(path);
-      return true;
-    } catch (cause: unknown) {
-      // best-effort cleanup: optional launcher probing; absence means not ready.
-      void cause;
-      return false;
-    }
-  },
-  async openApplication(path) {
-    await execFileAsync("open", [path], { env: environment });
-  },
-  cleanup: (path) => rm(path, { recursive: true, force: true }),
-  destination: () =>
-    join(homeDirectory, "Applications/Hopper Disassembler.app"),
-});
-
-const downloadPackage = async (url: string) => {
-  const response = await fetch(url, {
-    headers: { accept: "application/json", "user-agent": "rea-installer" },
-    signal: AbortSignal.timeout(120_000),
-  });
-  const length = Number(response.headers.get("content-length") ?? "0");
-  if (length > MAX_PACKAGE_BYTES) return { ok: false, bytes: new Uint8Array() };
-  const bytes = new Uint8Array(await response.arrayBuffer());
-  return { ok: response.ok && bytes.byteLength <= MAX_PACKAGE_BYTES, bytes };
+      return failure;
+    },
+    destination: () =>
+      join(homeDirectory, "Applications/Hopper Disassembler.app"),
+  };
 };
 
 const parseJson = (bytes: Uint8Array): unknown =>
@@ -275,7 +319,7 @@ const integrityMatches = (
   release: z.infer<typeof releaseSchema>,
 ): boolean =>
   bytes.byteLength === Number(release.file_length) &&
-  bytes.byteLength <= MAX_PACKAGE_BYTES &&
+  bytes.byteLength <= HOPPER_DOWNLOAD_BYTES &&
   createHash("sha1").update(bytes).digest("hex") === release.file_hash;
 const commandSucceeds = async (
   command: string,
@@ -291,6 +335,8 @@ const commandSucceeds = async (
     return false;
   }
 };
+const failureMessage = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);
 const releaseSchema = z.object({
   filename: z.string().url(),
   file_length: z.string().regex(/^\d+$/u),

src/application/Setup.ts

@@ -29,6 +29,49 @@ export const runSetup = async (
   options: SetupOptions,
   host: SetupHost = systemSetupHost(),
   confirm?: SetupConfirmation,
+): Promise<SetupResult> => {
+  let result: SetupResult | undefined;
+  let primaryFailure: unknown;
+  let threw = false;
+  try {
+    result = await runSetupWorkflow(options, host, confirm);
+  } catch (cause: unknown) {
+    threw = true;
+    primaryFailure = cause;
+  }
+
+  let cleanupFailure: string | undefined;
+  try {
+    cleanupFailure = await host.close?.();
+  } catch (cause: unknown) {
+    cleanupFailure = `Setup resource cleanup failed: ${failureMessage(cause)}`;
+  }
+
+  if (threw) {
+    if (cleanupFailure !== undefined)
+      throw new AggregateError(
+        [primaryFailure, new Error(cleanupFailure)],
+        "Setup and resource cleanup failed.",
+        { cause: primaryFailure },
+      );
+    throw primaryFailure;
+  }
+  if (result === undefined) throw new Error("Setup returned no result.");
+  if (cleanupFailure === undefined) return result;
+  return {
+    ...result,
+    status: "needs_human",
+    code: result.code ?? "cleanup_failed",
+    remediation: result.remediation
+      ? `${result.remediation} ${cleanupFailure}`
+      : cleanupFailure,
+  };
+};
+
+const runSetupWorkflow = async (
+  options: SetupOptions,
+  host: SetupHost,
+  confirm?: SetupConfirmation,
 ): Promise<SetupResult> => {
   const appliedActions: string[] = [];
   let plannedActions: readonly SetupAction[] = [];
@@ -59,6 +102,7 @@ export const runSetup = async (
     options.readinessScope?.clients === undefined &&
     options.allDetectedClients !== true &&
     options.installHopper !== true &&
+    options.skillClientIds === undefined &&
     options.installSkill === undefined;
   const interactiveSelection =
     confirm !== undefined && !options.structured && clientSelectionAllowed;
@@ -67,10 +111,12 @@ export const runSetup = async (
     : (options.clientIds ??
       options.readinessScope?.clients ??
       discovery.defaultClientIds);
-  let skillNeedsInstall = await host.skillNeedsInstall(selectedClientIds);
+  let selectedSkillClientIds = options.skillClientIds ?? selectedClientIds;
+  let skillNeedsInstall = await host.skillNeedsInstall(selectedSkillClientIds);
   let skillSelected =
     options.installSkill === true ||
-    (options.installSkill !== false && selectedClientIds.length > 0);
+    (options.installSkill !== false &&
+      (selectedClientIds.length > 0 || selectedSkillClientIds.length > 0));
   let installSkill = skillSelected && skillNeedsInstall;
   let planDiscovery = discovery;
   if (interactiveSelection) {
@@ -138,6 +184,7 @@ export const runSetup = async (
         selectedClientIds.length === 0) ||
       (options.installSkill !== false && selectedClientIds.length > 0);
     installSkill = skillSelected && skillNeedsInstall;
+    selectedSkillClientIds = selectedClientIds;
   }
   const planned = await planSetupActions({
     discovery: planDiscovery,
@@ -145,7 +192,7 @@ export const runSetup = async (
     providerEnvironment,
     command: host.registrationCommand,
     clientIds: selectedClientIds,
-    skillClientIds: selectedClientIds,
+    skillClientIds: selectedSkillClientIds,
     installSkill,
   });
   plannedActions = planned.plannedActions;
@@ -256,7 +303,7 @@ export const runSetup = async (
       host,
       options,
       appliedActions,
-      selectedClientIds,
+      selectedSkillClientIds,
     ))
   )
     return fail(
@@ -325,8 +372,11 @@ const installHopperAction = async (input: {
   emitProgress(input.options, {
     actionId: "install_hopper",
     label,
-    state: "completed",
-    detail: installed.launcherPath,
+    state: installed.cleanupFailure === undefined ? "completed" : "warning",
+    detail:
+      installed.cleanupFailure === undefined
+        ? installed.launcherPath
+        : `${installed.launcherPath}; ${installed.cleanupFailure}`,
   });
   const providerEnvironment = {
     ...input.providerEnvironment,
@@ -492,3 +542,6 @@ const summarizeDoctor = (report: DoctorReport): SetupDoctorSummary => ({
         },
       }),
 });
+
+const failureMessage = (cause: unknown): string =>
+  cause instanceof Error ? cause.message : String(cause);

src/application/SetupHost.ts

@@ -94,6 +94,10 @@ export const systemSetupHost = (
   const doctorHost = selectedDoctorHost ?? systemDoctorHost({ environment });
   const platform = doctorHost.platform;
   const { homeDirectory } = doctorHost;
+  const macHopperHost =
+    platform === "darwin"
+      ? systemMacHopperInstallHost(homeDirectory, environment)
+      : undefined;
   return {
     platform,
     homeDirectory,
@@ -106,6 +110,7 @@ export const systemSetupHost = (
     nodeVersion: process.versions.node,
     macosVersion: () => doctorHost.macosVersion(),
     linuxDistribution: readLinuxDistribution,
+    close: () => macHopperHost?.close() ?? Promise.resolve(undefined),
     initialSetupState: async (
       scope?: DoctorScope,
     ): Promise<SetupInitialState> => {
@@ -126,15 +131,33 @@ export const systemSetupHost = (
       };
     },
     installHopper: async (replaceExisting) => {
-      const result =
-        platform === "linux"
-          ? await installLinuxHopper(systemLinuxHopperInstallHost(environment))
-          : await installMacHopper(
-              { replaceExisting },
-              systemMacHopperInstallHost(homeDirectory, environment),
-            );
-      if (result.status === "installed") return result;
-      return setupInstallFailure(result.reason);
+      if (platform === "linux") {
+        const result = await installLinuxHopper(
+          systemLinuxHopperInstallHost(environment),
+        );
+        return result.status === "installed"
+          ? result
+          : setupInstallFailure(result.reason);
+      }
+      if (macHopperHost === undefined)
+        return setupInstallFailure("unsupported_host");
+      const result = await installMacHopper({ replaceExisting }, macHopperHost);
+      if (result.status === "installed")
+        return {
+          status: "installed",
+          launcherPath: result.launcherPath,
+          ...(result.cleanupFailure === undefined
+            ? {}
+            : { cleanupFailure: result.cleanupFailure }),
+        };
+      const failure = setupInstallFailure(result.reason);
+      if (result.cleanupFailure === undefined) return failure;
+      return failure.status === "failed"
+        ? {
+            ...failure,
+            remediation: `${failure.remediation} ${result.cleanupFailure}`,
+          }
+        : failure;
     },
     detectedClients: () => detectClients(homeDirectory, platform, environment),
     supportedClients: () =>

src/application/SetupInstallFailure.ts

@@ -10,10 +10,15 @@ export type SetupFailureCode =
   | "destination_exists"
   | "mount_failed"
   | "bundle_invalid"
-  | "copy_failed";
+  | "copy_failed"
+  | "cleanup_failed";
 
 export type SetupHopperInstallResult =
-  | { readonly status: "installed"; readonly launcherPath: string }
+  | {
+      readonly status: "installed";
+      readonly launcherPath: string;
+      readonly cleanupFailure?: string;
+    }
   | {
       readonly status: "failed";
       readonly code: SetupFailureCode;

src/application/SetupSkill.ts

@@ -1,11 +1,16 @@
-import { mkdir, readFile, rm } from "node:fs/promises";
+import { copyFile, lstat, mkdir, readFile, rm } from "node:fs/promises";
+import { constants as fsConstants } from "node:fs";
 import { dirname, join } from "node:path";
 import writeFileAtomic from "write-file-atomic";
 
 import { PRODUCT_IDENTITY } from "../identity.js";
+import {
+  NonRegularFileReadError,
+  openRegularFile,
+} from "../filesystem/RegularFile.js";
 import { clientSkillDirectories } from "./SupportedClients.js";
 
-const SKILL_FILES = [
+export const MANAGED_SKILL_FILES = [
   "SKILL.md",
   "references/native-and-artifacts.md",
   "references/javascript-applications.md",
@@ -14,6 +19,19 @@ const SKILL_FILES = [
   "references/evidence-workflows.md",
 ] as const;
 
+export const isManagedSkillManifest = (content: string): boolean =>
+  content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
+  content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
+
+export const readSkillFile = async (path: string): Promise<string> => {
+  const handle = await openRegularFile(path, { symlinks: "reject" });
+  try {
+    return await handle.readFile("utf8");
+  } finally {
+    await handle.close();
+  }
+};
+
 interface CanonicalSkillFile {
   readonly content: string;
   readonly destination: string;
@@ -47,9 +65,38 @@ export const skillDestinations = (
     }),
   );
 
+/** Resolve existing REA-owned skill roots using setup's canonical destinations. */
+export const existingSkillDestinations = async (
+  home: string,
+  environment: Readonly<NodeJS.ProcessEnv> = {},
+  platform: NodeJS.Platform = process.platform,
+): Promise<readonly SkillDestination[]> => {
+  const existing: SkillDestination[] = [];
+  for (const destination of skillDestinations(
+    home,
+    undefined,
+    environment,
+    platform,
+  )) {
+    try {
+      const root = await lstat(destination.path);
+      if (root.isSymbolicLink() || !root.isDirectory()) continue;
+      const manifest = join(destination.path, "SKILL.md");
+      const content = await readSkillFile(manifest);
+      if (isManagedSkillManifest(content)) existing.push(destination);
+    } catch (cause: unknown) {
+      if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
+        continue;
+      if (cause instanceof NonRegularFileReadError) continue;
+      throw cause;
+    }
+  }
+  return existing;
+};
+
 const readOptionalText = async (path: string): Promise<string | undefined> => {
   try {
-    return await readFile(path, "utf8");
+    return await readSkillFile(path);
   } catch (cause: unknown) {
     if (cause instanceof Error && "code" in cause && cause.code === "ENOENT")
       return undefined;
@@ -66,7 +113,7 @@ const canonicalSkillFiles = async (
   Promise.all(
     skillDestinations(home, clientIds, environment, platform).flatMap(
       ({ path: root }) =>
-        SKILL_FILES.map(async (relativePath) => {
+        MANAGED_SKILL_FILES.map(async (relativePath) => {
           const destination = join(root, relativePath);
           return {
             destination,
@@ -104,6 +151,19 @@ export const canonicalSkillNeedsInstall = async (
 const writeText = (path: string, content: string): Promise<void> =>
   writeFileAtomic(path, content, { encoding: "utf8", mode: 0o600 });
 
+const preserveSkillBackup = async (
+  source: string,
+  destination: string,
+): Promise<void> => {
+  try {
+    await copyFile(source, destination, fsConstants.COPYFILE_EXCL);
+  } catch (cause: unknown) {
+    if (cause instanceof Error && "code" in cause && cause.code === "EEXIST")
+      return;
+    throw cause;
+  }
+};
+
 const restoreSkillFiles = async (
   changed: readonly CanonicalSkillFile[],
 ): Promise<void> => {
@@ -134,7 +194,7 @@ export const installCanonicalSkill = async (
     for (const { destination, original } of changed) {
       await mkdir(dirname(destination), { recursive: true });
       if (original !== undefined)
-        await writeText(`${destination}.rea.backup`, original);
+        await preserveSkillBackup(destination, `${destination}.rea.backup`);
     }
     for (const { destination, content } of changed)
       await writeText(destination, content);

src/application/SetupTypes.ts

@@ -50,6 +50,8 @@ export interface SetupHost {
   linuxDistribution(): Promise<LinuxDistribution | undefined>;
   initialSetupState(scope?: DoctorScope): Promise<SetupInitialState>;
   installHopper(replaceExisting: boolean): Promise<SetupHopperInstallResult>;
+  /** Retry and report any cleanup resources still owned by this setup host. */
+  close?(): Promise<string | undefined>;
   detectedClients(): Promise<readonly SetupClient[]>;
   supportedClients(): Promise<readonly SetupClient[]>;
   configureClient(
@@ -155,6 +157,8 @@ export interface SetupOptions {
   readonly structured: boolean;
   readonly proposeHopper?: boolean;
   readonly clientIds?: readonly string[];
+  /** Skill roots to update independently of MCP registrations (maintenance). */
+  readonly skillClientIds?: readonly string[];
   readonly installSkill?: boolean;
   readonly readinessScope?: DoctorScope;
   readonly dryRun?: boolean;

src/application/Uninstall.ts

@@ -15,7 +15,12 @@ import writeFileAtomic from "write-file-atomic";
 import { z } from "zod";
 
 import { PRODUCT_IDENTITY } from "../identity.js";
-import { skillDestinations } from "./SetupSkill.js";
+import {
+  isManagedSkillManifest,
+  MANAGED_SKILL_FILES,
+  readSkillFile,
+  skillDestinations,
+} from "./SetupSkill.js";
 import { isOwnedClientRegistrationCommand } from "./ClientRegistrationIdentity.js";
 import { resolveClientConfigTransactionPath } from "./ClientConfigPath.js";
 import {
@@ -27,29 +32,32 @@ import {
 interface ManagedPathStats {
   readonly uid?: number;
   isFile?(): boolean;
+  isDirectory?(): boolean;
   isSymbolicLink(): boolean;
 }
 
 /** Injectable filesystem operations used to prove uninstall failure recovery. */
 export interface UninstallFileSystem {
   readText(path: string): Promise<string>;
+  readRegularText?(path: string): Promise<string>;
   /** Preserve the first backup; reject an existing destination with EEXIST. */
   copy(source: string, destination: string): Promise<void>;
   writeText(path: string, contents: string): Promise<void>;
   stat(path: string): Promise<ManagedPathStats>;
   realpath?(path: string): Promise<string>;
-  remove(path: string): Promise<void>;
+  remove(path: string, recursive?: boolean): Promise<void>;
 }
 
 const systemFileSystem: UninstallFileSystem = {
   readText: (path) => readFile(path, "utf8"),
+  readRegularText: readSkillFile,
   copy: (source, destination) =>
     copyFile(source, destination, fsConstants.COPYFILE_EXCL),
   writeText: (path, contents) =>
     writeFileAtomic(path, contents, { encoding: "utf8" }),
   stat: (path) => lstat(path),
   realpath: (path) => realpath(path),
-  remove: (path) => rm(path, { recursive: true }),
+  remove: (path, recursive = true) => rm(path, { recursive }),
 };
 
 /** One explicitly classified uninstall action. */
@@ -422,7 +430,7 @@ const removeManagedSkills = async (
   const results = await Promise.all(
     skillDestinations(home, undefined, environment, platform).map(
       ({ client, path }) =>
-        removeManagedPath(
+        removeManagedSkill(
           path,
           client === "claude_code" ? "Claude Code skill" : "skill",
           fileSystem,
@@ -457,6 +465,146 @@ const removeManagedSkills = async (
   );
 };
 
+const removeManagedSkill = async (
+  path: string,
+  name: string,
+  fileSystem: UninstallFileSystem,
+): Promise<UninstallItem> => {
+  let root: ManagedPathStats;
+  try {
+    root = await fileSystem.stat(path);
+  } catch (cause: unknown) {
+    return isMissing(cause)
+      ? item(name, "skipped", "Skill directory does not exist.")
+      : item(name, "failed", "Skill directory could not be inspected.");
+  }
+  if (root.isSymbolicLink())
+    return item(name, "retained", "Skill directory is a symbolic link.");
+  if (root.isDirectory?.() !== true)
+    return item(name, "retained", "Skill path is not a directory.");
+
+  const manifestPath = join(path, "SKILL.md");
+  try {
+    const manifest = await fileSystem.stat(manifestPath);
+    if (manifest.isSymbolicLink())
+      return item(name, "retained", "Skill manifest is a symbolic link.");
+    if (manifest.isFile?.() !== true)
+      return item(name, "retained", "Skill manifest is not a regular file.");
+  } catch (cause: unknown) {
+    return isMissing(cause)
+      ? item(name, "retained", "Skill ownership could not be established.")
+      : item(name, "failed", "Skill manifest could not be inspected.");
+  }
+  let content: string;
+  try {
+    content = await (fileSystem.readRegularText?.(manifestPath) ??
+      fileSystem.readText(manifestPath));
+  } catch (cause: unknown) {
+    return isMissing(cause)
+      ? item(name, "retained", "Skill ownership could not be established.")
+      : item(name, "failed", "Skill manifest could not be read.");
+  }
+  if (!isManagedSkillManifest(content))
+    return item(name, "retained", "Skill manifest is not REA-owned.");
+
+  const manifestName = "SKILL.md";
+  const otherFiles = MANAGED_SKILL_FILES.filter(
+    (relativePath) => relativePath !== manifestName,
+  );
+  const results: UninstallItem[] = [];
+  for (const relativePath of otherFiles)
+    results.push(
+      await removeManagedSkillFile(path, relativePath, name, fileSystem),
+    );
+  if (
+    results.some(({ status }) => status === "failed" || status === "retained")
+  )
+    results.push(
+      item(
+        name,
+        "retained",
+        "REA ownership manifest was retained because a managed file could not be safely removed.",
+      ),
+    );
+  else
+    results.push(
+      await removeManagedSkillFile(path, manifestName, name, fileSystem),
+    );
+  const failed = results.find(({ status }) => status === "failed");
+  if (failed !== undefined)
+    return item(name, "failed", results.map(({ detail }) => detail).join(" "));
+  const removed = results.some(({ status }) => status === "removed");
+  return item(
+    name,
+    removed ? "removed" : "skipped",
+    "REA-managed skill files were removed; other files were preserved.",
+  );
+};
+
+const removeManagedSkillFile = async (
+  root: string,
+  relativePath: string,
+  name: string,
+  fileSystem: UninstallFileSystem,
+): Promise<UninstallItem> => {
+  const segments = relativePath.split(/[\\/]/u);
+  let parent = root;
+  for (const segment of segments.slice(0, -1)) {
+    parent = join(parent, segment);
+    try {
+      const stats = await fileSystem.stat(parent);
+      if (stats.isSymbolicLink() || stats.isDirectory?.() !== true)
+        return item(
+          name,
+          "retained",
+          `Managed path parent was retained: ${parent}.`,
+        );
+    } catch (cause: unknown) {
+      return isMissing(cause)
+        ? item(
+            name,
+            "skipped",
+            `${join(parent, segments.at(-1) ?? "")} does not exist.`,
+          )
+        : item(
+            name,
+            "failed",
+            `Managed path parent could not be inspected: ${parent}.`,
+          );
+    }
+  }
+
+  const target = join(root, relativePath);
+  let stats: ManagedPathStats;
+  try {
+    stats = await fileSystem.stat(target);
+  } catch (cause: unknown) {
+    return isMissing(cause)
+      ? item(name, "skipped", `${target} does not exist.`)
+      : item(name, "failed", `Managed file could not be inspected: ${target}.`);
+  }
+  if (stats.isSymbolicLink())
+    return item(
+      name,
+      "retained",
+      `Managed file is a symbolic link: ${target}.`,
+    );
+  if (stats.isFile?.() !== true)
+    return item(
+      name,
+      "retained",
+      `Managed path is not a regular file: ${target}.`,
+    );
+  try {
+    await fileSystem.remove(target, false);
+    return item(name, "removed", `Removed ${target}.`);
+  } catch (cause: unknown) {
+    return isMissing(cause)
+      ? item(name, "skipped", `${target} does not exist.`)
+      : item(name, "failed", `Managed file could not be removed: ${target}.`);
+  }
+};
+
 const item = (
   name: string,
   status: UninstallItem["status"],

src/application/UpdateMaintenance.ts

@@ -1,5 +1,4 @@
 import { readFile } from "node:fs/promises";
-import { join } from "node:path";
 import { z } from "zod";
 
 import { PRODUCT_IDENTITY } from "../identity.js";
@@ -12,6 +11,7 @@ import {
   parseClientConfiguration,
 } from "./ClientConfigurationDocument.js";
 import { supportedClients } from "./SupportedClients.js";
+import { existingSkillDestinations } from "./SetupSkill.js";
 import type { SetupAction } from "./SetupTypes.js";
 import type { Result } from "../domain/result.js";
 
@@ -19,6 +19,10 @@ import type { Result } from "../domain/result.js";
 export interface MaintenanceScope {
   readonly clients: readonly string[];
   readonly skill: boolean;
+  readonly skillDestinations?: readonly {
+    readonly client: string;
+    readonly path: string;
+  }[];
 }
 
 /** Unapplied maintenance evidence produced by the updated setup executable. */
@@ -49,7 +53,7 @@ const setupPlanSchema = z.object({
   ),
 });
 
-/** Discover owned registrations and an existing REA skill without writes. */
+/** Discover owned registrations and REA skills without writes. */
 export const existingMaintenanceScope = async (
   home: string,
   entryPoint: string,
@@ -87,20 +91,12 @@ export const existingMaintenanceScope = async (
     )
       clients.push(client.name);
   }
-  let skill = false;
-  try {
-    const content = await readFile(
-      join(home, ".agents", "skills", PRODUCT_IDENTITY.skillName, "SKILL.md"),
-      "utf8",
-    );
-    skill =
-      content.startsWith(`---\nname: ${PRODUCT_IDENTITY.skillName}\n`) ||
-      content.startsWith(`---\r\nname: ${PRODUCT_IDENTITY.skillName}\r\n`);
-  } catch (cause: unknown) {
-    if (!(cause instanceof Error && "code" in cause && cause.code === "ENOENT"))
-      throw cause;
-  }
-  return { clients, skill };
+  const skillDestinations = await existingSkillDestinations(home, environment);
+  return {
+    clients,
+    skill: skillDestinations.length > 0,
+    skillDestinations,
+  };
 };
 
 /** Ask the verified new executable to plan only existing REA integrations. */
@@ -112,6 +108,7 @@ export const planIntegrationMaintenance = async (
 ): Promise<IntegrationMaintenance> => {
   try {
     const scope = await existingMaintenanceScope(home, entryPoint, environment);
+    const skillDestinations = scope.skillDestinations ?? [];
     if (scope.clients.length === 0 && !scope.skill)
       return { status: "current", plannedActions: [] };
     const command = [
@@ -119,6 +116,7 @@ export const planIntegrationMaintenance = async (
       entryPoint,
       "setup",
       ...scope.clients.flatMap((client) => ["--client", client]),
+      ...skillDestinations.flatMap(({ client }) => ["--skill-client", client]),
       `--skill=${String(scope.skill)}`,
     ];
     const execution = await execute([...command, "--dry-run", "--json"]);
@@ -132,11 +130,15 @@ export const planIntegrationMaintenance = async (
       };
     if (plan.data.plannedActions.length === 0)
       return { status: "current", plannedActions: [] };
-    const allowedIds = new Set([
-      ...scope.clients.map((client) => `configure_client:${client}`),
-      ...(scope.skill ? ["install_skill"] : []),
-    ]);
-    if (plan.data.plannedActions.some(({ id }) => !allowedIds.has(id)))
+    const allowedIds = new Set(scope.clients.map((client) => `configure_client:${client}`));
+    const skillTargets = new Set(skillDestinations.map(({ path }) => path));
+    if (
+      plan.data.plannedActions.some((action) =>
+        action.kind === "install_skill"
+          ? !skillTargets.has(action.target)
+          : !allowedIds.has(action.id),
+      )
+    )
       return {
         status: "unavailable",
         remediation:

src/cli/setupCommands.ts

@@ -39,6 +39,7 @@ const supportedClientSchema = z
     (candidate) => supportedClientIds.some((name) => name === candidate),
     "Unsupported agent integration",
   );
+const skillClientSchema = z.union([z.literal("shared"), supportedClientSchema]);
 
 /** Register setup, doctor, uninstall, and update CLI commands. */
 export const registerSetupCommands = (
@@ -72,6 +73,10 @@ const registerSetupCommand = (
         .array(supportedClientSchema)
         .default([])
         .describe("Agent integration to configure; repeat for multiple agents"),
+      skillClient: z
+        .array(skillClientSchema)
+        .default([])
+        .describe("Existing client skill destination to update; repeatable"),
       allDetected: z
         .boolean()
         .default(false)
@@ -186,6 +191,7 @@ interface SetupCommandOptions {
   readonly yes: boolean;
   readonly installHopper: boolean;
   readonly client: readonly string[];
+  readonly skillClient: readonly string[];
   readonly allDetected: boolean;
   readonly skill?: boolean | undefined;
   readonly dryRun: boolean;
@@ -224,8 +230,13 @@ const setupRunOptions = (
 ): SetupOptions => {
   const { options } = input;
   const agentIntegrationSelected =
-    options.allDetected || options.client.length > 0;
-  const hasSelectedClients = hasExplicitScope && !options.allDetected;
+    options.allDetected ||
+    options.client.length > 0 ||
+    options.skillClient.length > 0;
+  const hasSelectedClients =
+    hasExplicitScope &&
+    !options.allDetected &&
+    (options.client.length > 0 || options.skillClient.length > 0);
   return {
     approved: options.yes && !options.dryRun,
     installHopper: options.installHopper,
@@ -234,6 +245,9 @@ const setupRunOptions = (
     allDetectedClients: options.allDetected,
     proposeHopper: interactive || options.installHopper,
     ...(hasSelectedClients ? { clientIds: options.client } : {}),
+    ...(options.skillClient.length > 0
+      ? { skillClientIds: options.skillClient }
+      : {}),
     ...(hasExplicitScope
       ? { installSkill: options.skill ?? agentIntegrationSelected }
       : {}),
@@ -264,6 +278,7 @@ const setupIsInteractive = (
 const setupHasExplicitScope = (options: SetupCommandOptions): boolean =>
   options.allDetected ||
   options.client.length > 0 ||
+  options.skillClient.length > 0 ||
   options.skill !== undefined ||
   options.installHopper;