aicodeman 1.41.0 → 1.42.0

package/dist/web/routes/session-routes.js

@@ -8,12 +8,15 @@ import { homedir } from 'node:os';
 import { existsSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFile } from 'node:child_process';
 import fs from 'node:fs/promises';
+import { finished } from 'node:stream/promises';
 import { randomBytes, randomUUID } from 'node:crypto';
+import { isUtf8 } from 'node:buffer';
 import { performance } from 'node:perf_hooks';
 import { ApiErrorCode, createErrorResponse, getErrorMessage, } from '../../types.js';
 import { Session, cliTakesSessionModel, isAltScreenStripMode, isExternalCliMode, isMuxAltScreenOnlyStripMode, isMuxMouseStripMode, } from '../../session.js';
 import { SseEvent } from '../sse-events.js';
 import { webviewCapabilities } from '../../webview-capabilities.js';
+import { htmlViewCapabilities } from '../../html-view-capabilities.js';
 import { CreateSessionSchema, SessionNameSchema, SessionColorSchema, RunPromptSchema, SessionInputWithLimitSchema, ResizeSchema, AutoClearSchema, AutoCompactSchema, AutoResumeSchema, PinSessionSchema, ImageWatcherSchema, FlickerFilterSchema, QuickRunSchema, QuickStartSchema, InteractiveStartSchema, SessionOrderUpdateSchema, SessionWaitQuerySchema, SessionWaitOutputQuerySchema, CustomModelSelectionSchema, } from '../schemas.js';
 import { readCustomModelHosts } from '../../custom-model-hosts.js';
 import { applyCustomModelInjection, removeConfigDir } from '../../custom-model-injection-apply.js';
@@ -34,7 +37,7 @@ import { applyLaunchDefaults } from '../launch-defaults.js';
 import { legacyConfigForMode } from '../../session-cli-registry-bridge.js';
 import { isMultiUserMode } from '../../config/multiuser.js';
 import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
-import { writeHooksConfig, updateCaseModel, stripCaseEnvKeys, applyAgentSkill, refreshUserAgentSkill, seedAgentSessionPreamble, applyWorkspaceHooks, refreshStaleCodemanHooks, } from '../../hooks-config.js';
+import { writeHooksConfig, updateCaseModel, stripCaseEnvKeys, agentSkillDir, agentSkillDirFor, applyAgentSkill, refreshUserAgentSkill, seedAgentSessionPreamble, applyWorkspaceHooks, refreshStaleCodemanHooks, } from '../../hooks-config.js';
 import { generateClaudeMd } from '../../templates/claude-md.js';
 import { imageWatcher } from '../../image-watcher.js';
 import { convertHeicToJpeg } from '../heic-jpeg-converter.js';
@@ -43,10 +46,13 @@ import { mergeUnifiedSessions, filterAndPaginate, } from '../../services/unified
 import { buildHistorySessionIndexItems, setHistoryIndexRefresher, setHistorySessionIndex, } from '../session-history-index.js';
 import { RunSummaryTracker } from '../../run-summary.js';
 import { MAX_INPUT_LENGTH, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js';
-import { MAX_PASTE_IMAGE_BYTES } from '../../config/buffer-limits.js';
+import { MAX_PASTE_IMAGE_BYTES, MAX_PASTE_VIDEO_BYTES } from '../../config/buffer-limits.js';
+import { VIDEO_ATTACHMENT_EXTENSIONS } from '../../attachment-registry.js';
 import { dataPath, getDataDir } from '../../config/instance.js';
 import { checkRemoteTmuxAvailable, readRemoteCases, readRemoteHosts, rehydrateRemoteHostFields, toAttachedSessionRemote, toSessionRemote, } from '../../remote-hosts.js';
+import { fetchRemoteScrollback } from '../../remote-pane-history.js';
 import { checkDockerAvailable, checkDockerConfigDrift, probeAdoptableContainer, checkDockerTmuxAvailable, ensureAgentBaseImage, DEFAULT_AGENT_IMAGE, persistDockerCaseClaudeSessionId, readDockerCases, readDockerHosts, toSessionDocker, } from '../../docker-hosts.js';
+import { resolveCaseRepository, resolveManagedWorktree } from '../../git-worktrees.js';
 import { LRUMap } from '../../utils/lru-map.js';
 import { describeUnknownPath, probePathKind } from '../../utils/index.js';
 import { findLatestOmpSessionId } from '../../utils/omp-session-resolver.js';
@@ -179,19 +185,37 @@ export function stripInkRedrawBloat(buffer) {
     return parts.join('');
 }
 /**
- * Validate image bytes against a declared extension. Sniffs the first ~12 bytes
- * for a known magic-number signature. Defends against polyglots (e.g. HTML or
- * SVG disguised under a `Content-Type: image/png` header) and against simple
- * extension-only spoofing — both the multipart filename and the Content-Type
- * are attacker-controlled, the raw bytes are not.
+ * The text half of the document allowlist: these are judged on their encoding
+ * (valid UTF-8, no NUL byte) rather than on a signature, since plain text has none.
+ */
+const TEXT_UPLOAD_EXTS = new Set(['.txt', '.md', '.csv', '.tsv', '.json', '.log', '.yaml', '.yml', '.xml']);
+/**
+ * Validate upload bytes against a declared extension. Sniffs the first ~12 bytes
+ * for a known magic-number signature (a text file is instead required to be
+ * UTF-8 without a NUL byte, the one check plain text allows). Defends against
+ * polyglots (e.g. HTML or SVG disguised under a `Content-Type: image/png`
+ * header) and against simple extension-only spoofing — both the multipart
+ * filename and the Content-Type are attacker-controlled, the raw bytes are not.
+ * Fail-closed: an extension this function does not know is never a match.
  *
  * Signatures: https://en.wikipedia.org/wiki/List_of_file_signatures
  */
 export function imageMagicMatchesExt(data, ext) {
+    if (TEXT_UPLOAD_EXTS.has(ext))
+        return data.length > 0 && !data.includes(0) && isUtf8(data);
     if (data.length < 12)
         return false;
     const u32be = (off) => data.readUInt32BE(off);
     switch (ext) {
+        case '.pdf':
+            // "%PDF-"
+            return u32be(0) === 0x25504446 && data[4] === 0x2d;
+        case '.docx':
+        case '.pptx':
+        case '.xlsx':
+        case '.zip':
+            // PK\x03\x04, the local-file header every non-empty zip (OOXML included) opens with
+            return u32be(0) === 0x504b0304;
         case '.png':
             return u32be(0) === 0x89504e47 && u32be(4) === 0x0d0a1a0a;
         case '.jpg':
@@ -219,6 +243,19 @@ export function imageMagicMatchesExt(data, ext) {
             const brand = data.subarray(8, 12).toString('ascii');
             return ['heic', 'heix', 'hevc', 'hevx', 'mif1', 'msf1'].includes(brand);
         }
+        case '.mp4':
+        case '.m4v':
+        case '.mov':
+            // ISO Base Media File Format / QuickTime: size + a top-level atom type. Brands
+            // vary too widely to enumerate (qt, isom, mp42, avc1, hev1, ...), and an older
+            // QuickTime file can open on an atom other than ftyp.
+            return ['ftyp', 'moov', 'mdat', 'wide', 'free', 'skip'].includes(data.subarray(4, 8).toString('ascii'));
+        case '.webm':
+            // EBML header (Matroska's WebM subset)
+            return u32be(0) === 0x1a45dfa3;
+        case '.ogv':
+            // Ogg container ("OggS")
+            return u32be(0) === 0x4f676753;
         default:
             return false;
     }
@@ -235,7 +272,9 @@ export function imageMagicMatchesExt(data, ext) {
  * touched, and a file already there is theirs and stays as it is.
  */
 async function ensureUploadDir(workingDir) {
-    // workingDir is guaranteed to exist (live session).
+    // workingDir exists (live session) and the caller bounded-probed its mount, so
+    // the lstat/mkdir below normally start on a reachable path; a mount that dies
+    // after that probe is the same residual race POST /api/sessions accepts.
     const uploadDir = join(workingDir, UPLOADS_DIR);
     try {
         const dirStat = await fs.lstat(uploadDir);
@@ -275,37 +314,74 @@ async function ensureUploadDir(workingDir) {
     }
     return uploadDir;
 }
-// Per-(IP, sessionId) token bucket for paste-image. 30 requests/minute.
-// Bucket map entries are pruned when they drift > 1h stale to bound memory
-// against a flood of unique IP keys.
+/**
+ * The part of an uploaded document's name that survives into the saved name,
+ * so `Q3 report (final).pdf` is findable as `paste-<ts>-<hex>-Q3-report-final.pdf`.
+ * Only `[A-Za-z0-9._-]` survive, runs of anything else become one `-`, and the
+ * result is capped at 40 chars; nothing in it can be a path separator or a
+ * second extension that matters (the allowlisted extension is appended after).
+ */
+function sanitizeUploadStem(filename) {
+    const stem = basename(filename).replace(/\.[^.]*$/, '');
+    return stem
+        .replace(/[^A-Za-z0-9._-]+/g, '-')
+        .replace(/^[-.]+|[-.]+$/g, '')
+        .slice(0, 40);
+}
+/** Open a fresh, uniquely named paste file for writing. */
+async function openPasteFile(imageDir, ext, stem = '') {
+    // Date.now() collides on same-ms uploads from two tabs (last-write wins
+    // silently). Append 8 hex chars so concurrent pastes get distinct names.
+    // The `paste-` prefix is what the GC (paste-image-gc.ts) matches on.
+    const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${stem ? `-${stem}` : ''}${ext}`;
+    const filepath = join(imageDir, filename);
+    // O_EXCL: refuse to overwrite (collision is impossible with random suffix,
+    // but defends against TOCTOU). O_NOFOLLOW: refuse if filepath is a symlink.
+    const fh = await fs.open(filepath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW);
+    return { filename, filepath, fh };
+}
+// Per-(IP, sessionId) token buckets for paste-image. Images: 30/min. Videos: 3/min,
+// a much lower rate because one video can be up to MAX_PASTE_VIDEO_BYTES (1GB), so the
+// 30/min cap would let a single authenticated client write 30GB of disk a minute; 3/min
+// bounds that to 3GB. Bucket entries are pruned when they drift > 1h stale to bound
+// memory against a flood of unique IP keys.
 const PASTE_RATE_TOKENS = 30;
-const PASTE_RATE_REFILL_PER_MS = PASTE_RATE_TOKENS / 60_000;
+const VIDEO_RATE_TOKENS = 3;
 const PASTE_BUCKET_TTL_MS = 60 * 60 * 1000;
 const PASTE_BUCKET_GC_THRESHOLD = 1000;
 const pasteRateBuckets = new Map();
-export function consumePasteToken(key, now = Date.now()) {
-    if (pasteRateBuckets.size > PASTE_BUCKET_GC_THRESHOLD) {
-        for (const [k, b] of pasteRateBuckets) {
+const videoRateBuckets = new Map();
+function takeToken(buckets, key, capacity, now) {
+    if (buckets.size > PASTE_BUCKET_GC_THRESHOLD) {
+        for (const [k, b] of buckets) {
             if (now - b.lastRefill > PASTE_BUCKET_TTL_MS)
-                pasteRateBuckets.delete(k);
+                buckets.delete(k);
         }
     }
-    let b = pasteRateBuckets.get(key);
+    let b = buckets.get(key);
     if (!b) {
-        b = { tokens: PASTE_RATE_TOKENS, lastRefill: now };
-        pasteRateBuckets.set(key, b);
+        b = { tokens: capacity, lastRefill: now };
+        buckets.set(key, b);
     }
-    const delta = (now - b.lastRefill) * PASTE_RATE_REFILL_PER_MS;
-    b.tokens = Math.min(PASTE_RATE_TOKENS, b.tokens + delta);
+    b.tokens = Math.min(capacity, b.tokens + (now - b.lastRefill) * (capacity / 60_000));
     b.lastRefill = now;
     if (b.tokens < 1)
         return false;
     b.tokens -= 1;
     return true;
 }
+export function consumePasteToken(key, now = Date.now()) {
+    return takeToken(pasteRateBuckets, key, PASTE_RATE_TOKENS, now);
+}
+// Videos stream to disk under a far larger per-file cap, so they draw on their own,
+// much lower bucket (see the comment above the constants).
+export function consumeVideoToken(key, now = Date.now()) {
+    return takeToken(videoRateBuckets, key, VIDEO_RATE_TOKENS, now);
+}
 // Test hook: reset between runs.
 export function _resetPasteRateBuckets() {
     pasteRateBuckets.clear();
+    videoRateBuckets.clear();
 }
 /**
  * Security (multi-user §6.3): the Claude-only permission-mode downgrade does not
@@ -464,6 +540,23 @@ function currentSignalFor(session, dead) {
         return 'exit';
     return signalForStatus(session.status);
 }
+/**
+ * `currentSignalFor`, answering `blocked` for a session whose pane is showing a dialog
+ * its CLI is blocked on (`Session.screenBlocked`, read off the screen for a CLI with no
+ * hook: codex) when the caller asked for it. A hook-raised `blocked` is an edge with no
+ * history, but this one is a level the server is still looking at, so a caller that
+ * asks after the dialog appeared is answered at once instead of waiting out its timeout
+ * for an edge that already passed. Only when `blocked` was asked for: such a pane is also
+ * `idle`, and a caller that asked for `idle` alone must keep getting `idle`. Used by
+ * `GET .../wait` and by a DUPLICATE send-and-wait, every place a wait answers from the
+ * session's current state.
+ */
+function currentSignalForWait(session, dead, until) {
+    const signal = currentSignalFor(session, dead);
+    if (signal !== 'exit' && session.screenBlocked && until.includes('blocked'))
+        return 'blocked';
+    return signal;
+}
 // ── Worker liveness for tmux-backed sessions ────────────────────────────────
 //
 // `session.pid` is the LOCAL `tmux attach` client, not the worker. Codeman sets
@@ -626,8 +719,8 @@ function abortOnClientHangUp(reply) {
  * Injection is best-effort and stays that way: neither a refusal nor a thrown error
  * may fail the create.
  */
-async function injectAgentSkill(casePath) {
-    const skillDir = join(casePath, '.claude', 'skills', 'codeman');
+async function injectAgentSkill(casePath, dir) {
+    const skillDir = agentSkillDirFor(casePath, dir);
     try {
         // Claude Code loads a same-named USER-LEVEL skill (`~/.claude/skills/codeman`,
         // written once by `codeman skill install`) over the case copy injected below, so a
@@ -636,7 +729,7 @@ async function injectAgentSkill(casePath) {
         // current on the same trigger. Refresh-only + marker-guarded; quiet on refusal,
         // since a foreign user copy is the user's own authored skill, not a config error.
         await refreshUserAgentSkill();
-        const result = await applyAgentSkill(casePath, true);
+        const result = await applyAgentSkill(casePath, true, dir);
         if (result === 'foreign') {
             console.warn(`[agent-skill] not injected: ${skillDir} exists but is not Codeman-managed (no marker), refusing to touch it. Remove that copy if you want the packaged skill there.`);
         }
@@ -759,6 +852,7 @@ options = {}) {
         // logout has to retire them too or every dashboard URL opened during this
         // login keeps relaying without one (WebviewCapabilityStore.revokeOwner).
         webviewCapabilities.revokeOwner(ownerFor(req));
+        htmlViewCapabilities.revokeOwner(ownerFor(req));
         reply.clearCookie(AUTH_COOKIE_NAME, { path: '/' });
         return {};
     });
@@ -920,13 +1014,6 @@ options = {}) {
         // materializing in ~/.claude/settings.local.json was never asked for.
         if (!remote && body.workingDir && (body.mode ?? 'claude') === 'claude') {
             await applyWorkspaceHooks(workingDir, await ctx.getWorkspaceHooksEnabled());
-            // Agent skill (docs/agent-control-plan.md §2): ADD-ONLY on create, same shared-
-            // .claude rationale as the statusLine above: a create must never remove the
-            // skill from under other live sessions in the repo. Marker-guarded, so a
-            // user's own skills/codeman is never touched.
-            if (await ctx.getAgentSkillEnabled()) {
-                await injectAgentSkill(workingDir);
-            }
         }
         // Refuse up front if the requested CLI cannot start, rather than spawning a pane that
         // dies on `command not found`. The message comes from the resolver, so it names where
@@ -945,6 +1032,17 @@ options = {}) {
                 return createErrorResponse(ApiErrorCode.OPERATION_FAILED, cliLaunchError);
             }
         }
+        // Agent skill (docs/agent-control-plan.md §2): ADD-ONLY on create, same shared-
+        // workspace rationale as the statusLine above: a create must never remove the
+        // skill from under other live sessions in the repo. Marker-guarded, so a user's
+        // own copy is never touched. Every CLI that takes the skill gets it in the directory
+        // that CLI scans (`capabilities.agentSkillDir`); the same remote and named-workingDir
+        // conditions as the hooks above, and only once the launch pre-flight passed, so a
+        // CLI that cannot start leaves nothing in the workspace.
+        const createSkillDir = agentSkillDir(getCli(body.mode ?? 'claude')?.capabilities);
+        if (!remote && body.workingDir && createSkillDir && (await ctx.getAgentSkillEnabled())) {
+            await injectAgentSkill(workingDir, createSkillDir);
+        }
         // Pre-validate resumeSessionId: check that the conversation file actually exists
         // in Claude's projects directory. If not, skip resume to avoid confusing
         // "No conversation found" errors from Claude CLI.
@@ -1033,13 +1131,16 @@ options = {}) {
             owner,
             parentSessionId: resolveParentSessionId(ctx, req, body.parentSessionId, owner),
         });
-        await ctx.addSession(session);
+        const tabLayout = body.tabGroupId
+            ? await ctx.addSession(session, { tabGroupId: body.tabGroupId })
+            : await ctx.addSession(session);
         ctx.store.incrementSessionsCreated();
         ctx.persistSessionState(session);
         await ctx.setupSessionListeners(session);
         // Pre-seed the agent skill's preamble cache so its §0 bootstrap is a two-line
-        // loader (see seedAgentSessionPreamble). Local claude sessions only; best-effort.
-        if (getCli(mode)?.capabilities.agentSkillInjection && !remote && (await ctx.getAgentSkillEnabled())) {
+        // loader (see seedAgentSessionPreamble). Local sessions of a CLI that takes the
+        // skill; best-effort.
+        if (agentSkillDir(getCli(mode)?.capabilities) && !remote && (await ctx.getAgentSkillEnabled())) {
             await seedAgentSessionPreamble(session.id).catch((err) => console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`));
         }
         getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name });
@@ -1047,7 +1148,9 @@ options = {}) {
         // Avoids serializing 2-3MB of terminal+text buffers per session creation.
         const lightState = ctx.getSessionStateWithRespawn(session);
         ctx.broadcast(SseEvent.SessionCreated, lightState);
-        return { session: lightState };
+        // A grouped creation also returns the layout that placed it, so the browser
+        // draws the tab inside its group at once instead of after a re-read.
+        return { session: lightState, ...(body.tabGroupId ? { tabLayout } : {}) };
     });
     // ========== Rename Session ==========
     app.put('/api/sessions/:id/name', async (req) => {
@@ -1595,7 +1698,9 @@ options = {}) {
                     // A DUPLICATE has no new turn coming, so it answers from the current state
                     // instead of blocking for a transition that already happened.
                     requireTransition: !duplicate,
-                    currentSignal: duplicate ? currentSignalFor(session, workerDead) : undefined,
+                    // The `...ForWait` variant, as on GET .../wait: a screen-read dialog the first
+                    // delivery raised is a level, and a retry asking for `blocked` must find it.
+                    currentSignal: duplicate ? currentSignalForWait(session, workerDead, until) : undefined,
                 });
             }
             catch (err) {
@@ -1612,7 +1717,7 @@ options = {}) {
         }
         const stopDeathWatch = wantsWait ? watchForDeadWorker(ctx.mux, session, id) : () => { };
         // Write input to PTY. Direct write is synchronous; writeViaMux
-        // (tmux send-keys) is fire-and-forget to avoid blocking the HTTP response.
+        // (tmux paste + Enter) is fire-and-forget to avoid blocking the HTTP response.
         // Every write here is `fromUser`: this route carries a person's prompt, or an
         // agent's on their behalf, so it may name the tab (Ralph, respawn, cron and
         // approvals write through the session directly and never say so).
@@ -1634,7 +1739,7 @@ options = {}) {
         // A plain prompt (`<text>\r`) goes through the mux even when the caller did not
         // ask for it: written straight into the pane it arrives as one burst, and Claude
         // Code takes a long burst as a paste whose `\r` becomes a newline, so the prompt
-        // sat unsent (see isPlainPromptInput). The mux path types the text, presses Enter
+        // sat unsent (see isPlainPromptInput). The mux path pastes the text, presses Enter
         // separately and arms the SubmitVerifier. An explicit `useMux: false` keeps the
         // raw write for a caller that really wants it.
         const autoMux = useMux === undefined && isPlainPromptInput(inputStr);
@@ -1782,7 +1887,7 @@ options = {}) {
                 abortSignal: abort.signal,
                 requireTransition: query.fresh === '1' || query.fresh === 'true',
                 // Read BEFORE awaiting: this is the state the caller is asking about.
-                currentSignal: currentSignalFor(session, workerIsDead(ctx.mux, session)),
+                currentSignal: currentSignalForWait(session, workerIsDead(ctx.mux, session), until),
             });
             return {
                 success: true,
@@ -2672,6 +2777,8 @@ options = {}) {
     // Query params:
     //   tail=<bytes> - Only return last N bytes (faster initial load)
     //   full=1       - Explicitly request the entire tmux scrollback (COD-47)
+    //   alt=recording - With full=1: if the pane is in the alternate screen, load
+    //                  the visible frame over the byte recording instead
     app.get('/api/sessions/:id/terminal', async (req, reply) => {
         const routeStartedAt = performance.now();
         const { id } = req.params;
@@ -2682,7 +2789,7 @@ options = {}) {
         // Requests WITHOUT it — shell selection/tab switches (`tail=`) and legacy
         // no-param callers — keep the fast visible-frame capture.
         const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
-        const isFullReload = query.full === '1' || query.full === 'true';
+        let isFullReload = query.full === '1' || query.full === 'true';
         const { tmuxHistoryLimit, terminalBufferMaxBytes } = await ctx.getTerminalHistoryConfig();
         // Prepend the live tmux pane buffer so tab-switch replay shows the current
         // on-screen frame, not just the accumulated byte history. This matters for
@@ -2699,16 +2806,48 @@ options = {}) {
         // for. See PaneCaptureOptions.capturedGeometry.
         // `lines` bounds only the history a FULL capture reads; the visible-frame
         // path reads no history and is untouched by it.
-        const captureOpts = isFullReload
+        let captureOpts = isFullReload
             ? {
                 fullHistory: true,
                 historyLimitLines: captureHistoryLines(query.lines, tmuxHistoryLimit),
                 maxCaptureBytes: terminalBufferMaxBytes,
             }
             : {};
-        const liveMuxBuffer = muxName && typeof ctx.mux.captureActivePaneBuffer === 'function'
-            ? ctx.mux.captureActivePaneBuffer(muxName, captureOpts)
+        // A remote session's local pane only sees the remote tmux client's repaints,
+        // so its own scrollback is a fraction of the real one: read that from the
+        // remote tmux and splice it above the local frame. Null (host unreachable,
+        // no remote session, back-off) keeps the local capture as before.
+        if (isFullReload && session.remote && muxName && captureOpts.historyLimitLines !== undefined) {
+            const remoteScrollback = await fetchRemoteScrollback(session.remote, session.id, captureOpts.historyLimitLines, terminalBufferMaxBytes);
+            if (remoteScrollback !== null) {
+                captureOpts.scrollbackOverride = remoteScrollback.scrollback;
+                captureOpts.scrollbackOverrideScreen = remoteScrollback.screen;
+            }
+        }
+        const capture = (opts) => muxName && typeof ctx.mux.captureActivePaneBuffer === 'function'
+            ? ctx.mux.captureActivePaneBuffer(muxName, opts)
             : null;
+        let liveMuxBuffer = capture(captureOpts);
+        // tmux adds no history while a pane is in the alternate screen, and a
+        // nested tmux client (a remote SSH or Docker case, or `tmux` run by hand
+        // in a shell) holds its pane there for good, so the full capture above is
+        // one screen plus whatever came before. The byte recording still carries
+        // the scrollback, so a caller that opts in (a shell's automatic load,
+        // `alt=recording`) gets the old visible-frame load over it, tailed, rather
+        // than losing everything above the screen. `alternate_on` cannot tell a
+        // nested tmux from vim or less, so those take this path too while open:
+        // the load the shell had before tmux-rendered loads existed. Not when the
+        // history came from the remote tmux (`scrollbackOverride`): a remote pane is
+        // in the alternate screen only because it hosts that tmux's client, and
+        // the fallback would throw the remote scrollback away.
+        if (isFullReload &&
+            query.alt === 'recording' &&
+            captureOpts.scrollbackOverride === undefined &&
+            captureOpts.capturedAlternateOn === true) {
+            isFullReload = false;
+            captureOpts = {};
+            liveMuxBuffer = capture(captureOpts);
+        }
         const captureFinishedAt = performance.now();
         const hasLiveMuxBuffer = liveMuxBuffer !== null && liveMuxBuffer.length > 0;
         const source = hasLiveMuxBuffer
@@ -2749,6 +2888,29 @@ options = {}) {
         // why the UI could only ever say "truncated for performance".
         let truncationReason = null;
         let cleanBuffer;
+        // A `lines=` bound shallower than tmux's history left the older lines in
+        // tmux: an intentional partial read, so 'tail', and a later pull with a
+        // deeper (or no) bound recovers them. Without this a bounded window looks
+        // like the whole history to the client. The byte cap below still wins.
+        // Only a bound the CLIENT set and below the configured ceiling counts:
+        // without `lines=` the bound is the ceiling itself, and on tmux before 3.7
+        // a live pane can hold more than a lowered ceiling, which no request can
+        // read, so calling that a recoverable cut would offer a button that can
+        // never return more.
+        // `historyLinesCut` tells the client this happened, apart from any byte
+        // cut below: `fullSize` counts only what tmux returned, so the bytes a
+        // later `tail` cut are not all that is left, and the client must not name
+        // them as the remainder.
+        const capturedHistoryLines = captureOpts.capturedHistoryLines;
+        const historyLinesCut = isFullCapture &&
+            captureOpts.historyLimitLines !== undefined &&
+            captureOpts.historyLimitLines < tmuxHistoryLimit &&
+            capturedHistoryLines !== undefined &&
+            capturedHistoryLines > captureOpts.historyLimitLines;
+        if (historyLinesCut) {
+            truncated = true;
+            truncationReason = 'tail';
+        }
         // Cap the payload EARLY — before the regex normalization passes below run
         // over it. A full-history tmux capture can be tens of MB of scrollback;
         // normalizing all of it would stall the event loop only to discard most
@@ -2828,6 +2990,9 @@ options = {}) {
             fullSize,
             truncated,
             truncationReason,
+            // The `lines=` bound left older lines in tmux (see above): the remainder
+            // is more than `fullSize - retainedBytes`, by an amount unknown here.
+            historyLinesCut,
             // `retainedBytes` is what this response actually carries; `fullSize` is
             // what existed before the cut. The gap is what the indicator reports.
             retainedBytes: cleanBuffer.length,
@@ -2851,6 +3016,15 @@ options = {}) {
             // damage that does not exist.
             captureCols: hasLiveMuxBuffer ? captureOpts.capturedGeometry?.cols : undefined,
             captureRows: hasLiveMuxBuffer ? captureOpts.capturedGeometry?.rows : undefined,
+            // Rows tmux holds above the visible frame, which is the most a `full=1`
+            // pull can add. `truncated` measures the BYTE stream, and for a pane that
+            // keeps no scrollback (a fullscreen CLI in the alternate screen) the bytes
+            // a tail cut drops are old repaints that no request can bring back, so a
+            // client must not offer to load them. Absent when the pane was not read,
+            // and for a remote session: its local pane hosts the remote tmux client in
+            // the alternate screen, so it always reports 0, while a `full=1` load reads
+            // the real scrollback from the remote tmux (`fetchRemoteScrollback`).
+            paneHistoryLines: hasLiveMuxBuffer && !session.remote ? captureOpts.capturedHistoryLines : undefined,
         };
     });
     // ═══════════════════════════════════════════════════════════════
@@ -3053,7 +3227,7 @@ options = {}) {
         const capMsg = sessionCapacityMessage(ctx.sessions, owner);
         if (capMsg)
             return createErrorResponse(ApiErrorCode.SESSION_BUSY, capMsg);
-        const { caseName = 'testcase', sessionName, mode = 'claude', modelOverride, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig, ompConfig, envOverrides, effort, advisorModel, parentSessionId, agentOrigin, customModel, } = parseBody(QuickStartSchema, req.body);
+        const { caseName = 'testcase', sessionName, mode = 'claude', modelOverride, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig, ompConfig, envOverrides, effort, advisorModel, parentSessionId, agentOrigin, customModel, tabGroupId, worktree, } = parseBody(QuickStartSchema, req.body);
         // Resolved ONCE here: the same value labels a case directory this request creates
         // (agent-case-marker.ts) and draws the tab lineage line on the session below.
         const qsParentSessionId = resolveParentSessionId(ctx, req, parentSessionId, owner);
@@ -3079,6 +3253,13 @@ options = {}) {
         const dockerCase = remoteCase
             ? undefined
             : (await readDockerCases(CODEMAN_CONFIG_DIR)).find((item) => item.name === caseName && canAccessOwned(getAuthUser(req), item.owner));
+        // Worktrees are local only (src/git-worktrees.ts): refused BEFORE a remote host is woken or a
+        // container is touched, since neither branch below could honour it.
+        if (worktree && (remoteCase || dockerCase)) {
+            return createErrorResponse(ApiErrorCode.INVALID_INPUT, remoteCase
+                ? 'worktree is not available for remote (SSH) cases: the repository is on another machine'
+                : 'worktree is not available for Docker cases: git would run on this machine over a workspace the container can write');
+        }
         if (remoteCase) {
             const host = (await readRemoteHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === remoteCase.hostId);
             if (!host)
@@ -3283,6 +3464,28 @@ options = {}) {
         if (localCaseState === 'unknown') {
             return createErrorResponse(ApiErrorCode.OPERATION_FAILED, describeUnknownPath('Case folder', resolvedCasePath, { pastCap: true }));
         }
+        // Where the session runs: the case folder, or one of its git worktrees. A worktree is only
+        // ever USED here (created through POST /api/cases/:name/worktrees), so a case that does not
+        // exist yet is a 404 rather than a scaffold, and the worktree must be a registered, managed
+        // one, every path component a real directory (src/git-worktrees.ts).
+        let workspacePath = resolvedCasePath;
+        if (worktree) {
+            if (localCaseState === 'absent') {
+                return createErrorResponse(ApiErrorCode.NOT_FOUND, `Case "${caseName}" not found`);
+            }
+            if (localCaseState !== 'directory') {
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Case path is not a folder');
+            }
+            const caseRepo = await resolveCaseRepository(resolvedCasePath, {
+                dockerWorkspaces: (await readDockerCases(CODEMAN_CONFIG_DIR)).map((c) => c.hostWorkspacePath).filter(Boolean),
+            });
+            if (!caseRepo.ok)
+                return createErrorResponse(ApiErrorCode[caseRepo.code], caseRepo.message);
+            const managed = await resolveManagedWorktree(caseRepo.repo, worktree);
+            if (!managed.ok)
+                return createErrorResponse(ApiErrorCode[managed.code], managed.message);
+            workspacePath = managed.path;
+        }
         // Create case folder and CLAUDE.md if it doesn't exist (only for non-linked, non-remote,
         // non-docker cases — docker workspaces are scaffolded in their own block below)
         if (localCaseState === 'absent') {
@@ -3334,19 +3537,21 @@ options = {}) {
             // of its own. Skipped for remote cases — resolvedCasePath is a REMOTE path that
             // doesn't exist on the local filesystem.
             if (getCli(mode)?.capabilities.hooks === 'always') {
-                await applyWorkspaceHooks(resolvedCasePath, await ctx.getWorkspaceHooksEnabled());
+                await applyWorkspaceHooks(workspacePath, await ctx.getWorkspaceHooksEnabled());
             }
             else {
-                await refreshStaleCodemanHooks(resolvedCasePath).catch(() => { });
+                await refreshStaleCodemanHooks(workspacePath).catch(() => { });
             }
         }
         // Agent skill injection (docs/agent-control-plan.md §2): ADD-ONLY on create,
-        // marker-guarded (a user's own skills/codeman is never touched). Claude mode only
-        // (`.claude/skills/` is a Claude Code surface); skipped for remote cases, whose
-        // casePath lives on another host. Docker cases qualify: hostWorkspacePath is a
-        // real host dir and the skill crosses the bind mount like the rest of `.claude/`.
-        if (!remote && getCli(mode)?.capabilities.agentSkillInjection && (await ctx.getAgentSkillEnabled())) {
-            await injectAgentSkill(resolvedCasePath);
+        // marker-guarded (a user's own copy is never touched). Each CLI that takes the
+        // skill gets it in the directory it scans (`capabilities.agentSkillDir`:
+        // `.claude/skills` for claude, `.agents/skills` for most others); skipped for
+        // remote cases, whose casePath lives on another host. Docker cases qualify:
+        // hostWorkspacePath is a real host dir and the skill crosses the bind mount.
+        const quickStartSkillDir = agentSkillDir(getCli(mode)?.capabilities);
+        if (!remote && quickStartSkillDir && (await ctx.getAgentSkillEnabled())) {
+            await injectAgentSkill(workspacePath, quickStartSkillDir);
         }
         // Docker cases: the workspace is a REAL host dir bind-mounted into the container.
         // Scaffold hooks (+ a CLAUDE.md) if MISSING so in-container permission prompts and
@@ -3379,13 +3584,13 @@ options = {}) {
         // docker — the docker workspace is a real host dir, so the settings file crosses
         // the bind mount and the in-container claude reads it). Remote was rejected above.
         if (getCli(mode)?.capabilities.model.source === 'claude-settings-file' && modelOverride !== undefined) {
-            await updateCaseModel(resolvedCasePath, modelOverride || null);
+            await updateCaseModel(workspacePath, modelOverride || null);
         }
         // Strip stale disk entries for keys this request is actively setting (Claude only —
         // see POST /api/sessions for full rationale).
         // Same chain, same replacement as the create path above: byte-identical, drift-proof.
         if (!isExternalCliMode(mode) && !remote && envOverrides && Object.keys(envOverrides).length > 0) {
-            await stripCaseEnvKeys(resolvedCasePath, Object.keys(envOverrides));
+            await stripCaseEnvKeys(workspacePath, Object.keys(envOverrides));
         }
         // Create a new session with the case as working directory
         // Apply global Nice priority config and model config from settings
@@ -3421,7 +3626,7 @@ options = {}) {
         const { codexConfig: qsGatedCodexConfig, geminiConfig: qsGatedGeminiConfig, antigravityConfig: qsGatedAntigravityConfig, piConfig: qsGatedPiConfig, grokConfig: qsGatedGrokConfig, deepSeekConfig: qsGatedDeepSeekConfig, } = await _clampExternalCliBypassForOwner(owner, qsLaunchConfigs.codexConfig, qsLaunchConfigs.geminiConfig, qsLaunchConfigs.antigravityConfig, qsLaunchConfigs.piConfig, qsLaunchConfigs.grokConfig, qsLaunchConfigs.deepSeekConfig);
         const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
         const qsGatedEnvOverrides = await clampEnvOverridesForOwner(owner, envOverrides);
-        const qsResolvedOmpConfig = resolveOmpConfigForCreate(mode, resolvedCasePath, qsLaunchOmpConfig);
+        const qsResolvedOmpConfig = resolveOmpConfigForCreate(mode, workspacePath, qsLaunchOmpConfig);
         // Custom Model Endpoint Profiles, applied AT CREATE TIME (docs/custom-model-endpoints-plan.md)
         // rather than via the dedicated restart-in-place route (POST /api/sessions/:id/custom-
         // model, still what an ALREADY-RUNNING session uses to switch later): computing the
@@ -3505,7 +3710,7 @@ options = {}) {
             // with, not a placeholder: `new Session({ id: ... })` accepts an explicit id for
             // exactly this reason.
             qsCustomModelSessionId = randomUUID();
-            const cmApplied = applyCustomModelInjection(cmEntry, cmEndpoint, customModel.modelId, qsCustomModelSessionId, cmContextLength, resolvedCasePath);
+            const cmApplied = applyCustomModelInjection(cmEntry, cmEndpoint, customModel.modelId, qsCustomModelSessionId, cmContextLength, workspacePath);
             if (!cmApplied) {
                 return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${mode} has no known custom-model mechanism`);
             }
@@ -3537,7 +3742,7 @@ options = {}) {
         }
         const qsSessionOptions = {
             id: qsCustomModelSessionId,
-            workingDir: resolvedCasePath,
+            workingDir: workspacePath,
             name: sessionName ? sessionName.slice(0, MAX_SESSION_NAME_LENGTH) : '',
             mux: ctx.mux,
             useMux: true,
@@ -3594,19 +3799,20 @@ options = {}) {
         // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
         // so the initial state already has the phrase configured (only if globally enabled)
         if (getCli(mode)?.capabilities.ralph && !remote && !docker && ctx.store.getConfig().ralphEnabled) {
-            autoConfigureRalph(session, resolvedCasePath, ctx);
+            autoConfigureRalph(session, workspacePath, ctx);
             if (!session.ralphTracker.enabled) {
                 session.ralphTracker.enable();
                 session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart
             }
         }
-        await ctx.addSession(session);
+        const tabLayout = tabGroupId ? await ctx.addSession(session, { tabGroupId }) : await ctx.addSession(session);
         ctx.store.incrementSessionsCreated();
         ctx.persistSessionState(session);
         await ctx.setupSessionListeners(session);
         // Pre-seed the agent skill's preamble cache so its §0 bootstrap is a two-line
-        // loader (see seedAgentSessionPreamble). Local claude sessions only; best-effort.
-        if (getCli(mode)?.capabilities.agentSkillInjection && !remote && !docker && (await ctx.getAgentSkillEnabled())) {
+        // loader (see seedAgentSessionPreamble). Local sessions of a CLI that takes the
+        // skill; best-effort.
+        if (agentSkillDir(getCli(mode)?.capabilities) && !remote && !docker && (await ctx.getAgentSkillEnabled())) {
             await seedAgentSessionPreamble(session.id).catch((err) => console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`));
         }
         getLifecycleLog().log({
@@ -3648,37 +3854,44 @@ options = {}) {
             if (docker && mode === 'claude') {
                 void persistDockerCaseClaudeSessionId(CODEMAN_CONFIG_DIR, docker.containerName, session.claudeSessionId || session.id).catch(() => { });
             }
-            // Save lastUsedCase to settings for TUI/web sync
-            try {
-                const settingsFilePath = SETTINGS_PATH;
-                let settings = {};
+            // Save lastUsedCase to settings for TUI/web sync. It is a key of the server-wide
+            // settings.json, readable by every user through GET /api/settings, so a non-admin's
+            // case name is not written there in multi-user mode (writes are admin-only, like
+            // PUT /api/settings). isAdmin is always true in single-user mode.
+            if (isAdmin(req)) {
                 try {
-                    settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
+                    const settingsFilePath = SETTINGS_PATH;
+                    let settings = {};
+                    try {
+                        settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
+                    }
+                    catch (err) {
+                        if (err.code !== 'ENOENT')
+                            throw err;
+                    }
+                    settings.lastUsedCase = caseName;
+                    const dir = dirname(settingsFilePath);
+                    if (!existsSync(dir)) {
+                        mkdirSync(dir, { recursive: true });
+                    }
+                    // Use async write to avoid blocking event loop
+                    fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
+                        // Non-critical but log for debugging
+                        console.warn('[Server] Failed to save settings (lastUsedCase):', err);
+                    });
                 }
                 catch (err) {
-                    if (err.code !== 'ENOENT')
-                        throw err;
-                }
-                settings.lastUsedCase = caseName;
-                const dir = dirname(settingsFilePath);
-                if (!existsSync(dir)) {
-                    mkdirSync(dir, { recursive: true });
-                }
-                // Use async write to avoid blocking event loop
-                fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
                     // Non-critical but log for debugging
-                    console.warn('[Server] Failed to save settings (lastUsedCase):', err);
-                });
-            }
-            catch (err) {
-                // Non-critical but log for debugging
-                console.warn('[Server] Failed to prepare settings update:', err);
+                    console.warn('[Server] Failed to prepare settings update:', err);
+                }
             }
             return {
                 sessionId: session.id,
                 casePath: resolvedCasePath,
                 caseName,
+                ...(worktree ? { worktree, workingDir: workspacePath } : {}),
                 ...(customModel ? { modelSwapInProgress: qsCustomModelSwapInProgress } : {}),
+                ...(tabGroupId ? { tabLayout } : {}),
             };
         }
         catch (err) {
@@ -4565,7 +4778,38 @@ options = {}) {
     // Paste Image (clipboard / drag-drop upload)
     // ═══════════════════════════════════════════════════════════════
     const ALLOWED_IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.heic', '.heif']);
+    // Single-sourced from the attachment registry (what the file viewer can also play),
+    // so an uploaded video is a type that previews. 3gp/mkv are deliberately out: they
+    // would upload but not preview, and a phone's camera roll produces neither.
+    const ALLOWED_VIDEO_EXTS = new Set([...VIDEO_ATTACHMENT_EXTENSIONS].map((e) => `.${e}`));
+    // Documents a user hands an agent to read: the office formats plus the text
+    // family. Curated on purpose, never SUPPORTED_ATTACHMENT_EXTENSIONS or
+    // EDITABLE_EXTENSIONS, which carry sh/py/js/html; a prompt upload is a thing
+    // to read, not a thing to run or serve. Each is judged on its bytes by
+    // imageMagicMatchesExt (signature, or UTF-8 without NUL for text).
+    const ALLOWED_DOCUMENT_EXTS = new Set(['.pdf', '.docx', '.pptx', '.xlsx', '.zip', ...TEXT_UPLOAD_EXTS]);
+    const VIDEO_MIME_EXT = {
+        mp4: '.mp4',
+        quicktime: '.mov',
+        'x-m4v': '.m4v',
+        webm: '.webm',
+        ogg: '.ogv',
+    };
     // The per-file size cap (MAX_PASTE_IMAGE_BYTES) is enforced by @fastify/multipart (registered in server.ts).
+    /** Write buffered upload bytes into the session's upload dir. Null: the dir is not a real directory. */
+    async function writeBufferedUpload(workingDir, ext, bytes, stem = '') {
+        const uploadDir = await ensureUploadDir(workingDir);
+        if (!uploadDir)
+            return null;
+        const { filename, filepath, fh } = await openPasteFile(uploadDir, ext, stem);
+        try {
+            await fh.writeFile(bytes);
+        }
+        finally {
+            await fh.close();
+        }
+        return { path: filepath, filename };
+    }
     app.post('/api/sessions/:id/paste-image', async (req, reply) => {
         // CSRF defense: state-changing routes must come from same origin.
         // Cookies are SameSite=lax, multipart/form-data is a "simple" CORS request
@@ -4602,12 +4846,19 @@ options = {}) {
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'CSRF check failed');
         }
         const { id } = req.params;
-        // Rate limit per (IP, sessionId): 30/min. Defends against disk-fill DoS
-        // — even an authenticated attacker can otherwise loop large image POSTs.
-        if (!consumePasteToken(`${req.ip}:${id}`)) {
+        // `?kind=video` selects the disk-streamed path (see below). It is read here so the
+        // rate check draws on the right bucket before any work: videos get 3/min, images 30.
+        const isVideo = req.query.kind === 'video';
+        // Rate limit per (IP, sessionId). Defends against disk-fill DoS — even an
+        // authenticated client can otherwise loop large uploads. Videos get their own,
+        // far lower bucket because the per-file cap is 1GB (see the bucket constants).
+        const rateKey = `${req.ip}:${id}`;
+        if (!(isVideo ? consumeVideoToken(rateKey) : consumePasteToken(rateKey))) {
             reply.code(429);
             reply.header('Retry-After', '60');
-            return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Rate limit exceeded (30 uploads/min per session)');
+            return createErrorResponse(ApiErrorCode.INVALID_INPUT, isVideo
+                ? 'Rate limit exceeded (3 video uploads/min per session)'
+                : 'Rate limit exceeded (30 uploads/min per session)');
         }
         const session = findSessionOrFail(ctx, id, req);
         // The file lands on THIS host under the session's working directory, which
@@ -4620,6 +4871,16 @@ options = {}) {
             reply.code(400);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Prompt uploads are not supported for remote (SSH) sessions');
         }
+        // The upload is written under session.workingDir (ensureUploadDir below), and
+        // a live session's workspace can sit on a network mount that stopped answering.
+        // Probe it bounded before the first disk touch, as #516 requires for a path the
+        // user named, so one dead mount cannot freeze a libuv threadpool worker per
+        // upload. Only "unknown" (the mount is not answering) is refused here, the way
+        // the create route does; absent / not-a-directory keep ensureUploadDir's own
+        // errors, since a live session's workspace should be neither.
+        if ((await probePathKind(session.workingDir, { pastCap: true })) === 'unknown') {
+            return createErrorResponse(ApiErrorCode.OPERATION_FAILED, describeUnknownPath('Workspace', session.workingDir, { pastCap: true }));
+        }
         if (!req.isMultipart()) {
             reply.code(400);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Expected multipart/form-data');
@@ -4630,9 +4891,15 @@ options = {}) {
         // boundary scanner with several bugs: literal boundary matches anywhere in
         // body, LF-only clients silently corrupted the last byte (hard-coded \r\n
         // offsets), no part-count cap.
+        // `?kind=video` (read above for the rate check) is the ONLY way onto the video
+        // path: it selects the larger, disk-streamed budget before the part is seen
+        // (busboy takes its limits up front), and it admits video types alone, so an
+        // image can never ride the video cap through memory. Without it the route is
+        // byte-identical to the image-only version. Truncation is checked on the stream
+        // below rather than thrown, since the file is being written as it arrives.
         let part;
         try {
-            part = await req.file();
+            part = await req.file(isVideo ? { limits: { fileSize: MAX_PASTE_VIDEO_BYTES }, throwFileSizeLimit: false } : undefined);
         }
         catch (err) {
             reply.code(413);
@@ -4646,6 +4913,76 @@ options = {}) {
             reply.code(400);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Unexpected field "${part.fieldname}", expected "image"`);
         }
+        if (isVideo) {
+            let ext = '';
+            if (part.filename) {
+                const origExt = extname(part.filename).toLowerCase();
+                if (ALLOWED_VIDEO_EXTS.has(origExt))
+                    ext = origExt;
+            }
+            const videoMime = (part.mimetype || '').toLowerCase().match(/^video\/(mp4|quicktime|x-m4v|webm|ogg)$/);
+            if (videoMime)
+                ext = VIDEO_MIME_EXT[videoMime[1]] ?? ext;
+            if (!ext) {
+                await finished(part.file.resume()).catch(() => { });
+                reply.code(400);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Unsupported video type. Allowed: ${[...ALLOWED_VIDEO_EXTS].join(', ')}`);
+            }
+            const uploadDir = await ensureUploadDir(session.workingDir);
+            if (!uploadDir) {
+                await finished(part.file.resume()).catch(() => { });
+                reply.code(403);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
+            }
+            const { filename, filepath, fh } = await openPasteFile(uploadDir, ext);
+            // Written as it arrives: a phone video is far too large to buffer the way an
+            // image is. The container is judged on the first 12 bytes as soon as they are
+            // in, so a mislabeled upload stops touching disk at its first chunk; the rest
+            // of the body is drained unwritten (as busboy does past its own size limit),
+            // which is what lets the answer reach the client. A transfer that dies midway
+            // (the phone left the network) leaves no partial file behind.
+            const head = Buffer.alloc(12);
+            let headLen = 0;
+            let mislabeled = false;
+            try {
+                for await (const chunk of part.file) {
+                    if (mislabeled)
+                        continue;
+                    if (headLen < head.length) {
+                        headLen += chunk.copy(head, headLen, 0, head.length - headLen);
+                        mislabeled = headLen === head.length && !imageMagicMatchesExt(head, ext);
+                        if (mislabeled)
+                            continue;
+                    }
+                    // writeFile loops until the whole chunk is on disk; a bare write() may be short.
+                    await fh.writeFile(chunk);
+                }
+            }
+            catch (err) {
+                await fs.unlink(filepath).catch(() => { });
+                throw err;
+            }
+            finally {
+                await fh.close();
+            }
+            let failure = null;
+            if (headLen === 0)
+                failure = { status: 400, message: 'Empty file' };
+            else if (!imageMagicMatchesExt(head.subarray(0, headLen), ext)) {
+                console.warn(`[paste-image] video magic mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${ext} magic=${head.subarray(0, headLen).toString('hex')}`);
+                failure = { status: 415, message: `Video bytes do not match declared type ${ext}` };
+            }
+            else if (part.file.truncated) {
+                const maxMb = Math.round(MAX_PASTE_VIDEO_BYTES / (1024 * 1024));
+                failure = { status: 413, message: `File too large (max ${maxMb}MB)` };
+            }
+            if (failure) {
+                await fs.unlink(filepath).catch(() => { });
+                reply.code(failure.status);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, failure.message);
+            }
+            return { path: filepath, filename };
+        }
         let imageBytes;
         try {
             imageBytes = await part.toBuffer();
@@ -4659,13 +4996,34 @@ options = {}) {
             reply.code(400);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Empty file');
         }
+        // Dispatch mirrors the client's _promptAttachKind: an image MIME type takes
+        // the image path whatever the name says, a document extension (the MIME a
+        // phone gives a .md is anyone's guess) takes the document branch, anything
+        // else the image path exactly as before, HEIC sniff included. See CLAUDE.md.
+        const origExt = part.filename ? extname(part.filename).toLowerCase() : '';
+        const imageMime = /^image\//i.test(part.mimetype || '');
+        if (!imageMime && ALLOWED_DOCUMENT_EXTS.has(origExt)) {
+            if (!imageMagicMatchesExt(imageBytes, origExt)) {
+                // The first bytes of a text file are user content, so for text the log
+                // names the failure and never the bytes; a signature is safe to print.
+                const detail = TEXT_UPLOAD_EXTS.has(origExt)
+                    ? `reason=${imageBytes.includes(0) ? 'nul-byte' : 'not-utf8'}`
+                    : `magic=${imageBytes.subarray(0, 12).toString('hex')}`;
+                console.warn(`[paste-image] document mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${origExt} size=${imageBytes.length} ${detail}`);
+                reply.code(415);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `File bytes do not match declared type ${origExt}`);
+            }
+            const saved = await writeBufferedUpload(session.workingDir, origExt, imageBytes, sanitizeUploadStem(part.filename));
+            if (!saved) {
+                reply.code(403);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
+            }
+            return saved;
+        }
         // Determine extension from filename or Content-Type.
         let ext = '.png';
-        if (part.filename) {
-            const origExt = extname(part.filename).toLowerCase();
-            if (ALLOWED_IMAGE_EXTS.has(origExt))
-                ext = origExt;
-        }
+        if (ALLOWED_IMAGE_EXTS.has(origExt))
+            ext = origExt;
         const mimeMatch = (part.mimetype || '').toLowerCase().match(/^image\/(png|jpeg|jpg|webp|gif|bmp|heic|heif)$/);
         if (mimeMatch) {
             const map = {
@@ -4701,6 +5059,15 @@ options = {}) {
             }
         }
         else if (!imageMagicMatchesExt(imageBytes, ext)) {
+            // A foreign extension with no image MIME (a script, an HTML page, a video
+            // without its flag) was never going to be an image: say so, rather than
+            // the ".png" the default extension would name. Decided only HERE, after
+            // the sniff, so anything the image path ever accepted by its bytes (a
+            // HEIC under a generic name) still is.
+            if (origExt && !ALLOWED_IMAGE_EXTS.has(origExt) && !imageMime) {
+                reply.code(400);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Unsupported file type: ${origExt}`);
+            }
             // Sniff actual bytes — a polyglot HTML/PNG would otherwise pass and
             // serve back with image/png MIME. Log the real header so format
             // mismatches can be pinned down without a reproduce-and-guess loop. The
@@ -4709,26 +5076,12 @@ options = {}) {
             reply.code(415);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
         }
-        // {workingDir}/.codeman-uploads/, see ensureUploadDir.
-        const imageDir = await ensureUploadDir(session.workingDir);
-        if (!imageDir) {
+        const saved = await writeBufferedUpload(session.workingDir, ext, imageBytes);
+        if (!saved) {
             reply.code(403);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, `${UPLOADS_DIR} is not a regular directory`);
         }
-        // Date.now() collides on same-ms uploads from two tabs (last-write wins
-        // silently). Append 8 hex chars so concurrent pastes get distinct names.
-        const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${ext}`;
-        const filepath = join(imageDir, filename);
-        // O_EXCL: refuse to overwrite (collision is impossible with random suffix,
-        // but defends against TOCTOU). O_NOFOLLOW: refuse if filepath is a symlink.
-        const fh = await fs.open(filepath, fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW);
-        try {
-            await fh.writeFile(imageBytes);
-        }
-        finally {
-            await fh.close();
-        }
-        return { path: filepath, filename };
+        return saved;
     });
     // Returned so the server can own the registry's LIFETIME (drop state when a session is
     // cleaned up on any of its paths, resolve in-flight wakes on shutdown). The wake-CAPABLE