server.js

#!/usr/bin/env node
'use strict';

// Claude Control Center — backend server.
//
// Part 1: security skeleton — localhost bind, Host check, per-launch token
// auth on /api/*, whitelisted static files.
// Part 2: session index — transcript scanner, live-session poller, status
// derivation, GET /api/sessions[/:id].
// Part 3: tmux controller — mapPanes (PPID walk), capturePane, sendPrompt,
// sendKeys (whitelist), launchSession, killPane. No HTTP routes yet (Part 6).
// Part 4: JSONL tailer (byte offsets + partial-line buffers), directory
// watchers with a 2s safety pump, SSE hub (GET /api/events), and the
// transcript seed route (GET /api/sessions/:id/transcript).
// Part 5: aux endpoints (GET /api/sessions/:id/tasks, /api/stats,
// /api/projects) and macOS notifications on busy -> ready|idle.
// Part 6: control endpoints — POST prompt/keys/kill/new/watch wired to the
// tmux controller (incl. resume-into-new-tmux-session for done sessions),
// the launch overlay that bridges the post-launch adoption gap, and the
// watched-pane mirror loop feeding `pane` SSE events.
//
// Stdlib only. This file never writes anything under ~/.claude.

const http = require('http');
const fs = require('fs');
const fsp = fs.promises;
const path = require('path');
const crypto = require('crypto');
const os = require('os');
const { execFile } = require('child_process');

// ---------------------------------------------------------------------------
// Config
// ---------------------------------------------------------------------------

const DEFAULT_PORT = 7777;
const PORT = (() => {
  const raw = process.env.CCC_PORT;
  if (typeof raw !== 'string' || !/^\d+$/.test(raw)) return DEFAULT_PORT;
  const n = Number.parseInt(raw, 10);
  return n >= 1 && n <= 65535 ? n : DEFAULT_PORT;
})();

// Per-launch token; never persisted. Gates every /api/* route.
const TOKEN = crypto.randomBytes(32).toString('hex');
const TOKEN_BUF = Buffer.from(TOKEN, 'utf8');

const PUBLIC_DIR = path.join(__dirname, 'public');

// Read-only data sources under ~/.claude. CCC_CLAUDE_DIR exists ONLY so smoke
// tests can point at a throwaway fixture tree (the dead-PID path cannot be
// exercised against the real ~/.claude without writing to it, which is
// forbidden — this server never writes anything under CLAUDE_DIR).
const CLAUDE_DIR = process.env.CCC_CLAUDE_DIR || path.join(os.homedir(), '.claude');
const PROJECTS_DIR = path.join(CLAUDE_DIR, 'projects');
const SESSIONS_DIR = path.join(CLAUDE_DIR, 'sessions');
const TASKS_DIR = path.join(CLAUDE_DIR, 'tasks');
// ~/.claude.json holds secrets. It is read-only input and ONLY its .projects
// key set is ever consumed (see readProjectKeys). CCC_CLAUDE_JSON mirrors the
// CCC_CLAUDE_DIR fixture override for smoke tests.
const CLAUDE_JSON_PATH = process.env.CCC_CLAUDE_JSON || path.join(os.homedir(), '.claude.json');
const LIVE_SCAN_INTERVAL_MS = 2000;

// The ONLY paths ever served as static files. Lookup is an exact-string match
// on the WHATWG-normalized url.pathname, and the map values are fixed
// filenames — request input is never joined into a filesystem path, so
// traversal to non-whitelisted files is structurally impossible.
const STATIC_WHITELIST = {
  '/':          { file: 'index.html', type: 'text/html; charset=utf-8' },
  '/app.js':    { file: 'app.js',     type: 'text/javascript; charset=utf-8' },
  '/style.css': { file: 'style.css',  type: 'text/css; charset=utf-8' },
};

// ---------------------------------------------------------------------------
// Security helpers
// ---------------------------------------------------------------------------

// Accept only `localhost` or `127.0.0.1`, optionally with a `:<digits>` port
// suffix. We bind 127.0.0.1, so `[::1]` cannot legitimately appear; anything
// else (other IPs, DNS names, IPv6 forms) is rejected.
function isAllowedHost(hostHeader) {
  if (typeof hostHeader !== 'string' || hostHeader === '') return false;
  const host = hostHeader.replace(/:\d+$/, '');
  return host.toLowerCase() === 'localhost' || host === '127.0.0.1';
}

// Constant-time token comparison. Candidate comes from the X-CCC-Token header
// or the ?token= query param (the latter is needed for EventSource later).
function checkToken(req, url) {
  let candidate = req.headers['x-ccc-token'];
  if (candidate === undefined) candidate = url.searchParams.get('token');
  if (typeof candidate !== 'string') return false; // array header / absent
  const candidateBuf = Buffer.from(candidate, 'utf8');
  if (candidateBuf.length !== TOKEN_BUF.length) return false;
  return crypto.timingSafeEqual(candidateBuf, TOKEN_BUF);
}

// ---------------------------------------------------------------------------
// Response helpers
// ---------------------------------------------------------------------------

// Applied to every response, success and error alike. The launch URL carries
// the token in its query string, so suppressing referrers is cheap insurance.
function baseHeaders() {
  return {
    'X-Content-Type-Options': 'nosniff',
    'Referrer-Policy': 'no-referrer',
  };
}

function sendJson(res, status, obj) {
  const body = JSON.stringify(obj);
  res.writeHead(status, {
    ...baseHeaders(),
    'Content-Type': 'application/json; charset=utf-8',
    'Cache-Control': 'no-store',
    'Content-Length': Buffer.byteLength(body),
  });
  res.end(body);
}

function serveStatic(req, res, pathname) {
  if (req.method !== 'GET' && req.method !== 'HEAD') {
    res.writeHead(405, {
      ...baseHeaders(),
      'Allow': 'GET, HEAD',
      'Content-Type': 'application/json; charset=utf-8',
      'Cache-Control': 'no-store',
    });
    res.end(JSON.stringify({ error: 'method not allowed' }));
    return;
  }
  const entry = STATIC_WHITELIST[pathname];
  if (!entry) {
    sendJson(res, 404, { error: 'not found' });
    return;
  }
  fs.readFile(path.join(PUBLIC_DIR, entry.file), (err, data) => {
    if (err) {
      sendJson(res, 404, { error: 'not found' });
      return;
    }
    res.writeHead(200, {
      ...baseHeaders(),
      'Content-Type': entry.type,
      'Cache-Control': 'no-store',
      'Content-Length': data.length,
    });
    if (req.method === 'HEAD') res.end();
    else res.end(data);
  });
}

// ---------------------------------------------------------------------------
// Session index
// ---------------------------------------------------------------------------
//
// Sources (all read-only):
//   PROJECTS_DIR/<encoded-cwd>/<sessionId>.jsonl  — transcripts (depth-2 only;
//     deeper paths are subagent transcripts and are excluded). Encoded dir
//     names are lossy and are NEVER decoded — real cwd comes from JSONL
//     content or the live session file.
//   SESSIONS_DIR/<pid>.json — live session status files. Stale files for dead
//     PIDs are ignored, never deleted or modified.
//   TASKS_DIR/<sessionId>/<n>.json — task lists.

// Single source of truth for what a sessionId may look like. Enforced when
// ids are admitted to the index (from transcript filenames and live session
// files), re-checked in getTasks before any path.join, and reused by the
// /api/sessions/:id route pattern — so nothing path-unsafe (e.g. "..") can
// ever become an index key or reach the filesystem.
const SESSION_ID_PATTERN = '[A-Za-z0-9-]{1,128}';
const SESSION_ID_RE = new RegExp(`^${SESSION_ID_PATTERN}$`);

const transcriptCache = new Map(); // path -> { mtimeMs, size, summary }
let transcriptBySession = new Map(); // sessionId -> summary (deduped, deterministic)
const sessionIndex = new Map(); // sessionId -> record (exported; cleared in place)
let liveBySession = new Map(); // sessionId -> { pid, status, cwd, name, startedAt, updatedAt }

const warnedOnce = new Set();
function warnOnce(key, message) {
  if (warnedOnce.has(key)) return;
  warnedOnce.add(key);
  console.warn(`ccc: ${message}`);
}

function safeJsonParse(str) {
  try {
    return JSON.parse(str);
  } catch (err) {
    return null;
  }
}

// Null-safe timestamp math: non-finite/null operands are ignored; returns
// null only when both are absent. Every place timestamps merge goes through
// these so NaN can never reach a record or the sort comparator.
function maxTs(a, b) {
  const av = Number.isFinite(a) ? a : null;
  const bv = Number.isFinite(b) ? b : null;
  if (av === null) return bv;
  if (bv === null) return av;
  return av > bv ? av : bv;
}

function minTs(a, b) {
  const av = Number.isFinite(a) ? a : null;
  const bv = Number.isFinite(b) ? b : null;
  if (av === null) return bv;
  if (bv === null) return av;
  return av < bv ? av : bv;
}

function toTs(value) {
  return Number.isFinite(value) ? value : null;
}

function toCount(value) {
  return Number.isFinite(value) ? value : 0;
}

// Local-calendar-day key ("YYYY-MM-DD") for per-day stats buckets. Buckets
// are keyed by absolute day, not a "today"-relative window, so a cached
// summary parsed yesterday is still correct after midnight (a file not
// modified today cannot contain entries timestamped today).
function dayKey(tsMs) {
  const d = new Date(tsMs);
  const pad = (n) => String(n).padStart(2, '0');
  return `${d.getFullYear()}-${pad(d.getMonth() + 1)}-${pad(d.getDate())}`;
}

// Get-or-create the summary's per-day bucket for a (finite) timestamp.
function dayBucket(summary, tsMs) {
  const key = dayKey(tsMs);
  let bucket = summary.byDay[key];
  if (!bucket) {
    // byModel keys come from JSONL message.model strings — null prototype
    // guards against __proto__/constructor key collisions.
    bucket = { msgs: 0, byModel: Object.create(null) };
    summary.byDay[key] = bucket;
  }
  return bucket;
}

// Reduce one parsed transcript entry into the running summary. One assistant
// API message spans multiple jsonl lines sharing message.id, each carrying
// identical usage — msgCount and tokens MUST dedupe by message.id or they
// overcount up to 7x (verified). isSidechain exclusion applies to counts and
// tokens only. Per-day buckets are filled at exactly the two count sites, so
// they inherit the dedupe and sidechain/isMeta exclusions bit-for-bit;
// entries without a finite timestamp count toward cumulative totals but are
// not bucketed (excluded from per-day stats).
function reduceTranscriptEntry(summary, entry, seenAssistantIds) {
  if (typeof entry.cwd === 'string' && entry.cwd !== '') summary.cwd = entry.cwd;
  if (typeof entry.gitBranch === 'string' && entry.gitBranch !== '') summary.gitBranch = entry.gitBranch;
  if (typeof entry.slug === 'string' && entry.slug !== '') summary.slug = entry.slug;
  if (typeof entry.version === 'string' && entry.version !== '') summary.version = entry.version;

  let entryTs = null;
  if (typeof entry.timestamp === 'string') {
    const ts = Date.parse(entry.timestamp);
    if (Number.isFinite(ts)) {
      entryTs = ts;
      summary.firstTs = minTs(summary.firstTs, ts);
      summary.lastTs = maxTs(summary.lastTs, ts);
      summary.lastEntry = {
        type: typeof entry.type === 'string' ? entry.type : null,
        subtype: typeof entry.subtype === 'string' ? entry.subtype : null,
      };
    }
  }

  switch (entry.type) {
    case 'assistant': {
      const msg = entry.message && typeof entry.message === 'object' ? entry.message : null;
      if (msg && typeof msg.model === 'string' && msg.model !== '') summary.model = msg.model;
      if (entry.isSidechain === true) break;
      const id = msg && typeof msg.id === 'string' && msg.id !== '' ? msg.id : null;
      if (id !== null) {
        if (seenAssistantIds.has(id)) break; // later lines of the same message
        seenAssistantIds.add(id);
      }
      summary.msgCount += 1;
      const usage = msg && msg.usage && typeof msg.usage === 'object' ? msg.usage : null;
      if (usage) {
        summary.tokens.input += toCount(usage.input_tokens);
        summary.tokens.output += toCount(usage.output_tokens);
        summary.tokens.cacheRead += toCount(usage.cache_read_input_tokens);
        summary.tokens.cacheCreate += toCount(usage.cache_creation_input_tokens);
      }
      if (entryTs !== null) {
        const bucket = dayBucket(summary, entryTs);
        bucket.msgs += 1;
        if (usage) {
          // The message's OWN model, not summary.model — sessions switch models.
          const model = msg && typeof msg.model === 'string' && msg.model !== ''
            ? msg.model
            : 'unknown';
          let m = bucket.byModel[model];
          if (!m) {
            m = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
            bucket.byModel[model] = m;
          }
          m.input += toCount(usage.input_tokens);
          m.output += toCount(usage.output_tokens);
          m.cacheRead += toCount(usage.cache_read_input_tokens);
          m.cacheCreate += toCount(usage.cache_creation_input_tokens);
        }
      }
      break;
    }
    case 'user':
      if (entry.isSidechain !== true && entry.isMeta !== true) {
        summary.msgCount += 1;
        if (entryTs !== null) dayBucket(summary, entryTs).msgs += 1;
      }
      break;
    case 'ai-title':
      if (typeof entry.aiTitle === 'string' && entry.aiTitle !== '') summary.aiTitle = entry.aiTitle;
      break;
    case 'system':
      if (entry.subtype === 'away_summary' && typeof entry.content === 'string') {
        summary.awaySummary = entry.content;
      }
      break;
    default:
      break; // unknown entry types are fine — skip
  }
}

// Streamed line-by-line transcript parse (manual \n splitting; the stdlib
// whitelist does not include readline). The trailing partial line — present
// when the file is mid-append — is parsed if it is valid JSON, else dropped.
// Resolves null on stream errors (ENOENT race, EACCES); caller drops the file.
function parseTranscriptFile(filePath) {
  return new Promise((resolve) => {
    const summary = {
      path: filePath,
      sessionId: null, // set by the caller from the filename
      cwd: null,
      gitBranch: null,
      slug: null,
      version: null,
      model: null,
      aiTitle: null,
      awaySummary: null,
      firstTs: null,
      lastTs: null,
      msgCount: 0,
      tokens: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 },
      lastEntry: null, // { type, subtype } of the last entry with a timestamp
      // dayKey -> { msgs, byModel } (stats only; makeRecord copies explicit
      // fields, so byDay never reaches API records or SSE snapshots).
      byDay: Object.create(null),
    };
    const seenAssistantIds = new Set();
    const reduceLine = (line) => {
      if (line === '' || line.trim() === '') return;
      const entry = safeJsonParse(line);
      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return;
      reduceTranscriptEntry(summary, entry, seenAssistantIds);
    };

    let partial = '';
    const stream = fs.createReadStream(filePath, { encoding: 'utf8' });
    stream.on('data', (chunk) => {
      const pieces = (partial + chunk).split('\n');
      partial = pieces.pop();
      for (const piece of pieces) reduceLine(piece);
    });
    stream.on('end', () => {
      reduceLine(partial);
      resolve(summary);
    });
    stream.on('error', () => resolve(null));
  });
}

let transcriptScans = 0;

// Scan PROJECTS_DIR/*/*.jsonl (depth-2 regular files only). Unchanged files
// (matching mtimeMs+size) reuse the cached summary, so steady-state ticks are
// stat-only. After the cache pass, transcriptBySession is rebuilt with
// deterministic duplicate resolution: later lastTs wins, ties go to the
// lexicographically smaller path — the outcome never depends on Map order.
async function scanTranscripts() {
  const t0 = Date.now();
  let dirents = [];
  try {
    dirents = await fsp.readdir(PROJECTS_DIR, { withFileTypes: true });
  } catch (err) {
    if (err.code === 'ENOENT') warnOnce('projects-enoent', `projects dir missing: ${PROJECTS_DIR}`);
    else warnOnce('projects-readdir', `cannot read projects dir: ${err.message}`);
    dirents = [];
  }

  const seenPaths = new Set();
  for (const dirent of dirents) {
    if (!dirent.isDirectory()) continue;
    const dirPath = path.join(PROJECTS_DIR, dirent.name);
    let files = [];
    try {
      files = await fsp.readdir(dirPath, { withFileTypes: true });
    } catch (err) {
      continue; // dir vanished mid-scan
    }
    for (const f of files) {
      if (!f.isFile() || !f.name.endsWith('.jsonl')) continue;
      if (!SESSION_ID_RE.test(path.basename(f.name, '.jsonl'))) continue;
      const filePath = path.join(dirPath, f.name);
      let st;
      try {
        st = await fsp.stat(filePath);
      } catch (err) {
        continue; // file vanished mid-scan
      }
      if (!st.isFile()) continue;
      seenPaths.add(filePath);
      const cached = transcriptCache.get(filePath);
      if (cached && cached.mtimeMs === st.mtimeMs && cached.size === st.size) continue;
      const summary = await parseTranscriptFile(filePath);
      if (summary === null) {
        transcriptCache.delete(filePath);
        seenPaths.delete(filePath);
        continue;
      }
      summary.sessionId = path.basename(f.name, '.jsonl');
      transcriptCache.set(filePath, { mtimeMs: st.mtimeMs, size: st.size, summary });
    }
  }

  for (const key of transcriptCache.keys()) {
    if (!seenPaths.has(key)) transcriptCache.delete(key);
  }

  const next = new Map();
  for (const { summary } of transcriptCache.values()) {
    const prev = next.get(summary.sessionId);
    if (!prev) {
      next.set(summary.sessionId, summary);
      continue;
    }
    warnOnce(`dup-${summary.sessionId}`, `duplicate transcripts for session ${summary.sessionId}`);
    const prevTs = prev.lastTs === null ? -Infinity : prev.lastTs;
    const curTs = summary.lastTs === null ? -Infinity : summary.lastTs;
    if (curTs > prevTs || (curTs === prevTs && summary.path < prev.path)) {
      next.set(summary.sessionId, summary);
    }
  }
  transcriptBySession = next;

  transcriptScans += 1;
  if (transcriptScans === 1) {
    console.log(`ccc: scanned ${transcriptCache.size} transcripts in ${Date.now() - t0}ms`);
  }
}

// PID-reuse guard: one batched `ps -o pid=,lstart= -p p1,p2,...` (argv array,
// never a shell) for all kill-alive candidates. procStart strings in session
// files are `ps lstart` rendered in UTC (verified: machine TZ is PDT yet every
// file matches `TZ=UTC ps` exactly), so ps runs with TZ=UTC or every
// comparison would fail and all live sessions would be treated as dead.
// Resolves a Map<pid, lstart>, or null on total ps failure (guard skipped).
function psLstartByPid(pids) {
  return new Promise((resolve) => {
    execFile(
      'ps',
      ['-o', 'pid=,lstart=', '-p', pids.join(',')],
      { timeout: 5000, env: { ...process.env, TZ: 'UTC' } },
      (err, stdout) => {
        // Non-zero exit just means some PIDs were gone — parse whatever stdout
        // it produced. Spawn-level failure (string err.code) or a timeout kill
        // means no trustworthy output: skip the guard this tick.
        if (err && (typeof err.code === 'string' || err.killed)) {
          warnOnce('ps-guard', `ps unavailable, PID-reuse guard skipped: ${err.message}`);
          resolve(null);
          return;
        }
        const byPid = new Map();
        for (const line of String(stdout || '').split('\n')) {
          const m = /^\s*(\d+)\s+(.+?)\s*$/.exec(line);
          if (m) byPid.set(Number.parseInt(m[1], 10), m[2]);
        }
        resolve(byPid);
      }
    );
  });
}

function normalizeWhitespace(str) {
  return str.trim().replace(/\s+/g, ' ');
}

// kill(pid, 0) aliveness probe; EPERM = exists but not ours = alive.
function isPidAlive(pid) {
  try {
    process.kill(pid, 0);
    return true;
  } catch (err) {
    return err.code === 'EPERM';
  }
}

// Scan SESSIONS_DIR/*.json into a fresh liveBySession map. A file survives
// only if its pid is alive (`process.kill(pid, 0)`; EPERM counts as alive)
// AND, when the file carries a procStart string, that string matches the live
// process's `ps lstart` (PID reuse by an unrelated process => treated as
// dead). Dead/stale files are ignored — NEVER deleted or modified. This
// matters because later parts type keystrokes into panes resolved from these
// PIDs.
async function scanLiveSessions() {
  let dirents = [];
  try {
    dirents = await fsp.readdir(SESSIONS_DIR, { withFileTypes: true });
  } catch (err) {
    if (err.code !== 'ENOENT') warnOnce('sessions-readdir', `cannot read sessions dir: ${err.message}`);
    dirents = [];
  }

  const candidates = [];
  for (const dirent of dirents) {
    // Only regular files named <pid>.json, and the embedded pid must match
    // the filename — a stale or malformed file must not be able to point at
    // an arbitrary alive process (later parts control sessions by PID).
    if (!dirent.isFile()) continue;
    const nameMatch = /^([1-9]\d*)\.json$/.exec(dirent.name);
    if (!nameMatch) continue;
    const filePid = Number.parseInt(nameMatch[1], 10);
    let raw;
    try {
      raw = await fsp.readFile(path.join(SESSIONS_DIR, dirent.name), 'utf8');
    } catch (err) {
      continue; // vanished mid-scan
    }
    const data = safeJsonParse(raw); // mid-write JSON -> null -> retried next tick
    if (!data || typeof data !== 'object' || Array.isArray(data)) continue;
    const pid = data.pid;
    if (!Number.isSafeInteger(pid) || pid <= 0) continue; // never reaches process.kill
    if (pid !== filePid) continue;
    if (typeof data.sessionId !== 'string' || !SESSION_ID_RE.test(data.sessionId)) continue;
    if (!isPidAlive(pid)) continue; // stale file: ignore, never delete
    candidates.push({ pid, sessionId: data.sessionId, data });
  }

  if (candidates.length > 0) {
    const lstartByPid = await psLstartByPid(candidates.map((c) => c.pid));
    if (lstartByPid !== null) {
      for (let i = candidates.length - 1; i >= 0; i--) {
        const { pid, data } = candidates[i];
        if (typeof data.procStart !== 'string' || data.procStart === '') continue; // kill-only fallback
        const liveLstart = lstartByPid.get(pid);
        if (liveLstart === undefined ||
            normalizeWhitespace(data.procStart) !== normalizeWhitespace(liveLstart)) {
          candidates.splice(i, 1); // PID reused by an unrelated process
        }
      }
    }
  }

  const next = new Map();
  for (const { pid, sessionId, data } of candidates) {
    const entry = {
      pid,
      status: typeof data.status === 'string' ? data.status : null,
      cwd: typeof data.cwd === 'string' && data.cwd !== '' ? data.cwd : null,
      name: typeof data.name === 'string' && data.name !== '' ? data.name : null,
      version: typeof data.version === 'string' && data.version !== '' ? data.version : null,
      startedAt: toTs(data.startedAt),
      updatedAt: toTs(data.updatedAt),
      // Internal only (never copied onto API records): lets the op-time
      // guard (assertLiveRecordPid) re-run the PID-reuse check above.
      procStart: typeof data.procStart === 'string' && data.procStart !== '' ? data.procStart : null,
    };
    const prev = next.get(sessionId);
    if (!prev) {
      next.set(sessionId, entry);
      continue;
    }
    // Two surviving files claim the same sessionId: larger updatedAt wins.
    const prevTs = prev.updatedAt === null ? -Infinity : prev.updatedAt;
    const curTs = entry.updatedAt === null ? -Infinity : entry.updatedAt;
    if (curTs > prevTs) next.set(sessionId, entry);
  }
  liveBySession = next;
}

const TASK_FILE_MAX_BYTES = 1024 * 1024; // task files are <1KB in practice

// Tasks for one session (route added in Part 5 — this feeds an HTTP
// endpoint). Defense in depth before path.join: the id must match
// SESSION_ID_RE (no "..", no separators) AND be one we discovered ourselves
// via readdir. Only regular files are read: dirents must be files (a symlink
// named 1.json must not be able to exfiltrate arbitrary JSON such as
// ~/.claude.json), and the open itself uses O_NOFOLLOW + O_NONBLOCK with an
// fstat re-check, so a swap-to-symlink/FIFO between readdir and open can
// neither follow a link nor block the event loop. Reads are size-capped.
function getTasks(sessionId) {
  if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) return [];
  if (!sessionIndex.has(sessionId)) return [];
  const dir = path.join(TASKS_DIR, sessionId);
  let dirents;
  try {
    dirents = fs.readdirSync(dir, { withFileTypes: true });
  } catch (err) {
    return []; // ENOENT et al -> no tasks
  }
  const tasks = [];
  const taskNames = dirents
    .filter((d) => d.isFile() && /^\d+\.json$/.test(d.name))
    .map((d) => d.name)
    .sort((a, b) => Number.parseInt(a, 10) - Number.parseInt(b, 10));
  const openFlags = fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW | fs.constants.O_NONBLOCK;
  for (const name of taskNames) {
    let raw = null;
    let fd = null;
    try {
      fd = fs.openSync(path.join(dir, name), openFlags);
      const st = fs.fstatSync(fd);
      if (st.isFile() && st.size <= TASK_FILE_MAX_BYTES) {
        raw = fs.readFileSync(fd, 'utf8');
      }
    } catch (err) {
      // ELOOP (symlink), ENOENT (vanished), etc. -> skip this entry
    } finally {
      if (fd !== null) {
        try { fs.closeSync(fd); } catch (err) { /* already closed */ }
      }
    }
    if (raw === null) continue;
    const task = safeJsonParse(raw);
    // Only task-shaped values (plain objects) are exposed.
    if (task && typeof task === 'object' && !Array.isArray(task)) tasks.push(task);
  }
  return tasks;
}

// ---------------------------------------------------------------------------
// JSONL tailer
// ---------------------------------------------------------------------------
//
// Per-file incremental transcript reader feeding the SSE hub: seeds read the
// trailing tailKb of a file, pumps read only appended bytes. Splitting is
// done on raw bytes (0x0A) and only complete lines are decoded, so a
// multi-byte UTF-8 character split across reads is never corrupted. Strictly
// read-only: stat / open('r') / read; every FileHandle closes in try/finally.

const TAIL_SKIP_THRESHOLD_BYTES = 512 * 1024; // a single pump never reads more
const TAIL_WINDOW_BYTES = 64 * 1024; // trailing window when skipping ahead
const TAIL_PARTIAL_CAP_BYTES = 1024 * 1024; // pathological line without \n
const WIRE_TEXT_CAP = 4000;
const WIRE_PREVIEW_CAP = 200;

const tailStates = new Map(); // path -> { offset, partial: Buffer, sessionId }
const tailOpTails = new Map(); // path -> never-rejecting tail promise

// Per-file op queue (same pattern as enqueuePaneOp): a seed read and a
// watcher pump on the same file can never interleave their
// stat/read/state-update sequences.
function enqueueTailOp(filePath, fn) {
  const tail = tailOpTails.get(filePath) || Promise.resolve();
  const run = tail.then(fn);
  const guard = run.then(() => undefined, () => undefined);
  tailOpTails.set(filePath, guard);
  guard.then(() => {
    if (tailOpTails.get(filePath) === guard) tailOpTails.delete(filePath);
  });
  return run;
}

// First line of a string, capped for wire previews.
function previewLine(str) {
  if (typeof str !== 'string') return '';
  const nl = str.indexOf('\n');
  return (nl === -1 ? str : str.slice(0, nl)).slice(0, WIRE_PREVIEW_CAP);
}

function toolResultPreview(content) {
  if (typeof content === 'string') return previewLine(content);
  if (Array.isArray(content)) {
    for (const block of content) {
      if (block && typeof block === 'object' && block.type === 'text' &&
          typeof block.text === 'string') {
        return previewLine(block.text);
      }
    }
  }
  return '';
}

// Reduce one parsed JSONL entry to the compact wire format. Full tool
// payloads never cross the wire — tool inputs/results can carry secrets, so
// previews stay strictly capped. Returns null for non-object entries. The
// client dedupes seed/SSE overlap (and truncation replays) by uuid.
function toWireEntry(entry) {
  if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return null;
  const msg = entry.message && typeof entry.message === 'object' && !Array.isArray(entry.message)
    ? entry.message
    : null;

  let text = null;
  const blocks = [];
  if (entry.type === 'user' || entry.type === 'assistant') {
    const content = msg ? msg.content : null;
    const parts = [];
    if (typeof content === 'string') {
      parts.push(content);
    } else if (Array.isArray(content)) {
      for (const block of content) {
        if (!block || typeof block !== 'object') continue;
        if (block.type === 'text' && typeof block.text === 'string') {
          parts.push(block.text);
        } else if (block.type === 'tool_use') {
          let preview = '';
          try {
            const json = JSON.stringify(block.input); // single-line by construction
            if (typeof json === 'string') preview = json.slice(0, WIRE_PREVIEW_CAP);
          } catch (err) { /* unstringifiable input -> empty preview */ }
          blocks.push({
            kind: 'tool_use',
            name: typeof block.name === 'string' ? block.name : null,
            preview,
          });
        } else if (block.type === 'tool_result') {
          blocks.push({
            kind: 'tool_result',
            preview: toolResultPreview(block.content),
            isError: block.is_error === true,
          });
        }
      }
    }
    if (parts.length > 0) text = parts.join('\n');
  } else if (typeof entry.content === 'string') {
    text = entry.content; // system entries (incl. away_summary)
  }

  let textTruncated = false;
  if (typeof text === 'string' && text.length > WIRE_TEXT_CAP) {
    text = text.slice(0, WIRE_TEXT_CAP);
    textTruncated = true;
  }

  const ts = typeof entry.timestamp === 'string' ? Date.parse(entry.timestamp) : NaN;
  return {
    uuid: typeof entry.uuid === 'string' ? entry.uuid : null,
    ts: Number.isFinite(ts) ? ts : null,
    type: typeof entry.type === 'string' ? entry.type : null,
    subtype: typeof entry.subtype === 'string' ? entry.subtype : null,
    isSidechain: entry.isSidechain === true,
    role: msg && typeof msg.role === 'string' ? msg.role : null,
    model: msg && typeof msg.model === 'string' ? msg.model : null,
    text,
    textTruncated,
    blocks,
    // Carried for turn_duration dividers in the UI; null on all other entries.
    durationMs: Number.isFinite(entry.durationMs) ? entry.durationMs : null,
  };
}

// Split a buffer on 0x0A. `lines` are complete lines (views into buf);
// `rest` is a COPY of the trailing incomplete piece so storing it as a tail
// state's `partial` does not pin a large parent buffer in memory.
function splitBufferLines(buf) {
  const lines = [];
  let start = 0;
  let idx;
  while ((idx = buf.indexOf(0x0a, start)) !== -1) {
    lines.push(buf.subarray(start, idx));
    start = idx + 1;
  }
  return { lines, rest: Buffer.from(buf.subarray(start)) };
}

function pushWireLine(lineBuf, entries) {
  const line = lineBuf.toString('utf8');
  if (line.trim() === '') return;
  const wire = toWireEntry(safeJsonParse(line)); // malformed JSON -> null -> dropped
  if (wire !== null) entries.push(wire);
}

// Read [start, end) through an open file handle. Returns however many bytes
// were actually available (the file may shrink between stat and read).
async function readByteRange(fh, start, end) {
  const length = end - start;
  const buf = Buffer.alloc(length);
  let done = 0;
  while (done < length) {
    const { bytesRead } = await fh.read(buf, done, length - done, start + done);
    if (bytesRead === 0) break;
    done += bytesRead;
  }
  return done === length ? buf : buf.subarray(0, done);
}

// Seed read for the transcript route: the trailing tailKb of the file. When
// the read does not start at byte 0, everything up to and including the
// first \n is dropped (a partial first line must never be parsed); the
// trailing piece at EOF is parsed if it is complete valid JSON, dropped
// otherwise. PURE READ: tail states are never created, advanced, or rewound
// here — startup EOF seeding and pumpTail own that state. A seed that
// touched it could mark a newly discovered file "already delivered" and
// suppress its first broadcast to existing SSE clients; the overlap a
// seeding client may see instead is deduped client-side by uuid. Runs inside
// the per-file op queue so it cannot interleave with a pump's stat/read
// sequence. ENOENT resolves to []; any other error propagates to the route's
// 500 boundary.
function readTailSeed(filePath, tailKb) {
  return enqueueTailOp(filePath, async () => {
    let fh;
    try {
      fh = await fsp.open(filePath, 'r');
    } catch (err) {
      if (err && err.code === 'ENOENT') return [];
      throw err;
    }
    let buf;
    try {
      const size = (await fh.stat()).size;
      const start = Math.max(0, size - tailKb * 1024);
      buf = await readByteRange(fh, start, size);
      if (start > 0) {
        const nl = buf.indexOf(0x0a);
        buf = nl === -1 ? Buffer.alloc(0) : buf.subarray(nl + 1);
      }
    } finally {
      await fh.close();
    }
    const entries = [];
    const { lines, rest } = splitBufferLines(buf);
    for (const lineBuf of lines) pushWireLine(lineBuf, entries);
    pushWireLine(rest, entries); // EOF piece: parsed if valid, else dropped
    return entries;
  });
}

// Incremental pump: read appended bytes, return new wire entries (callers
// broadcast). Never rejects — watcher callbacks and the safety pump must not
// throw. State transitions:
//   no state      -> created at offset 0, so a file first seen via a watcher
//                    streams from the start (bounded by the skip-ahead cap)
//   ENOENT        -> state dropped (recreated at 0 if the file reappears)
//   size < offset -> truncation/replacement: reset to 0 and pump the current
//                    contents in this same call (a coalesced truncate+append
//                    still delivers; uuid-dedupe absorbs replays)
//   far behind    -> skip-ahead: only the trailing 64 KB window is read
function pumpTail(filePath) {
  return enqueueTailOp(filePath, async () => {
    let state = tailStates.get(filePath);
    if (!state) {
      state = {
        offset: 0,
        partial: Buffer.alloc(0),
        sessionId: path.basename(filePath, '.jsonl'),
      };
      tailStates.set(filePath, state);
    }
    let size;
    try {
      size = (await fsp.stat(filePath)).size;
    } catch (err) {
      if (err && err.code === 'ENOENT') tailStates.delete(filePath);
      return [];
    }
    if (size < state.offset) {
      state.offset = 0;
      state.partial = Buffer.alloc(0);
    }
    if (size === state.offset) return [];

    let fh;
    try {
      fh = await fsp.open(filePath, 'r');
    } catch (err) {
      if (err && err.code === 'ENOENT') tailStates.delete(filePath);
      return [];
    }
    const entries = [];
    try {
      if (size - state.offset > TAIL_SKIP_THRESHOLD_BYTES) {
        // Skip-ahead: discard the old partial, deliver the trailing window.
        const start = size - TAIL_WINDOW_BYTES;
        let buf = await readByteRange(fh, start, size);
        const consumed = start + buf.length;
        const nl = buf.indexOf(0x0a);
        buf = nl === -1 ? Buffer.alloc(0) : buf.subarray(nl + 1);
        const { lines, rest } = splitBufferLines(buf);
        for (const lineBuf of lines) pushWireLine(lineBuf, entries);
        state.offset = consumed;
        state.partial = rest;
      } else {
        const chunk = await readByteRange(fh, state.offset, size);
        const combined = Buffer.concat([state.partial, chunk]);
        const { lines, rest } = splitBufferLines(combined);
        for (const lineBuf of lines) pushWireLine(lineBuf, entries);
        state.offset += chunk.length;
        // Defensive cap: a giant line that never ends must not grow forever.
        state.partial = rest.length > TAIL_PARTIAL_CAP_BYTES ? Buffer.alloc(0) : rest;
      }
    } catch (err) {
      return []; // read error: keep state, retry on the next pump
    } finally {
      await fh.close().catch(() => {});
    }
    return entries;
  });
}

// ---------------------------------------------------------------------------
// tmux controller
// ---------------------------------------------------------------------------
//
// All control operations target tmux pane IDs (%N from #{pane_id}): unique,
// stable for the pane's lifetime, and immune to the session-name prefix/glob
// matching and window/pane-index renumbering that make session:window.pane
// strings unsafe for scripted control. The human-readable string is kept on
// records as tmuxLabel for display only. tmux is always invoked via execFile
// with argv arrays — never a shell.

const TMUX_BIN = fs.existsSync('/opt/homebrew/bin/tmux') ? '/opt/homebrew/bin/tmux' : 'tmux';
const PANE_ID_RE = /^%\d+$/;

// Promise wrapper around execFile(tmux, ...). Rejects with the subcommand and
// trimmed stderr so callers see real causes ("can't find pane", "no server
// running"); spawn failure (ENOENT) rejects too. `input`, when given, is
// written to stdin (with an error listener so an early tmux exit surfaces as
// the callback's rejection, not an EPIPE crash).
function execTmux(args, { input } = {}) {
  return new Promise((resolve, reject) => {
    const child = execFile(
      TMUX_BIN,
      args,
      { timeout: 10000, maxBuffer: 4 * 1024 * 1024 },
      (err, stdout, stderr) => {
        if (err) {
          const detail = String(stderr || '').trim() || err.message;
          reject(new Error(`tmux ${args[0]}: ${detail}`));
          return;
        }
        resolve(String(stdout));
      }
    );
    if (child.stdin) {
      child.stdin.on('error', () => {}); // EPIPE if tmux exits early
      if (input !== undefined) child.stdin.end(input);
      else child.stdin.end();
    }
  });
}

// The only target form this module ever stores or accepts. Targets are always
// passed as the argv element after -t, so flag/shell injection is
// structurally impossible even before this check.
function assertTarget(target) {
  if (typeof target !== 'string' || !PANE_ID_RE.test(target)) {
    throw new Error(`invalid tmux target: ${String(target).slice(0, 64)}`);
  }
}

let tmuxTargetByPid = new Map(); // live claude pid -> { paneId, label }; swapped atomically

// Panes created by launchSession this run: paneId -> tmux SERVER pid at
// launch time. Entries are removed on a successful killPane, and mapPanes
// purges every entry recorded against a different tmux server generation —
// pane IDs are never reused within one server's lifetime, but a RESTARTED
// tmux server starts its %N counter over, so without the generation tag a
// stale id could match an unrelated new pane and pass assertControlledPane.
// Within one generation a stale id can only ever error, never reach another
// pane, and the map is bounded by the number of launches per server run.
const launchedPaneIds = new Map();

// Ownership boundary on top of the shape check: control operations are
// allowed only against panes that hold a live claude we mapped ourselves
// (tmuxTargetByPid) or panes this module launched. The Part 6 routes derive
// targets server-side from the session index, but these functions are
// client-reachable there — a token holder must not be able to capture or
// type into arbitrary tmux panes by guessing pane ids. .code lets the routes
// map this to a 409 (pane vanished between scan ticks / stale index).
function assertControlledPane(target) {
  assertTarget(target);
  if (launchedPaneIds.has(target)) return;
  for (const pane of tmuxTargetByPid.values()) {
    if (pane.paneId === target) return;
  }
  const err = new Error(`not a controlled pane: ${target}`);
  err.code = 'UNKNOWN_TARGET';
  throw err;
}

// Op-time generation re-check for panes we launched: the scan-driven purge
// in mapPanes is up to one tick (~2s) behind, and across a tmux server
// restart pane ids restart and may be reused — a stale launched id must
// never reach an unrelated pane on the new server. One display-message
// round-trip pins the pane to the server generation it was launched on; a
// mismatch drops the entry and rejects. Panes resolved via tmuxTargetByPid
// skip this: that map is rebuilt from the CURRENT server every tick, pane
// ids are never reused within one server generation, and a restart kills the
// mapped claude (the pid guards reject the op).
async function verifyLaunchedPaneGeneration(target) {
  const expected = launchedPaneIds.get(target);
  if (expected === undefined) return;
  const out = await execTmux(['display-message', '-p', '-t', target, '#{pid}']);
  if (Number.parseInt(out.trim(), 10) !== expected) {
    launchedPaneIds.delete(target);
    const err = new Error(`not a controlled pane (tmux server restarted): ${target}`);
    err.code = 'UNKNOWN_TARGET';
    throw err;
  }
}

const paneOpTails = new Map(); // paneId -> never-rejecting tail promise

// Serialize input-mutating operations per pane: without this, two concurrent
// sendPrompt calls to the same pane could interleave as paste A, paste B,
// Enter A, Enter B and submit merged text. Tails stored in the map never
// reject (failures still propagate to the original caller via the returned
// promise) and the entry is dropped once the queue drains.
function enqueuePaneOp(target, fn) {
  const tail = paneOpTails.get(target) || Promise.resolve();
  const run = tail.then(fn);
  const guard = run.then(() => undefined, () => undefined);
  paneOpTails.set(target, guard);
  guard.then(() => {
    if (paneOpTails.get(target) === guard) paneOpTails.delete(target);
  });
  return run;
}

// The master plan's list-panes format, extended with two fields — a leading
// #{pid} (the tmux SERVER pid, the generation tag for launched/overlay pane
// ids) and a trailing #{pane_id}. Every specced field is still produced.
const PANE_LIST_FORMAT =
  '#{pid}|#{pane_pid}|#{session_name}:#{window_index}.#{pane_index}|#{pane_current_path}|#{pane_id}';

// list-panes -a parsed from the ends, where the unambiguous fields live:
// server pid before the FIRST `|`, pane_pid between the first and second,
// pane_id after the LAST `|` — all shape-checked (lines failing the checks
// are skipped; the two leading pids are digits-only, so a pathological `|`
// in a session name cannot shift them). The label between the second and
// third `|` is best-effort display data: a `|` in a session name can only
// degrade the label, never the control-critical fields. Also returns the set
// of EVERY pane id seen (independent of pid validity) — the launch-overlay
// cleanup uses it to detect panes that died, so it must be as complete as
// possible (a missing id there deletes an overlay entry).
async function listPanes() {
  const stdout = await execTmux(['list-panes', '-a', '-F', PANE_LIST_FORMAT]);
  const byPid = new Map(); // pane_pid -> { paneId, label }
  const paneIds = new Set(); // every pane_id in the tmux server
  let serverPid = null; // #{pid}: identical on every line
  for (const line of stdout.split('\n')) {
    if (line === '') continue;
    const firstBar = line.indexOf('|');
    const secondBar = firstBar === -1 ? -1 : line.indexOf('|', firstBar + 1);
    const lastBar = line.lastIndexOf('|');
    if (firstBar === -1 || secondBar === -1 || lastBar <= secondBar) continue;
    const serverPidStr = line.slice(0, firstBar);
    const pidStr = line.slice(firstBar + 1, secondBar);
    const paneId = line.slice(lastBar + 1);
    if (!PANE_ID_RE.test(paneId)) continue;
    paneIds.add(paneId);
    if (serverPid === null && /^[1-9]\d*$/.test(serverPidStr)) {
      serverPid = Number.parseInt(serverPidStr, 10);
    }
    if (!/^\d+$/.test(pidStr)) continue;
    const thirdBar = line.indexOf('|', secondBar + 1);
    const label = line.slice(secondBar + 1, thirdBar === -1 ? lastBar : thirdBar);
    byPid.set(Number.parseInt(pidStr, 10), { paneId, label });
  }
  return { byPid, paneIds, serverPid };
}

// One batched `ps -o pid=,ppid=` per hop level (same pattern as
// psLstartByPid). Non-zero exit with partial stdout is fine (some pids died
// mid-walk); spawn-level failure or a timeout kill resolves null.
function psPpidByPid(pids) {
  return new Promise((resolve) => {
    execFile(
      'ps',
      ['-o', 'pid=,ppid=', '-p', pids.join(',')],
      { timeout: 5000 },
      (err, stdout) => {
        if (err && (typeof err.code === 'string' || err.killed)) {
          resolve(null);
          return;
        }
        const byPid = new Map();
        for (const line of String(stdout || '').split('\n')) {
          const m = /^\s*(\d+)\s+(\d+)\s*$/.exec(line);
          if (m) byPid.set(Number.parseInt(m[1], 10), Number.parseInt(m[2], 10));
        }
        resolve(byPid);
      }
    );
  });
}

// Resolve live pids to the panes containing them. Hop 0 checks each pid
// against the pane map directly — required, not an optimization: dashboard-
// launched sessions run claude as the pane command, so pane_pid == claude
// pid. Otherwise walk the PPID chain (≤8 hops, one batched ps per level);
// drop a pid when its ppid is missing, 0, or 1. Never rejects.
async function walkToPane(livePids, paneByPid) {
  const resolved = new Map(); // live pid -> { paneId, label }
  let frontier = new Map(); // live pid -> current ancestor pid
  for (const pid of livePids) {
    const pane = paneByPid.get(pid);
    if (pane) resolved.set(pid, pane);
    else frontier.set(pid, pid);
  }
  for (let hop = 0; hop < 8 && frontier.size > 0; hop++) {
    const ancestors = [...new Set(frontier.values())];
    const ppidByPid = await psPpidByPid(ancestors);
    if (ppidByPid === null) {
      warnOnce('ps-walk', 'ps unavailable, pane mapping incomplete this tick');
      break; // keep whatever resolved so far
    }
    const nextFrontier = new Map();
    for (const [livePid, ancestor] of frontier) {
      const ppid = ppidByPid.get(ancestor);
      if (ppid === undefined || ppid <= 1) continue; // died / hit launchd
      const pane = paneByPid.get(ppid);
      if (pane) resolved.set(livePid, pane);
      else nextFrontier.set(livePid, ppid);
    }
    frontier = nextFrontier;
  }
  return resolved;
}

// Every pane id seen by the last SUCCESSFUL list-panes, or null when the
// listing failed (tmux missing / no server). null — not an empty set — so
// the overlay cleanup can tell "tmux says these panes are gone" apart from
// "tmux is unreachable" and never mass-deletes valid entries on an outage.
let knownPaneIds = null;

// The tmux server pid from the last successful list-panes (null until then /
// across outages). This is the pane-id generation: launched/overlay pane ids
// are only meaningful against the server they were created on.
let tmuxServerPid = null;

// Map every live claude pid to its tmux pane; runs each scan tick, so any
// claude started inside tmux is auto-adopted within ~2s and stale mappings
// live ≤2s. Never throws: tmux missing or no server running degrades to an
// empty map — every session becomes view-only, never a crash.
async function mapPanes() {
  let panes;
  try {
    panes = await listPanes();
  } catch (err) {
    warnOnce('tmux-unavailable', `tmux unavailable, sessions are view-only: ${err.message}`);
    tmuxTargetByPid = new Map();
    knownPaneIds = null; // unknown, not empty — see comment above
    return;
  }
  knownPaneIds = panes.paneIds;
  if (panes.serverPid !== null) {
    tmuxServerPid = panes.serverPid;
    // Purge launched panes recorded against a DIFFERENT tmux server: those
    // panes died with their server, and a restarted server restarts the %N
    // counter, so a stale id could otherwise match an unrelated new pane and
    // pass assertControlledPane. (Entries from a launch that raced this very
    // tick carry the new server's pid and survive.) The launch overlay gets
    // the same generation purge in cleanupLaunchOverlay.
    for (const [paneId, gen] of launchedPaneIds) {
      if (gen !== panes.serverPid) launchedPaneIds.delete(paneId);
    }
  }
  const livePids = [...liveBySession.values()].map((live) => live.pid);
  tmuxTargetByPid = await walkToPane(livePids, panes.byPid);
}

// Full rendered screen with ANSI SGR sequences. Errors ("can't find pane")
// propagate to the caller; routes map them in Part 6.
async function capturePane(target) {
  assertControlledPane(target);
  await verifyLaunchedPaneGeneration(target);
  return execTmux(['capture-pane', '-p', '-e', '-t', target]);
}

const MAX_PROMPT_BYTES = 256 * 1024; // defensive cap; routes may cap tighter

// Caller-input validation errors (vs tmux/launch failures). The control
// routes map BAD_INPUT to 400; everything untagged becomes a 502.
function badInput(message) {
  const err = new Error(message);
  err.code = 'BAD_INPUT';
  return err;
}

// Multiline-safe prompt delivery: load-buffer via stdin (newlines, quotes,
// unicode survive untouched) -> paste-buffer -p (bracketed paste: embedded
// newlines insert soft newlines instead of submitting) -r (keep LF as LF,
// matching what a real terminal paste delivers) -d (delete buffer on
// success) -> one explicit send-keys Enter to submit. The per-call unique
// buffer name means concurrent prompts can never cross-paste, and the named
// buffer never clobbers the user's buffer stack.
async function sendPrompt(target, text, { preflight } = {}) {
  assertControlledPane(target);
  if (typeof text !== 'string' || text === '') {
    throw badInput('prompt text must be a non-empty string');
  }
  if (Buffer.byteLength(text, 'utf8') > MAX_PROMPT_BYTES) {
    throw badInput('prompt text too large');
  }
  return enqueuePaneOp(target, async () => {
    // Final guards run INSIDE the queue: this op may have waited behind
    // earlier pane ops, and claude can exit / tmux can restart during that
    // wait — re-validate immediately before touching the pane. `preflight`
    // is the caller's record-level guard (assertLiveRecordPid); a throw here
    // propagates to the caller and the pane is never touched.
    if (preflight !== undefined) await preflight();
    await verifyLaunchedPaneGeneration(target);
    const bufName = 'ccc-' + crypto.randomUUID();
    let loaded = false;
    let pasted = false;
    try {
      await execTmux(['load-buffer', '-b', bufName, '-'], { input: text });
      loaded = true;
      await execTmux(['paste-buffer', '-d', '-p', '-r', '-b', bufName, '-t', target]);
      pasted = true;
      await execTmux(['send-keys', '-t', target, 'Enter']);
    } finally {
      // -d only deletes on successful paste; a failed prompt must not linger
      // in tmux buffers.
      if (loaded && !pasted) {
        await execTmux(['delete-buffer', '-b', bufName]).catch(() => {});
      }
    }
  });
}

// The whitelist is the security boundary: sendKeys becomes client-reachable
// in Part 6 and must never be an arbitrary-keystroke injector. Exact string
// match — no trimming, no case folding.
const KEY_WHITELIST = new Set([
  'Enter', 'Escape', 'Up', 'Down', 'Left', 'Right', 'Tab', 'BSpace', 'C-c',
  '1', '2', '3', '4', '5', '6', '7', '8', '9', 'y', 'n',
]);

async function sendKeys(target, key, { preflight } = {}) {
  if (typeof key !== 'string' || !KEY_WHITELIST.has(key)) {
    const err = new Error('key not in whitelist');
    err.code = 'BAD_KEY';
    throw err;
  }
  assertControlledPane(target);
  return enqueuePaneOp(target, async () => {
    // Same in-queue final guards as sendPrompt — see the comment there.
    if (preflight !== undefined) await preflight();
    await verifyLaunchedPaneGeneration(target);
    return execTmux(['send-keys', '-t', target, key]);
  });
}

// Pure helper: smallest n >= 1 such that ccc-<base>-<n> is not in the
// exact-match set of existing session names (so ccc-x-1 and ccc-x-10 never
// collide — `has-session -t` does prefix matching and is deliberately not
// used). tmux rejects `:`/`.` in session names, hence the sanitize.
function pickSessionName(base, existingNames) {
  let safe = String(base).replace(/[^A-Za-z0-9_-]/g, '-');
  if (safe === '') safe = 'session';
  const names = existingNames instanceof Set ? existingNames : new Set(existingNames);
  for (let n = 1; ; n++) {
    const candidate = `ccc-${safe}-${n}`;
    if (!names.has(candidate)) return candidate;
  }
}

// "No server running" counts as an empty set.
async function listSessionNames() {
  let stdout;
  try {
    stdout = await execTmux(['list-sessions', '-F', '#{session_name}']);
  } catch (err) {
    return new Set();
  }
  return new Set(stdout.split('\n').filter((line) => line !== ''));
}

// Find the SESSIONS_DIR/<pid>.json written by the claude we just launched,
// hardened against stale files carrying the same sessionId (matters most for
// --resume). A candidate matches only if ALL hold: parsed object with the
// expected sessionId; embedded pid === filename pid; pid alive (EPERM counts
// alive); procStart (when present) matches the live process's `ps lstart`;
// and the pid's PPID ancestry reaches panePid — proving the file belongs to
// the claude inside OUR launched pane, not a stale or unrelated process.
// Read-only: nothing is ever written or deleted. Returns { pid, data }|null.
async function findLaunchedSessionFile(expectedSessionId, panePid) {
  let dirents = [];
  try {
    dirents = await fsp.readdir(SESSIONS_DIR, { withFileTypes: true });
  } catch (err) {
    return null;
  }
  for (const dirent of dirents) {
    if (!dirent.isFile()) continue;
    const nameMatch = /^([1-9]\d*)\.json$/.exec(dirent.name);
    if (!nameMatch) continue;
    const filePid = Number.parseInt(nameMatch[1], 10);
    let raw;
    try {
      raw = await fsp.readFile(path.join(SESSIONS_DIR, dirent.name), 'utf8');
    } catch (err) {
      continue;
    }
    const data = safeJsonParse(raw);
    if (!data || typeof data !== 'object' || Array.isArray(data)) continue;
    if (data.sessionId !== expectedSessionId) continue;
    if (!Number.isSafeInteger(data.pid) || data.pid !== filePid) continue;
    if (!isPidAlive(filePid)) continue;
    if (typeof data.procStart === 'string' && data.procStart !== '') {
      const lstartByPid = await psLstartByPid([filePid]);
      if (lstartByPid !== null) {
        const liveLstart = lstartByPid.get(filePid);
        if (liveLstart === undefined ||
            normalizeWhitespace(data.procStart) !== normalizeWhitespace(liveLstart)) {
          continue; // PID reused by an unrelated process
        }
      }
    }
    const probeMap = new Map([[panePid, { paneId: null, label: null }]]);
    const resolved = await walkToPane([filePid], probeMap);
    if (!resolved.has(filePid)) continue;
    return { pid: filePid, data };
  }
  return null;
}

const LAUNCH_POLL_INTERVAL_MS = 500;
const LAUNCH_TIMEOUT_MS = 20000;

// Launch claude in a new detached ccc-* tmux session and wait for its session
// file to appear. Returns { sessionId, tmuxTarget, tmuxLabel, serverPid,
// promptSent }; throws on hard failure. The user can `tmux attach -t ccc-…`
// at any time.
async function launchSession({ cwd, resumeSessionId, initialPrompt } = {}) {
  if (typeof cwd !== 'string' || !path.isAbsolute(cwd)) {
    throw badInput('cwd must be an absolute path');
  }
  let st;
  try {
    st = await fsp.stat(cwd);
  } catch (err) {
    throw badInput(`cwd does not exist: ${cwd}`);
  }
  if (!st.isDirectory()) throw badInput(`cwd is not a directory: ${cwd}`);
  if (resumeSessionId === undefined || resumeSessionId === null) {
    resumeSessionId = null;
  } else if (typeof resumeSessionId !== 'string' || !SESSION_ID_RE.test(resumeSessionId)) {
    throw badInput('invalid resumeSessionId');
  }
  if (initialPrompt === undefined || initialPrompt === null) {
    initialPrompt = null;
  } else if (typeof initialPrompt !== 'string' || initialPrompt === '') {
    throw badInput('initialPrompt must be a non-empty string');
  } else if (Buffer.byteLength(initialPrompt, 'utf8') > MAX_PROMPT_BYTES) {
    // Same cap sendPrompt enforces — checked BEFORE any tmux session is
    // created, so an oversized prompt cannot produce a side-effectful launch
    // that then fails.
    throw badInput('initialPrompt too large');
  }

  // Resume keeps the session id (master plan contract); new sessions get a
  // uuid we choose, so the poll below knows exactly what to look for.
  const expectedSessionId = resumeSessionId !== null ? resumeSessionId : crypto.randomUUID();
  const claudeArgs = resumeSessionId !== null
    ? ['--resume', resumeSessionId]
    : ['--session-id', expectedSessionId];

  // Spawn detached; with multiple words after `--`, tmux execs them directly
  // (no shell). Retry on a duplicate-session race between two launches.
  let name = null;
  for (let attempt = 0; attempt < 3; attempt++) {
    const candidate = pickSessionName(path.basename(cwd), await listSessionNames());
    try {
      await execTmux(['new-session', '-d', '-s', candidate, '-c', cwd, '--', 'claude', ...claudeArgs]);
      name = candidate;
      break;
    } catch (err) {
      if (attempt < 2 && /duplicate session/i.test(err.message)) continue;
      throw err;
    }
  }
  if (name === null) throw new Error('launch failed: could not create tmux session');

  // A brand-new detached session has exactly one pane; all subsequent probes
  // and operations use its pane ID only (immune to renames/renumbering).
  // #{pid} (the tmux server pid) is the generation tag the pane id is valid
  // against — see launchedPaneIds.
  const paneLine = (await execTmux([
    'list-panes', '-t', name,
    '-F', '#{pane_id}|#{pane_pid}|#{pid}|#{session_name}:#{window_index}.#{pane_index}',
  ])).split('\n')[0] || '';
  const firstBar = paneLine.indexOf('|');
  const secondBar = firstBar === -1 ? -1 : paneLine.indexOf('|', firstBar + 1);
  const thirdBar = secondBar === -1 ? -1 : paneLine.indexOf('|', secondBar + 1);
  const paneId = firstBar === -1 ? '' : paneLine.slice(0, firstBar);
  const panePid = secondBar === -1 ? NaN : Number.parseInt(paneLine.slice(firstBar + 1, secondBar), 10);
  const serverPid = thirdBar === -1 ? NaN : Number.parseInt(paneLine.slice(secondBar + 1, thirdBar), 10);
  const tmuxLabel = thirdBar === -1 ? null : paneLine.slice(thirdBar + 1);
  if (!PANE_ID_RE.test(paneId) || !Number.isSafeInteger(panePid) || panePid <= 0 ||
      !Number.isSafeInteger(serverPid) || serverPid <= 0) {
    throw new Error(`launch failed: cannot resolve pane of tmux session ${name}`);
  }
  // We created this pane: it is controllable from now on (sendPrompt below
  // and killPane/capturePane by callers), even before mapPanes adopts its
  // claude pid on the next scan tick.
  launchedPaneIds.set(paneId, serverPid);

  const deadline = Date.now() + LAUNCH_TIMEOUT_MS;
  let matched = false;
  while (Date.now() < deadline) {
    await new Promise((resolve) => setTimeout(resolve, LAUNCH_POLL_INTERVAL_MS));

    // Pane liveness first, every iteration: '1' = remain-on-exit corpse; an
    // error = pane gone. (has-session only proves the session exists, not
    // that the process lives, so it is not used.)
    let dead;
    try {
      dead = (await execTmux(['display-message', '-p', '-t', paneId, '#{pane_dead}'])).trim();
    } catch (err) {
      dead = '1';
    }
    if (dead === '1') {
      throw new Error(`launch failed: claude exited during startup (tmux session ${name})`);
    }

    const found = await findLaunchedSessionFile(expectedSessionId, panePid);
    if (found !== null) {
      matched = true;
      if (initialPrompt === null) {
        return { sessionId: expectedSessionId, tmuxTarget: paneId, tmuxLabel, serverPid, promptSent: false };
      }
      const status = found.data.status;
      if (status === 'ready' || status === 'idle') {
        await sendPrompt(paneId, initialPrompt);
        return { sessionId: expectedSessionId, tmuxTarget: paneId, tmuxLabel, serverPid, promptSent: true };
      }
      // Not ready yet (e.g. busy starting up, or a trust-folder dialog ->
      // status "waiting") — keep polling within the same budget.
    }
  }
  if (!matched) {
    // The pane is deliberately left alive so the user can inspect it.
    throw new Error(
      `launch failed: no session file matched within ${LAUNCH_TIMEOUT_MS / 1000}s ` +
      `(tmux session ${name} left running — attach to inspect)`
    );
  }
  // Matched but never reached ready/idle: the pane exists and is
  // controllable; the Part 6 route / UI decides what to do.
  return { sessionId: expectedSessionId, tmuxTarget: paneId, tmuxLabel, serverPid, promptSent: false };
}

// Confirm-dialog UX is Part 8; the route lives below.
async function killPane(target) {
  assertControlledPane(target);
  await verifyLaunchedPaneGeneration(target);
  await execTmux(['kill-pane', '-t', target]);
  launchedPaneIds.delete(target);
}

// ---------------------------------------------------------------------------
// Launch overlay
// ---------------------------------------------------------------------------
//
// launchSession returns a controllable pane immediately, but the session
// index only carries live/tmuxTarget after claude writes its session file AND
// a scan tick adopts it (1-3s, longer when claude starts slowly). The overlay
// bridges that gap: every successful launch (new or resume) records its pane
// here, makeRecord and the control routes fall back to it, and scanTick
// cleans it up once the index has adopted the pane (or the pane died).
// Without it, an immediate /watch, /keys, or second /prompt on a just-
// launched session would 404/409 — or double-resume a done session.

// sessionId -> { paneId, label, serverPid, launchedAt }; serverPid is the
// pane-id generation tag (see launchedPaneIds).
const launchOverlay = new Map();
const LAUNCH_OVERLAY_TTL_MS = 10 * 60 * 1000;

// The single pane-resolution point for the control routes and the mirror
// loop. The overlay pane is in launchedPaneIds, so assertControlledPane
// accepts it. `record` may be undefined (brand-new session not yet indexed).
function resolveControlPane(sessionId, record) {
  if (record && record.tmuxTarget !== null) return record.tmuxTarget;
  const overlay = launchOverlay.get(sessionId);
  return overlay ? overlay.paneId : null;
}

// Runs inside scanTick after mapPanes and BEFORE rebuildIndex, so a deleted
// entry and the record fallback copied from it disappear in the same tick —
// no record ever carries a deleted overlay's tmuxTarget past this scan.
function cleanupLaunchOverlay(nowMs) {
  for (const [sessionId, entry] of launchOverlay) {
    // Adopted: the index now carries the real pid -> pane mapping.
    const live = liveBySession.get(sessionId);
    if (live && tmuxTargetByPid.has(live.pid)) {
      launchOverlay.delete(sessionId);
      continue;
    }
    // Different tmux server generation: the entry's pane died with its
    // server, and its id may have been REUSED by the current server (where
    // knownPaneIds would then still contain it) — never let it route there.
    if (tmuxServerPid !== null && entry.serverPid !== tmuxServerPid) {
      launchOverlay.delete(sessionId);
      continue;
    }
    // Pane died (claude exited / user killed it) — a dead launch must not
    // present as controllable forever. Skipped when the pane listing failed
    // this tick (knownPaneIds === null): an outage must not wipe valid
    // entries. The TTL below still bounds that case.
    if (knownPaneIds !== null && !knownPaneIds.has(entry.paneId)) {
      launchOverlay.delete(sessionId);
      continue;
    }
    if (nowMs - entry.launchedAt > LAUNCH_OVERLAY_TTL_MS) {
      launchOverlay.delete(sessionId);
    }
  }
}

// ---------------------------------------------------------------------------
// Status derivation
// ---------------------------------------------------------------------------

// Priority: live PID alive -> map the file status (busy/shell -> busy,
// ready -> ready, anything else -> idle); no live PID -> done, with a
// sub-label derived from the last transcript entry.
function deriveStatus(live, summary) {
  if (live) {
    const s = live.status;
    if (s === 'busy' || s === 'shell') return { displayStatus: 'busy', statusDetail: null };
    if (s === 'ready') return { displayStatus: 'ready', statusDetail: null };
    return { displayStatus: 'idle', statusDetail: null };
  }
  const last = summary && summary.lastEntry;
  if (!last || typeof last.type !== 'string') return { displayStatus: 'done', statusDetail: null };
  if (last.type === 'assistant') return { displayStatus: 'done', statusDetail: 'assistant replied' };
  if (last.type === 'user') return { displayStatus: 'done', statusDetail: 'awaiting reply' };
  if (last.type === 'system' && last.subtype === 'away_summary') {
    return { displayStatus: 'done', statusDetail: 'away summary' };
  }
  return { displayStatus: 'done', statusDetail: last.type };
}

function makeRecord(sessionId, summary, live) {
  const { displayStatus, statusDetail } = deriveStatus(live, summary);
  const liveField = live ? { pid: live.pid, status: live.status } : null;
  const pane = live ? tmuxTargetByPid.get(live.pid) : undefined;
  let tmuxTarget = pane ? pane.paneId : null;
  let tmuxLabel = pane ? pane.label : null;
  // Launch-overlay fallback: a just-launched/resumed session is controllable
  // before the index adopts its pane (its record may still look done/live-
  // without-pane). Apart from that window, done sessions (live === null)
  // stay tmuxTarget: null / controllable: false.
  if (tmuxTarget === null) {
    const overlay = launchOverlay.get(sessionId);
    if (overlay) {
      tmuxTarget = overlay.paneId;
      tmuxLabel = overlay.label;
    }
  }
  if (summary) {
    return {
      sessionId,
      // Both are real cwds from real data; the live file's is current.
      cwd: (live && live.cwd) || summary.cwd || null,
      transcriptPath: summary.path,
      gitBranch: summary.gitBranch,
      slug: summary.slug,
      name: (live && live.name) || summary.aiTitle || null,
      model: summary.model,
      version: (live && live.version) || summary.version || null,
      firstTs: summary.firstTs,
      lastTs: live ? maxTs(summary.lastTs, live.updatedAt) : summary.lastTs,
      msgCount: summary.msgCount,
      tokens: { ...summary.tokens },
      awaySummary: summary.awaySummary,
      live: liveField,
      tmuxTarget,
      tmuxLabel,
      displayStatus,
      statusDetail,
      controllable: tmuxTarget !== null,
    };
  }
  // Live session with no transcript yet.
  return {
    sessionId,
    cwd: live.cwd,
    transcriptPath: null,
    gitBranch: null,
    slug: null,
    name: live.name,
    model: null,
    version: live.version,
    firstTs: live.startedAt,
    lastTs: live.updatedAt,
    msgCount: 0,
    tokens: { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 },
    awaySummary: null,
    live: liveField,
    tmuxTarget,
    tmuxLabel,
    displayStatus,
    statusDetail,
    controllable: tmuxTarget !== null,
  };
}

// Rebuild sessionIndex in place (the Map identity is exported) from
// transcriptBySession + liveBySession.
function rebuildIndex() {
  sessionIndex.clear();
  for (const [sessionId, summary] of transcriptBySession) {
    sessionIndex.set(sessionId, makeRecord(sessionId, summary, liveBySession.get(sessionId) || null));
  }
  for (const [sessionId, live] of liveBySession) {
    if (!sessionIndex.has(sessionId)) sessionIndex.set(sessionId, makeRecord(sessionId, null, live));
  }
}

const STATUS_RANK = { busy: 0, ready: 1, idle: 2, done: 3 };

// busy -> ready -> idle -> done, lastTs desc within each group (null sorts
// last), sessionId tiebreak for stability.
function compareSessionRecords(a, b) {
  const rank = STATUS_RANK[a.displayStatus] - STATUS_RANK[b.displayStatus];
  if (rank !== 0) return rank;
  const at = a.lastTs === null ? -Infinity : a.lastTs;
  const bt = b.lastTs === null ? -Infinity : b.lastTs;
  if (at !== bt) return at < bt ? 1 : -1;
  return a.sessionId < b.sessionId ? -1 : a.sessionId > b.sessionId ? 1 : 0;
}

// ---------------------------------------------------------------------------
// Stats + projects
// ---------------------------------------------------------------------------

function localMidnight(nowMs) {
  const d = new Date(nowMs);
  d.setHours(0, 0, 0, 0);
  return d.getTime();
}

// GET /api/stats payload — exactly these four fields, computed from the live
// in-memory index only (~/.claude/stats-cache.json is stale and never read).
// Token counts only; no dollar/cost fields anywhere. "Today" is re-derived
// per call, so midnight rollover needs no cache invalidation.
function computeStats(nowMs) {
  const midnight = localMidnight(nowMs);
  const today = dayKey(nowMs);
  let activeSessions = 0;
  let sessionsToday = 0;
  for (const record of sessionIndex.values()) {
    if (record.live !== null) activeSessions += 1;
    if (record.lastTs !== null && record.lastTs >= midnight) sessionsToday += 1;
  }
  let messagesToday = 0;
  // Null prototype: model names are JSONL-derived strings, and
  // JSON.stringify of a null-prototype object is normal JSON.
  const tokensTodayByModel = Object.create(null);
  for (const summary of transcriptBySession.values()) {
    const bucket = summary.byDay[today];
    if (!bucket) continue;
    messagesToday += bucket.msgs;
    for (const model of Object.keys(bucket.byModel)) {
      const src = bucket.byModel[model];
      let dst = tokensTodayByModel[model];
      if (!dst) {
        dst = { input: 0, output: 0, cacheRead: 0, cacheCreate: 0 };
        tokensTodayByModel[model] = dst;
      }
      dst.input += src.input;
      dst.output += src.output;
      dst.cacheRead += src.cacheRead;
      dst.cacheCreate += src.cacheCreate;
    }
  }
  return { activeSessions, sessionsToday, messagesToday, tokensTodayByModel };
}

// SECURITY BOUNDARY: ~/.claude.json holds secrets (API keys, OAuth state).
// The parsed object is consumed as Object.keys(parsed.projects) ONLY —
// filtered to absolute-path strings — then discarded. No values, no other
// top-level keys; never stored, logged, or exposed.
//
// The file can be multi-MB, so a successful stat+parse caches its keys under
// the exact (mtimeMs, size); a parse failure or missing/non-object .projects
// caches [] for that same (mtimeMs, size) — a corrupt file is not re-parsed
// per request but is re-read the moment it changes. stat/read errors
// (ENOENT/EACCES) are NEVER cached: return [] and re-stat next request, so a
// ~/.claude.json created later is picked up immediately.
let projectKeysCache = null; // { mtimeMs, size, keys }

async function readProjectKeys() {
  let st;
  try {
    st = await fsp.stat(CLAUDE_JSON_PATH);
  } catch (err) {
    return [];
  }
  if (projectKeysCache !== null &&
      projectKeysCache.mtimeMs === st.mtimeMs &&
      projectKeysCache.size === st.size) {
    return projectKeysCache.keys;
  }
  let raw;
  try {
    raw = await fsp.readFile(CLAUDE_JSON_PATH, 'utf8');
  } catch (err) {
    return [];
  }
  const parsed = safeJsonParse(raw);
  let keys = [];
  if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) &&
      parsed.projects && typeof parsed.projects === 'object' &&
      !Array.isArray(parsed.projects)) {
    keys = Object.keys(parsed.projects).filter(
      (k) => typeof k === 'string' && path.isAbsolute(k)
    );
  }
  projectKeysCache = { mtimeMs: st.mtimeMs, size: st.size, keys };
  return keys;
}

// ---------------------------------------------------------------------------
// SSE hub
// ---------------------------------------------------------------------------
//
// One generic broadcast channel for all four event types: sessions (full
// snapshot, rate-limited to <=1/s), transcript (tailer output), pane and
// notify (emitters arrive in Parts 6 and 5). Token auth on GET /api/events
// comes from the existing /api/* gate (checkToken accepts ?token=, which
// EventSource needs).

const SSE_MAX_BUFFERED_BYTES = 4 * 1024 * 1024; // wedged-consumer cutoff
const SSE_HEARTBEAT_MS = 25000;
const SESSIONS_BROADCAST_MIN_GAP_MS = 1000;

const sseClients = new Set(); // raw http.ServerResponse objects

// Write one pre-formatted SSE payload to one client. A throwing write or a
// wedged consumer (> 4 MB buffered) gets destroyed and dropped — one slow
// reader must never block the hub or grow memory without bound. The buffer
// cap is enforced both before AND after the write, so a single large payload
// cannot sit queued past the cutoff until the next event happens to arrive.
function sseSendRaw(res, payload) {
  if (res.destroyed || res.writableEnded) {
    sseClients.delete(res);
    return;
  }
  if (res.writableLength > SSE_MAX_BUFFERED_BYTES) {
    sseClients.delete(res);
    res.destroy();
    return;
  }
  try {
    res.write(payload);
  } catch (err) {
    sseClients.delete(res);
    try { res.destroy(); } catch (e) { /* already gone */ }
    return;
  }
  if (res.writableLength > SSE_MAX_BUFFERED_BYTES) {
    sseClients.delete(res);
    res.destroy();
  }
}

// JSON.stringify output never contains raw newlines, so a single data: line
// is always a valid SSE frame.
function sseWrite(res, event, data) {
  sseSendRaw(res, `event: ${event}\ndata: ${JSON.stringify(data)}\n\n`);
}

function broadcastJson(event, json) {
  if (sseClients.size === 0) return;
  const payload = `event: ${event}\ndata: ${json}\n\n`;
  for (const res of [...sseClients]) sseSendRaw(res, payload);
}

// Stringify once, deliver to every client.
function broadcast(event, data) {
  if (sseClients.size === 0) return;
  broadcastJson(event, JSON.stringify(data));
}

function sseHeartbeat() {
  for (const res of [...sseClients]) sseSendRaw(res, ': hb\n\n');
}

// Exactly the GET /api/sessions response shape — the SSE snapshot and the
// REST route share this builder so they can never drift apart.
function sessionsSnapshot() {
  return { sessions: Array.from(sessionIndex.values()).sort(compareSessionRecords) };
}

// Suppression state for the BROADCAST path only. Per-client seeds must never
// touch these: seeding one newly connected client must not suppress (or
// delay) a later broadcast to existing clients.
let lastSessionsJson = null;
let lastSessionsSentAt = 0;
let sessionsBroadcastTimer = null;

function sendSessionsSnapshot() {
  const json = JSON.stringify(sessionsSnapshot());
  if (json === lastSessionsJson) return; // identical steady-state tick
  lastSessionsJson = json;
  lastSessionsSentAt = Date.now();
  broadcastJson('sessions', json);
}

// At most one sessions snapshot per second: leading edge when >1s has passed
// since the last send, else a trailing-edge timer coalesces the burst.
// Called from the end of every scanTick (interval- and watcher-triggered).
function scheduleSessionsBroadcast() {
  if (sessionsBroadcastTimer !== null) return; // burst already coalescing
  const since = Date.now() - lastSessionsSentAt;
  if (since >= SESSIONS_BROADCAST_MIN_GAP_MS) {
    sendSessionsSnapshot();
    return;
  }
  sessionsBroadcastTimer = setTimeout(() => {
    sessionsBroadcastTimer = null;
    sendSessionsSnapshot();
  }, SESSIONS_BROADCAST_MIN_GAP_MS - since);
}

function handleEvents(req, res) {
  res.writeHead(200, {
    ...baseHeaders(),
    'Content-Type': 'text/event-stream',
    'Cache-Control': 'no-store',
    'Connection': 'keep-alive',
  });
  req.socket.setNoDelay(true);
  res.write(': connected\n\nretry: 2000\n\n');
  sseClients.add(res);
  const drop = () => sseClients.delete(res);
  res.on('close', drop);
  res.on('error', drop);
  req.on('error', drop);
  // Per-client seed so the UI paints without racing the next tick. Written
  // directly via sseWrite — bypasses the suppression state on purpose.
  sseWrite(res, 'sessions', sessionsSnapshot());
}

// ---------------------------------------------------------------------------
// Pane mirror loop
// ---------------------------------------------------------------------------
//
// Mirrors ONE pane — the session selected in the UI (POST /api/watch) — as
// `pane` SSE events. Single global watcher by design: a new watch replaces
// the old one. Read-only by construction: the loop only ever calls
// capturePane (tmux capture-pane -p -e), which goes through
// assertControlledPane — a token holder still cannot mirror arbitrary tmux
// panes, only mapped/launched claude panes.

const PANE_POLL_MS = 600;
let watchedSessionId = null;
let watchTimer = null; // interval handle, running only while watching
let watchTickInFlight = false;
let lastPaneScreen = null; // last broadcast screen (dedupe)

function setWatch(sessionId) {
  watchedSessionId = sessionId;
  lastPaneScreen = null;
  if (sessionId === null) {
    if (watchTimer !== null) {
      clearInterval(watchTimer);
      watchTimer = null;
    }
    return;
  }
  if (watchTimer === null) watchTimer = setInterval(watchTick, PANE_POLL_MS);
  watchTick(); // immediate first paint; never rejects
}

// Never rejects. A tick that cannot capture (session ended, pane died, watch
// raced a kill, tmux hiccup) just skips — mirroring auto-resumes when the
// index/overlay catches up; the watch is never silently cleared.
async function watchTick() {
  if (watchTickInFlight) return;
  watchTickInFlight = true;
  try {
    const id = watchedSessionId; // snapshot: the watch may switch mid-tick
    if (id === null) return;
    if (sseClients.size === 0) {
      // No one to push to — skip the tmux call, and forget the dedupe state
      // so the first tick after a client (re)connects always broadcasts.
      lastPaneScreen = null;
      return;
    }
    const record = sessionIndex.get(id);
    const pane = resolveControlPane(id, record);
    if (pane === null) return;
    // Stale-mapping guard (cheap, sync): an auto-adopted claude can exit
    // back to a shell between scan ticks — never mirror that shell, even for
    // one frame. Overlay panes need no pid check here (claude IS the pane
    // command; capturePane below just fails when the pane died).
    if (record && record.live !== null && !isPidAlive(record.live.pid)) {
      scanTick(); // refresh promptly (reentrancy-guarded); skip this frame
      return;
    }
    let screen;
    try {
      screen = await capturePane(pane);
    } catch (err) {
      return; // pane vanished mid-tick (UNKNOWN_TARGET race, tmux error)
    }
    // The watch was cleared or switched while capture-pane ran: discard, or
    // a stale screen from the old pane would be attributed to the new watch.
    if (watchedSessionId !== id) return;
    if (screen === lastPaneScreen) return;
    lastPaneScreen = screen;
    broadcast('pane', { sessionId: id, screen });
  } finally {
    watchTickInFlight = false;
  }
}

// ---------------------------------------------------------------------------
// Notifications
// ---------------------------------------------------------------------------
//
// macOS notification on busy -> ready|idle, edge-triggered off the derived
// displayStatus each scan tick (shell is already folded into busy, dead PID
// into done by deriveStatus — the raw live.status is never consulted here).
// Busy phases shorter than NOTIFY_MIN_BUSY_MS never notify (flap guard), and
// each session notifies at most once per NOTIFY_DEBOUNCE_MS. busy -> done
// (process died) does not notify.

const NOTIFY_MIN_BUSY_MS = 5000;
const NOTIFY_DEBOUNCE_MS = 15000;

const notifyState = new Map(); // sessionId -> { status, busySince, lastNotifyAt }

// Human label for a record; cwd can legitimately be null (live-only or
// sparse-transcript records), hence the guard before basename.
function notificationLabel(record) {
  return record.name || record.slug ||
    (record.cwd ? path.basename(record.cwd) : null) ||
    record.sessionId.slice(0, 8);
}

// Detect notification-worthy transitions; pure apart from notifyState, and
// free of osascript/SSE so the unit harness can drive it with synthetic
// records and controlled clocks. First sight never notifies (covers server
// startup seeing already-busy sessions); lastNotifyAt: null means "never
// notified" — distinct from any real timestamp, so small controlled clocks
// behave (with 0 the first debounce check would spuriously fail for
// nowMs < NOTIFY_DEBOUNCE_MS). Sessions absent from `records` are dropped
// from notifyState (bounds memory).
function detectNotifications(records, nowMs) {
  const events = [];
  const seen = new Set();
  for (const record of records) {
    const cur = record.displayStatus;
    seen.add(record.sessionId);
    const state = notifyState.get(record.sessionId);
    if (!state) {
      notifyState.set(record.sessionId, {
        status: cur,
        busySince: cur === 'busy' ? nowMs : null,
        lastNotifyAt: null,
      });
      continue;
    }
    if (state.status !== cur) {
      if (state.status === 'busy' && (cur === 'ready' || cur === 'idle') &&
          state.busySince !== null &&
          nowMs - state.busySince >= NOTIFY_MIN_BUSY_MS &&
          (state.lastNotifyAt === null ||
            nowMs - state.lastNotifyAt >= NOTIFY_DEBOUNCE_MS)) {
        events.push({
          sessionId: record.sessionId,
          status: cur,
          title: 'Claude Control Center',
          message: `${notificationLabel(record)} is ${cur}`,
        });
        state.lastNotifyAt = nowMs;
      }
      state.status = cur;
      state.busySince = cur === 'busy' ? nowMs : null;
    }
  }
  for (const sessionId of [...notifyState.keys()]) {
    if (!seen.has(sessionId)) notifyState.delete(sessionId);
  }
  return events;
}

// Strip `"` and `\` (master-plan requirement) plus ALL control chars (a raw
// newline would break the AppleScript literal), cap at 200 chars. The
// remaining text is interpolated into a quoted AppleScript string literal
// where no metacharacters survive this filter.
function sanitizeNotificationText(str) {
  return String(str).replace(/["\\\u0000-\u001f\u007f]/g, '').slice(0, 200);
}

// Best-effort delivery via osascript (execFile argv array, never a shell).
// A machine without osascript must not crash the server: errors warn once.
function sendMacNotification(title, message) {
  const script = `display notification "${sanitizeNotificationText(message)}"` +
    ` with title "${sanitizeNotificationText(title)}"`;
  try {
    execFile('osascript', ['-e', script], { timeout: 5000 }, (err) => {
      if (err) warnOnce('osascript', `notification failed: ${err.message}`);
    });
  } catch (err) {
    warnOnce('osascript', `notification failed: ${err.message}`);
  }
}

// Single delivery point for both channels: macOS notification + the SSE
// `notify` event reserved by Part 4.
function fireNotifications(events) {
  for (const event of events) {
    sendMacNotification(event.title, event.message);
    broadcast('notify', {
      sessionId: event.sessionId,
      status: event.status,
      title: event.title,
      message: event.message,
      ts: Date.now(),
    });
  }
}

// ---------------------------------------------------------------------------
// API router — later parts add entries here.
// ---------------------------------------------------------------------------

function handleListSessions(req, res) {
  sendJson(res, 200, sessionsSnapshot());
}

function handleGetSession(req, res, url, match) {
  const record = sessionIndex.get(match[1]);
  if (!record) {
    sendJson(res, 404, { error: 'unknown session' });
    return;
  }
  sendJson(res, 200, record);
}

// Seed entries for one session's transcript; live updates then arrive as SSE
// `transcript` events, with the seed/stream overlap deduped client-side by
// uuid. transcriptPath comes exclusively from our own scanner (never from
// request input), so only real transcript files under PROJECTS_DIR are read.
async function handleGetTranscript(req, res, url, match) {
  const record = sessionIndex.get(match[1]);
  if (!record) {
    sendJson(res, 404, { error: 'unknown session' });
    return;
  }
  if (record.transcriptPath === null) {
    // Live session with no transcript on disk yet.
    sendJson(res, 200, { sessionId: record.sessionId, entries: [] });
    return;
  }
  let tailKb = 64;
  const raw = url.searchParams.get('tailKb');
  if (typeof raw === 'string' && /^\d+$/.test(raw)) {
    tailKb = Math.min(1024, Math.max(1, Number.parseInt(raw, 10)));
  }
  const entries = await readTailSeed(record.transcriptPath, tailKb);
  sendJson(res, 200, { sessionId: record.sessionId, entries });
}

// Task list for one session. getTasks re-validates the id and maps a missing
// tasks dir to [] — a session that never used tasks returns tasks: [].
function handleGetTasks(req, res, url, match) {
  if (!sessionIndex.has(match[1])) {
    sendJson(res, 404, { error: 'unknown session' });
    return;
  }
  sendJson(res, 200, { sessionId: match[1], tasks: getTasks(match[1]) });
}

function handleGetStats(req, res) {
  sendJson(res, 200, computeStats(Date.now()));
}

// Union of ~/.claude.json .projects keys + real cwds from the transcript
// index (JSONL content — encoded dir names are never decoded). Live-only
// sessions' cwds are deliberately not included (per the part spec).
async function handleGetProjects(req, res) {
  const set = new Set(await readProjectKeys());
  for (const summary of transcriptBySession.values()) {
    // Same gate as the config keys: absolute paths only, so a corrupt JSONL
    // cwd can never put a relative/garbage string into this API.
    if (typeof summary.cwd === 'string' && path.isAbsolute(summary.cwd)) {
      set.add(summary.cwd);
    }
  }
  sendJson(res, 200, { projects: [...set].sort() });
}

// ---------------------------------------------------------------------------
// Control endpoints (POST prompt/keys/kill/new/watch)
// ---------------------------------------------------------------------------

// A 256 KB prompt can legally JSON-escape to ~1.5 MB, hence the headroom.
const MAX_BODY_BYTES = 2 * 1024 * 1024;

// Accumulate the request body with a hard byte cap. On overflow the request
// is paused but NOT destroyed — the route layer responds 413 first (so the
// client sees JSON, not a connection reset) and tears the socket down after.
// `discard: true` skips accumulation (bounded drain for body-less routes).
function readBodyBuffer(req, { discard = false } = {}) {
  return new Promise((resolve, reject) => {
    let settled = false; // exactly one of resolve/reject ever runs
    const fail = (code, message) => {
      if (settled) return;
      settled = true;
      const err = new Error(message);
      err.code = code;
      reject(err);
    };
    const len = req.headers['content-length'];
    if (typeof len === 'string' && /^\d+$/.test(len) &&
        Number.parseInt(len, 10) > MAX_BODY_BYTES) {
      fail('BODY_TOO_LARGE', 'request body too large');
      return; // no data listener — the stream never flows
    }
    const chunks = [];
    let total = 0;
    const onData = (chunk) => {
      total += chunk.length;
      if (total > MAX_BODY_BYTES) {
        req.removeListener('data', onData); // stop consuming
        req.pause();
        fail('BODY_TOO_LARGE', 'request body too large');
        return;
      }
      if (!discard) chunks.push(chunk);
    };
    req.on('data', onData);
    req.on('end', () => {
      if (settled) return;
      settled = true;
      resolve(Buffer.concat(chunks));
    });
    req.on('error', () => fail('ABORTED', 'request aborted'));
    // 'close' before 'end' = client aborted mid-upload. On a normal request
    // 'close' fires after 'end', where the settled guard makes this a no-op.
    req.on('close', () => fail('ABORTED', 'request aborted'));
  });
}

// Body must parse to a plain JSON object (not array/null). No Content-Type
// enforcement: the X-CCC-Token requirement already blocks cross-origin
// browser POSTs (custom headers force a CORS preflight we never approve).
async function readJsonBody(req) {
  const buf = await readBodyBuffer(req);
  const parsed = safeJsonParse(buf.toString('utf8'));
  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
    const err = new Error('request body must be a JSON object');
    err.code = 'BAD_JSON';
    throw err;
  }
  return parsed;
}

// Bounded drain for /kill: a side-effect endpoint must not be an unmetered
// sink. Overflow still rejects BODY_TOO_LARGE; content is discarded.
async function drainBody(req) {
  await readBodyBuffer(req, { discard: true });
}

// Error -> HTTP mapping for every control handler's catch. Anything untagged
// is a tmux/launch failure: 502 with the (secret-free) detail — tmux stderr
// or our own launch messages.
function sendControlError(res, err) {
  const code = err && err.code;
  if (code === 'BODY_TOO_LARGE') {
    // Answer first, then cut: the client may still be streaming the
    // oversized body, and this connection cannot be reused.
    if (!res.headersSent) {
      const body = JSON.stringify({ error: 'request body too large' });
      res.writeHead(413, {
        ...baseHeaders(),
        'Content-Type': 'application/json; charset=utf-8',
        'Cache-Control': 'no-store',
        'Content-Length': Buffer.byteLength(body),
        'Connection': 'close',
      });
      res.end(body, () => res.destroy());
    } else {
      res.destroy();
    }
    return;
  }
  if (code === 'ABORTED') {
    // Client is gone: nothing to say, no JSON.
    if (!res.headersSent) res.destroy();
    else res.end();
    return;
  }
  if (code === 'BAD_JSON' || code === 'BAD_INPUT' || code === 'BAD_KEY') {
    sendJson(res, 400, { error: err.message });
    return;
  }
  if (code === 'UNKNOWN_TARGET') {
    sendJson(res, 409, { error: 'pane no longer controllable' });
    return;
  }
  sendJson(res, 502, { error: 'tmux operation failed', detail: err.message });
}

const PLAIN_TERMINAL_ERROR =
  'running in a plain terminal — view only (relaunch with `ccc claude` to control)';

// Resume launches in flight, keyed by sessionId. Added before launchSession,
// removed after the overlay entry is written — so there is no gap in which a
// concurrent prompt to the same done session could launch a second resume.
const resumesInFlight = new Set();

// Mutating-op guard for panes resolved from a LIVE record: the pid -> pane
// mapping is at most one scan tick (~2s) old, and an auto-adopted claude can
// exit within that window leaving e.g. the user's shell in the same pane —
// pasting text+Enter there must not be possible. Re-check at op time: the
// pid must be alive AND, when the session file recorded the process start
// time, still match `ps lstart` (the scanner's PID-reuse guard, re-run here
// so an op cannot ride a pid recycled between ticks; ps failure skips the
// lstart half, same as the scanner). Stale -> UNKNOWN_TARGET (409 "pane no
// longer controllable") + an immediate rescan. Overlay-launched panes need
// no check here: claude IS the pane command, so its exit destroys the pane
// and tmux itself errors out.
async function assertLiveRecordPid(record) {
  if (!record || record.live === null) return;
  const pid = record.live.pid;
  let alive = isPidAlive(pid);
  if (alive) {
    const liveEntry = liveBySession.get(record.sessionId);
    const procStart = liveEntry && liveEntry.pid === pid ? liveEntry.procStart : null;
    if (procStart !== null) {
      const lstartByPid = await psLstartByPid([pid]);
      if (lstartByPid !== null) {
        const liveLstart = lstartByPid.get(pid);
        if (liveLstart === undefined ||
            normalizeWhitespace(procStart) !== normalizeWhitespace(liveLstart)) {
          alive = false; // PID reused by an unrelated process
        }
      }
    }
  }
  if (alive) return;
  scanTick(); // refresh the index promptly; never rejects
  const err = new Error(`live claude exited: session ${record.sessionId}`);
  err.code = 'UNKNOWN_TARGET';
  throw err;
}

function recordLaunchOverlay(sessionId, launched) {
  launchOverlay.set(sessionId, {
    paneId: launched.tmuxTarget,
    label: launched.tmuxLabel,
    serverPid: launched.serverPid,
    launchedAt: Date.now(),
  });
}

// POST /api/sessions/:id/prompt {prompt} — paste+Enter into the session's
// pane; done sessions resume into a new ccc-* tmux session first.
async function handlePostPrompt(req, res, url, match) {
  const sessionId = match[1];
  try {
    const body = await readJsonBody(req);
    const prompt = body.prompt;
    if (typeof prompt !== 'string' || prompt === '') {
      sendJson(res, 400, { error: 'prompt must be a non-empty string' });
      return;
    }
    if (Buffer.byteLength(prompt, 'utf8') > MAX_PROMPT_BYTES) {
      sendJson(res, 400, { error: 'prompt too large' });
      return;
    }
    // Checked BEFORE pane resolution: while a resume launch is in flight, a
    // scan tick may already have adopted the new pane — sending there now
    // could land this prompt ahead of the resume's own initialPrompt (or
    // type into claude's startup/trust UI). Every concurrent prompt 409s
    // until launchSession returns and the overlay entry is written.
    if (resumesInFlight.has(sessionId)) {
      sendJson(res, 409, { error: 'resume already in progress' });
      return;
    }
    const record = sessionIndex.get(sessionId);
    const pane = resolveControlPane(sessionId, record);
    if (pane !== null) {
      // Live+tmux, or just launched/resumed and still in the overlay — a
      // second prompt to a just-resumed session lands here, never in the
      // resume flow below (no double resume). enqueuePaneOp serializes
      // concurrent prompts; a busy claude just queues the paste.
      // assertLiveRecordPid runs as the in-queue preflight so the guard is
      // still fresh even when this prompt waited behind earlier pane ops.
      await sendPrompt(pane, prompt, { preflight: () => assertLiveRecordPid(record) });
      sendJson(res, 200, {
        ok: true, sessionId, tmuxTarget: pane, resumed: false, promptSent: true,
      });
      return;
    }
    if (!record) {
      sendJson(res, 404, { error: 'unknown session' });
      return;
    }
    if (record.live !== null) {
      sendJson(res, 409, { error: PLAIN_TERMINAL_ERROR });
      return;
    }
    // Done session: resume it into a new ccc-* tmux session.
    if (record.cwd === null) {
      sendJson(res, 409, { error: 'cannot resume: session cwd unknown' });
      return;
    }
    resumesInFlight.add(sessionId);
    let launched;
    try {
      // launchSession polls for the session file and sends the prompt once
      // claude reports ready/idle. A thrown launch writes no overlay entry
      // (the pane, if any, stays reachable only via `tmux attach`).
      launched = await launchSession({
        cwd: record.cwd,
        resumeSessionId: sessionId,
        initialPrompt: prompt,
      });
      recordLaunchOverlay(sessionId, launched);
    } finally {
      resumesInFlight.delete(sessionId);
    }
    scanTick(); // latency only — correctness does not depend on it
    // promptSent: false = pane matched but never reached ready/idle within
    // launchSession's budget (e.g. trust-folder dialog). The pane is still
    // controllable via the overlay: watch it, answer via /keys, re-prompt.
    sendJson(res, 200, {
      ok: true,
      sessionId,
      tmuxTarget: launched.tmuxTarget,
      resumed: true,
      promptSent: launched.promptSent,
    });
  } catch (err) {
    sendControlError(res, err);
  }
}

// POST /api/sessions/:id/keys {key} — whitelisted key into the pane (answer
// dialogs, Esc interrupt, arrows).
async function handlePostKeys(req, res, url, match) {
  const sessionId = match[1];
  try {
    const body = await readJsonBody(req);
    const key = body.key;
    // Whitelist check BEFORE any tmux/target work; sendKeys re-checks as
    // defense in depth.
    if (typeof key !== 'string' || !KEY_WHITELIST.has(key)) {
      sendJson(res, 400, { error: 'key not in whitelist' });
      return;
    }
    const record = sessionIndex.get(sessionId);
    const pane = resolveControlPane(sessionId, record);
    if (pane === null) {
      if (!record) sendJson(res, 404, { error: 'unknown session' });
      else if (record.live !== null) sendJson(res, 409, { error: PLAIN_TERMINAL_ERROR });
      else sendJson(res, 409, { error: 'session is not tmux-controllable' });
      return;
    }
    // In-queue preflight — see handlePostPrompt.
    await sendKeys(pane, key, { preflight: () => assertLiveRecordPid(record) });
    sendJson(res, 200, { ok: true });
  } catch (err) {
    sendControlError(res, err);
  }
}

// POST /api/sessions/:id/kill — kill the pane of a tmux-backed session;
// 404 otherwise (master-plan contract). Body content is ignored.
async function handlePostKill(req, res, url, match) {
  const sessionId = match[1];
  try {
    await drainBody(req);
    const record = sessionIndex.get(sessionId);
    const pane = resolveControlPane(sessionId, record);
    if (pane === null) {
      sendJson(res, 404, { error: 'not a tmux-backed session' });
      return;
    }
    // Same stale-mapping guard as prompt/keys: if the mapped claude already
    // exited, killing the pane could destroy whatever now runs there (the
    // user's shell) — 409 instead; the next scan drops the row to done.
    await assertLiveRecordPid(record);
    await killPane(pane);
    launchOverlay.delete(sessionId);
    scanTick(); // drop the row to done quickly. If this was the watched
    // session, the mirror loop degrades to no-op ticks — no special casing.
    sendJson(res, 200, { ok: true });
  } catch (err) {
    sendControlError(res, err);
  }
}

// POST /api/sessions/new {cwd, prompt?} — launch a fresh claude (with a
// --session-id uuid chosen inside launchSession) in a new ccc-* tmux session.
async function handleNewSession(req, res) {
  try {
    const body = await readJsonBody(req);
    if (typeof body.cwd !== 'string') {
      sendJson(res, 400, { error: 'cwd must be a string' });
      return;
    }
    let prompt = null; // absent/null -> no initial prompt
    if (body.prompt !== undefined && body.prompt !== null) {
      if (typeof body.prompt !== 'string' || body.prompt === '') {
        sendJson(res, 400, { error: 'prompt must be a non-empty string' });
        return;
      }
      if (Buffer.byteLength(body.prompt, 'utf8') > MAX_PROMPT_BYTES) {
        sendJson(res, 400, { error: 'prompt too large' });
        return;
      }
      prompt = body.prompt;
    }
    // launchSession enforces absolute + exists + directory (BAD_INPUT -> 400).
    const launched = await launchSession({ cwd: body.cwd, initialPrompt: prompt });
    // Overlay entry so /watch, /keys, /prompt work immediately, before the
    // index has any record of the new session.
    recordLaunchOverlay(launched.sessionId, launched);
    scanTick();
    sendJson(res, 201, {
      sessionId: launched.sessionId,
      tmuxTarget: launched.tmuxTarget,
      promptSent: launched.promptSent,
    });
  } catch (err) {
    sendControlError(res, err);
  }
}

// POST /api/watch {sessionId|null} — select THE pane the server mirrors.
// The key must be explicit: null clears, a valid id switches, absent is 400.
async function handleWatch(req, res) {
  try {
    const body = await readJsonBody(req);
    const sessionId = body.sessionId;
    if (sessionId === null) {
      setWatch(null);
      sendJson(res, 200, { watching: null });
      return;
    }
    if (typeof sessionId !== 'string' || !SESSION_ID_RE.test(sessionId)) {
      sendJson(res, 400, { error: 'sessionId must be null or a session id string' });
      return;
    }
    const record = sessionIndex.get(sessionId);
    const pane = resolveControlPane(sessionId, record);
    if (pane === null) {
      // An overlay entry implies pane !== null, so reaching here with no
      // record means the session is unknown everywhere.
      if (!record) sendJson(res, 404, { error: 'unknown session' });
      else sendJson(res, 409, { error: 'session is not tmux-controllable' });
      return;
    }
    setWatch(sessionId);
    sendJson(res, 200, { watching: sessionId });
  } catch (err) {
    sendControlError(res, err);
  }
}

const API_ROUTES = {
  'GET /api/ping': (req, res, url) => sendJson(res, 200, { ok: true, now: Date.now() }),
  'GET /api/sessions': handleListSessions,
  'GET /api/events': handleEvents,
  'GET /api/stats': handleGetStats,
  'GET /api/projects': handleGetProjects,
  // Exact match runs before the pattern routes, so a hypothetical session id
  // "new" cannot collide with this route.
  'POST /api/sessions/new': handleNewSession,
  'POST /api/watch': handleWatch,
};

// Consulted only after the exact-match lookup misses. The capture group is
// SESSION_ID_PATTERN — the same strict charset enforced at index admission —
// so no percent-decoding concerns and nothing path-unsafe ever reaches a
// handler. Empty ids and deeper paths fall through to the 404.
const API_PATTERN_ROUTES = [
  {
    method: 'GET',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})$`),
    handler: handleGetSession,
  },
  {
    method: 'GET',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})/transcript$`),
    handler: handleGetTranscript,
  },
  {
    method: 'GET',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})/tasks$`),
    handler: handleGetTasks,
  },
  {
    method: 'POST',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})/prompt$`),
    handler: handlePostPrompt,
  },
  {
    method: 'POST',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})/keys$`),
    handler: handlePostKeys,
  },
  {
    method: 'POST',
    pattern: new RegExp(`^/api/sessions/(${SESSION_ID_PATTERN})/kill$`),
    handler: handlePostKill,
  },
];

// ---------------------------------------------------------------------------
// Main handler
// ---------------------------------------------------------------------------

// Error boundary for API handlers (sync throws and rejected promises alike):
// log internally, return a generic 500 if possible, and always terminate the
// response so no socket is left hanging.
function handleApiError(res, err) {
  console.error(`ccc: api handler error: ${(err && err.stack) || err}`);
  if (!res.headersSent) sendJson(res, 500, { error: 'internal error' });
  else res.end();
}

function handleRequest(req, res) {
  // Accept only origin-form request targets ("/path?query"). This rejects
  // absolute-form and network-path targets like "//evil.test/api/ping" that
  // the WHATWG URL parser would otherwise interpret as a different host.
  if (typeof req.url !== 'string' || !req.url.startsWith('/') || req.url.startsWith('//')) {
    sendJson(res, 400, { error: 'bad request' });
    return;
  }

  let url;
  try {
    url = new URL(req.url, 'http://127.0.0.1');
  } catch (err) {
    sendJson(res, 400, { error: 'bad request' });
    return;
  }

  // Host check runs before everything else, including static.
  if (!isAllowedHost(req.headers.host)) {
    sendJson(res, 403, { error: 'forbidden host' });
    return;
  }

  if (url.pathname === '/api' || url.pathname.startsWith('/api/')) {
    if (!checkToken(req, url)) {
      sendJson(res, 401, { error: 'unauthorized' });
      return;
    }
    let handler = API_ROUTES[`${req.method} ${url.pathname}`];
    let match = null;
    if (!handler) {
      for (const route of API_PATTERN_ROUTES) {
        if (route.method !== req.method) continue;
        const m = route.pattern.exec(url.pathname);
        if (m) {
          handler = route.handler;
          match = m;
          break;
        }
      }
    }
    if (!handler) {
      sendJson(res, 404, { error: 'unknown api route' });
      return;
    }
    try {
      Promise.resolve(handler(req, res, url, match)).catch((err) => handleApiError(res, err));
    } catch (err) {
      handleApiError(res, err);
    }
    return;
  }

  serveStatic(req, res, url.pathname);
}

// ---------------------------------------------------------------------------
// Watchers
// ---------------------------------------------------------------------------
//
// fs.watch is used at directory level only (reliable on macOS; per-file
// watches are not). Handlers ignore the eventType/filename arguments
// entirely and re-examine the directory — the only pattern that behaves
// across platforms (macOS may report 'rename' for everything). Watchers are
// purely a latency optimization: the safety pump at the end of every
// scanTick guarantees delivery within ~2s even with zero working watchers.

const WATCH_DEBOUNCE_MS = 120;
const WATCHER_REFRESH_MS = 30000;

const debounceTimers = new Map(); // key -> Timeout (trailing edge)

// Trailing-edge debounce. fn may be async; a throw/rejection is logged,
// never fatal (these fire from watcher callbacks and timers).
function debounced(key, ms, fn) {
  const existing = debounceTimers.get(key);
  if (existing !== undefined) clearTimeout(existing);
  debounceTimers.set(key, setTimeout(() => {
    debounceTimers.delete(key);
    try {
      Promise.resolve(fn()).catch((err) => {
        console.error(`ccc: ${key} failed: ${(err && err.stack) || err}`);
      });
    } catch (err) {
      console.error(`ccc: ${key} failed: ${(err && err.stack) || err}`);
    }
  }, ms));
}

// fs.watch with error hygiene: an unhandled FSWatcher 'error' event would
// crash the process, so every watcher closes itself and reports through
// onGone; the 30s refresh recreates it if the directory still exists.
// Returns null when the directory cannot be watched (e.g. does not exist).
function watchDir(dirPath, onEvent, onGone) {
  let watcher;
  try {
    watcher = fs.watch(dirPath, () => {
      try {
        onEvent();
      } catch (err) {
        console.error(`ccc: watch handler for ${dirPath} failed: ${(err && err.stack) || err}`);
      }
    });
  } catch (err) {
    return null;
  }
  watcher.on('error', () => {
    try { watcher.close(); } catch (err) { /* already closed */ }
    onGone();
  });
  return watcher;
}

// Pump every transcript in one project dir (one transcript event per file
// per pump), then schedule an index refresh — tokens/lastTs/status come from
// the scanner, so the sessions snapshot must follow real index data. Never
// rejects.
async function pumpProjectDir(dirPath) {
  let dirents = [];
  try {
    dirents = await fsp.readdir(dirPath, { withFileTypes: true });
  } catch (err) {
    return; // dir vanished — the watcher refresh will drop its watcher
  }
  for (const f of dirents) {
    if (!f.isFile() || !f.name.endsWith('.jsonl')) continue;
    const sessionId = path.basename(f.name, '.jsonl');
    if (!SESSION_ID_RE.test(sessionId)) continue;
    const entries = await pumpTail(path.join(dirPath, f.name));
    if (entries.length > 0) broadcast('transcript', { sessionId, entries });
  }
  debounced('scan tick', WATCH_DEBOUNCE_MS, scanTick);
}

const projectDirWatchers = new Map(); // dirPath -> FSWatcher
let sessionsDirWatcher = null;
let projectsParentWatcher = null;
let watcherRefreshInFlight = false;

// Create/close per-project-dir watchers to match the live directory listing.
// A NEW dir gets one immediate catch-up pump — files created before its
// watcher attached produce no events, so this pump is what makes brand-new
// project dirs stream. Reentrancy-guarded (startup + 30s interval + parent
// watch can overlap).
async function refreshProjectWatchers() {
  if (watcherRefreshInFlight) return;
  watcherRefreshInFlight = true;
  try {
    let dirents = [];
    try {
      dirents = await fsp.readdir(PROJECTS_DIR, { withFileTypes: true });
    } catch (err) {
      warnOnce('projects-watch', `cannot watch project dirs: ${err.message}`);
      dirents = [];
    }
    const seen = new Set();
    for (const d of dirents) {
      if (!d.isDirectory()) continue;
      const dirPath = path.join(PROJECTS_DIR, d.name);
      seen.add(dirPath);
      if (projectDirWatchers.has(dirPath)) continue;
      const watcher = watchDir(
        dirPath,
        () => debounced(`pump ${dirPath}`, WATCH_DEBOUNCE_MS, () => pumpProjectDir(dirPath)),
        () => projectDirWatchers.delete(dirPath)
      );
      if (watcher === null) continue; // vanished between readdir and watch
      projectDirWatchers.set(dirPath, watcher);
      await pumpProjectDir(dirPath); // catch-up for pre-watcher files
    }
    for (const [dirPath, watcher] of projectDirWatchers) {
      if (seen.has(dirPath)) continue;
      try { watcher.close(); } catch (err) { /* already closed */ }
      projectDirWatchers.delete(dirPath);
    }
  } finally {
    watcherRefreshInFlight = false;
  }
}

// Root watchers: SESSIONS_DIR events feed the debounced scanTick (~120ms
// status latency; the 2s interval stays as the safety net for PID deaths),
// and PROJECTS_DIR events re-run dir discovery so brand-new project dirs are
// picked up in ~120ms instead of <=30s. Missing dirs are retried every 30s.
function ensureRootWatchers() {
  if (sessionsDirWatcher === null) {
    sessionsDirWatcher = watchDir(
      SESSIONS_DIR,
      () => debounced('scan tick', WATCH_DEBOUNCE_MS, scanTick),
      () => { sessionsDirWatcher = null; }
    );
    if (sessionsDirWatcher === null) {
      warnOnce('sessions-watch', `cannot watch sessions dir: ${SESSIONS_DIR}`);
    }
  }
  if (projectsParentWatcher === null) {
    projectsParentWatcher = watchDir(
      PROJECTS_DIR,
      () => debounced('refresh watchers', WATCH_DEBOUNCE_MS, refreshProjectWatchers),
      () => { projectsParentWatcher = null; }
    );
    if (projectsParentWatcher === null) {
      warnOnce('projects-parent-watch', `cannot watch projects dir: ${PROJECTS_DIR}`);
    }
  }
}

// Missed-event insurance, run at the end of every scanTick (after
// scanTranscripts has refreshed transcriptCache, which stats every transcript
// each scan — zero extra stats here): pump any transcript whose cached size
// disagrees with its tail offset — a MISSING state counts as needing a pump,
// which is what makes brand-new files stream from byte 0 with zero working
// watchers — and any tailed path that vanished from the cache (lets pumpTail
// observe ENOENT and drop the state). Offsets make this idempotent: when a
// watcher already pumped, size === offset and nothing happens.
async function safetyPumpTails() {
  for (const [filePath, cached] of transcriptCache) {
    const state = tailStates.get(filePath);
    if (state && state.offset === cached.size) continue;
    const entries = await pumpTail(filePath);
    if (entries.length > 0) {
      broadcast('transcript', { sessionId: path.basename(filePath, '.jsonl'), entries });
    }
  }
  for (const filePath of [...tailStates.keys()]) {
    if (transcriptCache.has(filePath)) continue;
    const entries = await pumpTail(filePath);
    if (entries.length > 0) {
      broadcast('transcript', { sessionId: path.basename(filePath, '.jsonl'), entries });
    }
  }
}

// ---------------------------------------------------------------------------
// Startup
// ---------------------------------------------------------------------------

const server = http.createServer(handleRequest);

// Periodic rescan (also triggered, debounced, by the watchers). The entire
// tick body sits inside try/finally so a thrown or rejected scan can neither
// crash the process via unhandled rejection nor wedge inFlight and freeze
// updates. Steady-state transcript scans are stat-only for unchanged files.
let scanInFlight = false;
async function scanTick() {
  if (scanInFlight) return;
  scanInFlight = true;
  try {
    await scanLiveSessions();
    await mapPanes(); // consumes liveBySession; never throws
    // Before rebuildIndex, so deleted overlay entries and the record
    // fallbacks copied from them disappear in the same tick.
    cleanupLaunchOverlay(Date.now());
    await scanTranscripts();
    rebuildIndex();
    // Edge-triggered off derived statuses, so the watcher-debounced extra
    // ticks are harmless (no transition -> no event).
    fireNotifications(detectNotifications(sessionIndex.values(), Date.now()));
    await safetyPumpTails(); // never rejects
    scheduleSessionsBroadcast();
  } catch (err) {
    console.error(`ccc: scan tick failed: ${(err && err.stack) || err}`);
  } finally {
    scanInFlight = false;
  }
}

if (require.main === module) {
  server.on('error', (err) => {
    console.error(`ccc: failed to listen on 127.0.0.1:${PORT}: ${err.code || err.message}`);
    process.exit(1);
  });

  (async () => {
    // Initial scan completes before listen so the first paint always has data.
    await scanTranscripts();
    // Seed tail offsets at EOF for every transcript known at startup (zero
    // extra stats — the scanner just cached the sizes). History is served by
    // the seed route, never replayed over SSE; files appearing later get
    // their states from watchers / the safety pump and stream from byte 0.
    for (const [filePath, cached] of transcriptCache) {
      tailStates.set(filePath, {
        offset: cached.size,
        partial: Buffer.alloc(0),
        sessionId: cached.summary.sessionId,
      });
    }
    await scanLiveSessions();
    await mapPanes();
    cleanupLaunchOverlay(Date.now()); // no-op at boot; keeps the invariant
    rebuildIndex();
    // Seed notifyState now (first sight never notifies), so a session busy
    // at boot starts its busySince clock immediately rather than on the
    // first interval tick.
    detectNotifications(sessionIndex.values(), Date.now());
    setInterval(scanTick, LIVE_SCAN_INTERVAL_MS);
    // Watchers + heartbeat live only here: module consumers (smoke tests)
    // stay side-effect free.
    ensureRootWatchers();
    refreshProjectWatchers(); // never rejects; catch-up pumps are no-ops now
    setInterval(() => {
      ensureRootWatchers();
      refreshProjectWatchers();
    }, WATCHER_REFRESH_MS);
    setInterval(sseHeartbeat, SSE_HEARTBEAT_MS);
    server.listen(PORT, '127.0.0.1', () => {
      console.log('Claude Control Center');
      console.log(`http://127.0.0.1:${PORT}/?token=${TOKEN}`);
    });
  })().catch((err) => {
    console.error(`ccc: startup failed: ${(err && err.stack) || err}`);
    process.exit(1);
  });
}

// For smoke tests: require('./server.js') exposes the scanners without
// starting the server or the interval (see require.main guard above).
module.exports = {
  scanTranscripts,
  scanLiveSessions,
  rebuildIndex,
  deriveStatus,
  getTasks,
  sessionIndex,
  mapPanes,
  capturePane,
  sendPrompt,
  sendKeys,
  launchSession,
  killPane,
  pickSessionName,
  findLaunchedSessionFile,
  getTmuxTargets: () => tmuxTargetByPid,
  readTailSeed,
  pumpTail,
  toWireEntry,
  broadcast,
  computeStats,
  dayKey,
  readProjectKeys,
  detectNotifications,
  fireNotifications,
  sendMacNotification,
  sanitizeNotificationText,
  notifyState,
  setWatch,
  getWatchedSessionId: () => watchedSessionId,
  launchOverlay,
};