buddy-workbench 0.1.110 → 0.1.112

package/server/services/clipboard-history.js

@@ -1,6 +1,6 @@
-import { execFile } from 'node:child_process';
+import { execFile, spawn } from 'node:child_process';
 import { createHash, randomUUID } from 'node:crypto';
-import { existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { chmodSync, existsSync, mkdirSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { promisify } from 'node:util';
 import { fileURLToPath } from 'node:url';
@@ -22,6 +22,10 @@ let suppressImageCaptureUntil = 0;
 // recompiling Swift and incrementing the same error counter every poll.
 let swiftClipboardRetryAt = 0;
 let mozjpegWasmModule = null;
+let macClipboardHelper = null;
+let macClipboardHelperRestartTimer = null;
+let macClipboardHelperWatchdog = null;
+let macClipboardHelperExitHookRegistered = false;
 const clipboardErrorCounts = new Map();
 const clipboardErrorLoggedStages = new Set();
 
@@ -192,6 +196,212 @@ if let data = pb.data(forType: .png) {
   return null;
 }
 
+function persistCapturedClipboardImage(buffer, hash, extension = 'jpg') {
+  if (!buffer?.length || !hash || hash === lastImageHash) return;
+
+  let isDuplicate = false;
+  for (const date of clipboardDates()) {
+    if (dayItems(date).some((item) => item.imageHash === hash || item.fileHash === hash || item.imageHashes?.includes(hash))) {
+      isDuplicate = true;
+      break;
+    }
+  }
+
+  if (isDuplicate) {
+    lastImageHash = hash;
+    return;
+  }
+
+  saveClipboardImage(buffer, extension, hash);
+  lastImageHash = hash;
+  markClipboardSuccess('image save');
+}
+
+function handleMacClipboardHelperMessage(state, line) {
+  let message;
+  try {
+    message = JSON.parse(line);
+  } catch (error) {
+    logClipboardError('native image helper protocol', error);
+    return;
+  }
+  state.lastMessageAt = Date.now();
+
+  if (message.kind === 'ready') {
+    state.ready = true;
+    markClipboardSuccess('native image helper startup', 'native image helper process');
+    return;
+  }
+  if (message.kind === 'heartbeat') {
+    markClipboardSuccess('native image helper stall');
+    return;
+  }
+  if (message.kind === 'error') {
+    const stage = `native clipboard ${String(message.stage || 'capture')}`;
+    const elapsedMs = Number(message.elapsedMs);
+    const elapsedNote = Number.isFinite(elapsedMs) ? ` (${elapsedMs} ms)` : '';
+    logClipboardError(stage, new Error(`${String(message.message || 'Native clipboard capture failed.')}${elapsedNote}`), 1);
+    return;
+  }
+  if (message.kind !== 'image') return;
+
+  const filename = String(message.filename || '');
+  const validFilename = /^capture-[0-9a-f-]+\.jpg$/i.test(filename);
+  if (validFilename && Date.now() < suppressImageCaptureUntil) {
+    try { unlinkSync(join(paths.clipboardDir, 'content', filename)); } catch {}
+    return;
+  }
+  const tempPath = validFilename ? join(paths.clipboardDir, 'content', filename) : null;
+  const width = Number(message.width);
+  const height = Number(message.height);
+  const reportedBytes = Number(message.bytes);
+  if (!validFilename
+      || !Number.isInteger(width) || width <= 0
+      || !Number.isInteger(height) || height <= 0
+      || width * height > 40_000_000
+      || !Number.isInteger(reportedBytes) || reportedBytes <= 0 || reportedBytes > macClipboardCommandMaxBuffer) {
+    if (tempPath) { try { unlinkSync(tempPath); } catch {} }
+    logClipboardError('native image helper protocol', new Error('Native image helper returned invalid image metadata.'));
+    return;
+  }
+
+  try {
+    const jpeg = readFileSync(tempPath);
+    if (!jpeg.length || jpeg.length !== reportedBytes || jpeg.length > macClipboardCommandMaxBuffer) {
+      throw new Error('Temporary JPEG size did not match the helper metadata.');
+    }
+    const hash = createHash('md5').update(jpeg).digest('hex');
+    persistCapturedClipboardImage(jpeg, hash, 'jpg');
+    const elapsedMs = Number(message.elapsedMs);
+    if (Number.isFinite(elapsedMs) && elapsedMs >= 3000) {
+      addErrorRecord({
+        source: 'Clipboard Monitor',
+        level: 'warning',
+        message: `Clipboard image capture took ${elapsedMs} ms.`,
+        details: `${width} × ${height}, source type ${String(message.sourceType || 'unknown')}, JPEG ${jpeg.length} bytes.`
+      });
+    }
+    markClipboardSuccess(
+      'native clipboard pasteboard read',
+      'native clipboard image validation',
+      'native clipboard image decode',
+      'native clipboard JPEG encode',
+      'native clipboard JPEG save'
+    );
+  } catch (error) {
+    logClipboardError('native clipboard JPEG handoff', error);
+  } finally {
+    try { unlinkSync(tempPath); } catch {}
+  }
+}
+
+function scheduleMacClipboardHelperRestart() {
+  if (macClipboardHelperRestartTimer) return;
+  macClipboardHelperRestartTimer = setTimeout(() => {
+    macClipboardHelperRestartTimer = null;
+    startMacClipboardImageHelper();
+  }, 5000);
+  macClipboardHelperRestartTimer.unref();
+}
+
+function stopMacClipboardImageHelper() {
+  if (macClipboardHelperRestartTimer) {
+    clearTimeout(macClipboardHelperRestartTimer);
+    macClipboardHelperRestartTimer = null;
+  }
+  const active = macClipboardHelper;
+  macClipboardHelper = null;
+  if (active) active.child.kill('SIGTERM');
+}
+
+function startMacClipboardImageHelper() {
+  if (process.platform !== 'darwin' || macClipboardHelper || macClipboardHelperRestartTimer) return;
+  const outputDirectory = join(paths.clipboardDir, 'content');
+  mkdirSync(outputDirectory, { recursive: true, mode: 0o700 });
+  try { chmodSync(outputDirectory, 0o700); } catch (error) {
+    logClipboardError('native image helper directory permissions', error);
+    return;
+  }
+  const scriptPath = fileURLToPath(new URL('./mac-clipboard-helper.swift', import.meta.url));
+  let child;
+  try {
+    child = spawn('swift', [scriptPath, outputDirectory], { stdio: ['ignore', 'pipe', 'pipe'], windowsHide: true });
+  } catch (error) {
+    logClipboardError('native image helper startup', error);
+    scheduleMacClipboardHelperRestart();
+    return;
+  }
+
+  const state = { child, ready: false, lastMessageAt: Date.now(), lineBuffer: '', stderr: '' };
+  macClipboardHelper = state;
+  child.stdout.setEncoding('utf8');
+  child.stdout.on('data', (chunk) => {
+    state.lineBuffer += chunk;
+    if (state.lineBuffer.length > 64 * 1024) {
+      logClipboardError('native image helper protocol', new Error('Native image helper message exceeded 64 KiB.'));
+      child.kill('SIGTERM');
+      return;
+    }
+    let newline;
+    while ((newline = state.lineBuffer.indexOf('\n')) >= 0) {
+      const line = state.lineBuffer.slice(0, newline);
+      state.lineBuffer = state.lineBuffer.slice(newline + 1);
+      if (line) handleMacClipboardHelperMessage(state, line);
+    }
+  });
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', (chunk) => {
+    state.stderr = (state.stderr + chunk).slice(-4000);
+  });
+  child.on('error', (error) => {
+    logClipboardError('native image helper startup', error);
+  });
+  child.on('exit', (code, signal) => {
+    if (macClipboardHelper !== state) return;
+    macClipboardHelper = null;
+    if (code !== 0) {
+      const details = state.stderr.trim();
+      logClipboardError('native image helper process', new Error(details || `Helper exited with code ${code ?? signal ?? 'unknown'}.`));
+    }
+    scheduleMacClipboardHelperRestart();
+  });
+
+  if (!macClipboardHelperWatchdog) {
+    macClipboardHelperWatchdog = setInterval(() => {
+      const active = macClipboardHelper;
+      if (!active?.ready || Date.now() - active.lastMessageAt < 30_000) return;
+      logClipboardError('native image helper stall', new Error('Native image helper stopped responding for 30 seconds.'));
+      active.child.kill('SIGTERM');
+    }, 5000);
+    macClipboardHelperWatchdog.unref();
+  }
+
+  if (!macClipboardHelperExitHookRegistered) {
+    macClipboardHelperExitHookRegistered = true;
+    process.once('exit', () => {
+      try { macClipboardHelper?.child.kill('SIGTERM'); } catch {}
+    });
+  }
+}
+
+async function captureMacClipboardImageLegacy() {
+  try {
+    const imageData = await getMacClipboardImageData();
+    if (imageData?.rgbaBuf?.length) {
+      const hash = createHash('md5').update(imageData.rgbaBuf).digest('hex');
+      if (hash === lastImageHash) return;
+      const jpeg = await compressMozjpeg(imageData.rgbaBuf, imageData.width, imageData.height, 75);
+      persistCapturedClipboardImage(jpeg, hash, 'jpg');
+    } else if (imageData?.rawBuffer?.length) {
+      const hash = createHash('md5').update(imageData.rawBuffer).digest('hex');
+      if (hash === lastImageHash) return;
+      persistCapturedClipboardImage(imageData.rawBuffer, hash, 'png');
+    }
+  } catch (error) {
+    logClipboardError('legacy clipboard image capture', error);
+  }
+}
+
 function today() { return new Intl.DateTimeFormat('en-CA').format(new Date()); }
 function dayFile(date) { const [year, month, day] = date.split('-'); return join(paths.clipboardDir, year, month, `${day}.json`); }
 function readJson(file, fallback) { try { return existsSync(file) ? JSON.parse(readFileSync(file, 'utf8')) : fallback; } catch { return fallback; } }
@@ -351,6 +561,13 @@ export function deleteClipboardItem(date, id) {
 
 export async function captureClipboard() {
   const settings = readSettings();
+  if (process.platform === 'darwin') {
+    if (settings.clipboardEnabled !== false && settings.clipboardImageEnabled !== false) {
+      startMacClipboardImageHelper();
+    } else {
+      stopMacClipboardImageHelper();
+    }
+  }
   if (settings.clipboardEnabled === false) return;
 
   // 1. Text capture
@@ -409,86 +626,13 @@ export async function captureClipboard() {
     }
   } catch {}
 
-  // 2. Image capture (Mac only & clipboardImageEnabled !== false)
-  if (process.platform === 'darwin' && settings.clipboardImageEnabled !== false && Date.now() >= suppressImageCaptureUntil) {
-    try {
-      const imageData = await getMacClipboardImageData();
-      if (!imageData) {
-        // No image on clipboard (or transient capture failed and will retry next tick)
-        return;
-      }
-
-      if (imageData.rgbaBuf && imageData.rgbaBuf.length > 0) {
-        const hash = createHash('md5').update(imageData.rgbaBuf).digest('hex');
-        if (hash !== lastImageHash) {
-          let isDuplicate = false;
-          const dates = clipboardDates();
-          for (const d of dates) {
-            const dayList = dayItems(d);
-            if (dayList.some(item => {
-              if (item.imageHash === hash || item.fileHash === hash) return true;
-              if (Array.isArray(item.imageHashes) && item.imageHashes.includes(hash)) return true;
-              return false;
-            })) {
-              isDuplicate = true;
-              break;
-            }
-          }
-
-          if (!isDuplicate) {
-            try {
-              const mozjpegBuf = await compressMozjpeg(imageData.rgbaBuf, imageData.width, imageData.height, 75);
-              saveClipboardImage(mozjpegBuf, 'jpg', hash);
-              lastImageHash = hash;
-              markClipboardSuccess('image compression or save (WASM/JPEG)', 'image save');
-            } catch (error) {
-              logClipboardError('image compression or save (WASM/JPEG)', error);
-              const rawBuf = await getMacClipboardImageBuffer();
-              if (rawBuf) {
-                try {
-                  saveClipboardImage(rawBuf, 'png', hash);
-                  lastImageHash = hash;
-                  markClipboardSuccess('raw image save after compression fallback', 'image save');
-                } catch (fallbackError) {
-                  logClipboardError('raw image save after compression fallback', fallbackError);
-                }
-              }
-            }
-          } else {
-            lastImageHash = hash;
-          }
-        }
-      } else if (imageData.rawBuffer && imageData.rawBuffer.length > 0) {
-        const hash = createHash('md5').update(imageData.rawBuffer).digest('hex');
-        if (hash !== lastImageHash) {
-          let isDuplicate = false;
-          const dates = clipboardDates();
-          for (const d of dates) {
-            const dayList = dayItems(d);
-            if (dayList.some(item => {
-              if (item.imageHash === hash || item.fileHash === hash) return true;
-              if (Array.isArray(item.imageHashes) && item.imageHashes.includes(hash)) return true;
-              return false;
-            })) {
-              isDuplicate = true;
-              break;
-            }
-          }
-
-          if (!isDuplicate) {
-            try {
-              saveClipboardImage(imageData.rawBuffer, 'png', hash);
-              lastImageHash = hash;
-              markClipboardSuccess('image save');
-            } catch (error) {
-              logClipboardError('image save', error);
-            }
-          } else {
-            lastImageHash = hash;
-          }
-        }
-      }
-    } catch {}
+  // While the native helper is compiling or unavailable, retain the prior
+  // capture path as a compatibility fallback.
+  if (process.platform === 'darwin'
+      && settings.clipboardImageEnabled !== false
+      && Date.now() >= suppressImageCaptureUntil
+      && macClipboardHelper === null) {
+    await captureMacClipboardImageLegacy();
   }
 }
 

package/server/services/cron-jobs.js

@@ -0,0 +1,216 @@
+import { existsSync } from 'node:fs';
+import { listCronJobs, saveCronJobs } from '../repositories/cron-jobs.js';
+import { listGroupTasks } from '../repositories/group-tasks.js';
+import { listLaunchers } from '../repositories/launchers.js';
+import { readPackageScripts } from './package-scripts.js';
+import { runScript } from './process-manager.js';
+
+const MINUTE = 60 * 1000;
+const schedulerState = { started: false, timer: null, runningJobs: new Set() };
+
+function validTime(value) {
+  const time = String(value || '').trim();
+  return /^([01]\d|2[0-3]):[0-5]\d$/.test(time) ? time : null;
+}
+
+function setLocalTime(date, time) {
+  const [hours, minutes] = time.split(':').map(Number);
+  const next = new Date(date);
+  next.setSeconds(0, 0);
+  next.setHours(hours, minutes, 0, 0);
+  return next;
+}
+
+function nextPresetRun(job, now = new Date()) {
+  const time = validTime(job.time);
+  if (!time) return null;
+  const candidate = setLocalTime(now, time);
+
+  if (job.scheduleType === 'daily') {
+    if (candidate <= now) candidate.setDate(candidate.getDate() + 1);
+    return candidate.toISOString();
+  }
+
+  if (job.scheduleType === 'weekdays') {
+    if (candidate <= now) candidate.setDate(candidate.getDate() + 1);
+    while ([0, 6].includes(candidate.getDay())) candidate.setDate(candidate.getDate() + 1);
+    return candidate.toISOString();
+  }
+
+  const weekday = Number(job.weekday);
+  if (job.scheduleType !== 'weekly' || !Number.isInteger(weekday) || weekday < 0 || weekday > 6) return null;
+  let daysAhead = (weekday - candidate.getDay() + 7) % 7;
+  if (daysAhead === 0 && candidate <= now) daysAhead = 7;
+  candidate.setDate(candidate.getDate() + daysAhead);
+  return candidate.toISOString();
+}
+
+function parseCronField(field, min, max) {
+  const values = new Set();
+  for (const part of String(field || '').split(',')) {
+    const token = part.trim();
+    if (!token) return null;
+    const [rangeToken, stepToken] = token.split('/');
+    const step = stepToken === undefined ? 1 : Number(stepToken);
+    if (!Number.isInteger(step) || step < 1) return null;
+    let start;
+    let end;
+    if (rangeToken === '*') {
+      start = min;
+      end = max;
+    } else if (/^\d+$/.test(rangeToken)) {
+      start = Number(rangeToken);
+      end = start;
+    } else {
+      const range = rangeToken.match(/^(\d+)-(\d+)$/);
+      if (!range) return null;
+      start = Number(range[1]);
+      end = Number(range[2]);
+    }
+    if (start < min || end > max || start > end) return null;
+    for (let value = start; value <= end; value += step) values.add(value);
+  }
+  return values;
+}
+
+function parseCronExpression(expression) {
+  const fields = String(expression || '').trim().split(/\s+/);
+  if (fields.length !== 5) return null;
+  const ranges = [[0, 59], [0, 23], [1, 31], [1, 12], [0, 6]];
+  const parsed = fields.map((field, index) => parseCronField(field, ...ranges[index]));
+  return parsed.some((field) => !field) ? null : parsed;
+}
+
+function nextCronRun(expression, now = new Date()) {
+  const parsed = parseCronExpression(expression);
+  if (!parsed) return null;
+  const candidate = new Date(now);
+  candidate.setSeconds(0, 0);
+  candidate.setMinutes(candidate.getMinutes() + 1);
+  const limit = candidate.getTime() + 366 * 24 * 60 * MINUTE;
+  const [minutes, hours, days, months, weekdays] = parsed;
+  const domWildcard = String(expression).trim().split(/\s+/)[2] === '*';
+  const dowWildcard = String(expression).trim().split(/\s+/)[4] === '*';
+  while (candidate.getTime() <= limit) {
+    const dayMatches = days.has(candidate.getDate());
+    const weekdayMatches = weekdays.has(candidate.getDay());
+    const calendarMatches = domWildcard || dowWildcard ? dayMatches && weekdayMatches : dayMatches || weekdayMatches;
+    if (minutes.has(candidate.getMinutes()) && hours.has(candidate.getHours()) && months.has(candidate.getMonth() + 1) && calendarMatches) return candidate.toISOString();
+    candidate.setMinutes(candidate.getMinutes() + 1);
+  }
+  return null;
+}
+
+export function nextCronJobRun(job, now = new Date()) {
+  if (job.scheduleType === 'once') {
+    const scheduledAt = new Date(job.scheduledAt);
+    return Number.isNaN(scheduledAt.getTime()) ? null : scheduledAt.toISOString();
+  }
+  if (job.scheduleType === 'cron') return nextCronRun(job.cronExpression, now);
+  return nextPresetRun(job, now);
+}
+
+function resolveLauncherScript(launcher, scriptId) {
+  const custom = launcher?.scripts?.find((script) => script.id === scriptId);
+  if (custom) return custom;
+  const packageScript = readPackageScripts(launcher?.folder || '').find((script) => script.id === scriptId);
+  return packageScript ? { ...packageScript, command: `${launcher.executor} run ${packageScript.name}` } : null;
+}
+
+function appendArguments(script, args) {
+  const suffix = String(args || '').trim();
+  return suffix ? { ...script, command: `${script.command} ${suffix}` } : script;
+}
+
+function runTarget(job) {
+  const launchers = listLaunchers();
+  if (job.targetType === 'custom') {
+    if (!job.command?.trim()) throw new Error('Custom command is empty.');
+    if (!job.workingDirectory || !existsSync(job.workingDirectory)) throw new Error('The custom script working directory does not exist.');
+    runScript({ id: `cron-${job.id}`, alias: `Cron Job · ${job.name}`, folder: job.workingDirectory, executor: 'shell' }, { id: 'run', name: job.name, command: `${job.command}${job.args ? ` ${job.args}` : ''}` });
+    return;
+  }
+
+  if (job.targetType === 'launcher-script') {
+    const launcher = launchers.find((item) => item.id === job.launcherId);
+    const script = resolveLauncherScript(launcher, job.scriptId);
+    if (!launcher) throw new Error('The selected Launcher no longer exists.');
+    if (!script) throw new Error('The selected Launcher script no longer exists.');
+    runScript(launcher, appendArguments(script, job.args));
+    return;
+  }
+
+  if (job.targetType === 'quick-launch') {
+    const task = listGroupTasks().find((item) => item.id === job.quickLaunchId);
+    if (!task) throw new Error('The selected Quick Launch no longer exists.');
+    const failures = [];
+    for (const item of task.items) {
+      const launcher = launchers.find((entry) => entry.id === item.launcherId);
+      const script = resolveLauncherScript(launcher, item.scriptId);
+      if (!launcher || !script) {
+        failures.push('A Launcher or script is missing.');
+        continue;
+      }
+      try { runScript(launcher, appendArguments(script, job.args)); } catch (error) { failures.push(error.message); }
+    }
+    if (failures.length === task.items.length) throw new Error(failures[0]);
+    return;
+  }
+
+  throw new Error('Unsupported Cron Job target.');
+}
+
+export function executeCronJob(id) {
+  const jobs = listCronJobs();
+  const job = jobs.find((item) => item.id === id);
+  if (!job) throw new Error('Cron Job not found.');
+  if (schedulerState.runningJobs.has(id)) throw new Error('This Cron Job is already running.');
+  schedulerState.runningJobs.add(id);
+  try {
+    runTarget(job);
+    const now = new Date().toISOString();
+    const latest = listCronJobs();
+    const index = latest.findIndex((item) => item.id === id);
+    if (index >= 0) {
+      latest[index] = { ...latest[index], lastStatus: 'started', lastError: '', lastRunAt: now, updatedAt: now };
+      saveCronJobs(latest);
+    }
+    return { ok: true };
+  } catch (error) {
+    const now = new Date().toISOString();
+    const latest = listCronJobs();
+    const index = latest.findIndex((item) => item.id === id);
+    if (index >= 0) {
+      latest[index] = { ...latest[index], lastStatus: 'failed', lastError: error.message, lastRunAt: now, updatedAt: now };
+      saveCronJobs(latest);
+    }
+    throw error;
+  } finally {
+    schedulerState.runningJobs.delete(id);
+  }
+}
+
+function tick() {
+  const now = new Date();
+  const jobs = listCronJobs();
+  let changed = false;
+  for (const job of jobs) {
+    if (!job.enabled || !job.nextRunAt || new Date(job.nextRunAt) > now || schedulerState.runningJobs.has(job.id)) continue;
+    const index = jobs.findIndex((item) => item.id === job.id);
+    const nextRunAt = job.scheduleType === 'once' ? null : nextCronJobRun(job, new Date(now.getTime() + 1000));
+    jobs[index] = { ...job, enabled: job.scheduleType === 'once' ? false : job.enabled, nextRunAt, lastStatus: 'queued', lastError: '', updatedAt: now.toISOString() };
+    changed = true;
+    setImmediate(() => {
+      try { executeCronJob(job.id); } catch { /* The failure is stored on the job. */ }
+    });
+  }
+  if (changed) saveCronJobs(jobs);
+}
+
+export function startCronJobScheduler() {
+  if (schedulerState.started) return;
+  schedulerState.started = true;
+  tick();
+  schedulerState.timer = setInterval(tick, 1000);
+  schedulerState.timer.unref?.();
+}

package/server/services/mac-clipboard-helper.swift

@@ -0,0 +1,116 @@
+import AppKit
+import CoreGraphics
+import ImageIO
+import Foundation
+
+// Keep this process alive so Swift is compiled once. Pasteboard image bytes
+// are requested only after the pasteboard ownership changes.
+let outputDirectory = URL(fileURLWithPath: CommandLine.arguments[1], isDirectory: true)
+let maxInputBytes = 100 * 1024 * 1024
+let maxPixelCount = 40_000_000
+let imageTypes: [NSPasteboard.PasteboardType] = [
+    .png,
+    NSPasteboard.PasteboardType("public.jpeg"),
+    .tiff,
+    NSPasteboard.PasteboardType("public.heic")
+]
+
+func emit(_ value: [String: Any]) {
+    guard let data = try? JSONSerialization.data(withJSONObject: value),
+          let line = String(data: data, encoding: .utf8) else { return }
+    FileHandle.standardOutput.write(Data((line + "\n").utf8))
+}
+
+// Returns false only when the pasteboard advertised image data but could not
+// provide it yet. That case is retried briefly for delayed clipboard owners.
+func captureImage(_ pasteboard: NSPasteboard, changeCount: Int, startedAt: Date) -> Bool {
+    guard let type = pasteboard.types?.first(where: { imageTypes.contains($0) }) else { return true }
+    guard let input = pasteboard.data(forType: type) else {
+        return false
+    }
+    guard !input.isEmpty, input.count <= maxInputBytes else {
+        emit(["kind": "error", "stage": "image validation", "message": "Image data was empty or exceeded the 100 MiB input limit.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+        return true
+    }
+    guard let source = CGImageSourceCreateWithData(input as CFData, nil),
+          let properties = CGImageSourceCopyPropertiesAtIndex(source, 0, nil) as? [CFString: Any],
+          let width = (properties[kCGImagePropertyPixelWidth] as? NSNumber)?.intValue,
+          let height = (properties[kCGImagePropertyPixelHeight] as? NSNumber)?.intValue,
+          width > 0, height > 0,
+          width <= maxPixelCount / height else {
+        emit(["kind": "error", "stage": "image validation", "message": "Image dimensions were invalid or exceeded the 40 megapixel limit.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+        return true
+    }
+    guard let image = CGImageSourceCreateImageAtIndex(source, 0, [kCGImageSourceShouldCache: true] as CFDictionary) else {
+        emit(["kind": "error", "stage": "image decode", "message": "ImageIO could not decode the clipboard image.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+        return true
+    }
+
+    let jpeg = NSMutableData()
+    guard let destination = CGImageDestinationCreateWithData(jpeg, "public.jpeg" as CFString, 1, nil) else {
+        emit(["kind": "error", "stage": "JPEG encode", "message": "ImageIO could not create a JPEG encoder.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+        return true
+    }
+    CGImageDestinationAddImage(destination, image, [kCGImageDestinationLossyCompressionQuality: 0.75] as CFDictionary)
+    guard CGImageDestinationFinalize(destination), jpeg.length > 0 else {
+        emit(["kind": "error", "stage": "JPEG encode", "message": "ImageIO could not finish JPEG encoding.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+        return true
+    }
+
+    let filename = "capture-\(UUID().uuidString).jpg"
+    let outputURL = outputDirectory.appendingPathComponent(filename, isDirectory: false)
+    do {
+        try (jpeg as Data).write(to: outputURL, options: .atomic)
+        try FileManager.default.setAttributes([.posixPermissions: 0o600], ofItemAtPath: outputURL.path)
+        emit([
+            "kind": "image",
+            "changeCount": changeCount,
+            "sourceType": type.rawValue,
+            "width": width,
+            "height": height,
+            "bytes": jpeg.length,
+            "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000),
+            "filename": filename
+        ])
+    } catch {
+        try? FileManager.default.removeItem(at: outputURL)
+        emit(["kind": "error", "stage": "JPEG save", "message": "Could not write the temporary JPEG.", "changeCount": changeCount, "elapsedMs": Int(Date().timeIntervalSince(startedAt) * 1000)])
+    }
+    return true
+}
+
+emit(["kind": "ready"])
+let pasteboard = NSPasteboard.general
+var lastChangeCount: Int?
+var pendingChangeCount: Int?
+var pendingStartedAt = Date()
+var attemptsForPendingChange = 0
+var lastHeartbeat = Date()
+
+while true {
+    let now = Date()
+    let currentChangeCount = pasteboard.changeCount
+    if lastChangeCount == nil || currentChangeCount != lastChangeCount {
+        lastChangeCount = currentChangeCount
+        pendingChangeCount = currentChangeCount
+        pendingStartedAt = now
+        attemptsForPendingChange = 0
+    }
+
+    if let pending = pendingChangeCount {
+        attemptsForPendingChange += 1
+        let completed = captureImage(pasteboard, changeCount: pending, startedAt: pendingStartedAt)
+        if !completed && attemptsForPendingChange >= 12 {
+            emit(["kind": "error", "stage": "pasteboard read", "message": "Image data remained unavailable after 12 retries.", "changeCount": pending, "elapsedMs": Int(Date().timeIntervalSince(pendingStartedAt) * 1000)])
+        }
+        if completed || attemptsForPendingChange >= 12 {
+            pendingChangeCount = nil
+        }
+    }
+
+    if now.timeIntervalSince(lastHeartbeat) >= 2 {
+        emit(["kind": "heartbeat"])
+        lastHeartbeat = now
+    }
+    Thread.sleep(forTimeInterval: 0.25)
+}