elanous 0.2.6 → 0.2.7

package/src/exec-requests/runner.ts

@@ -0,0 +1,338 @@
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { basename, dirname, isAbsolute, join, resolve, sep } from 'node:path';
+import { createHash, randomUUID } from 'node:crypto';
+import { debug } from '../debug/log.js';
+import { effectiveInstanceRoot } from '../instance/resolve.js';
+import { lastJsonObject, runGraph, type GraphRunState } from '../graph-runner/runner.js';
+import { installedGraphs, planExecRequest, type ExecPlanItem, type InstalledGraph } from './planner.js';
+import { ExecRequestStore, type ExecRequest, type ExecResult, type ExecSeat } from './store.js';
+
+export interface ExecRunnerDeps {
+  store?: ExecRequestStore;
+  graphs?: () => Promise<InstalledGraph[]>;
+  plan?: (text: string) => Promise<ExecPlanItem[]>;
+  run?: typeof runGraph;
+  root?: string;
+}
+
+const active = new Set<string>();
+const SEGMENT = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+const kinds: Record<string, ExecResult['kind']> = {
+  '.pdf': 'pdf', '.mp4': 'video', '.mov': 'video', '.webm': 'video', '.png': 'image', '.jpg': 'image',
+  '.jpeg': 'image', '.webp': 'image', '.md': 'report', '.txt': 'text',
+};
+
+function safeFile(path: string, root: string, graphId: string, runId: string): string | null {
+  if (!SEGMENT.test(graphId) || !SEGMENT.test(runId)) return null;
+  // Only run-prefixed files or the run artifact directory, never a sibling run's output.
+  const allowed = join(root, 'graph-runs', graphId);
+  const candidate = isAbsolute(path) ? path : resolve(allowed, path);
+  try {
+    const real = realpathSync(candidate);
+    const base = realpathSync(allowed);
+    const runPrefix = `${runId}.json.`;
+    const local = dirname(real) === base && basename(real).startsWith(runPrefix)
+      && !/\.(?:decision\.json|tmp)$/.test(real);
+    const artifactsDir = join(allowed, `${runId}.json.artifacts`);
+    const realArtifactsDir = existsSync(artifactsDir) && statSync(artifactsDir).isDirectory()
+      ? realpathSync(artifactsDir) : null;
+    const inRunDirectory = realArtifactsDir === join(base, `${runId}.json.artifacts`)
+      && real.startsWith(`${realArtifactsDir}${sep}`);
+    if ((!local && !inRunDirectory) || !statSync(real).isFile()) return null;
+    return real;
+  } catch { return null; }
+}
+
+function publicLink(value: unknown): string | null {
+  if (typeof value !== 'string') return null;
+  try {
+    const url = new URL(value);
+    return (url.protocol === 'https:' || url.protocol === 'http:') && url.hostname && !url.username && !url.password ? value : null;
+  } catch { return null; }
+}
+
+function fileName(path: string, runId: string): string {
+  const digest = createHash('sha256').update(path).digest('hex');
+  return `${runId}--${digest}--${basename(path)}`;
+}
+
+function resultOf(output: Record<string, unknown>, seat: ExecSeat, id: string, root: string): ExecResult | null {
+  const candidate = typeof output.file === 'string' ? output.file : typeof output.path === 'string' ? output.path : null;
+  let url: string;
+  let kind: ExecResult['kind'];
+  let name: string;
+  if (candidate !== null) {
+    const path = safeFile(candidate, root, seat.graphId, seat.runId);
+    if (!path) return null;
+    const fileKind = kinds[basename(path).slice(basename(path).lastIndexOf('.')).toLowerCase()];
+    if (!fileKind) return null;
+    kind = fileKind;
+    name = basename(path);
+    url = `/v1/exec-requests/${id}/files/${encodeURIComponent(fileName(path, seat.runId))}`;
+  } else {
+    const link = publicLink(output.url);
+    if (!link) return null;
+    kind = 'link';
+    name = link;
+    url = link;
+  }
+  const sources = Array.isArray(output.sources) ? output.sources.flatMap((source: unknown) => {
+    if (!source || typeof source !== 'object') return [];
+    const entry = source as { title?: unknown; url?: unknown };
+    const sourceUrl = publicLink(entry.url);
+    return typeof entry.title === 'string' && sourceUrl ? [{ title: entry.title, url: sourceUrl }] : [];
+  }) : [];
+  return { seat: seat.seat, kind, title: typeof output.title === 'string' ? output.title : name,
+    url, ...(sources.length ? { sources } : {}) };
+}
+
+function syncRun(item: ExecRequest, seat: ExecSeat, state: GraphRunState, root: string): void {
+  const previous = seat.status;
+  seat.status = state.status === 'done' ? 'done' : state.status === 'failed' || state.status === 'budget-exceeded' ? 'failed' : 'running';
+  if (previous !== seat.status) debug.log('exec-requests', 'seat-status', { id: item.id, seat: seat.seat, from: previous, to: seat.status, graphId: seat.graphId, runId: seat.runId });
+  const claim = state.status === 'awaiting-approval' && state.pending
+    ? `${join(root, 'graph-runs', seat.graphId, `${seat.runId}.json`)}.${state.path.length}.decision.json` : '';
+  if (state.status === 'awaiting-approval' && state.pending && !state.pending.decision && !existsSync(claim)) {
+    if (!item.approvals.some(a => a.graphId === seat.graphId && a.runId === seat.runId)) {
+      item.approvals.push({ graphId: seat.graphId, runId: seat.runId, message: state.pending.message });
+    }
+  } else item.approvals = item.approvals.filter(a => a.graphId !== seat.graphId || a.runId !== seat.runId);
+  for (const node of state.nodes ?? []) {
+    const output = lastJsonObject(node.output);
+    if (!output) continue;
+    const entries = Array.isArray(output.artifacts) ? output.artifacts : [output];
+    for (const entry of entries) {
+      if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+      const result = resultOf(entry as Record<string, unknown>, seat, item.id, root);
+      if (result && !item.results.some(existing => existing.seat === result.seat && existing.url === result.url)) item.results.push(result);
+    }
+  }
+  const summary = [...(state.nodes ?? [])].reverse().map(node => lastJsonObject(node.output)?.summary).find(value => typeof value === 'string');
+  if (typeof summary === 'string') item.summary = summary;
+  if (seat.status === 'failed') seat.reason = state.nodes?.at(-1)?.error ?? `그래프 런 ${state.status}`;
+}
+
+function aggregate(item: ExecRequest): void {
+  if (item.status === 'planning' || item.seats.length === 0) return;
+  if (item.seats.some(seat => seat.status === 'waiting' || seat.status === 'running')) item.status = 'running';
+  else item.status = item.seats.some(seat => seat.status === 'failed') ? 'failed' : 'done';
+  // 실패면 요약은 «실패 사유»가 이긴다 — 먼저 끝난 자리의 산출 설명이 남아 있어도 덮는다(혼합 결과에서 성공처럼 보이지 않게).
+  if (item.status === 'failed') {
+    const reasons = item.seats.filter(seat => seat.status === 'failed').map(seat => seat.reason ?? `${seat.seat}: 그래프 실행 실패`);
+    if (reasons.length > 0) item.summary = reasons.join('; ');
+  }
+}
+
+export class ExecRequestRunner {
+  readonly store: ExecRequestStore;
+  private readonly root: string;
+  constructor(private readonly deps: ExecRunnerDeps = {}) {
+    this.store = deps.store ?? new ExecRequestStore();
+    this.root = deps.root ?? effectiveInstanceRoot();
+  }
+
+  /** 데몬 «시작» 때 한 번만 부른다(`startNexusHttpServer`). 생성자에서 부르면 모듈을 import 만 한 다른 프로세스
+   *  (시험·CLI·동시 서버)가 살아 있는 요청을 «재시작 중단»으로 실패 처리한다(리뷰 3라운드 must-fix). */
+  reconcileInterrupted(): void {
+    for (const item of this.store.list()) {
+      if (item.status !== 'planning' && item.status !== 'running') continue;
+      if (item.status === 'planning') {
+        item.status = 'failed';
+        item.summary = '데몬 재시작으로 COO 계획이 중단됐습니다';
+      } else {
+        if (item.seats.length === 0) {
+          item.status = 'failed';
+          item.summary = '데몬 재시작으로 자리 배정이 중단됐습니다';
+        }
+        for (const seat of item.seats) {
+          if (seat.status === 'done' || seat.status === 'failed') continue;
+          const reason = '데몬 재시작으로 그래프 실행이 중단됐습니다';
+          if (SEGMENT.test(seat.graphId) && SEGMENT.test(seat.runId)) {
+            try {
+              const file = join(this.root, 'graph-runs', seat.graphId, `${seat.runId}.json`);
+              const state = JSON.parse(readFileSync(file, 'utf8')) as GraphRunState;
+              if (state.graphId === seat.graphId && state.runId === seat.runId) {
+                if (state.status === 'done' || state.status === 'failed' || state.status === 'budget-exceeded'
+                  || (state.status === 'awaiting-approval' && state.pending)) {
+                  syncRun(item, seat, state, this.root);
+                  continue;
+                }
+              }
+            } catch { /* No trustworthy completed or approval-pending run to recover. */ }
+          }
+          const previous = seat.status;
+          seat.status = 'failed';
+          seat.reason = reason;
+          item.approvals = item.approvals.filter(a => a.graphId !== seat.graphId || a.runId !== seat.runId);
+          debug.log('exec-requests', 'seat-status', { id: item.id, seat: seat.seat, from: previous, to: 'failed', reason });
+        }
+        aggregate(item);
+        if (item.status === 'failed' && item.seats.length > 0) item.summary = item.seats.filter(seat => seat.status === 'failed')
+          .map(seat => seat.reason ?? `${seat.seat}: 그래프 실행 실패`).join('; ');
+      }
+      this.store.save(item);
+      if (item.status === 'failed') debug.log('exec-requests', 'failed', { id: item.id, reason: item.summary });
+    }
+  }
+
+  submit(text: string): ExecRequest {
+    const item = this.store.create(text);
+    void this.execute(item.id).catch(error => {
+      const current = this.store.get(item.id);
+      if (!current) return;
+      current.status = 'failed';
+      current.summary = error instanceof Error ? error.message : String(error);
+      this.store.save(current);
+      debug.log('exec-requests', 'failed', { id: item.id, reason: current.summary });
+    });
+    return item;
+  }
+
+  private async execute(id: string): Promise<void> {
+    const item = this.store.get(id);
+    if (!item) return;
+    const graphs = await (this.deps.graphs ?? installedGraphs)();
+    const plans = await (this.deps.plan ?? ((text: string) => planExecRequest(text, { graphs: async () => graphs })))(item.text);
+    const byId = new Map(graphs.map(graph => [graph.id, graph]));
+    item.seats = plans.map(plan => ({ seat: plan.seat, title: plan.title, status: plan.reason || !byId.has(plan.graphId) ? 'failed' : 'waiting', graphId: plan.graphId,
+      runId: plan.reason || !byId.has(plan.graphId) ? '' : randomUUID(), inputs: plan.inputs,
+      ...(plan.reason || !byId.has(plan.graphId) ? { reason: plan.reason ?? `${plan.seat}: 요청에 맞는 설치된 실행 그래프가 없습니다` } : {}) }));
+    item.status = 'running';
+    debug.log('exec-requests', 'planned', { id, seats: item.seats.map(seat => ({ seat: seat.seat, graphId: seat.graphId, status: seat.status })) });
+    this.store.save(item);
+    await Promise.all(item.seats.map(async (seat, index) => {
+      const graph = byId.get(seat.graphId);
+      if (!graph || seat.status === 'failed') return;
+      const starting = this.store.get(id)!;
+      starting.seats[index]!.status = 'running';
+      this.store.save(starting);
+      debug.log('exec-requests', 'started', { id, seat: seat.seat, graphId: seat.graphId, runId: seat.runId });
+      debug.log('exec-requests', 'seat-status', { id, seat: seat.seat, from: 'waiting', to: 'running' });
+      try {
+        const state = await (this.deps.run ?? runGraph)(graph.path, { input: seat.inputs, runId: seat.runId, deps: { root: this.root } });
+        const current = this.store.get(id)!;
+        syncRun(current, current.seats[index]!, state, this.root);
+        aggregate(current);
+        this.store.save(current);
+      } catch (error) {
+        const current = this.store.get(id)!;
+        current.seats[index]!.status = 'failed';
+        current.seats[index]!.reason = error instanceof Error ? error.message : String(error);
+        debug.log('exec-requests', 'seat-status', { id, seat: seat.seat, to: 'failed', reason: current.seats[index]!.reason });
+        aggregate(current);
+        this.store.save(current);
+      }
+    }));
+    const finished = this.store.get(id)!;
+    aggregate(finished);
+    this.store.save(finished);
+    if (finished.status === 'done' || finished.status === 'failed') debug.log('exec-requests', finished.status, { id, results: finished.results.length });
+  }
+
+  get(id: string): ExecRequest | null {
+    const item = this.store.get(id);
+    if (!item) return null;
+    if (item.status === 'planning' || item.status === 'done' || item.status === 'failed') return item;
+    for (const seat of item.seats) {
+      // An approved decision triggers a resume; failures are terminal and never retried on reads.
+      // A terminal seat is never re-synced from a stale awaiting-approval snapshot.
+      if (seat.status === 'done' || seat.status === 'failed' || !seat.runId || !SEGMENT.test(seat.graphId) || !SEGMENT.test(seat.runId)) continue;
+      const file = join(this.root, 'graph-runs', seat.graphId, `${seat.runId}.json`);
+      if (!existsSync(file)) continue;
+      try {
+        const state = JSON.parse(readFileSync(file, 'utf8')) as GraphRunState;
+        if (state.graphId !== seat.graphId || state.runId !== seat.runId) continue;
+        syncRun(item, seat, state, this.root);
+        if (state.status === 'awaiting-approval' && state.pending && !state.pending.decision) {
+          const decision = `${file}.${state.path.length}.decision.json`;
+          if (existsSync(decision)) {
+            item.approvals = item.approvals.filter(a => a.runId !== seat.runId);
+            const key = `${seat.graphId}/${seat.runId}`;
+            if (!active.has(key)) {
+              active.add(key);
+              const launch = async () => {
+                try {
+                  const graphs = await (this.deps.graphs ?? installedGraphs)();
+                  const graph = graphs.find(candidate => candidate.id === seat.graphId);
+                  if (!graph) throw new Error('설치된 그래프가 없습니다');
+                  const resumed = await (this.deps.run ?? runGraph)(graph.path, { resumeRunId: seat.runId, deps: { root: this.root } });
+                  const current = this.store.get(id);
+                  const target = current?.seats.find(s => s.runId === seat.runId);
+                  if (current && target) { syncRun(current, target, resumed, this.root); aggregate(current); this.store.save(current); }
+                } catch (error) {
+                  const reason = error instanceof Error ? error.message : String(error);
+                  const current = this.store.get(id);
+                  const target = current?.seats.find(s => s.graphId === seat.graphId && s.runId === seat.runId);
+                  if (current && target && target.status !== 'done') {
+                    target.status = 'failed';
+                    target.reason = `그래프 재개 실패: ${reason}`;
+                    current.approvals = current.approvals.filter(a => a.graphId !== seat.graphId || a.runId !== seat.runId);
+                    aggregate(current);
+                    this.store.save(current);
+                    debug.log('exec-requests', 'seat-status', { id, seat: seat.seat, to: 'failed', reason: target.reason });
+                  }
+                  debug.log('exec-requests', 'failed', { id, seat: seat.seat, reason });
+                } finally { active.delete(key); }
+              };
+              void launch();
+            }
+          }
+        }
+      } catch (error) { debug.log('exec-requests', 'failed', { id, seat: seat.seat, reason: String(error) }); }
+    }
+    const current = this.store.get(id) ?? item;
+    for (const seat of item.seats) {
+      const target = current.seats.find(candidate => candidate.runId && candidate.runId === seat.runId);
+      if (target && target.status !== 'done' && target.status !== 'failed') {
+        target.status = seat.status;
+        if (seat.reason) target.reason = seat.reason;
+      }
+    }
+    const approvals = new Map(current.approvals.map(approval => [`${approval.graphId}/${approval.runId}`, approval]));
+    for (const approval of item.approvals) approvals.set(`${approval.graphId}/${approval.runId}`, approval);
+    current.approvals = [...approvals.values()].filter(approval => {
+      const seat = current.seats.find(candidate => candidate.graphId === approval.graphId && candidate.runId === approval.runId);
+      if (!seat || seat.status === 'done' || seat.status === 'failed') return false;
+      const file = join(this.root, 'graph-runs', approval.graphId, `${approval.runId}.json`);
+      try {
+        const state = JSON.parse(readFileSync(file, 'utf8')) as GraphRunState;
+        return state.status === 'awaiting-approval' && !!state.pending && !state.pending.decision
+          && !existsSync(`${file}.${state.path.length}.decision.json`);
+      } catch { return false; }
+    });
+    for (const result of item.results) {
+      if (!current.results.some(existing => existing.url === result.url)) current.results.push(result);
+    }
+    if (item.summary && !current.summary) current.summary = item.summary;
+    aggregate(current);
+    this.store.save(current);
+    return current;
+  }
+
+  file(id: string, name: string): string | null {
+    // Artifact names may contain spaces and Unicode; only a single safe path component is accepted.
+    if (!name || name === '.' || name === '..' || name !== basename(name) || /[\\/\x00-\x1f\x7f]/.test(name)) return null;
+    const item = this.get(id);
+    const result = item?.results.find(entry => entry.url === `/v1/exec-requests/${id}/files/${encodeURIComponent(name)}`);
+    if (!result) return null;
+    const seat = item!.seats.find(entry => name.startsWith(`${entry.runId}--`) && entry.seat === result.seat);
+    if (!seat) return null;
+    try {
+      const state = JSON.parse(readFileSync(join(this.root, 'graph-runs', seat.graphId, `${seat.runId}.json`), 'utf8')) as GraphRunState;
+      if (state.graphId !== seat.graphId || state.runId !== seat.runId) return null;
+      for (const node of state.nodes ?? []) {
+        const output = lastJsonObject(node.output);
+        if (!output) continue;
+        for (const entry of Array.isArray(output.artifacts) ? output.artifacts : [output]) {
+          if (!entry || typeof entry !== 'object' || Array.isArray(entry)) continue;
+          const artifact = entry as Record<string, unknown>;
+          const candidate = typeof artifact.file === 'string' ? artifact.file : artifact.path;
+          if (typeof candidate !== 'string') continue;
+          const path = safeFile(candidate, this.root, seat.graphId, seat.runId);
+          if (path && fileName(path, seat.runId) === name) return path;
+        }
+      }
+    } catch { return null; }
+    return null;
+  }
+}

package/src/exec-requests/store.ts

@@ -0,0 +1,76 @@
+import { randomUUID } from 'node:crypto';
+import { mkdirSync, readFileSync, readdirSync, renameSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { getElanousConfigDir } from '../elanous-config-dir.js';
+
+export type SeatStatus = 'waiting' | 'running' | 'done' | 'failed';
+export interface ExecSeat {
+  seat: string;
+  title: string;
+  status: SeatStatus;
+  graphId: string;
+  runId: string;
+  inputs?: Record<string, unknown>;
+  reason?: string;
+}
+export interface ExecResult {
+  seat: string;
+  kind: 'report' | 'pdf' | 'video' | 'image' | 'text' | 'link';
+  title: string;
+  url: string;
+  sources?: Array<{ title: string; url: string }>;
+}
+export interface ExecRequest {
+  id: string;
+  text: string;
+  createdAt: string;
+  status: 'planning' | 'running' | 'done' | 'failed';
+  summary: string;
+  seats: ExecSeat[];
+  results: ExecResult[];
+  approvals: Array<{ graphId: string; runId: string; message: string }>;
+}
+
+const validId = (id: string) => /^[a-f0-9-]{36}$/.test(id);
+
+export class ExecRequestStore {
+  readonly dir: string;
+  constructor(configDir = getElanousConfigDir()) { this.dir = join(configDir, 'exec-requests'); }
+
+  create(text: string): ExecRequest {
+    const item: ExecRequest = { id: randomUUID(), text, createdAt: new Date().toISOString(), status: 'planning', summary: '', seats: [], results: [], approvals: [] };
+    this.save(item);
+    return item;
+  }
+
+  get(id: string): ExecRequest | null {
+    if (!validId(id)) return null;
+    try {
+      const item = JSON.parse(readFileSync(join(this.dir, `${id}.json`), 'utf8')) as ExecRequest;
+      return item.id === id ? item : null;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return null;
+      throw error;
+    }
+  }
+
+  list(): ExecRequest[] {
+    try {
+      return readdirSync(this.dir).filter(file => /^[a-f0-9-]{36}\.json$/.test(file))
+        .flatMap(file => { const item = this.get(file.slice(0, -5)); return item ? [item] : []; })
+        .sort((a, b) => b.createdAt.localeCompare(a.createdAt) || b.id.localeCompare(a.id));
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+      throw error;
+    }
+  }
+
+  save(item: ExecRequest): void {
+    if (!validId(item.id)) throw new Error('invalid exec request id');
+    mkdirSync(this.dir, { recursive: true, mode: 0o700 });
+    const target = join(this.dir, `${item.id}.json`);
+    const temp = join(this.dir, `${item.id}.${randomUUID()}.tmp`);
+    writeFileSync(temp, JSON.stringify(item) + '\n', { flag: 'wx', mode: 0o600 });
+    renameSync(temp, target);
+  }
+}

package/src/field/field-media.ts

@@ -52,6 +52,8 @@ export interface FieldMediaInput {
   bytes: Uint8Array;
   /** 촬영 시각(ISO 문자열·epoch ms). 못 읽으면 업로드 시각. */
   capturedAt?: string | number | Date;
+  /** 이 파일에 붙일 자막. */
+  caption?: string;
 }
 
 export interface FieldSaveOptions {
@@ -178,7 +180,7 @@ export function saveFieldMedia(inputs: FieldMediaInput[], opts: FieldSaveOptions
     total += size;
     if (total > FIELD_MAX_REQUEST_BYTES) throw new FieldUploadError('too-large', 'the request exceeds 250 MB');
     const name = `${fieldTimestamp(input.capturedAt, now)}-${opts.device}-${sanitizeFieldName(input.originalName, mime)}`;
-    return { name, bytes: input.bytes };
+    return { name, bytes: input.bytes, caption: input.caption };
   });
 
   mkdirSync(dir, { recursive: true });
@@ -190,8 +192,11 @@ export function saveFieldMedia(inputs: FieldMediaInput[], opts: FieldSaveOptions
     atomicWrite(dir, name, item.bytes);
     saved.push({ name, bytes: item.bytes.byteLength });
   }
-  const line = normalizeFieldCaption(opts.caption);
-  if (line && saved[0]) appendFileSync(join(dir, FIELD_CAPTIONS_FILE), `${saved[0].name} | ${line}\n`);
+  const lines = planned.flatMap((item, i) => {
+    const line = normalizeFieldCaption(item.caption ?? (i === 0 ? opts.caption : undefined));
+    return line ? [`${saved[i]!.name} | ${line}\n`] : [];
+  });
+  if (lines.length) appendFileSync(join(dir, FIELD_CAPTIONS_FILE), lines.join(''));
   const count = refreshFieldReady(dir);
   return { event: opts.event, dir, saved, count };
 }

package/src/field/field-reel.ts

@@ -0,0 +1,196 @@
+// 한 행사 폴더의 업로드 디바운스와 직렬 렌더. 프로세스 안의 폴더별 단일 실행기.
+import { existsSync, mkdirSync, readFileSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { spawn, execFileSync } from 'node:child_process';
+import { debug } from '../debug/log.js';
+import { listFieldMedia } from './field-media.js';
+
+export interface FieldReelResult { ok: boolean; file?: string; seconds: number; error?: string }
+export type FieldReelRunner = (dir: string, opts: { title: string; sub: string }) => Promise<FieldReelResult>;
+export interface FieldReelStatus {
+  state: 'waiting' | 'rendering' | 'done' | 'failed';
+  items: number;
+  updatedAt: string;
+  startedAt?: string;
+  finishedAt?: string;
+  seconds?: number;
+  file?: string;
+  error?: string;
+}
+export interface FieldReelOptions {
+  quietMs?: number;
+  title?: string;
+  sub?: string;
+  runner?: FieldReelRunner;
+  onDone?: (result: FieldReelResult) => void | Promise<void>;
+  /** 같은 수신자가 앨범 항목마다 예약해도 한 렌더당 한 번만 통지한다. */
+  notificationKey?: string;
+}
+
+const REEL_FILE = 'reel-9x16.mp4';
+interface Job {
+  timer?: ReturnType<typeof setTimeout>;
+  running: boolean;
+  dirty: boolean;
+  lastUploadAt: number;
+  opts: FieldReelOptions;
+  callbacks: Map<string, NonNullable<FieldReelOptions['onDone']>>;
+}
+const jobs = new Map<string, Job>();
+
+export function fieldReelFile(dir: string): string { return join(dir, 'reel', REEL_FILE); }
+
+/** 요청 경로용 싼 검사 — 파일이 있고 비어 있지 않다. 디코딩 검사는 렌더가 끝날 때 한 번(`isValidFieldReelFile`)만 한다. */
+export function hasFieldReelFile(file: string): boolean {
+  try {
+    const stat = statSync(file);
+    return stat.isFile() && stat.size > 0;
+  } catch {
+    return false;
+  }
+}
+
+/** Publish only a reel with a decodable video frame, not merely valid-looking MP4 boxes.
+ *  렌더 완료 때 한 번만 부른다 — 첫 영상 프레임 하나만 읽는다(`-read_intervals %+#1`) · 긴 영상도 출력이 작다. */
+export function isValidFieldReelFile(file: string): boolean {
+  try {
+    if (!hasFieldReelFile(file)) return false;
+    const probe = JSON.parse(execFileSync('ffprobe', [
+      '-v', 'error', '-select_streams', 'v:0', '-read_intervals', '%+#1', '-show_streams', '-show_frames',
+      '-show_entries', 'stream=codec_type:frame=media_type', '-of', 'json', file,
+    ], { encoding: 'utf8', timeout: 30_000, maxBuffer: 2 * 1024 * 1024, stdio: ['ignore', 'pipe', 'ignore'] })) as {
+      streams?: Array<{ codec_type?: string }>;
+      frames?: Array<{ media_type?: string }>;
+    };
+    return probe.streams?.some((stream) => stream.codec_type === 'video') === true
+      && probe.frames?.some((frame) => frame.media_type === 'video') === true;
+  } catch {
+    return false;
+  }
+}
+/** 상태 파일은 `reel/` «밖»에 둔다 — `reel.sh` 가 시작할 때 `reel/` 을 지우므로 안에 두면 렌더 중에 사라진다. */
+export function fieldReelStatusPath(dir: string): string { return join(dir, '.reel-status.json'); }
+const statusPath = fieldReelStatusPath;
+function writeStatus(dir: string, status: Omit<FieldReelStatus, 'updatedAt'>): void {
+  mkdirSync(dir, { recursive: true });
+  const tmp = join(dir, `.reel-status-${randomUUID()}`);
+  try {
+    writeFileSync(tmp, JSON.stringify({ ...status, updatedAt: new Date().toISOString() }));
+    renameSync(tmp, statusPath(dir));
+  } finally {
+    if (existsSync(tmp)) unlinkSync(tmp);
+  }
+}
+
+export function readFieldReelStatus(dir: string): FieldReelStatus | null {
+  try { return JSON.parse(readFileSync(statusPath(dir), 'utf8')) as FieldReelStatus; }
+  catch (err) {
+    if ((err as NodeJS.ErrnoException).code === 'ENOENT') return null;
+    throw err;
+  }
+}
+
+export const defaultFieldReelRunner: FieldReelRunner = (dir, { title, sub }) => new Promise((finish) => {
+  const script = resolve(import.meta.dir, '../../skills/explainer-video/engine/reel.sh');
+  const started = Date.now();
+  const child = spawn('zsh', [script, dir, '--title', title, '--sub', sub], { stdio: 'ignore' });
+  let settled = false;
+  const done = (error?: string) => {
+    if (settled) return;
+    settled = true;
+    const file = fieldReelFile(dir);
+    const seconds = Math.round((Date.now() - started) / 1000);
+    // 디코딩 검사(ffprobe)는 `render()` 한 곳에서만 한다 — 여기선 존재만 본다(리뷰: 검사 두 번 금지).
+    finish(error || !hasFieldReelFile(file)
+      ? { ok: false, seconds, error: error ?? `invalid or missing MP4 output: ${file}` }
+      : { ok: true, file, seconds });
+  };
+  child.once('error', (err) => done(err.message));
+  child.once('close', (code) => done(code === 0 ? undefined : `reel.sh exited ${code ?? 'unknown'}`));
+});
+
+function arm(dir: string, job: Job): void {
+  if (job.timer) clearTimeout(job.timer);
+  job.timer = setTimeout(() => {
+    job.timer = undefined;
+    if (!job.running) void render(dir, job);
+  }, Math.max(0, (job.opts.quietMs ?? 20_000) - (Date.now() - job.lastUploadAt)));
+  job.timer.unref?.();
+}
+
+async function render(dir: string, job: Job): Promise<void> {
+  job.running = true;
+  job.dirty = false;
+  const items = listFieldMedia(dir).length;
+  const startedAt = new Date().toISOString();
+  const event = dir.split(/[\\/]/).at(-1)!;
+  // 현재 렌더의 수신자 스냅샷. 렌더 중 업로드의 수신자는 다음 렌더로 넘긴다.
+  const callbacks = job.callbacks;
+  const renderOpts = job.opts;
+  job.callbacks = new Map();
+  writeStatus(dir, { state: 'rendering', items, startedAt });
+  mkdirSync(join(dir, 'reel'), { recursive: true }); // 실행기 계약 — 산출 폴더는 있다(reel.sh 는 스스로 다시 만든다)
+  debug.log('field.reel', 'started', { event, items });
+  let result: FieldReelResult;
+  try {
+    const date = new Date();
+    const sub = `${date.getFullYear()}-${String(date.getMonth() + 1).padStart(2, '0')}-${String(date.getDate()).padStart(2, '0')}`;
+    let titleLines: string[] = [];
+    try { titleLines = readFileSync(join(dir, 'title.txt'), 'utf8').split(/\r?\n/); }
+    catch (err) { if ((err as NodeJS.ErrnoException).code !== 'ENOENT') throw err; }
+    result = await (renderOpts.runner ?? defaultFieldReelRunner)(dir, {
+      title: titleLines[0]?.trim() || renderOpts.title || event,
+      sub: titleLines[1]?.trim() || renderOpts.sub || sub,
+    });
+  } catch (err) {
+    result = { ok: false, seconds: 0, error: err instanceof Error ? err.message : String(err) };
+  }
+  if (result.ok && (!result.file || resolve(result.file) !== fieldReelFile(dir) || !isValidFieldReelFile(result.file))) {
+    result = { ok: false, seconds: result.seconds, error: 'render output invalid or missing' };
+  }
+  const finishedAt = new Date().toISOString();
+  writeStatus(dir, { state: result.ok ? 'done' : 'failed', items, startedAt, finishedAt,
+    seconds: result.seconds, ...(result.ok ? { file: result.file } : { error: result.error ?? 'render failed' }) });
+  debug.log('field.reel', result.ok ? 'done' : 'failed', { event, items, seconds: result.seconds });
+  if (result.ok) {
+    // EV10b: 엔진이 timeline.json 에 남긴 비전 호출 수·성공·«현장 N» 강등·걸린 ms — codex 잔량과 겹치므로 관측한다(OP 10-01).
+    try {
+      const t = JSON.parse(readFileSync(join(dir, 'reel', 'timeline.json'), 'utf8')) as { vision?: Record<string, unknown>; music?: unknown };
+      if (t.vision) debug.log('field.reel', 'vision', { event, ...t.vision, music: t.music === true });
+    } catch { debug.log('field.reel', 'vision-unread', { event }); }
+  }
+  job.running = false;
+  if (job.dirty) {
+    writeStatus(dir, { state: 'waiting', items: listFieldMedia(dir).length });
+    arm(dir, job);
+  } else {
+    jobs.delete(dir);
+  }
+  for (const cb of callbacks.values()) {
+    void Promise.resolve().then(() => cb(result)).catch((err) => {
+      debug.log('field.reel', 'delivery-failed', { event, error: String(err) });
+    });
+  }
+}
+
+/** 저장 성공 직후 호출한다. quiet 기간의 연속 업로드를 합치고 렌더 중 변경은 뒤이어 다시 렌더한다. */
+export function scheduleFieldReel(dir: string, opts: FieldReelOptions = {}): void {
+  dir = resolve(dir);
+  const event = dir.split(/[\\/]/).at(-1)!;
+  let job = jobs.get(dir);
+  if (!job) {
+    job = { running: false, dirty: false, lastUploadAt: Date.now(), opts, callbacks: new Map() };
+    jobs.set(dir, job);
+  }
+  job.opts = { ...opts, runner: opts.runner ?? job.opts.runner, quietMs: opts.quietMs ?? job.opts.quietMs };
+  job.lastUploadAt = Date.now();
+  if (opts.onDone) job.callbacks.set(opts.notificationKey ?? 'default', opts.onDone);
+  const items = listFieldMedia(dir).length;
+  if (job.running) job.dirty = true;
+  else {
+    writeStatus(dir, { state: 'waiting', items });
+    arm(dir, job);
+  }
+  debug.log('field.reel', 'scheduled', { event, items });
+}

package/src/grok/credential.ts

@@ -35,11 +35,13 @@ export const GROK_SUBSCRIPTION_BASE_URL = 'https://cli-chat-proxy.grok.com/v1';
 /** API 키 경로 베이스(토큰 과금). */
 export const GROK_API_BASE_URL = 'https://api.x.ai/v1';
 
-/** 프록시가 요구하는 최소 CLI 버전(실측 426 문면). 이보다 낮으면 거절된다. */
-export const GROK_PROXY_MIN_CLI_VERSION = '0.1.202';
-/** 설치본을 못 읽었을 때 신고할 값. ⛔ 하한을 쓰면 프록시가 하한을 «올리는» 날
- *  전부 426 이 된다 — 그래서 아래 `detectGrokCliVersion()` 이 1순위다. */
-const GROK_PROXY_FALLBACK_CLI_VERSION = GROK_PROXY_MIN_CLI_VERSION;
+/** 프록시가 요구하는 최소 CLI 버전(실측 426 문면). 이보다 낮으면 거절된다.
+ *  2026-10-01 실측: «Your Grok CLI version (0.1.202) is outdated. Please update to version 1.0.13 or later». */
+export const GROK_PROXY_MIN_CLI_VERSION = '1.0.13';
+/** 설치본을 못 읽었을 때(grok CLI 없는 기계 · 파드) 신고할 값 — 하한이 아니라 실측된 최근 설치본.
+ *  ⛔ 하한을 쓰면 프록시가 하한을 «올리는» 날 전부 426 이 된다(10-01 파드 자식이 0.1.202 로 전부 거절됨).
+ *  그래서 아래 `detectGrokCliVersion()` 이 1순위다. */
+const GROK_PROXY_FALLBACK_CLI_VERSION = '1.0.41';
 
 /** 설치된 grok CLI 의 버전. ⭐ 하드코딩 하한 대신 «실제 설치본»을 신고한다.
  *