livedesk 0.1.589 → 0.1.591

package/client/bin/livedesk-client-node.js

@@ -7,7 +7,8 @@ import crypto from 'crypto';
 import { existsSync, promises as fs, statfsSync } from 'fs';
 import { spawn } from 'child_process';
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath } from 'node:url';
+import { resolveAgentShellCommand } from '../src/runtime/agent-shell.js';
 
 const require = createRequire(import.meta.url);
 const CLIENT_UPDATE_BOOTSTRAP_PATH = fileURLToPath(
@@ -1142,9 +1143,10 @@ async function resolveAgentPath(options, value, permissionMode, rejectSensitive
     return resolved;
 }
 
-function runNodeAgentProcess(executable, args, timeoutMs = 15000, cwd = undefined) {
-    return new Promise((resolve, reject) => {
-        const child = spawn(executable, args, { cwd, windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
+function runNodeAgentProcess(executable, args, timeoutMs = 15000, cwd = undefined, maxTimeoutMs = 30000) {
+    return new Promise((resolve, reject) => {
+        const startedAt = Date.now();
+        const child = spawn(executable, args, { cwd, windowsHide: true, shell: false, stdio: ['ignore', 'pipe', 'pipe'] });
         let output = '';
         let timedOut = false;
         const append = chunk => { output = `${output}${String(chunk || '')}`.replace(/[\0\r]/g, ' ').slice(0, MAX_AGENT_OUTPUT_CHARS); };
@@ -1154,11 +1156,55 @@ function runNodeAgentProcess(executable, args, timeoutMs = 15000, cwd = undefine
             timedOut = true;
             child.kill('SIGTERM');
             setTimeout(() => child.kill('SIGKILL'), 1000).unref?.();
-        }, Math.max(1000, Math.min(30000, Number(timeoutMs) || 15000)));
-        child.once('error', error => { clearTimeout(timer); reject(error); });
-        child.once('close', code => { clearTimeout(timer); resolve({ output: redactAgentOutput(`${output}${timedOut ? '\n[timeout]' : ''}`.trim()), exitCode: timedOut ? -1 : code ?? -1, timedOut }); });
-    });
-}
+        }, Math.max(1000, Math.min(maxTimeoutMs, Number(timeoutMs) || 15000)));
+        child.once('error', error => { clearTimeout(timer); reject(error); });
+        child.once('close', code => { clearTimeout(timer); resolve({ output: redactAgentOutput(`${output}${timedOut ? '\n[timeout]' : ''}`.trim()), exitCode: timedOut ? -1 : code ?? -1, timedOut, durationMs: Date.now() - startedAt }); });
+    });
+}
+
+async function searchNodeAgentFiles(options, args, permissionMode) {
+    const root = await resolveAgentPath(options, args.path, permissionMode);
+    const query = String(args.query || '').trim().toLowerCase();
+    if (!query || query.length > 160 || /[\0\r\n]/.test(query)) throw new Error('search query is invalid');
+    const maxResults = Math.max(1, Math.min(200, Number(args.maxResults) || 100));
+    const maxDepth = Math.max(0, Math.min(8, Number(args.maxDepth) || 4));
+    const maxScannedEntries = Math.max(maxResults, Math.min(5000, Number(args.maxScannedEntries) || 2000));
+    const queue = [{ directory: root, depth: 0 }];
+    const matches = [];
+    let scannedEntries = 0;
+    while (queue.length > 0 && matches.length < maxResults && scannedEntries < maxScannedEntries) {
+        const current = queue.shift();
+        let entries;
+        try {
+            entries = await fs.readdir(current.directory, { withFileTypes: true });
+        } catch {
+            continue;
+        }
+        for (const entry of entries) {
+            if (matches.length >= maxResults || scannedEntries >= maxScannedEntries) break;
+            scannedEntries += 1;
+            const entryPath = path.join(current.directory, entry.name);
+            if (isSensitiveAgentPath(entryPath)) continue;
+            const isDirectory = entry.isDirectory();
+            if (entry.name.toLowerCase().includes(query)) {
+                matches.push({ name: entry.name, path: entryPath, type: isDirectory ? 'directory' : 'file' });
+            }
+            if (isDirectory && current.depth < maxDepth && !entry.isSymbolicLink()) {
+                queue.push({ directory: entryPath, depth: current.depth + 1 });
+            }
+        }
+    }
+    return {
+        summary: `Found ${matches.length} matching path${matches.length === 1 ? '' : 's'}.`,
+        data: {
+            path: root,
+            query,
+            matches,
+            scannedEntries,
+            truncated: matches.length >= maxResults || scannedEntries >= maxScannedEntries
+        }
+    };
+}
 
 function redactAgentOutput(value) {
     let output = String(value || '').replace(/[\0\r]/g, ' ');
@@ -1324,7 +1370,7 @@ async function executeNodeAgentOperation(options, operation, payload = {}) {
         else await fs.unlink(filePath);
         return { summary: `Deleted ${path.basename(filePath)}.`, data: { path: filePath, recursive: args.recursive === true } };
     }
-    if (operation === 'file.list') {
+    if (operation === 'file.list') {
         const directory = await resolveAgentPath(options, args.path, permissionMode);
         const entries = await fs.readdir(directory, { withFileTypes: true });
         const maxEntries = Math.max(1, Math.min(500, Number(args.maxEntries) || 200));
@@ -1334,8 +1380,15 @@ async function executeNodeAgentOperation(options, operation, payload = {}) {
             if (isSensitiveAgentPath(entryPath)) continue;
             data.push({ name: entry.name, path: entryPath, type: entry.isDirectory() ? 'directory' : 'file', sizeBytes: entry.isDirectory() ? 0 : (await fs.stat(entryPath)).size });
         }
-        return { summary: `Listed ${data.length} entries.`, data: { path: directory, entries: data, truncated: entries.length > maxEntries } };
-    }
+        return { summary: `Listed ${data.length} entries.`, data: { path: directory, entries: data, truncated: entries.length > maxEntries } };
+    }
+    if (operation === 'file.search') return searchNodeAgentFiles(options, args, permissionMode);
+    if (operation === 'directory.create') {
+        let directory = await resolveAgentPath(options, args.path, permissionMode);
+        await fs.mkdir(directory, { recursive: true });
+        directory = await resolveAgentPath(options, args.path, permissionMode);
+        return { summary: `Created directory ${path.basename(directory)}.`, data: { path: directory, created: true } };
+    }
     if (operation === 'application.launch') {
         const executable = String(args.executable || '').trim();
         if (!executable || executable.length > 400 || /[\0\r\n]/.test(executable)) throw new Error('executable is invalid');
@@ -1389,12 +1442,13 @@ async function executeNodeAgentOperation(options, operation, payload = {}) {
         if (!ok) throw new Error(`Service ${action} failed for ${service}.`);
         return { summary: `Service ${action} completed for ${service}.`, data: { service, action, results } };
     }
-    if (operation === 'command.run') {
-        const command = String(args.command || '');
-        const executable = process.platform === 'win32' ? 'cmd.exe' : '/bin/sh';
-        const commandArgs = process.platform === 'win32' ? ['/d', '/s', '/c', command] : ['-lc', command];
-        const result = await runNodeAgentProcess(executable, commandArgs, args.timeoutMs, args.workingDirectory ? await resolveAgentPath(options, args.workingDirectory, permissionMode, false) : undefined);
-        return { summary: result.timedOut ? 'Command timed out.' : `Command exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output) } };
+    if (operation === 'command.run') {
+        const command = String(args.command || '');
+        if (!command || command.length > 16000 || /\0/.test(command)) throw new Error('command is invalid');
+        const shellCommand = resolveAgentShellCommand({ shell: args.shell, command });
+        const workingDirectory = args.workingDirectory ? await resolveAgentPath(options, args.workingDirectory, permissionMode, false) : undefined;
+        const result = await runNodeAgentProcess(shellCommand.executable, shellCommand.args, args.timeoutMs, workingDirectory, 300000);
+        return { summary: result.timedOut ? `${shellCommand.shell} command timed out.` : `${shellCommand.shell} command exited with code ${result.exitCode}.`, data: { ...result, output: redactAgentOutput(result.output), shell: shellCommand.shell, workingDirectory: workingDirectory || process.cwd() } };
     }
     if (operation === 'script.run') {
         const scriptPath = await resolveAgentPath(options, args.path, permissionMode);
@@ -1481,7 +1535,7 @@ function normalizeNodeAgentTaskResult(result) {
     return { ...result, ok, status: ok ? 'completed' : 'failed', error };
 }
 
-const NODE_AGENT_OPERATIONS = new Set(['process.control', 'service.control', 'application.launch', 'application.close', 'file.read', 'file.write', 'file.delete', 'file.list', 'command.run', 'script.run', 'software.install', 'network.status', 'system.power', 'system.configure', 'logs.collect']);
+const NODE_AGENT_OPERATIONS = new Set(['process.control', 'service.control', 'application.launch', 'application.close', 'file.read', 'file.write', 'file.delete', 'file.list', 'file.search', 'directory.create', 'command.run', 'script.run', 'software.install', 'network.status', 'system.power', 'system.configure', 'logs.collect']);
 
 function remotePolicyAllows(options, command) {
     const policy = options.effectivePolicy;
@@ -1723,7 +1777,7 @@ async function handleRemoteCommand(socket, options, message, nextFrameSeq, activ
                     summary: result.summary,
                     error: result.error || undefined,
                     data: result.data,
-                    sideEffects: ['file.read', 'file.list', 'network.status', 'logs.collect'].includes(command) ? 'none' : 'audited',
+                    sideEffects: ['file.read', 'file.list', 'file.search', 'network.status', 'logs.collect'].includes(command) ? 'none' : 'audited',
                     completedAt: new Date().toISOString()
                 }
             });

package/client/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@livedesk/client",
-  "version": "0.1.249",
+  "version": "0.1.251",
   "description": "LiveDesk local remote client",
   "type": "module",
   "bin": {
@@ -42,10 +42,10 @@
     "ws": "^8.18.3"
   },
   "optionalDependencies": {
-    "@livedesk/fast-linux-x64": "0.1.445",
-    "@livedesk/fast-osx-arm64": "0.1.445",
-    "@livedesk/fast-osx-x64": "0.1.445",
-    "@livedesk/fast-win-x64": "0.1.445"
+    "@livedesk/fast-linux-x64": "0.1.447",
+    "@livedesk/fast-osx-arm64": "0.1.447",
+    "@livedesk/fast-osx-x64": "0.1.447",
+    "@livedesk/fast-win-x64": "0.1.447"
   },
   "publishConfig": {
     "access": "public"

package/client/src/runtime/agent-shell.js

@@ -0,0 +1,66 @@
+import { existsSync } from 'node:fs';
+
+export const AGENT_SHELL_NAMES = Object.freeze([
+    'auto',
+    'powershell',
+    'pwsh',
+    'cmd',
+    'sh',
+    'bash',
+    'zsh'
+]);
+
+function unixShellPath(shell, platform, fileExists) {
+    if (shell === 'sh') return '/bin/sh';
+    if (shell === 'bash') return '/bin/bash';
+    if (shell === 'zsh') return '/bin/zsh';
+    if (shell === 'pwsh') return 'pwsh';
+    if (shell === 'powershell' || shell === 'cmd') {
+        throw new Error(`${shell} is not available on ${platform}.`);
+    }
+    if (platform === 'darwin' && fileExists('/bin/zsh')) return '/bin/zsh';
+    if (fileExists('/bin/bash')) return '/bin/bash';
+    return '/bin/sh';
+}
+
+export function resolveAgentShellCommand({
+    platform = process.platform,
+    shell = 'auto',
+    command = '',
+    fileExists = existsSync
+} = {}) {
+    const normalizedShell = String(shell || 'auto').trim().toLowerCase();
+    if (!AGENT_SHELL_NAMES.includes(normalizedShell)) {
+        throw new Error(`Unsupported shell: ${normalizedShell || 'empty'}.`);
+    }
+    if (platform === 'win32') {
+        if (['sh', 'bash', 'zsh'].includes(normalizedShell)) {
+            throw new Error(`${normalizedShell} is not available on Windows.`);
+        }
+        if (normalizedShell === 'cmd') {
+            return {
+                shell: 'cmd',
+                executable: process.env.ComSpec || 'cmd.exe',
+                args: ['/d', '/s', '/c', String(command)]
+            };
+        }
+        const powershellCore = normalizedShell === 'pwsh';
+        return {
+            shell: powershellCore ? 'pwsh' : 'powershell',
+            executable: powershellCore ? 'pwsh.exe' : 'powershell.exe',
+            args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass', '-Command', String(command)]
+        };
+    }
+
+    const executable = unixShellPath(normalizedShell, platform, fileExists);
+    if (executable.startsWith('/') && !fileExists(executable)) {
+        throw new Error(`${normalizedShell} is not installed at ${executable}.`);
+    }
+    return {
+        shell: normalizedShell === 'auto'
+            ? executable.endsWith('/zsh') ? 'zsh' : executable.endsWith('/bash') ? 'bash' : 'sh'
+            : normalizedShell,
+        executable,
+        args: ['-lc', String(command)]
+    };
+}

package/electron/auth-session-owner.mjs

@@ -1,7 +1,16 @@
 export const DESKTOP_AUTH_REFRESH_SKEW_SECONDS = 5 * 60;
 export const DESKTOP_AUTH_RETRY_MS = 15_000;
 export const DESKTOP_AUTH_MINIMUM_TIMER_MS = 30_000;
-export const DESKTOP_AUTH_INVALID_CONFIRMATIONS = 3;
+export const DESKTOP_AUTH_INVALID_CONFIRMATIONS = 3;
+
+const DEFINITIVE_REFRESH_REJECTION_CODES = new Set([
+  'invalid_grant',
+  'refresh_token_already_used',
+  'refresh_token_not_found',
+  'session_expired',
+  'session_not_found',
+  'user_not_found'
+]);
 
 export function desktopSessionNeedsRefresh(
   session,
@@ -35,10 +44,20 @@ export function desktopSessionRefreshDelayMs(
   );
 }
 
-export function isPermanentDesktopAuthRefreshFailure(error) {
-  const status = Number(error?.authStatus || 0);
-  return status === 400 || status === 401 || status === 403;
-}
+export function isPermanentDesktopAuthRefreshFailure(error) {
+  const status = Number(error?.authStatus || 0);
+  if (status !== 400 && status !== 401 && status !== 403) return false;
+
+  // Status alone is not logout authority. A captive portal, provider edge,
+  // corporate proxy, or temporarily inconsistent auth replica can all return
+  // 403 while the saved refresh token remains valid. Supabase provides a
+  // stable refresh/session error code for an actual credential rejection; old
+  // GoTrue releases are covered by the narrow legacy message fallback.
+  const code = String(error?.authCode || '').trim().toLowerCase();
+  if (DEFINITIVE_REFRESH_REJECTION_CODES.has(code)) return true;
+  const message = String(error?.message || '');
+  return /invalid refresh token|refresh token (?:was )?(?:not found|already used)/i.test(message);
+}
 
 export function selectFreshestDesktopSession(currentSession, incomingSession) {
   if (!currentSession) return incomingSession || null;

package/electron/desktop-clipboard-owner.mjs

@@ -0,0 +1,382 @@
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+import {
+  mkdir,
+  mkdtemp,
+  open,
+  readdir,
+  readFile,
+  rm,
+  stat,
+  writeFile
+} from 'node:fs/promises';
+import { basename, join, resolve, sep } from 'node:path';
+
+export const DESKTOP_CLIPBOARD_CHUNK_BYTES = 512 * 1024;
+export const DESKTOP_CLIPBOARD_TEXT_BYTES = 1024 * 1024;
+export const DESKTOP_CLIPBOARD_PNG_BYTES = 24 * 1024 * 1024;
+export const DESKTOP_CLIPBOARD_TOTAL_BYTES = 256 * 1024 * 1024;
+export const DESKTOP_CLIPBOARD_MAX_ITEMS = 24;
+
+const DESKTOP_CLIPBOARD_MAX_BASE64_CHARS = Math.ceil(DESKTOP_CLIPBOARD_CHUNK_BYTES / 3) * 4;
+const CANONICAL_BASE64_PATTERN = /^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/;
+
+const HELPER_TIMEOUT_MS = 30_000;
+const HELPER_OUTPUT_LIMIT = 32 * 1024;
+const SNAPSHOT_TTL_MS = 10 * 60 * 1000;
+
+function safeOperationId(value) {
+  return String(value || '').replace(/[^a-zA-Z0-9_.:-]/g, '-').slice(0, 128);
+}
+
+function safeStorageName(value, index) {
+  const name = String(value || `item-${index}.bin`);
+  if (name !== basename(name) || !/^item-\d+\.bin$/.test(name)) {
+    throw new Error('clipboard-storage-name-invalid');
+  }
+  return name;
+}
+
+function normalizeManifest(value, expectedOperationId = '') {
+  const source = value && typeof value === 'object' ? value : {};
+  const operationId = safeOperationId(source.operationId || expectedOperationId);
+  const contentKind = String(source.contentKind || '').toLowerCase();
+  if (!operationId || !['text', 'image', 'files'].includes(contentKind)) {
+    throw new Error('clipboard-manifest-invalid');
+  }
+  const rawItems = Array.isArray(source.items) ? source.items : [];
+  if (rawItems.length < 1 || rawItems.length > DESKTOP_CLIPBOARD_MAX_ITEMS) {
+    throw new Error('clipboard-item-count-invalid');
+  }
+  const items = rawItems.map((item, index) => {
+    const itemIndex = Number(item?.itemIndex);
+    const kind = String(item?.kind || '').toLowerCase();
+    const size = Number(item?.size);
+    if (!Number.isInteger(itemIndex) || itemIndex !== index
+      || !['text', 'image', 'file'].includes(kind)
+      || !Number.isSafeInteger(size) || size < 0
+      || (kind !== 'file' && size === 0)) {
+      throw new Error('clipboard-item-invalid');
+    }
+    const expectedKind = contentKind === 'files' ? 'file' : contentKind;
+    if (kind !== expectedKind) {
+      throw new Error('clipboard-item-kind-mismatch');
+    }
+    return {
+      itemIndex,
+      kind,
+      name: String(item?.name || '').replace(/[\0\r\n\t]/g, ' ').trim().slice(0, 240),
+      mimeType: String(item?.mimeType || '').slice(0, 160),
+      size,
+      lastModified: Math.max(0, Number(item?.lastModified || 0) || 0),
+      sha256: String(item?.sha256 || '').toLowerCase(),
+      storageName: safeStorageName(item?.storageName, index)
+    };
+  });
+  if (items.some(item => !/^[a-f0-9]{64}$/.test(item.sha256))) {
+    throw new Error('clipboard-item-hash-invalid');
+  }
+  const totalBytes = items.reduce((sum, item) => sum + item.size, 0);
+  if (totalBytes !== Number(source.totalBytes)
+    || totalBytes > DESKTOP_CLIPBOARD_TOTAL_BYTES
+    || (contentKind === 'text' && totalBytes > DESKTOP_CLIPBOARD_TEXT_BYTES)
+    || (contentKind === 'image' && totalBytes > DESKTOP_CLIPBOARD_PNG_BYTES)) {
+    throw new Error('clipboard-size-limit');
+  }
+  return { operationId, contentKind, totalBytes, items };
+}
+
+function appendBounded(previous, chunk) {
+  const next = previous + String(chunk || '');
+  return next.length <= HELPER_OUTPUT_LIMIT ? next : next.slice(-HELPER_OUTPUT_LIMIT);
+}
+
+async function runHelper(helperPath, args, { spawnImpl = spawn, timeoutMs = HELPER_TIMEOUT_MS } = {}) {
+  if (!helperPath) throw new Error('clipboard-helper-unavailable');
+  return await new Promise((resolvePromise, rejectPromise) => {
+    const child = spawnImpl(helperPath, args, {
+      stdio: ['ignore', 'pipe', 'pipe'],
+      windowsHide: true,
+      shell: false
+    });
+    let stdout = '';
+    let stderr = '';
+    let settled = false;
+    let timer = null;
+    const finish = (error, result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      if (error) rejectPromise(error);
+      else resolvePromise(result);
+    };
+    child.stdout?.on('data', chunk => { stdout = appendBounded(stdout, chunk); });
+    child.stderr?.on('data', chunk => { stderr = appendBounded(stderr, chunk); });
+    child.once('error', error => finish(error));
+    child.once('exit', (code, signal) => {
+      if (code === 0) finish(null, { stdout, stderr });
+      else finish(new Error(`clipboard-helper-failed:${code ?? signal ?? 'unknown'}:${stderr.trim()}`));
+    });
+    timer = setTimeout(() => {
+      try { child.kill('SIGKILL'); } catch { /* exact helper already exited */ }
+      finish(new Error('clipboard-helper-timeout'));
+    }, timeoutMs);
+    timer.unref?.();
+  });
+}
+
+function assertOwnedStage(root, stagePath) {
+  const normalizedRoot = resolve(root) + sep;
+  const normalizedStage = resolve(stagePath) + sep;
+  if (!normalizedStage.startsWith(normalizedRoot)) {
+    throw new Error('clipboard-stage-owner-invalid');
+  }
+}
+
+export function createDesktopClipboardOwner({
+  rootDir,
+  helperPath,
+  spawnImpl = spawn,
+  now = () => Date.now()
+}) {
+  if (!rootDir) throw new Error('clipboard-root-required');
+  const readOwners = new Map();
+  const writeOwners = new Map();
+  const retainedFileStages = [];
+  let initializePromise = null;
+
+  const initializeRoot = async () => {
+    await mkdir(rootDir, { recursive: true });
+    const entries = await readdir(rootDir, { withFileTypes: true });
+    const oldWriteStages = [];
+    for (const entry of entries) {
+      if (!entry.isDirectory() || !/^(read|write)-/.test(entry.name)) continue;
+      const stagePath = join(rootDir, entry.name);
+      if (entry.name.startsWith('read-')) {
+        await rm(stagePath, { recursive: true, force: true });
+        continue;
+      }
+      const stageStat = await stat(stagePath);
+      oldWriteStages.push({ stagePath, mtimeMs: stageStat.mtimeMs });
+    }
+    oldWriteStages.sort((left, right) => right.mtimeMs - left.mtimeMs);
+    for (const [index, owner] of oldWriteStages.entries()) {
+      if (index < 2) retainedFileStages.push(owner);
+      else await rm(owner.stagePath, { recursive: true, force: true });
+    }
+  };
+
+  const ensureRoot = () => {
+    if (!initializePromise) initializePromise = initializeRoot();
+    return initializePromise;
+  };
+
+  const createStage = async prefix => {
+    await ensureRoot();
+    return await mkdtemp(join(rootDir, `${prefix}-`));
+  };
+
+  const removeStage = async stagePath => {
+    if (!stagePath) return;
+    assertOwnedStage(rootDir, stagePath);
+    await rm(stagePath, { recursive: true, force: true });
+  };
+
+  const sweepExpired = async () => {
+    const deadline = now() - SNAPSHOT_TTL_MS;
+    for (const owners of [readOwners, writeOwners]) {
+      for (const [operationId, owner] of owners) {
+        if (owner.touchedAt > deadline) continue;
+        owners.delete(operationId);
+        await removeStage(owner.stagePath);
+      }
+    }
+  };
+
+  const readSnapshot = async operationValue => {
+    await sweepExpired();
+    const operationId = safeOperationId(operationValue);
+    if (!operationId) throw new Error('clipboard-operation-id-required');
+    const previous = readOwners.get(operationId);
+    if (previous) {
+      previous.touchedAt = now();
+      return previous.manifest;
+    }
+    const stagePath = await createStage('read');
+    try {
+      await runHelper(helperPath, ['--clipboard-helper', 'read', stagePath, operationId], { spawnImpl });
+      const manifest = normalizeManifest(
+        JSON.parse(await readFile(join(stagePath, 'manifest.json'), 'utf8')),
+        operationId);
+      if (manifest.operationId !== operationId) throw new Error('clipboard-operation-mismatch');
+      for (const item of manifest.items) {
+        const payloadStat = await stat(join(stagePath, item.storageName));
+        if (!payloadStat.isFile() || payloadStat.size !== item.size) {
+          throw new Error('clipboard-helper-payload-invalid');
+        }
+      }
+      readOwners.set(operationId, { operationId, stagePath, manifest, touchedAt: now() });
+      return manifest;
+    } catch (error) {
+      await removeStage(stagePath);
+      throw error;
+    }
+  };
+
+  const readChunk = async ({ operationId: operationValue, itemIndex, offset, maxBytes }) => {
+    const operationId = safeOperationId(operationValue);
+    const owner = readOwners.get(operationId);
+    const index = Number(itemIndex);
+    const start = Number(offset);
+    const requested = Math.min(DESKTOP_CLIPBOARD_CHUNK_BYTES, Math.max(1, Number(maxBytes) || DESKTOP_CLIPBOARD_CHUNK_BYTES));
+    const item = owner?.manifest.items[index];
+    if (!owner || !item || item.itemIndex !== index || !Number.isSafeInteger(start) || start < 0 || start > item.size) {
+      throw new Error('clipboard-read-owner-invalid');
+    }
+    owner.touchedAt = now();
+    const byteLength = Math.min(requested, item.size - start);
+    const handle = await open(join(owner.stagePath, item.storageName), 'r');
+    try {
+      const buffer = Buffer.allocUnsafe(byteLength);
+      const { bytesRead } = await handle.read(buffer, 0, byteLength, start);
+      if (bytesRead !== byteLength) throw new Error('clipboard-read-incomplete');
+      return {
+        operationId,
+        itemIndex: index,
+        offset: start,
+        byteLength,
+        dataBase64: buffer.toString('base64'),
+        final: start + byteLength === item.size
+      };
+    } finally {
+      await handle.close();
+    }
+  };
+
+  const releaseRead = async operationValue => {
+    const operationId = safeOperationId(operationValue);
+    const owner = readOwners.get(operationId);
+    readOwners.delete(operationId);
+    if (owner) await removeStage(owner.stagePath);
+    return { ok: true };
+  };
+
+  const beginWrite = async manifestValue => {
+    await sweepExpired();
+    const manifest = normalizeManifest(manifestValue);
+    const previous = writeOwners.get(manifest.operationId);
+    if (previous) await removeStage(previous.stagePath);
+    const stagePath = await createStage('write');
+    await writeFile(join(stagePath, 'manifest.json'), JSON.stringify(manifest), 'utf8');
+    writeOwners.set(manifest.operationId, {
+      operationId: manifest.operationId,
+      stagePath,
+      manifest,
+      offsets: new Array(manifest.items.length).fill(0),
+      hashers: manifest.items.map(() => createHash('sha256')),
+      hashesVerified: new Array(manifest.items.length).fill(false),
+      touchedAt: now()
+    });
+    return { ok: true, operationId: manifest.operationId };
+  };
+
+  const writeChunk = async ({ operationId: operationValue, itemIndex, offset, dataBase64, final }) => {
+    const operationId = safeOperationId(operationValue);
+    const owner = writeOwners.get(operationId);
+    const index = Number(itemIndex);
+    const start = Number(offset);
+    const item = owner?.manifest.items[index];
+    const encoded = String(dataBase64 || '');
+    if (!owner || !item || item.itemIndex !== index
+      || !Number.isSafeInteger(start) || start !== owner.offsets[index]
+      || encoded.length > DESKTOP_CLIPBOARD_MAX_BASE64_CHARS
+      || !CANONICAL_BASE64_PATTERN.test(encoded)) {
+      throw new Error('clipboard-write-chunk-invalid');
+    }
+    const bytes = Buffer.from(encoded, 'base64');
+    if (bytes.length > DESKTOP_CLIPBOARD_CHUNK_BYTES
+      || start + bytes.length > item.size
+      || (bytes.length === 0 && item.size !== 0)
+      || bytes.toString('base64') !== encoded) {
+      throw new Error('clipboard-write-chunk-invalid');
+    }
+    const completesItem = start + bytes.length === item.size;
+    if ((final === true) !== completesItem) throw new Error('clipboard-write-final-mismatch');
+    owner.touchedAt = now();
+    const path = join(owner.stagePath, item.storageName);
+    const handle = await open(path, start === 0 ? 'w' : 'r+');
+    try {
+      const { bytesWritten } = await handle.write(bytes, 0, bytes.length, start);
+      if (bytesWritten !== bytes.length) throw new Error('clipboard-write-incomplete');
+      if (final === true) await handle.sync();
+    } finally {
+      await handle.close();
+    }
+    owner.offsets[index] += bytes.length;
+    owner.hashers[index].update(bytes);
+    const complete = owner.offsets[index] === item.size;
+    if (complete && !owner.hashesVerified[index]) {
+      const actualHash = owner.hashers[index].digest('hex');
+      if (actualHash !== item.sha256) throw new Error('clipboard-write-hash-mismatch');
+      owner.hashesVerified[index] = true;
+    }
+    return { ok: true, operationId, itemIndex: index, offset: owner.offsets[index], complete };
+  };
+
+  const commitWrite = async operationValue => {
+    const operationId = safeOperationId(operationValue);
+    const owner = writeOwners.get(operationId);
+    if (!owner
+      || owner.offsets.some((offset, index) => offset !== owner.manifest.items[index].size)
+      || owner.hashesVerified.some(verified => !verified)) {
+      throw new Error('clipboard-write-not-complete');
+    }
+    await runHelper(helperPath, ['--clipboard-helper', 'write', owner.stagePath, operationId], { spawnImpl });
+    writeOwners.delete(operationId);
+    if (owner.manifest.contentKind === 'files') {
+      retainedFileStages.push(owner);
+      while (retainedFileStages.length > 2) {
+        const stale = retainedFileStages.shift();
+        if (stale) await removeStage(stale.stagePath);
+      }
+    } else {
+      await removeStage(owner.stagePath);
+    }
+    return { ok: true, operationId, contentKind: owner.manifest.contentKind };
+  };
+
+  const cancelWrite = async operationValue => {
+    const operationId = safeOperationId(operationValue);
+    const owner = writeOwners.get(operationId);
+    writeOwners.delete(operationId);
+    if (owner) await removeStage(owner.stagePath);
+    return { ok: true };
+  };
+
+  const close = async () => {
+    for (const owner of [...readOwners.values(), ...writeOwners.values()]) {
+      await removeStage(owner.stagePath);
+    }
+    readOwners.clear();
+    writeOwners.clear();
+    // File clipboard entries refer to these exact local paths. Preserve the
+    // two bounded committed stages so Explorer/Finder can still paste after
+    // the LiveDesk window is hidden or the app exits.
+  };
+
+  return {
+    readSnapshot,
+    readChunk,
+    releaseRead,
+    beginWrite,
+    writeChunk,
+    commitWrite,
+    cancelWrite,
+    close,
+    getSnapshot: () => ({
+      readOwners: readOwners.size,
+      writeOwners: writeOwners.size,
+      retainedFileStages: retainedFileStages.length
+    })
+  };
+}