elanous 0.2.10 → 0.2.11

package/scripts/tech1-public-measure.ts

@@ -0,0 +1,94 @@
+import { readFileSync } from 'node:fs';
+import { loadGraphTemplatesFrom, defaultGraphsDir } from '../src/self-implement/graph-templates.js';
+
+// Public metrics for release/public/tech/tech1.json. Log metrics read the installed `elanous`
+// (operational universe) over --since/--until; `--all` adds every registered instance incl. test.
+const key = process.argv[2];
+const flag = (name: string): string | undefined => {
+  const at = process.argv.indexOf(name);
+  return at < 0 ? undefined : process.argv[at + 1];
+};
+const PAGE = 100000;
+
+type Row = { id?: number; category: string; event: string; data?: unknown };
+
+function logRows(args: string[]): { rows: Row[]; limitReached: boolean } {
+  const proc = Bun.spawnSync(['elanous', 'logs', ...args, '--json', '--json-data'], { stdout: 'pipe', stderr: 'pipe', maxBuffer: 2 ** 31 } as Parameters<typeof Bun.spawnSync>[1]);
+  if (proc.exitCode !== 0) throw new Error(`elanous logs failed: ${new TextDecoder().decode(proc.stderr).slice(0, 300)}`);
+  const rows: Row[] = [];
+  let limitReached = false;
+  for (const line of new TextDecoder().decode(proc.stdout).split('\n')) {
+    if (!line) continue;
+    const row = JSON.parse(line) as Row & { _meta?: { type?: string; limitReached?: boolean } };
+    if (row._meta) { if (row._meta.type === 'log-query-limit' && row._meta.limitReached) limitReached = true; continue; }
+    rows.push(row);
+  }
+  return { rows, limitReached };
+}
+
+function window(): string[] {
+  const since = flag('--since');
+  const until = flag('--until');
+  if (!since || !until) throw new Error('--since <ISO> --until <ISO> required');
+  return ['--since', since, '--until', until];
+}
+
+/** One page across all instances; refuses a truncated page instead of reporting a short count. */
+function unionCount(categories: string, events?: string): Map<string, number> {
+  const args = [...window(), '--all', '--include-test', '--limit', String(PAGE), '--category', categories, ...(events ? ['--event', events] : [])];
+  const { rows, limitReached } = logRows(args);
+  if (limitReached) throw new Error(`truncated at ${PAGE} rows — narrow --event`);
+  const counts = new Map<string, number>();
+  for (const row of rows) counts.set(`${row.category} ${row.event}`, (counts.get(`${row.category} ${row.event}`) ?? 0) + 1);
+  return counts;
+}
+
+const at = (counts: Map<string, number>, k: string): number => counts.get(k) ?? 0;
+
+if (key === 'graph.templates') {
+  const result = loadGraphTemplatesFrom(defaultGraphsDir());
+  console.log(Object.keys(result.templates).length);
+} else if (key === 'loop-agents.loops') {
+  const proc = Bun.spawnSync(['bun', 'bin/elanous.mjs', '--test', 'loop', 'list', '--json'], { stdout: 'pipe', stderr: 'pipe' });
+  if (proc.exitCode !== 0) throw new Error('loop catalog unavailable');
+  console.log(JSON.parse(new TextDecoder().decode(proc.stdout)).length);
+} else if (key === 'harness.author-tags') {
+  const tags = [...readFileSync('src/self-implement/goal-author.ts', 'utf8').matchAll(/tag: '([a-z-]+)'/g)].map(match => match[1]);
+  console.log(new Set(tags).size);
+} else if (key === 'observability.events') {
+  // Operational instance only; pages with --before so the 100k page cap does not cut the count.
+  let before: number | undefined;
+  let total = 0;
+  for (;;) {
+    const { rows } = logRows([...window(), '--limit', String(PAGE), ...(before === undefined ? [] : ['--before', String(before)])]);
+    total += rows.length;
+    if (rows.length < PAGE) break;
+    before = Math.min(...rows.map((row) => row.id ?? Number.POSITIVE_INFINITY));
+  }
+  console.log(total);
+} else if (key === 'stages.author') {
+  const c = unionCount('harness.author', 'goal-id-assigned');
+  console.log(JSON.stringify({ auto: at(c, 'harness.author goal-id-assigned') }));
+} else if (key === 'stages.clarify') {
+  const c = unionCount('hitl.execution,harness.author.clarify', 'auto-recommended,assumed,asked,self-answered,unresolved');
+  console.log(JSON.stringify({
+    auto: at(c, 'hitl.execution auto-recommended') + at(c, 'hitl.execution assumed') + at(c, 'harness.author.clarify self-answered'),
+    human: at(c, 'hitl.execution asked'),
+    unknown: at(c, 'harness.author.clarify unresolved'),
+  }));
+} else if (key === 'stages.ledger') {
+  const { rows, limitReached } = logRows([...window(), '--all', '--include-test', '--limit', String(PAGE), '--category', 'self-implement.pod', '--event', 'ledger-live-appended']);
+  if (limitReached) throw new Error(`truncated at ${PAGE} rows`);
+  const runs = new Set(rows.map((row) => (row.data as { runId?: string } | undefined)?.runId).filter(Boolean));
+  console.log(JSON.stringify({ auto: runs.size, appends: rows.length }));
+} else if (key === 'stages.heal') {
+  const c = unionCount('self-dev.rework,self-dev.hitl', 'repeat-count,escalation');
+  console.log(JSON.stringify({ auto: at(c, 'self-dev.rework repeat-count'), human: at(c, 'self-dev.hitl escalation') }));
+} else if (key === 'pty.missions') {
+  // External coding agents driven through an inner PTY (agent-mission) — distinct missions with any row in the window.
+  const { rows, limitReached } = logRows([...window(), '--all', '--include-test', '--limit', String(PAGE), '--category', 'agent-mission']);
+  if (limitReached) throw new Error(`truncated at ${PAGE} rows`);
+  console.log(new Set(rows.map((row) => (row.data as { missionId?: string } | undefined)?.missionId).filter(Boolean)).size);
+} else {
+  throw new Error(`Unknown public metric: ${key ?? '(missing)'}`);
+}

package/scripts/test-diet/node.ts

@@ -54,7 +54,7 @@ function measure(ctx: Context, audit = false): number {
     'while IFS= read -r f; do',
     '  [ -n "$f" ] || continue',
     '  s=$(date +%s)',
-    '  if [ -n "$TO" ]; then /usr/bin/time -l "$TO" -k 10 300 bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; else /usr/bin/time -l bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; fi',
+    `  if [ -n "$TO" ]; then /usr/bin/time -l "$TO" -k 10 300 ${audit ? 'env ELANOUS_NIGHTLY_AUDIT=1 ' : ''}bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; else /usr/bin/time -l ${audit ? 'env ELANOUS_NIGHTLY_AUDIT=1 ' : ''}bun run scripts/test-deterministic.ts "./$f" > "$T/out" 2> "$T/err"; fi`,
     '  rc=$?; e=$(( $(date +%s) - s ))',
     '  rss=$(awk \'/maximum resident set size/ {printf "%d", $1/1048576}\' "$T/err")',
     // bun test prints its summary on stderr — read both streams.

package/scripts/tui-regress.ts

@@ -42,7 +42,7 @@ async function runCheck(check: TuiCheck): Promise<Verdict> {
       else snaps[step.as] = await handle.renderScreen();
     }
     // TUI_REGRESS_DUMP=<id> prints that check's screens (to see why a verdict failed).
-    if (process.env.TUI_REGRESS_DUMP === check.id) for (const [k, v] of Object.entries(snaps)) console.log(`--- ${check.id}:${k}\n${v.split('\n').filter((l) => l.trim()).join('\n')}`);
+    if (!json && process.env.TUI_REGRESS_DUMP === check.id) for (const [k, v] of Object.entries(snaps)) console.log(`--- ${check.id}:${k}\n${v.split('\n').filter((l) => l.trim()).join('\n')}`);
     return check.judge(snaps);
   } catch (error) {
     return { ok: false, reason: `실행 오류: ${String(error).slice(0, 120)}` };
@@ -67,5 +67,5 @@ for (const check of checks) {
 }
 const fail = results.filter((r) => !r.ok).length;
 if (json) console.log(JSON.stringify({ results, pass: results.length - fail, fail }));
-console.log(`tui-regress: pass ${results.length - fail} · fail ${fail}`);
+else console.log(`tui-regress: pass ${results.length - fail} · fail ${fail}`);
 process.exit(fail ? 1 : 0);

package/scripts/ux/demo-rehearsal.ts

@@ -0,0 +1,243 @@
+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 인텔리전스'];
+
+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 = args.demo && scene === 5;
+      if (hiddenByDemo) {
+        const result = judgeScene({ scene, title: TITLES[scene - 1]!, hiddenByDemo, secs: 0, frames: 0, exceptions: [], failedRequests: [], textLength: 0, leaks: [], sectionsInDom: 0, visibleScene: null });
+        scenes.push(result);
+        console.log(`scene ${scene} ${result.verdict} 0s frames=0`);
+        continue;
+      }
+      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 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 () => {
+        states.push(await cdp.ev<SceneState>(`(()=>{const sections=[...document.querySelectorAll('[data-inside-scene]')]; const visible=sections.filter(s=>!s.hidden && s.getClientRects().length>0); return {sectionsInDom:sections.length,visibleScene:visible.length===1?Number(visible[0].getAttribute('data-inside-scene')):null,textLength:visible.length===1?visible[0].innerText.length:0}})()`));
+      };
+      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 };
+      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}`,
+      '',
+    ].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}`);
+    // 0 = all seen and ok · 1 = broken · 2 = nothing broken but a scene was not seen (not a pass).
+    return result.verdict === 'broken' ? 1 : result.verdict === 'unverified' ? 2 : 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/lib/rehearsal-verdict.ts

@@ -0,0 +1,73 @@
+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;
+  /** 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'; 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}건`);
+  return { ...obs, verdict: reasons.length ? 'broken' : '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;
+  // broken wins; otherwise any unseen scene keeps the whole run from reading as a pass.
+  const verdict = broken ? 'broken' as const : unverified ? 'unverified' as const : 'ok' as const;
+  const banner = scenes.filter((scene) => scene.verdict === 'unverified')
+    .map((scene) => `${CIRCLED[scene.scene - 1] ?? scene.scene} 미검증 — WIZ1 착지 뒤 실물 필요`);
+  return { verdict, ok, broken, unverified, banner, scenes };
+}