coxpit 2.1.0

package/src/db/index.ts

@@ -0,0 +1,73 @@
+import { createClient } from '@libsql/client';
+import { drizzle } from 'drizzle-orm/libsql';
+import { config } from '../config';
+import * as schema from './schema';
+
+// libSQL(NAPI 프리빌드 = 노드버전 무관). 로컬 파일 모드.
+const client = createClient({ url: `file:${config.dbPath}` });
+
+export const db = drizzle(client, { schema });
+
+/** 스키마 부트스트랩(멱등). 정식 마이그레이션은 drizzle-kit(추후). */
+export async function ensureSchema(): Promise<void> {
+  await client.executeMultiple(`
+    CREATE TABLE IF NOT EXISTS machines (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      slug TEXT NOT NULL UNIQUE,
+      name TEXT NOT NULL,
+      address TEXT NOT NULL DEFAULT '',
+      ssh_user TEXT NOT NULL DEFAULT '',
+      kind TEXT NOT NULL DEFAULT 'local',
+      online INTEGER NOT NULL DEFAULT 0,
+      last_seen INTEGER
+    );
+    CREATE TABLE IF NOT EXISTS repos (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      machine_id INTEGER NOT NULL,
+      path TEXT NOT NULL,
+      name TEXT NOT NULL,
+      default_branch TEXT NOT NULL DEFAULT 'main'
+    );
+    CREATE TABLE IF NOT EXISTS design_captures (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      url TEXT NOT NULL DEFAULT '',
+      selector TEXT NOT NULL DEFAULT '',
+      html TEXT NOT NULL DEFAULT '',
+      css TEXT NOT NULL DEFAULT '',
+      note TEXT NOT NULL DEFAULT '',
+      created_at INTEGER DEFAULT (unixepoch())
+    );
+    CREATE TABLE IF NOT EXISTS tasks (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      repo_id INTEGER NOT NULL,
+      title TEXT NOT NULL,
+      prompt TEXT NOT NULL DEFAULT '',
+      status TEXT NOT NULL DEFAULT 'open',
+      design_capture_id INTEGER,
+      created_at INTEGER DEFAULT (unixepoch())
+    );
+    CREATE TABLE IF NOT EXISTS agent_runs (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      task_id INTEGER NOT NULL,
+      machine_id INTEGER NOT NULL,
+      agent TEXT NOT NULL DEFAULT 'claude-code',
+      worktree_path TEXT NOT NULL DEFAULT '',
+      branch TEXT NOT NULL DEFAULT '',
+      tmux_window TEXT NOT NULL DEFAULT '',
+      status TEXT NOT NULL DEFAULT 'pending',
+      files_changed INTEGER NOT NULL DEFAULT 0,
+      started_at INTEGER,
+      ended_at INTEGER,
+      exit_summary TEXT NOT NULL DEFAULT ''
+    );
+    CREATE TABLE IF NOT EXISTS agent_events (
+      id INTEGER PRIMARY KEY AUTOINCREMENT,
+      run_id INTEGER NOT NULL,
+      kind TEXT NOT NULL,
+      payload TEXT NOT NULL DEFAULT '',
+      ts INTEGER DEFAULT (unixepoch())
+    );
+  `);
+  // 기존 DB 마이그레이션(멱등) — tasks.design_capture_id
+  try { await client.execute('ALTER TABLE tasks ADD COLUMN design_capture_id INTEGER'); } catch { /* exists */ }
+}

package/src/db/schema.ts

@@ -0,0 +1,69 @@
+import { sqliteTable, text, integer } from 'drizzle-orm/sqlite-core';
+
+/** 접근 대상 머신. address 빈값 = 로컬(데몬이 도는 머신), 그 외 = 원격(ssh). */
+export const machines = sqliteTable('machines', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  slug: text('slug').notNull().unique(),
+  name: text('name').notNull(),
+  address: text('address').notNull().default(''), // tailscale/LAN host; '' = local
+  sshUser: text('ssh_user').notNull().default(''),
+  kind: text('kind').notNull().default('local'), // local | remote
+  online: integer('online', { mode: 'boolean' }).notNull().default(false),
+  lastSeen: integer('last_seen', { mode: 'timestamp' }),
+});
+
+/** 머신 위의 git 저장소. */
+export const repos = sqliteTable('repos', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  machineId: integer('machine_id').notNull(),
+  path: text('path').notNull(),
+  name: text('name').notNull(),
+  defaultBranch: text('default_branch').notNull().default('main'),
+});
+
+/** Design Mode 캡처 — 북마클릿 인스펙터가 보낸 UI 요소 컨텍스트. */
+export const designCaptures = sqliteTable('design_captures', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  url: text('url').notNull().default(''),
+  selector: text('selector').notNull().default(''),
+  html: text('html').notNull().default(''),
+  css: text('css').notNull().default(''),
+  note: text('note').notNull().default(''),
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+});
+
+/** 하나의 요청. 여러 AgentRun 으로 병렬 시도됨. */
+export const tasks = sqliteTable('tasks', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  repoId: integer('repo_id').notNull(),
+  title: text('title').notNull(),
+  prompt: text('prompt').notNull().default(''),
+  status: text('status').notNull().default('open'), // open | done
+  designCaptureId: integer('design_capture_id'), // 선택 — 프롬프트에 DESIGN CONTEXT 주입
+  createdAt: integer('created_at', { mode: 'timestamp' }),
+});
+
+/** 에이전트 1 = worktree 1 = tmux 창 1 = 브랜치 1. 태스크의 한 병렬 시도. */
+export const agentRuns = sqliteTable('agent_runs', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  taskId: integer('task_id').notNull(),
+  machineId: integer('machine_id').notNull(),
+  agent: text('agent').notNull().default('claude-code'),
+  worktreePath: text('worktree_path').notNull().default(''),
+  branch: text('branch').notNull().default(''),
+  tmuxWindow: text('tmux_window').notNull().default(''),
+  status: text('status').notNull().default('pending'), // pending | running | waiting | done | error
+  filesChanged: integer('files_changed').notNull().default(0),
+  startedAt: integer('started_at', { mode: 'timestamp' }),
+  endedAt: integer('ended_at', { mode: 'timestamp' }),
+  exitSummary: text('exit_summary').notNull().default(''),
+});
+
+/** 감사·재생용 이벤트(라이브는 WebSocket). */
+export const agentEvents = sqliteTable('agent_events', {
+  id: integer('id').primaryKey({ autoIncrement: true }),
+  runId: integer('run_id').notNull(),
+  kind: text('kind').notNull(), // output | status | diff | prompt
+  payload: text('payload').notNull().default(''),
+  ts: integer('ts', { mode: 'timestamp' }),
+});

package/src/design.ts

@@ -0,0 +1,89 @@
+// Design Mode 북마클릿 인스펙터 — 사용자의 개발 중 웹앱에 주입되어
+// 요소 호버 하이라이트 → 클릭 캡처(selector·HTML·computed CSS) → 데몬으로 POST.
+// 자신의 <script src> 에서 엔드포인트와 캡처 키를 읽는다.
+export const BOOKMARKLET_JS = `(function(){
+  if (window.__coxpitInspector) { window.__coxpitInspector.stop(); return; }
+  var script = document.currentScript || Array.from(document.scripts).find(function(s){return s.src.indexOf('/design/bookmarklet.js')>-1;});
+  if (!script) { alert('coxpit: cannot locate script origin'); return; }
+  var u = new URL(script.src);
+  var endpoint = u.origin + '/api/design/capture' + (u.search || '');
+
+  var box = document.createElement('div');
+  box.style.cssText = 'position:fixed;pointer-events:none;z-index:2147483646;border:2px solid #4ec9b0;background:rgba(78,201,176,.08);border-radius:3px;transition:all .06s;display:none';
+  var tag = document.createElement('div');
+  tag.style.cssText = 'position:fixed;z-index:2147483647;background:#0b0d12;color:#4ec9b0;font:11px ui-monospace,monospace;padding:3px 8px;border-radius:4px;pointer-events:none;display:none;max-width:60vw;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;border:1px solid #4ec9b0';
+  document.documentElement.appendChild(box); document.documentElement.appendChild(tag);
+
+  function cssPath(el){
+    var parts = [];
+    while (el && el.nodeType === 1 && parts.length < 6) {
+      var p = el.tagName.toLowerCase();
+      if (el.id) { parts.unshift(p + '#' + el.id); break; }
+      var cls = (el.className && typeof el.className === 'string') ? el.className.trim().split(/\\s+/).slice(0,2).join('.') : '';
+      if (cls) p += '.' + cls;
+      var parent = el.parentElement;
+      if (parent) {
+        var sibs = Array.from(parent.children).filter(function(c){return c.tagName===el.tagName;});
+        if (sibs.length > 1) p += ':nth-of-type(' + (sibs.indexOf(el)+1) + ')';
+      }
+      parts.unshift(p); el = parent;
+    }
+    return parts.join(' > ');
+  }
+  var CSS_PROPS = ['display','position','width','height','margin','padding','color','background-color','font-family','font-size','font-weight','line-height','border','border-radius','box-shadow','flex-direction','justify-content','align-items','gap','grid-template-columns','text-align','opacity','overflow','z-index'];
+  function styleOf(el){
+    var cs = getComputedStyle(el), out = {};
+    CSS_PROPS.forEach(function(k){ var v = cs.getPropertyValue(k); if (v) out[k]=v; });
+    return out;
+  }
+  function toast(msg, ok){
+    var t = document.createElement('div');
+    t.textContent = msg;
+    t.style.cssText = 'position:fixed;top:16px;right:16px;z-index:2147483647;background:#0b0d12;color:'+(ok?'#4ec9b0':'#e25b67')+';font:12px ui-monospace,monospace;padding:9px 14px;border-radius:7px;border:1px solid '+(ok?'#4ec9b0':'#e25b67');
+    document.documentElement.appendChild(t);
+    setTimeout(function(){ t.remove(); }, 2200);
+  }
+
+  var current = null;
+  function onMove(e){
+    var el = document.elementFromPoint(e.clientX, e.clientY);
+    if (!el || el===box || el===tag || el===document.documentElement || el===document.body) return;
+    current = el;
+    var r = el.getBoundingClientRect();
+    box.style.display='block';
+    box.style.left=r.left+'px'; box.style.top=r.top+'px'; box.style.width=r.width+'px'; box.style.height=r.height+'px';
+    tag.style.display='block';
+    tag.style.left=Math.max(4,r.left)+'px'; tag.style.top=Math.max(4,r.top-26)+'px';
+    tag.textContent = cssPath(el) + '  ·  ' + Math.round(r.width)+'×'+Math.round(r.height);
+  }
+  function onClick(e){
+    if (!current) return;
+    e.preventDefault(); e.stopPropagation();
+    var el = current;
+    var body = {
+      url: location.href,
+      selector: cssPath(el),
+      html: (el.outerHTML||'').slice(0, 4000),
+      css: JSON.stringify(styleOf(el), null, 1).slice(0, 3000),
+      note: document.title,
+    };
+    fetch(endpoint, { method:'POST', headers:{'content-type':'application/json'}, body: JSON.stringify(body) })
+      .then(function(r){ if(!r.ok) throw new Error(r.status); toast('coxpit: captured ' + body.selector, true); })
+      .catch(function(err){ toast('coxpit: capture failed ('+err.message+')', false); });
+    stop();
+  }
+  function onKey(e){ if (e.key==='Escape') stop(); }
+  function stop(){
+    document.removeEventListener('mousemove', onMove, true);
+    document.removeEventListener('click', onClick, true);
+    document.removeEventListener('keydown', onKey, true);
+    box.remove(); tag.remove();
+    window.__coxpitInspector = null;
+  }
+  document.addEventListener('mousemove', onMove, true);
+  document.addEventListener('click', onClick, true);
+  document.addEventListener('keydown', onKey, true);
+  window.__coxpitInspector = { stop: stop };
+  toast('coxpit: click an element to capture · Esc to exit', true);
+})();
+`;

package/src/exec.ts

@@ -0,0 +1,75 @@
+import { execFile, spawn, type ChildProcess } from 'node:child_process';
+import { config } from './config';
+
+export interface RunResult {
+  ok: boolean;        // 프로세스가 exit 0 인가
+  code: number;       // exit code (-1 = spawn/timeout 실패)
+  stdout: string;
+  stderr: string;
+}
+
+/** 단일 프로세스 실행(promise). shell 없음 — 인자는 그대로 전달. */
+function run(file: string, args: string[], timeoutMs = 12000): Promise<RunResult> {
+  return new Promise((resolve) => {
+    execFile(file, args, { timeout: timeoutMs, maxBuffer: 1 << 20 }, (err, stdout, stderr) => {
+      if (!err) return resolve({ ok: true, code: 0, stdout: String(stdout), stderr: String(stderr) });
+      const code = typeof (err as NodeJS.ErrnoException).code === 'number'
+        ? (err as unknown as { code: number }).code
+        : -1;
+      resolve({ ok: false, code, stdout: String(stdout), stderr: String(stderr) });
+    });
+  });
+}
+
+/** POSIX 싱글쿼트 이스케이프 — 사용자 경로를 셸 커맨드에 안전하게 삽입. */
+export function shq(s: string): string {
+  return `'${s.replace(/'/g, `'\\''`)}'`;
+}
+
+export interface MachineTarget {
+  slug: string;
+  kind: string;
+  address: string;
+  sshUser: string;
+}
+
+function isLocal(m: MachineTarget): boolean {
+  return m.kind === 'local' || m.address === '';
+}
+
+/**
+ * 머신에서 셸 커맨드 1줄 실행.
+ * 로컬 → `sh -c`, 원격 → `ssh [-i key] user@addr <cmd>`.
+ * BatchMode=yes 라 비밀번호 프롬프트로 매달리지 않음(키/에이전트 없으면 즉시 실패).
+ */
+export async function runShellOn(m: MachineTarget, shellCmd: string, timeoutMs = 12000): Promise<RunResult> {
+  if (isLocal(m)) return run('sh', ['-c', shellCmd], timeoutMs);
+  const args: string[] = [
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=6',
+    '-o', 'StrictHostKeyChecking=accept-new',
+  ];
+  if (config.sshKey) args.push('-i', config.sshKey);
+  const target = m.sshUser ? `${m.sshUser}@${m.address}` : m.address;
+  args.push(target, shellCmd);
+  return run('ssh', args, timeoutMs);
+}
+
+/**
+ * 스트리밍 실행 — 자식 프로세스를 반환(stdout/stderr pipe).
+ * 오케스트레이터가 stdout 라인을 실시간 파싱하는 용도.
+ */
+export function spawnShellOn(m: MachineTarget, shellCmd: string): ChildProcess {
+  // detached → 자체 프로세스 그룹. stop 시 그룹 전체(-pid) SIGTERM 으로
+  // sh 의 손자(실제 에이전트)까지 확실히 종료.
+  if (isLocal(m)) return spawn('sh', ['-c', shellCmd], { stdio: ['ignore', 'pipe', 'pipe'], detached: true });
+  const args: string[] = [
+    '-o', 'BatchMode=yes',
+    '-o', 'ConnectTimeout=6',
+    '-o', 'StrictHostKeyChecking=accept-new',
+  ];
+  if (config.sshKey) args.push('-i', config.sshKey);
+  const target = m.sshUser ? `${m.sshUser}@${m.address}` : m.address;
+  args.push(target, shellCmd);
+  return spawn('ssh', args, { stdio: ['ignore', 'pipe', 'pipe'] });
+}

package/src/hub.ts

@@ -0,0 +1,21 @@
+// 라이브 이벤트 팬아웃 — /ws 소켓과 오케스트레이터를 잇는 초경량 허브.
+export interface Sink {
+  send: (data: string) => void;
+}
+
+const sinks = new Set<Sink>();
+
+export function addSink(s: Sink): void {
+  sinks.add(s);
+}
+export function removeSink(s: Sink): void {
+  sinks.delete(s);
+}
+
+/** 모든 구독 소켓에 JSON 이벤트 push. 개별 send 실패는 무시(끊긴 소켓). */
+export function broadcast(obj: unknown): void {
+  const data = JSON.stringify(obj);
+  for (const s of sinks) {
+    try { s.send(data); } catch { /* dead socket */ }
+  }
+}

package/src/index.ts

@@ -0,0 +1,14 @@
+import { config } from './config';
+import { db, ensureSchema } from './db';
+import { machines } from './db/schema';
+import { buildServer } from './server';
+
+await ensureSchema();
+
+// 첫 실행 시 로컬 머신 시드(데몬이 도는 이 기계).
+if ((await db.select().from(machines)).length === 0) {
+  await db.insert(machines).values({ slug: 'local', name: 'This machine', kind: 'local', online: true });
+}
+
+const app = await buildServer();
+await app.listen({ host: config.host, port: config.port });

package/src/orchestrator.ts

@@ -0,0 +1,304 @@
+import { posix as ppath } from 'node:path';
+import { createInterface } from 'node:readline';
+import type { ChildProcess } from 'node:child_process';
+import { eq } from 'drizzle-orm';
+import { config } from './config';
+import { db } from './db';
+import { agentRuns, agentEvents, tasks, repos, machines, designCaptures } from './db/schema';
+import { runShellOn, spawnShellOn, shq, type MachineTarget } from './exec';
+import { broadcast } from './hub';
+
+/** 에이전트 실행 커맨드. 드라이런=모의 stream-json + 실제 파일 1건 변경. */
+function agentCommand(prompt: string, real: boolean): string {
+  if (real) {
+    // claude-code headless. stream-json 라인이 stdout 으로 흐른다.
+    return `${config.agent.bin} -p ${shq(prompt)} --output-format stream-json --verbose` +
+      ` --permission-mode ${config.agent.perm}`;
+  }
+  // 모의: init → assistant → (파일 변경) → result. 진짜 stream-json 라인 형태.
+  return [
+    `printf '%s\\n' '{"type":"system","subtype":"init","session":"dryrun"}'`,
+    `printf '%s\\n' '{"type":"assistant","text":"planning: '"$(printf %s ${shq(prompt)} | cut -c1-40)"'"}'`,
+    `printf '%s\\n' 'coxpit dry-run' > COXPIT_DRYRUN.txt`,
+    `printf '%s\\n' '{"type":"assistant","text":"edited COXPIT_DRYRUN.txt"}'`,
+    `printf '%s\\n' '{"type":"result","subtype":"success","num_turns":1}'`,
+  ].join('; ');
+}
+
+async function recordEvent(runId: number, kind: string, payload: string): Promise<void> {
+  await db.insert(agentEvents).values({ runId, kind, payload });
+  broadcast({ type: 'event', runId, kind, payload });
+}
+
+async function setRun(runId: number, patch: Partial<typeof agentRuns.$inferInsert>): Promise<void> {
+  await db.update(agentRuns).set(patch).where(eq(agentRuns.id, runId));
+  broadcast({ type: 'run', runId, ...patch });
+}
+
+// 실행 중 run 의 자식 프로세스(stop 용). stoppedRuns = 사용자가 멈춘 run 표식.
+const liveChildren = new Map<number, ChildProcess>();
+const stoppedRuns = new Set<number>();
+
+interface RunContext {
+  runId: number;
+  machine: MachineTarget;
+  repoPath: string;
+  baseBranch: string;
+  prompt: string;
+  real: boolean;
+}
+
+async function loadContext(runId: number): Promise<RunContext | null> {
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!run) return null;
+  const tr = await db.select().from(tasks).where(eq(tasks.id, run.taskId)).limit(1);
+  const task = tr[0];
+  if (!task) return null;
+  const rp = await db.select().from(repos).where(eq(repos.id, task.repoId)).limit(1);
+  const repo = rp[0];
+  if (!repo) return null;
+  const mr = await db.select().from(machines).where(eq(machines.id, repo.machineId)).limit(1);
+  const m = mr[0];
+  if (!m) return null;
+
+  // Design Mode — 태스크에 캡처가 연결돼 있으면 프롬프트에 컨텍스트 블록 주입
+  let prompt = task.prompt;
+  if (task.designCaptureId) {
+    const dc = (await db.select().from(designCaptures).where(eq(designCaptures.id, task.designCaptureId)).limit(1))[0];
+    if (dc) {
+      prompt += `\n\n--- DESIGN CONTEXT (captured from the running app) ---\n` +
+        `Page: ${dc.url}\nSelector: ${dc.selector}\n` +
+        `Element HTML:\n${dc.html}\n` +
+        `Computed styles:\n${dc.css}\n` +
+        `--- END DESIGN CONTEXT ---`;
+    }
+  }
+
+  return {
+    runId,
+    machine: { slug: m.slug, kind: m.kind, address: m.address, sshUser: m.sshUser },
+    repoPath: repo.path,
+    baseBranch: repo.defaultBranch,
+    prompt,
+    real: run.agent === 'claude-code' ? config.agent.real : config.agent.real,
+  };
+}
+
+/**
+ * 한 AgentRun 실행: worktree 생성 → tmux 창(best-effort) → 에이전트 spawn →
+ * stdout 라인 파싱하며 이벤트 적재 → 종료 시 files_changed 집계 + status 전이.
+ * fire-and-forget. 실패는 status='error' 로 봉인.
+ */
+export async function launchRun(runId: number, real?: boolean): Promise<void> {
+  const ctx = await loadContext(runId);
+  if (!ctx) return;
+  const useReal = real ?? ctx.real;
+
+  const branch = `coxpit/r${runId}`;
+  const wtParent = ppath.join(ppath.dirname(ctx.repoPath), '.coxpit-worktrees');
+  const wtPath = ppath.join(wtParent, `r${runId}`);
+  const session = `coxpit-r${runId}`;
+
+  try {
+    await setRun(runId, { status: 'preparing', branch, worktreePath: wtPath, tmuxWindow: session, startedAt: new Date() });
+
+    // 1) worktree 생성(격리 브랜치)
+    const prep = await runShellOn(
+      ctx.machine,
+      `mkdir -p ${shq(wtParent)} && git -C ${shq(ctx.repoPath)} worktree add -b ${shq(branch)} ${shq(wtPath)} ${shq(ctx.baseBranch)}`,
+      20000,
+    );
+    if (!prep.ok) {
+      await recordEvent(runId, 'error', (prep.stderr || prep.stdout).trim().slice(0, 500));
+      await setRun(runId, { status: 'error', endedAt: new Date(), exitSummary: 'worktree add failed' });
+      return;
+    }
+
+    // 2) tmux 창(사람이 attach 해 개입할 수 있게) — best-effort
+    await runShellOn(ctx.machine, `tmux new-session -d -s ${shq(session)} -c ${shq(wtPath)} 2>/dev/null || true`, 8000);
+
+    await setRun(runId, { status: 'running' });
+    await recordEvent(runId, 'meta', JSON.stringify({ branch, worktree: wtPath, real: useReal }));
+
+    // 3) 에이전트 spawn(스트리밍)
+    // 원격은 ssh 채널이 죽어도 프로세스가 남을 수 있어 pid 파일을 남긴다(stop 시 원격 kill).
+    const isRemote = ctx.machine.kind !== 'local' && ctx.machine.address !== '';
+    const pidPrefix = isRemote ? `printf '%s' "$$" > .coxpit-agent.pid && ` : '';
+    const cmd = `cd ${shq(wtPath)} && ${pidPrefix}{ ${agentCommand(ctx.prompt, useReal)}; }`;
+    const child = spawnShellOn(ctx.machine, cmd);
+    liveChildren.set(runId, child);
+
+    let lastResult = '';
+    if (child.stdout) {
+      const rl = createInterface({ input: child.stdout });
+      rl.on('line', (line: string) => {
+        const s = line.trim();
+        if (!s) return;
+        let kind = 'log';
+        try {
+          const obj = JSON.parse(s) as { type?: string; result?: string };
+          if (obj.type) kind = obj.type;
+          // result 이벤트의 사람이 읽는 요약만 뽑아 둔다(없으면 원본 라인).
+          if (obj.type === 'result') lastResult = typeof obj.result === 'string' ? obj.result : s;
+        } catch { /* 비-JSON 로그 라인 */ }
+        void recordEvent(runId, kind, s.slice(0, 2000));
+      });
+    }
+    if (child.stderr) {
+      const rle = createInterface({ input: child.stderr });
+      rle.on('line', (line: string) => {
+        const s = line.trim();
+        if (s) void recordEvent(runId, 'stderr', s.slice(0, 2000));
+      });
+    }
+
+    const code: number = await new Promise((resolve) => {
+      child.on('close', (c) => resolve(c ?? 0));
+      child.on('error', () => resolve(-1));
+    });
+    liveChildren.delete(runId);
+
+    // 4) 변경 파일 수 집계
+    const stat = await runShellOn(ctx.machine, `git -C ${shq(wtPath)} status --porcelain | wc -l`, 10000);
+    const filesChanged = stat.ok ? parseInt(stat.stdout.trim(), 10) || 0 : 0;
+
+    const wasStopped = stoppedRuns.delete(runId);
+    await setRun(runId, {
+      status: wasStopped ? 'stopped' : code === 0 ? 'done' : 'failed',
+      endedAt: new Date(),
+      filesChanged,
+      exitSummary: wasStopped ? 'stopped by user' : lastResult ? lastResult.slice(0, 500) : `exit ${code}`,
+    });
+  } catch (e) {
+    await recordEvent(runId, 'error', String(e).slice(0, 500));
+    await setRun(runId, { status: 'error', endedAt: new Date(), exitSummary: 'orchestrator error' });
+  }
+}
+
+/** 터미널 attach 용 — run 의 머신 타깃 + tmux 세션명. */
+export async function getRunTermInfo(runId: number): Promise<{ machine: MachineTarget; session: string } | null> {
+  const ctx = await loadContext(runId);
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!ctx || !run || !run.tmuxWindow) return null;
+  return { machine: ctx.machine, session: run.tmuxWindow };
+}
+
+/**
+ * 실행 중 run 중지 — 자식 프로세스 SIGTERM. close 핸들러가 status='stopped' 로 봉인.
+ */
+export async function stopRun(runId: number): Promise<{ ok: boolean; detail: string }> {
+  const child = liveChildren.get(runId);
+  if (!child) return { ok: false, detail: 'not running' };
+  stoppedRuns.add(runId);
+
+  // 원격이면 먼저 원격 프로세스를 pid 파일로 죽인다(ssh 채널만 끊으면 잔존 가능).
+  const ctx = await loadContext(runId);
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (ctx && run && ctx.machine.kind !== 'local' && ctx.machine.address !== '' && run.worktreePath) {
+    const pidFile = shq(`${run.worktreePath}/.coxpit-agent.pid`);
+    // 그룹 kill(-P, sshd 는 커맨드 셸을 세션리더로 띄워 성립) → 실패 시 자식(pkill -P)+본체 순.
+    await runShellOn(
+      ctx.machine,
+      `P=$(cat ${pidFile} 2>/dev/null) && { kill -TERM -"$P" 2>/dev/null || { pkill -TERM -P "$P" 2>/dev/null; kill -TERM "$P" 2>/dev/null; }; } || true`,
+      8000,
+    );
+  }
+
+  // 로컬(또는 ssh 채널) 프로세스 그룹 종료 — sh 손자(실제 에이전트) 포함.
+  try {
+    if (child.pid) process.kill(-child.pid, 'SIGTERM');
+    else child.kill('SIGTERM');
+  } catch {
+    child.kill('SIGTERM');
+  }
+  return { ok: true, detail: 'SIGTERM sent' };
+}
+
+/**
+ * run worktree 의 변경 diff — tracked 는 diff HEAD, untracked 는 /dev/null 대비.
+ */
+export async function getRunDiff(runId: number): Promise<{ ok: boolean; diff: string; stat: string }> {
+  const ctx = await loadContext(runId);
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!ctx || !run || !run.worktreePath) return { ok: false, diff: '', stat: 'no worktree' };
+  const wt = shq(run.worktreePath);
+  const cmd =
+    `git -C ${wt} status --porcelain` +
+    ` ; echo '---DIFF---'` +
+    ` ; git -C ${wt} diff HEAD` +
+    ` ; git -C ${wt} ls-files --others --exclude-standard | while IFS= read -r f; do` +
+    ` git -C ${wt} diff --no-index -- /dev/null "$f"; done ; true`;
+  const r = await runShellOn(ctx.machine, cmd, 20000);
+  const [stat = '', diff = ''] = r.stdout.split('---DIFF---\n');
+  return { ok: true, stat: stat.trim(), diff: diff.slice(0, 200_000) };
+}
+
+/**
+ * 승자 run 머지 — worktree 미커밋 변경을 자동 커밋 후 run 브랜치를
+ * repo 기본 브랜치에 merge. 본 repo 가 기본 브랜치+클린일 때만, 충돌 시 abort.
+ */
+export async function mergeRun(runId: number): Promise<{ ok: boolean; detail: string }> {
+  const ctx = await loadContext(runId);
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!ctx || !run || !run.worktreePath || !run.branch) return { ok: false, detail: 'no worktree/branch' };
+  if (liveChildren.has(runId)) return { ok: false, detail: 'still running — stop it first' };
+  const wt = shq(run.worktreePath);
+  const repo = shq(ctx.repoPath);
+  const ident = `-c user.name='coxpit' -c user.email='coxpit@local'`;
+
+  // 1) worktree 미커밋 변경 자동 커밋(있을 때만)
+  const c1 = await runShellOn(
+    ctx.machine,
+    `git -C ${wt} add -A && (git -C ${wt} diff --cached --quiet || git -C ${wt} ${ident} -c commit.gpgsign=false commit -m ${shq(`coxpit r${runId}: agent changes`)})`,
+    20000,
+  );
+  if (!c1.ok) return { ok: false, detail: 'worktree commit failed: ' + (c1.stderr || c1.stdout).trim().slice(0, 300) };
+
+  // 2) 본 repo 가드 — 기본 브랜치 위 + 클린
+  const guard = await runShellOn(
+    ctx.machine,
+    `git -C ${repo} rev-parse --abbrev-ref HEAD && echo '---S---' && git -C ${repo} status --porcelain`,
+    10000,
+  );
+  if (!guard.ok) return { ok: false, detail: 'repo check failed' };
+  const [head = '', dirty = ''] = guard.stdout.split('---S---');
+  if (head.trim() !== ctx.baseBranch) {
+    return { ok: false, detail: `repo is on '${head.trim()}', expected '${ctx.baseBranch}'` };
+  }
+  if (dirty.trim() !== '') return { ok: false, detail: 'repo working tree not clean' };
+
+  // 3) merge (충돌 시 abort)
+  const mg = await runShellOn(
+    ctx.machine,
+    `git -C ${repo} ${ident} -c commit.gpgsign=false merge --no-ff -m ${shq(`coxpit: merge r${runId} (${run.branch})`)} ${shq(run.branch)} 2>&1 || (git -C ${repo} merge --abort 2>/dev/null; echo COXPIT_MERGE_FAILED)`,
+    30000,
+  );
+  if (mg.stdout.includes('COXPIT_MERGE_FAILED')) {
+    return { ok: false, detail: 'merge conflict — aborted: ' + mg.stdout.replace('COXPIT_MERGE_FAILED', '').trim().slice(0, 300) };
+  }
+  await setRun(runId, { status: 'merged' });
+  return { ok: true, detail: mg.stdout.trim().slice(0, 300) };
+}
+
+/**
+ * worktree/브랜치/tmux 정리(태스크 종료·run 폐기 시).
+ */
+export async function cleanupRun(runId: number): Promise<{ ok: boolean; detail: string }> {
+  const ctx = await loadContext(runId);
+  const rr = await db.select().from(agentRuns).where(eq(agentRuns.id, runId)).limit(1);
+  const run = rr[0];
+  if (!ctx || !run || !run.worktreePath) return { ok: false, detail: 'no worktree' };
+  await runShellOn(ctx.machine, `tmux kill-session -t ${shq(`coxpit-r${runId}`)} 2>/dev/null || true`, 8000);
+  const rm = await runShellOn(
+    ctx.machine,
+    `git -C ${shq(ctx.repoPath)} worktree remove --force ${shq(run.worktreePath)} 2>&1` +
+    ` ; git -C ${shq(ctx.repoPath)} branch -D ${shq(run.branch)} 2>&1 || true`,
+    20000,
+  );
+  return { ok: true, detail: rm.stdout.trim().slice(0, 300) };
+}