movehat 0.2.0 → 0.2.2

package/src/fork/server.ts

@@ -2,6 +2,19 @@ import http from 'http';
 import { URL } from 'url';
 import { ForkManager } from './manager.js';
 
+export interface ForkServerOptions {
+  /**
+   * Origins allowed to make cross-origin requests. When unset (default),
+   * no `Access-Control-Allow-Origin` header is emitted — any browser
+   * cross-origin read is rejected by the user agent. Setting this to a
+   * non-empty list opts into echoing matching `Origin` request headers
+   * back. Wildcard `'*'` is intentionally NOT supported: cached fork
+   * state may include resources that should not be readable by every
+   * page in the dev's browser.
+   */
+  corsAllowOrigins?: readonly string[];
+}
+
 /**
  * Fork Server - Serves fork data via Movement L1 RPC API
  * Emulates a Movement L1 node using local fork storage
@@ -11,16 +24,38 @@ export class ForkServer {
   private forkManager: ForkManager;
   private port: number;
   private host: string;
+  private readonly corsAllowOrigins: ReadonlySet<string>;
 
   /**
    * @param host Interface to bind. Defaults to `127.0.0.1` so cached fork
    *   state (which may include sensitive resources) is not exposed on the LAN.
    *   Pass `'0.0.0.0'` only if you intentionally need to expose the server.
+   * @param options Optional CORS allowlist (see {@link ForkServerOptions}).
    */
-  constructor(forkPath: string, port: number = 8080, host: string = '127.0.0.1') {
+  constructor(
+    forkPath: string,
+    port: number = 8080,
+    host: string = '127.0.0.1',
+    options: ForkServerOptions = {}
+  ) {
     this.forkManager = new ForkManager(forkPath);
     this.port = port;
     this.host = host;
+    this.corsAllowOrigins = new Set(options.corsAllowOrigins ?? []);
+  }
+
+  /**
+   * Set CORS headers for a request when the request's `Origin` is in
+   * the allowlist. No-op otherwise.
+   */
+  private applyCors(req: http.IncomingMessage, res: http.ServerResponse): void {
+    const origin = req.headers.origin;
+    if (typeof origin === 'string' && this.corsAllowOrigins.has(origin)) {
+      res.setHeader('Access-Control-Allow-Origin', origin);
+      res.setHeader('Vary', 'Origin');
+      res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+      res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    }
   }
 
   /**
@@ -44,10 +79,7 @@ export class ForkServer {
 
         // Only send response if headers haven't been sent yet
         if (!res.headersSent) {
-          // Add CORS headers (same as in handleRequest)
-          res.setHeader('Access-Control-Allow-Origin', '*');
-          res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-          res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+          this.applyCors(req, res);
 
           // Send generic error response (no internal details exposed)
           this.sendJSON(res, 500, {
@@ -143,10 +175,7 @@ export class ForkServer {
     // Log request
     console.log(`[${new Date().toISOString()}] ${req.method} ${pathname}`);
 
-    // CORS headers
-    res.setHeader('Access-Control-Allow-Origin', '*');
-    res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
-    res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+    this.applyCors(req, res);
 
     // Handle OPTIONS for CORS preflight
     if (req.method === 'OPTIONS') {

package/src/fork/test.ts

@@ -9,7 +9,6 @@ export interface SnapshotOptions {
   /**
    * Override the child-process adapter. Test-only — production callers
    * leave this undefined so the default spawn-based adapter is used.
-   * Mirrors the M1.3c pattern on `runtime.deployContract`.
    */
   adapter?: ChildProcessAdapter;
 }

package/src/harness/Harness.ts

@@ -36,16 +36,10 @@ interface HarnessInit {
  * a Proxy that synchronously throws {@link HarnessDisposedError} on any
  * post-`cleanup()` call to one of the deployment / script / view methods.
  *
- * Methods `deployCodeObject`, `upgradeCodeObject`, `runViewFunction`,
- * and `runMoveScript` are stubbed in M2.1 — they throw at runtime until
- * M2.2/M2.3 lands. The type surface is complete so callers and docs can
- * be written against it ahead of time.
- *
- * AccountManager note: as of M2.1 the underlying account pool is a
- * process-wide static (see `core/AccountManager.ts`). Two Harness
- * instances in the same process share account labels; this is the same
- * constraint that already governs `setupTestFixture`. A per-Harness pool
- * is a future change.
+ * AccountManager note: the underlying account pool is a process-wide
+ * static (see `core/AccountManager.ts`). Two Harness instances in the
+ * same process share account labels; this is the same constraint that
+ * already governs `setupTestFixture`.
  */
 export class Harness {
   public readonly mode: HarnessMode;
@@ -98,19 +92,28 @@ export class Harness {
    * and `runMoveScript` throw with a message pointing at `createLocal`.
    * `runViewFunction` works (read-only path).
    *
-   * @param network - Network to fork (e.g. `"testnet"`).
+   * @param network - Network to fork. Built-ins: `"testnet"`, `"mainnet"`.
+   *   Any other name requires `rpcUrl`.
    * @param apiKey - Optional Movement API key. When set, every upstream
    *   request from the fork's `MovementApiClient` carries
    *   `Authorization: Bearer <apiKey>`. Use for rate-limited public
    *   endpoints or auth-gated nodes. The key stays in process memory
    *   (not persisted to the fork's on-disk metadata).
+   * @param rpcUrl - Required when forking a non-built-in network.
+   *   Ignored when a fork already exists on disk (the saved metadata's
+   *   nodeUrl is reused).
    */
-  static async createFork(network: string, apiKey?: string): Promise<Harness> {
+  static async createFork(
+    network: string,
+    apiKey?: string,
+    rpcUrl?: string
+  ): Promise<Harness> {
     const setupOpts: import("../types/config.js").LocalTestOptions = {
       mode: "fork",
       forkNetwork: network,
     };
     if (apiKey !== undefined) setupOpts.forkApiKey = apiKey;
+    if (rpcUrl !== undefined) setupOpts.forkRpcUrl = rpcUrl;
     const ctx = await setupLocalTesting(setupOpts);
     const init: HarnessInit = {
       mode: "fork",
@@ -128,7 +131,7 @@ export class Harness {
    * spawned; transactions are submitted to the configured RPC.
    *
    * @param network - Named network from movehat.config.ts.
-   * @param _faucetUrl - Reserved for M2.2 (auto-fund on networks with a faucet).
+   * @param _faucetUrl - Reserved for future auto-fund support on networks with a faucet.
    */
   static async createLive(network: string, _faucetUrl?: string): Promise<Harness> {
     const runtime = await initRuntime({ network });

package/src/harness/codeObject.ts

@@ -1,6 +1,4 @@
-import { homedir } from "os";
-import { join } from "path";
-import { randomUUID } from "crypto";
+import { PrivateKey, PrivateKeyVariants } from "@aptos-labs/ts-sdk";
 import type { MovehatRuntime } from "../types/runtime.js";
 import type {
   DeployCodeObjectOptions,
@@ -14,7 +12,7 @@ import {
   validateSafeName,
   type DeploymentInfo,
 } from "../core/deployments.js";
-import { validatePathSafety, validateProfileSafety } from "../core/shell.js";
+import { validatePathSafety } from "../core/shell.js";
 import {
   CliExecutionError,
   ModuleAlreadyDeployedError,
@@ -24,10 +22,9 @@ import { runCli } from "../utils/runCli.js";
 import { parseTxHash } from "../utils/parseCliOutput.js";
 import { logger } from "../ui/index.js";
 import {
-  withYamlLock,
-  addProfile,
-  removeProfile,
-  removeProfileSync,
+  writeTempKeyFile,
+  removeKeyFile,
+  removeKeyFileSyncBestEffort,
   ensureSignalHandler,
   cleanupCallbacks,
 } from "../core/movementProfile.js";
@@ -170,9 +167,7 @@ async function executeMovementMoveObject(
   }
 
   const dir = opts.packageDir || config.moveDir;
-  const profile = `movehat-deploy-${randomUUID().slice(0, 8)}`;
   const safeDir = validatePathSafety(dir, "package directory");
-  const safeProfile = validateProfileSafety(profile);
 
   logger.step(
     `${subcommand === "deploy-object" ? "Deploying" : "Upgrading"} module "${moduleName}" from ${dir}...`
@@ -213,30 +208,28 @@ async function executeMovementMoveObject(
     );
     if (buildResult.stdout) console.log(buildResult.stdout.trim());
 
-    // Strip `ed25519-priv-` prefix if present — Movement CLI expects the
-    // raw hex.
-    let cleanPrivateKey = config.privateKey;
-    if (cleanPrivateKey.startsWith("ed25519-priv-")) {
-      cleanPrivateKey = cleanPrivateKey.replace("ed25519-priv-", "");
-    }
+    // Format the private key into AIP-80 shape so the Movement CLI
+    // doesn't emit its raw-hex deprecation warning. `formatPrivateKey`
+    // is idempotent for already-prefixed inputs.
+    const formattedPrivateKey = PrivateKey.formatPrivateKey(
+      config.privateKey,
+      PrivateKeyVariants.Ed25519,
+    );
 
-    const movementConfigPath = join(homedir(), ".aptos", "config.yaml");
+    // Pass the private key via a 0o600 temp file (--private-key-file)
+    // and the on-chain address via --sender-account. This avoids the
+    // CLI's profile-yaml lookup entirely — no CWD / HOME / .aptos /
+    // .movement dance, no CLI-variant dependency.
+    const keyFilePath = writeTempKeyFile(formattedPrivateKey);
 
-    // Register SIGINT-safe sync cleanup BEFORE writing the key (same
-    // pattern as Publisher — closes bug #36).
+    // Register SIGINT-safe sync cleanup BEFORE invoking the CLI so
+    // the private key never persists on disk after an abnormal exit.
+    // The signal-handler path uses the best-effort variant because the
+    // event loop is dead and we cannot logger.warning.
     ensureSignalHandler();
-    const syncCleanup = () => removeProfileSync(movementConfigPath, profile);
+    const syncCleanup = () => removeKeyFileSyncBestEffort(keyFilePath);
     cleanupCallbacks.add(syncCleanup);
 
-    await withYamlLock(() =>
-      addProfile(movementConfigPath, profile, {
-        private_key: cleanPrivateKey,
-        public_key: account.publicKey.toString(),
-        account: deployerAddress,
-        rest_url: config.rpc,
-      })
-    );
-
     let deployOut = "";
     try {
       logger.step(
@@ -258,8 +251,10 @@ async function executeMovementMoveObject(
             safeDir,
             "--url",
             config.rpc,
-            "--profile",
-            safeProfile,
+            "--private-key-file",
+            keyFilePath,
+            "--sender-account",
+            deployerAddress,
             "--assume-yes",
             ...includedArtifacts,
             ...namedAddrArgs,
@@ -273,24 +268,21 @@ async function executeMovementMoveObject(
       if (result.stdout) console.log(result.stdout.trim());
       if (result.stderr) console.error(result.stderr.trim());
     } finally {
-      // Best-effort profile removal. CRITICAL: catch + log instead of
-      // re-throwing — an await-in-finally that throws would clobber the
-      // try block's success/error (the bug-#37 lesson from Publisher).
-      await withYamlLock(() => removeProfile(movementConfigPath, profile)).catch(
-        (err) => {
-          const cleanupMsg = err instanceof Error ? err.message : String(err);
-          logger.warning(
-            `Failed to remove deploy profile "${profile}" from ${movementConfigPath}: ${cleanupMsg}. ` +
-              `Run 'movement config delete-profile --profile ${profile}' to clean up manually.`
-          );
-        }
-      );
+      // Unlink via the observable helper — emit a warning if the file
+      // could not be removed AND still exists on disk (private key
+      // would persist silently otherwise). ENOENT and races are
+      // treated as benign success.
+      const cleanupErr = removeKeyFile(keyFilePath);
+      if (cleanupErr) {
+        logger.warning(
+          `Failed to remove temp key file '${keyFilePath}': ${cleanupErr.message}. ` +
+            `The file has mode 0o600 but should be removed manually: rm ${keyFilePath}`
+        );
+      }
       cleanupCallbacks.delete(syncCleanup);
     }
 
     // Parse object address (for deploy-object) and txHash (both flows).
-    // No captured fixture exists at M2.2 commit time; M4 integration
-    // tests validate against real CLI output.
     const objectAddress = opts.fixedAddress ?? parseObjectAddress(deployOut);
     const txHash = parseTxHash(deployOut);
 
@@ -361,9 +353,7 @@ async function executeMovementMoveObject(
 /**
  * Extract a code-object address from `movement move deploy-object` stdout.
  *
- * Movement CLI typically emits the address in one of these shapes (none
- * of them captured at M2.2 commit time — patterns are speculative, with
- * M4 integration tests as the validation gate):
+ * Movement CLI typically emits the address in one of these shapes:
  *
  *   - Free text: `Code was successfully deployed to object address 0x…`
  *   - Free text: `Object address: 0x…`

package/src/harness/script.ts

@@ -1,22 +1,20 @@
 import { existsSync } from "fs";
-import { homedir } from "os";
-import { extname, join } from "path";
-import { randomUUID } from "crypto";
+import { extname } from "path";
+import { PrivateKey, PrivateKeyVariants } from "@aptos-labs/ts-sdk";
 import type { MovehatRuntime } from "../types/runtime.js";
 import type {
   RunMoveScriptOptions,
   MoveScriptResult,
 } from "../types/harness.js";
-import { validatePathSafety, validateProfileSafety } from "../core/shell.js";
+import { validatePathSafety } from "../core/shell.js";
 import { CliExecutionError } from "../errors.js";
 import { runCli } from "../utils/runCli.js";
 import { parseTxHash } from "../utils/parseCliOutput.js";
 import { logger } from "../ui/index.js";
 import {
-  withYamlLock,
-  addProfile,
-  removeProfile,
-  removeProfileSync,
+  writeTempKeyFile,
+  removeKeyFile,
+  removeKeyFileSyncBestEffort,
   ensureSignalHandler,
   cleanupCallbacks,
 } from "../core/movementProfile.js";
@@ -29,9 +27,9 @@ import {
  *   - `.mv` compiled bytecode → `--compiled-script-path`
  *
  * Reuses Publisher's security model via the shared `movementProfile`
- * helpers: per-deploy unique profile, atomic 0o600 yaml writes under
- * the mutex, SIGINT-safe sync cleanup, `--profile` auth (key never
- * appears in `ps` output).
+ * helpers: per-invocation temp key file (0o600), SIGINT-safe sync
+ * cleanup, `--private-key-file` auth (key never appears in `ps`
+ * output or in the user's `~/.aptos/config.yaml`).
  *
  * Returns {@link MoveScriptResult}. `txHash` is guaranteed; `success`
  * and `vmStatus` are best-effort parsed from the CLI's Result JSON.
@@ -70,8 +68,6 @@ export async function runMoveScript(
   }
 
   const safeScriptPath = validatePathSafety(options.scriptPath, "script path");
-  const profile = `movehat-script-${randomUUID().slice(0, 8)}`;
-  const safeProfile = validateProfileSafety(profile);
 
   logger.step(
     `Running Move script '${options.scriptPath}' on ${config.network}...`
@@ -80,26 +76,28 @@ export async function runMoveScript(
   try {
     const deployerAddress = account.accountAddress.toString();
 
-    let cleanPrivateKey = config.privateKey;
-    if (cleanPrivateKey.startsWith("ed25519-priv-")) {
-      cleanPrivateKey = cleanPrivateKey.replace("ed25519-priv-", "");
-    }
+    // Format the private key into AIP-80 shape before writing to the
+    // temp key file. `formatPrivateKey` is idempotent for already-
+    // prefixed inputs.
+    const formattedPrivateKey = PrivateKey.formatPrivateKey(
+      config.privateKey,
+      PrivateKeyVariants.Ed25519,
+    );
 
-    const movementConfigPath = join(homedir(), ".aptos", "config.yaml");
+    // Pass the private key via a 0o600 temp file (--private-key-file)
+    // and the on-chain address via --sender-account. Avoids the CLI's
+    // profile-yaml lookup chain entirely (no CWD / HOME / .aptos /
+    // .movement dance, no CLI-variant dependency).
+    const keyFilePath = writeTempKeyFile(formattedPrivateKey);
 
+    // SIGINT-safe sync cleanup BEFORE the CLI call so the private key
+    // never persists on disk after an abnormal exit. The signal-handler
+    // path uses the best-effort variant because the event loop is dead
+    // and we cannot logger.warning.
     ensureSignalHandler();
-    const syncCleanup = () => removeProfileSync(movementConfigPath, profile);
+    const syncCleanup = () => removeKeyFileSyncBestEffort(keyFilePath);
     cleanupCallbacks.add(syncCleanup);
 
-    await withYamlLock(() =>
-      addProfile(movementConfigPath, profile, {
-        private_key: cleanPrivateKey,
-        public_key: account.publicKey.toString(),
-        account: deployerAddress,
-        rest_url: config.rpc,
-      })
-    );
-
     let scriptOut = "";
     try {
       const typeArgsFragment: string[] =
@@ -117,8 +115,10 @@ export async function runMoveScript(
           args: [
             "move",
             "run-script",
-            "--profile",
-            safeProfile,
+            "--private-key-file",
+            keyFilePath,
+            "--sender-account",
+            deployerAddress,
             "--url",
             config.rpc,
             "--assume-yes",
@@ -135,15 +135,16 @@ export async function runMoveScript(
       if (result.stdout) console.log(result.stdout.trim());
       if (result.stderr) console.error(result.stderr.trim());
     } finally {
-      await withYamlLock(() => removeProfile(movementConfigPath, profile)).catch(
-        (err) => {
-          const cleanupMsg = err instanceof Error ? err.message : String(err);
-          logger.warning(
-            `Failed to remove script profile "${profile}" from ${movementConfigPath}: ${cleanupMsg}. ` +
-              `Run 'movement config delete-profile --profile ${profile}' to clean up manually.`
-          );
-        }
-      );
+      // Observable cleanup — emit a warning if the unlink failed and
+      // the file is still on disk (private key would persist silently
+      // otherwise).
+      const cleanupErr = removeKeyFile(keyFilePath);
+      if (cleanupErr) {
+        logger.warning(
+          `Failed to remove temp key file '${keyFilePath}': ${cleanupErr.message}. ` +
+            `The file has mode 0o600 but should be removed manually: rm ${keyFilePath}`
+        );
+      }
       cleanupCallbacks.delete(syncCleanup);
     }
 

package/src/helpers/__tests__/setupLocalTesting.fork-network.test.ts

@@ -0,0 +1,212 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdirSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+/**
+ * F1 — Harness.createFork(network) must honor the requested network.
+ *
+ * Mocks ForkManager so we can capture which RPC URL the fresh-fork
+ * code path picks. Strategy mirrors the pattern in
+ * src/fork/__tests__/manager.test.ts: replace the manager module with
+ * a stub that records every call to `initialize`.
+ *
+ * The mock also implements `load()` + `getMetadata()` so the
+ * "fork-exists, wrong network" case (audit-f1 follow-up) can exercise
+ * the metadata-mismatch guard in the `else` branch of `setupWithFork`.
+ */
+
+interface InitCall {
+  nodeUrl: string;
+  networkName?: string;
+  apiKey?: string;
+}
+const initializeCalls: InitCall[] = [];
+
+vi.mock("../../fork/manager.js", async () => {
+  const fs = await import("node:fs");
+  return {
+    ForkManager: class {
+      forkPath: string;
+      metadata: { network: string; nodeUrl: string } | null = null;
+      constructor(forkPath: string) {
+        this.forkPath = forkPath;
+      }
+      async initialize(nodeUrl: string, networkName?: string, apiKey?: string) {
+        const entry: InitCall = { nodeUrl };
+        if (networkName !== undefined) entry.networkName = networkName;
+        if (apiKey !== undefined) entry.apiKey = apiKey;
+        initializeCalls.push(entry);
+        this.metadata = { network: networkName ?? "custom", nodeUrl };
+      }
+      load() {
+        const raw = fs.readFileSync(`${this.forkPath}/metadata.json`, "utf-8");
+        this.metadata = JSON.parse(raw);
+      }
+      getMetadata() {
+        if (!this.metadata) {
+          throw new Error("Fork not initialized");
+        }
+        return this.metadata;
+      }
+      setApiKey() {}
+      async resetState() {}
+      async fundAccount() {}
+      async fundMultipleAccounts() {}
+    },
+  };
+});
+
+vi.mock("../../fork/server.js", () => {
+  return {
+    ForkServer: class {
+      constructor(_p: string, _port: number) {}
+      async start() {}
+      async stop() {}
+    },
+  };
+});
+
+vi.mock("../../runtime.js", () => ({
+  initRuntime: vi.fn(async () => ({})),
+}));
+
+vi.mock("../../core/AccountManager.js", () => {
+  let _seq = 0;
+  return {
+    AccountManager: {
+      createBatch(labels: readonly string[]) {
+        const out: Record<string, { accountAddress: { toString(): string } }> = {};
+        for (const l of labels) {
+          _seq++;
+          const addr = "0x" + _seq.toString(16).padStart(64, "0");
+          out[l] = { accountAddress: { toString: () => addr } };
+        }
+        return out;
+      },
+      exportPrivateKeys(_labels: readonly string[]) {
+        return { deployer: "0x" + "1".repeat(64) };
+      },
+    },
+  };
+});
+
+// Imported after mocks so vi.hoisted ordering applies.
+import { setupLocalTesting } from "../setupLocalTesting.js";
+import { logger } from "../../ui/index.js";
+
+describe("F1 — setupLocalTesting honors forkNetwork", () => {
+  let cwdBackup: string;
+  let tmpRoot: string;
+
+  beforeEach(() => {
+    initializeCalls.length = 0;
+    cwdBackup = process.cwd();
+    tmpRoot = mkdtempSync(join(tmpdir(), "movehat-f1-"));
+    process.chdir(tmpRoot);
+    vi.spyOn(logger, "step").mockImplementation(() => undefined);
+    vi.spyOn(logger, "success").mockImplementation(() => undefined);
+    vi.spyOn(logger, "plain").mockImplementation(() => undefined);
+    vi.spyOn(logger, "newline").mockImplementation(() => undefined);
+    vi.spyOn(logger, "warning").mockImplementation(() => undefined);
+    vi.spyOn(logger, "error").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    process.chdir(cwdBackup);
+    rmSync(tmpRoot, { recursive: true, force: true });
+    vi.restoreAllMocks();
+  });
+
+  it("uses the mainnet RPC when forkNetwork = 'mainnet'", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "mainnet",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("mainnet");
+    expect(call.nodeUrl).not.toMatch(/testnet/i);
+    expect(call.nodeUrl).toMatch(/mainnet/i);
+  });
+
+  it("uses the testnet RPC when forkNetwork = 'testnet'", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "testnet",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("testnet");
+    expect(call.nodeUrl).toMatch(/testnet/i);
+  });
+
+  it("uses forkRpcUrl override when supplied for a custom network", async () => {
+    await setupLocalTesting({
+      mode: "fork",
+      forkNetwork: "custom",
+      forkRpcUrl: "https://my-custom-node.example/v1",
+      accountLabels: ["deployer"],
+      autoFund: false,
+    });
+
+    expect(initializeCalls).toHaveLength(1);
+    const call = initializeCalls[0]!;
+    expect(call.networkName).toBe("custom");
+    expect(call.nodeUrl).toBe("https://my-custom-node.example/v1");
+  });
+
+  it("rejects a non-built-in forkNetwork when no forkRpcUrl is provided", async () => {
+    await expect(
+      setupLocalTesting({
+        mode: "fork",
+        forkNetwork: "some-unknown-network",
+        accountLabels: ["deployer"],
+        autoFund: false,
+      })
+    ).rejects.toThrow(/forkRpcUrl/i);
+    expect(initializeCalls).toHaveLength(0);
+  });
+
+  it("rejects when an existing fork's saved network does not match the requested one (audit-f1 follow-up)", async () => {
+    // Pre-seed `.movehat/forks/test-local/metadata.json` with the
+    // wrong network so the `forkExists` branch fires and loads stale
+    // metadata. Without the metadata-mismatch guard, setupLocalTesting
+    // would silently serve a testnet snapshot while the caller thinks
+    // it's reading mainnet.
+    const forkDir = join(tmpRoot, ".movehat", "forks", "test-local");
+    mkdirSync(forkDir, { recursive: true });
+    writeFileSync(
+      join(forkDir, "metadata.json"),
+      JSON.stringify({
+        network: "testnet",
+        nodeUrl: "https://testnet.movementnetwork.xyz/v1",
+        chainId: 250,
+        ledgerVersion: "0",
+        timestamp: "0",
+        epoch: "0",
+        blockHeight: "0",
+        createdAt: new Date().toISOString(),
+      }),
+    );
+
+    await expect(
+      setupLocalTesting({
+        mode: "fork",
+        forkNetwork: "mainnet",
+        accountLabels: ["deployer"],
+        autoFund: false,
+      })
+    ).rejects.toThrow(/network mismatch|created for|requested/i);
+    // Must not have re-initialized — the existing dir is what poisons
+    // the load path, and silently reinitializing would clobber the
+    // user's saved snapshot.
+    expect(initializeCalls).toHaveLength(0);
+  });
+});