@remcp/runtime 0.2.173 → 0.2.174

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## 0.2.174 — 2026-10-22
+
+- Preserve the 83 runtime operations and existing schemas while separating guarded browser CDP security policy and diagnostics recording backends.
+- Retain browser-origin, DNS/SSRF checks, platform protections and output limits without widening device permissions.
+- Publish alongside the refactored client/host at the same version for package compatibility.
+
 ## 0.2.173 — 2026-10-22
 
 - Return initial terminal output promptly after a bounded 175 ms grace when a long-running process writes without exiting.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.173",
+  "version": "0.2.174",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/extended/browser-endpoint.mjs

@@ -1,8 +1,6 @@
 import process from 'node:process';
 import os from 'node:os';
 import path from 'node:path';
-import { isIP } from 'node:net';
-import { lookup } from 'node:dns/promises';
 import { existsSync, mkdirSync } from 'node:fs';
 import { resolveSafePath } from '../util.mjs';
 import { selectSafeBrowserLaunchProfile } from './browser-session-backup.mjs';
@@ -10,16 +8,14 @@ import { shouldRestoreBrowserSession } from './browser-session-directory.mjs';
 import { shareBrowserDiscovery } from './browser-discovery-flight.mjs';
 import { observeBrowserLaunchExit, browserLaunchExitHint } from './browser-launch-lifecycle.mjs';
 import { clamp, commandExists, jsonResult, optionalString, requireEnum, spawnDetached, unavailable } from './common.mjs';
+import {
+  endpointUrl, endpointAuthority, isLoopbackHost, normalizedHost,
+  safePageUrl, assertResolvedPageUrl, productionBrowserPolicyReady,
+} from './browser-policy.mjs';
+export * from './browser-policy.mjs';
 
-
-
-export const DEFAULT_ENDPOINT = 'http://127.0.0.1:9222';
 export const MAX_DISCOVERY_BYTES = 8 * 1024 * 1024;
 export const MAX_CDP_MESSAGE_BYTES = 16 * 1024 * 1024;
-export const MAX_EVALUATION_BYTES = 256 * 1024;
-export const BROWSER_PROTOCOLS = new Set(['http:', 'https:']);
-export const BLOCKED_BROWSER_SCHEME = /(?:^|[\s"'`(=])(?:file|chrome|devtools|view-source|filesystem|blob|wss?):/i;
-export const BLOCKED_BROWSER_NETWORK_API = /\b(?:fetch|WebSocket|EventSource|XMLHttpRequest|sendBeacon)\b/;
 export const PRODUCTION_SESSION_IDLE_MS = 10 * 60 * 1000;
 export const productionBrowserSessions = new Map();
 
@@ -133,185 +129,6 @@ export async function browserControlAvailable(endpoint, timeoutMs = 500) {
   return browserAutoLaunchAvailable();
 }
 
-export function boundedText(value, max = 1000) {
-  const text = String(value ?? '');
-  return text.length <= max ? text : `${text.slice(0, max)}…`;
-}
-
-export function normalizedHost(hostname) {
-  return String(hostname || '').replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
-}
-
-export function isLoopbackHost(hostname) {
-  const host = normalizedHost(hostname);
-  return ['localhost', '127.0.0.1', '::1'].includes(host);
-}
-
-export function localBrowserNavigationAllowed() {
-  if (process.env.NODE_ENV === 'production') return false;
-  return ['REMCP_BROWSER_ALLOW_LOCAL_NAVIGATION', 'REMCP_BROWSER_ALLOW_LOCAL', 'REMCP_ALLOW_LOCAL_BROWSER_NAVIGATION']
-    .some(name => ['1', 'true', 'yes', 'on'].includes(String(process.env[name] || '').trim().toLowerCase()));
-}
-
-export function isPrivateIpv4(host) {
-  if (isIP(host) !== 4) return false;
-  const parts = host.split('.').map(Number);
-  const [a, b, c] = parts;
-  return a === 0
-    || a === 10
-    || a === 127
-    || (a === 100 && b >= 64 && b <= 127)
-    || (a === 169 && b === 254)
-    || (a === 172 && b >= 16 && b <= 31)
-    || (a === 192 && b === 0 && c === 0)
-    || (a === 192 && b === 0 && c === 2)
-    || (a === 192 && b === 168)
-    || (a === 198 && (b === 18 || b === 19))
-    || (a === 198 && b === 51 && c === 100)
-    || (a === 203 && b === 0 && c === 113)
-    || a >= 224;
-}
-
-export function isPrivateIpv6(host) {
-  if (isIP(host) !== 6) return false;
-  if (host === '::' || host === '::1') return true;
-  if (/^f[cd]/.test(host) || /^fe[89ab]/.test(host) || host.startsWith('ff')) return true;
-  const mapped = host.match(/^::(?:ffff:)?([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
-  if (mapped) {
-    const high = Number.parseInt(mapped[1], 16);
-    const low = Number.parseInt(mapped[2], 16);
-    return isPrivateIpv4([high >> 8, high & 255, low >> 8, low & 255].join('.'));
-  }
-  return false;
-}
-
-export function isPrivateBrowserHost(hostname) {
-  const host = normalizedHost(hostname);
-  if (!host) return true;
-  if (isPrivateIpv4(host) || isPrivateIpv6(host)) return true;
-  return host === 'localhost'
-    || host.endsWith('.localhost')
-    || host.endsWith('.local')
-    || host.endsWith('.internal')
-    || host.endsWith('.home.arpa')
-    || host.endsWith('.lan')
-    || host === 'localhost.localdomain'
-    || host === 'ip6-localhost'
-    || host === 'ip6-loopback';
-}
-
-export function endpointUrl(value) {
-  if (value != null && typeof value !== 'string' && !(value instanceof URL)) {
-    throw new Error('endpoint must be a valid local http(s) URL');
-  }
-  let url;
-  try {
-    const provided = value instanceof URL ? value.href : optionalString(value);
-    url = new URL(provided || process.env.REMCP_CDP_URL || DEFAULT_ENDPOINT);
-  } catch { throw new Error('endpoint must be a valid local http(s) URL'); }
-  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('endpoint must use http or https');
-  if (!isLoopbackHost(url.hostname)) throw new Error('Browser CDP endpoint must be loopback-only');
-  if (url.username || url.password) throw new Error('Browser CDP endpoint must not contain credentials');
-  return url;
-}
-
-export function endpointAuthority(url) {
-  const port = url.port || ((url.protocol === 'https:' || url.protocol === 'wss:') ? '443' : '80');
-  return `${normalizedHost(url.hostname)}:${port}`;
-}
-
-export function safeBrowserUrl(value, field = 'url') {
-  let url;
-  try { url = new URL(String(value || '')); }
-  catch { throw new Error(`${field} must be a valid absolute URL`); }
-  if (!BROWSER_PROTOCOLS.has(url.protocol)) throw new Error(`${field} must use http or https`);
-  if (url.username || url.password) throw new Error(`${field} must not embed credentials`);
-  if (!localBrowserNavigationAllowed() && isPrivateBrowserHost(url.hostname)) {
-    throw new Error(`${field} must not target loopback, private, or link-local addresses`);
-  }
-  return url.href;
-}
-
-export function safePageUrl(value, field = 'browser page URL') {
-  if (String(value || '') === 'about:blank') return value;
-  return safeBrowserUrl(value, field);
-}
-
-export function configuredBrowserHosts() {
-  return String(process.env.REMCP_BROWSER_ALLOWED_HOSTS || '')
-    .split(/[,\s]+/)
-    .map(normalizedHost)
-    .filter(Boolean);
-}
-
-export function browserHostAllowlisted(host) {
-  return configuredBrowserHosts().some(pattern => pattern === host
-    || (pattern.startsWith('*.') && host.endsWith(pattern.slice(1)) && host.length > pattern.length - 1));
-}
-
-export function browserDnsRebindingExplicitlyAllowed() {
-  return ['1', 'true', 'yes', 'on'].includes(String(process.env.REMCP_BROWSER_ALLOW_DNS_REBIND || '').trim().toLowerCase());
-}
-
-export function productionBrowserPolicyReady() {
-  const hosts = configuredBrowserHosts();
-  return (hosts.length > 0 && hosts.some(isIP))
-    || (browserDnsRebindingExplicitlyAllowed() && hosts.length > 0);
-}
-
-export async function assertResolvedBrowserUrl(value, field = 'browser URL') {
-  const safe = safeBrowserUrl(value, field);
-  if (localBrowserNavigationAllowed() && process.env.NODE_ENV !== 'production') return safe;
-  const host = normalizedHost(new URL(safe).hostname);
-  if (process.env.NODE_ENV === 'production' && !browserHostAllowlisted(host)) {
-    throw new Error(`${field} host is not in REMCP_BROWSER_ALLOWED_HOSTS`);
-  }
-  if (isIP(host) || (host.endsWith('.test') && process.env.NODE_ENV !== 'production')) return safe;
-  if (process.env.NODE_ENV === 'production' && !isIP(host) && !browserDnsRebindingExplicitlyAllowed()) {
-    throw new Error(`${field} requires an IP-literal allowlist in production; set REMCP_BROWSER_ALLOW_DNS_REBIND=1 only with a DNS/egress boundary`);
-  }
-  let addresses;
-  try { addresses = await lookup(host, { all:true, verbatim:true }); }
-  catch (error) { throw new Error(`${field} host could not be resolved safely: ${error instanceof Error ? error.message : String(error)}`); }
-  if (addresses.some(address => isPrivateBrowserHost(address.address))) {
-    throw new Error(`${field} must not resolve to loopback, private, or link-local addresses`);
-  }
-  return safe;
-}
-
-export async function assertResolvedPageUrl(value, field = 'browser page URL') {
-  if (String(value || '') === 'about:blank') return value;
-  return assertResolvedBrowserUrl(value, field);
-}
-
-export function expressionHasPrivateDestination(expression) {
-  const urls = expression.match(/(?:https?|wss?):\/\/[^\s"'`<>]+/gi) || [];
-  return urls.some(value => {
-    try { return isPrivateBrowserHost(new URL(value).hostname); }
-    catch { return false; }
-  });
-}
-
-export function safeEvaluationExpression(value) {
-  const expression = String(value || '');
-  if (!expression.trim()) throw new Error('expression is required');
-  if (expression.includes('\0') || Buffer.byteLength(expression, 'utf8') > MAX_EVALUATION_BYTES) {
-    throw new Error(`expression must be at most ${MAX_EVALUATION_BYTES} bytes`);
-  }
-  if (BLOCKED_BROWSER_SCHEME.test(expression)) throw new Error('expression contains a blocked local browser scheme');
-  if (!localBrowserNavigationAllowed() && (expressionHasPrivateDestination(expression) || BLOCKED_BROWSER_NETWORK_API.test(expression))) {
-    throw new Error('expression contains a blocked private browser destination or network API');
-  }
-  return expression;
-}
-
-export async function assertSafeEvaluationExpression(value) {
-  const expression = safeEvaluationExpression(value);
-  const urls = expression.match(/(?:https?|wss?):\/\/[^\s"'`<>]+/gi) || [];
-  await Promise.all(urls.map(url => assertResolvedBrowserUrl(url, 'expression destination')));
-  return expression;
-}
-
 export async function requestJson(pathname, endpoint, options = {}) {
   const base = endpointUrl(endpoint);
   const url = new URL(pathname, base);

package/src/extended/browser-policy.mjs

@@ -0,0 +1,190 @@
+// Browser navigation, CDP-origin and evaluation policies. No CDP transport or session state.
+import process from 'node:process';
+import { isIP } from 'node:net';
+import { lookup } from 'node:dns/promises';
+import { optionalString } from './common.mjs';
+
+export const DEFAULT_ENDPOINT = 'http://127.0.0.1:9222';
+export const MAX_EVALUATION_BYTES = 256 * 1024;
+export const BROWSER_PROTOCOLS = new Set(['http:', 'https:']);
+export const BLOCKED_BROWSER_SCHEME = /(?:^|[\s"'`(=])(?:file|chrome|devtools|view-source|filesystem|blob|wss?):/i;
+export const BLOCKED_BROWSER_NETWORK_API = /\b(?:fetch|WebSocket|EventSource|XMLHttpRequest|sendBeacon)\b/;
+
+export function boundedText(value, max = 1000) {
+  const text = String(value ?? '');
+  return text.length <= max ? text : `${text.slice(0, max)}…`;
+}
+
+export function normalizedHost(hostname) {
+  return String(hostname || '').replace(/^\[|\]$/g, '').replace(/\.$/, '').toLowerCase();
+}
+
+export function isLoopbackHost(hostname) {
+  const host = normalizedHost(hostname);
+  return ['localhost', '127.0.0.1', '::1'].includes(host);
+}
+
+export function localBrowserNavigationAllowed() {
+  if (process.env.NODE_ENV === 'production') return false;
+  return ['REMCP_BROWSER_ALLOW_LOCAL_NAVIGATION', 'REMCP_BROWSER_ALLOW_LOCAL', 'REMCP_ALLOW_LOCAL_BROWSER_NAVIGATION']
+    .some(name => ['1', 'true', 'yes', 'on'].includes(String(process.env[name] || '').trim().toLowerCase()));
+}
+
+export function isPrivateIpv4(host) {
+  if (isIP(host) !== 4) return false;
+  const parts = host.split('.').map(Number);
+  const [a, b, c] = parts;
+  return a === 0
+    || a === 10
+    || a === 127
+    || (a === 100 && b >= 64 && b <= 127)
+    || (a === 169 && b === 254)
+    || (a === 172 && b >= 16 && b <= 31)
+    || (a === 192 && b === 0 && c === 0)
+    || (a === 192 && b === 0 && c === 2)
+    || (a === 192 && b === 168)
+    || (a === 198 && (b === 18 || b === 19))
+    || (a === 198 && b === 51 && c === 100)
+    || (a === 203 && b === 0 && c === 113)
+    || a >= 224;
+}
+
+export function isPrivateIpv6(host) {
+  if (isIP(host) !== 6) return false;
+  if (host === '::' || host === '::1') return true;
+  if (/^f[cd]/.test(host) || /^fe[89ab]/.test(host) || host.startsWith('ff')) return true;
+  const mapped = host.match(/^::(?:ffff:)?([0-9a-f]{1,4}):([0-9a-f]{1,4})$/);
+  if (mapped) {
+    const high = Number.parseInt(mapped[1], 16);
+    const low = Number.parseInt(mapped[2], 16);
+    return isPrivateIpv4([high >> 8, high & 255, low >> 8, low & 255].join('.'));
+  }
+  return false;
+}
+
+export function isPrivateBrowserHost(hostname) {
+  const host = normalizedHost(hostname);
+  if (!host) return true;
+  if (isPrivateIpv4(host) || isPrivateIpv6(host)) return true;
+  return host === 'localhost'
+    || host.endsWith('.localhost')
+    || host.endsWith('.local')
+    || host.endsWith('.internal')
+    || host.endsWith('.home.arpa')
+    || host.endsWith('.lan')
+    || host === 'localhost.localdomain'
+    || host === 'ip6-localhost'
+    || host === 'ip6-loopback';
+}
+
+export function endpointUrl(value) {
+  if (value != null && typeof value !== 'string' && !(value instanceof URL)) {
+    throw new Error('endpoint must be a valid local http(s) URL');
+  }
+  let url;
+  try {
+    const provided = value instanceof URL ? value.href : optionalString(value);
+    url = new URL(provided || process.env.REMCP_CDP_URL || DEFAULT_ENDPOINT);
+  } catch { throw new Error('endpoint must be a valid local http(s) URL'); }
+  if (!['http:', 'https:'].includes(url.protocol)) throw new Error('endpoint must use http or https');
+  if (!isLoopbackHost(url.hostname)) throw new Error('Browser CDP endpoint must be loopback-only');
+  if (url.username || url.password) throw new Error('Browser CDP endpoint must not contain credentials');
+  return url;
+}
+
+export function endpointAuthority(url) {
+  const port = url.port || ((url.protocol === 'https:' || url.protocol === 'wss:') ? '443' : '80');
+  return `${normalizedHost(url.hostname)}:${port}`;
+}
+
+export function safeBrowserUrl(value, field = 'url') {
+  let url;
+  try { url = new URL(String(value || '')); }
+  catch { throw new Error(`${field} must be a valid absolute URL`); }
+  if (!BROWSER_PROTOCOLS.has(url.protocol)) throw new Error(`${field} must use http or https`);
+  if (url.username || url.password) throw new Error(`${field} must not embed credentials`);
+  if (!localBrowserNavigationAllowed() && isPrivateBrowserHost(url.hostname)) {
+    throw new Error(`${field} must not target loopback, private, or link-local addresses`);
+  }
+  return url.href;
+}
+
+export function safePageUrl(value, field = 'browser page URL') {
+  if (String(value || '') === 'about:blank') return value;
+  return safeBrowserUrl(value, field);
+}
+
+export function configuredBrowserHosts() {
+  return String(process.env.REMCP_BROWSER_ALLOWED_HOSTS || '')
+    .split(/[,\s]+/)
+    .map(normalizedHost)
+    .filter(Boolean);
+}
+
+export function browserHostAllowlisted(host) {
+  return configuredBrowserHosts().some(pattern => pattern === host
+    || (pattern.startsWith('*.') && host.endsWith(pattern.slice(1)) && host.length > pattern.length - 1));
+}
+
+export function browserDnsRebindingExplicitlyAllowed() {
+  return ['1', 'true', 'yes', 'on'].includes(String(process.env.REMCP_BROWSER_ALLOW_DNS_REBIND || '').trim().toLowerCase());
+}
+
+export function productionBrowserPolicyReady() {
+  const hosts = configuredBrowserHosts();
+  return (hosts.length > 0 && hosts.some(isIP))
+    || (browserDnsRebindingExplicitlyAllowed() && hosts.length > 0);
+}
+
+export async function assertResolvedBrowserUrl(value, field = 'browser URL') {
+  const safe = safeBrowserUrl(value, field);
+  if (localBrowserNavigationAllowed() && process.env.NODE_ENV !== 'production') return safe;
+  const host = normalizedHost(new URL(safe).hostname);
+  if (process.env.NODE_ENV === 'production' && !browserHostAllowlisted(host)) {
+    throw new Error(`${field} host is not in REMCP_BROWSER_ALLOWED_HOSTS`);
+  }
+  if (isIP(host) || (host.endsWith('.test') && process.env.NODE_ENV !== 'production')) return safe;
+  if (process.env.NODE_ENV === 'production' && !isIP(host) && !browserDnsRebindingExplicitlyAllowed()) {
+    throw new Error(`${field} requires an IP-literal allowlist in production; set REMCP_BROWSER_ALLOW_DNS_REBIND=1 only with a DNS/egress boundary`);
+  }
+  let addresses;
+  try { addresses = await lookup(host, { all:true, verbatim:true }); }
+  catch (error) { throw new Error(`${field} host could not be resolved safely: ${error instanceof Error ? error.message : String(error)}`); }
+  if (addresses.some(address => isPrivateBrowserHost(address.address))) {
+    throw new Error(`${field} must not resolve to loopback, private, or link-local addresses`);
+  }
+  return safe;
+}
+
+export async function assertResolvedPageUrl(value, field = 'browser page URL') {
+  if (String(value || '') === 'about:blank') return value;
+  return assertResolvedBrowserUrl(value, field);
+}
+
+export function expressionHasPrivateDestination(expression) {
+  const urls = expression.match(/(?:https?|wss?):\/\/[^\s"'`<>]+/gi) || [];
+  return urls.some(value => {
+    try { return isPrivateBrowserHost(new URL(value).hostname); }
+    catch { return false; }
+  });
+}
+
+export function safeEvaluationExpression(value) {
+  const expression = String(value || '');
+  if (!expression.trim()) throw new Error('expression is required');
+  if (expression.includes('\0') || Buffer.byteLength(expression, 'utf8') > MAX_EVALUATION_BYTES) {
+    throw new Error(`expression must be at most ${MAX_EVALUATION_BYTES} bytes`);
+  }
+  if (BLOCKED_BROWSER_SCHEME.test(expression)) throw new Error('expression contains a blocked local browser scheme');
+  if (!localBrowserNavigationAllowed() && (expressionHasPrivateDestination(expression) || BLOCKED_BROWSER_NETWORK_API.test(expression))) {
+    throw new Error('expression contains a blocked private browser destination or network API');
+  }
+  return expression;
+}
+
+export async function assertSafeEvaluationExpression(value) {
+  const expression = safeEvaluationExpression(value);
+  const urls = expression.match(/(?:https?|wss?):\/\/[^\s"'`<>]+/gi) || [];
+  await Promise.all(urls.map(url => assertResolvedBrowserUrl(url, 'expression destination')));
+  return expression;
+}

package/src/extended/diagnostics-recording.mjs

@@ -0,0 +1,375 @@
+// Screen recording backends and safe output handling, independent of system diagnostics.
+import os from 'node:os';
+import path from 'node:path';
+import process from 'node:process';
+import { randomUUID } from 'node:crypto';
+import { constants, existsSync } from 'node:fs';
+import { lstat, mkdtemp, open, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
+import { isWaylandSession } from '../screenshot-portal.mjs';
+import { openDirectoryPath } from '../tools/files.mjs';
+import { resolveSafePath } from '../util.mjs';
+import { clamp, commandExists, jsonResult, runFile, unavailable } from './common.mjs';
+
+export function resolveRecordScreenFfmpeg({
+  platform = process.platform,
+  commandExistsFn = commandExists,
+  existsSyncFn = existsSync,
+} = {}) {
+  if (commandExistsFn('ffmpeg')) return 'ffmpeg';
+  if (platform === 'darwin') {
+    for (const candidate of ['/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg']) {
+      if (existsSyncFn(candidate)) return candidate;
+    }
+  }
+  return null;
+}
+
+export function parseAvfoundationScreenInput(output) {
+  for (const line of String(output || '').split(/\r?\n/)) {
+    const match = line.match(/\[(\d+)\]\s+Capture screen(?:\s+\d+)?\s*$/i);
+    if (match) return match[1];
+  }
+  return null;
+}
+
+async function avfoundationScreenInput(ffmpeg) {
+  const result = await runFile(ffmpeg, [
+    '-hide_banner',
+    '-f','avfoundation',
+    '-list_devices','true',
+    '-i','',
+  ], { label:'AVFoundation device inventory', timeout:10_000, allowFailure:true });
+  const index = parseAvfoundationScreenInput(`${result.stderr || ''}\n${result.stdout || ''}`);
+  if (!index) unavailable('Screen recording', 'ffmpeg could not find an AVFoundation Capture screen input');
+  return index;
+}
+
+export function gnomeScreencastCandidate({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  commandExistsFn = commandExists,
+} = {}) {
+  const gnomeSession = /gnome/i.test(String(desktop)) || Boolean(String(gnomeSessionMode).trim());
+  return platform === 'linux'
+    && wayland
+    && gnomeSession
+    && Boolean(String(sessionBus).trim())
+    && commandExistsFn('gjs');
+}
+
+export function recordScreenBackend({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  display = process.env.DISPLAY || '',
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  gnomeSupported = false,
+  commandExistsFn = commandExists,
+  existsSyncFn = existsSync,
+} = {}) {
+  if (platform === 'linux') {
+    if (wayland) {
+      if (gnomeSupported && gnomeScreencastCandidate({
+        platform,
+        wayland,
+        desktop,
+        gnomeSessionMode,
+        sessionBus,
+        commandExistsFn,
+      })) return 'gnome-shell';
+      if (commandExistsFn('wf-recorder') && commandExistsFn('timeout')) return 'wf-recorder';
+      return null;
+    }
+    return Boolean(String(display).trim()) && commandExistsFn('ffmpeg') ? 'ffmpeg-x11' : null;
+  }
+  if (platform === 'darwin') {
+    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-avfoundation' : null;
+  }
+  if (platform === 'win32') {
+    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-gdigrab' : null;
+  }
+  return null;
+}
+
+export function recordScreenAvailable({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  display = process.env.DISPLAY || '',
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  gnomeSupported = false,
+  commandExistsFn = commandExists,
+  existsSyncFn = existsSync,
+} = {}) {
+  return Boolean(recordScreenBackend({
+    platform,
+    wayland,
+    display,
+    desktop,
+    gnomeSessionMode,
+    sessionBus,
+    gnomeSupported,
+    commandExistsFn,
+    existsSyncFn,
+  }));
+}
+
+const GNOME_SCREENCAST_SUPPORT_HELPER = `const {Gio, GLib} = imports.gi;
+const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
+const value = bus.call_sync(
+  'org.gnome.Shell.Screencast',
+  '/org/gnome/Shell/Screencast',
+  'org.freedesktop.DBus.Properties',
+  'Get',
+  new GLib.Variant('(ss)', ['org.gnome.Shell.Screencast', 'ScreencastSupported']),
+  new GLib.VariantType('(v)'),
+  Gio.DBusCallFlags.NONE,
+  3000,
+  null
+).deepUnpack();
+print(value[0].deepUnpack() ? 'true' : 'false');
+`;
+
+let gnomeScreencastSupportCache = { key:'', value:false, expiresAt:0 };
+let gnomeScreencastSupportProbe = { key:'', promise:null };
+
+export async function gnomeScreencastSupported({
+  platform = process.platform,
+  wayland = platform === 'linux' ? isWaylandSession() : false,
+  desktop = process.env.XDG_CURRENT_DESKTOP || '',
+  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
+  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
+  commandExistsFn = commandExists,
+  runFileFn = runFile,
+  cacheMs = 15_000,
+  nowFn = Date.now,
+} = {}) {
+  if (!gnomeScreencastCandidate({
+    platform,
+    wayland,
+    desktop,
+    gnomeSessionMode,
+    sessionBus,
+    commandExistsFn,
+  })) return false;
+
+  const key = [platform, wayland ? 'wayland' : '', desktop, gnomeSessionMode, sessionBus].join('|');
+  const now = nowFn();
+  if (cacheMs > 0 && gnomeScreencastSupportCache.key === key && gnomeScreencastSupportCache.expiresAt > now) {
+    return gnomeScreencastSupportCache.value;
+  }
+  if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise) {
+    return gnomeScreencastSupportProbe.promise;
+  }
+
+  const promise = (async () => {
+    let value = false;
+    try {
+      const result = await runFileFn('gjs', ['-c', GNOME_SCREENCAST_SUPPORT_HELPER], {
+        label:'GNOME Shell screencast capability probe',
+        timeout:5000,
+        maxBuffer:64 * 1024,
+        allowFailure:true,
+      });
+      value = Number(result.code) === 0 && String(result.stdout || '').trim() === 'true';
+    } catch {
+      value = false;
+    }
+    gnomeScreencastSupportCache = {
+      key,
+      value,
+      expiresAt:nowFn() + Math.max(0, cacheMs),
+    };
+    return value;
+  })();
+
+  gnomeScreencastSupportProbe = { key, promise };
+  try {
+    return await promise;
+  } finally {
+    if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise === promise) {
+      gnomeScreencastSupportProbe = { key:'', promise:null };
+    }
+  }
+}
+
+const GNOME_SCREENCAST_HELPER = `const {Gio, GLib} = imports.gi;
+const [destination, secondsRaw, fpsRaw] = ARGV;
+const seconds = Number(secondsRaw);
+const fps = Number(fpsRaw);
+const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
+const destinationName = 'org.gnome.Shell.Screencast';
+const objectPath = '/org/gnome/Shell/Screencast';
+const interfaceName = 'org.gnome.Shell.Screencast';
+const property = bus.call_sync(
+  destinationName,
+  objectPath,
+  'org.freedesktop.DBus.Properties',
+  'Get',
+  new GLib.Variant('(ss)', [interfaceName, 'ScreencastSupported']),
+  new GLib.VariantType('(v)'),
+  Gio.DBusCallFlags.NONE,
+  5000,
+  null
+).deepUnpack();
+if (!property[0].deepUnpack()) throw new Error('GNOME Shell reports ScreencastSupported=false');
+const options = {
+  'draw-cursor': new GLib.Variant('b', true),
+  'framerate': new GLib.Variant('i', fps),
+};
+const started = bus.call_sync(
+  destinationName,
+  objectPath,
+  interfaceName,
+  'Screencast',
+  new GLib.Variant('(sa{sv})', [destination, options]),
+  new GLib.VariantType('(bs)'),
+  Gio.DBusCallFlags.NONE,
+  10000,
+  null
+).deepUnpack();
+if (!started[0]) throw new Error('GNOME Shell refused to start screencast');
+GLib.usleep(Math.round(seconds * 1000000));
+const stopped = bus.call_sync(
+  destinationName,
+  objectPath,
+  interfaceName,
+  'StopScreencast',
+  null,
+  new GLib.VariantType('(b)'),
+  Gio.DBusCallFlags.NONE,
+  10000,
+  null
+).deepUnpack();
+if (!stopped[0]) throw new Error('GNOME Shell did not stop screencast cleanly');
+print(JSON.stringify({ destination:started[1], stopped:stopped[0] }));
+`;
+
+async function recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps }) {
+  const helper = path.join(stagingDirectory, 'gnome-screencast.js');
+  await writeFile(helper, GNOME_SCREENCAST_HELPER, { mode:0o600 });
+  await runFile('gjs', [helper, staged, String(seconds), String(fps)], {
+    label:'GNOME Shell screen recording',
+    timeout:(seconds + 20) * 1000,
+    maxBuffer:2 * 1024 * 1024,
+  });
+}
+
+export function validateRecordingDestinationFormat(destination, format) {
+  if (!destination) return;
+  const extension = path.extname(destination).slice(1).toLowerCase();
+  if (extension && extension !== format) {
+    throw new Error(`Screen recording backend produces .${format}; destination must use .${format} or omit the extension`);
+  }
+}
+
+async function openRecordingParent(destination) {
+  return openDirectoryPath(path.dirname(destination));
+}
+
+async function copyRecordingFile(source, destination) {
+  let input;
+  let output;
+  let parent;
+  let temporary;
+  try {
+    input = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+    const sourceInfo = await input.stat();
+    if (!sourceInfo.isFile()) throw new Error('Screen recording staging path is not a regular file');
+    parent = await openRecordingParent(destination);
+    const anchoredDestination = path.join(parent.anchor, path.basename(destination));
+    const existing = await lstat(anchoredDestination).catch(() => null);
+    if (existing?.isSymbolicLink()) throw new Error('Screen recording destination cannot be a symbolic link');
+    if (existing && !existing.isFile()) throw new Error('Screen recording destination is not a regular file');
+    temporary = path.join(parent.anchor, `.${path.basename(destination)}.${randomUUID()}.tmp`);
+    output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
+    const buffer = Buffer.allocUnsafe(1024 * 1024);
+    let offset = 0;
+    for (;;) {
+      const { bytesRead } = await input.read(buffer, 0, buffer.length, offset);
+      if (!bytesRead) break;
+      let written = 0;
+      while (written < bytesRead) {
+        const result = await output.write(buffer, written, bytesRead - written, offset + written);
+        if (!result.bytesWritten) throw new Error('Could not finish writing the screen recording');
+        written += result.bytesWritten;
+      }
+      offset += bytesRead;
+    }
+    await output.sync();
+    await output.close();
+    output = null;
+    await rename(temporary, anchoredDestination);
+    temporary = null;
+  } finally {
+    if (output) await output.close().catch(() => {});
+    if (temporary) await unlink(temporary).catch(() => {});
+    if (input) await input.close().catch(() => {});
+    if (parent) await parent.close().catch(() => {});
+  }
+}
+
+export async function recordScreen(args) {
+  const seconds = clamp(args.duration_seconds, 5, 1, 120);
+  const fps = clamp(args.fps, 15, 1, 60);
+  const wayland = process.platform === 'linux' && isWaylandSession();
+  const gnomeSupported = wayland ? await gnomeScreencastSupported() : false;
+  const backend = recordScreenBackend({ platform:process.platform, wayland, gnomeSupported });
+  if (!backend) {
+    if (wayland) unavailable('Screen recording', 'GNOME Shell Screencast or wf-recorder with timeout is required on Wayland');
+    if (process.platform === 'linux' && !String(process.env.DISPLAY || '').trim()) unavailable('Screen recording', 'an active X11 DISPLAY is required on Linux X11');
+    if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
+    if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
+    unavailable('Screen recording', 'ffmpeg is required on X11');
+  }
+
+  const format = backend === 'gnome-shell' ? 'webm' : 'mp4';
+  const requestedDestination = args.destination ? await resolveSafePath(args.destination, 'destination') : '';
+  if (requestedDestination) {
+    validateRecordingDestinationFormat(requestedDestination, format);
+    const existing = await lstat(requestedDestination).catch(() => null);
+    if (existing?.isSymbolicLink()) throw new Error('Screen recording destination cannot be a symbolic link');
+    if (existing && !existing.isFile()) throw new Error('Screen recording destination is not a regular file');
+  }
+
+  const stagingDirectory = await mkdtemp(path.join(os.tmpdir(), 'remcp-screen-'));
+  const staged = path.join(stagingDirectory, `capture-${randomUUID()}.${format}`);
+  let keepStaging = false;
+  try {
+    if (backend === 'gnome-shell') {
+      await recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps });
+    } else if (backend === 'wf-recorder') {
+      const result = await runFile('timeout', ['--signal=INT', `${seconds}s`, 'wf-recorder', '-f',staged,'-r',String(fps),'-c','libx264'], { label:'screen recording', timeout:(seconds+10)*1000, allowFailure:true });
+      if (![0, 124, 130].includes(Number(result.code))) throw new Error(result.stderr.trim() || `wf-recorder exited ${result.code}`);
+    } else {
+      const ffmpeg = resolveRecordScreenFfmpeg();
+      if (!ffmpeg) {
+        if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
+        if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
+        unavailable('Screen recording', 'ffmpeg is required on X11');
+      }
+      let argv;
+      if (process.platform === 'win32') argv=['-y','-f','gdigrab','-framerate',String(fps),'-i','desktop','-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      else if (process.platform === 'darwin') {
+        const input = await avfoundationScreenInput(ffmpeg);
+        argv=['-y','-f','avfoundation','-framerate',String(fps),'-i',`${input}:none`,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      } else argv=['-y','-f','x11grab','-framerate',String(fps),'-i',process.env.DISPLAY,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
+      await runFile(ffmpeg, argv, { label:'screen recording', timeout:(seconds+20)*1000, maxBuffer:8*1024*1024 });
+    }
+    if (requestedDestination) {
+      await copyRecordingFile(staged, requestedDestination);
+      await rm(stagingDirectory, { recursive:true, force:true });
+    }
+    const output = requestedDestination || staged;
+    const info = await stat(output);
+    keepStaging = !requestedDestination;
+    return jsonResult({ path:output, bytes:info.size, duration_seconds:seconds, format });
+  } finally {
+    if (!keepStaging) await rm(stagingDirectory, { recursive:true, force:true }).catch(() => {});
+  }
+}

package/src/extended/diagnostics.mjs

@@ -1,35 +1,14 @@
-import dns from 'node:dns';
-import net from 'node:net';
-import os from 'node:os';
-import path from 'node:path';
 import process from 'node:process';
-import { randomUUID } from 'node:crypto';
-import { constants, existsSync } from 'node:fs';
-import { lstat, mkdtemp, open, rename, rm, stat, unlink, writeFile } from 'node:fs/promises';
 import { assertAllowedCommand } from '../policy.mjs';
-import { isWaylandSession } from '../screenshot-portal.mjs';
-import { openDirectoryPath } from '../tools/files.mjs';
-import { resolveSafePath, text, throwIfCancelled, ToolError } from '../util.mjs';
-import {
-  clamp,
-  commandExists,
-  escapePowerShellSingle,
-  jsonResult,
-  optionalString,
-  requireEnum,
-  runFile,
-  runFileHeadLines,
-  runOsa,
-  runPowerShell,
-  safeEnvironment,
-  spawnDetached,
-  unavailable,
-} from './common.mjs';
-
+import { text, throwIfCancelled, ToolError } from '../util.mjs';
+import { commandExists, requireEnum, runFile, runOsa, runPowerShell, spawnDetached, unavailable } from './common.mjs';
 import { serviceTool, eventLog, networkTool, installedApps } from './diagnostics-platform.mjs';
 import { environmentTool, audioTool } from './diagnostics-audio.mjs';
+import { recordScreen } from './diagnostics-recording.mjs';
+
 export * from './diagnostics-platform.mjs';
 export * from './diagnostics-audio.mjs';
+export * from './diagnostics-recording.mjs';
 
 export const POWER_ACTION_MAX_DELAY_SECONDS = 90;
 
@@ -90,370 +69,6 @@ export async function powerAction(args, extra = {}) {
   return text(`${policy.note ? `${policy.note}\n` : ''}Power action ${action} requested.`);
 }
 
-export function resolveRecordScreenFfmpeg({
-  platform = process.platform,
-  commandExistsFn = commandExists,
-  existsSyncFn = existsSync,
-} = {}) {
-  if (commandExistsFn('ffmpeg')) return 'ffmpeg';
-  if (platform === 'darwin') {
-    for (const candidate of ['/opt/homebrew/bin/ffmpeg', '/usr/local/bin/ffmpeg']) {
-      if (existsSyncFn(candidate)) return candidate;
-    }
-  }
-  return null;
-}
-
-export function parseAvfoundationScreenInput(output) {
-  for (const line of String(output || '').split(/\r?\n/)) {
-    const match = line.match(/\[(\d+)\]\s+Capture screen(?:\s+\d+)?\s*$/i);
-    if (match) return match[1];
-  }
-  return null;
-}
-
-async function avfoundationScreenInput(ffmpeg) {
-  const result = await runFile(ffmpeg, [
-    '-hide_banner',
-    '-f','avfoundation',
-    '-list_devices','true',
-    '-i','',
-  ], { label:'AVFoundation device inventory', timeout:10_000, allowFailure:true });
-  const index = parseAvfoundationScreenInput(`${result.stderr || ''}\n${result.stdout || ''}`);
-  if (!index) unavailable('Screen recording', 'ffmpeg could not find an AVFoundation Capture screen input');
-  return index;
-}
-
-export function gnomeScreencastCandidate({
-  platform = process.platform,
-  wayland = platform === 'linux' ? isWaylandSession() : false,
-  desktop = process.env.XDG_CURRENT_DESKTOP || '',
-  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
-  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
-  commandExistsFn = commandExists,
-} = {}) {
-  const gnomeSession = /gnome/i.test(String(desktop)) || Boolean(String(gnomeSessionMode).trim());
-  return platform === 'linux'
-    && wayland
-    && gnomeSession
-    && Boolean(String(sessionBus).trim())
-    && commandExistsFn('gjs');
-}
-
-export function recordScreenBackend({
-  platform = process.platform,
-  wayland = platform === 'linux' ? isWaylandSession() : false,
-  display = process.env.DISPLAY || '',
-  desktop = process.env.XDG_CURRENT_DESKTOP || '',
-  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
-  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
-  gnomeSupported = false,
-  commandExistsFn = commandExists,
-  existsSyncFn = existsSync,
-} = {}) {
-  if (platform === 'linux') {
-    if (wayland) {
-      if (gnomeSupported && gnomeScreencastCandidate({
-        platform,
-        wayland,
-        desktop,
-        gnomeSessionMode,
-        sessionBus,
-        commandExistsFn,
-      })) return 'gnome-shell';
-      if (commandExistsFn('wf-recorder') && commandExistsFn('timeout')) return 'wf-recorder';
-      return null;
-    }
-    return Boolean(String(display).trim()) && commandExistsFn('ffmpeg') ? 'ffmpeg-x11' : null;
-  }
-  if (platform === 'darwin') {
-    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-avfoundation' : null;
-  }
-  if (platform === 'win32') {
-    return resolveRecordScreenFfmpeg({ platform, commandExistsFn, existsSyncFn }) ? 'ffmpeg-gdigrab' : null;
-  }
-  return null;
-}
-
-export function recordScreenAvailable({
-  platform = process.platform,
-  wayland = platform === 'linux' ? isWaylandSession() : false,
-  display = process.env.DISPLAY || '',
-  desktop = process.env.XDG_CURRENT_DESKTOP || '',
-  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
-  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
-  gnomeSupported = false,
-  commandExistsFn = commandExists,
-  existsSyncFn = existsSync,
-} = {}) {
-  return Boolean(recordScreenBackend({
-    platform,
-    wayland,
-    display,
-    desktop,
-    gnomeSessionMode,
-    sessionBus,
-    gnomeSupported,
-    commandExistsFn,
-    existsSyncFn,
-  }));
-}
-
-const GNOME_SCREENCAST_SUPPORT_HELPER = `const {Gio, GLib} = imports.gi;
-const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
-const value = bus.call_sync(
-  'org.gnome.Shell.Screencast',
-  '/org/gnome/Shell/Screencast',
-  'org.freedesktop.DBus.Properties',
-  'Get',
-  new GLib.Variant('(ss)', ['org.gnome.Shell.Screencast', 'ScreencastSupported']),
-  new GLib.VariantType('(v)'),
-  Gio.DBusCallFlags.NONE,
-  3000,
-  null
-).deepUnpack();
-print(value[0].deepUnpack() ? 'true' : 'false');
-`;
-
-let gnomeScreencastSupportCache = { key:'', value:false, expiresAt:0 };
-let gnomeScreencastSupportProbe = { key:'', promise:null };
-
-export async function gnomeScreencastSupported({
-  platform = process.platform,
-  wayland = platform === 'linux' ? isWaylandSession() : false,
-  desktop = process.env.XDG_CURRENT_DESKTOP || '',
-  gnomeSessionMode = process.env.GNOME_SHELL_SESSION_MODE || '',
-  sessionBus = process.env.DBUS_SESSION_BUS_ADDRESS || '',
-  commandExistsFn = commandExists,
-  runFileFn = runFile,
-  cacheMs = 15_000,
-  nowFn = Date.now,
-} = {}) {
-  if (!gnomeScreencastCandidate({
-    platform,
-    wayland,
-    desktop,
-    gnomeSessionMode,
-    sessionBus,
-    commandExistsFn,
-  })) return false;
-
-  const key = [platform, wayland ? 'wayland' : '', desktop, gnomeSessionMode, sessionBus].join('|');
-  const now = nowFn();
-  if (cacheMs > 0 && gnomeScreencastSupportCache.key === key && gnomeScreencastSupportCache.expiresAt > now) {
-    return gnomeScreencastSupportCache.value;
-  }
-  if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise) {
-    return gnomeScreencastSupportProbe.promise;
-  }
-
-  const promise = (async () => {
-    let value = false;
-    try {
-      const result = await runFileFn('gjs', ['-c', GNOME_SCREENCAST_SUPPORT_HELPER], {
-        label:'GNOME Shell screencast capability probe',
-        timeout:5000,
-        maxBuffer:64 * 1024,
-        allowFailure:true,
-      });
-      value = Number(result.code) === 0 && String(result.stdout || '').trim() === 'true';
-    } catch {
-      value = false;
-    }
-    gnomeScreencastSupportCache = {
-      key,
-      value,
-      expiresAt:nowFn() + Math.max(0, cacheMs),
-    };
-    return value;
-  })();
-
-  gnomeScreencastSupportProbe = { key, promise };
-  try {
-    return await promise;
-  } finally {
-    if (gnomeScreencastSupportProbe.key === key && gnomeScreencastSupportProbe.promise === promise) {
-      gnomeScreencastSupportProbe = { key:'', promise:null };
-    }
-  }
-}
-
-const GNOME_SCREENCAST_HELPER = `const {Gio, GLib} = imports.gi;
-const [destination, secondsRaw, fpsRaw] = ARGV;
-const seconds = Number(secondsRaw);
-const fps = Number(fpsRaw);
-const bus = Gio.bus_get_sync(Gio.BusType.SESSION, null);
-const destinationName = 'org.gnome.Shell.Screencast';
-const objectPath = '/org/gnome/Shell/Screencast';
-const interfaceName = 'org.gnome.Shell.Screencast';
-const property = bus.call_sync(
-  destinationName,
-  objectPath,
-  'org.freedesktop.DBus.Properties',
-  'Get',
-  new GLib.Variant('(ss)', [interfaceName, 'ScreencastSupported']),
-  new GLib.VariantType('(v)'),
-  Gio.DBusCallFlags.NONE,
-  5000,
-  null
-).deepUnpack();
-if (!property[0].deepUnpack()) throw new Error('GNOME Shell reports ScreencastSupported=false');
-const options = {
-  'draw-cursor': new GLib.Variant('b', true),
-  'framerate': new GLib.Variant('i', fps),
-};
-const started = bus.call_sync(
-  destinationName,
-  objectPath,
-  interfaceName,
-  'Screencast',
-  new GLib.Variant('(sa{sv})', [destination, options]),
-  new GLib.VariantType('(bs)'),
-  Gio.DBusCallFlags.NONE,
-  10000,
-  null
-).deepUnpack();
-if (!started[0]) throw new Error('GNOME Shell refused to start screencast');
-GLib.usleep(Math.round(seconds * 1000000));
-const stopped = bus.call_sync(
-  destinationName,
-  objectPath,
-  interfaceName,
-  'StopScreencast',
-  null,
-  new GLib.VariantType('(b)'),
-  Gio.DBusCallFlags.NONE,
-  10000,
-  null
-).deepUnpack();
-if (!stopped[0]) throw new Error('GNOME Shell did not stop screencast cleanly');
-print(JSON.stringify({ destination:started[1], stopped:stopped[0] }));
-`;
-
-async function recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps }) {
-  const helper = path.join(stagingDirectory, 'gnome-screencast.js');
-  await writeFile(helper, GNOME_SCREENCAST_HELPER, { mode:0o600 });
-  await runFile('gjs', [helper, staged, String(seconds), String(fps)], {
-    label:'GNOME Shell screen recording',
-    timeout:(seconds + 20) * 1000,
-    maxBuffer:2 * 1024 * 1024,
-  });
-}
-
-export function validateRecordingDestinationFormat(destination, format) {
-  if (!destination) return;
-  const extension = path.extname(destination).slice(1).toLowerCase();
-  if (extension && extension !== format) {
-    throw new Error(`Screen recording backend produces .${format}; destination must use .${format} or omit the extension`);
-  }
-}
-
-async function openRecordingParent(destination) {
-  return openDirectoryPath(path.dirname(destination));
-}
-
-async function copyRecordingFile(source, destination) {
-  let input;
-  let output;
-  let parent;
-  let temporary;
-  try {
-    input = await open(source, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
-    const sourceInfo = await input.stat();
-    if (!sourceInfo.isFile()) throw new Error('Screen recording staging path is not a regular file');
-    parent = await openRecordingParent(destination);
-    const anchoredDestination = path.join(parent.anchor, path.basename(destination));
-    const existing = await lstat(anchoredDestination).catch(() => null);
-    if (existing?.isSymbolicLink()) throw new Error('Screen recording destination cannot be a symbolic link');
-    if (existing && !existing.isFile()) throw new Error('Screen recording destination is not a regular file');
-    temporary = path.join(parent.anchor, `.${path.basename(destination)}.${randomUUID()}.tmp`);
-    output = await open(temporary, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL | (constants.O_NOFOLLOW || 0), 0o600);
-    const buffer = Buffer.allocUnsafe(1024 * 1024);
-    let offset = 0;
-    for (;;) {
-      const { bytesRead } = await input.read(buffer, 0, buffer.length, offset);
-      if (!bytesRead) break;
-      let written = 0;
-      while (written < bytesRead) {
-        const result = await output.write(buffer, written, bytesRead - written, offset + written);
-        if (!result.bytesWritten) throw new Error('Could not finish writing the screen recording');
-        written += result.bytesWritten;
-      }
-      offset += bytesRead;
-    }
-    await output.sync();
-    await output.close();
-    output = null;
-    await rename(temporary, anchoredDestination);
-    temporary = null;
-  } finally {
-    if (output) await output.close().catch(() => {});
-    if (temporary) await unlink(temporary).catch(() => {});
-    if (input) await input.close().catch(() => {});
-    if (parent) await parent.close().catch(() => {});
-  }
-}
-
-export async function recordScreen(args) {
-  const seconds = clamp(args.duration_seconds, 5, 1, 120);
-  const fps = clamp(args.fps, 15, 1, 60);
-  const wayland = process.platform === 'linux' && isWaylandSession();
-  const gnomeSupported = wayland ? await gnomeScreencastSupported() : false;
-  const backend = recordScreenBackend({ platform:process.platform, wayland, gnomeSupported });
-  if (!backend) {
-    if (wayland) unavailable('Screen recording', 'GNOME Shell Screencast or wf-recorder with timeout is required on Wayland');
-    if (process.platform === 'linux' && !String(process.env.DISPLAY || '').trim()) unavailable('Screen recording', 'an active X11 DISPLAY is required on Linux X11');
-    if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
-    if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
-    unavailable('Screen recording', 'ffmpeg is required on X11');
-  }
-
-  const format = backend === 'gnome-shell' ? 'webm' : 'mp4';
-  const requestedDestination = args.destination ? await resolveSafePath(args.destination, 'destination') : '';
-  if (requestedDestination) {
-    validateRecordingDestinationFormat(requestedDestination, format);
-    const existing = await lstat(requestedDestination).catch(() => null);
-    if (existing?.isSymbolicLink()) throw new Error('Screen recording destination cannot be a symbolic link');
-    if (existing && !existing.isFile()) throw new Error('Screen recording destination is not a regular file');
-  }
-
-  const stagingDirectory = await mkdtemp(path.join(os.tmpdir(), 'remcp-screen-'));
-  const staged = path.join(stagingDirectory, `capture-${randomUUID()}.${format}`);
-  let keepStaging = false;
-  try {
-    if (backend === 'gnome-shell') {
-      await recordGnomeShellScreen({ staged, stagingDirectory, seconds, fps });
-    } else if (backend === 'wf-recorder') {
-      const result = await runFile('timeout', ['--signal=INT', `${seconds}s`, 'wf-recorder', '-f',staged,'-r',String(fps),'-c','libx264'], { label:'screen recording', timeout:(seconds+10)*1000, allowFailure:true });
-      if (![0, 124, 130].includes(Number(result.code))) throw new Error(result.stderr.trim() || `wf-recorder exited ${result.code}`);
-    } else {
-      const ffmpeg = resolveRecordScreenFfmpeg();
-      if (!ffmpeg) {
-        if (process.platform === 'darwin') unavailable('Screen recording', 'ffmpeg is required on macOS');
-        if (process.platform === 'win32') unavailable('Screen recording', 'ffmpeg is required on Windows');
-        unavailable('Screen recording', 'ffmpeg is required on X11');
-      }
-      let argv;
-      if (process.platform === 'win32') argv=['-y','-f','gdigrab','-framerate',String(fps),'-i','desktop','-t',String(seconds),'-pix_fmt','yuv420p',staged];
-      else if (process.platform === 'darwin') {
-        const input = await avfoundationScreenInput(ffmpeg);
-        argv=['-y','-f','avfoundation','-framerate',String(fps),'-i',`${input}:none`,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
-      } else argv=['-y','-f','x11grab','-framerate',String(fps),'-i',process.env.DISPLAY,'-t',String(seconds),'-pix_fmt','yuv420p',staged];
-      await runFile(ffmpeg, argv, { label:'screen recording', timeout:(seconds+20)*1000, maxBuffer:8*1024*1024 });
-    }
-    if (requestedDestination) {
-      await copyRecordingFile(staged, requestedDestination);
-      await rm(stagingDirectory, { recursive:true, force:true });
-    }
-    const output = requestedDestination || staged;
-    const info = await stat(output);
-    keepStaging = !requestedDestination;
-    return jsonResult({ path:output, bytes:info.size, duration_seconds:seconds, format });
-  } finally {
-    if (!keepStaging) await rm(stagingDirectory, { recursive:true, force:true }).catch(() => {});
-  }
-}
-
 export const diagnosticHandlers = {
   service:serviceTool,
   event_log:eventLog,