From dc0be48a6c4869df28031ad16dbb6bb08163f6ef Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 17:14:42 -0400
Subject: [PATCH 1/8] feat: declare named worker project environments

---
 packages/code/README.md                    |  47 ++++
 packages/code/package-lock.json            |  18 +-
 packages/code/package.json                 |   3 +-
 packages/code/src/cli.ts                   | 249 +++++++++++++++----
 packages/code/src/environment-live.test.ts | 103 ++++++++
 packages/code/src/environment.test.ts      | 165 ++++++++++++
 packages/code/src/environment.ts           | 276 +++++++++++++++++++++
 packages/code/src/protocol.ts              | 239 +++++++++++++++---
 packages/code/src/workspace.ts             |   3 +
 9 files changed, 1022 insertions(+), 81 deletions(-)
 create mode 100644 packages/code/src/environment-live.test.ts
 create mode 100644 packages/code/src/environment.test.ts
 create mode 100644 packages/code/src/environment.ts

diff --git a/packages/code/README.md b/packages/code/README.md
index 87d9dded..22abc705 100644
--- a/packages/code/README.md
+++ b/packages/code/README.md
@@ -652,3 +652,50 @@ To recover a quarantined native root:
 
 The workspace selector in LibreChat must preserve these registered IDs. Adding
 roots here does not grant a principal access or change an agent's selected root.
+# Named project environments
+
+An operator can keep a project definition outside the coding workspace and start
+the worker with `librechat-code run --environment /operator/app.yaml
+--allow-workspace-commands --allow-workspace-writes`. Existing pairing settings
+still identify the machine and its principal. Repeat `--environment` for independent,
+non-overlapping roots (up to 32). Do not combine definitions with workspace directory,
+ID, or name flags or environment variables.
+
+```yaml
+name: app-dev
+root: /projects/app
+repo: example/app
+ref: main
+setup:
+  command: npm ci
+  timeoutMs: 300000
+actions:
+  - name: typecheck
+    command: npm run typecheck
+    timeoutMs: 120000
+```
+
+The root must already exist; relative roots resolve from the YAML file's directory.
+Repository and ref are descriptive metadata, not a clone or checkout instruction.
+No Git repository is required. Definitions are loaded once at startup, hashed into
+the worker's policy identity, and protected from sandbox writes. All definition
+files must be outside every registered root. Unknown fields are rejected.
+
+Setup is an operator-authorized startup command under the configured native sandbox
+policy. It requires commands to be enabled, runs once per worker startup before
+registration, and must be idempotent for restarts. Its timeout is bounded to five
+minutes and captured output to 8 KiB. Setup failure prevents registration. A crash
+or uncertain termination retains the existing workspace quarantine marker; inspect
+the workspace before clearing quarantine. No setup output is sent to the model.
+
+Named actions are fixed commands without model-supplied substitution. The bridge
+advertises only their names and the definition fingerprint, never their shell source
+or host root. A command request can select `environmentAction: { name, fingerprint }`;
+the worker resolves the command from its loaded definition and rejects stale revisions,
+unknown names, other roots, or a changed working directory. Actions use ordinary
+command authorization, queueing, cancellation and quarantine. They never override
+deployment approval rules or expand the pairing's principal scope.
+
+Rollout: update Code API and the LibreChat environment-descriptor consumer before
+enabling this opt-in flag on a worker. Older validators reject the additional metadata.
+Existing workers without `--environment` continue to use their existing registration.
diff --git a/packages/code/package-lock.json b/packages/code/package-lock.json
index ac9affc8..426b950f 100644
--- a/packages/code/package-lock.json
+++ b/packages/code/package-lock.json
@@ -10,7 +10,8 @@
       "license": "Apache-2.0",
       "dependencies": {
         "@anthropic-ai/sandbox-runtime": "0.0.75",
-        "koffi": "3.2.1"
+        "koffi": "3.2.1",
+        "yaml": "2.9.1"
       },
       "bin": {
         "librechat-code": "dist/cli.js"
@@ -414,6 +415,21 @@
       "dev": true,
       "license": "MIT"
     },
+    "node_modules/yaml": {
+      "version": "2.9.1",
+      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.1.tgz",
+      "integrity": "sha512-3NxN8+78OdzbT7C/WjGsyfPAtJaN3FNDsWxv7Y7mcDsT/oOmgW8BpyQQFFBnvZE3j9Y2Sdz1ULFLezL7Eb2yFw==",
+      "license": "ISC",
+      "bin": {
+        "yaml": "bin.mjs"
+      },
+      "engines": {
+        "node": ">= 14.6"
+      },
+      "funding": {
+        "url": "https://github.com/sponsors/eemeli"
+      }
+    },
     "node_modules/zod": {
       "version": "3.25.76",
       "resolved": "https://registry.npmjs.org/zod/-/zod-3.25.76.tgz",
diff --git a/packages/code/package.json b/packages/code/package.json
index 452a8be7..b00ca807 100644
--- a/packages/code/package.json
+++ b/packages/code/package.json
@@ -65,6 +65,7 @@
   },
   "dependencies": {
     "@anthropic-ai/sandbox-runtime": "0.0.75",
-    "koffi": "3.2.1"
+    "koffi": "3.2.1",
+    "yaml": "2.9.1"
   }
 }
diff --git a/packages/code/src/cli.ts b/packages/code/src/cli.ts
index 289b0dc4..324cd6ff 100644
--- a/packages/code/src/cli.ts
+++ b/packages/code/src/cli.ts
@@ -5,6 +5,11 @@ import { realpath, stat } from 'node:fs/promises';
 import { basename, resolve, relative, isAbsolute, sep } from 'node:path';
 
 import { pairBridgeWorker } from './pairing.js';
+import {
+    loadCodeEnvironment,
+    assertEnvironmentDefinitionsOutsideRoots,
+    EnvironmentWorkspaceTools,
+} from './environment.js';
 import { startFileRelay } from './relay.js';
 import { DockerFileRelaySupervisor } from './relay-runtime.js';
 import {
@@ -61,7 +66,8 @@ function workspaceSecurityIdentity(
   configuredToken: string | undefined,
 ): string {
   return (
-    pairedPublicKey ?? required('LIBRECHAT_CODE_WORKER_TOKEN', configuredToken)
+        pairedPublicKey ??
+        required('LIBRECHAT_CODE_WORKER_TOKEN', configuredToken)
   );
 }
 
@@ -70,7 +76,8 @@ function workspaceQuarantinePath(options: {
   workerId: string;
   workspaceRoot?: string;
 }): string {
-  const override = process.env.LIBRECHAT_CODE_WORKSPACE_QUARANTINE_FILE?.trim();
+    const override =
+        process.env.LIBRECHAT_CODE_WORKSPACE_QUARANTINE_FILE?.trim();
   if (override) return override;
   return defaultWorkspaceQuarantinePath({
     ...options,
@@ -88,7 +95,7 @@ function list(value: string | undefined): string[] {
   return (
     value
       ?.split(',')
-      .map((item) => item.trim())
+            .map(item => item.trim())
       .filter(Boolean) ?? []
   );
 }
@@ -127,7 +134,7 @@ function option(args: string[], name: string): string | undefined {
   const index = args.indexOf(name);
   if (index >= 0) return args[index + 1];
   return args
-    .find((value) => value.startsWith(`${name}=`))
+        .find(value => value.startsWith(`${name}=`))
     ?.slice(name.length + 1);
 }
 
@@ -175,7 +182,9 @@ function githubCredentials(): {
     try {
       parsedApiUrl = new URL(apiUrl);
     } catch {
-      throw new Error('LIBRECHAT_CODE_GITHUB_API_URL must be a valid URL');
+            throw new Error(
+                'LIBRECHAT_CODE_GITHUB_API_URL must be a valid URL',
+            );
     }
     apiHost =
       parsedApiUrl.hostname.toLowerCase() === 'api.github.com'
@@ -288,7 +297,7 @@ async function relay(): Promise<void> {
   process.stdout.write(
     `librechat-code: file relay listening at ${handle.url}\n`,
   );
-  await new Promise<void>((resolve) => {
+    await new Promise<void>(resolve => {
     process.once('SIGINT', resolve);
     process.once('SIGTERM', resolve);
   });
@@ -299,6 +308,47 @@ async function run(
   runtimeSessionId?: string,
   args: string[] = [],
 ): Promise<void> {
+    const environmentPaths: string[] = [];
+    for (let i = 0; i < args.length; i++) {
+        if (args[i] === '--environment') {
+            const path = args[++i];
+            if (!path || path.startsWith('--'))
+                throw new Error('--environment requires a YAML file');
+            environmentPaths.push(path);
+        } else if (args[i].startsWith('--environment=')) {
+            const path = args[i].slice('--environment='.length);
+            if (!path) throw new Error('--environment requires a YAML file');
+            environmentPaths.push(path);
+        }
+    }
+    if (environmentPaths.length > 32)
+        throw new Error('At most 32 environments may be registered');
+    const environments = await Promise.all(
+        environmentPaths.map(loadCodeEnvironment),
+    );
+    if (
+        environments.length &&
+        (runtimeSessionId != null ||
+            args.some(arg =>
+                [
+                    '--worker-dir',
+                    '--default-workspace',
+                    '--workspace',
+                    '--workspace-id',
+                    '--workspace-name',
+                ].some(flag => arg === flag || arg.startsWith(`${flag}=`)),
+            ) ||
+            [
+                process.env.LIBRECHAT_CODE_WORKER_DIR,
+                process.env.LIBRECHAT_CODE_DEFAULT_WORKSPACE,
+                process.env.LIBRECHAT_CODE_WORKSPACE_ID,
+                process.env.LIBRECHAT_CODE_WORKSPACE_NAME,
+            ].some(value => value?.trim()))
+    ) {
+        throw new Error(
+            '--environment cannot be combined with workspace directory, ID, or name settings',
+        );
+    }
   const configuredWorkerId = process.env.LIBRECHAT_CODE_WORKER_ID?.trim();
   const configuredIdentityPath =
     process.env.LIBRECHAT_CODE_IDENTITY_FILE?.trim();
@@ -347,7 +397,8 @@ async function run(
     );
   }
   const nsjailDockerMode =
-    runtimeMode === 'docker-nsjail' || runtimeMode === 'docker-macos-nsjail';
+        runtimeMode === 'docker-nsjail' ||
+        runtimeMode === 'docker-macos-nsjail';
   const sandboxEndpoint =
     process.env.LIBRECHAT_CODE_SANDBOX_ENDPOINT ??
     'http://127.0.0.1:2000/api/v2';
@@ -374,16 +425,18 @@ async function run(
     runtimeSessionId == null &&
     (fileRelayUpstream?.length ?? 0) > 0;
   const workspaceId =
+        environments[0]?.definition.name ??
     option(args, '--workspace-id') ??
     process.env.LIBRECHAT_CODE_WORKSPACE_ID?.trim() ??
     'primary';
   const explicitWorkerDirectory =
-    runtimeSessionId == null
+        environments[0]?.definition.root ??
+        (runtimeSessionId == null
       ? nonEmpty(
           option(args, '--worker-dir') ??
             process.env.LIBRECHAT_CODE_WORKER_DIR?.trim(),
         )
-      : undefined;
+            : undefined);
   const useDefaultWorkspace =
     runtimeSessionId == null &&
     (args.includes('--default-workspace') ||
@@ -403,11 +456,25 @@ async function run(
     option(args, '--command-sandbox') ??
     process.env.LIBRECHAT_CODE_COMMAND_SANDBOX?.trim().toLowerCase() ??
     (nsjailDockerMode ? 'runtime' : 'native-srt');
-  if (commandSandboxMode !== 'native-srt' && commandSandboxMode !== 'runtime') {
+    if (
+        commandSandboxMode !== 'native-srt' &&
+        commandSandboxMode !== 'runtime'
+    ) {
     throw new Error(
       'LIBRECHAT_CODE_COMMAND_SANDBOX must be native-srt or runtime',
     );
   }
+    if (environments.length && commandSandboxMode !== 'native-srt') {
+        throw new Error('Environment definitions require native-srt');
+    }
+    if (
+        environments.some(environment => environment.definition.setup) &&
+        !allowWorkspaceCommands
+    ) {
+        throw new Error(
+            'Environment setup requires --allow-workspace-commands',
+        );
+    }
   const nativeProgrammaticEnabled =
     allowWorkspaceCommands &&
     commandSandboxMode === 'native-srt' &&
@@ -486,7 +553,8 @@ async function run(
     }
   }
   const mutationQuarantinePath =
-    (allowWorkspaceWrites || allowWorkspaceCommands) && canonicalWorkerDirectory
+        (allowWorkspaceWrites || allowWorkspaceCommands) &&
+        canonicalWorkerDirectory
       ? workspaceQuarantinePath({
           codeApiUrl,
           workerId,
@@ -508,14 +576,27 @@ async function run(
           root: canonicalWorkerDirectory,
           writable: allowWorkspaceWrites,
           name:
+                      environments[0]?.definition.name ??
             option(args, '--workspace-name') ??
             process.env.LIBRECHAT_CODE_WORKSPACE_NAME?.trim() ??
             (useDefaultWorkspace
               ? workspaceId
-              : defaultWorkspaceName(workerDirectory!, workspaceId)),
+                          : defaultWorkspaceName(
+                                workerDirectory!,
+                                workspaceId,
+                            )),
         },
       ]
     : [];
+    for (const environment of environments.slice(1)) {
+        roots.push({
+            id: environment.definition.name,
+            name: environment.definition.name,
+            root: environment.definition.root,
+            writable: allowWorkspaceWrites,
+        });
+    }
+    assertEnvironmentDefinitionsOutsideRoots(environments, roots);
   for (let i = 0; i < args.length; i++) {
     if (
       args[i] === '--workspace' &&
@@ -551,16 +632,18 @@ async function run(
   if (roots.length > 32)
     throw new Error('At most 32 workspace roots may be registered');
   const rootIdentities = await Promise.all(
-    roots.map((root) => stat(root.root)),
+        roots.map(root => stat(root.root)),
   );
-  const normalized = roots.map((root) => root.root);
+    const normalized = roots.map(root => root.root);
   for (let i = 0; i < roots.length; i++)
     for (let j = 0; j < i; j++) {
       const inside = (a: string, b: string): boolean => {
         const path = relative(a, b);
         return (
           path === '' ||
-          (path !== '..' && !path.startsWith(`..${sep}`) && !isAbsolute(path))
+                    (path !== '..' &&
+                        !path.startsWith(`..${sep}`) &&
+                        !isAbsolute(path))
         );
       };
       if (
@@ -578,7 +661,9 @@ async function run(
     workspaceLeaseSlots > 1 &&
     (!allowWorkspaceCommands || commandSandboxMode !== 'native-srt')
   ) {
-    throw new Error('Concurrent workspace leases require native-srt commands');
+        throw new Error(
+            'Concurrent workspace leases require native-srt commands',
+        );
   }
   if (
     roots.length > 1 &&
@@ -589,7 +674,7 @@ async function run(
     );
   }
   const rootQuarantinePaths = new Map(
-    roots.map((root) => [
+        roots.map(root => [
       root.id,
       workspaceQuarantinePath({
         codeApiUrl,
@@ -676,7 +761,10 @@ async function run(
           token: createHmac(
             'sha256',
             pairedIdentity?.privateKey ??
-              required('LIBRECHAT_CODE_WORKER_TOKEN', configuredToken),
+                          required(
+                              'LIBRECHAT_CODE_WORKER_TOKEN',
+                              configuredToken,
+                          ),
           )
             .update('librechat-code-file-relay-v1')
             .digest('hex'),
@@ -712,8 +800,11 @@ async function run(
           image: runtimeImage,
           ...(nsjailDockerMode && runtimeSessionId == null
             ? (() => {
-                const { seccompProfile, packagesPath, profileRevision } =
-                  nsjailLaunchProfile!;
+                            const {
+                                seccompProfile,
+                                packagesPath,
+                                profileRevision,
+                            } = nsjailLaunchProfile!;
                 return {
                   capabilities: MACOS_NSJAIL_CAPABILITIES,
                   securityOptions: [`seccomp=${seccompProfile}`],
@@ -733,10 +824,12 @@ async function run(
                   httpClient: 'bun' as const,
                   environment: {
                     SANDBOX_USE_CGROUPV2: 'false',
-                    SANDBOX_REMOVE_UMOUNT_AFTER_STARTUP: 'false',
+                                    SANDBOX_REMOVE_UMOUNT_AFTER_STARTUP:
+                                        'false',
                     ...(workspaceMount
                       ? {
-                          SANDBOX_EXTERNAL_WORKSPACE_ENABLED: 'true',
+                                              SANDBOX_EXTERNAL_WORKSPACE_ENABLED:
+                                                  'true',
                           SANDBOX_EXTERNAL_WORKSPACE_ROOT:
                             workspaceMount.target,
                           SANDBOX_EXTERNAL_WORKSPACE_TOKEN:
@@ -745,15 +838,21 @@ async function run(
                       : {}),
                     ...(fileRelayProfile
                       ? {
-                          EGRESS_GATEWAY_URL: fileRelayProfile.url,
+                                              EGRESS_GATEWAY_URL:
+                                                  fileRelayProfile.url,
                           SANDBOX_PRIME_CONCURRENCY: String(
-                            fileRelayLimits!.maxConcurrentRequests,
+                                                  fileRelayLimits!
+                                                      .maxConcurrentRequests,
                           ),
-                          SANDBOX_UPLOAD_CONCURRENCY: String(
-                            fileRelayLimits!.maxConcurrentRequests,
+                                              SANDBOX_UPLOAD_CONCURRENCY:
+                                                  String(
+                                                      fileRelayLimits!
+                                                          .maxConcurrentRequests,
                           ),
-                          SANDBOX_FILE_RELAY_TOKEN: fileRelayProfile.token,
-                          SANDBOX_REQUIRE_EGRESS_MANIFEST: 'true',
+                                              SANDBOX_FILE_RELAY_TOKEN:
+                                                  fileRelayProfile.token,
+                                              SANDBOX_REQUIRE_EGRESS_MANIFEST:
+                                                  'true',
                           SANDBOX_EXECUTION_MANIFEST_PUBLIC_KEY:
                             executionManifestPublicKey!,
                         }
@@ -766,8 +865,10 @@ async function run(
                   bindMounts: [workspaceMount],
                   environment: {
                     SANDBOX_EXTERNAL_WORKSPACE_ENABLED: 'true',
-                    SANDBOX_EXTERNAL_WORKSPACE_ROOT: workspaceMount.target,
-                    SANDBOX_EXTERNAL_WORKSPACE_TOKEN: workspaceCommandToken!,
+                                  SANDBOX_EXTERNAL_WORKSPACE_ROOT:
+                                      workspaceMount.target,
+                                  SANDBOX_EXTERNAL_WORKSPACE_TOKEN:
+                                      workspaceCommandToken!,
                   },
                 }
               : {}),
@@ -781,6 +882,7 @@ async function run(
     commandPolicy,
     protectedPaths: [
       identityPath,
+            ...environments.map(environment => environment.path),
       ...rootQuarantinePaths.values(),
       github.privateKeyPath,
     ].filter((path): path is string => path != null),
@@ -814,7 +916,7 @@ async function run(
       ? roots.length > 1 || workspaceLeaseSlots > 1
         ? new NativeWorkspaceCommandPool(
             new Map(
-              roots.map((root) => [
+                          roots.map(root => [
                 root.id,
                 { ...nativeOptions, workspaceRoot: root.root },
               ]),
@@ -826,7 +928,7 @@ async function run(
   if (allowWorkspaceCommands && workspaceTools) {
     workspaceTools = new SandboxWorkspaceTools({
       workspaceTools,
-      commandWorkspaces: roots.map((root) => root.id),
+            commandWorkspaces: roots.map(root => root.id),
       ...(nativeProgrammaticEnabled
         ? { programmaticLanguages: ['bash'] }
         : {}),
@@ -839,6 +941,12 @@ async function run(
         }),
     });
   }
+    if (workspaceTools && environments.length) {
+        workspaceTools = new EnvironmentWorkspaceTools(
+            workspaceTools,
+            environments,
+        );
+    }
   const capabilities = {
     statefulWorkspace,
     sandboxProfile:
@@ -854,6 +962,11 @@ async function run(
     policyDigest: createHash('sha256')
       .update(policy)
       .update(
+                environments.length
+                    ? `\0environments\0${environments.map(environment => environment.fingerprint).join('\0')}`
+                    : '',
+            )
+            .update(
         allowWorkspaceCommands && commandSandboxMode === 'native-srt'
           ? `\0native-srt\0${serializeNativeSrtCommandPolicy(commandPolicy)}\0${commandAllowedDomains.join('\0')}\0${github.policyIdentity}`
           : '',
@@ -863,7 +976,9 @@ async function run(
     ...(workspaceLeaseSlots > 1
       ? { workspaceLeaseSlots, requiresReadyConfirmation: true }
       : {}),
-    ...(workspaceTools ? { workspaceTools: workspaceTools.capabilities } : {}),
+        ...(workspaceTools
+            ? { workspaceTools: workspaceTools.capabilities }
+            : {}),
   };
   if (!isValidBridgeWorkerCapabilities(capabilities)) {
     await fileRelaySupervisor?.stop().catch(() => undefined);
@@ -874,6 +989,39 @@ async function run(
   try {
     await github.provider?.getCredential(controller.signal);
     await nativeCommandSandbox?.prepare();
+        for (const environment of environments) {
+            const setup = environment.definition.setup;
+            if (!setup || !nativeCommandSandbox) continue;
+            const id = environment.definition.name;
+            const guard = workspaceMutationGuard(
+                rootQuarantinePaths.get(id)!,
+                workerId,
+                id,
+                incarnationId,
+            );
+            await guard.assertAvailable();
+            await guard.arm('Environment setup did not settle', 'setup');
+            const result = await nativeCommandSandbox.execute(
+                {
+                    protocolVersion: 1,
+                    operation: 'execute_command',
+                    workspaceId: id,
+                    command: setup.command,
+                    timeoutMs: setup.timeoutMs,
+                    maxOutputBytes: 8192,
+                },
+                controller.signal,
+            );
+            await guard.clear('setup');
+            if (result.exitCode !== 0 || result.timedOut) {
+                throw new Error(
+                    `Environment ${id} setup failed; inspect the setup command before restarting`,
+                );
+            }
+            process.stdout.write(
+                `librechat-code: environment ${id} prepared\n`,
+            );
+        }
   } catch (error) {
     await nativeCommandSandbox?.close().catch(() => undefined);
     await fileRelaySupervisor?.stop().catch(() => undefined);
@@ -895,7 +1043,7 @@ async function run(
       ...(workspaceLeaseSlots > 1 || roots.length > 1
         ? {
             workspaceQuarantines: new Map(
-              roots.map((root) => [
+                          roots.map(root => [
                 root.id,
                 workspaceMutationGuard(
                   rootQuarantinePaths.get(root.id)!,
@@ -913,7 +1061,8 @@ async function run(
         roots.length === 1
           ? {
               async assertAvailable() {
-                const record = await loadWorkspaceMutationQuarantine(
+                              const record =
+                                  await loadWorkspaceMutationQuarantine(
                   mutationQuarantinePath,
                 );
                 if (record != null) {
@@ -925,15 +1074,18 @@ async function run(
                 }
               },
               async arm(reason) {
-                await saveWorkspaceMutationQuarantine(mutationQuarantinePath, {
+                              await saveWorkspaceMutationQuarantine(
+                                  mutationQuarantinePath,
+                                  {
                   version: 1,
                   workerId,
                   workspaceId,
                   ownerId: incarnationId,
                   quarantinedAt: new Date().toISOString(),
                   reason,
-                });
               },
+                              );
+                          },
               async clear() {
                 await clearWorkspaceMutationQuarantine(
                   mutationQuarantinePath,
@@ -950,7 +1102,7 @@ async function run(
           : undefined,
       onIdentityChange:
         pairedIdentity && identityPath
-          ? async (identity) => {
+                    ? async identity => {
               await saveBridgeIdentity(identityPath, {
                 ...pairedIdentity,
                 credential: identity.credential,
@@ -959,10 +1111,12 @@ async function run(
             }
           : undefined,
       onRegistered: fileRelaySupervisor
-        ? async (registration) => {
+                ? async registration => {
             if (
               registration.registrationGeneration == null ||
-              !Number.isSafeInteger(registration.registrationGeneration) ||
+                          !Number.isSafeInteger(
+                              registration.registrationGeneration,
+                          ) ||
               registration.registrationGeneration < 1
             ) {
               throw new Error(
@@ -975,10 +1129,14 @@ async function run(
             );
           }
         : undefined,
-      onError: (error) => {
+            onError: error => {
         const message =
-          error instanceof Error ? error.message : 'unknown bridge error';
-        process.stderr.write(`librechat-code: reconnecting after ${message}\n`);
+                    error instanceof Error
+                        ? error.message
+                        : 'unknown bridge error';
+                process.stderr.write(
+                    `librechat-code: reconnecting after ${message}\n`,
+                );
       },
     });
     if (runtimeSessionId !== undefined) {
@@ -994,7 +1152,10 @@ async function run(
     if (resetNativeRoot != null) {
       await worker.refreshCredential(controller.signal);
       await worker.registerForMaintenance(controller.signal);
-      await worker.resetNativeWorkspace(resetNativeRoot, controller.signal);
+            await worker.resetNativeWorkspace(
+                resetNativeRoot,
+                controller.signal,
+            );
       process.stdout.write(
         `librechat-code: reset acknowledged for native workspace ${resetNativeRoot}\n`,
       );
diff --git a/packages/code/src/environment-live.test.ts b/packages/code/src/environment-live.test.ts
new file mode 100644
index 00000000..76842efb
--- /dev/null
+++ b/packages/code/src/environment-live.test.ts
@@ -0,0 +1,103 @@
+import assert from 'node:assert/strict';
+import { spawn } from 'node:child_process';
+import { once } from 'node:events';
+import { mkdtemp, mkdir, readFile, writeFile, rm } from 'node:fs/promises';
+import { createServer } from 'node:http';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import test from 'node:test';
+
+for (const succeeds of [true, false]) {
+    test(
+        `real CLI environment setup gates registration (success=${succeeds})`,
+        {
+            skip: process.env.LIBRECHAT_CODE_LIVE_SRT_TESTS !== '1',
+            timeout: 20_000,
+        },
+        async t => {
+            const directory = await mkdtemp(join(tmpdir(), 'code-env-live-'));
+            t.after(() => rm(directory, { recursive: true, force: true }));
+            const root = join(directory, 'project');
+            await mkdir(root);
+            const path = join(directory, 'environment.yaml');
+            await writeFile(
+                path,
+                `name: project\nroot: project\nsetup:\n  command: 'printf prepared > prepared.txt; exit ${succeeds ? 0 : 2}'\n  timeoutMs: 5000\n`,
+            );
+            let registrations = 0;
+            let receive: (() => void) | undefined;
+            const registered = new Promise<void>(resolve => {
+                receive = resolve;
+            });
+            const server = createServer(async (request, response) => {
+                request.resume();
+                if (request.url?.endsWith('/register')) {
+                    registrations++;
+                    assert.equal(
+                        await readFile(join(root, 'prepared.txt'), 'utf8'),
+                        'prepared',
+                    );
+                    receive?.();
+                }
+                response.writeHead(503).end();
+            });
+            await new Promise<void>(resolve =>
+                server.listen(0, '127.0.0.1', resolve),
+            );
+            t.after(() => {
+                server.closeAllConnections();
+                server.close();
+            });
+            const address = server.address();
+            assert.ok(address && typeof address !== 'string');
+            const child = spawn(
+                process.execPath,
+                [
+                    fileURLToPath(new URL('./cli.js', import.meta.url)),
+                    'run',
+                    '--environment',
+                    path,
+                    '--allow-workspace-commands',
+                ],
+                {
+                    env: {
+                        PATH: process.env.PATH,
+                        HOME: process.env.HOME,
+                        TMPDIR: process.env.TMPDIR,
+                        LIBRECHAT_CODE_URL: `http://127.0.0.1:${address.port}/v1`,
+                        LIBRECHAT_CODE_WORKER_ID: 'environment-test',
+                        LIBRECHAT_CODE_WORKER_TOKEN: 'test-only-token',
+                        LIBRECHAT_CODE_WORKSPACE_QUARANTINE_FILE: join(
+                            directory,
+                            'quarantine.json',
+                        ),
+                    },
+                    stdio: ['ignore', 'pipe', 'pipe'],
+                },
+            );
+            const exited = once(child, 'exit');
+            t.after(() => child.kill('SIGKILL'));
+            let stderr = '';
+            child.stderr.on('data', chunk => {
+                stderr += chunk.toString();
+            });
+            if (succeeds) {
+                await Promise.race([
+                    registered,
+                    exited.then(() => {
+                        throw new Error(stderr);
+                    }),
+                ]);
+                child.kill('SIGTERM');
+                await exited;
+                assert.ok(registrations > 0);
+            } else {
+                const [code] = await exited;
+                assert.notEqual(code, 0);
+                assert.match(stderr, /Environment project setup failed/);
+                assert.equal(registrations, 0);
+            }
+        },
+    );
+}
diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
new file mode 100644
index 00000000..b3b22728
--- /dev/null
+++ b/packages/code/src/environment.test.ts
@@ -0,0 +1,165 @@
+import assert from 'node:assert/strict';
+import { mkdtemp, mkdir, writeFile, rm, symlink } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import test from 'node:test';
+import {
+    parseCodeEnvironment,
+    loadCodeEnvironment,
+    assertEnvironmentDefinitionsOutsideRoots,
+    EnvironmentWorkspaceTools,
+} from './environment.js';
+import { LocalWorkspaceTools, SandboxWorkspaceTools } from './workspace.js';
+import { isValidBridgeWorkspaceToolCapabilities } from './protocol.js';
+import type { WorkspaceExecuteCommandRequest } from './protocol.js';
+
+test('environment YAML validates setup and rejects unsupported policy or action fields', () => {
+    const definition = parseCodeEnvironment(
+        'name: app\nroot: ./project\nsetup:\n  command: npm ci\n',
+    );
+    assert.equal(definition.setup?.timeoutMs, 300_000);
+    for (const suffix of [
+        'scope: { users: [anyone] }',
+        'actions: [{}]',
+        'unknown: true',
+        'setup: { command: npm ci, timeoutMs: 600000 }',
+        'setup: { command: npm ci, timeoutMs: -1 }',
+        'setup: { command: npm ci, env: { SECRET: x } }',
+        'name: duplicate',
+        'repo: https://token@github.com/a/b',
+    ])
+        assert.throws(() =>
+            parseCodeEnvironment(`name: app\nroot: ./project\n${suffix}\n`),
+        );
+    assert.throws(() => parseCodeEnvironment('name: &id app\nroot: *id'));
+    assert.throws(() => parseCodeEnvironment('x'.repeat(65_537)));
+});
+
+test('named actions use the loaded definition, reject stale revisions and preserve command restrictions', async t => {
+    const directory = await mkdtemp(join(tmpdir(), 'code-env-action-'));
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    const local = await LocalWorkspaceTools.create({
+        workspaces: [{ id: 'app', root: directory }],
+    });
+    const executed: WorkspaceExecuteCommandRequest[] = [];
+    const commands = new SandboxWorkspaceTools({
+        workspaceTools: local,
+        commandWorkspaces: ['app'],
+        commandSandbox: {
+            mutationFailuresAreAtomic: true,
+            async execute(request) {
+                executed.push(request);
+                return {
+                    protocolVersion: 1,
+                    operation: 'execute_command',
+                    workspaceId: 'app',
+                    stdout: '',
+                    stderr: '',
+                    exitCode: 0,
+                    timedOut: false,
+                    truncated: false,
+                };
+            },
+        },
+    });
+    const environments = [
+        {
+            path: '/operator/environment.yaml',
+            fingerprint: 'a'.repeat(64),
+            definition: {
+                name: 'app',
+                root: directory,
+                actions: [
+                    { name: 'test', command: 'npm test', timeoutMs: 2000 },
+                ],
+            },
+        },
+    ];
+    const tools = new EnvironmentWorkspaceTools(commands, environments);
+    assert.ok(isValidBridgeWorkspaceToolCapabilities(tools.capabilities));
+    assert.deepEqual(tools.capabilities.workspaces[0].environment?.actions, [
+        'test',
+    ]);
+    assert.equal(
+        JSON.stringify(tools.capabilities).includes('npm test'),
+        false,
+    );
+    const request: WorkspaceExecuteCommandRequest = {
+        protocolVersion: 1,
+        operation: 'execute_command',
+        workspaceId: 'app',
+        command: 'untrusted placeholder',
+        timeoutMs: 5000,
+        environmentAction: { name: 'test', fingerprint: 'a'.repeat(64) },
+    };
+    await tools.execute(request);
+    assert.equal(executed[0].command, 'npm test');
+    assert.equal(executed[0].timeoutMs, 2000);
+    assert.equal(executed[0].environmentAction, undefined);
+    for (const altered of [
+        { ...request, workspaceId: 'other' },
+        { ...request, cwd: 'nested' },
+        {
+            ...request,
+            environmentAction: { name: 'test', fingerprint: 'b'.repeat(64) },
+        },
+        {
+            ...request,
+            environmentAction: { name: 'other', fingerprint: 'a'.repeat(64) },
+        },
+    ])
+        await assert.rejects(
+            tools.execute(altered),
+            /unavailable or its definition changed/,
+        );
+    await assert.rejects(commands.execute(request), /not resolved/);
+    const readOnly = new EnvironmentWorkspaceTools(local, environments);
+    assert.deepEqual(
+        readOnly.capabilities.workspaces[0].environment?.actions,
+        [],
+    );
+    await assert.rejects(readOnly.execute(request));
+    assert.equal(executed.length, 1);
+});
+
+test('environment roots resolve relative to the definition and fingerprints cover setup', async t => {
+    const directory = await mkdtemp(join(tmpdir(), 'code-env-definition-'));
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    await mkdir(join(directory, 'project'));
+    const path = join(directory, 'environment.yaml');
+    await writeFile(
+        path,
+        'name: app\nroot: project\nsetup: { command: "printf first" }\n',
+    );
+    const first = await loadCodeEnvironment(path);
+    assert.ok(first.definition.root.endsWith('/project'));
+    assertEnvironmentDefinitionsOutsideRoots(
+        [first],
+        [{ id: 'app', root: first.definition.root }],
+    );
+    await writeFile(
+        path,
+        'name: app\nroot: project\nsetup: { command: "printf second" }\n',
+    );
+    assert.notEqual(
+        (await loadCodeEnvironment(path)).fingerprint,
+        first.fingerprint,
+    );
+    assert.throws(() =>
+        assertEnvironmentDefinitionsOutsideRoots(
+            [first],
+            [
+                {
+                    id: 'parent',
+                    root: first.definition.root.slice(0, -'/project'.length),
+                },
+            ],
+        ),
+    );
+    await symlink(path, join(directory, 'project', 'alias.yaml'));
+    assert.equal(
+        (await loadCodeEnvironment(join(directory, 'project', 'alias.yaml')))
+            .path,
+        first.path,
+    );
+});
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
new file mode 100644
index 00000000..5709f1b1
--- /dev/null
+++ b/packages/code/src/environment.ts
@@ -0,0 +1,276 @@
+import { createHash } from 'node:crypto';
+import { open, realpath, stat } from 'node:fs/promises';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { parseDocument } from 'yaml';
+import { BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS } from './protocol.js';
+import type { LocalWorkspaceConfig } from './workspace.js';
+import { WorkspaceToolError } from './workspace.js';
+import type { WorkspaceToolExecutor } from './workspace.js';
+import type { WorkspaceToolRequest, WorkspaceToolResult } from './protocol.js';
+
+export interface CodeEnvironmentDefinition {
+    name: string;
+    root: string;
+    repo?: string;
+    ref?: string;
+    setup?: { command: string; timeoutMs: number };
+    actions?: { name: string; command: string; timeoutMs: number }[];
+}
+
+export interface LoadedCodeEnvironment {
+    path: string;
+    definition: CodeEnvironmentDefinition;
+    fingerprint: string;
+}
+
+function record(value: unknown): value is Record<string, unknown> {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+
+function text(value: unknown, max: number): value is string {
+    return (
+        typeof value === 'string' &&
+        value.trim().length > 0 &&
+        value.length <= max &&
+        !value.includes('\0')
+    );
+}
+
+export function parseCodeEnvironment(
+    source: string,
+): CodeEnvironmentDefinition {
+    if (Buffer.byteLength(source) > 65_536)
+        throw new Error('Environment file exceeds 64 KiB');
+    const document = parseDocument(source, {
+        schema: 'core',
+        uniqueKeys: true,
+    });
+    if (document.errors.length || document.warnings.length) {
+        throw new Error('Invalid environment YAML');
+    }
+    const value: unknown = document.toJS({ maxAliasCount: 0 });
+    if (
+        !record(value) ||
+        Object.keys(value).some(
+            key =>
+                !['name', 'root', 'repo', 'ref', 'setup', 'actions'].includes(
+                    key,
+                ),
+        ) ||
+        !text(value.name, 64) ||
+        !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(value.name) ||
+        !text(value.root, 4096) ||
+        (value.repo !== undefined &&
+            (!text(value.repo, 256) ||
+                !/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(value.repo))) ||
+        (value.ref !== undefined &&
+            (!text(value.ref, 256) || /[\r\n]/.test(value.ref)))
+    ) {
+        throw new Error(
+            'Invalid environment definition: expected name, root, optional repo, ref and setup',
+        );
+    }
+    let setup: CodeEnvironmentDefinition['setup'];
+    if (value.setup !== undefined) {
+        if (
+            !record(value.setup) ||
+            Object.keys(value.setup).some(
+                key => !['command', 'timeoutMs'].includes(key),
+            ) ||
+            !text(value.setup.command, 16_384)
+        ) {
+            throw new Error('Invalid environment setup');
+        }
+        const timeoutMs =
+            value.setup.timeoutMs ?? BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS;
+        if (
+            typeof timeoutMs !== 'number' ||
+            !Number.isSafeInteger(timeoutMs) ||
+            timeoutMs < 1 ||
+            timeoutMs > BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS
+        ) {
+            throw new Error(
+                `Environment setup timeout must be between 1 and ${BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS} ms`,
+            );
+        }
+        setup = { command: value.setup.command, timeoutMs };
+    }
+    let actions: CodeEnvironmentDefinition['actions'];
+    if (value.actions !== undefined) {
+        if (!Array.isArray(value.actions) || value.actions.length > 32)
+            throw new Error('Invalid environment actions');
+        const names = new Set<string>();
+        actions = value.actions.map((action: unknown) => {
+            if (
+                !record(action) ||
+                Object.keys(action).some(
+                    key => !['name', 'command', 'timeoutMs'].includes(key),
+                ) ||
+                !text(action.name, 64) ||
+                !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(action.name) ||
+                names.has(action.name) ||
+                !text(action.command, 16_384)
+            )
+                throw new Error('Invalid environment action');
+            const timeoutMs = action.timeoutMs ?? 30_000;
+            if (
+                typeof timeoutMs !== 'number' ||
+                !Number.isSafeInteger(timeoutMs) ||
+                timeoutMs < 1 ||
+                timeoutMs > BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS
+            )
+                throw new Error('Invalid environment action timeout');
+            names.add(action.name);
+            return { name: action.name, command: action.command, timeoutMs };
+        });
+    }
+    return {
+        name: value.name,
+        root: value.root,
+        ...(typeof value.repo === 'string' ? { repo: value.repo } : {}),
+        ...(typeof value.ref === 'string' ? { ref: value.ref } : {}),
+        ...(setup ? { setup } : {}),
+        ...(actions ? { actions } : {}),
+    };
+}
+
+/** Resolve actions only against the worker-owned snapshot, after normal command admission. */
+export class EnvironmentWorkspaceTools implements WorkspaceToolExecutor {
+    readonly mutationFailuresAreAtomic?: true;
+    readonly capabilities: WorkspaceToolExecutor['capabilities'];
+    private readonly environments: Map<string, LoadedCodeEnvironment>;
+
+    constructor(
+        private readonly delegate: WorkspaceToolExecutor,
+        environments: LoadedCodeEnvironment[],
+    ) {
+        this.mutationFailuresAreAtomic = delegate.mutationFailuresAreAtomic;
+        this.environments = new Map(
+            environments.map(environment => [
+                environment.definition.name,
+                environment,
+            ]),
+        );
+        this.capabilities = {
+            ...delegate.capabilities,
+            workspaces: delegate.capabilities.workspaces.map(workspace => {
+                const environment = this.environments.get(workspace.id);
+                if (!environment) return workspace;
+                const operations =
+                    workspace.operations ?? delegate.capabilities.operations;
+                return {
+                    ...workspace,
+                    environment: {
+                        fingerprint: environment.fingerprint,
+                        ...(environment.definition.repo
+                            ? { repo: environment.definition.repo }
+                            : {}),
+                        ...(environment.definition.ref
+                            ? { ref: environment.definition.ref }
+                            : {}),
+                        actions: operations.includes('execute_command')
+                            ? (environment.definition.actions ?? []).map(
+                                  action => action.name,
+                              )
+                            : [],
+                    },
+                };
+            }),
+        };
+    }
+
+    async execute(
+        request: WorkspaceToolRequest,
+        signal?: AbortSignal,
+    ): Promise<WorkspaceToolResult> {
+        if (
+            request.operation !== 'execute_command' ||
+            !request.environmentAction
+        ) {
+            return this.delegate.execute(request, signal);
+        }
+        const environment = this.environments.get(request.workspaceId);
+        const action = environment?.definition.actions?.find(
+            action => action.name === request.environmentAction?.name,
+        );
+        if (
+            !environment ||
+            environment.fingerprint !== request.environmentAction.fingerprint ||
+            !action ||
+            (request.cwd !== undefined && request.cwd !== '.')
+        ) {
+            throw new WorkspaceToolError(
+                'Environment action is unavailable or its definition changed',
+                'INVALID_REQUEST',
+            );
+        }
+        const { environmentAction: _action, ...commandRequest } = request;
+        return this.delegate.execute(
+            {
+                ...commandRequest,
+                command: action.command,
+                timeoutMs: Math.min(
+                    request.timeoutMs ?? action.timeoutMs,
+                    action.timeoutMs,
+                ),
+                cwd: '.',
+            },
+            signal,
+        );
+    }
+}
+
+export async function loadCodeEnvironment(
+    path: string,
+): Promise<LoadedCodeEnvironment> {
+    const canonicalPath = await realpath(path);
+    const handle = await open(canonicalPath, 'r');
+    let definition: CodeEnvironmentDefinition;
+    try {
+        const metadata = await handle.stat();
+        if (!metadata.isFile() || metadata.size > 65_536)
+            throw new Error('Invalid environment file');
+        const buffer = Buffer.alloc(65_537);
+        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        definition = parseCodeEnvironment(
+            buffer.subarray(0, bytesRead).toString('utf8'),
+        );
+    } finally {
+        await handle.close();
+    }
+    const root = await realpath(
+        resolve(dirname(canonicalPath), definition.root),
+    );
+    if (!(await stat(root)).isDirectory())
+        throw new Error('Environment root must be a directory');
+    definition = { ...definition, root };
+    return {
+        path: canonicalPath,
+        definition,
+        fingerprint: createHash('sha256')
+            .update(JSON.stringify(definition))
+            .digest('hex'),
+    };
+}
+
+/** A workspace must never be able to rewrite a definition used on the next startup. */
+export function assertEnvironmentDefinitionsOutsideRoots(
+    environments: readonly LoadedCodeEnvironment[],
+    roots: readonly LocalWorkspaceConfig[],
+): void {
+    for (const environment of environments) {
+        for (const root of roots) {
+            const path = relative(root.root, environment.path);
+            if (
+                path === '' ||
+                (!isAbsolute(path) &&
+                    path !== '..' &&
+                    !path.startsWith(`..${sep}`))
+            ) {
+                throw new Error(
+                    'Environment definitions must be outside every registered workspace root',
+                );
+            }
+        }
+    }
+}
diff --git a/packages/code/src/protocol.ts b/packages/code/src/protocol.ts
index b92d21ac..9199fcf0 100644
--- a/packages/code/src/protocol.ts
+++ b/packages/code/src/protocol.ts
@@ -21,7 +21,8 @@ export const BRIDGE_WORKSPACE_COMMAND_DEFAULT_OUTPUT_BYTES = 256 * 1024;
 export const BRIDGE_WORKSPACE_COMMAND_MAX_OUTPUT_BYTES = 1024 * 1024;
 export const BRIDGE_WORKSPACE_COMMAND_SIGNAL_MAX_LENGTH = 32;
 export const BRIDGE_WORKSPACE_PROGRAMMATIC_MAX_FILES = 100;
-export const BRIDGE_WORKSPACE_PROGRAMMATIC_MAX_INPUT_FILES = BRIDGE_WORKSPACE_PROGRAMMATIC_MAX_FILES - 2;
+export const BRIDGE_WORKSPACE_PROGRAMMATIC_MAX_INPUT_FILES =
+    BRIDGE_WORKSPACE_PROGRAMMATIC_MAX_FILES - 2;
 export const BRIDGE_WORKSPACE_PROGRAMMATIC_TRANSFER_CONCURRENCY = 4;
 export const BRIDGE_WORKSPACE_PROGRAMMATIC_TRANSFER_TIMEOUT_MS = 30_000;
 
@@ -41,26 +42,119 @@ export const BRIDGE_CANCELLED_WORKSPACE_SETTLEMENT_GRACE_MS = 5_000;
  * locally instead of discovering the mismatch only after mutating a workspace.
  */
 const BRIDGE_ARTIFACT_EXTENSIONS = new Set([
-  '.c', '.cs', '.cpp', '.go', '.java', '.js', '.kt', '.kts', '.lua',
-  '.php', '.pl', '.ps1', '.py', '.r', '.rb', '.rs', '.scala', '.sh',
-  '.sql', '.swift', '.ts', '.jsx', '.tsx', '.groovy',
-  '.css', '.htm', '.html', '.less', '.sass', '.scss', '.svg', '.svelte', '.vue',
-  '.adoc', '.asciidoc', '.md', '.rst', '.tex', '.txt', '.wiki',
-  '.csv', '.json', '.bson', '.json5', '.jsonl', '.parquet', '.tsv',
-  '.xml', '.yaml', '.yml',
-  '.ics', '.ical', '.ifb', '.icalendar',
-  '.conf', '.env', '.gitignore', '.ini', '.properties', '.toml',
-  '.doc', '.docx', '.pdf', '.ppt', '.pptx', '.xls', '.xlsx',
-  '.odt', '.ods', '.odp', '.rtf',
-  '.avif', '.bmp', '.gif', '.ico', '.jpeg', '.jpg', '.png',
-  '.tif', '.tiff', '.webp',
-  '.eot', '.ttf', '.woff', '.woff2',
-  '.7z', '.bz2', '.gz', '.gzip', '.rar', '.tar', '.zip',
-  '.tf', '.tfvars', '.tfstate', '.hcl',
-  '.dockerfile', '.Dockerfile', '.dockerignore',
-  '.helmignore', '.helmfile', '.jenkinsfile', '.vagrantfile',
-  '.eslintrc', '.prettierrc', '.editorconfig', '.nomad',
-  '.bat', '.cmd', '.deb', '.log', '.rpm', '.vbs',
+    '.c',
+    '.cs',
+    '.cpp',
+    '.go',
+    '.java',
+    '.js',
+    '.kt',
+    '.kts',
+    '.lua',
+    '.php',
+    '.pl',
+    '.ps1',
+    '.py',
+    '.r',
+    '.rb',
+    '.rs',
+    '.scala',
+    '.sh',
+    '.sql',
+    '.swift',
+    '.ts',
+    '.jsx',
+    '.tsx',
+    '.groovy',
+    '.css',
+    '.htm',
+    '.html',
+    '.less',
+    '.sass',
+    '.scss',
+    '.svg',
+    '.svelte',
+    '.vue',
+    '.adoc',
+    '.asciidoc',
+    '.md',
+    '.rst',
+    '.tex',
+    '.txt',
+    '.wiki',
+    '.csv',
+    '.json',
+    '.bson',
+    '.json5',
+    '.jsonl',
+    '.parquet',
+    '.tsv',
+    '.xml',
+    '.yaml',
+    '.yml',
+    '.ics',
+    '.ical',
+    '.ifb',
+    '.icalendar',
+    '.conf',
+    '.env',
+    '.gitignore',
+    '.ini',
+    '.properties',
+    '.toml',
+    '.doc',
+    '.docx',
+    '.pdf',
+    '.ppt',
+    '.pptx',
+    '.xls',
+    '.xlsx',
+    '.odt',
+    '.ods',
+    '.odp',
+    '.rtf',
+    '.avif',
+    '.bmp',
+    '.gif',
+    '.ico',
+    '.jpeg',
+    '.jpg',
+    '.png',
+    '.tif',
+    '.tiff',
+    '.webp',
+    '.eot',
+    '.ttf',
+    '.woff',
+    '.woff2',
+    '.7z',
+    '.bz2',
+    '.gz',
+    '.gzip',
+    '.rar',
+    '.tar',
+    '.zip',
+    '.tf',
+    '.tfvars',
+    '.tfstate',
+    '.hcl',
+    '.dockerfile',
+    '.Dockerfile',
+    '.dockerignore',
+    '.helmignore',
+    '.helmfile',
+    '.jenkinsfile',
+    '.vagrantfile',
+    '.eslintrc',
+    '.prettierrc',
+    '.editorconfig',
+    '.nomad',
+    '.bat',
+    '.cmd',
+    '.deb',
+    '.log',
+    '.rpm',
+    '.vbs',
 ]);
 
 function portableBasename(name: string): string {
@@ -94,7 +188,8 @@ const BRIDGE_ARTIFACT_MEDIA_TYPES: Readonly<Record<string, string>> = {
   '.css': 'text/css',
   '.csv': 'text/csv',
   '.doc': 'application/msword',
-  '.docx': 'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
+    '.docx':
+        'application/vnd.openxmlformats-officedocument.wordprocessingml.document',
   '.gif': 'image/gif',
   '.gz': 'application/gzip',
   '.gzip': 'application/gzip',
@@ -123,7 +218,8 @@ const BRIDGE_ARTIFACT_MEDIA_TYPES: Readonly<Record<string, string>> = {
   '.pdf': 'application/pdf',
   '.png': 'image/png',
   '.ppt': 'application/vnd.ms-powerpoint',
-  '.pptx': 'application/vnd.openxmlformats-officedocument.presentationml.presentation',
+    '.pptx':
+        'application/vnd.openxmlformats-officedocument.presentationml.presentation',
   '.py': 'text/x-python',
   '.rst': 'text/x-rst',
   '.rtf': 'application/rtf',
@@ -143,7 +239,8 @@ const BRIDGE_ARTIFACT_MEDIA_TYPES: Readonly<Record<string, string>> = {
   '.woff': 'font/woff',
   '.woff2': 'font/woff2',
   '.xls': 'application/vnd.ms-excel',
-  '.xlsx': 'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
+    '.xlsx':
+        'application/vnd.openxmlformats-officedocument.spreadsheetml.sheet',
   '.xml': 'application/xml',
   '.yaml': 'application/yaml',
   '.yml': 'application/yaml',
@@ -180,6 +277,12 @@ export interface BridgeWorkspaceDescriptor {
   name?: string;
   /** Optional per-workspace restriction. Omitted by protocol-v1 readers. */
   operations?: BridgeWorkspaceToolOperation[];
+    environment?: {
+        fingerprint: string;
+        repo?: string;
+        ref?: string;
+        actions: string[];
+    };
 }
 
 export interface BridgeWorkspaceToolCapabilities {
@@ -291,7 +394,8 @@ interface WorkspaceEditFileRequestBase {
   expectedBaseSha256?: string;
 }
 
-export interface WorkspaceSingleEditFileRequest extends WorkspaceEditFileRequestBase {
+export interface WorkspaceSingleEditFileRequest
+    extends WorkspaceEditFileRequestBase {
   /** Legacy single-edit form. */
   oldText: string;
   /** Legacy single-edit form. */
@@ -299,7 +403,8 @@ export interface WorkspaceSingleEditFileRequest extends WorkspaceEditFileRequest
   edits?: never;
 }
 
-export interface WorkspaceBatchEditFileRequest extends WorkspaceEditFileRequestBase {
+export interface WorkspaceBatchEditFileRequest
+    extends WorkspaceEditFileRequestBase {
   /** Ordered exact replacements applied atomically as one file mutation. */
   edits: WorkspaceTextEdit[];
   oldText?: never;
@@ -307,7 +412,8 @@ export interface WorkspaceBatchEditFileRequest extends WorkspaceEditFileRequestB
 }
 
 export type WorkspaceEditFileRequest =
-    WorkspaceSingleEditFileRequest | WorkspaceBatchEditFileRequest;
+    | WorkspaceSingleEditFileRequest
+    | WorkspaceBatchEditFileRequest;
 
 export interface WorkspaceTextEdit {
   oldText: string;
@@ -330,20 +436,23 @@ interface WorkspacePreviewEditRequestBase {
   path: string;
 }
 
-export interface WorkspaceSinglePreviewEditRequest extends WorkspacePreviewEditRequestBase {
+export interface WorkspaceSinglePreviewEditRequest
+    extends WorkspacePreviewEditRequestBase {
   oldText: string;
   newText: string;
   edits?: never;
 }
 
-export interface WorkspaceBatchPreviewEditRequest extends WorkspacePreviewEditRequestBase {
+export interface WorkspaceBatchPreviewEditRequest
+    extends WorkspacePreviewEditRequestBase {
   edits: WorkspaceTextEdit[];
   oldText?: never;
   newText?: never;
 }
 
 export type WorkspacePreviewEditRequest =
-    WorkspaceSinglePreviewEditRequest | WorkspaceBatchPreviewEditRequest;
+    | WorkspaceSinglePreviewEditRequest
+    | WorkspaceBatchPreviewEditRequest;
 
 export interface WorkspacePreviewEditResult {
   protocolVersion: BridgeProtocolVersion;
@@ -368,6 +477,7 @@ export interface WorkspaceExecuteCommandRequest {
   timeoutMs?: number;
   /** Aggregate UTF-8 stdout and stderr budget. */
   maxOutputBytes?: number;
+    environmentAction?: { name: string; fingerprint: string };
 }
 
 export interface WorkspaceExecuteCommandResult {
@@ -452,6 +562,7 @@ const WORKSPACE_PREVIEW_EDIT_REQUEST_KEYS = new Set([
 ]);
 const WORKSPACE_TEXT_EDIT_KEYS = new Set(['oldText', 'newText']);
 const WORKSPACE_COMMAND_REQUEST_KEYS = new Set([
+    'environmentAction',
   'protocolVersion',
   'operation',
   'workspaceId',
@@ -720,7 +831,8 @@ export function isWorkspaceToolErrorCode(
 }
 
 export type BridgeSettlement<TResult = object> =
-  BridgeFulfilledSettlement<TResult> | BridgeRejectedSettlement;
+    | BridgeFulfilledSettlement<TResult>
+    | BridgeRejectedSettlement;
 
 export interface BridgeSettlementResponse {
   protocolVersion: BridgeProtocolVersion;
@@ -806,7 +918,8 @@ export function isBridgeWorkspaceProgrammaticRequest(
     (body.transfer_timeout_ms !== undefined &&
       (!Number.isSafeInteger(body.transfer_timeout_ms) ||
         Number(body.transfer_timeout_ms) < 1 ||
-        Number(body.transfer_timeout_ms) > BRIDGE_WORKSPACE_PROGRAMMATIC_TRANSFER_TIMEOUT_MS)) ||
+                Number(body.transfer_timeout_ms) >
+                    BRIDGE_WORKSPACE_PROGRAMMATIC_TRANSFER_TIMEOUT_MS)) ||
     (body.run_timeout !== undefined &&
       (!Number.isSafeInteger(body.run_timeout) ||
         Number(body.run_timeout) < 1 ||
@@ -826,7 +939,8 @@ export function isBridgeWorkspaceProgrammaticRequest(
     if (
       !isSafePortableRelativePath(file.name) ||
       file.name === '.' ||
-      portableBasename(file.name).toLowerCase() === '_ptc_pending_result.json' ||
+            portableBasename(file.name).toLowerCase() ===
+                '_ptc_pending_result.json' ||
       normalizePortableRelativePath(file.name) !== file.name ||
       names.has(file.name)
     ) {
@@ -875,7 +989,9 @@ export function isBridgeWorkspaceProgrammaticRequest(
     const segments = name.split('/');
     let ancestor = '';
     for (let index = 0; index < segments.length - 1; index += 1) {
-      ancestor = ancestor ? `${ancestor}/${segments[index]}` : segments[index]!;
+            ancestor = ancestor
+                ? `${ancestor}/${segments[index]}`
+                : segments[index]!;
       if (names.has(ancestor)) return false;
     }
   }
@@ -1105,6 +1221,22 @@ export function isWorkspaceToolRequest(
   }
   if (request.operation === 'execute_command') {
     return (
+            (request.environmentAction === undefined ||
+                (typeof request.environmentAction === 'object' &&
+                    request.environmentAction !== null &&
+                    Object.keys(request.environmentAction).length === 2 &&
+                    typeof (request.environmentAction as { name?: unknown })
+                        .name === 'string' &&
+                    /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(
+                        (request.environmentAction as { name: string }).name,
+                    ) &&
+                    typeof (
+                        request.environmentAction as { fingerprint?: unknown }
+                    ).fingerprint === 'string' &&
+                    /^[a-f0-9]{64}$/.test(
+                        (request.environmentAction as { fingerprint: string })
+                            .fingerprint,
+                    ))) &&
       hasOnlyKeys(request, WORKSPACE_COMMAND_REQUEST_KEYS) &&
       typeof request.command === 'string' &&
       request.command.trim().length > 0 &&
@@ -1438,11 +1570,17 @@ export function isValidBridgeWorkspaceToolCapabilities(
     const descriptor = workspace as Record<string, unknown>;
     if (
       Object.keys(descriptor).some(
-                key => key !== 'id' && key !== 'name' && key !== 'operations',
+                key =>
+                    key !== 'id' &&
+                    key !== 'name' &&
+                    key !== 'operations' &&
+                    key !== 'environment',
       ) ||
       typeof descriptor.id !== 'string' ||
       !isValidBridgeWorkerId(descriptor.id) ||
       workspaceIds.has(descriptor.id) ||
+            (descriptor.environment !== undefined &&
+                !isValidCodeEnvironmentDescriptor(descriptor.environment)) ||
       (descriptor.name !== undefined &&
         (typeof descriptor.name !== 'string' ||
           descriptor.name.trim().length === 0 ||
@@ -1469,6 +1607,37 @@ export function isValidBridgeWorkspaceToolCapabilities(
   });
 }
 
+export function isValidCodeEnvironmentDescriptor(
+    value: unknown,
+): value is NonNullable<BridgeWorkspaceDescriptor['environment']> {
+    if (typeof value !== 'object' || value === null) return false;
+    const environment = value as Record<string, unknown>;
+    return (
+        Object.keys(environment).every(key =>
+            ['fingerprint', 'repo', 'ref', 'actions'].includes(key),
+        ) &&
+        typeof environment.fingerprint === 'string' &&
+        /^[a-f0-9]{64}$/.test(environment.fingerprint) &&
+        (environment.repo === undefined ||
+            (typeof environment.repo === 'string' &&
+                environment.repo.length <= 256 &&
+                /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(environment.repo))) &&
+        (environment.ref === undefined ||
+            (typeof environment.ref === 'string' &&
+                environment.ref.trim().length > 0 &&
+                environment.ref.length <= 256 &&
+                !/[\0\r\n]/.test(environment.ref))) &&
+        Array.isArray(environment.actions) &&
+        environment.actions.length <= 32 &&
+        environment.actions.every(
+            name =>
+                typeof name === 'string' &&
+                /^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$/.test(name),
+        ) &&
+        new Set(environment.actions).size === environment.actions.length
+    );
+}
+
 export function isValidBridgeWorkerCapabilities(
   value: unknown,
 ): value is BridgeWorkerCapabilities {
diff --git a/packages/code/src/workspace.ts b/packages/code/src/workspace.ts
index dfda49fc..91e89f54 100644
--- a/packages/code/src/workspace.ts
+++ b/packages/code/src/workspace.ts
@@ -1693,6 +1693,9 @@ export class SandboxWorkspaceTools implements WorkspaceToolExecutor {
     if (request.operation !== 'execute_command') {
       return this.options.workspaceTools.execute(request, signal);
     }
+    if (request.environmentAction) {
+      throw new WorkspaceToolError('Environment action was not resolved by this worker', 'INVALID_REQUEST');
+    }
     if (!this.commandWorkspaces.has(request.workspaceId)) {
       throw new WorkspaceToolError(
         'Command execution is disabled for this workspace',

From c6b542ebadc7ce3048b8a6ec0321545523120800 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 17:26:41 -0400
Subject: [PATCH 2/8] fix: preserve environment trust and negotiated action
 boundaries

---
 packages/code/src/cli.ts                   |  2 +-
 packages/code/src/environment-live.test.ts | 25 ++++++++---
 packages/code/src/environment.test.ts      | 21 ++++++++-
 packages/code/src/environment.ts           | 51 +++++++++++++++++-----
 packages/code/src/worker.ts                | 14 ++++--
 packages/code/src/workspace-worker.test.ts | 24 ++++++++++
 6 files changed, 114 insertions(+), 23 deletions(-)

diff --git a/packages/code/src/cli.ts b/packages/code/src/cli.ts
index 324cd6ff..81637c85 100644
--- a/packages/code/src/cli.ts
+++ b/packages/code/src/cli.ts
@@ -989,7 +989,7 @@ async function run(
   try {
     await github.provider?.getCredential(controller.signal);
     await nativeCommandSandbox?.prepare();
-        for (const environment of environments) {
+        for (const environment of option(args, '--reset-workspace-quarantine') == null ? environments : []) {
             const setup = environment.definition.setup;
             if (!setup || !nativeCommandSandbox) continue;
             const id = environment.definition.name;
diff --git a/packages/code/src/environment-live.test.ts b/packages/code/src/environment-live.test.ts
index 76842efb..cee50a63 100644
--- a/packages/code/src/environment-live.test.ts
+++ b/packages/code/src/environment-live.test.ts
@@ -8,9 +8,13 @@ import { join } from 'node:path';
 import { fileURLToPath } from 'node:url';
 import test from 'node:test';
 
-for (const succeeds of [true, false]) {
+for (const { succeeds, reset } of [
+    { succeeds: true, reset: false },
+    { succeeds: false, reset: false },
+    { succeeds: true, reset: true },
+]) {
     test(
-        `real CLI environment setup gates registration (success=${succeeds})`,
+        `real CLI environment setup gates registration (success=${succeeds}, reset=${reset})`,
         {
             skip: process.env.LIBRECHAT_CODE_LIVE_SRT_TESTS !== '1',
             timeout: 20_000,
@@ -34,10 +38,16 @@ for (const succeeds of [true, false]) {
                 request.resume();
                 if (request.url?.endsWith('/register')) {
                     registrations++;
-                    assert.equal(
-                        await readFile(join(root, 'prepared.txt'), 'utf8'),
-                        'prepared',
-                    );
+                    if (reset)
+                        await assert.rejects(
+                            readFile(join(root, 'prepared.txt')),
+                            { code: 'ENOENT' },
+                        );
+                    else
+                        assert.equal(
+                            await readFile(join(root, 'prepared.txt'), 'utf8'),
+                            'prepared',
+                        );
                     receive?.();
                 }
                 response.writeHead(503).end();
@@ -59,6 +69,9 @@ for (const succeeds of [true, false]) {
                     '--environment',
                     path,
                     '--allow-workspace-commands',
+                    ...(reset
+                        ? ['--reset-workspace-quarantine', 'project']
+                        : []),
                 ],
                 {
                     env: {
diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index b3b22728..82e66696 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -1,5 +1,5 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, mkdir, writeFile, rm, symlink } from 'node:fs/promises';
+import { mkdtemp, mkdir, writeFile, rm, symlink, link } from 'node:fs/promises';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
@@ -157,9 +157,28 @@ test('environment roots resolve relative to the definition and fingerprints cove
         ),
     );
     await symlink(path, join(directory, 'project', 'alias.yaml'));
+    const alias = await loadCodeEnvironment(
+        join(directory, 'project', 'alias.yaml'),
+    );
+    assert.throws(() =>
+        assertEnvironmentDefinitionsOutsideRoots(
+            [alias],
+            [{ id: 'app', root: first.definition.root }],
+        ),
+    );
     assert.equal(
         (await loadCodeEnvironment(join(directory, 'project', 'alias.yaml')))
             .path,
         first.path,
     );
 });
+
+test('rejects a trusted definition with an in-workspace hard link', async t => {
+    const directory = await mkdtemp(join(tmpdir(), 'code-env-hardlink-'));
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    await mkdir(join(directory, 'project'));
+    const path = join(directory, 'environment.yaml');
+    await writeFile(path, 'name: app\nroot: project\n');
+    await link(path, join(directory, 'project', 'alias.yaml'));
+    await assert.rejects(loadCodeEnvironment(path), /one link/);
+});
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index 5709f1b1..a5624a13 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -2,6 +2,10 @@ import { createHash } from 'node:crypto';
 import { open, realpath, stat } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { parseDocument } from 'yaml';
+import {
+    assertPrivateStorageAcl,
+    assertPrivateStorageAncestors,
+} from './private-storage.js';
 import { BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS } from './protocol.js';
 import type { LocalWorkspaceConfig } from './workspace.js';
 import { WorkspaceToolError } from './workspace.js';
@@ -19,6 +23,7 @@ export interface CodeEnvironmentDefinition {
 
 export interface LoadedCodeEnvironment {
     path: string;
+    sourceParents?: string[];
     definition: CodeEnvironmentDefinition;
     fingerprint: string;
 }
@@ -223,11 +228,29 @@ export class EnvironmentWorkspaceTools implements WorkspaceToolExecutor {
 export async function loadCodeEnvironment(
     path: string,
 ): Promise<LoadedCodeEnvironment> {
-    const canonicalPath = await realpath(path);
+    const sourcePath = resolve(path);
+    await assertPrivateStorageAncestors(sourcePath);
+    const canonicalPath = await realpath(sourcePath);
+    const sourceParents: string[] = [];
+    for (let parent = dirname(sourcePath); ; parent = dirname(parent)) {
+        sourceParents.push(await realpath(parent));
+        if (parent === dirname(parent)) break;
+    }
     const handle = await open(canonicalPath, 'r');
     let definition: CodeEnvironmentDefinition;
     try {
         const metadata = await handle.stat();
+        const self = process.getuid?.();
+        if (
+            metadata.nlink !== 1 ||
+            (metadata.mode & 0o022) !== 0 ||
+            (self !== undefined && metadata.uid !== self && metadata.uid !== 0)
+        ) {
+            throw new Error(
+                'Environment definitions must have one link, a trusted owner and no group or other write permissions',
+            );
+        }
+        await assertPrivateStorageAcl(handle, canonicalPath);
         if (!metadata.isFile() || metadata.size > 65_536)
             throw new Error('Invalid environment file');
         const buffer = Buffer.alloc(65_537);
@@ -246,6 +269,7 @@ export async function loadCodeEnvironment(
     definition = { ...definition, root };
     return {
         path: canonicalPath,
+        sourceParents,
         definition,
         fingerprint: createHash('sha256')
             .update(JSON.stringify(definition))
@@ -260,16 +284,21 @@ export function assertEnvironmentDefinitionsOutsideRoots(
 ): void {
     for (const environment of environments) {
         for (const root of roots) {
-            const path = relative(root.root, environment.path);
-            if (
-                path === '' ||
-                (!isAbsolute(path) &&
-                    path !== '..' &&
-                    !path.startsWith(`..${sep}`))
-            ) {
-                throw new Error(
-                    'Environment definitions must be outside every registered workspace root',
-                );
+            for (const controlPath of [
+                environment.path,
+                ...(environment.sourceParents ?? []),
+            ]) {
+                const path = relative(root.root, controlPath);
+                if (
+                    path === '' ||
+                    (!isAbsolute(path) &&
+                        path !== '..' &&
+                        !path.startsWith(`..${sep}`))
+                ) {
+                    throw new Error(
+                        'Environment definitions must be outside every registered workspace root',
+                    );
+                }
             }
         }
     }
diff --git a/packages/code/src/worker.ts b/packages/code/src/worker.ts
index ffe1b350..6abcd054 100644
--- a/packages/code/src/worker.ts
+++ b/packages/code/src/worker.ts
@@ -236,7 +236,9 @@ function registrationCompatibleCapabilities(
       return [];
     }
     const { operations: _operations, ...compatibleWorkspace } = workspace;
-    return [compatibleWorkspace];
+    return [{ ...compatibleWorkspace, ...(workspace.environment ? {
+      environment: { ...workspace.environment, actions: [] },
+    } : {}) }];
   });
   if (workspaces.length === 0) {
     const { workspaceTools: _workspaceTools, ...compatible } = capabilities;
@@ -312,13 +314,17 @@ function supportedWorkspaceCapabilities(
     editOperations.has(operation),
   );
   const workspaces = desired.workspaces.flatMap((workspace) => {
-    if (workspace.operations == null) return [workspace];
-    const workspaceOperations = workspace.operations.filter((operation) =>
+    const workspaceOperations = (workspace.operations ?? operations).filter((operation) =>
       operations.includes(operation),
     );
     return workspaceOperations.length === 0
       ? []
-      : [{ ...workspace, operations: workspaceOperations }];
+      : [{ ...workspace,
+          ...(workspace.operations ? { operations: workspaceOperations } : {}),
+          ...(workspace.environment && !workspaceOperations.includes('execute_command') ? {
+            environment: { ...workspace.environment, actions: [] },
+          } : {}),
+        }];
   });
   if (workspaces.length === 0) return undefined;
   const editFileFeatures = desired.editFileFeatures?.filter((feature) =>
diff --git a/packages/code/src/workspace-worker.test.ts b/packages/code/src/workspace-worker.test.ts
index f6205cd4..684a6cb1 100644
--- a/packages/code/src/workspace-worker.test.ts
+++ b/packages/code/src/workspace-worker.test.ts
@@ -7,6 +7,30 @@ import { SandboxWorkspaceTools, WorkspaceToolError } from './workspace.js';
 
 const incarnationId = 'incarnation-00000001';
 
+test('worker clears named actions when command execution is not negotiated', async () => {
+  const workspaceTools = {
+    protocolVersion: 1 as const,
+    operations: ['read_file' as const, 'execute_command' as const],
+    workspaces: [{ id: 'primary', environment: { fingerprint: 'a'.repeat(64), actions: ['test'] } }],
+  };
+  const registrations: Array<typeof workspaceTools> = [];
+  const worker = new BridgeWorker({
+    codeApiUrl: 'https://code.example/v1', token: 'worker-secret', workerId: 'vm-1', incarnationId,
+    sandboxEndpoint: 'http://127.0.0.1:2000/api/v2',
+    capabilities: { statefulWorkspace: true, sandboxProfile: 'nsjail', runtimes: ['bash'], workspaceTools },
+    workspaceMutationQuarantine: mutationQuarantine(),
+    workspaceTools: { capabilities: workspaceTools, async execute() { throw new Error('not executed'); } },
+    fetchImpl: async (_input, init) => {
+      registrations.push(JSON.parse(String(init?.body)).capabilities.workspaceTools);
+      return Response.json({ protocolVersion: 1, workerId: 'vm-1', incarnationId,
+        registeredAt: new Date().toISOString(), leaseTtlMs: 60000, supportedWorkspaceToolOperations: ['read_file'] });
+    },
+  });
+  await worker.register();
+  assert.ok(registrations.length > 0);
+  for (const registration of registrations) assert.deepEqual(registration.workspaces[0].environment.actions, []);
+});
+
 const listWorkspaceCapabilities = {
   protocolVersion: 1 as const,
   operations: [

From bc176581c8ad63aee9d5079a0e23987e52c19a79 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 17:36:59 -0400
Subject: [PATCH 3/8] Harden environment loading and executor identity

---
 packages/code/src/environment.test.ts      | 96 +++++++++++++++++++++-
 packages/code/src/environment.ts           | 47 ++++++++---
 packages/code/src/private-storage.ts       | 10 ++-
 packages/code/src/worker.ts                |  7 ++
 packages/code/src/workspace-worker.test.ts | 26 ++++++
 5 files changed, 171 insertions(+), 15 deletions(-)

diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index 82e66696..75d79773 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -1,5 +1,15 @@
 import assert from 'node:assert/strict';
-import { mkdtemp, mkdir, writeFile, rm, symlink, link } from 'node:fs/promises';
+import {
+    mkdtemp,
+    mkdir,
+    writeFile,
+    rm,
+    symlink,
+    link,
+    open,
+    realpath,
+} from 'node:fs/promises';
+import { execFileSync } from 'node:child_process';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import test from 'node:test';
@@ -33,6 +43,16 @@ test('environment YAML validates setup and rejects unsupported policy or action
         );
     assert.throws(() => parseCodeEnvironment('name: &id app\nroot: *id'));
     assert.throws(() => parseCodeEnvironment('x'.repeat(65_537)));
+    for (const field of ['setup', 'actions']) {
+        const command = '漢'.repeat(12_000);
+        const suffix =
+            field === 'setup'
+                ? `setup: { command: '${command}' }`
+                : `actions: [{ name: test, command: '${command}' }]`;
+        assert.throws(() =>
+            parseCodeEnvironment(`name: app\nroot: project\n${suffix}`),
+        );
+    }
 });
 
 test('named actions use the loaded definition, reject stale revisions and preserve command restrictions', async t => {
@@ -182,3 +202,77 @@ test('rejects a trusted definition with an in-workspace hard link', async t => {
     await link(path, join(directory, 'project', 'alias.yaml'));
     await assert.rejects(loadCodeEnvironment(path), /one link/);
 });
+
+test('rejects nested aliases passing through a workspace-controlled link', async t => {
+    const directory = await realpath(
+        await mkdtemp(join(tmpdir(), 'code-env-nested-')),
+    );
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    const root = join(directory, 'project');
+    const trusted = join(directory, 'trusted');
+    await mkdir(root);
+    await mkdir(trusted);
+    await writeFile(
+        join(trusted, 'environment.yaml'),
+        `name: app\nroot: ${root}\n`,
+    );
+    await symlink(trusted, join(root, 'pivot'));
+    await symlink(join(root, 'pivot'), join(directory, 'alias'));
+    const loaded = await loadCodeEnvironment(
+        join(directory, 'alias', 'environment.yaml'),
+    );
+    assert.throws(
+        () =>
+            assertEnvironmentDefinitionsOutsideRoots(
+                [loaded],
+                [{ id: 'app', root }],
+            ),
+        /outside/,
+    );
+});
+
+test('reads complete definitions despite short filesystem reads', async t => {
+    const directory = await mkdtemp(join(tmpdir(), 'code-env-short-read-'));
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    await mkdir(join(directory, 'project'));
+    const path = join(directory, 'environment.yaml');
+    await writeFile(
+        path,
+        'name: app\nroot: project\nsetup: { command: echo prepared }\n',
+    );
+    const sample = await open(path);
+    const prototype = Object.getPrototypeOf(sample);
+    const read = prototype.read;
+    await sample.close();
+    t.mock.method(
+        prototype,
+        'read',
+        function (
+            this: unknown,
+            buffer: Buffer,
+            offset: number,
+            length: number,
+            position: number,
+        ) {
+            return read.call(
+                this,
+                buffer,
+                offset,
+                Math.min(length, 7),
+                position,
+            );
+        },
+    );
+    assert.equal(
+        (await loadCodeEnvironment(path)).definition.setup?.command,
+        'echo prepared',
+    );
+});
+
+test('rejects a FIFO definition without waiting for a writer', async t => {
+    const directory = await mkdtemp(join(tmpdir(), 'code-env-fifo-'));
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    const path = join(directory, 'environment.yaml');
+    execFileSync('mkfifo', ['-m', '600', path], { timeout: 2000 });
+    await assert.rejects(loadCodeEnvironment(path), /Invalid environment file/);
+});
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index a5624a13..db9e0ac1 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -1,4 +1,5 @@
 import { createHash } from 'node:crypto';
+import { constants } from 'node:fs';
 import { open, realpath, stat } from 'node:fs/promises';
 import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
 import { parseDocument } from 'yaml';
@@ -6,7 +7,10 @@ import {
     assertPrivateStorageAcl,
     assertPrivateStorageAncestors,
 } from './private-storage.js';
-import { BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS } from './protocol.js';
+import {
+    BRIDGE_WORKSPACE_COMMAND_MAX_TIMEOUT_MS,
+    BRIDGE_WORKSPACE_COMMAND_MAX_BYTES,
+} from './protocol.js';
 import type { LocalWorkspaceConfig } from './workspace.js';
 import { WorkspaceToolError } from './workspace.js';
 import type { WorkspaceToolExecutor } from './workspace.js';
@@ -82,7 +86,9 @@ export function parseCodeEnvironment(
             Object.keys(value.setup).some(
                 key => !['command', 'timeoutMs'].includes(key),
             ) ||
-            !text(value.setup.command, 16_384)
+            !text(value.setup.command, 16_384) ||
+            Buffer.byteLength(value.setup.command) >
+                BRIDGE_WORKSPACE_COMMAND_MAX_BYTES
         ) {
             throw new Error('Invalid environment setup');
         }
@@ -114,7 +120,9 @@ export function parseCodeEnvironment(
                 !text(action.name, 64) ||
                 !/^[A-Za-z0-9][A-Za-z0-9_-]*$/.test(action.name) ||
                 names.has(action.name) ||
-                !text(action.command, 16_384)
+                !text(action.command, 16_384) ||
+                Buffer.byteLength(action.command) >
+                    BRIDGE_WORKSPACE_COMMAND_MAX_BYTES
             )
                 throw new Error('Invalid environment action');
             const timeoutMs = action.timeoutMs ?? 30_000;
@@ -229,14 +237,12 @@ export async function loadCodeEnvironment(
     path: string,
 ): Promise<LoadedCodeEnvironment> {
     const sourcePath = resolve(path);
-    await assertPrivateStorageAncestors(sourcePath);
+    const sourceParents = await assertPrivateStorageAncestors(sourcePath);
     const canonicalPath = await realpath(sourcePath);
-    const sourceParents: string[] = [];
-    for (let parent = dirname(sourcePath); ; parent = dirname(parent)) {
-        sourceParents.push(await realpath(parent));
-        if (parent === dirname(parent)) break;
-    }
-    const handle = await open(canonicalPath, 'r');
+    const handle = await open(
+        canonicalPath,
+        constants.O_RDONLY | constants.O_NONBLOCK | constants.O_NOFOLLOW,
+    );
     let definition: CodeEnvironmentDefinition;
     try {
         const metadata = await handle.stat();
@@ -254,7 +260,26 @@ export async function loadCodeEnvironment(
         if (!metadata.isFile() || metadata.size > 65_536)
             throw new Error('Invalid environment file');
         const buffer = Buffer.alloc(65_537);
-        const { bytesRead } = await handle.read(buffer, 0, buffer.length, 0);
+        let bytesRead = 0;
+        while (bytesRead < buffer.length) {
+            const result = await handle.read(
+                buffer,
+                bytesRead,
+                buffer.length - bytesRead,
+                bytesRead,
+            );
+            if (result.bytesRead === 0) break;
+            bytesRead += result.bytesRead;
+        }
+        const after = await handle.stat();
+        if (
+            bytesRead !== metadata.size ||
+            after.size !== metadata.size ||
+            after.mtimeMs !== metadata.mtimeMs ||
+            after.ctimeMs !== metadata.ctimeMs
+        ) {
+            throw new Error('Environment definition changed while reading');
+        }
         definition = parseCodeEnvironment(
             buffer.subarray(0, bytesRead).toString('utf8'),
         );
diff --git a/packages/code/src/private-storage.ts b/packages/code/src/private-storage.ts
index 25f23a2a..d896de33 100644
--- a/packages/code/src/private-storage.ts
+++ b/packages/code/src/private-storage.ts
@@ -48,12 +48,15 @@ export async function removePrivateStorageAcl(
  * links one component at a time so even intermediate link targets are checked.
  * Other local accounts cannot replace a checked entry: its parent is either
  * non-writable or sticky and the entry belongs to this account or root.
+ * Returns every traversed entry, including intermediate symlinks, so callers
+ * can also enforce containment restrictions without resolving those entries away.
  */
 export async function assertPrivateStorageAncestors(
   path: string,
   allowMissing = false,
-): Promise<void> {
+): Promise<string[]> {
   assertPrivateStorageSupported();
+  const visited: string[] = [];
   const uid = process.getuid!();
   let current = '/';
   const pending = (isAbsolute(path) ? path : `${process.cwd()}/${path}`).split('/');
@@ -63,7 +66,8 @@ export async function assertPrivateStorageAncestors(
       if (allowMissing && error.code === 'ENOENT') return undefined;
       throw error;
     });
-    if (metadata === undefined) return;
+    if (metadata === undefined) return visited;
+    visited.push(current);
     if (metadata.uid !== uid && metadata.uid !== 0) {
       throw new BridgeProtocolError(
         `${current} is owned by another account (uid ${metadata.uid}), ` +
@@ -102,7 +106,7 @@ export async function assertPrivateStorageAncestors(
     }
     let next = pending.shift();
     while (next === '' || next === '.') next = pending.shift();
-    if (next === undefined) return;
+    if (next === undefined) return visited;
     current = next === '..' ? dirname(current) : `${current === '/' ? '' : current}/${next}`;
   }
 }
diff --git a/packages/code/src/worker.ts b/packages/code/src/worker.ts
index 6abcd054..86e85872 100644
--- a/packages/code/src/worker.ts
+++ b/packages/code/src/worker.ts
@@ -192,6 +192,13 @@ function workspaceCapabilitiesMatch(
       (workspace, index) =>
         workspace.id === executor.workspaces[index]?.id &&
         workspace.name === executor.workspaces[index]?.name &&
+        workspace.environment?.fingerprint === executor.workspaces[index]?.environment?.fingerprint &&
+        workspace.environment?.repo === executor.workspaces[index]?.environment?.repo &&
+        workspace.environment?.ref === executor.workspaces[index]?.environment?.ref &&
+        workspace.environment?.actions.length === executor.workspaces[index]?.environment?.actions.length &&
+        (workspace.environment?.actions.every(
+          (action, actionIndex) => action === executor.workspaces[index]?.environment?.actions[actionIndex],
+        ) ?? executor.workspaces[index]?.environment == null) &&
         workspace.operations?.length ===
           executor.workspaces[index]?.operations?.length &&
         (workspace.operations?.every(
diff --git a/packages/code/src/workspace-worker.test.ts b/packages/code/src/workspace-worker.test.ts
index 684a6cb1..d97735dc 100644
--- a/packages/code/src/workspace-worker.test.ts
+++ b/packages/code/src/workspace-worker.test.ts
@@ -2446,6 +2446,32 @@ test('worker refuses to advertise workspace tools without a matching executor',
   );
 });
 
+test('worker refuses environment metadata that differs from its executor', () => {
+  const environment = { fingerprint: 'a'.repeat(64), repo: 'owner/repo', ref: 'main', actions: [] as string[] };
+  const workspaceTools = {
+    protocolVersion: 1 as const,
+    operations: ['read_file' as const],
+    workspaces: [{ id: 'primary', environment }],
+  };
+  for (const changed of [
+    undefined,
+    { ...environment, fingerprint: 'b'.repeat(64) },
+    { ...environment, repo: 'other/repo' },
+    { ...environment, ref: 'other' },
+    { ...environment, actions: ['test'] },
+  ]) {
+    assert.throws(() => new BridgeWorker({
+      codeApiUrl: 'https://code.example/v1', token: 'worker-secret', workerId: 'vm-1', incarnationId,
+      sandboxEndpoint: 'http://127.0.0.1:2000/api/v2',
+      capabilities: { statefulWorkspace: true, sandboxProfile: 'nsjail', runtimes: ['bash'], workspaceTools },
+      workspaceTools: {
+        capabilities: { ...workspaceTools, workspaces: [{ id: 'primary', ...(changed ? { environment: changed } : {}) }] },
+        async execute() { throw new Error('not executed'); },
+      },
+    }), /workspace tool capabilities require a matching executor/i);
+  }
+});
+
 test('worker requires durable quarantine before advertising command execution', () => {
   const workspaceCapabilities = {
     protocolVersion: 1 as const,

From dc57e12f101262a783b5bd35b3322aa4e8ef4efd Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 17:47:44 -0400
Subject: [PATCH 4/8] Protect environment root traversal and exact config bytes

---
 packages/code/src/cli.ts                   |  4 +--
 packages/code/src/environment-live.test.ts |  1 +
 packages/code/src/environment.test.ts      | 35 ++++++++++++++++++++++
 packages/code/src/environment.ts           | 28 ++++++++++++++---
 4 files changed, 62 insertions(+), 6 deletions(-)

diff --git a/packages/code/src/cli.ts b/packages/code/src/cli.ts
index 81637c85..7255cd46 100644
--- a/packages/code/src/cli.ts
+++ b/packages/code/src/cli.ts
@@ -340,10 +340,10 @@ async function run(
             ) ||
             [
                 process.env.LIBRECHAT_CODE_WORKER_DIR,
-                process.env.LIBRECHAT_CODE_DEFAULT_WORKSPACE,
                 process.env.LIBRECHAT_CODE_WORKSPACE_ID,
                 process.env.LIBRECHAT_CODE_WORKSPACE_NAME,
-            ].some(value => value?.trim()))
+            ].some(value => value?.trim()) ||
+            process.env.LIBRECHAT_CODE_DEFAULT_WORKSPACE?.trim().toLowerCase() === 'true')
     ) {
         throw new Error(
             '--environment cannot be combined with workspace directory, ID, or name settings',
diff --git a/packages/code/src/environment-live.test.ts b/packages/code/src/environment-live.test.ts
index cee50a63..bb84c8b5 100644
--- a/packages/code/src/environment-live.test.ts
+++ b/packages/code/src/environment-live.test.ts
@@ -81,6 +81,7 @@ for (const { succeeds, reset } of [
                         LIBRECHAT_CODE_URL: `http://127.0.0.1:${address.port}/v1`,
                         LIBRECHAT_CODE_WORKER_ID: 'environment-test',
                         LIBRECHAT_CODE_WORKER_TOKEN: 'test-only-token',
+                        LIBRECHAT_CODE_DEFAULT_WORKSPACE: 'false',
                         LIBRECHAT_CODE_WORKSPACE_QUARANTINE_FILE: join(
                             directory,
                             'quarantine.json',
diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index 75d79773..967d6ef1 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -269,6 +269,41 @@ test('reads complete definitions despite short filesystem reads', async t => {
     );
 });
 
+test('rejects a root routed through another workspace and malformed UTF-8', async t => {
+    const directory = await realpath(
+        await mkdtemp(join(tmpdir(), 'code-env-root-')),
+    );
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    const rootA = join(directory, 'a');
+    const rootB = join(directory, 'b');
+    await mkdir(rootA);
+    await mkdir(rootB);
+    await symlink(rootA, join(rootB, 'pivot'));
+    const path = join(directory, 'environment.yaml');
+    await writeFile(path, `name: a\nroot: ${join(rootB, 'pivot')}\n`);
+    const loaded = await loadCodeEnvironment(path);
+    assert.throws(
+        () =>
+            assertEnvironmentDefinitionsOutsideRoots(
+                [loaded],
+                [
+                    { id: 'a', root: rootA },
+                    { id: 'b', root: rootB },
+                ],
+            ),
+        /root traversal/,
+    );
+    await writeFile(
+        path,
+        Buffer.concat([
+            Buffer.from(`name: a\nroot: ${rootA}\nsetup: { command: echo `),
+            Buffer.from([0xff]),
+            Buffer.from(' }'),
+        ]),
+    );
+    await assert.rejects(loadCodeEnvironment(path), /encoded data/);
+});
+
 test('rejects a FIFO definition without waiting for a writer', async t => {
     const directory = await mkdtemp(join(tmpdir(), 'code-env-fifo-'));
     t.after(() => rm(directory, { recursive: true, force: true }));
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index db9e0ac1..9be98ca3 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -28,6 +28,7 @@ export interface CodeEnvironmentDefinition {
 export interface LoadedCodeEnvironment {
     path: string;
     sourceParents?: string[];
+    rootPaths?: string[];
     definition: CodeEnvironmentDefinition;
     fingerprint: string;
 }
@@ -281,20 +282,23 @@ export async function loadCodeEnvironment(
             throw new Error('Environment definition changed while reading');
         }
         definition = parseCodeEnvironment(
-            buffer.subarray(0, bytesRead).toString('utf8'),
+            new TextDecoder('utf-8', { fatal: true }).decode(
+                buffer.subarray(0, bytesRead),
+            ),
         );
     } finally {
         await handle.close();
     }
-    const root = await realpath(
-        resolve(dirname(canonicalPath), definition.root),
-    );
+    const rootPath = resolve(dirname(canonicalPath), definition.root);
+    const rootPaths = await assertPrivateStorageAncestors(rootPath);
+    const root = await realpath(rootPath);
     if (!(await stat(root)).isDirectory())
         throw new Error('Environment root must be a directory');
     definition = { ...definition, root };
     return {
         path: canonicalPath,
         sourceParents,
+        rootPaths,
         definition,
         fingerprint: createHash('sha256')
             .update(JSON.stringify(definition))
@@ -309,6 +313,22 @@ export function assertEnvironmentDefinitionsOutsideRoots(
 ): void {
     for (const environment of environments) {
         for (const root of roots) {
+            // A different granted workspace must not control how this root resolves on restart.
+            if (root.id !== environment.definition.name) {
+                for (const component of environment.rootPaths ?? []) {
+                    const path = relative(root.root, component);
+                    if (
+                        path === '' ||
+                        (!isAbsolute(path) &&
+                            path !== '..' &&
+                            !path.startsWith(`..${sep}`))
+                    ) {
+                        throw new Error(
+                            'Environment root traversal crosses another registered workspace',
+                        );
+                    }
+                }
+            }
             for (const controlPath of [
                 environment.path,
                 ...(environment.sourceParents ?? []),

From 19c89683de6f8409a7e2eb33b6fc7c5270eab2bd Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 17:56:13 -0400
Subject: [PATCH 5/8] Reject self-controlled environment root aliases

---
 packages/code/src/environment.test.ts | 11 +++++++++++
 packages/code/src/environment.ts      |  8 +++++---
 2 files changed, 16 insertions(+), 3 deletions(-)

diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index 967d6ef1..31e4247c 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -293,6 +293,17 @@ test('rejects a root routed through another workspace and malformed UTF-8', asyn
             ),
         /root traversal/,
     );
+    await symlink(rootA, join(rootA, 'self-pivot'));
+    await writeFile(path, `name: a\nroot: ${join(rootA, 'self-pivot')}\n`);
+    const selfControlled = await loadCodeEnvironment(path);
+    assert.throws(
+        () =>
+            assertEnvironmentDefinitionsOutsideRoots(
+                [selfControlled],
+                [{ id: 'a', root: rootA }],
+            ),
+        /root traversal/,
+    );
     await writeFile(
         path,
         Buffer.concat([
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index 9be98ca3..a707fb5c 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -313,10 +313,12 @@ export function assertEnvironmentDefinitionsOutsideRoots(
 ): void {
     for (const environment of environments) {
         for (const root of roots) {
-            // A different granted workspace must not control how this root resolves on restart.
-            if (root.id !== environment.definition.name) {
+            // No granted workspace may control how this root resolves on restart.
+            {
                 for (const component of environment.rootPaths ?? []) {
                     const path = relative(root.root, component);
+                    if (path === '' && root.id === environment.definition.name)
+                        continue;
                     if (
                         path === '' ||
                         (!isAbsolute(path) &&
@@ -324,7 +326,7 @@ export function assertEnvironmentDefinitionsOutsideRoots(
                             !path.startsWith(`..${sep}`))
                     ) {
                         throw new Error(
-                            'Environment root traversal crosses another registered workspace',
+                            'Environment root traversal crosses a workspace-controlled component',
                         );
                     }
                 }

From 700e875a35430fc2ecea9453cf62e66c8b648cc0 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 18:03:33 -0400
Subject: [PATCH 6/8] Check filesystem identities at environment trust
 boundaries

---
 packages/code/src/cli.ts              |  2 +-
 packages/code/src/environment.test.ts | 36 ++++++++++++++++++++++-----
 packages/code/src/environment.ts      | 18 ++++++++++++--
 3 files changed, 47 insertions(+), 9 deletions(-)

diff --git a/packages/code/src/cli.ts b/packages/code/src/cli.ts
index 7255cd46..5498af63 100644
--- a/packages/code/src/cli.ts
+++ b/packages/code/src/cli.ts
@@ -596,7 +596,7 @@ async function run(
             writable: allowWorkspaceWrites,
         });
     }
-    assertEnvironmentDefinitionsOutsideRoots(environments, roots);
+    await assertEnvironmentDefinitionsOutsideRoots(environments, roots);
   for (let i = 0; i < args.length; i++) {
     if (
       args[i] === '--workspace' &&
diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index 31e4247c..73b390e1 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -153,7 +153,7 @@ test('environment roots resolve relative to the definition and fingerprints cove
     );
     const first = await loadCodeEnvironment(path);
     assert.ok(first.definition.root.endsWith('/project'));
-    assertEnvironmentDefinitionsOutsideRoots(
+    await assertEnvironmentDefinitionsOutsideRoots(
         [first],
         [{ id: 'app', root: first.definition.root }],
     );
@@ -165,7 +165,7 @@ test('environment roots resolve relative to the definition and fingerprints cove
         (await loadCodeEnvironment(path)).fingerprint,
         first.fingerprint,
     );
-    assert.throws(() =>
+    await assert.rejects(() =>
         assertEnvironmentDefinitionsOutsideRoots(
             [first],
             [
@@ -180,7 +180,7 @@ test('environment roots resolve relative to the definition and fingerprints cove
     const alias = await loadCodeEnvironment(
         join(directory, 'project', 'alias.yaml'),
     );
-    assert.throws(() =>
+    await assert.rejects(() =>
         assertEnvironmentDefinitionsOutsideRoots(
             [alias],
             [{ id: 'app', root: first.definition.root }],
@@ -221,7 +221,7 @@ test('rejects nested aliases passing through a workspace-controlled link', async
     const loaded = await loadCodeEnvironment(
         join(directory, 'alias', 'environment.yaml'),
     );
-    assert.throws(
+    await assert.rejects(
         () =>
             assertEnvironmentDefinitionsOutsideRoots(
                 [loaded],
@@ -282,7 +282,7 @@ test('rejects a root routed through another workspace and malformed UTF-8', asyn
     const path = join(directory, 'environment.yaml');
     await writeFile(path, `name: a\nroot: ${join(rootB, 'pivot')}\n`);
     const loaded = await loadCodeEnvironment(path);
-    assert.throws(
+    await assert.rejects(
         () =>
             assertEnvironmentDefinitionsOutsideRoots(
                 [loaded],
@@ -296,7 +296,7 @@ test('rejects a root routed through another workspace and malformed UTF-8', asyn
     await symlink(rootA, join(rootA, 'self-pivot'));
     await writeFile(path, `name: a\nroot: ${join(rootA, 'self-pivot')}\n`);
     const selfControlled = await loadCodeEnvironment(path);
-    assert.throws(
+    await assert.rejects(
         () =>
             assertEnvironmentDefinitionsOutsideRoots(
                 [selfControlled],
@@ -322,3 +322,27 @@ test('rejects a FIFO definition without waiting for a writer', async t => {
     execFileSync('mkfifo', ['-m', '600', path], { timeout: 2000 });
     await assert.rejects(loadCodeEnvironment(path), /Invalid environment file/);
 });
+
+test('rejects a filesystem-identical control directory despite a different root path', async t => {
+    const directory = await realpath(
+        await mkdtemp(join(tmpdir(), 'code-env-identity-')),
+    );
+    t.after(() => rm(directory, { recursive: true, force: true }));
+    const trusted = join(directory, 'trusted');
+    const alias = join(directory, 'alias');
+    const project = join(directory, 'project');
+    await mkdir(trusted);
+    await mkdir(project);
+    await symlink(trusted, alias);
+    const path = join(trusted, 'environment.yaml');
+    await writeFile(path, `name: app\nroot: ${project}\n`);
+    const loaded = await loadCodeEnvironment(path);
+    // Unlike realpath-based containment, inode comparison also covers bind-mount aliases.
+    await assert.rejects(
+        assertEnvironmentDefinitionsOutsideRoots(
+            [loaded],
+            [{ id: 'alias', root: alias }],
+        ),
+        /outside/,
+    );
+});
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index a707fb5c..a10eabcb 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -307,12 +307,24 @@ export async function loadCodeEnvironment(
 }
 
 /** A workspace must never be able to rewrite a definition used on the next startup. */
-export function assertEnvironmentDefinitionsOutsideRoots(
+export async function assertEnvironmentDefinitionsOutsideRoots(
     environments: readonly LoadedCodeEnvironment[],
     roots: readonly LocalWorkspaceConfig[],
-): void {
+): Promise<void> {
+    const identities = new Map<string, Promise<string>>();
+    const identity = (path: string): Promise<string> => {
+        let result = identities.get(path);
+        if (!result) {
+            result = stat(path).then(
+                metadata => `${metadata.dev}:${metadata.ino}`,
+            );
+            identities.set(path, result);
+        }
+        return result;
+    };
     for (const environment of environments) {
         for (const root of roots) {
+            const rootIdentity = await identity(root.root);
             // No granted workspace may control how this root resolves on restart.
             {
                 for (const component of environment.rootPaths ?? []) {
@@ -320,6 +332,7 @@ export function assertEnvironmentDefinitionsOutsideRoots(
                     if (path === '' && root.id === environment.definition.name)
                         continue;
                     if (
+                        (await identity(component)) === rootIdentity ||
                         path === '' ||
                         (!isAbsolute(path) &&
                             path !== '..' &&
@@ -337,6 +350,7 @@ export function assertEnvironmentDefinitionsOutsideRoots(
             ]) {
                 const path = relative(root.root, controlPath);
                 if (
+                    (await identity(controlPath)) === rootIdentity ||
                     path === '' ||
                     (!isAbsolute(path) &&
                         path !== '..' &&

From efe1aa15f00c36c567734ca6254b2e186f0e01a3 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 18:13:37 -0400
Subject: [PATCH 7/8] Validate environment containment across Linux mount
 aliases

---
 packages/code/README.md                     |   5 +
 packages/code/src/environment-mount.test.ts |  68 +++++++++++
 packages/code/src/environment-mount.ts      | 127 ++++++++++++++++++++
 packages/code/src/environment.ts            |  33 +++++
 4 files changed, 233 insertions(+)
 create mode 100644 packages/code/src/environment-mount.test.ts
 create mode 100644 packages/code/src/environment-mount.ts

diff --git a/packages/code/README.md b/packages/code/README.md
index 22abc705..f47210fb 100644
--- a/packages/code/README.md
+++ b/packages/code/README.md
@@ -680,6 +680,11 @@ Repository and ref are descriptive metadata, not a clone or checkout instruction
 No Git repository is required. Definitions are loaded once at startup, hashed into
 the worker's policy identity, and protected from sandbox writes. All definition
 files must be outside every registered root. Unknown fields are rejected.
+On Linux, startup also verifies the mount namespace so bind mounts cannot expose
+definitions or their controlling paths through a workspace. The mount table is
+bounded to 4 MiB, with at most 256 exposed mount boundaries; ambiguous stacked
+mount mappings fail closed. Operators must keep mount topology stable while the
+worker runs. This inspection happens at startup, not on the command hot path.
 
 Setup is an operator-authorized startup command under the configured native sandbox
 policy. It requires commands to be enabled, runs once per worker startup before
diff --git a/packages/code/src/environment-mount.test.ts b/packages/code/src/environment-mount.test.ts
new file mode 100644
index 00000000..67448b22
--- /dev/null
+++ b/packages/code/src/environment-mount.test.ts
@@ -0,0 +1,68 @@
+import assert from 'node:assert/strict';
+import test from 'node:test';
+import { assertEnvironmentMountIsolation } from './environment-mount.js';
+
+const base = '1 0 8:1 / / rw - ext4 /dev/root rw\n';
+test('mount coordinates reject definition aliases in both directions and mounted files', () => {
+    for (const entry of [
+        '2 1 8:1 /workspace/config /operator rw - ext4 /dev/root rw',
+        '2 1 8:1 /operator /workspace/config rw - ext4 /dev/root rw',
+        '2 1 8:1 /operator/app.yaml /workspace/app.yaml rw - ext4 /dev/root rw',
+        '2 1 8:1 /workspace/app.yaml /operator/app.yaml rw - ext4 /dev/root rw',
+    ])
+        assert.throws(
+            () =>
+                assertEnvironmentMountIsolation(
+                    base + entry,
+                    ['/operator/app.yaml'],
+                    ['/workspace'],
+                ),
+            /mount alias/,
+        );
+});
+test('mount coordinates retain safe separate filesystems and escaped paths', () => {
+    assertEnvironmentMountIsolation(
+        base + '2 1 9:1 / /workspace rw - ext4 /dev/other rw',
+        ['/operator/app.yaml'],
+        ['/workspace'],
+    );
+    assertEnvironmentMountIsolation(
+        base,
+        ['/operator/app.yaml'],
+        ['/workspace'],
+    );
+    assert.throws(
+        () =>
+            assertEnvironmentMountIsolation(
+                base +
+                    '2 1 8:1 /workspace/my\\040config /operator rw - ext4 /dev/root rw',
+                ['/operator/app.yaml'],
+                ['/workspace'],
+            ),
+        /mount alias/,
+    );
+    assert.throws(() => assertEnvironmentMountIsolation('invalid', [], []));
+    assert.throws(
+        () =>
+            assertEnvironmentMountIsolation(
+                base + '2 1 9:1 / / rw - ext4 /dev/other rw',
+                [],
+                [],
+            ),
+        /Ambiguous/,
+    );
+    const many = Array.from(
+        { length: 257 },
+        (_, index) =>
+            `${index + 2} 1 9:1 / /workspace/m${index} rw - ext4 /dev/other rw`,
+    ).join('\n');
+    assert.throws(
+        () =>
+            assertEnvironmentMountIsolation(
+                base + many,
+                ['/operator/app.yaml'],
+                ['/workspace'],
+            ),
+        /Too many/,
+    );
+});
diff --git a/packages/code/src/environment-mount.ts b/packages/code/src/environment-mount.ts
new file mode 100644
index 00000000..1aa0dd60
--- /dev/null
+++ b/packages/code/src/environment-mount.ts
@@ -0,0 +1,127 @@
+import { open } from 'node:fs/promises';
+import { posix } from 'node:path';
+
+interface Mount {
+    device: string;
+    root: string;
+    point: string;
+}
+const inside = (root: string, path: string): boolean =>
+    path === root || path.startsWith(root === '/' ? '/' : `${root}/`);
+const decode = (path: string): string => {
+    if (!path.startsWith('/') || /\\(?!040|011|012|134)/.test(path))
+        throw new Error('Invalid environment mount table');
+    return path.replace(/\\(040|011|012|134)/g, (_, octal: string) =>
+        String.fromCharCode(parseInt(octal, 8)),
+    );
+};
+
+/** Compare filesystem coordinates, not mount aliases. Include mounted descendants of each grant. */
+export function createEnvironmentMountIsolation(
+    table: string,
+): (controls: readonly string[], roots: readonly string[]) => void {
+    if (Buffer.byteLength(table) > 4 * 1024 * 1024)
+        throw new Error('Environment mount table exceeds limit');
+    const mounts: Mount[] = table
+        .trimEnd()
+        .split('\n')
+        .map(line => {
+            const fields = line.split(' ');
+            const separator = fields.indexOf('-', 6);
+            if (
+                separator < 6 ||
+                fields.length !== separator + 4 ||
+                !/^\d+:\d+$/.test(fields[2] ?? '')
+            )
+                throw new Error('Invalid environment mount table');
+            return {
+                device: fields[2],
+                root: decode(fields[3] ?? ''),
+                point: decode(fields[4] ?? ''),
+            };
+        });
+    const mappings = new Map<string, string>();
+    for (const mount of mounts) {
+        const mapping = `${mount.device}:${mount.root}`;
+        const previous = mappings.get(mount.point);
+        if (previous !== undefined && previous !== mapping)
+            throw new Error('Ambiguous environment mount topology');
+        mappings.set(mount.point, mapping);
+    }
+    const cache = new Map<string, { device: string; path: string }>();
+    const coordinate = (path: string): { device: string; path: string } => {
+        const cached = cache.get(path);
+        if (cached) return cached;
+        let mount: Mount | undefined;
+        for (const candidate of mounts)
+            if (
+                inside(candidate.point, path) &&
+                (!mount || candidate.point.length >= mount.point.length)
+            )
+                mount = candidate;
+        if (!mount) throw new Error('Environment path has no mount mapping');
+        const result = {
+            device: mount.device,
+            path: posix.join(mount.root, posix.relative(mount.point, path)),
+        };
+        cache.set(path, result);
+        return result;
+    };
+    return (controls, roots) => {
+        const points = new Set(roots);
+        for (const mount of mounts)
+            if (roots.some(root => inside(root, mount.point)))
+                points.add(mount.point);
+        if (points.size > 256)
+            throw new Error('Too many workspace mount boundaries');
+        const exposed = [...points].map(coordinate);
+        for (const control of controls) {
+            const target = coordinate(control);
+            if (
+                exposed.some(
+                    root =>
+                        root.device === target.device &&
+                        inside(root.path, target.path),
+                )
+            ) {
+                throw new Error(
+                    'Environment control path is writable through a workspace mount alias',
+                );
+            }
+        }
+    };
+}
+
+export function assertEnvironmentMountIsolation(
+    table: string,
+    controls: readonly string[],
+    roots: readonly string[],
+): void {
+    createEnvironmentMountIsolation(table)(controls, roots);
+}
+
+export async function readEnvironmentMountTable(): Promise<string | undefined> {
+    if (process.platform !== 'linux') return undefined;
+    const handle = await open('/proc/self/mountinfo', 'r');
+    try {
+        const buffer = Buffer.alloc(4 * 1024 * 1024 + 1);
+        let length = 0;
+        while (length < buffer.length) {
+            const result = await handle.read(
+                buffer,
+                length,
+                buffer.length - length,
+                null,
+            );
+            if (!result.bytesRead) break;
+            length += result.bytesRead;
+        }
+        if (length === buffer.length)
+            throw new Error('Environment mount table exceeds limit');
+        return new TextDecoder('utf-8', { fatal: true }).decode(
+            buffer.subarray(0, length),
+        );
+    } finally {
+        await handle.close();
+    }
+}
diff --git a/packages/code/src/environment.ts b/packages/code/src/environment.ts
index a10eabcb..700fc0dc 100644
--- a/packages/code/src/environment.ts
+++ b/packages/code/src/environment.ts
@@ -13,6 +13,10 @@ import {
 } from './protocol.js';
 import type { LocalWorkspaceConfig } from './workspace.js';
 import { WorkspaceToolError } from './workspace.js';
+import {
+    createEnvironmentMountIsolation,
+    readEnvironmentMountTable,
+} from './environment-mount.js';
 import type { WorkspaceToolExecutor } from './workspace.js';
 import type { WorkspaceToolRequest, WorkspaceToolResult } from './protocol.js';
 
@@ -311,6 +315,35 @@ export async function assertEnvironmentDefinitionsOutsideRoots(
     environments: readonly LoadedCodeEnvironment[],
     roots: readonly LocalWorkspaceConfig[],
 ): Promise<void> {
+    if (!environments.length) return;
+    const mountTable = await readEnvironmentMountTable();
+    if (mountTable !== undefined) {
+        const assertMountIsolation =
+            createEnvironmentMountIsolation(mountTable);
+        assertMountIsolation(
+            environments.flatMap(environment => [
+                environment.path,
+                ...(environment.sourceParents ?? []),
+            ]),
+            roots.map(root => root.root),
+        );
+        for (const environment of environments) {
+            assertMountIsolation(
+                environment.rootPaths ?? [],
+                roots
+                    .filter(root => root.id !== environment.definition.name)
+                    .map(root => root.root),
+            );
+            assertMountIsolation(
+                (environment.rootPaths ?? []).filter(
+                    path => path !== environment.definition.root,
+                ),
+                roots
+                    .filter(root => root.id === environment.definition.name)
+                    .map(root => root.root),
+            );
+        }
+    }
     const identities = new Map<string, Promise<string>>();
     const identity = (path: string): Promise<string> => {
         let result = identities.get(path);

From 5bea52e0a98d0a4b7e10caceffba8a8742d65356 Mon Sep 17 00:00:00 2001
From: Danny Avila <danny@librechat.ai>
Date: Mon, 14 Sep 2026 18:18:10 -0400
Subject: [PATCH 8/8] Handle stacked mounts conservatively without blocking
 unrelated paths

---
 packages/code/README.md                     |  4 +-
 packages/code/src/environment-mount.test.ts | 11 +++--
 packages/code/src/environment-mount.ts      | 50 ++++++++++-----------
 packages/code/src/environment.test.ts       |  8 ++--
 4 files changed, 37 insertions(+), 36 deletions(-)

diff --git a/packages/code/README.md b/packages/code/README.md
index f47210fb..c3bb16d3 100644
--- a/packages/code/README.md
+++ b/packages/code/README.md
@@ -682,8 +682,8 @@ the worker's policy identity, and protected from sandbox writes. All definition
 files must be outside every registered root. Unknown fields are rejected.
 On Linux, startup also verifies the mount namespace so bind mounts cannot expose
 definitions or their controlling paths through a workspace. The mount table is
-bounded to 4 MiB, with at most 256 exposed mount boundaries; ambiguous stacked
-mount mappings fail closed. Operators must keep mount topology stable while the
+bounded to 4 MiB, with at most 256 exposed mount boundaries; stacked and hidden
+mount mappings are considered conservatively. Operators must keep mount topology stable while the
 worker runs. This inspection happens at startup, not on the command hot path.
 
 Setup is an operator-authorized startup command under the configured native sandbox
diff --git a/packages/code/src/environment-mount.test.ts b/packages/code/src/environment-mount.test.ts
index 67448b22..fdd5b581 100644
--- a/packages/code/src/environment-mount.test.ts
+++ b/packages/code/src/environment-mount.test.ts
@@ -42,14 +42,19 @@ test('mount coordinates retain safe separate filesystems and escaped paths', ()
         /mount alias/,
     );
     assert.throws(() => assertEnvironmentMountIsolation('invalid', [], []));
+    assertEnvironmentMountIsolation(
+        base + '2 1 9:1 / / rw - ext4 /dev/other rw',
+        ['/operator/app.yaml'],
+        ['/workspace'],
+    );
     assert.throws(
         () =>
             assertEnvironmentMountIsolation(
                 base + '2 1 9:1 / / rw - ext4 /dev/other rw',
-                [],
-                [],
+                ['/workspace/config/app.yaml'],
+                ['/workspace'],
             ),
-        /Ambiguous/,
+        /mount alias/,
     );
     const many = Array.from(
         { length: 257 },
diff --git a/packages/code/src/environment-mount.ts b/packages/code/src/environment-mount.ts
index 1aa0dd60..bbc8483e 100644
--- a/packages/code/src/environment-mount.ts
+++ b/packages/code/src/environment-mount.ts
@@ -40,30 +40,22 @@ export function createEnvironmentMountIsolation(
                 point: decode(fields[4] ?? ''),
             };
         });
-    const mappings = new Map<string, string>();
-    for (const mount of mounts) {
-        const mapping = `${mount.device}:${mount.root}`;
-        const previous = mappings.get(mount.point);
-        if (previous !== undefined && previous !== mapping)
-            throw new Error('Ambiguous environment mount topology');
-        mappings.set(mount.point, mapping);
-    }
-    const cache = new Map<string, { device: string; path: string }>();
-    const coordinate = (path: string): { device: string; path: string } => {
+    const cache = new Map<string, { device: string; path: string }[]>();
+    const coordinate = (path: string): { device: string; path: string }[] => {
         const cached = cache.get(path);
         if (cached) return cached;
-        let mount: Mount | undefined;
-        for (const candidate of mounts)
-            if (
-                inside(candidate.point, path) &&
-                (!mount || candidate.point.length >= mount.point.length)
-            )
-                mount = candidate;
-        if (!mount) throw new Error('Environment path has no mount mapping');
-        const result = {
-            device: mount.device,
-            path: posix.join(mount.root, posix.relative(mount.point, path)),
-        };
+        // Include every possible backing mapping. Hidden/stacked mounts may cause
+        // conservative rejection but must never hide an accessible control path.
+        const result = mounts
+            .filter(mount => inside(mount.point, path))
+            .map(mount => ({
+                device: mount.device,
+                path: posix.join(mount.root, posix.relative(mount.point, path)),
+            }));
+        if (!result.length || result.length > 256)
+            throw new Error(
+                'Environment path has an unsupported mount mapping',
+            );
         cache.set(path, result);
         return result;
     };
@@ -74,14 +66,18 @@ export function createEnvironmentMountIsolation(
                 points.add(mount.point);
         if (points.size > 256)
             throw new Error('Too many workspace mount boundaries');
-        const exposed = [...points].map(coordinate);
+        const exposed = [...points].flatMap(coordinate);
+        if (exposed.length > 1024)
+            throw new Error('Too many workspace mount mappings');
         for (const control of controls) {
             const target = coordinate(control);
             if (
-                exposed.some(
-                    root =>
-                        root.device === target.device &&
-                        inside(root.path, target.path),
+                target.some(target =>
+                    exposed.some(
+                        root =>
+                            root.device === target.device &&
+                            inside(root.path, target.path),
+                    ),
                 )
             ) {
                 throw new Error(
diff --git a/packages/code/src/environment.test.ts b/packages/code/src/environment.test.ts
index 73b390e1..9080f6a2 100644
--- a/packages/code/src/environment.test.ts
+++ b/packages/code/src/environment.test.ts
@@ -227,7 +227,7 @@ test('rejects nested aliases passing through a workspace-controlled link', async
                 [loaded],
                 [{ id: 'app', root }],
             ),
-        /outside/,
+        /outside|mount alias/,
     );
 });
 
@@ -291,7 +291,7 @@ test('rejects a root routed through another workspace and malformed UTF-8', asyn
                     { id: 'b', root: rootB },
                 ],
             ),
-        /root traversal/,
+        /root traversal|mount alias/,
     );
     await symlink(rootA, join(rootA, 'self-pivot'));
     await writeFile(path, `name: a\nroot: ${join(rootA, 'self-pivot')}\n`);
@@ -302,7 +302,7 @@ test('rejects a root routed through another workspace and malformed UTF-8', asyn
                 [selfControlled],
                 [{ id: 'a', root: rootA }],
             ),
-        /root traversal/,
+        /root traversal|mount alias/,
     );
     await writeFile(
         path,
@@ -343,6 +343,6 @@ test('rejects a filesystem-identical control directory despite a different root
             [loaded],
             [{ id: 'alias', root: alias }],
         ),
-        /outside/,
+        /outside|mount alias/,
     );
 });