feat(server): WORKSPACE_STATE_DIR override for mutable state (token, master key, logs)

The server resolves its encrypted token, master key, and log directory
against PROJECT_ROOT (the extension checkout). When the package is
installed in a read-only location (e.g. a system-wide install owned by
root while the server runs as an unprivileged user), those writes fail
with EACCES. WORKSPACE_STATE_DIR points mutable state at a writable
directory; the default (PROJECT_ROOT) is unchanged.

Author: Federico Liva

workspace-server/dist/headless-login.js

@@ -44,6 +44,7 @@ jest.mock('node:path', () => {
 });
 jest.mock('../../utils/paths', () => ({
   PROJECT_ROOT: '/mock/project/root',
+  STATE_DIR: '/mock/project/root',
   ENCRYPTED_TOKEN_PATH: '/mock/project/root/token.json',
   ENCRYPTION_MASTER_KEY_PATH: '/mock/project/root/key',
 }));

workspace-server/dist/index.js

@@ -26,4 +26,44 @@ describe('paths utils', () => {
       expect(PROJECT_ROOT.endsWith('workspace-server')).toBe(false);
     });
   });
+
+  describe('STATE_DIR', () => {
+    const reload = () => {
+      jest.resetModules();
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      return require('../../utils/paths') as typeof import('../../utils/paths');
+    };
+
+    afterEach(() => {
+      delete process.env['WORKSPACE_STATE_DIR'];
+      jest.resetModules();
+    });
+
+    it('defaults to PROJECT_ROOT when WORKSPACE_STATE_DIR is unset', () => {
+      delete process.env['WORKSPACE_STATE_DIR'];
+      const m = reload();
+      expect(m.STATE_DIR).toBe(m.PROJECT_ROOT);
+      expect(m.ENCRYPTED_TOKEN_PATH).toBe(
+        path.join(m.PROJECT_ROOT, 'gemini-cli-workspace-token.json'),
+      );
+      expect(m.ENCRYPTION_MASTER_KEY_PATH).toBe(
+        path.join(m.PROJECT_ROOT, '.gemini-cli-workspace-master-key'),
+      );
+    });
+
+    it('honors WORKSPACE_STATE_DIR for token and master-key paths', () => {
+      process.env['WORKSPACE_STATE_DIR'] = '/var/lib/workspace-state';
+      const m = reload();
+      expect(m.STATE_DIR).toBe('/var/lib/workspace-state');
+      expect(m.ENCRYPTED_TOKEN_PATH).toBe(
+        path.join('/var/lib/workspace-state', 'gemini-cli-workspace-token.json'),
+      );
+      expect(m.ENCRYPTION_MASTER_KEY_PATH).toBe(
+        path.join(
+          '/var/lib/workspace-state',
+          '.gemini-cli-workspace-master-key',
+        ),
+      );
+    });
+  });
 });

workspace-server/src/__tests__/services/DriveService.test.ts

@@ -6,9 +6,9 @@
 
 import * as fs from 'node:fs/promises';
 import * as path from 'node:path';
-import { PROJECT_ROOT } from './paths';
+import { STATE_DIR } from './paths';
 
-const logFilePath = path.join(PROJECT_ROOT, 'logs', 'server.log');
+const logFilePath = path.join(STATE_DIR, 'logs', 'server.log');
 
 async function ensureLogDirectoryExists() {
   try {

workspace-server/src/__tests__/utils/paths.test.ts

@@ -22,11 +22,23 @@ function findProjectRoot(): string {
 
 // Construct an absolute path to the project root.
 export const PROJECT_ROOT = findProjectRoot();
+
+/**
+ * Directory for mutable server state (encrypted token, master key, logs).
+ *
+ * Defaults to PROJECT_ROOT (the historical behavior, suitable when the
+ * extension runs from a user-writable checkout). Deployments that install
+ * the package in a read-only location (e.g. a system-wide install owned by
+ * root while the server runs as an unprivileged user) can point state at a
+ * writable directory via the WORKSPACE_STATE_DIR environment variable.
+ */
+export const STATE_DIR = process.env['WORKSPACE_STATE_DIR'] || PROJECT_ROOT;
+
 export const ENCRYPTED_TOKEN_PATH = path.join(
-  PROJECT_ROOT,
+  STATE_DIR,
   'gemini-cli-workspace-token.json',
 );
 export const ENCRYPTION_MASTER_KEY_PATH = path.join(
-  PROJECT_ROOT,
+  STATE_DIR,
   '.gemini-cli-workspace-master-key',
 );