/** * @fileoverview Session management routes. * Covers session CRUD, input/output, terminal buffer, quick-start, quick-run, * auto-clear, auto-compact, image watcher, flicker filter, and logout. */ import { claudeProjectDirName } from '../../case-rename.js'; import { FastifyInstance, type FastifyRequest } from 'fastify'; import { z } from 'zod'; import { join, dirname, extname, basename, isAbsolute, 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'; 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, type ApiResponse, type SessionColor, type SessionStatus, type SessionMode, type CodexConfig, type GeminiConfig, type AntigravityConfig, type PiConfig, type GrokConfig, type CopilotConfig, type DeepSeekConfig, type OmpConfig, type RemoteHost, } from '../../types.js'; import { GuardedInputBusyError, Session, cliTakesSessionModel, isAltScreenStripMode, isExternalCliMode, isMuxAltScreenOnlyStripMode, isMuxMouseStripMode, } from '../../session.js'; import type { PaneCaptureOptions } from '../../mux-interface.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, KeepWarmSchema, GitFetchSettingsSchema, PinSessionSchema, ImageWatcherSchema, FlickerFilterSchema, QuickRunSchema, QuickStartSchema, InteractiveStartSchema, SessionOrderUpdateSchema, SessionWaitQuerySchema, SessionWaitOutputQuerySchema, CustomModelSelectionSchema, } from '../schemas.js'; import { readCustomModelHosts, resolveCustomModelContextLength } from '../../custom-model-hosts.js'; import { applyCustomModelInjection, removeConfigDir } from '../../custom-model-injection-apply.js'; import { buildCustomModelInjection } from '../../custom-model-injection.js'; import { getLlamaSwapStatus, triggerLlamaSwapLoad, exceedsSafeContextFloor, CLAUDE_MIN_SAFE_CONTEXT_TOKENS, } from './custom-model-routes.js'; import { matchesPattern } from '../../config/cli-registry/patterns.js'; import { ownerLayoutKey } from '../../tab-layout-persistence.js'; import { TabLayoutValidationError, type TabLayout } from '../../tab-layout.js'; import { sessionWaits, resolveWaitSignals, sessionHookOptions, signalForStatus, WaitCapacityError, type WaitSignal, type SignalWaitResult, } from '../session-wait-registry.js'; import { RemoteWakeRegistry, REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS, createDefaultRemoteWakeDeps, isProbeable, type WakeableRemote, } 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, readJsonConfig, resolveAgentCaseOrigin, resolveCasesDir, resolveParentSessionId, sessionCapacityMessage, validatePathWithinBase, waitCapacityResponse, abortOnClientHangUp, } from '../route-helpers.js'; import { mutateSettingsFile } from '../settings-writer.js'; import { buildAgentCaseMarker, writeAgentCaseMarker } from '../../agent-case-marker.js'; import { agentInbox } from '../agent-inbox.js'; import { canUsernameRunPrivilegedCommands, resolveClaudeModeForUsername } from '../../user-store.js'; import { clampEnvOverridesForOwner } from '../../session-env-clamp.js'; import { enabledClis, getCli } from '../../config/cli-registry/registry.js'; import type { AgentSkillDir, CliEntry, NewlineSequence } from '../../config/cli-registry/types.js'; import { resolveCliLaunchError } from '../../utils/cli-launcher.js'; 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, 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'; import { getLifecycleLog } from '../../session-lifecycle-log.js'; import { mergeUnifiedSessions, filterAndPaginate, type LiveSessionInput, type PersistedSessionInput, type LifecycleInput, type HistoryInput, type MuxStatInput, type UnifiedSessionItem, } from '../../services/unified-session-service.js'; import { buildHistorySessionIndexItems, setHistoryIndexRefresher, setHistorySessionIndex, } from '../session-history-index.js'; import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort, TabLayoutPort, KeepWarmPort, } from '../ports/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, 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'; import { scanOmpSessionsHistory } from '../../omp-transcript.js'; import { scanCodexSessionsHistory, codexThreadBySessionId } from '../../codex-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_-]+$/; /** `/.claude/worktrees/`: 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: TabLayout | undefined, sessionId: string): boolean { return !!layout?.groups.some((group) => group.refs.some((ref) => ref.kind === 'session' && ref.id === sessionId)); } /** * Guard a session-supplied configDir home BEFORE `applyCustomModelInjection` runs. * * The apply resolves the CLI's real home from this session's env override and then runs * synchronous `existsSync`/`mkdirSync` on it (deepseek `DSH_HOME`, and any future * `linkFromRealHome` recipe). A path on an unreachable network mount makes a synchronous * stat wait forever, and this runs INSIDE a request handler, so it would freeze the whole * web server (CLAUDE.md, the #516 rule on user-chosen paths). A relative home is left to * the apply, which already refuses to join non-absolute values. * * Probe the session's own home with `probePathKind(..., { pastCap: true })` first: on * `'unknown'` (a dead mount that never answered) hand the apply a lookup that hides that * one env var, so linking falls through to the server's own environment and the unresponsive * path is never touched. Any other entry's lookup passes through untouched. */ export async function guardSessionConfigDirHome( entry: Pick, baseLookup: (envVar: string) => string | undefined ): Promise<(envVar: string) => string | undefined> { const recipe = entry.capabilities.customModelInjection; if (recipe?.kind !== 'configDir' || !recipe.linkFromRealHome?.length) return baseLookup; const dirEnvVar = recipe.dirEnvVar; const supplied = baseLookup(dirEnvVar)?.trim(); if (!supplied || !isAbsolute(supplied)) return baseLookup; if ((await probePathKind(supplied, { pastCap: true })) === 'unknown') { console.warn( `[custom-model] ${dirEnvVar} (${supplied}) did not answer; linking from the server's own home instead` ); return (envVar: string) => (envVar === dirEnvVar ? undefined : baseLookup(envVar)); } return baseLookup; } /** * 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 * (`/.claude/worktrees/`) 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: FastifyRequest, workingDir: string): Promise { // 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/; // eslint-disable-next-line no-control-regex const CTRL_L_PATTERN = /\x0c/g; const LEADING_WHITESPACE_PATTERN = /^[\s\r\n]+/; /** * Match xterm alternate-screen mode toggles + the standalone scrollback-erase. * * - DECSET/DECRST 47, 1047, 1049 = enter/exit alternate screen buffer * (1049 also saves cursor and clears the alt buffer). * - CSI 3 J = erase saved lines (scrollback). * * Codex AND Claude Code emit `\x1b[?1049h` and clear-scrollback sequences (the * latter intermittently, e.g. full-screen pickers/dialogs). xterm.js obeys them * by switching to the alt buffer (no native scrollback) and wiping saved lines, * so the user's conversation history disappears on every tab switch / pane * refresh (and scroll-up breaks live). Stripping these from the replayed byte * stream keeps everything in the main buffer with scrollback intact. Mirrors the * live-stream strip in Session._handleTerminalOutput (isAltScreenStripMode). */ // eslint-disable-next-line no-control-regex const ALT_SCREEN_TOGGLE_PATTERN = /\x1b\[\?(?:47|1047|1049)[hl]/g; // eslint-disable-next-line no-control-regex const ERASE_SCROLLBACK_PATTERN = /\x1b\[3J/g; // Mouse-tracking enables (X10/button/any-event/UTF-8/SGR/alt-scroll) — once on, // xterm.js forwards wheel events to the app instead of scrolling the viewport. // Live streams are stripped at the source, but buffers persisted BEFORE that // strip existed can still carry them; strip on replay for parity. // eslint-disable-next-line no-control-regex const MOUSE_TRACKING_PATTERN = /\x1b\[\?(?:1000|1001|1002|1003|1005|1006|1007)[hl]/g; /** * The replay half of the strip parity triangle: what `_handleTerminalOutput` (session.ts) * removes from the live stream, removed again from a stored buffer before it is replayed, * because a buffer recorded before the live-side strip existed (or by an older server) * still carries the sequences, and one replayed enable is enough to re-park xterm. * * - `strip-full` (claude/codex/gemini): alt-screen toggles, `3J` and mouse DECSETs. * xterm obeys the toggles by switching to its scrollback-less alt buffer and wiping * saved lines, so history disappeared on tab switch. * - `strip-mux-and-mouse` (opencode, tmux-backed): alt-screen toggles and mouse DECSETs. * A replayed tracking enable parks xterm in report mode, where a drag goes to the CLI * instead of selecting text (and Ctrl+C without a selection is opencode's app_exit). * `3J` stays: a TUI is not a `clear` consumer. * - every other mode, tmux-backed: tmux's own client smcup only (#205). * * Exported so the parity with the live strip is a test (claude-scrollback-strip.test.ts). */ export function stripReplayBuffer(buffer: string, mode: SessionMode, usesMux: boolean): string { if (isAltScreenStripMode(mode)) { return buffer .replace(ALT_SCREEN_TOGGLE_PATTERN, '') .replace(ERASE_SCROLLBACK_PATTERN, '') .replace(MOUSE_TRACKING_PATTERN, ''); } if (isMuxMouseStripMode(mode, usesMux)) { return buffer.replace(ALT_SCREEN_TOGGLE_PATTERN, '').replace(MOUSE_TRACKING_PATTERN, ''); } if (isMuxAltScreenOnlyStripMode(mode, usesMux)) return buffer.replace(ALT_SCREEN_TOGGLE_PATTERN, ''); return buffer; } /** * Strip redundant Ink spinner/status-bar redraw frames from the terminal buffer. * Ink (Claude Code's TUI) uses absolute cursor positioning (CSI n d = VPA) to animate * the spinner and update the status bar. During long thinking phases, these frames * accumulate to 500KB+ of repeated overwrites to the same rows. * * Strategy: detect "redraw clusters" — dense runs of VPA escapes where each is within * FRAME_GAP bytes of the previous (i.e. continuous rerendering of the same UI region). * Collapse each big cluster down to just the bytes from its last VPA onwards (the final * frame). Content *between* clusters (Claude's streamed response text) is preserved. * * Without clustering, a single first-VPA-finds-all approach would discard the entire * conversation after Claude's first render — losing 100KB+ of legitimate scrollback. */ export function stripInkRedrawBloat(buffer: string): string { // eslint-disable-next-line no-control-regex const vpaRe = /\x1b\[\d+d/g; const positions: number[] = []; let m: RegExpExecArray | null; while ((m = vpaRe.exec(buffer)) !== null) { positions.push(m.index); } if (positions.length < 10) return buffer; // Too few VPAs to be bloat // Group consecutive VPAs into clusters separated by gaps > FRAME_GAP. // Within a cluster, VPAs are close together (continuous rerenders). // Between clusters, real terminal output (response text) lives. const FRAME_GAP = 8 * 1024; // 8KB — one Ink frame is typically 1-4KB const MIN_BLOAT_SIZE = 32 * 1024; // Only collapse clusters spanning >= 32KB const clusters: { start: number; end: number }[] = []; let cs = positions[0]; let ce = positions[0]; for (let i = 1; i < positions.length; i++) { if (positions[i] - ce <= FRAME_GAP) { ce = positions[i]; } else { clusters.push({ start: cs, end: ce }); cs = positions[i]; ce = positions[i]; } } clusters.push({ start: cs, end: ce }); // For each big cluster, replace [start..end] with the bytes from `end` onwards // (which contains the last frame's content up to where the next cluster, or // post-cluster content, begins). const parts: string[] = []; let cursor = 0; for (const cl of clusters) { if (cl.end - cl.start < MIN_BLOAT_SIZE) continue; parts.push(buffer.slice(cursor, cl.start)); cursor = cl.end; } parts.push(buffer.slice(cursor)); return parts.join(''); } /** * 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']); /** * 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: ReadonlySet = 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 * 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: Buffer, ext: string): boolean { if (TEXT_UPLOAD_EXTS.has(ext)) return data.length > 0 && !data.includes(0) && isUtf8(data); if (data.length < 12) return false; const u32be = (off: number): number => 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': case '.jpeg': return data[0] === 0xff && data[1] === 0xd8 && data[2] === 0xff; case '.gif': return ( data[0] === 0x47 && data[1] === 0x49 && data[2] === 0x46 && data[3] === 0x38 && (data[4] === 0x37 || data[4] === 0x39) && data[5] === 0x61 ); case '.webp': // RIFF....WEBP return u32be(0) === 0x52494646 && u32be(8) === 0x57454250; case '.bmp': return data[0] === 0x42 && data[1] === 0x4d; case '.heic': case '.heif': { // ISO Base Media File Format: size + "ftyp" + major brand. The brand // list matches heic-decode's own isHeic() — accepting more brands here // would only route bytes into a conversion that always throws. if (u32be(4) !== 0x66747970) return false; 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; } } /** * 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: string): Promise { // 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: unknown) { if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err; try { await fs.mkdir(uploadDir); } catch (mkErr: unknown) { // 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 as NodeJS.ErrnoException).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: unknown) { if ((err as NodeJS.ErrnoException).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; } /** * The part of an uploaded document's name that survives into the saved name, * so `Q3 report (final).pdf` is findable as `paste---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: string): string { 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: string, ext: string, 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 VIDEO_RATE_TOKENS = 3; const PASTE_BUCKET_TTL_MS = 60 * 60 * 1000; const PASTE_BUCKET_GC_THRESHOLD = 1000; const pasteRateBuckets = new Map(); const videoRateBuckets = new Map(); function takeToken( buckets: Map, key: string, capacity: number, now: number ): boolean { if (buckets.size > PASTE_BUCKET_GC_THRESHOLD) { for (const [k, b] of buckets) { if (now - b.lastRefill > PASTE_BUCKET_TTL_MS) buckets.delete(k); } } let b = buckets.get(key); if (!b) { b = { tokens: capacity, lastRefill: now }; buckets.set(key, b); } 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: string, now: number = Date.now()): boolean { 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: string, now: number = Date.now()): boolean { return takeToken(videoRateBuckets, key, VIDEO_RATE_TOKENS, now); } // Test hook: reset between runs. export function _resetPasteRateBuckets(): void { pasteRateBuckets.clear(); videoRateBuckets.clear(); } /** * Security (multi-user §6.3): the Claude-only permission-mode downgrade does not * cover the other CLIs' bypass switches. Codex `--dangerously-bypass-approvals-and-sandbox`, * Gemini `--approval-mode yolo`, and Antigravity `--dangerously-skip-permissions` disable * the safety classifier the non-granted-user downgrade is meant to keep on, so clamp them * for a non-granted owner. buildGeminiCommand defaults an ABSENT approvalMode to yolo, so * the gemini config must be MATERIALIZED (auto_edit) even when the request sent none. * Antigravity is like Codex: an ABSENT config already defaults safe (no bypass flag), so * only a sent config needs the flag forced off. No-op in single-user mode / for a granted * owner (canUsernameRunPrivilegedCommands returns true when !isMultiUserMode()). * * Pi has no permission prompts at all, so there is no bypass switch to clamp; its * privilege-shaped knob is `approveProjectTrust`, which makes pi LOAD AND EXECUTE * repo-local `.pi/extensions` TypeScript and npm-install missing project packages. * Pi joins the gemini-style MATERIALIZE branch, not the codex/antigravity * only-if-sent one: pi's absent-config default is an interactive trust prompt the * session user could simply answer "yes" to in the terminal, so merely omitting * `--approve` is not a clamp. Forcing `approveProjectTrust: false` makes * buildPiCommand emit `--no-approve`, and the prompt never appears. * * Grok is like Codex/Antigravity: the bypass switch is `alwaysApprove` * (`--always-approve`), and an ABSENT config already spawns in grok's own * ask-mode default, so only a sent config needs the flag forced off. * * DeepSeek joins the same only-if-sent branch, but its switch is not a flag: the * harness has no command-line permission option, and its sandbox/approval rows * read `DSH_PERMISSION_MODE`. Omitting that export leaves the harness on its own * `workspace-write` preset, which still asks, so an absent config is already * safe; a sent one is forced down to `workspace-write` rather than to * `read-only`, because the clamp exists to remove PRIVILEGE, not to break a * session's ability to edit its own workspace. */ async function clampExternalCliBypassForOwner( owner: string | undefined, configs: Record ): Promise> { if (await canUsernameRunPrivilegedCommands(owner)) return configs; const out = { ...configs }; for (const entry of enabledClis()) { const field = entry.launch.legacyConfigField; if (!field) continue; // `privilegedParams[].param` names the REGISTRY param, so it has to be translated to the // legacy wire field on the way out — the same `legacyConfigAliases` hop `configSetenvValues` // already makes. Writing `param` straight through would put it in a DIFFERENT namespace // from every other `param` in the schema, and a name that is right in one and wrong in the // other is a SILENT no-op: no load error, no failing test, the clamp simply stops clamping. // Codex is where the two names differ (`bypassApprovals` vs `dangerouslyBypassApprovals`), // and `schema.ts` refuses an entry naming a param it never declared. const aliases = entry.launch.legacyConfigAliases ?? {}; const existing = out[field] as Record | undefined; let next = existing; for (const { param, clampTo, materializeWhenAbsent } of entry.capabilities.privilegedParams) { // MATERIALIZE vs ONLY-IF-SENT is the whole design of this clamp, and the two are not // interchangeable — see CliCapabilities.privilegedParams. Materialize where the CLI's // own absent-config default is ITSELF unsafe (gemini defaults to yolo; pi's default is // an interactive trust prompt the session user could just answer "yes" to), so a // caller who sends no config at all still gets clamped. if (next === undefined && !materializeWhenAbsent) continue; next = { ...(next ?? {}), [aliases[param] ?? param]: clampTo }; } if (next !== existing) out[field] = next; } return out; } /** * Test hook, and the positional shape the clamp has always been called with in tests. * * The clamp itself is now generic over the registry, which is what makes a CUSTOM CLI's * privileged flag clampable with no code here — previously the five config objects were * named individually, so `privilegedParams` on anything outside that list was declared but * unreachable. */ export async function _clampExternalCliBypassForOwner( owner: string | undefined, codexConfig?: CodexConfig, geminiConfig?: GeminiConfig, antigravityConfig?: AntigravityConfig, piConfig?: PiConfig, grokConfig?: GrokConfig, deepSeekConfig?: DeepSeekConfig, copilotConfig?: CopilotConfig ): Promise<{ codexConfig: CodexConfig | undefined; geminiConfig: GeminiConfig | undefined; antigravityConfig: AntigravityConfig | undefined; piConfig: PiConfig | undefined; grokConfig: GrokConfig | undefined; deepSeekConfig: DeepSeekConfig | undefined; copilotConfig: CopilotConfig | undefined; }> { const out = await clampExternalCliBypassForOwner(owner, { codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, deepSeekConfig, copilotConfig, }); return out as { codexConfig: CodexConfig | undefined; geminiConfig: GeminiConfig | undefined; antigravityConfig: AntigravityConfig | undefined; piConfig: PiConfig | undefined; grokConfig: GrokConfig | undefined; deepSeekConfig: DeepSeekConfig | undefined; copilotConfig: CopilotConfig | undefined; }; } /** Test hook: the env-var half of the same multi-user safety gate. */ export const _clampEnvOverridesForOwner = clampEnvOverridesForOwner; // ═══════════════════════════════════════════════════════════════ // Agent wait helpers (shared by GET /wait, GET /wait-output, POST /input) // ═══════════════════════════════════════════════════════════════ /** * Validate a wait query WITHOUT throwing away the Zod issue. * * `parseBody`'s message argument REPLACES the issue text, so `?timeout=30s` came * back as a bare "Invalid wait parameters": the caller could not tell which of * `until`, `timeout` or `fresh` it got wrong, and its only move was to retry with * a different guess. These endpoints are driven by an LLM with no documentation in * context — the error message IS the documentation, which is why the signal parser * one line later goes to the trouble of naming the bad token and listing the valid * ones. This keeps the endpoint label AND names the offending field. */ function parseWaitQuery(schema: z.ZodType, query: unknown, label: string): T { const result = schema.safeParse(query); if (result.success) return result.data; const issue = result.error.issues[0]; const field = issue && issue.path.length > 0 ? issue.path.join('.') : ''; const detail = issue?.message ?? 'validation failed'; const message = field ? `Invalid ${label} parameter '${field}': ${detail}` : `Invalid ${label} parameters: ${detail}`; throw Object.assign(new Error(message), { statusCode: 400, body: createErrorResponse(ApiErrorCode.INVALID_INPUT, message), }); } /** * The signal a session is ALREADY emitting, corrected for liveness. * * `signalForStatus` alone is not enough here, because `Session` parks a DEAD PTY at * `_status = 'idle'` (both `onExit` handlers do) and the object survives in the * session map until an explicit DELETE. Trusting the status therefore answers the * default wait with `{signal:"idle", immediate:true}` for a worker that has * crashed — HTTP 200, no error anywhere, and the agent types its next prompt into a * corpse — while `until=exit` blocks for the full timeout on an event that already * happened and can never happen again. * * `pid === null` means no process is behind this session: it exited, it was * detached, or it was created and never started. All three are `exit` from a * caller's point of view — nothing is running — and in all three the agent's * correct next move is to (re)start the worker rather than to type at it. The * response still carries the raw `status` alongside, so nothing is hidden. * * ⚠️ `pid` alone is NOT enough, and on the normal configuration it is never the * thing that fires — see `workerIsDead()`. `dead` carries the mux layer's answer. * * Fixing it HERE rather than in `signalForStatus` is deliberate: liveness is not * derivable from `SessionStatus`, and the registry holds no `Session` reference. */ function currentSignalFor(session: { pid: number | null; status: SessionStatus }, dead: boolean): WaitSignal | null { if (dead || session.pid === null || session.pid === undefined) 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: { pid: number | null; status: SessionStatus; screenBlocked?: boolean }, dead: boolean, until: readonly WaitSignal[] ): WaitSignal | null { 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 // `remain-on-exit on` for every session it creates, so when the command inside the // pane exits, tmux keeps the pane (`pane_dead=1`), the tmux session survives, the // attach client keeps running and `pid` never goes null — no `exit` event is emitted // and nothing in `Session` changes. Measured on a shell worker killed with `exit 42`: // tmux reports `pane_dead=1 status=42` while Codeman reports `pid=309406 status=idle` // and the DEFAULT wait answers `{signal:"idle", immediate:true}` in 0 ms for a corpse. // So the liveness check has to ask the mux layer. `pid === null` still matters: it is // the right (and only) answer for a direct-PTY session, which has no pane to ask about. // // Cost control, because `isPaneDead()` is a synchronous `execSync` and `/wait` is // polled in a loop by design: // 1. Only mux-backed sessions are probed at all. // 2. Only requests that actually wait probe — a plain `POST .../input` (the browser's // hot path, thousands per session) never touches tmux. // 3. Results are cached per pane for PANE_DEATH_TTL_MS, so a poll loop cannot turn // into one exec per request. // 4. The while-blocked watcher is ONE timer per session no matter how many waiters // are parked on it, and it exists only while at least one of them is. /** How long a pane-liveness probe is reused. Long enough to absorb a poll loop. */ const PANE_DEATH_TTL_MS = 750; /** How often a session with a parked waiter is re-checked for a dead worker. */ const PANE_DEATH_POLL_MS = 3_000; /** Bounded, because a 24h server churns through panes. */ const paneDeathCache = new LRUMap({ maxSize: 256 }); /** One watcher per pane, refcounted by the waits currently parked on it. */ const paneDeathWatchers = new Map(); type LivenessSession = { usesMux?: boolean; muxName?: string | null }; /** * Whether the worker inside this session's tmux pane has exited. * * False for anything not tmux-backed (nothing to ask), and false when the probe is * unavailable or throws — an unknown answer must never invent a death. */ function workerIsDead(mux: InfraPort['mux'], session: LivenessSession, now: number = Date.now()): boolean { const muxName = session.usesMux === false ? null : session.muxName; if (!muxName) return false; // Defensive: `TerminalMultiplexer` declares it, but route-test doubles may not. if (typeof mux?.isPaneDead !== 'function') return false; const cached = paneDeathCache.get(muxName); if (cached && now - cached.at < PANE_DEATH_TTL_MS) return cached.dead; let dead = false; try { dead = mux.isPaneDead(muxName) === true; } catch { dead = false; } paneDeathCache.set(muxName, { dead, at: now }); return dead; } /** * Release every waiter on a session whose worker has died, in the documented order. * * The same pair the PTY-exit listener and the delete path use, for the same reason: * `until=exit` callers get their signal, everyone else gets `ended: true` instead of * burning the rest of their timeout on feeds that will never produce anything. */ function releaseWaitersForDeadWorker(sessionId: string): void { sessionWaits.notifySignal(sessionId, 'exit'); sessionWaits.cancelAll(sessionId); } /** * While a wait is parked on a mux-backed session, poll for the worker dying. * * Without this, a worker that dies DURING a wait is invisible: no `exit` event fires * (the attach client is still alive), no output arrives, and the caller blocks for its * full timeout — the common orchestration case, "send a prompt and wait", where the * worker crashes mid-turn. * * @returns a release function; call it in a `finally`, or the timer outlives the wait. */ function watchForDeadWorker(mux: InfraPort['mux'], session: LivenessSession, sessionId: string): () => void { const muxName = session.usesMux === false ? null : session.muxName; if (!muxName || typeof mux?.isPaneDead !== 'function') return () => {}; const existing = paneDeathWatchers.get(muxName); if (existing) { existing.refs++; } else { const timer = setInterval(() => { if (!workerIsDead(mux, session)) return; releaseWaitersForDeadWorker(sessionId); }, PANE_DEATH_POLL_MS); // Auxiliary to the waiter's own timer, which is deliberately NOT unref'd; this one // must never be the reason the process stays up. timer.unref(); paneDeathWatchers.set(muxName, { timer, refs: 1 }); } let released = false; return () => { if (released) return; released = true; const entry = paneDeathWatchers.get(muxName); if (!entry) return; entry.refs--; if (entry.refs <= 0) { clearInterval(entry.timer); paneDeathWatchers.delete(muxName); } }; } /** Test seam: pane-liveness state is module-level, so a suite must be able to reset it. */ export function _resetPaneLivenessState(): void { for (const entry of paneDeathWatchers.values()) clearInterval(entry.timer); paneDeathWatchers.clear(); paneDeathCache.clear(); } /** Test seam: how many panes are currently being watched for a dead worker. */ export function _paneDeathWatcherCount(): number { return paneDeathWatchers.size; } /** * Inject the agent skill into a case on create, surfacing only the REFUSALS. * * `applyAgentSkill` declines two shapes rather than writing through them ('foreign': * an unmarked skills/codeman the user authored; 'symlink': the skill dir or its * parent is a link). Both were silent: the user flips `agentSkillEnabled` on, nothing * appears in the case, and there is nowhere to look for why. The ordinary outcomes * ('installed'/'refreshed'/'unchanged') stay unlogged since they would print on every * single session create. * * Injection is best-effort and stays that way: neither a refusal nor a thrown error * may fail the create. */ async function injectAgentSkill(casePath: string, dir: AgentSkillDir): Promise { 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 // stale user copy silently replaces every fresh injection (observed 2026-08-14: an // old copy cost every spawned worker its lineage arc and the fast path). Keep it // 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, 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.` ); } else if (result === 'symlink') { console.warn( `[agent-skill] not injected: ${skillDir} (or its parent) is a symlink, refusing to write through it. Replace it with a real directory to let Codeman install the skill.` ); } } catch (err: unknown) { console.warn(`[agent-skill] injection failed for ${skillDir}: ${getErrorMessage(err)}`); } } // Workspace hooks: the install-vs-refresh decision core moved to // `applyWorkspaceHooks` in hooks-config.ts (imported above) so the non-route // claude create paths — cron fires, legacy scheduled runs, the plan-orchestrator // one-shots, the boot recovery sweep — share the SAME decision instead of // bypassing the `workspaceHooksEnabled` setting. Route handlers here resolve the // setting through the ConfigPort (tests stub it) and pass it as the second arg. /** * A "Resume"/"continue" request for a NEW omp-mode session (the frontend's * resumeHistorySession(), or anyone hitting the API directly) carries * `continueSession: true` but no id — omp has none to give it, since Codeman * has never tracked its own conversation UUID. Left as `--continue`, that * picks whichever session file in the directory is newest, which silently * drifts to the WRONG conversation the moment a second omp session (this * one, a sibling worker, a stray manual run) has touched the same directory * more recently. Resolve the real id up front instead, same as the * dead-pane-respawn path in session.ts does, so even the FIRST relaunch of a * resumed conversation is pinned rather than guessed. */ export function resolveOmpConfigForCreate( mode: SessionMode, workingDir: string, ompConfig: OmpConfig | undefined ): OmpConfig | undefined { if (mode !== 'omp') return undefined; if (!ompConfig || ompConfig.resumeSessionId || !ompConfig.continueSession) { return ompConfig; } const resolvedId = findLatestOmpSessionId(workingDir); if (!resolvedId) { console.warn( `[Session] OMP: no session file found under ${workingDir} to pin --resume; falling back to ambiguous --continue` ); } return resolvedId ? { ...ompConfig, resumeSessionId: resolvedId } : ompConfig; } /** * The tmux history lines a full capture may read (`capture-pane -S -`): the * optional `lines` query parameter, an integer of at least 1, never more than * the configured history limit; absent or malformed, the limit itself, as * before. A grid tile sends its own scrollback size: its xterm keeps no more * than that, while a capture of the whole history (tens of thousands of lines, * cut to `tail` only afterwards) is synchronous work on this event loop. */ function captureHistoryLines(raw: string | undefined, historyLimit: number): number { if (typeof raw !== 'string' || !/^\d{1,9}$/.test(raw)) return historyLimit; const lines = Number(raw); return lines >= 1 ? Math.min(lines, historyLimit) : historyLimit; } /** * `RemoteHost` → the wake registry's host shape. They differ in one field name only * (`id` in host config vs `hostId` on a session's `remote`), but the rename is load- * bearing: the registry keys its per-host wake state on `hostId`. The proxy fields * travel too: they are what tells the registry its probe cannot reach this host. */ function wakeableHost(host: RemoteHost): WakeableRemote { return { hostId: host.id, label: host.label, host: host.host, port: host.port, wakeMac: host.wakeMac, wakeCommand: host.wakeCommand, jumpHost: host.jumpHost, socksProxy: host.socksProxy, extraSshOptions: host.extraSshOptions, }; } export function registerSessionRoutes( app: FastifyInstance, ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort & TabLayoutPort & KeepWarmPort, /** Test seam: inject a registry with fake IO instead of the real TCP/WoL probes. */ options: { remoteWake?: RemoteWakeRegistry } = {} ): RemoteWakeRegistry { // Wake-on-LAN for sleeping remote hosts (see remote-wake.ts). One registry per // route registration (= one web server) — the same shape as the process-wide // `sessionWaits` singleton, but without the global. // // ⚠️ The ONLY caller that may wake a host is the input route below. The // auto-reconnect watcher and boot recovery deliberately have no access to this // registry: waking there would re-wake the host seconds after every suspend, so // it could never stay asleep. const remoteWake = options.remoteWake ?? new RemoteWakeRegistry( createDefaultRemoteWakeDeps({ noteReconnected: (sessionId, success) => { // Duck-typed exactly like server.ts: TmuxManager owns the COD-108 backoff // state, and the port interface does not expose it. const mux = ctx.mux as unknown as { noteRemoteReconnect?: (id: string, ok: boolean) => void }; mux.noteRemoteReconnect?.(sessionId, success); }, broadcast: (event, payload) => ctx.broadcast(event, payload), log: (message) => console.log(message), // The session's `remote` block is a launch-time snapshot, so a wake target // configured later (banner's config dialog, or a hand-edited remote-hosts.json) // is resolved here — throttled by the registry, and the host config is // authoritative in BOTH directions (removing the field turns the feature off // for a live session too). resolveRemote: async (session) => { const remote = session.remote; if (!remote) return undefined; const hosts = await readRemoteHosts(CODEMAN_CONFIG_DIR); return rehydrateRemoteHostFields(remote, new Map(hosts.map((host) => [host.id, host]))); }, }) ); // ═══════════════════════════════════════════════════════════════ // Auth // ═══════════════════════════════════════════════════════════════ // ========== Logout ========== app.post('/api/logout', async (req, reply) => { // Invalidate server-side session token (not just the browser cookie) const sessionToken = req.cookies[AUTH_COOKIE_NAME]; if (sessionToken) { ctx.authSessions?.delete(sessionToken); } // The web-tab proxy authenticates on capabilities, not on this cookie, so a // 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 {}; }); // ═══════════════════════════════════════════════════════════════ // Session CRUD (list, create, rename, color, delete, detail) // ═══════════════════════════════════════════════════════════════ // ========== Session Listing ========== app.get('/api/sessions', async (req) => { const list = ctx.getLightSessionsState(); if (!isMultiUserMode()) return list; const user = getAuthUser(req); if (user.role === 'admin') return list; return (list as Array<{ owner?: string }>).filter((s) => canAccessOwned(user, s.owner)); }); // ========== Legacy Session Tab Order (temporary synchronized compatibility bridge) ========== app.put('/api/session-order', async (req, reply): Promise> => { try { const { order } = parseBody(SessionOrderUpdateSchema, req.body, 'Invalid session order'); const user = getAuthUser(req); const result = await ctx.tabLayouts.putLegacyOrder( { owner: ownerLayoutKey(ownerFor(req)), isAdmin: user.role === 'admin' }, order ); return { success: true, data: { order: result.order } }; } catch (error) { if (error instanceof TabLayoutValidationError) { return reply.code(400).send(createErrorResponse(ApiErrorCode.INVALID_INPUT, error.message)); } throw error; } }); // ========== Session Creation ========== app.post('/api/sessions', async (req) => { const owner = ownerFor(req); // Global + per-user session cap. const capMsg = sessionCapacityMessage(ctx.sessions, owner); if (capMsg) return createErrorResponse(ApiErrorCode.OPERATION_FAILED, capMsg); const body = parseBody(CreateSessionSchema, req.body); // The top-level `model` is Claude's per-session `--model`. Every other CLI takes its model // in its own config object (`codexConfig.model` and so on), so a `model` here would be // dropped without a word; refuse it before anything is written for the session. if (body.model && !cliTakesSessionModel(body.mode ?? 'claude')) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'model applies to claude sessions only; other CLIs take their model in their own config object, such as codexConfig.model' ); } // An attach launches nothing (the remote agent is already running), so a launch model // or advisor would be dropped the same way, so both are refused, as they have been since // they were added. The older launch fields (effort, envOverrides) predate this and keep // their silent ignore here, since refusing them now would break existing callers. if (body.attachRemoteSession && (body.model || body.advisorModel)) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'model and advisorModel shape a new launch, and attachRemoteSession launches nothing; leave them out when attaching' ); } let workingDir = body.workingDir || process.cwd(); let remote = undefined; // COD-105 — attach to a discovered (non-owned) remote tmux session. The // remote session is already running, so we skip the tmux-prereq probe and // build a NON-owned SessionRemote (detach-not-kill on close). Remote CASE // creation (owned durable sessions) is handled by the dedicated case-create // endpoint below, which #145 consolidated remote-host resolution into. if (body.attachRemoteSession) { // Remote hosts are admin-only infrastructure everywhere else (the list answers // `[]` to a non-admin; write and discovery routes are `adminOnly`), and the wake // below spawns the host's `wakeCommand` or broadcasts a packet. So the gate comes // FIRST — before the host is even looked up — or an unprivileged account could // invoke that executable for any configured `hostId` and only then be told the // workingDir was outside its workspace (reproduced upstream: wake spy fired, 403). if (isMultiUserMode() && !isAdmin(req)) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Remote hosts are admin-only in multi-user mode'); } const { hostId, remoteSessionName } = body.attachRemoteSession; const host = (await readRemoteHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === hostId); if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Remote host not found'); // An explicit wake request is the only thing that may wake a host, and the user // pressing Attach IS one (see quick-start for the same gate, and // `remote-wake.ts` for what must never call this). Without it a sleeping host // answers with an ssh failure that blames anything but the machine being asleep. const hostWake = await remoteWake.ensureHostAwake(wakeableHost(host), { timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS, // No session yet, so the wake events name their requester (multi-user routing). requestedBy: ownerFor(req), }); if (hostWake === 'failed') { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, `${host.label} did not come back after a wake-on-LAN request — nothing was attached` ); } workingDir = `${host.username}@${host.host}:${remoteSessionName}`; remote = toAttachedSessionRemote(host, remoteSessionName, workingDir); } // Multi-user: shell mode is arbitrary command execution as the host account, // gated behind the same grant as bypass (section 6.3). Resolve the owner's grant // from the store so a GRANTED regular user is not wrongly denied (AuthUser role alone can't tell). if ( getCli(body.mode ?? 'claude')?.capabilities.privilegedCommandGate && !(await canUsernameRunPrivilegedCommands(owner)) ) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Shell sessions require the can-bypass-permissions grant'); } // Multi-user linchpin (section 6.2): a non-admin's workingDir must resolve // inside their own case space. Enforced BEFORE any disk-mutating call below so // a foreign path can never be written into. if (!isWorkingDirAllowed(getAuthUser(req), workingDir)) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'workingDir is outside your workspace'); } // Validate workingDir exists and is a directory. Bounded: a workingDir on a // network mount that stopped answering must not freeze the event loop, and // "did not answer" is reported as such, never as "does not exist". if (body.workingDir) { const kind = await probePathKind(workingDir, { pastCap: true }); if (kind === 'unknown') { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, describeUnknownPath('workingDir', workingDir, { pastCap: true }) ); } if (kind === 'absent') { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist'); } if (kind !== 'directory') { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory'); } } // envOverrides flow through Session → tmux setenv (ephemeral, per-session). // // For keys the caller is actively setting, strip any stale disk entry a prior // Codeman version may have written. Scope limited to: // - Claude mode (OpenCode/Codex/Gemini/Antigravity don't read .claude/settings.local.json) // - workingDir inside CASES_DIR / the per-user case space (Codeman's managed // territory — we never mutate .claude/settings.local.json in arbitrary user // repos that POST /api/sessions can target, as those may have hand-authored // values). const managedCasesBase = resolveCasesDir(getAuthUser(req)); // `!isExternalCliMode()` is byte-identical to the eight-mode `!==` chain it replaces // (claude and shell are the two non-external modes) and, unlike the chain, cannot fall // behind the next CLI added. const canStripDisk = !isExternalCliMode(body.mode ?? 'claude') && body.envOverrides && Object.keys(body.envOverrides).length > 0 && (workingDir.startsWith(CASES_DIR + '/') || workingDir.startsWith(managedCasesBase + '/')); if (canStripDisk) { await stripCaseEnvKeys(workingDir, Object.keys(body.envOverrides!)); } // Write model override to .claude/settings.local.json if provided if (body.modelOverride !== undefined) { await updateCaseModel(workingDir, body.modelOverride || null); } // Plan-usage telemetry (App Settings → header chip): no request-time field // here anymore, and NO disk write — a settings.local.json statusLine used // to take precedence over the user's own global/project statusLine for ANY // `claude` run in that directory, including entirely outside Codeman, with // no disclosure and no way to undo it (real bug, found 2026-08-31). // TmuxManager.createSession reads the persisted `showPlanUsageLimits` // setting FRESH at spawn (readPlanUsageTelemetryEnabled in hooks-config.ts) // and resolves it into an EPHEMERAL `claude --settings` CLI flag — never // written to disk, so a plain `claude` run outside Codeman is untouched — // and applies uniformly to every claude creation path (this route, cron, // the Ralph Loop API, quick-start), not just this one. That resolution // also self-heals: it strips any legacy disk-written exporter an older // Codeman build left behind. // Hooks for the workspace this session runs in (install vs refresh-only is the // `workspaceHooksEnabled` setting; see applyWorkspaceHooks). Never for a remote // attach (workingDir is a user@host:session pseudo-path — mkdir would create it // as a junk local dir), and only when the caller named a workingDir: the // process-cwd fallback is $HOME under installer-created services, and hooks // materializing in ~/.claude/settings.local.json was never asked for. if (!remote && body.workingDir && (body.mode ?? 'claude') === 'claude') { await applyWorkspaceHooks(workingDir, await ctx.getWorkspaceHooksEnabled()); } // 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 // resolution actually looked (server PATH, login shell, the entry's search dirs); a // LAUNCHER CLI answers with its own more specific reason instead — for dsh, whether the // binary is missing, no pane-capable profile exists, or the profile the caller NAMED // cannot drive a pane, which are three different things to go and fix. // // Scoped to EXTERNAL CLIs, matching what this route has always pre-flighted: claude and // shell deliberately fall through to tmux-manager's own not-found throw instead, and // pulling them forward here would change which error a missing claude produces. const requestedMode = body.mode ?? 'claude'; if (getCli(requestedMode)?.capabilities.external) { const cliLaunchError = await resolveCliLaunchError( requestedMode, legacyConfigForMode(requestedMode, body as unknown as Record) ); if (cliLaunchError) { 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. let validatedResumeId = body.resumeSessionId; if (validatedResumeId) { const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects'); let found = false; try { const projectDirs = await fs.readdir(projectsDir); for (const projDir of projectDirs) { const sessionFile = join(projectsDir, projDir, `${validatedResumeId}.jsonl`); try { const stat = await fs.stat(sessionFile); if (stat.size > 4000) { found = true; break; } } catch { // File doesn't exist in this project dir } } } catch { // Projects dir doesn't exist } if (!found) { console.log(`[Session] Resume session ${validatedResumeId} not found on disk, starting fresh`); validatedResumeId = undefined; } } const globalNice = await ctx.getGlobalNiceConfig(); const modelConfig = await ctx.getModelConfig(); const mode = body.mode || 'claude'; // Synced App Settings launch defaults (capabilities.launchDefaults, codex's model and // effort today) fill the CLI's own config object where the caller left it unset. // Local launches only: a remote attach runs whatever the remote pane already runs. const launchBody = remote ? body : await applyLaunchDefaults(mode, body); // Where a model override comes from is a capability, and the three answers are // genuinely different mechanisms: // 'flag' — the CLI takes --model, so read the value the caller sent // in that CLI's own config object. // 'claude-settings-file' — claude alone, whose persistent model is written to // /.claude/settings.local.json (`modelOverride`). A // per-session `model` from the caller goes out as --model and // wins; without one, the app-wide default applies. // 'none' — shell has no model; deepseek's is a composition entry in // the profile's config tree, not a session field // (docs/deepseek-integration.md). Both get nothing. const modelSource = getCli(mode)?.capabilities.model; const model = modelSource?.source === 'flag' ? (legacyConfigForMode(mode, launchBody as unknown as Record)?.[ modelSource.param ?? 'model' ] as string | undefined) : modelSource?.source === 'claude-settings-file' ? body.model || modelConfig?.defaultModel || undefined : undefined; const claudeModeConfig = await ctx.getClaudeModeConfig(); // 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, 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, mode, name: body.name || '', mux: ctx.mux, useMux: true, niceConfig: globalNice, model, claudeMode: effectiveClaudeMode, allowedTools: claudeModeConfig.allowedTools, openCodeConfig: mode === 'opencode' ? launchBody.openCodeConfig : undefined, codexConfig: mode === 'codex' ? gatedCodexConfig : undefined, geminiConfig: mode === 'gemini' ? gatedGeminiConfig : undefined, 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, envOverrides: await clampEnvOverridesForOwner(owner, body.envOverrides), effort: body.effort, advisorModel: body.advisorModel, tmuxHistoryLimit: terminalHistoryConfig.tmuxHistoryLimit, remote, owner, parentSessionId: resolveParentSessionId(ctx, req, body.parentSessionId, owner), }); // 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); // Pre-seed the agent skill's preamble cache so its §0 bootstrap is a two-line // 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: unknown) => console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`) ); } getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name }); // Use light state for broadcast + response — buffers are fetched on-demand via /terminal. // Avoids serializing 2-3MB of terminal+text buffers per session creation. const lightState = ctx.getSessionStateWithRespawn(session); ctx.broadcast(SseEvent.SessionCreated, lightState); // 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) => { const { id } = req.params as { id: string }; const body = parseBody(SessionNameSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); const name = String(body.name || '').slice(0, MAX_SESSION_NAME_LENGTH); // A no-op rename (the Session Options name field saves on blur and recomposes the same // string) must not flip nameSource to 'manual' or append a custom-title row to the transcript. if (name === session.name) return { name: session.name }; session.name = name; // Also update the mux session name if applicable ctx.mux.updateSessionName(id, session.name); persistAndBroadcastSession(ctx, session); await syncClaudeTitle(session); return { name: session.name }; }); // ========== Set Session Color ========== app.put('/api/sessions/:id/color', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(SessionColorSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); const validColors = ['default', 'red', 'orange', 'yellow', 'green', 'blue', 'purple', 'pink']; if (!validColors.includes(body.color)) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid color'); } session.setColor(body.color as SessionColor); persistAndBroadcastSession(ctx, session); return { color: session.color }; }); // ========== Custom Model Endpoint Profiles (docs/custom-model-endpoints-plan.md) ========== // // Applies (or clears) a session's custom OpenAI-compatible endpoint selection and // RESTARTS the pane's CLI process — these harnesses read endpoint config at process // start, not per-turn, so a live hot-swap isn't possible (confirmed with the // maintainer). Endpoints come from the admin-configured custom-model-hosts store // (chunk 3's CRUD routes), never raw client-supplied env — that's what keeps this // route safe to let any session owner call for their own session, unlike the // generic envOverrides field the privilegedEnvKeys clamp exists to guard. // // ⚠️ Local sessions only for now. A remote session's `restartCli()` renders // `ssh ... tmux new-session -A`, which reattaches the durable remote tmux rather than // restarting the agent, and the env lands on the LOCAL pane running ssh, which // forwards nothing; docker is the same attach-or-create shape. Both used to answer // `restarted: true` and change nothing, so they are refused until those paths are // plumbed (the env would have to ride the remote/in-container launch command). app.post('/api/sessions/:id/custom-model', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(CustomModelSelectionSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); if (session.remote || session.docker) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'Custom model endpoints are not supported for remote (SSH) or Docker sessions yet' ); } if (session.isBusy()) { return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy'); } if ('clear' in body) { const { previousConfigDir } = session.setCustomModel(undefined); removeConfigDir(previousConfigDir); const restarted = await session.restartCli(); persistAndBroadcastSession(ctx, session); return { customModel: session.customModel, restarted }; } const entry = getCli(session.mode); if (!entry) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, `No CLI registry entry for mode ${session.mode}`); } if (entry.capabilities.customModelInjection.kind === 'unsupported') { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${session.mode} has no known custom-model mechanism`); } const hosts = await readCustomModelHosts(getDataDir()); const endpoint = hosts.find((h) => h.id === body.endpointId); if (!endpoint) { return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found'); } // Discovery's per-model figure wins; the endpoint's user-set default covers models // whose size discovery could not determine (a gateway that states none, say). With // neither, the existing "no override, CLI assumes its own default" behaviour stands. const contextLength = resolveCustomModelContextLength(endpoint, body.modelId); const slotCount = endpoint.modelSlotCounts?.[body.modelId]; // A CLI whose config alone cannot select the model also gets its `model` launch param // forced (pi/omp `custom/`, grok's block name, and codex now carries its bare // selected id too). The argv engine DROPS a token that // fails its pattern rather than quoting it, which would silently launch the CLI on its // own default provider again, so refuse an id the pattern cannot carry up front. // The check runs on the PURE build result, before applyCustomModelInjection below: // the forced launch id only comes out of that build, and writing first would mean a // refused id already replaced the config dir a live codex session uses as CODEX_HOME. // It also runs before the two confirmations, so nobody agrees to evict a model only // to be told the id was never usable. const modelSpec = entry.launch.params.model; const injection = buildCustomModelInjection(entry, endpoint, body.modelId, contextLength); const forcedLaunchModel = injection.kind === 'unsupported' ? undefined : injection.launchModel; if ( forcedLaunchModel !== undefined && modelSpec?.type === 'token' && !matchesPattern(modelSpec.pattern, forcedLaunchModel) ) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, `Model id ${JSON.stringify(body.modelId)} cannot be passed to ${session.mode} on its command line` ); } // 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 // against a model configured with a real 16384-token context. Warn before committing // to a restart that's certain to fail, rather than letting the user discover it via a // cryptic 400 from the CLI itself. Answered by `confirmedContext` (or the legacy // `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, 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 // demand, which can take anywhere from a few seconds to over a minute — long enough // that a session mid-swap looks indistinguishable from one that never left the native // backend. Feature-detected via llama-swap's own `GET /running` (a plain llama.cpp // server has no such endpoint and reads as `isLlamaSwap: false` — nothing to check). const swapStatus = await getLlamaSwapStatus(endpoint); const currentlyLoaded = swapStatus.running.find((r) => r.state === 'ready')?.model ?? swapStatus.running[0]?.model; // Distinct from targetReady below: this is ONLY about whether proceeding would evict a // model another session is actively using — true even if nothing is loaded at all yet // would be wrong here (nothing to evict), so this stays narrowly "a DIFFERENT model is // currently ready". const swapNeeded = swapStatus.isLlamaSwap && !!currentlyLoaded && currentlyLoaded !== body.modelId; // Whether the TARGET model itself is already the one loaded and ready — false whether // nothing is loaded yet, a different model is loaded, or this one is loaded but still // mid-load. Drives both the actual load trigger below and modelSwapInProgress in the // response; deliberately broader than swapNeeded, which only gates the confirmation ask. const targetReady = swapStatus.running.some((r) => r.model === body.modelId && r.state === 'ready'); // Only ask when switching would actually take the model away from another session // that is currently using it — never just because a swap is needed at all. Answered // by `confirmedSwap` (or the legacy `confirmed`). ⚠ It must NOT read // `confirmedContext`: this check runs second, and while the two shared one flag a // user who clicked past a too-small-context warning had already, silently, agreed to // evict another session's model. if (swapNeeded && !(body.confirmed || body.confirmedSwap)) { const conflicting = [...ctx.sessions.values()].filter( (s) => s.id !== session.id && s.customModel?.endpointId === endpoint.id && s.customModel?.modelId === currentlyLoaded ); if (conflicting.length > 0) { // Applying a custom model is ungated for any session owner, so in multi-user // mode a non-admin pointing their own session at a shared endpoint must not // learn another user's session names in the confirm dialog — with // autoNameSessions on, those names are that user's own prompts. The swap is // still blocked pending confirmation regardless of ownership (a foreign // session is just as real a disruption); only which ones get NAMED is scoped. const requestUser = getAuthUser(req); const affectedSessions = conflicting .filter((s) => canAccessOwned(requestUser, s.owner)) .map((s) => ({ id: s.id, name: s.name })); return { requiresConfirmation: true, currentlyLoadedModel: currentlyLoaded, affectedSessions }; } } const applied = applyCustomModelInjection( entry, endpoint, body.modelId, session.id, contextLength, session.workingDir, await guardSessionConfigDirHome(entry, (envVar) => session.envOverrideValue(envVar)) ); if (!applied) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${session.mode} has no known custom-model mechanism`); } const { previousConfigDir } = session.setCustomModel( { endpointId: endpoint.id, modelId: body.modelId, label: endpoint.label, envKeys: applied.envKeys, configDir: applied.configDir, launchModel: applied.launchModel, }, applied.envOverrides ); // Clean up the OLD config dir on disk, unless the new one happens to reuse the same // path (same session, configDir kind again) — never delete the dir we just wrote. if (previousConfigDir && previousConfigDir !== applied.configDir) { removeConfigDir(previousConfigDir); } // Actually kick off llama-swap's load now, rather than waiting on the restarted CLI's // own first prompt to do it — confirmed live that applying a selection alone never // reached the llama-swap server at all (nothing in its own logs), since llama-swap has // no "switch model" admin call, only a real inference request naming the model. if (swapStatus.isLlamaSwap && !targetReady) { triggerLlamaSwapLoad(endpoint, body.modelId); } const restarted = await session.restartCli(); persistAndBroadcastSession(ctx, session); return { customModel: session.customModel, restarted, modelSwapInProgress: swapStatus.isLlamaSwap && !targetReady }; }); // ========== Delete Session ========== app.delete('/api/sessions/:id', async (req) => { const { id } = req.params as { id: string }; const query = req.query as { killMux?: string }; const killMux = query.killMux !== 'false'; // Default to true // A resumed/detached-but-never-live row (e.g. a non-claude "Resume" that // relaunched into a NEW session and wants to retire the old one it can no // longer reattach to) has no entry in ctx.sessions at all — only in // persisted state. Fall back to removing that persisted record directly // rather than 404ing: the caller means "make this row go away", and a // stale duplicate row is exactly what's left behind otherwise. Pinned // sessions keep their existing demote-not-delete protection. if (!ctx.sessions.has(id)) { // Called for its existence/ownership 404 side effect only — demoteOrRemoveSession // below re-looks-up the record by id, so the returned SessionState is unused here. findPersistedSessionOrFail(ctx.store, id, req); // The edit history goes with the record (same rule as `cleanupSession`). if (ctx.store.demoteOrRemoveSession(id) === 'removed') ctx.forgetEditHistory(id); // A detached session kept its agent inbox (server.ts _doCleanupSession drops it // only on killMux); retiring the row is the delete, so the mail goes now. agentInbox.drop(id); // Mirrors the broadcast at the tail of the live-session cleanup path // (_doCleanupSession in server.ts) — without it, other open tabs keep // showing the retired row until their next unrelated fetch. ctx.broadcast(SseEvent.SessionDeleted, { id }); return {}; } const session = findSessionOrFail(ctx, id, req); // Wake state is dropped by `cleanupSession` itself (server.ts), on EVERY cleanup // path — not here: the scheduled-run and admin paths clean up without this route. await ctx.cleanupSession(session.id, killMux, 'user_delete'); return {}; }); // ========== Delete All Sessions ========== app.delete('/api/sessions', async (req): Promise> => { // Security: scope the bulk sweep to sessions the caller can access — a non-admin // must not wipe other users' sessions (canAccessOwned is allow-all for admin/single-user). const user = getAuthUser(req); const sessionIds = Array.from(ctx.sessions.values()) .filter((s) => canAccessOwned(user, s.owner)) .map((s) => s.id); let killed = 0; for (const id of sessionIds) { if (ctx.sessions.has(id)) { await ctx.cleanupSession(id, true, 'user_bulk_delete'); killed++; } } return { success: true, data: { killed } }; }); // ========== Get Session Detail ========== app.get('/api/sessions/:id', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); // Use light state (no full buffers) — terminal buffer available via /terminal endpoint. // Full buffers were 2-3MB and caused slowness when polled frequently (e.g. Ralph wizard). return ctx.getSessionStateWithRespawn(session); }); // ═══════════════════════════════════════════════════════════════ // Session Data (output, ralph state, run summary, active tools) // ═══════════════════════════════════════════════════════════════ // ========== Get Session Output ========== app.get('/api/sessions/:id/output', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); return { success: true, data: { textOutput: session.textOutput, messages: session.messages, errorBuffer: session.errorBuffer, }, }; }); // ========== Get Ralph State ========== app.get('/api/sessions/:id/ralph-state', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); return { success: true, data: { loop: session.ralphLoopState, todos: session.ralphTodos, todoStats: session.ralphTodoStats, }, }; }); // ========== Get Run Summary ========== app.get('/api/sessions/:id/run-summary', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); const tracker = ctx.runSummaryTrackers.get(id); if (!tracker) { // Create a fresh tracker if one doesn't exist (shouldn't happen normally) const newTracker = new RunSummaryTracker(id, session.name); ctx.runSummaryTrackers.set(id, newTracker); return { summary: newTracker.getSummary() }; } // Update session name in case it changed tracker.setSessionName(session.name); return { summary: tracker.getSummary() }; }); // ========== Get Active Tools ========== app.get('/api/sessions/:id/active-tools', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); return { success: true, data: { tools: session.activeTools, }, }; }); // ═══════════════════════════════════════════════════════════════ // Session Execution (run prompt, interactive mode, shell mode) // ═══════════════════════════════════════════════════════════════ // ========== Run Prompt ========== app.post('/api/sessions/:id/run', async (req) => { const { id } = req.params as { id: string }; const { prompt } = parseBody(RunPromptSchema, req.body); const session = findSessionOrFail(ctx, id, req); if (session.isBusy()) { return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy'); } // Run async, don't wait session.runPrompt(prompt).catch((err) => { ctx.broadcast(SseEvent.SessionError, { id, error: err.message }); }); ctx.broadcast(SseEvent.SessionRunning, { id, prompt }); return {}; }); // ========== Start Interactive Mode ========== app.post('/api/sessions/:id/interactive', async (req) => { const { id } = req.params as { id: string }; // Body is optional (auto-reattach callers send none) — same idiom as /interactive-respawn. const bodyResult = req.body ? InteractiveStartSchema.safeParse(req.body) : { success: true as const, data: {} as { clearBreaker?: boolean } }; if (!bodyResult.success) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid request body'); } const { clearBreaker } = bodyResult.data; const session = findSessionOrFail(ctx, id, req); if (session.isBusy()) { return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy'); } try { // Auto-detect completion phrase from CLAUDE.md BEFORE starting (only if globally // enabled and not explicitly disabled by user). // // `isExternalCliMode()` is what the eight-mode `!==` chain this replaces was FOR: its // own comment asked the next person to keep the list in step with that predicate by // hand. Calling it instead is byte-identical today (claude and shell are the two // non-external modes, exactly what the chain admitted) and cannot drift. // // ⚠️ Deliberately NOT `capabilities.ralph`, which the quick-start path below reads: // that capability is claude-only, so using it here would stop auto-enabling Ralph for // SHELL sessions, which this path has always done. The two paths genuinely disagree // about shell, and they disagree upstream too — reconciling them is a behaviour change // and belongs in its own PR, not in a refactor that is meant to change nothing. if ( !isExternalCliMode(session.mode) && ctx.store.getConfig().ralphEnabled && !session.ralphTracker.autoEnableDisabled ) { autoConfigureRalph(session, session.workingDir, ctx); if (!session.ralphTracker.enabled) { session.ralphTracker.enable(); } } // COD-118: ONLY an explicit user-initiated restart (body {clearBreaker:true}) // clears a tripped PTY-exit circuit breaker. This endpoint is ALSO the frontend's // automatic re-attach path (selectSession auto-POSTs it for any pid===null // session), so an unconditional reset here would re-arm the exact crash loop // the breaker exists to stop — auto-reattach sends no body and must not clear. if (clearBreaker) { session.resetRespawnBreaker(); } // Re-attach listener wiring if a prior PTY exit detached it: the wiring exit // handler removes ALL session listeners (incl. respawnBreakerTripped), and only // session-create/boot-recovery paths ran setupSessionListeners before this fix — // without this, a re-attached session's SSE/terminal/trip events go unobserved. // setupSessionListeners is idempotent (no-op while refs are still attached). await ctx.setupSessionListeners(session); await session.startInteractive(); getLifecycleLog().log({ event: 'started', sessionId: id, name: session.name, mode: session.mode, }); // Persist, not just broadcast. Starting a command in the pane changes // `pid` and retracts any `paneExit` (Ark0N/Codeman#446), and the pane-exit // watcher cannot write that retraction to disk for us: its next tick finds // the in-memory field already cleared, reports no change and persists // nothing, so `state.json` would keep saying the agent had exited. ctx.persistSessionState(session); ctx.broadcast(SseEvent.SessionInteractive, { id }); ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) }); return {}; } catch (err) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err)); } }); // ========== Start Shell Mode ========== app.post('/api/sessions/:id/shell', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); if (session.isBusy()) { return createErrorResponse(ApiErrorCode.SESSION_BUSY, 'Session is busy'); } try { // Re-attach listener wiring if a prior PTY exit detached it (see /interactive). await ctx.setupSessionListeners(session); await session.startShell(); getLifecycleLog().log({ event: 'started', sessionId: id, name: session.name, mode: 'shell', }); // Persist for the same reason /interactive does: a started pane retracts // `paneExit`, and the watcher's next tick cannot write that retraction. ctx.persistSessionState(session); ctx.broadcast(SseEvent.SessionInteractive, { id, mode: 'shell' }); ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) }); return {}; } catch (err) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err)); } }); // ═══════════════════════════════════════════════════════════════ // Terminal I/O (input, resize, buffer) // ═══════════════════════════════════════════════════════════════ // ========== Wake-on-LAN: state + manual trigger ========== // // Both routes are session-scoped (not host-scoped) because the wake flow needs the // SESSION: a woken host whose pane is not reattached is still a dead terminal, and an // exhausted COD-108 backoff never retries on its own. The probe in `/reachability` is // the same cheap TCP connect the input path uses and it NEVER wakes a host — the UI // decides that, with the button. app.get('/api/sessions/:id/reachability', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); const remote = session.remote; if (!remote) { return { success: true, data: { reachable: true, probeable: true, wakeConfigured: 'none' as const } }; } const force = (req.query as { force?: string })?.force === '1'; // `reachable: null` + `probeable: false` for a host behind a jump host / SOCKS proxy: // the probe cannot reach it, so the UI shows no banner and stops polling. const reachable = await remoteWake.checkReachable(session, { force }); return { success: true, data: { reachable, probeable: isProbeable(remote), wakeConfigured: await remoteWake.wakeConfigured(session), host: remote.host, label: remote.label, }, }; }); app.post('/api/sessions/:id/wake', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); if (!session.remote) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Not a remote session'); } // The UI uses this to route to the host config dialog instead of a dead button. if (!(await remoteWake.hasWakeTarget(session))) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'No wake-on-LAN target configured for this host (set a MAC address or a wake command)' ); } // The button is pressed from the SAME dashboard the create/attach paths are, under // the same reverse proxy — so it holds the request open the same way and needs the // same request budget, not the 90 s session default (see remote-wake.ts). const woke = await remoteWake.ensureAwake(session, { force: true, timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS, }); return { success: true, data: { woke, reachable: await remoteWake.checkReachable(session), wakeConfigured: await remoteWake.wakeConfigured(session), }, }; }); // ========== Send Input ========== app.post('/api/sessions/:id/input', async (req, reply) => { const { id } = req.params as { id: string }; const { input, useMux, seq, clientId, wait, waitTimeout } = parseBody(SessionInputWithLimitSchema, req.body); const session = findSessionOrFail(ctx, id, req); const inputStr = String(input); if (inputStr.length > MAX_INPUT_LENGTH) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, `Input exceeds maximum length (${MAX_INPUT_LENGTH} bytes)` ); } // Send-and-wait (agent orchestration). This has to be ONE endpoint rather than a // POST followed by GET .../wait: between the write and the session flipping to // `working` there is a window in which a separate wait sees the session still // idle and returns instantly, reporting the PREVIOUS turn as this turn's answer. // Registering the waiter before the write closes that window. const wantsWait = wait === true || (typeof wait === 'string' && wait.trim().length > 0) || (Array.isArray(wait) && wait.length > 0); let until: readonly WaitSignal[] = []; if (wantsWait) { const resolved = resolveWaitSignals(wait === true ? undefined : wait, { mode: session.mode, ...sessionHookOptions(session), }); if (resolved.error) return createErrorResponse(ApiErrorCode.INVALID_INPUT, resolved.error); until = resolved.until; } // Reliable delivery (POST fallback when the WebSocket is down): a 2xx IS the // client's ACK, so a tagged duplicate redelivery must still return 200 but // skip the write. Untagged requests (curl/legacy) always apply. const tagged = typeof clientId === 'string' && typeof seq === 'number'; const duplicate = tagged && !session.shouldApplyInput(clientId as string, seq as number); if (duplicate && !wantsWait) { return {}; } // Wake-on-LAN (remote-wake.ts): a wake-enabled remote host that suspended leaves // the local ssh pane STALLED, and `send-keys` succeeds against it — the bytes // would vanish with no error anywhere. Give the registry the chance to probe the // host, wake it, reattach, and own delivery before we write into nothing. // // Costs nothing for non-wake hosts (the `wakeCommand` guard) or while the host is // known reachable inside the probe throttle window; the probe itself is a bare // TCP connect on wake-enabled hosts only, at most once per // REMOTE_WAKE_PROBE_MIN_INTERVAL_MS. if (!duplicate && (await remoteWake.hasWakeTarget(session))) { if (wantsWait) { // Send-and-wait keeps the response open anyway, so blocking on the wake is // simpler and more correct than buffering (buffering would break the wait). // A host that never comes back is an error here, as on the create/attach // paths: writing into the stalled pane would answer `delivered:true` plus a // timeout, which is the combination the API docs send callers to the wrong // recovery for. if (!(await remoteWake.ensureAwake(session))) { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, `${session.remote?.label ?? 'the remote host'} did not come back after a wake-on-LAN request — nothing was sent` ); } } else { const outcome = await remoteWake.handleInput(session, inputStr); // The registry holds the bytes and flushes them in order once the pane is // reattached. The client's ACK is this 200 — a tagged retry is deduped // (`shouldApplyInput` above already consumed the seq), so nothing is lost. // `buffered` is additive to the historical bare `{}`; `dropped` says the chunk // was over the wake buffer's cap and is GONE (a 200 with no field could not // tell delivered from buffered from dropped). if (outcome === 'buffered') return { buffered: true }; if (outcome === 'dropped') return { buffered: true, dropped: true }; } } // A guarded submit (agent-staging.ts) holds the input lease for the few // milliseconds of its conditional Enter, and input that arrives meanwhile is held // and written in arrival order after it. A TAGGED request is refused for that span // (the lease plus the held input's drain) rather than overtake held input: say so // instead of answering 200 for bytes that were never written, and give the seq // back so the browser's durable queue (which keeps a frame on any 409, and whose // POST drainer sends one frame at a time) delivers it on its next retry. An // UNTAGGED request has no retry behind it (the phone accessory keys and the Stop // button's Ctrl+C are fire-and-forget POSTs that never read the answer), so it is // held instead, like a WebSocket frame: `writeViaMux` takes its own turn behind // the lease, and the raw write below is held explicitly. Nothing from here to the // write below awaits, so the lease cannot be taken in between. const refuseGuarded = () => reply .code(409) .send( createErrorResponse( ApiErrorCode.CONFLICT, 'A guarded submit is in progress on this session; nothing was written. Retry the input.' ) ); if (!duplicate && tagged && session.guardedInputHeld === true) { session.forgetInputSeq(clientId as string, seq as number); return refuseGuarded(); } // Only a waiting request pays for the tmux probe: the browser's plain input path // (thousands of calls per session) must stay exec-free. const workerDead = wantsWait && workerIsDead(ctx.mux, session); const timeoutMs = clampWaitMs(waitTimeout ?? undefined); // Same slot leak as the GET routes: a client that gives up mid-wait would // otherwise hold a waiter for the full timeout. Response-side, always — see // abortOnClientHangUp: on THIS route a request-side listener fires the moment the // JSON body finishes streaming and aborts every send-and-wait before it starts. const abort = abortOnClientHangUp(reply); let waitPromise: Promise | null = null; if (wantsWait) { try { waitPromise = sessionWaits.waitForSignal(id, { until, timeoutMs, owner: ownerFor(req), abortSignal: abort.signal, // A FRESH delivery must not be satisfied by the state the session is already // in: it is idle right now, which is precisely why we are typing at it. // 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, // 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) { if (err instanceof WaitCapacityError) { // Nothing has been written yet, but `shouldApplyInput` already consumed the // seq. Give it back or the caller's retry is rejected as a duplicate and the // input is lost by the very mechanism meant to make delivery reliable. if (tagged && !duplicate) session.forgetInputSeq(clientId as string, seq as number); return waitCapacityResponse(err); } throw err; } } const stopDeathWatch = wantsWait ? watchForDeadWorker(ctx.mux, session, id) : () => {}; // Write input to PTY. Direct write is synchronous; writeViaMux // (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). // // Because the response has already been sent by then, a failure there is the // one case the caller can never learn about — so the dedup bookkeeping is // rolled back. Otherwise the seq stays recorded as applied and a retry, the // very mechanism reliable delivery exists for, is rejected as a duplicate. const undoOnFailure = () => { if (tagged) session.forgetInputSeq(clientId as string, seq as number); }; // Whether the bytes actually reached a write path. Only meaningful on the wait // path (the fire-and-forget branches return before the response is built), and // reported there instead of the old `!duplicate`: a PTY that has exited fails // BOTH writes, and telling the caller "delivered, but it timed out" points it at // the wrong recovery — wait longer, when the truth is "restart the worker". let delivered = false; // A plain prompt (`\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 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); if (duplicate) { // Redelivery of an already-applied input: skip the write, but still honor the // wait, since the caller's question ("tell me when this settles") is unanswered. } else if ((useMux || autoMux) && waitPromise) { // The response is already staying open for the wait, so the tmux write can be // awaited here. This is the ONE path where a writeViaMux failure is observable. const ok = await session.writeViaMux(inputStr, { fromUser: true }).catch(() => false); if (ok) { delivered = true; } else { console.warn(`[Server] writeViaMux failed for session ${id}, falling back to direct write`); delivered = session.write(inputStr, { fromUser: true }); if (!delivered) undoOnFailure(); } } else if (autoMux) { // Awaited, unlike the explicit useMux branch below. This shape also reaches here // from the browser's POST fallback, which sends its frames one at a time and // waits for each 2xx; answering only once Enter has gone out is what keeps the // next keystroke from overtaking it. const ok = await session.writeViaMux(inputStr, { fromUser: true }).catch(() => false); if (!ok) { console.warn(`[Server] writeViaMux failed for session ${id}, falling back to direct write`); if (!session.write(inputStr, { fromUser: true })) undoOnFailure(); } } else if (useMux) { // Fire-and-forget: don't block the HTTP response on a tmux child process. // Fallback to a direct write on failure. Unchanged from before send-and-wait. session .writeViaMux(inputStr, { fromUser: true }) .then((ok) => { if (ok) return; console.warn(`[Server] writeViaMux failed for session ${id}, falling back to direct write`); if (!session.write(inputStr, { fromUser: true })) undoOnFailure(); }) .catch(() => { if (!session.write(inputStr, { fromUser: true })) undoOnFailure(); }); } else { // Same rollback. NOT an error response, deliberately: a session can // legitimately have no PTY yet (created but not started), and callers have // always been able to write to one without a 4xx. // // During a guarded submit (untagged only: a tagged one was refused above) the // write is held and runs in arrival order once the lease is released. The answer // is a 200 once held; a send-and-wait reads `delivered` from the held write. Only // a full hold queue refuses, after releasing the waiter registered above. let heldWrite: Promise | null = null; if (session.guardedInputHeld === true) { let settle!: (written: boolean) => void; const written = new Promise((resolve) => { settle = resolve; }); const held = session.holdForGuardedLease( () => { let ok = false; try { ok = session.write(inputStr, { fromUser: true }); } finally { settle(ok); } }, inputStr.length, inputStr ); if (held === 'full') { abort.abort(); stopDeathWatch(); return refuseGuarded(); } if (held === 'held') heldWrite = written; } if (heldWrite && !waitPromise) return {}; delivered = heldWrite ? await heldWrite : session.write(inputStr, { fromUser: true }); if (!delivered && tagged) { session.forgetInputSeq(clientId as string, seq as number); } } if (!waitPromise) return {}; try { // `send-keys` SUCCEEDS against a dead pane — tmux is happy to write into a corpse // — so a truthful `delivered` cannot come from the write's return value alone. // This is the case the field exists for: "delivered, but it timed out" tells an // agent to wait longer when the truth is "restart the worker". if (delivered && workerDead) { delivered = false; // The bytes went nowhere, so the seq must not be recorded as applied or the // caller's retry against a restarted worker is refused as a duplicate. if (!duplicate) undoOnFailure(); } // Nothing was written and nothing will be: no turn is coming, so blocking for the // full timeout would only delay the caller's real recovery by up to ten minutes. // Releasing the waiter also hands its slot back immediately. const selfReleased = !delivered && !duplicate; if (selfReleased) abort.abort(); const result = await waitPromise; return { success: true, data: { delivered, duplicate, status: session.status, limitPaused: session.isLimitPaused, // Identical `wait` object to the two GET endpoints, so one client helper // reads all three, `timeoutMs` (post-clamp) included. // // `aborted` is the CLIENT-facing "you hung up, nobody is reading this", and // by that definition it is unobservable — which is exactly what the API // reference promises. The abort above is the server releasing its own waiter // on a delivery that failed, and the client IS reading this response, so // reporting `aborted: true` there would break that promise and hand an agent // a second, contradictory reason for the same outcome. `delivered: false` // already says what happened; `ended` says the wait was released early. wait: { ...result, aborted: selfReleased ? false : result.aborted, until: [...until] }, }, }; } finally { stopDeathWatch(); } }); // ========== Wait For A Signal (agent orchestration) ========== // // A bounded long-poll: block until the session hits one of `until`, then answer. // This exists because SSE is the only "tell me when" channel Codeman has, and an // agent driving the API from a shell tool cannot hold a stream and parse events // inline. See docs/agent-control-plan.md. // // A TIMEOUT IS A 200, not an error: callers are expected to loop over short waits // (proxies such as `tailscale serve` cut idle connections), and turning every poll // boundary into a 4xx would make that loop indistinguishable from a real failure. app.get('/api/sessions/:id/wait', async (req, reply) => { const { id } = req.params as { id: string }; const query = parseWaitQuery(SessionWaitQuerySchema, req.query, 'wait'); const session = findSessionOrFail(ctx, id, req); // An agent polls this URL in a loop with identical parameters. Any intermediary // applying heuristic freshness to the 200 would serve the stored `timedOut:true` // body to the next iteration instantly, turning the loop into a busy spin that // never observes the signal. reply.header('Cache-Control', 'no-store'); // Shared with the `wait` field on POST .../input: unknown token is a 400, // hook-only signals are rejected explicitly but dropped from the default. const { until, error } = resolveWaitSignals(query.until, { mode: session.mode, ...sessionHookOptions(session) }); if (error) return createErrorResponse(ApiErrorCode.INVALID_INPUT, error); // The value actually applied after clamping, echoed below: a caller that asked // for 30 minutes and silently got 10 could not otherwise tell a poll boundary // from a wedged worker, and would kill a session that was working fine. const timeoutMs = clampWaitMs(query.timeout); // Free the waiter when the caller hangs up; the response can no longer be sent by // then, so freeing the slot is the entire purpose. const abort = abortOnClientHangUp(reply); // A worker that dies while this request is parked emits nothing at all (the tmux // attach client survives it), so a wait would otherwise run to its full timeout. const stopDeathWatch = watchForDeadWorker(ctx.mux, session, id); try { const result = await sessionWaits.waitForSignal(id, { until, timeoutMs, owner: ownerFor(req), abortSignal: abort.signal, requireTransition: query.fresh === '1' || query.fresh === 'true', // Read BEFORE awaiting: this is the state the caller is asking about. currentSignal: currentSignalForWait(session, workerIsDead(ctx.mux, session), until), }); return { success: true, data: { sessionId: id, // Post-wait status, so a caller that timed out still learns where things stand. status: session.status, // A session paused on a usage limit emits nothing until its reset, so a // timeout here is expected rather than a stall worth retrying hard. limitPaused: session.isLimitPaused, // One shape across all three endpoints, so a single `is_done(resp)` helper // works against any of them. `result.timeoutMs` is the value actually // applied after clamping, which is what makes the clamp observable. wait: { ...result, until: [...until] }, }, }; } catch (err) { if (err instanceof WaitCapacityError) return waitCapacityResponse(err); throw err; } finally { stopDeathWatch(); } }); // ========== Wait For Output (agent orchestration) ========== // // The companion to /wait: block until a literal string appears in this session's // output. Same 200-on-timeout contract. Fed by the `terminal` listener in // session-listener-wiring.ts, so what this scans is byte-for-byte what the pane // printed, ANSI stripped. // // ⚠️ A tmux repaint replays text already on screen, so `from=now` can match // something printed before the request. Callers need a marker unique per call. app.get('/api/sessions/:id/wait-output', async (req, reply) => { const { id } = req.params as { id: string }; // Reject `regex` loudly instead of ignoring it. Matching is deliberately literal // (no ReDoS surface on a caller-supplied pattern over a live stream), and an agent // that assumed otherwise would silently wait on the wrong thing. if (req.query && typeof req.query === 'object' && 'regex' in req.query) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'regex is not supported; use match= (optionally with nocase=1)' ); } const query = parseWaitQuery(SessionWaitOutputQuerySchema, req.query, 'wait-output'); const session = findSessionOrFail(ctx, id, req); // Same reason as /wait: this URL is polled in a loop with identical parameters. reply.header('Cache-Control', 'no-store'); const timeoutMs = clampWaitMs(query.timeout); const abort = abortOnClientHangUp(reply); const owner = ownerFor(req); // Output waiters are the ones a dead worker strands hardest: the feed simply stops. const stopDeathWatch = watchForDeadWorker(ctx.mux, session, id); try { // Check the cap BEFORE touching the buffer. `session.terminalBuffer` is // `BufferAccumulator.value`, which joins the WHOLE accumulator (up to 32MB) // before the slice below takes its tail — so a request that is going to be // rejected anyway must not pay for a full materialization first, or the cap // provides no backpressure at all against a `from=buffer` loop. sessionWaits.assertCapacity(id, owner); // `from=buffer` scans what already scrolled past before blocking. Bounded to a // tail: the buffer runs to 32MB and this is a per-request ANSI strip. let initialText: string | undefined; if (query.from === 'buffer') { const buffer = session.terminalBuffer; initialText = buffer.length > MAX_BUFFER_SCAN_BYTES ? buffer.slice(buffer.length - MAX_BUFFER_SCAN_BYTES) : buffer; } const result = await sessionWaits.waitForOutput(id, { match: query.match, nocase: query.nocase === '1' || query.nocase === 'true', timeoutMs, owner, abortSignal: abort.signal, initialText, }); return { success: true, data: { sessionId: id, status: session.status, limitPaused: session.isLimitPaused, // Same envelope as /wait; this one carries `matched`/`snippet`/`match` // where the signal wait carries `signal`/`until`. wait: { ...result, match: query.match }, }, }; } catch (err) { if (err instanceof WaitCapacityError) return waitCapacityResponse(err); throw err; } finally { stopDeathWatch(); } }); // ========== Send Named Key (tmux send-keys -H) ========== // Sends raw hex bytes to tmux pane for keys like Shift+Enter / Ctrl+Enter. // Uses send-keys -H (hex) to inject a newline chord: 0x0a (line feed) by default, or the CLI's // own `capabilities.newline`. Claude Code's Ink input recognizes 0x0a as "insert newline" vs // 0x0d (carriage return = submit). app.post('/api/sessions/:id/send-key', async (req, reply) => { const { id } = req.params as { id: string }; const body = req.body as Record; const key = typeof body?.key === 'string' ? body.key : ''; if (key !== 'S-Enter' && key !== 'C-Enter') { return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Key not allowed: ${key}`); } const session = findSessionOrFail(ctx, id, req); const muxName = session.muxName; if (!muxName) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'No tmux session'); } // Key names map to hex byte sequences. Ctrl+Enter is always a line feed; Shift+Enter is the // CLI's own newline chord (`capabilities.newline`, default line feed), so a CLI that wants // Esc+Enter declares it in the registry instead of being special-cased here. const NEWLINE_HEX: Record = { 'line-feed': ['0a'], // \n 'esc-enter': ['1b', '0d'], // ESC CR, the Alt/Option+Enter chord }; const hex = key === 'C-Enter' ? NEWLINE_HEX['line-feed'] : NEWLINE_HEX[getCli(session.mode)?.capabilities.newline ?? 'line-feed']; try { // Route through the dedicated Codeman socket — bare `tmux` would target the // user's default server and never find this session (same #80 regression class). await session.performAuxiliaryInput( () => new Promise((resolve, reject) => { execFile( 'tmux', ['-L', ctx.mux.muxSocket, 'send-keys', '-H', '-t', muxName, ...hex], { timeout: 5000 }, (err) => { if (err) reject(err); else resolve(); } ); }) ); } catch (err) { // A guarded submit's lease holds the key until its Enter is out; only a full // hold queue refuses it, and that is a retryable conflict, not a tmux failure. if (err instanceof GuardedInputBusyError) { return reply.code(409).send(createErrorResponse(ApiErrorCode.CONFLICT, err.message)); } console.error('[Server] send-key failed:', err); return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'tmux send-keys failed'); } // The bytes bypassed the session's write path, so tell the auto-name // tracker about them or the two lines of a prompt join with no separator. session.trackUserInput(hex.map((byte) => String.fromCharCode(parseInt(byte, 16))).join('')); return {}; }); // ========== Resize Terminal ========== app.post('/api/sessions/:id/resize', async (req) => { const { id } = req.params as { id: string }; const { cols, rows, viewportType, force } = parseBody(ResizeSchema, req.body); const session = findSessionOrFail(ctx, id, req); session.resize(cols, rows, { viewportType, force }); // Answer with the geometry the PTY ACTUALLY holds, which is not always the // one asked for: `Session.resize` declines small-viewport requests while a // desktop connection holds an active sizing claim. A browser terminal left // at a shape the PTY refused renders garbled output, not merely wrong-sized // output, so the client adopts this (issue #464). A session with no pane // reports nothing rather than the constructor defaults — see `ptyGeometry`. return session.ptyGeometry ?? {}; }); // ========== Get Last Response (from transcript JSONL) ========== // How far apart a ~/.claude/history.jsonl entry and a pane's Enter may be and // still be the same submission. Claude appends to history as it accepts the // prompt, so the true gap is milliseconds — this is slack for a loaded box, // not a search radius. const CLAUDE_SUBMIT_MATCH_MS = 10_000; // history.jsonl grows forever; only the tail can hold entries near a submit. const CLAUDE_HISTORY_TAIL_BYTES = 256 * 1024; // Resolves the Claude conversation id THIS pane is currently on by matching // ~/.claude/history.jsonl (which logs every submitted prompt as // {project, sessionId, timestamp}) against the pane's last Enter. After // `/clear` Claude keeps writing to a new .jsonl, and history.jsonl is // the only source-of-truth update that does not rely on project-local hooks // (we intentionally don't install hooks in arbitrary user repos, see the // POST /api/sessions comment). // // The pane's own Enter is what makes an entry OURS. `project` alone is not: // a cwd is shared by every other Codeman tab on it, by tabs long since // closed, and by any plain `claude` the user runs in their own terminal — // adopting the newest entry for the cwd pinned the viewer to whichever of // those conversations was typed in last, so the eye showed a stranger's // transcript. With no correlated entry we keep the id we have; a viewer one // turn behind beats a viewer showing someone else's conversation. const claudeHistoryPinCache = new LRUMap({ maxSize: 1024 }); async function resolveActiveClaudeSessionIdFromHistory( session: Session, projectsDir: string ): Promise { // A pane whose conversation id came from its OWN hook needs no correlation: // $CODEMAN_SESSION_ID (the pane's env) -> data.session_id (the CLI's own // stdin JSON) is a first-hand binding that never looks at cwd, so it cannot // be stolen by a sibling pane, a closed tab, or a bare `claude` in a // terminal. Guessing can only be worse than the fact. This is also what // closes the hole below for a pane driven straight from tmux: it never // reaches `if (!submitAt)`. if (session.claudeSessionIdIsFirstHand) return null; const submitAt = session.lastSubmitAt; if (!submitAt) return null; // no anchor at all — nothing to credit const cached = claudeHistoryPinCache.get(session.id); if (cached && cached.submitAt === submitAt) return cached.claudeSessionId; // Ids another live pane is already pinned to can never be ours, and every // pane sharing this cwd competes for the entry we are about to claim — // including non-Claude panes, since a shell pane can run `claude` too. const otherClaudeIds = new Set(); const otherSubmits: number[] = []; for (const s of ctx.sessions.values()) { if (s.id === session.id || s.workingDir !== session.workingDir) continue; if (s.claudeSessionId) otherClaudeIds.add(s.claudeSessionId); if (s.lastSubmitAt) otherSubmits.push(s.lastSubmitAt); } const historyPath = join(homedir(), '.claude', 'history.jsonl'); const stat = await fs.stat(historyPath).catch(() => null); if (!stat || stat.size === 0) return null; const tail = await readFileTail(historyPath, Buffer.alloc(CLAUDE_HISTORY_TAIL_BYTES), stat.size); if (!tail) return null; let best: { sessionId: string; dist: number } | undefined; for (const line of tail.split('\n')) { if (!line) continue; let entry: { project?: string; sessionId?: string; timestamp?: number }; try { entry = JSON.parse(line) as typeof entry; } catch { continue; // the first tail line is usually cut mid-JSON } const { sessionId, timestamp } = entry; if (entry.project !== session.workingDir) continue; if (typeof sessionId !== 'string' || !sessionId) continue; if (typeof timestamp !== 'number') continue; if (otherClaudeIds.has(sessionId)) continue; const dist = Math.abs(timestamp - submitAt); if (dist > CLAUDE_SUBMIT_MATCH_MS) continue; if (otherSubmits.some((other) => Math.abs(timestamp - other) < dist)) continue; // another pane is closer if (!best || dist <= best.dist) best = { sessionId, dist }; // ties: the newer entry wins } if (!best) return null; // Sanity: the conversation we switch to must exist on disk and must not be // staler than the one we are leaving. A `/clear` successor never is. const currentSessionId = session.claudeSessionId || session.id; if (best.sessionId !== currentSessionId) { const projectDirs = await fs.readdir(projectsDir).catch(() => null); if (!projectDirs) return null; let candidateMtime = 0; let currentMtime = 0; for (const projDir of projectDirs) { const candidateStat = await fs.stat(join(projectsDir, projDir, `${best.sessionId}.jsonl`)).catch(() => null); if (candidateStat && candidateStat.mtimeMs > candidateMtime) candidateMtime = candidateStat.mtimeMs; const currentStat = await fs.stat(join(projectsDir, projDir, `${currentSessionId}.jsonl`)).catch(() => null); if (currentStat && currentStat.mtimeMs > currentMtime) currentMtime = currentStat.mtimeMs; } if (candidateMtime === 0) return null; // transcript not written yet — retry next poll if (currentMtime > 0 && candidateMtime < currentMtime) return null; } claudeHistoryPinCache.set(session.id, { submitAt, claudeSessionId: best.sessionId }); return best.sessionId; } interface ClaudeResponseMessage { kind: 'prompt' | 'response'; label: 'Prompt' | 'Response'; role: 'user' | 'assistant'; text: string; timestamp?: string; turn: number; queued?: boolean; } interface ClaudeTranscriptEntry { type?: string; timestamp?: string; isMeta?: boolean; isSidechain?: boolean; isCompactSummary?: boolean; message?: { content?: unknown }; // A prompt typed while Claude is working is absorbed mid-turn and recorded // ONLY here — the CLI never re-emits it as a `user` row. Every field stays // optional and unvalidated: `queued_command` is not a documented CLI // contract, so a missing/renamed field must mean "skip", which is also what // the CLI's own non-human queue entries (commandMode 'task-notification', // no `origin` key) require. Shape observed on Claude Code 2.1.220-2.1.251. attachment?: { type?: string; prompt?: string; commandMode?: string; timestamp?: string; origin?: { kind?: string }; }; } function extractClaudeText(content: unknown, separator: string): string { if (typeof content === 'string') return content; if (!Array.isArray(content)) return ''; return content .filter( (block): block is { type: string; text: string } => !!block && typeof block === 'object' && (block as { type?: string }).type === 'text' && typeof (block as { text?: string }).text === 'string' ) .map((block) => block.text) .join(separator); } function isClaudeSyntheticUserMessage(entry: ClaudeTranscriptEntry, text: string): boolean { if (entry.isMeta || entry.isCompactSummary) return true; return /^(?:|||(); const currentAssistantFragments = new Set(); // Turn 0 is reserved for anything emitted before the first human prompt. let turn = 0; const pushUserMessage = (text: string, timestamp: string | undefined, queued: boolean): void => { // A run of consecutive human inputs (a mid-turn queued burst) is ONE turn, // so the viewer renders it under one badge instead of one badge per line. if (messages.at(-1)?.role !== 'user') turn += 1; const message: ClaudeResponseMessage = { kind: 'prompt', label: 'Prompt', role: 'user', text, timestamp, turn }; if (queued) message.queued = true; messages.push(message); currentUserFragments.add(text); currentAssistantFragments.clear(); }; for (const line of content.split('\n')) { if (!line) continue; let entry: ClaudeTranscriptEntry; try { entry = JSON.parse(line) as ClaudeTranscriptEntry; } catch { continue; } // Sidechains belong to agents/forks, not the main conversation. Meta user // rows include repeated image dimensions and other UI-generated context. if (entry.isSidechain) continue; // A prompt typed while Claude is working is absorbed mid-turn and lives // ONLY in an attachment row, so it was lost outright. `origin.kind` and // `commandMode` separate the human's queue entries from the CLI's own: // measured over 57 real transcripts on 2026-09-01, 322 queued_command rows // split 163 `prompt`/`human` and 159 `task-notification`, and not one of // those 159 carries an `origin` key. The 163 human rows become 162 user // cards here — one is a verbatim repeat inside a still-unanswered user run // and is collapsed by the dedup guard below — out of 353 user cards total. if (entry.type === 'attachment') { if (!full) continue; const queued = entry.attachment; if (!queued || queued.type !== 'queued_command') continue; if (queued.origin?.kind !== 'human' || queued.commandMode !== 'prompt') continue; const text = typeof queued.prompt === 'string' ? queued.prompt.trim() : ''; if (!text || isClaudeSyntheticUserMessage(entry, text)) continue; if (currentUserFragments.has(text)) continue; pushUserMessage(text, queued.timestamp || entry.timestamp, true); continue; } if (entry.type === 'user') { const text = extractClaudeText(entry.message?.content, '\n').trim(); // A tool_result block has no text block and naturally drops out here. if (!text || isClaudeSyntheticUserMessage(entry, text)) continue; if (!full) continue; // Claude replays the initial user row while restoring a transcript, and // a CLI that also wrote an absorbed prompt as a user row would double it. // Both collapse here. The same prompt sent again AFTER a reply is a // legitimate second turn, because that reply cleared the set. if (currentUserFragments.has(text)) continue; pushUserMessage(text, entry.timestamp, false); continue; } if (entry.type !== 'assistant') continue; const text = extractClaudeText(entry.message?.content, '\n\n').trim(); if (!text) continue; lastText = text; lastTimestamp = entry.timestamp || ''; if (!full) continue; // Replayed snapshots repeat an identical text block inside one turn. if (currentAssistantFragments.has(text)) continue; messages.push({ kind: 'response', label: 'Response', role: 'assistant', text, timestamp: entry.timestamp, turn }); currentAssistantFragments.add(text); currentUserFragments.clear(); } return full ? { text: lastText, timestamp: lastTimestamp, messages } : { text: lastText, timestamp: lastTimestamp }; } /** * Mirror a rename into the conversation's `/resume` title (claude-session-title.ts). * Local Claude-format transcripts only: a remote pane's transcript lives on the remote host and a * docker pane's inside the container (HOME=/home/agent), never under the host's projects dir. Best * effort: the tab rename has already happened and must not fail on this. */ async function syncClaudeTitle(session: Session): Promise { if (getCli(session.mode)?.capabilities.transcript !== 'claude-jsonl' || session.remote || session.docker) return; try { const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects'); const hookPath = ctx.getTranscriptPath(session.id); const transcript = hookPath ? { sessionId: basename(hookPath, '.jsonl'), path: hookPath } : await findClaudeTranscript(projectsDir, session.claudeSessionId || session.id, session.id); if (transcript) await appendClaudeCustomTitle(transcript.path, transcript.sessionId, session.name); } catch (err) { console.warn(`[Session] Could not carry rename into the Claude transcript for ${session.id}:`, err); } } /** Locate a top-level Claude transcript, including recovered tmux sessions. */ async function findClaudeTranscript( projectsDir: string, conversationId: string, codemanSessionId: string ): Promise<{ sessionId: string; path: string } | null> { let projectDirs: import('node:fs').Dirent[]; try { projectDirs = await fs.readdir(projectsDir, { withFileTypes: true }); } catch { return null; } const safeIds = [...new Set([conversationId, codemanSessionId])].filter((value) => /^[a-zA-Z0-9._-]+$/.test(value)); for (const candidateId of safeIds) { for (const projectDir of projectDirs) { if (!projectDir.isDirectory()) continue; const jsonlPath = join(projectsDir, projectDir.name, `${candidateId}.jsonl`); try { const stat = await fs.stat(jsonlPath); if (stat.isFile()) return { sessionId: candidateId, path: jsonlPath }; } catch { /* continue */ } } } // If mux-sessions.json was lost or stale, reconcileSessions() historically // recovered `codeman-40568a29` as `restored-40568a29` and used the server cwd. // The tmux name still carries the first eight UUID characters, which safely // reconnects the viewer when exactly one matching top-level transcript exists. const restoredMatch = /^restored-([a-f0-9]{8,})$/i.exec(codemanSessionId); if (!restoredMatch) return null; const fragment = restoredMatch[1].toLowerCase(); const candidates: Array<{ sessionId: string; path: string; mtimeMs: number }> = []; const uuidPattern = /^[a-f0-9]{8}-[a-f0-9]{4}-[1-5][a-f0-9]{3}-[89ab][a-f0-9]{3}-[a-f0-9]{12}$/i; for (const projectDir of projectDirs) { if (!projectDir.isDirectory()) continue; const dirPath = join(projectsDir, projectDir.name); let files: import('node:fs').Dirent[]; try { files = await fs.readdir(dirPath, { withFileTypes: true }); } catch { continue; } for (const file of files) { if (!file.isFile() || !file.name.endsWith('.jsonl')) continue; const candidateId = file.name.slice(0, -'.jsonl'.length); if (!candidateId.toLowerCase().startsWith(fragment) || !uuidPattern.test(candidateId)) continue; const path = join(dirPath, file.name); const stat = await fs.stat(path).catch(() => null); if (stat) candidates.push({ sessionId: candidateId, path, mtimeMs: stat.mtimeMs }); } } const candidateIds = new Set(candidates.map((candidate) => candidate.sessionId)); if (candidateIds.size !== 1) return null; candidates.sort((a, b) => b.mtimeMs - a.mtimeMs); return candidates[0] ?? null; } // The body of GET /api/sessions/:id/last-response, so the Discord bridge reads the same transcript // the response viewer does (per-CLI reader, pane fallback) without a second copy of this logic. const lastResponseFor = async (session: Session, context?: string) => { // Codex sessions don't write to ~/.claude/projects — their transcripts // live in ~/.codex/sessions/**. Branch to a Codex-specific reader so the // response-viewer works for Codex panes too. if (getCli(session.mode)?.capabilities.transcript === 'codex-rollout') { return await readCodexLastResponse(session, context === 'full'); } // DeepSeek Harness writes a real structured transcript under // `$DSH_HOME/sessions/**`, so read that rather than segmenting the pane. // ⚠️ For dsh the pane fallback is not merely coarse, it is WRONG: dsh-TUI // paints a full-screen splash, and the segmenter served its ASCII-art logo // back as the worker's answer (measured), which an agent polling for a // reply reads as a reply. So an EMPTY transcript result still wins over the // pane — "nothing said yet" is the honest answer. Only `null`, meaning a // Node too old to decode zstd, falls through to the segmenter below. // ⚠️ Local sessions only: a docker case's harness writes its transcript // inside the CONTAINER's ~/.dsh (the workspace bind-mount does not cover // it) and a remote-SSH case's lives on the remote host, so the local // reader would scan a $DSH_HOME that can never hold this session's file // and return "nothing said yet" forever — an agent polling that worker // would starve on an answer that exists. Those configurations keep the // pane segmenter below: coarse, but the real conversation. if (getCli(session.mode)?.capabilities.transcript === 'deepseek-zstd' && !session.docker && !session.remote) { const full = context === 'full'; const transcript = await readDeepSeekLastResponse(session, { blocks: full }); if (transcript) { return { text: transcript.text, timestamp: transcript.timestamp, hasContext: transcript.text.length > 0 || transcript.blocks.length > 0, messages: full ? transcript.blocks : undefined, }; } } // OpenCode / Gemini / Antigravity / Pi render their own TUIs and write no // Claude transcript, so the scan below finds nothing and the response viewer // renders permanently empty for them. Segment the terminal buffer instead — // the pane IS the transcript for these CLIs. Codex is already handled above, // where a real rollout file is the better source. if (isExternalCliTranscriptMode(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: '', hasContext: blocks.length > 0, messages: context === 'full' ? blocks : undefined, }; } // Scan ~/.claude/projects/*/ for the transcript file const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects'); // Adopt the current conversation id if the user ran `/clear` — Claude CLI's // interactive PTY emits no JSON on stdout, so without this lookup the // stored id stays pinned to the pre-/clear transcript. const activeId = await resolveActiveClaudeSessionIdFromHistory(session, projectsDir); if (activeId && activeId !== session.claudeSessionId) { session.adoptClaudeSessionId(activeId); // Flush the Enter that vouched for this adoption to state.json. A `/clear` // emits no completion event, so without this the anchor could still be // unpersisted when the server restarts — and recovery would fall back to // the launch conversation. ctx.persistSessionState(session); // Docker sessions: keep the case's resume seed following the live conversation. if (session.docker) { void persistDockerCaseClaudeSessionId(CODEMAN_CONFIG_DIR, session.docker.containerName, activeId).catch( () => {} ); } } // `turn` is the brief view's context: the last ANSWERED turn's assistant // messages, so a multi-row answer is not reduced to its final row. `text` // stays the last assistant row in every mode (agent pollers hash it). const wantsMessages = context === 'full' || context === 'turn'; const claudeSessionId = session.claudeSessionId || session.id; const transcript = await findClaudeTranscript(projectsDir, claudeSessionId, session.id); if (!transcript) { return wantsMessages ? { text: '', timestamp: '', messages: [] } : { text: '', timestamp: '' }; } if (transcript.sessionId !== session.claudeSessionId && transcript.sessionId !== session.id) { session.adoptClaudeSessionId(transcript.sessionId); if (session.docker) { void persistDockerCaseClaudeSessionId( CODEMAN_CONFIG_DIR, session.docker.containerName, transcript.sessionId ).catch(() => {}); } } try { const content = await fs.readFile(transcript.path, 'utf8'); const parsed = parseClaudeResponseTranscript(content, wantsMessages); if (context === 'turn') { return { text: parsed.text, timestamp: parsed.timestamp, messages: selectLastAnsweredTurn(parsed.messages ?? []), }; } return parsed; } catch { return wantsMessages ? { text: '', timestamp: '', messages: [] } : { text: '', timestamp: '' }; } }; ctx.lastResponseFor = lastResponseFor; app.get('/api/sessions/:id/last-response', async (req) => { const { id } = req.params as { id: string }; const session = findSessionOrFail(ctx, id, req); return lastResponseFor(session, (req.query as { context?: string }).context); }); function isCodexInjectedContext(text: string): boolean { return ( /^# AGENTS\.md instructions\b/i.test(text) || /^({ maxSize: 1024 }); async function resolveCodexThreadFromHistory( session: { id: string; lastSubmitAt?: number }, codexHome: string ): Promise { const submitAt = session.lastSubmitAt || 0; if (!submitAt) return null; const cached = codexHistoryPinCache.get(session.id); if (cached && cached.submitAt === submitAt) return cached.threadId; const histPath = join(codexHome, 'history.jsonl'); const st = await fs.stat(histPath).catch(() => null); if (!st || st.size === 0) return null; const tail = await readFileTail(histPath, Buffer.alloc(65536), st.size); if (!tail) return null; const WINDOW_MS = 15_000; const otherSubmits: number[] = []; for (const s of ctx.sessions.values()) { if (s.id !== session.id && getCli(s.mode)?.capabilities.transcript === 'codex-rollout' && s.lastSubmitAt) { otherSubmits.push(s.lastSubmitAt); } } let best: { threadId: string; dist: number } | undefined; for (const line of tail.split('\n')) { if (!line) continue; let e: { session_id?: string; ts?: number }; try { e = JSON.parse(line); } catch { continue; // first tail line may be cut mid-JSON } if (!e.session_id || typeof e.ts !== 'number') continue; const tsMs = e.ts * 1000; // history timestamps are unix seconds const dist = Math.abs(tsMs - submitAt); if (dist > WINDOW_MS) continue; if (otherSubmits.some((o) => Math.abs(tsMs - o) < dist)) continue; // another pane is closer if (!best || dist < best.dist) best = { threadId: e.session_id, dist }; } if (!best) return null; codexHistoryPinCache.set(session.id, { submitAt, threadId: best.threadId }); return best.threadId; } // Locate THIS pane's rollout, in order of confidence: // 0. history match — the thread the pane last submitted a message to // (see resolveCodexThreadFromHistory); tracks the pane through // /resume //new //fork typed inside the TUI. // 1. originator match — Codeman spawns codex panes with // CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codeman_, which codex // writes into session_meta.originator of every rollout it creates // (including new files after /new in the same pane; newest match wins). // 2. resume-id match — resumed rollouts keep their ORIGINAL session_meta // (codex appends without rewriting it), so originator matching can't // see them; but the rollout uuid is in the filename and we know the id. // 3. legacy cwd+mtime heuristic — panes started before this feature, or // TUI-resumed threads before their first tracked submit. Case-blind // cwd compare (codex records the launch-time case, /mnt paths vary) // and rollouts claimed by OTHER codeman panes are excluded. async function findActiveCodexFile(session: { id: string; workingDir: string; lastSubmitAt?: number; codexConfig?: { resumeSessionId?: string }; }): Promise { const codexHome = process.env.CODEX_HOME || join(process.env.HOME || '/tmp', '.codex'); const sessionsDir = join(codexHome, 'sessions'); const files: Array<{ path: string; mtimeMs: number }> = []; const walk = async (dir: string): Promise => { let entries: import('node:fs').Dirent[]; try { entries = await fs.readdir(dir, { withFileTypes: true }); } catch { return; } for (const entry of entries) { const fullPath = join(dir, entry.name); if (entry.isDirectory()) { await walk(fullPath); continue; } if (!entry.isFile() || !entry.name.endsWith('.jsonl')) continue; const st = await fs.stat(fullPath).catch(() => null); if (!st || st.size < 100) continue; files.push({ path: fullPath, mtimeMs: st.mtimeMs }); } }; await walk(sessionsDir); files.sort((a, b) => b.mtimeMs - a.mtimeMs); const historyThreadId = await resolveCodexThreadFromHistory(session, codexHome); if (historyThreadId) { const hit = files.find((f) => basename(f.path).endsWith(`-${historyThreadId}.jsonl`)); if (hit) return hit.path; } const rawResumeId = session.codexConfig?.resumeSessionId; const resumeId = rawResumeId && /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(rawResumeId) ? rawResumeId : undefined; const idMatch = resumeId ? files.find((f) => basename(f.path).endsWith(`-${resumeId}.jsonl`)) : undefined; // Scan newest-first for our originator; anything strictly older than the // id match can never beat it, so the head reads stop there (mtime ties are // still scanned — a /new rollout may land in the same clock tick). The // 128 KiB head budget covers the session_meta line, which embeds full // base_instructions (observed max ~22 KiB on codex 0.144). const originator = `codeman_${session.id}`; const wantCwd = session.workingDir.toLowerCase(); const headBuf = Buffer.alloc(131072); let cwdFallback: { path: string; mtimeMs: number } | undefined; for (const f of files) { if (idMatch && f.mtimeMs < idMatch.mtimeMs) break; const meta = await readCodexRolloutMetaCached(f.path, headBuf); if (!meta) continue; if (meta.originator === originator) return f.path; // newest-first → first hit wins if ( !cwdFallback && !idMatch && meta.cwd?.toLowerCase() === wantCwd && // A rollout stamped by another codeman pane belongs to that pane. !(meta.originator?.startsWith('codeman_') && meta.originator !== originator) ) { cwdFallback = f; } } return idMatch?.path ?? cwdFallback?.path ?? null; } // session_meta is written once when codex creates the rollout and never // rewritten (verified: resume appends without touching it), so the parsed // identity of a given path can be cached forever. This turns the per-request // scan into stat calls plus head reads for new files only. const codexRolloutMetaCache = new LRUMap({ maxSize: 4096 }); async function readCodexRolloutMetaCached( filePath: string, headBuf: Buffer ): Promise<{ cwd?: string; originator?: string } | null> { const cached = codexRolloutMetaCache.get(filePath); if (cached) return cached; const head = await readFileHead(filePath, headBuf); if (!head) return null; const meta = readCodexRolloutMeta(head); // Don't cache a still-incomplete head: a rollout being created may not // have flushed session_meta/turn_context yet. if (!meta.cwd && !meta.originator) return meta; codexRolloutMetaCache.set(filePath, meta); return meta; } function extractCodexBlockText(content: unknown, kinds: string[]): string { if (typeof content === 'string') return content; if (!Array.isArray(content)) return ''; return content .filter( (b): b is { type: string; text: string } => !!b && typeof b === 'object' && kinds.includes((b as { type?: string }).type || '') && typeof (b as { text?: string }).text === 'string' ) .map((b) => b.text) .join('\n\n'); } // Single pass over a Codex rollout: track the last assistant message (for the // default eye view) and, when `full`, the whole user/assistant thread. // // User turns come from event_msg/user_message when available: codex emits one // per REAL user input, and injected context (AGENTS.md, environment_context, // compaction summaries, …) never appears there — so no filtering heuristics. // response_item user rows duplicate those inputs mixed with the injections; // they are kept only as a fallback for old rollouts without event_msg rows. async function readCodexLastResponse( session: { id: string; workingDir: string; codexConfig?: { resumeSessionId?: string } }, full: boolean ): Promise<{ text: string; timestamp: string; messages?: Array<{ role: string; text: string; timestamp?: string }>; }> { const empty = full ? { text: '', timestamp: '', messages: [] } : { text: '', timestamp: '' }; const filePath = await findActiveCodexFile(session); if (!filePath) return empty; let content: string; try { content = await fs.readFile(filePath, 'utf8'); } catch { return empty; } let lastText = ''; let lastTimestamp = ''; const messages: Array<{ role: string; text: string; timestamp?: string; legacyUser?: boolean }> = []; // Multiset of event-sourced user texts: a real input appears BOTH as an // event_msg and as a response_item row, so each event text cancels exactly // one legacy twin. Legacy rows without an event twin (turns written by an // older codex appending to the same rollout) survive — a file-wide boolean // would wrongly drop them. const eventUserTexts = new Map(); for (const line of content.split('\n')) { if (!line) continue; let entry: { timestamp?: string; type?: string; payload?: { type?: string; role?: string; content?: unknown; message?: unknown; images?: unknown; local_images?: unknown; }; }; try { entry = JSON.parse(line); } catch { continue; } if (full && entry.type === 'event_msg' && entry.payload?.type === 'user_message') { let text = typeof entry.payload.message === 'string' ? entry.payload.message.trim() : ''; if (text && isCodexInjectedContext(text)) continue; if (text) eventUserTexts.set(text, (eventUserTexts.get(text) || 0) + 1); // Image-only (or image+text) inputs: the text field alone would make // the turn vanish, so surface a placeholder. const imageCount = (Array.isArray(entry.payload.images) ? entry.payload.images.length : 0) + (Array.isArray(entry.payload.local_images) ? entry.payload.local_images.length : 0); if (imageCount > 0) text = text ? `${text}\n\n*[image ×${imageCount}]*` : `*[image ×${imageCount}]*`; if (text) messages.push({ role: 'user', text, timestamp: entry.timestamp }); continue; } if (entry.type !== 'response_item' || entry.payload?.type !== 'message') continue; const role = entry.payload?.role; if (role === 'assistant') { const text = extractCodexBlockText(entry.payload?.content, ['output_text', 'text']); if (text) { lastText = text; lastTimestamp = entry.timestamp || ''; if (full) messages.push({ role: 'assistant', text, timestamp: entry.timestamp }); } } else if (role === 'user' && full) { const text = extractCodexBlockText(entry.payload?.content, ['input_text', 'text']).trim(); // Drop Codex's injected context turns (AGENTS.md, environment_context, …) // so the thread shows real user prompts only. if (text && !isCodexInjectedContext(text)) { messages.push({ role: 'user', text, timestamp: entry.timestamp, legacyUser: true }); } } } const thread = messages .filter((m) => { if (!m.legacyUser) return true; const n = eventUserTexts.get(m.text) || 0; if (n > 0) { eventUserTexts.set(m.text, n - 1); return false; // duplicate of an event_msg row already in the thread } return true; }) .map(({ role, text, timestamp }) => ({ role, text, timestamp })); return full ? { text: lastText, timestamp: lastTimestamp, messages: thread } : { text: lastText, timestamp: lastTimestamp }; } // ========== Get Terminal Buffer ========== // Query params: // tail= - 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 as { id: string }; const query = req.query as { tail?: string; full?: string; lines?: string; alt?: string }; const session = findSessionOrFail(ctx, id, req); // `full=1` is the EXPLICIT full-history signal (COD-47): capture the ENTIRE // tmux scrollback so history beyond the server byte buffer can be recovered. // 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; 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 // TUI modes (codex/opencode) that repaint only their latest frame: the // accumulated buffer alone replays as the idle banner. We clear the viewport // (`\x1b[H\x1b[2J`) between the history and the live pane so they don't // overlap. `captureActivePaneBuffer` is a no-op ('') under test mode and // returns null when unavailable, in which case we fall back to history. const muxName = session.muxName; const captureStartedAt = performance.now(); // The visible path used to pass no options at all. It passes one now for a // single reason: `capturedGeometry` comes BACK on it, and the response has // to tell the client what size the frame it is about to render was built // 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. let captureOpts: PaneCaptureOptions = isFullReload ? { fullHistory: true, historyLimitLines: captureHistoryLines(query.lines, tmuxHistoryLimit), maxCaptureBytes: terminalBufferMaxBytes, } : {}; // 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: PaneCaptureOptions): string | null => 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: 'history' | 'mux-visible' | 'mux-full-history' = hasLiveMuxBuffer ? isFullReload ? 'mux-full-history' : 'mux-visible' : 'history'; // What the three row-preserving skips below must key on. `isFullReload` is // only what the CLIENT ASKED FOR: when the capture comes back null — ENOBUFS, // a timeout, a vanished pane, or a session with no mux at all — rawBuffer // falls back to the byte history, which is a stream of successive frames with // no row alignment to protect and every reason to be stripped. const isFullCapture = isFullReload && hasLiveMuxBuffer; let rawBuffer: string; if (liveMuxBuffer !== null && liveMuxBuffer.length > 0) { // Full-history capture is the RENDERED form of everything already in the // byte buffer (up to tmux eviction) — return it alone. Prepending the byte // history would replay the whole conversation twice: `\x1b[2J` clears only // the viewport, not xterm scrollback. The history+clear+frame concat stays // for the visible-frame path, where the single pane frame lacks history. rawBuffer = isFullReload ? liveMuxBuffer : session.terminalBufferLength > 0 ? `${session.terminalBuffer}\x1b[H\x1b[2J${liveMuxBuffer}` : liveMuxBuffer; } else { rawBuffer = session.terminalBuffer; } const fullSize = rawBuffer.length; let truncated = false; // WHY the reason and not just the boolean (#258): `truncated` is set at two // sites that mean opposite things to a user. 'tail' is an intentional // partial replay and the rest is still retained, so a `full=1` pull recovers // it. 'capped' means we hit the byte ceiling — and on a full-history capture // that is already everything tmux holds, so the oldest output is genuinely // out of reach rather than one click away. Collapsing both into one flag is // why the UI could only ever say "truncated for performance". let truncationReason: 'capped' | 'tail' | null = null; let cleanBuffer: string; // 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 // bytes anyway. Keep the most RECENT bytes (slice from the end) and align // to a line boundary so we never start mid-ANSI-escape. if (terminalBufferMaxBytes > 0 && rawBuffer.length > terminalBufferMaxBytes) { rawBuffer = rawBuffer.slice(-terminalBufferMaxBytes); truncated = true; truncationReason = 'capped'; const capNewline = rawBuffer.indexOf('\n'); if (capNewline > 0 && capNewline < 4096) { rawBuffer = rawBuffer.slice(capNewline + 1); } } // Strip redundant Ink spinner/status redraws BEFORE tailing. // During long thinking phases, Ink rewrites the same rows thousands of times // (500KB+). Without stripping, tail mode returns only spinner frames and // the terminal appears empty when switching tabs. // A full reload's buffer IS the rendered pane, one line per screen row, and // it ends with an absolute cursor move back to the pane's own position. // Every transform below that can DELETE A LINE would shift the rows out from // under that position, leaving the caret a row off — on the composer's // border rather than its input line. Redraw-bloat stripping exists for a // byte stream of successive frames; a capture holds no successive frames. let strippedBuffer = isFullCapture || getCli(session.mode)?.capabilities.stripInkBloat === false ? rawBuffer : stripInkRedrawBloat(rawBuffer); // Same strip as the live stream (session.ts), so a buffer recorded before the // live-side strip existed cannot re-park xterm on replay. See stripReplayBuffer. strippedBuffer = stripReplayBuffer(strippedBuffer, session.mode, session.usesMux); if (tailBytes > 0 && strippedBuffer.length > tailBytes) { // Fast path: tail from the end, skip expensive banner search on full 2MB buffer. // Banner is near the top and gets discarded by tail anyway. cleanBuffer = strippedBuffer.slice(-tailBytes); truncated = true; // 'capped' already means the oldest bytes are gone for good; a tail cut on // top of it does not soften that, so the stronger reason wins. truncationReason ??= 'tail'; // Avoid starting mid-ANSI-escape: find first newline within the first 4KB // and start from there. This prevents xterm.js from parsing a partial escape // sequence which corrupts cursor position for all subsequent Ink redraws. const firstNewline = cleanBuffer.indexOf('\n'); if (firstNewline > 0 && firstNewline < 4096) { cleanBuffer = cleanBuffer.slice(firstNewline + 1); } } else { // Full buffer: clean junk before actual Claude content cleanBuffer = strippedBuffer; // Find where Claude banner starts (has color codes before "Claude") // Skipped for a full reload: the banner sits at whatever row the pane has // it, and cutting to it would drop the blank rows above and move every // row up by that many. const claudeMatch = isFullCapture ? null : cleanBuffer.match(CLAUDE_BANNER_PATTERN); if (claudeMatch && claudeMatch.index !== undefined && claudeMatch.index > 0) { let lineStart = claudeMatch.index; while (lineStart > 0 && cleanBuffer[lineStart - 1] !== '\n') { lineStart--; } cleanBuffer = cleanBuffer.slice(lineStart); } } // Remove Ctrl+L and leading whitespace (cheap on tailed subset) // Leading whitespace goes too, except on a full reload where a leading // blank line is the pane's own first row and dropping it shifts every row // up by one. cleanBuffer = cleanBuffer.replace(CTRL_L_PATTERN, ''); if (!isFullCapture) cleanBuffer = cleanBuffer.replace(LEADING_WHITESPACE_PATTERN, ''); const finishedAt = performance.now(); reply.header( 'Server-Timing', `capture;dur=${(captureFinishedAt - captureStartedAt).toFixed(1)}, ` + `prepare;dur=${(finishedAt - captureFinishedAt).toFixed(1)}, ` + `total;dur=${(finishedAt - routeStartedAt).toFixed(1)}` ); return { terminalBuffer: cleanBuffer, status: session.status, 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, source, // The pane geometry this frame was drawn for. A visible-frame capture // positions every row absolutely, so a client whose terminal has fewer // rows than this overwrites its last line with the overflow and loses // the rows underneath. The client compares these against its own size. // // BOTH FIELDS ARE ABSENT unless this response really carries a capture, // and that is the honest answer rather than a gap to paper over. Two // separate things can leave a frame unpositioned. The cursor query is // what produces the absolute addressing in the first place, so a capture // that lost it returned a raw frame with no row positioning in it. And a // capture can report geometry and STILL hand back nothing: the // full-history path returns '' for a pane holding nothing visible, which // drops `source` to `history` while `capturedGeometry` is already // written, so the geometry has to be suppressed HERE rather than trusted // to be missing. Naming a size for a body that is the byte stream would // describe a frame that was never drawn and invite the client to repair // 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, }; }); // ═══════════════════════════════════════════════════════════════ // Session Settings (auto-clear, auto-compact, image watcher, flicker filter) // ═══════════════════════════════════════════════════════════════ // ========== Auto-Clear ========== app.post('/api/sessions/:id/auto-clear', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(AutoClearSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); session.setAutoClear(body.enabled, body.threshold); persistAndBroadcastSession(ctx, session); return { success: true, data: { autoClear: { enabled: session.autoClearEnabled, threshold: session.autoClearThreshold, }, }, }; }); // ========== Auto-Compact ========== app.post('/api/sessions/:id/auto-compact', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(AutoCompactSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); session.setAutoCompact(body.enabled, body.threshold, body.prompt); persistAndBroadcastSession(ctx, session); return { success: true, data: { autoCompact: { enabled: session.autoCompactEnabled, threshold: session.autoCompactThreshold, prompt: session.autoCompactPrompt, }, }, }; }); // ========== 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 as { id: string }; 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, }, }, }; }); // ========== Git fetch on an interval ========== // Per-session override for the fetch interval (src/git-fetch-scheduler.ts), which is what the Session // Options rows say it is: two sessions on one folder can hold different choices, and that folder is // fetched when the first of them is due. `null` on either field clears this session's choice so the // app-wide setting applies again, and a field left out of the body leaves the other half as it was: the // Session Options rows save on their own. Refused for a remote or Docker session, exactly as the Git // panel excludes them: a container can write to the repository it mounts, so git there would run that // repository's own configuration on the host. app.post('/api/sessions/:id/git-fetch-settings', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(GitFetchSettingsSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); if (session.remote || session.docker) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Git fetch does not run for remote or Docker sessions'); } const enabled = 'enabled' in body ? (body.enabled ?? undefined) : session.gitFetchEnabled; const intervalSeconds = 'intervalSeconds' in body ? (body.intervalSeconds ?? undefined) : session.gitFetchIntervalSeconds; session.setGitFetchSettings(enabled, intervalSeconds); persistAndBroadcastSession(ctx, session); return { success: true, data: { gitFetchSettings: { enabled: session.gitFetchEnabled ?? null, intervalSeconds: session.gitFetchIntervalSeconds ?? null, }, }, }; }); // ========== Auto-Resume (usage-limit pause) ========== app.post('/api/sessions/:id/auto-resume', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(AutoResumeSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); session.setAutoResume(body.enabled); persistAndBroadcastSession(ctx, session); return { success: true, data: { autoResume: { enabled: session.autoResumeEnabled, resumeAt: session.autoResumeAt ?? undefined, }, }, }; }); // ========== Pin (float to top of the session manager list, COD-139) ========== app.post('/api/sessions/:id/pin', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(PinSessionSchema, req.body, 'Invalid request body'); const session = ctx.sessions.get(id); if (session) { if (!canAccessOwned(getAuthUser(req), session.owner)) { return createErrorResponse(ApiErrorCode.NOT_FOUND, `Session ${id} not found`); } session.setPinned(body.pinned); // Persist + broadcast session:updated (keeps tabs/state consistent), then a // dedicated session:pinned event so the session manager list re-sorts live. persistAndBroadcastSession(ctx, session); ctx.broadcast(SseEvent.SessionPinned, { id, pinned: session.pinned, pinnedAt: session.pinnedAt ?? undefined, }); return { success: true, data: { pinned: session.pinned, pinnedAt: session.pinnedAt ?? undefined, }, }; } // COD-142 keeps a pinned session's record after kill (demoteOrRemoveSession), // so pin toggles must also work WITHOUT a live Session — otherwise a // pinned-then-killed record could never be unpinned (cleanup skips pinned // records, and the record has no live session to route through). const persisted = ctx.store.getSession(id); if (!persisted || !canAccessOwned(getAuthUser(req), persisted.owner)) { return createErrorResponse(ApiErrorCode.NOT_FOUND, `Session ${id} not found`); } const pinnedAt = body.pinned ? Date.now() : undefined; ctx.store.setSession(id, { ...persisted, pinned: body.pinned || undefined, pinnedAt }); ctx.broadcast(SseEvent.SessionPinned, { id, pinned: body.pinned, pinnedAt }); return { success: true, data: { pinned: body.pinned, pinnedAt } }; }); // ========== Image Watcher ========== app.post('/api/sessions/:id/image-watcher', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(ImageWatcherSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); // A remote session's workingDir is a path on the remote host; the watcher would watch it on the // LOCAL disk (a missing folder, or a same-named local one whose images are not the session's). if (body.enabled && session.remote) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Image watching does not run for remote sessions'); } if (body.enabled) { imageWatcher.watchSession(session.id, session.workingDir); } else { imageWatcher.unwatchSession(session.id); } // Store state on session for persistence session.imageWatcherEnabled = body.enabled; ctx.persistSessionState(session); return { success: true, data: { imageWatcherEnabled: body.enabled, }, }; }); // ========== Flicker Filter ========== app.post('/api/sessions/:id/flicker-filter', async (req) => { const { id } = req.params as { id: string }; const body = parseBody(FlickerFilterSchema, req.body, 'Invalid request body'); const session = findSessionOrFail(ctx, id, req); session.flickerFilterEnabled = body.enabled; persistAndBroadcastSession(ctx, session); return { success: true, data: { flickerFilterEnabled: body.enabled, }, }; }); // ═══════════════════════════════════════════════════════════════ // Quick Actions (quick-run, quick-start) // ═══════════════════════════════════════════════════════════════ // ========== Quick Run ========== app.post('/api/run', async (req) => { const runOwner = ownerFor(req); const capMsg = sessionCapacityMessage(ctx.sessions, runOwner); if (capMsg) return createErrorResponse(ApiErrorCode.SESSION_BUSY, capMsg); const { prompt, workingDir, envOverrides: runEnvOverrides, } = parseBody(QuickRunSchema, req.body, 'Invalid request body'); if (!prompt.trim()) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'prompt is required'); } const dir = workingDir || process.cwd(); // Multi-user: confine a non-admin's one-shot working dir to their space. if (!isWorkingDirAllowed(getAuthUser(req), dir)) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'workingDir is outside your workspace'); } // Validate workingDir exists and is a directory if (workingDir) { try { const stat = statSync(dir); if (!stat.isDirectory()) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory'); } } catch { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist'); } } // Section 6.3: the one-shot spawn path (runPrompt/buildPromptArgs) respects the // session's claudeMode, so resolve it for the owner (bypass -> auto for non-granted). const runClaudeModeConfig = await ctx.getClaudeModeConfig(); const runClaudeMode = await resolveClaudeModeForUsername(runClaudeModeConfig.claudeMode, runOwner); const session = new Session({ workingDir: dir, envOverrides: runEnvOverrides, claudeMode: runClaudeMode, allowedTools: runClaudeModeConfig.allowedTools, owner: runOwner, }); await ctx.addSession(session); ctx.store.incrementSessionsCreated(); ctx.persistSessionState(session); await ctx.setupSessionListeners(session); getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name, reason: 'run_prompt', }); ctx.broadcast(SseEvent.SessionCreated, ctx.getSessionStateWithRespawn(session)); try { const result = await session.runPrompt(prompt); // Clean up session after completion to prevent memory leak await ctx.cleanupSession(session.id, true, 'run_prompt_complete'); return { sessionId: session.id, ...result }; } catch (err) { // Clean up session on error too. The session is destroyed here, so its id // is only useful for log correlation — carry it in the error message. await ctx.cleanupSession(session.id, true, 'run_prompt_error'); return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${getErrorMessage(err)} (session ${session.id})`); } }); // ========== Quick Start ========== app.post('/api/quick-start', async (req) => { const owner = ownerFor(req); 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, 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); // Multi-user: shell mode is arbitrary host-account execution, gated by the grant. // Resolve the owner's grant from the store so a GRANTED regular user is not wrongly denied. if (getCli(mode)?.capabilities.privilegedCommandGate && !(await canUsernameRunPrivilegedCommands(owner))) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'Shell sessions require the can-bypass-permissions grant'); } // Resolve the remote case FIRST — the CLI executes on the REMOTE host over ssh, // so the LOCAL availability gates below (isCodexAvailable() etc.) don't apply and // would wrongly reject a machine that hasn't got the CLI installed locally. let remote = undefined; let docker = undefined; let dockerResumeId: string | undefined; let casePath: string | null = null; // Security: fold ownership INTO the match (don't early-return) so a NON-OWNED // same-named remote/docker case is skipped and control falls through to the caller's // own LOCAL case — remote/docker names are globally unique but local names are // per-user, so a name collision must not shadow the caller's own case. canAccessOwned // is allow-all for admins/single-user, so flag-OFF stays byte-identical. const remoteCases = await readRemoteCases(CODEMAN_CONFIG_DIR); const remoteCase = remoteCases.find( (item) => item.name === caseName && canAccessOwned(getAuthUser(req), item.owner) ); 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) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Remote host not found'); // Per-session config that is applied to the LOCAL tmux/CLI wrapper (env vars via // tmux setenv, effort/model CLI args, codex/gemini/antigravity/opencode config) does NOT // cross ssh, so it would silently no-op. Reject rather than pretend it worked — // remote command/env customization goes through the per-host command override. if ( (envOverrides && Object.keys(envOverrides).length > 0) || effort || advisorModel || modelOverride !== undefined || codexConfig || geminiConfig || antigravityConfig || piConfig || grokConfig || copilotConfig || deepSeekConfig || ompConfig || openCodeConfig || customModel ) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'envOverrides, effort, advisorModel, modelOverride, per-CLI config, and custom model endpoints are not supported for remote cases (they do not cross ssh). Configure the remote command via the host command override instead.' ); } // The user pressing "Run" on a case whose host is asleep IS an explicit wake // request (docs/remote-sessions.md §Wake-on-LAN), and the tmux probe below would // otherwise fail with "could not verify tmux on remote host …" — an ssh failure // that blames tmux for a machine that is merely suspended. Wired HERE, in the HTTP // route, and deliberately NOT in the shared session service: `cron-service.ts` // builds sessions through the service, and a wake down there would re-wake the // host on every schedule (the failure invariant #1 exists to prevent). const hostWake = await remoteWake.ensureHostAwake(wakeableHost(host), { timeoutMs: REMOTE_WAKE_REQUEST_READY_TIMEOUT_MS, // No session yet, so the wake events name their requester (multi-user routing). requestedBy: ownerFor(req), }); if (hostWake === 'failed') { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, `${host.label} did not come back after a wake-on-LAN request — the session was not started` ); } // tmux is a hard prerequisite on the remote host (the agent runs inside a remote // tmux server so it survives ssh drops). Probe before spawning so a missing tmux // surfaces a clear, structured error instead of a dead "tmux: command not found" pane. const tmuxCheck = await checkRemoteTmuxAvailable(host); if (!tmuxCheck.ok) { // An unreachable host and a host without tmux fail the same way over ssh, so the // probe's own message would send the user hunting for a tmux install. Ask the // registry (which just probed, when it woke the host) which of the two it is. // `=== false` on purpose: a proxied host answers `null` (the probe cannot reach // it), and an unknown verdict must not replace the real ssh error with // "not reachable" over a host that is fine. if ((await remoteWake.checkHostReachable(wakeableHost(host))) === false) { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, hostWake === 'no-target' ? `${host.label} (${host.host}) is not reachable, and this host has no wake-on-LAN target — configure a MAC address or a wake command first` : `${host.label} (${host.host}) is not reachable` ); } return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'remote host is missing tmux'); } casePath = remoteCase.remotePath; remote = toSessionRemote(host, remoteCase); } else if (dockerCase) { // Docker case: the CLI executes INSIDE a container via local tmux + `docker // exec`, so the LOCAL availability gates below don't apply. Mirror the remote // branch's rejection of per-session config that would not cross into the // container (it would silently no-op). (Ownership is enforced in the .find above.) const host = (await readDockerHosts(CODEMAN_CONFIG_DIR)).find((item) => item.id === dockerCase.hostId); if (!host) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Docker host not found'); if ( (envOverrides && Object.keys(envOverrides).length > 0) || effort || advisorModel || codexConfig || geminiConfig || antigravityConfig || piConfig || grokConfig || copilotConfig || deepSeekConfig || ompConfig || openCodeConfig || customModel ) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, 'envOverrides, effort, advisorModel, per-CLI config, and custom model endpoints are not supported for docker cases (they do not cross into the container). Configure the container via the docker host command override instead.' ); } const availability = await checkDockerAvailable(host.engine); if (!availability.ok) { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, availability.error || 'docker daemon is not available' ); } const sessionDocker = toSessionDocker(host, dockerCase); // An ADOPTED container skips every image-side gate: we never run `docker // create`, so the image is the user's business, and `ensureAgentBaseImage` // would build/require an image that has nothing to do with their container. // The prerequisite that DOES still hold is tmux inside it, so probe the live // container (not the image) and refuse before launch rather than dead-paning. if (sessionDocker.owned === false) { const probe = await probeAdoptableContainer(sessionDocker, [mode]); if (!probe.ok) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, probe.error || 'container is not usable'); } // The probe already exec'd into the container; carry its facts onto the // live session so the launch chain does not have to re-ask. sessionDocker.runsAsRoot = probe.runsAsRoot; // No `mode !== 'shell'` arm: a mode with no binary of its own is reported // available by the probe unconditionally, so this reads the same answer for it. if (!probe.availableModes?.includes(mode)) { return createErrorResponse( ApiErrorCode.OPERATION_FAILED, `"${mode}" is not installed in container "${sessionDocker.containerName}". Adoption never modifies the container — install it inside, or pick another mode.` ); } } else { // Ensure the base image exists, auto-building the default image on first use so // it is never a blocker. Dedup'd with any build kicked off at case-create, so // this awaits the SAME in-flight build rather than starting a second one. const ensured = await ensureAgentBaseImage(sessionDocker, sessionDocker.image, { onProgress: (line) => ctx.broadcast(SseEvent.DockerImageBuildProgress, { name: dockerCase.name, line }), }); if (!ensured.ok) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, ensured.error || 'base image not available'); } if (ensured.built) { ctx.broadcast(SseEvent.DockerImageBuildComplete, { name: dockerCase.name, image: sessionDocker.image }); } // tmux is a hard prerequisite (the in-container tmux makes reconnect durable). // Skip the extra container-run probe for our OWN default image (the baked // Dockerfile always contains tmux); still verify a custom image. if (sessionDocker.image !== DEFAULT_AGENT_IMAGE) { const tmuxCheck = await checkDockerTmuxAvailable(sessionDocker); if (!tmuxCheck.ok) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'base image is missing tmux'); } } } // Config drift (docs/docker-cases-plan.md §4): the desired create-config no // longer matches the existing container's codeman.confighash label. Refuse to // silently launch into the stale container — the frontend confirms a recreate // (POST /api/docker-cases/:name/recreate; workspace + transcripts ride bind // mounts and the conversation resumes), or the user reverts the host edit. const drift = await checkDockerConfigDrift(sessionDocker); if (drift.exists && drift.drifted) { return createErrorResponse( ApiErrorCode.CONFLICT, `Container config for case "${dockerCase.name}" changed since the container was created. Recreate the container to apply it (workspace and conversation survive), or revert the docker host edit.` ); } casePath = dockerCase.hostWorkspacePath; // a REAL host dir (bind-mounted into the container) docker = sessionDocker; // Seed only Claude's resume id. Codex, Gemini, and the other CLIs have // separate conversation stores and must never receive a Claude UUID. if (mode === 'claude' && sessionDocker.resumeOnStart && dockerCase.lastClaudeSessionId) { dockerResumeId = dockerCase.lastClaudeSessionId; } } else { // Same pre-flight as POST /api/sessions: refuse before spawning a pane that would die // on `command not found`, with the resolver's own diagnostics, and a launcher CLI's // more specific reason (dsh: binary vs no pane-capable profile vs the profile the // caller named). External CLIs only — claude and shell fall through to tmux-manager's // own not-found throw, exactly as before. if (getCli(mode)?.capabilities.external) { const qsLaunchError = await resolveCliLaunchError( mode, legacyConfigForMode(mode, { openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, } as unknown as Record) ); if (qsLaunchError) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, qsLaunchError); } } // Resolve case path: check linked-cases registry first, then fall back to CASES_DIR. // This mirrors the behaviour of resolveCasePath() in case-routes so that linked // external project directories are honoured by quick-start just like regular case routes. let linkedCases: Record = {}; try { const raw = await fs.readFile(LINKED_CASES_FILE, 'utf-8'); linkedCases = JSON.parse(raw); } catch { // File missing or unparseable — treat as empty registry } // Multi-user: the linked-cases registry is ownerless/global, so only admins may // resolve a name to an arbitrary linked path. A non-admin resolves inside their // OWN case space only (single-user: isAdmin true, so linked cases still honoured). const linked = isAdmin(req) ? linkedCases[caseName] : undefined; casePath = linked || validatePathWithinBase(caseName, resolveCasesDir(getAuthUser(req))); if (!casePath) { return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Invalid case path'); } } // By this point casePath is guaranteed non-null: for remote cases it was set from remoteCase.remotePath, // for local cases the !casePath guard above returned early. TypeScript can't narrow across the if/else. const resolvedCasePath = casePath as string; // Multi-user linchpin (section 6.2): confine the resolved workingDir to the caller's // own case space BEFORE any mkdir/scaffold below creates or mutates it. Applies to // LOCAL and DOCKER cases (docker.hostWorkspacePath is a real host dir the file routes // trust); skipped for REMOTE, whose path is an ssh path that would spuriously fail // realpath confinement. No-op for admins / single-user mode. if (!remote && !isWorkingDirAllowed(getAuthUser(req), resolvedCasePath)) { return createErrorResponse(ApiErrorCode.FORBIDDEN, 'case path is outside your workspace'); } // Bounded probe of a local case folder: a linked case can sit on a network mount // that stopped answering, and a synchronous check there froze the whole server. // Only a DEFINITE absence may scaffold a new case; "did not answer" must not // create one over the top of where the real case is mounted. const localCaseState = remote || docker ? undefined : await probePathKind(resolvedCasePath, { pastCap: true }); 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') { try { mkdirSync(resolvedCasePath, { recursive: true }); mkdirSync(join(resolvedCasePath, 'src'), { recursive: true }); // Read settings to get custom template path const templatePath = await ctx.getDefaultClaudeMdPath(); const claudeMd = generateClaudeMd(caseName, '', templatePath); writeFileSync(join(resolvedCasePath, 'CLAUDE.md'), claudeMd); // Write .claude/settings.local.json with hooks for desktop notifications // (Claude-specific — OpenCode, Codex, Gemini, Antigravity, Pi, Grok, DeepSeek and OMP use their own systems) if ( mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini' && mode !== 'antigravity' && mode !== 'pi' && mode !== 'grok' && mode !== 'omp' ) { await writeHooksConfig(resolvedCasePath); } // Label a directory an AGENT asked us to create, so the scratch workspaces a // long orchestration leaves behind can be told apart from the user's real // projects later (see agent-case-marker.ts). This is the only branch that may // write it: it is the only one that creates the directory, and a pre-existing // case must never be labelled. Best-effort — a failed marker must not fail the // spawn it decorates. const qsAgentOrigin = resolveAgentCaseOrigin(req, agentOrigin, qsParentSessionId); if (qsAgentOrigin) { await writeAgentCaseMarker( resolvedCasePath, buildAgentCaseMarker({ createdBy: qsAgentOrigin, parentSessionId: qsParentSessionId, parentSessionName: qsParentSessionId ? ctx.sessions.get(qsParentSessionId)?.name : undefined, mode, owner, }) ); } ctx.broadcast(SseEvent.CaseCreated, { name: caseName, path: resolvedCasePath }); } catch (err) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`); } } else if (!remote && !docker && mode !== 'opencode') { // EXISTING case directory (a linked case, a cloned repo, anything Codeman did // not scaffold): install-or-refresh per the setting (see applyWorkspaceHooks). // Other modes keep the narrower COD-91 self-heal unconditionally: only claude // reads `.claude` hooks, so a shell/codex quick-start should not author a block // 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(workspacePath, await ctx.getWorkspaceHooksEnabled()); } else { await refreshStaleCodemanHooks(workspacePath).catch(() => {}); } } // Agent skill injection (docs/agent-control-plan.md §2): ADD-ONLY on create, // 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 // hook-idle detection fire (decision: wire hooks now). Never clobbers an existing // configured project. Claude mode ONLY — only claude reads `.claude` hooks, so a // shell or external-CLI quick-start must not author a block of its own (the same // rule the existing-case branch above states; this branch used to exclude just // the five external CLIs and let `shell` through). if (docker && docker.hooksEnabled && getCli(mode)?.capabilities.hooks === 'always') { try { if (!existsSync(join(resolvedCasePath, 'CLAUDE.md'))) { const templatePath = await ctx.getDefaultClaudeMdPath(); writeFileSync(join(resolvedCasePath, 'CLAUDE.md'), generateClaudeMd(caseName, '', templatePath)); } if (!existsSync(join(resolvedCasePath, '.claude', 'settings.local.json'))) { await writeHooksConfig(resolvedCasePath); } else { // A settings file with no hooks in it is the same dead-surface case as a // linked case. This branch is already gated on `docker.hooksEnabled`, and // applyWorkspaceHooks adds the user-level gate on top. await applyWorkspaceHooks(resolvedCasePath, await ctx.getWorkspaceHooksEnabled()); } } catch { /* non-fatal — the session still runs, hooks may be degraded */ } } // Model override → /.claude/settings.local.json (claude-mode; local AND // 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(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(workspacePath, Object.keys(envOverrides)); } // Create a new session with the case as working directory // Apply global Nice priority config and model config from settings const niceConfig = await ctx.getGlobalNiceConfig(); const qsModelConfig = await ctx.getModelConfig(); // Synced App Settings launch defaults, as on the create path: local launches only, so // never a remote or Docker case, and never a custom model endpoint launch. const qsRequestConfigs = { openCodeConfig, codexConfig, geminiConfig, antigravityConfig, piConfig, grokConfig, copilotConfig, deepSeekConfig, ompConfig, }; const qsLaunchConfigs = remote || docker ? qsRequestConfigs : await applyLaunchDefaults(mode, qsRequestConfigs, !!customModel); // ⚠️ The model is read from a bag WITHOUT ompConfig, as it always was here: quick-start // has never taken omp's session model from ompConfig (the create path does). Kept as // found rather than changed in passing. const { ompConfig: qsLaunchOmpConfig, ...qsModelConfigs } = qsLaunchConfigs; // See the create path for why this is a capability rather than a mode ladder. const qsModelSource = getCli(mode)?.capabilities.model; const qsModel = qsModelSource?.source === 'flag' ? (legacyConfigForMode(mode, qsModelConfigs as unknown as Record)?.[ qsModelSource.param ?? 'model' ] as string | undefined) : qsModelSource?.source === 'claude-settings-file' ? qsModelConfig?.defaultModel || undefined : undefined; 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, 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); // 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 // injection before the process exists and launching directly on it avoids the visible // native-boot-then-restart the restart-after-launch design otherwise shows on every // custom-model run — most jarring on a CLI like Codex whose TUI fully reinitializes. // Mirrors the dedicated route's own checks (llama-swap conflict, unsupported CLI, // unknown endpoint, a model id the CLI's argv pattern can't carry) rather than trusting // a lighter version of them, since this is the same server-side authority reached a // different way, not a separate, less-checked path. let qsCustomModelEnvOverrides = qsGatedEnvOverrides; // Only the INJECTED keys (never the caller's envOverrides merged in) — this is what // setCustomModel() bookkeeping must be given below. The Session constructor already // applies qsCustomModelEnvOverrides (the full merged set) directly; re-merging that // full set into setCustomModel() would put CLAUDE_CODE_EFFORT_LEVEL back after the // constructor stripped it (see setCustomModel()'s own doc comment in session.ts). let qsCustomModelAppliedEnvOverrides: Record | undefined; let qsCustomModelLaunchModel: string | undefined; let qsCustomModelSessionId: string | undefined; let qsCustomModelSwapInProgress = false; let qsCustomModelBookkeeping: | { endpointId: string; modelId: string; label?: string; envKeys: string[]; configDir?: string; launchModel?: string; } | undefined; if (customModel) { const cmEntry = getCli(mode); if (!cmEntry) return createErrorResponse(ApiErrorCode.INVALID_INPUT, `No CLI registry entry for mode ${mode}`); if (cmEntry.capabilities.customModelInjection.kind === 'unsupported') { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${mode} has no known custom-model mechanism`); } const cmHosts = await readCustomModelHosts(CODEMAN_CONFIG_DIR); const cmEndpoint = cmHosts.find((h) => h.id === customModel.endpointId); if (!cmEndpoint) return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Model endpoint not found'); // Per-model discovery figure first, user-set endpoint default second, nothing third // (see the dedicated route's own comment above). const cmContextLength = resolveCustomModelContextLength(cmEndpoint, customModel.modelId); const cmSlotCount = cmEndpoint.modelSlotCounts?.[customModel.modelId]; // See the dedicated route: refused on the pure build, before either confirmation, so // nobody agrees to evict a model for an id that could never launch, and before anything // is written. const cmModelSpec = cmEntry.launch.params.model; const cmInjection = buildCustomModelInjection(cmEntry, cmEndpoint, customModel.modelId, cmContextLength); const cmForcedLaunchModel = cmInjection.kind === 'unsupported' ? undefined : cmInjection.launchModel; if ( cmForcedLaunchModel !== undefined && cmModelSpec?.type === 'token' && !matchesPattern(cmModelSpec.pattern, cmForcedLaunchModel) ) { return createErrorResponse( ApiErrorCode.INVALID_INPUT, `Model id ${JSON.stringify(customModel.modelId)} cannot be passed to ${mode} on its command line` ); } // 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 // fail immediately. // See the dedicated route above for why this reads `confirmedContext` and never // `confirmedSwap`. if ( !(customModel.confirmed || customModel.confirmedContext) && 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 // model at a time, llama-swap swaps on demand, and switching away from what another // live session is actively using deserves a warning, not a silent switch. There is no // "self" to exclude from the affected-sessions scan here — this session doesn't exist // yet. const cmSwapStatus = await getLlamaSwapStatus(cmEndpoint); const cmCurrentlyLoaded = cmSwapStatus.running.find((r) => r.state === 'ready')?.model ?? cmSwapStatus.running[0]?.model; const cmSwapNeeded = cmSwapStatus.isLlamaSwap && !!cmCurrentlyLoaded && cmCurrentlyLoaded !== customModel.modelId; // Broader than cmSwapNeeded (which only gates the confirmation ask above): true // whenever the TARGET model isn't already loaded and ready, including when nothing // is loaded at all yet. Drives the actual load trigger below. const cmTargetReady = cmSwapStatus.running.some((r) => r.model === customModel.modelId && r.state === 'ready'); qsCustomModelSwapInProgress = cmSwapStatus.isLlamaSwap && !cmTargetReady; if (cmSwapNeeded && !(customModel.confirmed || customModel.confirmedSwap)) { const cmConflicting = [...ctx.sessions.values()].filter( (s) => s.customModel?.endpointId === cmEndpoint.id && s.customModel?.modelId === cmCurrentlyLoaded ); if (cmConflicting.length > 0) { // Same reasoning as the dedicated /custom-model route above: the swap is // still blocked pending confirmation regardless of ownership, but a // non-admin caller only learns the names of sessions they can access. const cmRequestUser = getAuthUser(req); const cmAffectedSessions = cmConflicting .filter((s) => canAccessOwned(cmRequestUser, s.owner)) .map((s) => ({ id: s.id, name: s.name })); return { requiresConfirmation: true, currentlyLoadedModel: cmCurrentlyLoaded, affectedSessions: cmAffectedSessions, }; } } // Minted ourselves (rather than left to Session's own default) so the injection // below — and any configDir it writes — can target the REAL id the session launches // 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, workspacePath, await guardSessionConfigDirHome(cmEntry, (envVar) => qsGatedEnvOverrides?.[envVar]) ); if (!cmApplied) { return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `${mode} has no known custom-model mechanism`); } qsCustomModelEnvOverrides = { ...qsGatedEnvOverrides, ...cmApplied.envOverrides }; qsCustomModelAppliedEnvOverrides = cmApplied.envOverrides; qsCustomModelLaunchModel = cmApplied.launchModel; qsCustomModelBookkeeping = { endpointId: cmEndpoint.id, modelId: customModel.modelId, label: cmEndpoint.label, envKeys: cmApplied.envKeys, configDir: cmApplied.configDir, launchModel: cmApplied.launchModel, }; // Actually kick off llama-swap's load now — see the dedicated apply route's own // comment on triggerLlamaSwapLoad for why this can't just wait on the launched CLI's // first prompt. Fired here, before the session is even created, so the load starts // concurrently with Claude/Codex/etc. booting rather than after. if (qsCustomModelSwapInProgress) { triggerLlamaSwapLoad(cmEndpoint, customModel.modelId); } } const qsSessionOptions: ConstructorParameters[0] = { id: qsCustomModelSessionId, workingDir: workspacePath, name: sessionName ? sessionName.slice(0, MAX_SESSION_NAME_LENGTH) : '', mux: ctx.mux, useMux: true, mode: mode, niceConfig: niceConfig, model: qsModel, claudeMode: qsEffectiveClaudeMode, allowedTools: qsClaudeModeConfig.allowedTools, owner, openCodeConfig: mode === 'opencode' ? qsLaunchConfigs.openCodeConfig : undefined, codexConfig: mode === 'codex' ? qsGatedCodexConfig : undefined, geminiConfig: mode === 'gemini' ? qsGatedGeminiConfig : undefined, 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, effort, advisorModel, remote, docker, resumeSessionId: dockerResumeId, tmuxHistoryLimit: qsTerminalHistoryConfig.tmuxHistoryLimit, parentSessionId: qsParentSessionId, }; // Force the custom-model selection's launchModel (pi/omp `custom/`, grok's // `[model.]` block name) onto whichever config field the registry says the // CLI's `model` launch param lives in — mirrors Session._withCustomModelLaunchModel, // which the restart-in-place path already uses, rather than a hardcoded per-CLI // branch here that a CLI landing its injection recipe later would silently miss. if (qsCustomModelLaunchModel !== undefined) { const qsCustomModelField = getCli(mode)?.launch.legacyConfigField; if (qsCustomModelField) { const qsSessionOptionsBag = qsSessionOptions as unknown as Record; qsSessionOptionsBag[qsCustomModelField] = { ...((qsSessionOptionsBag[qsCustomModelField] as Record) ?? {}), model: qsCustomModelLaunchModel, }; } else { qsSessionOptions.model = qsCustomModelLaunchModel; } } const session = new Session(qsSessionOptions); // Records the selection for session.customModel/getCustomModelForPersist() and future // clear/switch calls — the actual env vars and launch-model config are already part of // the launch above (constructor envOverrides, piConfig/grokConfig/ompConfig.model), so // this is bookkeeping only, never a restart: setCustomModel() is synchronous state, no // tmux IO of its own (see its own doc comment in session.ts). if (qsCustomModelBookkeeping) { session.setCustomModel(qsCustomModelBookkeeping, qsCustomModelAppliedEnvOverrides); } // 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, workspacePath, ctx); if (!session.ralphTracker.enabled) { session.ralphTracker.enable(); session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart } } const tabLayout = await ctx.addSession(session, { caseName, ...(tabGroupId ? { tabGroupId } : {}) }); 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 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: unknown) => console.warn(`[agent-skill] preamble seed failed for ${session.id}: ${getErrorMessage(err)}`) ); } getLifecycleLog().log({ event: 'created', sessionId: session.id, name: session.name, reason: 'quick_start', }); ctx.broadcast(SseEvent.SessionCreated, ctx.getSessionStateWithRespawn(session)); // Start in the appropriate mode try { if (getCli(mode)?.capabilities.startMode === 'shell') { await session.startShell(); getLifecycleLog().log({ event: 'started', sessionId: session.id, name: session.name, mode: 'shell', }); ctx.broadcast(SseEvent.SessionInteractive, { id: session.id, mode: 'shell' }); } else { // every non-shell mode ('claude', the external CLIs) uses startInteractive() await session.startInteractive(); getLifecycleLog().log({ event: 'started', sessionId: session.id, name: session.name, mode, }); ctx.broadcast(SseEvent.SessionInteractive, { id: session.id, mode }); } ctx.broadcast(SseEvent.SessionUpdated, { session: ctx.getSessionStateWithRespawn(session) }); // Docker + claude: the pane command pins the conversation id (--session-id / // --resume, claudeDockerPaneCommand), so persist it as the case's resume seed // NOW — a later container stop/reboot relaunch resumes this conversation even // if no in-container hook ever reaches the host (loopback bind, no bridge // listener). Hook/last-response adoption updates it again after /clear. if (docker && mode === 'claude') { void persistDockerCaseClaudeSessionId( CODEMAN_CONFIG_DIR, docker.containerName, session.claudeSessionId || session.id ).catch(() => {}); } // 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. // Awaited and serialized with every other settings.json writer (mutateSettingsFile): the // un-awaited write this replaced could land after the response, over a settings save. if (isAdmin(req)) { try { await mutateSettingsFile((settings) => ({ ...settings, lastUsedCase: caseName })); } catch (err) { // Non-critical: the session is already running. console.warn('[Server] Failed to save settings (lastUsedCase):', getErrorMessage(err)); } } return { sessionId: session.id, casePath: resolvedCasePath, caseName, ...(worktree ? { worktree, workingDir: workspacePath } : {}), ...(customModel ? { modelSwapInProgress: qsCustomModelSwapInProgress } : {}), ...(tabGroupId || landedInGroup(tabLayout, session.id) ? { tabLayout } : {}), }; } catch (err) { // Clean up session on error to prevent orphaned resources await ctx.cleanupSession(session.id, true, 'quick_start_error'); return createErrorResponse(ApiErrorCode.OPERATION_FAILED, getErrorMessage(err)); } }); // ═══════════════════════════════════════════════════════════════ // History — list past Claude conversations for resume // ═══════════════════════════════════════════════════════════════ /** Extract the text of the first user message from a JSONL transcript head. */ function extractFirstUserPrompt(head: string): string | undefined { const MAX_PROMPT_LEN = 120; // Iterate lines without allocating a full split array let start = 0; while (start < head.length) { const end = head.indexOf('\n', start); const line = end === -1 ? head.slice(start) : head.slice(start, end); start = end === -1 ? head.length : end + 1; if (!line.includes('"type":"user"')) continue; try { const entry = JSON.parse(line); if (entry.type !== 'user' || !entry.message) continue; const content = entry.message.content; let text: string | undefined; if (typeof content === 'string') { text = content; } else if (Array.isArray(content)) { const textBlock = content.find((b: { type: string }) => b.type === 'text'); if (textBlock) text = textBlock.text; } if (!text) continue; // Strip XML-like system/command tags and ANSI escapes from transcripts text = text .replace(/<[^>]+>/g, '') .replace(new RegExp(String.raw`\x1b\[[0-9;]*[a-zA-Z]`, 'g'), '') .trim() .replace(/\s+/g, ' '); if (!text) continue; // Skip system-injected messages, slash command artifacts, and expanded skill prompts if ( /^(Caveat:|init\b|clear\b|resume\b|\/[a-z][\w-]*\b|You are a |\[Request |Set model to )/i.test(text) || /^(Please )?(analyze|review) this codebase/i.test(text) || /^(Read|Implement the following) .+, then (search|list|check) /i.test(text) || /^\d+ vulnerabilit/i.test(text) || /\btoolu_/.test(text) || /^[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/.test(text) || /\b(sk-ant-|ANTHROPIC_API_KEY|API_KEY=|SECRET|TOKEN=)/i.test(text) || text.length < 8 ) continue; return text.length > MAX_PROMPT_LEN ? text.slice(0, MAX_PROMPT_LEN) + '\u2026' : text; } catch { // Malformed line — skip } } return undefined; } /** * Is this `entrypoint` value an automated/SDK-driven invocation? * * ⚠️ Deliberately a BLOCKLIST on the SDK shape, not an allowlist on `'cli'`. * The exclusion below hides rows, so an allowlist fails CLOSED on any value * Claude Code has not shipped yet: the day it stamps a new interactive * entrypoint (a rename, or a second interactive host), every transcript stops * matching `'cli'` and the whole Past Sessions list goes blank with nothing in * the UI to explain it. A blocklist fails OPEN instead — an automated * entrypoint we do not recognize yet costs a few noisy rows, which is the * annoyance this filter set out to fix rather than a broken feature. * * Observed values: `cli` (interactive), `sdk-cli` / `sdk-py` (automated). */ function isAutomatedEntrypoint(entrypoint: string): boolean { return /^sdk(-|$)/.test(entrypoint); } /** * The `entrypoint` field Claude Code stamps on its own message records: * 'cli' for a real interactive session, something else (e.g. 'sdk-py') for * an SDK/automated invocation. Used to exclude non-interactive transcripts * (CI review bots, etc.) from the resumable history list — they were never * something a user can resume into. * * Scans every `"type":"user"`/`"type":"assistant"` line with an entrypoint * field — not just the first one — and returns 'cli' the moment ANY of them * carries it. A transcript is excluded only when every entrypoint-bearing * message says something else; "first field wins" would misattribute a * transcript that started under an older Claude Code version (no entrypoint * on its true first message) and later picked up a non-'cli' entrypoint on * some later message, wrongly hiding a genuinely interactive session. This * deliberately errs toward keeping a session visible: one real interactive * message anywhere is enough. Returns undefined ("unknown", fail-open) only * when nothing scanned carries the field at all. */ function extractTranscriptEntrypoint(text: string): string | undefined { let start = 0; let sawNonCli: string | undefined; while (start < text.length) { const end = text.indexOf('\n', start); const line = end === -1 ? text.slice(start) : text.slice(start, end); start = end === -1 ? text.length : end + 1; if (!line.includes('"type":"user"') && !line.includes('"type":"assistant"')) continue; if (!line.includes('"entrypoint"')) continue; try { const entry = JSON.parse(line); if ((entry.type === 'user' || entry.type === 'assistant') && typeof entry.entrypoint === 'string') { if (entry.entrypoint === 'cli') return 'cli'; sawNonCli ??= entry.entrypoint; } } catch { // Malformed/truncated line — skip } } return sawNonCli; } /** Git/worktree facts recovered from a transcript. Every field is optional — * "unknown" must stay distinguishable from "not a worktree" (#265/#266). */ type TranscriptGitInfo = { /** The literal `cwd` Claude Code stamped on its own records. */ cwd?: string; gitBranch?: string; worktreeName?: string; /** Main repo root the worktree belongs to. */ worktreeRepo?: string; }; /** * Recover cwd / branch / worktree from a transcript chunk. * * Claude Code stamps `"cwd"` and `"gitBranch"` on every user/assistant record, * and writes a dedicated `worktree-state` record when the session was started * through its own worktree feature. This reads buffers `scanProjectDir` has * ALREADY loaded, so it costs no extra file I/O. * * Why this matters beyond a label: `decodeProjectKey()` reconstructs a path by * stat-walking the filesystem and falls back to `$HOME` when nothing resolves. * A deleted worktree is the normal end of a worktree's life, so every past * worktree session used to collapse onto `$HOME` (#265). The transcript value * is the literal cwd — non-lossy, and it survives the directory being removed. * * cwd is taken from the FIRST record that carries it (a session's cwd does not * move); gitBranch from the LAST (a branch genuinely changes mid-session, and * the newest value in the scanned chunk is the closest to current). */ function extractTranscriptGitInfo(text: string): TranscriptGitInfo { const info: TranscriptGitInfo = {}; let start = 0; while (start < text.length) { const end = text.indexOf('\n', start); const line = end === -1 ? text.slice(start) : text.slice(start, end); start = end === -1 ? text.length : end + 1; // Highest-confidence source: Claude's own worktree record. Names the // worktree explicitly, so it beats anything inferred from the path. if (line.includes('"worktree-state"')) { try { const rec = JSON.parse(line) as { worktreeSession?: { worktreeName?: unknown; worktreePath?: unknown; originalCwd?: unknown }; }; const ws = rec.worktreeSession; if (ws) { if (typeof ws.worktreeName === 'string') info.worktreeName ||= ws.worktreeName; if (typeof ws.originalCwd === 'string') info.worktreeRepo ||= ws.originalCwd; if (typeof ws.worktreePath === 'string') info.cwd ||= ws.worktreePath; } } catch { // Malformed/truncated line — skip } continue; } if (!line.includes('"cwd"') && !line.includes('"gitBranch"')) continue; if (!line.includes('"type":"user"') && !line.includes('"type":"assistant"')) continue; try { const rec = JSON.parse(line) as { cwd?: unknown; gitBranch?: unknown }; if (!info.cwd && typeof rec.cwd === 'string' && rec.cwd) info.cwd = rec.cwd; // Last one wins — closest to the session's current branch. if (typeof rec.gitBranch === 'string' && rec.gitBranch) info.gitBranch = rec.gitBranch; } catch { // Malformed/truncated line — skip } } // No explicit worktree record: infer from Claude's own worktree path layout. // A worktree created by hand (`git worktree add` anywhere) has no recoverable // NAME here — it still gets a branch, and the badge degrades to branch-only // rather than guessing. if (!info.worktreeName && info.cwd) { const m = CLAUDE_WORKTREE_PATH.exec(info.cwd); if (m) { info.worktreeName = m[2]; info.worktreeRepo ||= m[1]; } } return info; } /** * Extract the text of the LAST user message from a JSONL transcript chunk * (COD-145). Mirrors `extractFirstUserPrompt` exactly — same user-message * detection, same noise/secret/slash-command filters, same 120-char cap — but * keeps the last qualifying match instead of returning on the first. Scan the * file tail for this (the most recent prompt lives near the end). */ function extractLastUserPrompt(text: string): string | undefined { const MAX_PROMPT_LEN = 120; let result: string | undefined; let start = 0; while (start < text.length) { const end = text.indexOf('\n', start); const line = end === -1 ? text.slice(start) : text.slice(start, end); start = end === -1 ? text.length : end + 1; if (!line.includes('"type":"user"')) continue; try { const entry = JSON.parse(line); if (entry.type !== 'user' || !entry.message) continue; const content = entry.message.content; let msgText: string | undefined; if (typeof content === 'string') { msgText = content; } else if (Array.isArray(content)) { const textBlock = content.find((b: { type: string }) => b.type === 'text'); if (textBlock) msgText = textBlock.text; } if (!msgText) continue; msgText = msgText .replace(/<[^>]+>/g, '') .replace(new RegExp(String.raw`\x1b\[[0-9;]*[a-zA-Z]`, 'g'), '') .trim() .replace(/\s+/g, ' '); if (!msgText) continue; if ( /^(Caveat:|init\b|clear\b|resume\b|\/[a-z][\w-]*\b|You are a |\[Request |Set model to )/i.test(msgText) || /^(Please )?(analyze|review) this codebase/i.test(msgText) || /^(Read|Implement the following) .+, then (search|list|check) /i.test(msgText) || /^\d+ vulnerabilit/i.test(msgText) || /\btoolu_/.test(msgText) || /^[A-Za-z0-9_-]{20,}\.[A-Za-z0-9_-]+/.test(msgText) || /\b(sk-ant-|ANTHROPIC_API_KEY|API_KEY=|SECRET|TOKEN=)/i.test(msgText) || msgText.length < 8 ) continue; result = msgText.length > MAX_PROMPT_LEN ? msgText.slice(0, MAX_PROMPT_LEN) + '…' : msgText; } catch { // Malformed line — skip } } return result; } /** * Decode a Claude project key (e.g. "-Users-teigen-Documents-Workspace-AI-project-Mirror") * back to a filesystem path ("/Users/teigen/Documents/Workspace/AI_project/Mirror"). * * Claude CLI encodes both '/' and '_' as '-', so each '-' in the key could be * any of: '/' (path separator), '_' (underscore), or '-' (literal dash). * * Strategy: recursive backtracking with longest-match-first preference. * At each segment boundary, try joining as many segments as possible (with '_' * or '-') into a single existing directory name. If a shorter match leads to a * dead end, backtrack and try the next-shorter candidate. * * Why backtracking: when both `diary/` and `diary-app/` exist as siblings, the * naive shortest-match would pick `diary` and then fail to find `app` inside, * leaving the rest of the key unresolved. Longest-first picks `diary-app`. */ async function decodeProjectKey(projKey: string): Promise { const encoded = projKey.startsWith('-') ? projKey.slice(1) : projKey; const segments = encoded.split('-'); const isDirCache = new Map(); const isDir = async (p: string): Promise => { const cached = isDirCache.get(p); if (cached !== undefined) return cached; const result = await fs .stat(p) .then((s) => s.isDirectory()) .catch(() => false); isDirCache.set(p, result); return result; }; // Recursive backtracking: returns the deepest valid path that consumes all // segments. Tries the longest segment-join first at each step so that // dash-containing directory names win over shorter same-prefix siblings. async function tryDecode(idx: number, current: string): Promise { if (idx >= segments.length) return current; const maxLook = Math.min(idx + 4, segments.length); // Longest first: end = maxLook-1 down to idx for (let end = maxLook - 1; end >= idx; end--) { const candidates: string[] = []; if (end === idx) { // Skip an EMPTY segment: `isDir(current + '/' + '')` stats `current + '/'`, // which always succeeds, so the empty candidate would match unconditionally // and swallow the doubled dash that is the whole signature of a dotdir. It // then resolves "/home/x/.sib" to "/home/x//sib" whenever a non-dot sibling // exists, and shadows the dotdir branch below in every other case. if (segments[idx] !== '') candidates.push(segments[idx]); } else { candidates.push(segments.slice(idx, end + 1).join('-')); candidates.push(segments.slice(idx, end + 1).join('_')); } for (const child of candidates) { const candidate = current + '/' + child; if (await isDir(candidate)) { const result = await tryDecode(end + 1, candidate); if (result) return result; } } } // The encoder maps both '/' and '.' to '-', so a literal '.' in the // original path (e.g. "/home/timkjr/.codeman") collapses into an empty // split segment here. Retry this window as a dotdir/dotfile: ".". if (segments[idx] === '' && idx + 1 < segments.length) { const dotMaxLook = Math.min(idx + 1 + 4, segments.length); for (let end = dotMaxLook - 1; end >= idx + 1; end--) { const dotCandidates = end === idx + 1 ? [segments[idx + 1]] : [segments.slice(idx + 1, end + 1).join('-'), segments.slice(idx + 1, end + 1).join('_')]; for (const child of dotCandidates) { const candidate = current + '/.' + child; if (await isDir(candidate)) { const result = await tryDecode(end + 1, candidate); if (result) return result; } } } } return null; } const decoded = await tryDecode(0, ''); if (decoded) return decoded; // Fallback: greedy shortest-match (original behavior) — best effort when // no fully-valid path exists (e.g. directory was deleted after the // conversation was recorded). let current = ''; let i = 0; while (i < segments.length) { let matched = false; const maxLook = Math.min(i + 4, segments.length); for (let end = i; end < maxLook; end++) { const candidates: string[] = []; if (end === i) { // Same empty-segment skip as tryDecode above. This loop is shortest-match // first, so without it the empty candidate matches on the very first try // and sets `matched`, leaving the dotdir branch below permanently dead. if (segments[i] !== '') candidates.push(segments[i]); } else { candidates.push(segments.slice(i, end + 1).join('_')); candidates.push(segments.slice(i, end + 1).join('-')); } for (const child of candidates) { const candidate = current + '/' + child; if (await isDir(candidate)) { current = candidate; i = end + 1; matched = true; break; } } if (matched) break; } if (!matched && segments[i] === '' && i + 1 < segments.length) { const dotMaxLook = Math.min(i + 1 + 4, segments.length); for (let end = i + 1; end < dotMaxLook; end++) { const dotCandidates = end === i + 1 ? [segments[i + 1]] : [segments.slice(i + 1, end + 1).join('_'), segments.slice(i + 1, end + 1).join('-')]; for (const child of dotCandidates) { const candidate = current + '/.' + child; if (await isDir(candidate)) { current = candidate; i = end + 1; matched = true; break; } } if (matched) break; } } if (!matched) { if (segments[i] === '') { // Nothing on disk matched (the usual reason this fallback runs at all is // that the directory was deleted). An empty segment still means the // encoder ate a literal '.', so guess the dotdir form rather than // appending a bare '/' and emitting a "//" path. if (i + 1 < segments.length) { current = current + '/.' + segments[i + 1]; i += 2; } else { i++; } } else { current = current + '/' + segments[i]; i++; } } } const finalExists = await fs .access(current) .then(() => true) .catch(() => false); return finalExists ? current : process.env.HOME || '/tmp'; } /** Read the first `buf.length` bytes of a file for content sniffing. */ async function readFileHead(path: string, buf: Buffer): Promise { try { const fd = await fs.open(path, 'r'); const { bytesRead } = await fd.read(buf, 0, buf.length, 0); await fd.close(); return buf.toString('utf8', 0, bytesRead); } catch { return null; } } /** Read the last `buf.length` bytes of a file (for tail-scanning user prompts). */ async function readFileTail(path: string, buf: Buffer, fileSize: number): Promise { try { const fd = await fs.open(path, 'r'); const offset = Math.max(0, fileSize - buf.length); const { bytesRead } = await fd.read(buf, 0, buf.length, offset); await fd.close(); const text = buf.toString('utf8', 0, bytesRead); // Skip first partial line when we didn't read from the start if (offset > 0) { const nl = text.indexOf('\n'); return nl >= 0 ? text.slice(nl + 1) : null; } return text; } catch { return null; } } type HistorySession = { sessionId: string; workingDir: string; projectKey: string; sizeBytes: number; lastModified: string; firstPrompt?: string; lastPrompt?: string; /** True when workingDir came from the transcript rather than decodeProjectKey's guess. */ workingDirExact?: boolean; gitBranch?: string; worktreeName?: string; worktreeRepo?: string; }; // Scan a single project directory and return all valid history sessions in it. // Reused by both the global overview and the single-folder drill-down. async function scanProjectDir( projPath: string, projDir: string, smallHeadBuf: Buffer, headBuf: Buffer ): Promise { const out: HistorySession[] = []; const stat = await fs.stat(projPath).catch(() => null); if (!stat?.isDirectory()) return out; const workingDir = await decodeProjectKey(projDir); const staleCwd = new Map(); const entries = await fs.readdir(projPath).catch(() => [] as string[]); for (const entry of entries) { if (!entry.endsWith('.jsonl')) continue; const sessionId = entry.replace('.jsonl', ''); if (!/^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/.test(sessionId)) continue; const filePath = join(projPath, entry); const fileStat = await fs.stat(filePath).catch(() => null); if (!fileStat) continue; if (fileStat.size < 4000) continue; const hasConversation = (text: string) => text.includes('"type":"user"') || text.includes('"type":"assistant"') || text.includes('"type":"summary"'); // Two-tier head read: try the cheap smallHeadBuf (16KB) size first -- enough // for the vast majority of transcripts -- and only escalate to the full // headBuf (128KB) when that wasn't enough. Reading 128KB unconditionally for // EVERY file in the directory roughly quadrupled the cost of a full scan // (measured against a real ~/.claude/projects tree: ~4x both bytes read and // wall time) to fix a problem only ~28% of files actually have. Escalating // resolves the restart-bookkeeping case (the reason 128KB exists at all) // without ever touching the tail-read fallback below for most of that 28%. let head = await readFileHead(filePath, smallHeadBuf); let foundContent = head ? hasConversation(head) : false; let firstPrompt = head ? extractFirstUserPrompt(head) : undefined; if ((!foundContent || !firstPrompt) && head !== null && fileStat.size > smallHeadBuf.length) { const biggerHead = await readFileHead(filePath, headBuf); if (biggerHead) { head = biggerHead; if (!foundContent) foundContent = hasConversation(head); if (!firstPrompt) firstPrompt = extractFirstUserPrompt(head); } } let tail: string | null = null; // `head === null` (a failed read -- e.g. EMFILE while scanning hundreds of // files) must also get a shot at the tail, not just "file bigger than the // head buffer". Losing this dropped the session from history entirely // instead of giving it a second chance, for any file at or under the head // buffer size whose head read happened to fail. if (!foundContent && (head === null || fileStat.size > headBuf.length)) { const tailBuf = Buffer.alloc(32768); tail = await readFileTail(filePath, tailBuf, fileStat.size); if (tail) foundContent = hasConversation(tail); } if (!foundContent) continue; // firstPrompt was already attempted from head (both tiers) above; this is // purely the tail fallback for whatever's left unresolved. if (!firstPrompt && (head === null || fileStat.size > headBuf.length)) { if (!tail) { const tailBuf = Buffer.alloc(32768); tail = await readFileTail(filePath, tailBuf, fileStat.size); } if (tail) firstPrompt = extractFirstUserPrompt(tail); } // COD-145: last (most recent) user prompt lives near the END of the file, so // prefer the tail. For large files where no tail was read yet, read one // (mirrors the firstPrompt > headBuf.length block). Small files fit in `head`, // which then contains the whole transcript — scan it for the last match instead. if (!tail && fileStat.size > headBuf.length) { const tailBuf = Buffer.alloc(32768); tail = await readFileTail(filePath, tailBuf, fileStat.size); } const lastPrompt = (tail ? extractLastUserPrompt(tail) : undefined) ?? (head ? extractLastUserPrompt(head) : undefined); // Automated/SDK-driven invocations (CI review bots, etc.) write transcripts // into the same ~/.claude/projects tree as interactive sessions but were // never something a user can resume into — no PTY, no running process, and // their "conversation" is typically a single one-shot prompt (often with a // full diff embedded, which is exactly why it dwarfs this scanner's read // windows and shows up above as blank or as an identical boilerplate // sentence across many rows). Checked last, so it reuses whatever `head`/ // `tail` the prompt extraction above already read rather than triggering // an extra file read. Missing entrypoint (older transcripts) reads as // interactive — fail open, matching every other gating check in this // codebase. // // head and tail are checked independently and merged with "cli wins" (not // a first-truthy-value `??` chain): a large file's head might land on a // non-'cli' message while a real interactive message sits in the tail (or // vice versa), and either one being 'cli' is enough to keep the session. const headEntrypoint = head ? extractTranscriptEntrypoint(head) : undefined; const tailEntrypoint = tail ? extractTranscriptEntrypoint(tail) : undefined; const entrypoint = headEntrypoint === 'cli' || tailEntrypoint === 'cli' ? 'cli' : (headEntrypoint ?? tailEntrypoint); if (entrypoint && isAutomatedEntrypoint(entrypoint)) continue; // Git/worktree facts from the buffers already read above — no extra I/O. // head first (cwd is stamped near the top; median offset ~1KB), tail as the // fallback for transcripts whose head read failed or came up empty. const headGit = head ? extractTranscriptGitInfo(head) : {}; const tailGit = tail ? extractTranscriptGitInfo(tail) : {}; const git: TranscriptGitInfo = { cwd: headGit.cwd ?? tailGit.cwd, // Last-wins within a chunk; across chunks the tail is the newer one. gitBranch: tailGit.gitBranch ?? headGit.gitBranch, worktreeName: headGit.worktreeName ?? tailGit.worktreeName, worktreeRepo: headGit.worktreeRepo ?? tailGit.worktreeRepo, }; // A case rename moves the project directory but leaves the old path in each transcript's // cwd. When that cwd is gone and the decoded key is a real folder that encodes back to this // very key (not the $HOME collapse of #265), the key is the truer answer. let cwd = git.cwd; if (cwd !== undefined && cwd !== workingDir) { let stale = staleCwd.get(cwd); if (stale === undefined) { stale = claudeProjectDirName(workingDir) === projDir && (await fs.stat(cwd).then( () => false, () => true )) && (await fs.stat(workingDir).then( (s) => s.isDirectory(), () => false )); staleCwd.set(cwd, stale); } if (stale) cwd = undefined; } out.push({ sessionId, // The transcript's literal cwd beats decodeProjectKey's stat-walked guess, // which silently collapses to $HOME once the directory is gone (#265). // Absent cwd falls back to the old behaviour rather than inventing a path. workingDir: cwd ?? workingDir, workingDirExact: cwd !== undefined, projectKey: projDir, sizeBytes: fileStat.size, lastModified: fileStat.mtime.toISOString(), firstPrompt, lastPrompt, gitBranch: git.gitBranch, worktreeName: git.worktreeName, worktreeRepo: git.worktreeRepo, }); } return out; } app.get('/api/history/sessions', async (req) => { const query = req.query as { projectKey?: string; offset?: string; limit?: string }; const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects'); // scanProjectDir tries smallHeadBuf (16KB, the original size) first for every // file and only escalates to headBuf (128KB) when that wasn't enough — see the // comment at the escalation site in scanProjectDir for why unconditional 128KB // reads were too expensive to keep. 128KB matches the existing precedent // elsewhere in this file (line ~1431). const smallHeadBuf = Buffer.alloc(16384); const headBuf = Buffer.alloc(131072); // Multi-user: this scans the host-wide ~/.claude/projects tree, so a non-admin // must only see history whose decoded workingDir is inside their own case space. // Do NOT trust the caller-supplied projectKey — confine on the decoded path. // No-op for admins / single-user mode. const user = getAuthUser(req); const scopeHistory = isMultiUserMode() && user.role !== 'admin'; // Single-folder drill-down: when projectKey is provided, scan only that // directory, bypass the 50-cap, and honor offset/limit pagination. if (query.projectKey) { // Validate projectKey format to prevent path traversal if (!/^[A-Za-z0-9_-]+$/.test(query.projectKey)) { return { sessions: [], total: 0 }; } const offset = Math.max(0, parseInt(query.offset || '0', 10) || 0); const limit = Math.min(100, Math.max(1, parseInt(query.limit || '20', 10) || 20)); const projPath = join(projectsDir, query.projectKey); let all = await scanProjectDir(projPath, query.projectKey, smallHeadBuf, headBuf); // Confine to the caller's workspace (a projectKey maps to a single foreign cwd). if (scopeHistory) all = all.filter((r) => isWorkingDirAllowed(user, r.workingDir)); all.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime()); return { sessions: all.slice(offset, offset + limit), total: all.length }; } // Global overview: scan all projects, return up to 50 most-recent sessions. let results: HistorySession[] = []; try { const projectDirs = await fs.readdir(projectsDir); for (const projDir of projectDirs) { const projPath = join(projectsDir, projDir); const list = await scanProjectDir(projPath, projDir, smallHeadBuf, headBuf); results.push(...list); } } catch { // Projects dir may not exist } // Multi-user: drop rows outside the non-admin caller's own case space. if (scopeHistory) results = results.filter((r) => isWorkingDirAllowed(user, r.workingDir)); results.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime()); return { sessions: results.slice(0, 50) }; }); /** * Gather the four read-only views the unified list is merged from, plus mux * stats. This is the expensive half (the lifecycle log and a scan of every * Claude transcript), factored out of the route handler because the * past-session search index rebuilds itself from the very same inputs, off * the request path, see session-history-index.ts. */ async function gatherUnifiedInputs(): Promise<{ live: LiveSessionInput[]; persisted: PersistedSessionInput[]; lifecycle: LifecycleInput[]; history: HistoryInput[]; mux: MuxStatInput[]; }> { // Live (in-memory) sessions. const live: LiveSessionInput[] = [...ctx.sessions.values()].map((s) => { const st = s.toState(); return { id: st.id, name: st.name, mode: st.mode, status: st.status, isWorking: s.isWorking, workingDir: st.workingDir, createdAt: st.createdAt, lastActivityAt: st.lastActivityAt, claudeSessionId: s.claudeSessionId ?? undefined, pinned: st.pinned, pinnedAt: st.pinnedAt, }; }); // Persisted sessions (state.json). resumeSessionId is the Claude // conversation UUID a resumed session continues — feed it to the merge's // alias map so its transcript row folds into this session. // // codex keeps its thread id in `codexConfig` instead, and state.json stores // that, so read it here as well. Without it a resumed codex session that has // been demoted to a persisted-only record loses its alias and duplicates: the // originator fallback below cannot rescue that one, because a RESUMED rollout // keeps the original session_meta (see findActiveCodexFile) and so still // names whichever pane first created the thread. const persisted: PersistedSessionInput[] = Object.values(ctx.store.getState().sessions).map((p) => ({ id: p.id, name: p.name, mode: p.mode, status: p.status, workingDir: p.workingDir, createdAt: p.createdAt, lastActivityAt: p.lastActivityAt, claudeSessionId: p.resumeSessionId || p.codexConfig?.resumeSessionId, pinned: p.pinned, pinnedAt: p.pinnedAt, })); // Lifecycle audit log (newest-first, capped). let lifecycle: LifecycleInput[] = []; try { const entries = await getLifecycleLog().query({ limit: 2000 }); lifecycle = entries.map((e) => ({ sessionId: e.sessionId, name: e.name, mode: e.mode, ts: e.ts, event: e.event, })); } catch { // Lifecycle log may be unavailable; treat as empty. } // Transcript history (~/.claude/projects) — reuse the same scanner as the overview. const history: HistoryInput[] = []; try { const projectsDir = join(process.env.HOME || '/tmp', '.claude', 'projects'); // See the sibling allocation above for why there are two sizes. const smallHeadBuf = Buffer.alloc(16384); const headBuf = Buffer.alloc(131072); const projectDirs = await fs.readdir(projectsDir); for (const projDir of projectDirs) { const projPath = join(projectsDir, projDir); const list = await scanProjectDir(projPath, projDir, smallHeadBuf, headBuf); for (const h of list) { history.push({ sessionId: h.sessionId, workingDir: h.workingDir, sizeBytes: h.sizeBytes, lastModified: h.lastModified, firstPrompt: h.firstPrompt, lastPrompt: h.lastPrompt, projectKey: h.projectKey, gitBranch: h.gitBranch, worktreeName: h.worktreeName, worktreeRepo: h.worktreeRepo, }); } } } catch { // Projects dir may not exist. } // OMP's own session files (~/.omp/agent/sessions) — the non-claude twin // of the scan above; see omp-transcript.ts for why this exists at all. try { for (const h of scanOmpSessionsHistory()) { history.push({ sessionId: h.sessionId, workingDir: h.workingDir, sizeBytes: h.sizeBytes, lastModified: h.lastModified, firstPrompt: h.firstPrompt, lastPrompt: h.lastPrompt, mode: 'omp', }); } } catch { // Best-effort, same as the claude scan above. } // Codex's own rollout store (~/.codex/sessions) — the same treatment omp // gets above, and for the same reason: codex writes no Claude transcript, so // without this a codex conversation disappears from the list as soon as its // session record does. `resumeId` is the rollout's own thread id, which is // what `codex resume` takes; see codex-transcript.ts. try { const codexRows = await scanCodexSessionsHistory(); for (const h of codexRows) { history.push({ sessionId: h.sessionId, workingDir: h.workingDir, sizeBytes: h.sizeBytes, lastModified: h.lastModified, firstPrompt: h.firstPrompt, lastPrompt: h.lastPrompt, mode: 'codex', resumeId: h.sessionId, }); } // Fold a FRESH codex pane into its own rollout row. A resumed one already // folds, because Session sets `claudeSessionId` from the resume id it was // given; a fresh one has no thread id until codex writes the rollout, so // the link has to come from the other side. Codeman spawns every codex pane // with CODEX_INTERNAL_ORIGINATOR_OVERRIDE=codeman_, and codex // stamps that into session_meta.originator, so the rollout names the pane. // // Newest rollout wins: `/new` typed inside the TUI leaves several rollouts // carrying the same originator, and the pane is on the most recent one. // Rows arrive newest-first, so the first match is it. // // Never overwrites an id a session already knows — that one came from the // resume path and is authoritative. const codexThreads = codexThreadBySessionId(codexRows); for (const row of [...live, ...persisted]) { if (row.claudeSessionId && row.claudeSessionId !== row.id) continue; const threadId = codexThreads.get(row.id); if (threadId) row.claudeSessionId = threadId; } } catch { // Best-effort, same as the two scans above. } // Mux process stats (best-effort; guard against mocks lacking the method). let mux: MuxStatInput[] = []; try { const getStats = (ctx.mux as { getSessionsWithStats?: () => Promise }).getSessionsWithStats; if (typeof getStats === 'function') { const muxSessions = (await getStats.call(ctx.mux)) as Array<{ sessionId: string; muxName?: string; mode?: string; remote?: unknown; stats?: { memoryMB: number; cpuPercent: number }; }>; mux = muxSessions.map((m) => ({ sessionId: m.sessionId, muxName: m.muxName, mode: m.mode, remote: m.remote !== undefined ? true : undefined, stats: m.stats ? { memoryMB: m.stats.memoryMB, cpuPercent: m.stats.cpuPercent } : undefined, })); } } catch { // Mux stats are optional. } return { live, persisted, lifecycle, history, mux }; } /** * Publish a merged unified list as the past-session search index (issue #261). * The snapshot is stored UNSCOPED with a per-row owner, so it must only ever be * built from an unscoped merge, `harvestSources()` in search-routes re-applies * the ownership check on read. */ function publishHistorySessionIndex(merged: UnifiedSessionItem[]): void { const ownerById = new Map(); const stored = ctx.store.getState().sessions as Record; for (const p of Object.values(stored)) ownerById.set(p.id, p.owner); // Live wins: a session's owner on disk can lag the running one. for (const s of ctx.sessions.values()) ownerById.set(s.id, s.owner); const liveIds = new Set(ctx.sessions.keys()); setHistorySessionIndex(buildHistorySessionIndexItems(merged, ownerById, liveIds)); } // Rebuild hook for the search route: it kicks this (fire-and-forget) when the // snapshot goes stale, so a search never pays for the scan itself. setHistoryIndexRefresher(async () => { if (ctx.testMode) return; publishHistorySessionIndex(mergeUnifiedSessions(await gatherUnifiedInputs())); }); // Unified, read-only session list: merges live + persisted + lifecycle + // transcript history + mux stats into one de-duplicated, searchable list // (COD-121). Pure merge/filter logic lives in unified-session-service.ts. app.get('/api/sessions/unified', async (req) => { const query = req.query as { q?: string; offset?: string; limit?: string }; if (ctx.testMode) { return { sessions: [], total: 0 }; } const { live, persisted, lifecycle, history, mux } = await gatherUnifiedInputs(); // Multi-user: a non-admin only sees their own sessions; host-wide transcript // history (not tied to an owned session) is admin-only. let sLive = live; let sPersisted = persisted; let sLifecycle = lifecycle; let sHistory = history; let scoped = false; const uUser = getAuthUser(req); if (isMultiUserMode() && uUser.role !== 'admin') { scoped = true; const ownedLive = new Set( [...ctx.sessions.values()].filter((s) => canAccessOwned(uUser, s.owner)).map((s) => s.id) ); const stored = ctx.store.getState().sessions as Record; const ownedPersisted = new Set( Object.values(stored) .filter((p) => canAccessOwned(uUser, p.owner)) .map((p) => p.id) ); const isOwned = (id: string) => ownedLive.has(id) || ownedPersisted.has(id); sLive = live.filter((l) => isOwned(l.id)); sPersisted = persisted.filter((p) => isOwned(p.id)); sLifecycle = lifecycle.filter((e) => isOwned(e.sessionId)); sHistory = []; } const merged = mergeUnifiedSessions({ live: sLive, persisted: sPersisted, lifecycle: sLifecycle, history: sHistory, mux, }); // Refresh the search index off the back of this request, the home screen // fetches this endpoint whenever it opens, which is the same screen the // search box lives on, so the snapshot is warm before anyone types. A scoped // merge is a per-user subset and would corrupt the shared snapshot, so that // path re-merges unscoped instead (multi-user is opt-in and rarely hit). publishHistorySessionIndex(scoped ? mergeUnifiedSessions({ live, persisted, lifecycle, history, mux }) : merged); const offset = query.offset !== undefined ? parseInt(query.offset, 10) : undefined; const limit = query.limit !== undefined ? parseInt(query.limit, 10) : undefined; return filterAndPaginate(merged, { q: query.q, offset: Number.isNaN(offset as number) ? undefined : offset, limit: Number.isNaN(limit as number) ? undefined : limit, }); }); // ═══════════════════════════════════════════════════════════════ // 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: Record = { 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: string, ext: string, bytes: Buffer, 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 // (no preflight), so a cross-origin
// submit attaches the session cookie unimpeded. Reject unless Origin/Referer // matches req.host. Non-browser clients (no Origin AND no Referer) must // supply X-Codeman-CSRF — a header browsers cannot add cross-origin without // a preflight, which our CORS config does not allow from other origins. const reqHost = req.headers.host; const origin = req.headers.origin; const referer = req.headers.referer; let csrfOk = false; if (origin) { try { csrfOk = new URL(origin).host === reqHost; } catch { /* invalid Origin → not ok */ } } else if (referer) { try { csrfOk = new URL(referer).host === reqHost; } catch { /* invalid Referer → not ok */ } } else { csrfOk = !!req.headers['x-codeman-csrf']; } if (!csrfOk) { reply.code(403); return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'CSRF check failed'); } const { id } = req.params as { id: string }; // `?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 as { kind?: string }).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, 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'); } // Read the single file part. @fastify/multipart enforces the per-file size // cap (MAX_PASTE_IMAGE_BYTES) and the 1-file/4-field count limits (server.ts), // replacing a hand-rolled // 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: import('@fastify/multipart').MultipartFile | undefined; try { part = await req.file( isVideo ? { limits: { fileSize: MAX_PASTE_VIDEO_BYTES }, throwFileSizeLimit: false } : undefined ); } catch (err: unknown) { reply.code(413); return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err) || 'Invalid multipart payload'); } if (!part) { reply.code(400); return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'No image uploaded'); } if (part.fieldname !== 'image') { 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: unknown) { await fs.unlink(filepath).catch(() => {}); throw err; } finally { await fh.close(); } let failure: { status: number; message: string } | null = 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: Buffer; try { imageBytes = await part.toBuffer(); } catch (err: unknown) { reply.code(413); const maxMb = Math.round(MAX_PASTE_IMAGE_BYTES / (1024 * 1024)); return createErrorResponse(ApiErrorCode.INVALID_INPUT, getErrorMessage(err) || `File too large (max ${maxMb}MB)`); } if (imageBytes.length === 0) { 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. // 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, 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) { 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 (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: Record = { png: '.png', jpeg: '.jpg', jpg: '.jpg', webp: '.webp', gif: '.gif', bmp: '.bmp', heic: '.heic', heif: '.heif', }; ext = map[mimeMatch[1]] ?? ext; } if (!ALLOWED_IMAGE_EXTS.has(ext)) { reply.code(400); return createErrorResponse( ApiErrorCode.INVALID_INPUT, `Unsupported image type: ${ext}. Allowed: ${[...ALLOWED_IMAGE_EXTS].join(', ')}` ); } // Route HEIC on the raw bytes, NOT the declared ext/mime: on some Android // galleries (e.g. MIUI) a HEIF comes back mislabeled as image/jpeg, and // browsers that cannot decode HEIF upload the original file as-is — so a // HEIC payload can arrive under any declared type. Filename and // Content-Type are attacker-supplied anyway; only the bytes are trusted. if (imageMagicMatchesExt(imageBytes, '.heic')) { try { imageBytes = await convertHeicToJpeg(imageBytes); ext = '.jpg'; } catch (err: unknown) { console.warn( `[paste-image] HEIC conversion failed: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} error=${getErrorMessage(err)}` ); reply.code(415); return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Could not convert HEIC image to JPEG'); } } 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 // client re-encodes images to JPEG/PNG before upload, so this is rare. console.warn( `[paste-image] magic mismatch: filename=${JSON.stringify(part.filename)} mime=${JSON.stringify(part.mimetype)} declaredExt=${ext} magic=${imageBytes.subarray(0, 12).toString('hex')}` ); reply.code(415); return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Image bytes do not match declared type ${ext}`); } 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`); } 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 // code stays here: `test/remote-wake.test.ts` pins that `server.ts` calls nothing but // `drop`/`stop` on this handle, so no timer path can reach a wake through it. return remoteWake; }