/**
 * @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 { FastifyInstance } from 'fastify';
import { join, dirname, extname, basename } 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 { randomBytes } from 'node:crypto';
import {
  ApiErrorCode,
  createErrorResponse,
  getErrorMessage,
  type ApiResponse,
  type SessionColor,
} from '../../types.js';
import { Session, isAltScreenStripMode } from '../../session.js';
import { SseEvent } from '../sse-events.js';
import {
  CreateSessionSchema,
  SessionNameSchema,
  SessionColorSchema,
  RunPromptSchema,
  SessionInputWithLimitSchema,
  ResizeSchema,
  AutoClearSchema,
  AutoCompactSchema,
  AutoResumeSchema,
  ImageWatcherSchema,
  FlickerFilterSchema,
  QuickRunSchema,
  QuickStartSchema,
  InteractiveStartSchema,
  SessionOrderUpdateSchema,
} from '../schemas.js';
import { mergeSessionOrder } from '../../session-order.js';
import {
  autoConfigureRalph,
  CASES_DIR,
  findSessionOrFail,
  parseBody,
  persistAndBroadcastSession,
  SETTINGS_PATH,
  validatePathWithinBase,
} from '../route-helpers.js';
import { AUTH_COOKIE_NAME } from '../middleware/auth.js';
import {
  writeHooksConfig,
  updateCaseModel,
  stripCaseEnvKeys,
  applyStatusLineConfig,
  refreshStaleHookSecret,
} 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,
} from '../../services/unified-session-service.js';
import type { SessionPort, EventPort, ConfigPort, InfraPort, AuthPort } from '../ports/index.js';
import { MAX_CONCURRENT_SESSIONS } from '../../config/map-limits.js';
import { RunSummaryTracker } from '../../run-summary.js';

import { MAX_INPUT_LENGTH, MAX_SESSION_NAME_LENGTH } from '../../config/terminal-limits.js';
import { MAX_PASTE_IMAGE_BYTES } from '../../config/buffer-limits.js';
import { dataPath, getDataDir } from '../../config/instance.js';
import { checkRemoteTmuxAvailable, readRemoteCases, readRemoteHosts, toSessionRemote } from '../../remote-hosts.js';
import { LRUMap } from '../../utils/lru-map.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();

// 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;

/**
 * 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('');
}

/**
 * Validate image bytes against a declared extension. Sniffs the first ~12 bytes
 * for a known magic-number signature. Defends against polyglots (e.g. HTML or
 * SVG disguised under a `Content-Type: image/png` header) and against simple
 * extension-only spoofing — both the multipart filename and the Content-Type
 * are attacker-controlled, the raw bytes are not.
 *
 * Signatures: https://en.wikipedia.org/wiki/List_of_file_signatures
 */
export function imageMagicMatchesExt(data: Buffer, ext: string): boolean {
  if (data.length < 12) return false;
  const u32be = (off: number): number => data.readUInt32BE(off);
  switch (ext) {
    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);
    }
    default:
      return false;
  }
}

// Per-(IP, sessionId) token bucket for paste-image. 30 requests/minute.
// Bucket map entries are pruned when they drift > 1h stale to bound memory
// against a flood of unique IP keys.
const PASTE_RATE_TOKENS = 30;
const PASTE_RATE_REFILL_PER_MS = PASTE_RATE_TOKENS / 60_000;
const PASTE_BUCKET_TTL_MS = 60 * 60 * 1000;
const PASTE_BUCKET_GC_THRESHOLD = 1000;
const pasteRateBuckets = new Map<string, { tokens: number; lastRefill: number }>();

export function consumePasteToken(key: string, now: number = Date.now()): boolean {
  if (pasteRateBuckets.size > PASTE_BUCKET_GC_THRESHOLD) {
    for (const [k, b] of pasteRateBuckets) {
      if (now - b.lastRefill > PASTE_BUCKET_TTL_MS) pasteRateBuckets.delete(k);
    }
  }
  let b = pasteRateBuckets.get(key);
  if (!b) {
    b = { tokens: PASTE_RATE_TOKENS, lastRefill: now };
    pasteRateBuckets.set(key, b);
  }
  const delta = (now - b.lastRefill) * PASTE_RATE_REFILL_PER_MS;
  b.tokens = Math.min(PASTE_RATE_TOKENS, b.tokens + delta);
  b.lastRefill = now;
  if (b.tokens < 1) return false;
  b.tokens -= 1;
  return true;
}

// Test hook: reset between runs.
export function _resetPasteRateBuckets(): void {
  pasteRateBuckets.clear();
}

export function registerSessionRoutes(
  app: FastifyInstance,
  ctx: SessionPort & EventPort & ConfigPort & InfraPort & AuthPort
): void {
  // ═══════════════════════════════════════════════════════════════
  // 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);
    }
    reply.clearCookie(AUTH_COOKIE_NAME, { path: '/' });
    return {};
  });

  // ═══════════════════════════════════════════════════════════════
  // Session CRUD (list, create, rename, color, delete, detail)
  // ═══════════════════════════════════════════════════════════════

  // ========== Session Listing ==========

  app.get('/api/sessions', async () => {
    return ctx.getLightSessionsState();
  });

  // ========== Session Tab Order (global sync, COD-131) ==========

  app.put('/api/session-order', async (req): Promise<ApiResponse<{ order: string[] }>> => {
    const { order } = parseBody(SessionOrderUpdateSchema, req.body, 'Invalid session order');
    // Server is authoritative but never drops ids it knows about that the
    // pushing device hadn't loaded yet — those fall to the end (mergeSessionOrder).
    const merged = mergeSessionOrder(order, ctx.store.getSessionOrder());
    ctx.store.setSessionOrder(merged);
    ctx.broadcast(SseEvent.SessionOrderChanged, { order: merged });
    return { success: true, data: { order: merged } };
  });

  // ========== Session Creation ==========

  app.post('/api/sessions', async (req) => {
    // Prevent unbounded session creation
    if (ctx.sessions.size >= MAX_CONCURRENT_SESSIONS) {
      return createErrorResponse(
        ApiErrorCode.OPERATION_FAILED,
        `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached. Delete some sessions first.`
      );
    }

    const body = parseBody(CreateSessionSchema, req.body);
    const workingDir = body.workingDir || process.cwd();

    // Validate workingDir exists and is a directory
    if (body.workingDir) {
      try {
        const stat = statSync(workingDir);
        if (!stat.isDirectory()) {
          return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir is not a directory');
        }
      } catch {
        return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'workingDir does not exist');
      }
    }

    // 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 don't read .claude/settings.local.json)
    //   - workingDir inside CASES_DIR (Codeman's managed territory — we never mutate
    //     .claude/settings.local.json in arbitrary user repos that POST /api/sessions
    //     can target, because those may have hand-authored values).
    const canStripDisk =
      body.mode !== 'opencode' &&
      body.mode !== 'codex' &&
      body.mode !== 'gemini' &&
      body.envOverrides &&
      Object.keys(body.envOverrides).length > 0 &&
      workingDir.startsWith(CASES_DIR + '/');
    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 statusLine exporter (App Settings → Display → "Plan Usage
    // Limits"). Claude-only; runs for ANY working dir (linked cases / real repos,
    // where most sessions live), mirroring updateCaseModel above.
    //
    // ADD-ONLY: we never remove on create. Sessions in a repo share one
    // settings.local.json, so a single create-with-false (e.g. a client whose
    // synced setting hadn't loaded yet) must NOT yank the statusLine out from
    // under other live sessions in that repo — that breaks their footer + the
    // chip's data feed for everyone. The exporter is benign when the chip is off
    // (the footer just shows session status). isOurs-guarded so a user's own
    // statusLine is never touched.
    if ((body.mode ?? 'claude') === 'claude' && body.statusLineTelemetry === true) {
      await applyStatusLineConfig(workingDir, true);
    }

    // COD-91 self-heal: refresh a pre-secret hooks block in an existing case so the now
    // unconditional hook-secret gate keeps accepting its hook events. No-op for fresh
    // cases (writeHooksConfig already wrote the secret) and for non-Codeman/absent hooks.
    if ((body.mode ?? 'claude') === 'claude') {
      await refreshStaleHookSecret(workingDir).catch(() => {});
    }

    // Check OpenCode availability if requested
    if (body.mode === 'opencode') {
      const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
      if (!isOpenCodeAvailable()) {
        return createErrorResponse(
          ApiErrorCode.OPERATION_FAILED,
          'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash'
        );
      }
    }

    // Check Codex availability if requested
    if (body.mode === 'codex') {
      const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
      if (!isCodexAvailable()) {
        return createErrorResponse(
          ApiErrorCode.OPERATION_FAILED,
          'Codex CLI not found. Install with: npm install -g @openai/codex'
        );
      }
    }

    // Check Gemini availability if requested
    if (body.mode === 'gemini') {
      const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
      if (!isGeminiAvailable()) {
        return createErrorResponse(
          ApiErrorCode.OPERATION_FAILED,
          'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
        );
      }
    }

    // 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';
    const model =
      mode === 'opencode'
        ? body.openCodeConfig?.model
        : mode === 'codex'
          ? body.codexConfig?.model
          : mode === 'gemini'
            ? body.geminiConfig?.model
            : mode !== 'shell'
              ? modelConfig?.defaultModel || undefined
              : undefined;
    const claudeModeConfig = await ctx.getClaudeModeConfig();
    const terminalHistoryConfig = await ctx.getTerminalHistoryConfig();
    const session = new Session({
      workingDir,
      mode,
      name: body.name || '',
      mux: ctx.mux,
      useMux: true,
      niceConfig: globalNice,
      model,
      claudeMode: claudeModeConfig.claudeMode,
      allowedTools: claudeModeConfig.allowedTools,
      openCodeConfig: mode === 'opencode' ? body.openCodeConfig : undefined,
      codexConfig: mode === 'codex' ? body.codexConfig : undefined,
      geminiConfig: mode === 'gemini' ? body.geminiConfig : undefined,
      resumeSessionId: validatedResumeId,
      envOverrides: body.envOverrides,
      effort: body.effort,
      tmuxHistoryLimit: terminalHistoryConfig.tmuxHistoryLimit,
    });

    ctx.addSession(session);
    ctx.store.incrementSessionsCreated();
    ctx.persistSessionState(session);
    await ctx.setupSessionListeners(session);
    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);
    return { session: lightState };
  });

  // ========== 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);

    const name = String(body.name || '').slice(0, MAX_SESSION_NAME_LENGTH);
    session.name = name;
    // Also update the mux session name if applicable
    ctx.mux.updateSessionName(id, session.name);
    persistAndBroadcastSession(ctx, 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);

    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 };
  });

  // ========== 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

    if (!ctx.sessions.has(id)) {
      return createErrorResponse(ApiErrorCode.NOT_FOUND, 'Session not found');
    }

    await ctx.cleanupSession(id, killMux, 'user_delete');
    return {};
  });

  // ========== Delete All Sessions ==========

  app.delete('/api/sessions', async (): Promise<ApiResponse<{ killed: number }>> => {
    const sessionIds = Array.from(ctx.sessions.keys());
    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);

    // 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);

    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);

    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);

    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);

    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);

    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);

    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)
      // Ralph tracker is not supported for opencode / codex / gemini sessions
      if (
        session.mode !== 'opencode' &&
        session.mode !== 'codex' &&
        session.mode !== 'gemini' &&
        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,
      });
      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);

    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',
      });
      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)
  // ═══════════════════════════════════════════════════════════════

  // ========== Send Input ==========

  app.post('/api/sessions/:id/input', async (req) => {
    const { id } = req.params as { id: string };
    const { input, useMux, seq, clientId } = parseBody(SessionInputWithLimitSchema, req.body);
    const session = findSessionOrFail(ctx, id);

    const inputStr = String(input);
    if (inputStr.length > MAX_INPUT_LENGTH) {
      return createErrorResponse(
        ApiErrorCode.INVALID_INPUT,
        `Input exceeds maximum length (${MAX_INPUT_LENGTH} bytes)`
      );
    }

    // 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.
    if (typeof clientId === 'string' && typeof seq === 'number' && !session.shouldApplyInput(clientId, seq)) {
      return {};
    }

    // Write input to PTY. Direct write is synchronous; writeViaMux
    // (tmux send-keys) is fire-and-forget to avoid blocking the HTTP response.
    if (useMux) {
      // Fire-and-forget: don't block HTTP response on tmux child process.
      // Fallback to direct write on failure.
      session
        .writeViaMux(inputStr)
        .then((ok) => {
          if (!ok) {
            console.warn(`[Server] writeViaMux failed for session ${id}, falling back to direct write`);
            session.write(inputStr);
          }
        })
        .catch(() => {
          session.write(inputStr);
        });
    } else {
      session.write(inputStr);
    }
    return {};
  });

  // ========== 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 0x0a (line feed) which Claude Code's
  // Ink input recognizes as "insert newline" vs 0x0d (carriage return = submit).

  app.post('/api/sessions/:id/send-key', async (req) => {
    const { id } = req.params as { id: string };
    const body = req.body as Record<string, unknown>;
    const key = typeof body?.key === 'string' ? body.key : '';

    // Map key names to hex byte sequences
    const KEY_HEX_MAP: Record<string, string[]> = {
      'S-Enter': ['0a'], // \n (line feed)
      'C-Enter': ['0a'], // \n (line feed)
    };
    const hex = KEY_HEX_MAP[key];
    if (!hex) {
      return createErrorResponse(ApiErrorCode.INVALID_INPUT, `Key not allowed: ${key}`);
    }

    const session = findSessionOrFail(ctx, id);
    const muxName = session.muxName;
    if (!muxName) {
      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'No tmux session');
    }

    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 new Promise<void>((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) {
      console.error('[Server] send-key failed:', err);
      return createErrorResponse(ApiErrorCode.INTERNAL_ERROR, 'tmux send-keys failed');
    }
    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);

    session.resize(cols, rows, { viewportType, force });
    return {};
  });

  // ========== Get Last Response (from transcript JSONL) ==========

  // Resolves the most recent Claude conversation id for a session's cwd by
  // tailing ~/.claude/history.jsonl. After `/clear`, Claude Code keeps writing
  // to a new <uuid>.jsonl; 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).
  //
  // Entries from OTHER Codeman sessions in the same cwd are filtered out by
  // their known claudeSessionIds so concurrent tabs don't shadow each other,
  // as long as each has had its id resolved at least once.
  async function resolveActiveClaudeSessionIdFromHistory(
    session: Session,
    projectsDir: string
  ): Promise<string | null> {
    const historyPath = join(homedir(), '.claude', 'history.jsonl');
    const otherClaudeIds = new Set<string>();
    for (const s of ctx.sessions.values()) {
      if (s.id !== session.id && s.workingDir === session.workingDir && s.claudeSessionId) {
        otherClaudeIds.add(s.claudeSessionId);
      }
    }

    let candidateSid: string | null = null;
    try {
      const content = await fs.readFile(historyPath, 'utf8');
      const lines = content.split('\n');
      for (let i = lines.length - 1; i >= 0; i--) {
        const line = lines[i];
        if (!line) continue;
        try {
          const entry = JSON.parse(line) as { project?: string; sessionId?: string };
          if (
            entry.project === session.workingDir &&
            typeof entry.sessionId === 'string' &&
            !otherClaudeIds.has(entry.sessionId)
          ) {
            candidateSid = entry.sessionId;
            break;
          }
        } catch {
          // Skip unparseable lines
        }
      }
    } catch {
      return null;
    }
    if (!candidateSid || candidateSid === session.id) return candidateSid;

    // Safety: only adopt if the candidate's jsonl is more recently written
    // than our initial conversation's jsonl. Blocks stale ids inherited from
    // a prior Codeman session that happened to share this cwd.
    try {
      const projectDirs = await fs.readdir(projectsDir);
      let candidateMtime = 0;
      let initialMtime = 0;
      for (const projDir of projectDirs) {
        try {
          const cs = await fs.stat(join(projectsDir, projDir, `${candidateSid}.jsonl`));
          if (cs.mtimeMs > candidateMtime) candidateMtime = cs.mtimeMs;
        } catch {
          /* not in this dir */
        }
        try {
          const is = await fs.stat(join(projectsDir, projDir, `${session.id}.jsonl`));
          if (is.mtimeMs > initialMtime) initialMtime = is.mtimeMs;
        } catch {
          /* not in this dir */
        }
      }
      if (candidateMtime === 0) return null;
      if (initialMtime > 0 && candidateMtime <= initialMtime) return null;
    } catch {
      return null;
    }
    return candidateSid;
  }

  app.get('/api/sessions/:id/last-response', async (req) => {
    const { id } = req.params as { id: string };
    const session = findSessionOrFail(ctx, id);

    // 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 (session.mode === 'codex') {
      const codexQuery = req.query as { context?: string };
      return await readCodexLastResponse(session, codexQuery.context === 'full');
    }

    // 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);
    }

    // The Claude conversation ID (used as JSONL filename)
    const claudeSessionId = session.claudeSessionId || session.id;
    let transcriptText = '';
    let transcriptTimestamp = '';

    try {
      const projectDirs = await fs.readdir(projectsDir);
      for (const projDir of projectDirs) {
        const jsonlPath = join(projectsDir, projDir, `${claudeSessionId}.jsonl`);
        try {
          const content = await fs.readFile(jsonlPath, 'utf8');
          const lines = content.trim().split('\n');

          // Search from end for last assistant message with text
          for (let i = lines.length - 1; i >= 0; i--) {
            try {
              const entry = JSON.parse(lines[i]);
              if (entry.type === 'assistant' && entry.message?.content) {
                const blocks = Array.isArray(entry.message.content)
                  ? entry.message.content
                  : [{ type: 'text', text: String(entry.message.content) }];
                const textBlocks = blocks
                  .filter((b: { type: string; text?: string }) => b.type === 'text' && b.text)
                  .map((b: { type: string; text?: string }) => b.text);
                if (textBlocks.length > 0) {
                  transcriptText = textBlocks.join('\n\n');
                  transcriptTimestamp = entry.timestamp || '';
                  break;
                }
              }
            } catch {
              // Skip unparseable lines
            }
          }
          if (transcriptText) break; // Found it, stop scanning directories
        } catch {
          // File doesn't exist in this project dir, continue
        }
      }
    } catch {
      // projects dir doesn't exist
    }

    // If ?context=full, return all user+assistant messages for conversation view
    const query = req.query as { context?: string };
    if (query.context === 'full' && transcriptText) {
      const allMessages: Array<{ role: string; text: string; timestamp?: string }> = [];
      try {
        const projectDirs = await fs.readdir(projectsDir);
        for (const projDir of projectDirs) {
          const jsonlPath = join(projectsDir, projDir, `${claudeSessionId}.jsonl`);
          try {
            const content = await fs.readFile(jsonlPath, 'utf8');
            const lines = content.trim().split('\n');
            for (const line of lines) {
              try {
                const entry = JSON.parse(line);
                if (entry.type === 'user' && entry.message?.content) {
                  const text =
                    typeof entry.message.content === 'string'
                      ? entry.message.content
                      : (entry.message.content as Array<{ type: string; text?: string }>)
                          .filter((b) => b.type === 'text' && b.text)
                          .map((b) => b.text)
                          .join('\n');
                  // Skip system/command messages
                  if (text && !text.startsWith('<local-command') && !text.startsWith('<command-name>')) {
                    allMessages.push({ role: 'user', text, timestamp: entry.timestamp });
                  }
                } else if (entry.type === 'assistant' && entry.message?.content) {
                  const blocks = Array.isArray(entry.message.content)
                    ? entry.message.content
                    : [{ type: 'text', text: String(entry.message.content) }];
                  const text = blocks
                    .filter((b: { type: string; text?: string }) => b.type === 'text' && b.text)
                    .map((b: { type: string; text?: string }) => b.text)
                    .join('\n\n');
                  if (text) {
                    allMessages.push({ role: 'assistant', text, timestamp: entry.timestamp });
                  }
                }
              } catch {
                /* skip */
              }
            }
            if (allMessages.length > 0) break;
          } catch {
            /* continue */
          }
        }
      } catch {
        /* ignore */
      }
      return { text: transcriptText, timestamp: transcriptTimestamp, messages: allMessages };
    }

    return {
      text: transcriptText,
      timestamp: transcriptTimestamp,
    };
  });

  function isCodexInjectedContext(text: string): boolean {
    return (
      /^# AGENTS\.md instructions\b/i.test(text) ||
      /^<environment_context\b/i.test(text) ||
      /^<turn_aborted\b/i.test(text) ||
      /^<codex_internal_context\b/i.test(text) ||
      /^<recommended_plugins\b/i.test(text) ||
      /^<user_instructions\b/i.test(text) ||
      /^# Options\b/i.test(text)
    );
  }

  // ── Codex response-viewer support ───────────────────────────────────────────────────────
  // Read the rollout's session_meta identity fields (plus turn_context cwd as
  // a fallback when the huge session_meta line got truncated by the head read).
  function readCodexRolloutMeta(head: string): { cwd?: string; originator?: string } {
    let cwd: string | undefined;
    let originator: string | undefined;
    for (const line of head.split('\n')) {
      if (!line) continue;
      try {
        const entry = JSON.parse(line) as {
          type?: string;
          payload?: { cwd?: string; originator?: string };
        };
        if (entry.type === 'session_meta') {
          cwd ??= entry.payload?.cwd;
          originator ??= entry.payload?.originator;
        } else if (entry.type === 'turn_context') {
          cwd ??= entry.payload?.cwd;
        }
      } catch {
        // Malformed or truncated head line — keep scanning.
      }
      if (cwd && originator) break;
    }
    return { cwd, originator };
  }

  // The pane's last Enter (Session.codexLastSubmitAt) correlated against
  // ~/.codex/history.jsonl, which logs every submitted user message as
  // {session_id, ts}. This identifies the thread the pane is ACTUALLY on and
  // is the only signal that survives /resume, /new and /fork typed inside the
  // codex TUI itself. An entry is credited to this pane only when its Enter is
  // the closest among all codex panes, so a menu keystroke in another pane
  // can't steal the attribution.
  const codexHistoryPinCache = new LRUMap<string, { submitAt: number; threadId: string }>({ maxSize: 1024 });
  async function resolveCodexThreadFromHistory(
    session: { id: string; codexLastSubmitAt?: number },
    codexHome: string
  ): Promise<string | null> {
    const submitAt = session.codexLastSubmitAt || 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 && s.mode === 'codex' && s.codexLastSubmitAt) {
        otherSubmits.push(s.codexLastSubmitAt);
      }
    }

    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_<sessionId>, 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;
    codexLastSubmitAt?: number;
    codexConfig?: { resumeSessionId?: string };
  }): Promise<string | null> {
    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<void> => {
      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<string, { cwd?: string; originator?: string }>({ 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<string, number>();

    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=<bytes> - Only return last N bytes (faster initial load)
  //   full=1       - Full page reload: replay the entire tmux scrollback (COD-47)
  app.get('/api/sessions/:id/terminal', async (req) => {
    const { id } = req.params as { id: string };
    const query = req.query as { tail?: string; full?: string };
    const session = findSessionOrFail(ctx, id);

    // `full=1` is the EXPLICIT full-reload signal (COD-47): the browser reloaded
    // the page and wants the whole scroll history back, so we capture the ENTIRE
    // tmux scrollback and the user gets back history that scrolled off Codeman's
    // byte buffer. Requests WITHOUT it — tab switches (`tail=`) and the legacy
    // no-param callers (response-viewer fallback, clearTerminal refresh) — keep
    // the fast visible-frame capture.
    const tailBytes = query.tail ? parseInt(query.tail, 10) : 0;
    const 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 liveMuxBuffer =
      muxName && typeof ctx.mux.captureActivePaneBuffer === 'function'
        ? ctx.mux.captureActivePaneBuffer(
            muxName,
            isFullReload
              ? { fullHistory: true, historyLimitLines: tmuxHistoryLimit, maxCaptureBytes: terminalBufferMaxBytes }
              : undefined
          )
        : null;
    const hasLiveMuxBuffer = liveMuxBuffer !== null && liveMuxBuffer.length > 0;
    const source: 'history' | 'mux-visible' | 'mux-full-history' = hasLiveMuxBuffer
      ? isFullReload
        ? 'mux-full-history'
        : 'mux-visible'
      : 'history';
    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;
    let cleanBuffer: string;

    // 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;
      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.
    let strippedBuffer = session.mode === 'shell' ? rawBuffer : stripInkRedrawBloat(rawBuffer);

    // Strip alt-screen toggles and scrollback-erase from Codex/Claude byte
    // streams. xterm.js obeys them by switching to its scrollback-less alt
    // buffer and wiping saved lines, so conversation history disappears on tab
    // switch. Same gate as the live-stream strip in session.ts.
    if (isAltScreenStripMode(session.mode)) {
      strippedBuffer = strippedBuffer
        .replace(ALT_SCREEN_TOGGLE_PATTERN, '')
        .replace(ERASE_SCROLLBACK_PATTERN, '')
        .replace(MOUSE_TRACKING_PATTERN, '');
    }

    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;
      // 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")
      const claudeMatch = 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)
    cleanBuffer = cleanBuffer.replace(CTRL_L_PATTERN, '').replace(LEADING_WHITESPACE_PATTERN, '');

    return {
      terminalBuffer: cleanBuffer,
      status: session.status,
      fullSize,
      truncated,
      source,
    };
  });

  // ═══════════════════════════════════════════════════════════════
  // 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);

    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);

    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,
        },
      },
    };
  });

  // ========== 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);

    session.setAutoResume(body.enabled);
    persistAndBroadcastSession(ctx, session);

    return {
      success: true,
      data: {
        autoResume: {
          enabled: session.autoResumeEnabled,
          resumeAt: session.autoResumeAt ?? undefined,
        },
      },
    };
  });

  // ========== 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);

    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);

    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) => {
    // Prevent unbounded session creation
    if (ctx.sessions.size >= MAX_CONCURRENT_SESSIONS) {
      return createErrorResponse(
        ApiErrorCode.SESSION_BUSY,
        `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached`
      );
    }

    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();

    // 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');
      }
    }

    const session = new Session({ workingDir: dir, envOverrides: runEnvOverrides });
    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) => {
    // Prevent unbounded session creation
    if (ctx.sessions.size >= MAX_CONCURRENT_SESSIONS) {
      return createErrorResponse(
        ApiErrorCode.SESSION_BUSY,
        `Maximum concurrent sessions (${MAX_CONCURRENT_SESSIONS}) reached.`
      );
    }

    const {
      caseName = 'testcase',
      mode = 'claude',
      openCodeConfig,
      codexConfig,
      geminiConfig,
      envOverrides,
      effort,
    } = parseBody(QuickStartSchema, req.body);

    // 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 casePath: string | null = null;
    const remoteCases = await readRemoteCases(CODEMAN_CONFIG_DIR);
    const remoteCase = remoteCases.find((item) => item.name === caseName);
    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/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 ||
        codexConfig ||
        geminiConfig ||
        openCodeConfig
      ) {
        return createErrorResponse(
          ApiErrorCode.INVALID_INPUT,
          'envOverrides, effort, and per-CLI config are not supported for remote cases (they do not cross ssh). Configure the remote command via the host command override instead.'
        );
      }

      // 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) {
        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, tmuxCheck.error || 'remote host is missing tmux');
      }

      casePath = remoteCase.remotePath;
      remote = toSessionRemote(host, remoteCase);
    } else {
      // Check OpenCode availability if requested
      if (mode === 'opencode') {
        const { isOpenCodeAvailable } = await import('../../utils/opencode-cli-resolver.js');
        if (!isOpenCodeAvailable()) {
          return createErrorResponse(
            ApiErrorCode.OPERATION_FAILED,
            'OpenCode CLI not found. Install with: curl -fsSL https://opencode.ai/install | bash'
          );
        }
      }

      // Check Codex availability if requested
      if (mode === 'codex') {
        const { isCodexAvailable } = await import('../../utils/codex-cli-resolver.js');
        if (!isCodexAvailable()) {
          return createErrorResponse(
            ApiErrorCode.OPERATION_FAILED,
            'Codex CLI not found. Install with: npm install -g @openai/codex'
          );
        }
      }

      // Check Gemini availability if requested
      if (mode === 'gemini') {
        const { isGeminiAvailable } = await import('../../utils/gemini-cli-resolver.js');
        if (!isGeminiAvailable()) {
          return createErrorResponse(
            ApiErrorCode.OPERATION_FAILED,
            'Gemini CLI not found. Install with: npm install -g @google/gemini-cli'
          );
        }
      }

      // 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<string, string> = {};
      try {
        const raw = await fs.readFile(LINKED_CASES_FILE, 'utf-8');
        linkedCases = JSON.parse(raw);
      } catch {
        // File missing or unparseable — treat as empty registry
      }
      casePath = linkedCases[caseName] || validatePathWithinBase(caseName, CASES_DIR);
      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;

    // Create case folder and CLAUDE.md if it doesn't exist (only for non-linked, non-remote cases)
    if (!remote && !existsSync(resolvedCasePath)) {
      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, and Gemini use their own systems)
        if (mode !== 'opencode' && mode !== 'codex' && mode !== 'gemini') {
          await writeHooksConfig(resolvedCasePath);
        }

        ctx.broadcast(SseEvent.CaseCreated, { name: caseName, path: resolvedCasePath });
      } catch (err) {
        return createErrorResponse(ApiErrorCode.OPERATION_FAILED, `Failed to create case: ${getErrorMessage(err)}`);
      }
    } else if (!remote && mode !== 'opencode') {
      // COD-91 self-heal for an EXISTING case: refresh a pre-secret hooks block so the
      // now-unconditional hook-secret gate keeps accepting its hook events. No-op when
      // the hooks aren't ours or already carry the secret. Skipped for remote cases —
      // resolvedCasePath is a REMOTE path that doesn't exist on the local filesystem.
      await refreshStaleHookSecret(resolvedCasePath).catch(() => {});
    }

    // Strip stale disk entries for keys this request is actively setting (Claude only —
    // see POST /api/sessions for full rationale).
    if (
      mode !== 'opencode' &&
      mode !== 'codex' &&
      mode !== 'gemini' &&
      !remote &&
      envOverrides &&
      Object.keys(envOverrides).length > 0
    ) {
      await stripCaseEnvKeys(resolvedCasePath, 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();
    const qsModel =
      mode === 'opencode'
        ? openCodeConfig?.model
        : mode === 'codex'
          ? codexConfig?.model
          : mode === 'gemini'
            ? geminiConfig?.model
            : mode !== 'shell'
              ? qsModelConfig?.defaultModel || undefined
              : undefined;
    const qsClaudeModeConfig = await ctx.getClaudeModeConfig();
    const qsTerminalHistoryConfig = await ctx.getTerminalHistoryConfig();
    const session = new Session({
      workingDir: resolvedCasePath,
      mux: ctx.mux,
      useMux: true,
      mode: mode,
      niceConfig: niceConfig,
      model: qsModel,
      claudeMode: qsClaudeModeConfig.claudeMode,
      allowedTools: qsClaudeModeConfig.allowedTools,
      openCodeConfig: mode === 'opencode' ? openCodeConfig : undefined,
      codexConfig: mode === 'codex' ? codexConfig : undefined,
      geminiConfig: mode === 'gemini' ? geminiConfig : undefined,
      envOverrides,
      effort,
      remote,
      tmuxHistoryLimit: qsTerminalHistoryConfig.tmuxHistoryLimit,
    });

    // Auto-detect completion phrase from CLAUDE.md BEFORE broadcasting
    // so the initial state already has the phrase configured (only if globally enabled)
    if (mode === 'claude' && !remote && ctx.store.getConfig().ralphEnabled) {
      autoConfigureRalph(session, resolvedCasePath, ctx);
      if (!session.ralphTracker.enabled) {
        session.ralphTracker.enable();
        session.ralphTracker.enableAutoEnable(); // Allow re-enabling on restart
      }
    }

    ctx.addSession(session);
    ctx.store.incrementSessionsCreated();
    ctx.persistSessionState(session);
    await ctx.setupSessionListeners(session);
    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 (mode === '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 {
        // 'claude', 'opencode', 'codex', and 'gemini' modes use 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) });

      // Save lastUsedCase to settings for TUI/web sync
      try {
        const settingsFilePath = SETTINGS_PATH;
        let settings: Record<string, unknown> = {};
        try {
          settings = JSON.parse(await fs.readFile(settingsFilePath, 'utf-8'));
        } catch (err) {
          if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
        }
        settings.lastUsedCase = caseName;
        const dir = dirname(settingsFilePath);
        if (!existsSync(dir)) {
          mkdirSync(dir, { recursive: true });
        }
        // Use async write to avoid blocking event loop
        fs.writeFile(settingsFilePath, JSON.stringify(settings, null, 2)).catch((err) => {
          // Non-critical but log for debugging
          console.warn('[Server] Failed to save settings (lastUsedCase):', err);
        });
      } catch (err) {
        // Non-critical but log for debugging
        console.warn('[Server] Failed to prepare settings update:', err);
      }

      return {
        sessionId: session.id,
        casePath: resolvedCasePath,
        caseName,
      };
    } 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;
  }

  /**
   * 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<string> {
    const encoded = projKey.startsWith('-') ? projKey.slice(1) : projKey;
    const segments = encoded.split('-');

    const isDirCache = new Map<string, boolean>();
    const isDir = async (p: string): Promise<boolean> => {
      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<string | null> {
      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) {
          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;
          }
        }
      }
      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) {
          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) {
        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 16KB of a file for content sniffing. */
  async function readFileHead(path: string, buf: Buffer): Promise<string | null> {
    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<string | null> {
    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;
  };

  // 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, headBuf: Buffer): Promise<HistorySession[]> {
    const out: HistorySession[] = [];
    const stat = await fs.stat(projPath).catch(() => null);
    if (!stat?.isDirectory()) return out;

    const workingDir = await decodeProjectKey(projDir);
    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;

      let firstPrompt: string | undefined;
      const head = await readFileHead(filePath, headBuf);
      const hasConversation = (text: string) =>
        text.includes('"type":"user"') || text.includes('"type":"assistant"') || text.includes('"type":"summary"');

      let foundContent = head ? hasConversation(head) : false;
      let tail: string | null = null;
      if (!foundContent && fileStat.size > 16384) {
        const tailBuf = Buffer.alloc(32768);
        tail = await readFileTail(filePath, tailBuf, fileStat.size);
        if (tail) foundContent = hasConversation(tail);
      }
      if (!foundContent) continue;

      if (head) firstPrompt = extractFirstUserPrompt(head);
      if (!firstPrompt && fileStat.size > 65536) {
        if (!tail) {
          const tailBuf = Buffer.alloc(32768);
          tail = await readFileTail(filePath, tailBuf, fileStat.size);
        }
        if (tail) firstPrompt = extractFirstUserPrompt(tail);
      }

      out.push({
        sessionId,
        workingDir,
        projectKey: projDir,
        sizeBytes: fileStat.size,
        lastModified: fileStat.mtime.toISOString(),
        firstPrompt,
      });
    }
    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');
    const headBuf = Buffer.alloc(16384);

    // 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);
      const all = await scanProjectDir(projPath, query.projectKey, headBuf);
      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.
    const 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, headBuf);
        results.push(...list);
      }
    } catch {
      // Projects dir may not exist
    }

    results.sort((a, b) => new Date(b.lastModified).getTime() - new Date(a.lastModified).getTime());
    return { sessions: results.slice(0, 50) };
  });

  // 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 };
    }

    // 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,
      };
    });

    // 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.
    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,
    }));

    // 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');
      const headBuf = Buffer.alloc(16384);
      const projectDirs = await fs.readdir(projectsDir);
      for (const projDir of projectDirs) {
        const projPath = join(projectsDir, projDir);
        const list = await scanProjectDir(projPath, projDir, headBuf);
        for (const h of list) {
          history.push({
            sessionId: h.sessionId,
            workingDir: h.workingDir,
            sizeBytes: h.sizeBytes,
            lastModified: h.lastModified,
            firstPrompt: h.firstPrompt,
            projectKey: h.projectKey,
          });
        }
      }
    } catch {
      // Projects dir may not exist.
    }

    // Mux process stats (best-effort; guard against mocks lacking the method).
    let mux: MuxStatInput[] = [];
    try {
      const getStats = (ctx.mux as { getSessionsWithStats?: () => Promise<unknown[]> }).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.
    }

    const merged = mergeUnifiedSessions({ live, persisted, lifecycle, history, mux });
    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']);
  // The per-file size cap (MAX_PASTE_IMAGE_BYTES) is enforced by @fastify/multipart (registered in server.ts).

  app.post('/api/sessions/:id/paste-image', async (req, reply) => {
    // CSRF defense: state-changing routes must come from same origin.
    // Cookies are SameSite=lax, multipart/form-data is a "simple" CORS request
    // (no preflight), so a cross-origin <form enctype="multipart/form-data">
    // 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 };

    // Rate limit per (IP, sessionId): 30/min. Defends against disk-fill DoS
    // — even an authenticated attacker can otherwise loop large image POSTs.
    if (!consumePasteToken(`${req.ip}:${id}`)) {
      reply.code(429);
      reply.header('Retry-After', '60');
      return createErrorResponse(ApiErrorCode.INVALID_INPUT, 'Rate limit exceeded (30 uploads/min per session)');
    }

    const session = findSessionOrFail(ctx, id);

    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.
    let part: import('@fastify/multipart').MultipartFile | undefined;
    try {
      part = await req.file();
    } 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"`);
    }
    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');
    }

    // Determine extension from filename or Content-Type.
    let ext = '.png';
    if (part.filename) {
      const origExt = extname(part.filename).toLowerCase();
      if (ALLOWED_IMAGE_EXTS.has(origExt)) ext = origExt;
    }
    const mimeMatch = (part.mimetype || '').toLowerCase().match(/^image\/(png|jpeg|jpg|webp|gif|bmp|heic|heif)$/);
    if (mimeMatch) {
      const map: Record<string, string> = {
        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)) {
      // 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}`);
    }

    // Save to {workingDir}/.claude-images/
    // Refuse symlinks at imageDir — an agent or postinstall script could plant
    // `.claude-images -> ~/.ssh/` and redirect future writes outside workingDir.
    // We lstat (not stat) so we see the symlink itself. Use mkdir without
    // `recursive` so the leaf creation does not follow a symlink either, and
    // O_EXCL|O_NOFOLLOW on the file open so the write itself is symlink-safe.
    const imageDir = join(session.workingDir, '.claude-images');
    try {
      const dirStat = await fs.lstat(imageDir);
      if (dirStat.isSymbolicLink() || !dirStat.isDirectory()) {
        reply.code(403);
        return createErrorResponse(ApiErrorCode.INVALID_INPUT, '.claude-images is not a regular directory');
      }
    } catch (err: unknown) {
      if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err;
      // Non-recursive mkdir: does not follow symlinks for the leaf.
      // session.workingDir is guaranteed to exist (live session).
      try {
        await fs.mkdir(imageDir);
      } catch (mkErr: unknown) {
        // Concurrent uploads (a batch of photos) race to create .claude-images —
        // the losers get EEXIST. Treat an already-present REAL directory as
        // success, but re-verify it isn't a symlink a racing actor planted
        // (preserve the symlink-safety guarantee above).
        if ((mkErr as NodeJS.ErrnoException).code !== 'EEXIST') throw mkErr;
        const raceStat = await fs.lstat(imageDir);
        if (raceStat.isSymbolicLink() || !raceStat.isDirectory()) {
          reply.code(403);
          return createErrorResponse(ApiErrorCode.INVALID_INPUT, '.claude-images is not a regular directory');
        }
      }
    }
    // Date.now() collides on same-ms uploads from two tabs (last-write wins
    // silently). Append 8 hex chars so concurrent pastes get distinct names.
    const filename = `paste-${Date.now()}-${randomBytes(4).toString('hex')}${ext}`;
    const filepath = join(imageDir, filename);
    // O_EXCL: refuse to overwrite (collision is impossible with random suffix,
    // but defends against TOCTOU). O_NOFOLLOW: refuse if filepath is a symlink.
    const fh = await fs.open(
      filepath,
      fs.constants.O_WRONLY | fs.constants.O_CREAT | fs.constants.O_EXCL | fs.constants.O_NOFOLLOW
    );
    try {
      await fh.writeFile(imageBytes);
    } finally {
      await fh.close();
    }

    return { path: filepath, filename };
  });
}