claude-remote 0.4.7 → 0.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "claude-remote",
-  "version": "0.4.7",
+  "version": "0.5.0",
   "description": "Remote control bridge for Claude Code REPL - drive from phone/WebUI",
   "main": "server.js",
   "bin": {

package/server.js

@@ -184,22 +184,23 @@ let pendingInitialClearTranscript = null; // { sessionId }
 let tailRemainder = Buffer.alloc(0);
 let tailCatchingUp = false; // true while reading historical transcript content
 const isTTY = process.stdin.isTTY && process.stdout.isTTY;
-const LEGACY_REPLAY_DELAY_MS = 1500;
+const LEGACY_REPLAY_DELAY_MS = 1500;
 const IMAGE_UPLOAD_TTL_MS = 15 * 60 * 1000;
 const LINUX_CLIPBOARD_READY_GRACE_MS = 400;
-const IMAGE_UPLOAD_DIR = path.join(CLAUDE_HOME, 'remote-uploads');
-let turnStateVersion = 0;
+const LINUX_AT_PROMPT_SUBMIT_DELAY_MS = 450;
+const LINUX_AT_IMAGE_CLEANUP_DELAY_MS = 10 * 60 * 1000;
+let turnStateVersion = 0;
 let turnState = {
   phase: 'idle',
   sessionId: null,
   version: 0,
   updatedAt: Date.now(),
 };
-let ttyInputForwarderAttached = false;
-let ttyInputHandler = null;
-let ttyResizeHandler = null;
-let activeLinuxClipboardProc = null;
-let linuxImagePasteInFlight = false;
+let ttyInputForwarderAttached = false;
+let ttyInputHandler = null;
+let ttyResizeHandler = null;
+let activeLinuxClipboardProc = null;
+let linuxImagePasteInFlight = false;
 
 // --- Permission approval state ---
 let approvalSeq = 0;
@@ -222,10 +223,10 @@ function formatTtyInputChunk(chunk) {
   return `len=${buf.length} hex=${buf.toString('hex')} base64=${buf.toString('base64')} utf8=${JSON.stringify(buf.toString('utf8'))}`;
 }
 
-function clearActiveLinuxClipboardProc(reason = '') {
-  if (!activeLinuxClipboardProc) return;
-  const { child, tool } = activeLinuxClipboardProc;
-  activeLinuxClipboardProc = null;
+function clearActiveLinuxClipboardProc(reason = '') {
+  if (!activeLinuxClipboardProc) return;
+  const { child, tool } = activeLinuxClipboardProc;
+  activeLinuxClipboardProc = null;
   try {
     child.kill('SIGTERM');
     log(`Linux clipboard process terminated (${tool}) reason=${reason || 'cleanup'}`);
@@ -683,145 +684,362 @@ function cleanupClientUploads(ws) {
   }
 }
 
-function createTempImageFile(buffer, mediaType, uploadId) {
-  const isLinux = process.platform !== 'win32' && process.platform !== 'darwin';
-  const tmpDir = isLinux
-    ? IMAGE_UPLOAD_DIR
-    : (process.env.CLAUDE_CODE_TMPDIR || os.tmpdir());
-  const type = String(mediaType || 'image/png').toLowerCase();
-  const ext = type.includes('jpeg') || type.includes('jpg') ? '.jpg' : '.png';
-  fs.mkdirSync(tmpDir, { recursive: true });
-  const tmpFile = path.join(tmpDir, `bridge_upload_${uploadId}_${Date.now()}${ext}`);
-  fs.writeFileSync(tmpFile, buffer);
-  return tmpFile;
-}
-
-function isLinuxClipboardToolInstalled(tool) {
-  try {
-    execSync(`command -v ${tool} >/dev/null 2>&1`, {
-      stdio: 'ignore',
-      shell: '/bin/sh',
-      timeout: 2000,
-    });
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function setLinuxImagePasteInFlight(active, reason = '') {
-  linuxImagePasteInFlight = !!active;
-  if (reason) log(`Linux image paste lock=${linuxImagePasteInFlight ? 'on' : 'off'} reason=${reason}`);
-}
-
-function getLinuxClipboardToolCandidates() {
-  if (process.platform === 'win32' || process.platform === 'darwin') return [];
-  const preferred = [];
-  if (process.env.WAYLAND_DISPLAY) preferred.push('wl-copy');
-  if (process.env.DISPLAY) preferred.push('xclip');
-  return preferred;
+function createTempImageFile(buffer, mediaType, uploadId) {
+  const isLinux = process.platform !== 'win32' && process.platform !== 'darwin';
+  const tmpDir = isLinux
+    ? path.join(CWD, 'tmp')
+    : (process.env.CLAUDE_CODE_TMPDIR || os.tmpdir());
+  const type = String(mediaType || 'image/png').toLowerCase();
+  const ext = type.includes('jpeg') || type.includes('jpg') ? '.jpg' : '.png';
+  fs.mkdirSync(tmpDir, { recursive: true });
+  const tmpFile = path.join(tmpDir, `bridge_upload_${uploadId}_${Date.now()}${ext}`);
+  fs.writeFileSync(tmpFile, buffer);
+  return tmpFile;
 }
 
-function assertLinuxClipboardAvailable() {
-  const candidates = getLinuxClipboardToolCandidates();
-  const available = candidates.filter(isLinuxClipboardToolInstalled);
-  if (available.length > 0) return available;
-  if (!process.env.WAYLAND_DISPLAY && !process.env.DISPLAY) {
-    throw new Error('Linux image paste requires an active graphical session (WAYLAND_DISPLAY or DISPLAY).');
-  }
-  throw new Error('Linux image paste requires wl-copy or xclip on the server. Install a matching clipboard tool and try again.');
+function toClaudeAtPath(filePath) {
+  const normalized = path.normalize(String(filePath || ''));
+  const rel = path.relative(CWD, normalized);
+  const inProject = rel && !rel.startsWith('..') && !path.isAbsolute(rel);
+  const target = inProject ? rel : normalized;
+  return target.split(path.sep).join('/');
 }
 
-function spawnLinuxClipboardTool(tool, imageBuffer, type) {
-  return new Promise((resolve, reject) => {
-    const args = tool === 'xclip'
-      ? ['-quiet', '-selection', 'clipboard', '-t', type, '-i']
-      : ['--type', type];
-    const child = spawn(tool, args, {
-      detached: true,
-      stdio: ['pipe', 'ignore', 'pipe'],
-    });
-    let settled = false;
-    let stderr = '';
-    let readyTimer = null;
-
-    const settleFailure = (message) => {
-      if (settled) return;
-      settled = true;
-      if (readyTimer) clearTimeout(readyTimer);
-      if (child.exitCode == null && child.signalCode == null) {
-        try { child.kill('SIGTERM'); } catch {}
-      }
-      reject(new Error(message));
-    };
-
-    const settleSuccess = (trackProcess = true) => {
-      if (settled) return;
-      settled = true;
-      if (readyTimer) clearTimeout(readyTimer);
-      if (trackProcess && child.exitCode == null && child.signalCode == null) {
-        activeLinuxClipboardProc = { child, tool };
-        child.unref();
-      }
-      resolve(tool);
-    };
-
-    child.on('error', (err) => {
-      log(`Linux clipboard process error (${tool}): ${err.message}`);
-      settleFailure(`Linux clipboard tool ${tool} failed: ${err.message}`);
-    });
-    child.stderr.on('data', (chunk) => {
-      stderr += chunk.toString('utf8');
-      if (stderr.length > 2000) stderr = stderr.slice(-2000);
-    });
-    child.on('exit', (code, signal) => {
-      if (activeLinuxClipboardProc && activeLinuxClipboardProc.child === child) activeLinuxClipboardProc = null;
-      const extra = stderr.trim() ? ` stderr=${JSON.stringify(stderr.trim())}` : '';
-      log(`Linux clipboard process exited (${tool}) code=${code ?? 'null'} signal=${signal ?? 'null'}${extra}`);
-      if (!settled) {
-        if (tool === 'xclip' && code === 0 && !signal && !stderr.trim()) {
-          log('Linux clipboard xclip exited cleanly without stderr; treating clipboard arm as successful');
-          settleSuccess(false);
-          return;
-        }
-        const detail = stderr.trim() || `exit code ${code ?? 'null'} signal ${signal ?? 'null'}`;
-        settleFailure(`Linux clipboard tool ${tool} exited before paste: ${detail}`);
-      }
-    });
-    child.stdin.on('error', (err) => {
-      if (err.code === 'EPIPE') {
-        settleFailure(`Linux clipboard tool ${tool} closed its input early`);
-        return;
-      }
-      log(`Linux clipboard stdin error (${tool}): ${err.message}`);
-      settleFailure(`Linux clipboard tool ${tool} stdin failed: ${err.message}`);
-    });
-
-    child.stdin.end(imageBuffer);
-    log(`Linux clipboard process started (${tool}) pid=${child.pid ?? 'null'} type=${type} bytes=${imageBuffer.length}`);
-    readyTimer = setTimeout(() => settleSuccess(), LINUX_CLIPBOARD_READY_GRACE_MS);
-  });
-}
-
-async function startLinuxClipboardImage(tmpFile, mediaType) {
-  const type = String(mediaType || 'image/png').toLowerCase();
-  const imageBuffer = fs.readFileSync(tmpFile);
-  const availableTools = assertLinuxClipboardAvailable();
-  clearActiveLinuxClipboardProc('replace');
-
-  let lastErr = null;
-  for (const tool of availableTools) {
-    try {
-      return await spawnLinuxClipboardTool(tool, imageBuffer, type);
-    } catch (err) {
-      lastErr = err;
-      log(`Linux clipboard arm failed (${tool}): ${err.message}`);
-    }
-  }
-
-  throw lastErr || new Error('Linux clipboard could not be initialized');
+function buildLinuxImagePrompt(text, tmpFile) {
+  const trimmedText = String(text || '').trim();
+  const atPath = `@${toClaudeAtPath(tmpFile)}`;
+  return trimmedText ? `${trimmedText} ${atPath}` : atPath;
 }
 
+function isLinuxClipboardToolInstalled(tool) {
+  try {
+    execSync(`command -v ${tool} >/dev/null 2>&1`, {
+      stdio: 'ignore',
+      shell: '/bin/sh',
+      timeout: 2000,
+    });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function setLinuxImagePasteInFlight(active, reason = '') {
+  linuxImagePasteInFlight = !!active;
+  if (reason) log(`Linux image paste lock=${linuxImagePasteInFlight ? 'on' : 'off'} reason=${reason}`);
+}
+
+function normalizeLinuxEnvVar(value) {
+  const text = String(value || '').trim();
+  return text || null;
+}
+
+function parseLinuxProcStatusUid(statusText) {
+  const match = String(statusText || '').match(/^Uid:\s+(\d+)/m);
+  return match ? Number(match[1]) : null;
+}
+
+function readLinuxProcGuiEnv(pid) {
+  try {
+    const statusPath = `/proc/${pid}/status`;
+    const environPath = `/proc/${pid}/environ`;
+    const statusText = fs.readFileSync(statusPath, 'utf8');
+    const currentUid = typeof process.getuid === 'function' ? process.getuid() : null;
+    if (currentUid != null) {
+      const procUid = parseLinuxProcStatusUid(statusText);
+      if (procUid == null || procUid !== currentUid) return null;
+    }
+
+    const envRaw = fs.readFileSync(environPath, 'utf8');
+    if (!envRaw) return null;
+    let waylandDisplay = null;
+    let display = null;
+    let runtimeDir = null;
+    let xAuthority = null;
+
+    for (const entry of envRaw.split('\0')) {
+      if (!entry) continue;
+      if (entry.startsWith('WAYLAND_DISPLAY=')) waylandDisplay = normalizeLinuxEnvVar(entry.slice('WAYLAND_DISPLAY='.length));
+      else if (entry.startsWith('DISPLAY=')) display = normalizeLinuxEnvVar(entry.slice('DISPLAY='.length));
+      else if (entry.startsWith('XDG_RUNTIME_DIR=')) runtimeDir = normalizeLinuxEnvVar(entry.slice('XDG_RUNTIME_DIR='.length));
+      else if (entry.startsWith('XAUTHORITY=')) xAuthority = normalizeLinuxEnvVar(entry.slice('XAUTHORITY='.length));
+    }
+
+    if (!waylandDisplay && !display) return null;
+    return { waylandDisplay, display, runtimeDir, xAuthority };
+  } catch {
+    return null;
+  }
+}
+
+function discoverLinuxGuiEnvFromProc() {
+  if (process.platform === 'win32' || process.platform === 'darwin') return null;
+  let entries = [];
+  try {
+    entries = fs.readdirSync('/proc', { withFileTypes: true });
+  } catch {
+    return null;
+  }
+
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    if (!/^\d+$/.test(entry.name)) continue;
+    if (Number(entry.name) === process.pid) continue;
+    const discovered = readLinuxProcGuiEnv(entry.name);
+    if (discovered) return discovered;
+  }
+  return null;
+}
+
+function discoverLinuxGuiEnvFromSocket() {
+  if (process.platform === 'win32' || process.platform === 'darwin') return null;
+  const discovered = {
+    waylandDisplay: null,
+    display: null,
+    runtimeDir: null,
+    xAuthority: null,
+  };
+
+  const currentUid = typeof process.getuid === 'function' ? process.getuid() : null;
+  const runtimeDir = currentUid != null ? `/run/user/${currentUid}` : null;
+  if (runtimeDir && fs.existsSync(runtimeDir)) {
+    discovered.runtimeDir = runtimeDir;
+    try {
+      const entries = fs.readdirSync(runtimeDir);
+      const waylandSockets = entries.filter(name => /^wayland-\d+$/.test(name)).sort();
+      if (waylandSockets.length > 0) discovered.waylandDisplay = waylandSockets[0];
+    } catch {}
+  }
+
+  try {
+    const xEntries = fs.readdirSync('/tmp/.X11-unix');
+    const displaySockets = xEntries
+      .map(name => {
+        const match = /^X(\d+)$/.exec(name);
+        return match ? Number(match[1]) : null;
+      })
+      .filter(num => Number.isInteger(num))
+      .sort((a, b) => a - b);
+    if (displaySockets.length > 0) discovered.display = `:${displaySockets[0]}`;
+  } catch {}
+
+  if (!discovered.waylandDisplay && !discovered.display) return null;
+  return discovered;
+}
+
+function getLinuxClipboardEnv() {
+  if (process.platform === 'win32' || process.platform === 'darwin') {
+    return { env: process.env, source: 'not_linux' };
+  }
+
+  const overlay = {
+    WAYLAND_DISPLAY: normalizeLinuxEnvVar(process.env.CLAUDE_REMOTE_WAYLAND_DISPLAY) || normalizeLinuxEnvVar(process.env.WAYLAND_DISPLAY),
+    DISPLAY: normalizeLinuxEnvVar(process.env.CLAUDE_REMOTE_DISPLAY) || normalizeLinuxEnvVar(process.env.DISPLAY),
+    XDG_RUNTIME_DIR: normalizeLinuxEnvVar(process.env.CLAUDE_REMOTE_XDG_RUNTIME_DIR) || normalizeLinuxEnvVar(process.env.XDG_RUNTIME_DIR),
+    XAUTHORITY: normalizeLinuxEnvVar(process.env.CLAUDE_REMOTE_XAUTHORITY) || normalizeLinuxEnvVar(process.env.XAUTHORITY),
+  };
+
+  let source = 'process_env';
+  const needsSocketDiscovery =
+    (!overlay.WAYLAND_DISPLAY && !overlay.DISPLAY) ||
+    (!!overlay.WAYLAND_DISPLAY && !overlay.XDG_RUNTIME_DIR);
+  if (needsSocketDiscovery) {
+    const before = {
+      waylandDisplay: overlay.WAYLAND_DISPLAY,
+      display: overlay.DISPLAY,
+      runtimeDir: overlay.XDG_RUNTIME_DIR,
+      xAuthority: overlay.XAUTHORITY,
+    };
+    const fromSocket = discoverLinuxGuiEnvFromSocket();
+    if (fromSocket) {
+      if (!overlay.WAYLAND_DISPLAY && fromSocket.waylandDisplay) overlay.WAYLAND_DISPLAY = fromSocket.waylandDisplay;
+      if (!overlay.DISPLAY && fromSocket.display) overlay.DISPLAY = fromSocket.display;
+      if (!overlay.XDG_RUNTIME_DIR && fromSocket.runtimeDir) overlay.XDG_RUNTIME_DIR = fromSocket.runtimeDir;
+      if (!overlay.XAUTHORITY && fromSocket.xAuthority) overlay.XAUTHORITY = fromSocket.xAuthority;
+      const changed =
+        before.waylandDisplay !== overlay.WAYLAND_DISPLAY ||
+        before.display !== overlay.DISPLAY ||
+        before.runtimeDir !== overlay.XDG_RUNTIME_DIR ||
+        before.xAuthority !== overlay.XAUTHORITY;
+      if (changed) source = 'socket_discovery';
+    }
+  }
+
+  const needsProcDiscovery =
+    (!overlay.WAYLAND_DISPLAY && !overlay.DISPLAY) ||
+    (!!overlay.DISPLAY && !overlay.XAUTHORITY) ||
+    (!!overlay.WAYLAND_DISPLAY && !overlay.XDG_RUNTIME_DIR);
+  if (needsProcDiscovery) {
+    const before = {
+      waylandDisplay: overlay.WAYLAND_DISPLAY,
+      display: overlay.DISPLAY,
+      runtimeDir: overlay.XDG_RUNTIME_DIR,
+      xAuthority: overlay.XAUTHORITY,
+    };
+    const fromProc = discoverLinuxGuiEnvFromProc();
+    if (fromProc) {
+      if (!overlay.WAYLAND_DISPLAY && fromProc.waylandDisplay) overlay.WAYLAND_DISPLAY = fromProc.waylandDisplay;
+      if (!overlay.DISPLAY && fromProc.display) overlay.DISPLAY = fromProc.display;
+      if (!overlay.XDG_RUNTIME_DIR && fromProc.runtimeDir) overlay.XDG_RUNTIME_DIR = fromProc.runtimeDir;
+      if (!overlay.XAUTHORITY && fromProc.xAuthority) overlay.XAUTHORITY = fromProc.xAuthority;
+      const changed =
+        before.waylandDisplay !== overlay.WAYLAND_DISPLAY ||
+        before.display !== overlay.DISPLAY ||
+        before.runtimeDir !== overlay.XDG_RUNTIME_DIR ||
+        before.xAuthority !== overlay.XAUTHORITY;
+      if (changed) {
+        source = source === 'socket_discovery' ? 'socket+proc_discovery' : 'proc_discovery';
+      }
+    }
+  }
+
+  const env = { ...process.env };
+  if (overlay.WAYLAND_DISPLAY) env.WAYLAND_DISPLAY = overlay.WAYLAND_DISPLAY;
+  if (overlay.DISPLAY) env.DISPLAY = overlay.DISPLAY;
+  if (overlay.XDG_RUNTIME_DIR) env.XDG_RUNTIME_DIR = overlay.XDG_RUNTIME_DIR;
+  if (overlay.XAUTHORITY) env.XAUTHORITY = overlay.XAUTHORITY;
+
+  return {
+    env,
+    source,
+    waylandDisplay: overlay.WAYLAND_DISPLAY || null,
+    display: overlay.DISPLAY || null,
+    runtimeDir: overlay.XDG_RUNTIME_DIR || null,
+    xAuthority: overlay.XAUTHORITY || null,
+  };
+}
+
+function getLinuxClipboardToolCandidates(clipboardEnv = process.env) {
+  if (process.platform === 'win32' || process.platform === 'darwin') return [];
+  const preferred = [];
+  if (clipboardEnv.WAYLAND_DISPLAY) preferred.push('wl-copy');
+  if (clipboardEnv.DISPLAY) preferred.push('xclip');
+  return preferred;
+}
+
+function assertLinuxClipboardAvailable() {
+  const gui = getLinuxClipboardEnv();
+  const candidates = getLinuxClipboardToolCandidates(gui.env);
+  const available = candidates.filter(isLinuxClipboardToolInstalled);
+  if (available.length > 0) {
+    return {
+      tools: available,
+      env: gui.env,
+      source: gui.source,
+      waylandDisplay: gui.waylandDisplay,
+      display: gui.display,
+      runtimeDir: gui.runtimeDir,
+      xAuthority: gui.xAuthority,
+    };
+  }
+  if (!gui.waylandDisplay && !gui.display) {
+    throw new Error('Linux image paste requires a graphical session. Could not detect WAYLAND_DISPLAY or DISPLAY (common in pm2/systemd). Set CLAUDE_REMOTE_DISPLAY or CLAUDE_REMOTE_WAYLAND_DISPLAY and retry.');
+  }
+  throw new Error('Linux image paste requires wl-copy or xclip on the server. Install a matching clipboard tool and try again.');
+}
+
+function formatLinuxClipboardEnvLog(info) {
+  if (!info) return '';
+  const parts = [];
+  if (info.waylandDisplay) parts.push(`WAYLAND_DISPLAY=${info.waylandDisplay}`);
+  if (info.display) parts.push(`DISPLAY=${info.display}`);
+  if (info.runtimeDir) parts.push(`XDG_RUNTIME_DIR=${info.runtimeDir}`);
+  if (info.xAuthority) parts.push(`XAUTHORITY=${info.xAuthority}`);
+  return parts.length ? ` env[${parts.join(', ')}]` : '';
+}
+
+function spawnLinuxClipboardTool(tool, imageBuffer, type, clipboardEnv) {
+  return new Promise((resolve, reject) => {
+    const args = tool === 'xclip'
+      ? ['-quiet', '-selection', 'clipboard', '-t', type, '-i']
+      : ['--type', type];
+    const child = spawn(tool, args, {
+      detached: true,
+      stdio: ['pipe', 'ignore', 'pipe'],
+      env: clipboardEnv || process.env,
+    });
+    let settled = false;
+    let stderr = '';
+    let readyTimer = null;
+
+    const settleFailure = (message) => {
+      if (settled) return;
+      settled = true;
+      if (readyTimer) clearTimeout(readyTimer);
+      if (child.exitCode == null && child.signalCode == null) {
+        try { child.kill('SIGTERM'); } catch {}
+      }
+      reject(new Error(message));
+    };
+
+    const settleSuccess = (trackProcess = true) => {
+      if (settled) return;
+      settled = true;
+      if (readyTimer) clearTimeout(readyTimer);
+      if (trackProcess && child.exitCode == null && child.signalCode == null) {
+        activeLinuxClipboardProc = { child, tool };
+        child.unref();
+      }
+      resolve(tool);
+    };
+
+    child.on('error', (err) => {
+      log(`Linux clipboard process error (${tool}): ${err.message}`);
+      settleFailure(`Linux clipboard tool ${tool} failed: ${err.message}`);
+    });
+    child.stderr.on('data', (chunk) => {
+      stderr += chunk.toString('utf8');
+      if (stderr.length > 2000) stderr = stderr.slice(-2000);
+    });
+    child.on('exit', (code, signal) => {
+      if (activeLinuxClipboardProc && activeLinuxClipboardProc.child === child) activeLinuxClipboardProc = null;
+      const extra = stderr.trim() ? ` stderr=${JSON.stringify(stderr.trim())}` : '';
+      log(`Linux clipboard process exited (${tool}) code=${code ?? 'null'} signal=${signal ?? 'null'}${extra}`);
+      if (!settled) {
+        if (tool === 'xclip' && code === 0 && !signal && !stderr.trim()) {
+          log('Linux clipboard xclip exited cleanly without stderr; treating clipboard arm as successful');
+          settleSuccess(false);
+          return;
+        }
+        const detail = stderr.trim() || `exit code ${code ?? 'null'} signal ${signal ?? 'null'}`;
+        settleFailure(`Linux clipboard tool ${tool} exited before paste: ${detail}`);
+      }
+    });
+    child.stdin.on('error', (err) => {
+      if (err.code === 'EPIPE') {
+        settleFailure(`Linux clipboard tool ${tool} closed its input early`);
+        return;
+      }
+      log(`Linux clipboard stdin error (${tool}): ${err.message}`);
+      settleFailure(`Linux clipboard tool ${tool} stdin failed: ${err.message}`);
+    });
+
+    child.stdin.end(imageBuffer);
+    log(`Linux clipboard process started (${tool}) pid=${child.pid ?? 'null'} type=${type} bytes=${imageBuffer.length}`);
+    readyTimer = setTimeout(() => settleSuccess(), LINUX_CLIPBOARD_READY_GRACE_MS);
+  });
+}
+
+async function startLinuxClipboardImage(tmpFile, mediaType, clipboardInfo = null) {
+  const type = String(mediaType || 'image/png').toLowerCase();
+  const imageBuffer = fs.readFileSync(tmpFile);
+  const resolved = clipboardInfo || assertLinuxClipboardAvailable();
+  const availableTools = resolved.tools;
+  clearActiveLinuxClipboardProc('replace');
+
+  let lastErr = null;
+  for (const tool of availableTools) {
+    try {
+      return await spawnLinuxClipboardTool(tool, imageBuffer, type, resolved.env);
+    } catch (err) {
+      lastErr = err;
+      log(`Linux clipboard arm failed (${tool}): ${err.message}`);
+    }
+  }
+
+  throw lastErr || new Error('Linux clipboard could not be initialized');
+}
+
 setInterval(() => {
   const now = Date.now();
   for (const [uploadId, upload] of pendingImageUploads) {
@@ -1064,26 +1282,17 @@ wss.on('connection', (ws, req) => {
         }
         break;
       }
-      case 'image_upload_init': {
-        const uploadId = String(msg.uploadId || '');
-        if (!uploadId) {
-          sendUploadStatus(ws, '', 'error', { message: 'Missing uploadId' });
-          break;
-        }
-        cleanupImageUpload(uploadId);
-        if (process.platform !== 'win32' && process.platform !== 'darwin') {
-          try {
-            const tools = assertLinuxClipboardAvailable();
-            log(`Linux clipboard preflight OK: ${tools.join(', ')}`);
-          } catch (err) {
-            sendUploadStatus(ws, uploadId, 'error', { message: err.message });
-            break;
-          }
+      case 'image_upload_init': {
+        const uploadId = String(msg.uploadId || '');
+        if (!uploadId) {
+          sendUploadStatus(ws, '', 'error', { message: 'Missing uploadId' });
+          break;
         }
-        pendingImageUploads.set(uploadId, {
-          id: uploadId,
-          owner: ws,
-          mediaType: msg.mediaType || 'image/png',
+        cleanupImageUpload(uploadId);
+        pendingImageUploads.set(uploadId, {
+          id: uploadId,
+          owner: ws,
+          mediaType: msg.mediaType || 'image/png',
           name: msg.name || 'image',
           totalBytes: Number.isFinite(msg.totalBytes) ? msg.totalBytes : 0,
           totalChunks: Number.isFinite(msg.totalChunks) ? msg.totalChunks : 0,
@@ -1181,13 +1390,13 @@ wss.on('connection', (ws, req) => {
           sendUploadStatus(ws, uploadId, 'error', { message: 'Upload not ready' });
           break;
         }
-        try {
-          await handlePreparedImageUpload({
-            tmpFile: upload.tmpFile,
-            mediaType: upload.mediaType,
-            text: msg.text || '',
-            logLabel: upload.name || uploadId,
-            onCleanup: () => cleanupImageUpload(uploadId),
+        try {
+          await handlePreparedImageUpload({
+            tmpFile: upload.tmpFile,
+            mediaType: upload.mediaType,
+            text: msg.text || '',
+            logLabel: upload.name || uploadId,
+            onCleanup: () => cleanupImageUpload(uploadId),
           });
           upload.submitted = true;
           upload.updatedAt = Date.now();
@@ -1396,11 +1605,20 @@ function extractSlashCommand(content) {
   return inlineMatch ? inlineMatch[1].trim().toLowerCase() : '';
 }
 
+function isUserInterruptEvent(content) {
+  const text = flattenUserContent(content)
+    .replace(/\x1B\[[0-9;]*m/g, '')
+    .trim();
+  if (!text) return false;
+  return /(?:^|\n)\[Request interrupted by user(?: for tool use)?\](?:\r?\n|$)/i.test(text);
+}
+
 function isNonAiUserEvent(event, content) {
   if (!event || typeof event !== 'object') return false;
   if (event.isMeta === true) return true;
   if (event.isCompactSummary === true) return true;
   if (event.isVisibleInTranscriptOnly === true) return true;
+  if (isUserInterruptEvent(content)) return true;
 
   const text = flattenUserContent(content).trim();
   if (!text) return false;
@@ -1554,12 +1772,16 @@ function startTailing() {
           if (event.type === 'user' || (event.message && event.message.role === 'user')) {
             const content = event.message && event.message.content;
             const slashCommand = extractSlashCommand(content);
+            const isInterruptedUserEvent = isUserInterruptEvent(content);
             const isPassiveUserEvent = isNonAiUserEvent(event, content);
             const ignoreInitialClear = (
               slashCommand === '/clear' &&
               pendingInitialClearTranscript &&
               pendingInitialClearTranscript.sessionId === currentSessionId
             );
+            if (!tailCatchingUp && isInterruptedUserEvent) {
+              setTurnState('idle', { sessionId: currentSessionId, reason: 'transcript_user_interrupt' });
+            }
             // Only live, AI-producing user messages can move the turn state
             // into running. Historical replay and slash commands are ignored.
             if (!tailCatchingUp && !slashCommand && !isPassiveUserEvent) {
@@ -1815,81 +2037,91 @@ function restartClaude(newCwd) {
 // ============================================================
 //  5. Image Upload → Clipboard Injection
 // ============================================================
-async function handlePreparedImageUpload({ tmpFile, mediaType, text, logLabel = '', onCleanup = null }) {
-  if (!claudeProc) throw new Error('Claude not running');
-  if (!tmpFile || !fs.existsSync(tmpFile)) throw new Error('Prepared image file missing');
-
+async function handlePreparedImageUpload({ tmpFile, mediaType, text, logLabel = '', onCleanup = null }) {
+  if (!claudeProc) throw new Error('Claude not running');
+  if (!tmpFile || !fs.existsSync(tmpFile)) throw new Error('Prepared image file missing');
+
   const isWin = process.platform === 'win32';
   const isMac = process.platform === 'darwin';
   const isLinux = !isWin && !isMac;
-  if (isLinux && linuxImagePasteInFlight) {
-    throw new Error('Another Linux image paste is still in progress. Please wait a moment and try again.');
-  }
   try {
     const stat = fs.statSync(tmpFile);
     log(`Image ready: ${logLabel || path.basename(tmpFile)} (${stat.size} bytes)`);
-    if (isLinux) setLinuxImagePasteInFlight(true, 'prepare_upload');
-
-    if (isWin) {
-      const psCmd = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $img = [System.Drawing.Image]::FromFile('${tmpFile.replace(/'/g, "''")}'); [System.Windows.Forms.Clipboard]::SetImage($img); $img.Dispose()`;
-      execSync(`powershell -NoProfile -STA -Command "${psCmd}"`, { timeout: 10000 });
-    } else if (isMac) {
-      execSync(`osascript -e 'set the clipboard to (read POSIX file "${tmpFile}" as 芦class PNGf禄)'`, { timeout: 10000 });
-    } else {
-      const tool = await startLinuxClipboardImage(tmpFile, mediaType);
-      log(`Linux clipboard armed with ${tool}`);
-    }
-    log('Clipboard set with image');
-
-    const pasteDelayMs = isWin || isMac ? 0 : 150;
-    await new Promise((resolve, reject) => {
-      setTimeout(() => {
+    if (isLinux) {
+      const linuxPrompt = buildLinuxImagePrompt(text, tmpFile);
+      await new Promise((resolve, reject) => {
         if (!claudeProc) {
-          reject(new Error('Claude stopped before image paste'));
+          reject(new Error('Claude stopped before Linux image submit'));
           return;
         }
-        if (isWin) claudeProc.write('\x1bv');
-        else claudeProc.write('\x16');
-        log('Sent image paste keypress to PTY');
-
+        claudeProc.write(linuxPrompt);
         setTimeout(() => {
           if (!claudeProc) {
-            reject(new Error('Claude stopped before image prompt'));
+            reject(new Error('Claude stopped before Linux image submit'));
             return;
           }
-          const trimmedText = (text || '').trim();
-          if (trimmedText) claudeProc.write(trimmedText);
-
+          claudeProc.write('\r');
+          log(`Sent Linux image prompt via @ref: "${linuxPrompt.substring(0, 120)}"`);
           setTimeout(() => {
-            if (!claudeProc) {
-              reject(new Error('Claude stopped before image submit'));
-              return;
+            if (onCleanup) onCleanup();
+            else {
+              try { fs.unlinkSync(tmpFile); } catch {}
             }
-            claudeProc.write('\r');
-            log('Sent Enter after image paste' + (trimmedText ? ` + text: "${trimmedText.substring(0, 60)}"` : ''));
+          }, LINUX_AT_IMAGE_CLEANUP_DELAY_MS);
+          resolve();
+        }, LINUX_AT_PROMPT_SUBMIT_DELAY_MS);
+      });
+      return;
+    }
 
-            if (isLinux) {
-              setTimeout(() => clearActiveLinuxClipboardProc('post-paste'), 1000);
+    if (isWin) {
+      const psCmd = `Add-Type -AssemblyName System.Drawing; Add-Type -AssemblyName System.Windows.Forms; $img = [System.Drawing.Image]::FromFile('${tmpFile.replace(/'/g, "''")}'); [System.Windows.Forms.Clipboard]::SetImage($img); $img.Dispose()`;
+      execSync(`powershell -NoProfile -STA -Command "${psCmd}"`, { timeout: 10000 });
+    } else if (isMac) {
+      execSync(`osascript -e 'set the clipboard to (read POSIX file "${tmpFile}" as 芦class PNGf禄)'`, { timeout: 10000 });
+    }
+    log('Clipboard set with image');
+
+    const pasteDelayMs = isWin || isMac ? 0 : 150;
+    await new Promise((resolve, reject) => {
+      setTimeout(() => {
+        if (!claudeProc) {
+          reject(new Error('Claude stopped before image paste'));
+          return;
+        }
+        if (isWin) claudeProc.write('\x1bv');
+        else claudeProc.write('\x16');
+        log('Sent image paste keypress to PTY');
+
+        setTimeout(() => {
+          if (!claudeProc) {
+            reject(new Error('Claude stopped before image prompt'));
+            return;
+          }
+          const trimmedText = (text || '').trim();
+          if (trimmedText) claudeProc.write(trimmedText);
+
+          setTimeout(() => {
+            if (!claudeProc) {
+              reject(new Error('Claude stopped before image submit'));
+              return;
             }
+            claudeProc.write('\r');
+            log('Sent Enter after image paste' + (trimmedText ? ` + text: "${trimmedText.substring(0, 60)}"` : ''));
 
             setTimeout(() => {
-              if (isLinux) setLinuxImagePasteInFlight(false, 'cleanup');
               if (onCleanup) onCleanup();
               else {
                 try { fs.unlinkSync(tmpFile); } catch {}
               }
-            }, 5000);
-            resolve();
-          }, 150);
-        }, 1000);
-      }, pasteDelayMs);
-    });
+            }, 5000);
+            resolve();
+          }, 150);
+        }, 1000);
+      }, pasteDelayMs);
+    });
   } catch (err) {
     log(`Image upload error: ${err.message}`);
-    if (isLinux) {
-      clearActiveLinuxClipboardProc('error');
-      setLinuxImagePasteInFlight(false, 'error');
-    }
     if (onCleanup) onCleanup();
     else {
       try { fs.unlinkSync(tmpFile); } catch {}
@@ -1907,30 +2139,26 @@ function handleImageUpload(msg) {
     log('Image upload ignored: no base64 data');
     return;
   }
-  let tmpFile = null;
-
+  let tmpFile = null;
+
   try {
-    if (process.platform !== 'win32' && process.platform !== 'darwin') {
-      const tools = assertLinuxClipboardAvailable();
-      log(`Linux clipboard preflight OK (legacy upload): ${tools.join(', ')}`);
-    }
     const buf = Buffer.from(msg.base64, 'base64');
     tmpFile = createTempImageFile(buf, msg.mediaType, `legacy_${Date.now()}`);
     log(`Image saved: ${tmpFile} (${buf.length} bytes)`);
-    handlePreparedImageUpload({
-      tmpFile,
-      mediaType: msg.mediaType,
-      text: msg.text || '',
-    }).then(() => {
-      setTurnState('running', { reason: 'legacy_image_upload' });
-    }).catch((err) => {
-      log(`Image upload error: ${err.message}`);
-    });
-  } catch (err) {
-    log(`Image upload error: ${err.message}`);
-    try { fs.unlinkSync(tmpFile); } catch {}
-  }
-}
+    handlePreparedImageUpload({
+      tmpFile,
+      mediaType: msg.mediaType,
+      text: msg.text || '',
+    }).then(() => {
+      setTurnState('running', { reason: 'legacy_image_upload' });
+    }).catch((err) => {
+      log(`Image upload error: ${err.message}`);
+    });
+  } catch (err) {
+    log(`Image upload error: ${err.message}`);
+    try { fs.unlinkSync(tmpFile); } catch {}
+  }
+}
 
 // ============================================================
 //  6. Hook Auto-Setup