project-knowledge 0.1.0 → 1.0.0

package/_site/lib/claude-cli-runner.js

@@ -0,0 +1,862 @@
+// Claude CLI Runner — spawns `claude` (Claude Code CLI) as a subprocess, streams its
+// NDJSON output, and exposes a session-based subscribe/sendInput/abort API.
+//
+// Used by server.js to power the live Claude terminal in the dashboard.
+//
+// Key design:
+// - One session per "kickoff" (initial analyze or follow-up). Each session has a
+//   server-generated sessionId; claude itself has a separate session_id captured from
+//   the system/init event and used for --resume on follow-ups.
+// - Listeners are SSE response objects. When an event arrives, it's emitted to all
+//   current listeners AND appended to outputBuffer so late subscribers can replay.
+// - NDJSON parsing uses a per-process line buffer — stdout chunks may split mid-line.
+// - Windows: claude is installed as a .cmd shim by npm. spawn('claude', ...) without
+//   shell:true fails with ENOENT. We use shell:true + a single argv string built safely.
+
+const { spawn } = require('child_process');
+const crypto = require('crypto');
+const fs = require('fs');
+const path = require('path');
+const { renderPrompt } = require('./prompt-registry');
+const aiWorkspace = require('./ai-workspace');
+
+// ---- session store ----
+// Map<sessionId, Session>
+const sessions = new Map();
+const KB_ROOT = path.resolve(__dirname, '..', '..');
+const WORKBENCH_DIR = 'claude-workbench';
+
+function newSessionId() {
+  return 'sess-' + crypto.randomBytes(6).toString('hex');
+}
+
+function createSession({ projectSlug, projectPath, kbPath, promptKey }) {
+  const sessionId = newSessionId();
+  const session = {
+    sessionId,
+    projectSlug,
+    projectPath,
+    kbPath: kbPath || path.join(KB_ROOT, 'projects', projectSlug),
+    promptKey,
+    state: 'idle',
+    model: null,
+    claudeSessionId: null,
+    startedAt: new Date().toISOString(),
+    endedAt: null,
+    exitCode: null,
+    listeners: new Set(),
+    outputBuffer: [],
+    subprocess: null,
+    turns: 0,
+    error: null,
+    claudeEnv: {},
+    pendingPermission: null,
+    pendingTurn: null,
+    pendingToolApproval: null,
+    restored: false,
+  };
+  sessions.set(sessionId, session);
+  persistSession(session);
+  return session;
+}
+
+function sessionRecordPath(session) {
+  if (!session || !session.projectSlug) return null;
+  return path.join(aiWorkspace.ensureProjectAIPath(session.projectSlug), WORKBENCH_DIR, `${session.sessionId}.json`);
+}
+
+function toPersistedSession(session) {
+  return {
+    schema: 'claude-workbench-session/v1',
+    sessionId: session.sessionId,
+    projectSlug: session.projectSlug,
+    projectPath: session.projectPath,
+    kbPath: session.kbPath,
+    promptKey: session.promptKey,
+    runner: session.runner || 'cli',
+    state: session.state,
+    model: session.model,
+    aiProfileId: session.aiProfileId || null,
+    claudeSessionId: session.claudeSessionId,
+    startedAt: session.startedAt,
+    endedAt: session.endedAt,
+    exitCode: session.exitCode,
+    turns: session.turns,
+    error: session.error,
+    pendingPermission: session.pendingPermission,
+    events: session.outputBuffer.slice(-5000),
+    updatedAt: new Date().toISOString(),
+  };
+}
+
+function persistSession(session) {
+  const file = sessionRecordPath(session);
+  if (!file) return;
+  try {
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(toPersistedSession(session), null, 2) + '\n', 'utf-8');
+  } catch (e) {
+    // Persistence should never interrupt the live Claude process.
+  }
+}
+
+function readPersistedRecord(file) {
+  try {
+    const parsed = JSON.parse(fs.readFileSync(file, 'utf-8'));
+    if (parsed && parsed.schema === 'claude-workbench-session/v1' && parsed.sessionId) return parsed;
+  } catch {}
+  return null;
+}
+
+function scanPersistedRecords(projectSlug = null) {
+  let projectDirs = [];
+  try {
+    const projects = JSON.parse(fs.readFileSync(path.join(KB_ROOT, 'projects.json'), 'utf-8'));
+    projectDirs = Object.entries(projects || {})
+      .filter(([slug]) => !projectSlug || slug === projectSlug)
+      .map(([slug, cfg]) => ({ name: slug, kbPath: cfg.kbPath || path.join(KB_ROOT, 'projects', slug) }));
+  } catch {
+    const projectsRoot = path.join(KB_ROOT, 'projects');
+    try {
+      projectDirs = fs.readdirSync(projectsRoot, { withFileTypes: true })
+        .filter(entry => entry.isDirectory())
+        .filter(entry => !projectSlug || entry.name === projectSlug)
+        .map(entry => ({ name: entry.name, kbPath: path.join(projectsRoot, entry.name) }));
+    } catch { return []; }
+  }
+  const records = [];
+  for (const entry of projectDirs) {
+    const dirs = [
+      path.join(aiWorkspace.projectAIPath(entry.name), WORKBENCH_DIR),
+      path.join(entry.kbPath, '_ai', WORKBENCH_DIR),
+    ];
+    for (const dir of dirs) {
+      let files = [];
+      try { files = fs.readdirSync(dir); } catch { continue; }
+      for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        const record = readPersistedRecord(path.join(dir, file));
+        if (record) records.push(record);
+      }
+    }
+  }
+  return records.sort((a, b) => String(b.updatedAt || b.startedAt || '').localeCompare(String(a.updatedAt || a.startedAt || '')));
+}
+
+function findPersistedRecord(sessionId) {
+  return scanPersistedRecords().find(record => record.sessionId === sessionId) || null;
+}
+
+function restoreSessionFromDisk(sessionId) {
+  if (sessions.has(sessionId)) return sessions.get(sessionId);
+  const record = findPersistedRecord(sessionId);
+  if (!record) return null;
+  const liveState = ['running', 'spawning', 'pending-permission'].includes(record.state) ? 'idle' : (record.state || 'idle');
+  const session = {
+    sessionId: record.sessionId,
+    projectSlug: record.projectSlug,
+    projectPath: record.projectPath,
+    kbPath: record.kbPath || path.join(KB_ROOT, 'projects', record.projectSlug),
+    promptKey: record.promptKey,
+    runner: record.runner || 'cli',
+    state: liveState,
+    model: record.model || null,
+    aiProfileId: record.aiProfileId || null,
+    claudeSessionId: record.claudeSessionId || null,
+    startedAt: record.startedAt || new Date().toISOString(),
+    endedAt: liveState === record.state ? record.endedAt || null : null,
+    exitCode: record.exitCode ?? null,
+    listeners: new Set(),
+    outputBuffer: Array.isArray(record.events) ? record.events : [],
+    subprocess: null,
+    turns: record.turns || 0,
+    error: record.error || null,
+    claudeEnv: {},
+    pendingPermission: null,
+    pendingTurn: null,
+    pendingToolApproval: null,
+    restored: true,
+  };
+  sessions.set(sessionId, session);
+  if (liveState !== record.state) {
+    emit(session, { type: 'claude/restored', fromState: record.state, state: liveState });
+  }
+  return session;
+}
+
+function buildClaudeEnvFromProfile(profile) {
+  const env = { CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC: '1' };
+  if (!profile || typeof profile !== 'object') return env;
+
+  const apiKeyFromEnv = profile.apiKeyEnv ? process.env[profile.apiKeyEnv] : '';
+  const apiKey = profile.apiKey || profile.authToken || profile.anthropicAuthToken || apiKeyFromEnv || '';
+  const baseUrl = profile.baseUrl || profile.apiBaseUrl || profile.anthropicBaseUrl || '';
+  const model = profile.model || '';
+  const timeoutMs = profile.timeoutMs || process.env.API_TIMEOUT_MS || '';
+  const version = profile.version || profile.anthropicVersion || '';
+
+  if (apiKey) env.ANTHROPIC_AUTH_TOKEN = String(apiKey);
+  if (baseUrl) env.ANTHROPIC_BASE_URL = String(baseUrl);
+  if (model) {
+    env.ANTHROPIC_MODEL = String(model);
+    env.ANTHROPIC_SMALL_FAST_MODEL = String(model);
+    env.ANTHROPIC_DEFAULT_SONNET_MODEL = String(model);
+    env.ANTHROPIC_DEFAULT_OPUS_MODEL = String(model);
+    env.ANTHROPIC_DEFAULT_HAIKU_MODEL = String(model);
+  }
+  if (timeoutMs) env.API_TIMEOUT_MS = String(timeoutMs);
+  if (version) env.ANTHROPIC_VERSION = String(version);
+
+  return env;
+}
+
+function getSession(sessionId) {
+  return sessions.get(sessionId) || restoreSessionFromDisk(sessionId);
+}
+
+function sessionSummary(s) {
+  return {
+    sessionId: s.sessionId,
+    projectSlug: s.projectSlug,
+    promptKey: s.promptKey,
+    runner: s.runner || 'cli',
+    state: s.state,
+    model: s.model,
+    aiProfileId: s.aiProfileId || null,
+    claudeSessionId: s.claudeSessionId,
+    startedAt: s.startedAt,
+    endedAt: s.endedAt,
+    exitCode: s.exitCode,
+    turns: s.turns,
+    pendingPermission: s.pendingPermission,
+    restored: !!s.restored,
+  };
+}
+
+function listSessions(filter = {}) {
+  const projectSlug = filter.projectSlug || null;
+  const byId = new Map();
+  for (const record of scanPersistedRecords(projectSlug)) {
+    byId.set(record.sessionId, sessionSummary({
+      ...record,
+      listeners: new Set(),
+      outputBuffer: record.events || [],
+      subprocess: null,
+      pendingPermission: ['running', 'spawning'].includes(record.state) ? null : record.pendingPermission,
+      restored: true,
+    }));
+  }
+  for (const s of sessions.values()) {
+    if (projectSlug && s.projectSlug !== projectSlug) continue;
+    byId.set(s.sessionId, sessionSummary(s));
+  }
+  return [...byId.values()].sort((a, b) => String(b.startedAt || '').localeCompare(String(a.startedAt || '')));
+}
+
+function emit(session, event) {
+  session.outputBuffer.push(event);
+  if (session.outputBuffer.length > 5000) session.outputBuffer.shift();
+  for (const listener of session.listeners) {
+    try { listener(event); } catch { /* listener may be a dead SSE */ }
+  }
+  persistSession(session);
+}
+
+function setState(session, state, extra = {}) {
+  session.state = state;
+  if (state === 'ended' || state === 'failed' || state === 'aborted') {
+    session.endedAt = new Date().toISOString();
+  }
+  emit(session, { type: 'claude/state', state, ...extra });
+}
+
+function newPermissionId() {
+  return 'perm-' + crypto.randomBytes(6).toString('hex');
+}
+
+function requiresTurnPermission(opts) {
+  if (!opts) return false;
+  if (opts.requirePermission === false) return false;
+  if (opts.permissionMode === 'bypassPermissions') return true;
+  const tools = Array.isArray(opts.allowedTools) ? opts.allowedTools : [];
+  return tools.some(tool => ['Bash', 'Edit', 'Write', 'MultiEdit', 'NotebookEdit'].includes(tool));
+}
+
+function summarizePermission(opts, meta) {
+  return {
+    cwd: opts.cwd || '',
+    model: opts.model || null,
+    permissionMode: opts.permissionMode || 'default',
+    allowedTools: Array.isArray(opts.allowedTools) ? opts.allowedTools : [],
+    promptPreview: String(opts.userPrompt || '').slice(0, 500),
+    turnKind: meta && meta.turnKind || 'analysis',
+    isResume: !!opts.resumeSessionId,
+  };
+}
+
+function beginTurn(session, opts, meta = {}) {
+  if (requiresTurnPermission(opts)) {
+    const requestId = newPermissionId();
+    session.pendingPermission = {
+      requestId,
+      status: 'pending',
+      createdAt: new Date().toISOString(),
+      summary: summarizePermission(opts, meta),
+    };
+    session.pendingTurn = {
+      opts,
+      isResume: !!opts.resumeSessionId,
+      nextTurn: session.turns + 1,
+    };
+    setState(session, 'pending-permission', { requestId, turn: session.turns + 1 });
+    emit(session, { type: 'claude/permission-request', ...session.pendingPermission });
+    return { pendingPermission: session.pendingPermission };
+  }
+  startTurn(session, opts, !!opts.resumeSessionId);
+  return { started: true };
+}
+
+function startTurn(session, opts, isResume) {
+  session.pendingPermission = null;
+  session.pendingTurn = null;
+  setState(session, 'spawning', { turn: session.turns + 1 });
+  spawnClaude(session, opts);
+  session.turns += 1;
+  setState(session, 'running', { turn: session.turns });
+}
+
+function resolvePermission(sessionId, requestId, decision) {
+  const session = getSession(sessionId);
+  if (!session) throw new Error(`session not found: ${sessionId}`);
+  if (!session.pendingPermission || session.pendingPermission.requestId !== requestId) {
+    throw new Error('permission request not found or already resolved');
+  }
+  const allow = decision && decision.allow === true;
+  const resolvedAt = new Date().toISOString();
+  emit(session, {
+    type: 'claude/permission-resolved',
+    requestId,
+    allow,
+    message: decision && decision.message || '',
+    resolvedAt,
+  });
+  if (session.pendingToolApproval && session.pendingToolApproval.requestId === requestId) {
+    const approval = session.pendingToolApproval;
+    session.pendingToolApproval = null;
+    session.pendingPermission = null;
+    setState(session, 'running', { message: allow ? 'tool permission approved' : 'tool permission denied', requestId });
+    approval.resolve(allow
+      ? { behavior: 'allow', updatedInput: approval.input, toolUseID: approval.toolUseID }
+      : { behavior: 'deny', message: decision && decision.message || 'User denied tool use', toolUseID: approval.toolUseID });
+    persistSession(session);
+    return { ok: true, started: true, toolPermission: true };
+  }
+  if (!allow) {
+    session.pendingPermission = { ...session.pendingPermission, status: 'denied', resolvedAt };
+    session.pendingTurn = null;
+    setState(session, 'idle', { message: 'permission denied', requestId });
+    session.pendingPermission = null;
+    persistSession(session);
+    return { ok: true, started: false };
+  }
+  const pending = session.pendingTurn;
+  if (!pending) throw new Error('permission has no pending turn');
+  startTurn(session, pending.opts, pending.isResume);
+  return { ok: true, started: true };
+}
+
+// ---- NDJSON parsing ----
+function attachProcessHandlers(session, proc, isResume) {
+  let lineBuffer = '';
+  // Tool input is streamed across many content_block_delta events; accumulate per content block
+  // and emit a final tool-use event with the assembled input when the block closes.
+  const toolInputBuffers = new Map();  // contentBlockId -> partial_json string
+
+  proc.stdout.on('data', chunk => {
+    lineBuffer += chunk.toString('utf-8');
+    let idx;
+    while ((idx = lineBuffer.indexOf('\n')) >= 0) {
+      const line = lineBuffer.slice(0, idx).trim();
+      lineBuffer = lineBuffer.slice(idx + 1);
+      if (line) handleNdjsonLine(session, line, toolInputBuffers);
+    }
+  });
+
+  let stderrBuf = '';
+  proc.stderr.on('data', chunk => {
+    stderrBuf += chunk.toString('utf-8');
+    let idx;
+    while ((idx = stderrBuf.indexOf('\n')) >= 0) {
+      const line = stderrBuf.slice(0, idx).trim();
+      stderrBuf = stderrBuf.slice(idx + 1);
+      if (line) emit(session, { type: 'claude/stderr', text: line });
+    }
+  });
+
+  proc.on('error', e => {
+    session.error = e.message;
+    emit(session, { type: 'claude/error', message: `spawn error: ${e.message}` });
+    setState(session, 'failed', { error: e.message });
+  });
+
+  proc.on('close', code => {
+    session.exitCode = code;
+    session.subprocess = null;
+    if (lineBuffer.trim()) {
+      try { handleNdjsonLine(session, lineBuffer.trim()); } catch {}
+    }
+    if (session.state !== 'aborted' && session.state !== 'failed') {
+      if (code === 0) {
+        setState(session, 'idle', { exitCode: code, message: isResume ? 'follow-up complete' : 'turn complete, awaiting input or new analysis' });
+        emit(session, { type: 'claude/turn-end', exitCode: code });
+      } else {
+        setState(session, 'failed', { exitCode: code, error: `claude exited with code ${code}` });
+        emit(session, { type: 'claude/exit', exitCode: code });
+      }
+    } else {
+      emit(session, { type: 'claude/exit', exitCode: code });
+    }
+  });
+
+  session.subprocess = proc;
+}
+
+function handleNdjsonLine(session, line, toolInputBuffers) {
+  let parsed;
+  try {
+    parsed = JSON.parse(line);
+  } catch {
+    emit(session, { type: 'claude/raw', text: line });
+    return;
+  }
+
+  const t = parsed.type;
+
+  if (t === 'system' && parsed.subtype === 'init') {
+    if (parsed.session_id) session.claudeSessionId = parsed.session_id;
+    if (parsed.model) session.model = typeof parsed.model === 'string' ? parsed.model : (parsed.model.id || parsed.model.name || null);
+    emit(session, {
+      type: 'claude/init',
+      claudeSessionId: session.claudeSessionId,
+      model: session.model,
+      aiProfileId: session.aiProfileId || null,
+      tools: parsed.tools || [],
+      mcpServers: parsed.mcp_servers || [],
+    });
+    return;
+  }
+
+  if (t === 'stream_event' && parsed.event) {
+    const ev = parsed.event;
+    if (ev.type === 'message_start' && ev.message) {
+      emit(session, { type: 'claude/message-start', role: ev.message.role });
+      return;
+    }
+    if (ev.type === 'content_block_start' && ev.content_block) {
+      const cb = ev.content_block;
+      if (cb.type === 'tool_use') {
+        // Initialize the per-block input accumulator; emit nothing yet (input is empty).
+        // The full input arrives via input_json_delta events and is emitted on content_block_stop.
+        if (cb.id) toolInputBuffers.set(cb.id, '');
+        emit(session, { type: 'claude/tool-use-start', id: cb.id, name: cb.name });
+        return;
+      }
+      if (cb.type === 'thinking') {
+        emit(session, { type: 'claude/thinking-start', id: cb.id });
+        return;
+      }
+      return;
+    }
+    if (ev.type === 'content_block_delta' && ev.delta) {
+      const d = ev.delta;
+      if (d.type === 'text_delta') {
+        emit(session, { type: 'claude/text-delta', text: d.text });
+        return;
+      }
+      if (d.type === 'input_json_delta') {
+        // Accumulate into the tool-use block; also emit a low-level delta for live UIs.
+        if (ev.index != null && toolInputBuffers) {
+          // We don't know block id here; emit raw delta
+        }
+        emit(session, { type: 'claude/tool-input-delta', text: d.partial_json });
+        return;
+      }
+      if (d.type === 'thinking_delta') {
+        emit(session, { type: 'claude/thinking-delta', text: d.thinking });
+        return;
+      }
+      return;
+    }
+    if (ev.type === 'content_block_stop') {
+      // Block ended — but we don't reliably know which block. Tool input emission is
+      // best-effort: the assistant message envelope at message_delta carries final tools.
+      return;
+    }
+    if (ev.type === 'message_delta' && ev.delta) {
+      if (ev.delta.stop_reason) {
+        emit(session, { type: 'claude/message-stop', stopReason: ev.delta.stop_reason });
+      }
+      return;
+    }
+    if (ev.type === 'message_stop') {
+      return;
+    }
+    return;
+  }
+
+  if (t === 'user' || t === 'assistant') {
+    // On assistant turn boundaries, the full message (with completed tool_use blocks)
+    // appears here. Emit any tool-use blocks we haven't fully captured yet.
+    if (t === 'assistant' && parsed.message && Array.isArray(parsed.message.content)) {
+      for (const block of parsed.message.content) {
+        if (block && block.type === 'tool_use') {
+          emit(session, {
+            type: 'claude/tool-use',
+            id: block.id,
+            name: block.name,
+            input: block.input || {},
+          });
+        }
+      }
+    }
+    return;
+  }
+
+  if (t === 'result') {
+    emit(session, {
+      type: 'claude/result',
+      subtype: parsed.subtype || null,
+      costUsd: parsed.total_cost_usd,
+      durationMs: parsed.duration_ms,
+      result: typeof parsed.result === 'string' ? parsed.result : JSON.stringify(parsed.result),
+      isError: parsed.is_error === true,
+    });
+    return;
+  }
+
+  emit(session, { type: 'claude/raw', json: parsed });
+}
+
+// ---- public API ----
+
+// spawn claude for the FIRST turn (initial analysis)
+function startSession({ slug, projectPath, kbPath, promptKey, vars, aiProfile, runner }) {
+  const rendered = renderPrompt(promptKey, vars || {});
+  if (!rendered) {
+    throw new Error(`unknown prompt key: ${promptKey}`);
+  }
+  const session = createSession({ projectSlug: slug, projectPath, kbPath, promptKey });
+  session.aiProfileId = aiProfile && aiProfile.id || null;
+  session.claudeEnv = buildClaudeEnvFromProfile(aiProfile);
+  session.runner = runner || aiProfile && aiProfile.runner || 'cli';
+  emit(session, {
+    type: 'claude/system-prompt',
+    text: rendered.systemPrompt,
+    promptKey,
+    aiProfileId: session.aiProfileId,
+  });
+  emit(session, {
+    type: 'claude/user-prompt',
+    text: rendered.userPrompt,
+    promptKey,
+    isInitial: true,
+  });
+  const turnOpts = {
+    userPrompt: rendered.userPrompt,
+    systemPrompt: rendered.systemPrompt,
+    model: rendered.model,
+    permissionMode: rendered.permissionMode,
+    allowedTools: rendered.allowedTools,
+    cwd: session.kbPath,
+    env: session.claudeEnv,
+  };
+  if (session.runner === 'sdk') {
+    startSdkTurn(session, turnOpts, false);
+    return { sessionId: session.sessionId, pendingPermission: null, runner: 'sdk' };
+  }
+  const turn = beginTurn(session, turnOpts, { turnKind: 'initial-analysis' });
+  return { sessionId: session.sessionId, pendingPermission: turn.pendingPermission || null };
+}
+
+// spawn claude for a FOLLOW-UP turn using --resume
+async function sendInput(sessionId, text, aiProfile = null, runner = null) {
+  const session = getSession(sessionId);
+  if (!session) throw new Error(`session not found: ${sessionId}`);
+  if (!session.claudeSessionId) {
+    throw new Error('claude session not initialized yet — wait for the first turn to emit claude/init');
+  }
+  if (session.subprocess) {
+    throw new Error(`a subprocess is already running on session ${sessionId}`);
+  }
+  if (aiProfile) {
+    session.aiProfileId = aiProfile.id || session.aiProfileId || null;
+    session.claudeEnv = buildClaudeEnvFromProfile(aiProfile);
+    session.runner = runner || aiProfile.runner || session.runner || 'cli';
+  }
+  emit(session, { type: 'claude/user-prompt', text, isFollowUp: true });
+  const turnOpts = {
+    userPrompt: text,
+    model: session.model || 'sonnet',
+    permissionMode: 'bypassPermissions',
+    allowedTools: ['Read', 'Grep', 'Glob', 'Bash', 'Edit'],
+    cwd: session.kbPath,
+    resumeSessionId: session.claudeSessionId,
+    systemPrompt: null,
+    env: session.claudeEnv,
+  };
+  if ((runner || session.runner) === 'sdk') {
+    startSdkTurn(session, { ...turnOpts, permissionMode: 'default' }, true);
+    return { started: true, pendingPermission: null, runner: 'sdk' };
+  }
+  return beginTurn(session, turnOpts, { turnKind: 'follow-up' });
+}
+
+function findClaudeExecutable() {
+  // Prefer the .exe path the running Claude Code sets in the env — bypasses cmd.exe shim
+  // entirely and avoids Windows shell quoting pitfalls on long prompts.
+  if (process.env.CLAUDE_CODE_EXECPATH) {
+    return { cmd: process.env.CLAUDE_CODE_EXECPATH, shell: false };
+  }
+  // Fallbacks
+  if (process.platform === 'win32') {
+    const npmRoot = process.env.APPDATA && require('path').join(process.env.APPDATA, 'npm');
+    if (npmRoot) {
+      const candidates = [
+        require('path').join(npmRoot, 'node_modules', '@anthropic-ai', 'claude-code', 'bin', 'claude.exe'),
+        require('path').join(npmRoot, 'claude.cmd'),
+      ];
+      const fs = require('fs');
+      for (const c of candidates) {
+        if (fs.existsSync(c)) return { cmd: c, shell: c.endsWith('.cmd') };
+      }
+    }
+    return { cmd: 'claude', shell: true };  // last resort
+  }
+  return { cmd: 'claude', shell: false };
+}
+
+function spawnClaude(session, opts) {
+  const args = ['-p', opts.userPrompt, '--output-format', 'stream-json', '--verbose', '--include-partial-messages'];
+  if (opts.systemPrompt) {
+    args.push('--system-prompt', opts.systemPrompt);
+  }
+  if (opts.model) {
+    args.push('--model', opts.model);
+  }
+  if (opts.permissionMode === 'bypassPermissions') {
+    args.push('--dangerously-skip-permissions');
+  } else if (opts.permissionMode) {
+    args.push('--permission-mode', opts.permissionMode);
+  }
+  if (Array.isArray(opts.allowedTools) && opts.allowedTools.length) {
+    args.push('--allowedTools', opts.allowedTools.join(','));
+  }
+  if (opts.resumeSessionId) {
+    args.push('--resume', opts.resumeSessionId);
+  }
+
+  const { cmd, shell } = findClaudeExecutable();
+  const proc = spawn(cmd, args, {
+    cwd: opts.cwd,
+    shell,
+    windowsHide: false,
+    env: { ...process.env, ...(opts.env || {}), FORCE_COLOR: '0', NO_COLOR: '1' },
+    // WindowsVerbatimArguments defaults to true on win32 for native shells; keep false so
+    // Node's argument escaping handles the embedded double quotes in our JSON-shape prompts.
+    windowsVerbatimArguments: false,
+  });
+  attachProcessHandlers(session, proc, !!opts.resumeSessionId);
+  return proc;
+}
+
+async function runSdkTurn(session, opts, isResume) {
+  const { query } = await import('@anthropic-ai/claude-agent-sdk');
+  const toolInputBuffers = new Map();
+  const sdkOptions = {
+    cwd: opts.cwd,
+    env: { ...process.env, ...(opts.env || {}), FORCE_COLOR: '0', NO_COLOR: '1' },
+    model: opts.model,
+    tools: { type: 'preset', preset: 'claude_code' },
+    disallowedTools: [],
+    settingSources: ['project', 'user', 'local'],
+    includePartialMessages: true,
+    pathToClaudeCodeExecutable: findClaudeExecutable().cmd,
+    systemPrompt: opts.systemPrompt || { type: 'preset', preset: 'claude_code' },
+    permissionMode: opts.permissionMode === 'bypassPermissions' ? 'default' : (opts.permissionMode || 'default'),
+    canUseTool: async (toolName, input, context = {}) => {
+      const requestId = newPermissionId();
+      const summary = {
+        turnKind: 'tool-use',
+        isResume,
+        cwd: opts.cwd || '',
+        model: opts.model || null,
+        permissionMode: sdkOptions.permissionMode,
+        allowedTools: [toolName],
+        toolName,
+        toolUseID: context.toolUseID || null,
+        title: context.title || context.displayName || toolName,
+        description: context.description || context.decisionReason || '',
+        promptPreview: JSON.stringify(input || {}).slice(0, 500),
+      };
+      session.pendingPermission = {
+        requestId,
+        status: 'pending',
+        createdAt: new Date().toISOString(),
+        summary,
+      };
+      setState(session, 'pending-permission', { requestId, toolName, toolUseID: context.toolUseID || null });
+      emit(session, { type: 'claude/permission-request', ...session.pendingPermission });
+      return await new Promise((resolve) => {
+        const cancel = () => {
+          if (session.pendingToolApproval && session.pendingToolApproval.requestId === requestId) {
+            session.pendingToolApproval = null;
+            session.pendingPermission = null;
+            resolve({ behavior: 'deny', message: 'Permission request cancelled', toolUseID: context.toolUseID });
+          }
+        };
+        if (context.signal) {
+          if (context.signal.aborted) return cancel();
+          context.signal.addEventListener('abort', cancel, { once: true });
+        }
+        session.pendingToolApproval = {
+          requestId,
+          resolve,
+          input,
+          toolUseID: context.toolUseID,
+        };
+      });
+    },
+  };
+  if (opts.resumeSessionId) sdkOptions.resume = opts.resumeSessionId;
+
+  let queryInstance;
+  try {
+    queryInstance = query({ prompt: opts.userPrompt, options: sdkOptions });
+    session.subprocess = { kill: () => queryInstance.close && queryInstance.close() };
+    for await (const message of queryInstance) {
+      if (message.session_id) session.claudeSessionId = message.session_id;
+      handleNdjsonLine(session, JSON.stringify(message), toolInputBuffers);
+    }
+    if (session.state !== 'aborted' && session.state !== 'failed') {
+      setState(session, 'idle', { exitCode: 0, message: isResume ? 'follow-up complete' : 'turn complete, awaiting input or new analysis' });
+      emit(session, { type: 'claude/turn-end', exitCode: 0 });
+    }
+  } catch (e) {
+    session.error = e.message;
+    emit(session, { type: 'claude/error', message: e.message });
+    setState(session, 'failed', { error: e.message });
+  } finally {
+    session.subprocess = null;
+    session.pendingToolApproval = null;
+    session.pendingPermission = null;
+    persistSession(session);
+  }
+}
+
+function startSdkTurn(session, opts, isResume) {
+  session.pendingPermission = null;
+  session.pendingTurn = null;
+  setState(session, 'spawning', { turn: session.turns + 1, runner: 'sdk' });
+  session.turns += 1;
+  setState(session, 'running', { turn: session.turns, runner: 'sdk' });
+  runSdkTurn(session, opts, isResume).catch(e => {
+    session.error = e.message;
+    emit(session, { type: 'claude/error', message: e.message });
+    setState(session, 'failed', { error: e.message });
+  });
+}
+
+function abort(sessionId) {
+  const session = getSession(sessionId);
+  if (!session) throw new Error(`session not found: ${sessionId}`);
+  if (session.subprocess) {
+    try {
+      session.subprocess.kill();
+    } catch {}
+    setState(session, 'aborted', { reason: 'user-abort' });
+    emit(session, { type: 'claude/aborted', reason: 'user-abort' });
+  } else {
+    session.pendingPermission = null;
+    session.pendingTurn = null;
+    setState(session, 'aborted', { reason: 'no-active-subprocess' });
+  }
+}
+
+// Subscribe to live events. Callback receives each event as it arrives.
+// Late subscribers also get replayed outputBuffer.
+function subscribe(sessionId, onEvent) {
+  const session = getSession(sessionId);
+  if (!session) throw new Error(`session not found: ${sessionId}`);
+  // replay buffer first
+  for (const ev of session.outputBuffer) {
+    try { onEvent(ev); } catch {}
+  }
+  session.listeners.add(onEvent);
+  return () => {
+    session.listeners.delete(onEvent);
+  };
+}
+
+function getState(sessionId) {
+  const s = getSession(sessionId);
+  if (!s) return null;
+  return {
+    sessionId: s.sessionId,
+    projectSlug: s.projectSlug,
+    promptKey: s.promptKey,
+    runner: s.runner || 'cli',
+    state: s.state,
+    model: s.model,
+    aiProfileId: s.aiProfileId || null,
+    claudeSessionId: s.claudeSessionId,
+    startedAt: s.startedAt,
+    endedAt: s.endedAt,
+    exitCode: s.exitCode,
+    turns: s.turns,
+    error: s.error,
+    listenerCount: s.listeners.size,
+    bufferedEvents: s.outputBuffer.length,
+    pendingPermission: s.pendingPermission,
+    restored: !!s.restored,
+  };
+}
+
+function deleteSession(sessionId) {
+  const s = sessions.get(sessionId);
+  if (!s) return false;
+  if (s.subprocess) {
+    try { s.subprocess.kill(); } catch {}
+  }
+  sessions.delete(sessionId);
+  try {
+    const file = sessionRecordPath(s);
+    if (file) fs.rmSync(file, { force: true });
+  } catch {}
+  return true;
+}
+
+// Periodically clean up old sessions with no listeners (memory hygiene)
+function pruneOldSessions(maxAgeMs = 30 * 60 * 1000) {
+  const now = Date.now();
+  for (const [id, s] of sessions) {
+    if (s.listeners.size === 0 && s.subprocess === null && s.endedAt) {
+      const age = now - new Date(s.endedAt).getTime();
+      if (age > maxAgeMs) sessions.delete(id);
+    }
+  }
+}
+
+setInterval(pruneOldSessions, 5 * 60 * 1000).unref();
+
+module.exports = {
+  startSession,
+  buildClaudeEnvFromProfile,
+  sendInput,
+  resolvePermission,
+  abort,
+  subscribe,
+  getSession,
+  getState,
+  listSessions,
+  deleteSession,
+};