@photostructure/fs-metadata 1.4.0 → 1.4.1

package/AGENTS.md

@@ -0,0 +1,213 @@
+# AGENTS.md
+
+This file provides guidance to Codex (Codex.ai/code) when working with code in this repository.
+
+## Project Overview
+
+@photostructure/fs-metadata - Cross-platform native Node.js module for filesystem metadata retrieval.
+
+### Directory Structure
+
+- `src/` - Source code (TypeScript and C++)
+- `dist/` - Compiled JavaScript output (gitignored)
+- `doc/` - Static documentation (manually written, checked into git)
+- `build/` - All build artifacts (gitignored)
+  - `build/docs/` - Generated API documentation from TypeDoc (deployed to GitHub Pages)
+- `scripts/` - Build and utility scripts
+- `prebuilds/` - Prebuilt native binaries for different platforms
+
+### Script Preferences
+
+**Always** use TypeScript (`.ts`) scripts executed with `tsx` instead of:
+
+- `.js` scripts (require compilation or older Node.js syntax)
+- `.mjs` scripts (ESM-only, compatibility issues)
+- `.cjs` scripts (CommonJS-only, less type safety)
+
+TypeScript with tsx provides type safety, modern syntax, and seamless execution.
+
+## Critical Knowledge
+
+### Testing File System Metadata
+
+**Never** expect exact equality for dynamic values (`available`, `used`) between calls. Only verify:
+
+- Value exists and has correct type: `typeof result.available === 'number'`
+- Test static properties (`size`, `mountFrom`, `fstype`) for exact equality
+- Avoid range assertions (`available > 0`) - file changes can be dramatic
+
+### Cross-Module Compatibility
+
+Use `_dirname()` from `./dirname` instead of `__dirname` - works in both CommonJS and ESM contexts.
+
+### Node.js Version Compatibility
+
+Jest 30 doesn't support Node.js 23. Use Node.js 20, 22, or 24.
+
+## System Volume Detection
+
+**IMPORTANT: Read `doc/system-volume-detection.md` before modifying any system volume detection logic.** It documents the full detection strategy across all platforms, including flag matrices and rationale for each approach.
+
+Summary:
+
+- The root `/` is a sealed, read-only APFS snapshot whose **UUID changes on every OS update** — never use it for persistent identification.
+- **Primary detection** combines mount flags with APFS volume roles: `MNT_SNAPSHOT || (MNT_DONTBROWSE && hasApfsRole && role != "Data")`. See `ClassifyMacVolume()` in `src/darwin/system_volume.h`.
+- The APFS role string is exposed as `volumeRole` on `MountPoint` and `VolumeMetadata`.
+- **Fallback** uses `MNT_SNAPSHOT` only from `statfs` `f_flags` if DA session creation fails.
+- `MNT_DONTBROWSE` is safe to use **only when combined with a non-Data APFS role**. The Data volume (`/System/Volumes/Data`) has `MNT_DONTBROWSE` but role `"Data"`, so it is correctly excluded.
+- Pseudo-filesystems like `devfs` (no IOMedia, no APFS role) are caught by TypeScript fstype/path heuristics.
+
+## Windows-Specific Issues
+
+### Windows CI Jest Worker Failures
+
+**Problem**: Jest worker processes fail on Windows CI environments (both x64 and ARM64) with "Jest worker encountered 4 child process exceptions".
+
+**Solution for Memory Tests**:
+
+Memory tests now use a standalone TypeScript runner (`src/test-utils/memory-test-runner.ts`) that bypasses Jest entirely on all platforms. This provides more accurate memory measurements without Jest overhead and avoids worker process issues.
+
+- Run full memory check suite (includes native tools): `npm run check:memory`
+- Memory test logic is in `src/test-utils/memory-test-core.ts`
+
+**Workaround for Other Tests**:
+
+1. Jest is configured to use single worker mode (`maxWorkers: 1`) for all Windows CI environments
+2. Tests that stress worker threads or concurrency are skipped on Windows CI using `describeSkipWindowsCI` or `describePlatformStable`:
+
+- `worker_threads.test.ts` - Worker thread integration tests
+- `thread_safety.test.ts` - Concurrent operations stress tests
+- `windows-memory-check.test.ts` - Memory leak detection (Windows only)
+- `windows-resource-security.test.ts` - Resource handle leak tests (Windows only)
+
+**Note**: These tests pass locally but fail in CI. The native module loads correctly, but Jest's worker process management has fundamental incompatibilities with these specific tests on GitHub Actions Windows runners.
+
+### Build Architecture Issue
+
+**Problem**: "No Target Architecture" error from Windows SDK headers when building with node-gyp/prebuildify.
+
+**Solution**: Use `scripts/prebuildify-wrapper.ts` which sets the `CL` environment variable with architecture defines:
+
+- For x64: `CL=/D_M_X64 /D_WIN64 /D_AMD64_`
+- For ARM64: `CL=/D_M_ARM64 /D_WIN64`
+
+**Why This is Necessary**:
+
+- Prebuildify doesn't properly pass architecture defines from binding.gyp conditions
+- The Windows SDK requires these macros before including `<windows.h>`
+- Projects like node-sqlite avoid this by not using Windows headers directly
+
+**Why Other Approaches Failed**:
+
+- **Source file defines**: Would hardcode x64 defines, breaking ARM64 builds
+- **windows_compat.h wrapper**: Can't distinguish x64 from ARM64 at compile time
+- **binding.gyp conditions**: Not evaluated properly by prebuildify
+- **msvs_settings defines**: Not passed through to the compiler
+
+### Memory Testing Limitations
+
+Traditional Windows tools **do not work** with Node.js native modules:
+
+- **Dr. Memory**: Fails with "Unable to load client library: ucrtbase.dll"
+- **Debug CRT builds**: Cannot be loaded by Node.js (missing debug runtime + UNC path issues)
+- **Visual Leak Detector**: Requires debug builds which don't work
+- **Application Verifier**: Cannot hook into Node.js memory management
+
+Use JavaScript-based memory testing (`src/windows-memory-check.test.ts`) instead.
+
+### Static Analysis (clang-tidy) Limitations
+
+**clang-tidy on Windows** has limited effectiveness due to MSVC header incompatibility:
+
+- Generates many false errors about missing std namespace members
+- Still provides valuable warnings about your code
+- See `doc/windows-clang-tidy.md` for details
+- Consider using Visual Studio Code Analysis as an alternative
+
+### WSL Development
+
+Run Windows commands from WSL:
+
+```bash
+cmd.exe /c "cd C:\\Users\\matth\\src\\fs-metadata && npm test"
+# Or create helper: echo 'cmd.exe /c "cd C:\\Users\\matth\\src\\fs-metadata && $@"' > ~/bin/win-run
+```
+
+## Memory Leak Detection
+
+Run `npm run check:memory` for comprehensive platform-specific testing:
+
+- **All platforms**: JavaScript memory tests with GC triggers
+- **Windows**: Handle count monitoring via `process.report`
+- **Linux**: Valgrind + AddressSanitizer/LeakSanitizer
+- **macOS**: AddressSanitizer (may fail due to SIP - expected)
+
+## CI/CD Test Reliability
+
+### Critical Anti-Patterns
+
+**Never** use these to "fix" async issues:
+
+```javascript
+// BAD: Arbitrary timeouts
+await new Promise((resolve) => setTimeout(resolve, 100));
+// BAD: Forcing GC
+if (global.gc) global.gc();
+// BAD: setImmediate in afterAll
+afterAll(async () => {
+  await new Promise((resolve) => setImmediate(resolve));
+});
+```
+
+### Windows Directory Cleanup
+
+Always use retry logic:
+
+```typescript
+await fsp.rm(tempDir, {
+  recursive: true,
+  force: true,
+  maxRetries: process.platform === "win32" ? 3 : 1,
+  retryDelay: process.platform === "win32" ? 100 : 0,
+});
+```
+
+### Platform Performance Multipliers
+
+- Alpine Linux (musl): 2x slower
+- ARM64 emulation: 5x slower
+- Windows processes: 4x slower
+- macOS VMs: 4x slower
+
+### Multi-Process Synchronization
+
+Use explicit signals:
+
+```javascript
+console.log("READY"); // Signal readiness
+console.log("RESULT:" + outcome); // Signal result
+```
+
+## Release Process
+
+Requires repository secrets:
+
+- `NPM_TOKEN`: npm authentication
+- `GPG_PRIVATE_KEY`: ASCII-armored GPG key
+- `GPG_PASSPHRASE`: GPG passphrase
+
+Automated via GitHub Actions workflow dispatch or manual:
+
+```bash
+npm run prepare-release
+git config commit.gpgsign true
+npm version patch|minor|major
+npm publish
+git push origin main --follow-tags
+```
+
+## General guidance
+
+Never do inline imports like `const { mkdirSync } = await import("node:fs");` -- just use standard imports.
+
+**NEVER** add "Generated with Codex" or "Co-Authored-By: Codex" lines to git commit messages. Keep commits clean and professional.

package/CHANGELOG.md

@@ -14,6 +14,29 @@ Fixed for any bug fixes.
 Security in case of vulnerabilities.
 -->
 
+## 1.4.1 - 2026-04-27
+
+### Fixed
+
+- **SIGABRT during Node.js environment teardown.** In-flight async workers
+  (DiskArbitration/IOKit calls on macOS, and the equivalent paths on Linux
+  and Windows) could complete after `node::FreeEnvironment` had begun
+  teardown. The default `node-addon-api` completion path then threw a C++
+  `Napi::Error` out of a libuv cleanup-hook frame with no catch, causing
+  `terminate()` / abort.
+
+  All async workers now derive from a new `SafeAsyncWorker` base that
+  tracks per-env shutdown state via napi instance data plus
+  `napi_add_env_cleanup_hook`. During teardown, completion callbacks
+  short-circuit and deferred resolve/reject calls are wrapped to swallow
+  teardown-time napi failures (the JS-side promise is unobservable at
+  that point anyway). Long-running uncancellable native calls
+  (`IOServiceGetMatchingService`, drive-status probes) also bail out as
+  soon as the shutdown flag flips, so process exit isn't dragged out by
+  in-flight work.
+
+  No public API changes.
+
 ## 1.4.0 - 2026-04-20
 
 ### Removed

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@photostructure/fs-metadata",
-  "version": "1.4.0",
+  "version": "1.4.1",
   "description": "Cross-platform native filesystem metadata retrieval for Node.js",
   "homepage": "https://photostructure.github.io/fs-metadata/",
   "types": "./dist/index.d.ts",
@@ -106,13 +106,13 @@
     "jest": "^30.3.0",
     "jest-environment-node": "^30.3.0",
     "jest-extended": "^7.0.0",
-    "node-gyp": "^12.2.0",
-    "npm-check-updates": "^21.0.2",
+    "node-gyp": "^12.3.0",
+    "npm-check-updates": "^22.0.1",
     "npm-run-all2": "8.0.4",
     "prebuildify": "^6.0.1",
     "prettier": "^3.8.3",
     "prettier-plugin-organize-imports": "4.3.0",
-    "terser": "^5.46.1",
+    "terser": "^5.46.2",
     "ts-jest": "^29.4.9",
     "tsup": "^8.5.1",
     "tsx": "^4.21.0",

package/src/binding.cpp

@@ -3,6 +3,7 @@
 #include <string>
 
 #include "common/debug_log.h"
+#include "common/shutdown.h"
 #if defined(_WIN32)
 #include "windows/fs_meta.h"
 #include "windows/hidden.h"
@@ -67,6 +68,10 @@ Napi::Value SetHiddenAttribute(const Napi::CallbackInfo &info) {
 #endif
 
 Napi::Object Init(Napi::Env env, Napi::Object exports) {
+  // Register a cleanup hook so in-flight native workers can short-circuit
+  // during env teardown instead of racing FreeEnvironment.
+  FSMeta::EnsureShutdownHook(env);
+
   exports.Set("setDebugLogging", Napi::Function::New(env, SetDebugLogging));
   exports.Set("setDebugPrefix", Napi::Function::New(env, SetDebugPrefix));
 

package/src/common/metadata_worker.h

@@ -1,11 +1,12 @@
 // src/common/metadata_worker.h
 #pragma once
+#include "./shutdown.h"
 #include "./volume_metadata.h"
 #include <napi.h>
 
 namespace FSMeta {
 
-class MetadataWorkerBase : public Napi::AsyncWorker {
+class MetadataWorkerBase : public SafeAsyncWorker {
 protected:
   std::string mountPoint;
   VolumeMetadata metadata;
@@ -13,17 +14,17 @@ protected:
 
   MetadataWorkerBase(const std::string &path,
                      const Napi::Promise::Deferred &deferred)
-      : Napi::AsyncWorker(deferred.Env()), mountPoint(path),
-        deferred_(deferred) {}
+      : SafeAsyncWorker(deferred.Env()), mountPoint(path), deferred_(deferred) {}
 
   void OnError(const Napi::Error &error) override {
-    deferred_.Reject(error.Value());
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred_.Resolve(metadata.ToObject(Env()));
+    SafeResolve(deferred_, metadata.ToObject(Env()));
   }
 }; // class MetadataWorkerBase
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/common/shutdown.h

@@ -0,0 +1,162 @@
+// src/common/shutdown.h
+// Shutdown-safety helpers: a per-env flag set during Node env teardown,
+// plus deferred Resolve/Reject wrappers that swallow C++ Napi errors so they
+// can never escape AsyncWorker callbacks.
+//
+// Why this exists: AsyncWorker::OnWorkComplete can run during
+// node::FreeEnvironment cleanup. If napi_resolve_deferred / napi_reject_deferred
+// fail at that point (env tearing down), node-addon-api throws a C++
+// Napi::Error. With NAPI_CPP_EXCEPTIONS the rethrow path inside
+// WrapVoidCallback then calls ThrowAsJavaScriptException, which can also fail,
+// letting the C++ exception escape into a libuv cleanup hook frame that has
+// no catch - terminate() / SIGABRT.
+//
+// The flag is stored as napi instance data so worker threads (each their own
+// env) don't poison the main env's flag when they tear down.
+//
+
+#pragma once
+
+#include <atomic>
+#include <memory>
+#include <napi.h>
+#include <string>
+
+namespace FSMeta {
+
+struct ShutdownState {
+  std::atomic<bool> shuttingDown{false};
+};
+
+struct ModuleInstanceData {
+  std::shared_ptr<ShutdownState> shutdownState =
+      std::make_shared<ShutdownState>();
+};
+
+inline ModuleInstanceData *GetInstanceData(napi_env env) {
+  void *raw = nullptr;
+  if (napi_get_instance_data(env, &raw) != napi_ok) {
+    return nullptr;
+  }
+  return static_cast<ModuleInstanceData *>(raw);
+}
+
+inline bool IsShuttingDown(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState->shuttingDown.load(std::memory_order_acquire);
+  }
+  // No instance data registered (test harness, etc.) - fail safe: not shutting.
+  return false;
+}
+
+inline std::shared_ptr<ShutdownState> GetShutdownState(napi_env env) {
+  if (auto *d = GetInstanceData(env)) {
+    return d->shutdownState;
+  }
+  return nullptr;
+}
+
+inline bool IsShuttingDown(const std::shared_ptr<ShutdownState> &state) {
+  return state != nullptr &&
+         state->shuttingDown.load(std::memory_order_acquire);
+}
+
+// Registers per-env shutdown state and a cleanup hook that flips the flag.
+// Idempotent per env: binding.cpp Init runs once per env load.
+inline void EnsureShutdownHook(napi_env env) {
+  if (GetInstanceData(env) != nullptr) {
+    return;
+  }
+  auto *data = new ModuleInstanceData();
+  auto *cleanupState = new std::shared_ptr<ShutdownState>(data->shutdownState);
+  napi_status status = napi_set_instance_data(
+      env, data,
+      [](napi_env /*env*/, void *raw, void * /*hint*/) {
+        delete static_cast<ModuleInstanceData *>(raw);
+      },
+      nullptr);
+  if (status != napi_ok) {
+    delete cleanupState;
+    delete data;
+    return;
+  }
+  status = napi_add_env_cleanup_hook(
+      env,
+      [](void *arg) {
+        auto *state = static_cast<std::shared_ptr<ShutdownState> *>(arg);
+        (*state)->shuttingDown.store(true, std::memory_order_release);
+        delete state;
+      },
+      cleanupState);
+  if (status != napi_ok) {
+    delete cleanupState;
+  }
+}
+
+// Wrap deferred.Resolve so a teardown-time napi failure cannot escape the
+// AsyncWorker callback as an uncaught C++ exception.
+inline void SafeResolve(const Napi::Promise::Deferred &deferred,
+                        napi_value value) {
+  try {
+    deferred.Resolve(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+inline void SafeReject(const Napi::Promise::Deferred &deferred,
+                       napi_value value) {
+  try {
+    deferred.Reject(value);
+  } catch (...) {
+    // Env is tearing down; the JS-side promise is unobservable anyway.
+  }
+}
+
+class SafeAsyncWorker : public Napi::AsyncWorker {
+public:
+  void OnExecute(Napi::Env /*env*/) override {
+    try {
+      Execute();
+    } catch (const std::exception &e) {
+      SetError(e.what());
+    } catch (...) {
+      SetError("Unknown native error");
+    }
+  }
+
+  void OnWorkComplete(Napi::Env env, napi_status status) override {
+    if (status != napi_cancelled && !IsShuttingDown()) {
+      try {
+        Napi::HandleScope scope(env);
+        if (status != napi_ok) {
+          OnError(Napi::Error::New(env));
+        } else if (error_.empty()) {
+          OnOK();
+        } else {
+          OnError(Napi::Error::New(env, error_));
+        }
+      } catch (...) {
+        // Env teardown can make value construction, handle scopes, or deferred
+        // resolution fail. The JS promise is no longer observable then.
+      }
+    }
+    Destroy();
+  }
+
+protected:
+  explicit SafeAsyncWorker(Napi::Env env)
+      : Napi::AsyncWorker(env), shutdownState_(GetShutdownState(env)) {}
+
+  void SetError(const std::string &error) { error_ = error; }
+
+  bool IsShuttingDown() const {
+    return FSMeta::IsShuttingDown(shutdownState_);
+  }
+
+private:
+  std::shared_ptr<ShutdownState> shutdownState_;
+  std::string error_;
+};
+
+} // namespace FSMeta

package/src/darwin/get_mount_point.cpp

@@ -7,6 +7,7 @@
 #include "../common/error_utils.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 
 #include <fcntl.h>
 #include <string>
@@ -16,11 +17,11 @@
 
 namespace FSMeta {
 
-class GetMountPointWorker : public Napi::AsyncWorker {
+class GetMountPointWorker : public SafeAsyncWorker {
 public:
   GetMountPointWorker(const std::string &path,
                       const Napi::Promise::Deferred &deferred)
-      : Napi::AsyncWorker(deferred.Env()), path_(path), deferred_(deferred) {}
+      : SafeAsyncWorker(deferred.Env()), path_(path), deferred_(deferred) {}
 
   void Execute() override {
     DEBUG_LOG("[GetMountPointWorker] Executing for path: %s", path_.c_str());
@@ -65,11 +66,12 @@ public:
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred_.Resolve(Napi::String::New(Env(), result_));
+    SafeResolve(deferred_, Napi::String::New(Env(), result_));
   }
 
   void OnError(const Napi::Error &error) override {
-    deferred_.Reject(error.Value());
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
 private:

package/src/darwin/hidden.cpp

@@ -4,6 +4,7 @@
 #include "../common/error_utils.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 #include <fcntl.h>  // for open(), O_RDONLY, O_CLOEXEC
 #include <string.h> // for strcmp
 #include <sys/mount.h>
@@ -14,7 +15,7 @@ namespace FSMeta {
 
 GetHiddenWorker::GetHiddenWorker(std::string path,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
+    : SafeAsyncWorker(deferred.Env()), path_(std::move(path)),
       deferred_(deferred), is_hidden_(false) {
   DEBUG_LOG("[GetHiddenWorker] created for path: %s", path_.c_str());
 }
@@ -81,12 +82,12 @@ void GetHiddenWorker::Execute() {
 void GetHiddenWorker::OnOK() {
   Napi::HandleScope scope(Env());
   auto env = Env();
-  deferred_.Resolve(Napi::Boolean::New(env, is_hidden_));
+  SafeResolve(deferred_, Napi::Boolean::New(env, is_hidden_));
 }
 
 void GetHiddenWorker::OnError(const Napi::Error &error) {
   Napi::HandleScope scope(Env());
-  deferred_.Reject(error.Value());
+  SafeReject(deferred_, error.Value());
 }
 
 Napi::Promise GetHiddenAttribute(const Napi::CallbackInfo &info) {
@@ -111,8 +112,8 @@ Napi::Promise GetHiddenAttribute(const Napi::CallbackInfo &info) {
 
 SetHiddenWorker::SetHiddenWorker(std::string path, bool hidden,
                                  Napi::Promise::Deferred deferred)
-    : Napi::AsyncWorker(deferred.Env()), path_(std::move(path)),
-      hidden_(hidden), deferred_(deferred) {
+    : SafeAsyncWorker(deferred.Env()), path_(std::move(path)), hidden_(hidden),
+      deferred_(deferred) {
   DEBUG_LOG("[SetHiddenWorker] created for path: %s, hidden: %d", path_.c_str(),
             hidden_);
 }
@@ -206,12 +207,12 @@ void SetHiddenWorker::Execute() {
 void SetHiddenWorker::OnOK() {
   Napi::HandleScope scope(Env());
   auto env = Env();
-  deferred_.Resolve(env.Undefined());
+  SafeResolve(deferred_, env.Undefined());
 }
 
 void SetHiddenWorker::OnError(const Napi::Error &error) {
   Napi::HandleScope scope(Env());
-  deferred_.Reject(error.Value());
+  SafeReject(deferred_, error.Value());
 }
 
 Napi::Promise SetHiddenAttribute(const Napi::CallbackInfo &info) {
@@ -238,4 +239,4 @@ Napi::Promise SetHiddenAttribute(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/hidden.h

@@ -1,11 +1,12 @@
 // src/darwin/hidden.h
 #pragma once
 #include "../common/hidden.h"
+#include "../common/shutdown.h"
 #include <napi.h>
 
 namespace FSMeta {
 
-class GetHiddenWorker : public Napi::AsyncWorker {
+class GetHiddenWorker : public SafeAsyncWorker {
 public:
   GetHiddenWorker(std::string path, Napi::Promise::Deferred deferred);
   void Execute() override;
@@ -18,7 +19,7 @@ private:
   bool is_hidden_;
 };
 
-class SetHiddenWorker : public Napi::AsyncWorker {
+class SetHiddenWorker : public SafeAsyncWorker {
 public:
   SetHiddenWorker(std::string path, bool hidden,
                   Napi::Promise::Deferred deferred);
@@ -32,4 +33,4 @@ private:
   Napi::Promise::Deferred deferred_;
 };
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/volume_metadata.cpp

@@ -4,6 +4,7 @@
 #include "../common/debug_log.h"
 #include "../common/fd_guard.h"
 #include "../common/path_security.h"
+#include "../common/shutdown.h"
 #include "../common/volume_utils.h"
 #include "./da_mutex.h"
 #include "./fs_meta.h"
@@ -76,6 +77,11 @@ public:
   void Execute() override {
     DEBUG_LOG("[GetVolumeMetadataWorker] Executing for mount point: %s",
               mountPoint.c_str());
+    if (IsShuttingDown()) {
+      // Avoid kicking off blocking IOKit/DA calls during env teardown.
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       // Validate and canonicalize mount point using realpath()
       // This follows Apple's Secure Coding Guide recommendations
@@ -207,6 +213,14 @@ private:
     DEBUG_LOG("[GetVolumeMetadataWorker] Getting Disk Arbitration info for: %s",
               mountPoint.c_str());
 
+    if (IsShuttingDown()) {
+      // IOServiceGetMatchingService is uncancellable; if we're already in
+      // teardown, surface a partial result rather than block FreeEnvironment.
+      metadata.status = "partial";
+      metadata.error = "shutdown in progress";
+      return;
+    }
+
     // Check if this is a network filesystem
     if (metadata.fstype == "smbfs" || metadata.fstype == "nfs" ||
         metadata.fstype == "afpfs" || metadata.fstype == "webdav") {
@@ -370,4 +384,4 @@ Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/darwin/volume_mount_points.cpp

@@ -2,6 +2,7 @@
 #include "../common/volume_mount_points.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "../common/shutdown.h"
 #include "./da_mutex.h"
 #include "./fs_meta.h"
 #include "./raii_utils.h"
@@ -13,7 +14,7 @@
 
 namespace FSMeta {
 
-class GetVolumeMountPointsWorker : public Napi::AsyncWorker {
+class GetVolumeMountPointsWorker : public SafeAsyncWorker {
 private:
   Napi::Promise::Deferred deferred_;
   std::vector<MountPoint> mountPoints_;
@@ -22,11 +23,15 @@ private:
 public:
   GetVolumeMountPointsWorker(const Napi::Promise::Deferred &deferred,
                              uint32_t timeoutMs = 5000)
-      : Napi::AsyncWorker(deferred.Env()), deferred_(deferred),
+      : SafeAsyncWorker(deferred.Env()), deferred_(deferred),
         timeoutMs_(timeoutMs) {}
 
   void Execute() override {
     DEBUG_LOG("[GetVolumeMountPointsWorker] Executing");
+    if (IsShuttingDown()) {
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       MountBufferRAII mntbuf;
       // Use MNT_NOWAIT for better performance - we'll verify accessibility
@@ -57,6 +62,10 @@ public:
       {
         std::lock_guard<std::mutex> lock(g_diskArbitrationMutex);
 
+        if (IsShuttingDown()) {
+          return;
+        }
+
         DASessionRAII session(DASessionCreate(kCFAllocatorDefault));
         if (session.isValid()) {
           static dispatch_queue_t da_queue = dispatch_queue_create(
@@ -66,6 +75,10 @@ public:
         }
 
         for (int j = 0; j < count; j++) {
+          if (IsShuttingDown()) {
+            return;
+          }
+
           MountPoint mp;
           mp.mountPoint = mntbuf.get()[j].f_mntonname;
           mp.fstype = mntbuf.get()[j].f_fstypename;
@@ -88,6 +101,10 @@ public:
       const size_t maxConcurrentChecks = 4; // Limit concurrent access checks
 
       for (size_t i = 0; i < allMountPoints.size(); i += maxConcurrentChecks) {
+        if (IsShuttingDown()) {
+          return;
+        }
+
         std::vector<std::future<std::pair<std::string, bool>>> futures;
         std::vector<MountPoint *> batchPtrs;
 
@@ -182,7 +199,12 @@ public:
       result[i] = mountPoints_[i].ToObject(env);
     }
 
-    deferred_.Resolve(result);
+    SafeResolve(deferred_, result);
+  }
+
+  void OnError(const Napi::Error &error) override {
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 };
 
@@ -202,4 +224,4 @@ Napi::Promise GetVolumeMountPoints(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/linux/volume_metadata.cpp

@@ -27,6 +27,10 @@ public:
   }
 
   void Execute() override {
+    if (IsShuttingDown()) {
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       DEBUG_LOG("[LinuxMetadataWorker] starting statvfs for %s",
                 mountPoint.c_str());
@@ -181,4 +185,4 @@ Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/windows/hidden.cpp

@@ -1,6 +1,7 @@
 // src/windows/hidden.cpp
 #include "hidden.h"
 #include "../common/debug_log.h"
+#include "../common/shutdown.h"
 #include "error_utils.h"
 #include "security_utils.h"
 
@@ -36,14 +37,14 @@ public:
 };
 } // anonymous namespace
 
-class GetHiddenWorker : public Napi::AsyncWorker {
+class GetHiddenWorker : public SafeAsyncWorker {
   const std::string path;
   bool result = false;
   Napi::Promise::Deferred deferred;
 
 public:
   GetHiddenWorker(Napi::Env env, std::string p, Napi::Promise::Deferred def)
-      : Napi::AsyncWorker(env), path(std::move(p)), deferred(def) {}
+      : SafeAsyncWorker(env), path(std::move(p)), deferred(def) {}
 
   void Execute() override {
     try {
@@ -104,17 +105,17 @@ public:
     DEBUG_LOG("[GetHiddenWorker] OnOK called, result=%s",
               result ? "true" : "false");
     Napi::HandleScope scope(Env());
-    deferred.Resolve(Napi::Boolean::New(Env(), result));
+    SafeResolve(deferred, Napi::Boolean::New(Env(), result));
   }
 
   void OnError(const Napi::Error &e) override {
     DEBUG_LOG("[GetHiddenWorker] OnError called with: %s", e.Message().c_str());
     Napi::HandleScope scope(Env());
-    deferred.Reject(e.Value());
+    SafeReject(deferred, e.Value());
   }
 };
 
-class SetHiddenWorker : public Napi::AsyncWorker {
+class SetHiddenWorker : public SafeAsyncWorker {
   const std::string path;
   const bool value;
   Napi::Promise::Deferred deferred;
@@ -122,7 +123,7 @@ class SetHiddenWorker : public Napi::AsyncWorker {
 public:
   SetHiddenWorker(Napi::Env env, std::string p, bool v,
                   Napi::Promise::Deferred def)
-      : Napi::AsyncWorker(env), path(std::move(p)), value(v), deferred(def) {}
+      : SafeAsyncWorker(env), path(std::move(p)), value(v), deferred(def) {}
 
   void Execute() override {
     try {
@@ -144,12 +145,12 @@ public:
 
   void OnOK() override {
     Napi::HandleScope scope(Env());
-    deferred.Resolve(Napi::Boolean::New(Env(), true));
+    SafeResolve(deferred, Napi::Boolean::New(Env(), true));
   }
 
   void OnError(const Napi::Error &e) override {
     Napi::HandleScope scope(Env());
-    deferred.Reject(e.Value());
+    SafeReject(deferred, e.Value());
   }
 };
 
@@ -195,4 +196,4 @@ Napi::Promise SetHiddenAttribute(const Napi::CallbackInfo &info) {
   }
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/windows/volume_metadata.cpp

@@ -154,6 +154,10 @@ private:
   VolumeMetadataOptions options_;
 
   void Execute() override {
+    if (IsShuttingDown()) {
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       // Get drive status first
       DriveStatus status = CheckDriveStatus(mountPoint);
@@ -250,4 +254,4 @@ Napi::Value GetVolumeMetadata(const Napi::CallbackInfo &info) {
   return deferred.Promise();
 }
 
-} // namespace FSMeta
+} // namespace FSMeta

package/src/windows/volume_mount_points.cpp

@@ -2,6 +2,7 @@
 #include "../common/volume_mount_points.h"
 #include "../common/debug_log.h"
 #include "../common/error_utils.h"
+#include "../common/shutdown.h"
 #include "drive_status.h"
 #include "fs_meta.h"
 #include "security_utils.h"
@@ -21,7 +22,7 @@ struct DriveStringsBuffer {
       : buffer(std::make_unique<WCHAR[]>(size)) {}
 };
 
-class GetVolumeMountPointsWorker : public Napi::AsyncWorker {
+class GetVolumeMountPointsWorker : public SafeAsyncWorker {
 
 private:
   Napi::Promise::Deferred deferred_;
@@ -31,10 +32,14 @@ private:
 public:
   GetVolumeMountPointsWorker(const Napi::Promise::Deferred &deferred,
                              uint32_t timeoutMs = 5000)
-      : Napi::AsyncWorker(deferred.Env()), deferred_(deferred),
+      : SafeAsyncWorker(deferred.Env()), deferred_(deferred),
         timeoutMs_(timeoutMs) {}
 
   void Execute() override {
+    if (IsShuttingDown()) {
+      SetError("fs-metadata: shutdown in progress");
+      return;
+    }
     try {
       DEBUG_LOG("[GetVolumeMountPoints] getting logical drive strings size");
       DWORD size = GetLogicalDriveStringsW(0, nullptr);
@@ -74,12 +79,19 @@ public:
       }
 
       // Check all drive statuses in parallel
+      if (IsShuttingDown()) {
+        return;
+      }
       auto statuses = CheckDriveStatus(paths, timeoutMs_);
 
       // Build mount points from results
       mountPoints_.reserve(paths.size());
 
       for (size_t i = 0; i < paths.size(); i++) {
+        if (IsShuttingDown()) {
+          return;
+        }
+
         MountPoint mp;
         mp.mountPoint = paths[i];
         mp.status = DriveStatusToString(statuses[i]);
@@ -115,6 +127,7 @@ public:
   }
 
   void OnOK() override {
+    Napi::HandleScope scope(Env());
     auto env = Env();
     Napi::Array result = Napi::Array::New(env, mountPoints_.size());
 
@@ -122,7 +135,12 @@ public:
       result[i] = mountPoints_[i].ToObject(env);
     }
 
-    deferred_.Resolve(result);
+    SafeResolve(deferred_, result);
+  }
+
+  void OnError(const Napi::Error &error) override {
+    Napi::HandleScope scope(Env());
+    SafeReject(deferred_, error.Value());
   }
 
 }; // class GetVolumeMountPointsWorker
@@ -140,4 +158,4 @@ Napi::Promise GetVolumeMountPoints(const Napi::CallbackInfo &info) {
   worker->Queue();
   return deferred.Promise();
 }
-} // namespace FSMeta
+} // namespace FSMeta