@depup/nx 23.1.2-depup.1 → 23.2.0-depup.0

package/dist/src/daemon/message-types/daemon-message.d.ts

@@ -23,7 +23,8 @@ type WorkspaceScopedMessage = {
 };
 /**
  * A message from a different workspace — two sharing an NX_SOCKET_DIR — must not
- * be processed. Compared directly; both come from the same resolution.
+ * be processed. Roots are normalized first so that a workspace does not look
+ * foreign to itself; see {@link normalizeWorkspaceRoot}.
  */
 export declare function isForeignWorkspaceMessage(msg: WorkspaceScopedMessage, receiverWorkspaceRoot: string): boolean;
 /**

package/dist/src/daemon/message-types/daemon-message.js

@@ -3,18 +3,41 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isDaemonMessage = isDaemonMessage;
 exports.isForeignWorkspaceMessage = isForeignWorkspaceMessage;
 exports.assertNotForeignWorkspaceMessage = assertNotForeignWorkspaceMessage;
+const node_path_1 = require("node:path");
 function isDaemonMessage(msg) {
     return typeof msg === 'object' && msg && 'type' in msg;
 }
+/**
+ * Puts a workspace root into a form two independently-resolved spellings of the
+ * same directory agree on.
+ *
+ * The sender's root and the receiver's root do not always come out of the same
+ * branch of `workspaceRootInner`: one side can be handed `NX_WORKSPACE_ROOT_PATH`
+ * verbatim while the other walks up from `process.cwd()`. On Windows those two
+ * sources routinely disagree on the case of the drive letter — an editor or
+ * agent may export `d:\repo` while `process.cwd()` reports `D:\repo` — and on
+ * separators. Both address the same directory: Windows paths are
+ * case-insensitive, and a drive letter is case-insensitive without exception.
+ *
+ * POSIX roots keep their case, where `/repo` and `/REPO` really can be two
+ * directories.
+ */
+function normalizeWorkspaceRoot(workspaceRoot) {
+    return process.platform === 'win32'
+        ? node_path_1.win32.normalize(workspaceRoot).toLowerCase()
+        : node_path_1.posix.normalize(workspaceRoot);
+}
 /**
  * A message from a different workspace — two sharing an NX_SOCKET_DIR — must not
- * be processed. Compared directly; both come from the same resolution.
+ * be processed. Roots are normalized first so that a workspace does not look
+ * foreign to itself; see {@link normalizeWorkspaceRoot}.
  */
 function isForeignWorkspaceMessage(msg, receiverWorkspaceRoot) {
     if (msg.workspaceRoot === undefined) {
         return false;
     }
-    return msg.workspaceRoot !== receiverWorkspaceRoot;
+    return (normalizeWorkspaceRoot(msg.workspaceRoot) !==
+        normalizeWorkspaceRoot(receiverWorkspaceRoot));
 }
 /**
  * Throws on a message this receiver must not act on. The daemon catches it and

package/dist/src/daemon/sandbox-socket-hint.d.ts

@@ -0,0 +1,27 @@
+export interface SandboxSocketHintOptions {
+    /**
+     * Pass `true` only when an errno proves the operating system refused the
+     * socket (`EPERM`/`EACCES` on a bind or connect). Most callers reach this
+     * hint holding a failure that denied permission only explains — a worker
+     * that died before it reported anything, an internal daemon error — and for
+     * those the lead line offers the cause rather than asserting it.
+     */
+    certain?: boolean;
+}
+/**
+ * Guidance for a unix socket Nx was not allowed to use. The lead line names
+ * denied permission, which is the part Nx can observe; a sandbox is the most
+ * common source but not the only one, so which remedy applies is left to the
+ * list rather than decided in the first sentence.
+ *
+ * Every sandbox-shaped line — the `configure-ai-agents` remediation, the
+ * per-agent setting, the knowledge base link — is dropped unless a sandbox is
+ * actually running. A root-owned socket dir on a plain workstation reaches this
+ * hint too, and there the permission line is the whole truth, so it is stated
+ * outright rather than offered as the one item of a list.
+ *
+ * Lives in its own module (rather than the daemon client) so that plugin
+ * workers and the plugin host can use it without pulling in the daemon
+ * client's module-level `DaemonClient` singleton.
+ */
+export declare function sandboxSocketHint({ certain, }?: SandboxSocketHintOptions): string[];

package/dist/src/daemon/sandbox-socket-hint.js

@@ -0,0 +1,136 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.sandboxSocketHint = sandboxSocketHint;
+const native_1 = require("../native");
+const is_sandbox_1 = require("../utils/is-sandbox");
+const nx_tmp_dir_1 = require("../utils/nx-tmp-dir");
+/**
+ * The containers a sandbox has to allow, best first — not the directory finally
+ * used. Socket resolution walks a chain and the winning tier depends on what it
+ * could establish, so naming one root would be wrong wherever the other was
+ * picked. These are also the paths an allowlist entry covers: everything Nx
+ * binds lives beneath them.
+ *
+ * The home root is shown as the literal `~/.nx` rather than expanded, because a
+ * committed allowlist entry has to expand per user to be worth sharing.
+ *
+ * A configured NX_SOCKET_DIR overrides the chain entirely, so it is named on its
+ * own — pointing someone at the default roots when their sockets are somewhere
+ * else is worse than saying nothing. `||` rather than `??` matches how
+ * `tmp-dir` reads it: an empty value means unset.
+ *
+ * Read from `utils/nx-tmp-dir` rather than from `daemon/tmp-dir`, whose module
+ * scope establishes directories and resolves a socket tier on import. Plugin
+ * workers print this hint, and must not pay that to do it.
+ */
+function socketRoots() {
+    const configured = process.env.NX_SOCKET_DIR || process.env.NX_DAEMON_SOCKET_DIR;
+    if (configured) {
+        return configured;
+    }
+    return [nx_tmp_dir_1.NX_TMP_DIR, nx_tmp_dir_1.NX_HOME_TMP_DIR ? '~/.nx' : undefined]
+        .filter(Boolean)
+        .join(' or ');
+}
+/**
+ * Guidance for a unix socket Nx was not allowed to use. The lead line names
+ * denied permission, which is the part Nx can observe; a sandbox is the most
+ * common source but not the only one, so which remedy applies is left to the
+ * list rather than decided in the first sentence.
+ *
+ * Every sandbox-shaped line — the `configure-ai-agents` remediation, the
+ * per-agent setting, the knowledge base link — is dropped unless a sandbox is
+ * actually running. A root-owned socket dir on a plain workstation reaches this
+ * hint too, and there the permission line is the whole truth, so it is stated
+ * outright rather than offered as the one item of a list.
+ *
+ * Lives in its own module (rather than the daemon client) so that plugin
+ * workers and the plugin host can use it without pulling in the daemon
+ * client's module-level `DaemonClient` singleton.
+ */
+function sandboxSocketHint({ certain = false, } = {}) {
+    const roots = socketRoots();
+    const sandboxRemedy = sandboxSpecificRemedy(roots, certain);
+    const lead = certain
+        ? `Nx was denied permission to use its unix socket under ${roots}.`
+        : `Nx could not use its unix socket under ${roots}. Denied permission on that directory is a common cause.`;
+    const permissionRemedy = `Get permission to create sockets under ${roots}, or set NX_SOCKET_DIR to a directory you do have permission for.`;
+    if (sandboxRemedy.length === 0) {
+        return [lead, permissionRemedy];
+    }
+    return [
+        lead,
+        'To fix this, do one of the following:',
+        // Only Claude Code: the generator's `sandbox` block sits inside
+        // `hasAgent('claude')`, so offering this to a Codex or Copilot CLI user
+        // sends them to a command that writes nothing they need.
+        ...((0, native_1.detectAiAgent)() === 'claude'
+            ? [
+                '  - Run `nx configure-ai-agents` to write the sandbox allowances Nx needs. Agent sandboxes usually block writes to their own settings file, so this may have to be run from a regular terminal rather than through the agent.',
+            ]
+            : []),
+        ...sandboxRemedy.map((remedy) => `  - ${remedy}`),
+        `  - ${permissionRemedy}`,
+        'See https://nx.dev/docs/kb/nx-sandbox-unix-sockets for details.',
+    ];
+}
+/**
+ * The per-agent form of "allow sockets under these roots", or nothing at all
+ * when nothing indicates a sandbox.
+ *
+ * A detected agent is not itself that indication: every Claude Code session sets
+ * `CLAUDECODE`, but only a sandboxed one sets `SANDBOX_RUNTIME` (measured on
+ * 2.1.248 with `sandbox.enabled` both ways). What counts is `isSandbox()`, or —
+ * for a *known* agent — an errno proving the socket was refused. Copilot CLI
+ * needs that second arm: its sandbox sets no variable `isSandbox()` reads
+ * (measured on 1.0.80, where a bind under both roots is refused while `$TMPDIR`
+ * succeeds), so the errno is the only evidence Nx ever gets. An unknown
+ * environment gets no such benefit, because there a refusal is just a refusal —
+ * a root-owned socket dir left by `sudo nx` reads identically.
+ *
+ * The agent then decides *which* setting to name, because each sandbox gates
+ * socket creation on something different and a single generic sentence sends at
+ * least one of them to a setting that does not exist:
+ *
+ * - Claude Code gates on the path allowlist. A scoped `allowUnixSockets` entry
+ *   covers binding as well as connecting, so it is sufficient and preferable to
+ *   `allowAllUnixSockets`, which opens every socket on the machine.
+ * - Codex gates on `network_access` instead, and has no path-scoped socket
+ *   setting. `writable_roots` alone does not unblock a bind. That grant is a
+ *   broad one, so the line says what it costs rather than presenting it as
+ *   equivalent to the scoped entries.
+ * - Copilot CLI gates on the path like Claude, but reads its sandbox policy
+ *   only from the user-level settings file, so this is the one agent
+ *   `configure-ai-agents` cannot configure by writing into the workspace.
+ *
+ * Any other agent, or none, leaves the setting unknown, so the fallback can only
+ * describe the grant.
+ */
+function sandboxSpecificRemedy(roots, certain) {
+    const sandboxed = (0, is_sandbox_1.isSandbox)();
+    const agent = (0, native_1.detectAiAgent)();
+    const knownAgent = agent === 'claude' || agent === 'codex' || agent === 'copilot-cli';
+    if (knownAgent && !sandboxed && !certain) {
+        return [];
+    }
+    switch (agent) {
+        case 'claude':
+            return [
+                `Add ${roots} to \`sandbox.network.allowUnixSockets\` and to \`sandbox.filesystem.allowRead\`/\`allowWrite\` in \`.claude/settings.json\`. The scoped entry covers creating sockets, not only connecting to them.`,
+            ];
+        case 'copilot-cli':
+            return [
+                `Add ${roots} to \`sandbox.userPolicy.filesystem.readwritePaths\` in \`~/.copilot/settings.json\`. Copilot CLI reads sandbox policy only from that user-level file, so a copy committed to the workspace has no effect.`,
+            ];
+        case 'codex':
+            return [
+                `In \`~/.codex/config.toml\`, set \`sandbox_workspace_write.network_access\` to true and add ${roots} to \`sandbox_workspace_write.writable_roots\`. Codex has no setting that scopes sockets to a path, and \`network_access\` also grants general network access, so this is a broader grant than the other agents need.`,
+            ];
+        default:
+            return sandboxed
+                ? [
+                    `Allow your sandbox to create unix sockets under ${roots}, not only connect to them, and grant read and write on those directories.`,
+                ]
+                : [];
+    }
+}

package/dist/src/daemon/server/client-socket-context.d.ts

@@ -7,7 +7,7 @@ export declare function getTopicSubscribers(topic: ProgressTopic): Set<Socket>;
 export declare function assertOnDaemon(helperName: string): void;
 /**
  * Writes a streaming message over the given socket using the daemon's
- * configured serialization format and terminated with MESSAGE_END_SEQ.
+ * configured serialization format, length-prefixed like any other message.
  * Errors are logged to the daemon's stdout (redirected to the daemon
  * log) rather than propagated — a disconnected client shouldn't tear
  * down the current request handler or other subscribers.

package/dist/src/daemon/server/client-socket-context.js

@@ -7,7 +7,6 @@ exports.assertOnDaemon = assertOnDaemon;
 exports.writeStreamingMessage = writeStreamingMessage;
 exports.sendProgressMessageToTopic = sendProgressMessageToTopic;
 exports.sendEmitLogMessageToTopic = sendEmitLogMessageToTopic;
-const consume_messages_from_socket_1 = require("../../utils/consume-messages-from-socket");
 const is_on_daemon_1 = require("../is-on-daemon");
 const logger_1 = require("../logger");
 const streaming_messages_1 = require("../message-types/streaming-messages");
@@ -43,7 +42,7 @@ function assertOnDaemon(helperName) {
 }
 /**
  * Writes a streaming message over the given socket using the daemon's
- * configured serialization format and terminated with MESSAGE_END_SEQ.
+ * configured serialization format, length-prefixed like any other message.
  * Errors are logged to the daemon's stdout (redirected to the daemon
  * log) rather than propagated — a disconnected client shouldn't tear
  * down the current request handler or other subscribers.
@@ -51,7 +50,7 @@ function assertOnDaemon(helperName) {
 function writeStreamingMessage(socket, payload, description) {
     try {
         logger_1.serverLogger.log('Streaming message to client:', description);
-        socket.write((0, socket_utils_1.serialize)(payload) + consume_messages_from_socket_1.MESSAGE_END_SEQ, (err) => {
+        (0, socket_utils_1.sendMessage)(socket, payload, undefined, (err) => {
             if (err) {
                 console.log(`Streaming message write error (client likely disconnected): ${err.message}`);
             }

package/dist/src/daemon/server/dotenv-graph-changes.d.ts

@@ -0,0 +1,97 @@
+import type { ProjectGraph } from '../../config/project-graph';
+import { type WatchEvent } from '../../native';
+export interface DotEnvChangeClassification {
+    invalidating: string[];
+    unclassified: WatchEvent[];
+}
+/**
+ * Splits the change events into `invalidating`: the paths with the dotenv name
+ * shape getEnvPathsForTask loads (`.env[.<id>]` / `.<id>.env` variants), under
+ * the workspace root or a project root, whose content actually changed; and
+ * `unclassified`: the dotenv-shaped events under no known root. The
+ * invalidating names are a superset of what any task loads: target and
+ * configuration names are unknown here, so `.env.staging` is reported whether
+ * or not a task loads it. The daemon uses this to refresh its graph cache so
+ * createNodes re-resolves config that reads process.env.
+ *
+ * Only the workspace root and project roots invalidate: getEnvPathsForTask
+ * loads dotenv files from those, never from an arbitrary subdirectory (e.g. one
+ * under node_modules), and the outputs watcher spans the whole workspace root.
+ * An unclassified event is not necessarily irrelevant, though: the graph it was
+ * classified against can predate the file's project root (none is committed
+ * during the initial computation, and a replaced graph lacks a project that
+ * computation is adding), so the caller queues it for replay against the next
+ * graph a computation is about to serve rather than dropping it.
+ *
+ * Known limitation: a `.nxignore`d dotenv file never reaches this watcher (the
+ * native watcher applies `.nxignore` even with `use_ignore: false`), so a warm
+ * edit of one does not invalidate the graph. The cold path still resolves it:
+ * getGraphTimeDotEnvForTask reads dotenv from disk directly.
+ */
+export declare function classifyDotEnvChanges(changeEvents: WatchEvent[], projectGraph: ProjectGraph | undefined): DotEnvChangeClassification;
+/**
+ * `generation` is the recomputation generation current at queue time; the
+ * drain compares it against the serving computation's generation to prove
+ * whether that computation started before the event arrived.
+ */
+export declare function queuePendingDotEnvEvents(paths: string[], generation: number): void;
+/**
+ * Takes and clears the queued unclassified events, returning the paths that
+ * are dotenv files under a root of `projectGraph` and were queued at or after
+ * `sinceGeneration` (the serving computation's generation). A path queued
+ * earlier is dropped safely: the computation claimed its generation after the
+ * event was queued, so it read the file after the edit landed. Content hashes
+ * are neither consulted nor recorded here, and any hash recorded for a
+ * drained path is dropped: a hash taken mid-computation is not proof any
+ * served graph observed those bytes (the computation may read intermediate
+ * content), so suppressing a later event on it could leave the graph stale.
+ * `overflowed` means events were lost at or after `sinceGeneration`, so the
+ * caller cannot prove its graph fresh and must invalidate; an overflow
+ * recorded earlier is dropped by the same rule as a queued entry. A relevant
+ * overflow also drops every recorded hash: with events lost, a retained hash
+ * (even for a path that invalidated directly and never entered the queue)
+ * could suppress a later event over intermediate bytes read by the successor
+ * this drain forces. That successor is already being forced, so clearing
+ * adds no recomputation.
+ *
+ * A stamp records callback time, not edit time, so an event whose edit a
+ * workspace-watcher-triggered computation already observed can still
+ * invalidate it: one redundant recompute, accepted because the callback
+ * cannot prove which side of that computation's file read the edit landed on.
+ */
+export declare function drainPendingDotEnvEvents(projectGraph: ProjectGraph | undefined, sinceGeneration: number): {
+    invalidating: string[];
+    overflowed: boolean;
+};
+/**
+ * Whether the queue holds evidence that a computation at `sinceGeneration`
+ * may have read a dotenv file before a reported edit landed: an entry or an
+ * overflow stamped at or after that generation. Consumes nothing and
+ * classifies against no roots: the error paths use this to decide on a retry,
+ * where there may be no graph to classify against, and a spurious retry costs
+ * one recompute on an already failing path. A persistent error retries once,
+ * because the retry's successor claims a generation above every stamp
+ * recorded so far.
+ */
+export declare function hasPendingDotEnvEvidence(sinceGeneration: number): boolean;
+/**
+ * Like hasPendingDotEnvEvidence, but classifies each entry against the roots
+ * of `projectGraph`: evidence is an overflow stamped at or after
+ * `sinceGeneration`, or an entry so stamped whose path is a dotenv file under
+ * one of the graph's roots. The warm-reuse check uses this, where the graph
+ * the cache serves exists and is exactly what a recompute would refresh;
+ * skipping paths under none of its roots avoids recomputing for events only
+ * a future graph could classify, and consuming nothing leaves those entries
+ * queued for that computation's drain.
+ */
+export declare function hasRelevantPendingDotEnvEvidence(projectGraph: ProjectGraph | undefined, sinceGeneration: number): boolean;
+/**
+ * Drops every recorded content hash. Each computation clears on claiming its
+ * generation, bounding every hash to the window since the last claim: an
+ * older hash is not proof the graph a successor serves observed those bytes,
+ * and kept, it could suppress a callback that lands while the successor
+ * reads. The error-path retry and the warm-reuse check also clear when they
+ * force a successor while preserving the queue for its drain.
+ */
+export declare function clearDotEnvFileHashes(): void;
+export declare function _resetPendingDotEnvEvents(): void;

package/dist/src/daemon/server/dotenv-graph-changes.js

@@ -0,0 +1,284 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.classifyDotEnvChanges = classifyDotEnvChanges;
+exports.queuePendingDotEnvEvents = queuePendingDotEnvEvents;
+exports.drainPendingDotEnvEvents = drainPendingDotEnvEvents;
+exports.hasPendingDotEnvEvidence = hasPendingDotEnvEvidence;
+exports.hasRelevantPendingDotEnvEvidence = hasRelevantPendingDotEnvEvidence;
+exports.clearDotEnvFileHashes = clearDotEnvFileHashes;
+exports._resetPendingDotEnvEvents = _resetPendingDotEnvEvents;
+const node_path_1 = require("node:path");
+const native_1 = require("../../native");
+const workspace_root_1 = require("../../utils/workspace-root");
+// Last-seen content hash per dotenv file, so a byte-identical rewrite (an editor
+// save that changes nothing) does not invalidate the graph cache.
+const dotEnvFileHashes = new Map();
+// getEnvPathsForTask loads `.env`, `.env.local`, `.local.env` and the
+// target-scoped `.env.<id>[.local]` / `.<id>[.local].env` variants. The `<id>`
+// (a target or configuration name) may itself contain `/`, so the name is
+// matched relative to the owning root rather than by basename.
+const DOTENV_PREFIXED = /^\.env(\..+)?$/;
+const DOTENV_SUFFIXED = /^\..+\.env$/;
+function isDotEnvName(name) {
+    return DOTENV_PREFIXED.test(name) || DOTENV_SUFFIXED.test(name);
+}
+/**
+ * Splits the change events into `invalidating`: the paths with the dotenv name
+ * shape getEnvPathsForTask loads (`.env[.<id>]` / `.<id>.env` variants), under
+ * the workspace root or a project root, whose content actually changed; and
+ * `unclassified`: the dotenv-shaped events under no known root. The
+ * invalidating names are a superset of what any task loads: target and
+ * configuration names are unknown here, so `.env.staging` is reported whether
+ * or not a task loads it. The daemon uses this to refresh its graph cache so
+ * createNodes re-resolves config that reads process.env.
+ *
+ * Only the workspace root and project roots invalidate: getEnvPathsForTask
+ * loads dotenv files from those, never from an arbitrary subdirectory (e.g. one
+ * under node_modules), and the outputs watcher spans the whole workspace root.
+ * An unclassified event is not necessarily irrelevant, though: the graph it was
+ * classified against can predate the file's project root (none is committed
+ * during the initial computation, and a replaced graph lacks a project that
+ * computation is adding), so the caller queues it for replay against the next
+ * graph a computation is about to serve rather than dropping it.
+ *
+ * Known limitation: a `.nxignore`d dotenv file never reaches this watcher (the
+ * native watcher applies `.nxignore` even with `use_ignore: false`), so a warm
+ * edit of one does not invalidate the graph. The cold path still resolves it:
+ * getGraphTimeDotEnvForTask reads dotenv from disk directly.
+ */
+function classifyDotEnvChanges(changeEvents, projectGraph) {
+    // Outputs batches rarely touch dotenv files, so the O(projects) roots set is
+    // only built once a path clears this superset-of-dotenv-names check.
+    const candidates = changeEvents.filter((event) => mayBeDotEnvPath(event.path));
+    if (candidates.length === 0) {
+        return { invalidating: [], unclassified: [] };
+    }
+    const roots = graphTimeDotEnvRoots(projectGraph);
+    const invalidating = [];
+    const unclassified = [];
+    for (const event of candidates) {
+        const { path, type } = event;
+        if (!isDotEnvUnderRoot(path, roots)) {
+            // A recorded hash stops being proof the graph observed the current
+            // content once an event for the path cannot be classified: the pending
+            // replay can drop it, and a later classified event with the same bytes
+            // would then be suppressed as an unchanged rewrite over a graph that
+            // observed a different state (e.g. the file's absence).
+            dotEnvFileHashes.delete(path);
+            unclassified.push(event);
+            continue;
+        }
+        if (type === "delete" /* EventType.delete */) {
+            // A removed dotenv file drops the vars it set, so the config resolves
+            // differently; there is no content to hash.
+            dotEnvFileHashes.delete(path);
+            invalidating.push(path);
+            continue;
+        }
+        const hash = (0, native_1.hashFile)((0, node_path_1.join)(workspace_root_1.workspaceRoot, path));
+        if (hash !== null && dotEnvFileHashes.get(path) === hash) {
+            continue;
+        }
+        // hashFile returns null on a vanished/unreadable file; when we cannot prove
+        // the content is unchanged, report the path rather than risk a stale graph.
+        if (hash !== null) {
+            dotEnvFileHashes.set(path, hash);
+        }
+        else {
+            dotEnvFileHashes.delete(path);
+        }
+        invalidating.push(path);
+    }
+    return { invalidating, unclassified };
+}
+// Superset of the names both regexes accept: a prefixed name's first segment
+// starts with `.env` and a suffixed name's last segment ends with `.env`, even
+// when the target/configuration identifier contains `/`.
+function mayBeDotEnvPath(path) {
+    // Nearly every outputs path lacks the substring, so check it before the
+    // per-segment split: this runs for every path in every outputs batch.
+    if (!path.includes('.env')) {
+        return false;
+    }
+    return path
+        .split('/')
+        .some((segment) => segment.startsWith('.env') || segment.endsWith('.env'));
+}
+function graphTimeDotEnvRoots(projectGraph) {
+    const roots = new Set(['.']);
+    if (projectGraph) {
+        for (const node of Object.values(projectGraph.nodes)) {
+            roots.add(node.data.root);
+        }
+    }
+    return roots;
+}
+/**
+ * Whether `path` is a dotenv file that getEnvPathsForTask would load from the
+ * workspace root or a project root. For a project root, the name relative to
+ * the root may contain `/` because a target/configuration identifier can, and
+ * every root ancestor is tried, so a nested project root does not shadow a
+ * parent's slash-identifier dotenv. At the workspace root, only
+ * single-segment names match.
+ */
+function isDotEnvUnderRoot(path, roots) {
+    for (let slash = path.lastIndexOf('/'); slash > 0; slash = path.lastIndexOf('/', slash - 1)) {
+        const dir = path.slice(0, slash);
+        // Keep walking past a closer root that yields no dotenv name: the same path
+        // can still be a slash-identifier dotenv for a shallower (parent) root.
+        if (roots.has(dir) && isDotEnvName(path.slice(slash + 1))) {
+            return true;
+        }
+    }
+    // No project-root ancestor: a workspace-root dotenv, single-segment names
+    // only. A deeper path (e.g. `.github/workflows/ci.env`) has the dotenv name
+    // shape only for a target identifier containing `/`; accepting those would
+    // invalidate on every write under such dot-directories.
+    return roots.has('.') && !path.includes('/') && isDotEnvName(path);
+}
+// Paths of dotenv-shaped events whose graph refresh is not provably scheduled:
+// paths under no known root on arrival (the next graph may know the root) and
+// edits to tracked files (the workspace watcher schedules the refresh, but a
+// computation already in flight may have read the file before the edit). Each
+// maps to the recomputation generation current at queue time, so the pre-serve
+// replay can prove whether a computation started before the event arrived.
+const pendingDotEnvEvents = new Map();
+// Bounds daemon-lived growth when nothing drains for a long time. The
+// generation current when the last event was lost stands in for the lost
+// stamps, so overflow follows the same freshness rule as a queued entry.
+const MAX_PENDING_DOTENV_EVENTS = 1024;
+let pendingDotEnvEventsOverflowedAtGeneration;
+/**
+ * `generation` is the recomputation generation current at queue time; the
+ * drain compares it against the serving computation's generation to prove
+ * whether that computation started before the event arrived.
+ */
+function queuePendingDotEnvEvents(paths, generation) {
+    for (const path of paths) {
+        if (pendingDotEnvEvents.size >= MAX_PENDING_DOTENV_EVENTS &&
+            !pendingDotEnvEvents.has(path)) {
+            pendingDotEnvEventsOverflowedAtGeneration = generation;
+            // A lost path never reaches a drain, so its recorded hash would outlive
+            // the queue's deletion discipline and could suppress a later event over
+            // a graph that observed different bytes. Drop it while the identity is
+            // still known.
+            dotEnvFileHashes.delete(path);
+        }
+        else {
+            pendingDotEnvEvents.set(path, generation);
+        }
+    }
+}
+/**
+ * Takes and clears the queued unclassified events, returning the paths that
+ * are dotenv files under a root of `projectGraph` and were queued at or after
+ * `sinceGeneration` (the serving computation's generation). A path queued
+ * earlier is dropped safely: the computation claimed its generation after the
+ * event was queued, so it read the file after the edit landed. Content hashes
+ * are neither consulted nor recorded here, and any hash recorded for a
+ * drained path is dropped: a hash taken mid-computation is not proof any
+ * served graph observed those bytes (the computation may read intermediate
+ * content), so suppressing a later event on it could leave the graph stale.
+ * `overflowed` means events were lost at or after `sinceGeneration`, so the
+ * caller cannot prove its graph fresh and must invalidate; an overflow
+ * recorded earlier is dropped by the same rule as a queued entry. A relevant
+ * overflow also drops every recorded hash: with events lost, a retained hash
+ * (even for a path that invalidated directly and never entered the queue)
+ * could suppress a later event over intermediate bytes read by the successor
+ * this drain forces. That successor is already being forced, so clearing
+ * adds no recomputation.
+ *
+ * A stamp records callback time, not edit time, so an event whose edit a
+ * workspace-watcher-triggered computation already observed can still
+ * invalidate it: one redundant recompute, accepted because the callback
+ * cannot prove which side of that computation's file read the edit landed on.
+ */
+function drainPendingDotEnvEvents(projectGraph, sinceGeneration) {
+    const entries = Array.from(pendingDotEnvEvents.entries());
+    const overflowed = pendingDotEnvEventsOverflowedAtGeneration !== undefined &&
+        pendingDotEnvEventsOverflowedAtGeneration >= sinceGeneration;
+    pendingDotEnvEvents.clear();
+    pendingDotEnvEventsOverflowedAtGeneration = undefined;
+    if (overflowed) {
+        dotEnvFileHashes.clear();
+    }
+    if (entries.length === 0) {
+        return { invalidating: [], overflowed };
+    }
+    const roots = graphTimeDotEnvRoots(projectGraph);
+    const invalidating = [];
+    for (const [path, generation] of entries) {
+        dotEnvFileHashes.delete(path);
+        if (generation >= sinceGeneration && isDotEnvUnderRoot(path, roots)) {
+            invalidating.push(path);
+        }
+    }
+    return { invalidating, overflowed };
+}
+/**
+ * Whether the queue holds evidence that a computation at `sinceGeneration`
+ * may have read a dotenv file before a reported edit landed: an entry or an
+ * overflow stamped at or after that generation. Consumes nothing and
+ * classifies against no roots: the error paths use this to decide on a retry,
+ * where there may be no graph to classify against, and a spurious retry costs
+ * one recompute on an already failing path. A persistent error retries once,
+ * because the retry's successor claims a generation above every stamp
+ * recorded so far.
+ */
+function hasPendingDotEnvEvidence(sinceGeneration) {
+    if (pendingDotEnvEventsOverflowedAtGeneration !== undefined &&
+        pendingDotEnvEventsOverflowedAtGeneration >= sinceGeneration) {
+        return true;
+    }
+    for (const generation of pendingDotEnvEvents.values()) {
+        if (generation >= sinceGeneration) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Like hasPendingDotEnvEvidence, but classifies each entry against the roots
+ * of `projectGraph`: evidence is an overflow stamped at or after
+ * `sinceGeneration`, or an entry so stamped whose path is a dotenv file under
+ * one of the graph's roots. The warm-reuse check uses this, where the graph
+ * the cache serves exists and is exactly what a recompute would refresh;
+ * skipping paths under none of its roots avoids recomputing for events only
+ * a future graph could classify, and consuming nothing leaves those entries
+ * queued for that computation's drain.
+ */
+function hasRelevantPendingDotEnvEvidence(projectGraph, sinceGeneration) {
+    if (pendingDotEnvEventsOverflowedAtGeneration !== undefined &&
+        pendingDotEnvEventsOverflowedAtGeneration >= sinceGeneration) {
+        return true;
+    }
+    let roots;
+    for (const [path, generation] of pendingDotEnvEvents) {
+        if (generation < sinceGeneration) {
+            continue;
+        }
+        if (!roots) {
+            roots = graphTimeDotEnvRoots(projectGraph);
+        }
+        if (isDotEnvUnderRoot(path, roots)) {
+            return true;
+        }
+    }
+    return false;
+}
+/**
+ * Drops every recorded content hash. Each computation clears on claiming its
+ * generation, bounding every hash to the window since the last claim: an
+ * older hash is not proof the graph a successor serves observed those bytes,
+ * and kept, it could suppress a callback that lands while the successor
+ * reads. The error-path retry and the warm-reuse check also clear when they
+ * force a successor while preserving the queue for its drain.
+ */
+function clearDotEnvFileHashes() {
+    dotEnvFileHashes.clear();
+}
+// Test helper: the queue is daemon-lived module state.
+function _resetPendingDotEnvEvents() {
+    pendingDotEnvEvents.clear();
+    pendingDotEnvEventsOverflowedAtGeneration = undefined;
+}

package/dist/src/daemon/server/handle-client-env.d.ts

@@ -0,0 +1,8 @@
+export declare function _setEnvForwardTimeoutMs(ms: number): void;
+/**
+ * Applies an env-carrying client message to the daemon. Must be awaited
+ * before dispatching the message's handler: plugin workers key their disk
+ * caches on their own process env, so a graph request must not reach a worker
+ * whose env still reflects the previous client.
+ */
+export declare function handleClientEnv(env: Record<string, string>): Promise<void>;