aicodeman 1.40.0 → 1.41.1

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

@@ -8,12 +8,14 @@ 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 { 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 +36,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,9 +45,11 @@ 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 { LRUMap } from '../../utils/lru-map.js';
 import { describeUnknownPath, probePathKind } from '../../utils/index.js';
@@ -55,6 +59,7 @@ import { scanCodexSessionsHistory, codexThreadBySessionId } from '../../codex-tr
 import { getLastTranscriptResponse, isExternalCliTranscriptMode, parseExternalCliTranscript, selectLastAnsweredTurn, } from '../response-viewer-transcript.js';
 import { readDeepSeekLastResponse } from '../../deepseek-transcript.js';
 import { appendClaudeCustomTitle } from '../../claude-session-title.js';
+import { UPLOADS_DIR } from '../paste-image-gc.js';
 // Path to linked-cases registry (same file used by case-routes resolveCasePath)
 const LINKED_CASES_FILE = dataPath('linked-cases.json');
 const CODEMAN_CONFIG_DIR = getDataDir();
@@ -218,41 +223,130 @@ 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;
     }
 }
-// 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.
+/**
+ * Create or re-verify `{workingDir}/.codeman-uploads` for a prompt upload, or
+ * null when something other than a regular directory sits there. An agent or
+ * postinstall script could plant `.codeman-uploads -> ~/.ssh/` and redirect
+ * future writes outside workingDir: lstat (not stat) sees the symlink itself,
+ * and mkdir without `recursive` does not follow one for the leaf either;
+ * O_EXCL|O_NOFOLLOW on the file open makes the write itself symlink-safe.
+ * The folder ignores itself: a `.gitignore` of `*`, written once with O_EXCL,
+ * so the user's repository never sees uploads, their own ignore file is never
+ * touched, and a file already there is theirs and stays as it is.
+ */
+async function ensureUploadDir(workingDir) {
+    // 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);
+        if (dirStat.isSymbolicLink() || !dirStat.isDirectory())
+            return null;
+    }
+    catch (err) {
+        if (err.code !== 'ENOENT')
+            throw err;
+        try {
+            await fs.mkdir(uploadDir);
+        }
+        catch (mkErr) {
+            // Concurrent uploads (a batch of photos) race to create the dir — the
+            // losers get EEXIST. Treat an already-present REAL directory as success,
+            // but re-verify it isn't a symlink a racing actor planted.
+            if (mkErr.code !== 'EEXIST')
+                throw mkErr;
+            const raceStat = await fs.lstat(uploadDir);
+            if (raceStat.isSymbolicLink() || !raceStat.isDirectory())
+                return null;
+        }
+    }
+    const ignoreFile = join(uploadDir, '.gitignore');
+    try {
+        // 'wx' = O_CREAT|O_EXCL, which also fails on a symlink at the path.
+        await fs.writeFile(ignoreFile, '*\n', { flag: 'wx' });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST')
+            return uploadDir;
+        // The create can succeed before the write fails (ENOSPC): an empty ignore
+        // file would read as the user's on the next upload, so take it back; its own
+        // failure must not replace the cause.
+        await fs.rm(ignoreFile, { force: true }).catch(() => { });
+        throw err;
+    }
+    return uploadDir;
+}
+/** Open a fresh, uniquely named paste file for writing. */
+async function openPasteFile(imageDir, ext) {
+    // 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);
+    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
@@ -573,8 +667,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
@@ -583,7 +677,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.`);
         }
@@ -706,6 +800,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 {};
     });
@@ -867,13 +962,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
@@ -892,6 +980,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.
@@ -980,13 +1079,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 });
@@ -994,7 +1096,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) => {
@@ -2619,6 +2723,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;
@@ -2629,7 +2735,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
@@ -2646,16 +2752,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
@@ -2696,6 +2834,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
@@ -2775,6 +2936,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,
@@ -2798,6 +2962,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,
         };
     });
     // ═══════════════════════════════════════════════════════════════
@@ -3000,7 +3173,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, } = 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);
@@ -3288,12 +3461,14 @@ options = {}) {
             }
         }
         // 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(resolvedCasePath, 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
@@ -3547,13 +3722,14 @@ options = {}) {
                 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({
@@ -3626,6 +3802,7 @@ options = {}) {
                 casePath: resolvedCasePath,
                 caseName,
                 ...(customModel ? { modelSwapInProgress: qsCustomModelSwapInProgress } : {}),
+                ...(tabGroupId ? { tabLayout } : {}),
             };
         }
         catch (err) {
@@ -4512,6 +4689,17 @@ 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}`));
+    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).
     app.post('/api/sessions/:id/paste-image', async (req, reply) => {
         // CSRF defense: state-changing routes must come from same origin.
@@ -4549,14 +4737,41 @@ 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
+        // for a remote (SSH) session is the remote path: the agent there could never
+        // read it, and the write would land in a same-named local directory or fail.
+        // An owned Docker case is fine, its workspace is bind-mounted at the same
+        // absolute path; an adopted container (owned: false) mounts nothing, so its
+        // agent reads the file only if the container exposes that host path.
+        if (session.remote) {
+            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');
@@ -4567,9 +4782,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);
@@ -4583,6 +4804,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 imageDir = await ensureUploadDir(session.workingDir);
+            if (!imageDir) {
+                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(imageDir, 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();
@@ -4646,49 +4937,13 @@ options = {}) {
             reply.code(415);
             return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`);
         }
-        // Save to {workingDir}/.claude-images/
-        // Refuse symlinks at imageDir — an agent or postinstall script could plant
-        // `.claude-images -> ~/.ssh/` and redirect future writes outside workingDir.
-        // We lstat (not stat) so we see the symlink itself. Use mkdir without
-        // `recursive` so the leaf creation does not follow a symlink either, and
-        // O_EXCL|O_NOFOLLOW on the file open so the write itself is symlink-safe.
-        const imageDir = join(session.workingDir, '.claude-images');
-        try {
-            const dirStat = await fs.lstat(imageDir);
-            if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
-                reply.code(403);
-                return createErrorResponse(ApiErrorCode.INVALID_INPUT, '.claude-images is not a regular directory');
-            }
-        }
-        catch (err) {
-            if (err.code !== 'ENOENT')
-                throw err;
-            // Non-recursive mkdir: does not follow symlinks for the leaf.
-            // session.workingDir is guaranteed to exist (live session).
-            try {
-                await fs.mkdir(imageDir);
-            }
-            catch (mkErr) {
-                // Concurrent uploads (a batch of photos) race to create .claude-images —
-                // the losers get EEXIST. Treat an already-present REAL directory as
-                // success, but re-verify it isn't a symlink a racing actor planted
-                // (preserve the symlink-safety guarantee above).
-                if (mkErr.code !== 'EEXIST')
-                    throw mkErr;
-                const raceStat = await fs.lstat(imageDir);
-                if (raceStat.isSymbolicLink() || !raceStat.isDirectory()) {
-                    reply.code(403);
-                    return createErrorResponse(ApiErrorCode.INVALID_INPUT, '.claude-images is not a regular directory');
-                }
-            }
+        // {workingDir}/.codeman-uploads/, see ensureUploadDir.
+        const imageDir = await ensureUploadDir(session.workingDir);
+        if (!imageDir) {
+            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);
+        const { filename, filepath, fh } = await openPasteFile(imageDir, ext);
         try {
             await fh.writeFile(imageBytes);
         }