Harden screenshot input delivery and recovery

docs/screenshot-input.md

@@ -1,6 +1,6 @@
 # Screenshot input
 
-Status: proposed
+Status: implemented in draft PR
 
 Date: 2026-08-05
 
@@ -61,10 +61,10 @@ denominator:
 | Harness | Observed path as of this design | First implementation |
 |---|---|---|
 | Claude Code | accepts an image path in a prompt; native terminals also support image paste/drop | explicit absolute path in the prompt |
-| Codex | `-i/--image` supports initial images; in-session image paste reads the server clipboard | explicit path, allowing `view_image`; native first-turn flag later |
+| Codex | `-i/--image` supports initial images; in-session image paste reads the server clipboard | native `-i` on the first turn plus an explicit path fallback |
 | Gemini CLI | `@<path>` injects supported images as multimodal context | `@<absolute-path>` |
 | opencode | TUI image drop and `opencode run -f/--file` are supported | explicit/drop-style absolute path |
-| Hermes | `--image` and the interactive `/image <path>` command are supported | `/image <absolute-path>` adapter, with explicit-path fallback |
+| Hermes | the current TUI supports `/image <path>` and detects a pasted standalone image path | `/image <absolute-path>` adapter, with explicit-path fallback |
 | OpenClaw | no stable image-attachment CLI contract was verified | explicit path, best effort |
 
 Every adapter must retain the explicit-path fallback. CLI flags and TUI commands
@@ -226,6 +226,10 @@ session's own directory, and never join an arbitrary browser-supplied filename.
   whose newest file is older than seven days. The grace period covers a crash
   between session persistence and upload completion.
 - Failed and aborted uploads delete their temporary file immediately.
+- Each session is capped at 200 stored screenshots and 500 MiB. Uploads for one
+  session are serialized so concurrent requests cannot race the quota check.
+- Pruning and session deletion use asynchronous filesystem operations so a
+  large attachment store cannot block terminal I/O.
 
 No separate database is required. The session-scoped directory, validated id,
 extension, and `stat` provide the metadata needed in v1.
@@ -262,7 +266,8 @@ and abort with `413` above 25 MiB. Once complete:
 
 1. Read the first small header from the temporary file.
 2. Detect PNG, JPEG, GIF, or WebP by magic bytes.
-3. Reject an unsupported or mismatched body with `415`.
+3. Reject unsupported or malformed bytes with `415`. A missing, aliased, or
+   incorrect request `Content-Type` does not override byte detection.
 4. Rename to the detected extension atomically.
 5. Return `201`.
 
@@ -358,15 +363,12 @@ trace.
 ### 8.2 Adapter interface
 
 Keep version-sensitive behavior in one module rather than scattered across React
-components and `runner.js`:
+components and `runner.js`. The implementation exposes the universal formatted
+prompt and any native prelude commands separately:
 
 ```ts
-interface AttachmentDelivery {
-  prompt: string;
-  prelude?: Array<{ text: string; submit: boolean; settleMs?: number }>;
-}
-
-formatAttachmentDelivery(cli, text, paths): AttachmentDelivery
+formatAttachmentDelivery(cli, text, images): string
+formatAttachmentPrelude(cli, images): string[]
 ```
 
 Initial adapters:
@@ -376,9 +378,10 @@ Initial adapters:
   prompt. If the command is unavailable, use the universal prompt.
 - all others: use the universal prompt.
 
-Codex `--image`, opencode `--file`, and other native launch flags are optional
-follow-ups. They should be added only with version probes/tests and must not be
-required for the feature to function.
+opencode `--file` and other native launch flags are optional follow-ups. Codex
+uses its installed `--image` support on a first turn; every adapter retains the
+explicit path so a missing or changed native flag is not the only route to the
+file.
 
 ### 8.3 First prompt without a boot race
 
@@ -391,8 +394,10 @@ two-step browser flow—create the session, then upload to its attachment scope
 2. Upload all pending images to the returned session id.
 3. `POST /api/sessions/:id/input` with text and attachment ids.
 4. If the session has never started and its CLI has `withPrompt`, store the
-   fully formatted prompt as `pendingPrompt` and call `ensureRunning()`.
-5. `commandFor()` consumes `pendingPrompt` on the first launch as it does today.
+   fully formatted prompt as `pendingPrompt`; for Codex, also retain the
+   validated paths as `pendingImagePaths`; then call `ensureRunning()`.
+5. `commandFor()` consumes those fields on the first launch, adding one Codex
+   `-i` flag per image, and clears them once the PTY starts.
 
 Only resumed or already-started sessions use the existing boot-then-type path.
 If attachment upload fails after session creation, keep the stopped session and
@@ -401,19 +406,26 @@ the browser draft. Automatically deleting it would make recovery surprising.
 ### 8.4 Terminal insertion
 
 Live terminal paste/drop does not call `/input`, because `/input` submits a turn.
-After upload, the browser uses `insertText` returned by the attachment endpoint:
+After upload, it asks the server to insert the resolved attachments without a
+Return key:
 
-```ts
-term.paste(uploaded.insertText)
+```http
+POST /api/sessions/:id/attachments/insert
+Content-Type: application/json
+
+{"attachmentIds":["att_74e0f69dc9ed772cb685999e"]}
 ```
 
-`paste()` retains xterm's bracketed-paste handling. The browser claims terminal
-control before insertion exactly as it does for ordinary paste. A watcher that
-cannot claim control reports `Image uploaded, but this pane is watching—interact
-and try again` rather than pretending the path reached the CLI.
+The server writes `insertText` to the running PTY and acknowledges only after
+the write is accepted. It never sends Return. If the process stops after upload,
+the browser says the image was saved but not inserted and retains its attachment
+id behind a Retry action. This avoids treating a browser-local xterm paste as
+proof that a disconnected or non-controlling pane reached the CLI. Completed
+terminal insertions are idempotent by attachment id, so retrying after a lost
+HTTP response cannot paste the same path twice.
 
-Hermes is the one useful native exception: the browser may send `/image <path>`
-and Return, wait for the command to settle, and then restore focus without
+Hermes is the one useful native exception: the server may send `/image <path>`
+and Return, briefly wait for the command to settle, and then restore focus without
 submitting the actual prompt. This logic should still live behind the same
 adapter and fall back to `insertText`.
 
@@ -421,7 +433,7 @@ adapter and fall back to `insertText`.
 
 Add a small module, for example `web/src/lib/imageAttachments.ts`, containing:
 
-- accepted MIME types and client-side 25 MiB check;
+- accepted MIME hints, byte/size checks, and client-side 25 MiB check;
 - `imageFilesFromTransfer(DataTransfer)`;
 - `transferMayContainImage(DataTransfer)`;
 - duplicate suppression across `items` and `files`;
@@ -545,6 +557,7 @@ may reuse already uploaded ids while uploading only failed files.
 - The byte limit trips during streaming and leaves no partial file.
 - Aborted requests leave no partial file.
 - Concurrent uploads produce unique files.
+- Concurrent uploads cannot race the per-session byte/count quota.
 - Attachment ids cannot cross sessions or traverse paths.
 - Preview headers include CSP and `nosniff`.
 - A structured prompt rejects if any referenced attachment is absent.
@@ -561,7 +574,11 @@ may reuse already uploaded ids while uploading only failed files.
 - Plain-text paste is unchanged.
 - Removing a chip revokes its preview and excludes it from upload.
 - A multi-image submission waits for every upload before `/input`.
-- Terminal paste uploads and inserts a path without Return.
+- Every chip mutation remains disabled for the complete multi-image send.
+- Terminal paste receives a server acknowledgement and inserts without Return.
+- A terminal stopped after upload reports saved-but-not-inserted, disables new
+  attachments, and can retry the stored attachment after restart.
+- Remote composers show a visible explanation on touch layouts.
 - Terminal image drop does not trigger pane movement.
 - Pane movement data does not trigger the image drop UI.
 - The mobile fallback textarea handles both image and text paste.

server/package.json

@@ -13,7 +13,8 @@
   "scripts": {
     "start": "node src/index.js",
     "dev": "node --watch src/index.js",
-    "test:ui": "node terminal-ui.test.mjs",
+    "test:ui": "node terminal-ui.test.mjs && node screenshot-input.test.mjs",
+    "test:screenshots": "node screenshot-input.test.mjs",
     "test": "node test/attachments.test.mjs && node test/repin.test.mjs && node test/opencode-resume.test.mjs && node test/terminal-modes.test.mjs && node migration.test.mjs && node resize.test.mjs"
   },
   "engines": {

server/screenshot-input.test.mjs

@@ -0,0 +1,249 @@
+#!/usr/bin/env node
+/**
+ * Screenshot-input integration checks in a real browser:
+ *   - stored bytes, response MIME, and preview headers come from detection;
+ *   - a stopped terminal never reports a false insertion success;
+ *   - an uploaded-but-uninserted screenshot can be retried without reupload;
+ *   - attachment chips cannot mutate an in-flight send;
+ *   - remote limitations are visible rather than tooltip-only.
+ *
+ * Set SCREENSHOT_PUBLIC_DIR to a prebuilt web/dist to skip the build.
+ */
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { spawn, spawnSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { chromium } from 'playwright';
+
+const HERE = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.dirname(HERE);
+const DATA_DIR = fs.mkdtempSync(path.join(os.tmpdir(), 'am-screenshot-ui-'));
+const PUBLIC_DIR = process.env.SCREENSHOT_PUBLIC_DIR || path.join(DATA_DIR, 'public');
+const API = 'http://127.0.0.1:7896';
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+const png = Buffer.alloc(45);
+Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(png);
+png.writeUInt32BE(13, 8); Buffer.from('IHDR').copy(png, 12);
+png.writeUInt32BE(1, 16); png.writeUInt32BE(1, 20);
+Buffer.from('IEND').copy(png, 37);
+
+let failures = 0;
+const check = (name, ok, detail = '') => {
+  console.log(`${ok ? 'PASS' : 'FAIL'}  ${name}${detail ? `  ${detail}` : ''}`);
+  if (!ok) failures += 1;
+};
+const waitFor = async (fn, timeout = 15_000) => {
+  const until = Date.now() + timeout;
+  while (Date.now() < until) {
+    try { if (await fn()) return true; } catch {}
+    await sleep(100);
+  }
+  return false;
+};
+const apiJson = async (url, init) => {
+  const response = await fetch(`${API}${url}`, init);
+  const body = await response.json().catch(() => ({}));
+  return { response, body };
+};
+
+if (!process.env.SCREENSHOT_PUBLIC_DIR) {
+  const build = spawnSync('npm', ['run', 'build', '--', '--outDir', PUBLIC_DIR], {
+    cwd: path.join(ROOT, 'web'), encoding: 'utf8',
+  });
+  if (build.status !== 0) throw new Error(`web build failed:\n${build.stdout}\n${build.stderr}`);
+}
+
+const backend = spawn('node', ['src/index.js'], {
+  cwd: HERE,
+  env: {
+    ...process.env,
+    PORT: '7896', DATA_DIR, PUBLIC_DIR, AM_BASHRC: '/nonexistent', SPACE_HOST: '',
+    AM_TEST_REPAINT_CMD: 'bash --noprofile --norc',
+  },
+  stdio: ['ignore', 'pipe', 'pipe'],
+});
+let logs = '';
+backend.stdout.on('data', (data) => { logs += data; });
+backend.stderr.on('data', (data) => { logs += data; });
+
+let browser;
+try {
+  if (!await waitFor(() => fetch(`${API}/api/health`).then((response) => response.ok).catch(() => false), 60_000)) {
+    throw new Error(`server did not start:\n${logs.slice(-2000)}`);
+  }
+  await fetch(`${API}/api/welcome/seen`, { method: 'POST' });
+
+  const created = await apiJson('/api/sessions', {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli: 'test-repaint', name: 'screenshot-e2e', path: '.' }),
+  });
+  const id = created.body.id;
+  if (!id) throw new Error(`session creation failed: ${JSON.stringify(created.body)}`);
+
+  // The browser's declared type is deliberately non-canonical. The response
+  // and raw preview must reflect the PNG bytes, not that metadata.
+  const upload = await fetch(`${API}/api/sessions/${id}/attachments`, {
+    method: 'POST', headers: { 'content-type': 'application/json' }, body: png,
+  });
+  const stored = await upload.json();
+  check('upload MIME is detected from bytes', upload.status === 201 && stored.mime === 'image/png',
+    JSON.stringify({ status: upload.status, mime: stored.mime }));
+  const preview = await fetch(`${API}${stored.previewUrl}`);
+  check('preview uses private, sandboxed response headers',
+    preview.headers.get('content-type') === 'image/png'
+      && preview.headers.get('cache-control') === 'no-store'
+      && preview.headers.get('x-content-type-options') === 'nosniff'
+      && preview.headers.get('content-security-policy') === 'sandbox');
+
+  const missingId = `att_${'0'.repeat(24)}`;
+  const mixedSend = await apiJson(`/api/sessions/${id}/input`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ text: 'must not send partially', attachmentIds: [stored.id, missingId] }),
+  });
+  const sessionsAfterReject = await (await fetch(`${API}/api/sessions`)).json();
+  check('structured send rejects atomically before starting the agent',
+    mixedSend.response.status === 404
+      && sessionsAfterReject.find((session) => session.id === id)?.running === false,
+    JSON.stringify({ status: mixedSend.response.status, error: mixedSend.body.error }));
+
+  const remoteCreated = await apiJson('/api/sessions', {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ cli: 'remote', name: 'remote-screenshot-e2e', path: '.' }),
+  });
+  const remoteUpload = await fetch(`${API}/api/sessions/${remoteCreated.body.id}/attachments`, {
+    method: 'POST', headers: { 'content-type': 'image/png' }, body: png,
+  });
+  const remoteUploadBody = await remoteUpload.json();
+  check('remote uploads are rejected with an actionable reason',
+    remoteUpload.status === 400 && remoteUploadBody.error.includes('cannot read files stored on this Space'));
+
+  const bakedChromium = '/opt/pw-browsers/chromium-1208/chrome-linux64/chrome';
+  const chromiumExecutable = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
+    || (fs.existsSync(bakedChromium) ? bakedChromium : undefined);
+  browser = await chromium.launch({
+    headless: true,
+    ...(chromiumExecutable ? { executablePath: chromiumExecutable } : {}),
+  });
+  const page = await browser.newPage({ viewport: { width: 1280, height: 800 } });
+  await page.goto(API, { waitUntil: 'domcontentloaded' });
+  await page.locator('.sidebar .row[title^="screenshot-e2e"]').first().click();
+  await page.locator('.tile-terminal:not(.tile-cached) .xterm-screen').waitFor({ state: 'visible' });
+  await page.locator('.pane-head .ph-image').waitFor({ state: 'visible' });
+  await waitFor(() => page.locator('.pane-head .ph-image').isEnabled());
+
+  // Let the upload finish, stop the process, and only then expose the response
+  // to the UI. The following insert request must fail authoritatively.
+  let disconnectedAttachmentId;
+  await page.route(`**/api/sessions/${id}/attachments`, async (route) => {
+    const response = await route.fetch();
+    disconnectedAttachmentId = (await response.json()).id;
+    await fetch(`${API}/api/sessions/${id}/stop`, { method: 'POST' });
+    await route.fulfill({ response });
+  }, { times: 1 });
+  await page.locator('.pane-head .image-file-input').setInputFiles({
+    name: 'disconnect.png', mimeType: 'image/png', buffer: png,
+  });
+  const retryStatus = page.locator('.term-image-status.has-action');
+  await retryStatus.waitFor({ state: 'visible' });
+  const failedText = await retryStatus.textContent();
+  check('a stopped terminal reports saved-but-not-inserted, never success',
+    !!failedText?.includes('saved but not inserted') && !failedText.includes('press Enter'),
+    JSON.stringify({ failedText }));
+  await page.locator('.term-exit').waitFor({ state: 'visible' });
+  check('terminal attachment picker is unavailable while stopped',
+    await page.locator('.pane-head .ph-image').isDisabled());
+
+  await page.locator('.term-exit .tx-btn').click();
+  await waitFor(() => page.locator('.pane-head .ph-image').isEnabled(), 20_000);
+  const retry = retryStatus.locator('button');
+  await retry.click();
+  await page.locator('.term-image-status.success').waitFor({ state: 'visible' });
+  const successText = await page.locator('.term-image-status.success').textContent();
+  check('retry inserts the already-uploaded screenshot after restart',
+    !!successText?.includes('inserted') && successText.includes('press Enter'),
+    JSON.stringify({ successText }));
+  const terminalTail = await (await fetch(`${API}/api/agents/${id}/tail?lines=80`)).json();
+  check('terminal retry reaches the PTY without submitting the prompt',
+    terminalTail.text.includes('Screenshot:') && !terminalTail.text.includes('command not found'));
+  const repeatedInsert = await apiJson(`/api/sessions/${id}/attachments/insert`, {
+    method: 'POST', headers: { 'content-type': 'application/json' },
+    body: JSON.stringify({ attachmentIds: [disconnectedAttachmentId] }),
+  });
+  const tailAfterRepeat = await (await fetch(`${API}/api/agents/${id}/tail?lines=80`)).json();
+  const insertedCount = (value) => (value.match(/Screenshot:/g) || []).length;
+  check('retry is idempotent if the successful HTTP response was lost',
+    repeatedInsert.body.repeated === true
+      && insertedCount(tailAfterRepeat.text) === insertedCount(terminalTail.text));
+
+  const watcher = await browser.newPage({ viewport: { width: 1000, height: 700 } });
+  await watcher.goto(API, { waitUntil: 'domcontentloaded' });
+  await watcher.locator('.sidebar .row[title^="screenshot-e2e"]').first().click();
+  await watcher.locator('.ph-role', { hasText: 'watching' }).waitFor({ state: 'visible' });
+  check('a shared-terminal watcher cannot inject into the controller composer',
+    await watcher.locator('.pane-head .ph-image').isDisabled()
+      && (await watcher.locator('.pane-head .ph-image').getAttribute('title'))?.includes('take control'));
+  await watcher.close();
+
+  // Remote support is phase two, but its reason must be readable on touch
+  // devices where a disabled button's title can never be discovered.
+  await page.locator('.bolt-btn').click();
+  await page.locator('.quick-cli[title^="Remote agent"]').click();
+  const remoteReason = page.locator('.quick .image-attachments-note');
+  check('remote screenshot limitation is visibly explained',
+    await remoteReason.isVisible() && (await remoteReason.textContent())?.includes('cannot read files stored on this Space'));
+
+  // Switch back to the test harness and hold the second upload. Once the first
+  // chip says uploaded, every attachment mutation must remain disabled until
+  // the single logical send transaction finishes.
+  await page.locator('.quick-cli[title="Repaint fixture"]').click();
+  await page.locator('.quick-prompt').fill('inspect both screenshots');
+  await page.locator('.quick-prompt').evaluate((element, bytes) => {
+    const raw = atob(bytes);
+    const data = Uint8Array.from(raw, (character) => character.charCodeAt(0));
+    const transfer = new DataTransfer();
+    transfer.items.add(new File([data], 'first.jpg', { type: 'image/jpg' }));
+    element.dispatchEvent(new ClipboardEvent('paste', {
+      bubbles: true, cancelable: true, clipboardData: transfer,
+    }));
+  }, png.toString('base64'));
+  check('clipboard image paste creates one deduplicated chip and preserves prompt text',
+    await page.locator('.quick .image-chip').count() === 1
+      && await page.locator('.quick-prompt').inputValue() === 'inspect both screenshots');
+  await page.locator('.quick .image-file-input').setInputFiles({
+    name: 'second.png', mimeType: 'image/png', buffer: png,
+  });
+  let releaseSecond;
+  let sawSecond;
+  const secondReached = new Promise((resolve) => { sawSecond = resolve; });
+  const secondHold = new Promise((resolve) => { releaseSecond = resolve; });
+  let uploadCount = 0;
+  await page.route('**/api/sessions/*/attachments', async (route) => {
+    uploadCount += 1;
+    if (uploadCount === 2) {
+      sawSecond();
+      await secondHold;
+    }
+    await route.continue();
+  });
+  await page.locator('.quick-prompt').press('Enter');
+  await Promise.race([
+    secondReached,
+    sleep(20_000).then(() => { throw new Error('second upload did not start'); }),
+  ]);
+  const removeButtons = page.locator('.quick .image-chip > button');
+  check('all attachment mutations stay locked for the full send transaction',
+    await page.locator('.quick .image-pick').isDisabled()
+      && await removeButtons.nth(0).isDisabled()
+      && await removeButtons.nth(1).isDisabled());
+  releaseSecond();
+  await page.locator('.controls').waitFor({ state: 'hidden', timeout: 30_000 });
+} finally {
+  try { await browser?.close(); } catch {}
+  backend.kill('SIGKILL');
+  fs.rmSync(DATA_DIR, { recursive: true, force: true });
+}
+
+console.log(failures ? `\n${failures} FAILURE(S)` : '\nall checks passed');
+process.exit(failures ? 1 : 0);

server/src/attachments.js

@@ -6,6 +6,11 @@ import { pipeline } from 'node:stream/promises';
 import { STATE_DIR } from './config.js';
 
 export const ATTACHMENT_LIMIT = 25 * 1024 * 1024;
+// A single prompt is capped separately at five images. This lifetime cap keeps
+// a forgotten session from growing without bound while still leaving room for
+// many ordinary screenshot turns.
+export const SESSION_ATTACHMENT_LIMIT = 500 * 1024 * 1024;
+export const SESSION_ATTACHMENT_COUNT_LIMIT = 200;
 export const ATTACHMENT_ID = /^att_[a-f0-9]{24}$/;
 export const IMAGE_MIMES = Object.freeze([
   'image/png',
@@ -22,6 +27,7 @@ const EXTENSIONS = Object.freeze({
   'image/gif': 'gif',
 });
 const uploadWindows = new Map();
+const uploadLocks = new Map();
 
 function httpError(statusCode, message) {
   const error = new Error(message);
@@ -47,6 +53,39 @@ function checkUploadRate(sessionId) {
   uploadWindows.set(sessionId, recent);
 }
 
+// Serialize writes within one session so concurrent uploads cannot each pass a
+// stale quota check. Different sessions still stream in parallel.
+async function withUploadLock(sessionId, task) {
+  const previous = uploadLocks.get(sessionId) || Promise.resolve();
+  let release;
+  const hold = new Promise((resolve) => { release = resolve; });
+  const tail = previous.catch(() => {}).then(() => hold);
+  uploadLocks.set(sessionId, tail);
+  await previous.catch(() => {});
+  try {
+    return await task();
+  } finally {
+    release();
+    if (uploadLocks.get(sessionId) === tail) uploadLocks.delete(sessionId);
+  }
+}
+
+async function attachmentUsage(dir) {
+  let entries = [];
+  try { entries = await fs.promises.readdir(dir); } catch { return { bytes: 0, count: 0 }; }
+  let bytes = 0;
+  let count = 0;
+  for (const name of entries) {
+    try {
+      const stat = await fs.promises.lstat(path.join(dir, name));
+      if (!stat.isFile() || stat.isSymbolicLink()) continue;
+      bytes += stat.size;
+      if (ATTACHMENT_ID.test(path.parse(name).name)) count += 1;
+    } catch {}
+  }
+  return { bytes, count };
+}
+
 export function detectImageMime(bytes) {
   if (bytes.length >= 8
       && bytes[0] === 0x89 && bytes.subarray(1, 4).toString('ascii') === 'PNG'
@@ -108,57 +147,63 @@ const responseShape = (sessionId, id, mime, bytes, filePath) => ({
 
 /** Stream one browser image into the session-owned attachment store. */
 export async function receiveImage(readable, sessionId, contentType) {
-  const declared = String(contentType || '').split(';', 1)[0].trim().toLowerCase();
-  if (!IMAGE_MIMES.includes(declared)) throw httpError(415, 'use PNG, JPEG, GIF, or WebP');
+  // Browser MIME metadata is advisory. Clipboard implementations commonly
+  // omit it or use aliases such as image/jpg; the byte signature below is the
+  // security boundary and determines the stored extension and response type.
+  void contentType;
   checkUploadRate(sessionId);
+  return withUploadLock(sessionId, async () => {
+    const dir = sessionDir(sessionId);
+    await fs.promises.mkdir(dir, { recursive: true });
+    const usage = await attachmentUsage(dir);
+    if (usage.count >= SESSION_ATTACHMENT_COUNT_LIMIT) {
+      throw httpError(413, `this session already has ${SESSION_ATTACHMENT_COUNT_LIMIT} screenshots`);
+    }
+    const id = `att_${crypto.randomBytes(12).toString('hex')}`;
+    const temporary = path.join(dir, `.${id}.${crypto.randomBytes(4).toString('hex')}.part`);
+    let bytes = 0;
+    const limiter = new Transform({
+      transform(chunk, _encoding, callback) {
+        bytes += chunk.length;
+        if (bytes > ATTACHMENT_LIMIT) return callback(httpError(413, 'image is larger than 25 MB'));
+        if (usage.bytes + bytes > SESSION_ATTACHMENT_LIMIT) {
+          return callback(httpError(413, 'this session has reached its 500 MB screenshot limit'));
+        }
+        callback(null, chunk);
+      },
+    });
 
-  const dir = sessionDir(sessionId);
-  await fs.promises.mkdir(dir, { recursive: true });
-  const id = `att_${crypto.randomBytes(12).toString('hex')}`;
-  const temporary = path.join(dir, `.${id}.${crypto.randomBytes(4).toString('hex')}.part`);
-  let bytes = 0;
-  const limiter = new Transform({
-    transform(chunk, _encoding, callback) {
-      bytes += chunk.length;
-      if (bytes > ATTACHMENT_LIMIT) return callback(httpError(413, 'image is larger than 25 MB'));
-      callback(null, chunk);
-    },
-  });
-
-  try {
-    await pipeline(readable, limiter, fs.createWriteStream(temporary, { flags: 'wx' }));
-    if (bytes === 0) throw httpError(413, 'image is empty');
-
-    const handle = await fs.promises.open(temporary, 'r');
-    const header = Buffer.alloc(32);
-    const tail = Buffer.alloc(Math.min(16, bytes));
-    let bytesRead = 0;
-    let tailBytesRead = 0;
     try {
-      ({ bytesRead } = await handle.read(header, 0, header.length, 0));
-      ({ bytesRead: tailBytesRead } = await handle.read(tail, 0, tail.length, Math.max(0, bytes - tail.length)));
-    } finally {
-      await handle.close();
-    }
-    const headerBytes = header.subarray(0, bytesRead);
-    const tailBytes = tail.subarray(0, tailBytesRead);
-    const detected = detectImageMime(headerBytes);
-    if (!detected || detected !== declared) {
-      throw httpError(415, detected
-        ? `image bytes are ${detected}, not ${declared}`
-        : 'file is not a supported raster image');
-    }
-    if (!imageEnvelopeIsValid(detected, headerBytes, tailBytes, bytes)) {
-      throw httpError(415, 'image is truncated or malformed');
-    }
+      await pipeline(readable, limiter, fs.createWriteStream(temporary, { flags: 'wx' }));
+      if (bytes === 0) throw httpError(413, 'image is empty');
 
-    const finalPath = path.join(dir, `${id}.${EXTENSIONS[detected]}`);
-    await fs.promises.rename(temporary, finalPath);
-    return responseShape(sessionId, id, detected, bytes, finalPath);
-  } catch (error) {
-    await fs.promises.unlink(temporary).catch(() => {});
-    throw error;
-  }
+      const handle = await fs.promises.open(temporary, 'r');
+      const header = Buffer.alloc(32);
+      const tail = Buffer.alloc(Math.min(16, bytes));
+      let bytesRead = 0;
+      let tailBytesRead = 0;
+      try {
+        ({ bytesRead } = await handle.read(header, 0, header.length, 0));
+        ({ bytesRead: tailBytesRead } = await handle.read(tail, 0, tail.length, Math.max(0, bytes - tail.length)));
+      } finally {
+        await handle.close();
+      }
+      const headerBytes = header.subarray(0, bytesRead);
+      const tailBytes = tail.subarray(0, tailBytesRead);
+      const detected = detectImageMime(headerBytes);
+      if (!detected) throw httpError(415, 'file is not a supported raster image');
+      if (!imageEnvelopeIsValid(detected, headerBytes, tailBytes, bytes)) {
+        throw httpError(415, 'image is truncated or malformed');
+      }
+
+      const finalPath = path.join(dir, `${id}.${EXTENSIONS[detected]}`);
+      await fs.promises.rename(temporary, finalPath);
+      return responseShape(sessionId, id, detected, bytes, finalPath);
+    } catch (error) {
+      await fs.promises.unlink(temporary).catch(() => {});
+      throw error;
+    }
+  });
 }
 
 /** Resolve an untrusted attachment id within exactly one session. */
@@ -183,17 +228,17 @@ export function resolveImages(sessionId, attachmentIds) {
   return attachmentIds.map((id) => resolveImage(sessionId, id));
 }
 
-export function removeSessionAttachments(sessionId) {
+export async function removeSessionAttachments(sessionId) {
   uploadWindows.delete(sessionId);
-  fs.rmSync(sessionDir(sessionId), { recursive: true, force: true });
+  await withUploadLock(sessionId, () => fs.promises.rm(sessionDir(sessionId), { recursive: true, force: true }));
 }
 
 /** Remove only old orphan stores; recent crash leftovers keep a seven-day grace. */
-export function pruneAttachmentDirs(sessionIds, now = Date.now()) {
+export async function pruneAttachmentDirs(sessionIds, now = Date.now()) {
   const live = new Set(sessionIds);
   const cutoff = now - 7 * 24 * 60 * 60 * 1000;
   let entries = [];
-  try { entries = fs.readdirSync(ATTACHMENTS_DIR, { withFileTypes: true }); } catch { return; }
+  try { entries = await fs.promises.readdir(ATTACHMENTS_DIR, { withFileTypes: true }); } catch { return; }
   for (const entry of entries) {
     if (!entry.isDirectory()) continue;
     const dir = path.join(ATTACHMENTS_DIR, entry.name);
@@ -201,24 +246,33 @@ export function pruneAttachmentDirs(sessionIds, now = Date.now()) {
     // Normal request failures remove these immediately; this is the crash
     // backstop, with the same grace period as orphan session directories.
     try {
-      for (const name of fs.readdirSync(dir)) {
+      for (const name of await fs.promises.readdir(dir)) {
         const part = path.join(dir, name);
-        if (name.endsWith('.part') && fs.lstatSync(part).isFile() && fs.statSync(part).mtimeMs < cutoff) {
-          fs.unlinkSync(part);
+        const stat = await fs.promises.lstat(part);
+        if (name.endsWith('.part') && stat.isFile() && !stat.isSymbolicLink() && stat.mtimeMs < cutoff) {
+          await fs.promises.unlink(part);
         }
       }
     } catch {}
     if (live.has(entry.name)) continue;
     let newest = 0;
     try {
-      newest = Math.max(fs.statSync(dir).mtimeMs, ...fs.readdirSync(dir).map((name) => fs.lstatSync(path.join(dir, name)).mtimeMs));
+      const names = await fs.promises.readdir(dir);
+      const stats = await Promise.all(names.map((name) => fs.promises.lstat(path.join(dir, name))));
+      newest = Math.max((await fs.promises.stat(dir)).mtimeMs, ...stats.map((stat) => stat.mtimeMs));
     } catch { continue; }
-    if (newest < cutoff) fs.rmSync(dir, { recursive: true, force: true });
+    if (newest < cutoff) await fs.promises.rm(dir, { recursive: true, force: true });
   }
 }
 
 const quotePath = (filePath) => JSON.stringify(filePath);
 
+/** TUI commands that attach native image context before the textual prompt. */
+export function formatAttachmentPrelude(cli, images) {
+  if (cli !== 'hermes') return [];
+  return images.map((image) => `/image ${quotePath(image.path)}`);
+}
+
 /** Keep CLI-version-specific formatting out of request handlers and React. */
 export function formatAttachmentDelivery(cli, text, images) {
   const prompt = String(text || '').trim()

server/src/config.js

@@ -84,7 +84,9 @@ export const CLIS = [
     withPrompt: (q) => `claude ${q}`,
     setup: setupHint('ANTHROPIC_API_KEY') },
   { id: 'codex',    label: 'Codex',       bin: 'codex',    color: '#5eb6a6', run: 'codex',          cont: 'codex resume --last', resizeMode: 'repaint',
-    withPrompt: (q) => `codex ${q}`,
+    // `q` and image paths arrive shell-quoted from runner.commandFor(). Repeat
+    // -i because Codex's variadic flag would otherwise consume the prompt.
+    withPrompt: (q, images = []) => `codex${images.length ? ` ${images.map((image) => `-i ${image}`).join(' ')}` : ''} ${q}`,
     setup: setupHint('OPENAI_API_KEY') },
   { id: 'gemini',   label: 'Gemini CLI',  bin: 'gemini',   color: '#4796e3', run: 'gemini',         cont: null, resizeMode: 'repaint',
     withPrompt: (q) => `gemini -i ${q}`, // -i = interactive session seeded with the prompt

server/src/index.js

@@ -16,7 +16,7 @@ import * as store from './sessions.js';
 import * as groups from './groups.js';
 import * as order from './order.js';
 import * as demo from './demo.js';
-import { attach, agentInfo, deriveState, stop, stopAll, ensureRunning, sendInput, isRunning, capturePane, ghosttyReady, ghosttyError, installClaudeRepinHook } from './runner.js';
+import { attach, agentInfo, deriveState, stop, stopAll, ensureRunning, sendInput, pasteInput, isRunning, capturePane, ghosttyReady, ghosttyError, installClaudeRepinHook } from './runner.js';
 
 // Control frames ride the terminal socket behind a leading NUL pair, which real
 // PTY output never begins with. Same sentinel the old copy-mode hint used, so the
@@ -32,14 +32,15 @@ import { shareSession, shareNamespace, findTrace, shareAccess, grantAccess, revo
          importBundle, listBundles, SHAREABLE_CLIS } from './share.js';
 import * as backup from './backup.js';
 import {
-  formatAttachmentDelivery, pruneAttachmentDirs, receiveImage, removeSessionAttachments,
+  formatAttachmentDelivery, formatAttachmentPrelude, pruneAttachmentDirs, receiveImage, removeSessionAttachments,
   resolveImage, resolveImages,
 } from './attachments.js';
 
 ensureDirs();
 refreshVersions();
 store.init();
-pruneAttachmentDirs(store.list().map((session) => session.id));
+pruneAttachmentDirs(store.list().map((session) => session.id))
+  .catch((e) => console.error('[attachments.prune]', e && e.message));
 groups.init();
 order.init();
 demo.init();
@@ -155,7 +156,14 @@ process.on('unhandledRejection', (e) => console.error('[unhandledRejection]', e)
 process.on('uncaughtException', (e) => console.error('[uncaughtException]', e));
 
 const app = express();
-app.use(express.json());
+const jsonBody = express.json();
+app.use((req, res, next) => {
+  // The attachment route determines type from bytes. Skip JSON parsing even
+  // when untrusted browser metadata falsely claims application/json, or the
+  // global parser would reject valid PNG bytes before the streaming route.
+  if (req.method === 'POST' && /^\/api\/sessions\/[^/]+\/attachments$/.test(req.path)) return next();
+  return jsonBody(req, res, next);
+});
 
 // Safety lock: with no authentication, only serve the terminal backend when the
 // Space is private. If it's public, block every working API (and /ws below) and
@@ -264,16 +272,24 @@ async function deliver(session, { text, attachments = [] }, from) {
     return false;
   }
   const prompt = formatAttachmentDelivery(session.cli, text, attachments);
+  const prelude = formatAttachmentPrelude(session.cli, attachments);
   // A session created before its first prompt can still use the CLI's launch
   // argument. This is especially important for quickstart attachments: upload
   // needs a session id first, but typing into a half-booted TUI loses turns.
   const cli = cliById(session.cli);
-  if (!session.everStarted && cli?.withPrompt) {
-    store.update(session.id, { pendingPrompt: prompt });
+  if (!session.everStarted && cli?.withPrompt && prelude.length === 0) {
+    store.update(session.id, {
+      pendingPrompt: prompt,
+      pendingImagePaths: session.cli === 'codex' ? attachments.map((image) => image.path) : undefined,
+    });
     return ensureRunning(store.get(session.id) || session);
   }
   const started = ensureRunning(session);
   if (started) await sleep(3500); // let the CLI boot before the keystrokes land
+  for (const command of prelude) {
+    await sendInput(session.id, command);
+    await sleep(500);
+  }
   await sendInput(session.id, prompt);
   return started;
 }
@@ -299,6 +315,10 @@ app.post('/api/sessions/:id/input', async (req, res) => {
 
 const canAttachImages = (session) => session.cli !== 'shell'
   && !PASSIVE_CLIS.includes(session.cli) && !isRemote(session.cli);
+// A lost HTTP response must not make the Retry action paste the same path a
+// second time. Attachment ids are unique and the terminal UI never intentionally
+// inserts one twice, so this bounded per-session set is a natural idempotency key.
+const terminalAttachmentInsertions = new Map();
 
 // Managed screenshots live under STATE_DIR, never in the user's repository.
 // The raw body is streamed and capped in attachments.js; express.json ignores
@@ -320,6 +340,39 @@ app.post('/api/sessions/:id/attachments', async (req, res) => {
   }
 });
 
+// Insert terminal attachments without pressing Return on the operator's
+// prompt. This server acknowledgement is the source of truth for the terminal
+// overlay; a browser-local xterm paste can be dropped after a disconnect or
+// when another viewer owns the input lease.
+app.post('/api/sessions/:id/attachments/insert', async (req, res) => {
+  const s = store.get(req.params.id);
+  if (!s) return res.status(404).json({ error: 'not found' });
+  if (!canAttachImages(s)) return res.status(400).json({ error: `${s.cli} pane cannot accept screenshots` });
+  try {
+    const attachments = resolveImages(s.id, (req.body || {}).attachmentIds ?? []);
+    if (!attachments.length) return res.status(400).json({ error: 'no screenshots to insert' });
+    const inserted = terminalAttachmentInsertions.get(s.id) || new Set();
+    const pending = attachments.filter((image) => !inserted.has(image.id));
+    const mode = s.cli === 'hermes' ? 'attached' : 'inserted';
+    if (!pending.length) return res.json({ ok: true, mode, repeated: true });
+    terminalAttachmentInsertions.set(s.id, inserted);
+    const prelude = formatAttachmentPrelude(s.cli, pending);
+    if (prelude.length) {
+      for (let index = 0; index < prelude.length; index += 1) {
+        await sendInput(s.id, prelude[index]);
+        inserted.add(pending[index].id);
+        await sleep(500);
+      }
+    } else {
+      pasteInput(s.id, pending.map((image) => image.insertText).join(''));
+      for (const image of pending) inserted.add(image.id);
+    }
+    return res.json({ ok: true, mode });
+  } catch (e) {
+    return res.status(e.statusCode || 409).json({ error: String(e.message || e) });
+  }
+});
+
 app.get('/api/sessions/:id/attachments/:attachmentId/raw', (req, res) => {
   const s = store.get(req.params.id);
   if (!s) return res.status(404).json({ error: 'not found' });
@@ -2065,7 +2118,7 @@ app.put('/api/trace/:id/source', (req, res) => {
   res.json({ ok: true, traceSource: { kind, ref } });
 });
 
-app.delete('/api/sessions/:id', (req, res) => {
+app.delete('/api/sessions/:id', async (req, res) => {
   const s = store.get(req.params.id);
   if (!s) return res.status(404).json({ error: 'not found' });
   stop(s.id);
@@ -2076,7 +2129,8 @@ app.delete('/api/sessions/:id', (req, res) => {
   groups.detachSession(s.id);
   order.drop(`s:${s.id}`);
   store.remove(s.id);
-  try { removeSessionAttachments(s.id); } catch (e) { console.error('[attachments.remove]', e && e.message); }
+  terminalAttachmentInsertions.delete(s.id);
+  try { await removeSessionAttachments(s.id); } catch (e) { console.error('[attachments.remove]', e && e.message); }
   res.json({ ok: true });
 });
 

server/src/runner.js

@@ -104,6 +104,7 @@ const MAX_COLS = 1000;
 const MAX_ROWS = 500;
 
 const hosts = new Map(); // session id -> host
+const stopping = new Set();
 
 function djb2(s) {
   let h = 5381;
@@ -112,7 +113,7 @@ function djb2(s) {
 }
 
 export function isRunning(id) {
-  return hosts.has(id);
+  return hosts.has(id) && !stopping.has(id);
 }
 
 export function ghosttyReady() {
@@ -1168,6 +1169,9 @@ export function commandFor(session) {
   // (claude 'p', codex 'p', gemini -i 'p', opencode --prompt 'p') — the CLI
   // starts already working on it, no typing race against a booting TUI.
   const q0 = !session.everStarted && session.pendingPrompt ? shq(session.pendingPrompt) : '';
+  const q0Images = !session.everStarted && Array.isArray(session.pendingImagePaths)
+    ? session.pendingImagePaths.map((image) => shq(String(image))) : [];
+  const firstCommand = () => cli.withPrompt(q0, q0Images);
 
   // Claude keys conversations by working directory, so grouped sessions sharing
   // a folder would all `--continue` onto the SAME most-recent conversation. Pin
@@ -1238,7 +1242,7 @@ export function commandFor(session) {
     const shared = list().some((o) => o.id !== session.id && o.cli === 'opencode' && (o.path ?? o.id) === folder);
     const base = session.everStarted && cli.cont && !shared
       ? `${cli.cont} || exec ${cli.run}`
-      : `exec ${q0 && cli.withPrompt ? cli.withPrompt(q0) : cli.run}`;
+      : `exec ${q0 && cli.withPrompt ? firstCommand() : cli.run}`;
     return `${guard}${base}`;
   }
 
@@ -1256,7 +1260,7 @@ export function commandFor(session) {
   // the agent is the PTY's foreground process; when it exits the session ends —
   // a clear "done" signal — and the fallback preserves that.
   if (session.everStarted && cli.cont) return `${cli.cont} || exec ${cli.run}`;
-  if (q0 && cli.withPrompt) return `exec ${cli.withPrompt(q0)}`;
+  if (q0 && cli.withPrompt) return `exec ${firstCommand()}`;
   return `exec ${cli.run}`;
 }
 
@@ -1397,6 +1401,7 @@ export function ensureRunning(session, cols = 120, rows = 34) {
 
   term.onExit(() => {
     hosts.delete(session.id);
+    stopping.delete(session.id);
     if (host.gridTimer) { clearTimeout(host.gridTimer); host.gridTimer = null; }
     if (host.traceHistoryTimer) { clearTimeout(host.traceHistoryTimer); host.traceHistoryTimer = null; }
     if (host.resizeCapture) {
@@ -1411,8 +1416,11 @@ export function ensureRunning(session, cols = 120, rows = 34) {
   });
 
   hosts.set(session.id, host);
+  stopping.delete(session.id);
   if (!persistedHistory && captureResize) hydrateTraceHistory(session, host);
-  if (!session.everStarted) update(session.id, { everStarted: true, pendingPrompt: undefined });
+  if (!session.everStarted) update(session.id, {
+    everStarted: true, pendingPrompt: undefined, pendingImagePaths: undefined,
+  });
   if (session.cli === 'codex') scheduleCodexCapture(session, workdir);
   if (session.cli === 'opencode') scheduleOpencodeCapture(session, workdir);
   if (session.cli === 'claude') scheduleClaudeCapture(session, workdir);
@@ -1496,7 +1504,7 @@ export function attach(session, cols, rows) {
 /** Type a line into the session's terminal (works with no browser attached). */
 export async function sendInput(id, text) {
   const host = hosts.get(id);
-  if (!host) throw new Error('session is not running');
+  if (!host || stopping.has(id)) throw new Error('session is not running');
   // Multi-line prompts go in as a bracketed paste so the CLI's composer treats
   // the inner newlines as soft line breaks instead of submitting early.
   const payload = text.includes('\n') ? `\x1b[200~${text}\x1b[201~` : text;
@@ -1508,6 +1516,16 @@ export async function sendInput(id, text) {
   host.pty.write('\r');
 }
 
+/** Insert text into a running terminal's composer without submitting it. */
+export function pasteInput(id, text) {
+  const host = hosts.get(id);
+  if (!host || stopping.has(id)) throw new Error('session is not running');
+  const value = String(text || '');
+  if (!value) return;
+  const payload = value.includes('\n') ? `\x1b[200~${value}\x1b[201~` : value;
+  host.pty.write(payload);
+}
+
 /**
  * The session's rendered screen plus `lines` of scrollback above it — what a
  * human would see in the pane. Used by the agent API so one agent can watch
@@ -1534,6 +1552,7 @@ export function capturePane(id, lines = 80) {
 export function stop(id) {
   const host = hosts.get(id);
   if (!host) return;
+  stopping.add(id);
   try { host.pty.kill(); } catch {}
 }
 
@@ -1543,6 +1562,7 @@ export function stop(id) {
  */
 export function stopAll() {
   for (const host of hosts.values()) {
+    stopping.add(host.id);
     try { host.pty.kill(); } catch {}
   }
 }

server/terminal-ui.test.mjs

@@ -102,7 +102,13 @@ try {
   }));
   await sleep(600);
 
-  browser = await chromium.launch({ headless: true });
+  const bakedChromium = '/opt/pw-browsers/chromium-1208/chrome-linux64/chrome';
+  const chromiumExecutable = process.env.PLAYWRIGHT_CHROMIUM_EXECUTABLE_PATH
+    || (fs.existsSync(bakedChromium) ? bakedChromium : undefined);
+  browser = await chromium.launch({
+    headless: true,
+    ...(chromiumExecutable ? { executablePath: chromiumExecutable } : {}),
+  });
   const context = await browser.newContext({
     viewport: { width: 1280, height: 800 },
     permissions: ['clipboard-read', 'clipboard-write'],

server/test/attachments.test.mjs

@@ -8,9 +8,12 @@ const root = fs.mkdtempSync(path.join(os.tmpdir(), 'am-attachments-'));
 process.env.DATA_DIR = root;
 
 const {
-  detectImageMime, formatAttachmentDelivery, pruneAttachmentDirs, receiveImage, removeSessionAttachments,
-  resolveImage, resolveImages,
+  ATTACHMENT_LIMIT, SESSION_ATTACHMENT_LIMIT, detectImageMime, formatAttachmentDelivery,
+  formatAttachmentPrelude, pruneAttachmentDirs, receiveImage, removeSessionAttachments, resolveImage,
+  resolveImages,
 } = await import('../src/attachments.js');
+const { cliById } = await import('../src/config.js');
+const { commandFor } = await import('../src/runner.js');
 
 const png = Buffer.alloc(45);
 Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]).copy(png);
@@ -43,10 +46,10 @@ try {
   assert.throws(() => resolveImage('codex-123abc', '../sessions.json'), /not found/);
   assert.throws(() => resolveImages('codex-123abc', Array(6).fill(stored.id)), /at most five/);
 
-  await assert.rejects(
-    receiveImage(Readable.from([png]), 'codex-123abc', 'image/jpeg'),
-    (error) => error.statusCode === 415,
-  );
+  const mislabeled = await receiveImage(Readable.from([png]), 'codex-123abc', 'image/jpeg');
+  assert.equal(mislabeled.mime, 'image/png');
+  const untyped = await receiveImage(Readable.from([png]), 'codex-123abc', '');
+  assert.equal(untyped.mime, 'image/png');
   await assert.rejects(
     receiveImage(Readable.from([png.subarray(0, 24)]), 'codex-123abc', 'image/png'),
     (error) => error.statusCode === 415 && /malformed/.test(error.message),
@@ -55,12 +58,66 @@ try {
     receiveImage(Readable.from([]), 'codex-123abc', 'image/png'),
     (error) => error.statusCode === 413,
   );
+  await assert.rejects(
+    receiveImage(Readable.from([Buffer.alloc(ATTACHMENT_LIMIT + 1)]), 'large-123abc', 'image/png'),
+    (error) => error.statusCode === 413 && /25 MB/.test(error.message),
+  );
+  assert.equal(fs.readdirSync(path.join(root, 'state', 'attachments', 'large-123abc')).some((name) => name.endsWith('.part')), false);
+
+  const aborted = new Readable({
+    read() {
+      this.push(png.subarray(0, 20));
+      this.destroy(new Error('request aborted'));
+    },
+  });
+  await assert.rejects(receiveImage(aborted, 'aborted-123abc', 'image/png'), /request aborted/);
+  assert.equal(fs.readdirSync(path.join(root, 'state', 'attachments', 'aborted-123abc')).some((name) => name.endsWith('.part')), false);
+
+  const quotaDir = path.join(root, 'state', 'attachments', 'quota-123abc');
+  fs.mkdirSync(quotaDir, { recursive: true });
+  const quotaFile = path.join(quotaDir, 'existing.bin');
+  fs.writeFileSync(quotaFile, '');
+  fs.truncateSync(quotaFile, SESSION_ATTACHMENT_LIMIT);
+  await assert.rejects(
+    receiveImage(Readable.from([png]), 'quota-123abc', 'image/png'),
+    (error) => error.statusCode === 413 && /500 MB/.test(error.message),
+  );
+
+  const raceQuotaDir = path.join(root, 'state', 'attachments', 'race-quota-123abc');
+  fs.mkdirSync(raceQuotaDir, { recursive: true });
+  const raceQuotaFile = path.join(raceQuotaDir, 'existing.bin');
+  fs.writeFileSync(raceQuotaFile, '');
+  fs.truncateSync(raceQuotaFile, SESSION_ATTACHMENT_LIMIT - png.length);
+  const raced = await Promise.allSettled([
+    receiveImage(Readable.from([png]), 'race-quota-123abc', 'image/png'),
+    receiveImage(Readable.from([png]), 'race-quota-123abc', 'image/png'),
+  ]);
+  assert.equal(raced.filter((result) => result.status === 'fulfilled').length, 1);
+  assert.equal(raced.filter((result) => result.status === 'rejected'
+    && result.reason.statusCode === 413).length, 1);
+
+  const concurrent = await Promise.all(Array.from({ length: 4 }, () =>
+    receiveImage(Readable.from([png]), 'parallel-123abc', 'application/octet-stream')));
+  assert.equal(new Set(concurrent.map((image) => image.id)).size, concurrent.length);
 
   const formatted = formatAttachmentDelivery('codex', 'Compare this', [stored]);
   assert.match(formatted, /Compare this/);
   assert.match(formatted, /Attached screenshots:/);
   assert.match(formatted, new RegExp(stored.id));
   assert.match(formatAttachmentDelivery('gemini', '', [stored]), /Please inspect the attached screenshot\./);
+  assert.deepEqual(formatAttachmentPrelude('hermes', [stored]), [`/image ${JSON.stringify(stored.path)}`]);
+  assert.deepEqual(formatAttachmentPrelude('codex', [stored]), []);
+  assert.equal(
+    cliById('codex').withPrompt("'compare  both'", ["'/tmp/first image.png'", "'/tmp/second.png'"]),
+    "codex -i '/tmp/first image.png' -i '/tmp/second.png' 'compare  both'",
+  );
+  assert.equal(
+    commandFor({
+      id: 'codex-first-image', cli: 'codex', everStarted: false,
+      pendingPrompt: 'compare  both', pendingImagePaths: ['/tmp/first image.png'],
+    }),
+    "exec codex -i '/tmp/first image.png' 'compare  both'",
+  );
 
   const old = new Date(Date.now() - 8 * 24 * 60 * 60 * 1000);
   const oldPart = path.join(path.dirname(stored.path), '.crashed.part');
@@ -71,11 +128,11 @@ try {
   fs.writeFileSync(path.join(orphan, 'old'), 'old');
   fs.utimesSync(path.join(orphan, 'old'), old, old);
   fs.utimesSync(orphan, old, old);
-  pruneAttachmentDirs(['codex-123abc']);
+  await pruneAttachmentDirs(['codex-123abc']);
   assert.equal(fs.existsSync(oldPart), false);
   assert.equal(fs.existsSync(orphan), false);
 
-  removeSessionAttachments('codex-123abc');
+  await removeSessionAttachments('codex-123abc');
   assert.equal(fs.existsSync(path.dirname(stored.path)), false);
   console.log('attachment tests passed');
 } finally {

web/src/App.tsx

@@ -520,7 +520,10 @@ export default function App() {
       await refresh();
       setActiveRef(`s:${sessionId}`);
     } catch (e) {
-      showErr('Couldn’t quickstart the agent')(e);
+      // Quickstart owns a persistent inline recovery state (including the
+      // stopped session created before an upload), so a second generic toast
+      // obscures the useful error and makes one failure look like two.
+      console.error('Couldn’t quickstart the agent', e);
       throw e;
     }
   };

web/src/api.ts

@@ -190,17 +190,26 @@ export interface ImageAttachment {
 }
 
 export const uploadImageAttachment = async (id: string, file: File): Promise<ImageAttachment> => {
+  const headers: Record<string, string> = {
+    'x-file-name': encodeURIComponent(file.name || 'Screenshot'),
+  };
+  if (file.type) headers['content-type'] = file.type;
   const response = await fetch(`/api/sessions/${id}/attachments`, {
     method: 'POST',
-    headers: {
-      'content-type': file.type,
-      'x-file-name': encodeURIComponent(file.name || 'Screenshot'),
-    },
+    headers,
     body: file,
   });
   return jsonOrError(response);
 };
 
+export const insertImageAttachments = (
+  id: string,
+  attachmentIds: string[],
+): Promise<{ ok: boolean; mode: 'inserted' | 'attached'; repeated?: boolean }> =>
+  fetch(`/api/sessions/${id}/attachments/insert`, {
+    method: 'POST', headers: HEADERS, body: JSON.stringify({ attachmentIds }),
+  }).then(jsonOrError);
+
 export const sendInput = (id: string, text: string, attachmentIds: string[] = []): Promise<{ ok: boolean; started?: boolean }> =>
   fetch(`/api/sessions/${id}/input`, { method: 'POST', headers: HEADERS, body: JSON.stringify({ text, attachmentIds }) }).then(jsonOrError);
 

web/src/components/ImageAttachments.tsx

@@ -1,4 +1,4 @@
-import { useRef } from 'react';
+import { useId, useRef } from 'react';
 import type { PendingImage } from '../lib/imageAttachments';
 import { IMAGE_ACCEPT } from '../lib/imageAttachments';
 
@@ -14,14 +14,17 @@ export default function ImageAttachments({ images, disabled, disabledReason, onF
   onRemove: (key: string) => void;
 }) {
   const picker = useRef<HTMLInputElement>(null);
+  const reasonId = useId();
+  const showReason = !!disabled && !!disabledReason;
   return (
-    <div className={`image-attachments${images.length ? ' has-images' : ''}`}>
+    <div className={`image-attachments${images.length ? ' has-images' : ''}${showReason ? ' has-note' : ''}`}>
       <button
         type="button"
         className="image-pick"
         disabled={disabled}
         title={disabledReason || 'Attach screenshots'}
-        aria-label={disabledReason || 'Attach screenshots'}
+        aria-label="Attach screenshots"
+        aria-describedby={showReason ? reasonId : undefined}
         onClick={() => picker.current?.click()}
       >
         <svg viewBox="0 0 18 18" aria-hidden="true">
@@ -42,17 +45,24 @@ export default function ImageAttachments({ images, disabled, disabledReason, onF
           event.currentTarget.value = '';
         }}
       />
+      {showReason && <span id={reasonId} className="image-attachments-note">{disabledReason}</span>}
       {images.map((image) => (
         <div key={image.key} className={`image-chip ${image.status}`}>
-          <img src={image.previewUrl} alt="" />
+          {image.error === 'unsupported image type' ? (
+            <span className="image-chip-placeholder mono" aria-hidden="true">IMG</span>
+          ) : (
+            <a className="image-chip-preview" href={image.previewUrl} target="_blank" rel="noreferrer" title={`Preview ${image.file.name || 'screenshot'}`}>
+              <img src={image.previewUrl} alt="" />
+            </a>
+          )}
           <span className="image-chip-copy">
             <span className="image-chip-name">{image.file.name || 'Screenshot'}</span>
-            <span className="image-chip-meta">
+            <span className="image-chip-meta" aria-live="polite">
               {image.status === 'uploading' ? 'uploading…'
                 : image.error || (image.status === 'uploaded' ? 'uploaded' : fmtBytes(image.file.size))}
             </span>
           </span>
-          <button type="button" onClick={() => onRemove(image.key)} disabled={image.status === 'uploading'} aria-label={`Remove ${image.file.name || 'screenshot'}`}>×</button>
+          <button type="button" onClick={() => onRemove(image.key)} disabled={disabled || image.status === 'uploading'} aria-label={`Remove ${image.file.name || 'screenshot'}`}>×</button>
         </div>
       ))}
     </div>

web/src/components/Overview.tsx

@@ -60,21 +60,30 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
   useEffect(() => () => revokePendingImages(imagesRef.current), []);
 
   const addImages = (files: File[]) => {
-    if (!allowImages || !files.length) return;
-    const next = pendingImagesFromFiles(files, images.length);
-    setImages((current) => [...current, ...next.images]);
+    if (!allowImages || sending || !files.length) return;
+    const next = pendingImagesFromFiles(files, imagesRef.current.length);
+    const merged = [...imagesRef.current, ...next.images];
+    imagesRef.current = merged;
+    setImages(merged);
     setImageError(next.error);
   };
   const removeImage = (key: string) => {
+    if (sending) return;
     setImages((current) => {
       const removed = current.find((image) => image.key === key);
       if (removed) URL.revokeObjectURL(removed.previewUrl);
-      return current.filter((image) => image.key !== key);
+      const next = current.filter((image) => image.key !== key);
+      imagesRef.current = next;
+      return next;
     });
     setImageError(null);
   };
   const updateImage = (key: string, patch: Partial<PendingImage>) => {
-    setImages((current) => current.map((image) => image.key === key ? { ...image, ...patch } : image));
+    setImages((current) => {
+      const next = current.map((image) => image.key === key ? { ...image, ...patch } : image);
+      imagesRef.current = next;
+      return next;
+    });
   };
 
   // After you send (or when the transcript shows a prompt newer than the last
@@ -92,15 +101,17 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
 
   const send = async () => {
     const text = draft.trim();
-    if ((!text && !images.length) || sending) return;
+    const batch = imagesRef.current;
+    if ((!text && !batch.length) || sending) return;
     setSending(true);
     setFailed(null);
     try {
-      const attachments = await uploadPendingImages(s.id, images, updateImage);
+      const attachments = await uploadPendingImages(s.id, batch, updateImage);
       await api.sendInput(s.id, text, attachments.map((image) => image.id));
-      const optimisticText = text || defaultImagePrompt(images.length);
+      const optimisticText = text || defaultImagePrompt(batch.length);
       setDraft('');
-      revokePendingImages(images);
+      revokePendingImages(batch);
+      imagesRef.current = [];
       setImages([]);
       setImageError(null);
       setSent({ text: optimisticText, at: Date.now() });
@@ -186,11 +197,11 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
 
       <div
         className={`ov-composer${dropActive ? ' image-drop' : ''}`}
-        onDragEnter={(event) => { if (allowImages && transferMayContainImage(event.dataTransfer)) { event.preventDefault(); setDropActive(true); } }}
-        onDragOver={(event) => { if (allowImages && transferMayContainImage(event.dataTransfer)) { event.preventDefault(); event.dataTransfer.dropEffect = 'copy'; } }}
+        onDragEnter={(event) => { if (allowImages && !sending && transferMayContainImage(event.dataTransfer)) { event.preventDefault(); setDropActive(true); } }}
+        onDragOver={(event) => { if (allowImages && !sending && transferMayContainImage(event.dataTransfer)) { event.preventDefault(); event.dataTransfer.dropEffect = 'copy'; } }}
         onDragLeave={(event) => { if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setDropActive(false); }}
         onDrop={(event) => {
-          if (!allowImages || !transferMayContainImage(event.dataTransfer)) return;
+          if (!allowImages || sending || !transferMayContainImage(event.dataTransfer)) return;
           event.preventDefault(); event.stopPropagation(); setDropActive(false);
           addImages(imageFilesFromTransfer(event.dataTransfer));
         }}
@@ -198,7 +209,7 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
         <ImageAttachments
           images={images}
           disabled={sending || !allowImages}
-          disabledReason={!allowImages ? 'Screenshots are not available for remote agents yet' : undefined}
+          disabledReason={!allowImages ? 'Screenshots are not available for remote agents yet — that agent cannot read files stored on this Space.' : undefined}
           onFiles={addImages}
           onRemove={removeImage}
         />
@@ -216,7 +227,7 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
             spellCheck={false}
             onPaste={(event) => {
               const files = imageFilesFromTransfer(event.clipboardData);
-              if (!allowImages || !files.length) return;
+              if (!allowImages || sending || !files.length) return;
               event.preventDefault(); addImages(files);
             }}
             onChange={(e) => { setDraft(e.target.value); e.currentTarget.style.height = 'auto'; e.currentTarget.style.height = `${e.currentTarget.scrollHeight}px`; }}
@@ -234,7 +245,7 @@ function Card({ s, color, pending, isMobile, onOpen, onClose }: {
           {(draft.trim() || images.length > 0) && !isMobile && <span className="ov-hint">↵ send · ⇧↵ newline</span>}
         </div>
       </div>
-      {(imageError || failed) && <div className="ov-note">{imageError || failed}</div>}
+      {(imageError || failed) && <div className="ov-note" role="alert">{imageError || failed}</div>}
     </div>
   );
 }

web/src/components/Sidebar.tsx

@@ -108,18 +108,28 @@ export default function Sidebar({
   useEffect(() => () => revokePendingImages(quickImagesRef.current), []);
 
   const updateQuickImage = (key: string, patch: Partial<PendingImage>) => {
-    setQuickImages((current) => current.map((image) => image.key === key ? { ...image, ...patch } : image));
+    setQuickImages((current) => {
+      const next = current.map((image) => image.key === key ? { ...image, ...patch } : image);
+      quickImagesRef.current = next;
+      return next;
+    });
   };
   const addQuickImages = (files: File[]) => {
-    const next = pendingImagesFromFiles(files, quickImages.length);
-    setQuickImages((current) => [...current, ...next.images]);
+    if (quickSending) return;
+    const next = pendingImagesFromFiles(files, quickImagesRef.current.length);
+    const merged = [...quickImagesRef.current, ...next.images];
+    quickImagesRef.current = merged;
+    setQuickImages(merged);
     setQuickError(next.error);
   };
   const removeQuickImage = (key: string) => {
+    if (quickSending) return;
     setQuickImages((current) => {
       const removed = current.find((image) => image.key === key);
       if (removed) URL.revokeObjectURL(removed.previewUrl);
-      return current.filter((image) => image.key !== key);
+      const next = current.filter((image) => image.key !== key);
+      quickImagesRef.current = next;
+      return next;
     });
     setQuickError(null);
   };
@@ -127,9 +137,13 @@ export default function Sidebar({
   // server-created session. Changing its identity starts a fresh target.
   const resetQuickTarget = () => {
     setQuickSessionId(null);
-    setQuickImages((current) => current.map((image) => image.attachment
-      ? { ...image, attachment: undefined, status: 'pending', error: undefined }
-      : image));
+    setQuickImages((current) => {
+      const next = current.map((image) => image.attachment
+        ? { ...image, attachment: undefined, status: 'pending' as const, error: undefined }
+        : image);
+      quickImagesRef.current = next;
+      return next;
+    });
   };
 
   const clearDrag = () => { setDragRef(null); setDrop(null); onDragState?.(null); };
@@ -155,7 +169,8 @@ export default function Sidebar({
   const bump = (id: string, d: number) => setCart((c) => ({ ...c, [id]: Math.max(0, (c[id] || 0) + d) }));
   const closePanel = () => {
     if (panel === 'quick') {
-      revokePendingImages(quickImages);
+      revokePendingImages(quickImagesRef.current);
+      quickImagesRef.current = [];
       setQuickImages([]);
       setQuickSessionId(null);
       setQuickSending(false);
@@ -410,18 +425,18 @@ export default function Sidebar({
           <div
             className={`widget quick${quickDrop ? ' image-drop' : ''}`}
             onDragEnter={(event) => {
-              if (quickMode === 'agent' && quickCli && !isRemote(quickCli) && transferMayContainImage(event.dataTransfer)) {
+              if (!quickSending && quickMode === 'agent' && quickCli && !isRemote(quickCli) && transferMayContainImage(event.dataTransfer)) {
                 event.preventDefault(); setQuickDrop(true);
               }
             }}
             onDragOver={(event) => {
-              if (quickMode === 'agent' && quickCli && !isRemote(quickCli) && transferMayContainImage(event.dataTransfer)) {
+              if (!quickSending && quickMode === 'agent' && quickCli && !isRemote(quickCli) && transferMayContainImage(event.dataTransfer)) {
                 event.preventDefault(); event.dataTransfer.dropEffect = 'copy';
               }
             }}
             onDragLeave={(event) => { if (!event.currentTarget.contains(event.relatedTarget as Node | null)) setQuickDrop(false); }}
             onDrop={(event) => {
-              if (quickMode !== 'agent' || !quickCli || isRemote(quickCli) || !transferMayContainImage(event.dataTransfer)) return;
+              if (quickSending || quickMode !== 'agent' || !quickCli || isRemote(quickCli) || !transferMayContainImage(event.dataTransfer)) return;
               event.preventDefault(); event.stopPropagation(); setQuickDrop(false);
               addQuickImages(imageFilesFromTransfer(event.dataTransfer));
             }}
@@ -432,7 +447,7 @@ export default function Sidebar({
                   key={c.id}
                   className={`quick-cli${quickMode === 'agent' && quickCli === c.id ? ' on' : ''}${c.available ? '' : ' off'}`}
                   title={c.available ? c.label : `${c.label} (not installed)`}
-                  disabled={!c.available}
+                  disabled={!c.available || quickSending}
                   style={quickMode === 'agent' && quickCli === c.id ? { borderColor: c.color } : undefined}
                   onClick={() => { setQuickMode('agent'); if (quickCli !== c.id) resetQuickTarget(); setQuickCli(c.id); }}
                 ><Logo cli={c.id} size={14} /></button>
@@ -441,7 +456,8 @@ export default function Sidebar({
               <button
                 className={`quick-cli quick-grp${quickMode === 'group' ? ' on' : ''}`}
                 title="New group"
-                  onClick={() => setQuickMode('group')}
+                disabled={quickSending}
+                onClick={() => setQuickMode('group')}
               >
                 <span className="grp-mini">
                   <Logo cli="claude" size={8} />
@@ -454,10 +470,11 @@ export default function Sidebar({
                 <button
                   className={`quick-cli${quickMode === 'agent' && quickCli === 'remote' ? ' on' : ''}`}
                   title="Remote agent — an agent on another machine"
+                  disabled={quickSending}
                   style={quickMode === 'agent' && quickCli === 'remote' ? { borderColor: remoteCli.color } : undefined}
                   onClick={() => {
                     setQuickMode('agent'); setQuickCli('remote'); setQuickSessionId(null);
-                    revokePendingImages(quickImages); setQuickImages([]); setQuickError(null);
+                    revokePendingImages(quickImagesRef.current); quickImagesRef.current = []; setQuickImages([]); setQuickError(null);
                   }}
                 ><Logo cli="remote" size={14} /></button>
               )}
@@ -465,7 +482,12 @@ export default function Sidebar({
 
             {quickMode === 'agent' ? (
               <>
-                {quickError && <div className="open-trace-err">{quickError}</div>}
+                {quickError && <div className="open-trace-err" role="alert">{quickError}</div>}
+                {quickError && quickSessionId && (
+                  <div className="quick-recovery mono">
+                    The agent was created. Retry will reuse it; delete it from the agent row if you want to start over.
+                  </div>
+                )}
                 <textarea
                   autoFocus
                   rows={1}
@@ -474,7 +496,7 @@ export default function Sidebar({
                   value={quickPrompt}
                   disabled={quickSending}
                   onPaste={(event) => {
-                    if (!quickCli || isRemote(quickCli)) return;
+                    if (quickSending || !quickCli || isRemote(quickCli)) return;
                     const files = imageFilesFromTransfer(event.clipboardData);
                     if (!files.length) return;
                     event.preventDefault(); addQuickImages(files);
@@ -488,7 +510,7 @@ export default function Sidebar({
                 <ImageAttachments
                   images={quickImages}
                   disabled={quickSending || !quickCli || isRemote(quickCli)}
-                  disabledReason={quickCli && isRemote(quickCli) ? 'Screenshots are not available for remote agents yet' : undefined}
+                  disabledReason={quickCli && isRemote(quickCli) ? 'Screenshots are not available for remote agents yet — that agent cannot read files stored on this Space.' : undefined}
                   onFiles={addQuickImages}
                   onRemove={removeQuickImage}
                 />

web/src/components/TerminalPane.tsx

@@ -9,8 +9,9 @@ import { STATE_LABEL } from '../types';
 import Logo from './Logo';
 import { CloseGlyph, RefreshGlyph } from './icons';
 import * as api from '../api';
+import type { ImageAttachment } from '../api';
 import {
-  IMAGE_ACCEPT, IMAGE_MIMES, MAX_IMAGE_BYTES, MAX_IMAGES, imageFilesFromTransfer,
+  IMAGE_ACCEPT, MAX_IMAGES, imageFileError, imageFilesFromTransfer, looksLikeImageFile,
   transferMayContainImage,
 } from '../lib/imageAttachments';
 
@@ -228,7 +229,12 @@ export default function TerminalPane({
   const [pasteOpen, setPasteOpen] = useState(false);
   const [imageDrop, setImageDrop] = useState(false);
   const [imageStatus, setImageStatus] = useState<{ kind: 'uploading' | 'success' | 'error'; text: string } | null>(null);
+  const [imageUploadBusy, setImageUploadBusy] = useState(false);
+  const [pendingInsert, setPendingInsert] = useState<ImageAttachment[]>([]);
   const supportsImages = session.cli !== 'shell';
+  const hasInputControl = viewers <= 1 || controller;
+  const canAttachImages = supportsImages && conn === 'connected' && hasInputControl
+    && !imageUploadBusy && pendingInsert.length === 0;
   const commitName = () => {
     const v = draft.trim();
     if (v && v !== session.name) onRename?.(v);
@@ -251,30 +257,97 @@ export default function TerminalPane({
     if (linger) imageStatusTimerRef.current = window.setTimeout(() => setImageStatus(null), linger);
   };
 
+  const insertTerminalImages = async (attachments: ImageAttachment[]) => {
+    try {
+      const result = await api.insertImageAttachments(session.id, attachments.map((image) => image.id));
+      setPendingInsert([]);
+      const count = attachments.length;
+      showImageStatus({
+        kind: 'success',
+        text: result.mode === 'attached'
+          ? `${count === 1 ? 'Screenshot' : `${count} screenshots`} attached — continue typing`
+          : `${count === 1 ? 'Screenshot' : `${count} screenshots`} inserted — press Enter when ready`,
+      }, 3000);
+      termRef.current?.focus();
+      return true;
+    } catch {
+      setPendingInsert(attachments);
+      showImageStatus({
+        kind: 'error',
+        text: `${attachments.length === 1 ? 'Screenshot was' : 'Screenshots were'} saved but not inserted`,
+      });
+      return false;
+    }
+  };
+
+  const retryTerminalInsert = async () => {
+    if (!pendingInsert.length || imageUploadBusyRef.current) return;
+    if (conn !== 'connected') {
+      showImageStatus({ kind: 'error', text: 'Restart or reconnect the agent before retrying' });
+      return;
+    }
+    if (!hasInputControl) {
+      showImageStatus({ kind: 'error', text: 'Interact with the terminal to take control before retrying' });
+      return;
+    }
+    imageUploadBusyRef.current = true;
+    setImageUploadBusy(true);
+    showImageStatus({ kind: 'uploading', text: 'inserting saved screenshot…' });
+    try { await insertTerminalImages(pendingInsert); } finally {
+      imageUploadBusyRef.current = false;
+      setImageUploadBusy(false);
+    }
+  };
+
   uploadImagesRef.current = (files: File[]) => {
     if (!supportsImages) return;
+    if (conn !== 'connected') {
+      showImageStatus({ kind: 'error', text: 'Restart or reconnect the agent before attaching screenshots' }, 5000);
+      return;
+    }
+    if (!hasInputControl) {
+      showImageStatus({ kind: 'error', text: 'Interact with the terminal to take control before attaching screenshots' }, 5000);
+      return;
+    }
+    if (pendingInsert.length) {
+      showImageStatus({ kind: 'error', text: 'Retry the saved screenshot before attaching another' });
+      return;
+    }
     if (imageUploadBusyRef.current) return;
-    const images = files
-      .filter((file) => (IMAGE_MIMES as readonly string[]).includes(file.type))
-      .slice(0, MAX_IMAGES);
+    const candidates = files.filter(looksLikeImageFile);
+    if (candidates.length > MAX_IMAGES) {
+      showImageStatus({ kind: 'error', text: `Attach at most ${MAX_IMAGES} screenshots at a time` }, 4000);
+      return;
+    }
+    const images = candidates.slice(0, MAX_IMAGES);
     if (!images.length) { showImageStatus({ kind: 'error', text: 'Use PNG, JPEG, GIF, or WebP' }, 4000); return; }
-    const invalid = images.find((file) => file.size === 0 || file.size > MAX_IMAGE_BYTES);
-    if (invalid) { showImageStatus({ kind: 'error', text: invalid.size ? 'Image is larger than 25 MB' : 'Image is empty' }, 4000); return; }
+    const invalid = images.map((file) => imageFileError(file)).find(Boolean);
+    if (invalid) { showImageStatus({ kind: 'error', text: invalid }, 4000); return; }
     imageUploadBusyRef.current = true;
+    setImageUploadBusy(true);
     void (async () => {
+      const attachments: ImageAttachment[] = [];
       try {
         for (let index = 0; index < images.length; index += 1) {
           showImageStatus({ kind: 'uploading', text: `uploading screenshot${images.length > 1 ? ` ${index + 1}/${images.length}` : ''}…` });
           const attachment = await api.uploadImageAttachment(session.id, images[index]);
-          claimRef.current();
-          termRef.current?.paste(attachment.insertText);
+          attachments.push(attachment);
         }
-        termRef.current?.focus();
-        showImageStatus({ kind: 'success', text: `${images.length === 1 ? 'Screenshot' : `${images.length} screenshots`} inserted — press Enter when ready` }, 3000);
+        showImageStatus({ kind: 'uploading', text: `inserting screenshot${images.length === 1 ? '' : 's'}…` });
+        await insertTerminalImages(attachments);
       } catch (error) {
-        showImageStatus({ kind: 'error', text: error instanceof Error ? error.message : 'screenshot upload failed' }, 5000);
+        if (attachments.length) {
+          setPendingInsert(attachments);
+          showImageStatus({
+            kind: 'error',
+            text: `${attachments.length} screenshot${attachments.length === 1 ? '' : 's'} saved; another failed to upload`,
+          });
+        } else {
+          showImageStatus({ kind: 'error', text: error instanceof Error ? error.message : 'screenshot upload failed' }, 5000);
+        }
       } finally {
         imageUploadBusyRef.current = false;
+        setImageUploadBusy(false);
       }
     })();
   };
@@ -927,7 +1000,13 @@ export default function TerminalPane({
             <>
               <button
                 className="mini-btn ph-image"
-                title="Attach screenshot"
+                title={conn === 'connected'
+                  ? (!hasInputControl
+                    ? 'Interact with the terminal to take control before attaching screenshots'
+                    : (pendingInsert.length ? 'Retry the saved screenshot first' : 'Attach screenshot'))
+                  : 'Restart or reconnect the agent to attach screenshots'}
+                aria-label="Attach screenshot"
+                disabled={!canAttachImages}
                 draggable={false}
                 onMouseDown={(event) => event.stopPropagation()}
                 onClick={(event) => { event.stopPropagation(); imagePickerRef.current?.click(); }}
@@ -944,6 +1023,7 @@ export default function TerminalPane({
                 type="file"
                 accept={IMAGE_ACCEPT}
                 multiple
+                disabled={!canAttachImages}
                 onChange={(event) => {
                   uploadImagesRef.current(Array.from(event.currentTarget.files || []));
                   event.currentTarget.value = '';
@@ -957,7 +1037,18 @@ export default function TerminalPane({
       <div className={`term-host${imageDrop ? ' image-drop' : ''}`} ref={frameRef}>
         <div className="term-fill" ref={hostRef} />
       </div>
-      {imageStatus && <div className={`term-image-status ${imageStatus.kind} mono`}>{imageStatus.text}</div>}
+      {imageStatus && (
+        <div
+          className={`term-image-status ${imageStatus.kind}${pendingInsert.length ? ' has-action' : ''} mono`}
+          role={imageStatus.kind === 'error' ? 'alert' : 'status'}
+          aria-live={imageStatus.kind === 'error' ? 'assertive' : 'polite'}
+        >
+          <span>{imageStatus.text}</span>
+          {pendingInsert.length > 0 && (
+            <button type="button" onClick={retryTerminalInsert} disabled={imageUploadBusy || conn !== 'connected' || !hasInputControl}>retry</button>
+          )}
+        </div>
+      )}
       {isMobile && conn === 'connected' && (
         // Control keys the phone keyboard lacks — needed for TUI menus (model
         // pickers, etc.). preventDefault keeps terminal focus so the keyboard

web/src/lib/imageAttachments.ts

@@ -18,10 +18,37 @@ export interface PendingImage {
 }
 
 const identity = (file: File) => `${file.name}\u0000${file.type}\u0000${file.size}\u0000${file.lastModified}`;
+const IMAGE_EXTENSION = /\.(png|jpe?g|gif|webp)$/i;
+
+export function normalizedImageMime(type: string) {
+  const value = String(type || '').split(';', 1)[0].trim().toLowerCase();
+  return value === 'image/jpg' || value === 'image/pjpeg' ? 'image/jpeg' : value;
+}
+
+// Clipboard and drag sources sometimes omit MIME metadata. Use it as a hint,
+// not as proof; the server validates the actual bytes before storing anything.
+export function looksLikeImageFile(file: Pick<File, 'name' | 'type'>) {
+  const type = normalizedImageMime(file.type);
+  return !type || type === 'application/octet-stream'
+    || type.startsWith('image/') || IMAGE_EXTENSION.test(file.name || '');
+}
+
+export function imageFileError(file: Pick<File, 'name' | 'type' | 'size'>) {
+  if (file.size > MAX_IMAGE_BYTES) return 'too large (25 MB max)';
+  if (file.size === 0) return 'empty image';
+  const type = normalizedImageMime(file.type);
+  if (type.startsWith('image/') && !(IMAGE_MIMES as readonly string[]).includes(type)) {
+    return 'unsupported image type';
+  }
+  if (type && type !== 'application/octet-stream' && !type.startsWith('image/')
+      && !IMAGE_EXTENSION.test(file.name || '')) return 'unsupported image type';
+  return undefined;
+}
 
 export function transferMayContainImage(transfer: DataTransfer) {
-  return Array.from(transfer.items || []).some((item) => item.kind === 'file' && item.type.startsWith('image/'))
-    || Array.from(transfer.files || []).some((file) => file.type.startsWith('image/'));
+  return Array.from(transfer.items || []).some((item) => item.kind === 'file'
+      && (item.type.startsWith('image/') || looksLikeImageFile(item.getAsFile() || { name: '', type: item.type })))
+    || Array.from(transfer.files || []).some(looksLikeImageFile);
 }
 
 /** DataTransfer exposes the same file through both items and files in Chromium. */
@@ -29,7 +56,7 @@ export function imageFilesFromTransfer(transfer: DataTransfer) {
   const files: File[] = [];
   const seen = new Set<string>();
   const add = (file: File | null) => {
-    if (!file || !file.type.startsWith('image/')) return;
+    if (!file || !looksLikeImageFile(file)) return;
     const id = identity(file);
     if (seen.has(id)) return;
     seen.add(id);
@@ -45,10 +72,7 @@ export function imageFilesFromTransfer(transfer: DataTransfer) {
 export function pendingImagesFromFiles(files: File[], currentCount = 0) {
   const remaining = Math.max(0, MAX_IMAGES - currentCount);
   const accepted = files.slice(0, remaining).map((file): PendingImage => {
-    let error: string | undefined;
-    if (!(IMAGE_MIMES as readonly string[]).includes(file.type)) error = 'unsupported image type';
-    else if (file.size > MAX_IMAGE_BYTES) error = 'too large (25 MB max)';
-    else if (file.size === 0) error = 'empty image';
+    const error = imageFileError(file);
     return {
       key: globalThis.crypto?.randomUUID?.() || `${Date.now()}-${Math.random()}`,
       file,
@@ -82,8 +106,7 @@ export async function uploadPendingImages(
       attachments.push(image.attachment);
       continue;
     }
-    if (!(IMAGE_MIMES as readonly string[]).includes(image.file.type)
-        || image.file.size === 0 || image.file.size > MAX_IMAGE_BYTES) {
+    if (imageFileError(image.file)) {
       throw new Error(image.error || 'invalid image');
     }
     update(image.key, { status: 'uploading', error: undefined });

web/src/styles.css

@@ -164,6 +164,7 @@ body {
 .quick-foot .quick-hint { margin-left: auto; white-space: nowrap; }
 .quick-more { background: none; border: none; padding: 0; font: inherit; font-size: 10.5px; font-weight: 600; color: var(--accent); cursor: pointer; white-space: nowrap; }
 .quick-more:hover { text-decoration: underline; }
+.quick-recovery { margin-top: -3px; color: var(--muted); font-size: 9.5px; line-height: 1.35; }
 .cart-row.off { opacity: 0.45; }
 
 /* screenshot attachments: one compact operational row shared by composers */
@@ -173,10 +174,14 @@ body {
 .image-pick:hover:not(:disabled) { color: var(--accent); border-color: color-mix(in srgb, var(--accent) 45%, var(--border)); }
 .image-pick:disabled { opacity: 0.38; cursor: not-allowed; }
 .image-pick svg { width: 15px; height: 15px; }
+.image-attachments-note { min-width: 0; color: var(--muted); font-size: 10px; line-height: 1.3; }
 .image-chip { min-width: 0; max-width: 205px; height: 36px; display: flex; align-items: center; gap: 6px; padding: 3px 5px 3px 3px; border: 1px solid var(--border); border-radius: var(--r-md); background: var(--panel); }
 .image-chip.error { border-color: color-mix(in srgb, var(--danger) 48%, var(--border)); }
 .image-chip.uploading { border-color: color-mix(in srgb, var(--accent) 42%, var(--border)); }
-.image-chip img { flex: none; width: 29px; height: 28px; border-radius: 3px; object-fit: cover; background: var(--panel-2); }
+.image-chip-preview { flex: none; width: 29px; height: 28px; border-radius: 3px; overflow: hidden; background: var(--panel-2); }
+.image-chip-preview:focus-visible { outline: 2px solid var(--accent); outline-offset: 1px; }
+.image-chip img { display: block; width: 29px; height: 28px; object-fit: cover; }
+.image-chip-placeholder { flex: none; width: 29px; height: 28px; display: inline-flex; align-items: center; justify-content: center; border-radius: 3px; background: var(--panel-2); color: var(--muted); font-size: 8px; }
 .image-chip-copy { min-width: 0; display: flex; flex-direction: column; line-height: 1.15; }
 .image-chip-name { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; font-size: 10.5px; font-weight: 600; }
 .image-chip-meta { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; margin-top: 2px; color: var(--muted); font: 9.5px var(--font-mono); }
@@ -363,7 +368,9 @@ body {
 .ov-composer { display: grid; grid-template-columns: auto minmax(0, 1fr); align-items: center; gap: 7px 8px; border-top: 1px solid var(--border); padding-top: 7px; }
 .ov-composer.image-drop { outline: 1px dashed var(--accent); outline-offset: 5px; background: var(--drop); }
 .ov-composer .image-attachments.has-images { grid-column: 1 / -1; }
-.ov-composer .image-attachments.has-images + .ov-live { grid-column: 1 / -1; }
+.ov-composer .image-attachments.has-note { grid-column: 1 / -1; }
+.ov-composer .image-attachments.has-images + .ov-live,
+.ov-composer .image-attachments.has-note + .ov-live { grid-column: 1 / -1; }
 .ov-composer .ov-live { border-top: none; padding-top: 0; }
 .ov-live { display: flex; gap: 8px; align-items: center; border-top: 1px solid var(--border); padding-top: 7px; font-size: 13px; }
 .ov-live .ov-p { color: var(--accent); font-weight: 700; font-size: 13px; }
@@ -604,6 +611,10 @@ body {
 .term-image-status.uploading { color: var(--accent); animation: breathe 1.2s ease-in-out infinite; }
 .term-image-status.success { color: var(--go); }
 .term-image-status.error { color: var(--danger); border-color: color-mix(in srgb, var(--danger) 40%, var(--border)); }
+.term-image-status.has-action { display: flex; align-items: center; gap: 8px; pointer-events: auto; }
+.term-image-status button { padding: 0; border: 0; background: none; color: inherit; font: inherit; font-weight: 700; cursor: pointer; text-decoration: underline; text-underline-offset: 2px; }
+.term-image-status button:disabled { opacity: 0.45; cursor: default; }
+.pane-head .ph-image:disabled { opacity: 0.35; cursor: default; }
 /* The grid is measured against this filler, so it must stay unpadded: FitAddon
    reads the PARENT's computed height and does NOT subtract its padding, so a
    padded parent made the grid count a row that doesn't fit and the bottom line