@fitlab-ai/agent-infra 0.8.2 → 0.8.3

package/dist/lib/task/commands/issue-body.js

@@ -1,8 +1,8 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from "../resolve-ref.js";
-import { extractTitle } from "../frontmatter.js";
-import { extractSection, findSectionHeading } from "../sections.js";
-import { renderTemplateBody, PLACEHOLDER } from "../issue-form.js";
+import { resolveTaskRef } from '../resolve-ref.js';
+import { extractTitle } from '../frontmatter.js';
+import { extractSection, findSectionHeading } from '../sections.js';
+import { renderTemplateBody, PLACEHOLDER } from '../issue-form.js';
 const USAGE = `Usage: ai task issue-body <N | #N | TASK-id> [--template <path>]
 
 Print a deterministic Issue body extracted from a task's task.md.

package/dist/lib/task/commands/log.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
-import { formatTable } from "../../table.js";
-import { resolveTaskRef } from "../resolve-ref.js";
-import { parseLedger, HUMAN_DECISION_STATUSES } from "../ledger.js";
+import { formatTable } from '../../table.js';
+import { resolveTaskRef } from '../resolve-ref.js';
+import { parseLedger } from '../ledger.js';
 const USAGE = `Usage: ai task log <N | #N | TASK-id>
 
 Renders a task's activity log as a per-step status table. A step's start and
@@ -13,7 +13,7 @@ Columns: # (row) / STEP / AGENT / STARTED / DONE / NOTE
   A human-executed step shows AGENT as 'human' and, when it has no start marker,
   a '-' STARTED placeholder. Review-step NOTE also carries two human counts in
   the verdict list, right after blockers/major/minor: manual-validation
-  and human-decision (current ledger stage total).
+  and human-decision (current pending ledger stage total).
 `;
 const TABLE_HEADERS = ['#', 'STEP', 'AGENT', 'STARTED', 'DONE', 'NOTE'];
 // The activity-log H2 heading is language-dependent (zh template / en template).
@@ -100,7 +100,7 @@ function pairEntries(entries) {
 function countHumanDecisionsByStage(rows) {
     const counts = new Map();
     for (const row of rows) {
-        if (!isReviewStage(row.stage) || !HUMAN_DECISION_STATUSES.has(row.status))
+        if (!isReviewStage(row.stage) || row.status !== 'needs-human-decision')
             continue;
         counts.set(row.stage, (counts.get(row.stage) ?? 0) + 1);
     }

package/dist/lib/task/commands/ls.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { formatTable } from "../../table.js";
-import { parseTaskFrontmatter, extractTitle } from "../frontmatter.js";
-import { loadShortIdByTaskId } from "../short-id.js";
+import { formatTable } from '../../table.js';
+import { parseTaskFrontmatter, extractTitle } from '../frontmatter.js';
+import { loadShortIdByTaskId } from '../short-id.js';
 const USAGE = `Usage: ai task ls [--all | --blocked | --completed]
 
 Lists tasks under .agents/workspace/. Defaults to active tasks only.

package/dist/lib/task/commands/show.js

@@ -1,5 +1,5 @@
 import fs from 'node:fs';
-import { resolveTaskRef } from "../resolve-ref.js";
+import { resolveTaskRef } from '../resolve-ref.js';
 const USAGE = `Usage: ai task show <N | #N | TASK-id>
 
 Prints the task.md content for the matching task.

package/dist/lib/task/commands/status.js

@@ -1,12 +1,14 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
-import { commandForEngine } from "../../sandbox/shell.js";
-import { resolveTaskRef } from "../resolve-ref.js";
-import { enumerateArtifacts } from "../artifacts.js";
-import { parseTaskFrontmatter, extractTitle } from "../frontmatter.js";
-import { loadShortIdByTaskId } from "../short-id.js";
-import { parseActivityLog, pairEntries } from "./log.js";
+import { commandForEngine } from '../../sandbox/shell.js';
+import { resolveTaskRef } from '../resolve-ref.js';
+import { enumerateArtifacts } from '../artifacts.js';
+import { parseTaskFrontmatter, extractTitle } from '../frontmatter.js';
+import { loadShortIdByTaskId } from '../short-id.js';
+import { getOpenWorkflowWarnings, formatWorkflowWarningSummary } from '../workflow-warnings.js';
+import { parseActivityLog, pairEntries } from './log.js';
+import { statusCard } from '../../server/display.js';
 const USAGE = `Usage: ai task status <N | #N | TASK-id>
 
 Prints an aggregated "health check" view for a task: header, metadata,
@@ -267,6 +269,9 @@ function renderStatus(model) {
     if (model.title)
         lines.push(model.title);
     lines.push('', 'Metadata', ...renderPairs(model.metadata));
+    if (model.workflowWarnings.length > 0) {
+        lines.push('', `Workflow Warnings (${model.workflowWarnings.length} open)`, ...formatWorkflowWarningSummary(model.workflowWarnings).map((line) => `  ${line}`));
+    }
     lines.push('', `Artifacts (${model.artifacts.count})`);
     if (model.artifacts.groups.length === 0) {
         lines.push('  (none)');
@@ -302,6 +307,59 @@ function renderStatus(model) {
     ]));
     return lines;
 }
+function modelTone(model) {
+    if (model.workflow.state === 'in-progress')
+        return model.workflow.stale === 'yes' ? 'warning' : 'running';
+    if (model.metadata.some(([key, value]) => key === 'status' && value === 'completed'))
+        return 'success';
+    if (model.metadata.some(([key, value]) => key === 'status' && (value === 'blocked' || value === 'cancelled'))) {
+        return 'danger';
+    }
+    return 'info';
+}
+function buildFromResolved(input) {
+    const content = fs.readFileSync(input.taskMdPath, 'utf8');
+    const fm = parseTaskFrontmatter(content);
+    const run = input.run ?? makeRunner(input.repoRoot);
+    const artifacts = enumerateArtifacts(input.taskDir);
+    const workflow = collectWorkflow(content, input.now);
+    return {
+        taskId: input.taskId,
+        shortId: input.shortId ?? loadShortIdByTaskId(input.repoRoot).get(input.taskId) ?? DASH,
+        title: extractTitle(content),
+        metadata: collectMetadata(fm),
+        workflowWarnings: getOpenWorkflowWarnings(content),
+        artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
+        workflow,
+        runtime: collectRuntime(input.taskDir, workflow, run),
+        git: collectGit(fm.branch ?? '', run)
+    };
+}
+function buildStatusModel(refOrInput, options = {}) {
+    if (typeof refOrInput !== 'string') {
+        return buildFromResolved(refOrInput);
+    }
+    const resolved = resolveTaskRef(refOrInput);
+    if (!resolved.ok) {
+        throw new Error(resolved.message);
+    }
+    return buildFromResolved({
+        taskId: resolved.taskId,
+        taskDir: resolved.taskDir,
+        taskMdPath: resolved.taskMdPath,
+        repoRoot: resolved.repoRoot,
+        run: options.run,
+        now: options.now
+    });
+}
+function statusModelToDisplay(model) {
+    return statusCard(`Task ${model.taskId} (${model.shortId})`, modelTone(model), [
+        ['workflow', model.workflow.state],
+        ['step', model.workflow.step],
+        ['runtime', model.runtime.status],
+        ['git', model.git.uncommitted]
+    ], renderStatus(model).join('\n'));
+}
 function status(args = []) {
     if (args.length === 0 || args[0] === '--help' || args[0] === '-h') {
         process.stdout.write(USAGE);
@@ -309,30 +367,18 @@ function status(args = []) {
             process.exitCode = 1;
         return;
     }
-    const resolved = resolveTaskRef(args[0]);
-    if (!resolved.ok) {
-        process.stderr.write(`ai task status: ${resolved.message}\n`);
+    let model;
+    try {
+        model = buildStatusModel(args[0]);
+    }
+    catch (error) {
+        process.stderr.write(`ai task status: ${error instanceof Error ? error.message : String(error)}\n`);
         process.exitCode = 1;
         return;
     }
-    const content = fs.readFileSync(resolved.taskMdPath, 'utf8');
-    const fm = parseTaskFrontmatter(content);
-    const run = makeRunner(resolved.repoRoot);
-    const artifacts = enumerateArtifacts(resolved.taskDir);
-    const workflow = collectWorkflow(content);
-    const model = {
-        taskId: resolved.taskId,
-        shortId: loadShortIdByTaskId(resolved.repoRoot).get(resolved.taskId) ?? DASH,
-        title: extractTitle(content),
-        metadata: collectMetadata(fm),
-        artifacts: { count: artifacts.length, groups: groupArtifacts(artifacts) },
-        workflow,
-        runtime: collectRuntime(resolved.taskDir, workflow, run),
-        git: collectGit(fm.branch ?? '', run)
-    };
     for (const line of renderStatus(model)) {
         process.stdout.write(`${line}\n`);
     }
 }
-export { status, makeRunner, collectMetadata, groupArtifacts, collectGit, collectWorkflow, collectRuntime, renderStatus, METADATA_KEYS };
+export { status, makeRunner, buildStatusModel, collectMetadata, groupArtifacts, collectGit, collectWorkflow, collectRuntime, renderStatus, statusModelToDisplay, METADATA_KEYS };
 //# sourceMappingURL=status.js.map

package/dist/lib/task/index.js

@@ -41,48 +41,48 @@ export async function runTask(args) {
     }
     switch (subcommand) {
         case 'cat': {
-            const { cat } = await import("./commands/cat.js");
+            const { cat } = await import('./commands/cat.js');
             cat(rest);
             break;
         }
         case 'decisions':
         case 'd': {
-            const { decisions } = await import("./commands/decisions.js");
+            const { decisions } = await import('./commands/decisions.js');
             decisions(rest);
             break;
         }
         case 'files': {
-            const { files } = await import("./commands/files.js");
+            const { files } = await import('./commands/files.js');
             files(rest);
             break;
         }
         case 'grep': {
-            const { grep } = await import("./commands/grep.js");
+            const { grep } = await import('./commands/grep.js');
             grep(rest);
             break;
         }
         case 'issue-body': {
-            const { issueBody } = await import("./commands/issue-body.js");
+            const { issueBody } = await import('./commands/issue-body.js');
             issueBody(rest);
             break;
         }
         case 'log': {
-            const { log } = await import("./commands/log.js");
+            const { log } = await import('./commands/log.js');
             log(rest);
             break;
         }
         case 'ls': {
-            const { ls } = await import("./commands/ls.js");
+            const { ls } = await import('./commands/ls.js');
             ls(rest);
             break;
         }
         case 'show': {
-            const { show } = await import("./commands/show.js");
+            const { show } = await import('./commands/show.js');
             show(rest);
             break;
         }
         case 'status': {
-            const { status } = await import("./commands/status.js");
+            const { status } = await import('./commands/status.js');
             status(rest);
             break;
         }

package/dist/lib/task/resolve-ref.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync, spawnSync } from 'node:child_process';
-import { normalizeShortIdInput } from "./short-id.js";
+import { normalizeShortIdInput } from './short-id.js';
 const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
 // Flat-structured workspace dirs that hold tasks under `{dir}/{taskId}/task.md`.
 // Note: `archive` uses a three-level YYYY/MM/DD layout and is handled separately.

package/dist/lib/task/workflow-warnings.js

@@ -0,0 +1,94 @@
+import { extractSection } from './sections.js';
+const WORKFLOW_WARNING_HEADINGS = ['工作流告警', 'Workflow Warnings'];
+const WORKFLOW_WARNING_STATUSES = new Set(['open', 'resolved', 'ignored']);
+const WORKFLOW_WARNING_SEVERITIES = new Set(['IMPORTANT', 'ACTION_REQUIRED']);
+function splitTableRow(line) {
+    let value = line.trim();
+    if (!value.startsWith('|'))
+        return [];
+    value = value.replace(/^\|/, '').replace(/\|$/, '');
+    const cells = [];
+    let cell = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        if (char === '|' && !isEscapedAt(value, index)) {
+            cells.push(unescapeTableCell(cell.trim()));
+            cell = '';
+            continue;
+        }
+        cell += char;
+    }
+    cells.push(unescapeTableCell(cell.trim()));
+    return cells;
+}
+function unescapeTableCell(value) {
+    let output = '';
+    for (let index = 0; index < value.length; index += 1) {
+        const char = value[index];
+        const next = value[index + 1];
+        if (char === '\\' && (next === '\\' || next === '|')) {
+            output += next;
+            index += 1;
+            continue;
+        }
+        output += char;
+    }
+    return output;
+}
+function isEscapedAt(value, index) {
+    let backslashes = 0;
+    for (let cursor = index - 1; cursor >= 0 && value[cursor] === '\\'; cursor -= 1) {
+        backslashes += 1;
+    }
+    return backslashes % 2 === 1;
+}
+function isSeparatorRow(cells) {
+    return cells.length > 0 && cells.every((cell) => /^:?-{3,}:?$/.test(cell));
+}
+/**
+ * Parses well-formed workflow warning rows. Malformed rows are intentionally
+ * ignored here; validate-artifact is responsible for reporting structure errors.
+ */
+function parseWorkflowWarnings(content) {
+    const section = extractSection(content, WORKFLOW_WARNING_HEADINGS);
+    if (!section)
+        return [];
+    const rows = [];
+    for (const rawLine of section.split(/\r?\n/)) {
+        const cells = splitTableRow(rawLine);
+        if (cells.length === 0)
+            continue;
+        if ((cells[0] ?? '').toLowerCase() === 'id')
+            continue;
+        if (isSeparatorRow(cells))
+            continue;
+        if (cells.length < 11)
+            continue;
+        rows.push({
+            id: cells[0] ?? '',
+            time: cells[1] ?? '',
+            step: cells[2] ?? '',
+            severity: cells[3] ?? '',
+            code: cells[4] ?? '',
+            status: cells[5] ?? '',
+            target: cells[6] ?? '',
+            message: cells[7] ?? '',
+            action: cells[8] ?? '',
+            resolvedAt: cells[9] ?? '',
+            resolution: cells[10] ?? ''
+        });
+    }
+    return rows;
+}
+function getOpenWorkflowWarnings(content) {
+    return parseWorkflowWarnings(content).filter((warning) => warning.status === 'open');
+}
+function formatWorkflowWarningSummary(warnings) {
+    return warnings.map((warning) => {
+        const target = warning.target ? ` ${warning.target}` : '';
+        const action = warning.action ? ` - ${warning.action}` : '';
+        return `${warning.id} [${warning.severity}] ${warning.code}${target}${action}`;
+    });
+}
+export { WORKFLOW_WARNING_HEADINGS, WORKFLOW_WARNING_STATUSES, WORKFLOW_WARNING_SEVERITIES, parseWorkflowWarnings, getOpenWorkflowWarnings, formatWorkflowWarningSummary };
+//# sourceMappingURL=workflow-warnings.js.map

package/dist/lib/update.js

@@ -1,9 +1,9 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { info, ok, err } from "./log.js";
-import { resolveTemplateDir } from "./paths.js";
-import { renderFile, copySkillDir, KNOWN_PLATFORMS } from "./render.js";
-import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from "./builtin-tuis.js";
+import { info, ok, err } from './log.js';
+import { resolveTemplateDir } from './paths.js';
+import { renderFile, copySkillDir, KNOWN_PLATFORMS } from './render.js';
+import { isPathOwnedByDisabledTUI, resolveEnabledTUIs } from './builtin-tuis.js';
 const defaults = JSON.parse(fs.readFileSync(new URL('./defaults.json', import.meta.url), 'utf8'));
 const CONFIG_DIR = '.agents';
 const CONFIG_PATH = path.join(CONFIG_DIR, '.airc.json');

package/lib/defaults.json

@@ -14,6 +14,7 @@
       "gemini-cli",
       "opencode"
     ],
+    "refreshIntervalDays": 7,
     "dockerfile": null,
     "vm": {
       "cpu": null,

package/lib/sandbox/clipboard/bridge.ts

@@ -30,8 +30,13 @@ type BridgeOptions = {
   createDetector?: () => CtrlVDetector;
 };
 
+type TextImageClipboardAdapter = ClipboardAdapter & {
+  readImageFromText?: (text: string) => Buffer | null;
+};
+
 const FALLBACK_PREFIX = 'Warning: clipboard image paste bridge disabled';
 const PARTIAL_ESCAPE_FLUSH_MS = 30;
+const BRACKETED_PASTE_RE = /^\x1b\[200~([\s\S]*)\x1b\[201~$/u;
 
 // Node's stdin.setRawMode(true) uses libuv's RAW mode, which (unlike the
 // cfmakeraw that `docker exec -it` applies on the non-bridge path) keeps ONLCR
@@ -147,7 +152,7 @@ async function runBridge({
     clearFlushTimer();
     for (const token of detector.feed(inputDecoder.write(chunk))) {
       if (token.kind === 'text') {
-        child.write(token.raw);
+        handleText(token.raw, child);
       } else {
         handleCtrlV(token, child);
       }
@@ -157,7 +162,7 @@ async function runBridge({
         flushTimer = null;
         for (const token of detector.flush()) {
           if (token.kind === 'text') {
-            child.write(token.raw);
+            handleText(token.raw, child);
           } else {
             handleCtrlV(token, child);
           }
@@ -169,6 +174,37 @@ async function runBridge({
   const onSigint = () => child.kill('SIGINT');
   const onSigterm = () => child.kill('SIGTERM');
 
+  function writeImagePaste(png: Buffer, target: PtyProcess): void {
+    const filename = pngClipboardFilename(png);
+    writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
+    pruneClipboardDir(clipboardHostDir(home));
+    target.write(buildBracketedPaste(containerClipboardPath(filename)));
+  }
+
+  function handleText(raw: string, target: PtyProcess): void {
+    const textAdapter = adapter as TextImageClipboardAdapter;
+    const pastedText = extractSinglePathPaste(raw);
+    if (!textAdapter.readImageFromText || pastedText === null) {
+      target.write(raw);
+      return;
+    }
+
+    try {
+      const png = textAdapter.readImageFromText(pastedText);
+      if (!png) {
+        target.write(raw);
+        return;
+      }
+      writeImagePaste(png, target);
+    } catch (error) {
+      target.write(raw);
+      if (!warnedPasteFailure) {
+        warnedPasteFailure = true;
+        writeStderr(`Warning: clipboard image paste failed; forwarded pasted text (${error instanceof Error ? error.message : 'unknown error'})\n`);
+      }
+    }
+  }
+
   function handleCtrlV(match: CtrlVMatch, target: PtyProcess): void {
     try {
       // readImagePng returns null both for "no image on clipboard" and for
@@ -181,10 +217,7 @@ async function runBridge({
         target.write(match.raw);
         return;
       }
-      const filename = pngClipboardFilename(png);
-      writeClipboardPngAtomic(clipboardHostDir(home), filename, png);
-      pruneClipboardDir(clipboardHostDir(home));
-      target.write(buildBracketedPaste(containerClipboardPath(filename)));
+      writeImagePaste(png, target);
     } catch (error) {
       target.write(match.raw);
       if (!warnedPasteFailure) {
@@ -219,14 +252,14 @@ async function runBridge({
     try {
       for (const token of detector.feed(inputDecoder.end())) {
         if (token.kind === 'text') {
-          child.write(token.raw);
+          handleText(token.raw, child);
         } else {
           handleCtrlV(token, child);
         }
       }
       for (const token of detector.flush()) {
         if (token.kind === 'text') {
-          child.write(token.raw);
+          handleText(token.raw, child);
         }
       }
     } catch {
@@ -244,6 +277,15 @@ async function runBridge({
   }
 }
 
+function extractSinglePathPaste(raw: string): string | null {
+  const match = raw.match(BRACKETED_PASTE_RE);
+  const text = (match ? match[1] : raw)?.trim();
+  if (!text || /[\r\n]/u.test(text)) {
+    return null;
+  }
+  return text;
+}
+
 function onceExit(
   child: PtyProcess,
   stdin: NodeJS.ReadStream

package/lib/sandbox/clipboard/index.ts

@@ -1,7 +1,9 @@
 import { platform } from 'node:os';
 import { createDarwinClipboardAdapter, type DarwinClipboardAdapter } from './darwin.ts';
+import { createLinuxClipboardAdapter, type LinuxClipboardAdapter } from './linux.ts';
+import { createWin32ClipboardAdapter, type Win32ClipboardAdapter } from './win32.ts';
 
-export type ClipboardAdapter = DarwinClipboardAdapter;
+export type ClipboardAdapter = DarwinClipboardAdapter | LinuxClipboardAdapter | Win32ClipboardAdapter;
 
 export function createClipboardAdapter({
   platformName = platform()
@@ -10,12 +12,9 @@ export function createClipboardAdapter({
     case 'darwin':
       return createDarwinClipboardAdapter();
     case 'linux':
-      // Future work: dispatch based on $WAYLAND_DISPLAY (wl-paste) or $DISPLAY (xclip);
-      // see Issue #386 follow-up. Returning null disables the bridge for now.
-      return null;
+      return createLinuxClipboardAdapter();
     case 'win32':
-      // Future work: native Win32 clipboard reader. Returning null disables the bridge.
-      return null;
+      return createWin32ClipboardAdapter();
     default:
       return null;
   }

package/lib/sandbox/clipboard/linux.ts

@@ -0,0 +1,124 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import type { ExecFileSyncOptions } from 'node:child_process';
+
+const PROBE_TIMEOUT_MS = 2_000;
+const READ_IMAGE_TIMEOUT_MS = 5_000;
+const PNG_MAGIC = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+
+type ExecFn = (cmd: string, args: string[], options?: ExecFileSyncOptions) => Buffer | string;
+type ExecToFileFn = (cmd: string, args: string[], outputPath: string, timeout: number) => void;
+
+type LinuxBackend =
+  | { kind: 'wayland'; command: 'wl-paste' }
+  | { kind: 'x11'; command: 'xclip' };
+
+export type LinuxClipboardAdapter = {
+  available(): { ok: true } | { ok: false; reason: string };
+  readImagePng(): Buffer | null;
+};
+
+export function createLinuxClipboardAdapter({
+  env = process.env,
+  execFn = execFileSync,
+  execToFileFn = execToFile,
+  mkdtempFn = fs.mkdtempSync,
+  readFileFn = fs.readFileSync,
+  rmFn = fs.rmSync
+}: {
+  env?: NodeJS.ProcessEnv;
+  execFn?: ExecFn;
+  execToFileFn?: ExecToFileFn;
+  mkdtempFn?: typeof fs.mkdtempSync;
+  readFileFn?: typeof fs.readFileSync;
+  rmFn?: typeof fs.rmSync;
+} = {}): LinuxClipboardAdapter {
+  return {
+    available() {
+      const backend = selectBackend(env);
+      try {
+        execFn(backend.command, versionArgs(backend), {
+          encoding: 'utf8',
+          timeout: PROBE_TIMEOUT_MS
+        });
+        return { ok: true };
+      } catch {
+        return { ok: false, reason: unavailableReason(backend) };
+      }
+    },
+    readImagePng() {
+      const backend = selectBackend(env);
+      try {
+        const mimeTypes = String(execFn(backend.command, mimeArgs(backend), {
+          encoding: 'utf8',
+          timeout: PROBE_TIMEOUT_MS
+        }));
+        if (!hasPngMime(mimeTypes)) {
+          return null;
+        }
+
+        const tmpDir = mkdtempFn(path.join(os.tmpdir(), 'agent-infra-clipboard-'));
+        const outputPath = path.join(tmpDir, 'clipboard.png');
+        try {
+          execToFileFn(backend.command, imageArgs(backend), outputPath, READ_IMAGE_TIMEOUT_MS);
+          const png = Buffer.from(readFileFn(outputPath));
+          return isPng(png) ? png : null;
+        } finally {
+          rmFn(tmpDir, { recursive: true, force: true });
+        }
+      } catch {
+        return null;
+      }
+    }
+  };
+}
+
+function selectBackend(env: NodeJS.ProcessEnv): LinuxBackend {
+  return env.WAYLAND_DISPLAY?.trim()
+    ? { kind: 'wayland', command: 'wl-paste' }
+    : { kind: 'x11', command: 'xclip' };
+}
+
+function versionArgs(backend: LinuxBackend): string[] {
+  return backend.kind === 'wayland' ? ['--version'] : ['-version'];
+}
+
+function mimeArgs(backend: LinuxBackend): string[] {
+  return backend.kind === 'wayland'
+    ? ['--list-types']
+    : ['-selection', 'clipboard', '-t', 'TARGETS', '-o'];
+}
+
+function imageArgs(backend: LinuxBackend): string[] {
+  return backend.kind === 'wayland'
+    ? ['-t', 'image/png']
+    : ['-selection', 'clipboard', '-t', 'image/png', '-o'];
+}
+
+function unavailableReason(backend: LinuxBackend): string {
+  return backend.kind === 'wayland'
+    ? 'Wayland clipboard tool wl-paste is unavailable; install wl-clipboard to enable image paste'
+    : 'X11 clipboard tool xclip is unavailable; install xclip to enable image paste';
+}
+
+function hasPngMime(output: string): boolean {
+  return output.split(/\s+/u).some((type) => type === 'image/png');
+}
+
+function execToFile(cmd: string, args: string[], outputPath: string, timeout: number): void {
+  const fd = fs.openSync(outputPath, 'w', 0o600);
+  try {
+    execFileSync(cmd, args, {
+      timeout,
+      stdio: ['ignore', fd, 'pipe']
+    });
+  } finally {
+    fs.closeSync(fd);
+  }
+}
+
+function isPng(buffer: Buffer): boolean {
+  return buffer.length >= PNG_MAGIC.length && PNG_MAGIC.every((byte, index) => buffer[index] === byte);
+}