elanous 0.2.10 → 0.2.12

package/src/exec-requests/planner.ts

@@ -7,6 +7,7 @@ import { defaultGraphsDir } from '../self-implement/graph-templates.js';
 import { getElanousConfigDir } from '../elanous-config-dir.js';
 import type { ExecAttachment } from './store.js';
 import { debug } from '../debug/log.js';
+import { OUTPUT_KINDS, pickDefaultOutput, type OutputKind } from './default-outputs.js';
 
 export interface InstalledGraph {
   id: string;
@@ -21,6 +22,8 @@ export interface ExecPlanItem {
   title: string;
   graphId: string;
   inputs: Record<string, unknown>;
+  /** Planner fills this for every returned row; older injected plan fixtures may omit it. */
+  output?: OutputKind;
   reason?: string;
   /** A5b — indexes of earlier items whose results this item needs (it starts after they finish). */
   after?: number[];
@@ -147,7 +150,7 @@ export function latestFieldFolder(configRoot = getElanousConfigDir()): string |
 
 export function execPlanPrompt(text: string, graphs: readonly InstalledGraph[], seats: readonly string[], attachments: readonly ExecAttachment[] = [], fieldFolder: string | null = latestFieldFolder()): string {
   const supplied = attachments.map(({ name, path }) => `첨부: ${name} (${/\.(?:png|jpe?g|webp|gif|heic)$/i.test(name) ? '이미지' : '파일'}) — ${path}`).join('\n');
-  return `COO 역할. 요청을 실행 가능한 자리별 그래프로 나눠 맡겨라. JSON 배열만 출력: [{"seat":"자리","title":"할 일","graphId":"설치된 그래프 ID 또는 빈 문자열","inputs":{},"after":[]}]. 앞 항목의 결과가 있어야 할 수 있는 일(예: 점검·조사 «결과로» 쓰는 한 장 · 보고)은 after 에 그 앞 항목 번호(0부터)를 적는다 — 그 항목은 앞 항목이 끝난 뒤 그 결과를 받아 시작한다. 서로 기다릴 필요가 없으면 after 는 빈 배열. 자리 이름은 주어진 목록에서만, 그래프 ID는 설치된 목록에서만 고른다. 맞는 그래프가 없으면 graphId=""로 표시한다. 그래프에 inputKeys 가 있으면 inputs 를 그 키로만 채우되 한 줄과 아래 알려진 값에서 얻을 수 있는 값만 넣는다(모르는 값은 넣지 않는다). image/photo/file 입력에는 알맞은 첨부 경로를 쓸 수 있다. folder 입력에는 첨부가 없거나 첨부 사진이 그 현장 폴더 안에 있을 때만 오늘 현장 폴더를 쓸 수 있다. 다른 현장 사진이나 출처를 모르는 업로드 사진이 있으면 폴더를 추측하지 마라. 그 그래프가 꼭 받아야 할 값(예: 브랜드 이름 · 사진 파일)을 알 수 없으면 graphId=""로 두고 title 끝에 « — <무엇> 필요»를 적는다. 단순히 묻는 말에는 없는 그래프를 지어내지 말고 graphId=""로 표시한다. 없는 그래프나 산출을 지어내지 마라. 바깥 게시·발행·광고·결제는 승인 노드를 거치기 전 실행하면 안 된다.\n자리: ${JSON.stringify(seats)}\n실행 가능한 그래프: ${JSON.stringify(graphs.map(({ id, title, description, inputKeys }) => ({ id, title, description, ...(inputKeys ? { inputKeys } : {}) })))}\n${fieldFolder ? `알려진 값: 오늘 현장 폴더 = ${fieldFolder}\n` : ''}${supplied ? `${supplied}\n` : ''}한 줄: ${JSON.stringify(text)}`;
+  return `COO 역할. 요청을 실행 가능한 자리별 그래프로 나눠 맡겨라. JSON 배열만 출력: [{"seat":"자리","title":"할 일","graphId":"설치된 그래프 ID 또는 빈 문자열","inputs":{},"after":[]}]. 각 행에는 선택 칸 "output":"report|slides|research|post|video|answer"를 쓸 수 있다: ${Object.entries(OUTPUT_KINDS).map(([kind, entry]) => `${entry.guidance} = ${kind}${entry.fileName ? ` (${entry.fileName})` : ''}`).join(', ')}; 그 외 일은 report로 둔다. 앞 항목의 결과가 있어야 할 수 있는 일(예: 점검·조사 «결과로» 쓰는 한 장 · 보고)은 after 에 그 앞 항목 번호(0부터)를 적는다 — 그 항목은 앞 항목이 끝난 뒤 그 결과를 받아 시작한다. 서로 기다릴 필요가 없으면 after 는 빈 배열. 자리 이름은 주어진 목록에서만, 그래프 ID는 설치된 목록에서만 고른다. 맞는 그래프가 없으면 graphId=""로 표시한다. 그래프에 inputKeys 가 있으면 inputs 를 그 키로만 채우되 한 줄과 아래 알려진 값에서 얻을 수 있는 값만 넣는다(모르는 값은 넣지 않는다). image/photo/file 입력에는 알맞은 첨부 경로를 쓸 수 있다. folder 입력에는 첨부가 없거나 첨부 사진이 그 현장 폴더 안에 있을 때만 오늘 현장 폴더를 쓸 수 있다. 다른 현장 사진이나 출처를 모르는 업로드 사진이 있으면 폴더를 추측하지 마라. 그 그래프가 꼭 받아야 할 값(예: 브랜드 이름 · 사진 파일)을 알 수 없으면 graphId=""로 두고 title 끝에 « — <무엇> 필요»를 적는다. 단순히 묻는 말에는 없는 그래프를 지어내지 말고 graphId=""로 표시한다. 없는 그래프나 산출을 지어내지 마라. 바깥 게시·발행·광고·결제는 승인 노드를 거치기 전 실행하면 안 된다.\n자리: ${JSON.stringify(seats)}\n실행 가능한 그래프: ${JSON.stringify(graphs.map(({ id, title, description, inputKeys }) => ({ id, title, description, ...(inputKeys ? { inputKeys } : {}) })))}\n${fieldFolder ? `알려진 값: 오늘 현장 폴더 = ${fieldFolder}\n` : ''}${supplied ? `${supplied}\n` : ''}한 줄: ${JSON.stringify(text)}`;
 }
 
 export async function judgeExecPlan(text: string, graphs: readonly InstalledGraph[], seats: readonly string[], attachments: readonly ExecAttachment[] = [], fieldFolder: string | null = latestFieldFolder()): Promise<unknown> {
@@ -183,6 +186,11 @@ export async function planExecRequest(text: string, deps: {
       ? [...new Set(row.after.filter((n): n is number => Number.isInteger(n) && (n as number) >= 0 && (n as number) < index))]
       : [];
     const graph = known.get(row.graphId);
+    const modelOutput = typeof row.output === 'string' && Object.hasOwn(OUTPUT_KINDS, row.output)
+      ? row.output as OutputKind : undefined;
+    const picked = modelOutput ?? pickDefaultOutput(row.title).kind;
+    const output = picked === 'video' && !graph ? 'report' : picked;
+    debug.log('exec.plan', 'default-output', { kind: output, source: modelOutput === output ? 'model' : 'rule' });
     const inputs = { ...row.inputs as Record<string, unknown> };
     let folderReason: string | undefined;
     if (graph) {
@@ -206,7 +214,7 @@ export async function planExecRequest(text: string, deps: {
       }
     }
     return {
-      seat: row.seat, title: row.title.trim(), graphId: row.graphId, inputs,
+      seat: row.seat, title: row.title.trim(), graphId: row.graphId, inputs, output,
       ...(after.length ? { after } : {}),
       ...(!graph ? { reason: `${row.seat}: 요청에 맞는 설치된 실행 그래프가 없습니다` } : folderReason ? { reason: folderReason } : {}),
     };

package/src/exec-requests/runner.ts

@@ -9,6 +9,12 @@ import { installedGraphs, planExecRequest, type ExecPlanItem, type InstalledGrap
 import { ExecRequestStore, type ExecAttachment, type ExecRequest, type ExecResult, type ExecSeat } from './store.js';
 import { answerAsSeat } from '../intake-plane/seat-answer.js';
 import { redactSecrets } from '../task-cards/card-store.js';
+import { recordOutput } from '../outputs/ledger.js';
+import type { OutputKind } from './default-outputs.js';
+
+function recordResult(result: ExecResult, id: string, root: string, kind: OutputKind | 'file'): void {
+  recordOutput({ source: 'exec', sourceId: id, seat: result.seat, title: result.title, url: result.url, kind }, root);
+}
 
 export interface ExecRunnerDeps {
   store?: ExecRequestStore;
@@ -137,14 +143,19 @@ function syncRun(item: ExecRequest, seat: ExecSeat, state: GraphRunState, root:
     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);
+      if (result && !item.results.some(existing => existing.seat === result.seat && existing.url === result.url)) {
+        item.results.push(result);
+        recordResult(result, item.id, root, seat.output ?? 'file');
+      }
     }
   }
   if (seat.status === 'done' && !item.results.some(existing => existing.seat === seat.seat)) {
     const file = textResultFile(seat, state, root);
     const result = file ? resultOf({ file, title: seat.title }, seat, item.id, root) : null;
-    if (result) item.results.push(result);
-    else {
+    if (result) {
+      item.results.push(result);
+      recordResult(result, item.id, root, seat.output ?? 'file');
+    } else {
       const keys = [...new Set((state.nodes ?? []).flatMap(node => Object.keys(lastJsonObject(node.output) ?? {})))];
       debug.log('exec.result', 'none', { seat: seat.seat, graphId: seat.graphId, keys });
     }
@@ -288,7 +299,7 @@ export class ExecRequestRunner {
             reason: plan.reason ?? `${plan.seat}: 요청에 맞는 설치된 실행 그래프가 없습니다` });
           continue;
         }
-        const seat: ExecSeat = { seat: plan.seat, title: plan.title, status: 'done', graphId: 'seat-answer', runId: randomUUID() };
+        const seat: ExecSeat = { seat: plan.seat, title: plan.title, status: 'done', graphId: 'seat-answer', runId: randomUUID(), ...(plan.output ? { output: plan.output } : {}) };
         const dir = join(this.root, 'graph-runs', seat.graphId);
         const statePath = join(dir, `${seat.runId}.json`);
         const artifactDir = join(dir, `${seat.runId}.json.artifacts`);
@@ -299,7 +310,10 @@ export class ExecRequestRunner {
         writeFileSync(statePath, JSON.stringify(state), { mode: 0o600 });
         item.seats.push(seat);
         const result = resultOf({ file, title: answered.title }, seat, id, this.root);
-        if (result) item.results.push(result);
+        if (result) {
+          item.results.push(result);
+          recordResult(result, item.id, this.root, seat.output ?? 'file');
+        }
       }
       item.status = 'running';
       aggregate(item);
@@ -307,7 +321,7 @@ export class ExecRequestRunner {
       return;
     }
     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.after?.length ? { after: plan.after } : {}),
+      runId: plan.reason || !byId.has(plan.graphId) ? '' : randomUUID(), inputs: plan.inputs, ...(plan.output ? { output: plan.output } : {}), ...(plan.after?.length ? { after: plan.after } : {}),
       ...(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 })) });

package/src/exec-requests/store.ts

@@ -2,6 +2,7 @@ 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';
+import type { OutputKind } from './default-outputs.js';
 
 export type SeatStatus = 'waiting' | 'running' | 'done' | 'failed';
 export interface ExecSeat {
@@ -10,6 +11,8 @@ export interface ExecSeat {
   status: SeatStatus;
   graphId: string;
   runId: string;
+  /** Requested output category, distinct from the result file MIME kind. */
+  output?: OutputKind;
   inputs?: Record<string, unknown>;
   reason?: string;
   /** A5b — indexes of earlier seats this seat waits for. */

package/src/execution-loop/launch-gate.ts

@@ -0,0 +1,109 @@
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { debug } from '../debug/log.js';
+import { extractVerbatimOriginalAsk } from '../self-implement/goal-author.js';
+import { loadRunLedger } from '../self-implement/run-ledger.js';
+import { queryRunningRuns, type QueriedRunningRunsResult } from '../self-implement/running-runs.js';
+import type { BudgetDecision } from '../self-implement/budget-gate.js';
+
+export type ActiveRunsForGoal = readonly string[] | 'unknown';
+
+/** Match an un-authored CLI request to the verbatim ask recorded in an authored run. */
+export function launchRequestId(text: string): string {
+  return `request-${createHash('sha256').update(text).digest('hex').slice(0, 32)}`;
+}
+
+export interface ActiveRunsForGoalDeps {
+  queryRuns?: () => QueriedRunningRunsResult;
+  loadLedger?: typeof loadRunLedger;
+  readGoalDocument?: (path: string) => string;
+}
+
+/** Only a live process with an exact goal ID or verbatim authored ask is a duplicate. Incomplete observation is not absence. */
+export function activeRunsForGoal(goalId: string, deps: ActiveRunsForGoalDeps = {}): ActiveRunsForGoal {
+  try {
+    const observation = (deps.queryRuns ?? (() => queryRunningRuns({ includeTest: true, caller: 'execution-loop.launch-gate', noCache: true })))();
+    const loadLedger = deps.loadLedger ?? loadRunLedger;
+    const readGoalDocument = deps.readGoalDocument ?? ((path: string) => readFileSync(path, 'utf8'));
+    let unknown = observation.completeness !== 'complete' || observation.pty.unreadable.length > 0;
+    const unknownReasons = new Set<string>();
+    if (observation.completeness !== 'complete') unknownReasons.add(`ledger observation ${observation.completeness}`);
+    for (const root of observation.pty.unreadable) unknownReasons.add(`unreadable PTY: ${root}`);
+    const active = new Set<string>();
+    for (const run of observation.entries) {
+      if (run.status === 'ended-unclosed') continue;
+      if (run.ledgerDirectories.length === 0) { unknown = true; unknownReasons.add(`${run.runId}: ledger directory absent`); continue; }
+      let identified = false;
+      for (const directory of run.ledgerDirectories) {
+        try {
+          const ledger = loadLedger(run.runId, directory);
+          if (ledger === null) { unknown = true; unknownReasons.add(`${run.runId}: ledger unavailable`); continue; }
+          const ids = new Set(ledger.flatMap((entry) => entry.goalId ? [entry.goalId] : []));
+          if (ids.size !== 1) { unknown = true; unknownReasons.add(`${run.runId}: expected one goalId, found ${ids.size}`); continue; }
+          identified = true;
+          let matches = ids.has(goalId);
+          if (!matches && goalId.startsWith('request-') && run.status === 'running' && run.ptyRefs.length > 0) {
+            const document = ledger.find((entry) => entry.event === 'start')?.data.goalFile;
+            if (typeof document === 'string') {
+              try {
+                const ask = extractVerbatimOriginalAsk(readGoalDocument(document));
+                matches = ask?.range !== undefined && launchRequestId(ask.ask) === goalId;
+              } catch { unknown = true; unknownReasons.add(`${run.runId}: goal document unreadable`); }
+            }
+          }
+          if (matches) {
+            if (run.status === 'running' && run.ptyRefs.length > 0) active.add(run.runId);
+            else { unknown = true; unknownReasons.add(`${run.runId}: matching ledger without live PTY`); }
+          }
+        } catch { unknown = true; unknownReasons.add(`${run.runId}: ledger read failed`); }
+      }
+      if (!identified) unknown = true;
+    }
+    // Positive evidence wins even if a different process or store is unreadable.
+    if (active.size > 0) return [...active].sort();
+    if (unknown) {
+      try { debug.log('execution-loop.launch-gate', 'active-runs-unknown', { goalId, reasons: [...unknownReasons] }); } catch { /* observation is fail-soft */ }
+      return 'unknown';
+    }
+    return [];
+  } catch (error) {
+    try { debug.log('execution-loop.launch-gate', 'active-runs-unknown', { goalId, reasons: [error instanceof Error ? error.message : String(error)] }); } catch { /* observation is fail-soft */ }
+    return 'unknown';
+  }
+}
+
+export interface PreLaunchGateInput {
+  goalId: string;
+  budget?: BudgetDecision | 'unknown';
+  forceLaunch?: boolean;
+}
+
+export interface PreLaunchGateDeps extends ActiveRunsForGoalDeps {
+  activeRuns?: (goalId: string) => ActiveRunsForGoal;
+}
+
+export interface PreLaunchGateDecision {
+  action: 'proceed' | 'blocked-duplicate' | 'blocked-budget' | 'wait-reset';
+  sameGoalActiveRuns: ActiveRunsForGoal;
+  budget: BudgetDecision | 'unknown';
+  reason: string;
+}
+
+/** Force bypasses only a duplicate observation, never an exhausted budget. */
+export function preLaunchGate(input: PreLaunchGateInput, deps: PreLaunchGateDeps = {}): PreLaunchGateDecision {
+  const decision = decidePreLaunch(input, deps);
+  debug.log('execution-loop.launch-gate', 'decision', { goalId: input.goalId, action: decision.action, sameGoalActiveRuns: decision.sameGoalActiveRuns, budget: decision.budget === 'unknown' ? 'unknown' : decision.budget.action, forceLaunch: input.forceLaunch === true, reason: decision.reason });
+  return decision;
+}
+
+function decidePreLaunch(input: PreLaunchGateInput, deps: PreLaunchGateDeps): PreLaunchGateDecision {
+  const sameGoalActiveRuns = (deps.activeRuns ?? ((goalId) => activeRunsForGoal(goalId, deps)))(input.goalId);
+  const budget = input.budget ?? 'unknown';
+  if (budget !== 'unknown' && (budget.action === 'stop' || budget.action === 'wait-reset')) {
+    return { action: budget.action === 'stop' ? 'blocked-budget' : 'wait-reset', sameGoalActiveRuns, budget, reason: budget.reasons.join(' · ') || `budget: ${budget.action}` };
+  }
+  if (sameGoalActiveRuns !== 'unknown' && sameGoalActiveRuns.length > 0 && !input.forceLaunch) {
+    return { action: 'blocked-duplicate', sameGoalActiveRuns, budget, reason: `same-goal active runs: ${sameGoalActiveRuns.join(', ')}` };
+  }
+  return { action: 'proceed', sameGoalActiveRuns, budget, reason: sameGoalActiveRuns === 'unknown' ? 'active runs unknown' : input.forceLaunch && sameGoalActiveRuns.length > 0 ? 'duplicate overridden by force-launch' : 'no confirmed duplicate' };
+}

package/src/field/field-reel.ts

@@ -7,6 +7,7 @@ import { debug } from '../debug/log.js';
 import { mergeCapturedPath } from '../shell-env-bootstrap.js';
 import { listFieldMedia } from './field-media.js';
 import { startFieldFeed, type FieldFeedStart } from './field-feed-auto.js';
+import { recordOutput } from '../outputs/ledger.js';
 
 export interface FieldReelResult { ok: boolean; file?: string; seconds: number; error?: string; feed?: FieldFeedStart }
 export type FieldReelRunner = (dir: string, opts: { title: string; sub: string; mode?: 'standard' | 'instant' }) => Promise<FieldReelResult>;
@@ -137,6 +138,7 @@ async function render(dir: string, job: Job): Promise<void> {
   // 현재 렌더의 수신자 스냅샷. 렌더 중 업로드의 수신자는 다음 렌더로 넘긴다.
   const callbacks = job.callbacks;
   const renderOpts = job.opts;
+  let reelTitle = renderOpts.title || event;
   job.callbacks = new Map();
   writeStatus(dir, { state: 'rendering', items, startedAt });
   mkdirSync(join(dir, 'reel'), { recursive: true }); // 실행기 계약 — 산출 폴더는 있다(reel.sh 는 스스로 다시 만든다)
@@ -148,8 +150,9 @@ async function render(dir: string, job: Job): Promise<void> {
     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; }
+    reelTitle = titleLines[0]?.trim() || renderOpts.title || event;
     result = await (renderOpts.runner ?? defaultFieldReelRunner)(dir, {
-      title: titleLines[0]?.trim() || renderOpts.title || event,
+      title: reelTitle,
       sub: titleLines[1]?.trim() || renderOpts.sub || sub,
       ...(renderOpts.mode ? { mode: renderOpts.mode } : {}),
     });
@@ -163,6 +166,7 @@ async function render(dir: string, job: Job): Promise<void> {
   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 && result.file) recordOutput({ source: 'field-reel', sourceId: event, kind: 'video', title: reelTitle, path: result.file });
   if (result.ok) {
     // EV10b: 엔진이 timeline.json 에 남긴 비전 호출 수·성공·«현장 N» 강등·걸린 ms — codex 잔량과 겹치므로 관측한다(OP 10-01).
     let cardsCache: 'hit' | 'miss' | 'n/a' = 'n/a';

package/src/field-note/index.ts

@@ -0,0 +1,201 @@
+export interface FieldPhoto {
+  file: string;
+  /** EXIF `YYYY:MM:DD HH:mm:ss`, ISO local time, or ISO time with an offset. */
+  exifTakenAt?: string | null;
+}
+
+export interface TranscriptEntry {
+  speaker: string;
+  timestamp: string;
+  text: string;
+}
+
+export interface FieldNoteOptions {
+  /** Minutes east of UTC for offset-free EXIF and transcript timestamps; KST by default. */
+  timeZoneOffsetMinutes?: number;
+  /** Minutes added to every dated photo after interpreting its EXIF timestamp. */
+  photoCorrectionMinutes?: number;
+  /** Maximum gap between consecutive photos in the same scene; 15 minutes by default. */
+  sceneGapMinutes?: number;
+}
+
+export interface TimedPhoto extends FieldPhoto {
+  takenAt: string;
+}
+
+export interface FieldScene {
+  start: string;
+  end: string;
+  photos: TimedPhoto[];
+  transcript: TranscriptEntry[];
+}
+
+export interface FieldTimeline {
+  scenes: FieldScene[];
+  undatedPhotos: FieldPhoto[];
+  /** Chronological entries when there are no dated photos to anchor a scene. */
+  transcriptWithoutPhotos: TranscriptEntry[];
+  timeZoneOffsetMinutes: number;
+}
+
+export interface FieldNoteLlm {
+  /** Only used for a raw transcript string; JSON entries bypass transcription. */
+  transcribe?: (source: string) => Promise<TranscriptEntry[]>;
+  summarize?: (entries: readonly TranscriptEntry[]) => Promise<string>;
+}
+
+const MINUTE = 60_000;
+
+function validOffset(minutes: number): boolean {
+  return Number.isInteger(minutes) && minutes >= -14 * 60 && minutes <= 14 * 60;
+}
+
+function parseTime(value: string, offsetMinutes: number): number | null {
+  const input = value.trim();
+  const local = /^(\d{4})[:-](\d{2})[:-](\d{2})[ T](\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?$/.exec(input);
+  const zoned = local ? null : /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d{1,3}))?(?:Z|[+-]\d{2}:\d{2})$/.exec(input);
+  const match = local ?? zoned;
+  if (!match) return null;
+  const [, year, month, day, hour, minute, second, fraction] = match;
+  if (+year! < 100) return null;
+  const milliseconds = fraction ? Number(fraction.padEnd(3, '0')) : 0;
+  const utc = Date.UTC(+year!, +month! - 1, +day!, +hour!, +minute!, +second!, milliseconds);
+  const date = new Date(utc);
+  if (date.getUTCFullYear() !== +year! || date.getUTCMonth() + 1 !== +month! ||
+      date.getUTCDate() !== +day! || date.getUTCHours() !== +hour! ||
+      date.getUTCMinutes() !== +minute! || date.getUTCSeconds() !== +second!) return null;
+  if (local) return utc - offsetMinutes * MINUTE;
+  // Offset-bearing ISO timestamps are absolute instants, not local wall-clock readings.
+  const parsed = Date.parse(input);
+  return Number.isFinite(parsed) ? parsed : null;
+}
+
+function iso(ms: number): string {
+  return new Date(ms).toISOString();
+}
+
+/** Pure alignment: neither mutates its inputs nor consults the machine clock/timezone. */
+export function alignFieldNote(
+  photos: readonly FieldPhoto[],
+  transcript: readonly TranscriptEntry[],
+  options: FieldNoteOptions = {},
+): FieldTimeline {
+  const offset = options.timeZoneOffsetMinutes ?? 540;
+  const correction = options.photoCorrectionMinutes ?? 0;
+  const gap = options.sceneGapMinutes ?? 15;
+  if (!validOffset(offset) || !Number.isFinite(correction) || !Number.isFinite(gap) || gap < 0) {
+    throw new RangeError('Invalid field-note timezone, photo correction, or scene gap');
+  }
+  const dated: Array<{ photo: TimedPhoto; time: number; order: number }> = [];
+  const undatedPhotos: FieldPhoto[] = [];
+  photos.forEach((photo, order) => {
+    const parsed = photo.exifTakenAt ? parseTime(photo.exifTakenAt, offset) : null;
+    if (parsed === null) undatedPhotos.push({ ...photo });
+    else dated.push({ photo: { ...photo, takenAt: iso(parsed + correction * MINUTE) }, time: parsed + correction * MINUTE, order });
+  });
+  dated.sort((a, b) => a.time - b.time || a.order - b.order);
+
+  const groups: typeof dated[] = [];
+  for (const item of dated) {
+    const last = groups.at(-1);
+    if (!last || item.time - last[last.length - 1]!.time > gap * MINUTE) groups.push([item]);
+    else last.push(item);
+  }
+
+  const entries = transcript.map((entry, order) => {
+    const time = parseTime(entry.timestamp, offset);
+    if (time === null) throw new RangeError(`Invalid transcript timestamp at index ${order}: ${entry.timestamp}`);
+    return { entry: { ...entry }, time, order };
+  }).sort((a, b) => a.time - b.time || a.order - b.order);
+
+  // An utterance belongs to the scene whose photo span [first, last] is nearest in time (inside the span = distance 0);
+  // a tie goes to the earlier scene. So a 10:55 line next to an 11:00 photo joins the 11:00 scene, not 09:00.
+  const spans = groups.map((group) => ({ start: group[0]!.time, end: group[group.length - 1]!.time }));
+  const sceneEntries: Array<Array<(typeof entries)[number]>> = groups.map(() => []);
+  for (const item of entries) {
+    if (groups.length === 0) break;
+    let best = 0;
+    let bestDistance = Infinity;
+    spans.forEach((span, index) => {
+      const distance = item.time < span.start ? span.start - item.time : item.time > span.end ? item.time - span.end : 0;
+      if (distance < bestDistance) { best = index; bestDistance = distance; }
+    });
+    sceneEntries[best]!.push(item);
+  }
+  const scenes = groups.map((group, index) => {
+    const assigned = sceneEntries[index]!;
+    const times = [group[0]!.time, group[group.length - 1]!.time, ...assigned.map((item) => item.time)];
+    return {
+      start: iso(Math.min(...times)), end: iso(Math.max(...times)),
+      photos: group.map((item) => item.photo), transcript: assigned.map((item) => item.entry),
+    };
+  });
+  return {
+    scenes, undatedPhotos,
+    transcriptWithoutPhotos: groups.length === 0 ? entries.map((item) => item.entry) : [],
+    timeZoneOffsetMinutes: offset,
+  };
+}
+
+function localTime(instant: string, offset: number): string {
+  const shifted = new Date(Date.parse(instant) + offset * MINUTE).toISOString().slice(0, 16).replace('T', ' ');
+  const sign = offset >= 0 ? '+' : '-';
+  const hours = String(Math.floor(Math.abs(offset) / 60)).padStart(2, '0');
+  const minutes = String(Math.abs(offset) % 60).padStart(2, '0');
+  return `${shifted} UTC${sign}${hours}:${minutes}`;
+}
+
+function photoLine(photo: FieldPhoto, label: string): string {
+  const file = encodeURIComponent(photo.file).replace(/%2F/gi, '/').replace(/[()]/g, (char) => char === '(' ? '%28' : '%29');
+  const alt = photo.file.split(/[\\/]/).at(-1)?.replace(/\]/g, '\\]') ?? photo.file;
+  return `- ${label} ![${alt}](<${file}>)`;
+}
+
+/** Synchronous, side-effect-free Markdown rendering; summaries are optional placeholders. */
+export function renderFieldNote(timeline: FieldTimeline, summaries: readonly string[] = []): string {
+  if (summaries.length > timeline.scenes.length + (timeline.transcriptWithoutPhotos.length ? 1 : 0)) {
+    throw new RangeError('More summaries than transcript sections');
+  }
+  const lines = ['# 현장 노트', ''];
+  timeline.scenes.forEach((scene, i) => {
+    lines.push(`## 장면 ${i + 1} · ${localTime(scene.start, timeline.timeZoneOffsetMinutes)} – ${localTime(scene.end, timeline.timeZoneOffsetMinutes)}`);
+    lines.push('', '### 전사 요약', summaries[i]?.trim() || '_(전사 요약 자리)_', '', '### 사진');
+    for (const photo of scene.photos) lines.push(photoLine(photo, localTime(photo.takenAt, timeline.timeZoneOffsetMinutes)));
+    lines.push('');
+  });
+  if (timeline.transcriptWithoutPhotos.length) {
+    lines.push('## 사진 없는 전사', '', '### 전사 요약',
+      summaries[timeline.scenes.length]?.trim() || '_(전사 요약 자리)_', '', '### 시간순 전사');
+    for (const entry of timeline.transcriptWithoutPhotos) {
+      lines.push(`- ${entry.timestamp} · ${entry.speaker}: ${entry.text}`);
+    }
+    lines.push('');
+  }
+  if (timeline.undatedPhotos.length) {
+    lines.push('## 시각 없음', '');
+    for (const photo of timeline.undatedPhotos) lines.push(photoLine(photo, '시각 없음'));
+    lines.push('');
+  }
+  return lines.join('\n').trimEnd() + '\n';
+}
+
+/** LLM calls are supplied by the caller; JSON transcripts need no transcription call. */
+export async function generateFieldNote(
+  photos: readonly FieldPhoto[],
+  transcript: readonly TranscriptEntry[] | string,
+  llm: FieldNoteLlm = {},
+  options: FieldNoteOptions = {},
+): Promise<string> {
+  let entries: readonly TranscriptEntry[];
+  if (typeof transcript === 'string') {
+    if (!llm.transcribe) throw new Error('A transcribe dependency is required for raw transcript input');
+    entries = await llm.transcribe(transcript);
+  } else entries = transcript;
+  const timeline = alignFieldNote(photos, entries, options);
+  const sections = timeline.scenes.map((scene) => scene.transcript);
+  if (timeline.transcriptWithoutPhotos.length) sections.push(timeline.transcriptWithoutPhotos);
+  const summaries = llm.summarize
+    ? await Promise.all(sections.map((segment) => segment.length ? llm.summarize!(segment) : ''))
+    : [];
+  return renderFieldNote(timeline, summaries);
+}

package/src/field-note/telegram.ts

@@ -0,0 +1,142 @@
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, unlinkSync, writeFileSync } from 'node:fs';
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import { spawnSync } from 'node:child_process';
+import { generateFieldNote, type FieldPhoto, type TranscriptEntry } from './index.js';
+import { transcribeFieldAudio, type FieldAudio, type TranscriptionEngine } from './transcribe.js';
+import type { TgIncoming, TgIncomingAttachment } from '../telegram.js';
+
+interface SavedMedia { kind: 'photo' | 'voice' | 'audio'; file: string; receivedAt: string; messageId: number }
+interface NoteWindow { title: string; start: string; end: string; status: 'open' | 'done'; openedBy: number; media: SavedMedia[]; notePath?: string }
+
+export interface TelegramFieldNoteDeps {
+  rootDir: string;
+  download: (fileId: string) => Promise<{ localPath: string }>;
+  reply: (ctx: TgIncoming, text: string) => Promise<void>;
+  engine?: TranscriptionEngine;
+  decodeAudio?: (file: string, recordedAt: string) => FieldAudio;
+  now?: () => Date;
+}
+
+/** Decode Telegram's Ogg/Opus (or audio file) into NOTE3a's 16kHz mono float PCM. */
+export function decodeFieldAudio(file: string, recordedAt: string): FieldAudio {
+  const result = spawnSync('ffmpeg', ['-v', 'error', '-i', file, '-f', 'f32le', '-ac', '1', '-ar', '16000', 'pipe:1'], { maxBuffer: 1024 * 1024 * 1024 });
+  if (result.status !== 0) throw new Error(`음성 디코딩 실패: ${result.stderr.toString().trim() || result.error?.message || 'ffmpeg'}`);
+  if (result.stdout.length % 4) throw new Error('음성 디코딩 실패: 잘못된 PCM 길이');
+  const bytes = result.stdout;
+  const samples = new Float32Array(bytes.length / 4);
+  for (let i = 0; i < samples.length; i++) samples[i] = bytes.readFloatLE(i * 4);
+  return { samples, sampleRate: 16000, recordedAt };
+}
+
+function windowPath(ctx: TgIncoming, root: string): string {
+  const bot = (ctx.botId ?? 'bot').replace(/[^a-zA-Z0-9_-]/g, '_');
+  return join(root, 'field-notes', 'telegram', bot, String(ctx.chatId), String(ctx.threadId ?? 0), String(ctx.userId), 'window.json');
+}
+
+function readWindow(path: string): NoteWindow | null {
+  return existsSync(path) ? JSON.parse(readFileSync(path, 'utf8')) as NoteWindow : null;
+}
+
+function saveWindow(path: string, window: NoteWindow): void {
+  mkdirSync(join(path, '..'), { recursive: true });
+  const temp = `${path}.${randomUUID()}.tmp`;
+  try {
+    writeFileSync(temp, JSON.stringify(window, null, 2) + '\n');
+    renameSync(temp, path);
+  } finally {
+    if (existsSync(temp)) unlinkSync(temp);
+  }
+}
+
+function parseWindow(text: string, now: Date): { title: string; start: string; end: string } | null {
+  const match = /^노트:\s*(.+?)\s+(\d{2}):(\d{2})\s*[~～]\s*(\d{2}):(\d{2})$/.exec(text.trim());
+  if (!match) return null;
+  const [, title, h1, m1, h2, m2] = match;
+  if (!Number.isFinite(now.getTime()) || +h1! > 23 || +h2! > 23 || +m1! > 59 || +m2! > 59) return null;
+  const local = new Date(now.getTime() + 9 * 60 * 60_000).toISOString().slice(0, 10);
+  const start = new Date(`${local}T${h1}:${m1}:00+09:00`);
+  const end = new Date(`${local}T${h2}:${m2}:00+09:00`);
+  if (end <= start) return null;
+  return { title: title!.trim(), start: start.toISOString(), end: end.toISOString() };
+}
+
+export async function handleTelegramFieldNote(ctx: TgIncoming, deps: TelegramFieldNoteDeps): Promise<boolean> {
+  const text = ctx.text.trim();
+  const path = windowPath(ctx, deps.rootDir);
+  if (text.startsWith('노트:')) {
+    const parsed = parseWindow(text, ctx.receivedAt ? new Date(ctx.receivedAt) : (deps.now ?? (() => new Date()))());
+    if (!parsed) await deps.reply(ctx, '노트 시간 형식: 노트: 세미나 18:00~20:00');
+    else {
+      const previous = readWindow(path);
+      if (previous?.status === 'open' && previous.media.length) {
+        await deps.reply(ctx, '열린 노트 창이 있습니다 — 먼저 노트 만들기를 완료하세요.');
+        return true;
+      }
+      saveWindow(path, { ...parsed, status: 'open', openedBy: ctx.messageId, media: [] });
+      await deps.reply(ctx, `노트 창 열림 · ${parsed.title} · ${text.slice(text.lastIndexOf(' ') + 1)}`);
+    }
+    return true;
+  }
+  if (text !== '노트 만들기' && !ctx.attachments.some((a) => a.kind === 'photo' || a.kind === 'voice' || a.kind === 'audio')) return false;
+  const window = readWindow(path);
+  if (text === '노트 만들기') {
+    if (!window || window.status !== 'open') {
+      await deps.reply(ctx, '열린 노트 창 없음');
+      return true;
+    }
+    if (window.media.some((item) => item.kind !== 'photo') && !deps.engine) {
+      await deps.reply(ctx, '전사 엔진 없음 — NOTE3a 전사 엔진을 설정해 주세요. 모은 파일은 유지됩니다.');
+      return true;
+    }
+    try {
+      const photos: FieldPhoto[] = window.media.filter((item) => item.kind === 'photo').map((item) => ({ file: item.file, exifTakenAt: item.receivedAt }));
+      const transcript: TranscriptEntry[] = [];
+      for (const item of window.media.filter((m) => m.kind !== 'photo')) {
+        const audio = (deps.decodeAudio ?? decodeFieldAudio)(item.file, item.receivedAt);
+        transcript.push(...await transcribeFieldAudio(audio, deps.engine!));
+      }
+      const markdown = await generateFieldNote(photos, transcript, {
+        summarize: async (entries) => entries.map((entry) => `${entry.timestamp} · ${entry.speaker}: ${entry.text}`).join('\n'),
+      });
+      const notePath = join(path, '..', `note-${window.openedBy}.md`);
+      const noteTemp = `${notePath}.${randomUUID()}.tmp`;
+      try {
+        writeFileSync(noteTemp, `# ${window.title}\n\n시간 창: ${window.start} ~ ${window.end}\n\n${markdown}`);
+        renameSync(noteTemp, notePath);
+      } finally {
+        if (existsSync(noteTemp)) unlinkSync(noteTemp);
+      }
+      saveWindow(path, { ...window, status: 'done', notePath });
+      await deps.reply(ctx, `노트 생성 · ${notePath}`);
+    } catch (error) {
+      await deps.reply(ctx, `노트 생성 실패 · ${error instanceof Error ? error.message : String(error)}`);
+    }
+    return true;
+  }
+  if (!window || window.status !== 'open') return false;
+  const media = ctx.attachments.filter((a): a is TgIncomingAttachment & { kind: 'photo' | 'voice' | 'audio' } =>
+    a.kind === 'photo' || a.kind === 'voice' || a.kind === 'audio');
+  if (!media.length) return false;
+  const receivedAt = ctx.receivedAt ?? (deps.now ?? (() => new Date()))().toISOString();
+  if (ctx.messageId <= window.openedBy || receivedAt < window.start || receivedAt > window.end) return false;
+  const dir = join(path, '..', 'media');
+  mkdirSync(dir, { recursive: true });
+  try {
+    for (const [index, item] of media.entries()) {
+      if (window.media.some((saved) => saved.messageId === ctx.messageId && saved.kind === item.kind)) continue;
+      const downloaded = await deps.download(item.fileId);
+      const extension = item.kind === 'photo' ? 'jpg' : item.kind === 'voice' ? 'ogg'
+        : item.mimeType === 'audio/mpeg' ? 'mp3' : item.mimeType === 'audio/ogg' ? 'ogg' : 'audio';
+      const file = join(dir, `${ctx.messageId}-${index}.${extension}`);
+      try { copyFileSync(downloaded.localPath, file); }
+      finally { try { unlinkSync(downloaded.localPath); } catch { /* download may be reused by the caller */ } }
+      window.media.push({ kind: item.kind, file, receivedAt, messageId: ctx.messageId });
+      saveWindow(path, window);
+    }
+    await deps.reply(ctx, `노트 파일 모음 · 사진 ${window.media.filter((m) => m.kind === 'photo').length}장 · 음성 ${window.media.filter((m) => m.kind !== 'photo').length}개`);
+  } catch (error) {
+    await deps.reply(ctx, `노트 파일 저장 실패 · ${error instanceof Error ? error.message : String(error)}`);
+  }
+  return true;
+}