deckide 3.5.41 → 3.5.43

package/README.md

@@ -64,6 +64,11 @@ deckide config                 全設定表示
 deckide config set <key> <val> 設定値変更
 deckide config get <key>       設定値取得
 deckide config reset           設定リセット
+
+deckide codeserver install     code-server（VS Code エディタ）を取得/インストール
+deckide codeserver status      code-server のインストール状態
+deckide codeserver path        code-server バイナリのパスを表示
+deckide codeserver uninstall   取得済み code-server を削除
 ```
 
 ### 起動オプション
@@ -167,6 +172,29 @@ ide/
 | `AGENT_BROWSER_FFMPEG` | ffmpeg 実行ファイル | PATH から自動検出 |
 | `AGENT_BROWSER_PACTL` | pactl 実行ファイル | PATH から自動検出 |
 | `AGENT_BROWSER_AUDIO_SOURCE` | 音声キャプチャ元 | 既定 sink の monitor source |
+| `AGENT_BROWSER_WEBRTC` | エージェントブラウザ映像を WebRTC 配信（`true`/`auto`/`false`、現状はオプトイン） | false |
+| `AGENT_BROWSER_WEBRTC_BITRATE` | WebRTC ビットレート（ffmpeg `-b:v` 形式） | 3M |
+| `AGENT_BROWSER_WEBRTC_FPS` | WebRTC フレームレート | 30 |
+| `AGENT_BROWSER_WEBRTC_ICE_SERVERS` | ICE サーバ（JSON配列）。空ならホスト候補のみ（同一ホスト/LAN） | — |
+| `AGENT_BROWSER_DISPLAY` | キャプチャする X ディスプレイ（未設定なら Chrome から自動検出） | — |
+| `AGENT_BROWSER_CDP_PORT` | 共有ブラウザの CDP ポート | 9222 |
+| `AGENT_BROWSER_REAP_MCP` | リークした chrome-devtools-mcp スタックを自動回収 | true |
+| `AGENT_BROWSER_MAX_MCP_PER_AGENT` | 1エージェントが保持できる MCP スタック上限（超過分の古いものを回収） | 3 |
+| `AGENT_BROWSER_MCP_IDLE_MS` | 回収対象とみなすアイドル閾値 (ms) | 600000 |
+| `DECKIDE_CODE_SERVER_BIN` | code-server バイナリ（未設定なら ~/.deckide → PATH → 初回自動DL） | — |
+| `DECKIDE_CODE_SERVER_VERSION` | 取得する code-server バージョン | 4.125.0 |
+
+## Deck Drive シェルと code-server
+
+既定の UI は **Deck Drive**（Google Drive 風のファイル/ワークスペース・ブラウザ）です。ファイルを開くと **code-server（ブラウザ版 VS Code）** が同一オリジンのリバースプロキシ（`/codeserver/:wsId/*`）越しに起動します。ターミナルデッキ・エージェントブラウザもタブとして同じシェルに統合されています。
+
+- **code-server の取得**: 初回利用時に固定版（`DECKIDE_CODE_SERVER_VERSION`、既定 4.125.0）を `~/.deckide/code-server` へ自動ダウンロードします。手動なら `deckide codeserver install`。
+- **拡張機能**: Microsoft マーケットプレイスは利用不可（Open VSX のみ）。Pylance/Copilot/Remote-* は使えません（Pyright 等で代替）。
+- **リソース**: code-server はワークスペース毎に1プロセス（目安 +1GB RAM / +2 コア）。アイドル20分で自動停止します。
+- **認証**: code-server は `--auth none` で起動し、Deck IDE の Basic 認証配下の同一オリジンプロキシで保護します。
+- **旧 UI**: 従来の Monaco/分割ターミナル・シェルは `?shell=legacy` で引き続き利用できます。
+
+> エージェントブラウザの WebRTC 配信（`AGENT_BROWSER_WEBRTC` / `?webrtc=1`）は実験的なオプトインです。既定は従来の JPEG ストリーミングです。音声トラックは PulseAudio がある環境でのみ動作します。
 
 ## MCP / OAuth
 

package/bin/deckide.js

@@ -1,4 +1,4 @@
-#!/usr/bin/env node
+#!/usr/bin/env node
 
 import { fileURLToPath } from 'node:url';
 import path from 'node:path';
@@ -172,6 +172,11 @@ Usage:
   deckide config get <key>       Get a config value
   deckide config reset           Reset all settings
 
+  deckide codeserver install     Download/install code-server (the VS Code editor)
+  deckide codeserver status      Show code-server install status
+  deckide codeserver path        Print the code-server binary path
+  deckide codeserver uninstall   Remove the downloaded code-server
+
 Options (for start):
   -p, --port <port>              Port (default: 8787)
   --host <host>                  Host (default: 0.0.0.0)
@@ -338,6 +343,50 @@ if (command === 'auth') {
 }
 
 // ── deckide status ──
+// ── deckide codeserver ──
+if (command === 'codeserver') {
+  const sub = args[1] || 'status';
+  process.env.DECKIDE_DATA_DIR = dataDir;
+  const modPath = path.join(__dirname, '..', 'dist', 'utils', 'code-server.js');
+  let CodeServerService;
+  try {
+    ({ CodeServerService } = await import(modPath));
+  } catch (e) {
+    console.error(`code-server module not found — is Deck IDE built? (${e.message})`);
+    process.exit(1);
+  }
+  const cs = new CodeServerService(new Map());
+  if (sub === 'install') {
+    try {
+      const bin = await cs.download((m) => console.log(`  ${m}`));
+      console.log(`\x1b[32mInstalled\x1b[0m → ${bin}`);
+      process.exit(0);
+    } catch (e) {
+      console.error(`\x1b[31mInstall failed:\x1b[0m ${e.message}`);
+      process.exit(1);
+    }
+  } else if (sub === 'status') {
+    const s = await cs.getStatus();
+    console.log('code-server');
+    console.log(`  acquired: ${s.acquired}`);
+    console.log(`  binPath:  ${s.binPath || '(none)'}`);
+    if (s.reason) console.log(`  note:     ${s.reason}`);
+    process.exit(0);
+  } else if (sub === 'path') {
+    const bin = await cs.resolveBin();
+    if (bin) { console.log(bin); process.exit(0); }
+    console.error('code-server is not installed (run: deckide codeserver install)');
+    process.exit(1);
+  } else if (sub === 'uninstall') {
+    await cs.uninstall();
+    console.log('Uninstalled code-server.');
+    process.exit(0);
+  } else {
+    console.error('usage: deckide codeserver install|status|path|uninstall');
+    process.exit(1);
+  }
+}
+
 if (command === 'status') {
   const settings = loadSettings();
   const port = settings.port || 8787;

package/dist/config.js

@@ -35,6 +35,34 @@ export const MAX_FILE_SIZE = parseIntEnv(process.env.MAX_FILE_SIZE, 10 * 1024 *
 export const TERMINAL_BUFFER_LIMIT = parseIntEnv(process.env.TERMINAL_BUFFER_LIMIT, 500_000);
 export const MAX_REQUEST_BODY_SIZE = parseIntEnv(process.env.MAX_REQUEST_BODY_SIZE, 1024 * 1024); // 1MB default
 export const TRUST_PROXY = process.env.TRUST_PROXY === 'true'; // Only trust proxy headers if explicitly enabled
+// --- Agent browser WebRTC streaming (A1: direct Xvfb capture → ffmpeg → werift) ---
+// Master switch. 'false' (default) keeps the JPEG screencast path and never even
+// imports werift. 'true'/'auto' advertise the WebRTC capability; the client still
+// falls back to JPEG on any failure.
+const webrtcFlag = (process.env.AGENT_BROWSER_WEBRTC || 'false').toLowerCase();
+export const AGENT_BROWSER_WEBRTC = webrtcFlag === 'true' || webrtcFlag === 'auto';
+// Video codec for the encoded stream. Only 'vp8' is wired today; 'vp9'/'h264'
+// are accepted for forward-compat and validated in the relay.
+export const AGENT_BROWSER_WEBRTC_CODEC = (process.env.AGENT_BROWSER_WEBRTC_CODEC || 'vp8').toLowerCase();
+// Target video bitrate passed to the encoder (ffmpeg -b:v syntax, e.g. '3M').
+export const AGENT_BROWSER_WEBRTC_BITRATE = process.env.AGENT_BROWSER_WEBRTC_BITRATE || '3M';
+export const AGENT_BROWSER_WEBRTC_FPS = parseIntEnv(process.env.AGENT_BROWSER_WEBRTC_FPS, 30);
+// Optional explicit X display to capture (e.g. ':99'). When unset the relay
+// discovers it from the running Chrome process environment.
+export const AGENT_BROWSER_DISPLAY = process.env.AGENT_BROWSER_DISPLAY || '';
+// Optional ICE servers as JSON (e.g. '[{"urls":"stun:stun.l.google.com:19302"}]').
+// Empty = host candidates only, which is correct for same-host / LAN.
+export const AGENT_BROWSER_WEBRTC_ICE_SERVERS = process.env.AGENT_BROWSER_WEBRTC_ICE_SERVERS || '';
+// --- Shared-browser maintenance ---
+// CDP port the shared agent browser listens on (must match agent-browser's).
+export const AGENT_BROWSER_CDP_PORT = parseIntEnv(process.env.AGENT_BROWSER_CDP_PORT, 9222);
+// Reap leaked chrome-devtools-mcp server stacks when one agent accumulates too
+// many (the observed leak). On by default; set 'false' to disable.
+export const AGENT_BROWSER_REAP_MCP = (process.env.AGENT_BROWSER_REAP_MCP || 'true').toLowerCase() !== 'false';
+// Max chrome-devtools-mcp stacks a single agent may keep before old extras are reaped.
+export const AGENT_BROWSER_MAX_MCP_PER_AGENT = parseIntEnv(process.env.AGENT_BROWSER_MAX_MCP_PER_AGENT, 3);
+// Extra stacks must be older than this before being reaped (spares restart bursts).
+export const AGENT_BROWSER_MCP_IDLE_MS = parseIntEnv(process.env.AGENT_BROWSER_MCP_IDLE_MS, 600_000);
 // Flat structure: dist/ and web/dist/ are siblings at project root
 export const distDir = path.resolve(__dirname, '..', 'web', 'dist');
 export const hasStatic = fsSync.existsSync(distDir);

package/dist/routes/codeserver.js

@@ -0,0 +1,87 @@
+import { Hono } from 'hono';
+// Hop-by-hop / encoding headers that must not be forwarded verbatim. undici's
+// fetch already decompresses the body, so leaving content-encoding/length on the
+// response would make the browser try to decompress decoded bytes.
+const STRIP_RESPONSE_HEADERS = ['content-encoding', 'content-length', 'transfer-encoding', 'connection'];
+async function proxy(c, codeServer) {
+    const wsId = c.req.param('wsId');
+    if (!wsId) {
+        return c.json({ error: 'workspace id required' }, 400);
+    }
+    let port;
+    try {
+        port = await codeServer.ensure(wsId);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: message }, 503);
+    }
+    const url = new URL(c.req.url);
+    const prefix = `/codeserver/${wsId}`;
+    let upstreamPath = url.pathname.slice(prefix.length) || '/';
+    if (!upstreamPath.startsWith('/')) {
+        upstreamPath = `/${upstreamPath}`;
+    }
+    const target = `http://127.0.0.1:${port}${upstreamPath}${url.search}`;
+    const headers = new Headers(c.req.raw.headers);
+    headers.set('host', `127.0.0.1:${port}`);
+    // Ask code-server not to compress; we re-stream the body raw.
+    headers.set('accept-encoding', 'identity');
+    const method = c.req.method;
+    const init = {
+        method,
+        headers,
+        redirect: 'manual',
+    };
+    if (method !== 'GET' && method !== 'HEAD') {
+        init.body = c.req.raw.body;
+        init.duplex = 'half';
+    }
+    let upstream;
+    try {
+        upstream = await fetch(target, init);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return c.json({ error: `code-server proxy failed: ${message}` }, 502);
+    }
+    const respHeaders = new Headers(upstream.headers);
+    for (const name of STRIP_RESPONSE_HEADERS) {
+        respHeaders.delete(name);
+    }
+    // Let code-server's service worker claim the whole subpath scope.
+    respHeaders.set('service-worker-allowed', `/codeserver/${wsId}/`);
+    return new Response(upstream.body, {
+        status: upstream.status,
+        statusText: upstream.statusText,
+        headers: respHeaders,
+    });
+}
+export function createCodeServerRouter(codeServer) {
+    const router = new Hono();
+    // Capability/status (must be registered before the :wsId catch-all).
+    router.get('/status', async (c) => {
+        const wsId = c.req.query('wsId') || undefined;
+        return c.json(await codeServer.getStatus(wsId));
+    });
+    router.post('/stop', async (c) => {
+        const wsId = c.req.query('wsId');
+        if (wsId) {
+            await codeServer.stop(wsId);
+        }
+        return c.json(await codeServer.getStatus(wsId || undefined));
+    });
+    // Kick off the (single-flight) code-server download without blocking — the
+    // client polls /status until acquired. No-op if already installed.
+    router.post('/install', async (c) => {
+        if (!(await codeServer.isAcquired())) {
+            void codeServer.download().catch(() => undefined);
+        }
+        return c.json(await codeServer.getStatus());
+    });
+    // Reverse-proxy everything else under /codeserver/:wsId/* to that workspace's
+    // code-server instance (prefix stripped).
+    router.all('/:wsId/*', (c) => proxy(c, codeServer));
+    router.all('/:wsId', (c) => proxy(c, codeServer));
+    return router;
+}

package/dist/routes/files.js

@@ -186,6 +186,78 @@ export function createFileRouter(workspaces) {
             return handleError(c, error);
         }
     });
+    // Move / rename a file or directory within the workspace (Drive UI).
+    router.post('/move', async (c) => {
+        try {
+            const body = await readJson(c);
+            const workspaceId = body?.workspaceId;
+            if (!workspaceId) {
+                throw createHttpError('workspaceId is required', 400);
+            }
+            if (!body?.from || !body?.to) {
+                throw createHttpError('from and to are required', 400);
+            }
+            const workspace = requireWorkspace(workspaces, workspaceId);
+            const fromPath = await resolveSafePath(workspace.path, body.from);
+            const toPath = await resolveSafePath(workspace.path, body.to);
+            // Source must exist (throws ENOENT otherwise).
+            await fs.stat(fromPath);
+            // No-clobber unless the caller explicitly opts in.
+            if (!body.overwrite) {
+                try {
+                    await fs.access(toPath);
+                    throw createHttpError('Destination already exists', 409);
+                }
+                catch (err) {
+                    if (err.code !== 'ENOENT') {
+                        throw err;
+                    }
+                }
+            }
+            await fs.mkdir(path.dirname(toPath), { recursive: true });
+            await fs.rename(fromPath, toPath);
+            return c.json({ from: body.from, to: body.to, moved: true });
+        }
+        catch (error) {
+            return handleError(c, error);
+        }
+    });
+    // Upload one or more files into a workspace directory (multipart form). The
+    // form field `file` may repeat. Filenames are reduced to their basename so an
+    // upload can never escape the target directory.
+    router.post('/upload', async (c) => {
+        try {
+            const form = await c.req.parseBody({ all: true });
+            const workspaceId = typeof form.workspaceId === 'string' ? form.workspaceId : undefined;
+            if (!workspaceId) {
+                throw createHttpError('workspaceId is required', 400);
+            }
+            const dir = typeof form.path === 'string' ? form.path : '';
+            const workspace = requireWorkspace(workspaces, workspaceId);
+            const field = form.file;
+            const files = (Array.isArray(field) ? field : [field]).filter((item) => item instanceof File);
+            if (files.length === 0) {
+                throw createHttpError('no files provided', 400);
+            }
+            const uploaded = [];
+            for (const file of files) {
+                if (file.size > MAX_FILE_SIZE) {
+                    throw createHttpError(`File too large: ${file.name} (${Math.round(file.size / 1024 / 1024)}MB). Maximum is ${Math.round(MAX_FILE_SIZE / 1024 / 1024)}MB.`, 413);
+                }
+                const safeName = path.basename(file.name);
+                const rel = dir ? `${dir}/${safeName}` : safeName;
+                const target = await resolveSafePath(workspace.path, rel);
+                await fs.mkdir(path.dirname(target), { recursive: true });
+                const buffer = Buffer.from(await file.arrayBuffer());
+                await fs.writeFile(target, buffer);
+                uploaded.push(rel);
+            }
+            return c.json({ uploaded });
+        }
+        catch (error) {
+            return handleError(c, error);
+        }
+    });
     // Delete directory
     router.delete('/dir', async (c) => {
         try {

package/dist/server.js

@@ -7,7 +7,7 @@ import { serve } from '@hono/node-server';
 import { serveStatic } from '@hono/node-server/serve-static';
 import { bodyLimit } from 'hono/body-limit';
 import { DatabaseSync } from 'node:sqlite';
-import { PORT, HOST, NODE_ENV, BASIC_AUTH_USER, BASIC_AUTH_PASSWORD, CORS_ORIGIN, MAX_FILE_SIZE, MAX_REQUEST_BODY_SIZE, TRUST_PROXY, hasStatic, distDir, dbPath, } from './config.js';
+import { PORT, HOST, NODE_ENV, BASIC_AUTH_USER, BASIC_AUTH_PASSWORD, CORS_ORIGIN, MAX_FILE_SIZE, MAX_REQUEST_BODY_SIZE, TRUST_PROXY, hasStatic, distDir, dbPath, AGENT_BROWSER_REAP_MCP, AGENT_BROWSER_CDP_PORT, AGENT_BROWSER_MAX_MCP_PER_AGENT, AGENT_BROWSER_MCP_IDLE_MS, } from './config.js';
 import { securityHeaders } from './middleware/security.js';
 import { corsMiddleware } from './middleware/cors.js';
 import { basicAuthMiddleware, generateWsToken, isBasicAuthEnabled } from './middleware/auth.js';
@@ -20,7 +20,10 @@ import { createGitRouter } from './routes/git.js';
 import { createSettingsRouter } from './routes/settings.js';
 import { createMcpRouter } from './routes/mcp.js';
 import { createBrowserRouter } from './routes/browser.js';
+import { createCodeServerRouter } from './routes/codeserver.js';
 import { AgentBrowserService } from './utils/agent-browser.js';
+import { CodeServerService } from './utils/code-server.js';
+import { startMcpReaper } from './utils/browser-maintenance.js';
 import { setupWebSocketServer, getConnectionLimit, setConnectionLimit, getConnectionStats, clearAllConnections, } from './websocket.js';
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 // Request ID and logging middleware
@@ -51,6 +54,7 @@ export async function createServer() {
     const decks = new Map();
     const terminals = new Map();
     const browserService = new AgentBrowserService();
+    const codeServerService = new CodeServerService(workspaces);
     // 共有ブラウザを起動時から常駐させ、BrowserPane を開いていなくても
     // Codex/Claude の chrome MCP（--browserUrl 127.0.0.1:9222）が常に使えるようにする。
     // 失敗してもサーバ起動は継続（Chrome 未導入の環境などを考慮）。AGENT_BROWSER_AUTOSTART=false で無効化可。
@@ -59,6 +63,17 @@ export async function createServer() {
             console.error('[browser] 共有ブラウザの自動起動に失敗:', err instanceof Error ? err.message : err);
         });
     }
+    // Periodically reap leaked chrome-devtools-mcp servers (agents spawn one per
+    // session against our CDP port and can leave them disconnected — wedging the
+    // agent's chrome tools and leaking GBs). Safe: only disconnected + idle ones.
+    const stopMcpReaper = AGENT_BROWSER_REAP_MCP
+        ? startMcpReaper({
+            cdpPort: AGENT_BROWSER_CDP_PORT,
+            maxPerAgent: AGENT_BROWSER_MAX_MCP_PER_AGENT,
+            idleMs: AGENT_BROWSER_MCP_IDLE_MS,
+            intervalMs: 120_000,
+        })
+        : null;
     loadPersistedState(db, workspaces, workspacePathIndex, decks);
     // Create Hono app
     const app = new Hono();
@@ -80,6 +95,8 @@ export async function createServer() {
     if (basicAuthMiddleware) {
         app.use('/api/*', basicAuthMiddleware);
         app.use('/oauth/authorize', basicAuthMiddleware);
+        // code-server runs with --auth none; this same-origin proxy is the gate.
+        app.use('/codeserver/*', basicAuthMiddleware);
     }
     app.get('/health', (c) => c.json({ status: 'ok', timestamp: new Date().toISOString(), uptime: process.uptime() }));
     // Mount routers
@@ -90,6 +107,7 @@ export async function createServer() {
     app.route('/api/terminals', terminalRouter);
     app.route('/api/git', createGitRouter(workspaces));
     app.route('/api/browser', createBrowserRouter(browserService));
+    app.route('/codeserver', createCodeServerRouter(codeServerService));
     app.get('/api/config', getConfigHandler());
     app.get('/api/ws-token', (c) => c.json({ token: generateWsToken(), authEnabled: isBasicAuthEnabled() }));
     app.get('/api/ws/stats', (c) => c.json({ limit: getConnectionLimit(), connections: getConnectionStats() }));
@@ -122,7 +140,7 @@ export async function createServer() {
         });
     }
     const server = serve({ fetch: app.fetch, port: PORT, hostname: HOST });
-    setupWebSocketServer(server, terminals, browserService);
+    setupWebSocketServer(server, terminals, browserService, codeServerService);
     server.on('listening', () => {
         const baseUrl = `http://localhost:${PORT}`;
         console.log(`Deck IDE server listening on ${baseUrl}`);
@@ -157,7 +175,9 @@ export async function createServer() {
                 session.kill();
             });
             terminals.clear();
+            stopMcpReaper?.();
             await browserService.stop();
+            await codeServerService.stopAll();
             try {
                 db.close();
             }

package/dist/utils/agent-browser.js

@@ -5,6 +5,7 @@ import os from 'node:os';
 import path from 'node:path';
 import { WebSocket } from 'ws';
 import { BrowserAudioRelay } from './browser-audio.js';
+import { BrowserWebRtcRelay } from './browser-webrtc.js';
 const DEFAULT_PROFILE_DIR = path.join(os.homedir(), '.local', 'share', 'agent-browser', 'profile');
 const DEFAULT_OUTPUT_DIR = path.join(os.homedir(), '.local', 'share', 'agent-browser', 'output');
 const START_TIMEOUT_MS = 30_000;
@@ -320,6 +321,9 @@ export class AgentBrowserService {
     viewport = { ...DEFAULT_VIEWPORT };
     lastError;
     audioRelay = new BrowserAudioRelay();
+    // A1 WebRTC video path (direct Xvfb capture → ffmpeg → werift). Constructed
+    // always, but inert until AGENT_BROWSER_WEBRTC is enabled and a client connects.
+    webrtcRelay = new BrowserWebRtcRelay(this);
     profileDir = process.env.AGENT_BROWSER_PROFILE_DIR || DEFAULT_PROFILE_DIR;
     outputDir = process.env.AGENT_BROWSER_OUTPUT_DIR || DEFAULT_OUTPUT_DIR;
     async getStatus() {
@@ -336,6 +340,7 @@ export class AgentBrowserService {
             tabs: [...this.tabs.values()].map((tab) => ({ ...tab })),
             activeTabId: this.activeTargetId,
             audio: await this.audioRelay.getStatus(),
+            webrtc: await this.webrtcRelay.getStatus(),
             error: this.lastError,
         };
     }
@@ -421,6 +426,7 @@ export class AgentBrowserService {
         }
         this.closeLogStream();
         await this.audioRelay.stop();
+        await this.webrtcRelay.stop();
         await this.broadcastStatus();
     }
     attachWebSocket(socket) {
@@ -442,6 +448,57 @@ export class AgentBrowserService {
     attachAudioWebSocket(socket) {
         this.audioRelay.attachWebSocket(socket);
     }
+    attachWebRtcWebSocket(socket) {
+        this.webrtcRelay.attachWebSocket(socket);
+    }
+    // --- WebRtcHost: capabilities the WebRTC relay needs from the browser ---
+    isBrowserRunning() {
+        return this.isRunning();
+    }
+    // Position+size the active tab's OS window on the X display. No window manager
+    // runs under Xvfb, so 'maximized'/'fullscreen' window states are unreliable —
+    // explicit normal bounds are not.
+    async setActiveWindowBounds(left, top, width, height) {
+        if (!this.activeTargetId) {
+            return;
+        }
+        await this.connectBrowserCdp();
+        const cdp = this.browserCdp;
+        if (!cdp) {
+            return;
+        }
+        const win = await cdp
+            .send('Browser.getWindowForTarget', { targetId: this.activeTargetId })
+            .catch(() => null);
+        if (!win || typeof win.windowId !== 'number') {
+            return;
+        }
+        await cdp
+            .send('Browser.setWindowBounds', {
+            windowId: win.windowId,
+            bounds: { left, top, width, height, windowState: 'normal' },
+        })
+            .catch(() => undefined);
+    }
+    // Pin the active tab's render viewport to a fixed size (the WebRTC framebuffer)
+    // so captured pixels equal page coordinates. Does not mutate this.viewport, so
+    // the JPEG path's client-driven resize is unaffected when WebRTC isn't active.
+    async pinViewport(width, height) {
+        await this.ensureActiveCdp();
+        if (!this.activeCdp) {
+            return;
+        }
+        await this.activeCdp
+            .send('Emulation.setDeviceMetricsOverride', {
+            width,
+            height,
+            deviceScaleFactor: 1,
+            mobile: false,
+            screenWidth: width,
+            screenHeight: height,
+        })
+            .catch(() => undefined);
+    }
     async navigate(input) {
         const url = normalizeBrowserUrl(input);
         await this.start();
@@ -585,6 +642,9 @@ export class AgentBrowserService {
                 this.port = null;
                 this.disconnectActiveCdp();
                 this.closeBrowserCdp();
+                // Tear down the WebRTC relay too, so a Chrome crash never leaves an
+                // orphaned x11grab/ffmpeg encoder pointed at a dead display.
+                void this.webrtcRelay.stop();
                 this.tabs.clear();
                 this.activeTargetId = null;
                 this.ready = false;

package/dist/utils/browser-maintenance.js

@@ -0,0 +1,145 @@
+import fs from 'node:fs/promises';
+// Linux clock ticks per second. Effectively always 100 on Linux; used only to
+// estimate process age, where small drift is harmless.
+const CLOCK_HZ = 100;
+/**
+ * Pure selection: given the set of chrome-devtools-mcp processes (node servers +
+ * their npm/sh launcher wrappers), return the pids to kill. Exported for testing.
+ *
+ * A "stack top" is a proc whose parent is not itself in the set (its parent is
+ * the agent). Stacks are grouped by agent; for any agent owning more than
+ * `maxPerAgent` stacks, the oldest extras beyond the cap — and only those older
+ * than `idleMs` — are selected along with their whole subtree. Healthy agents
+ * (≤ maxPerAgent stacks) are never touched.
+ */
+export function planReap(procs, maxPerAgent, idleMs) {
+    const stacksByAgent = new Map();
+    for (const [pid, info] of procs) {
+        if (!procs.has(info.ppid)) {
+            const list = stacksByAgent.get(info.ppid) ?? [];
+            list.push(pid);
+            stacksByAgent.set(info.ppid, list);
+        }
+    }
+    const children = new Map();
+    for (const [pid, info] of procs) {
+        const list = children.get(info.ppid) ?? [];
+        list.push(pid);
+        children.set(info.ppid, list);
+    }
+    const kill = [];
+    for (const tops of stacksByAgent.values()) {
+        if (tops.length <= maxPerAgent) {
+            continue;
+        }
+        tops.sort((a, b) => procs.get(b).ageSec - procs.get(a).ageSec); // oldest first
+        for (const top of tops.slice(0, tops.length - maxPerAgent)) {
+            if (procs.get(top).ageSec * 1000 < idleMs) {
+                continue; // spare recent stacks (e.g. mid-restart)
+            }
+            const queue = [top];
+            while (queue.length) {
+                const pid = queue.shift();
+                kill.push(pid);
+                for (const child of children.get(pid) ?? []) {
+                    if (procs.has(child))
+                        queue.push(child);
+                }
+            }
+        }
+    }
+    return kill;
+}
+/**
+ * Reaps leaked `chrome-devtools-mcp` server stacks.
+ *
+ * Agents (Claude/Codex) spawn one chrome-devtools-mcp server per session pointed
+ * at our shared browser's CDP port. A buggy agent can respawn it on every failure
+ * without reaping the old one — we observed a single Codex process holding 66
+ * servers (~24 GB) with the agent's active one wedged ("can't use chrome").
+ *
+ * NOTE: chrome-devtools-mcp connects to the browser lazily (only during a tool
+ * call), so "not connected to 9222" does NOT mean "dead" — an idle-but-live
+ * session would look disconnected. We therefore key off the actual leak
+ * signature instead: when ONE agent process owns more than `maxPerAgent`
+ * chrome-devtools-mcp stacks (aimed at our port), the oldest extras beyond the
+ * cap that are also older than `idleMs` are killed, keeping the newest (active)
+ * ones. A healthy agent with a single MCP is never touched. Linux-only.
+ */
+export function startMcpReaper(opts) {
+    const timer = setInterval(() => {
+        void reapOnce(opts).catch(() => undefined);
+    }, opts.intervalMs);
+    timer.unref?.();
+    return () => clearInterval(timer);
+}
+// All chrome-devtools-mcp processes (node servers + npm/sh launcher wrappers)
+// whose cmdline targets our CDP port. Keyed by pid.
+async function readMcpProcs(cdpPort) {
+    const procs = new Map();
+    let uptime;
+    try {
+        uptime = parseFloat((await fs.readFile('/proc/uptime', 'utf8')).split(' ')[0]);
+    }
+    catch {
+        return procs; // not Linux / no procfs
+    }
+    let pids;
+    try {
+        pids = (await fs.readdir('/proc')).filter((n) => /^\d+$/.test(n));
+    }
+    catch {
+        return procs;
+    }
+    const portToken = `127.0.0.1:${cdpPort}`;
+    for (const pid of pids) {
+        let cmdline;
+        try {
+            cmdline = (await fs.readFile(`/proc/${pid}/cmdline`, 'utf8')).replace(/\0/g, ' ').trim();
+        }
+        catch {
+            continue;
+        }
+        // Target only chrome-devtools-mcp aimed at OUR shared browser.
+        if (!cmdline.includes('chrome-devtools-mcp') || !cmdline.includes(portToken)) {
+            continue;
+        }
+        let stat;
+        try {
+            stat = await fs.readFile(`/proc/${pid}/stat`, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        // comm (field 2) is parenthesised and may contain spaces/parens — parse after
+        // the final ')'. Then index 1 = ppid (field 4), index 19 = starttime (field 22).
+        const after = stat.slice(stat.lastIndexOf(')') + 2).split(' ');
+        const ppid = Number.parseInt(after[1], 10);
+        const starttime = Number.parseInt(after[19], 10);
+        if (!Number.isFinite(ppid) || !Number.isFinite(starttime)) {
+            continue;
+        }
+        procs.set(Number.parseInt(pid, 10), { ppid, cmdline, ageSec: uptime - starttime / CLOCK_HZ });
+    }
+    return procs;
+}
+async function reapOnce(opts) {
+    const procs = await readMcpProcs(opts.cdpPort);
+    if (procs.size === 0) {
+        return;
+    }
+    const kill = planReap(procs, opts.maxPerAgent, opts.idleMs);
+    let reaped = 0;
+    for (const pid of kill) {
+        try {
+            process.kill(pid, 'SIGTERM');
+            reaped++;
+        }
+        catch {
+            // already gone
+        }
+    }
+    if (reaped > 0) {
+        console.log(`[browser-maintenance] reaped ${reaped} process(es) from leaked chrome-devtools-mcp stacks`);
+    }
+}