elanous 0.2.5 → 0.2.6

package/src/task-orchestrator/surfaces/pod-command-job.ts

@@ -11,6 +11,7 @@ import { getUserConfig } from '../../user-config.js';
 import { debug } from '../../debug/log.js';
 import { effectiveInstanceRoot } from '../../instance/resolve.js';
 import { collectPodArtifacts } from './pod-artifact-return.js';
+import { podBunCacheVolume } from './pod-bun-cache.js';
 import { type PodPoolMember, PodPoolScheduler, resolvePodPoolSpec, parsePodPool, checkPodPool, syncPoolImages, type PoolKubectl } from './pod-pool.js';
 import { readSkillEnvFiles } from './pod-skills.js';
 import { podSourceScript, type PodSource } from './pod-source-receive.js';
@@ -76,6 +77,7 @@ export interface PodCommandJobInput {
   /** 저장소를 clone 한다 — 비공개 저장소라 GitHub 토큰이 Secret 으로 간다(명시 opt-in). 기본은 clone 없이 `~/work` 에서 이미지의 `elanous` 로 돈다. */
   clone?: boolean;
   hostMirror?: string;
+  bunCache?: string;
   /** 컨테이너 메모리 한도(기본 16Gi) — 게이트가 파일 하나 격리 Job 에 올린다. */
   memoryLimit?: string;
   source?: PodSource;
@@ -94,6 +96,7 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
     if (!/^[A-Za-z0-9][A-Za-z0-9._-]*$/u.test(name)) throw new Error(`pod command skill name rejected: ${name}`);
   }
   const grok = o.llm === 'grok';
+  const bunCache = o.bunCache ? podBunCacheVolume(o.bunCache) : undefined;
   const quotedArgs = o.command.map(bashSingleQuote).join(' ');
   const credLines = [
     ...(grok ? ['mkdir -p ~/.grok && install -m 600 /creds/grok-auth.json ~/.grok/auth.json'] : []),
@@ -108,6 +111,7 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
     ...(o.clone
       ? ['export GH_TOKEN="$(cat /creds/gh-token)" && gh auth setup-git', podSourceScript(o.source ?? { kind: 'default' }, o.repoUrl)]
       : ['mkdir -p ~/work && cd ~/work']),
+    ...(bunCache ? [bunCache.shellPrefix] : []),
     `set -- ${quotedArgs}`,
     '"$@"',
     'rc=$?',
@@ -138,14 +142,16 @@ export function podCommandJobManifest(o: PodCommandJobInput): Record<string, unk
               { name: 'ELANOUS_SUBSTRATE', value: 'pod' },
               { name: 'ELANOUS_POD_NAME', valueFrom: { fieldRef: { fieldPath: 'metadata.name' } } },
             ],
-            ...(secretKeys || o.hostMirror ? { volumeMounts: [
+            ...(secretKeys || o.hostMirror || bunCache ? { volumeMounts: [
               ...(secretKeys ? [{ name: 'creds', mountPath: '/creds', readOnly: true }] : []),
               ...(o.hostMirror ? [{ name: 'host-mirror', mountPath: '/host-mirror', readOnly: true }] : []),
+              ...(bunCache ? [bunCache.volumeMount] : []),
             ] } : {}),
           }],
-          ...(secretKeys || o.hostMirror ? { volumes: [
+          ...(secretKeys || o.hostMirror || bunCache ? { volumes: [
             ...(secretKeys ? [{ name: 'creds', secret: { secretName: `${o.name}-creds`, defaultMode: 0o400 } }] : []),
             ...(o.hostMirror ? [{ name: 'host-mirror', hostPath: { path: o.hostMirror, type: 'Directory' } }] : []),
+            ...(bunCache ? [bunCache.volume] : []),
           ] } : {}),
         },
       },
@@ -201,6 +207,7 @@ export interface RunPodCommandOptions {
   llm?: 'grok';
   clone?: boolean;
   hostMirror?: string;
+  bunCache?: string;
   /** 컨테이너 메모리 한도(기본 16Gi). */
   memoryLimit?: string;
   source?: PodSource;
@@ -263,6 +270,8 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
   const hostMirror = (options.hostMirror ?? env.ELANOUS_POD_HOST_MIRROR
     ?? (options.configHostMirror ?? (() => getUserConfig().pod?.hostMirror))())?.trim() || undefined;
   if (hostMirror && !isAbsolute(hostMirror)) throw new Error('pod.hostMirror must be an absolute directory path');
+  const bunCache = options.bunCache?.trim() || undefined;
+  if (bunCache && !isAbsolute(bunCache)) throw new Error('pod.bunCache must be an absolute directory path');
 
   let member: PodPoolMember | null = null;
   let pool = options.poolScheduler;
@@ -328,7 +337,7 @@ export async function runPodCommand(options: RunPodCommandOptions): Promise<PodC
       name, namespace, image: member?.imageRef ?? image,
       ...(member?.imageRef ? { imagePullPolicy: 'IfNotPresent' as const } : {}),
       repoUrl, command, skills, ...(llm ? { llm } : {}), ...(options.clone ? { clone: true } : {}),
-      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(options.memoryLimit ? { memoryLimit: options.memoryLimit } : {}), deadlineSeconds,
+      ...(options.source ? { source: options.source } : {}), ...(hostMirror ? { hostMirror } : {}), ...(bunCache ? { bunCache } : {}), ...(options.memoryLimit ? { memoryLimit: options.memoryLimit } : {}), deadlineSeconds,
       ...(options.runId ? { runId: options.runId } : {}),
     });
     kubectl(['-n', namespace, 'delete', 'job', name, '--ignore-not-found']);

package/src/telegram.ts

@@ -67,6 +67,8 @@ import { runUrlRoute } from './skills/url-route-exec.js';
 import { recordRoutedLinkAbsorbed } from './intake-plane/link-ledger.js';
 import { classifyFrontInput } from './intake-plane/front-classifier.js';
 import { effectiveInstanceRoot } from './instance/resolve.js';
+import { getElanousConfigDir } from './elanous-config-dir.js';
+import { defaultFieldEvent, FieldUploadError, parseFieldCaption, resolveFieldMime, saveFieldMedia } from './field/field-media.js';
 
 export type TgAttachmentKind = 'photo' | 'voice' | 'audio' | 'document';
 
@@ -105,6 +107,10 @@ export interface TgIncoming {
   botId?: string;
   /** 답장 대상 메시지의 텍스트(force_reply 정정 가로채기용). parseUpdate 가 채운다. */
   replyToText?: string;
+  /** 앨범(media group) id — `#현장` 캡션은 앨범의 첫 항목에만 붙으므로 나머지를 같은 행사로 묶는 데 쓴다. */
+  mediaGroupId?: string;
+  /** 영상 — `#현장` 저장 전용. `attachments` 에 넣지 않는다(LLM 경로의 동작을 안 바꾸려고). */
+  video?: TgIncomingAttachment;
 }
 
 /** Streaming surface passed to the message handler. The handler can
@@ -200,6 +206,10 @@ export interface TelegramBotOpts {
    *  independently of the LLM chat path. Best-effort: errors are
    *  swallowed by the caller — never blocks chat reply. */
   onTriggerTap?: (event: TgTriggerEvent) => void | Promise<void>;
+  /** `#현장` 기본 행사 — 없으면 `slashContext.userConfig.telegram.fieldDefaultEvent` · 그것도 없으면 `field-<로컬 날짜>`. */
+  fieldDefaultEvent?: string;
+  /** 시험 seam — 현장 폴더 뿌리(기본 `getElanousConfigDir()`). */
+  fieldRootDir?: () => string;
 }
 
 /** Surface-unification v2 (FU-2) — Telegram trigger event passed to
@@ -314,6 +324,13 @@ export class TelegramBot {
    *  the bot under Telegram's ~30/sec global cap without blocking
    *  further if load is bursty but average-safe. */
   private readonly globalWindow: number[] = [];
+  private readonly fieldDefaultEventOpt?: string;
+  private readonly fieldRootDir: () => string;
+  /** 앨범 id → `#현장` 행사 · 답장 디바운스. 태그된 앨범만 들어온다. */
+  private readonly fieldGroups = new Map<string, {
+    event: string; at: number; chatId: number; threadId?: number; replyTo: number; count: number;
+    timer?: ReturnType<typeof setTimeout>;
+  }>();
 
   constructor(opts: TelegramBotOpts) {
     if (!opts.token) throw new Error('TelegramBot: token required');
@@ -340,6 +357,8 @@ export class TelegramBot {
     this.slashCommands = opts.slashCommands ?? [];
     this.slashContext = opts.slashContext;
     this.voiceAdapter = opts.voiceAdapter;
+    this.fieldDefaultEventOpt = opts.fieldDefaultEvent;
+    this.fieldRootDir = opts.fieldRootDir ?? getElanousConfigDir;
     if (opts.onTriggerTap) {
       // Assign through `as unknown` to bypass `readonly` + private —
       // the tap is set once at construction and never reassigned.
@@ -1347,11 +1366,82 @@ export class TelegramBot {
     return false;
   }
 
+  /** `#현장` 캡션 사진·영상(이미지·영상 문서 포함)을 현장 폴더에 저장하고 한 줄로 답한다.
+   *  처리했으면 true. 저장 규칙은 HTTP 입구와 같은 `saveFieldMedia` 다. */
+  private async tryHandleFieldUpload(ctx: TgIncoming): Promise<boolean> {
+    const media = [
+      ...ctx.attachments.filter((a) => a.kind === 'photo'
+        || (a.kind === 'document' && resolveFieldMime(a.mimeType, a.fileName ?? '') !== null)),
+      ...(ctx.video ? [ctx.video] : []),
+    ];
+    if (media.length === 0) return false;
+    const now = this.nowImpl();
+    for (const [id, g] of this.fieldGroups) if (now - g.at > 10 * 60_000 && !g.timer) this.fieldGroups.delete(id);
+    const tag = parseFieldCaption(ctx.text);
+    const group = ctx.mediaGroupId ? this.fieldGroups.get(ctx.mediaGroupId) : undefined;
+    if (!tag && !group) return false;
+    const event = tag
+      ? tag.event ?? defaultFieldEvent(
+        this.fieldDefaultEventOpt ?? this.slashContext?.userConfig?.telegram?.fieldDefaultEvent, new Date(now))
+      : group!.event;
+
+    let count: number | null = null;
+    let failure: string | null = null;
+    try {
+      const inputs = [];
+      for (const att of media) {
+        const downloaded = await this.downloadFile(att.fileId);
+        try {
+          inputs.push({
+            originalName: att.fileName ?? downloaded.fileName ?? 'media',
+            mimeType: att.mimeType ?? (att.kind === 'photo' ? 'image/jpeg' : undefined),
+            bytes: new Uint8Array(readFileSync(downloaded.localPath)),
+          });
+        } finally {
+          try { unlinkSync(downloaded.localPath); } catch { /* 이미 없음 */ }
+        }
+      }
+      // 글(자막)은 캡션이 달린 항목에만 있다 — 앨범이면 첫 장에만 붙는다(MK 2026-09-30).
+      count = saveFieldMedia(inputs, { rootDir: this.fieldRootDir(), event, device: 'telegram', ...(tag?.text ? { caption: tag.text } : {}) }).count;
+      debug.log('field.upload', 'saved', { surface: 'telegram', files: inputs.length, count, album: !!ctx.mediaGroupId });
+    } catch (err) {
+      failure = err instanceof FieldUploadError ? err.code : 'download-failed';
+      debug.log('field.upload', 'refused', { surface: 'telegram', reason: failure });
+    }
+
+    if (failure !== null) {
+      await this.sendMessage(ctx.chatId, `현장 저장 실패 · ${event} · ${failure}`, { replyTo: ctx.messageId, threadId: ctx.threadId });
+      return true;
+    }
+    const line = (n: number) => `현장 폴더에 저장 · ${event} · 지금 ${n}장`;
+    if (!ctx.mediaGroupId) {
+      await this.sendMessage(ctx.chatId, line(count!), { replyTo: ctx.messageId, threadId: ctx.threadId });
+      return true;
+    }
+    // 앨범은 항목마다 답하지 않는다 — 마지막 항목 뒤 한 번(디바운스)만 최신 수로 답한다.
+    const entry = group ?? { event, at: now, chatId: ctx.chatId, threadId: ctx.threadId, replyTo: ctx.messageId, count: 0 };
+    entry.at = now;
+    entry.count = count!;
+    if (entry.timer) clearTimeout(entry.timer);
+    entry.timer = setTimeout(() => {
+      entry.timer = undefined;
+      void this.sendMessage(entry.chatId, line(entry.count), { replyTo: entry.replyTo, threadId: entry.threadId })
+        .catch((e) => this.log(`field reply failed: ${e instanceof Error ? e.message : String(e)}`));
+    }, 1500);
+    (entry.timer as { unref?: () => void }).unref?.();
+    this.fieldGroups.set(ctx.mediaGroupId, entry);
+    return true;
+  }
+
   private async handleIncoming(ctx: TgIncoming): Promise<void> {
     if (!this.isOwnerAllowed(ctx.userId)) {
       await this.refuseMessage(ctx);
       return;
     }
+    // 현장 업로드 — `#현장` 캡션(또는 태그된 앨범의 나머지)의 사진·영상은 LLM 대신 현장 폴더로.
+    if (await this.tryHandleFieldUpload(ctx)) return;
+    // 영상은 `#현장` 저장 전용으로만 파싱한다 — 그 밖의 영상은 종전처럼 무시한다.
+    if (ctx.video && ctx.attachments.length === 0) return;
     // Cascade-zyu U2 — capture utterance intent at update ingress.
     try {
       const { userIntentLogger } = await import('./user-intent/index.js');
@@ -2069,6 +2159,7 @@ export class TelegramBot {
 interface PhotoSize { file_id: string; file_size?: number; width: number; height: number }
 interface VoiceLike { file_id: string; file_size?: number; mime_type?: string; duration?: number }
 interface DocumentLike { file_id: string; file_size?: number; mime_type?: string; file_name?: string }
+interface VideoLike { file_id: string; file_size?: number; mime_type?: string; file_name?: string; duration?: number }
 
 interface RawUpdate {
   update_id: number;
@@ -2083,6 +2174,8 @@ interface RawUpdate {
     voice?: VoiceLike;
     audio?: VoiceLike;
     document?: DocumentLike;
+    video?: VideoLike;
+    media_group_id?: string;
     reply_to_message?: { text?: string; message_id?: number };
   };
   callback_query?: {
@@ -2175,8 +2268,20 @@ export function parseUpdate(u: RawUpdate): TgIncoming | null {
     });
   }
 
+  // 영상은 `#현장` 저장 전용 — 태그된 캡션이거나 앨범 항목일 때만 싣는다(그 밖의 영상은 종전처럼 무시).
+  const video = m.video && (parseFieldCaption(m.caption) || m.media_group_id)
+    ? {
+        kind: 'document' as const,
+        fileId: m.video.file_id,
+        fileSize: m.video.file_size,
+        mimeType: m.video.mime_type ?? 'video/mp4',
+        fileName: m.video.file_name,
+        duration: m.video.duration,
+      }
+    : undefined;
+
   // Skip updates with zero signal: no text AND no attachments.
-  if (typeof m.text !== 'string' && attachments.length === 0) return null;
+  if (typeof m.text !== 'string' && attachments.length === 0 && !video) return null;
 
   const isDm = m.chat.type === 'private';
   return {
@@ -2191,6 +2296,8 @@ export function parseUpdate(u: RawUpdate): TgIncoming | null {
     isGroup: !isDm,
     attachments,
     ...(m.reply_to_message?.text ? { replyToText: m.reply_to_message.text } : {}),
+    ...(m.media_group_id ? { mediaGroupId: m.media_group_id } : {}),
+    ...(video ? { video } : {}),
   };
 }
 

package/src/user-config.ts

@@ -833,6 +833,8 @@ export interface TelegramConfig {
   /** 발송 목적(kind) → 채널 역할. 명시 `channels` 가 있을 때만 쓴다 — 표에 없는 kind 는 옛 `reportChannel` 로 간다.
    *  기본표는 `DEFAULT_KIND_ROLES`(telegram-report.ts) · 여기 값이 덮어쓴다. */
   kindRoles?: Record<string, string>;
+  /** `#현장` 캡션에 행사 슬러그가 없을 때 쓸 기본 행사(예: `marketers-night-2026-10`). 없으면 `field-<로컬 날짜>`. */
+  fieldDefaultEvent?: string;
 }
 
 const TELEGRAM_DEFAULTS: TelegramConfig = { enabled: false, allowedUsers: [] };
@@ -4393,6 +4395,7 @@ export function buildUserConfig(path: string = defaultPath()): UserConfig {
       testChannel: normalizeTestChannel(tg.testChannel),
       ...(tg.poller === 'standalone' || tg.poller === 'nexus' ? { poller: tg.poller } : {}),
       ...(normalizeKindRoles(tg.kindRoles) ? { kindRoles: normalizeKindRoles(tg.kindRoles)! } : {}),
+      ...(str(tg.fieldDefaultEvent) ? { fieldDefaultEvent: str(tg.fieldDefaultEvent)! } : {}),
     },
     discord: {
       enabled: dc.enabled === true,
@@ -5565,6 +5568,7 @@ export function saveUserConfig(
       // ★ 2026-09-25: `poller`(T1 분리 스위치)가 파서엔 있고 이 whitelist 에 없어 `config set telegram.poller` 가
       //   「직렬화 드롭」으로 조용히 사라졌다 — 운영 전환 스위치를 켤 방법이 없었다(07-22 botUsername 과 같은 모양).
       poller: cfg.telegram.poller,
+      fieldDefaultEvent: cfg.telegram.fieldDefaultEvent,
     }),
     discord: stripUndef({
       enabled: cfg.discord.enabled,

package/src/version/packed-revision.json

@@ -1 +1 @@
-{"commit":"e491ebfd1661520b780aff439e71baa26895ab53"}
+{"commit":"65a4c7230c60a536b0f0f0428322c8ddcbcac752"}

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

@@ -0,0 +1,213 @@
+import { spawnSync } from 'node:child_process';
+import { existsSync, lstatSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import type { RunResult } from './ffmpeg.js';
+import { UNOBSERVED, type Recipe, type RecipeCtx, type RecipeResult } from './types.js';
+
+type CommandRunner = (bin: string, args: readonly string[], timeoutMs: number, cwd?: string) => RunResult;
+interface ExplainerDeps { readonly run?: CommandRunner; readonly engineDir?: string }
+
+const ENGINE = resolve(import.meta.dir, '../../../skills/explainer-video/engine');
+const ENGINE_MS = 600_000;
+const QC_MS = 180_000;
+
+function inside(root: string, candidate: string): boolean {
+  const rel = relative(root, candidate);
+  return rel === '' || (rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel));
+}
+
+// Resolve existing ancestors as well: an output directory may be a symlink before the engine writes into it.
+function safeOutput(root: string, candidate: string): boolean {
+  const base = realpathSync(root);
+  if (!inside(resolve(root), resolve(candidate))) return false;
+  // Walk up to the deepest component that exists as a directory entry (lstat, not existsSync):
+  // a broken symlink is «there» and must be judged, not skipped as missing.
+  let path = resolve(candidate);
+  for (;;) {
+    let isLink: boolean;
+    try { isLink = lstatSync(path).isSymbolicLink(); } catch {
+      const parent = dirname(path);
+      if (parent === path) return false;
+      path = parent;
+      continue;
+    }
+    if (isLink && !existsSync(path)) return false; // broken link — its target could be created outside the project
+    return inside(base, realpathSync(path));
+  }
+}
+
+function finish(ctx: RecipeCtx, name: string, result: RecipeResult): RecipeResult {
+  ctx.log(`explainer.${name}`, { outcome: result.outcome, ...result.produced, note: result.note });
+  return result;
+}
+
+function scriptPath(ctx: RecipeCtx): string | null {
+  const value = ctx.state.script_path;
+  return typeof value === 'string' && value.trim() ? resolve(value) : null;
+}
+
+function enginePath(deps: ExplainerDeps, file: string): string | null {
+  const path = resolve(deps.engineDir ?? ENGINE, file);
+  return existsSync(path) ? path : null;
+}
+
+function runner(deps: ExplainerDeps, ctx: RecipeCtx): CommandRunner {
+  if (deps.run) return deps.run;
+  return (bin, args, timeoutMs, cwd) => {
+    const r = spawnSync(bin, [...args], {
+      cwd, timeout: timeoutMs, encoding: 'utf8',
+      env: { ...process.env, EXPLAINER_CACHE: resolve(ctx.workdir, 'explainer-cache') },
+    });
+    return { ok: r.status === 0, code: r.status, signal: r.signal ?? null,
+      err: (r.stderr ?? r.error?.message ?? '').trim(), out: (r.stdout ?? '').trim() };
+  };
+}
+
+function unavailable(r: RunResult): boolean {
+  return r.signal === null && r.code === null && !r.ok;
+}
+
+function keys(script: unknown): string[] | null {
+  if (!script || typeof script !== 'object') return null;
+  const s = script as { intro?: { beats?: unknown }; chapters?: unknown; outro?: { beats?: unknown } };
+  if (!Array.isArray(s.intro?.beats) || !Array.isArray(s.chapters) || !Array.isArray(s.outro?.beats)) return null;
+  const chapters = s.chapters as { beats?: unknown }[];
+  if (!chapters.every((c) => c && Array.isArray(c.beats))) return null;
+  return [
+    ...s.intro.beats.map((_, i) => `i-${i}`),
+    ...chapters.flatMap((c, ci) => (c.beats as unknown[]).map((_, i) => `c${ci + 1}-${i}`)),
+    ...s.outro.beats.map((_, i) => `o-${i}`),
+  ];
+}
+
+export function explainerScript(): Recipe {
+  return async (ctx) => {
+    const path = scriptPath(ctx);
+    if (!path) return finish(ctx, 'script', { outcome: 'no-facts', note: 'script_path 가 state 에 없다 — 대본 저작이 필요하다' });
+    if (!existsSync(path)) return finish(ctx, 'script', { outcome: 'no-facts', note: `대본이 없다: ${path}` });
+    let script: unknown;
+    try { script = JSON.parse(readFileSync(path, 'utf8')); }
+    catch (e) { return finish(ctx, 'script', { outcome: UNOBSERVED, note: `대본 읽기 실패: ${String(e)}` }); }
+    const chapters = (script as { chapters?: unknown } | null)?.chapters;
+    const beatKeys = keys(script);
+    const voiced = (beat: unknown): boolean => beat !== null && typeof beat === 'object' &&
+      typeof (beat as { vo?: unknown }).vo === 'string' && (beat as { vo: string }).vo.trim().length > 0;
+    if (!beatKeys?.length || !Array.isArray(chapters) || chapters.length === 0 ||
+        !chapters.some((chapter: { beats: unknown[] }) => chapter.beats.some(voiced)) ||
+        ![...(script as { intro: { beats: unknown[] } }).intro.beats,
+          ...chapters.flatMap((chapter: { beats: unknown[] }) => chapter.beats),
+          ...(script as { outro: { beats: unknown[] } }).outro.beats].every(voiced)) {
+      return finish(ctx, 'script', { outcome: 'no-facts', note: 'intro.beats · chapters[] · outro.beats 에 내용이 없거나 구조가 없다' });
+    }
+    return finish(ctx, 'script', { outcome: 'ok', produced: { script_path: path } });
+  };
+}
+
+export function explainerVo(deps: ExplainerDeps = {}): Recipe {
+  return async (ctx) => {
+    const path = scriptPath(ctx);
+    if (!path || !existsSync(path)) return finish(ctx, 'vo', { outcome: UNOBSERVED, note: 'script_path 를 못 읽는다' });
+    const engine = enginePath(deps, 'vo.ts');
+    if (!engine) return finish(ctx, 'vo', { outcome: UNOBSERVED, note: 'skills/explainer-video/engine/vo.ts 가 없다' });
+    const project = dirname(path);
+    const voDir = resolve(project, 'source/vo');
+    try {
+      const beatKeys = keys(JSON.parse(readFileSync(path, 'utf8')));
+      if (!beatKeys?.length) return finish(ctx, 'vo', { outcome: UNOBSERVED, note: '대본의 VO beat 를 못 읽었다' });
+      const outputs = beatKeys.flatMap((key) => [
+        resolve(voDir, `${key}.mp3`), resolve(voDir, `${key}.json`),
+        resolve(voDir, `${key}.tmp.aiff`), resolve(voDir, `${key}.tmp.mp3`),
+      ]);
+      if (![voDir, ...outputs].every((p) => safeOutput(project, p))) {
+        return finish(ctx, 'vo', { outcome: UNOBSERVED, note: 'VO 출력이 대본 폴더 밖을 가리킨다' });
+      }
+    } catch (e) { return finish(ctx, 'vo', { outcome: UNOBSERVED, note: `VO 경로 확인 실패: ${String(e)}` }); }
+    let r: RunResult;
+    try { r = runner(deps, ctx)('bun', [engine, path], ENGINE_MS, project); }
+    catch (e) { return finish(ctx, 'vo', { outcome: UNOBSERVED, note: `bun vo.ts 를 못 불렀다: ${String(e)}` }); }
+    if (unavailable(r)) return finish(ctx, 'vo', { outcome: UNOBSERVED, note: `bun vo.ts 를 못 불렀다(code=${r.code} signal=${r.signal}): ${r.err}` });
+    if (!r.ok) return finish(ctx, 'vo', { outcome: 'error', note: `VO 엔진 실패: ${r.err.slice(0, 240)}` });
+    try {
+      const script = JSON.parse(readFileSync(path, 'utf8')) as unknown;
+      const beatKeys = keys(script);
+      if (!beatKeys?.length) throw new Error('대본에 VO beat 가 없다');
+      let seconds = 0;
+      for (const key of beatKeys) {
+        const audio = resolve(voDir, `${key}.mp3`);
+        const alignment = resolve(voDir, `${key}.json`);
+        if (!safeOutput(project, audio) || !safeOutput(project, alignment) || !existsSync(audio)) throw new Error(`${key} VO 파일이 없다`);
+        const j = JSON.parse(readFileSync(alignment, 'utf8')) as { alignment?: { character_end_times_seconds?: unknown } };
+        const ends = j.alignment?.character_end_times_seconds;
+        if (!Array.isArray(ends) || ends.length === 0 || !Number.isFinite(ends.at(-1)) || ends.at(-1) <= 0) throw new Error(`${key} 끝 시각을 못 읽었다`);
+        seconds += ends.at(-1) as number;
+      }
+      return finish(ctx, 'vo', { outcome: 'ok', produced: { vo_dir: voDir, narration_seconds: seconds } });
+    } catch (e) { return finish(ctx, 'vo', { outcome: UNOBSERVED, note: `VO 산출을 못 쟀다: ${String(e)}` }); }
+  };
+}
+
+export function explainerBuild(deps: ExplainerDeps = {}): Recipe {
+  return async (ctx) => {
+    const path = scriptPath(ctx);
+    if (!path || !existsSync(path)) return finish(ctx, 'build', { outcome: UNOBSERVED, note: 'script_path 를 못 읽는다' });
+    const engine = enginePath(deps, 'build.mjs');
+    if (!engine) return finish(ctx, 'build', { outcome: UNOBSERVED, note: 'skills/explainer-video/engine/build.mjs 가 없다' });
+    const project = dirname(path);
+    const hf = resolve(project, 'hf');
+    const timeline = resolve(project, 'timeline.json');
+    try {
+      mkdirSync(ctx.workdir, { recursive: true });
+      if (![hf, resolve(hf, 'assets'), resolve(hf, 'assets/fonts'), resolve(hf, 'assets/vo'), timeline].every((p) => safeOutput(project, p))
+        || !safeOutput(ctx.workdir, resolve(ctx.workdir, 'explainer-cache'))) {
+        return finish(ctx, 'build', { outcome: UNOBSERVED, note: '빌드 출력/캐시가 허용된 폴더 밖을 가리킨다' });
+      }
+    } catch (e) { return finish(ctx, 'build', { outcome: UNOBSERVED, note: `빌드 경로 확인 실패: ${String(e)}` }); }
+    let r: RunResult;
+    try { r = runner(deps, ctx)('node', [engine, path], ENGINE_MS, project); }
+    catch (e) { return finish(ctx, 'build', { outcome: UNOBSERVED, note: `node build.mjs 를 못 불렀다: ${String(e)}` }); }
+    if (unavailable(r)) return finish(ctx, 'build', { outcome: UNOBSERVED, note: `node build.mjs 를 못 불렀다(code=${r.code} signal=${r.signal}): ${r.err}` });
+    if (!r.ok) {
+      const badScript = /unknown diagram|DIAGRAMS\[dia\] is not a function|(?:invalid|missing|unsupported) (?:script|diagram|beat|chapter)/i.test(r.err);
+      return finish(ctx, 'build', { outcome: badScript ? 'bad-script' : 'error', note: `빌드 실패: ${r.err.slice(0, 240)}` });
+    }
+    try {
+      if (![resolve(hf, 'index.html'), timeline].every((p) => safeOutput(project, p) && existsSync(p))) {
+        return finish(ctx, 'build', { outcome: UNOBSERVED, note: '빌드가 hf/index.html 또는 timeline.json 을 내지 않았다' });
+      }
+    } catch (e) { return finish(ctx, 'build', { outcome: UNOBSERVED, note: `빌드 산출 확인 실패: ${String(e)}` }); }
+    return finish(ctx, 'build', { outcome: 'ok', produced: { hyperframes_project: hf, timeline_path: timeline } });
+  };
+}
+
+export function explainerQc(deps: ExplainerDeps = {}): Recipe {
+  return async (ctx) => {
+    const path = ctx.state.hf_render_path;
+    if (typeof path !== 'string' || !path || !existsSync(path)) {
+      return finish(ctx, 'qc', { outcome: UNOBSERVED, note: 'hf_render_path 를 못 읽는다' });
+    }
+    let r: RunResult;
+    try {
+      r = runner(deps, ctx)('ffmpeg', ['-hide_banner', '-nostats', '-i', resolve(path),
+        '-af', 'loudnorm=print_format=json', '-f', 'null', '-'], QC_MS, ctx.workdir);
+    } catch (e) { return finish(ctx, 'qc', { outcome: UNOBSERVED, note: `ffmpeg 를 못 불렀다: ${String(e)}` }); }
+    if (!r.ok) return finish(ctx, 'qc', { outcome: UNOBSERVED, note: `ffmpeg 음량 측정 실패(code=${r.code} signal=${r.signal}): ${r.err.slice(0, 240)}` });
+    const block = [...`${r.err}\n${r.out}`.matchAll(/\{[^{}]*"input_i"[^{}]*"input_tp"[^{}]*\}/g)].at(-1)?.[0];
+    try {
+      if (!block) throw new Error('loudnorm JSON 이 없다');
+      const j = JSON.parse(block) as { input_i?: unknown; input_tp?: unknown };
+      const loudness = Number(j.input_i);
+      const peak = Number(j.input_tp);
+      if (j.input_i == null || j.input_tp == null || !Number.isFinite(loudness) || !Number.isFinite(peak)) throw new Error('통합 음량/트루 피크가 비수다');
+      const produced = { loudness_lufs: loudness, true_peak_db: peak };
+      const outcome = loudness >= -16 && loudness <= -12 && peak <= -1 ? 'pass' : 'loudness';
+      return finish(ctx, 'qc', { outcome, produced, note: `${loudness} LUFS · ${peak} dBTP` });
+    } catch (e) { return finish(ctx, 'qc', { outcome: UNOBSERVED, note: `loudnorm 결과를 못 읽었다: ${String(e)}` }); }
+  };
+}
+
+export const EXPLAINER: Readonly<Record<string, Recipe>> = {
+  'explainer-script': explainerScript(),
+  'explainer-vo': explainerVo(),
+  'explainer-build': explainerBuild(),
+  'explainer-qc': explainerQc(),
+};

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

@@ -14,6 +14,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 { EXPLAINER } from './recipes/explainer.js';
 import { FILM } from './recipes/film.js';
 import { FREE_LINE } from './recipes/free-line.js';
 import { HYPERFRAMES } from './recipes/hyperframes.js';
@@ -21,8 +22,8 @@ import { UPSTREAM } from './recipes/upstream.js';
 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, ...BROLL };
+/** ⛔ 순서가 뜻이다 — 같은 이름이면 뒤가 이긴다. HYPERFRAMES · EXPLAINER 는 기존 키를 덮지 않는다. */
+export const ALL_RECIPES: Readonly<Record<string, Recipe>> = { ...UPSTREAM, ...FREE_LINE, ...VLOG, ...FILM, ...CHARACTER, ...HYPERFRAMES, ...BROLL, ...EXPLAINER };
 
 export interface GraphSpecLike {
   readonly graph_id: string;