elanous 0.2.0 → 0.2.5

package/src/util/spawn-sync-output.ts

@@ -0,0 +1,15 @@
+import { spawnSync, type SpawnSyncOptionsWithStringEncoding } from 'node:child_process';
+
+/** Read command text completely or fail closed; never return a partial stdout. */
+export function spawnSyncText(
+  cmd: string,
+  args: readonly string[],
+  opts: SpawnSyncOptionsWithStringEncoding = { encoding: 'utf8' },
+): string {
+  const result = spawnSync(cmd, [...args], { ...opts, maxBuffer: opts.maxBuffer ?? 256 * 1024 * 1024 });
+  if (result.error || result.status !== 0) {
+    const reason = result.error?.message ?? result.stderr?.trim() ?? '';
+    throw new Error(`${cmd} ${args.join(' ')} failed (status=${result.status}${result.error ? `, error=${(result.error as NodeJS.ErrnoException).code ?? result.error.name}` : ''}): ${reason}`);
+  }
+  return result.stdout;
+}

package/src/version/code-revision.ts

@@ -54,7 +54,7 @@ function usableInstallMetadataCommit(commit: string): string | undefined {
   return revision;
 }
 
-function readInstallMetadataCommit(metadataPath: string): string | undefined {
+export function readInstallMetadataCommit(metadataPath: string): string | undefined {
   try {
     const parsed: unknown = JSON.parse(readFileSync(metadataPath, 'utf8'));
     if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) return undefined;
@@ -140,11 +140,19 @@ function versionedInstallerMetadataPath(versionDir: string, packageEntry: string
   const root = resolve(versionsDir, '..');
   try {
     const shim = _joinPath(root, 'bin', 'elanous');
-    if (!lstatSync(shim).isSymbolicLink()) return undefined;
-    if (readlinkSync(shim, 'utf8').replace(/\\/g, '/') !== '../current/node_modules/.bin/elanous') return undefined;
-    const bunBinShim = _joinPath(versionDir, 'node_modules', '.bin', 'elanous');
-    if (!sameResolvedPath(bunBinShim, packageEntry)
-      && !(isFile(bunBinShim) && PACKAGE_ENTRY_PATTERN.test(readFileSync(bunBinShim, 'utf8')))) return undefined;
+    const shimStat = lstatSync(shim);
+    if (shimStat.isSymbolicLink()) {
+      if (readlinkSync(shim, 'utf8').replace(/\\/g, '/') !== '../current/node_modules/.bin/elanous') return undefined;
+      const bunBinShim = _joinPath(versionDir, 'node_modules', '.bin', 'elanous');
+      if (!sameResolvedPath(bunBinShim, packageEntry)
+        && !(isFile(bunBinShim) && PACKAGE_ENTRY_PATTERN.test(readFileSync(bunBinShim, 'utf8')))) return undefined;
+    } else if (shimStat.isFile()) {
+      // #21004 뒤 설치기는 bin/elanous 를 «bun 절대 경로 래퍼»(2번째 줄 `# elanous-wrapper`)로 쓴다 — 링크가 아니다.
+      //   래퍼가 이 설치 뿌리의 current 엔트리를 부를 때만 설치기 소유로 본다.
+      const text = readFileSync(shim, 'utf8');
+      if (text.split('\n')[1] !== '# elanous-wrapper') return undefined;
+      if (!text.includes(_joinPath(root, 'current', 'node_modules', 'elanous', 'bin', 'elanous.mjs'))) return undefined;
+    } else return undefined;
   } catch {
     return undefined;
   }
@@ -168,19 +176,36 @@ function installerOwnedMetadataPath(packageRoot: string): string | undefined {
   return _joinPath(prefix, 'install.json');
 }
 
-/** git 이 실패했을 때만 install.json 의 commit 을 본다. caller cwd 는 쓰지 않는다. */
-function installMetadataCommit(root: string): string | undefined {
+function installMetadataCandidates(root: string): string[] {
   const metadataRoot = testInstallMetadataRoot ?? root;
   const candidates = [_joinPath(metadataRoot, 'install.json')];
   const owned = installerOwnedMetadataPath(metadataRoot);
   if (owned && owned !== candidates[0]) candidates.push(owned);
-  for (const metadataPath of candidates) {
+  return candidates;
+}
+
+/** git 이 실패했을 때만 install.json 의 commit 을 본다. caller cwd 는 쓰지 않는다. */
+function installMetadataCommit(root: string): string | undefined {
+  for (const metadataPath of installMetadataCandidates(root)) {
     const commit = readInstallMetadataCommit(metadataPath);
     if (commit) return commit;
   }
   return undefined;
 }
 
+/** Return the install.json source only when it names an existing directory. */
+export function installMetadataSource(root: string = REPOSITORY_ROOT): string | undefined {
+  for (const metadataPath of installMetadataCandidates(root)) {
+    try {
+      const parsed: unknown = JSON.parse(readFileSync(metadataPath, 'utf8'));
+      if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) continue;
+      const source = (parsed as { readonly source?: unknown }).source;
+      if (typeof source === 'string' && statSync(source).isDirectory()) return source;
+    } catch { /* Try the next candidate. */ }
+  }
+  return undefined;
+}
+
 export function cliVersion(): string {
   return `${packageVersion()} ${codeRevision() ?? 'unknown'}`;
 }

package/src/version/packed-revision.json

@@ -1 +1 @@
-{"commit":"d67c25e0bae2a451acd69420018cd204263aac76"}
+{"commit":"e491ebfd1661520b780aff439e71baa26895ab53"}

package/src/video-pipeline/broll-agent.ts

@@ -0,0 +1,102 @@
+import { spawn } from 'node:child_process';
+import { lstatSync, realpathSync, unlinkSync } from 'node:fs';
+import { join, relative, resolve } from 'node:path';
+import { checkClaudeSubscription } from '../agent-mission/claude-subscription.js';
+import { resolveBackend, runAgentMission } from '../agent-mission/driver.js';
+import { debug } from '../debug/log.js';
+import { emitDecision } from '../live/detail-switch.js';
+import type { BrollAgent } from './recipes/broll.js';
+
+export interface BrollAgentOptions {
+  backend: 'codex' | 'claude' | 'elanous';
+  clipsDir: string;
+  skillDir: string;
+  runMission?: typeof runAgentMission;
+  runElanous?: (prompt: string, cwd: string, signal: AbortSignal) => Promise<void>;
+  claudeAvailable?: () => Promise<boolean>;
+}
+
+async function defaultRunElanous(prompt: string, cwd: string, signal: AbortSignal): Promise<void> {
+  await new Promise<void>((resolve, reject) => {
+    // `agent` currently requires positional text; relay stdin without interpolating prompt into shell code.
+    const child = spawn('sh', ['-c', 'prompt=$(cat); exec elanous agent --new --json "$prompt"'],
+      { cwd, signal, stdio: ['pipe', 'ignore', 'pipe'] });
+    child.stderr.resume();
+    child.on('error', reject);
+    child.on('close', (code) => code === 0 ? resolve() : reject(new Error(`elanous agent exit ${code}`)));
+    child.stdin.end(prompt);
+  });
+}
+
+function safeClip(path: string, dir: string, name: string): boolean {
+  try {
+    const root = realpathSync(dir);
+    const clip = realpathSync(path);
+    const rel = relative(root, clip);
+    const stat = lstatSync(path);
+    return rel === name && stat.isFile() && !stat.isSymbolicLink();
+  } catch { return false; }
+}
+
+/** Each invocation authors exactly one clip in the mission workdir. */
+export function createBrollAgent(opts: BrollAgentOptions): BrollAgent {
+  const clipsDir = resolve(opts.clipsDir);
+  const runMission = opts.runMission ?? runAgentMission;
+  const runElanous = opts.runElanous ?? defaultRunElanous;
+  const claudeAvailable = opts.claudeAvailable ?? (async () => checkClaudeSubscription({ env: process.env }).ok);
+  return async (slot, { signal }) => {
+    const milliseconds = Math.round(slot.start * 1000);
+    if (!Number.isSafeInteger(milliseconds) || milliseconds < 0) {
+      debug.log('video.broll-agent', 'skipped', { backend: opts.backend, slot: 'invalid', reason: 'invalid-slot-start' });
+      return null;
+    }
+    const name = `slot-${String(milliseconds).padStart(6, '0')}.mp4`;
+    const output = join(clipsDir, name);
+    const prompt = `Read and follow the motion B-roll skill at ${join(opts.skillDir, 'SKILL.md')} (including its engine reference).\n` +
+      `Author one motion-graphic clip for this slot. Spoken words: ${slot.prompt}\n` +
+      `Start: ${slot.start} seconds; end: ${slot.end} seconds; clip duration: ${slot.end - slot.start} seconds.\n` +
+      `Produce exactly one output clip at ${output}. Do not write outside the workdir ${clipsDir}. ` +
+      `Keep any intermediate files inside the workdir. Do not ask for approval; complete this assigned clip.\n` +
+      `The final evidence must be the new file ${name}.`;
+    let backend: BrollAgentOptions['backend'] = opts.backend;
+    debug.log('video.broll-agent', 'start', { backend, slot: name, reason: 'slot' });
+    try {
+      try {
+        lstatSync(output);
+        if (!safeClip(output, clipsDir, name)) {
+          debug.log('video.broll-agent', 'skipped', { backend, slot: name, reason: 'existing-unsafe-clip' });
+          return null;
+        }
+        unlinkSync(output);
+      } catch (e) {
+        if ((e as NodeJS.ErrnoException).code !== 'ENOENT') throw e;
+      }
+      if (backend === 'claude' && !await claudeAvailable()) {
+        backend = 'codex';
+        emitDecision({ kind: 'ROUTE', what: 'B-roll 저작 에이전트', reason: 'claude 로그인 없음 → codex', purpose: '클립 저작 계속', target: 'codex' });
+        debug.log('video.broll-agent', 'route', { backend, slot: name, reason: 'claude 로그인 없음 → codex' });
+      }
+      if (backend === 'elanous') {
+        await runElanous(prompt, clipsDir, signal);
+        if (safeClip(output, clipsDir, name)) {
+          debug.log('video.broll-agent', 'done', { backend, slot: name, reason: 'clip-created' });
+          return output;
+        }
+        debug.log('video.broll-agent', 'skipped', { backend, slot: name, reason: 'clip-missing' });
+        return null;
+      }
+      const result = await runMission({ mission: prompt, agent: resolveBackend(backend), workdir: clipsDir,
+        evidence: { kind: 'doc', dirRel: '.', glob: new RegExp(`^${name.replace('.', '\\.')}$`) }, signal,
+        headless: false, memory: false });
+      if (result.ok && result.evidencePath && resolve(result.evidencePath) === output && safeClip(result.evidencePath, clipsDir, name)) {
+        debug.log('video.broll-agent', 'done', { backend, slot: name, reason: 'evidence-verified' });
+        return result.evidencePath;
+      }
+      debug.log('video.broll-agent', 'skipped', { backend, slot: name, reason: result.ok ? 'evidence-mismatch' : (result.reason ?? 'mission-failed') });
+      return null;
+    } catch (e) {
+      debug.log('video.broll-agent', 'skipped', { backend, slot: name, reason: e instanceof Error ? e.name : 'agent-error' });
+      return null;
+    }
+  };
+}

package/src/video-pipeline/recipes/broll.ts

@@ -0,0 +1,263 @@
+import { createHash } from 'node:crypto';
+import { createReadStream, existsSync, lstatSync, mkdtempSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from 'node:fs';
+import { basename, isAbsolute, join, parse, relative, sep } from 'node:path';
+import { run, type RunResult } from './ffmpeg.js';
+import { UNOBSERVED, type Recipe, type RecipeCtx } from './types.js';
+
+export interface AlignedWord { word: string; start: number; end: number }
+export interface BrollSlot { start: number; end: number; prompt: string }
+export interface BrollClip extends BrollSlot { path: string }
+export type BrollRun = (bin: string, args: readonly string[], timeoutMs: number) => RunResult;
+export type BrollAgent = (slot: BrollSlot, options: { signal: AbortSignal; timeoutMs: number }) => Promise<string | null>;
+
+const runner = (ctx: RecipeCtx): BrollRun => typeof ctx.state.broll_run === 'function' ? ctx.state.broll_run as BrollRun : run;
+const missing = (key: string) => ({ outcome: UNOBSERVED, note: `계약 입력 '${key}' 가 state 에 없다` });
+const positive = (v: unknown): number | null => typeof v === 'number' && Number.isFinite(v) && v > 0 ? v : null;
+const inside = (root: string, path: string): boolean => {
+  const rel = relative(root, path);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+};
+const safeAsset = (path: string, dir: string): boolean => {
+  try {
+    const root = realpathSync(dir);
+    const asset = realpathSync(path);
+    return inside(root, asset) && /\.(mp4|mov|webm)$/i.test(asset);
+  } catch { return false; }
+};
+const errorOf = (e: unknown): string => e instanceof Error ? e.message : String(e);
+const fingerprint = async (path: string): Promise<string> => {
+  const hash = createHash('sha256');
+  for await (const chunk of createReadStream(path)) hash.update(chunk);
+  return hash.digest('hex');
+};
+const clipRecord = (clips: BrollClip[]) => clips.map(({ path, start, end }) => ({ path: realpathSync(path), start, end }));
+
+/** Compare decoded pixels, not an intended-cut manifest or container metadata. */
+const decodedFrame = (path: string, time: number, execute: BrollRun, workdir: string): Buffer | null => {
+  const frameDir = mkdtempSync(join(realpathSync(workdir), 'broll-frame-'));
+  try {
+    const framePath = join(frameDir, 'sample.rgb');
+    const r = execute('ffmpeg', ['-hide_banner', '-loglevel', 'error', '-y', '-ss', String(time), '-i', path,
+      '-frames:v', '1', '-vf', 'scale=32:18,format=rgb24', '-f', 'rawvideo', framePath], 30_000);
+    if (!r.ok || !safeManifest(framePath, workdir)) return null;
+    const frame = readFileSync(framePath);
+    return frame.length === 32 * 18 * 3 ? frame : null;
+  } finally { rmSync(frameDir, { recursive: true, force: true }); }
+};
+const pixelDifference = (a: Buffer, b: Buffer): number => {
+  let difference = 0;
+  for (let i = 0; i < a.length; i++) difference += Math.abs(a[i]! - b[i]!);
+  return difference / a.length;
+};
+const manifestPath = (path: string): string => `${path}.clips.json`;
+const safeManifest = (path: string, dir: string): boolean => {
+  try { return inside(realpathSync(dir), realpathSync(path)); } catch { return false; }
+};
+const occupied = (path: string): boolean => {
+  try { lstatSync(path); return true; } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') return false;
+    throw e;
+  }
+};
+
+/** Use supplied word timings or Whisper's JSON artifact; stdout is diagnostic text, not alignment data. */
+export const brollAlignWords: Recipe = async (ctx) => {
+  let words: unknown = ctx.state.aligned_words;
+  if (words === undefined) {
+    const audio = ctx.state.audio_path;
+    if (typeof audio !== 'string' || !existsSync(audio)) return missing('aligned_words or audio_path');
+    mkdirSync(ctx.workdir, { recursive: true });
+    const workRoot = realpathSync(ctx.workdir);
+    const outputDir = join(workRoot, 'broll-alignment');
+    mkdirSync(outputDir, { recursive: true });
+    if (!inside(workRoot, realpathSync(outputDir))) return { outcome: 'error', note: '정렬 출력 디렉터리가 workdir 밖을 가리킨다' };
+    const output = join(outputDir, `${parse(audio).name}.json`);
+    if (occupied(output)) {
+      let resolved: string;
+      try { resolved = realpathSync(output); } catch { return { outcome: UNOBSERVED, note: '정렬 출력 파일이 깨진 심볼릭 링크다' }; }
+      if (!inside(workRoot, resolved)) return { outcome: 'error', note: '정렬 출력 파일이 workdir 밖을 가리킨다' };
+      rmSync(output);
+    }
+    const r = runner(ctx)('whisper', [audio, '--output_format', 'json', '--word_timestamps', 'True', '--output_dir', outputDir], 180_000);
+    if (!r.ok) return { outcome: 'error', note: `단어 정렬 실패: ${r.err || r.signal || r.code}` };
+    try {
+      if (!inside(workRoot, realpathSync(output))) return { outcome: 'error', note: '정렬 출력 파일이 workdir 밖을 가리킨다' };
+      const parsed: unknown = JSON.parse(readFileSync(output, 'utf8'));
+      words = Array.isArray(parsed) ? parsed :
+        parsed && typeof parsed === 'object' && 'segments' in parsed && Array.isArray(parsed.segments)
+          ? parsed.segments.flatMap((segment: { words?: unknown }) => Array.isArray(segment.words) ? segment.words : [])
+            .filter((w: { start?: unknown; end?: unknown }) => w && !(typeof w.start === 'number' && w.start === w.end))
+          : parsed;
+    } catch { return { outcome: UNOBSERVED, note: '정렬 JSON 파일을 읽을 수 없다' }; }
+  }
+  if (!Array.isArray(words) || words.length === 0 || !words.every((w) => w && typeof w.word === 'string' && w.word.trim() && Number.isFinite(w.start) && Number.isFinite(w.end) && w.start >= 0 && w.end > w.start) ||
+    words.some((w, i) => i > 0 && w.start < words[i - 1].end)) {
+    return { outcome: UNOBSERVED, note: '시각이 정렬된 유효한 단어가 없다' };
+  }
+  const aligned_words: AlignedWord[] = words.map((w) => ({ word: w.word, start: w.start, end: w.end }));
+  return { outcome: 'ok', produced: { aligned_words, narration_seconds: aligned_words[aligned_words.length - 1]!.end }, note: `정렬 단어 ${aligned_words.length}개` };
+};
+
+/** Equally spaced slots are snapped to actual word boundaries; the density is clips per minute. */
+export const brollDensityPlan: Recipe = async (ctx) => {
+  const words = ctx.state.aligned_words as AlignedWord[] | undefined;
+  if (!Array.isArray(words) || !words.length) return missing('aligned_words');
+  const density = positive(ctx.state.density_target);
+  if (density === null) return missing('density_target (clips/min)');
+  const duration = words[words.length - 1]?.end;
+  if (typeof duration !== 'number' || !Number.isFinite(duration) || duration <= 0) return { outcome: UNOBSERVED, note: '나레이션 길이를 못 쟀다' };
+  const count = Math.max(1, Math.ceil(duration * density / 60));
+  if (!Number.isSafeInteger(count)) return { outcome: UNOBSERVED, note: '목표 컷 수를 계산할 수 없다' };
+  if (words.length < count) return { outcome: UNOBSERVED, note: `목표 ${count}컷 달성 불가: 단어 경계 ${words.length}개` };
+  if (!words.every((w, i) => w && typeof w.word === 'string' && w.word.trim() && Number.isFinite(w.start) && Number.isFinite(w.end) && w.start >= 0 && w.end > w.start &&
+    (i === 0 || w.start >= words[i - 1]!.end))) return { outcome: UNOBSERVED, note: '겹치거나 유효하지 않은 단어 경계로 목표 컷을 배치할 수 없다' };
+  const slots: BrollSlot[] = [];
+  let from = 0;
+  for (let i = 1; i <= count; i++) {
+    const remaining = count - i;
+    const desired = duration * i / count;
+    let to = words.length - remaining;
+    if (remaining) {
+      for (let j = from + 1; j <= to; j++) {
+        if (words[j]!.start >= desired) { to = j; break; }
+      }
+    }
+    const group = words.slice(from, to);
+    slots.push({ start: group[0]!.start, end: group[group.length - 1]!.end, prompt: group.map((w) => w.word).join(' ') });
+    from = to;
+  }
+  return { outcome: 'ok', produced: { broll_slots: slots, density_target: density, target_clips: count }, note: `목표 ${count}컷 · 단어 경계에 놓인 ${slots.length}컷` };
+};
+
+/** A failing/timed-out agent must not hold up the rest of the line. Only paths below clips_dir are accepted. */
+export const brollSelectClips: Recipe = async (ctx) => {
+  const slots = ctx.state.broll_slots as BrollSlot[] | undefined;
+  if (!Array.isArray(slots)) return missing('broll_slots');
+  const agent = ctx.state.broll_agent as BrollAgent | undefined;
+  if (typeof agent !== 'function') return missing('broll_agent');
+  const dir = ctx.state.clips_dir;
+  if (typeof dir !== 'string' || !existsSync(dir)) return missing('clips_dir');
+  const timeoutMs = positive(ctx.state.clip_timeout_ms) ?? 30_000;
+  const clips: BrollClip[] = [], skipped: { index: number; reason: string }[] = [];
+  for (const [index, slot] of slots.entries()) {
+    const abort = new AbortController();
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      const selected = await Promise.race([
+        Promise.resolve().then(() => agent(slot, { signal: abort.signal, timeoutMs })),
+        new Promise<null>((_, reject) => { timer = setTimeout(() => { abort.abort(); reject(new Error('timeout')); }, timeoutMs); }),
+      ]);
+      if (typeof selected !== 'string' || !safeAsset(selected, dir)) {
+        skipped.push({ index, reason: 'clip missing or outside clips_dir' });
+      } else clips.push({ ...slot, path: realpathSync(selected) });
+    } catch (e) { skipped.push({ index, reason: errorOf(e) }); }
+    finally { if (timer) clearTimeout(timer); }
+    if (skipped.at(-1)?.index === index) ctx.log('broll.clip-skipped', skipped.at(-1));
+  }
+  return { outcome: clips.length ? 'ok' : 'empty', produced: { broll_clips: clips, skipped_clips: skipped }, note: `선택 ${clips.length}/${slots.length} · 스킵 ${skipped.length}` };
+};
+
+/** FFmpeg receives argv, never a shell string; output is fixed under workdir. */
+export const brollRender: Recipe = async (ctx) => {
+  const base = ctx.state.base_video;
+  const clips = ctx.state.broll_clips as BrollClip[] | undefined;
+  if (typeof base !== 'string' || !existsSync(base)) return missing('base_video');
+  if (!Array.isArray(clips)) return missing('broll_clips');
+  const dir = ctx.state.clips_dir;
+  if (typeof dir !== 'string' || !existsSync(dir)) return missing('clips_dir');
+  const valid = clips.filter((c) => safeAsset(c.path, dir) && Number.isFinite(c.start) && Number.isFinite(c.end) && c.start >= 0 && c.end > c.start);
+  if (!valid.length) return { outcome: 'empty', produced: { rendered_path: null }, note: '렌더할 안전한 클립이 없다' };
+  mkdirSync(ctx.workdir, { recursive: true });
+  const workRoot = realpathSync(ctx.workdir);
+  const outputDir = join(workRoot, 'broll');
+  mkdirSync(outputDir, { recursive: true });
+  if (!inside(workRoot, realpathSync(outputDir))) return { outcome: 'error', note: 'BROLL 출력 디렉터리가 workdir 밖을 가리킨다' };
+  const rendered_path = join(outputDir, 'broll.mp4');
+  if (occupied(rendered_path)) {
+    let resolved: string;
+    try { resolved = realpathSync(rendered_path); } catch { return { outcome: 'error', note: 'BROLL 출력 파일이 깨진 심볼릭 링크다' }; }
+    if (!inside(workRoot, resolved)) return { outcome: 'error', note: 'BROLL 출력 파일이 workdir 밖을 가리킨다' };
+    rmSync(rendered_path);
+  }
+  const manifest = manifestPath(rendered_path);
+  if (occupied(manifest)) {
+    let resolved: string;
+    try { resolved = realpathSync(manifest); } catch { return { outcome: 'error', note: 'BROLL 클립 기록 파일이 깨진 심볼릭 링크다' }; }
+    if (!inside(workRoot, resolved)) return { outcome: 'error', note: 'BROLL 클립 기록 파일이 workdir 밖을 가리킨다' };
+    rmSync(manifest);
+  }
+  const filters: string[] = ['[0:v]setpts=PTS-STARTPTS,scale=1920:1080,setsar=1[v0]'];
+  valid.forEach((c, i) => {
+    const dur = c.end - c.start;
+    filters.push(`[${i + 1}:v]trim=duration=${dur},setpts=PTS-STARTPTS+${c.start}/TB,scale=1920:1080,setsar=1[b${i}]`);
+    filters.push(`[v${i}][b${i}]overlay=0:0:eof_action=pass:enable='between(t,${c.start},${c.end})'[v${i + 1}]`);
+  });
+  const args = ['-hide_banner', '-loglevel', 'error', '-y', '-i', base, ...valid.flatMap((c) => ['-i', c.path]), '-filter_complex', filters.join(';'), '-map', `[v${valid.length}]`, '-map', '0:a?', '-c:v', 'libx264', '-c:a', 'copy', '-movflags', '+faststart', rendered_path];
+  const r = runner(ctx)('ffmpeg', args, 1_200_000);
+  if (!r.ok || !existsSync(rendered_path) || !safeAsset(rendered_path, workRoot)) return { outcome: 'error', note: `BROLL 렌더 실패: ${r.err || r.signal || '안전한 산출 파일 없음'}` };
+  writeFileSync(manifest, JSON.stringify({ sha256: await fingerprint(rendered_path), base: realpathSync(base), clips: clipRecord(valid) }));
+  return { outcome: 'ok', produced: { rendered_path, rendered_clips: valid.length }, note: `BROLL ${valid.length}컷 · ${basename(rendered_path)}` };
+};
+
+/** Fail closed if the rendered artifact cannot be measured; enforce actual coverage, not just a successful subprocess. */
+export const brollQc: Recipe = async (ctx) => {
+  const path = ctx.state.rendered_path;
+  const clips = ctx.state.broll_clips as BrollClip[] | undefined;
+  const density = positive(ctx.state.density_target);
+  if (typeof path !== 'string' || !existsSync(path)) return missing('rendered_path');
+  if (!safeAsset(path, ctx.workdir)) return { outcome: 'fail', note: '렌더 산출 경로가 workdir 밖이거나 영상 파일이 아니다' };
+  if (!Array.isArray(clips) || density === null) return missing('broll_clips or density_target');
+  const manifest = manifestPath(path);
+  if (!existsSync(manifest) || !safeManifest(manifest, ctx.workdir)) return { outcome: 'fail', note: '렌더 클립 기록이 없거나 workdir 밖이다' };
+  let recorded: unknown;
+  try { recorded = JSON.parse(readFileSync(manifest, 'utf8')); } catch { return { outcome: 'fail', note: '렌더 클립 기록을 읽을 수 없다' }; }
+  let currentClips: ReturnType<typeof clipRecord>;
+  try {
+    if (!clips.every((c) => c && typeof c.path === 'string' && Number.isFinite(c.start) && Number.isFinite(c.end))) {
+      return { outcome: 'fail', note: '렌더 클립 입력이 유효하지 않다' };
+    }
+    currentClips = clipRecord(clips);
+  } catch { return { outcome: 'fail', note: '렌더 클립 입력 파일을 확인할 수 없다' }; }
+  if (!recorded || typeof recorded !== 'object' || !('sha256' in recorded) || recorded.sha256 !== await fingerprint(path) ||
+    !('base' in recorded) || typeof recorded.base !== 'string' || !existsSync(recorded.base) ||
+    !('clips' in recorded) || !Array.isArray(recorded.clips) || recorded.clips.length === 0 ||
+    !recorded.clips.every((c: unknown) => c && typeof c === 'object' && 'path' in c && typeof c.path === 'string' &&
+      'start' in c && typeof c.start === 'number' && Number.isFinite(c.start) && c.start >= 0 &&
+      'end' in c && typeof c.end === 'number' && Number.isFinite(c.end) && c.end > c.start) ||
+    JSON.stringify(recorded.clips) !== JSON.stringify(currentClips) ||
+    ctx.state.rendered_clips !== recorded.clips.length) {
+    return { outcome: 'fail', note: '렌더 클립 개수·입력 또는 산출물 기록이 일치하지 않는다' };
+  }
+  const r = runner(ctx)('ffprobe', ['-v', 'error', '-show_entries', 'format=duration', '-of', 'default=noprint_wrappers=1:nokey=1', path], 30_000);
+  const seconds = Number(r.out.trim());
+  if (!r.ok || !Number.isFinite(seconds) || seconds <= 0) return { outcome: UNOBSERVED, note: '렌더 길이를 읽을 수 없다' };
+  if (recorded.clips.some((c: { start: number; end: number }) => c.start >= seconds || c.end <= 0)) {
+    return { outcome: 'fail', note: '렌더 길이 밖에 놓인 클립은 실제 영상에 나타나지 않는다' };
+  }
+  const base = recorded.base;
+  let actual = 0;
+  try {
+    for (const clip of recorded.clips as { path: string; start: number; end: number }[]) {
+      if (!existsSync(clip.path)) return { outcome: 'fail', note: '렌더 입력 클립이 없다' };
+      const offset = Math.min((clip.end - clip.start) / 2, (seconds - clip.start) / 2);
+      if (offset <= 0) continue;
+      const execute = runner(ctx);
+      const rendered = decodedFrame(path, clip.start + offset, execute, ctx.workdir);
+      const source = decodedFrame(clip.path, offset, execute, ctx.workdir);
+      const background = decodedFrame(base, clip.start + offset, execute, ctx.workdir);
+      if (!rendered || !source || !background) return { outcome: UNOBSERVED, note: '실제 컷 프레임을 디코딩할 수 없다' };
+      if (pixelDifference(rendered, source) <= 32 && pixelDifference(rendered, background) >= 8) actual++;
+    }
+  } catch (e) { return { outcome: UNOBSERVED, note: `컷 프레임 확인 실패: ${errorOf(e)}` }; }
+  const density_actual = actual * 60 / seconds;
+  const produced = { qc_seconds: seconds, density_actual, qc_pass: actual > 0 && density_actual >= density };
+  return { outcome: produced.qc_pass ? 'pass' : 'fail', produced, note: `확인된 BROLL ${actual}컷 / ${seconds.toFixed(2)}s · ${density_actual.toFixed(2)}/${density} clips/min` };
+};
+
+export const BROLL: Readonly<Record<string, Recipe>> = {
+  'broll-align-words': brollAlignWords,
+  'broll-density-plan': brollDensityPlan,
+  'broll-select-clips': brollSelectClips,
+  'broll-render': brollRender,
+  'broll-qc': brollQc,
+};

package/src/video-pipeline/walk-line.ts

@@ -12,6 +12,7 @@
  */
 import { readdirSync, readFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { BROLL } from './recipes/broll.js';
 import { CHARACTER } from './recipes/character.js';
 import { FILM } from './recipes/film.js';
 import { FREE_LINE } from './recipes/free-line.js';
@@ -21,7 +22,7 @@ import { VLOG } from './recipes/vlog.js';
 import { UNOBSERVED, type Recipe, type RecipeCtx } from './recipes/types.js';
 
 /** ⛔ 순서가 뜻이다 — 같은 이름이면 뒤가 이긴다. HYPERFRAMES 는 새 이름뿐이라 기존 키를 덮지 않는다. */
-export const ALL_RECIPES: Readonly<Record<string, Recipe>> = { ...UPSTREAM, ...FREE_LINE, ...VLOG, ...FILM, ...CHARACTER, ...HYPERFRAMES };
+export const ALL_RECIPES: Readonly<Record<string, Recipe>> = { ...UPSTREAM, ...FREE_LINE, ...VLOG, ...FILM, ...CHARACTER, ...HYPERFRAMES, ...BROLL };
 
 export interface GraphSpecLike {
   readonly graph_id: string;

package/src/views/scratch-image-size.ts

@@ -0,0 +1,10 @@
+// Terminal dimensions for the retained scratch-image viewer.
+export function scratchImageSize(
+  terminalRows: number,
+  terminalCols: number,
+): { rows: number; cols: number } {
+  return {
+    cols: Math.max(20, Math.min(60, Math.floor(terminalCols * 0.25))),
+    rows: Math.max(8, Math.min(28, Math.floor(terminalRows * 0.45))),
+  };
+}

package/src/voice/channel-adapters/pwa-voice-adapter.ts

@@ -509,24 +509,8 @@ async function createWiredSession(opts: WiredSessionOpts): Promise<PwaVoiceSessi
   };
 }
 
-// ── Env gate ───────────────────────────────────────────────────────
-
-/**
- * Default ON since Phase U closure (2026-05-05) — PWA is now the unified
- * frontend, so the voice WS endpoint is part of the standard daemon
- * surface area. Set `ELANOUS_PWA_VOICE=0` (or `false`/`off`/`no`) to opt
- * OUT, e.g. when running elanous serve on a node without OPENAI_API_KEY
- * just to avoid the streaming STT init log line.
- *
- * Pre-Phase-U: this returned false unless the env was explicitly set —
- * a Phase 7 (2026-04-30) opt-in gate while the PWA voice path was
- * experimental. That justification is gone now.
- */
-export function isPwaVoiceEnabled(): boolean {
-  const raw = process.env.ELANOUS_PWA_VOICE?.trim().toLowerCase();
-  if (raw === '0' || raw === 'false' || raw === 'off' || raw === 'no') return false;
-  return true;
-}
+// ── Env gate — 졸업(2026-09-26 설정 졸업 · 대표 «기본으로 켜진 것은 옵션으로 두지 않는다») ──
+// PWA 음성 WS 는 데몬 표준 표면이다. 옛 끄기 스위치 ELANOUS_PWA_VOICE 는 없앴다(streaming STT 가 없으면 nexus 가 어댑터를 안 만든다).
 
 // ── Frame protocol contract (for frontend reference) ───────────────
 

package/src/voice/channel-adapters/telegram-voice-adapter.ts

@@ -220,12 +220,7 @@ export function createTelegramVoiceAdapter(opts: TelegramVoiceAdapterOpts): Tele
   };
 }
 
-// ── Env / config helpers ───────────────────────────────────────────
-
-export function isTelegramVoiceEnabled(): boolean {
-  const raw = process.env.ELANOUS_TELEGRAM_VOICE?.trim().toLowerCase();
-  return raw === '1' || raw === 'true' || raw === 'on' || raw === 'yes';
-}
+// ── Reply mode normalization ───────────────────────────────────────
 
 export function normalizeTelegramVoiceReplyMode(v: unknown): TelegramVoiceReplyMode {
   return normalizeVoiceMessageReplyMode(v);

package/src/voice/voice-tts-singleton.ts

@@ -10,6 +10,7 @@
 // Provider resolution order (MEMORY pattern — user-config wins over env):
 //   user-config voice.tts.provider > env TTS_PROVIDER > default 'openai-tts'
 
+import { accessSync, constants, existsSync, statSync } from 'node:fs';
 import { debug } from '../debug/log.js';
 import { getUserConfig } from '../user-config.js';
 import {
@@ -29,21 +30,50 @@ function credentialResolves(name: string): boolean {
   return (process.env[name] ?? '').trim().length > 0;
 }
 
-/** Pure availability for a TTS id. Paid ids need their credential class;
- *  free ids never do. A thrown measurement is not "absent". */
-export function isTtsProviderUsableNow(id: TTSProviderId): boolean {
+interface TtsAvailabilityDeps {
+  which(name: string): string | null;
+  exists(path: string): boolean;
+  executable(path: string): boolean;
+  platform: NodeJS.Platform;
+}
+
+function isExecutableFile(path: string): boolean {
+  try {
+    if (!statSync(path).isFile()) return false;
+    accessSync(path, constants.X_OK);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const defaultTtsAvailabilityDeps: TtsAvailabilityDeps = {
+  which: (name) => Bun.which(name),
+  exists: existsSync,
+  executable: isExecutableFile,
+  platform: process.platform,
+};
+
+/** Paid ids need credentials; free ids need their local executables. */
+export function isTtsProviderUsableNow(
+  ...[id, deps = defaultTtsAvailabilityDeps]: [TTSProviderId, TtsAvailabilityDeps?]
+): boolean {
   switch (id) {
     case 'openai-tts':
       return credentialResolves('OPENAI_API_KEY');
     case 'elevenlabs-tts':
       return credentialResolves('ELEVENLABS_API_KEY');
-    case 'edge-tts':
+    case 'edge-tts': {
+      const binary = process.env.EDGE_TTS_BIN?.trim();
+      return (binary ? deps.exists(binary) && deps.executable(binary) : deps.which('edge-tts') !== null)
+        && deps.which('sox') !== null;
+    }
     case 'macos-say':
-      return true;
+      return deps.platform === 'darwin' && deps.which('say') !== null;
   }
 }
 
-function resolveProviderId(): TTSProviderId {
+function resolveProviderId(deps: TtsAvailabilityDeps = defaultTtsAvailabilityDeps): TTSProviderId {
   let configOverride: TTSProviderId | undefined;
   try {
     const cfg = getUserConfig();
@@ -68,12 +98,15 @@ function resolveProviderId(): TTSProviderId {
   if (!unpaidDefault) return chosen;
   let usable = true;
   try {
-    usable = isTtsProviderUsableNow(chosen);
+    usable = isTtsProviderUsableNow(chosen, deps);
   } catch {
     return chosen;
   }
   if (usable) return chosen;
-  return TTS_FREE_FALLBACK.find((id) => isTtsProviderUsableNow(id)) ?? chosen;
+  const free = TTS_FREE_FALLBACK.find((id) => isTtsProviderUsableNow(id, deps));
+  if (free) return free;
+  debug.log('voice.tts', 'no-usable-provider', { tried: [chosen, ...TTS_FREE_FALLBACK] });
+  return chosen;
 }
 
 /** config화 (2026-07-12) — `voice.tts.voiceId` 를 provider 생성자에
@@ -119,6 +152,11 @@ export function resolveDaemonTtsProviderIdForTesting(): TTSProviderId {
   return resolveProviderId();
 }
 
+/** Resolve with a fake local executable probe without touching the host PATH. */
+export function resolveDaemonTtsProviderIdWithDepsForTesting(deps: TtsAvailabilityDeps): TTSProviderId {
+  return resolveProviderId(deps);
+}
+
 export async function initDaemonTtsProvider(): Promise<TTSProvider | null> {
   if (cached) return cached;
   if (initInFlight) return initInFlight;

package/src/web-push/vapid-keys.ts

@@ -37,7 +37,7 @@ export interface VapidKeyPair {
   subject: string;
 }
 
-const DEFAULT_SUBJECT = 'https://github.com/ElanvitalAI/monad';
+const DEFAULT_SUBJECT = 'https://github.com/ElanvitalAI/elanous';
 
 /** Lazy-loaded singleton — daemon boot path calls this once and
  *  holds the result for the lifetime of the process. */