cli: honor --preserve-symlinks/-main for __filename, make SIGUSR1 inert by default

src/bundler/transpiler.rs

@@ -1118,6 +1118,7 @@ pub(crate) fn resolver_bundle_options_subset(
         polyfill_node_globals: src.polyfill_node_globals,
         prefer_offline_install: src.prefer_offline_install,
         preserve_symlinks: src.preserve_symlinks,
+        preserve_symlinks_main: false,
         rewrite_jest_for_tests: src.rewrite_jest_for_tests,
         tsconfig_override: src.tsconfig_override.clone(),
         production: src.production,

src/js/internal/process/pre_execution.ts

@@ -258,6 +258,7 @@ function installExitTracing(): void {
   let catString: string | null = null;
   let filePattern: string | null = null;
   let stackTraceLimit: string | null = null;
+  let heapsnapshotSignal: string | null = null;
   let traceEnv = false;
   let traceEnvJsStack = false;
   let traceExit = false;
@@ -292,6 +293,10 @@ function installExitTracing(): void {
       // keys its native-stack assertions on that string appearing.
     } else if (arg === "--trace-exit") {
       traceExit = true;
+    } else if (arg === "--heapsnapshot-signal") {
+      if (i + 1 < execArgv.length) heapsnapshotSignal = execArgv[++i];
+    } else if (arg.startsWith("--heapsnapshot-signal=")) {
+      heapsnapshotSignal = arg.slice("--heapsnapshot-signal=".length);
     }
   }
 
@@ -333,6 +338,12 @@ function installExitTracing(): void {
     envTracePrintJsStack = traceEnvJsStack;
     installEnvTracing();
   }
+  if (heapsnapshotSignal !== null && process.platform !== "win32") {
+    require("internal/validators").validateSignalName(heapsnapshotSignal);
+    process.on(heapsnapshotSignal as NodeJS.Signals, () => {
+      require("node:v8").writeHeapSnapshot();
+    });
+  }
 }
 
 export default {};

src/jsc/VirtualMachine.rs

@@ -2304,7 +2304,9 @@ impl VirtualMachine {
         // execArgv. (The JS side re-reads `process.execArgv`, so an explicit
         // empty execArgv under a traced parent stays a no-op there.)
         fn is_bootstrap_flag(arg: &[u8]) -> bool {
-            arg.starts_with(b"--trace-") || arg.starts_with(b"--stack-trace-limit")
+            arg.starts_with(b"--trace-")
+                || arg.starts_with(b"--stack-trace-limit")
+                || arg.starts_with(b"--heapsnapshot-signal")
         }
         let needs_pre_execution = bun_core::argv().into_iter().any(is_bootstrap_flag)
             || self
@@ -4048,7 +4050,8 @@ impl VirtualMachine {
             return Err(crate::CrateError::ModuleNotFound);
         }
 
-        let is_special_source = source == MAIN_FILE_NAME || Macro::is_macro_path(source);
+        let is_main_entry_resolve = source == MAIN_FILE_NAME;
+        let is_special_source = is_main_entry_resolve || Macro::is_macro_path(source);
         let mut query_string: &[u8] = b"";
         let normalized_specifier = normalize_specifier_for_resolution(specifier, &mut query_string);
         let top_level_dir = self.top_level_dir();
@@ -4157,10 +4160,23 @@ impl VirtualMachine {
         let result_path = result
             .path_const()
             .ok_or(crate::CrateError::ModuleNotFound)?;
-        // SAFETY: `result_path.text` borrows the resolver's arena, which
-        // outlives `ResolveFunctionResult` (see the struct's lifetime-erasure
-        // note).
-        ret.path = unsafe { bun_ptr::detach_lifetime(result_path.text) };
+        // `--preserve-symlinks-main`: the synthetic `bun:main` wrapper resolving
+        // the entry module must keep the symlink spelling. `finalize_result`
+        // stores the pre-realpath text in `.pretty` when it rewrites `.text`
+        // (see `Path::set_realpath`), so read it back for this one resolve.
+        let path_text = if is_main_entry_resolve
+            && self.transpiler.resolver.opts.preserve_symlinks_main
+            && result_path.is_symlink
+            && !result_path.pretty.is_empty()
+        {
+            result_path.pretty
+        } else {
+            result_path.text
+        };
+        // SAFETY: `result_path.text`/`.pretty` borrow the resolver's arena,
+        // which outlives `ResolveFunctionResult` (see the struct's
+        // lifetime-erasure note).
+        ret.path = unsafe { bun_ptr::detach_lifetime(path_text) };
         ret.result = Some(result);
 
         Ok(())

src/jsc/bindings/BunProcess.cpp

@@ -1395,6 +1395,9 @@ extern "C" bool Bun__shouldIgnoreOneDisconnectEventListener(JSC::JSGlobalObject*
 extern "C" void Bun__ensureSignalHandler();
 extern "C" bool Bun__isMainThreadVM();
 extern "C" void Bun__onPosixSignal(int signalNumber);
+#if !OS(WINDOWS)
+extern "C" void Bun__noopSignalHandler(int);
+#endif
 
 __attribute__((noinline)) static void forwardSignal(int signalNumber)
 {
@@ -1587,7 +1590,10 @@ static void onDidChangeListeners(EventEmitter& eventEmitter, const Identifier& e
                     if (signalToContextIdsMap->find(signalNumber) != signalToContextIdsMap->end() && eventEmitter.listenerCount(eventName) == 0) {
 
 #if !OS(WINDOWS)
-                        if (void (*oldHandler)(int) = signal(signalNumber, SIG_DFL); oldHandler != forwardSignal) {
+                        // SIGUSR1 is reserved (inert) by default; restoring SIG_DFL would
+                        // make it fatal. Restore the startup no-op handler instead.
+                        void (*restoreTo)(int) = signalNumber == SIGUSR1 ? Bun__noopSignalHandler : SIG_DFL;
+                        if (void (*oldHandler)(int) = signal(signalNumber, restoreTo); oldHandler != forwardSignal) {
                             // Don't uninstall the old handler if it's not the one we installed.
                             signal(signalNumber, oldHandler);
                         }

src/jsc/bindings/c-bindings.cpp

@@ -572,6 +572,12 @@ extern "C" void Bun__setCTRLHandler(BOOL add)
 
 extern "C" int32_t bun_is_stdio_null[3] = { 0, 0, 0 };
 
+#if !OS(WINDOWS)
+extern "C" void Bun__noopSignalHandler(int)
+{
+}
+#endif
+
 extern "C" void bun_initialize_process()
 {
     // Disable printf() buffering. We buffer it ourselves.
@@ -653,6 +659,20 @@ extern "C" void bun_initialize_process()
         sigaction(SIGTERM, &sa, nullptr);
         sigaction(SIGINT, &sa, nullptr);
     }
+
+    // Node.js reserves SIGUSR1 for the debugger and never lets it terminate
+    // the process by default. Bun does not start an inspector on SIGUSR1, but
+    // still makes the signal inert so ops tooling that signals a node-compatible
+    // process does not kill it. A handler (not SIG_IGN) is used so the
+    // disposition resets to SIG_DFL across exec() for child processes.
+    {
+        struct sigaction sa;
+        memset(&sa, 0, sizeof(sa));
+        sigemptyset(&sa.sa_mask);
+        sa.sa_flags = SA_RESTART;
+        sa.sa_handler = Bun__noopSignalHandler;
+        sigaction(SIGUSR1, &sa, nullptr);
+    }
 #elif OS(WINDOWS)
     for (int fd = 0; fd <= 2; ++fd) {
         auto handle = reinterpret_cast<HANDLE>(uv_get_osfhandle(fd));

src/resolver/options.rs

@@ -232,6 +232,10 @@ pub struct BundleOptions {
     pub polyfill_node_globals: bool,
     pub prefer_offline_install: bool,
     pub preserve_symlinks: bool,
+    /// `--preserve-symlinks-main`: applies `preserve_symlinks` semantics to
+    /// the main entry module only. Consumed by the VM's `_resolve` when the
+    /// source is the synthetic `bun:main` wrapper.
+    pub preserve_symlinks_main: bool,
     pub rewrite_jest_for_tests: bool,
     pub tsconfig_override: Option<Box<[u8]>>,
     pub production: bool,
@@ -275,6 +279,7 @@ impl Default for BundleOptions {
             polyfill_node_globals: false,
             prefer_offline_install: false,
             preserve_symlinks: false,
+            preserve_symlinks_main: false,
             rewrite_jest_for_tests: false,
             tsconfig_override: None,
             output_dir: Box::default(),

src/resolver/resolver.rs

@@ -1665,8 +1665,16 @@
                     module_type_from_ext(name.ext).unwrap_or(options::ModuleType::Unknown);
             }
 
-            if let Some(entries) = dir.get_entries_ref(self.generation) {
-                if let Some(query) = entries.get(name.filename) {
+            // `--preserve-symlinks` (Node.js semantics): keep the symlink
+            // spelling as the resolved path so `__filename` / the module
+            // cache key is the link, not the realpath. `dir.abs_real_path`
+            // is already left empty under this flag (see `dir_info_uncached`),
+            // so skipping this block is the only remaining realpath source.
+            if !self.opts.preserve_symlinks
+                && let Some(entries) = dir.get_entries_ref(self.generation)
+                && let Some(query) = entries.get(name.filename)
+            {
+                {
                     // SAFETY: entries_mutex held; rfs points at the process-global RealFS.
                     let symlink_path =
                         unsafe { query.entry().symlink(self.rfs_ptr(), self.store_fd) };

src/runtime/cli/Arguments.rs

@@ -307,6 +307,7 @@ pub(crate) const RUNTIME_PARAMS_: &[ParamType] = &[
     parse_param!("--trace-exit"),
     parse_param!("--expose-internals"),
     parse_param!("--stack-trace-limit <STR>"),
+    parse_param!("--heapsnapshot-signal <STR>"),
 ];
 
 pub(crate) const AUTO_OR_RUN_PARAMS: &[ParamType] = &[

src/runtime/cli/run_command.rs

@@ -959,6 +959,11 @@ Full documentation is available at <magenta>https://bun.com/docs/cli/run<r>
         vm.argv = std::mem::take(&mut ctx.passthrough);
         // `InitOptions` has no `store_fd` field, so set it on the resolver directly.
         vm.transpiler.resolver.store_fd = ctx.debug.hot_reload != cli::command::HotReload::None;
+        vm.transpiler.resolver.opts.preserve_symlinks_main =
+            ctx.runtime_options.preserve_symlinks_main
+                || bun_core::env_var::NODE_PRESERVE_SYMLINKS_MAIN
+                    .get()
+                    .unwrap_or(false);
         // `vm.dns_result_order` is a `u8` until the b2-cycle widens
         // it to `bun_dns::Order`; the enum is `#[repr(u8)]` so `as u8` is exact.
         vm.dns_result_order =
@@ -2870,9 +2875,35 @@ impl RunCommand {
             ..Default::default()
         });
 
+        let preserve_symlinks_main = ctx.runtime_options.preserve_symlinks_main
+            || bun_core::env_var::NODE_PRESERVE_SYMLINKS_MAIN
+                .get()
+                .unwrap_or(false);
+
         // Re-derive the canonical absolute path from the open fd (resolves
-        // symlinks).
-        let absolute_script_path: Box<[u8]> = {
+        // symlinks). With `--preserve-symlinks-main`, Node.js keeps the
+        // symlink spelling for the entry module's `__filename`, so skip the
+        // realpath and resolve `target` against cwd instead.
+        let absolute_script_path: Box<[u8]> = if preserve_symlinks_main {
+            let mut cwd_buf = PathBuffer::uninit();
+            let Ok(cwd) = bun_core::getcwd(&mut cwd_buf) else {
+                let _ = bun_sys::close(fd);
+                return false;
+            };
+            let cwd_len = cwd.as_bytes().len();
+            cwd_buf[cwd_len] = paths::SEP;
+            let joined = paths::resolve_path::join_abs_string_buf::<paths::platform::Auto>(
+                &cwd_buf[..cwd_len + 1],
+                &mut script_name_buf.0,
+                &[target],
+            );
+            let joined = strings::without_trailing_slash(joined);
+            if joined.is_empty() {
+                let _ = bun_sys::close(fd);
+                return false;
+            }
+            joined.to_vec().into_boxed_slice()
+        } else {
             let resolved = match bun_sys::get_fd_path(fd, &mut script_name_buf) {
                 Ok(p) => p,
                 Err(_) => {