Feature request: per-async-context current working directory (AsyncLocalStorage-aware chdir/cwd)

[steve02081504]

Feature request: per-async-context current working directory

Problem

process.chdir() mutates the process-global current working directory. In a single-threaded event loop, multiple async functions interleave at await points and share that one global cwd, so a chdir() inside one task silently changes relative-path resolution for every other concurrently running task:

• fs operations with relative paths
• require.resolve() / ESM resolution
• child_process spawn without an explicit cwd
• anything else that resolves relative to process.cwd()

The conventional try/finally "push/pop" pattern is therefore not safe under concurrency: between chdir(newDir) and the finally { chdir(oldDir) }, any interleaved async task observes a cwd it did not set.

AsyncLocalStorage provides per-async-context state, but process.cwd() / process.chdir() are not ALS-aware, and no built-in mechanism exists for a working directory scoped to an async context (or to a single call).

Suggested directions

1. Make process.cwd() / process.chdir() respect an AsyncLocalStorage-provided override, e.g. process.chdir inside a scoped context only affects that context.
2. Alternatively, add an explicit scoped-run API, e.g. als.run({ cwd: '/foo' }, () => ...) where relative path resolution inside the callback uses /foo while the process cwd stays untouched.
3. At minimum, document in the process.chdir() / fs docs that chdir is process-global and not safe to use across interleaved async operations, since many users assume per-call isolation.

This mirrors thread-local cwd support found in other runtimes and would unblock use cases like per-request build tools, sandboxing, and test runners that currently must spawn child processes (or re-implement path resolution) just to get an isolated working directory.

Related

• Support process.chdir in worker thread #41673 ("Support process.chdir in worker thread", closed) — previously discussed isolating cwd per worker.
• fs APIs already accept an explicit cwd option, but that does not cover process.chdir-style global relative resolution.

Node.js version: current stable (reproducible on any recent version).

[steve02081504]

If accepted, the changes needed would be: (1) make process.chdir() / process.cwd() consult an AsyncLocalStorage-backed override, (2) update fs/child_process relative-path resolution docs, and (3) add tests proving two interleaved async tasks using scoped cwds cannot observe each other's directory. Filing this was prompted by fount (github.com/steve02081504/fount), which hit the global-cwd collision under concurrency and currently avoids process.chdir entirely.

[steve02081504]

Also filed on Deno for parity: denoland/deno#36773

[abhinav-phi]

Hi! I'd like to work on this.

Plan: I'll design the feature against the described behavior, implement it with the project's conventions, add unit/integration tests, and update the docs.

Could you please assign this issue to me? Thanks!

/assign take

[Renegade334]

AsyncLocalStorage isn't a process sandbox, it just tracks JS context. I don't see why there would be any expectation that running syscalls like chdir or umask would be contained to an async scope?

[steve02081504]

Fair point -- we're not expecting the underlying syscall to be contained. chdir/getcwd act on the process-global fd table and genuinely can't be scoped to an async context. But the relative-path resolution that actually breaks under interleaved tasks (fs ops, path.resolve, require.resolve, child_process spawn without cwd) all happens in JS, and process.cwd() is itself a JS-side value kept in sync with libuv -- that layer is exactly what AsyncLocalStorage can override. That's also why the issue proposes an explicit scoped-run API (als.run({ cwd }, fn), option 2) rather than pretending chdir becomes async-local.

fount hit this for real, and the workaround we landed on is instructive. Its code shell runs one AI agent per session, each pinned to its own workspace via a request-level workdir: {machine, path}. Isolation is achieved without chdir: shell spawns get the workspace as the child process cwd, and file operations explicitly resolve relative paths against the workspace instead of process.cwd().

The one thing this can't isolate is JS execution: the agent's JS runs in-process via async_eval -- it's just eval, which takes no cwd and always observes the runtime-global one. When a user opens several sessions at once, different agents share the same thread and would each try to process.chdir() into their own workspace -- clobbering each other and forcing us to bolt on locking/serialization on top. So we simply never call process.chdir. An ALS-aware cwd override would let each session's async_eval see its own working directory without spawning a child process.

Worker threads don't fill this gap either -- process.chdir throws ERR_WORKER_UNSUPPORTED_OPERATION there (#41673), so thread-level isolation isn't on the table and async context is the only remaining JS-level dimension.