aicodeman 1.42.0 → 1.44.0

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

@@ -3,7 +3,7 @@
  * Covers session CRUD, input/output, terminal buffer, quick-start, quick-run,
  * auto-clear, auto-compact, image watcher, flicker filter, and logout.
  */
-import { join, dirname, extname, basename } from 'node:path';
+import { join, dirname, extname, basename, resolve as resolvePath } from 'node:path';
 import { homedir } from 'node:os';
 import { existsSync, statSync, mkdirSync, writeFileSync } from 'node:fs';
 import { execFile } from 'node:child_process';
@@ -17,7 +17,7 @@ import { Session, cliTakesSessionModel, isAltScreenStripMode, isExternalCliMode,
 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 { CreateSessionSchema, SessionNameSchema, SessionColorSchema, RunPromptSchema, SessionInputWithLimitSchema, ResizeSchema, AutoClearSchema, AutoCompactSchema, AutoResumeSchema, KeepWarmSchema, 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';
 import { getLlamaSwapStatus, triggerLlamaSwapLoad, exceedsSafeContextFloor, CLAUDE_MIN_SAFE_CONTEXT_TOKENS, } from './custom-model-routes.js';
@@ -27,7 +27,7 @@ import { TabLayoutValidationError } from '../../tab-layout.js';
 import { sessionWaits, resolveWaitSignals, sessionHookOptions, signalForStatus, WaitCapacityError, } from '../session-wait-registry.js';
 import { RemoteWakeRegistry, REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS, createDefaultRemoteWakeDeps, isProbeable, } from '../../remote-wake.js';
 import { clampWaitMs, MAX_BUFFER_SCAN_BYTES } from '../../config/agent-wait.js';
-import { autoConfigureRalph, canAccessOwned, CASES_DIR, findPersistedSessionOrFail, findSessionOrFail, getAuthUser, isAdmin, isPlainPromptInput, isWorkingDirAllowed, ownerFor, parseBody, persistAndBroadcastSession, resolveAgentCaseOrigin, resolveCasesDir, resolveParentSessionId, sessionCapacityMessage, SETTINGS_PATH, validatePathWithinBase, } from '../route-helpers.js';
+import { autoConfigureRalph, canAccessOwned, CASES_DIR, findPersistedSessionOrFail, findSessionOrFail, getAuthUser, isAdmin, isPlainPromptInput, isWorkingDirAllowed, ownerFor, parseBody, persistAndBroadcastSession, readJsonConfig, resolveAgentCaseOrigin, resolveCasesDir, resolveParentSessionId, sessionCapacityMessage, SETTINGS_PATH, validatePathWithinBase, } from '../route-helpers.js';
 import { buildAgentCaseMarker, writeAgentCaseMarker } from '../../agent-case-marker.js';
 import { canUsernameRunPrivilegedCommands, resolveClaudeModeForUsername } from '../../user-store.js';
 import { clampEnvOverridesForOwner } from '../../session-env-clamp.js';
@@ -58,13 +58,48 @@ import { describeUnknownPath, probePathKind } from '../../utils/index.js';
 import { findLatestOmpSessionId } from '../../utils/omp-session-resolver.js';
 import { scanOmpSessionsHistory } from '../../omp-transcript.js';
 import { scanCodexSessionsHistory, codexThreadBySessionId } from '../../codex-transcript.js';
-import { getLastTranscriptResponse, isExternalCliTranscriptMode, parseExternalCliTranscript, selectLastAnsweredTurn, } from '../response-viewer-transcript.js';
+import { transcriptNeedsScreenCapture, 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();
+const SAFE_CASE_NAME = /^[a-zA-Z0-9_-]+$/;
+/** `<repo>/.claude/worktrees/<name>`: the layout Claude Code's own worktree feature creates. */
+const CLAUDE_WORKTREE_PATH = /^(.*)\/\.claude\/worktrees\/([^/]+)\/?$/;
+/** Did the committed layout put this session in a named group (not Ungrouped)? */
+function landedInGroup(layout, sessionId) {
+    return !!layout?.groups.some((group) => group.refs.some((ref) => ref.kind === 'session' && ref.id === sessionId));
+}
+/**
+ * The case a POST /api/sessions `workingDir` belongs to, for its default session
+ * group: a direct child of the caller's case space, or (admin / single-user, as
+ * GET /api/cases lists them) a linked case's exact path, or a Claude worktree
+ * (`<case>/.claude/worktrees/<name>`) of either. Lexical only: the browser sends
+ * the path the case list gave it, and this must never touch a possibly-dead
+ * mount. Anything else is no case, which keeps today's placement.
+ */
+async function inferLocalCaseName(req, workingDir) {
+    // The Git worktrees modal launches Claude through this route in the worktree, and every other CLI
+    // through quick-start with the case name: both are sessions of that case.
+    const resolved = resolvePath(workingDir);
+    const target = CLAUDE_WORKTREE_PATH.exec(resolved)?.[1] || resolved;
+    const user = getAuthUser(req);
+    if (dirname(target) === resolvePath(resolveCasesDir(user))) {
+        const name = basename(target);
+        if (SAFE_CASE_NAME.test(name))
+            return name;
+    }
+    if (isMultiUserMode() && !isAdmin(req))
+        return undefined;
+    const linked = await readJsonConfig(LINKED_CASES_FILE, 'linked cases', {});
+    for (const [name, path] of Object.entries(linked)) {
+        if (SAFE_CASE_NAME.test(name) && typeof path === 'string' && resolvePath(path) === target)
+            return name;
+    }
+    return undefined;
+}
 // Pre-compiled regex for terminal buffer cleaning (avoids per-request compilation)
 // eslint-disable-next-line no-control-regex
 const CLAUDE_BANNER_PATTERN = /\x1b\[1mClaud/;
@@ -189,6 +224,22 @@ export function stripInkRedrawBloat(buffer) {
  * (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']);
+/**
+ * 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). The browser
+ * keeps its own copies (test/upload-document-list-parity.test.ts pins them).
+ */
+export const ALLOWED_DOCUMENT_EXTS = new Set([
+    '.pdf',
+    '.docx',
+    '.pptx',
+    '.xlsx',
+    '.zip',
+    ...TEXT_UPLOAD_EXTS,
+]);
 /**
  * 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
@@ -456,7 +507,7 @@ async function clampExternalCliBypassForOwner(owner, configs) {
  * named individually, so `privilegedParams` on anything outside that list was declared but
  * unreachable.
  */
-export async function _clampExternalCliBypassForOwner(owner, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig) {
+export async function _clampExternalCliBypassForOwner(owner, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig, copilotConfig) {
     const out = await clampExternalCliBypassForOwner(owner, {
         codexConfig,
         geminiConfig,
@@ -464,6 +515,7 @@ export async function _clampExternalCliBypassForOwner(owner, codexConfig, gemini
         piConfig,
         grokConfig,
         deepSeekConfig,
+        copilotConfig,
     });
     return out;
 }
@@ -1102,7 +1154,7 @@ options = {}) {
         // Section 6.3: force non-granted users to a classifier-guarded mode.
         const effectiveClaudeMode = await resolveClaudeModeForUsername(claudeModeConfig.claudeMode, owner);
         // Section 6.3: clamp Codex/Gemini/Antigravity bypass switches for a non-granted owner (no-op single-user/granted).
-        const { codexConfig: gatedCodexConfig, geminiConfig: gatedGeminiConfig, antigravityConfig: gatedAntigravityConfig, piConfig: gatedPiConfig, grokConfig: gatedGrokConfig, deepSeekConfig: gatedDeepSeekConfig, } = await _clampExternalCliBypassForOwner(owner, launchBody.codexConfig, launchBody.geminiConfig, launchBody.antigravityConfig, launchBody.piConfig, launchBody.grokConfig, launchBody.deepSeekConfig);
+        const { codexConfig: gatedCodexConfig, geminiConfig: gatedGeminiConfig, antigravityConfig: gatedAntigravityConfig, piConfig: gatedPiConfig, grokConfig: gatedGrokConfig, deepSeekConfig: gatedDeepSeekConfig, copilotConfig: gatedCopilotConfig, } = await _clampExternalCliBypassForOwner(owner, launchBody.codexConfig, launchBody.geminiConfig, launchBody.antigravityConfig, launchBody.piConfig, launchBody.grokConfig, launchBody.deepSeekConfig, launchBody.copilotConfig);
         const terminalHistoryConfig = await ctx.getTerminalHistoryConfig();
         const session = new Session({
             workingDir,
@@ -1120,6 +1172,7 @@ options = {}) {
             antigravityConfig: mode === 'antigravity' ? gatedAntigravityConfig : undefined,
             piConfig: mode === 'pi' ? gatedPiConfig : undefined,
             grokConfig: mode === 'grok' ? gatedGrokConfig : undefined,
+            copilotConfig: mode === 'copilot' ? gatedCopilotConfig : undefined,
             deepSeekConfig: mode === 'deepseek' ? gatedDeepSeekConfig : undefined,
             ompConfig: resolveOmpConfigForCreate(mode, workingDir, launchBody.ompConfig),
             resumeSessionId: validatedResumeId,
@@ -1131,9 +1184,13 @@ options = {}) {
             owner,
             parentSessionId: resolveParentSessionId(ctx, req, body.parentSessionId, owner),
         });
-        const tabLayout = body.tabGroupId
-            ? await ctx.addSession(session, { tabGroupId: body.tabGroupId })
-            : await ctx.addSession(session);
+        // Only a named workingDir: without one the session starts in the server's own cwd, which is no case.
+        const placementCase = remote || !body.workingDir ? undefined : await inferLocalCaseName(req, workingDir);
+        const placement = {
+            ...(body.tabGroupId ? { tabGroupId: body.tabGroupId } : {}),
+            ...(placementCase ? { caseName: placementCase } : {}),
+        };
+        const tabLayout = Object.keys(placement).length > 0 ? await ctx.addSession(session, placement) : await ctx.addSession(session);
         ctx.store.incrementSessionsCreated();
         ctx.persistSessionState(session);
         await ctx.setupSessionListeners(session);
@@ -1148,9 +1205,13 @@ options = {}) {
         // Avoids serializing 2-3MB of terminal+text buffers per session creation.
         const lightState = ctx.getSessionStateWithRespawn(session);
         ctx.broadcast(SseEvent.SessionCreated, 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 } : {}) };
+        // A grouped creation (asked for, or its case's default group) 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 || landedInGroup(tabLayout, session.id) ? { tabLayout } : {}),
+        };
     });
     // ========== Rename Session ==========
     app.put('/api/sessions/:id/name', async (req) => {
@@ -1228,6 +1289,7 @@ options = {}) {
             return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
         }
         const contextLength = endpoint.modelContextLengths?.[body.modelId];
+        const slotCount = endpoint.modelSlotCounts?.[body.modelId];
         // Some CLIs (today: only claude) carry enough of their own fixed system-prompt/tool-
         // schema overhead that a small enough real context guarantees a first-message failure
         // no matter what CLAUDE_CODE_MAX_CONTEXT_TOKENS says — confirmed live at ~36.4K tokens
@@ -1237,12 +1299,13 @@ options = {}) {
         // `confirmed`, which still means both) — NOT by `confirmedSwap`: this warning is
         // about the caller's own session, and the swap warning below is about someone
         // else's, so an answer to one is not consent to the other.
-        if (!(body.confirmed || body.confirmedContext) && exceedsSafeContextFloor(entry, contextLength)) {
+        if (!(body.confirmed || body.confirmedContext) && exceedsSafeContextFloor(entry, contextLength, slotCount)) {
             return {
                 requiresContextWarning: true,
                 modelId: body.modelId,
                 contextLength,
                 minSafeContextTokens: CLAUDE_MIN_SAFE_CONTEXT_TOKENS,
+                ...(slotCount && slotCount > 1 ? { slotCount } : {}),
             };
         }
         // llama.cpp runs exactly one model at a time; llama-swap unloads and reloads it on
@@ -2417,7 +2480,13 @@ options = {}) {
         // where a real rollout file is the better source.
         if (isExternalCliTranscriptMode(session.mode)) {
             const externalQuery = req.query;
-            const blocks = parseExternalCliTranscript(session.terminalBuffer, session.mode);
+            // A repainting full-screen TUI (copilot) streams absolute cursor moves, not lines, so the
+            // buffer cannot be segmented; read the pane's visible screen instead, and fall back to the
+            // buffer when there is no tmux pane to ask (direct PTY, tests).
+            const screen = transcriptNeedsScreenCapture(session.mode) && session.muxName
+                ? (ctx.mux.capturePaneText?.(session.muxName) ?? null)
+                : null;
+            const blocks = parseExternalCliTranscript(screen ?? session.terminalBuffer, session.mode);
             return {
                 text: getLastTranscriptResponse(blocks),
                 timestamp: '',
@@ -3065,6 +3134,32 @@ options = {}) {
             },
         };
     });
+    // ========== Prompt-cache keep-warm ==========
+    // Per-session opt-in for the keep-alive nudge (prompt-cache-keepwarm.ts). `enabled: null`
+    // clears the choice so the app-wide default applies again. Refused for a CLI that reports
+    // no cache telemetry on its statusline: without `expires_at` there is nothing to schedule.
+    app.post('/api/sessions/:id/keep-warm', async (req) => {
+        const { id } = req.params;
+        const body = parseBody(KeepWarmSchema, req.body, 'Invalid request body');
+        const session = findSessionOrFail(ctx, id, req);
+        if (!getCli(session.mode)?.capabilities.statusLineTelemetry) {
+            return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Prompt-cache keep-warm needs the cache telemetry this CLI does not report');
+        }
+        session.setKeepWarmEnabled(body.enabled ?? undefined);
+        // Re-evaluate BEFORE the state broadcast and the response: both carry `keepWarm`, and a
+        // page that received the previous status would overwrite the one the toggle just produced.
+        await ctx.keepWarm.schedule(id);
+        persistAndBroadcastSession(ctx, session);
+        return {
+            success: true,
+            data: {
+                keepWarm: {
+                    enabled: session.keepWarmEnabled ?? null,
+                    status: session.keepWarm,
+                },
+            },
+        };
+    });
     // ========== Auto-Resume (usage-limit pause) ==========
     app.post('/api/sessions/:id/auto-resume', async (req) => {
         const { id } = req.params;
@@ -3227,7 +3322,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, tabGroupId, worktree, } = parseBody(QuickStartSchema, req.body);
+        const { caseName = 'testcase', sessionName, mode = 'claude', modelOverride, openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, 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);
@@ -3277,6 +3372,7 @@ options = {}) {
                 antigravityConfig ||
                 piConfig ||
                 grokConfig ||
+                copilotConfig ||
                 deepSeekConfig ||
                 ompConfig ||
                 openCodeConfig ||
@@ -3335,6 +3431,7 @@ options = {}) {
                 antigravityConfig ||
                 piConfig ||
                 grokConfig ||
+                copilotConfig ||
                 deepSeekConfig ||
                 ompConfig ||
                 openCodeConfig ||
@@ -3419,6 +3516,7 @@ options = {}) {
                     antigravityConfig,
                     piConfig,
                     grokConfig,
+                    copilotConfig,
                     deepSeekConfig,
                 }));
                 if (qsLaunchError) {
@@ -3605,6 +3703,7 @@ options = {}) {
             antigravityConfig,
             piConfig,
             grokConfig,
+            copilotConfig,
             deepSeekConfig,
             ompConfig,
         };
@@ -3623,7 +3722,7 @@ options = {}) {
         const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
         const qsEffectiveClaudeMode = await resolveClaudeModeForUsername(qsClaudeModeConfig.claudeMode, owner);
         // Section 6.3: clamp Codex/Gemini/Antigravity bypass switches for a non-granted owner (no-op single-user/granted).
-        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 { codexConfig: qsGatedCodexConfig, geminiConfig: qsGatedGeminiConfig, antigravityConfig: qsGatedAntigravityConfig, piConfig: qsGatedPiConfig, grokConfig: qsGatedGrokConfig, deepSeekConfig: qsGatedDeepSeekConfig, copilotConfig: qsGatedCopilotConfig, } = await _clampExternalCliBypassForOwner(owner, qsLaunchConfigs.codexConfig, qsLaunchConfigs.geminiConfig, qsLaunchConfigs.antigravityConfig, qsLaunchConfigs.piConfig, qsLaunchConfigs.grokConfig, qsLaunchConfigs.deepSeekConfig, qsLaunchConfigs.copilotConfig);
         const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
         const qsGatedEnvOverrides = await clampEnvOverridesForOwner(owner, envOverrides);
         const qsResolvedOmpConfig = resolveOmpConfigForCreate(mode, workspacePath, qsLaunchOmpConfig);
@@ -3660,6 +3759,7 @@ options = {}) {
             if (!cmEndpoint)
                 return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found');
             const cmContextLength = cmEndpoint.modelContextLengths?.[customModel.modelId];
+            const cmSlotCount = cmEndpoint.modelSlotCounts?.[customModel.modelId];
             // See the dedicated route's own comment for the full reasoning: some CLIs' own fixed
             // overhead can exceed a small enough real context on the very first message,
             // regardless of contextLengthVar. Warn before creating a session that's certain to
@@ -3667,12 +3767,13 @@ options = {}) {
             // See the dedicated route above for why this reads `confirmedContext` and never
             // `confirmedSwap`.
             if (!(customModel.confirmed || customModel.confirmedContext) &&
-                exceedsSafeContextFloor(cmEntry, cmContextLength)) {
+                exceedsSafeContextFloor(cmEntry, cmContextLength, cmSlotCount)) {
                 return {
                     requiresContextWarning: true,
                     modelId: customModel.modelId,
                     contextLength: cmContextLength,
                     minSafeContextTokens: CLAUDE_MIN_SAFE_CONTEXT_TOKENS,
+                    ...(cmSlotCount && cmSlotCount > 1 ? { slotCount: cmSlotCount } : {}),
                 };
             }
             // See the dedicated route's own comment for the full reasoning: llama.cpp runs one
@@ -3758,6 +3859,7 @@ options = {}) {
             antigravityConfig: mode === 'antigravity' ? qsGatedAntigravityConfig : undefined,
             piConfig: mode === 'pi' ? qsGatedPiConfig : undefined,
             grokConfig: mode === 'grok' ? qsGatedGrokConfig : undefined,
+            copilotConfig: mode === 'copilot' ? qsGatedCopilotConfig : undefined,
             deepSeekConfig: mode === 'deepseek' ? qsGatedDeepSeekConfig : undefined,
             ompConfig: qsResolvedOmpConfig,
             envOverrides: qsCustomModelEnvOverrides,
@@ -3805,7 +3907,7 @@ options = {}) {
                 session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart
             }
         }
-        const tabLayout = tabGroupId ? await ctx.addSession(session, { tabGroupId }) : await ctx.addSession(session);
+        const tabLayout = await ctx.addSession(session, { caseName, ...(tabGroupId ? { tabGroupId } : {}) });
         ctx.store.incrementSessionsCreated();
         ctx.persistSessionState(session);
         await ctx.setupSessionListeners(session);
@@ -3891,7 +3993,7 @@ options = {}) {
                 caseName,
                 ...(worktree ? { worktree, workingDir: workspacePath } : {}),
                 ...(customModel ? { modelSwapInProgress: qsCustomModelSwapInProgress } : {}),
-                ...(tabGroupId ? { tabLayout } : {}),
+                ...(tabGroupId || landedInGroup(tabLayout, session.id) ? { tabLayout } : {}),
             };
         }
         catch (err) {
@@ -4016,8 +4118,6 @@ options = {}) {
         }
         return sawNonCli;
     }
-    /** `<repo>/.claude/worktrees/<name>` — the layout Claude Code's own worktree feature creates. */
-    const CLAUDE_WORKTREE_PATH = /^(.*)\/\.claude\/worktrees\/([^/]+)\/?$/;
     /**
      * Recover cwd / branch / worktree from a transcript chunk.
      *
@@ -4782,12 +4882,6 @@ options = {}) {
     // 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',
@@ -5006,12 +5100,19 @@ options = {}) {
             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'}`
+                // A text refusal names the encoding, since an Excel or Notepad export
+                // (UTF-16 with a BOM, or Windows-1252) is not a corrupt file.
+                const isText = TEXT_UPLOAD_EXTS.has(origExt);
+                const bom = imageBytes.length >= 2 ? imageBytes.readUInt16BE(0) : 0;
+                const utf16 = bom === 0xfffe || bom === 0xfeff;
+                const detail = isText
+                    ? `reason=${utf16 ? 'utf16-bom' : 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}`);
+                return createErrorResponse(ApiErrorCode.INVALID_INPUT, isText
+                    ? `This ${origExt} file is ${utf16 ? 'UTF-16 text, not UTF-8' : 'not UTF-8 text'}; save it as UTF-8 and attach it again`
+                    : `File bytes do not match declared type ${origExt}`);
             }
             const saved = await writeBufferedUpload(session.workingDir, origExt, imageBytes, sanitizeUploadStem(part.filename));
             if (!saved) {