Skip to content

armgit / rea

Public Imported from GitHub
0

Reverse engineer anything with agents, from app behavior down to native binaries.

fix(hopper): recover provenance-verified Spotlight exits

morluto4acda94b7620
diff --git a/src/application/MacHopper.ts b/src/application/MacHopper.ts
index a211e9f2d..858e7fe48 100644
--- a/src/application/MacHopper.ts
+++ b/src/application/MacHopper.ts
@@ -15,6 +15,8 @@ import { promisify } from "node:util";
import { z } from "zod";
import { homeDirectoryFromEnvironment } from "../config/homeDirectory.js";
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
+import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js";
import {
downloadHopperPackage,
HOPPER_DOWNLOAD_BYTES,
@@ -24,29 +26,10 @@ 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/";
-
-/**
- * Apple publisher identity pinned for the official Hopper macOS bundle. The
- * team identifier was captured from `Hopper-6.6.0-demo.dmg` at
- * `https://www.hopperapp.com:443/downloader/public/Hopper-6.6.0-demo.dmg`
- * (34846271 bytes, SHA-1 0be530f038249742590992199c7b042ea20ca955) with
- * `codesign -dvvv`, which reported
- * `Authority=Developer ID Application: Cryptic Apps (2AMA2753NF)`.
- */
-export const HOPPER_PUBLISHER = Object.freeze({
- bundleIdentifier: "com.cryptic-apps.hopper-web-4",
- teamIdentifier: "2AMA2753NF",
-});
-
-/**
- * Code requirement enforcing the bundle identifier and signing team together.
- * The identifier is read from the sealed CodeDirectory, so it cannot be changed
- * by editing `Info.plist` the way the previous string comparison could.
- */
-const HOPPER_PUBLISHER_REQUIREMENT =
- `= identifier "${HOPPER_PUBLISHER.bundleIdentifier}"` +
- ` and anchor apple generic` +
- ` and certificate leaf[subject.OU] = "${HOPPER_PUBLISHER.teamIdentifier}"`;
+const HOPPER_PUBLISHER_REQUIREMENT = macDeveloperIdRequirement(
+ HOPPER_PUBLISHER.bundleIdentifier,
+ HOPPER_PUBLISHER.teamIdentifier,
+);
/** Outcome of reading a mounted bundle's signature and publisher identity. */
export type MacHopperBundleVerification =
diff --git a/src/application/SetupInstallFailure.test.ts b/src/application/SetupInstallFailure.test.ts
index 980e22151..d8ba27bdb 100644
--- a/src/application/SetupInstallFailure.test.ts
+++ b/src/application/SetupInstallFailure.test.ts
@@ -1,6 +1,6 @@
import { describe, expect, it } from "vitest";
-import { HOPPER_PUBLISHER } from "./MacHopper.js";
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
import { setupInstallFailure } from "./SetupInstallFailure.js";
describe("macOS Hopper setup failure projection", () => {
diff --git a/src/application/SetupInstallFailure.ts b/src/application/SetupInstallFailure.ts
index 0b332fa25..944a60343 100644
--- a/src/application/SetupInstallFailure.ts
+++ b/src/application/SetupInstallFailure.ts
@@ -1,4 +1,4 @@
-import { HOPPER_PUBLISHER } from "./MacHopper.js";
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
export type SetupFailureCode =
| "unsupported_host"
diff --git a/src/domain/hopperPublisher.ts b/src/domain/hopperPublisher.ts
new file mode 100644
index 000000000..6c212ea64
--- /dev/null
+++ b/src/domain/hopperPublisher.ts
@@ -0,0 +1,12 @@
+/**
+ * Apple publisher identity pinned for the official Hopper macOS bundle. The
+ * team identifier was captured from `Hopper-6.6.0-demo.dmg` at
+ * `https://www.hopperapp.com:443/downloader/public/Hopper-6.6.0-demo.dmg`
+ * (34846271 bytes, SHA-1 0be530f038249742590992199c7b042ea20ca955) with
+ * `codesign -dvvv`, which reported
+ * `Authority=Developer ID Application: Cryptic Apps (2AMA2753NF)`.
+ */
+export const HOPPER_PUBLISHER = Object.freeze({
+ bundleIdentifier: "com.cryptic-apps.hopper-web-4",
+ teamIdentifier: "2AMA2753NF",
+});
diff --git a/src/hopper/BridgeLauncher.ts b/src/hopper/BridgeLauncher.ts
index 043d394a4..3f83867bf 100644
--- a/src/hopper/BridgeLauncher.ts
+++ b/src/hopper/BridgeLauncher.ts
@@ -33,6 +33,7 @@ import {
} from "./HopperTargetLease.js";
import type { HopperTargetLease } from "./HopperTargetLease.js";
import { HOPPER_SHUTDOWN_TIMEOUT_MS } from "./HopperSessionValues.js";
+import { verifyMacHopperNativeHelper } from "./HopperMacPublisher.js";
const execFileAsync = promisify(execFile);
const HOPPER_BACKGROUND_STARTUP_MS = 5_000;
@@ -47,6 +48,8 @@ export interface BridgeSession {
/** Process handle returned by a bridge launcher. */
export type BridgeLaunch = {
+ /** Verified publisher and sealed native-helper identity; omission is unknown. */
+ readonly nativeHelperVerified?: true;
/** Only literal native-helper arguments support a pre-handoff denial conclusion. */
readonly authorizationDenialBeforeHandoff?: true;
/** Release application/target exclusivity only after verified document and process cleanup. */
@@ -106,6 +109,7 @@ export type HopperApplicationLauncherOptions =
});
export interface HopperApplicationLauncherDependencies {
+ readonly verifyNativeHelper?: typeof verifyMacHopperNativeHelper;
readonly platform?: NodeJS.Platform;
readonly acquireTargetLease?: typeof acquireHopperTargetLease;
readonly acquireApplicationLease?: typeof acquireLinuxHopperApplicationLease;
@@ -213,6 +217,13 @@ export class HopperApplicationLauncher implements BridgeLauncher {
if (signal?.aborted === true) return err(new HopperCancelledError());
const display = await this.#privateDisplay(signal);
if (!display.ok) return err(display.error);
+ const nativeHelperVerified =
+ (this.dependencies.platform ?? process.platform) === "darwin" &&
+ this.options.launchMode === "native" &&
+ (await (
+ this.dependencies.verifyNativeHelper ?? verifyMacHopperNativeHelper
+ )(this.options.launcherPath, this.options.environment, signal)) ===
+ "verified";
const prepared = await prepareHopperApplication(
this.options.launcherPath,
this.options.environment,
@@ -257,6 +268,9 @@ export class HopperApplicationLauncher implements BridgeLauncher {
...ownedLauncher,
providerLifetime: "external-application",
shutdownMode: "bridge-request",
+ ...(nativeHelperVerified
+ ? { nativeHelperVerified: true as const }
+ : {}),
// The vendor helper interpolates these values into AppleScript
// literals without escaping. Preserve them, but withhold the
// pre-handoff conclusion when they can alter that script.
diff --git a/src/hopper/HopperClient.ts b/src/hopper/HopperClient.ts
index 8af42774c..2943839f4 100644
--- a/src/hopper/HopperClient.ts
+++ b/src/hopper/HopperClient.ts
@@ -770,6 +770,10 @@ export class HopperClient {
});
}
if (hopperLauncherReportedApplicationNotFound(launcherFailure)) {
+ // Only the verified native helper's Spotlight exit precedes any target
+ // handoff. Wrappers can forward the same message after opening a document.
+ if (this.#resources.launch?.nativeHelperVerified === true)
+ this.#resources.shutdownConfirmed = true;
return new HopperStartError({
userMessage:
"Hopper's launcher could not find Hopper because it relies on Spotlight. Enable Spotlight indexing for the volume that contains Hopper (for example: sudo mdutil -i on /System/Volumes/Data), wait for indexing to finish, then retry opening the target.",
diff --git a/src/hopper/HopperMacPublisher.ts b/src/hopper/HopperMacPublisher.ts
new file mode 100644
index 000000000..f60852915
--- /dev/null
+++ b/src/hopper/HopperMacPublisher.ts
@@ -0,0 +1,36 @@
+import { HOPPER_PUBLISHER } from "../domain/hopperPublisher.js";
+import { macDeveloperIdRequirement } from "../process/MacCodeSignature.js";
+import { execFileOutput } from "../process/ExecFileOutput.js";
+
+/** Failure or unavailable verification leaves custom/native provenance unknown. */
+export const verifyMacHopperNativeHelper = async (
+ launcherPath: string,
+ environment: Readonly<NodeJS.ProcessEnv>,
+ signal?: AbortSignal,
+): Promise<"verified" | "unknown"> => {
+ // codesign treats a bare name as a local file, while spawn searches PATH.
+ // Without an explicit path they need not identify the same executable.
+ if (!launcherPath.includes("/")) return "unknown";
+ try {
+ await execFileOutput(
+ "/usr/bin/codesign",
+ [
+ "--verify",
+ "--strict",
+ `-R${macDeveloperIdRequirement("hopper", HOPPER_PUBLISHER.teamIdentifier)}`,
+ launcherPath,
+ ],
+ {
+ env: environment,
+ ...(signal === undefined ? {} : { signal }),
+ timeout: 5_000,
+ stopSignal: "SIGKILL",
+ },
+ );
+ return "verified";
+ } catch (cause: unknown) {
+ // Optional provenance: a failed check must never authorize lease release.
+ void cause;
+ return "unknown";
+ }
+};
diff --git a/src/process/MacCodeSignature.ts b/src/process/MacCodeSignature.ts
new file mode 100644
index 000000000..92cd7f86f
--- /dev/null
+++ b/src/process/MacCodeSignature.ts
@@ -0,0 +1,7 @@
+/** Require a sealed identifier and Apple Developer ID signing team together. */
+export const macDeveloperIdRequirement = (
+ identifier: string,
+ teamIdentifier: string,
+): string =>
+ `= identifier "${identifier}" and anchor apple generic` +
+ ` and certificate leaf[subject.OU] = "${teamIdentifier}"`;
diff --git a/tests/acceptance/providers/hopperStartupRecovery.test.ts b/tests/acceptance/providers/hopperStartupRecovery.test.ts
index 65882a86b..842fdaa07 100644
--- a/tests/acceptance/providers/hopperStartupRecovery.test.ts
+++ b/tests/acceptance/providers/hopperStartupRecovery.test.ts
@@ -50,7 +50,42 @@ test(
});
const mcp = new Client({ name: "hopper-literal-boundary", version: "1" });
let runtime: string | undefined;
- onTestFinished(async () => {
+ try {
+ await mcp.connect(transport);
+ const call = (name: string, arguments_: Record<string, string> = {}) =>
+ mcp.callTool({ name, arguments: arguments_ });
+ expect((await call("open_binary", { path: target })).isError).not.toBe(
+ true,
+ );
+ const first = parseMcpToolError(await call("current_document"));
+ runtime = dirname(await readFile(receipt, "utf8"));
+ expect(first.error).toMatchObject({
+ code: "cleanup_incomplete",
+ details: {
+ diagnostics: {
+ primary_error: {
+ code: "provider_unavailable",
+ details: {
+ launcher: {
+ exit_code: 2,
+ stderr: {
+ text: expect.stringContaining(
+ "Not authorized to send Apple events",
+ ),
+ },
+ },
+ },
+ },
+ },
+ },
+ });
+ await access(`${receipt}.document-created`);
+ await access(runtime);
+ expect(parseMcpToolError(await call("list_procedures"))).toEqual(first);
+ expect(parseMcpToolError(await call("close_binary")).error.code).toBe(
+ "cleanup_incomplete",
+ );
+ } finally {
// SDK close can return immediately after SIGKILL. Wait for its actual
// child-close event before recovering this process's retained lease.
let serverExited: Promise<void> | undefined;
@@ -77,41 +112,7 @@ test(
});
if (!acquired.acquired) throw new Error("Fixture lease remained live");
await acquired.lease.release();
- });
- await mcp.connect(transport);
- const call = (name: string, arguments_: Record<string, string> = {}) =>
- mcp.callTool({ name, arguments: arguments_ });
- expect((await call("open_binary", { path: target })).isError).not.toBe(
- true,
- );
- const first = parseMcpToolError(await call("current_document"));
- runtime = dirname(await readFile(receipt, "utf8"));
- expect(first.error).toMatchObject({
- code: "cleanup_incomplete",
- details: {
- diagnostics: {
- primary_error: {
- code: "provider_unavailable",
- details: {
- launcher: {
- exit_code: 2,
- stderr: {
- text: expect.stringContaining(
- "Not authorized to send Apple events",
- ),
- },
- },
- },
- },
- },
- },
- });
- await access(`${receipt}.document-created`);
- await access(runtime);
- expect(parseMcpToolError(await call("list_procedures"))).toEqual(first);
- expect(parseMcpToolError(await call("close_binary")).error.code).toBe(
- "cleanup_incomplete",
- );
+ }
}
},
);
@@ -201,7 +202,7 @@ test("recovers a denied Hopper launch through the same stdio MCP session and CLI
).toBe(false);
});
-test.each(["handoff", "not-found"] as const)(
+test.for(["handoff", "not-found"] as const)(
"preserves an unconfirmed %s handoff and closes only a late bridge with matching run identity",
{ timeout: 60_000 },
async (launchMode, { workspace }) => {
@@ -269,17 +270,21 @@ test.each(["handoff", "not-found"] as const)(
},
},
});
- if (launchMode === "not-found")
+ if (launchMode === "not-found") {
+ await access(`${receipt}.document-created`);
expect(initial.error.details).toMatchObject({
diagnostics: {
primary_error: { message: expect.stringContaining("Spotlight") },
},
});
+ }
expect(parseMcpToolError(await call("list_procedures"))).toEqual(initial);
const status = z.object({
result: z.object({
provider_operation_health: z.object({
- state: z.literal("not_started"),
+ state: z.literal(
+ launchMode === "handoff" ? "not_started" : "unknown",
+ ),
stage: z.literal("launch"),
}),
}),
diff --git a/tests/boundary/cli/hopperLaunchFailureCli.test.ts b/tests/boundary/cli/hopperLaunchFailureCli.test.ts
index 476f58f6b..9a4f55b7c 100644
--- a/tests/boundary/cli/hopperLaunchFailureCli.test.ts
+++ b/tests/boundary/cli/hopperLaunchFailureCli.test.ts
@@ -1,6 +1,6 @@
import { chmod, copyFile, rm } from "node:fs/promises";
-import { describe, expect, onTestFinished } from "vitest";
+import { describe, expect } from "vitest";
import { z } from "zod";
import { workspaceCliTest } from "../../support/cli/workspaceCliFixture.js";
@@ -39,7 +39,57 @@ describe("Hopper launcher failure through the one-shot CLI", () => {
const targetPath = workspace.path("probe");
await copyFile("/usr/bin/true", targetPath);
const loaderArgs = ["--probe"];
- onTestFinished(async () => {
+ try {
+ for (const attempt of ["first", "retry"]) {
+ const result = await cli.run({
+ arguments: [
+ "analyze",
+ targetPath,
+ "--provider",
+ "hopper",
+ "--json",
+ ],
+ environment: {
+ ...workspace.environment,
+ HOPPER_LAUNCHER_PATH: launcherPath,
+ HOPPER_LOADER_ARGS_JSON: JSON.stringify(loaderArgs),
+ REA_LOG_LEVEL: "silent",
+ },
+ timeoutMs: 45_000,
+ });
+ const retained = RetainedRuntime.safeParse(result.json);
+ if (retained.success)
+ await rm(
+ retained.data.details.diagnostics.cleanup_error.details
+ .diagnostics.runtime_root,
+ { recursive: true, force: true },
+ );
+
+ expect(result.exitCode, attempt).toBe(1);
+ expect(result.json, attempt).toMatchObject({
+ code: "cleanup_incomplete",
+ details: {
+ cleanup: "incomplete",
+ diagnostics: {
+ primary_error: {
+ code: "provider_unavailable",
+ details: {
+ stage: "launch",
+ launcher: {
+ exit_code: 2,
+ stderr: {
+ text: expect.stringContaining(
+ "Document state is unknown",
+ ),
+ },
+ },
+ },
+ },
+ },
+ },
+ });
+ }
+ } finally {
const recovered = await acquireHopperTargetLease({
targetPath,
targetKind: "executable",
@@ -48,50 +98,6 @@ describe("Hopper launcher failure through the one-shot CLI", () => {
});
expect(recovered.acquired).toBe(true);
if (recovered.acquired) await recovered.lease.release();
- });
-
- for (const attempt of ["first", "retry"]) {
- const result = await cli.run({
- arguments: ["analyze", targetPath, "--provider", "hopper", "--json"],
- environment: {
- ...workspace.environment,
- HOPPER_LAUNCHER_PATH: launcherPath,
- HOPPER_LOADER_ARGS_JSON: JSON.stringify(loaderArgs),
- REA_LOG_LEVEL: "silent",
- },
- timeoutMs: 45_000,
- });
- const retained = RetainedRuntime.safeParse(result.json);
- if (retained.success)
- await rm(
- retained.data.details.diagnostics.cleanup_error.details.diagnostics
- .runtime_root,
- { recursive: true, force: true },
- );
-
- expect(result.exitCode, attempt).toBe(1);
- expect(result.json, attempt).toMatchObject({
- code: "cleanup_incomplete",
- details: {
- cleanup: "incomplete",
- diagnostics: {
- primary_error: {
- code: "provider_unavailable",
- details: {
- stage: "launch",
- launcher: {
- exit_code: 2,
- stderr: {
- text: expect.stringContaining(
- "Document state is unknown",
- ),
- },
- },
- },
- },
- },
- },
- });
}
},
);
diff --git a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts
index 06e725dc1..b236b21eb 100644
--- a/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts
+++ b/tests/boundary/providers/hopper/hopperClient.helperFailure.test.ts
@@ -15,6 +15,7 @@ import type {
} from "../../../../src/hopper/BridgeLauncher.js";
import { HopperApplicationLauncher } from "../../../../src/hopper/BridgeLauncher.js";
import { HopperClient } from "../../../../src/hopper/HopperClient.js";
+import { acquireHopperTargetLease } from "../../../../src/hopper/HopperTargetLease.js";
import { HopperFixtureLauncher } from "./hopperClient.fixture.js";
// Failure assertions keep the external document unknown. Teardown then publishes
@@ -118,6 +119,86 @@ it("does not equate an owned native helper exit with an external GUI exit", asyn
});
});
+it.skipIf(process.platform !== "darwin")(
+ "releases the runtime and target lease after a provenance-verified Spotlight exit, then retries",
+ async () => {
+ const directory = await createTestTempDirectory(
+ "rea-hopper-native-not-found-",
+ );
+ const targetPath = join(directory, "target");
+ await writeFile(targetPath, "fixture target");
+ const loaderArgs = [
+ "-e",
+ 'process.stderr.write("Hopper has not been found.\\nPlease make sure that Spotlight is active in order for this tool to find Hopper\'s executable.\\n", () => process.exit(3))',
+ "--",
+ ];
+ // Simulate a verified native helper at the launcher provenance boundary;
+ // publisher verification itself has real codesign boundary coverage.
+ const native = new HopperApplicationLauncher(
+ {
+ environment: {},
+ launcherPath: process.execPath,
+ targetPath,
+ targetKind: "executable",
+ loaderArgs,
+ bridgeScriptPath: "/rea/hopper_bridge.py",
+ launchMode: "native",
+ },
+ { verifyNativeHelper: async () => "verified" },
+ );
+ const retry = new HopperFixtureLauncher();
+ let session: BridgeSession | undefined;
+ const client = new HopperClient({
+ launcher: {
+ async launch(input, options) {
+ if (session !== undefined) return retry.launch(input);
+ session = input;
+ const launched = await native.launch(input, options);
+ expect(launched).toMatchObject({
+ ok: true,
+ value: { nativeHelperVerified: true },
+ });
+ return launched;
+ },
+ },
+ startupTimeoutMs: 10_000,
+ });
+ onTestFinished(async () => {
+ const closed = await client.close();
+ if (!closed.ok) throw closed.error;
+ });
+ const failed = await client.start();
+ expect(failed).toMatchObject({
+ ok: false,
+ error: { _tag: "HopperStartError", cleanupIncomplete: false },
+ });
+ if (failed.ok) throw new Error("Expected Spotlight failure");
+ expect(projectAnalysisError(failed.error)).toMatchObject({
+ code: "provider_unavailable",
+ message: expect.stringContaining("Spotlight"),
+ details: { launcher: { exit_code: 3 } },
+ });
+ if (session === undefined) throw new Error("Missing launch session");
+ await expect(access(session.directory)).rejects.toMatchObject({
+ code: "ENOENT",
+ });
+ const lease = await acquireHopperTargetLease({
+ targetPath,
+ targetKind: "executable",
+ loaderArgs,
+ runId: "spotlight-retry-proof",
+ });
+ if (!lease.acquired)
+ throw new Error("Spotlight failure retained the target lease");
+ await lease.lease.release();
+ expect(await client.start()).toMatchObject({ ok: true });
+ expect(await client.callTool("echo", { value: "retried" })).toEqual({
+ ok: true,
+ value: { value: "retried" },
+ });
+ },
+);
+
it.each(["exit", "signal", "exit75"] as const)(
"reports a failed non-owning launcher %s without waiting for bridge timeout or inventing a GUI exit",
async (termination) => {
diff --git a/tests/boundary/setup/macosHopperPublisherVerification.test.ts b/tests/boundary/setup/macosHopperPublisherVerification.test.ts
index 29b696e85..dcb85cca5 100644
--- a/tests/boundary/setup/macosHopperPublisherVerification.test.ts
+++ b/tests/boundary/setup/macosHopperPublisherVerification.test.ts
@@ -6,10 +6,11 @@ import { promisify } from "node:util";
import { describe, expect, it } from "vitest";
import {
- HOPPER_PUBLISHER,
macHopperInstallDisclosure,
systemMacHopperInstallHost,
} from "../../../src/application/MacHopper.js";
+import { verifyMacHopperNativeHelper } from "../../../src/hopper/HopperMacPublisher.js";
+import { HOPPER_PUBLISHER } from "../../../src/domain/hopperPublisher.js";
import { createTestTempDirectory } from "../../fixtures/temporaryDirectory.js";
const run = promisify(execFile);
@@ -94,6 +95,24 @@ describe("macOS Hopper publisher verification", () => {
);
});
+ itDarwin(
+ "withholds native-helper provenance from custom signed or modified executables",
+ async () => {
+ const root = await createTestTempDirectory(
+ "rea-hopper-helper-publisher-",
+ );
+ const app = await buildBundle(root, "hopper");
+ const executable = join(app, ...executableSegments);
+ await expect(
+ verifyMacHopperNativeHelper(executable, process.env),
+ ).resolves.toBe("unknown");
+ await appendFile(executable, "modified\n");
+ await expect(
+ verifyMacHopperNativeHelper(executable, process.env),
+ ).resolves.toBe("unknown");
+ },
+ );
+
// Opt-in positive control: point this at a mounted official Hopper bundle,
// for example `hdiutil attach -readonly -nobrowse Hopper-6.6.0-demo.dmg`.
// It proves the pinned requirement is satisfiable by the real publisher, so
@@ -103,6 +122,12 @@ describe("macOS Hopper publisher verification", () => {
"accepts the officially signed Hopper application",
async () => {
await expect(host().validBundle(realApp ?? "")).resolves.toBe("verified");
+ await expect(
+ verifyMacHopperNativeHelper(
+ join(realApp ?? "", ...executableSegments),
+ process.env,
+ ),
+ ).resolves.toBe("verified");
},
);
});
diff --git a/tests/fixtures/hopperLaunchAdmission.mjs b/tests/fixtures/hopperLaunchAdmission.mjs
index bb80ad448..6a5033d6b 100644
--- a/tests/fixtures/hopperLaunchAdmission.mjs
+++ b/tests/fixtures/hopperLaunchAdmission.mjs
@@ -20,7 +20,8 @@ if (mode === "denied" || mode === "denied-after-handoff") {
},
);
} else if (mode === "not-found") {
- // The native helper's Spotlight lookup fails before any Apple event.
+ // A custom wrapper can forward the native diagnostic after a handoff.
+ await writeFile(`${receiptPath}.document-created`, "unconfirmed");
process.stderr.write(
"Hopper has not been found.\nPlease make sure that Spotlight is active in order for this tool to find Hopper's executable.\n",
() => process.exit(3),