e2e-agent-runner 1.0.0 → 1.1.0

package/README.md

@@ -1,6 +1,6 @@
 # e2e-runner — suseona 작업 에이전트 로컬 러너
 
-내 컴퓨터의 **Claude Code** 로 `구현 → 테스트 → 리뷰 → 배포` 파이프라인을 자동 수행하는
+내 컴퓨터의 **Claude Code** 로 `구현 → 테스트 → 리뷰 → 배포` 파이프라인과 웹사이트 기능 지도 추출을 자동 수행하는
 상주 데몬입니다. 코드는 내 폴더에, 실행은 내 Claude 구독으로 — 서버(e2e)는 오케스트레이션만
 담당합니다. 아웃바운드 폴링만 쓰므로 인바운드 포트·포트포워딩이 필요 없습니다.
 
@@ -89,6 +89,20 @@ WantedBy=default.target
 | `CLAUDE_BIN` | | `claude` | claude CLI 경로(비표준 설치 위치) |
 | `POLL_S` / `HEARTBEAT_S` | | 3 / 30 | 폴링·하트비트 주기 |
 | `RUNNER_STEP_TIMEOUT_S` | | 2700 | 단계 타임아웃(서버 watchdog 3600s 보다 작게) |
+| `DISCOVER_TIMEOUT_S` / `MAX_TURNS_DISCOVER` | | 5400 / 500 | 기능 지도 추출 시간·턴 상한 |
+| `E2E_BROWSER_MCP` | | (Playwright) | `off`=브라우저 없이 코드만 / MCP 설정 JSON 경로=사용자 지정 브라우저 MCP |
+| `E2E_PLAYWRIGHT_MCP` | | `@playwright/mcp@0.0.84` | 기능 지도용 Playwright MCP 패키지 스펙 |
+| `E2E_BROWSER_HEADED` | | — | `1`이면 브라우저 창을 띄워 탐색(디버깅) |
+
+## 기능 지도 추출(웹사이트 프로젝트)
+
+웹에서 프로젝트 유형을 **웹사이트**로 지정하면 "기능 지도 추출"을 실행할 수 있습니다. 러너는
+Claude Code 에 **Playwright MCP**(`npx @playwright/mcp`, 격리 프로필·헤드리스)를 붙여 실행하고,
+Claude 는 소스의 라우트 정의를 읽은 뒤 **라이브 사이트에 직접 접속해 화면을 보며** 라우트별 기능과
+상세 정의(흐름·입력 검증·기대 결과·상태·예외·QA 체크포인트)를 임시 폴더에 기록합니다. 러너가 이를
+수집해 서버에 보고합니다. 이 단계는 **읽기 전용**(브랜치·커밋 없음)이며 라이브 사이트에서 삭제·결제·
+발송 같은 파괴적 동작을 하지 않도록 지시됩니다. 첫 실행 시 브라우저 다운로드가 필요할 수 있습니다
+(Claude 가 `browser_install` 로 자동 설치).
 
 ## 보안 노트
 

package/claude.mjs

@@ -44,11 +44,13 @@ const BRIEF_MAX = 240;   // tool_use 요약 상한
  * @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 전송)
+ * @param {string[]} [opts.extraArgs]  claude 추가 인자(discover 의 MCP·추가 디렉터리)
  * @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;
+  const extraArgs = opts.extraArgs ?? [];
   return new Promise((resolve) => {
     const args = [
       '-p', prompt,
@@ -57,11 +59,15 @@ export function runClaude(opts) {
       '--permission-mode', 'bypassPermissions',
       '--max-turns', String(maxTurns),
       ...(resumeSessionId ? ['--resume', resumeSessionId] : []),
+      // 페이즈별 추가 플래그(discover: --mcp-config 브라우저 MCP·--add-dir 산출 폴더).
+      // 가변 인자 플래그(--mcp-config/--add-dir)가 프롬프트를 삼키지 않도록 항상 마지막에 둔다.
+      ...extraArgs,
     ];
     // detached(POSIX)=신규 프로세스 그룹 — 취소·타임아웃이 claude 가 띄운 도구 자식(bash 등)까지
     // 종료시킨다. detached 로 파이프(stdio)는 그대로 동작한다.
+    // stdin 은 닫는다 — 파이프로 열려 있으면 claude -p 가 입력을 3s 기다린 뒤 경고하고 진행한다.
     const child = spawn(CLAUDE_BIN, args, {
-      cwd, env: process.env, detached: process.platform !== 'win32',
+      cwd, env: process.env, detached: process.platform !== 'win32', stdio: ['ignore', 'pipe', 'pipe'],
     });
     let settled = false;
     let cancelled = false;

package/discover.mjs

@@ -0,0 +1,190 @@
+// 기능 지도(Feature Map) 추출 — discover 페이즈 실행기.
+//
+// Claude Code 를 프로젝트 폴더(소스 코드 정찰)에서 실행하되, 브라우저 MCP(Playwright)를 붙여
+// 라이브 사이트에 직접 접속해 화면(스크린샷·접근성 스냅샷)을 보며 기능을 확인하게 한다.
+// Claude 는 러너가 만든 임시 산출 폴더에 라우트별 JSON(routes/NNN.json)과 map.json 을
+// 점진적으로 기록하고, 러너는 종료 후(시간 초과·실패 포함) 기록분을 수집해 artifact 로 보고한다.
+//
+// 읽기 전용 페이즈: git 브랜치·프리플라이트·커밋 없음. 저장소가 수정되면 경고 이벤트만 남긴다
+// (변경을 되돌리지 않는다 — 사용자 파일일 수 있으므로 판단은 사용자에게).
+//
+// env:
+//   E2E_BROWSER_MCP        off=브라우저 없이(코드만) | <JSON 파일 경로>=사용자 MCP 설정 | 미설정=Playwright MCP
+//   E2E_PLAYWRIGHT_MCP     Playwright MCP 패키지 스펙(기본 @playwright/mcp@0.0.84 — 고정 버전)
+//   E2E_BROWSER_HEADED=1   브라우저 창 표시(디버깅)
+//   E2E_KEEP_FM_OUT=1      산출 폴더 보존(디버깅)
+import { mkdtempSync, mkdirSync, readdirSync, readFileSync, rmSync, statSync, writeFileSync, existsSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+
+const exec = promisify(execFile);
+
+const PLAYWRIGHT_MCP = process.env.E2E_PLAYWRIGHT_MCP || '@playwright/mcp@0.0.84';
+const ARTIFACT_MAX_BYTES = 6 * 1024 * 1024; // step_result 본문 상한(서버가 다시 정규화·절단)
+const ROUTE_FILE_MAX_BYTES = 1024 * 1024;
+
+/** 산출 폴더 준비 + 브라우저 MCP 설정 → { outDir, routesDir, extraArgs, browser, promptAddon, cleanup } */
+export function prepareDiscover({ siteUrl }) {
+  const outDir = mkdtempSync(join(tmpdir(), 'e2e-fm-'));
+  const routesDir = join(outDir, 'routes');
+  const shotsDir = join(outDir, 'shots');
+  mkdirSync(routesDir, { recursive: true });
+  mkdirSync(shotsDir, { recursive: true });
+
+  const mode = (process.env.E2E_BROWSER_MCP || '').trim();
+  let mcpPath = null;
+  let browser = 'playwright';
+  if (mode === 'off') {
+    browser = 'off';
+  } else if (mode && existsSync(mode)) {
+    mcpPath = mode; // 사용자 제공 MCP 설정(예: 사내 프록시·기존 Chrome 프로필)
+    browser = 'custom';
+  } else {
+    const pwArgs = [
+      '-y', PLAYWRIGHT_MCP,
+      '--isolated', // 매 실행 깨끗한 프로필 — 사용자 브라우저 세션·쿠키와 격리
+      '--viewport-size', '1440,900',
+      '--output-dir', shotsDir,
+      ...(process.env.E2E_BROWSER_HEADED === '1' ? [] : ['--headless']),
+    ];
+    // MCP 서버의 cwd 를 스크린샷 폴더로 고정 — Playwright MCP 는 상대 filename 을 자기 cwd(=claude cwd=
+    // 사용자 저장소) 기준으로 저장해 읽기 전용 탐색이 저장소를 오염시킨다(실검증에서 발견). mcp 설정엔
+    // cwd 필드가 없으므로 셸 래퍼로 이동 후 exec 한다(경로는 위치 인자로 전달 — 따옴표 주입 없음).
+    const server = process.platform === 'win32'
+      ? { command: 'cmd', args: ['/c', `cd /d "${shotsDir}" && npx ${pwArgs.map((a) => `"${a}"`).join(' ')}`] }
+      : { command: 'sh', args: ['-c', 'cd "$0" && exec npx "$@"', shotsDir, ...pwArgs] };
+    mcpPath = join(outDir, 'mcp.json');
+    writeFileSync(mcpPath, JSON.stringify({ mcpServers: { playwright: server } }, null, 2));
+  }
+
+  const extraArgs = ['--add-dir', outDir];
+  if (mcpPath) extraArgs.unshift('--mcp-config', mcpPath);
+
+  const promptAddon = [
+    '',
+    '# 산출물 위치(러너 지정 — 이 경로에만 쓰기)',
+    `- 라우트 파일 폴더: \`${routesDir}\`  (예: ${join(routesDir, '001.json')})`,
+    `- 서비스 요약 파일: \`${join(outDir, 'map.json')}\``,
+    `- 스크린샷 등 브라우저 산출물은 \`${shotsDir}\` 에 저장됩니다(저장소에 저장 금지).`,
+    '',
+    '# 브라우저 도구',
+    browser === 'off'
+      ? '- 이 머신은 브라우저 도구가 비활성화되어 있습니다(E2E_BROWSER_MCP=off). 코드 기반으로 추출하고 coverage.browser 를 "unavailable" 로 기록하세요.'
+      : [
+        `- 브라우저 MCP 도구(mcp__playwright__browser_* 등)를 사용해 ${siteUrl || '대상 사이트'} 에 직접 접속하세요.`,
+        '  browser_navigate 로 이동 → browser_take_screenshot 으로 화면을 직접 보고 → browser_snapshot 으로 요소를 확인 →',
+        '  browser_click/browser_type 등으로 비파괴적 상호작용을 확인합니다. 화면 폭 확인은 browser_resize.',
+        `- browser_take_screenshot 의 filename 을 지정할 때는 반드시 절대 경로(${shotsDir} 아래)를 쓰거나 생략하세요 — 저장소 폴더에 이미지를 저장하면 안 됩니다.`,
+        '- 브라우저 실행 파일이 없다는 오류가 나면 browser_install 도구를 한 번 실행한 뒤 다시 시도하세요.',
+        '- 브라우저 도구가 끝내 동작하지 않으면 코드 기반으로 계속하고 coverage.browser 를 "unavailable" 로 기록하세요.',
+      ].join('\n'),
+  ].join('\n');
+
+  const cleanup = () => {
+    if (process.env.E2E_KEEP_FM_OUT === '1') return;
+    try {
+      rmSync(outDir, { recursive: true, force: true });
+    } catch {
+      /* 임시 폴더 — OS 가 정리 */
+    }
+  };
+
+  return { outDir, routesDir, extraArgs, browser, promptAddon, cleanup };
+}
+
+/** 기록된 라우트 파일 수(진행률 이벤트용). */
+export function countRouteFiles(routesDir) {
+  try {
+    return readdirSync(routesDir).filter((f) => f.endsWith('.json')).length;
+  } catch {
+    return 0;
+  }
+}
+
+function readJson(path, maxBytes) {
+  const size = statSync(path).size;
+  if (size > maxBytes) throw new Error(`파일 과대(${size}B)`);
+  return JSON.parse(readFileSync(path, 'utf8'));
+}
+
+/** 최종 보고 텍스트의 마지막 ```json 블록 — 파일 기록이 전혀 없을 때의 폴백. */
+function fallbackFromText(text) {
+  if (!text) return null;
+  const blocks = [...text.matchAll(/```json\s*([\s\S]*?)```/g)];
+  for (let i = blocks.length - 1; i >= 0; i--) {
+    try {
+      const v = JSON.parse(blocks[i][1]);
+      if (v && Array.isArray(v.routes)) return v;
+      if (v && typeof v.path === 'string') return { routes: [v] };
+    } catch {
+      /* 다음 블록 */
+    }
+  }
+  return null;
+}
+
+/** 산출 폴더 수집 → artifact {map, routes[], partial, errors[], browser}. */
+export function collectArtifact({ outDir, routesDir, browser, finalText, partial }) {
+  const errors = [];
+  let map = null;
+  const mapPath = join(outDir, 'map.json');
+  if (existsSync(mapPath)) {
+    try {
+      map = readJson(mapPath, ROUTE_FILE_MAX_BYTES);
+    } catch (e) {
+      errors.push(`map.json 파싱 실패: ${e.message}`.slice(0, 300));
+    }
+  } else {
+    errors.push('map.json 없음(요약·커버리지 누락)');
+  }
+
+  const routes = [];
+  let files = [];
+  try {
+    files = readdirSync(routesDir).filter((f) => f.endsWith('.json')).sort();
+  } catch {
+    /* 폴더 없음 */
+  }
+  for (const f of files) {
+    try {
+      const v = readJson(join(routesDir, f), ROUTE_FILE_MAX_BYTES);
+      if (Array.isArray(v)) routes.push(...v); // 한 파일에 여러 라우트를 쓴 경우도 수용
+      else routes.push(v);
+    } catch (e) {
+      errors.push(`${f} 파싱 실패: ${e.message}`.slice(0, 300));
+    }
+  }
+  if (!routes.length) {
+    const fb = fallbackFromText(finalText);
+    if (fb) {
+      routes.push(...fb.routes);
+      if (!map && fb.map) map = fb.map;
+      errors.push('라우트 파일이 없어 최종 보고의 JSON 블록을 사용');
+    }
+  }
+
+  const artifact = { map, routes, partial: Boolean(partial), errors, browser };
+  // 본문 상한 — 초과 시 뒤쪽 라우트부터 제외(Claude 는 핵심 화면부터 기록한다).
+  let size = Buffer.byteLength(JSON.stringify(artifact));
+  while (size > ARTIFACT_MAX_BYTES && artifact.routes.length > 1) {
+    artifact.routes.pop();
+    artifact.partial = true;
+    size = Buffer.byteLength(JSON.stringify(artifact));
+  }
+  if (artifact.routes.length < routes.length) {
+    artifact.errors.push(`산출물 용량 상한으로 라우트 ${routes.length - artifact.routes.length}개 제외`);
+  }
+  return artifact;
+}
+
+/** 저장소 변경 감지(읽기 전용 위반 경고용) — git 저장소가 아니면 null. */
+export async function porcelain(cwd) {
+  try {
+    const { stdout } = await exec('git', ['status', '--porcelain'], { cwd, maxBuffer: 8 * 1024 * 1024 });
+    return stdout.trim();
+  } catch {
+    return null;
+  }
+}

package/git.mjs

@@ -41,13 +41,23 @@ export async function probeFolder(cwd) {
   }
 }
 
-/** 실행 전 검증 — 폴더 존재·git 저장소·클린 워킹트리(사용자 미커밋 변경 보호). */
+/** 실행 전 검증 — 폴더 존재·git 저장소·클린 워킹트리(사용자 미커밋 변경 보호).
+ *  dirty 거부 시 어떤 파일이 걸렸는지 목록을 에러에 포함(porcelain 행, ≤8건 표시+외 N건)
+ *  — 원인 파일을 바로 알게 해 "정리"의 실행 오류를 줄인다. */
 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)한 뒤 다시 시도하세요.');
+  if (dirty) {
+    const files = dirty.split('\n').filter(Boolean).map((l) => l.trim().slice(0, 80));
+    const shown = files.slice(0, 8);
+    const more = files.length - shown.length;
+    const list = shown.join(', ') + (more > 0 ? ` 외 ${more}건` : '');
+    throw new GitError(
+      `커밋되지 않은 변경(${files.length}건)이 있어 작업을 시작할 수 없습니다 — 폴더를 정리(커밋/stash)한 뒤 다시 시도하세요. 대상: ${list}`,
+    );
+  }
 }
 
 export async function currentBranch(cwd) {
@@ -77,6 +87,13 @@ export function taskBranchName(taskId) {
   return `e2e-task/${String(taskId).slice(0, 8)}`;
 }
 
+/** 작업 브랜치가 base 에 쌓은 커밋 수 — 0이면 무변경(질문·조사) 과제.
+ *  서버 상태머신이 테스트/리뷰/배포 생략(short-circuit)을 결정하는 결정론 신호다. */
+export async function commitCount(cwd, base) {
+  const n = await run(cwd, 'rev-list', '--count', `${base}..HEAD`);
+  return Number(n) || 0;
+}
+
 /** 작업 브랜치 생성(있으면 체크아웃) — implement 단계 전 1회. */
 export async function ensureTaskBranch(cwd, taskId) {
   const branch = taskBranchName(taskId);

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "e2e-agent-runner",
-  "version": "1.0.0",
-  "description": "suseona e2e 작업 에이전트 로컬 러너 — 내 컴퓨터의 Claude Code 로 구현→테스트→리뷰→배포를 자동 수행",
+  "version": "1.1.0",
+  "description": "suseona e2e 작업 에이전트 로컬 러너 — 내 컴퓨터의 Claude Code 로 구현→테스트→리뷰→배포와 웹사이트 기능 지도 추출을 자동 수행",
   "type": "module",
   "license": "UNLICENSED",
   "private": false,
@@ -17,6 +17,7 @@
     "api.mjs",
     "claude.mjs",
     "git.mjs",
+    "discover.mjs",
     "README.md"
   ],
   "repository": {

package/runner.mjs

@@ -17,8 +17,9 @@ 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 { collectArtifact, countRouteFiles, porcelain, prepareDiscover } from './discover.mjs';
 import {
-  ensureTaskBranch, escapeTaskBranch, GitError, mergeToBase, preflight, probeFolder, taskBranchName,
+  commitCount, ensureTaskBranch, escapeTaskBranch, GitError, mergeToBase, preflight, probeFolder, taskBranchName,
 } from './git.mjs';
 
 // runner/.env.local 자동 로드 — 이미 설정된 env 는 덮지 않는다(셀 export 우선).
@@ -49,6 +50,9 @@ const STEP_TIMEOUT_S = num(process.env.RUNNER_STEP_TIMEOUT_S, 2700); // 서버 w
 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 MAX_TURNS_DISCOVER = num(process.env.MAX_TURNS_DISCOVER, 500);
+// 기능 지도는 사이트 규모에 비례해 길다 — 서버 와치독은 하트비트(30s)로 갱신되므로 이보다 길어도 안전.
+const DISCOVER_TIMEOUT_S = num(process.env.DISCOVER_TIMEOUT_S, 5400);
 const BUSY_PROBE_POLL_S = 10; // 단계 실행 중 경로 확인(probe) 폴링 주기
 
 function num(v, dflt) {
@@ -162,6 +166,8 @@ async function handleStep({ step, task, project }) {
       result = await runImplement({ step, task, project, buf, cancelled });
     } else if (step.phase === 'deploy') {
       result = await runDeploy({ step, task, project, buf, cancelled });
+    } else if (step.phase === 'discover') {
+      result = await runDiscover({ step, task, project, buf, cancelled });
     } else {
       // test / remediate / review — 서버 프롬프트(prompt_md)·세션(resume) 그대로 실행.
       result = await runPhase({ step, task, project, buf, cancelled });
@@ -176,6 +182,10 @@ async function handleStep({ step, task, project }) {
       session_id: result.sessionId ?? null,
       error: cancelledNow ? 'cancelled' : (result.error ?? null),
       cancelled: Boolean(cancelledNow),
+      // implement 전용 — 작업 브랜치 커밋 수(무변경 단축 신호). 다른 페이즈는 미첨부.
+      commits: result.commits,
+      // discover 전용 — 기능 지도 산출물(서버가 정규화·기록).
+      artifact: result.artifact,
       usage: result.usage ?? undefined,
     });
     log(`단계 종결: ${task.id.slice(0, 8)}/${step.phase} → ${cancelledNow ? 'cancelled' : result.ok ? 'done' : 'fail'}`);
@@ -194,14 +204,80 @@ async function handleStep({ step, task, project }) {
 }
 
 /** implement — git 프리플라이트 → (이전 작업 브랜치 탈출) → 작업 브랜치 → claude(신규 세션).
- *  base_branch 를 서버에 보고(유실 방지: EventBuffer 가 재전송한다). */
+ *  base_branch 를 서버에 보고(유실 방지: EventBuffer 가 재전송한다).
+ *  종결 시 작업 브랜치의 커밋 수(base..HEAD)를 함께 보고 — 0이면 서버가 무변경 단축한다. */
 async function runImplement({ step, task, project, buf, cancelled }) {
   await preflight(project.folder_path);
   const base = await escapeTaskBranch(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 });
+  const result = await runPhase({ step, task, project, buf, cancelled, extraMeta: buf.taskMeta });
+  let commits;
+  try {
+    commits = await commitCount(project.folder_path, base);
+  } catch {
+    /* 커밋 수 계산 실패 — 미보고 시 서버는 기존 전체 파이프라인으로 동작 */
+  }
+  return { ...result, commits };
+}
+
+/** discover — 기능 지도 추출(읽기 전용). 브랜치·프리플라이트 없이 프로젝트 폴더에서 claude 를
+ *  브라우저 MCP 와 함께 실행하고, 임시 산출 폴더의 기록분을 artifact 로 수집해 보고한다.
+ *  시간 초과·실패여도 수집분이 있으면 보고(서버가 partial 로 보존). */
+async function runDiscover({ step, task, project, buf, cancelled }) {
+  if (!state.claudeBin) throw new Error('claude CLI 를 찾을 수 없습니다 — CLAUDE_BIN 확인 후 러너를 재시작하세요.');
+  const prep = prepareDiscover({ siteUrl: project.site_url });
+  log(`기능 지도 탐색 시작: ${project.site_url ?? '(사이트 없음)'} — browser=${prep.browser}, out=${prep.outDir}`);
+  buf.push(step.id, 'status', { event: 'fm_started', browser: prep.browser });
+  const before = await porcelain(project.folder_path);
+  let lastCount = 0;
+  const progress = setInterval(() => {
+    const n = countRouteFiles(prep.routesDir);
+    if (n !== lastCount) {
+      lastCount = n;
+      buf.push(step.id, 'status', { event: 'fm_progress', routes: n });
+    }
+  }, 10_000);
+  try {
+    const result = await runClaude({
+      cwd: project.folder_path,
+      prompt: `${step.prompt_md}\n${prep.promptAddon}\n`,
+      resumeSessionId: null,
+      maxTurns: MAX_TURNS_DISCOVER,
+      timeoutS: DISCOVER_TIMEOUT_S,
+      extraArgs: prep.extraArgs,
+      onEvent: (ev) => buf.push(step.id, ev.kind, ev.data),
+      shouldCancel: cancelled,
+      onSessionId: (sessionId) => {
+        buf.taskMeta = { session_id: sessionId };
+      },
+    });
+    const flag = parsePhaseMarker(result.finalText);
+    const artifact = collectArtifact({
+      outDir: prep.outDir,
+      routesDir: prep.routesDir,
+      browser: prep.browser,
+      finalText: result.finalText,
+      partial: !result.ok || flag !== 'pass',
+    });
+    buf.push(step.id, 'status', {
+      event: 'fm_collected', routes: artifact.routes.length, errors: artifact.errors.slice(0, 5),
+    });
+    const after = await porcelain(project.folder_path);
+    if (before !== null && after !== null && after !== before) {
+      buf.push(step.id, 'status', {
+        event: 'repo_modified',
+        note: '읽기 전용 탐색 중 저장소가 변경되었습니다 — git status 로 확인하세요.',
+        files: after.split('\n').slice(0, 8),
+      });
+    }
+    log(`기능 지도 수집: 라우트 ${artifact.routes.length}개, 오류 ${artifact.errors.length}건`);
+    return { ...result, flag, artifact };
+  } finally {
+    clearInterval(progress);
+    prep.cleanup();
+  }
 }
 
 /** test/remediate/review 공통 — prompt_md + resume 세션. */