codewake 0.0.1

package/lib/jobs.js

@@ -0,0 +1,327 @@
+import { spawnSync } from 'node:child_process';
+import {
+  chmodSync,
+  createWriteStream,
+  existsSync,
+  mkdirSync,
+  readdirSync,
+  readFileSync,
+  rmSync,
+  writeFileSync,
+} from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { which } from './agents.js';
+import { spawnAgent } from './proc.js';
+
+const CLI_BIN = fileURLToPath(new URL('../bin/codewake.js', import.meta.url));
+const OVERDUE_GRACE_MS = 60_000;
+const DEFAULT_POLL_MS = 60_000;
+
+/** Job state directory, per platform convention. */
+export function stateDir(env = process.env) {
+  if (env.CODEWAKE_STATE_DIR) return resolve(env.CODEWAKE_STATE_DIR);
+  if (process.platform === 'win32') {
+    const base = env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+    return join(base, 'codewake');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Application Support', 'codewake');
+  }
+  const base = env.XDG_STATE_HOME || join(homedir(), '.local', 'state');
+  return join(base, 'codewake');
+}
+
+/** Where job execution logs go, per platform convention. */
+export function logsDir(env = process.env) {
+  if (env.CODEWAKE_STATE_DIR) return join(resolve(env.CODEWAKE_STATE_DIR), 'logs');
+  if (process.platform === 'win32') {
+    const base = env.LOCALAPPDATA || join(homedir(), 'AppData', 'Local');
+    return join(base, 'codewake', 'Logs');
+  }
+  if (process.platform === 'darwin') {
+    return join(homedir(), 'Library', 'Logs', 'codewake');
+  }
+  const base = env.XDG_STATE_HOME || join(homedir(), '.local', 'state');
+  return join(base, 'codewake', 'logs');
+}
+
+function assertJobId(jobId) {
+  if (!jobId || !/^[a-z0-9-]+$/i.test(jobId)) throw new Error('Provide a valid job id.');
+  return jobId;
+}
+
+export function jobFile(jobId, env = process.env) {
+  return join(stateDir(env), `${assertJobId(jobId)}.json`);
+}
+
+export function logFile(jobId, env = process.env) {
+  return join(logsDir(env), `${assertJobId(jobId)}.log`);
+}
+
+function unitName(jobId) {
+  return `codewake-${jobId}`;
+}
+
+export function makeJobId() {
+  return `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+}
+
+function ensureDir(dir) {
+  mkdirSync(dir, { recursive: true, mode: 0o700 });
+  try {
+    // mkdirSync does not tighten a pre-existing directory.
+    chmodSync(dir, 0o700);
+  } catch {
+    // Best effort (e.g. Windows).
+  }
+}
+
+export function saveJob(job, env = process.env) {
+  ensureDir(stateDir(env));
+  writeFileSync(jobFile(job.id, env), `${JSON.stringify(job, null, 2)}\n`, { mode: 0o600 });
+  return job;
+}
+
+export function loadJob(jobId, env = process.env) {
+  const path = jobFile(jobId, env);
+  if (!existsSync(path)) throw new Error(`Job ${jobId} does not exist.`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+export function listJobs(env = process.env) {
+  const dir = stateDir(env);
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir)
+    .filter((file) => file.endsWith('.json'))
+    .map((file) => JSON.parse(readFileSync(join(dir, file), 'utf8')))
+    .sort((a, b) => Date.parse(b.createdAt) - Date.parse(a.createdAt));
+}
+
+/** Remove finished jobs (done/failed/cancelled) and their logs. */
+export function clearJobs(env = process.env) {
+  const removed = [];
+  for (const job of listJobs(env)) {
+    if (['done', 'failed', 'cancelled'].includes(job.status)) {
+      rmSync(jobFile(job.id, env), { force: true });
+      rmSync(logFile(job.id, env), { force: true });
+      removed.push(job);
+    }
+  }
+  return removed;
+}
+
+export function pickBackend(env = process.env) {
+  if (env.CODEWAKE_BACKEND === 'systemd' || env.CODEWAKE_BACKEND === 'spawn') {
+    return env.CODEWAKE_BACKEND;
+  }
+  return process.platform === 'linux' && which('systemd-run', env) ? 'systemd' : 'spawn';
+}
+
+/** Pending job already scheduled for the same agent session, if any. */
+export function findPendingForSession(agentId, sessionId, env = process.env) {
+  if (!sessionId) return null;
+  return listJobs(env).find(
+    (job) => job.status === 'pending' && job.agentId === agentId && job.sessionId === sessionId,
+  ) ?? null;
+}
+
+/**
+ * Persist and arm a job. `spec` carries agent/bin/args/mode/sessionId/
+ * prompt/skipPermissions/project/runAt. With `dryRun` nothing is written.
+ */
+export function scheduleJob(spec, { dryRun = false, env = process.env } = {}) {
+  const now = Date.now();
+  const runAt = spec.runAt instanceof Date ? spec.runAt : new Date(spec.runAt ?? now);
+  if (!existsSync(spec.project)) throw new Error(`Project directory does not exist: ${spec.project}`);
+  const duplicate = findPendingForSession(spec.agent.id, spec.sessionId ?? null, env);
+  if (duplicate) {
+    throw new Error(
+      `Session ${spec.sessionId} already has a pending job (${duplicate.id}, launching ${new Date(duplicate.runAt).toLocaleString()}). ` +
+      `Cancel it first with "codewake cancel ${duplicate.id}".`,
+    );
+  }
+  const job = {
+    id: makeJobId(),
+    agentId: spec.agent.id,
+    agentName: spec.agent.name,
+    bin: spec.bin,
+    args: spec.args,
+    mode: spec.mode,
+    sessionId: spec.sessionId ?? null,
+    prompt: spec.prompt,
+    skipPermissions: Boolean(spec.skipPermissions),
+    project: spec.project,
+    createdAt: new Date(now).toISOString(),
+    runAt: runAt.toISOString(),
+    backend: pickBackend(env),
+    status: 'pending',
+  };
+  if (dryRun) return job;
+  saveJob(job, env);
+  try {
+    if (job.backend === 'systemd') armSystemdTimer(job, now);
+    else armDetachedWaiter(job, env);
+  } catch (error) {
+    rmSync(jobFile(job.id, env), { force: true });
+    throw error;
+  }
+  return job;
+}
+
+/** "YYYY-MM-DD HH:MM:SS" in local time, for systemd's OnCalendar. */
+export function systemdCalendarSpec(runAtMs, now = Date.now()) {
+  // Wall-clock timers keep ticking through suspend and fire on resume;
+  // --on-active uses the monotonic clock, which pauses while suspended.
+  const at = new Date(Math.max(runAtMs, now + 5000));
+  const pad = (value) => String(value).padStart(2, '0');
+  return `${at.getFullYear()}-${pad(at.getMonth() + 1)}-${pad(at.getDate())} ` +
+    `${pad(at.getHours())}:${pad(at.getMinutes())}:${pad(at.getSeconds())}`;
+}
+
+function armSystemdTimer(job, now) {
+  const result = spawnSync('systemd-run', [
+    '--user',
+    `--unit=${unitName(job.id)}`,
+    `--on-calendar=${systemdCalendarSpec(Date.parse(job.runAt), now)}`,
+    '--collect',
+    '--quiet',
+    process.execPath,
+    CLI_BIN,
+    '--run',
+    job.id,
+  ], { encoding: 'utf8' });
+  if (result.error) throw new Error(`Could not run systemd-run: ${result.error.message}`);
+  if (result.status !== 0) {
+    throw new Error((result.stderr || result.stdout || 'systemd-run failed.').trim());
+  }
+}
+
+function armDetachedWaiter(job, env) {
+  const child = spawnAgent(process.execPath, [CLI_BIN, '--wait', job.id], {
+    detached: true,
+    stdio: 'ignore',
+    env: { ...process.env, CODEWAKE_STATE_DIR: stateDir(env) },
+  });
+  // Without a listener, an async spawn failure would crash the CLI later
+  // with an unhandled 'error' event instead of surfacing as a message.
+  child.on('error', (error) => {
+    console.error(`codewake: could not start the waiter for job ${job.id}: ${error.message}`);
+  });
+  job.pid = child.pid;
+  child.unref();
+  saveJob(job, env);
+}
+
+/** Launch the agent for a job right now. Resolves when the agent exits. */
+export function runJob(jobId, env = process.env) {
+  const job = loadJob(jobId, env);
+  if (job.status === 'cancelled') return Promise.resolve(job);
+  job.status = 'running';
+  job.startedAt = new Date().toISOString();
+  job.log = logFile(job.id, env);
+  saveJob(job, env);
+  ensureDir(logsDir(env));
+  const log = createWriteStream(job.log, { mode: 0o600 });
+  return new Promise((resolvePromise) => {
+    let settled = false;
+    const finish = (patch) => {
+      if (settled) return;
+      settled = true;
+      Object.assign(job, patch, { finishedAt: new Date().toISOString() });
+      saveJob(job, env);
+      log.end();
+      resolvePromise(job);
+    };
+    let child;
+    try {
+      child = spawnAgent(job.bin, job.args, { cwd: job.project, stdio: ['ignore', 'pipe', 'pipe'] });
+    } catch (error) {
+      finish({ status: 'failed', error: error.message });
+      return;
+    }
+    child.stdout.pipe(log, { end: false });
+    child.stderr.pipe(log, { end: false });
+    child.on('error', (error) => finish({ status: 'failed', error: error.message }));
+    child.on('exit', (code, signal) => finish({
+      status: code === 0 ? 'done' : 'failed',
+      exitCode: code,
+      signal: signal ?? undefined,
+    }));
+  });
+}
+
+const sleep = (ms) => new Promise((resolveSleep) => setTimeout(resolveSleep, ms));
+
+/**
+ * Wait until the job is due, then run it (used by the spawn backend).
+ *
+ * Polls the wall clock in short slices instead of one long setTimeout:
+ * a single timeout would drift by however long the machine was suspended
+ * (Node timers pause during suspend) and silently overflows past ~24.8
+ * days. Re-reading the job each slice also honors cancellation promptly.
+ */
+export async function waitJob(jobId, env = process.env) {
+  const pollMs = Number(env.CODEWAKE_POLL_MS) > 0
+    ? Number(env.CODEWAKE_POLL_MS)
+    : DEFAULT_POLL_MS;
+  for (;;) {
+    let job;
+    try {
+      job = loadJob(jobId, env);
+    } catch {
+      return null;
+    }
+    if (job.status !== 'pending') return job;
+    const remaining = Date.parse(job.runAt) - Date.now();
+    if (remaining <= 0) return runJob(jobId, env);
+    await sleep(Math.min(remaining, pollMs));
+  }
+}
+
+/**
+ * Cancel a pending job. Returns { job, warning }; `warning` is set when
+ * the scheduled launch could not be confirmed as disarmed.
+ */
+export function cancelJob(jobId, env = process.env) {
+  const job = loadJob(jobId, env);
+  if (job.status !== 'pending') {
+    throw new Error(`Job ${jobId} is ${job.status}; only pending jobs can be cancelled.`);
+  }
+  let warning = null;
+  const overdue = displayStatus(job) === 'overdue';
+  if (job.backend === 'systemd') {
+    const stop = spawnSync('systemctl', ['--user', 'stop', `${unitName(job.id)}.timer`], { encoding: 'utf8' });
+    // If the timer already elapsed, the transient service may be what's live.
+    spawnSync('systemctl', ['--user', 'stop', `${unitName(job.id)}.service`], { encoding: 'utf8' });
+    if (!overdue && (stop.error || stop.status !== 0)) {
+      warning = 'Could not confirm the systemd timer was stopped; check "systemctl --user list-timers".';
+    }
+  } else if (job.pid && !overdue) {
+    // Never signal an overdue job's recorded pid: after a reboot the OS may
+    // have reassigned it to an unrelated process. The waiter re-checks the
+    // job status on every poll and exits on its own when it sees the cancel.
+    try {
+      process.kill(job.pid);
+    } catch {
+      // Waiter already gone; the status check below still protects us.
+    }
+  }
+  // Re-read before the final write: the waiter may have flipped the job to
+  // running/done in the meantime, and a stale write would hide a live agent.
+  const fresh = loadJob(jobId, env);
+  if (fresh.status !== 'pending') {
+    throw new Error(`Job ${jobId} is already ${fresh.status}; too late to cancel.`);
+  }
+  fresh.status = 'cancelled';
+  fresh.cancelledAt = new Date().toISOString();
+  saveJob(fresh, env);
+  return { job: fresh, warning };
+}
+
+/** Human status; flags pending jobs whose launch time silently passed. */
+export function displayStatus(job, now = Date.now()) {
+  if (job.status === 'pending' && Date.parse(job.runAt) + OVERDUE_GRACE_MS < now) return 'overdue';
+  return job.status;
+}

package/lib/proc.js

@@ -0,0 +1,37 @@
+import { spawn } from 'node:child_process';
+
+/**
+ * Escape one argument for cmd.exe (same algorithm as the cross-spawn
+ * package): backslash-escape quotes, quote the whole argument, then
+ * caret-escape cmd metacharacters so nothing is interpreted by the shell.
+ */
+export function escapeCmdArg(argument) {
+  let escaped = String(argument);
+  // Double up backslashes that precede a quote, escape the quote itself.
+  escaped = escaped.replace(/(\\*)"/g, '$1$1\\"');
+  // Double up trailing backslashes so they don't escape the closing quote.
+  escaped = escaped.replace(/(\\*)$/, '$1$1');
+  escaped = `"${escaped}"`;
+  // Neutralize cmd.exe metacharacters.
+  escaped = escaped.replace(/[!^&|<>()%"]/g, '^$&');
+  return escaped;
+}
+
+const WINDOWS_SHIM = /\.(cmd|bat)$/i;
+
+/**
+ * Spawn an agent binary portably. On Windows, npm installs CLIs as
+ * .cmd/.bat shims which cannot be spawned directly (Node raises EINVAL);
+ * those are run through cmd.exe with every argument escaped — never with
+ * `shell: true`, which would leave arguments uninterpreted-quoted.
+ */
+export function spawnAgent(bin, args, options = {}) {
+  if (process.platform === 'win32' && WINDOWS_SHIM.test(bin)) {
+    const command = [escapeCmdArg(bin), ...args.map(escapeCmdArg)].join(' ');
+    return spawn(process.env.ComSpec || 'cmd.exe', ['/d', '/s', '/c', `"${command}"`], {
+      ...options,
+      windowsVerbatimArguments: true,
+    });
+  }
+  return spawn(bin, args, options);
+}

package/lib/registry.js

@@ -0,0 +1,151 @@
+/**
+ * Built-in agent registry: the list of coding agents `codewake` knows
+ * how to detect and drive. Each entry is plain data so users can add or
+ * override agents from ~/.config/codewake/config.json with the same shape.
+ *
+ * Fields:
+ *   id        stable identifier used on the command line (`--agent claude`)
+ *   name      display name
+ *   bins      executable names probed on PATH, first hit wins
+ *   sessions  session-discovery strategy (see lib/sessions.js):
+ *             'claude-projects' | 'codex-rollouts' | 'copilot-history' |
+ *             'goose-sessions'  | 'aider-history'  | 'manual' | 'none'
+ *   resume    command spec to resume an existing session (omit if unsupported)
+ *   create    command spec to start a new session (omit if unsupported)
+ *
+ * Command specs:
+ *   args      argv template; '{session}' and '{prompt}' are substituted as
+ *             whole argv elements (never through a shell, so no quoting bugs)
+ *   skip      extra argv appended when the user opts into skipping
+ *             permission/approval prompts (omit if the agent has no such flag)
+ */
+export const BUILTIN_AGENTS = [
+  {
+    id: 'claude',
+    name: 'Claude Code',
+    bins: ['claude'],
+    sessions: 'claude-projects',
+    resume: {
+      args: ['--resume', '{session}', '-p', '{prompt}'],
+      skip: ['--dangerously-skip-permissions'],
+    },
+    create: {
+      args: ['-p', '{prompt}'],
+      skip: ['--dangerously-skip-permissions'],
+    },
+  },
+  {
+    id: 'codex',
+    name: 'OpenAI Codex CLI',
+    bins: ['codex'],
+    sessions: 'codex-rollouts',
+    resume: {
+      args: ['exec', 'resume', '{session}', '{prompt}'],
+      skip: ['--dangerously-bypass-approvals-and-sandbox'],
+    },
+    create: {
+      args: ['exec', '{prompt}'],
+      skip: ['--dangerously-bypass-approvals-and-sandbox'],
+    },
+  },
+  {
+    id: 'gemini',
+    name: 'Gemini CLI',
+    bins: ['gemini'],
+    sessions: 'none',
+    create: {
+      args: ['-p', '{prompt}'],
+      skip: ['--yolo'],
+    },
+  },
+  {
+    id: 'copilot',
+    name: 'GitHub Copilot CLI',
+    bins: ['copilot'],
+    sessions: 'copilot-history',
+    resume: {
+      args: ['--resume', '{session}', '-p', '{prompt}'],
+      skip: ['--allow-all-tools'],
+    },
+    create: {
+      args: ['-p', '{prompt}'],
+      skip: ['--allow-all-tools'],
+    },
+  },
+  {
+    id: 'cursor',
+    name: 'Cursor CLI',
+    bins: ['cursor-agent'],
+    sessions: 'manual',
+    resume: {
+      args: ['--resume', '{session}', '-p', '{prompt}'],
+      skip: ['--force'],
+    },
+    create: {
+      args: ['-p', '{prompt}'],
+      skip: ['--force'],
+    },
+  },
+  {
+    id: 'opencode',
+    name: 'OpenCode',
+    bins: ['opencode'],
+    sessions: 'manual',
+    resume: {
+      args: ['run', '--session', '{session}', '{prompt}'],
+    },
+    create: {
+      args: ['run', '{prompt}'],
+    },
+  },
+  {
+    id: 'aider',
+    name: 'Aider',
+    bins: ['aider'],
+    sessions: 'aider-history',
+    resume: {
+      args: ['--restore-chat-history', '--message', '{prompt}'],
+      skip: ['--yes-always'],
+    },
+    create: {
+      args: ['--message', '{prompt}'],
+      skip: ['--yes-always'],
+    },
+  },
+  {
+    id: 'goose',
+    name: 'Goose',
+    bins: ['goose'],
+    sessions: 'goose-sessions',
+    resume: {
+      args: ['run', '--name', '{session}', '--resume', '--text', '{prompt}'],
+    },
+    create: {
+      args: ['run', '--text', '{prompt}'],
+    },
+  },
+  {
+    id: 'amp',
+    name: 'Amp',
+    bins: ['amp'],
+    sessions: 'manual',
+    resume: {
+      args: ['threads', 'continue', '{session}', '-x', '{prompt}'],
+      skip: ['--dangerously-allow-all'],
+    },
+    create: {
+      args: ['-x', '{prompt}'],
+      skip: ['--dangerously-allow-all'],
+    },
+  },
+  {
+    id: 'qwen',
+    name: 'Qwen Code',
+    bins: ['qwen'],
+    sessions: 'none',
+    create: {
+      args: ['-p', '{prompt}'],
+      skip: ['--yolo'],
+    },
+  },
+];

package/lib/sessions.js

@@ -0,0 +1,156 @@
+import { closeSync, existsSync, openSync, readdirSync, readSync, statSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join, resolve } from 'node:path';
+
+const HEAD_BYTES = 128 * 1024;
+const TITLE_LENGTH = 64;
+
+/**
+ * Discover resumable sessions for an agent. Always returns an array
+ * (possibly empty), newest first: [{ id, title, updatedAt }].
+ */
+export function listSessions(agent, { project = process.cwd(), home = homedir() } = {}) {
+  const strategy = STRATEGIES[agent.sessions] ?? STRATEGIES.none;
+  try {
+    return strategy({ project: resolve(project), home })
+      .sort((a, b) => (b.updatedAt?.getTime() ?? 0) - (a.updatedAt?.getTime() ?? 0));
+  } catch {
+    return [];
+  }
+}
+
+/** Claude Code encodes a project path by replacing non-alphanumerics with '-'. */
+export function encodeClaudeProject(project) {
+  return project.replace(/[^a-zA-Z0-9]/g, '-');
+}
+
+const STRATEGIES = {
+  none: () => [],
+  manual: () => [],
+
+  'claude-projects': ({ project, home }) => {
+    const dir = join(home, '.claude', 'projects', encodeClaudeProject(project));
+    return listFiles(dir, /\.jsonl$/).map(({ path, name, mtime }) => ({
+      id: name.replace(/\.jsonl$/, ''),
+      title: claudeTitle(path) ?? 'Untitled session',
+      updatedAt: mtime,
+    }));
+  },
+
+  'codex-rollouts': ({ project, home }) => {
+    const root = join(home, '.codex', 'sessions');
+    const sessions = [];
+    for (const { path, name, mtime } of walkFiles(root, /^rollout-.*\.jsonl$/)) {
+      const meta = firstJsonLine(path);
+      const payload = meta?.payload ?? meta;
+      const id = payload?.id
+        ?? /^rollout-\d{4}-\d{2}-\d{2}T\d{2}-\d{2}-\d{2}-(.+)\.jsonl$/.exec(name)?.[1];
+      if (!id) continue;
+      const cwd = typeof payload?.cwd === 'string' ? payload.cwd : null;
+      sessions.push({ id, title: cwd ?? 'Codex session', updatedAt: mtime, cwd });
+    }
+    const local = sessions.filter((session) => session.cwd === project);
+    return local.length ? local : sessions;
+  },
+
+  'copilot-history': ({ home }) => {
+    const dir = join(home, '.copilot', 'history-session-state');
+    return listFiles(dir, /\.json$/).map(({ name, mtime }) => ({
+      id: name.replace(/\.json$/, ''),
+      title: 'Copilot session',
+      updatedAt: mtime,
+    }));
+  },
+
+  'goose-sessions': ({ home }) => {
+    const dir = join(home, '.local', 'share', 'goose', 'sessions');
+    return listFiles(dir, /\.jsonl$/).map(({ path, name, mtime }) => ({
+      id: name.replace(/\.jsonl$/, ''),
+      title: cleanTitle(firstJsonLine(path)?.description) ?? 'Goose session',
+      updatedAt: mtime,
+    }));
+  },
+
+  'aider-history': ({ project }) => {
+    const history = join(project, '.aider.chat.history.md');
+    if (!existsSync(history)) return [];
+    return [{
+      id: 'project-history',
+      title: 'Chat history of this project',
+      updatedAt: statSync(history).mtime,
+    }];
+  },
+};
+
+function listFiles(dir, pattern) {
+  if (!existsSync(dir)) return [];
+  return readdirSync(dir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && pattern.test(entry.name))
+    .map((entry) => {
+      const path = join(dir, entry.name);
+      return { path, name: entry.name, mtime: statSync(path).mtime };
+    });
+}
+
+function walkFiles(dir, pattern, depth = 4) {
+  if (depth < 0 || !existsSync(dir)) return [];
+  const found = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    const path = join(dir, entry.name);
+    if (entry.isDirectory()) found.push(...walkFiles(path, pattern, depth - 1));
+    else if (entry.isFile() && pattern.test(entry.name)) {
+      found.push({ path, name: entry.name, mtime: statSync(path).mtime });
+    }
+  }
+  return found;
+}
+
+function head(path, bytes = HEAD_BYTES) {
+  const fd = openSync(path, 'r');
+  try {
+    const buffer = Buffer.alloc(bytes);
+    const read = readSync(fd, buffer, 0, bytes, 0);
+    return buffer.toString('utf8', 0, read);
+  } finally {
+    closeSync(fd);
+  }
+}
+
+function firstJsonLine(path) {
+  const line = head(path, 16 * 1024).split('\n').find((candidate) => candidate.trim());
+  if (!line) return null;
+  try {
+    return JSON.parse(line);
+  } catch {
+    return null;
+  }
+}
+
+function claudeTitle(path) {
+  let firstUserMessage = null;
+  for (const line of head(path).split('\n')) {
+    if (!line.trim()) continue;
+    let entry;
+    try {
+      entry = JSON.parse(line);
+    } catch {
+      continue;
+    }
+    if (entry.type === 'summary' && entry.summary) return cleanTitle(entry.summary);
+    if (!firstUserMessage && entry.type === 'user') {
+      const content = entry.message?.content;
+      if (typeof content === 'string') firstUserMessage = content;
+      else if (Array.isArray(content)) {
+        firstUserMessage = content.find((part) => part?.type === 'text')?.text ?? null;
+      }
+    }
+  }
+  return cleanTitle(firstUserMessage);
+}
+
+function cleanTitle(text) {
+  if (typeof text !== 'string') return null;
+  const flat = text.replace(/\s+/g, ' ').trim();
+  if (!flat) return null;
+  return flat.length > TITLE_LENGTH ? `${flat.slice(0, TITLE_LENGTH - 1)}…` : flat;
+}