@suseona/runner 0.0.0-stage → 1.0.1

package/README.md

@@ -1,3 +1,97 @@
-# Temporary Holding Version
+# e2e-runner — suseona 작업 에이전트 로컬 러너
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+내 컴퓨터의 **Claude Code** 로 `구현 → 테스트 → 리뷰 → 배포` 파이프라인을 자동 수행하는
+상주 데몬입니다. 코드는 내 폴더에, 실행은 내 Claude 구독으로 — 서버(e2e)는 오케스트레이션만
+담당합니다. 아웃바운드 폴링만 쓰므로 인바운드 포트·포트포워딩이 필요 없습니다.
+
+## 사전 조건
+
+- **Node.js ≥ 18.17**
+- **git**
+- **Claude Code CLI** 설치 + 로그인:
+  ```bash
+  npm install -g @anthropic-ai/claude-code
+  claude login   # 구독 계정으로 로그인
+  ```
+
+## 시작하기
+
+1. **웹에서 머신 등록**: [e2e](https://e2e.suseona.com) 로그인 → **머신** 페이지 →
+   "머신 추가" → 이름 입력(예: "맥북프로") → 발급된 토큰(`erun_…`) 복사.
+   토큰은 **이때 한 번만** 표시됩니다(분실 시 폐기 후 재등록).
+
+2. **내 컴퓨터에서 러너 시작**:
+   ```bash
+   E2E_RUNNER_TOKEN=erun_… npx @suseona/runner
+   ```
+   머신 상의 `runner/.env.local`(또는 셸 프로파일)에 넣어두면 env 없이 실행됩니다:
+   ```
+   E2E_RUNNER_TOKEN=erun_…
+   ```
+
+3. 웹 머신 페이지에서 **온라인** 배지와 `claude CLI` 상태를 확인하세요.
+
+4. **프로젝트 등록**(프로젝트 페이지) — 머신 선택 + 그 머신의 git 폴더 절대경로.
+   '경로 확인' 버튼으로 실제 존재·git 저장소·클린 트리를 미리 검증합니다.
+
+## 상시 구동(선택)
+
+**macOS — launchd** (`~/Library/LaunchAgents/com.suseona.e2e-runner.plist`):
+`PATH`에 node/claude가 보이도록 명시해야 합니다(launchd 기본 PATH엔 없음).
+```xml
+<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>com.suseona.e2e-runner</string>
+  <key>ProgramArguments</key><array>
+    <string>/usr/local/bin/node</string>
+    <string>/opt/e2e-runner/runner.mjs</string>
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>EnvironmentVariables</key><dict>
+    <key>PATH</key><string>/usr/local/bin:/opt/homebrew/bin:/usr/bin:/bin</string>
+    <key>HOME</key><string>/Users/YOU</string>
+    <key>E2E_RUNNER_TOKEN</key><string>erun_…</string>
+  </dict>
+  <key>StandardOutPath</key><string>/tmp/e2e-runner.log</string>
+  <key>StandardErrorPath</key><string>/tmp/e2e-runner.err</string>
+</dict></plist>
+```
+```bash
+launchctl load ~/Library/LaunchAgents/com.suseona.e2e-runner.plist
+```
+
+**Linux — systemd** (`~/.config/systemd/user/e2e-runner.service`):
+```ini
+[Unit]
+Description=suseona e2e runner
+After=network-online.target
+
+[Service]
+Environment=E2E_RUNNER_TOKEN=erun_…
+ExecStart=/usr/bin/node /opt/e2e-runner/runner.mjs
+Restart=always
+RestartSec=5
+
+[Install]
+WantedBy=default.target
+```
+
+**Windows** — 작업 스케줄러(로그인 시 `node runner.mjs`) 또는 NSSM 서비스.
+
+## 환경변수
+
+| 변수 | 필수 | 기본 | 설명 |
+|---|---|---|---|
+| `E2E_RUNNER_TOKEN` | ✅ | — | 웹에서 발급한 머신 토큰(`erun_…`) |
+| `AI_BASE_URL` | | `https://ai.suseona.com` | ai-backend 주소(자체 호스팅 시 변경) |
+| `CLAUDE_BIN` | | `claude` | claude CLI 경로(비표준 설치 위치) |
+| `POLL_S` / `HEARTBEAT_S` | | 3 / 30 | 폴링·하트비트 주기 |
+| `RUNNER_STEP_TIMEOUT_S` | | 2700 | 단계 타임아웃(서버 watchdog 3600s 보다 작게) |
+
+## 보안 노트
+
+- 토큰은 머신 단위 신원입니다 — 저장소·채팅에 커밋하지 마세요. 유출 시 웹에서 즉시 폐기.
+- 러너는 등록된 **내 프로젝트 폴더**에서만 작동하며, `bypassPermissions`로 Claude Code 가
+  파일 수정·커밋·(지정 시) 배포 커맨드를 실행합니다. 배포 커맨드는 내 머신 자격으로 실행됩니다.

package/api.mjs

@@ -0,0 +1,70 @@
+// ai-backend 작업 에이전트 채널 클라이얍트 — /ai/e2e/agent/runner/*.
+// 인증: 머신 개인 토큰(Authorization: Bearer erun_…) — 웹(머신 페이지)에서 발급.
+// 전역 시크릿(x-ai-secret)·자기선언 x-user-id 는 쓰지 않는다(다인 서비스).
+// 러너 경로는 사용자 rate limit 제외(main.py gate) — 3s 폴링·1s 플러시에 걸리지 않는다.
+//
+// ⚠️ BASE/헤더를 호출 시점에 읽는다(지연 평가) — runner.mjs 의 .env.local 로더가
+// import 평가 순서상 api.mjs top-level 상수보다 늦게 실행되기 때문.
+
+export const TOKEN_RE = /^erun_([0-9a-f]{32})_([0-9a-f]{64})$/;
+
+export function runnerToken() {
+  return (process.env.E2E_RUNNER_TOKEN || '').trim();
+}
+
+/** 토큰에서 머신 id 추출 — 로깅·표시용(신원 검증은 서버가 한다). */
+export function runnerIdFromToken(token = runnerToken()) {
+  const m = TOKEN_RE.exec(token);
+  return m ? m[1] : null;
+}
+
+function base() {
+  return (process.env.AI_BASE_URL || 'https://ai.suseona.com').replace(/\/+$/, '');
+}
+
+function headers() {
+  return {
+    'content-type': 'application/json',
+    authorization: `Bearer ${runnerToken()}`,
+  };
+}
+
+export class ApiError extends Error {
+  constructor(status, detail, path) {
+    super(`POST ${path} → ${status}: ${JSON.stringify(detail)}`);
+    this.status = status;
+    this.detail = detail;
+  }
+}
+
+/** POST 래퍼 — 네트워크 오류·5xx 만 2회 재시도(4xx 는 즉시 throw). */
+export async function api(path, body = {}, { retries = 2 } = {}) {
+  let lastErr;
+  for (let attempt = 0; attempt <= retries; attempt++) {
+    try {
+      const res = await fetch(`${base()}${path}`, {
+        method: 'POST',
+        headers: headers(),
+        body: JSON.stringify(body),
+      });
+      const text = await res.text();
+      const data = text ? JSON.parse(text) : {};
+      if (!res.ok) {
+        const err = new ApiError(res.status, data.detail ?? data.error, path);
+        if (res.status >= 500 && attempt < retries) {
+          lastErr = err;
+          continue;
+        }
+        throw err;
+      }
+      return data;
+    } catch (e) {
+      if (e instanceof ApiError) throw e;
+      lastErr = e; // 네트워크 오류 — 재시도
+    }
+    await sleep(500 * (attempt + 1));
+  }
+  throw lastErr;
+}
+
+export const sleep = (ms) => new Promise((r) => setTimeout(r, ms));

package/claude.mjs

@@ -0,0 +1,183 @@
+// Claude Code CLI(headless) 실행기 — stream-json 파싱·취소·타임아웃.
+// 인증은 Mac 의 Claude 로그인(구독) 그대로, 권한은 bypassPermissions(본인 프로젝트 전제).
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { sleep } from './api.mjs';
+
+const CLAUDE_BIN = process.env.CLAUDE_BIN || 'claude';
+
+// 러너와 서버(src/e2e/agent_prompts.py)가 동일 정규식을 유지 — 규약 변경 시 양쪽 수정.
+// (matchAll 사용 — g 플래그 필수)
+export const PHASE_RESULT_RE = /^PHASE_RESULT:\s*(PASS|FAIL)\s*$/gm;
+
+export function parsePhaseMarker(text) {
+  if (!text) return null; // 서버가 페이즈별 폴백 적용(implement=pass, 나머지=fail)
+  const m = [...text.matchAll(PHASE_RESULT_RE)];
+  return m.length ? m[m.length - 1][1].toLowerCase() : null;
+}
+
+/** `claude --version` 프로브 — 시작 시 1회(미설치 시 heartbeat ok:false 로 알림). */
+export function probeClaude() {
+  return new Promise((resolve) => {
+    const p = spawn(CLAUDE_BIN, ['--version'], { stdio: 'ignore' });
+    p.on('error', () => resolve(null));
+    p.on('exit', (code) => resolve(code === 0 ? CLAUDE_BIN : null));
+    setTimeout(() => {
+      p.kill('SIGKILL');
+      resolve(null);
+    }, 5000).unref?.();
+  });
+}
+
+const TEXT_MAX = 2000;   // message 이벤트 1건 텍스트 상한
+const BRIEF_MAX = 240;   // tool_use 요약 상한
+
+/**
+ * Claude Code 1세션 실행.
+ *
+ * @param {object} opts
+ * @param {string} opts.cwd            작업 폴더
+ * @param {string} opts.prompt         서버가 조립한 페이즈 프롬프트(prompt_md)
+ * @param {string|null} opts.resumeSessionId  이어받을 세션(null=신규)
+ * @param {number} opts.maxTurns       턴 상한(폭주 보호)
+ * @param {number} opts.timeoutS       세션 타임아웃(서버 watchdog 보다 작게)
+ * @param {(ev:{kind:string,data:object})=>void} opts.onEvent   message/tool 이벤트 콜백
+ * @param {()=>boolean} opts.shouldCancel  취소 플래그 폴링(라인 수신·1s 인터벌)
+ * @param {(sessionId:string)=>void} opts.onSessionId  init 이벤트 수신(session 저장·task_meta 전송)
+ * @returns {Promise<{ok:boolean, cancelled?:boolean, timedOut?:boolean, finalText?:string,
+ *                     sessionId?:string|null, usage?:object|null, error?:string|null}>}
+ */
+export function runClaude(opts) {
+  const { cwd, prompt, resumeSessionId, maxTurns, timeoutS, onEvent, shouldCancel, onSessionId } = opts;
+  return new Promise((resolve) => {
+    const args = [
+      '-p', prompt,
+      '--output-format', 'stream-json',
+      '--verbose',
+      '--permission-mode', 'bypassPermissions',
+      '--max-turns', String(maxTurns),
+      ...(resumeSessionId ? ['--resume', resumeSessionId] : []),
+    ];
+    const child = spawn(CLAUDE_BIN, args, { cwd, env: process.env });
+    let settled = false;
+    let cancelled = false;
+    let timedOut = false;
+    let finalText = '';
+    let usage = null;
+    let sessionId = resumeSessionId ?? null;
+    let stderrTail = '';
+
+    const finish = (out) => {
+      if (settled) return;
+      settled = true;
+      clearInterval(cancelTimer);
+      clearTimeout(timeoutTimer);
+      try {
+        child.stdout?.destroy();
+        child.stderr?.destroy();
+      } catch { /* already closed */ }
+      resolve(out);
+    };
+
+    // 타임아웃 — SIGTERM → 5s → SIGKILL
+    const timeoutTimer = setTimeout(() => {
+      timedOut = true;
+      killTree(child);
+      setTimeout(() => finish({
+        ok: false, timedOut: true,
+        finalText, sessionId, usage,
+        error: `단계 시간 초과(${timeoutS}s) — 세션을 종료했습니다.`,
+      }), 5000);
+    }, timeoutS * 1000);
+
+    // 취소 폴링(1s) — 이벤트 흐름이 뜸할 때도 반응
+    const cancelTimer = setInterval(() => {
+      if (!cancelled && shouldCancel()) {
+        cancelled = true;
+        killTree(child);
+      }
+    }, 1000);
+
+    const rl = createInterface({ input: child.stdout });
+    rl.on('line', (line) => {
+      line = line.trim();
+      if (!line) return;
+      if (!cancelled && shouldCancel()) {
+        cancelled = true;
+        killTree(child);
+        return;
+      }
+      let ev;
+      try {
+        ev = JSON.parse(line);
+      } catch {
+        return; // stream-json 이 아니면 무시(경고 스트림 등)
+      }
+      if (ev.type === 'system' && ev.subtype === 'init' && ev.session_id) {
+        sessionId = ev.session_id;
+        onSessionId?.(ev.session_id);
+        return;
+      }
+      if (ev.type === 'assistant' && Array.isArray(ev.message?.content)) {
+        for (const block of ev.message.content) {
+          if (block.type === 'text' && block.text) {
+            onEvent?.({ kind: 'message', data: { text: block.text.slice(0, TEXT_MAX) } });
+          } else if (block.type === 'tool_use') {
+            onEvent?.({
+              kind: 'tool',
+              data: { name: block.name, brief: JSON.stringify(block.input ?? {}).slice(0, BRIEF_MAX) },
+            });
+          }
+        }
+        return;
+      }
+      if (ev.type === 'result') {
+        finalText = ev.result ?? finalText;
+        usage = ev.usage
+          ? {
+            input_tokens: ev.usage.input_tokens ?? 0,
+            output_tokens: ev.usage.output_tokens ?? 0,
+            total_tokens: (ev.usage.input_tokens ?? 0) + (ev.usage.output_tokens ?? 0),
+          }
+          : usage;
+        if (ev.session_id) sessionId = ev.session_id;
+        return;
+      }
+    });
+
+    child.stderr?.on('data', (chunk) => {
+      stderrTail = `${stderrTail}${chunk}`.slice(-2000);
+    });
+
+    child.on('error', (e) => {
+      finish({ ok: false, finalText, sessionId, usage, error: `claude 실행 실패: ${e.message}` });
+    });
+
+    child.on('close', (code) => {
+      if (cancelled) {
+        finish({ ok: false, cancelled: true, finalText, sessionId, usage, error: 'cancelled' });
+      } else if (timedOut) {
+        return; // 타임아웃 finish 가 처리
+      } else if (code === 0) {
+        finish({ ok: true, finalText, sessionId, usage, error: null });
+      } else {
+        finish({
+          ok: false, finalText, sessionId, usage,
+          error: stderrTail.trim() || `claude 종료 코드 ${code}`,
+        });
+      }
+    });
+  });
+}
+
+/** 프로세스 그룹 종료(SIGTERM) — 자식 셸까지 남지 않게 detached 옵션은 쓰지 않고 프로세스만. */
+function killTree(child) {
+  try {
+    child.kill('SIGTERM');
+    setTimeout(() => {
+      try {
+        child.kill('SIGKILL');
+      } catch { /* already dead */ }
+    }, 5000).unref?.();
+  } catch { /* already dead */ }
+}

package/git.mjs

@@ -0,0 +1,87 @@
+// 작업 폴더 git 조작 — 결정적 조작은 러너가(LLM 아님): 브랜치 격리·병합·클린 트리 검증.
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { basename } from 'node:path';
+import { existsSync, statSync } from 'node:fs';
+
+const exec = promisify(execFile);
+
+export class GitError extends Error {}
+
+async function run(cwd, ...args) {
+  try {
+    const { stdout } = await exec('git', args, { cwd, maxBuffer: 16 * 1024 * 1024 });
+    return stdout.trim();
+  } catch (e) {
+    throw new GitError(`git ${args.join(' ')} 실패: ${(e.stderr || e.message || '').trim().slice(0, 500)}`);
+  }
+}
+
+/** 경로 확인(프로젝트 생성 다이얼로그) — 존재·git 저장소·브랜치·클린 트리·레포명 조사.
+ *  preflight 와 달리 절대 throw 하지 않는다: 결과 객체(ok/error)를 서버에 그대로 보고. */
+export async function probeFolder(cwd) {
+  const base = { path: cwd, name: basename(cwd) };
+  try {
+    if (!existsSync(cwd)) return { ...base, ok: false, error: '이 경로는 머신에 존재하지 않습니다.', code: 'not_found' };
+    if (!statSync(cwd).isDirectory()) return { ...base, ok: false, error: '폴더가 아닙니다(파일).', code: 'not_dir' };
+    const inside = await run(cwd, 'rev-parse', '--is-inside-work-tree');
+    if (inside !== 'true') return { ...base, ok: false, error: 'git 저장소가 아닙니다.', code: 'not_git' };
+    const branch = await run(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+    let remote = null;
+    try {
+      remote = await run(cwd, 'remote', 'get-url', 'origin');
+    } catch {
+      /* origin 없음 — 로컬 전용 저장소 */
+    }
+    const dirty = await run(cwd, 'status', '--porcelain');
+    const dirtyCount = dirty ? dirty.split('\n').filter(Boolean).length : 0;
+    return { ...base, ok: true, branch, remote, clean: dirtyCount === 0, dirty_count: dirtyCount };
+  } catch (e) {
+    return { ...base, ok: false, error: e.message?.slice(0, 300) || String(e), code: 'error' };
+  }
+}
+
+/** 실행 전 검증 — 폴더 존재·git 저장소·클린 워킹트리(사용자 미커밋 변경 보호). */
+export async function preflight(cwd) {
+  if (!existsSync(cwd)) throw new GitError(`프로젝트 폴더가 없습니다: ${cwd}`);
+  const inside = await run(cwd, 'rev-parse', '--is-inside-work-tree');
+  if (inside !== 'true') throw new GitError('git 저장소가 아닙니다(작업 브랜치·병합 불가).');
+  const dirty = await run(cwd, 'status', '--porcelain');
+  if (dirty) throw new GitError('커밋되지 않은 변경이 있어 작업을 시작할 수 없습니다 — 폴더를 정리(커밋/stash)한 뒤 다시 시도하세요.');
+}
+
+export async function currentBranch(cwd) {
+  return run(cwd, 'rev-parse', '--abbrev-ref', 'HEAD');
+}
+
+export function taskBranchName(taskId) {
+  return `e2e-task/${String(taskId).slice(0, 8)}`;
+}
+
+/** 작업 브랜치 생성(있으면 체크아웃) — implement 단계 전 1회. */
+export async function ensureTaskBranch(cwd, taskId) {
+  const branch = taskBranchName(taskId);
+  const branches = await run(cwd, 'branch', '--list', branch);
+  if (branches) {
+    await run(cwd, 'checkout', branch);
+  } else {
+    await run(cwd, 'checkout', '-b', branch);
+  }
+  return branch;
+}
+
+/** review 통과 후 base 로 병합(--no-ff — 작업 단위 커밋 흔적 보존). 충돌 시 GitError. */
+export async function mergeToBase(cwd, base, branch) {
+  await run(cwd, 'checkout', base);
+  try {
+    await run(cwd, 'merge', '--no-ff', branch, '-m', `merge ${branch} (e2e 작업 완료)`);
+  } catch (e) {
+    // 충돌 남은 상태 정리 — 다음 시도/수동 개입이 깨끗한 트리에서 시작되게.
+    try {
+      await run(cwd, 'merge', '--abort');
+    } catch {
+      /* already resolved/aborted */
+    }
+    throw new GitError(`base(${base}) 병합 충돌: 수동 해결이 필요합니다. 브랜치 \`${branch}\` 참조. ${e.message}`);
+  }
+}

package/package.json

@@ -1,6 +1,27 @@
 {
   "name": "@suseona/runner",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "1.0.1",
+  "description": "suseona e2e 작업 에이전트 로컬 러너 — 내 컴퓨터의 Claude Code 로 구현→테스트→리뷰→배포를 자동 수행",
+  "type": "module",
+  "license": "UNLICENSED",
+  "private": false,
+  "bin": {
+    "runner": "./runner.mjs",
+    "e2e-runner": "./runner.mjs"
+  },
+  "engines": {
+    "node": ">=18.17"
+  },
+  "files": [
+    "runner.mjs",
+    "api.mjs",
+    "claude.mjs",
+    "git.mjs",
+    "README.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/variouscafe/e2e",
+    "directory": "runner"
+  }
+}

package/runner.mjs

@@ -0,0 +1,334 @@
+#!/usr/bin/env node
+// e2e 작업 에이전트 로컬 러너 — 사용자 머신에서 Claude Code 파이프라인을 실행하는 상주 데몬.
+//
+// 역할: ai-backend(/ai/e2e/agent/runner/*) 폴링 → 단계 클레임 → 프로젝트 폴더에서
+// claude -p(또는 deploy_command) 실행 → 이벤트 스트리밍 → 종결 보고. 판단(다음 단계)은
+// 서버의 무상태 상태머신이 담당 — 러너는 충실한 실행기다.
+//
+// 인증: 머신 개인 토큰 E2E_RUNNER_TOKEN(erun_… — 웹 '머신' 페이지에서 발급).
+// 사전 조건: Node ≥18, git, Claude Code CLI 설치+로그인(claude login).
+//
+// 실행: npx @suseona/runner  또는  node runner.mjs — env 는 셸 export 또는
+// runner/.env.local(KEY=VALUE, gitignored).
+import { hostname } from 'node:os';
+import { spawn } from 'node:child_process';
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { api, runnerIdFromToken, sleep } from './api.mjs';
+import { parsePhaseMarker, probeClaude, runClaude } from './claude.mjs';
+import {
+  currentBranch, ensureTaskBranch, GitError, mergeToBase, preflight, probeFolder, taskBranchName,
+} from './git.mjs';
+
+// runner/.env.local 자동 로드 — 이미 설정된 env 는 덮지 않는다(셀 export 우선).
+{
+  const envPath = join(dirname(fileURLToPath(import.meta.url)), '.env.local');
+  try {
+    for (const line of readFileSync(envPath, 'utf8').split('\n')) {
+      const m = line.match(/^\s*([A-Z_][A-Z0-9_]*)\s*=\s*(.*)\s*$/);
+      if (m && process.env[m[1]] === undefined) process.env[m[1]] = m[2].replace(/^["']|["']$/g, '');
+    }
+  } catch {
+    /* .env.local 없음 — 정상 */
+  }
+}
+
+const RUNNER_VERSION = (() => {
+  try {
+    return JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), 'package.json'), 'utf8')).version;
+  } catch {
+    return '0.0.0';
+  }
+})();
+
+const POLL_S = num(process.env.POLL_S, 3);
+const HEARTBEAT_S = num(process.env.HEARTBEAT_S, 30);
+const FLUSH_S = num(process.env.FLUSH_S, 1);
+const STEP_TIMEOUT_S = num(process.env.RUNNER_STEP_TIMEOUT_S, 2700); // 서버 watchdog(3600s)보다 작게
+const DEPLOY_TIMEOUT_S = num(process.env.DEPLOY_TIMEOUT_S, 600);
+const MAX_TURNS_IMPLEMENT = num(process.env.MAX_TURNS_IMPLEMENT, 150);
+const MAX_TURNS_OTHER = num(process.env.MAX_TURNS_OTHER, 60);
+const BUSY_PROBE_POLL_S = 10; // 단계 실행 중 경로 확인(probe) 폴링 주기
+
+function num(v, dflt) {
+  const n = Number(v);
+  return Number.isFinite(n) && n > 0 ? n : dflt;
+}
+
+// ─── 공유 상태 ────────────────────────────────────────────────────────────────
+
+const state = {
+  runnerId: null,            // 토큰에서 유도(서버 발급 머신 id)
+  claudeBin: null,           // probe 결과(null=미설치)
+  cancelTaskIds: [],         // 서버 응답마다 갱신 — claude 세션 취소 플래그로 사용
+  currentTaskId: null,
+  currentStepId: null,
+  busy: false,
+  lastBusyProbeAt: 0,
+};
+
+function mergeCancels(res) {
+  if (Array.isArray(res?.cancel_task_ids)) state.cancelTaskIds = res.cancel_task_ids;
+}
+
+function log(...args) {
+  console.log(new Date().toISOString(), ...args);
+}
+
+// ─── 경로 확인(probe) — 프로젝트 생성 다이얼로그 '경로 확인' 버튼 ─────────────
+
+async function runProbe({ probe_id, folder_path }) {
+  try {
+    const result = await probeFolder(folder_path);
+    await api('/ai/e2e/agent/runner/probe_result', { probe_id, result });
+    log(`probe 완료: ${folder_path} → ${result.ok ? 'ok' : result.error}`);
+  } catch (e) {
+    log(`probe 실패(probe_id=${probe_id}): ${e.message}`);
+  }
+}
+
+function handleProbe(res) {
+  if (res?.probe?.probe_id && res.probe.folder_path) void runProbe(res.probe);
+}
+
+// ─── 이벤트 버퍼(1s 플러시) ───────────────────────────────────────────────────
+
+class EventBuffer {
+  constructor(taskId) {
+    this.taskId = taskId;
+    this.events = [];
+    this.taskMeta = null;   // init 수신 즉시 1회 전송(base_branch/branch/session_id)
+    this.timer = null;
+  }
+
+  start() {
+    this.timer = setInterval(() => this.flush(), FLUSH_S * 1000);
+  }
+
+  async stop() {
+    clearInterval(this.timer);
+    await this.flush();
+  }
+
+  push(stepId, kind, data) {
+    this.events.push({ step_id: stepId, kind, data });
+    if (this.events.length >= 100) this.flush().catch(() => {});
+  }
+
+  async flush() {
+    const events = this.events.splice(0);
+    const taskMeta = this.taskMeta;
+    this.taskMeta = null;
+    if (!events.length && !taskMeta) return;
+    try {
+      const res = await api('/ai/e2e/agent/runner/events', {
+        task_id: this.taskId, events, ...(taskMeta ? { task_meta: taskMeta } : {}),
+      });
+      mergeCancels(res);
+    } catch (e) {
+      log(`event flush 실패(${e.message}) — ${events.length}건 유실`);
+    }
+  }
+}
+
+// ─── 단계 실행 ────────────────────────────────────────────────────────────────
+
+async function handleStep({ step, task, project }) {
+  const buf = new EventBuffer(task.id);
+  buf.start();
+  state.currentTaskId = task.id;
+  state.currentStepId = step.id;
+  const cancelled = () => state.cancelTaskIds.includes(task.id);
+
+  try {
+    // 시작 알림 — 서버가 step→running·task 진행률 갱신(상태머신 트리거)
+    buf.push(step.id, 'status', { event: 'phase_started', phase: step.phase });
+
+    let result;
+    if (step.phase === 'implement') {
+      result = await runImplement({ step, task, project, buf, cancelled });
+    } else if (step.phase === 'deploy') {
+      result = await runDeploy({ step, task, project, buf, cancelled });
+    } else {
+      // test / remediate / review — 서버 프롬프트(prompt_md)·세션(resume) 그대로 실행.
+      result = await runPhase({ step, task, project, buf, cancelled });
+    }
+
+    const cancelledNow = cancelled() || result?.cancelled;
+    await api('/ai/e2e/agent/runner/step_result', {
+      step_id: step.id,
+      status: cancelledNow ? 'fail' : result.ok ? 'done' : 'fail',
+      result_md: result.finalText ?? null,
+      result_flag: result.flag ?? null, // null이면 서버 폴백(implement=pass, 나머지=fail)
+      session_id: result.sessionId ?? null,
+      error: cancelledNow ? 'cancelled' : (result.error ?? null),
+      cancelled: Boolean(cancelledNow),
+      usage: result.usage ?? undefined,
+    });
+    log(`단계 종결: ${task.id.slice(0, 8)}/${step.phase} → ${cancelledNow ? 'cancelled' : result.ok ? 'done' : 'fail'}`);
+  } catch (e) {
+    // 프리플라이트 실패·예상치 못한 오류 — 단계 실패로 보고(상태머신이 task 수렴).
+    log(`단계 오류: ${e.message}`);
+    await api('/ai/e2e/agent/runner/step_result', {
+      step_id: step.id, status: 'fail', error: String(e.message).slice(0, 500),
+      cancelled: cancelled(),
+    }).catch(() => {});
+  } finally {
+    await buf.stop();
+    state.currentTaskId = null;
+    state.currentStepId = null;
+  }
+}
+
+/** implement — git 프리플라이트 → 작업 브랜치 → claude(신규 세션). base_branch 를 서버에 보고. */
+async function runImplement({ step, task, project, buf, cancelled }) {
+  await preflight(project.folder_path);
+  const base = await currentBranch(project.folder_path);
+  const branch = await ensureTaskBranch(project.folder_path, task.id);
+  buf.taskMeta = { base_branch: base, branch };
+  log(`브랜치 준비: ${branch} (base ${base})`);
+  return runPhase({ step, task, project, buf, cancelled, extraMeta: buf.taskMeta });
+}
+
+/** test/remediate/review 공통 — prompt_md + resume 세션. */
+async function runPhase({ step, task, project, buf, cancelled, extraMeta }) {
+  if (!state.claudeBin) throw new Error('claude CLI 를 찾을 수 없습니다 — CLAUDE_BIN 확인 후 러너를 재시작하세요.');
+  return runClaude({
+    cwd: project.folder_path,
+    prompt: step.prompt_md,
+    resumeSessionId: step.session_id ?? null,
+    maxTurns: step.phase === 'implement' ? MAX_TURNS_IMPLEMENT : MAX_TURNS_OTHER,
+    timeoutS: STEP_TIMEOUT_S,
+    onEvent: (ev) => buf.push(step.id, ev.kind, ev.data),
+    shouldCancel: cancelled,
+    onSessionId: (sessionId) => {
+      if (extraMeta) buf.taskMeta = { ...extraMeta, session_id: sessionId };
+      else buf.taskMeta = { session_id: sessionId };
+    },
+  }).then((r) => ({ ...r, flag: parsePhaseMarker(r.finalText) }));
+}
+
+/** deploy — 항상 base 병합 먼저(결정적 조작) → deploy_command 직접 실행 또는 claude 배포. */
+async function runDeploy({ step, task, project, buf, cancelled }) {
+  const base = task.base_branch || 'main';
+  const branch = task.branch || taskBranchName(task.id);
+  await mergeToBase(project.folder_path, base, branch);
+  log(`병합 완료: ${branch} → ${base}`);
+  buf.push(step.id, 'status', { event: 'merged', base, branch });
+
+  if (project.deploy_command) {
+    const output = await new Promise((resolve) => {
+      const child = spawn(project.deploy_command, {
+        cwd: project.folder_path, shell: true, env: process.env,
+      });
+      let out = '';
+      const onData = (c) => {
+        out = `${out}${c}`.slice(-8000);
+      };
+      child.stdout.on('data', onData);
+      child.stderr.on('data', onData);
+      const cancelTimer = setInterval(() => {
+        if (cancelled()) child.kill('SIGTERM');
+      }, 1000);
+      const killer = setTimeout(() => child.kill('SIGKILL'), DEPLOY_TIMEOUT_S * 1000);
+      child.on('close', (code) => {
+        clearInterval(cancelTimer);
+        clearTimeout(killer);
+        resolve({ code, out });
+      });
+    });
+    const ok = output.code === 0 && !cancelled();
+    buf.push(step.id, 'result', { name: 'deploy_command', exit: output.code, tail: output.out.slice(-1000) });
+    log(`배포 커맨드 종료 코드 ${output.code}`);
+    return {
+      ok,
+      cancelled: cancelled(),
+      finalText: `# 배포 커맨드 결과\n\n종료 코드: ${output.code}\n\n\`\`\`\n${output.out.trim() || '(출력 없음)'}\n\`\`\`\n\nPHASE_RESULT: ${ok ? 'PASS' : 'FAIL'}`,
+      flag: ok ? 'pass' : 'fail',
+      sessionId: step.session_id ?? null,
+    };
+  }
+
+  // deploy_command 없음 — Claude 가 프로젝트 관례(CLAUDE.md/스크립트)를 파악해 배포.
+  return runPhase({ step, task, project, buf, cancelled });
+}
+
+// ─── 메인 루프 ────────────────────────────────────────────────────────────────
+
+async function heartbeat() {
+  try {
+    const res = await api('/ai/e2e/agent/runner/heartbeat', {
+      version: RUNNER_VERSION,
+      platform: process.platform,
+      current_task_id: state.currentTaskId,
+      current_step_id: state.currentStepId,
+      ok: Boolean(state.claudeBin),
+      reason: state.claudeBin ? null : 'claude CLI not found (CLAUDE_BIN 확인 필요)',
+    });
+    mergeCancels(res);
+  } catch (e) {
+    log(`heartbeat 실패: ${e.message}`);
+  }
+}
+
+async function main() {
+  const token = (process.env.E2E_RUNNER_TOKEN || '').trim();
+  if (!token) {
+    console.error('필수 env 누락: E2E_RUNNER_TOKEN — 웹 "머신" 페이지에서 머신을 등록하고 발급된 토큰(erun_…)을 설정하세요.');
+    process.exit(1);
+  }
+  state.runnerId = runnerIdFromToken(token);
+  if (!state.runnerId) {
+    console.error('E2E_RUNNER_TOKEN 형식이 잘못되었습니다 — 웹에서 발급된 전체 토큰(erun_…)을 그대로 붙여넣세요.');
+    process.exit(1);
+  }
+  state.claudeBin = await probeClaude();
+  console.log(`e2e 러너 시작 — 머신 id ${state.runnerId} (${hostname()})`);
+  console.log(`ai-backend: ${process.env.AI_BASE_URL || 'https://ai.suseona.com'} / runner v${RUNNER_VERSION}`);
+  console.log(`claude: ${state.claudeBin ?? '미발견(heartbeat ok:false 알림)'}`);
+  setInterval(heartbeat, HEARTBEAT_S * 1000);
+  heartbeat();
+
+  for (;;) {
+    if (!state.busy) {
+      try {
+        const res = await api('/ai/e2e/agent/runner/poll', {});
+        mergeCancels(res);
+        handleProbe(res);
+        if (res.step) {
+          state.busy = true;
+          try {
+            await handleStep(res);
+          } finally {
+            state.busy = false;
+          }
+          continue; // 대기 없이 즉시 다음 폴링(연속 작업)
+        }
+      } catch (e) {
+        if (e.status !== 503 && e.status !== 401) log(`poll 실패: ${e.message}`);
+        else if (e.status === 503) log(`서버 미구성(E2E_D1_DATABASE_ID): ${e.message}`);
+        else if (e.status === 401) {
+          console.error('토큰이 거부되었습니다(폐기·오타) — 웹에서 머신을 재등록하고 E2E_RUNNER_TOKEN 을 갱신하세요.');
+          process.exit(1);
+        }
+      }
+    } else if (Date.now() - state.lastBusyProbeAt > BUSY_PROBE_POLL_S * 1000) {
+      // 단계 실행 중에도 경로 확인(probe)은 응답 가능 — probe_only 폴링(단계 클레임 없음).
+      state.lastBusyProbeAt = Date.now();
+      try {
+        const res = await api('/ai/e2e/agent/runner/poll', { probe_only: true });
+        mergeCancels(res);
+        handleProbe(res);
+      } catch {
+        /* probe 폴링 실패는 무시 — 다음 주기 재시도 */
+      }
+    }
+    await sleep(POLL_S * 1000);
+  }
+}
+
+main().catch((e) => {
+  console.error('러너 치명 오류:', e);
+  process.exit(1);
+});