elanous 0.2.5 → 0.2.7

package/scripts/release-loop/ops-upgrade-node.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+import { homedir } from 'node:os';
+import { errorResult, finishNode, lastResult, nodeOutput, readGraphContext, runCommand, type CommandResult, type CommandRunner } from './node-verdict.js';
+
+interface HostResult { host: string; ok: boolean; before: string; after: string; error?: string; skipped?: string }
+
+function firstLine(text: string): string { return text.trim().split(/\r?\n/)[0]?.trim() ?? ''; }
+
+function reason(result: CommandResult): string {
+  const data = lastResult(result);
+  const message = [data?.error, data?.reason, data?.message, result.stderr, result.stdout].find((part) => typeof part === 'string' && part.trim());
+  const line = firstLine(String(message ?? `명령 실패 (rc=${result.status})`));
+  return /\b404\b/.test(line) ? `공급원에 판 없음 (404): ${line}` : line;
+}
+
+function quote(value: string): string { return `'${value.replaceAll("'", "'\\''")}'`; }
+
+export function runOpsUpgrade(run: CommandRunner = runCommand) {
+  const context = readGraphContext();
+  const hosts = context.input.opsHosts;
+  if (hosts === undefined || (Array.isArray(hosts) && hosts.length === 0)) {
+    return { outcome: 'ok' as const, verdict: 'pass' as const, summary: '운영 대상 없음 — 건너뜀', hosts: [] as HostResult[] };
+  }
+  if (!Array.isArray(hosts) || !hosts.every((host) => typeof host === 'string' && /^[A-Za-z0-9][A-Za-z0-9._-]*$/.test(host))) throw new Error('input.opsHosts must be an array of host names');
+  if (context.outputs.verify?.outcome !== 'ok') throw new Error('verify must pass before ops upgrade');
+  const version = context.input.version;
+  if (nodeOutput(context, 'publish', 'tag') !== `v${version}`) throw new Error('published tag/version mismatch');
+  const internalDist = context.input.internalDist;
+  if (internalDist !== undefined && (typeof internalDist !== 'string' || !internalDist.trim())) throw new Error('input.internalDist must be a path string');
+  const feedPath = typeof internalDist === 'string' && internalDist.startsWith('~/') ? `${homedir()}/${internalDist.slice(2)}` : internalDist;
+  let feedError = '';
+  if (typeof feedPath === 'string') {
+    try {
+      const feed = run('bun', ['scripts/publish-internal-dist.ts', '--checkout', process.cwd(), '--out', feedPath]);
+      const data = lastResult(feed);
+      if (feed.status !== 0 || data?.ok !== true || data.version !== version) feedError = `내부 피드 발행 실패: ${feed.status === 0 && data?.ok === true ? `판 불일치 (${String(data.version)})` : reason(feed)}`;
+    } catch (error) { feedError = `내부 피드 발행 실패: ${firstLine(String(error))}`; }
+  }
+  const results: HostResult[] = [];
+  for (const host of hosts as string[]) {
+    if (host !== 'local' && feedError) {
+      results.push({ host, ok: false, before: '', after: '', skipped: '내부 피드 발행 실패', error: feedError });
+      continue;
+    }
+    const command = (args: string[]): CommandResult => host === 'local'
+      ? run('elanous', args)
+      : run('ssh', [host, `PATH="$HOME/.local/bin:$HOME/.bun/bin:$PATH"; export PATH; elanous ${args.map(quote).join(' ')}`]);
+    let before = '';
+    let after = '';
+    try {
+      const previous = command(['--version']);
+      if (previous.status === 0) before = firstLine(previous.stdout);
+      const updated = command(['update', '--version', version, '--json', ...(context.input.opsRestart === true ? ['--restart'] : [])]);
+      const updateResult = lastResult(updated);
+      if (updated.status !== 0 || updateResult?.exitCode !== 0 || updateResult.installedVersion !== version) {
+        const error = updated.status === 0 && updateResult?.exitCode === 0
+          ? `설치판 불일치 (기대 ${version}, 실제 ${String(updateResult.installedVersion)})` : reason(updated);
+        results.push({ host, ok: false, before, after, error });
+        continue;
+      }
+      const current = command(['--version']);
+      if (current.status !== 0) {
+        results.push({ host, ok: false, before, after, error: reason(current) });
+        continue;
+      }
+      after = firstLine(current.stdout);
+      if (after.split(/\s+/)[0] !== version) {
+        results.push({ host, ok: false, before, after, error: `올렸는데 판이 그대로 (기대 ${version}, 실제 ${after || '없음'})` });
+        continue;
+      }
+      results.push({ host, ok: true, before, after });
+    } catch (error) {
+      results.push({ host, ok: false, before, after, error: firstLine(String(error)) });
+    }
+  }
+  const failures = results.filter((result) => !result.ok);
+  return { outcome: failures.length || feedError ? 'fail' as const : 'ok' as const,
+    verdict: failures.length || feedError ? 'fail' as const : 'pass' as const,
+    summary: failures.length ? `운영 판올림 실패: ${failures.map(({ host, error }) => `${host}: ${error}`).join('; ')}${feedError && !failures.some((item) => item.skipped) ? `; ${feedError}` : ''}`
+      : feedError || `운영 판올림 ${version} · ${results.length}대 확인`, hosts: results };
+}
+
+if (import.meta.main) {
+  let version = '';
+  try { version = readGraphContext().input.version; process.exitCode = finishNode('ops-upgrade', version, runOpsUpgrade()); }
+  catch (error) { process.exitCode = finishNode('ops-upgrade', version, errorResult(error)); }
+}

package/scripts/release-loop/release-readiness.ts

@@ -0,0 +1,58 @@
+import { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { checklistGate, type ChecklistGate } from '../../src/release-loop/checklist.js';
+
+export type ReleaseReadiness =
+  | { ready: false; reason: 'already-published'; details: string }
+  | { ready: false; reason: 'already-running'; details: string }
+  | { ready: false; reason: 'checklist-blocked'; details: ChecklistGate }
+  | { ready: true; reason: 'ready'; details: ChecklistGate };
+
+export interface ReleaseReadinessDeps {
+  ledgerRoot?: string;
+  checklist?: typeof checklistGate;
+  isPidAlive?: (pid: number) => boolean;
+}
+
+function readIfPresent(path: string): string | undefined {
+  try { return readFileSync(path, 'utf8'); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return undefined;
+    throw error;
+  }
+}
+
+function isPidAlive(pid: number): boolean {
+  try { process.kill(pid, 0); return true; }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ESRCH') return false;
+    if ((error as NodeJS.ErrnoException).code === 'EPERM') return true;
+    throw error;
+  }
+}
+
+/** Read-only preflight; callers own acquiring and releasing run.lock around the graph. */
+export function releaseReadiness(version: string, deps: ReleaseReadinessDeps = {}): ReleaseReadiness {
+  if (!/^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(deps.ledgerRoot ?? releaseLedgerRoot(), 'release', version);
+  const record = readIfPresent(join(dir, 'release.json'));
+  if (record) {
+    const data = JSON.parse(record) as { publishedAt?: unknown };
+    if (typeof data.publishedAt === 'string' && data.publishedAt.trim()) {
+      return { ready: false, reason: 'already-published', details: data.publishedAt };
+    }
+  }
+  const lock = readIfPresent(join(dir, 'run.lock'));
+  if (lock) {
+    let pid: unknown;
+    try { pid = (JSON.parse(lock) as { pid?: unknown } | null)?.pid; }
+    catch { pid = undefined; }
+    if (typeof pid === 'number' && Number.isSafeInteger(pid) && pid > 0 && (deps.isPidAlive ?? isPidAlive)(pid)) {
+      return { ready: false, reason: 'already-running', details: String(pid) };
+    }
+  }
+  const gate = (deps.checklist ?? checklistGate)(version);
+  if (!gate.ok) return { ready: false, reason: 'checklist-blocked', details: gate };
+  return { ready: true, reason: 'ready', details: gate };
+}

package/scripts/release-loop/shard-plan.ts

@@ -0,0 +1,47 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { join } from 'node:path';
+
+/** Read per-file seconds from previous cut Pod reports; missing or damaged reports are not estimates. */
+export function readFileDurations(dir: string): Map<string, number> {
+  const durations = new Map<string, number>();
+  let names: string[];
+  const entities: Record<string, string> = { '&amp;': '&', '&quot;': '"', '&apos;': "'", '&lt;': '<', '&gt;': '>' };
+  try { names = readdirSync(dir).filter((name) => name.endsWith('.junit.xml')).sort(); }
+  catch { return durations; }
+  for (const name of names) {
+    try {
+      const xml = readFileSync(join(dir, name), 'utf8');
+      for (const match of xml.matchAll(/<testsuite\b([^>]*)>/g)) {
+        const attrs = match[1]!;
+        const file = /\bfile="([^"]+)"/.exec(attrs)?.[1];
+        const rawTime = /\btime="([^"]+)"/.exec(attrs)?.[1];
+        if (!file || rawTime === undefined) continue;
+        const seconds = Number(rawTime);
+        if (!Number.isFinite(seconds) || seconds < 0) continue;
+        const path = file.replace(/&(?:amp|quot|apos|lt|gt);/g, (entity) => entities[entity]!);
+        durations.set(path, Math.max(durations.get(path) ?? 0, seconds));
+      }
+    } catch { /* One unreadable report must not discard the others. */ }
+  }
+  return durations;
+}
+
+/** Longest processing time first; tie-breaks use lexical paths, then the least populated lightest shard. */
+export function planShards(files: string[], durations: Map<string, number>, count: number): Array<{ files: string[]; plannedSeconds: number }> {
+  if (!Number.isSafeInteger(count) || count < 1) throw new Error('invalid shard count');
+  const known = files.map((file) => durations.get(file)).filter((value): value is number => value !== undefined && Number.isFinite(value) && value >= 0).sort((a, b) => a - b);
+  const median = known.length ? (known[Math.floor((known.length - 1) / 2)]! + known[Math.floor(known.length / 2)]!) / 2 : 1;
+  const weight = (file: string) => {
+    const value = durations.get(file);
+    return value !== undefined && Number.isFinite(value) && value >= 0 ? value : median;
+  };
+  const shards = Array.from({ length: Math.min(count, files.length) }, () => ({ files: [] as string[], plannedSeconds: 0 }));
+  for (const file of [...files].sort((a, b) => weight(b) - weight(a) || (a < b ? -1 : a > b ? 1 : 0))) {
+    let lightest = shards[0]!;
+    for (const shard of shards) if (shard.plannedSeconds < lightest.plannedSeconds
+      || (shard.plannedSeconds === lightest.plannedSeconds && shard.files.length < lightest.files.length)) lightest = shard;
+    lightest.files.push(file);
+    lightest.plannedSeconds += weight(file);
+  }
+  return shards.filter((shard) => shard.files.length > 0);
+}

package/scripts/release-loop/unattended-release.ts

@@ -0,0 +1,93 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDirOverride } from '../../src/elanous-config-dir.js';
+import { effectiveInstanceRoot, releaseLedgerRoot } from '../../src/instance/resolve.js';
+import { userConfigPath } from '../../src/user-config.js';
+import { checklistGate } from '../../src/release-loop/checklist.js';
+import { runGraph, type GraphRunState } from '../../src/graph-runner/runner.js';
+
+const VERSION = /^(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)\.(?:0|[1-9]\d*)$/;
+const GRAPH = join(import.meta.dir, '../../graphs/release/release-loop.yaml');
+
+export interface ReleaseLoopConfig {
+  gatePodPool?: string;
+  gatePodBunCache?: string;
+  gatePodShards?: number;
+  gatePodShardTimeoutSeconds?: number;
+  gateRemote?: string;
+  gateRemoteMirror?: string;
+  opsHosts?: string[];
+  internalDist?: string;
+  opsRestart?: boolean;
+}
+
+export interface ReleaseRunInput extends ReleaseLoopConfig {
+  version: string;
+  previousVersion: string;
+  gatePodPool: string;
+}
+
+export interface UnattendedReleaseDeps {
+  ledgerRoot?: string;
+  config?: ReleaseLoopConfig;
+  configPath?: string;
+  graph?: (path: string, options: { input: ReleaseRunInput }) => Promise<GraphRunState>;
+  checklist?: typeof checklistGate;
+}
+
+function compareVersions(a: string, b: string): number {
+  const aa = a.split('.').map(BigInt), bb = b.split('.').map(BigInt);
+  for (let i = 0; i < 3; i++) {
+    if (aa[i]! < bb[i]!) return -1;
+    if (aa[i]! > bb[i]!) return 1;
+  }
+  return 0;
+}
+
+/** Only completed publications in the release ledger count as a prior release. */
+export function latestPublishedPreviousVersion(version: string, ledgerRoot = releaseLedgerRoot()): string {
+  if (!VERSION.test(version)) throw new Error(`release version must be x.y.z: ${version}`);
+  const dir = join(ledgerRoot, 'release');
+  const versions = existsSync(dir) ? readdirSync(dir) : [];
+  const published = versions.filter((candidate) => {
+    if (!VERSION.test(candidate) || compareVersions(candidate, version) >= 0) return false;
+    try {
+      const record = JSON.parse(readFileSync(join(dir, candidate, 'release.json'), 'utf8')) as { version?: unknown; publishedAt?: unknown };
+      return record.version === candidate && typeof record.publishedAt === 'string' && record.publishedAt.trim().length > 0;
+    } catch { return false; }
+  });
+  const previous = published.sort((a, b) => compareVersions(b, a))[0];
+  if (!previous) throw new Error(`no published previous release before ${version} in ${dir}`);
+  return previous;
+}
+
+export function releaseLoopConfig(configPath = getElanousConfigDirOverride() ? join(effectiveInstanceRoot(), 'config.json') : userConfigPath()): ReleaseLoopConfig {
+  if (!existsSync(configPath)) return {};
+  const raw = JSON.parse(readFileSync(configPath, 'utf8')) as { release?: { loop?: ReleaseLoopConfig } };
+  return raw.release?.loop ?? {};
+}
+
+export function buildReleaseRunInput(version: string, deps: UnattendedReleaseDeps = {}): ReleaseRunInput {
+  const config = deps.config ?? releaseLoopConfig(deps.configPath);
+  const pool = config.gatePodPool;
+  if (typeof pool !== 'string' || !pool.trim()) throw new Error('release.loop.gatePodPool is required before graph execution');
+  const previousVersion = latestPublishedPreviousVersion(version, deps.ledgerRoot);
+  return {
+    ...config,
+    version, previousVersion,
+    gatePodPool: pool.trim(),
+  };
+}
+
+/** Fail closed at the entry boundary, before any graph node can change a release. */
+export async function runUnattendedRelease(
+  opts: { version: string; dryRun?: boolean },
+  deps: UnattendedReleaseDeps = {},
+): Promise<{ input: ReleaseRunInput; dryRun: boolean; state?: GraphRunState }> {
+  const input = buildReleaseRunInput(opts.version, deps);
+  if (opts.dryRun) return { input, dryRun: true };
+  const gate = (deps.checklist ?? checklistGate)(opts.version);
+  if (!gate.ok) throw new Error(`release checklist blocked: ${[...gate.red, ...gate.undecided, ...gate.blocked].join(', ')}`);
+  const state = await (deps.graph ?? runGraph)(GRAPH, { input });
+  return { input, dryRun: false, state };
+}

package/scripts/ux/measure-first-text.ts

@@ -0,0 +1,102 @@
+// Usage: bun scripts/ux/measure-first-text.ts --questions questions.json [--url http://127.0.0.1:3456] [--token-stdin] [--json]
+// questions.json is a nonempty JSON array of nonempty question strings. Each question starts a fresh session.
+import { readFileSync } from 'node:fs';
+
+export interface FirstTextMeasurement {
+  question: string;
+  firstTextMs: number;
+  delta: string;
+}
+
+/** Stop the clock on the first complete, nonempty text-delta SSE event, not on response headers or turn-begin. */
+export async function measureFirstText(
+  question: string,
+  url: string,
+  options: { token?: string; fetch?: typeof fetch; now?: () => number } = {},
+): Promise<FirstTextMeasurement> {
+  const fetchFn = options.fetch ?? fetch;
+  const now = options.now ?? (() => performance.now());
+  const controller = new AbortController();
+  const started = now();
+  let reader: ReadableStreamDefaultReader<Uint8Array> | undefined;
+  try {
+    const response = await fetchFn(new URL('/v1/prompt/stream', url), {
+      method: 'POST',
+      headers: {
+        'content-type': 'application/json',
+        accept: 'text/event-stream',
+        ...(options.token ? { authorization: `Bearer ${options.token}` } : {}),
+      },
+      body: JSON.stringify({ userText: question }),
+      signal: controller.signal,
+    });
+    if (!response.ok) throw new Error(`HTTP ${response.status}: ${await response.text()}`);
+    if (!response.body) throw new Error('SSE response has no body');
+    reader = response.body.getReader();
+    const decoder = new TextDecoder();
+    let buffer = '';
+    while (true) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      buffer += decoder.decode(value, { stream: true });
+      // SSE separators can straddle arbitrary UTF-8 chunks (including CRLF boundaries).
+      let boundary: RegExpExecArray | null;
+      while ((boundary = /\r?\n\r?\n/.exec(buffer)) !== null) {
+        const frame = buffer.slice(0, boundary.index);
+        buffer = buffer.slice(boundary.index + boundary[0].length);
+        const event = /^event:\s*(.*)$/m.exec(frame)?.[1]?.trim();
+        const data = frame.split(/\r?\n/).filter((line) => line.startsWith('data:')).map((line) => line.slice(5).trimStart()).join('\n');
+        if (event === 'text-delta') {
+          const payload: unknown = JSON.parse(data);
+          const delta = payload && typeof payload === 'object' && 'delta' in payload ? payload.delta : undefined;
+          if (typeof delta === 'string' && delta.length > 0) {
+            return { question, firstTextMs: now() - started, delta };
+          }
+        }
+        if (event === 'error') throw new Error(`SSE error: ${data}`);
+        if (event === 'turn-end') throw new Error('Turn ended without a text-delta');
+      }
+    }
+    throw new Error('SSE stream ended without a text-delta');
+  } finally {
+    // Do not leave the daemon generating the rest of a turn after the measurement.
+    if (reader) await reader.cancel().catch(() => {});
+    controller.abort();
+  }
+}
+
+export async function run(argv: string[], deps: { fetch?: typeof fetch; now?: () => number; stdin?: () => Promise<string> } = {}): Promise<FirstTextMeasurement[]> {
+  let url = 'http://127.0.0.1:3456';
+  let questionsPath: string | undefined;
+  let json = false;
+  let tokenStdin = false;
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (arg === '--json') json = true;
+    else if (arg === '--token-stdin') tokenStdin = true;
+    else if (arg === '--url' || arg === '--questions') {
+      const value = argv[++i];
+      if (!value || value.startsWith('--')) throw new Error(`${arg} requires a value`);
+      if (arg === '--url') url = value;
+      else questionsPath = value;
+    } else throw new Error(`Unknown argument: ${arg}`);
+  }
+  if (!questionsPath) throw new Error('Usage: --questions <JSON file> [--url <base URL>] [--token-stdin] [--json]');
+  const questions: unknown = JSON.parse(readFileSync(questionsPath, 'utf8'));
+  if (!Array.isArray(questions) || !questions.length || !questions.every((q) => typeof q === 'string' && q.trim().length > 0)) {
+    throw new Error('--questions must be a nonempty JSON array of nonempty strings');
+  }
+  const token = tokenStdin ? (await (deps.stdin ?? (() => Bun.stdin.text()))()).trim() : undefined;
+  const results: FirstTextMeasurement[] = [];
+  for (const question of questions as string[]) {
+    results.push(await measureFirstText(question, url, { token, fetch: deps.fetch, now: deps.now }));
+  }
+  if (json) console.log(JSON.stringify(results));
+  else for (const result of results) console.log(`${result.firstTextMs.toFixed(1)} ms\t${result.question}`);
+  return results;
+}
+
+if (import.meta.main) {
+  try { await run(process.argv.slice(2)); }
+  catch (error) { console.error(error instanceof Error ? error.message : String(error)); process.exitCode = 1; }
+}

package/scripts/ux/record-page.ts

@@ -12,7 +12,7 @@ import { Frames, launch, PUBLIC_LEAK_CHECK, sleep } from './lib/cdp.js';
 const arg = (k: string) => { const i = process.argv.indexOf(`--${k}`); return i > 0 ? process.argv[i + 1] : undefined; };
 const flag = (k: string) => process.argv.includes(`--${k}`);
 const rawUrl = arg('url'); const out = arg('out');
-if (!rawUrl || !out) { console.error('usage: --url <url> --out <dir> [--secs N] [--size WxH] [--mobile] [--type text] [--shot] [--token-stdin]'); process.exit(64); }
+if (!rawUrl || !out) { console.error('usage: --url <url> --out <dir> [--secs N] [--size WxH] [--mobile] [--type text] [--shot] [--token-stdin] [--eval <js>]'); process.exit(64); }
 const mobile = flag('mobile');
 const [W, H] = mobile ? [390, 844] : (arg('size') ?? '1920x1080').split('x').map(Number);
 const DPR = mobile ? 3 : 1; const SECS = Number(arg('secs') ?? 20);
@@ -26,6 +26,9 @@ if (flag('token-stdin')) {
   if (temp) { await cdp.send('Page.navigate', { url: `${u.origin}/app/` }); await sleep(3000); await cdp.ev(`localStorage.setItem('elanous.daemon.token', ${JSON.stringify(temp)})`); }
 }
 await cdp.send('Page.navigate', { url: u.toString() }); await sleep(8000);
+// --eval <js>: 녹화 전에 화면 상태를 맞춘다(출처 선택·토글·배너 닫기) — 기록에 남도록 그대로 찍는다.
+const pre = arg('eval');
+if (pre) { console.log('eval', await cdp.ev<string>(`(()=>{try{${pre};return 'ok'}catch(e){return 'error: '+e}})()`)); await sleep(4000); }
 const check = async (tag: string) => console.log(tag, await cdp.ev<string>(PUBLIC_LEAK_CHECK));
 await check('before');
 if (flag('shot')) { const f = join(out, `shot-${W}x${H}.png`); await cdp.png(f); console.log('png', f); cdp.close(); process.exit(0); }

package/scripts/vflow-collect.ts

@@ -22,17 +22,30 @@ const UA = 'Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) AppleWebKit/537.36';
 const OUT_DIR = process.env.VFLOW_OUT ?? join(homedir(), 'docs', 'ref', 'vflow');
 const NDJSON = join(OUT_DIR, 'prompts.ndjson');
 const URLS = join(OUT_DIR, 'urls.txt');
-const CONCURRENCY = 4;
-const GAP_MS = 120;
+// ⚠️ 2026-10-01 실측: 4병렬·120ms 로 전수를 돌리면 수백 건 뒤 사이트가 429 를 낸다(재수집 404건 중 158건).
+// 기본을 낮추고, 429 는 «없다»가 아니라 «기다려라»로 읽는다(Retry-After 를 따른다).
+const CONCURRENCY = Number(process.env.VFLOW_CONCURRENCY ?? 2);
+const GAP_MS = Number(process.env.VFLOW_GAP_MS ?? 400);
+const MAX_429_RETRIES = 5;
 
 const argv = process.argv.slice(2);
 const limitAt = argv.indexOf('--limit');
 const LIMIT = limitAt >= 0 ? Number(argv[limitAt + 1]) : Infinity;
 
+let throttled = 0;
 async function get(url: string): Promise<string> {
-  const r = await fetch(url, { headers: { 'User-Agent': UA } });
-  if (!r.ok) throw new Error(`HTTP ${r.status}`);
-  return r.text();
+  for (let attempt = 0; ; attempt++) {
+    const r = await fetch(url, { headers: { 'User-Agent': UA } });
+    if (r.status === 429 && attempt < MAX_429_RETRIES) {
+      throttled++;
+      const after = Number(r.headers.get('retry-after'));
+      const waitMs = Number.isFinite(after) && after > 0 ? after * 1000 : 5000 * 2 ** attempt;
+      await new Promise((res) => setTimeout(res, waitMs));
+      continue;
+    }
+    if (!r.ok) throw new Error(`HTTP ${r.status}`);
+    return r.text();
+  }
 }
 
 /** 사이트맵 전수 → 영문 `/prompts/` URL. ⛔ 번역판(`/{lang}/prompts/`)은 «같은 내용»이라 뺀다. */
@@ -166,14 +179,14 @@ async function main(): Promise<void> {
       catch { failed++; return null; }                  // ⛔ 「없다」가 아니라 «못 받았다»
     }));
     for (const r of rows) { if (r) { appendFileSync(NDJSON, JSON.stringify(r) + '\n'); ok++; } else noLd++; }
-    if ((i / CONCURRENCY) % 25 === 0) console.log(`  … ${ok + noLd}/${todo.length}  ok=${ok} 건너뜀=${noLd}`);
+    if ((i / CONCURRENCY) % 25 === 0) console.log(`  … ${ok + noLd}/${todo.length}  ok=${ok} 못받음=${failed} jsonld없음=${noLd - failed} 429대기=${throttled}`);
   }
   // ⛔ 수를 «도구가» 낸다 — 사람이 세지 않는다.
   writeFileSync(join(OUT_DIR, 'MANIFEST.txt'),
     [`source: https://vflow.live (robots: Allow: / · 2026-09-23 확인)`,
      `fetched: ${new Date().toISOString()}`,
      `urls_total: ${urls.length}`, `rows_ok: ${ok + done.size}`,
-     `skipped_no_jsonld: ${noLd - failed}`, `failed_fetch: ${failed}`,
+     `skipped_no_jsonld: ${noLd - failed}`, `failed_fetch: ${failed}`, `throttled_429_retries: ${throttled}`,
      `schema: url model category slug name description prompt keywords[] datePublished author authorUrl sourcePost thumb spec{duration,camera[],lighting[],mood[],difficulty,promptLanguage,includes[]} video{url,isoDuration,resolution,aspect}`,
      `refetch: bun scripts/vflow-collect.ts`, ''].join('\n'));
   console.log(`\n  ✅ ok ${ok} · 건너뜀 ${noLd - failed} · 못 받음 ${failed}  →  ${NDJSON}`);

package/scripts/vflow-search.ts

@@ -0,0 +1,73 @@
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { searchVflowReferences, type VflowQuery } from '../src/video-pipeline/vflow-reference.js';
+
+const args = process.argv.slice(2);
+let file = join(homedir(), 'docs', 'ref', 'vflow', 'prompts.ndjson');
+const query: { -readonly [K in keyof VflowQuery]: VflowQuery[K] } = { limit: 5 };
+let json = false;
+const techniques: string[] = [];
+const terms: string[] = [];
+
+for (let i = 0; i < args.length; i++) {
+  const arg = args[i]!;
+  if (arg === '--json') { json = true; continue; }
+  if (['--file', '--model', '--technique', '--category', '--limit', '--camera', '--lighting', '--mood', '--max-seconds'].includes(arg)) {
+    const value = args[++i];
+    if (!value || value.startsWith('--')) {
+      console.error(`값이 필요한 옵션: ${arg}`);
+      process.exit(1);
+    }
+    switch (arg) {
+      case '--file': file = value; break;
+      case '--model': query.model = value; break;
+      case '--technique': techniques.push(value); break;
+      case '--category': query.category = value; break;
+      case '--camera': query.camera = value; break;
+      case '--lighting': query.lighting = value; break;
+      case '--mood': query.mood = value; break;
+      case '--limit': {
+        const parsed = Number(value);
+        if (!Number.isSafeInteger(parsed) || parsed < 0) {
+          console.error(`--limit 은 0 이상의 정수여야 합니다: ${value}`);
+          process.exit(1);
+        }
+        query.limit = parsed;
+        break;
+      }
+      case '--max-seconds': {
+        const parsed = Number(value);
+        if (!Number.isFinite(parsed) || parsed < 0 || !value.trim()) {
+          console.error(`--max-seconds 은 0 이상의 숫자여야 합니다: ${value}`);
+          process.exit(1);
+        }
+        query.maxSeconds = parsed;
+        break;
+      }
+    }
+  } else if (arg.startsWith('--')) {
+    console.error(`알 수 없는 옵션: ${arg}`);
+    process.exit(1);
+  } else {
+    terms.push(arg);
+  }
+}
+query.terms = terms;
+query.techniques = techniques;
+const result = searchVflowReferences(file, query);
+if (!result.available) {
+  console.error(`입력 파일을 읽을 수 없습니다: ${file} (${result.reason})`);
+  process.exit(1);
+}
+if (json) {
+  console.log(JSON.stringify(result.rows.map(({ url, model, category, name, prompt, keywords, author, authorUrl, video }) =>
+    ({ url, model, category, name, prompt, keywords, author, authorUrl, video: video ?? null }))));
+  if (result.matches === 0) console.error(`일치 0 · 읽은 줄 ${result.read}`);
+} else if (result.matches === 0) {
+  console.log(`일치 0 · 읽은 줄 ${result.read}`);
+} else {
+  for (const row of result.rows) {
+    console.log(`${row.name} · ${row.model}\n${row.url}\n${row.author ?? ''}\n${row.prompt.slice(0, 240)}${row.video?.url ? `\n${row.video.url}` : ''}`);
+  }
+}
+if (result.skipped) console.error(`건너뛴 줄 ${result.skipped}`);

package/scripts/video-free-line-test-walker.ts

@@ -0,0 +1,36 @@
+import { readFileSync } from 'node:fs';
+import { parse as parseYaml } from 'yaml';
+import type { GraphSpecLike, WalkerApi } from '../src/video-pipeline/walk-line.js';
+
+interface TestGraph extends GraphSpecLike {
+  entry_node: string;
+  terminal_nodes: string[];
+  nodes: ({ node_id: string; recipe?: string; max_visits?: number })[];
+}
+
+export const readGraphSpec: WalkerApi['readGraphSpec'] = (path) => {
+  try { return { spec: parseYaml(readFileSync(path, 'utf8')) as TestGraph }; }
+  catch (e) { return { error: (e as Error).message }; }
+};
+
+export const walkGraph: WalkerApi['walkGraph'] = async (graph, step, opts) => {
+  const spec = graph as TestGraph;
+  const visits = new Map<string, number>();
+  const steps: { node: string; visit: number }[] = [];
+  let next = spec.entry_node;
+  while (steps.length < opts.maxSteps) {
+    const node = spec.nodes.find((n) => n.node_id === next);
+    if (!node) return { terminal: null, stopReason: 'no-node', steps };
+    const visit = (visits.get(next) ?? 0) + 1;
+    if (visit > (node.max_visits ?? 1)) return { terminal: null, stopReason: 'budget-exceeded', steps };
+    visits.set(next, visit);
+    steps.push({ node: next, visit });
+    if (spec.terminal_nodes.includes(next)) return { terminal: next, stopReason: 'terminal', steps };
+    const outcome = await step(node);
+    if (outcome === null) { next = opts.unobservedNode; continue; }
+    const edge = spec.edges.find((e) => e.from === next && (e.to !== undefined || e.map?.[outcome] !== undefined));
+    if (!edge) return { terminal: null, stopReason: 'no-edge', steps };
+    next = edge.to ?? edge.map![outcome]!;
+  }
+  return { terminal: null, stopReason: 'budget-exceeded', steps };
+};

package/scripts/video-pipeline.ts

@@ -998,9 +998,8 @@ async function plan() {
     return where.length ? `${u} → 구간을 «${where.join('/')}» 까지` : `${u} → ⛔ 스핀 결손`;
   });
 
-  sayUnprobed();
-
   if (COMPACT) {
+    sayUnprobed();
     // ⛔ 노드별로 찍지 않는다 — encode 가 세 번 나온다. 능력 단위로 «접는다».
     const seen = new Map<string, { impl?: Impl; required: boolean }>();
     for (const o of out) for (const p of o.picks) {
@@ -1138,6 +1137,7 @@ async function plan() {
     return;
   }
 
+  sayUnprobed();
   console.log(`\n🧱 추천 스택 — 구간 ${nodes[0].id} → ${nodes[nodes.length - 1].id} · 선호 ${TIER_MARK[prefer]}`);
   console.log(`   설정: ${LOADED.source}${MACHINE ? ` · 기계 «${MACHINE_NAME}»` : ''}`);
   if (MISSING.size) console.log(`   ⚠️ 없다고 «가정»한 것: ${[...MISSING].join(', ')}`);

package/skills/explainer-video/SKILL.md

@@ -35,13 +35,14 @@ The grammar of a chapter (take it from the reference, don't improvise):
 
 The outro gives one line that sums everything up, then the CTA.
 
-⛔ Every claim must trace to a merged change or a measured run, listed in `sources`. Don't write «fully autonomous», dates you can't promise, or comparisons (`docs/marketing/GUIDE-launch-tone-and-banned-claims-*`).
+⛔ Every claim must trace to a merged change or a measured run, listed in `sources`. Don't write «fully autonomous», dates you can't promise, or comparisons with other products.
 
 ## 2. Voice — `bun $SKILL/engine/vo.ts <project>/script.json`
 
 - Makes one `/with-timestamps` call per beat and writes `source/vo/<key>.mp3` and `<key>.json`, where the JSON holds per-character times.
 - A beat whose text hash is unchanged is skipped, so you can edit one line and re-run.
 - The key comes from `ELEVENLABS_API_KEY`, which the plugin connector sets (`elanous plugin credentials video-explainer`). Never print it.
+- **No key** → a draft voice from macOS `say` (a Korean system voice; `EXPLAINER_SAY_VOICE` picks one). Character times are then spread over the measured length — captions still land per line, keyword timing is approximate. Use it for unattended runs and rehearsals; use ElevenLabs for anything public.
 
 ## 3. Compose — `node $SKILL/engine/build.mjs <project>/script.json`
 
@@ -84,7 +85,27 @@ The reference supplies the **grammar** (components and staging), never its colou
 - **Text**: `#F2F1EE`.
 - **Motif**: the V6 «엘랑 소용돌이» mark (`engine/brand/`), used in three places — a slow, faint rotation behind the scene, the header, and the chapter cards.
 
-Why these choices, what the reference does, and what we can and cannot reproduce: `내부 문서 `RESEARCH-explainer-video-reference-decomposition-2026-09-30``.
+The reference is used only for its structure (header, chapter cards, a diagram that moves one step per line, keyword-timed captions). Its colours, artwork and voice are not reproduced.
+
+## Field reel — photos from the venue → a vertical video in about a minute
+
+```bash
+zsh $SKILL/engine/reel.sh <folder> --title "마케터의 밤" --sub "2026.10.02 · 서울"
+```
+
+- **Input**: a folder of phone photos (jpg · png · heic) and short clips (mp4 · mov). The default upload folder is `~/.elanous/field/<event>/`.
+- **Order**: by capture time (`mdls` creation date), then by file name.
+- **Captions**: optional `<folder>/captions.txt`, one line per item as `파일명 | 자막`. A photo without a line gets one line from a vision model (`codex exec -i`, all photos in parallel, 30 s cap each); if that fails it shows «현장 N». `FIELD_REEL_VISION=0` turns the vision step off.
+- **Title**: `--title`, or `title.txt` through the daemon. A slug-like title (`field-2026-10-01`) is replaced by a vision headline read from the first three photos (event or company names on screen first). The date line defaults to the first photo's capture date (KST).
+- **Music**: `FIELD_REEL_BGM=<file>` or `~/.cache/elanous-explainer/bgm/field.wav` — cut to length, faded in and out, leveled to about −16 LUFS. No file means no music. Use only licensed tracks (the default cache holds an Epidemic Sound download); the file is never committed.
+- **Output**:
+  - `<folder>/reel/reel-9x16.mp4` at 1080×1920, 24–60 s.
+  - An intro card (kicker, mark, title word by word, red rule, date), then each item: photos for about 4–6 s. A landscape photo is shown whole over a blurred fill of itself; a portrait photo fills the frame. Each move overlaps the next with a slide and a red wipe on the cut.
+  - Per item a counter (`01 / 03`), the caption rising word by word, and a red rule. The V6 header, an Icarus Red progress bar, and an end card with elanous.ai.
+  - `--part body` renders the photos only (no cards, no music) — for an instant version that stitches pre-rendered cards around it.
+- **Fitting to length**: over 60 s drops items from the middle, keeping the first and last. Under 24 s stretches the photos.
+- **Measured**: 3 photos → 24 s video in 28 s end to end, of which vision 8.7 s and render 15.9 s (M-series Mac, 10-01). Earlier: 7 items → 31.2 s video in 56–83 s.
+- **Before posting**: people's faces need their consent. Run the same 1 fps OCR check as any public video.
 
 ## Graph
 
@@ -96,4 +117,4 @@ Why these choices, what the reference does, and what we can and cannot reproduce
   - speech mismatch → vo;
   - bad script → script;
   - public release → needs-human.
-- **Not coded yet**: the `explainer-*` recipes. Until they are, you run these steps from this skill.
+- **Recipes**: the `explainer-*` recipes are in the elanous core, but `graph run` does not yet accept this graph's terminal nodes. The video-explainer plugin therefore ships the skill and nodes only; run these steps from this skill. The graph comes with plugin 0.2.0.