elanous 0.2.5 → 0.2.7

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

@@ -0,0 +1,250 @@
+// 현장(field) 업로드 폴더 계약 — HTTP 입구(`/v1/field/uploads`)와 텔레그램 `#현장` 이 «같은» 저장 함수를 쓴다.
+//
+// 폴더 계약(2026-09-30 합의 · 소비자 = reel 파이프라인):
+//   <configDir>/field/<event>/<ISO 기본형 타임스탬프>-<device>-<원래 이름>
+//   타임스탬프 = 클라이언트가 준 촬영 시각(있으면) · 없으면 업로드 시각 · UTC · `20261015T193012Z`(ISO 8601 기본형 —
+//   파일 이름에 콜론을 넣지 않으려고 기본형을 쓴다. 사전순 = 시간순).
+//   배치가 끝나면 `<folder>/.ready` 를 한 줄(= 폴더의 미디어 파일 수)로 덮어쓴다.
+
+import { appendFileSync, mkdirSync, readdirSync, renameSync, statSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { randomUUID } from 'node:crypto';
+
+export const FIELD_SLUG_RE = /^[a-z0-9][a-z0-9._-]{0,63}$/;
+export const FIELD_MAX_FILE_BYTES = 100 * 1024 * 1024; // 폰 현장 사진·짧은 영상 — 데몬 전역 요청 한도를 과하게 올리지 않으려고 낮게(2026-09-30)
+export const FIELD_MAX_REQUEST_BYTES = 250 * 1024 * 1024;
+export const FIELD_READY_FILE = '.ready';
+const MAX_ORIGINAL_NAME = 80;
+
+/** 허용 MIME → 대표 확장자. heif 는 heic 의 별칭으로 받는다. */
+const MIME_EXT: Record<string, string> = {
+  'image/jpeg': 'jpg',
+  'image/jpg': 'jpg',
+  'image/png': 'png',
+  'image/heic': 'heic',
+  'image/heif': 'heic',
+  'image/webp': 'webp',
+  'video/mp4': 'mp4',
+  'video/quicktime': 'mov',
+};
+const EXT_MIME: Record<string, string> = {
+  jpg: 'image/jpeg', jpeg: 'image/jpeg', png: 'image/png', heic: 'image/heic', heif: 'image/heif',
+  webp: 'image/webp', mp4: 'video/mp4', mov: 'video/quicktime',
+};
+
+export type FieldUploadErrorCode = 'bad-slug' | 'unsupported-media-type' | 'too-large' | 'no-files' | 'bad-request';
+
+export class FieldUploadError extends Error {
+  constructor(readonly code: FieldUploadErrorCode, message: string) {
+    super(message);
+    this.name = 'FieldUploadError';
+  }
+  get status(): number {
+    if (this.code === 'unsupported-media-type') return 415;
+    if (this.code === 'too-large') return 413;
+    return 400;
+  }
+}
+
+export interface FieldMediaInput {
+  originalName: string;
+  mimeType?: string;
+  bytes: Uint8Array;
+  /** 촬영 시각(ISO 문자열·epoch ms). 못 읽으면 업로드 시각. */
+  capturedAt?: string | number | Date;
+  /** 이 파일에 붙일 자막. */
+  caption?: string;
+}
+
+export interface FieldSaveOptions {
+  /** config 뿌리(`~/.elanous` 또는 격리 뿌리). 폴더 = `<rootDir>/field/<event>`. */
+  rootDir: string;
+  event: string;
+  device: string;
+  now?: () => Date;
+  /** 사람이 쓴 한 줄(텔레그램 캡션·앱 입력칸) — 있으면 `captions.txt` 에 «<첫 파일 이름> | <글>» 로 덧붙인다(reel 자막 · MK 2026-09-30). */
+  caption?: string;
+}
+
+export interface FieldSaveResult {
+  event: string;
+  dir: string;
+  saved: Array<{ name: string; bytes: number }>;
+  /** 저장 «후» 폴더의 미디어 파일 수(= `.ready` 에 쓴 값). */
+  count: number;
+}
+
+export function isFieldSlug(value: unknown): value is string {
+  return typeof value === 'string' && FIELD_SLUG_RE.test(value);
+}
+
+export function fieldEventDir(rootDir: string, event: string): string {
+  if (!isFieldSlug(event)) throw new FieldUploadError('bad-slug', 'event slug must match ^[a-z0-9][a-z0-9._-]{0,63}$');
+  return join(rootDir, 'field', event);
+}
+
+function extOf(name: string): string {
+  const dot = name.lastIndexOf('.');
+  return dot > 0 ? name.slice(dot + 1).toLowerCase() : '';
+}
+
+/** 허용 MIME 이면 정규화한 MIME, 아니면 null. MIME 이 비었거나 octet-stream 이면 확장자로 추정한다. */
+export function resolveFieldMime(mimeType: string | undefined, originalName: string): string | null {
+  const mime = (mimeType ?? '').split(';')[0]!.trim().toLowerCase();
+  if (mime && mime !== 'application/octet-stream') return MIME_EXT[mime] ? mime : null;
+  return EXT_MIME[extOf(originalName)] ?? null;
+}
+
+/** basename · `[A-Za-z0-9._-]` 외는 `_` · 앞 점 제거 · 최대 80자(확장자 보존) · 확장자가 MIME 과 안 맞으면 붙인다. */
+export function sanitizeFieldName(originalName: string, mime?: string): string {
+  const base = originalName.split(/[\\/]/).pop() ?? '';
+  let name = base.replace(/[^A-Za-z0-9._-]/g, '_').replace(/_+/g, '_').replace(/^\.+/, '');
+  const wantExt = mime ? MIME_EXT[mime] : undefined;
+  const ext = extOf(name);
+  if (wantExt && EXT_MIME[ext] === undefined) name = name ? `${name}.${wantExt}` : `media.${wantExt}`;
+  if (!name) name = 'media';
+  if (name.length > MAX_ORIGINAL_NAME) {
+    const e = extOf(name);
+    const suffix = e && e.length < 10 ? `.${e}` : '';
+    name = name.slice(0, MAX_ORIGINAL_NAME - suffix.length) + suffix;
+  }
+  return name;
+}
+
+/** `20261015T193012Z` — ISO 8601 기본형 UTC(초 단위). */
+export function fieldTimestamp(capturedAt: FieldMediaInput['capturedAt'], now: Date): string {
+  let at: Date | null = null;
+  if (capturedAt instanceof Date) at = capturedAt;
+  else if (typeof capturedAt === 'number') at = new Date(capturedAt);
+  else if (typeof capturedAt === 'string' && capturedAt.trim()) {
+    const trimmed = capturedAt.trim();
+    at = /^\d{10,13}$/.test(trimmed) ? new Date(Number(trimmed) * (trimmed.length === 10 ? 1000 : 1)) : new Date(trimmed);
+  }
+  if (!at || Number.isNaN(at.getTime())) at = now;
+  return at.toISOString().replace(/\.\d{3}Z$/, 'Z').replace(/[-:]/g, '');
+}
+
+function isMediaFile(name: string): boolean {
+  return !name.startsWith('.') && EXT_MIME[extOf(name)] !== undefined;
+}
+
+export function listFieldMedia(dir: string): Array<{ name: string; bytes: number }> {
+  let names: string[];
+  try { names = readdirSync(dir); }
+  catch (error) {
+    if ((error as NodeJS.ErrnoException).code === 'ENOENT') return [];
+    throw error;
+  }
+  const out: Array<{ name: string; bytes: number }> = [];
+  for (const name of names.sort()) {
+    if (!isMediaFile(name)) continue;
+    try {
+      const st = statSync(join(dir, name));
+      if (st.isFile()) out.push({ name, bytes: st.size });
+    } catch { /* 사이에 지워졌다 */ }
+  }
+  return out;
+}
+
+function atomicWrite(dir: string, name: string, bytes: Uint8Array | string): void {
+  const tmp = join(dir, `.tmp-${randomUUID()}`);
+  try {
+    writeFileSync(tmp, bytes);
+    renameSync(tmp, join(dir, name));
+  } catch (error) {
+    try { unlinkSync(tmp); } catch { /* 없음 */ }
+    throw error;
+  }
+}
+
+/** `.ready` 를 «지금» 폴더의 미디어 파일 수로 덮어쓴다. */
+export function refreshFieldReady(dir: string): number {
+  const count = listFieldMedia(dir).length;
+  atomicWrite(dir, FIELD_READY_FILE, `${count}\n`);
+  return count;
+}
+
+/** 검증(전부) → 쓰기(전부, 원자적) → `.ready` 갱신. 하나라도 검증에 걸리면 아무것도 안 쓴다. */
+export function saveFieldMedia(inputs: FieldMediaInput[], opts: FieldSaveOptions): FieldSaveResult {
+  const dir = fieldEventDir(opts.rootDir, opts.event);
+  if (!isFieldSlug(opts.device)) throw new FieldUploadError('bad-slug', 'device slug must match ^[a-z0-9][a-z0-9._-]{0,63}$');
+  if (inputs.length === 0) throw new FieldUploadError('no-files', 'at least one file is required');
+  const now = (opts.now ?? (() => new Date()))();
+  let total = 0;
+  const planned = inputs.map((input) => {
+    const mime = resolveFieldMime(input.mimeType, input.originalName);
+    if (!mime) throw new FieldUploadError('unsupported-media-type', 'only jpeg/png/heic/webp images and mp4/mov videos are accepted');
+    const size = input.bytes.byteLength;
+    if (size === 0) throw new FieldUploadError('bad-request', 'empty file');
+    if (size > FIELD_MAX_FILE_BYTES) throw new FieldUploadError('too-large', 'a file exceeds 100 MB');
+    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, caption: input.caption };
+  });
+
+  mkdirSync(dir, { recursive: true });
+  const taken = new Set<string>();
+  const saved: FieldSaveResult['saved'] = [];
+  for (const item of planned) {
+    const name = uniqueName(dir, item.name, item.bytes.byteLength, taken);
+    taken.add(name);
+    atomicWrite(dir, name, item.bytes);
+    saved.push({ name, bytes: item.bytes.byteLength });
+  }
+  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 };
+}
+
+/** 같은 이름·같은 크기면 재전송으로 보고 덮는다(중복 방지). 크기가 다르면 `-1`,`-2`… 를 붙인다. */
+function uniqueName(dir: string, name: string, size: number, taken: Set<string>): string {
+  const dot = name.lastIndexOf('.');
+  const stem = dot > 0 ? name.slice(0, dot) : name;
+  const ext = dot > 0 ? name.slice(dot) : '';
+  for (let i = 0; ; i += 1) {
+    const candidate = i === 0 ? name : `${stem}-${i}${ext}`;
+    if (taken.has(candidate)) continue;
+    let existing: number | null = null;
+    try { existing = statSync(join(dir, candidate)).size; } catch { existing = null; }
+    if (existing === null || existing === size) return candidate;
+  }
+}
+
+// ── 텔레그램 캡션 문법 ──────────────────────────────────────────────
+
+export const FIELD_CAPTION_TAG = '#현장';
+
+/** 캡션에 독립 토큰 `#현장` 이 있으면 `{ event? }`, 없으면 null.
+ *  `#현장 <slug>` — 바로 다음 토큰을 소문자로 바꿔 슬러그 규칙에 맞으면 행사 이름, 아니면 기본 행사. */
+export function parseFieldCaption(caption: string | undefined | null): { event?: string; text?: string } | null {
+  if (!caption) return null;
+  const tokens = caption.trim().split(/\s+/);
+  const at = tokens.indexOf(FIELD_CAPTION_TAG);
+  if (at < 0) return null;
+  const next = tokens[at + 1]?.toLowerCase();
+  const hasEvent = !!next && isFieldSlug(next);
+  // 태그·행사 이름을 뺀 나머지가 «글»(자막) — 태그 앞에 쓴 글도 같이.
+  const rest = tokens.filter((_, i) => i !== at && !(hasEvent && i === at + 1)).join(' ');
+  const text = normalizeFieldCaption(rest);
+  return { ...(hasEvent ? { event: next } : {}), ...(text ? { text } : {}) };
+}
+
+export const FIELD_CAPTIONS_FILE = 'captions.txt';
+
+/** 자막 한 줄 — 줄바꿈은 공백으로, `|` 는 구분자라 전각 `｜` 로, 280자까지. 비면 빈 값. */
+export function normalizeFieldCaption(value: string | undefined | null): string {
+  if (typeof value !== 'string') return '';
+  return value.replace(/[\r\n]+/g, ' ').replace(/\|/g, '｜').replace(/\s+/g, ' ').trim().slice(0, 280);
+}
+
+/** 기본 행사 = 유효한 config 값 · 없으면 `field-<로컬 YYYY-MM-DD>`. */
+export function defaultFieldEvent(configured: string | undefined, now: Date = new Date()): string {
+  if (configured && isFieldSlug(configured)) return configured;
+  const pad = (n: number) => String(n).padStart(2, '0');
+  return `field-${now.getFullYear()}-${pad(now.getMonth() + 1)}-${pad(now.getDate())}`;
+}

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 의 버전. ⭐ 하드코딩 하한 대신 «실제 설치본»을 신고한다.
  *

package/src/harness/aside-run-status.ts

@@ -0,0 +1,33 @@
+import { stripScreenAnsi } from './harness-screen.js';
+
+export type AsideRunStatus = {
+  kind: 'ok' | 'not-running' | 'auth-timeout' | 'repl-error' | 'no-marker';
+  hint?: string;
+};
+
+export function classifyAsideRun({ stdout, stderr, exitCode, timedOut = false }: {
+  stdout: string;
+  stderr: string;
+  exitCode: number | null;
+  /** We killed `aside` at our own timeout. */
+  timedOut?: boolean;
+}): AsideRunStatus {
+  const diagnosticStdout = stripScreenAnsi(stdout).split(/\r?\n/).filter((line) => {
+    try { JSON.parse(line.trim()); return false; } catch { return true; }
+  }).join('\n');
+  const diagnostics = `${diagnosticStdout}\n${stripScreenAnsi(stderr)}`;
+  if (exitCode !== 0 && /Aside isn't running/i.test(diagnostics)) {
+    return { kind: 'not-running', hint: 'Aside 브라우저가 안 떠 있음 — Aside 브라우저를 켜고 다시 · 또는 `aside exec --host <host>`' };
+  }
+  if (exitCode !== 0 && /daemon auth challenge/i.test(diagnostics) && /timeout|timed out/i.test(diagnostics)) {
+    return { kind: 'auth-timeout', hint: 'Aside 인증 요청 시간 초과 — Aside 브라우저를 켜고 다시 · 또는 `aside exec --host <host>`' };
+  }
+  // Killed by our timeout with nothing printed: aside never answered — the browser daemon is not reachable.
+  if (timedOut && !stripScreenAnsi(stdout).trim()) {
+    return { kind: 'auth-timeout', hint: 'Aside 가 응답하지 않음 — Aside 브라우저가 떠 있는지 확인하고 다시 · 또는 `aside exec --host <host>`' };
+  }
+  const marker = stripScreenAnsi(stdout).trimEnd().match(/\[(ok|error)\s*\|[^\]]+\]\s*$/);
+  if (marker?.[1] === 'error') return { kind: 'repl-error' };
+  if (marker?.[1] === 'ok') return { kind: 'ok' };
+  return { kind: 'no-marker' };
+}