movehat 0.2.1 → 0.2.2

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,18 +268,17 @@ 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);
     }
 

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);
+  });
+});

package/src/helpers/setupLocalTesting.ts

@@ -9,6 +9,25 @@ import { AccountManager } from "../core/AccountManager.js";
 import { logger } from "../ui/index.js";
 import type { LocalTestOptions } from "../types/config.js";
 
+const BUILTIN_FORK_RPCS: Record<string, string> = {
+  testnet: "https://testnet.movementnetwork.xyz/v1",
+  mainnet: "https://mainnet.movementnetwork.xyz/v1",
+};
+
+function resolveForkRpcUrl(
+  network: string,
+  override: string | undefined
+): string {
+  if (override !== undefined) return override;
+  const builtin = BUILTIN_FORK_RPCS[network];
+  if (builtin !== undefined) return builtin;
+  throw new Error(
+    `Cannot fork unknown network "${network}" without a forkRpcUrl. ` +
+      `Either pass forkRpcUrl in LocalTestOptions or use one of: ` +
+      `${Object.keys(BUILTIN_FORK_RPCS).join(", ")}.`
+  );
+}
+
 /**
  * Context returned by {@link setupLocalTesting}.
  *
@@ -264,8 +283,8 @@ async function setupWithFork(
 
   if (!forkExists) {
     logger.step(`Creating fork from ${forkNetwork}...`);
-    const testnetRpc = "https://testnet.movementnetwork.xyz/v1";
-    await forkManager.initialize(testnetRpc, forkNetwork, options.forkApiKey);
+    const rpcUrl = resolveForkRpcUrl(forkNetwork, options.forkRpcUrl);
+    await forkManager.initialize(rpcUrl, forkNetwork, options.forkApiKey);
     logger.success(`Fork created at ${forkPath}`);
     logger.newline();
   } else {
@@ -278,6 +297,21 @@ async function setupWithFork(
     }
     forkManager.load();
 
+    // Guard against the audit-f1 follow-up case: the default forkName
+    // ("test-local") doesn't encode the network, so a fork created for
+    // testnet would silently serve mainnet requests. Refuse to load
+    // when the saved metadata's network doesn't match what the caller
+    // asked for — the user must either pass a network-specific
+    // `forkName` or delete the stale directory.
+    const savedNetwork = forkManager.getMetadata().network;
+    if (savedNetwork !== forkNetwork) {
+      throw new Error(
+        `Fork at ${forkPath} was created for network "${savedNetwork}" but ` +
+          `you requested "${forkNetwork}". Use a different forkName ` +
+          `(e.g. "${forkNetwork}-local") or delete ${forkPath} to recreate.`
+      );
+    }
+
     if (forkResetState) {
       logger.step("Resetting fork state...");
       await forkManager.resetState();

package/src/index.ts

@@ -19,4 +19,12 @@ export type { ForkMetadata, AccountState, LedgerInfo, AccountData, AccountResour
 export { ModuleAlreadyDeployedError, PostPublishError } from "./errors.js";
 
 export { Harness, HarnessDisposedError } from "./harness/index.js";
-export type { HarnessMode } from "./harness/index.js";
+export type { HarnessMode } from "./harness/index.js";
+export type {
+  DeployCodeObjectOptions,
+  UpgradeCodeObjectOptions,
+  CodeObjectInfo,
+  RunViewFunctionOptions,
+  RunMoveScriptOptions,
+  MoveScriptResult,
+} from "./types/harness.js";

package/src/node/LocalNodeManager.ts

@@ -12,7 +12,15 @@ export interface LocalNodeOptions {
   testDir?: string;           // Directory for node data (default: .movehat/local-node)
   forceRestart?: boolean;     // Clean state and start fresh
   faucetPort?: number;        // Faucet port (default: 8081)
-  apiPort?: number;           // API/RPC port (default: 8080)
+  /**
+   * REST API port. Movement CLI (`movement node run-localnet`) does
+   * not accept a flag to change this — the node always binds 8080.
+   * Passing any other value triggers a warning at construction time
+   * and is replaced with 8080. Field is kept for source compatibility.
+   *
+   * @deprecated Movement CLI does not honor this. Omit it.
+   */
+  apiPort?: number;
   readyPort?: number;         // Ready server port (default: 8070)
   silent?: boolean;           // Suppress node output
   /**
@@ -22,6 +30,8 @@ export interface LocalNodeOptions {
   adapter?: ChildProcessAdapter;
 }
 
+const MOVEMENT_API_PORT = 8080;
+
 export interface LocalNodeInfo {
   rpcUrl: string;
   faucetUrl: string;
@@ -47,11 +57,23 @@ export class LocalNodeManager {
 
   constructor(options: LocalNodeOptions = {}) {
     this.adapter = options.adapter ?? defaultChildProcessAdapter;
+    if (
+      options.apiPort !== undefined &&
+      options.apiPort !== MOVEMENT_API_PORT
+    ) {
+      // Movement CLI hardcodes the REST API port to 8080. Surfacing
+      // the requested port via getNodeInfo() would lie about where
+      // the node actually listens.
+      logger.warning(
+        `LocalNodeManager: apiPort=${options.apiPort} is not supported by ` +
+          `movement node run-localnet; forcing REST API port to 8080.`
+      );
+    }
     this.options = {
       testDir: options.testDir || join(process.cwd(), ".movehat", "local-node"),
       forceRestart: options.forceRestart ?? false,
       faucetPort: options.faucetPort || 8081,
-      apiPort: options.apiPort || 8080,
+      apiPort: MOVEMENT_API_PORT,
       readyPort: options.readyPort || 8070,
       silent: options.silent ?? false,
     };

package/src/node/__tests__/LocalNodeManager.api-port.test.ts

@@ -0,0 +1,62 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+import { mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+import { LocalNodeManager } from "../LocalNodeManager.js";
+import { logger } from "../../ui/index.js";
+
+/**
+ * F9 — `apiPort` must not lie about where the node listens.
+ *
+ * `movement node run-localnet` (Movement CLI 7.4.0) does NOT accept a
+ * flag to change the REST API port. It always binds 8080. Earlier
+ * versions of LocalNodeManager accepted `apiPort: 9000` from the
+ * caller, stored it, and surfaced `http://127.0.0.1:9000` from
+ * `getNodeInfo()` — but the actual node was still on 8080. That
+ * mismatch would silently surface as "Movement command failed" with
+ * no useful signal. F9 closes the gap by refusing to lie: the
+ * effective port is 8080 regardless of what the caller passes, with a
+ * warning when they pass anything else.
+ */
+
+describe("F9 — LocalNodeManager apiPort is constrained to 8080", () => {
+  let tmpDir: string;
+  let warnSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    tmpDir = mkdtempSync(join(tmpdir(), "movehat-f9-"));
+    warnSpy = vi.spyOn(logger, "warning").mockImplementation(() => undefined);
+    vi.spyOn(logger, "step").mockImplementation(() => undefined);
+    vi.spyOn(logger, "plain").mockImplementation(() => undefined);
+    vi.spyOn(logger, "newline").mockImplementation(() => undefined);
+    vi.spyOn(logger, "success").mockImplementation(() => undefined);
+    vi.spyOn(logger, "error").mockImplementation(() => undefined);
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("ignores non-default apiPort, forces 8080, and warns", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir, apiPort: 9000 });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).toHaveBeenCalledTimes(1);
+    const msg = warnSpy.mock.calls[0]?.[0] as string;
+    expect(msg).toMatch(/8080/);
+    expect(msg).toMatch(/apiPort|REST API port/i);
+  });
+
+  it("accepts apiPort: 8080 without warning", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir, apiPort: 8080 });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+
+  it("accepts omitted apiPort without warning (default path)", () => {
+    const mgr = new LocalNodeManager({ testDir: tmpDir });
+    expect(mgr.getNodeInfo().rpcUrl).toBe("http://127.0.0.1:8080");
+    expect(warnSpy).not.toHaveBeenCalled();
+  });
+});