@vantran-se/openchamber-web 2.1.1 → 2.2.0

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

@@ -25,8 +25,17 @@ const MAX_PENDING_BYTES = 256 * 1024;
 /** A handshake that has not completed by now is not going to. */
 const HANDSHAKE_TIMEOUT_MS = 15_000;
 
-const toWebSocketUrl = (baseUrl, port) => {
-  const parsed = new URL('/api/dev-tunnel', baseUrl);
+const SPACE_ID = /^[0-9a-f]{12}$/;
+
+/**
+ * The host's own tunnel, or the one of an isolated space on that host: the
+ * host forwards `/api/spaces/<id>/dev-tunnel` to the server inside the space,
+ * which dials the port on its own loopback, the space's.
+ */
+const tunnelPath = (spaceId) => (spaceId ? `/api/spaces/${spaceId}/dev-tunnel` : '/api/dev-tunnel');
+
+const toWebSocketUrl = (baseUrl, port, spaceId) => {
+  const parsed = new URL(tunnelPath(spaceId), baseUrl);
   // WHATWG URL silently ignores a protocol assignment that crosses from a
   // non-special scheme (custom app protocols, relay-virtual URLs) to `ws:`.
   // Without this check the stale scheme survives into `new WebSocket(...)`,
@@ -45,8 +54,9 @@ export const createDevTunnelClient = ({
   handshakeTimeoutMs = HANDSHAKE_TIMEOUT_MS,
   maxPendingBytes = MAX_PENDING_BYTES,
 } = {}) => {
-  /** Keyed by `${baseUrl}|${remotePort}` so repeat opens reuse one listener. */
+  /** Keyed by base URL, space and remote port, so repeat opens reuse one listener. */
   const tunnels = new Map();
+  const tunnelKey = (baseUrl, remotePort, spaceId) => `${baseUrl}|${spaceId ?? ''}|${remotePort}`;
 
   const closeTunnel = (key) => {
     const tunnel = tunnels.get(key);
@@ -65,19 +75,20 @@ export const createDevTunnelClient = ({
      * Rejects if the listener cannot bind; per-connection failures close only
      * that connection, so one failed request cannot take the tunnel down.
      */
-    async open({ baseUrl, port, headers = {} }) {
+    async open({ baseUrl, port, headers = {}, spaceId = null }) {
       const remotePort = Number.parseInt(String(port), 10);
       if (!Number.isInteger(remotePort) || remotePort <= 0 || remotePort > 65535) {
         throw new Error('A valid remote port is required');
       }
       const base = String(baseUrl || '').trim();
       if (!base) throw new Error('A remote base URL is required');
+      if (spaceId !== null && !SPACE_ID.test(String(spaceId))) throw new Error('A valid space id is required');
 
-      const key = `${base}|${remotePort}`;
+      const key = tunnelKey(base, remotePort, spaceId);
       const existing = tunnels.get(key);
       if (existing) return { localPort: existing.localPort, reused: true };
 
-      const target = toWebSocketUrl(base, remotePort);
+      const target = toWebSocketUrl(base, remotePort, spaceId);
       const sockets = new Set();
 
       const server = net.createServer((socket) => {
@@ -173,12 +184,12 @@ export const createDevTunnelClient = ({
         logger.warn?.(`[dev-tunnel] listener error for port ${remotePort}: ${error?.message || error}`);
       });
 
-      tunnels.set(key, { server, sockets, localPort, remotePort, baseUrl: base });
+      tunnels.set(key, { server, sockets, localPort, remotePort, baseUrl: base, spaceId });
       return { localPort, reused: false };
     },
 
-    close({ baseUrl, port }) {
-      return closeTunnel(`${String(baseUrl || '').trim()}|${Number.parseInt(String(port), 10)}`);
+    close({ baseUrl, port, spaceId = null }) {
+      return closeTunnel(tunnelKey(String(baseUrl || '').trim(), Number.parseInt(String(port), 10), spaceId));
     },
 
     /** Closes every tunnel; used when the desktop switches runtime or quits. */
@@ -187,7 +198,7 @@ export const createDevTunnelClient = ({
     },
 
     list() {
-      return [...tunnels.values()].map(({ localPort, remotePort, baseUrl }) => ({ localPort, remotePort, baseUrl }));
+      return [...tunnels.values()].map(({ localPort, remotePort, baseUrl, spaceId }) => ({ localPort, remotePort, baseUrl, spaceId }));
     },
   };
 };

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

@@ -175,6 +175,40 @@ describe('dev tunnel end to end', () => {
     expect(second.reused).toBe(true);
   });
 
+  test('a space tunnel dials the space prefix on the host, and is a tunnel of its own', async () => {
+    // The host forwards `/api/spaces/<id>/dev-tunnel` into the space; what matters
+    // here is that the client asks for exactly that path, under its own key.
+    const paths = [];
+    const server = http.createServer((_req, res) => res.end('host'));
+    const sockets = trackSockets(server);
+    server.on('upgrade', (req, socket) => {
+      paths.push(req.url);
+      socket.write('HTTP/1.1 404 Not Found\r\n\r\n');
+      socket.destroy();
+    });
+    const hostPort = await listen(server);
+    started.push(stopServer(server, sockets));
+    const baseUrl = `http://127.0.0.1:${hostPort}`;
+
+    const client = createDevTunnelClient({ logger: { warn: () => {} } });
+    started.push(() => client.closeAll());
+    const space = await client.open({ baseUrl, port: 4321, spaceId: '84369ed6edda' });
+    const host = await client.open({ baseUrl, port: 4321 });
+    expect(space.localPort).not.toBe(host.localPort);
+    expect(client.list()).toEqual([
+      { localPort: space.localPort, remotePort: 4321, baseUrl, spaceId: '84369ed6edda' },
+      { localPort: host.localPort, remotePort: 4321, baseUrl, spaceId: null },
+    ]);
+
+    await expect(httpGet(space.localPort, '/')).rejects.toThrow();
+    await expect(httpGet(host.localPort, '/')).rejects.toThrow();
+    expect(paths).toEqual(['/api/spaces/84369ed6edda/dev-tunnel?port=4321', '/api/dev-tunnel?port=4321']);
+
+    expect(client.close({ baseUrl, port: 4321, spaceId: '84369ed6edda' })).toBe(true);
+    expect(client.list()).toEqual([{ localPort: host.localPort, remotePort: 4321, baseUrl, spaceId: null }]);
+    await expect(client.open({ baseUrl, port: 4321, spaceId: '../etc' })).rejects.toThrow(/space id/);
+  });
+
   test('refuses a port discovery does not report, so it is not a loopback proxy', async () => {
     const secret = await startDevServer((_req, res) => res.end('secret service'));
     const host = await startHost({ allowedPorts: [] });

package/server/lib/dispatch-results/runtime.js

@@ -39,7 +39,7 @@ const MESSAGE_PAGE_LIMIT = 50;
 // is cut, and the agent can read the rest with session.messages.
 const ANSWER_CHAR_LIMIT = 50_000;
 
-export const DISPATCH_RESULT_SOURCE = 'openchamber-session';
+const DISPATCH_RESULT_SOURCE = 'openchamber-session';
 
 const ID_CHARS = '0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz';
 

package/server/lib/enterprise-mode.d.ts

@@ -18,6 +18,7 @@ export interface EnterprisePolicy {
   allowLocalExtensions: boolean;
   /** OpenCode CLI path pinned by the policy file; null when nothing is pinned. */
   opencodeBinary: string | null;
+  hideBuiltinSkillCatalogs: boolean;
 }
 
 export type PublicEnterprisePolicy = Pick<EnterprisePolicy, 'enterpriseMode' | 'source' | 'organization' | 'policyError' | 'opencodeBinary'> & { networkAccessBlocked: boolean };

package/server/lib/enterprise-mode.js

@@ -69,6 +69,11 @@ import { z } from 'zod';
  * and OpenChamber neither installs nor upgrades it (`opencode/env-runtime.js`,
  * `packages/vscode/src/opencode.ts`).
  *
+ * The file can also hide the skills catalogs OpenChamber ships with
+ * (`hideBuiltinSkillCatalogs`), with or without enterprise mode, so the only
+ * catalogs on offer are the ones the organization added
+ * (`skills-catalog/curated-sources.js`, `packages/vscode/src/skillsCatalog.ts`).
+ *
  * The VS Code extension host, which runs no OpenChamber server, reads the
  * same policy through this module for the parts it has (provider connection,
  * update checks).
@@ -108,6 +113,7 @@ const policyFileSchema = z.object({
   allowLocalExtensions: z.boolean().optional(),
   jev: z.object({ url: optionalText, model: optionalText, apiKey: optionalText }).optional(),
   opencodeBinary: optionalText,
+  hideBuiltinSkillCatalogs: z.boolean().optional(),
 }).refine((policy) => !policy.jev || policy.jev.url || (!policy.jev.model && !policy.jev.apiKey), {
   message: '"jev" needs a "url"',
   path: ['jev'],
@@ -128,7 +134,7 @@ const parsePolicyFile = (text) => {
     const field = issue.path.length > 0 ? `"${issue.path.join('.')}": ` : '';
     throw new Error(`${field}${issue.message}`);
   }
-  const { enterpriseMode, organization, relayUrl, allowNetworkAccess, allowedExtensions, allowLocalExtensions, jev, opencodeBinary } = parsed.data;
+  const { enterpriseMode, organization, relayUrl, allowNetworkAccess, allowedExtensions, allowLocalExtensions, jev, opencodeBinary, hideBuiltinSkillCatalogs } = parsed.data;
   return {
     enterpriseMode: enterpriseMode === true,
     organization: organization ?? null,
@@ -138,6 +144,7 @@ const parsePolicyFile = (text) => {
     allowLocalExtensions,
     jev: jev?.url ? { url: jev.url, model: jev.model ?? null, apiKey: jev.apiKey ?? null } : undefined,
     opencodeBinary: opencodeBinary ?? null,
+    hideBuiltinSkillCatalogs: hideBuiltinSkillCatalogs === true,
   };
 };
 
@@ -208,6 +215,8 @@ export const readEnterprisePolicy = (options = {}) => {
       allowedExtensions: [],
       allowLocalExtensions: false,
       opencodeBinary: null,
+      // Fails closed like the rest: a broken policy offers no catalog it might have hidden.
+      hideBuiltinSkillCatalogs: true,
     };
   }
 
@@ -242,6 +251,8 @@ export const readEnterprisePolicy = (options = {}) => {
     // File only, in or out of enterprise mode: OPENCODE_BINARY already lets a
     // user pick a binary, and a pin they could override would not be one.
     opencodeBinary: fromFile?.opencodeBinary ?? null,
+    // File only, in or out of enterprise mode, for the same reason.
+    hideBuiltinSkillCatalogs: fromFile?.hideBuiltinSkillCatalogs === true,
   };
 };
 
@@ -306,7 +317,7 @@ const isMcpSignIn = (integrationId, rest) => (
 /**
  * Whether a request to OpenCode would add a way to reach a model provider:
  * every POST under `/api/integration/:id/connect` (key, oauth start and
- * complete, command), storing a key with `POST /api/credential`, and adding a
+ * complete, command, external since 2.0.25), storing a key with `POST /api/credential`, and adding a
  * well-known integration. Signing in to a
  * remote MCP server goes through the same routes and stays allowed. Reads,
  * cancelling an attempt and removing or switching an existing account stay

package/server/lib/enterprise-mode.test.js

@@ -41,6 +41,7 @@ describe('enterprise policy', () => {
       allowedExtensions: [],
       allowLocalExtensions: false,
       opencodeBinary: null,
+      hideBuiltinSkillCatalogs: false,
     });
   });
 
@@ -70,6 +71,25 @@ describe('enterprise policy', () => {
       allowedExtensions: [],
       allowLocalExtensions: false,
       opencodeBinary: null,
+      hideBuiltinSkillCatalogs: false,
+    });
+  });
+
+  describe('hidden built-in skill catalogs', () => {
+    it('comes from the file with or without enterprise mode', () => {
+      expect(readEnterprisePolicy(machine({ [LINUX_POLICY]: '{"hideBuiltinSkillCatalogs": true}' })))
+        .toMatchObject({ enterpriseMode: false, hideBuiltinSkillCatalogs: true });
+      expect(readEnterprisePolicy(machine({ [LINUX_POLICY]: '{"enterpriseMode": true, "hideBuiltinSkillCatalogs": true}' })).hideBuiltinSkillCatalogs)
+        .toBe(true);
+    });
+
+    it('is never taken from the environment', () => {
+      expect(readEnterprisePolicy(machine({}, { env: { OPENCHAMBER_ENTERPRISE_MODE: '1', OPENCHAMBER_HIDE_BUILTIN_SKILL_CATALOGS: '1' } })).hideBuiltinSkillCatalogs)
+        .toBe(false);
+    });
+
+    it('hides them when the file is broken', () => {
+      expect(readEnterprisePolicy(machine({ [LINUX_POLICY]: '{"hideBuiltinSkillCatalogs": "yes"}' })).hideBuiltinSkillCatalogs).toBe(true);
     });
   });
 
@@ -257,6 +277,7 @@ describe('enterprise policy', () => {
       '/api/integration/anthropic/connect/oauth',
       '/api/integration/anthropic/connect/oauth/att_1/complete',
       '/api/integration/github-copilot/connect/command',
+      '/api/integration/amazon-bedrock/connect/external',
       '/api/experimental/integration/wellknown',
       '/api/integration/openai/connect',
       '/api/integration/openai/connect/key/',

package/server/lib/event-stream/DOCUMENTATION.md

@@ -29,7 +29,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - `serializeMessageStreamWsEvent(payload, options)` and `sendSerializedMessageStreamWsFrame(socket, frame)` separate encoding from per-socket delivery. Delivery retains ready-state and backpressure checks.
 
 ### Runtime helpers
-- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay. The composition root owns the singleton and stops it during application shutdown; watchers and WebSocket bridges that receive it are borrowers and must not stop it.
+- `createGlobalMessageStreamHub(...)`: creates a shared `/global/event` upstream SSE hub with event/status subscribers and bounded event-id replay.
 - `createGlobalUiEventBroadcaster({ sseClients, wsClients, writeSseEvent })`: returns a broadcaster that fans out the same synthetic UI event to SSE and WS clients.
 - `createMessageStreamWsRuntime(...)`: mounts the message-stream WS server, upgrade handler, and SSE-to-WS bridge onto the web HTTP server.
 
@@ -59,7 +59,7 @@ This module contains the OpenChamber message-stream WebSocket protocol and runti
 - The hub numbers every event that arrives without an SSE id (`oc-<process>-<sequence>`). OpenCode 1.18 sends no ids at all, and an event without an id used to skip the replay buffer, so reconnecting clients had no cursor and lost whatever fell into the gap. The process prefix makes a cursor from before a server restart miss, which reports `replayReset`, instead of matching an unrelated sequence number.
 - Directory WS clients still attach one upstream `/event?directory=...` SSE reader per connection because directory streams are scoped.
 - If an upstream SSE stream stalls after the browser WS is already ready, the reader aborts that upstream fetch and reconnects upstream with `Last-Event-ID`, keeping the browser WS alive when recovery is fast.
-- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and runs its established scoped authoritative repair without requiring the browser WS to close. Shared-service recovery uses this edge rather than manufacturing a server-side interruption. Rebinding retires the old reader generation before starting its replacement, so delayed events, errors, and disconnect completion from the old reader cannot overwrite the replacement's connection state.
+- When the shared global upstream reconnects after it was previously ready, the global WS bridge sends a fresh `ready` frame to already-ready browser clients. The browser treats this as a reconnect edge and can run scoped state repair without requiring the browser WS to close.
 - Health checks are reserved for initial upstream connect failures and explicit upstream-unavailable responses, not for ordinary stall recovery on an already-established stream.
 - Global synthetic events such as `openchamber:session-status`, `openchamber:session-activity`, `openchamber:notification`, and `openchamber:heartbeat` are preserved on the WS path, but heartbeat frames are emitted only while an upstream SSE stream is actively attached.
 - Global UI broadcasts are fan-out capable across both SSE and WS clients.

package/server/lib/event-stream/index.js

@@ -17,7 +17,5 @@ export {
 } from './upstream-reader.js';
 
 export {
-  forwardTranslatedWireEvent,
-  translateWireEvent,
-  wireEventDirectory,
+  translateWireEvent
 } from './translate-v2.js';

package/server/lib/event-stream/translate-v2.js

@@ -21,8 +21,7 @@
  *   assistant `message.updated`; only the last one carries `finish: "stop"`,
  *   which is the same signal v1 gave once per turn.
  */
-
-const isRecord = (value) => value !== null && typeof value === 'object' && !Array.isArray(value);
+import { isRecord } from '../shared/guards.js';
 
 const trimmed = (value) => (typeof value === 'string' ? value.trim() : '');
 
@@ -131,13 +130,6 @@ export function translateWireEvent(payload) {
         info: compact({ id: sessionID, directory: directory || undefined, cost: data.cost, tokens: data.tokens, time: { updated: created } }),
       })];
 
-    case 'session.metadata.updated':
-      if (!sessionID) return [];
-      return [event('session.updated', {
-        sessionID,
-        info: compact({ id: sessionID, directory: directory || undefined, metadata: data.metadata, time: { updated: created } }),
-      })];
-
     case 'session.deleted':
       if (!sessionID) return [];
       return [event('session.deleted', { sessionID, info: { id: sessionID } })];

package/server/lib/event-stream/translate-v2.test.js

@@ -50,17 +50,6 @@ describe('translateWireEvent', () => {
     });
   });
 
-  test('metadata updates carry the adoption marker as session.updated', () => {
-    const [event] = translateWireEvent(wire('session.metadata.updated', {
-      sessionID: 's1',
-      metadata: { openchamber: { adopted: true } },
-    }));
-    expect(event).toMatchObject({
-      type: 'session.updated',
-      properties: { info: { id: 's1', metadata: { openchamber: { adopted: true } } } },
-    });
-  });
-
   test('a finished compaction reads as session.compacted', () => {
     expect(translateWireEvent(wire('session.compaction.ended', { sessionID: 's1', reason: 'auto', text: 'summary', recent: '' })))
       .toEqual([expect.objectContaining({ type: 'session.compacted', properties: { sessionID: 's1', directory: '/repo' } })]);

package/server/lib/fs/DOCUMENTATION.md

@@ -21,7 +21,10 @@ Own filesystem API behavior for the web server runtime, including workspace-boun
     - `POST /api/fs/write`
     - `POST /api/fs/upload`
     - `POST /api/fs/delete`
-    - `POST /api/fs/rename`
+    - `POST /api/fs/rename` — never replaces an existing destination: it
+      returns `409` with `reason: 'already-exists'`, except for a case-only
+      rename where the destination is the source itself. The check runs before
+      the rename, so a file created in between can still be replaced.
      - `POST /api/fs/reveal`
      - `POST /api/fs/clone`
      - `POST /api/fs/exec`
@@ -71,7 +74,7 @@ The Git service validates a selected commit identity before planning or spawning
 - Filesystem `EPERM`/`EACCES` failures use the stable `reason: "os-permission"` response marker. Workspace-boundary policy denials 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.
 - HTML previews are untrusted content. `POST /api/fs/preview` (normal API auth, body `{ path }`, workspace resolved like any read) mints a grant `{ grant, expiresAt }` for one page. `GET /api/fs/preview/<grant>/<absolute path>` serves the page and its files: the grant sits in the path, so the page's relative URLs carry it and no session credential appears in a URL the page can read. `core-routes.js` lets these GETs past API auth; the route itself rejects an unknown or expired grant with 403. A grant fixes the workspace base at mint time (the page's project, or the managed root it lives in) and lapses after ten idle minutes; every served file extends it. Every answer carries `Content-Security-Policy: sandbox allow-scripts allow-forms allow-popups allow-modals allow-downloads`, so the page is an opaque-origin document even when opened in its own tab, and the Files view frame has no `allow-same-origin`. Embedding (images, stylesheets, classic scripts) works anywhere the grant's base allows. Reading bytes from script (`fetch`, fonts, module scripts) is a CORS request from origin `null`, answered with `Access-Control-Allow-Origin: null` only inside the grant's read root: the page's project, or for a page inside a managed root, the page's own folder. Other files under `~/.config/openchamber` stay unreadable to the page.
-- `GET /api/fs/raw` answers one `Range: bytes=…` span with `206`, `Content-Range` and a stream from disk (`byte-range.js` reduces the header to a span). Media elements send a span on every seek, and Chromium and WebKit refuse to seek without a `206`, so the viewer's audio and video players depend on this; a whole-file request still reads and sends the buffer. The MIME table (`FILE_MIME_MAP`) is shared with `/api/fs/preview` and covers images, PDF, audio, video, fonts, CSV/TSV and Mermaid.
+- `GET /api/fs/raw` answers one `Range: bytes=…` span with `206`, `Content-Range` and a stream from disk (`byte-range.js` reduces the header to a span). Media elements send a span on every seek, and Chromium and WebKit refuse to seek without a `206`, so the viewer's audio and video players depend on this. A whole-file request streams from disk the same way, so a large PDF or recording never sits in server memory. The MIME table (`FILE_MIME_MAP`) is shared with `/api/fs/preview` and covers images, PDF, audio, video, fonts, CSV/TSV and Mermaid.
 - File read, raw and stat routes accept outside paths with `allowOutsideWorkspace=true` under the normal server authentication and OS permissions. They do not require a separate file grant. Legacy grant parameters are ignored. Workspace-scoped reads resolve symlinks after checking the requested path. 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

@@ -1,6 +1,7 @@
 import { createRealpathCache } from '../path-realpath-cache.js';
 import { redactGitText } from '../git/redaction.js';
 import { resolveByteRange } from './byte-range.js';
+import { createWorkspaceFileNameIndex } from './workspace-file-names.js';
 import nodeFsPromises from 'node:fs/promises';
 import nodePath from 'node:path';
 
@@ -972,6 +973,22 @@ export const registerFsRoutes = (app, dependencies) => {
     }
   });
 
+  // A bare file name an agent wrote without its folder (`Foo.tsx:12`): the
+  // workspace files with that name. One cached git listing per workspace
+  // answers every name (see workspace-file-names.js).
+  const workspaceFileNames = createWorkspaceFileNameIndex({ spawn, resolveGitBinary: resolveGitBinaryForSpawn });
+  app.get('/api/fs/find-by-name', async (req, res) => {
+    const name = typeof req.query.name === 'string' ? req.query.name.trim() : '';
+    if (!name || name.length > 255 || name === '.' || name === '..' || /[/\\*?[\]:]/.test(name)) {
+      return res.status(400).json({ error: 'A plain file name is required' });
+    }
+    const project = await resolveProjectDirectory(req);
+    if (!project.directory) {
+      return res.status(400).json({ error: project.error || 'Active workspace is required' });
+    }
+    return res.json({ paths: await workspaceFileNames.find(project.directory, name) });
+  });
+
   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';
@@ -1138,32 +1155,49 @@ export const registerFsRoutes = (app, dependencies) => {
       res.setHeader('Referrer-Policy', 'no-referrer');
       res.setHeader('Accept-Ranges', 'bytes');
 
-      // A byte span is streamed from disk rather than read whole: the audio
-      // and video players ask for one on every seek, and a recording can be
-      // hundreds of megabytes.
+      // The file is streamed from disk, never read whole: the audio and video
+      // players ask for a span on every seek, and a recording or a PDF can be
+      // hundreds of megabytes the server would otherwise hold in memory.
       const range = resolveByteRange(req.headers?.range, stats.size);
       if (range.kind === 'unsatisfiable') {
         res.setHeader('Content-Range', `bytes */${stats.size}`);
         return res.status(416).end();
       }
+      res.type(mimeType);
+      // An empty file has no byte to read, and a read stream over `0..-1` would fail.
+      if (stats.size === 0) {
+        res.setHeader('Content-Length', '0');
+        return res.end();
+      }
+      // Opened before any span header is set, so a failed open answers a clean error.
+      const handle = await fsPromises.open(canonicalPath, 'r');
+      const span = range.kind === 'range' ? range : { start: 0, end: stats.size - 1 };
       if (range.kind === 'range') {
-        const handle = await fsPromises.open(canonicalPath, 'r');
         res.status(206);
-        res.setHeader('Content-Range', `bytes ${range.start}-${range.end}/${stats.size}`);
-        res.setHeader('Content-Length', String(range.end - range.start + 1));
-        res.type(mimeType);
-        // The handle closes with the stream, on success and on failure alike.
-        const stream = handle.createReadStream({ start: range.start, end: range.end });
+        res.setHeader('Content-Range', `bytes ${span.start}-${span.end}/${stats.size}`);
+      }
+      res.setHeader('Content-Length', String(span.end - span.start + 1));
+      // pipe() leaves the source paused when a media player disconnects.
+      // Destroy it too so autoClose releases the FileHandle before GC.
+      try {
+        const stream = handle.createReadStream({ start: span.start, end: span.end });
+        const onResponseClose = () => stream.destroy();
+        res.once('close', onResponseClose);
+        stream.once('close', () => res.removeListener('close', onResponseClose));
         stream.on('error', (error) => {
-          console.error('Failed to stream raw file range:', error);
+          console.error('Failed to stream raw file:', error);
           res.destroy(error);
         });
-        stream.pipe(res);
-        return undefined;
+        if (res.destroyed) {
+          stream.destroy();
+        } else {
+          stream.pipe(res);
+        }
+      } catch (error) {
+        await handle.close();
+        throw error;
       }
-
-      const content = await fsPromises.readFile(canonicalPath);
-      return res.type(mimeType).send(content);
+      return undefined;
     } catch (error) {
       const err = error;
       if (err && typeof err === 'object' && err.code === 'ENOENT') {
@@ -1534,6 +1568,19 @@ export const registerFsRoutes = (app, dependencies) => {
         return res.status(400).json({ error: 'Source and destination must share the same workspace root' });
       }
 
+      // fs.rename silently replaces an existing file. A destination that is the
+      // source itself is a case-only rename on a case-insensitive filesystem.
+      const [sourceStats, destinationStats] = await Promise.all([
+        fsPromises.lstat(resolvedOld.resolved),
+        fsPromises.lstat(resolvedNew.resolved).catch((error) => {
+          if (error?.code === 'ENOENT') return null;
+          throw error;
+        }),
+      ]);
+      if (destinationStats && (destinationStats.dev !== sourceStats.dev || destinationStats.ino !== sourceStats.ino)) {
+        return res.status(409).json({ error: 'Destination path already exists', reason: 'already-exists' });
+      }
+
       await fsPromises.rename(resolvedOld.resolved, resolvedNew.resolved);
       return res.json({ success: true, path: resolvedNew.resolved });
     } catch (error) {