@vantran-se/openchamber-web 1.22.1 → 1.23.0

package/server/lib/data-dir-migration.test.js

@@ -0,0 +1,59 @@
+import { describe, expect, it } from 'vitest';
+import os from 'os';
+import path from 'path';
+import fsPromises from 'fs/promises';
+
+import { migrateLegacyUserDirs } from './data-dir-migration.js';
+
+const setup = async () => {
+  const root = await fsPromises.mkdtemp(path.join(os.tmpdir(), 'oc-data-dir-'));
+  const legacyRoot = path.join(root, 'legacy');
+  const dataDir = path.join(root, 'custom');
+  await fsPromises.mkdir(path.join(legacyRoot, 'projects'), { recursive: true });
+  await fsPromises.writeFile(path.join(legacyRoot, 'projects', 'p.json'), '{"a":1}');
+  await fsPromises.mkdir(path.join(legacyRoot, 'themes'), { recursive: true });
+  return { root, legacyRoot, dataDir, cleanup: () => fsPromises.rm(root, { recursive: true, force: true }) };
+};
+
+describe('migrateLegacyUserDirs', () => {
+  it('copies the user folders once into a custom data dir and leaves the originals', async () => {
+    const { legacyRoot, dataDir, cleanup } = await setup();
+    try {
+      const warnings = [];
+      const moved = await migrateLegacyUserDirs({ fsPromises, path, dataDir, legacyRoot, warn: (message) => warnings.push(message) });
+      expect(moved).toEqual(['projects', 'themes']);
+      expect(warnings).toEqual([]);
+      expect(await fsPromises.readFile(path.join(dataDir, 'projects', 'p.json'), 'utf8')).toBe('{"a":1}');
+      // The default instance keeps its own copy: a second instance must not strip it.
+      expect(await fsPromises.readFile(path.join(legacyRoot, 'projects', 'p.json'), 'utf8')).toBe('{"a":1}');
+      // A second start copies nothing more.
+      expect(await migrateLegacyUserDirs({ fsPromises, path, dataDir, legacyRoot })).toEqual([]);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('never merges into a folder that already exists in the data dir', async () => {
+    const { legacyRoot, dataDir, cleanup } = await setup();
+    try {
+      await fsPromises.mkdir(path.join(dataDir, 'projects'), { recursive: true });
+      await fsPromises.writeFile(path.join(dataDir, 'projects', 'q.json'), '{}');
+      const moved = await migrateLegacyUserDirs({ fsPromises, path, dataDir, legacyRoot });
+      expect(moved).toEqual(['themes']);
+      expect(await fsPromises.readdir(path.join(dataDir, 'projects'))).toEqual(['q.json']);
+      expect(await fsPromises.readdir(path.join(legacyRoot, 'projects'))).toEqual(['p.json']);
+    } finally {
+      await cleanup();
+    }
+  });
+
+  it('is a no-op when the data dir is the default root', async () => {
+    const { legacyRoot, cleanup } = await setup();
+    try {
+      expect(await migrateLegacyUserDirs({ fsPromises, path, dataDir: legacyRoot, legacyRoot })).toEqual([]);
+      expect(await fsPromises.readdir(path.join(legacyRoot, 'projects'))).toEqual(['p.json']);
+    } finally {
+      await cleanup();
+    }
+  });
+});

package/server/lib/dev-tunnel/DOCUMENTATION.md

@@ -20,7 +20,13 @@ and what made it fragile per framework.
 - `client.js` is the local end: it binds a loopback listener on the user's
   machine and pipes each accepted connection through one WebSocket. It lives in
   this package because it needs a WebSocket client the package already depends
-  on; the desktop shell drives it over IPC.
+  on; the desktop shell drives it over IPC for directly reachable HTTP(S)
+  runtimes.
+- Relay-only runtimes use `packages/electron/relay-dev-tunnel.mjs` for the local
+  listener. Each accepted connection gets an Electron `MessagePort`; the trusted
+  renderer carries its bytes through the active E2EE relay. This keeps relay
+  credentials and encryption in their existing renderer owner instead of
+  duplicating them in Electron main.
 - Port discovery is not owned here. `runtime.js` is given the reachable set by
   the same dev-server discovery the user's own list is built from.
 - The browser panel decides when to tunnel; this module never chooses a target.
@@ -40,9 +46,12 @@ and what made it fragile per framework.
     usual origin allowlist applies unchanged. That check is a CSRF defence: a
     hostile page can make a browser open a WebSocket carrying ambient cookies,
     and the origin is what exposes it.
-  - With no `Origin` the request must carry client-token auth. A browser cannot
-    reach this path — the WebSocket API always sends an origin and never lets a
-    page set an `Authorization` header — so this case is the desktop shell.
+  - With no `Origin` the request must carry client-token auth or a short-lived
+    URL token. The bearer case is the desktop main process. The URL-token case
+    is the trusted renderer carrying the socket through the E2EE relay.
+  - Through the E2EE relay, the trusted renderer mints a short-lived URL token
+    and includes it in the virtual WebSocket URL. The relay host and URL-token
+    allowlists accept exactly `/api/dev-tunnel`, not subpaths.
 - Concurrency is capped per host, not per page, because one page load opens
   many sockets.
 - A connection that cannot be established fails the socket rather than holding

package/server/lib/dev-tunnel/runtime.js

@@ -20,9 +20,9 @@
  *
  * - With an `Origin` header, the request came from a browser context and the
  *   usual origin check applies unchanged.
- * - With no `Origin`, the request must carry client-token auth. A browser
- *   cannot reach this path: the WebSocket API always sends an origin and never
- *   lets a page set an `Authorization` header.
+ * - With no `Origin`, the request must carry client-token auth or a short-lived
+ *   URL token. The URL-token case is used only by the trusted renderer through
+ *   the E2EE relay; the UI-auth allowlist limits it to this exact path.
  */
 import net from 'node:net';
 import { WebSocketServer } from 'ws';
@@ -133,7 +133,7 @@ export function createDevTunnelRuntime({
     void (async () => {
       try {
         if (uiAuthController?.enabled) {
-          const auth = await uiAuthController.resolveAuthContext(req, null, { allowUrlToken: false });
+          const auth = await uiAuthController.resolveAuthContext(req, null, { allowUrlToken: true });
           if (!auth) {
             rejectWebSocketUpgrade(socket, 401, 'UI authentication required');
             return;

package/server/lib/dev-tunnel/tunnel.test.js

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, test } from 'bun:test';
 import http from 'node:http';
 import net from 'node:net';
+import WebSocket from 'ws';
 
 import { createDevTunnelClient } from './client.js';
 import { createDevTunnelRuntime, isDevTunnelPath } from './runtime.js';
@@ -228,6 +229,12 @@ describe('dev tunnel authentication', () => {
     enabled: true,
     resolveAuthContext: async () => ({ type: 'session' }),
   };
+  const urlTokenAuth = {
+    enabled: true,
+    resolveAuthContext: async (req, _res, options) => (
+      options?.allowUrlToken === true && req.url.includes('oc_url_token=good') ? { type: 'client', token: 'url:authenticated' } : null
+    ),
+  };
 
   test('accepts a bearer-authenticated client that sends no origin', async () => {
     const devPort = await startDevServer((_req, res) => res.end('ok'));
@@ -243,6 +250,19 @@ describe('dev tunnel authentication', () => {
     expect((await httpGet(localPort, '/')).body).toBe('ok');
   });
 
+  test('accepts a URL-token client carried by the E2EE relay', async () => {
+    const devPort = await startDevServer((_req, res) => res.end('relay-ok'));
+    const host = await startHost({ allowedPorts: [devPort], auth: urlTokenAuth });
+
+    const body = await new Promise((resolve, reject) => {
+      const socket = new WebSocket(`ws://127.0.0.1:${host.port}/api/dev-tunnel?port=${devPort}&oc_url_token=good`);
+      socket.on('open', () => socket.send('GET / HTTP/1.1\r\nHost: localhost\r\nConnection: close\r\n\r\n'));
+      socket.on('message', (data) => resolve(Buffer.from(data).toString()));
+      socket.on('error', reject);
+    });
+    expect(body).toContain('relay-ok');
+  });
+
   test('rejects a client with no credentials', async () => {
     const devPort = await startDevServer((_req, res) => res.end('ok'));
     const host = await startHost({ allowedPorts: [devPort], auth: clientAuth });

package/server/lib/event-stream/runtime.test.js

@@ -446,18 +446,18 @@ describe('message stream websocket runtime', () => {
     const socket = new FakeSocket();
     runtime.wsServer.emit('connection', socket, { url: '/api/global/event/ws' });
 
-    await new Promise((resolve) => setTimeout(resolve, 35));
-
-    const readyFrames = socket.sent.filter((frame) => frame.type === 'ready');
-    const eventFrames = socket.sent.filter((frame) => frame.type === 'event' && frame.payload?.type === 'server.connected');
-
-    expect(readyFrames.length).toBeGreaterThanOrEqual(2);
-    expect(eventFrames.length).toBeGreaterThanOrEqual(2);
-    expect(fetchCalls.slice(0, 2)).toEqual([null, 'evt-1']);
-    expect(triggerHealthCheckCalls).toBe(0);
-
-    socket.close();
-    await runtime.close();
+    try {
+      // Wait for the reconnect event itself; a 35ms sleep raced the event
+      // loop when the workspace build and test workers ran together.
+      await expect.poll(() => socket.sent.filter((frame) => frame.type === 'ready').length).toBeGreaterThanOrEqual(2);
+      const eventFrames = socket.sent.filter((frame) => frame.type === 'event' && frame.payload?.type === 'server.connected');
+      expect(eventFrames.length).toBeGreaterThanOrEqual(2);
+      expect(fetchCalls.slice(0, 2)).toEqual([null, 'evt-1']);
+      expect(triggerHealthCheckCalls).toBe(0);
+    } finally {
+      socket.close();
+      await runtime.close();
+    }
   });
 
   it('keeps synthetic event processing on forwarded upstream events', async () => {

package/server/lib/fs/DOCUMENTATION.md

@@ -14,6 +14,8 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
     - `POST /api/fs/mkdir`
     - `GET /api/fs/read`
     - `GET /api/fs/raw`
+    - `GET /api/fs/stat`
+    - `GET /api/fs/directory-stat`
     - `GET /api/fs/serve/:path(*)`
     - `POST /api/fs/write`
     - `POST /api/fs/upload`
@@ -40,7 +42,10 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
 
 ## Notes for contributors
 - Keep filesystem policy (workspace root checks, error mapping, exec timeout behavior) inside this module, not in the composition root.
+- Workspace checks accept, besides the active workspace and its worktrees, the **managed roots**: the OpenChamber config root and the managed chats root (`managedChatsRoot` dependency; `OPENCHAMBER_CHATS_DIR` upstream, default `<config root>/chats`). Chat worktrees may legitimately live outside every project workspace.
+- `GET /api/fs/home` answers `{ home, chatsRoot }`. `chatsRoot` is the server-resolved managed chats root; clients must use it instead of joining `home` + the well-known segment (a relocated root does not contain that segment).
 - Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Policy denials such as workspace-boundary or missing-grant failures must not use that marker because a native folder picker cannot remediate them.
+- `GET /api/fs/directory-stat?path=...` uses one `stat` without listing contents or resolving project topology. It follows the same authenticated directory-discovery path policy as `/api/fs/list`, including targets outside the active workspace. A directory returns `{ isDirectory: true }`; `ENOENT` returns `not-found`, and a file or `ENOTDIR` returns `not-directory`. Permission and other failures remain distinct from a missing path. VS Code explicitly returns 501, so the shared client treats its probe as unknown.
 - Read-only routes authorize the requested path against the workspace before resolving symlinks. A symlink reached through the workspace may therefore target a file outside it, while a directly requested outside path still requires an exact-path grant. Write routes keep canonical-target boundary checks.
 - If adding new `/api/fs/*` endpoints, add them in `routes.js` and extend this document.
 - `GET /api/fs/list` may resolve symlinks with `realpath` to read directory contents, but the response `path` and each entry `path` must stay in the caller's requested path space (`path.join(requestedPath, name)`). Returning real paths breaks file-tree expansion for directories reached through workspace symlinks.

package/server/lib/fs/routes.js

@@ -196,7 +196,7 @@ const isPathWithinRoot = (resolvedPath, rootPath, path, os) => {
   return true;
 };
 
-const resolveWorkspacePath = ({ targetPath, baseDirectory, path, os, normalizeDirectoryPath, openchamberUserConfigRoot }) => {
+const resolveWorkspacePath = ({ targetPath, baseDirectory, path, os, normalizeDirectoryPath, managedRoots }) => {
   const normalized = normalizeDirectoryPath(targetPath);
   if (!normalized || typeof normalized !== 'string') {
     return { ok: false, error: 'Path is required' };
@@ -209,8 +209,12 @@ const resolveWorkspacePath = ({ targetPath, baseDirectory, path, os, normalizeDi
     return { ok: true, base: resolvedBase, resolved };
   }
 
-  if (isPathWithinRoot(resolved, openchamberUserConfigRoot, path, os)) {
-    return { ok: true, base: path.resolve(openchamberUserConfigRoot), resolved };
+  // Managed roots (config root, relocated chats root) stay valid targets
+  // even outside the active workspace.
+  for (const root of managedRoots) {
+    if (isPathWithinRoot(resolved, root, path, os)) {
+      return { ok: true, base: path.resolve(root), resolved };
+    }
   }
 
   return { ok: false, error: 'Path is outside of active workspace' };
@@ -249,7 +253,7 @@ const resolveWorkspacePathFromWorktrees = async ({ targetPath, baseDirectory, pa
   return { ok: false, error: 'Path is outside of active workspace' };
 };
 
-const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProjectDirectory, path, os, normalizeDirectoryPath, openchamberUserConfigRoot }) => {
+const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProjectDirectory, path, os, normalizeDirectoryPath, managedRoots }) => {
   const resolvedProject = await resolveProjectDirectory(req);
   if (!resolvedProject.directory) {
     return { ok: false, error: resolvedProject.error || 'Active workspace is required' };
@@ -261,7 +265,7 @@ const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProject
     path,
     os,
     normalizeDirectoryPath,
-    openchamberUserConfigRoot,
+    managedRoots,
   });
   if (resolved.ok || resolved.error !== 'Path is outside of active workspace') {
     return resolved;
@@ -281,7 +285,7 @@ const resolveWorkspacePathFromContext = async ({ req, targetPath, resolveProject
       path,
       os,
       normalizeDirectoryPath,
-      openchamberUserConfigRoot,
+      managedRoots,
     });
     if (lexical.ok) {
       return lexical;
@@ -412,7 +416,7 @@ const escapeCloneSshKeyPath = (sshKeyPath) => {
   return `'${normalized.replace(/'/g, "'\\''")}'`;
 };
 
-const resolveReadPathFromContext = async ({ req, targetPath, scope, resolveProjectDirectory, path, os, fsPromises, normalizeDirectoryPath, openchamberUserConfigRoot }) => {
+const resolveReadPathFromContext = async ({ req, targetPath, scope, resolveProjectDirectory, path, os, fsPromises, normalizeDirectoryPath, managedRoots }) => {
   if (req.query?.allowOutsideWorkspace === 'true') {
     const normalized = normalizeDirectoryPath(targetPath);
     if (!normalized || typeof normalized !== 'string') {
@@ -434,7 +438,7 @@ const resolveReadPathFromContext = async ({ req, targetPath, scope, resolveProje
     path,
     os,
     normalizeDirectoryPath,
-    openchamberUserConfigRoot,
+    managedRoots,
   });
 };
 
@@ -520,7 +524,14 @@ export const registerFsRoutes = (app, dependencies) => {
     buildAugmentedPath,
     resolveGitBinaryForSpawn,
     openchamberUserConfigRoot,
+    managedChatsRoot,
   } = dependencies;
+  // Chat worktrees may live outside every project workspace; both managed
+  // roots stay valid filesystem targets.
+  const chatsRoot = typeof managedChatsRoot === 'string' && managedChatsRoot.trim()
+    ? path.resolve(managedChatsRoot.trim())
+    : path.join(openchamberUserConfigRoot, 'chats');
+  const managedRoots = [path.resolve(openchamberUserConfigRoot), chatsRoot];
   const realpathCache = createRealpathCache({
     realpath: fsPromises.realpath.bind(fsPromises),
   });
@@ -699,7 +710,7 @@ export const registerFsRoutes = (app, dependencies) => {
       if (!home || typeof home !== 'string' || home.length === 0) {
         return res.status(500).json({ error: 'Failed to resolve home directory' });
       }
-      return res.json({ home });
+      return res.json({ home, chatsRoot });
     } catch (error) {
       console.error('Failed to resolve home directory:', error);
       return res.status(500).json({ error: (error && error.message) || 'Failed to resolve home directory' });
@@ -725,7 +736,7 @@ export const registerFsRoutes = (app, dependencies) => {
           path,
           os,
           normalizeDirectoryPath,
-          openchamberUserConfigRoot,
+          managedRoots,
         });
         if (!resolved.ok) {
           return res.status(400).json({ error: resolved.error });
@@ -853,6 +864,37 @@ export const registerFsRoutes = (app, dependencies) => {
     }
   });
 
+  app.get('/api/fs/directory-stat', async (req, res) => {
+    res.setHeader('Cache-Control', 'no-store');
+    const paths = new URL(req.url, 'http://openchamber.local').searchParams.getAll('path');
+    const directoryPath = paths.length === 1 ? paths[0].trim() : '';
+    if (!directoryPath) {
+      return res.status(400).json({ error: 'Path is required' });
+    }
+
+    try {
+      // Directory discovery uses the same path policy as /api/fs/list, including
+      // paths outside the current workspace. stat follows symlinks without readdir.
+      const resolvedPath = path.resolve(normalizeDirectoryPath(directoryPath));
+      const stats = await fsPromises.stat(resolvedPath);
+      if (!stats.isDirectory()) {
+        return res.status(400).json({ error: 'Specified path is not a directory', reason: 'not-directory' });
+      }
+      return res.json({ isDirectory: true });
+    } catch (error) {
+      if (error.code === 'ENOENT' || error.code === 'ENOTDIR') {
+        return res.status(error.code === 'ENOENT' ? 404 : 400).json({
+          error: error.code === 'ENOENT' ? 'Directory not found' : 'Specified path is not a directory',
+          reason: error.code === 'ENOENT' ? 'not-found' : 'not-directory',
+        });
+      }
+      if (isOsPermissionError(error)) {
+        return sendOsPermissionDenied(res, 'Access to directory denied');
+      }
+      return res.status(500).json({ error: 'Failed to stat directory' });
+    }
+  });
+
   app.get('/api/fs/stat', async (req, res) => {
     const filePath = typeof req.query.path === 'string' ? req.query.path.trim() : '';
     const optional = req.query.optional === 'true';
@@ -870,7 +912,7 @@ export const registerFsRoutes = (app, dependencies) => {
         os,
         fsPromises,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         if (req.query?.allowOutsideWorkspace === 'true') {
@@ -920,7 +962,7 @@ export const registerFsRoutes = (app, dependencies) => {
         os,
         fsPromises,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         if (req.query?.allowOutsideWorkspace === 'true') {
@@ -984,7 +1026,7 @@ export const registerFsRoutes = (app, dependencies) => {
         os,
         fsPromises,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         if (req.query?.allowOutsideWorkspace === 'true') {
@@ -1065,7 +1107,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         return res.status(400).json({ error: resolved.error });
@@ -1117,7 +1159,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         return res.status(400).json({ error: resolved.error });
@@ -1187,7 +1229,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         return res.status(400).json({ error: resolved.error });
@@ -1294,7 +1336,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         return res.status(400).json({ error: resolved.error });
@@ -1332,7 +1374,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolvedOld.ok) {
         return res.status(400).json({ error: resolvedOld.error });
@@ -1345,7 +1387,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolvedNew.ok) {
         return res.status(400).json({ error: resolvedNew.error });
@@ -1451,7 +1493,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolvedForWorkspace.ok) {
         console.warn(`Rejected /api/fs/exec outside workspace: ${resolvedForWorkspace.error}`);
@@ -1689,7 +1731,7 @@ export const registerFsRoutes = (app, dependencies) => {
         path,
         os,
         normalizeDirectoryPath,
-        openchamberUserConfigRoot,
+        managedRoots,
       });
       if (!resolved.ok) {
         return res.status(400).json({ error: resolved.error });

package/server/lib/fs/routes.test.js

@@ -1,5 +1,9 @@
 import { EventEmitter } from 'events';
 import path from 'path';
+import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import { execFileSync } from 'node:child_process';
+import { pathToFileURL } from 'node:url';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
 
 import { mintOutsideFileGrant, registerFsRoutes } from './routes.js';
@@ -1385,7 +1389,11 @@ describe('fs stat directory scope (issue 3019)', () => {
       path: path.posix,
       fsPromises: {
         realpath: async (targetPath) => targetPath,
-        stat: async () => ({ isFile: () => true, size: 12 }),
+        stat: async (targetPath) => (
+          targetPath === '/repo-b'
+            ? { isDirectory: () => true, mtimeMs: 123 }
+            : { isFile: () => true, size: 12, mtimeMs: 456 }
+        ),
       },
       spawn: vi.fn(),
       crypto: { randomUUID: () => 'job-0' },
@@ -1428,4 +1436,182 @@ describe('fs stat directory scope (issue 3019)', () => {
     expect(res.statusCode).toBe(200);
     expect(res.body.isFile).toBe(true);
   });
+
+});
+
+describe('fs stat directory error handling', () => {
+  it('loads in Node without workspace node_modules, as packaged desktop does', async () => {
+    const directory = await mkdtemp(path.join(tmpdir(), 'openchamber-fs-import-'));
+    try {
+      await mkdir(path.join(directory, 'fs'));
+      await copyFile(new URL('./routes.js', import.meta.url), path.join(directory, 'fs/routes.mjs'));
+      await copyFile(new URL('../path-realpath-cache.js', import.meta.url), path.join(directory, 'path-realpath-cache.js'));
+      expect(() => execFileSync('node', [
+        '--input-type=module',
+        '--eval',
+        'await import(process.argv[1])',
+        pathToFileURL(path.join(directory, 'fs/routes.mjs')).href,
+      ], { cwd: directory, stdio: 'pipe' })).not.toThrow();
+    } finally {
+      await rm(directory, { recursive: true, force: true });
+    }
+  });
+
+  it('returns directory-missing reasons and permission errors for directory stat', async () => {
+    const { app, getRoute } = createRouteRegistry();
+    const enoent = Object.assign(new Error('missing'), { code: 'ENOENT' });
+    const enotdir = Object.assign(new Error('not a directory'), { code: 'ENOTDIR' });
+    const eacces = Object.assign(new Error('denied'), { code: 'EACCES' });
+    const stat = vi.fn(async (targetPath) => {
+      if (targetPath === '/repo-b') throw enoent;
+      if (targetPath === '/repo-b/file.txt/child') throw enotdir;
+      if (targetPath === '/repo-b/protected') throw eacces;
+      if (targetPath === '/repo-b/file.txt') return { isDirectory: () => false };
+      if (targetPath === '/repo-b/failure') throw new Error('unavailable');
+      return { isDirectory: () => true, mtimeMs: 1 };
+    });
+    const readdir = vi.fn(async () => []);
+    const callStat = async (handler, { headers = {}, query }) => {
+      const res = createMockResponse();
+      const req = {
+        url: `/api/fs/directory-stat?${new URLSearchParams(query)}`,
+        query,
+        get: (name) => headers[name.toLowerCase()] ?? undefined,
+      };
+      await handler(req, res);
+      return res;
+    };
+    registerFsRoutes(app, {
+      os: { homedir: () => '/home/user' },
+      path: path.posix,
+      fsPromises: {
+        realpath: async (targetPath) => targetPath,
+        stat,
+        readdir,
+      },
+      spawn: vi.fn(),
+      crypto: { randomUUID: () => 'job-0' },
+      normalizeDirectoryPath: (p) => p,
+      resolveProjectDirectory: async () => ({ directory: '/repo' }),
+      buildAugmentedPath: () => '/usr/bin',
+      resolveGitBinaryForSpawn: () => 'git',
+      openchamberUserConfigRoot: '/home/user/.config',
+    });
+    const handler = getRoute('GET', '/api/fs/directory-stat');
+
+    const available = await callStat(handler, { query: { path: '/other-project' } });
+    expect(available.statusCode).toBe(200);
+    expect(available.body).toEqual({ isDirectory: true });
+    expect(available.getHeader('Cache-Control')).toBe('no-store');
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    const invalid = await callStat(handler, { query: { path: ' ' } });
+    expect(invalid.statusCode).toBe(400);
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    for (const query of ['path=/repo&path=/other', 'path[]=/repo', '']) {
+      const malformed = createMockResponse();
+      await handler({ url: `/api/fs/directory-stat?${query}` }, malformed);
+      expect(malformed.statusCode).toBe(400);
+    }
+    expect(stat).toHaveBeenCalledTimes(1);
+
+    const missing = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b', directory: 'true' } });
+    expect(missing.statusCode).toBe(404);
+    expect(missing.body).toEqual({ error: 'Directory not found', reason: 'not-found' });
+
+    const notDir = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b/file.txt/child', directory: 'true' } });
+    expect(notDir.statusCode).toBe(400);
+    expect(notDir.body).toEqual({ error: 'Specified path is not a directory', reason: 'not-directory' });
+
+    const denied = await callStat(handler, { headers: { 'x-opencode-directory': '/repo-b' }, query: { path: '/repo-b/protected', directory: 'true' } });
+    expect(denied.statusCode).toBe(403);
+    expect(denied.body).toEqual({ error: 'Access to directory denied', reason: 'os-permission' });
+
+    const file = await callStat(handler, { query: { path: '/repo-b/file.txt' } });
+    expect(file.statusCode).toBe(400);
+    expect(file.body.reason).toBe('not-directory');
+
+    const failure = await callStat(handler, { query: { path: '/repo-b/failure' } });
+    expect(failure.statusCode).toBe(500);
+    expect(failure.body).toEqual({ error: 'Failed to stat directory' });
+    expect(readdir).not.toHaveBeenCalled();
+  });
+});
+
+describe('fs managed chats root', () => {
+  const registerWithChatsRoot = ({ managedChatsRoot, fsPromises = {} } = {}) => {
+    const { app, getRoute } = createRouteRegistry();
+    registerFsRoutes(app, {
+      os: { homedir: () => '/home/user' },
+      path: path.posix,
+      fsPromises: {
+        realpath: async (targetPath) => targetPath,
+        mkdir: async () => undefined,
+        ...fsPromises,
+      },
+      spawn: vi.fn(),
+      crypto: { randomUUID: () => 'job-0' },
+      normalizeDirectoryPath: (p) => p,
+      resolveProjectDirectory: async () => ({ directory: '/repo' }),
+      buildAugmentedPath: () => '/usr/bin',
+      resolveGitBinaryForSpawn: () => 'git',
+      openchamberUserConfigRoot: '/home/user/.config/openchamber',
+      managedChatsRoot,
+    });
+    return {
+      home: getRoute('GET', '/api/fs/home'),
+      mkdir: getRoute('POST', '/api/fs/mkdir'),
+    };
+  };
+
+  it('exposes the default chats root next to the home directory', async () => {
+    const { home } = registerWithChatsRoot();
+
+    const res = createMockResponse();
+    await home(undefined, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.home).toBe('/home/user');
+    expect(res.body.chatsRoot).toBe('/home/user/.config/openchamber/chats');
+  });
+
+  it('exposes a relocated chats root when OPENCHAMBER_CHATS_DIR is configured upstream', async () => {
+    const { home } = registerWithChatsRoot({ managedChatsRoot: '/srv/openchamber-chats' });
+
+    const res = createMockResponse();
+    await home(undefined, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.chatsRoot).toBe('/srv/openchamber-chats');
+  });
+
+  it('allows mkdir inside the relocated chats root outside the active workspace', async () => {
+    const mkdirCalls = [];
+    const { mkdir } = registerWithChatsRoot({
+      managedChatsRoot: '/srv/openchamber-chats',
+      fsPromises: {
+        mkdir: async (targetPath) => {
+          mkdirCalls.push(targetPath);
+        },
+      },
+    });
+
+    const res = createMockResponse();
+    await mkdir({ body: { path: '/srv/openchamber-chats/2026-08-25/session-a' } }, res);
+
+    expect(res.statusCode).toBe(200);
+    expect(res.body.success).toBe(true);
+    expect(mkdirCalls).toEqual(['/srv/openchamber-chats/2026-08-25/session-a']);
+  });
+
+  it('still rejects mkdir outside the workspace and all managed roots', async () => {
+    const { mkdir } = registerWithChatsRoot({ managedChatsRoot: '/srv/openchamber-chats' });
+
+    const res = createMockResponse();
+    await mkdir({ body: { path: '/etc/passwd-holder' } }, res);
+
+    expect(res.statusCode).toBe(400);
+    expect(res.body).toEqual({ error: 'Path is outside of active workspace' });
+  });
 });