Unify file upload: server-driven clipboard + tmux injection

[niiyeboah]

Summary

• Server-side inject mode: POST /api/v1/agents/:id/media gains an inject=true form field. When set, the server decides the delivery mechanism (native clipboard for images when capable, or [File #N] <path> via tmux send-keys) and executes terminal injection itself — the client no longer manages delivery logic.
• Client simplification: Replaces two separate upload callbacks (uploadAndInsertFiles for drag-drop, pasteImage for clipboard paste) with a single uploadFiles callback. Removes fileSeqRef, clipboardCapableRef, pasteImageRef, and the useSystemDefaults dependency from the terminal hook. Net -88 lines on the client.
• Dead endpoint removal: Removes POST /api/v1/clipboard/image (184 lines) — its logic now lives in shared/lib/clipboard-write.ts, called by the media inject flow.
• Paste extension fix: Clipboard-pasted images now get correct extensions via extensionForMime() — WebP gets .webp, GIF gets .gif (previously all non-PNG/JPEG got .jpg).
• Bug fixes from review: code != null fix for signal-killed xclip, settled-race guard in clipboard write, PID-reuse TOCTOU fix in xclip reaper.

Test plan

• pnpm run check — type check passes (server + web + scripts)
• pnpm run finalize:web — production build succeeds
• pnpm run test — unit tests pass
• pnpm run test:e2e — 171 E2E tests pass (including updated drag-drop/paste tests)
• Manual: drag-drop a text file onto terminal → [File #N] <path> appears in agent prompt
• Manual: paste an image on macOS → native clipboard delivery (Ctrl+V sent to tmux)
• Manual: paste an image on Linux without Xvfb → falls back to path-based delivery

🤖 Generated with Claude Code

[niiyeboah]

Update: addressed architecture + infra review (both approved ✅)

Ran author-requested architecture-review and infra-review passes on this branch. Both returned request_changes in round 1 and approve in round 2. All findings are fixed in eed75ca (+ a round-2 follow-up in 4eb8c4a).

Correctness / robustness

• Replaced the 150ms paste heuristic with a deterministic readiness wait.waitForClipboardSelection() polls xclip -o -t TARGETS until xclip owns the selection and advertises the image mime (2s deadline), rejecting on timeout. A timeout now returns non-2xx so the client's path-based fallback fires — the previously silent, non-recoverable empty-paste race is gone.
• uploadingFiles has a single owner per phase in pasteImage (cleared on native success and before handing off to the path-based fallback), fixing the premature "Uploading…" hide.

Maintainability

• Extracted hostClipboardImageCapable() (shared/lib/clipboard-capability.ts) as the single source of truth for /system/defaults and /clipboard/image — closes the prior linux-vs-any-non-darwin divergence; the test asserts the helper.
• Added a shared useSystemDefaults() React Query hook; migrated both use-terminal and create-agent-dialog off duplicate raw fetches.
• Corrected the misleading /clipboard/image "not called / remove this route" comments; softened the [File #N] counter comment (per-mount, cosmetic).

Infra hardening

• Rate limit (30/min) + 8MB size cap (→413) on /clipboard/image.
• xclip reaper: SIGTERM the previous resident xclip before respawn; orphan-on-restart documented; round-2 PID-reuse TOCTOU closed by clearing the tracked PID on exit (4eb8c4a).
• macOS temp file moved into a private mkdtemp(0700) dir (no predictable /tmp clobber).
• Documented the shared-Xvfb cross-agent clipboard limitation at the DISPLAY export (per-session isolation scoped out).

Verification

Server + web type checks clean · 92 server unit tests pass · web production build succeeds.