@fitlab-ai/agent-infra 0.8.2 → 0.8.4

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/cp.ts

@@ -5,8 +5,9 @@ import { platform as currentPlatform, tmpdir as defaultTmpdir } from 'node:os';
 import path from 'node:path';
 import { parseArgs } from 'node:util';
 import { createClipboardAdapter, type ClipboardAdapter } from './sandbox/clipboard/index.ts';
+import { RECEIVER_CAPABILITY, receiveRemoteClipboardPng } from './sandbox/clipboard/inbox.ts';
 
-const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS NSPasteboard over ssh/scp.\n';
+const USAGE = 'Usage: ai cp <ssh-alias>\n\nCopy the local clipboard image (PNG) to a remote macOS clipboard or Linux sandbox over SSH.\n';
 const COMMAND_TIMEOUT_MS = 30_000;
 
 export type SpawnResult = {
@@ -65,6 +66,21 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     writeStderr = (chunk: string) => process.stderr.write(chunk)
   } = deps;
 
+  if (args.length === 1 && args[0] === '--remote-receive-capability') {
+    if (platform === 'linux') writeStdout(`${RECEIVER_CAPABILITY}\n`);
+    return platform === 'linux' ? 0 : 1;
+  }
+  if (args.length === 2 && args[0] === '--remote-receive-v1') {
+    try {
+      const result = receiveRemoteClipboardPng(process.env.HOME || process.env.USERPROFILE || '', args[1]!, platform);
+      writeStdout(`${result}\n`);
+      return 0;
+    } catch (error) {
+      writeStderr(`${error instanceof Error ? error.message : 'clipboard receive failed'}\n`);
+      return 1;
+    }
+  }
+
   if (args[0] === '--help' || args[0] === '-h' || args[0] === 'help') {
     writeStdout(USAGE);
     return 0;
@@ -110,6 +126,35 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     writeFileFn(localPng, png);
 
     remotePath = `/tmp/agent-infra-cp-${randomId()}.png`;
+    const remoteSystem = spawnFn('ssh', [
+      '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'uname', '-s'
+    ]);
+    if (remoteSystem.status !== 0) {
+      writeStderr(`failed to detect remote platform on ${alias}:\n${commandDetail(remoteSystem)}\n`);
+      return 1;
+    }
+    const remotePlatform = remoteSystem.stdout.trim();
+    if (remotePlatform !== 'Darwin' && remotePlatform !== 'Linux') {
+      writeStderr(`unsupported remote platform on ${alias}: ${remotePlatform || 'unknown'}\n`);
+      return 1;
+    }
+    if (remotePlatform === 'Linux') {
+      const homeCheck = spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'test', '-d', '$HOME/.agent-infra'
+      ]);
+      if (homeCheck.status !== 0) {
+        writeStderr(`remote agent-infra installation is missing on ${alias}\n`);
+        return 1;
+      }
+      const capability = spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-capability'
+      ]);
+      if (capability.status !== 0 || capability.stderr !== '' || capability.stdout.replace(/\n$/u, '') !== RECEIVER_CAPABILITY) {
+        writeStderr(`remote agent-infra clipboard receiver is unavailable or incompatible on ${alias}; update agent-infra\n`);
+        return 1;
+      }
+    }
+
     const upload = spawnFn('scp', [
       '-o',
       'BatchMode=yes',
@@ -124,25 +169,21 @@ export async function cmdCp(args: string[], deps: CpDeps = {}): Promise<number>
     }
     uploaded = true;
 
-    // Remote write currently targets macOS only: it pipes an AppleScript to the
-    // remote `osascript` to set its NSPasteboard. This is the extension point for
-    // other remote platforms later (e.g. dispatch on remote OS to wl-copy/xclip
-    // on Linux); a non-macOS remote fails here with a clear non-zero error today.
-    const setRemote = spawnFn('ssh', [
-      '-o',
-      'BatchMode=yes',
-      '-o',
-      'ConnectTimeout=10',
-      alias,
-      'osascript',
-      '-'
-    ], remoteSetScript(remotePath));
+    const setRemote = remotePlatform === 'Darwin'
+      ? spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'osascript', '-'
+      ], remoteSetScript(remotePath))
+      : spawnFn('ssh', [
+        '-o', 'BatchMode=yes', '-o', 'ConnectTimeout=10', alias, 'ai', 'cp', '--remote-receive-v1', remotePath
+      ]);
     if (setRemote.status !== 0) {
       writeStderr(`failed to set remote clipboard on ${alias}:\n${commandDetail(setRemote)}\n`);
       return 1;
     }
 
-    writeStdout(`copied clipboard image to ${alias}\n`);
+    writeStdout(remotePlatform === 'Linux'
+      ? `uploaded clipboard image to ${alias}; return to the SSH session and press Ctrl+V\n`
+      : `copied clipboard image to ${alias}\n`);
     return 0;
   } finally {
     if (uploaded && remotePath) {

package/lib/defaults.json

@@ -14,6 +14,7 @@
       "gemini-cli",
       "opencode"
     ],
+    "refreshIntervalDays": 7,
     "dockerfile": null,
     "vm": {
       "cpu": null,
@@ -51,6 +52,7 @@
       "**/test-integration.*",
       "**/test.*",
       "**/upgrade-dependency.*",
+      ".agents/rules/testing-discipline.*",
       ".agents/skills/post-release/SKILL.*",
       ".agents/skills/release/SKILL.*",
       ".agents/skills/test-integration/SKILL.*",

package/lib/sandbox/capture.ts

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import { loadConfig } from './config.ts';
 import { containerNameCandidates, sandboxBranchLabel, sandboxLabel } from './constants.ts';
 import { detectEngine } from './engine.ts';
+import { commandForEngine } from './shell.ts';
 import { hostTimezoneEnvFlags, terminalEnvFlags } from './commands/enter.ts';
 import {
   fetchSandboxRows,
@@ -95,12 +96,12 @@ function buildRunScript(params: {
   return `#!/bin/sh
 set -u
 cd /workspace
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/started_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/started_at
 printf '%s\\n' running > ${runDir}/status
 ${command}
 code=$?
 printf '%s\\n' "$code" > ${runDir}/exit_code
-date "+%Y-%m-%d %H:%M:%S%:z" > ${runDir}/finished_at
+date "+%Y-%m-%d %H:%M:%S%z" | sed 's/\\([+-][0-9][0-9]\\)\\([0-9][0-9]\\)$/\\1:\\2/' > ${runDir}/finished_at
 if [ "$code" -eq 0 ]; then
   printf '%s\\n' completed > ${runDir}/status
 else
@@ -202,7 +203,8 @@ export async function runInSandbox(
     '-lc',
     buildTmuxLauncher({ request, runId })
   ];
-  const result = await (options.spawn ?? spawnCapture)('docker', dockerArgs);
+  const command = commandForEngine(engine, 'docker', dockerArgs);
+  const result = await (options.spawn ?? spawnCapture)(command.cmd, command.args);
   return {
     ...result,
     run: {

package/lib/sandbox/clipboard/bridge.ts

@@ -9,6 +9,7 @@ import {
   pruneClipboardDir,
   writeClipboardPngAtomic
 } from './paths.ts';
+import { isClipboardInboxReadable, readPendingClipboardPath } from './inbox.ts';
 import { commandForEngine, restoreTerminal, runInteractiveEngine, runOkEngine } from '../shell.ts';
 import { loadNodePty, type NodePty, type PtyProcess } from './node-pty.ts';
 
@@ -30,8 +31,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
@@ -80,13 +86,9 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   if (!stdin.isTTY || !stdout.isTTY) {
     return fallback('host stdin/stdout is not a TTY');
   }
-  if (!adapter) {
-    return fallback('no clipboard adapter available on this platform');
-  }
-  const available = adapter.available();
-  if (!available.ok) {
-    return fallback(available.reason);
-  }
+  const available = adapter?.available() ?? { ok: false as const, reason: 'no clipboard adapter available on this platform' };
+  const inboxReady = isClipboardInboxReadable(home);
+  if (!available.ok && !inboxReady) return fallback(available.reason);
   if (!runOk(engine, 'docker', ['exec', container, 'sh', '-c', '[ -d /clipboard ] && [ -r /clipboard ]'])) {
     return fallback('container /clipboard mount is missing; rebuild the sandbox to enable image paste');
   }
@@ -114,7 +116,7 @@ export async function runInteractiveWithClipboardBridge(options: BridgeOptions):
   return runBridge({
     child,
     home,
-    adapter,
+    adapter: available.ok ? adapter : null,
     writeStderr,
     stdin,
     stdout,
@@ -133,7 +135,7 @@ async function runBridge({
 }: {
   child: PtyProcess;
   home: string;
-  adapter: ClipboardAdapter;
+  adapter: ClipboardAdapter | null;
   writeStderr: (chunk: string) => unknown;
   stdin: NodeJS.ReadStream;
   stdout: NodeJS.WriteStream;
@@ -147,7 +149,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 +159,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,22 +171,55 @@ 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 | null;
+    const pastedText = extractSinglePathPaste(raw);
+    if (!textAdapter || !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 {
+      const pendingPath = readPendingClipboardPath(home);
+      if (pendingPath) {
+        target.write(buildBracketedPaste(pendingPath));
+        return;
+      }
       // readImagePng returns null both for "no image on clipboard" and for
       // unexpected read failures; both cases forward the original Ctrl+V so
       // the container app handles it as a regular keystroke. The throw branch
       // below only fires on truly unexpected exceptions (e.g. fs write
       // errors writing to the host clipboard dir).
-      const png = adapter.readImagePng();
+      const png = adapter?.readImagePng() ?? null;
       if (!png) {
         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 +254,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 +279,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/inbox.ts

@@ -0,0 +1,83 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import {
+  clipboardHostDir,
+  containerClipboardPath,
+  pngClipboardFilename,
+  pruneClipboardDir,
+  writeClipboardPngAtomic
+} from './paths.ts';
+
+export const RECEIVER_CAPABILITY = 'AGENT_INFRA_CLIPBOARD_RECEIVER:v1';
+const MARKER = '.pending.json';
+const PNG_SIGNATURE = Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]);
+const HASHED_PNG = /^[a-f0-9]{16}\.png$/u;
+const REMOTE_TEMP = /^agent-infra-cp-[0-9a-f-]{36}\.png$/u;
+
+export function isClipboardInboxReadable(home: string): boolean {
+  const dir = clipboardHostDir(home);
+  try {
+    fs.accessSync(dir, fs.constants.R_OK);
+    return fs.statSync(dir).isDirectory();
+  } catch {
+    return false;
+  }
+}
+
+export function receiveRemoteClipboardPng(home: string, tempPath: string, platformName: NodeJS.Platform = process.platform): string {
+  if (platformName !== 'linux') throw new Error('remote clipboard receiver requires Linux');
+  if (path.dirname(tempPath) !== '/tmp' || !REMOTE_TEMP.test(path.basename(tempPath))) {
+    throw new Error('invalid clipboard upload path');
+  }
+  const signature = Buffer.alloc(PNG_SIGNATURE.length);
+  const fd = fs.openSync(tempPath, 'r');
+  let signatureBytes: number;
+  try {
+    signatureBytes = fs.readSync(fd, signature, 0, signature.length, 0);
+  } finally {
+    fs.closeSync(fd);
+  }
+  if (signatureBytes !== PNG_SIGNATURE.length || !signature.equals(PNG_SIGNATURE)) {
+    throw new Error('uploaded clipboard file is not a PNG');
+  }
+  const png = fs.readFileSync(tempPath);
+  const dir = clipboardHostDir(home);
+  if (!fs.existsSync(path.dirname(dir))) throw new Error('agent-infra is not installed on this host');
+  const filename = pngClipboardFilename(png);
+  writeClipboardPngAtomic(dir, filename, png);
+  pruneClipboardDir(dir);
+  const markerTmp = path.join(dir, `.${MARKER}.${process.pid}.tmp`);
+  fs.writeFileSync(markerTmp, JSON.stringify({ version: 1, filename, createdAt: new Date().toISOString() }) + '\n', { mode: 0o600 });
+  fs.renameSync(markerTmp, path.join(dir, MARKER));
+  return containerClipboardPath(filename);
+}
+
+export function readPendingClipboardPath(home: string): string | null {
+  const dir = clipboardHostDir(home);
+  const markerPath = path.join(dir, MARKER);
+  let markerText: string;
+  try {
+    markerText = fs.readFileSync(markerPath, 'utf8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+
+  let marker: { version?: unknown; filename?: unknown };
+  try {
+    marker = JSON.parse(markerText) as { version?: unknown; filename?: unknown };
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  if (marker.version !== 1 || typeof marker.filename !== 'string' || !HASHED_PNG.test(marker.filename)) {
+    throw new Error('invalid clipboard pending marker');
+  }
+  const filePath = path.join(dir, marker.filename);
+  try {
+    const stat = fs.lstatSync(filePath);
+    if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('pending clipboard image is not a regular file');
+  } catch (error) {
+    throw new Error('invalid clipboard pending marker', { cause: error });
+  }
+  return containerClipboardPath(marker.filename);
+}

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;
   }