elanous 0.2.10 → 0.2.12

package/scripts/ux/demo-rehearsal.ts

@@ -0,0 +1,247 @@
+import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import sharp from 'sharp';
+import { Frames, launch, PUBLIC_LEAK_CHECK, sleep } from './lib/cdp.js';
+import { failedApiResponse, judgeRun, judgeScene, worstSceneState, type SceneObservation, type SceneState } from './lib/rehearsal-verdict.js';
+
+const TITLES = ['문서 아키텍처', '라이브 트레이스', '루프 에이전트', '그래프 편집기', '마법사 → 마켓', 'PTY 인텔리전스'];
+export const EMPTY_STATE_PHRASES = ['지금 도는 런이 없습니다', '마법사가 아직 돌지 않았습니다', '터미널을 기다리는 중', '판단을 기다리는 중', '못 읽음'] as const;
+
+export function sceneSnapshotScript(): string {
+  return `(()=>{const sections=[...document.querySelectorAll('[data-inside-scene]')]; const visible=sections.filter(s=>!s.hidden && s.getClientRects().length>0); const text=visible.length===1?visible[0].innerText:''; return {sectionsInDom:sections.length,visibleScene:visible.length===1?Number(visible[0].getAttribute('data-inside-scene')):null,textLength:text.length,emptyStates:${JSON.stringify(EMPTY_STATE_PHRASES)}.filter(phrase=>text.includes(phrase))}})()`;
+}
+
+type Args = { url: string; out: string; secs: number; width: number; height: number; demo: boolean; tokenStdin: boolean };
+
+export function parseArgs(argv: string[]): Args {
+  const values = new Map<string, string>();
+  let demo = true;
+  let tokenStdin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const key = argv[i];
+    if (key === '--no-demo') { demo = false; continue; }
+    if (key === '--token-stdin') { tokenStdin = true; continue; }
+    if (!['--url', '--out', '--secs', '--size'].includes(key ?? '')) throw new Error(`알 수 없는 인자: ${key}`);
+    const value = argv[++i];
+    if (!value || value.startsWith('--')) throw new Error(`${key} 값이 필요합니다`);
+    values.set(key!, value);
+  }
+  const url = values.get('--url');
+  const out = values.get('--out');
+  if (!url || !out) throw new Error('--url <기반 URL> --out <폴더>가 필요합니다');
+  const base = new URL(url);
+  if (!['http:', 'https:'].includes(base.protocol) || base.username || base.password || base.search || base.hash) throw new Error('--url에는 인증정보·쿼리 없는 HTTP 기반 URL만 허용합니다');
+  const secsText = values.get('--secs') ?? '20';
+  const secs = Number(secsText);
+  if (!/^\d+(?:\.\d+)?$/.test(secsText) || !Number.isFinite(secs) || secs <= 0) throw new Error('--secs는 양의 초여야 합니다');
+  const size = /^(\d+)x(\d+)$/.exec(values.get('--size') ?? '1920x1080');
+  if (!size || +size[1]! < 1 || +size[2]! < 1 || !Number.isSafeInteger(+size[1]!) || !Number.isSafeInteger(+size[2]!)) throw new Error('--size는 양의 WxH여야 합니다');
+  return { url: base.origin, out, secs, width: +size[1]!, height: +size[2]!, demo, tokenStdin };
+}
+
+type FrameRect = { x: number; y: number; width: number; height: number };
+
+// Check the entire *visible scene*, not page chrome or the bottom margin of a valid scene.
+// An evenly blank scene is blank regardless of whether it is white, grey, or black.
+export async function isBlankFrame(jpeg: string, rect: FrameRect | null): Promise<boolean> {
+  if (!rect) return true;
+  const image = sharp(Buffer.from(jpeg, 'base64'));
+  const meta = await image.metadata();
+  const left = Math.max(0, Math.floor(rect.x));
+  const top = Math.max(0, Math.floor(rect.y));
+  const right = Math.min(meta.width, Math.ceil(rect.x + rect.width));
+  const bottom = Math.min(meta.height, Math.ceil(rect.y + rect.height));
+  if (right <= left || bottom <= top) return true;
+  const { data, info } = await image.extract({ left, top, width: right - left, height: bottom - top })
+    .resize({ width: 320, height: 180, fit: 'fill' })
+    .greyscale().raw().toBuffer({ resolveWithObject: true });
+  let edges = 0;
+  for (let y = 1; y < info.height; y++) {
+    for (let x = 1; x < info.width; x++) {
+      const i = y * info.width + x;
+      if (Math.abs(data[i]! - data[i - 1]!) > 20 ||
+          Math.abs(data[i]! - data[i - info.width]!) > 20) {
+        if (++edges >= 12) return false;
+      }
+    }
+  }
+  return true;
+}
+
+// The shared CDP client owns its socket; a second CDP session observes events without changing it.
+export async function observe(port: number) {
+  const pages = await (await fetch(`http://127.0.0.1:${port}/json/list`, { signal: AbortSignal.timeout(5000) })).json() as Array<{ type: string; webSocketDebuggerUrl?: string }>;
+  const endpoint = pages.find((page) => page.type === 'page')?.webSocketDebuggerUrl;
+  if (!endpoint) throw new Error('CDP page missing');
+  const socket = new WebSocket(endpoint);
+  try {
+    await new Promise<void>((resolve, reject) => {
+      const timer = setTimeout(() => reject(new Error('CDP observer connection timed out')), 5000);
+      socket.addEventListener('open', () => { clearTimeout(timer); resolve(); }, { once: true });
+      socket.addEventListener('error', () => { clearTimeout(timer); reject(new Error('CDP observer unavailable')); }, { once: true });
+      socket.addEventListener('close', () => { clearTimeout(timer); reject(new Error('CDP observer closed')); }, { once: true });
+    });
+  } catch (error) { socket.close(); throw error; }
+  let id = 0;
+  const pending = new Map<number, { resolve: (value: { error?: { message: string } }) => void; reject: (error: Error) => void; timer: ReturnType<typeof setTimeout> }>();
+  let closed = false;
+  const failPending = () => {
+    closed = true;
+    for (const [key, request] of pending) {
+      clearTimeout(request.timer);
+      request.reject(new Error('CDP observer disconnected'));
+      pending.delete(key);
+    }
+  };
+  socket.addEventListener('close', failPending);
+  socket.addEventListener('error', failPending);
+  const requests = new Map<string, string>();
+  let exceptions: string[] = [];
+  let failedRequests: string[] = [];
+  socket.addEventListener('message', (event) => {
+    const data = JSON.parse(String(event.data)) as { id?: number; error?: { message: string }; method?: string; params?: { requestId?: string; request?: { url: string }; response?: { url: string; status: number } } };
+    if (data.id !== undefined) {
+      const request = pending.get(data.id);
+      if (request) { clearTimeout(request.timer); pending.delete(data.id); request.resolve(data); }
+    }
+    if (data.method === 'Network.requestWillBeSent' && data.params?.requestId && data.params.request) {
+      // Preserve only the API classification; never persist a URL or a query containing a credential.
+      const path = new URL(data.params.request.url).pathname;
+      requests.set(data.params.requestId, /(?:^|\/)v1\//.test(path) ? '/v1/' : 'non-api request');
+    }
+    if (data.method === 'Network.responseReceived' && data.params?.response) {
+      const failed = failedApiResponse(data.params.response.url, data.params.response.status);
+      if (failed) failedRequests.push(failed);
+    }
+    if (data.method === 'Network.loadingFinished') requests.delete(data.params?.requestId ?? '');
+    if (data.method === 'Runtime.exceptionThrown') exceptions.push('Runtime.exceptionThrown');
+    if (data.method === 'Network.loadingFailed') {
+      const requestId = data.params?.requestId ?? '';
+      failedRequests.push(requests.get(requestId) ?? 'non-api request');
+      requests.delete(requestId);
+    }
+  });
+  const send = async (method: string) => {
+    if (closed || socket.readyState !== WebSocket.OPEN) throw new Error('CDP observer disconnected');
+    const response = await new Promise<{ error?: { message: string } }>((resolve, reject) => {
+      const next = ++id;
+      const timer = setTimeout(() => {
+        pending.delete(next);
+        reject(new Error(`CDP ${method} timed out`));
+      }, 5000);
+      pending.set(next, { resolve, reject, timer });
+      try { socket.send(JSON.stringify({ id: next, method })); }
+      catch { clearTimeout(timer); pending.delete(next); reject(new Error('CDP observer send failed')); }
+    });
+    if (response.error) throw new Error(`CDP ${method} failed`);
+  };
+  try { await send('Runtime.enable'); await send('Network.enable'); }
+  catch (error) { failPending(); socket.close(); throw error; }
+  return {
+    take: () => {
+      const result = { exceptions, failedRequests };
+      exceptions = []; failedRequests = [];
+      return result;
+    },
+    close: () => { failPending(); socket.close(); },
+  };
+}
+
+export async function run(args: Args): Promise<number> {
+  mkdirSync(args.out, { recursive: true });
+  const startedAt = new Date().toISOString();
+  const port = 9480 + Math.floor(Math.random() * 15);
+  const cdp = await launch({ port, timeoutMs: (args.secs * 6 + 180) * 1000, width: args.width, height: args.height });
+  let observer: Awaited<ReturnType<typeof observe>> | undefined;
+  try {
+    observer = await observe(port);
+    const target = new URL('/app/inside/', args.url);
+    target.searchParams.set('demo', args.demo ? '1' : '0');
+    target.searchParams.set('capture', 'public');
+    target.searchParams.set('scene', '1');
+    if (args.tokenStdin) {
+      const token = /elt_[A-Za-z0-9_-]{16,}/.exec(await Bun.stdin.text())?.[0];
+      if (token) {
+        await cdp.send('Page.navigate', { url: `${target.origin}/app/` });
+        await sleep(3000);
+        await cdp.ev(`localStorage.setItem('elanous.daemon.token', ${JSON.stringify(token)})`);
+      }
+    }
+    observer.take();
+    await cdp.send('Page.navigate', { url: target.toString() });
+    await sleep(8000);
+    const initialEvents = observer.take();
+    const scenes = [];
+    for (let scene = 1; scene <= 6; scene++) {
+      const hiddenByDemo = false;
+      if (scene !== 1) {
+        await cdp.ev<boolean>(`(()=>{const n=${scene}; const nav=document.querySelector('nav[aria-label="장면 선택"]'); const button=[...(nav?.querySelectorAll('button')??[])].find(b=>b.textContent?.trim().startsWith(n+' ')); button?.click(); return !!button})()`);
+        await sleep(300);
+      }
+      const frames = new Frames(join(args.out, `scene-${scene}`));
+      const states: SceneState[] = [];
+      const emptyStates = new Set<string>();
+      const sceneRect = await cdp.ev<FrameRect | null>(`(()=>{const s=document.querySelector('[data-inside-scene="${scene}"]'); if (!s || s.hidden) return null; const r=s.getBoundingClientRect(); return {x:r.x,y:r.y,width:r.width,height:r.height}})()`);
+      let blankFrames = 0;
+      const inspect = async () => {
+        const { emptyStates: observedEmpty, ...state } = await cdp.ev<SceneState & { emptyStates: string[] }>(sceneSnapshotScript());
+        states.push(state);
+        for (const phrase of observedEmpty) emptyStates.add(phrase);
+      };
+      const until = Date.now() + args.secs * 1000;
+      await inspect();
+      do {
+        const screenshot = await cdp.send('Page.captureScreenshot', { format: 'jpeg', quality: 92 });
+        frames.add(screenshot.data);
+        if (await isBlankFrame(screenshot.data, sceneRect)) blankFrames++;
+        await inspect();
+      } while (Date.now() < until);
+      await cdp.png(join(args.out, `scene-${scene}.png`));
+      const { bad } = JSON.parse(await cdp.ev<string>(PUBLIC_LEAK_CHECK)) as { bad: string[] };
+      const dom = worstSceneState(scene, states);
+      const observed = observer.take();
+      const events = scene === 1 ? {
+        exceptions: [...initialEvents.exceptions, ...observed.exceptions],
+        failedRequests: [...initialEvents.failedRequests, ...observed.failedRequests],
+      } : observed;
+      frames.toMp4(join(args.out, `scene-${scene}.mp4`), args.width, args.height);
+      const obs: SceneObservation = { scene, title: TITLES[scene - 1]!, hiddenByDemo, secs: args.secs, frames: frames.list.length, ...events, ...dom, leaks: bad, blankFrames, emptyStates: [...emptyStates] };
+      const result = judgeScene(obs);
+      scenes.push(result);
+      console.log(`scene ${scene} ${result.verdict} ${args.secs}s frames=${result.frames}`);
+    }
+    const result = judgeRun(scenes);
+    const report = { version: repoVersion(), startedAt, endedAt: new Date().toISOString(), ...result };
+    writeFileSync(join(args.out, 'rehearsal.json'), JSON.stringify(report, null, 2) + '\n');
+    writeFileSync(join(args.out, 'rehearsal.md'), [
+      '# DEMO-RUN 리허설',
+      '',
+      ...result.banner.map((line) => `> ⚠️ ${line}`),
+      ...(result.banner.length ? [''] : []),
+      `판: ${report.version} · 시작: ${startedAt} · 종료: ${report.endedAt} · 판정: ${report.verdict}`,
+      '',
+      '| 장면 | 판정 | 초 | 프레임 | 이유 |',
+      '|---|---|---:|---:|---|',
+      ...scenes.map((s) => `| ${s.scene} ${s.title} | ${s.verdict} | ${s.secs} | ${s.frames} | ${s.reasons.join('; ') || '없음'} |`),
+      '',
+      `ok ${result.ok} · broken ${result.broken} · 미검증 ${result.unverified} · 실데이터 없음 ${result.noData}`,
+      '',
+      '종료 코드: ok=0 · broken=1 · unverified=2 · no-data=3',
+      '',
+    ].join('\n'));
+    for (const line of result.banner) console.log(`⚠️ ${line}`);
+    console.log(`rehearsal ${result.verdict} ok=${result.ok} broken=${result.broken} unverified=${result.unverified} no-data=${result.noData}`);
+    // 0 = ok · 1 = broken · 2 = unverified · 3 = no-data.
+    return result.verdict === 'broken' ? 1 : result.verdict === 'unverified' ? 2 : result.verdict === 'no-data' ? 3 : 0;
+  } finally { observer?.close(); cdp.close(); }
+}
+
+function repoVersion(): string {
+  try { return String((JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')) as { version?: unknown }).version ?? 'unknown'); }
+  catch { return 'unknown'; }
+}
+
+if (import.meta.main) {
+  try { process.exitCode = await run(parseArgs(process.argv.slice(2))); }
+  catch { console.error('리허설 실행 실패'); process.exitCode = 1; }
+}

package/scripts/ux/demo-seed.ts

@@ -0,0 +1,108 @@
+import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+
+export type SeedArgs = { only: 'graph' | 'wizard' | 'all'; dryRun: boolean; json: boolean };
+export type SeedEvent = { target: 'graph' | 'wizard'; phase: 'start' | 'finish' | 'failure'; command: string[]; exitCode?: number; output?: string };
+
+export const SCENE_SIX_GUIDANCE = '⑥ PTY 인텔리전스는 이 시드로 생성하지 않습니다. 실제 격리 미션을 실행하고 read → judge → answer 이벤트를 관측하세요.';
+const GRAPH = 'graphs/demo/inside-seed.yaml';
+const WIZARD_REQUEST = '데모용 자료 조사 커넥터와 스킬·그래프 초안을 만들어 주세요. 설치하거나 실행하지 마세요.';
+const DRAFT = { description: 'Demo research draft only; no connector credentials or outbound messages.', connectors: [],
+  skill: { description: 'Demo research draft', instructions: 'Research draft only. Implement and validate processing before installing or running.', requires: [] } };
+
+export function parseArgs(argv: string[]): SeedArgs {
+  const result: SeedArgs = { only: 'all', dryRun: false, json: false };
+  const seen = new Set<string>();
+  for (let i = 0; i < argv.length; i++) {
+    const flag = argv[i]!;
+    if (!['--only', '--dry-run', '--json'].includes(flag)) throw new Error(`알 수 없는 인자: ${flag}`);
+    if (seen.has(flag)) throw new Error(`중복 인자: ${flag}`);
+    seen.add(flag);
+    if (flag === '--only') {
+      const value = argv[++i];
+      if (value !== 'all' && value !== 'graph' && value !== 'wizard') throw new Error('--only 값은 graph|wizard|all 이어야 합니다');
+      result.only = value;
+    } else if (flag === '--dry-run') result.dryRun = true;
+    else result.json = true;
+  }
+  return result;
+}
+
+export type SeedDeps = {
+  repo: string;
+  run: (command: string[], cwd: string) => Promise<{ exitCode: number; output: string; stdout?: string }>;
+  prepareDraft: (repo: string) => { file: string; parent: string };
+};
+
+function prepareDraft(repo: string): { file: string; parent: string } {
+  const root = resolve(repo, '.elanous-test', 'demo-seed');
+  mkdirSync(root, { recursive: true });
+  const parent = mkdtempSync(join(root, 'wizard-'));
+  const file = join(parent, 'research-draft.json');
+  writeFileSync(file, JSON.stringify(DRAFT) + '\n');
+  return { file, parent };
+}
+
+const defaultDeps: SeedDeps = {
+  repo: resolve(import.meta.dir, '../..'),
+  prepareDraft,
+  run: async (command, cwd) => {
+    const child = Bun.spawn(command, { cwd, env: { ...process.env, NODE_ENV: 'test' }, stdout: 'pipe', stderr: 'pipe' });
+    const [output, errors, exitCode] = await Promise.all([new Response(child.stdout).text(), new Response(child.stderr).text(), child.exited]);
+    return { exitCode, stdout: output, output: [output, errors].filter(Boolean).join('\n').trim() };
+  },
+};
+
+export async function seed(args: SeedArgs, deps: SeedDeps = defaultDeps, onEvent?: (event: SeedEvent) => void): Promise<{ events: SeedEvent[]; guidance: string; ok: boolean }> {
+  const events: SeedEvent[] = [];
+  const emit = (event: SeedEvent): void => { events.push(event); onEvent?.(event); };
+  let ok = true;
+  for (const target of (args.only === 'all' ? ['graph', 'wizard'] : [args.only]) as Array<'graph' | 'wizard'>) {
+    const base = ['bun', 'bin/elanous.mjs', '--test'];
+    const graphCommand = [...base, 'graph', 'run', GRAPH, '--json'];
+    const wizardCommand = [...base, 'plugin', 'make', WIZARD_REQUEST, '--name', 'inside-demo-draft', '--draft-file', '<isolated-draft-file>', '--dir', '<isolated-parent>', '--json'];
+    const command = target === 'graph' ? graphCommand : wizardCommand;
+    if (args.dryRun) {
+      emit({ target, phase: 'start', command });
+      emit({ target, phase: 'finish', command, exitCode: 0, output: 'dry-run: no process started' });
+      continue;
+    }
+    try {
+      if (target === 'wizard') {
+        const { file, parent } = deps.prepareDraft(deps.repo);
+        command.splice(command.indexOf('<isolated-draft-file>'), 1, file);
+        command.splice(command.indexOf('<isolated-parent>'), 1, parent);
+      }
+      emit({ target, phase: 'start', command });
+      const result = await deps.run(command, deps.repo);
+      const parsed = (() => {
+        try { return JSON.parse(result.stdout ?? result.output) as { status?: string; dryRun?: boolean; errors?: string[]; timings?: { install?: number } }; } catch { return null; }
+      })();
+      const complete = target === 'wizard'
+        ? parsed?.status === 'draft' && parsed.timings?.install === 0 && parsed.errors?.length === 0
+        : parsed?.status === 'done' && parsed.dryRun === false;
+      const phase = result.exitCode === 0 && complete ? 'finish' : 'failure';
+      emit({ target, phase, command, exitCode: result.exitCode, output: result.output });
+      if (phase === 'failure') ok = false;
+    } catch (error) {
+      ok = false;
+      emit({ target, phase: 'failure', command, output: error instanceof Error ? error.message : String(error) });
+    }
+  }
+  return { events, guidance: SCENE_SIX_GUIDANCE, ok };
+}
+
+if (import.meta.main) {
+  try {
+    const args = parseArgs(process.argv.slice(2));
+    const report = await seed(args, defaultDeps, args.json ? undefined : (event) => {
+      console.log(`${event.target} ${event.phase}${event.exitCode === undefined ? '' : ` (exit ${event.exitCode})`}: ${event.command.join(' ')}${event.output ? `\n${event.output}` : ''}`);
+    });
+    if (args.json) console.log(JSON.stringify(report));
+    else console.log(report.guidance);
+    if (!report.ok) process.exitCode = 1;
+  } catch (error) {
+    console.error(error instanceof Error ? error.message : String(error));
+    process.exitCode = 1;
+  }
+}

package/scripts/ux/lib/rehearsal-verdict.ts

@@ -0,0 +1,80 @@
+export type SceneObservation = {
+  scene: number;
+  title: string;
+  hiddenByDemo: boolean;
+  secs: number;
+  frames: number;
+  exceptions: string[];
+  failedRequests: string[];
+  textLength: number;
+  leaks: string[];
+  sectionsInDom: number;
+  visibleScene: number | null;
+  /** Empty-state phrases observed in the visible scene. */
+  emptyStates?: string[];
+  /** Number of captured JPEG frames with no discernible scene content. */
+  blankFrames?: number;
+};
+
+export type SceneState = Pick<SceneObservation, 'textLength' | 'sectionsInDom' | 'visibleScene'>;
+
+/** A recovered frame must not erase a blank or mismatched frame from the recording. */
+export function worstSceneState(scene: number, states: SceneState[]): SceneState {
+  return {
+    textLength: states.length ? Math.min(...states.map((state) => state.textLength)) : 0,
+    sectionsInDom: states.length ? Math.min(...states.map((state) => state.sectionsInDom)) : 0,
+    visibleScene: states.length && states.every((state) => state.visibleScene === scene) ? scene : null,
+  };
+}
+
+/** Keep the API path (so a broken scene says *which* call failed) and status, never the query string;
+ *  id-like segments (uuid · long hex · digits · run-…) collapse to `:id`. */
+export function failedApiResponse(url: string, status: number): string | null {
+  try {
+    const path = new URL(url).pathname;
+    if (!(status >= 400 && status <= 599 && /(?:^|\/)v1\//.test(path))) return null;
+    const shape = path.split('/').map((part) => (/^(?:run-)?[0-9a-f]{8,}(?:-[0-9a-f]{4,})*$/i.test(part) || /^\d+$/.test(part) ? ':id' : part)).join('/');
+    return `${shape} ${status}`;
+  } catch { return null; }
+}
+
+export type SceneResult = SceneObservation & { verdict: 'ok' | 'broken' | 'unverified' | 'no-data'; reasons: string[] };
+
+/** A scene the demo hides is not a pass — it was not seen. OP 10-03: ⑤ (wizard → market) is the 10-08 highlight. */
+export const UNVERIFIED_REASON = '시연 모드에서 숨긴 장면 — WIZ1 착지 뒤 실물 필요';
+const CIRCLED = ['①', '②', '③', '④', '⑤', '⑥', '⑦', '⑧', '⑨'];
+
+export function judgeScene(obs: SceneObservation): SceneResult {
+  if (obs.hiddenByDemo) return { ...obs, verdict: 'unverified', reasons: [UNVERIFIED_REASON] };
+  const reasons: string[] = [];
+  if (obs.exceptions.length) reasons.push(`실행 예외 ${obs.exceptions.length}건`);
+  const failed = obs.failedRequests.filter((request) => {
+    try {
+      const path = new URL(request, 'http://localhost').pathname;
+      return /(?:^|\/)v1\//.test(path) && !path.includes('/_next/static/') && !path.includes('favicon');
+    } catch { return false; }
+  });
+  if (failed.length) reasons.push(`API 요청 실패 ${failed.length}건`);
+  if (obs.textLength < 40) reasons.push(`빈 화면 (글자 ${obs.textLength}자)`);
+  if (obs.blankFrames) reasons.push(`녹화 프레임 빈 화면 ${obs.blankFrames}장`);
+  if (obs.sectionsInDom < 6) reasons.push(`장면 언마운트 (${obs.sectionsInDom}/6)`);
+  if (obs.visibleScene !== obs.scene) reasons.push(`보이는 장면 불일치 (기대 ${obs.scene}, 실제 ${obs.visibleScene ?? '없음'})`);
+  if (obs.leaks.length) reasons.push(`공개 화면 누설 ${obs.leaks.length}건`);
+  if (reasons.length) return { ...obs, verdict: 'broken', reasons };
+  if (obs.emptyStates?.length) return { ...obs, verdict: 'no-data', reasons: obs.emptyStates.map((phrase) => `실데이터 없음 — ${phrase}`) };
+  return { ...obs, verdict: 'ok', reasons };
+}
+
+export function judgeRun(scenes: SceneResult[]) {
+  const ok = scenes.filter((scene) => scene.verdict === 'ok').length;
+  const broken = scenes.filter((scene) => scene.verdict === 'broken').length;
+  const unverified = scenes.filter((scene) => scene.verdict === 'unverified').length;
+  const noData = scenes.filter((scene) => scene.verdict === 'no-data').length;
+  // Broken wins, then unseen scenes, then scenes without real data; none is a pass.
+  const verdict = broken ? 'broken' as const : unverified ? 'unverified' as const : noData ? 'no-data' as const : 'ok' as const;
+  const banner = scenes.filter((scene) => scene.verdict === 'unverified')
+    .map((scene) => `${CIRCLED[scene.scene - 1] ?? scene.scene} 미검증 — WIZ1 착지 뒤 실물 필요`);
+  const noDataScenes = scenes.filter((scene) => scene.verdict === 'no-data').map((scene) => CIRCLED[scene.scene - 1] ?? String(scene.scene));
+  if (noDataScenes.length) banner.push(`${noDataScenes.join('')} 실데이터 없음 — 런·PTY·마법사가 도는 판에서 다시`);
+  return { verdict, ok, broken, unverified, noData, banner, scenes };
+}