aimakeall-mcp 0.12.0 → 0.13.0

package/README.md

@@ -16,7 +16,7 @@ Claude Code·Codex 같은 MCP 클라이언트에서 자연어로 AImakeAll 영
   "mcpServers": {
     "aimakeall": {
       "command": "npx",
-      "args": ["-y", "aimakeall-mcp@0.12.0"],
+      "args": ["-y", "aimakeall-mcp@0.13.0"],
       "env": { "AIMAKEALL_PAT": "aio_pat_..." }
     }
   }
@@ -55,17 +55,26 @@ plan_shorts_video → (씬마다) generate_scene_image → get_generation_job(co
 
 ## 제작 스타일 유지와 컷컴포저 편집 (0.12.0)
 
-아래의 이미지 소스·영상 표현 선택과 TTS 자동 우선순위는 MCP 0.12.0과 대응 서버·컴패니언 런타임이 필요합니다. 기존 MCP 설정의 버전을 `aimakeall-mcp@0.12.0`으로 바꾸고 클라이언트를 다시 연결하세요. 토큰은 그대로 사용할 수 있습니다. 컴패니언에서 렌더 기능 업데이트를 요청하면 최신 설치 프로그램으로 업데이트하세요.
+아래의 이미지 소스·영상 표현 선택과 TTS 자동 우선순위는 MCP 0.12.0부터 지원합니다. 현재 설정은 `aimakeall-mcp@0.13.0`으로 바꾸고 클라이언트를 다시 연결하세요. 토큰은 그대로 사용할 수 있습니다. 대응 서버와 컴패니언 런타임도 필요하며, 컴패니언에서 렌더 기능 업데이트를 요청하면 최신 설치 프로그램으로 업데이트하세요.
 
 - `plan_shorts_video({categoryId:"viral-shorts",durationTargetSec:40,...})`는 `productionProfile`과 `productionPath`를 반환합니다. 이후 추천·TTS·스티치에 **가장 최근 반환된 `productionPath`**를 전달하세요. 제작별 불변 파일이라 동시에 만든 다른 영상의 스타일과 섞이지 않습니다.
 - 바이럴·커뮤니티 프로필은 `casual-social`을 사용합니다. 사건 소재라도 뉴스 브리핑형으로 자동 변경하지 않습니다. TTS의 `text`를 생략하면 저장된 기획 대본을 사용하며, 분명한 뉴스체 회귀는 과금 전 `422 NARRATION_STYLE_DRIFT`로 중단합니다. 자막은 실제 발화와 일치시켜야 하며 자극성을 위해 사실·인용·피해 내용을 꾸미면 안 됩니다.
-- 보이스 공급자 자동 선택은 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2 순서입니다. 키/실행 가능 상태를 먼저 확인하며 유료 합성 오류 뒤 다른 공급자로 몰래 재합성하지 않습니다. 대화형/소셜 목소리를 우선하되 실제 청취 결과라고 주장하지 않습니다. ElevenLabs 외의 공급자 자막은 실제 오디오 길이 기반 추정 타이밍임을 표시하므로 최종 동기화를 확인하세요.
+- 보이스 공급자 자동 선택은 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2 순서입니다. 키/실행 가능 상태를 먼저 확인하며, 0.13.0부터 확정된 일시 실패에 한해 아래의 안전한 폴백 규칙을 적용합니다. 명시한 목소리는 승인된 대체 보이스 없이 바꾸지 않습니다. 대화형/소셜 목소리를 우선하되 실제 청취 결과라고 주장하지 않습니다. ElevenLabs 외의 공급자 자막은 실제 오디오 길이 기반 추정 타이밍임을 표시하므로 최종 동기화를 확인하세요.
 - `list_composer_presets`에서 실제 편집기의 프리셋과 모션을 조회하세요. `titleStylePresetId`, `subtitleStylePresetId`, `subtitleLines[].stylePresetId`, `titleStyle`, `subtitleStyle`, `subtitleLines[].style`로 서로 다른 제목/본문 계층과 장면별 강조를 설정합니다. 명시 스타일 > 선택 프리셋 > 프로필 기본값 순서입니다.
 - `search_composer_assets` 또는 무료 `recommend_composer_overlays`로 관련 소재를 검토하고 선택한 `assetId`에 `startSec/endSec`, `xPct/yPct`, `widthPct`를 붙여 `stitch_timeline.overlays`로 전달하세요. 좌표는 화면의 백분율 중심점이며 `opacity`는 0~100입니다. SVG 아이콘·이모지, GIF/비디오, 효과음을 타임라인 레이어로 처리합니다. 사건·피해자에 조롱 밈을 강제로 붙이지 않으며, 출처·라이선스 확인이 필요한 소재는 공개 전에 검토해야 합니다.
 - 목표 길이는 실제 TTS 길이로 덮어쓰지 않습니다. 허용 오차 `max(2초, 목표의 10%)`를 벗어나면 경고하고 렌더 전에 차단합니다. 자동 유료 재합성을 하지 않으며, 무음이나 억지 영상 늘이기로 통과시키지 마세요.
 - 커뮤니티/바이럴 제작은 라이브러리 검토 없이 기본 자막만으로 끝내지 않습니다. 오버레이가 없으면 `decorationRationale`에 적합한 소재를 생략한 이유를 기록해야 렌더할 수 있습니다. 관련 없는 장식이나 부적절한 밈을 억지로 넣는 것은 해결이 아닙니다.
 - `review_production`은 구조만 점검합니다. `render_result`의 `qualityStatus`가 `needs-visual-and-listening-review`이면 아직 시각·청취 검증 전입니다. 최종 영상에서 강조색/글자 크기/모션/소재 겹침과 목소리를 직접 확인한 뒤에만 완성 품질을 보고하세요.
 
+## 공급자 폴백과 비용 기록 (0.13.0)
+
+- `tts_narration`과 `tts_narration_with_captions`는 일반 합성에서 확정된 일시 거절(429/503 등)에 한해 다음 사용 가능한 공급자를 고려합니다. `allowProviderFallback:false`로 끌 수 있습니다. 자동 선택 전 사용자 키로 보이스 목록을 확인하며, 비용 견적만 요청할 때는 이 추가 검증을 하지 않습니다.
+- 보이스를 명시했거나 제작 핸들에 캐스팅이 저장되어 있으면 공급자별 대체 보이스를 사용자가 허용해야 합니다. 예: `fallbackVoices:{elevenlabs:{voiceId:"사용자가-승인한-ID"}}`. 다른 공급자의 보이스/모델/스타일 ID를 그대로 재사용하지 않습니다. 커뮤니티형 제작은 기존처럼 먼저 `recommend_voice`를 사용하세요.
+- 성공 응답의 `provider`, `primaryProvider`, `providerFallback`, `accountCostEvents`로 실제 합성 공급자와 비용을 확인합니다. 폴백 후 새 `productionPath`에 실제 보이스를 저장하며 이전 제작 핸들은 바꾸지 않습니다. 항상 최신 핸들을 다음 단계에 넘기세요.
+- 제출 시간 초과·네트워크 단절·접수 후 결과 불명, 인증·입력·안전정책 오류에는 다른 유료 생성을 자동 실행하지 않습니다. 오류의 `fallbackStatus`, `fallbackReason`, `fallbackAvailable`, 접수된 비용을 확인하고 기존 작업부터 조회하세요. 실패했다고 비용이 없거나 환불되었다는 뜻은 아닙니다.
+- ElevenLabs의 정확한 문자별 타임스탬프를 선택한 요청은 추정 자막으로 대체하지 않습니다. 다른 공급자 일반 합성이 ElevenLabs로 전환되더라도 `timingSource:"estimated-from-audio-duration"`인 자막이 정밀 타임스탬프로 바뀌지는 않습니다. 사용자 PC의 Companion 직접 Edge TTS는 서버 폴백 체인 밖입니다.
+- 이미지·영상·LLM 폴백은 대응 서버가 지원하는 동일 기능/입력 경로에서만 동작합니다. SUNO, 음성 클로닝, 정밀 정렬 등 모든 독점 기능에 호환 대체가 있는 것은 아닙니다. 상태 조회만으로 미확인 유료 작업을 재생성하지 마세요.
+
 ## 장면 이미지 준비와 영상 표현 선택
 
 다음 설정은 0.12.0부터 지원합니다. 기존 0.11.0 클라이언트는 위의 버전 고정 설정을 바꾸고 다시 연결해야 새 입력과 도구 안내를 사용할 수 있습니다. 이미지 모션 렌더에는 해당 기능을 지원하는 최신 컴패니언 런타임도 필요합니다.
@@ -96,7 +105,31 @@ detect_shots(원본별, 컴패니언) → analyze_edit_points(videos + shotsFile
 - `analyze_edit_points`가 돌려주는 영상별 `burnedSubtitle`(박힌 자막 관측)을 `prepare_remake_timeline`의 `sourceVideos[].burnedSubtitle`로 그대로 넘기고 `subtitleCropMode: "auto"`를 주면 자막 박힌 소스만 하단 크롭됩니다.
 - `[N]`/`[SN]` 행의 `audioContent`는 유료 TTS로 합성됩니다 — 실행 전 사용자 확인을 받으세요. 원본 다운로드·렌더는 이 PC의 컴패니언이 수행합니다.
 
-## 한도
+## 영화·드라마 리뷰 제작 (0.13.0)
+
+이 절은 0.13.0과 대응 서버·컴패니언 런타임에서 사용하는 경로입니다. 기존 설치된 0.12.0에 포함된 기능이 아니므로 위 설정의 버전을 바꾸고 클라이언트를 다시 연결하세요.
+
+```
+analyze_review_sources → resumePath → analyze_review_sources(resumePath) 반복
+→ 원본 청크 분석 → 전체 서사 종합 → 원본 영상 재검증 → reviewSourcePath
+→ plan_review_video → productionPath
+→ recommend_voice(productionPath) → prepare_review_timeline(productionPath)
+→ review_production → render_start → render_status → render_result → 시각·청취·스포일러 검토
+```
+
+- 원본은 YouTube ID/URL 또는 로컬 MP4/MOV/M4V/MKV/WebM, 최대 5편·원본별 24시간·총 500청크입니다. 기본 `analysisScope:"full"`은 Gemini 3.8로 처음부터 끝까지 영상과 오디오를 분석합니다. 컴패니언이 최대 300초/10MiB MP4로 압축하고 구간 사이 15초를 겹칩니다. 큰 원본 파일 하나를 직접 올리지는 않지만, **원작의 전체 내용이 압축 청크로 클라우드에 전송됩니다.** 사용자 업로드·과금 동의를 받은 뒤 `allowCloudVideoUpload:true`를 지정해야 합니다. 동의 없이는 샘플 분석으로 우회하지 않습니다.
+- 시작 예: `analyze_review_sources({sources:[{kind:"local",videoPath:"/path/movie.mp4"}],workTitle:"작품명",allowCloudVideoUpload:true})`. YouTube는 `kind:"youtube",videoId:"URL 또는 ID"`입니다. 첫 호출은 원본·지원 기능 검사와 범위/예상 유료 단계 수만 보여 주고 과금하지 않습니다. 이후 `analyze_review_sources({resumePath,allowCloudVideoUpload:true})`를 `complete:true`까지 반복합니다. 기본 한 호출당 1단계이며 `progress`와 `review_analysis_status({resumePath})`로 진행 상황·누적 비용을 확인합니다.
+- 체크포인트는 원본 식별자·전체 전사·장면·등장인물·서사·단계별 비용을 보존합니다. 오래된 `resumePath`로 재개해도 최신 영수증을 찾아 완료된 청크를 재호출하지 않습니다. 오디오 미검토/전사 누락, 원본 변경, 재검증 모순·근거 부족, 접수 여부가 불확실한 요청은 중단합니다. `failedStageResultPath`에 반환된 분석/반박 근거를 보존하며 자동 재시도하지 않습니다. 추가 비용을 사용자가 승인한 경우에만 `retryFailedStage:true`를 사용하세요.
+- `resumePath`·`reviewSourcePath`·`productionPath` 및 실패 근거는 MCP의 임시 media 저장소에 있으며 기본 48시간 보존 정책의 정리 대상입니다. 첫 체크포인트 생성 후 48시간 안에 이어서 진행하세요. 장기 보관에는 연결된 체크포인트·근거 파일까지 별도 내보내기/백업이 필요하며 무기한 재개를 보장하지 않습니다.
+- 전체 줄거리와 인물 주장은 관련 원본 MP4+음성을 다시 보내 검증합니다. 모든 대상 검증이 지지되어야 전체 분석 핸들이 나옵니다. 이는 모델 판정이며 모든 프레임의 관찰·전사 완전성·사실성을 보증하지 않습니다. 최종 영상·음성과 원본 근거는 사람이 확인해야 합니다.
+- `analysisScope:"sample"`을 명시하면 예전 대표 프레임 점검(최대 18장)만 수행합니다. 원작 전체 이해가 아닙니다. `segments:[{startMs,endMs,note,dialogueText,spoilerLevel}]` 및 `transcriptSegments:[{startMs,endMs,text}]`를 제공할 수 있고, 구간에 완전히 포함된 대사만 인용 근거로 사용합니다. 이 자료로 부분 구간 리뷰를 만들려면 별도로 `allowPartialSourceReview:true`를 명시해야 합니다.
+- 스포일러 등급은 자동으로 안전하다고 인증하지 않습니다. 미확인 구간은 `unknown`이며 `none`/`limited` 기획에서 제외됩니다. 장편의 편집 후보만 최대 500개/180,000자로 제한하고, 검증된 서사 근거 장면을 우선 선택한 내역을 `catalogSelection`으로 알려 줍니다. `sourceIds`로 직접 선택할 수도 있습니다. 전체 서사·전사는 자르지 않고 유지하며, 전편 맥락 한도를 넘으면 작품/회차 분리를 요청합니다.
+- `plan_review_video({reviewSourcePath,workType:"film" 또는 "drama",workTitle,episode?,targetDurationSec:60..900,spoilerPolicy:"none"|"limited"|"full",reviewAngle,deliveryStyle})`로 리뷰 관점과 말투를 선택합니다. 사실·해석·가상 해석은 구분하며 실제 대사 인용은 제공한 원본 근거가 필요합니다.
+- 내레이션 `[N]`, 원본 대사 `[S]`, 현장음 `[A]`를 편집할 수 있습니다. 리뷰 준비는 공통 자막 프리셋·아이콘/이모지 자동 배치를 사용하며 `autoCompose:false`와 명시 스타일/오버레이로 제어할 수 있습니다. 준비된 길이·실측 TTS가 맞지 않으면 자동 재합성이나 억지 늘이기 대신 오류를 확인하세요.
+- TTS 공급자 우선순위는 Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2입니다. 보이스를 명시했으면 공급자도 지정하세요. 반환된 최신 `productionPath`를 계속 사용하면 동시 제작의 음성·원본이 섞이지 않습니다. 원본이 분석 후 바뀌면 다시 분석해야 합니다.
+- 영상 및 음악의 사용 권리, 인용 내용, 대사·장면 타이밍, 스포일러, 최종 자막과 음성은 공개 전에 직접 검토해야 합니다. 자동 검토를 공개 허가나 품질 보증으로 표시하지 않습니다.
+
+## 호출 한도
 
 - 쓰기(생성) 호출 분당 20회, 조회 분당 120회, 동시 생성 2개 (서버 강제)
 - 사용자당 활성 PAT 5개, 기본 만료 90일

package/lib/api-client.mjs

@@ -6,11 +6,21 @@ import { MCP_PROXY_VERSION } from "./config.mjs";
 const DEFAULT_TIMEOUT_MS = 60_000;
 
 export class AimakeallApiError extends Error {
-  constructor(message, { errorCode = "", retryAfterSeconds = 0, status = 0 } = {}) {
+  constructor(message, { errorCode = "", retryAfterSeconds = 0, status = 0, accountCostEvents, acceptedTaskCosts, operationId, costUsd, usage, partialProviderUsage, fallbackMetadata } = {}) {
     super(message);
     this.errorCode = errorCode;
     this.retryAfterSeconds = retryAfterSeconds;
     this.status = status;
+    this.accountCostEvents = Array.isArray(accountCostEvents) ? accountCostEvents : [];
+    this.acceptedTaskCosts = Array.isArray(acceptedTaskCosts) ? acceptedTaskCosts : [];
+    this.operationId = typeof operationId === "string" ? operationId : "";
+    this.costUsd = Number.isFinite(costUsd) ? costUsd : 0;
+    this.usage = usage && typeof usage === "object" ? usage : null;
+    this.partialProviderUsage = partialProviderUsage === true;
+    for (const field of ["fallbackStatus", "fallbackReason", "capability", "provider"]) {
+      if (typeof fallbackMetadata?.[field] === "string") this[field] = fallbackMetadata[field].slice(0, 160);
+    }
+    if (typeof fallbackMetadata?.fallbackAvailable === "boolean") this.fallbackAvailable = fallbackMetadata.fallbackAvailable;
   }
 }
 
@@ -65,9 +75,13 @@ export function createApiClient({ apiBase, pat }) {
 
     if (!response.ok) {
       throw new AimakeallApiError(describeApiFailure(response.status, payload), {
-        errorCode: String(payload?.error || ""),
+        errorCode: String(payload?.code || payload?.error || ""),
         retryAfterSeconds: Number(payload?.retryAfterSeconds) || Number(response.headers.get("retry-after")) || 0,
         status: response.status,
+        accountCostEvents: payload?.accountCostEvents, acceptedTaskCosts: payload?.acceptedTaskCosts,
+        operationId: payload?.operationId, costUsd: payload?.costUsd,
+        usage: payload?.usage, partialProviderUsage: payload?.partialProviderUsage,
+        fallbackMetadata: payload,
       });
     }
     return payload;
@@ -98,8 +112,12 @@ export function createApiClient({ apiBase, pat }) {
         payload = null;
       }
       throw new AimakeallApiError(describeApiFailure(response.status, payload), {
-        errorCode: String(payload?.error || ""),
+        errorCode: String(payload?.code || payload?.error || ""),
         status: response.status,
+        accountCostEvents: payload?.accountCostEvents, acceptedTaskCosts: payload?.acceptedTaskCosts,
+        operationId: payload?.operationId, costUsd: payload?.costUsd,
+        usage: payload?.usage, partialProviderUsage: payload?.partialProviderUsage,
+        fallbackMetadata: payload,
       });
     }
     return {

package/lib/cloud-tools.mjs

@@ -27,6 +27,7 @@ import { fetchGenerationJob, GENERATION_JOB_PATH, submitGenerationJob } from "./
 import { loudnessDbfsFromWav, silenceRatioFromWav } from "./wav-dsp.mjs";
 import { trimWavToSeconds } from "./wav-trim.mjs";
 import { registerComposerTools } from "./composer-tools.mjs";
+import { registerReviewTools } from "./review-tools.mjs";
 import { productionFields, visualProductionFields, sceneVisual, composerTextStyle, composerOverlay } from "./production-schemas.mjs";
 import { saveProductionContext, readProductionContext, durationReview, reviewProductionPayload } from "./production-context.mjs";
 import { TTS_PROVIDERS, buildTtsRequestBody, estimateTtsSubtitleLines, requestTtsBinary, resolveTtsSelection } from "./tts-workflow.mjs";
@@ -38,6 +39,11 @@ const BODY_BUDGET_BYTES = SERVER_JSON_BODY_LIMIT_BYTES - 512 * 1024; // 바디
 
 // 컴패니언 계약 상수 — companion/index.cjs 의 MAX_SHOT_COUNT 와 맞춘다.
 const COMPANION_MAX_SHOTS = 18;
+const ttsFallbackFields = {
+  allowProviderFallback: z.boolean().optional().describe("확정된 일시 거절 때만 대체 공급자 허용. 처리 결과 불명·인증·정책 오류는 재합성하지 않음"),
+  fallbackVoices: z.object(Object.fromEntries(TTS_PROVIDERS.map((provider) => [provider,
+    z.object({ voiceId: z.string().min(1) }).optional()]))).optional().describe("선택한 목소리를 대신해도 되는 공급자별 보이스 ID. 미지정이면 명시 보이스를 다른 목소리로 변경하지 않음"),
+};
 
 function assertEncodedBudget(filePaths, { context = "요청" } = {}) {
   let total = 0;
@@ -147,13 +153,21 @@ function describeLocalError(error) {
 }
 
 export function wrapCloudHandler(config, handler) {
-  return async (args) => {
+  return async (args, extra) => {
     if (!config.pat) return textResult(NO_PAT_GUIDE, { isError: true });
     try {
-      return await handler(args);
+      return await handler(args, extra);
     } catch (error) {
       if (error instanceof AimakeallApiError) {
         const retry = error.retryAfterSeconds ? ` (${error.retryAfterSeconds}초 후 재시도)` : "";
+        if (error.partialProviderUsage || error.accountCostEvents.length || error.fallbackStatus) {
+          return textResult(JSON.stringify({ error: error.message, code: error.errorCode, status: error.status,
+            provider: error.provider, fallbackStatus: error.fallbackStatus, fallbackReason: error.fallbackReason,
+            fallbackAvailable: error.fallbackAvailable, capability: error.capability,
+            accountCostEvents: error.accountCostEvents, acceptedTaskCosts: error.acceptedTaskCosts,
+            partialProviderUsage: error.partialProviderUsage, usage: error.usage,
+            guidance: "접수된 비용과 실패 사유를 확인하세요. 결과 불명 작업이나 지정한 보이스를 자동 재생성/교체하지 마세요." }, null, 2), { isError: true });
+        }
         return textResult(`${error.message}${retry}`, { isError: true });
       }
       return textResult(`요청 실패: ${describeLocalError(error)}`, { isError: true });
@@ -187,6 +201,7 @@ function trimAnalysis(analysis) {
 
 export function registerCloudTools(server, config, api) {
   registerComposerTools(server, config, api);
+  registerReviewTools(server, config, api, { wrap: handler => wrapCloudHandler(config, handler) });
   async function completedGenerationResult(job, includePreview) {
     const payload = job.result || {};
     const resultBody = { generationJobId: job.id, status: job.status, kind: job.kind,
@@ -293,7 +308,7 @@ export function registerCloudTools(server, config, api) {
       ttsChars: z.number().int().min(0).max(20000).optional().describe("내레이션 글자 수"),
     },
     wrapCloudHandler(config, async (input) => {
-      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider })).provider };
+      if (input.ttsChars > 0) input = { ...input, ttsProvider: (await resolveTtsSelection(api, config, { provider: input.ttsProvider, validateCredentials: false })).provider };
       const payload = await api.request("/api/tracker/cost/estimate", { body: input, method: "POST", timeoutMs: 30_000 });
       return jsonResult(payload);
     }),
@@ -711,17 +726,18 @@ export function registerCloudTools(server, config, api) {
 
   server.tool(
     "tts_narration",
-    "내레이션 TTS를 합성해 이 PC에 오디오 파일로 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge TTS → Supertonic2. 키/런타임이 없을 때 다음 공급자를 고려하며, 합성 실패 후 다른 유료 공급자로 재시도하지 않습니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 선택하세요.",
+    "내레이션 TTS를 합성해 이 PC에 저장합니다. 자동 순서: Typecast → ElevenLabs → Supertone → Edge → Supertonic2. 확정된 일시 거절에만 폴백하며, 명시 보이스는 fallbackVoices가 있어야 교체합니다. 접수 후 결과 불명·정책·인증 오류는 재합성하지 않습니다. 먼저 recommend_voice로 톤에 맞는 보이스를 고르세요.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 productionPath의 기획 대본"),
+      ...ttsFallbackFields,
       provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동: Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 선택/저장된 보이스는 유지"),
       voice: z.string().optional().describe("보이스 이름(라벨)"),
       speed: z.number().optional().describe("기본 1"),
       stability: z.number().min(0).max(1).optional(), style: z.number().min(0).max(1).optional(),
       modelId: z.string().optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, stability, style, modelId, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
@@ -731,13 +747,21 @@ export function registerCloudTools(server, config, api) {
       voice ||= context?.voice?.voiceId || "";
       if (!text?.trim()) return textResult("대본(text/productionPath)이 필요합니다.", { isError: true });
       if (productionProfile?.deliveryStyle === "casual-social" && !voice) return textResult("먼저 recommend_voice에 productionPath를 전달해 커뮤니티형 보이스를 선정하세요.", { isError: true });
-      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice });
+      const body = buildTtsRequestBody(provider, { productionProfile, costEventId: createUsageEventId(`mcp-tts-${provider}`), modelId, similarityBoost, speakerBoost, speed, stability, style, text, voice, fallbackVoices, allowProviderFallback });
       const result = await requestTtsBinary(api, config, selection, body);
+      provider = result.provider || provider;
+      voice = result.voiceId || voice;
       const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration.wav" : "narration.mp3", result.buffer, { contentType: result.contentType });
       const durationSec = audioDurationSecFromFile(saved.filePath);
       return jsonResult({
-        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text, tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
+        productionPath: saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
+          tts: { provider, filePath: saved.filePath, durationSec, voiceId: voice } }),
         provider,
+        primaryProvider: result.primaryProvider || provider,
+        providerFallback: result.providerFallback === true,
+        accountCostEvents: result.accountCostEvents || [],
+        hasAccountCostEvents: true,
         executionTarget: selection.executionTarget,
         durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec),
         bytes: saved.bytes,
@@ -1464,17 +1488,18 @@ export function registerCloudTools(server, config, api) {
   // ── 시간 동기 자막 TTS — 쇼츠 하단자막용 ─────────────────────────────────────
   server.tool(
     "tts_narration_with_captions",
-    "TTS 오디오와 자막을 만듭니다. 자동 순서: Typecast→ElevenLabs→Supertone→Edge→Supertonic2, 명시 보이스/공급자는 유지. ElevenLabs는 실제 char-level 타이밍, 나머지는 실측 오디오 길이에 비례한 추정 자막(timingSource 확인)입니다. 먼저 recommend_voice로 제작 톤에 맞는 보이스를 고르세요. 자동 추가 STT 과금이나 다른 공급자로의 재합성은 하지 않습니다.",
+    "TTS 오디오와 자막을 만듭니다. 순서 Typecast→ElevenLabs→Supertone→Edge→Supertonic2. 명시 목소리는 fallbackVoices 없이 변경하지 않습니다. ElevenLabs 선택 시 실제 char-level 타이밍을 유지하며 해당 정밀 기능은 대체하지 않습니다. 나머지는 실측 오디오 길이 기반 추정 자막이며 추가 STT 과금은 없습니다.",
     {
       ...productionFields,
       text: z.string().optional().describe("생략 시 제작 핸들의 기획 대본 그대로 합성. 사실·인용을 바꾸거나 뉴스체로 재작성하지 마세요."),
+      ...ttsFallbackFields,
       provider: z.enum(["auto", ...TTS_PROVIDERS]).optional().describe("기본 자동 선택 또는 제작 핸들에 선정된 공급자"),
       voice: z.string().optional().describe("보이스 이름 또는 ID (생략 시 기본 보이스)"),
       speed: z.number().optional().describe("기본 1 (0.7~1.2)"),
       modelId: z.string().optional(), stability: z.number().min(0).max(1).optional(),
       style: z.number().min(0).max(1).optional(), similarityBoost: z.number().min(0).max(1).optional(), speakerBoost: z.boolean().optional(),
     },
-    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost }) => {
+    wrapCloudHandler(config, async ({ text, provider, voice = "", speed, productionPath, productionProfile, modelId, stability, style, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback }) => {
       const context = readProductionContext(config.stateDir, productionPath);
       productionProfile = context?.productionProfile || productionProfile;
       text ??= context?.narrationScript;
@@ -1489,16 +1514,21 @@ export function registerCloudTools(server, config, api) {
         return textResult("커뮤니티형 음성을 위해 먼저 recommend_voice에 productionPath를 전달하고, 반환된 productionPath 또는 보이스 ID를 사용하세요.", { isError: true });
       }
       if (provider !== "elevenlabs") {
-        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
+        const body = buildTtsRequestBody(provider, { productionProfile, text, voice, speed, modelId, fallbackVoices, allowProviderFallback, costEventId: createUsageEventId(`mcp-tts-${provider}-captions`) });
         const result = await requestTtsBinary(api, config, selection, body);
+        provider = result.provider || provider;
+        voice = result.voiceId || voice;
         const saved = saveMediaBuffer(config.stateDir, provider === "supertonic2" ? "narration-captions.wav" : "narration-captions.mp3", result.buffer, { contentType: result.contentType });
         const durationSec = audioDurationSecFromFile(saved.filePath);
         const subtitleLines = estimateTtsSubtitleLines(text, durationSec);
         const timingSource = "estimated-from-audio-duration";
         const updatedProductionPath = saveProductionContext(config.stateDir, { ...context, productionProfile, narrationScript: text,
+          ...(result.providerFallback ? { voice: { provider, voiceId: voice, reason: "사용자가 허용한 공급자별 대체 보이스" } } : {}),
           tts: { provider, durationSec, filePath: saved.filePath, subtitleLines, voiceId: voice, timingSource },
         });
         return jsonResult({ productionPath: updatedProductionPath, productionProfile, provider, executionTarget: selection.executionTarget,
+          primaryProvider: result.primaryProvider || provider, providerFallback: result.providerFallback === true,
+          accountCostEvents: result.accountCostEvents || [], hasAccountCostEvents: true,
           durationSec, durationWarning: durationReview(productionProfile?.targetDurationSec, durationSec), filePath: saved.filePath,
           lineCount: subtitleLines.length, subtitleLines, timingSource,
           warnings: [durationSec > 0 ? "자막은 실측 오디오 길이 기준 추정입니다. 최종 렌더 전 발화와 동기를 확인하세요." : "오디오 길이를 측정하지 못해 자막을 만들지 않았습니다. 저장된 오디오를 확인하세요. 자동 재합성하지 않습니다."],

package/lib/companion-tools.mjs

@@ -9,6 +9,7 @@ import {
 import { detectRemoteEnvironment } from "./config.mjs";
 import { durationReview, reviewProductionPayload } from "./production-context.mjs";
 import { readPayloadHandle, saveMediaBuffer } from "./media-store.mjs";
+import { restoreReviewRenderSources } from "./review-sources.mjs";
 import {
   checkRenderPayloadSize,
   sanitizeRenderPayload,
@@ -176,6 +177,11 @@ export function registerCompanionTools(server, config) {
       }
 
       const { payload: cleaned, warnings } = sanitizeRenderPayload(resolvedPayload);
+      try {
+        restoreReviewRenderSources(cleaned, { stateDir: config.stateDir, fromSavedPayload: Boolean(payloadPath) });
+      } catch (error) {
+        return textResult(`리뷰 원본 검증 실패: ${String(error?.message || error)}`, { isError: true });
+      }
       const productionReview = reviewProductionPayload(cleaned);
       if (!productionReview.pass) {
         return textResult(JSON.stringify({ error: "PRODUCTION_SPEC_MISMATCH", ...productionReview }, null, 2), { isError: true });

package/lib/config.mjs

@@ -2,7 +2,7 @@ import { homedir } from "node:os";
 import path from "node:path";
 
 // 프록시 버전 — 서버가 X-AImakeAll-MCP-Version 으로 하한을 강제(426)할 수 있다.
-export const MCP_PROXY_VERSION = "0.12.0";
+export const MCP_PROXY_VERSION = "0.13.0";
 
 export const DEFAULT_API_BASE = "https://aimakeall.com";
 export const DEFAULT_COMPANION_URL = "http://127.0.0.1:9876";

package/lib/production-context.mjs

@@ -11,7 +11,7 @@ export function readProductionContext(stateDir, productionPath) {
   if (!productionPath) return null;
   const value = readPayloadHandle(productionPath, { stateDir });
   if (value?.kind !== "aimakeall-production" || value.version !== 1 || !value.productionId) {
-    throw new Error("productionPath는 plan_shorts_video 또는 TTS가 반환한 제작 핸들이어야 합니다.");
+    throw new Error("productionPath는 plan_* 또는 TTS가 반환한 제작 핸들이어야 합니다.");
   }
   return value;
 }

package/lib/review-full-analysis.mjs

@@ -0,0 +1,302 @@
+import { createHash, randomUUID } from "node:crypto";
+import { closeSync, openSync, readFileSync, readdirSync, unlinkSync, writeFileSync } from "node:fs";
+import path from "node:path";
+import { savePayloadHandle } from "./media-store.mjs";
+import { canonicalYoutubeWatchUrl } from "./payload-guard.mjs";
+import { inspectReviewLocalFile, readReviewHandle, reviewPublicSources, validateReviewSources } from "./review-sources.mjs";
+
+const KIND = "aimakeall-review-full-analysis";
+const MAX_CHUNK_BYTES = 10 * 1024 * 1024;
+const TEXT_BUDGET = 4 * 1024 * 1024;
+const RECEIPT_KEYS = ["accountCostEvents", "acceptedTaskCosts", "operationId", "costUsd", "usage", "partialProviderUsage", "model"];
+
+function fail(code, message) { const error = new Error(message); error.code = code; return error; }
+function textBudget(value) {
+  if (Buffer.byteLength(JSON.stringify(value)) > TEXT_BUDGET) throw fail("REVIEW_FULL_CONTEXT_TOO_LARGE", "전체 분석 근거가 4MiB를 초과했습니다. 근거를 몰래 삭제하거나 샘플링하지 않습니다. 작품/회차 단위로 나누어 분석하세요.");
+}
+export function fullReviewChunks(sourceId, durationSec) {
+  const durationMs = Math.round(durationSec * 1000);
+  if (!Number.isFinite(durationSec) || durationSec <= 0 || durationSec > 86400) throw fail("REVIEW_SOURCE_DURATION_INVALID", "원본별 분석 길이는 실측 24시간 이하이어야 합니다.");
+  const chunks = [];
+  for (let startMs = 0; startMs < durationMs; startMs += 285000) {
+    const endMs = Math.min(durationMs, startMs + 300000);
+    chunks.push({ chunkId: `${sourceId}:${startMs}-${endMs}`, sourceId, startMs, endMs });
+    if (endMs === durationMs) break;
+  }
+  return chunks;
+}
+
+function snapshot(config, state) {
+  state.revision = (state.revision || 0) + 1;
+  if (Buffer.byteLength(JSON.stringify(state)) > 12 * 1024 * 1024) throw fail("REVIEW_CHECKPOINT_TOO_LARGE", "체크포인트 12MiB 한도를 초과했습니다. 분석 근거를 임의로 생략하지 않습니다.");
+  return savePayloadHandle(config.stateDir, state, `review-full-${state.analysisId}-${state.revision}`).filePath;
+}
+
+export function loadFullReviewAnalysis(config, resumePath) {
+  const base = readReviewHandle(config.stateDir, resumePath, KIND);
+  if (!/^[a-f0-9-]{36}$/.test(base.analysisId || "")) throw fail("REVIEW_CHECKPOINT_INVALID", "전체 분석 체크포인트 ID가 잘못되었습니다.");
+  let state = base, latestPath = resumePath;
+  // Immutable journal discovery also finds a receipt saved just before a client
+  // disconnect. Resuming an old handle must not charge completed chunks again.
+  for (const name of readdirSync(path.join(config.stateDir, "media"))) {
+    if (!name.includes(`review-full-${base.analysisId}-`) || !name.endsWith(".json")) continue;
+    const filePath = path.join(config.stateDir, "media", name);
+    const candidate = readReviewHandle(config.stateDir, filePath, KIND);
+    if (candidate.analysisId !== base.analysisId) continue;
+    if (candidate.revision > state.revision) { state = candidate; latestPath = filePath; }
+  }
+  return { state, resumePath: latestPath };
+}
+
+function lockAnalysis(config, analysisId) {
+  const filePath = path.join(config.stateDir, "media", `review-analysis-${analysisId}.lock`);
+  let fd;
+  try { fd = openSync(filePath, "wx", 0o600); }
+  catch (error) {
+    if (error.code !== "EEXIST") throw error;
+    const pid = Number(readFileSync(filePath, "utf8"));
+    try { if (!(pid > 0)) throw new Error("unknown lock owner"); process.kill(pid, 0); }
+    catch (probe) {
+      if (probe.code === "ESRCH") { unlinkSync(filePath); fd = openSync(filePath, "wx", 0o600); }
+    }
+    if (fd === undefined) throw fail("REVIEW_ANALYSIS_RUNNING", "같은 전체 분석이 이미 실행 중입니다. 완료를 기다린 후 상태를 조회하세요.");
+  }
+  writeFileSync(fd, String(process.pid));
+  return () => { closeSync(fd); unlinkSync(filePath); };
+}
+
+function receipt(value, stage, chunkId = "") {
+  return { stage, chunkId, ...Object.fromEntries(RECEIPT_KEYS.filter(key => value?.[key] !== undefined).map(key => [key, value[key]])) };
+}
+function safeStageResult(value) {
+  if (Array.isArray(value)) return value.map(safeStageResult);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).filter(([key]) => !/base64|dataUrl|localPath|sourceHandle|apiKey|token/i.test(key)).map(([key, item]) => [key, safeStageResult(item)]));
+}
+function billing(state) {
+  const costs = state.receipts || [];
+  const unique = (field) => [...new Map(costs.flatMap(item => item[field] || []).map(item => [item.eventId || item.id || JSON.stringify(item), item])).values()];
+  return { accountCostEvents: unique("accountCostEvents"), acceptedTaskCosts: unique("acceptedTaskCosts"),
+    costUsd: costs.reduce((sum, item) => sum + (Number(item.costUsd) || 0), 0), stageReceipts: costs };
+}
+function summary(state, resumePath) {
+  const analyzedMs = state.sources.reduce((sum, source) => {
+    let end = 0, covered = 0;
+    for (const chunk of state.chunks.filter(item => item.sourceId === source.id && state.analyses[item.chunkId]).sort((a, b) => a.startMs - b.startMs)) {
+      covered += Math.max(0, chunk.endMs - Math.max(end, chunk.startMs)); end = Math.max(end, chunk.endMs);
+    }
+    return sum + covered;
+  }, 0);
+  return { analysisScope: "full", complete: state.stage === "complete", resumePath,
+    reviewSourcePath: state.stage === "complete" ? state.reviewSourcePath : undefined,
+    progress: { stage: state.stage, completedChunks: Object.keys(state.analyses).length, totalChunks: state.chunks.length,
+      completedVerifications: Object.keys(state.verifications || {}).length, totalVerifications: state.verifyChunkIds?.length || 0,
+      analyzedTimelineSec: analyzedMs / 1000, totalTimelineSec: state.sources.reduce((sum, item) => sum + item.durationSec, 0) },
+    sources: reviewPublicSources(state.sources), ...billing(state),
+    warnings: state.warnings || [], error: state.error || undefined,
+    failedStageResultPath: state.failedStageResultPath || undefined,
+    requiresHumanReview: true, next: state.stage === "complete" ? "plan_review_video({reviewSourcePath,...})" : state.stage === "blocked" ? "실패 원인·이미 접수된 비용을 확인하세요. 자동 재시도하지 않습니다." : "analyze_review_sources({resumePath,allowCloudVideoUpload:true})로 다음 1개 단계를 계속하세요.",
+  };
+}
+export function fullReviewStatus(config, resumePath) { const loaded = loadFullReviewAnalysis(config, resumePath); return summary(loaded.state, loaded.resumePath); }
+
+// This limits only the editing candidate list, never the full story/transcript
+// evidence. All native analysis remains in the original immutable handle.
+export function selectReviewPlanningCatalog(handle, requestedIds) {
+  const all = handle.sourceCatalog || [], byId = new Map(all.map(scene => [scene.sourceId, scene]));
+  const fits = items => items.length <= 500 && JSON.stringify(items).length <= 180000;
+  if (requestedIds?.length) {
+    if (new Set(requestedIds).size !== requestedIds.length || requestedIds.some(id => !byId.has(id))) throw fail("REVIEW_CATALOG_SELECTION_INVALID", "기획 sourceIds는 분석에서 반환한 장면 ID만 중복 없이 선택하세요.");
+    const selected = requestedIds.map(id => byId.get(id));
+    if (!fits(selected)) throw fail("REVIEW_CATALOG_SELECTION_LIMIT", "편집 후보는 최대 500개/180,000자입니다. 필요한 원본 장면을 더 좁혀 주세요. 전체 분석은 보존됩니다.");
+    return { sourceCatalog: selected, catalogSelection: { totalCount: all.length, selectedCount: selected.length, reason: "explicit-sourceIds", fullContextPreserved: true } };
+  }
+  if (fits(all)) return { sourceCatalog: all, catalogSelection: { totalCount: all.length, selectedCount: all.length, reason: "all-editing-candidates", fullContextPreserved: true } };
+  const evidenceIds = new Set((handle.globalStory?.verificationClaims || handle.globalStory?.timeline || []).flatMap(claim => claim.evidenceIds || []));
+  const transcriptEvidence = (handle.fullTranscriptSegments || []).filter(segment => evidenceIds.has(segment.id));
+  const selected = all.filter(scene => evidenceIds.has(scene.sourceId) || transcriptEvidence.some(segment => (segment.sourceId || segment.reviewSourceId) === scene.reviewSourceId && segment.startMs >= scene.startMs && segment.endMs <= scene.endMs));
+  if (!fits(selected)) throw fail("REVIEW_CATALOG_SELECTION_REQUIRED", "줄거리 근거 장면이 편집 후보 한도를 초과합니다. 전체 분석 핸들은 유지됩니다. plan_review_video.sourceIds로 이번 리뷰에서 사용할 장면을 명시하세요.");
+  const seen = new Set(selected.map(scene => scene.sourceId));
+  const remaining = all.filter(scene => !seen.has(scene.sourceId));
+  const slots = Math.min(500 - selected.length, remaining.length);
+  for (let i = 0; i < slots; i++) {
+    const candidate = remaining[Math.floor(i * remaining.length / slots)];
+    if (fits([...selected, candidate])) selected.push(candidate);
+  }
+  if (!selected.length) throw fail("REVIEW_CATALOG_SELECTION_REQUIRED", "편집할 장면 ID를 명시하세요.");
+  return { sourceCatalog: selected, catalogSelection: { totalCount: all.length, selectedCount: selected.length, reason: "verified-story-evidence-first-plus-time-distributed-editing-candidates", fullContextPreserved: true } };
+}
+
+async function inspectSource(companionJson, config, source) {
+  if (source.kind === "local") inspectReviewLocalFile(source.localPath, source.fingerprint);
+  const input = source.kind === "local" ? { videoPath: source.localPath } : { url: source.youtubeUrl };
+  const inspected = await companionJson(config, "/api/review/source", input, 600000);
+  const durationSec = Number(inspected.durationSec ?? Number(inspected.sourceDurationMs) / 1000);
+  if (inspected.ok !== true || !inspected.sourceHandle || !/^[a-f0-9]{64}$/i.test(inspected.sourceFingerprint || "") || typeof inspected.hasAudio !== "boolean") throw fail("REVIEW_INSPECT_INVALID", "전체 영상 분석용 로컬 처리기 업데이트가 필요하거나 원본 검사 결과가 불완전합니다.");
+  fullReviewChunks(source.id, durationSec);
+  if (source.sourceFingerprint && (source.sourceFingerprint !== inspected.sourceFingerprint || Math.abs(source.durationSec - durationSec) > .001 || source.hasAudio !== inspected.hasAudio)) throw fail("REVIEW_SOURCE_CHANGED", "분석 중 원본의 내용·길이·오디오가 변경되었습니다. 새 분석을 시작하세요.");
+  return { ...source, sourceHandle: inspected.sourceHandle, sourceFingerprint: inspected.sourceFingerprint, durationSec, hasAudio: inspected.hasAudio };
+}
+
+async function videoChunk(config, companionJson, source, chunk, expectedSha256) {
+  const media = await companionJson(config, "/api/review/source-chunk", { sourceHandle: source.sourceHandle, startMs: chunk.startMs, endMs: chunk.endMs, ...(expectedSha256 ? { expectedSha256 } : {}) }, 600000);
+  if (media.ok !== true || media.mimeType !== "video/mp4" || typeof media.videoBase64 !== "string" || !/^[A-Za-z0-9+/]+={0,2}$/.test(media.videoBase64) || media.videoBase64.length > Math.ceil(MAX_CHUNK_BYTES / 3) * 4) throw fail("REVIEW_CHUNK_INVALID", "영상 청크는 오디오가 유지된 10MiB 이하 MP4이어야 합니다. 이미지 샘플로 대체하지 않습니다.");
+  const bytes = Buffer.from(media.videoBase64, "base64");
+  const sha256 = createHash("sha256").update(bytes).digest("hex");
+  if (!bytes.length || bytes.length > MAX_CHUNK_BYTES || sha256 !== media.sha256 || (expectedSha256 && sha256 !== expectedSha256)) throw fail("REVIEW_CHUNK_CHANGED", "영상 청크 해시가 원본 분석과 일치하지 않습니다. 과금 분석을 중단합니다.");
+  if (media.startMs !== chunk.startMs || media.endMs !== chunk.endMs || !Number.isFinite(media.actualDurationSec) || Math.abs(media.actualDurationSec - (chunk.endMs - chunk.startMs) / 1000) > .25 || media.hasAudio !== source.hasAudio) throw fail("REVIEW_CHUNK_COVERAGE_INVALID", "영상 청크의 실제 길이·구간·오디오가 원본과 일치하지 않습니다. 전체 분석으로 표시하지 않습니다.");
+  if (media.sourceFingerprint && media.sourceFingerprint !== source.sourceFingerprint) throw fail("REVIEW_SOURCE_CHANGED", "영상 청크 원본 지문이 변경되었습니다.");
+  return { source: { ...reviewPublicSources([source])[0], hasAudio: source.hasAudio }, chunk: { chunkId: chunk.chunkId, startMs: chunk.startMs, endMs: chunk.endMs,
+    actualDurationSec: media.actualDurationSec, hasAudio: media.hasAudio, sha256, mimeType: media.mimeType, videoBase64: media.videoBase64 } };
+}
+
+function checkedAnalysis(value, chunk, media) {
+  const analysis = value.chunkAnalysis || value;
+  if (analysis.chunkId !== chunk.chunkId || analysis.sourceId !== chunk.sourceId || !Array.isArray(analysis.sceneCatalog) || !Array.isArray(analysis.transcriptSegments) || !analysis.sceneCatalog.length) throw fail("REVIEW_CHUNK_ANALYSIS_INCOMPLETE", "영상 청크의 장면·대본 분석 결과가 누락되었습니다.");
+  // Server returns absolute source times, not chunk-relative timestamps.
+  for (const item of [...analysis.sceneCatalog, ...analysis.transcriptSegments]) {
+    if (!Number.isFinite(item.startMs) || !Number.isFinite(item.endMs) || item.startMs < chunk.startMs || item.endMs <= item.startMs || item.endMs > chunk.endMs) throw fail("REVIEW_CHUNK_REFERENCE_INVALID", "청크 분석 근거의 원본 타임코드가 잘못되었습니다.");
+  }
+  if (analysis.coverage?.nativeVideoSubmitted !== true || analysis.coverage.nativeAudioSubmitted !== media.chunk.hasAudio || analysis.coverage.startMs !== chunk.startMs || analysis.coverage.endMs !== chunk.endMs || (media.chunk.hasAudio && analysis.coverage.transcriptComplete !== true)) throw fail("REVIEW_AUDIO_ANALYSIS_INCOMPLETE", "영상·음성 분석 범위 또는 전사에 미검토/불명확 구간이 있습니다. 대본을 생략한 채 전체 이해로 넘어가지 않습니다. 해당 구간과 접수 비용을 확인하세요.");
+  const { videoBase64, chunk: ignoredChunk, source: ignoredSource, ...safe } = analysis;
+  return { ...safe, chunkId: chunk.chunkId, sourceId: chunk.sourceId, startMs: chunk.startMs, endMs: chunk.endMs, sha256: media.chunk.sha256, hasAudio: media.chunk.hasAudio };
+}
+
+function verificationGroups(state) {
+  const timeline = state.storyResult?.story?.verificationClaims || state.storyResult?.story?.timeline;
+  if (!Array.isArray(timeline) || !timeline.length) throw fail("REVIEW_STORY_INCOMPLETE", "전체 서사에 원본 근거를 연결한 사건·해석이 없습니다.");
+  const evidenceToChunk = new Map();
+  for (const chunk of Object.values(state.analyses)) for (const item of [...chunk.sceneCatalog, ...chunk.transcriptSegments]) {
+    for (const id of [item.id, item.sourceId, item.evidenceId]) if (id) evidenceToChunk.set(id, chunk.chunkId);
+  }
+  const groups = new Set();
+  for (const claim of timeline) {
+    if (!claim.id || !Array.isArray(claim.evidenceIds) || !claim.evidenceIds.length) throw fail("REVIEW_STORY_UNGROUNDED", "원본 근거 없는 줄거리 주장이 있어 완료할 수 없습니다.");
+    for (const id of claim.evidenceIds) {
+      const chunkId = evidenceToChunk.get(id);
+      if (!chunkId) throw fail("REVIEW_STORY_UNGROUNDED", "전체 줄거리의 근거 ID가 원본 분석에 없습니다.");
+      groups.add(chunkId);
+    }
+  }
+  return [...groups];
+}
+
+export async function runFullReviewAnalysis({ config, api, args, companionJson, onProgress }) {
+  if (args.allowCloudVideoUpload !== true) throw fail("REVIEW_VIDEO_UPLOAD_CONSENT_REQUIRED", "전체 원작 이해에는 모든 구간의 압축 MP4와 음성을 클라우드 AI에 전송하며 분석·검증 비용이 발생합니다. 사용자 동의를 받은 뒤 allowCloudVideoUpload:true를 지정하세요. 동의 없이 대표 이미지 분석으로 바꾸지 않습니다.");
+  if (!args.resumePath) {
+    if (!args.sources?.length) throw fail("REVIEW_SOURCES_REQUIRED", "전체 분석할 sources 또는 재개할 resumePath가 필요합니다.");
+    const health = await companionJson(config, "/health", undefined, 15000);
+    if (health.capabilities?.reviewSourceAnalysis !== true || health.capabilities?.reviewSourceChunks !== true || health.capabilities.reviewSourceChunkMaxDurationSec < 300 || health.capabilities.reviewSourceChunkMaxBytes < MAX_CHUNK_BYTES) throw fail("COMPANION_UPDATE_REQUIRED", "전체 영상·음성 분석 청크를 지원하는 로컬 처리기로 업데이트하세요. 대표 프레임으로 우회하지 않습니다.");
+    const state = { kind: KIND, version: 1, analysisId: randomUUID(), revision: 0, stage: "analyzing", workTitle: args.workTitle || "",
+      sources: [], chunks: [], analyses: {}, verifications: {}, receipts: [], warnings: ["전체 구간을 압축 영상+오디오로 분석하고 서사 주장을 실제 원본 구간으로 재검증합니다. 공개 권리와 최종 해석은 사람이 확인해야 합니다."], uploadConsent: true };
+    const fingerprints = args.sources.map(source => source.kind === "local" ? inspectReviewLocalFile(source.videoPath) : null);
+    for (const [index, input] of args.sources.entries()) {
+      const id = `review-${randomUUID().slice(0, 8)}`;
+      const source = { id, kind: input.kind, title: input.title || `리뷰 원본 ${index + 1}`, videoId: "",
+        ...(input.kind === "local" ? { localPath: fingerprints[index].path, fingerprint: fingerprints[index] } : { youtubeUrl: canonicalYoutubeWatchUrl(input.videoId), videoId: new URL(canonicalYoutubeWatchUrl(input.videoId)).searchParams.get("v") }) };
+      const inspected = await inspectSource(companionJson, config, source);
+      state.sources.push(inspected); state.chunks.push(...fullReviewChunks(id, inspected.durationSec));
+    }
+    if (state.chunks.length > 500) throw fail("REVIEW_CHUNK_COUNT_LIMIT", "전체 분석은 최대 500개 청크입니다. 과금 호출 전에 작품/회차 단위로 나누세요.");
+    validateReviewSources(state.sources);
+    const resumePath = snapshot(config, state);
+    return { ...summary(state, resumePath), preparedOnly: true, estimatedPaidStages: { chunkAnalyses: state.chunks.length, storySynthesis: 1, sourceVerificationsMaximum: state.chunks.length },
+      next: "원본 범위·업로드 및 분석 비용을 확인한 뒤 analyze_review_sources({resumePath,allowCloudVideoUpload:true})를 호출하세요. 아직 유료 분석은 실행하지 않았습니다." };
+  }
+  if (args.sources?.length) throw fail("REVIEW_RESUME_SOURCE_CONFLICT", "재개할 때 sources를 바꾸지 마세요. 새 원본은 별도의 분석으로 시작하세요.");
+  const loaded = loadFullReviewAnalysis(config, args.resumePath);
+  const release = lockAnalysis(config, loaded.state.analysisId);
+  let state, resumePath;
+  try {
+    ({ state, resumePath } = loadFullReviewAnalysis(config, args.resumePath));
+    validateReviewSources(state.sources);
+    if (state.stage === "complete") return summary(state, resumePath);
+    if (state.inFlight || state.stage === "blocked") {
+      if (args.retryFailedStage !== true) return { ...summary(state, resumePath), requiresExplicitRetryApproval: true };
+      state.stage = state.failedStage || state.inFlight?.stage || "analyzing";
+      delete state.inFlight; delete state.error;
+      resumePath = snapshot(config, state);
+    }
+    const refreshed = new Set();
+    const getMedia = async (chunk, expectedSha256) => {
+      const index = state.sources.findIndex(source => source.id === chunk.sourceId);
+      try { return await videoChunk(config, companionJson, state.sources[index], chunk, expectedSha256); }
+      catch (error) {
+        const expired = error.status === 410 || ["REVIEW_SOURCE_HANDLE_EXPIRED", "REVIEW_SOURCE_HANDLE_INVALID", "REVIEW_SOURCE_HANDLE_NOT_FOUND"].includes(error.code);
+        if (!expired || refreshed.has(chunk.sourceId)) throw error;
+        state.sources[index] = await inspectSource(companionJson, config, state.sources[index]); refreshed.add(chunk.sourceId);
+        return videoChunk(config, companionJson, state.sources[index], chunk, expectedSha256);
+      }
+    };
+    const progress = async () => {
+      if (!onProgress) return;
+      try { await onProgress(summary(state, resumePath)); } catch { /* Progress delivery cannot replay/abort an accepted paid operation. */ }
+    };
+    const charge = async (stage, chunkId, route, body) => {
+      state.inFlight = { stage, chunkId, operationId: randomUUID() }; state.failedStage = stage;
+      resumePath = snapshot(config, state);
+      await progress();
+      let response;
+      try { response = await api.request(route, { method: "POST", body: { ...body, costEventId: state.inFlight.operationId }, timeoutMs: 600000 }); }
+      catch (error) { state.receipts.push(receipt(error, stage, chunkId)); throw error; }
+      state.receipts.push(receipt(response, stage, chunkId));
+      state.pendingStageResult = safeStageResult(response);
+      return response;
+    };
+    for (let step = 0; step < (args.maxSteps ?? 1); step++) {
+      if (state.stage === "analyzing") {
+        const chunk = state.chunks.find(item => !state.analyses[item.chunkId]);
+        if (!chunk) { state.stage = "synthesizing"; resumePath = snapshot(config, state); step--; continue; }
+        const media = await getMedia(chunk);
+        media.workTitle = state.workTitle;
+        const previous = Object.values(state.analyses).filter(item => item.sourceId === chunk.sourceId && item.startMs < chunk.startMs).sort((a, b) => b.startMs - a.startMs)[0];
+        if (previous) media.priorContext = JSON.stringify({ previousSummary: previous.summary, observedCharacters: previous.characters }).slice(0, 12000);
+        const response = await charge("analyzing", chunk.chunkId, "/api/tracker/review/analyze-chunk", media);
+        state.analyses[chunk.chunkId] = checkedAnalysis(response, chunk, media);
+      } else if (state.stage === "synthesizing") {
+        const body = { sources: reviewPublicSources(state.sources), chunks: Object.values(state.analyses), workTitle: state.workTitle };
+        textBudget(body);
+        state.storyResult = await charge("synthesizing", "", "/api/tracker/review/synthesize-story", body);
+        state.verifyChunkIds = verificationGroups(state);
+        state.stage = "verifying";
+      } else if (state.stage === "verifying") {
+        const id = state.verifyChunkIds.find(chunkId => !state.verifications[chunkId]);
+        if (!id) { state.stage = "finalizing"; step--; continue; }
+        const chunk = state.chunks.find(item => item.chunkId === id), analyzed = state.analyses[id];
+        const media = await getMedia(chunk, analyzed.sha256);
+        const response = await charge("verifying", id, "/api/tracker/review/verify-evidence", { story: state.storyResult.story, chunks: Object.values(state.analyses), chunk: media });
+        if (response.chunkId !== id || !Array.isArray(response.verdicts) || !response.verdicts.length || response.verdicts.some(item => item.status !== "supported")) throw fail("REVIEW_ORIGINAL_VERIFICATION_FAILED", "원본 재검증에서 모순되거나 근거가 부족한 주장이 발견되었습니다. 전체 이해 완료나 자동 기획으로 진행하지 않습니다. 사용자가 줄거리·근거를 검토해야 합니다.");
+        state.verifications[id] = response;
+      } else if (state.stage === "finalizing") {
+        const completed = { kind: "aimakeall-review-sources", version: 1, analysisScope: "full", analysisId: state.analysisId,
+          sources: state.sources, sourceCatalog: Object.values(state.analyses).flatMap(chunk => chunk.sceneCatalog), globalStory: state.storyResult.story,
+          fullTranscriptSegments: (state.storyResult.transcriptSegments || []).map(segment => {
+            const owner = Object.values(state.analyses).find(chunk => chunk.transcriptSegments.some(item => item.id === segment.id));
+            if (!owner) throw fail("REVIEW_TRANSCRIPT_REFERENCE_INVALID", "전체 전사의 원본 근거 ID가 없습니다.");
+            return { ...segment, sourceId: owner.sourceId, reviewSourceId: owner.sourceId };
+          }), coverage: state.storyResult.coverage,
+          originalVerification: { complete: true, results: Object.values(state.verifications) }, warnings: state.warnings, receipts: state.receipts };
+        if (!Array.isArray(completed.sourceCatalog) || !completed.sourceCatalog.length || !Array.isArray(completed.fullTranscriptSegments)) throw fail("REVIEW_FULL_RESULT_INCOMPLETE", "전체 분석 카탈로그 또는 대본이 없어 완료할 수 없습니다.");
+        textBudget(completed);
+        state.reviewSourcePath = savePayloadHandle(config.stateDir, completed, "review-sources-full").filePath;
+        state.stage = "complete";
+      }
+      delete state.inFlight; delete state.failedStage;
+      delete state.pendingStageResult;
+      resumePath = snapshot(config, state);
+      await progress();
+      if (state.stage === "complete") break;
+    }
+    return summary(state, resumePath);
+  } catch (error) {
+    if (!state) throw error;
+    state.failedStage ||= state.stage; state.stage = "blocked";
+    state.error = { code: error.errorCode || error.code || "REVIEW_FULL_ANALYSIS_FAILED", message: String(error.message || error) };
+    if (state.pendingStageResult) {
+      state.failedStageResultPath = savePayloadHandle(config.stateDir, { kind: "aimakeall-review-failed-stage", version: 1, analysisId: state.analysisId, stage: state.failedStage, result: state.pendingStageResult }, "review-failed-stage").filePath;
+      delete state.pendingStageResult;
+    }
+    resumePath = snapshot(config, state);
+    return { ...summary(state, resumePath), requiresExplicitRetryApproval: true };
+  } finally { release(); }
+}

package/lib/review-sources.mjs

@@ -0,0 +1,106 @@
+import { closeSync, openSync, readSync, realpathSync, statSync } from "node:fs";
+import path from "node:path";
+import { canonicalYoutubeWatchUrl, sanitizeRenderPayload } from "./payload-guard.mjs";
+import { readPayloadHandle, savePayloadHandle } from "./media-store.mjs";
+
+export const REVIEW_EVIDENCE_BUDGET = 12 * 1024 * 1024;
+export const REVIEW_MAX_FRAMES = 18; // existing /shots and video-analysis ceiling
+const VIDEO_EXTENSIONS = new Set([".mp4", ".mov", ".m4v", ".mkv", ".webm"]);
+
+// Read only a container header; never read/upload the whole movie. Resolve symlinks
+// before fingerprinting so a changed target cannot silently enter a later render.
+export function inspectReviewLocalFile(filePath, expected = null) {
+  const resolved = realpathSync(String(filePath || ""));
+  if (!VIDEO_EXTENSIONS.has(path.extname(resolved).toLowerCase())) throw new Error("리뷰 원본은 MP4/MOV/M4V/MKV/WebM 영상 파일이어야 합니다.");
+  const stat = statSync(resolved);
+  if (!stat.isFile() || stat.size < 12 || stat.size > 64 * 1024 ** 3) throw new Error("리뷰 원본은 64GB 이하의 정상 영상 파일이어야 합니다.");
+  const fd = openSync(resolved, "r");
+  const header = Buffer.alloc(16);
+  try { readSync(fd, header, 0, header.length, 0); } finally { closeSync(fd); }
+  if (header.toString("ascii", 4, 8) !== "ftyp" && header.readUInt32BE(0) !== 0x1a45dfa3) throw new Error("파일의 실제 영상 컨테이너 형식을 확인하지 못했습니다.");
+  const fingerprint = { path: resolved, size: stat.size, mtimeMs: stat.mtimeMs };
+  if (expected && (expected.path !== resolved || expected.size !== stat.size || expected.mtimeMs !== stat.mtimeMs)) throw new Error("분석 후 로컬 원본이 변경되었습니다. 원본 분석을 다시 진행하세요.");
+  return fingerprint;
+}
+
+export function readReviewHandle(stateDir, filePath, kind = "aimakeall-review-sources") {
+  const media = realpathSync(path.join(stateDir, "media"));
+  const resolved = realpathSync(String(filePath || ""));
+  if (!resolved.startsWith(media + path.sep)) throw new Error("리뷰 핸들은 이 MCP가 저장한 media 파일이어야 합니다.");
+  if (statSync(resolved).size > REVIEW_EVIDENCE_BUDGET) throw new Error("리뷰 핸들 크기 한도를 초과했습니다.");
+  // The realpath containment check above also handles macOS /var → /private/var.
+  const value = readPayloadHandle(resolved);
+  if (value?.kind !== kind || value.version !== 1) throw new Error("올바른 리뷰 핸들이 아닙니다.");
+  return value;
+}
+
+export function reviewPublicSources(sources) {
+  return sources.map(source => ({ id: source.id, kind: source.kind, videoId: source.videoId || "", title: source.title || "", durationSec: source.durationSec }));
+}
+
+export function assertReviewBudget(value) {
+  if (Buffer.byteLength(JSON.stringify(value), "utf8") > REVIEW_EVIDENCE_BUDGET) throw new Error("리뷰 분석 자료가 12MB를 초과했습니다. 원본 수나 프레임 수를 줄이세요. 원본 전체 업로드는 하지 않습니다.");
+}
+
+export function validateReviewSources(sources) {
+  if (!Array.isArray(sources) || !sources.length || sources.length > 5) throw new Error("리뷰 원본은 1~5개가 필요합니다.");
+  const ids = new Set();
+  for (const source of sources) {
+    if (!source?.id || ids.has(source.id)) throw new Error("리뷰 원본 ID가 없거나 중복입니다.");
+    ids.add(source.id);
+    if (!Number.isFinite(source.durationSec) || !(source.durationSec > 0) || source.durationSec > 86400) throw new Error("리뷰 원본 길이는 24시간 이하의 실측값이어야 합니다.");
+    if (source.kind === "local") {
+      if (!source.fingerprint || !Number.isFinite(source.fingerprint.size) || !Number.isFinite(source.fingerprint.mtimeMs)) throw new Error("로컬 리뷰 원본의 분석 지문이 없습니다.");
+      inspectReviewLocalFile(source.localPath, source.fingerprint);
+    }
+    else if (source.kind !== "youtube" || !canonicalYoutubeWatchUrl(source.videoId)) throw new Error("리뷰 원본 유형 또는 YouTube ID가 올바르지 않습니다.");
+  }
+}
+
+// The server may return only opaque source IDs. Never trust a server-supplied
+// local path/binding. The bindings below are created solely from a local handle.
+export function bindReviewRenderSources(stateDir, serverPayload, reviewSourcePath) {
+  const sourcesHandle = readReviewHandle(stateDir, reviewSourcePath);
+  validateReviewSources(sourcesHandle.sources);
+  const { payload, warnings } = sanitizeRenderPayload(serverPayload);
+  delete payload.reviewBindingPath;
+  const sources = new Map(sourcesHandle.sources.map(source => [source.id, source]));
+  const bindings = [];
+  const assetIds = new Set();
+  for (const asset of payload.assets || []) {
+    if (!asset?.id || assetIds.has(asset.id)) throw new Error("리뷰 렌더 자산 ID가 없거나 중복입니다.");
+    assetIds.add(asset.id);
+    if (!asset.reviewSourceId) continue;
+    if (asset.kind !== "video" || !sources.has(asset.reviewSourceId)) throw new Error("서버가 알 수 없는 리뷰 원본을 참조했습니다.");
+    for (const key of ["path", "url", "sourceUrl", "dataUrl", "youtubeUrl", "companionFileUrl"]) delete asset[key];
+    bindings.push({ assetId: asset.id, sourceId: asset.reviewSourceId });
+  }
+  if (!bindings.length) throw new Error("리뷰 렌더에 원본 영상 바인딩이 없습니다.");
+  payload.reviewBindingPath = savePayloadHandle(stateDir, {
+    kind: "aimakeall-review-bindings", version: 1, reviewSourcePath, bindings,
+  }, "review-bindings").filePath;
+  // Validate now, but paths are attached again only at local render submission.
+  restoreReviewRenderSources(structuredClone(payload), { stateDir, fromSavedPayload: true });
+  return { payload, warnings };
+}
+
+export function restoreReviewRenderSources(payload, { stateDir, fromSavedPayload = false } = {}) {
+  if (!payload.reviewBindingPath) return payload;
+  if (!fromSavedPayload) throw new Error("로컬 리뷰 원본은 prepare_review_timeline이 반환한 payloadPath로만 렌더할 수 있습니다.");
+  const handle = readReviewHandle(stateDir, payload.reviewBindingPath, "aimakeall-review-bindings");
+  const sourcesHandle = readReviewHandle(stateDir, handle.reviewSourcePath);
+  validateReviewSources(sourcesHandle.sources);
+  const sources = new Map(sourcesHandle.sources.map(source => [source.id, source]));
+  const assets = new Map((payload.assets || []).map(asset => [asset.id, asset]));
+  if (assets.size !== (payload.assets || []).length || !Array.isArray(handle.bindings) || !handle.bindings.length) throw new Error("리뷰 자산 또는 원본 바인딩이 없거나 중복입니다.");
+  const boundAssetIds = new Set(handle.bindings.map(binding => binding.assetId));
+  if (boundAssetIds.size !== handle.bindings.length || [...assets.values()].some(asset => asset.reviewSourceId && !boundAssetIds.has(asset.id))) throw new Error("리뷰 원본 바인딩이 변경되었거나 누락되었습니다.");
+  for (const binding of handle.bindings || []) {
+    const source = sources.get(binding.sourceId), asset = assets.get(binding.assetId);
+    if (!source || !asset || asset.kind !== "video" || asset.reviewSourceId !== source.id) throw new Error("리뷰 원본 바인딩이 변경되었거나 일치하지 않습니다.");
+    for (const key of ["path", "url", "sourceUrl", "dataUrl", "youtubeUrl", "companionFileUrl"]) delete asset[key];
+    if (source.kind === "local") asset.path = inspectReviewLocalFile(source.localPath, source.fingerprint).path;
+    else asset.youtubeUrl = canonicalYoutubeWatchUrl(source.videoId);
+  }
+  return payload;
+}

package/lib/review-tools.mjs

@@ -0,0 +1,285 @@
+import { randomUUID } from "node:crypto";
+import { z } from "zod";
+import { composerOverlay, composerTextStyle } from "./production-schemas.mjs";
+import { canonicalYoutubeWatchUrl } from "./payload-guard.mjs";
+import { savePayloadHandle } from "./media-store.mjs";
+import { readProductionContext, saveProductionContext } from "./production-context.mjs";
+import { TTS_PROVIDERS, buildTtsRequestBody, requestTtsBinary, resolveTtsSelection } from "./tts-workflow.mjs";
+import { wavDurationSec } from "./audio-duration.mjs";
+import { mp3DurationSec } from "./mp3-duration.mjs";
+import { createUsageEventId } from "./usage-event.mjs";
+import { assertReviewBudget, bindReviewRenderSources, inspectReviewLocalFile, readReviewHandle, REVIEW_MAX_FRAMES, reviewPublicSources, validateReviewSources } from "./review-sources.mjs";
+import { fullReviewStatus, runFullReviewAnalysis, selectReviewPlanningCatalog } from "./review-full-analysis.mjs";
+
+const spoiler = z.enum(["none", "limited", "full", "unknown"]);
+const interval = z.object({ startMs: z.number().int().min(0), endMs: z.number().int().positive(),
+  note: z.string().max(2000).optional(), dialogueText: z.string().max(2000).optional(),
+  spoilerLevel: spoiler.optional(),
+}).refine(value => value.endMs > value.startMs, "구간 끝은 시작 이후여야 합니다.");
+const transcript = z.object({ startMs: z.number().int().min(0), endMs: z.number().int().positive(), text: z.string().max(2000) })
+  .refine(value => value.endMs > value.startMs, "대본 구간 끝은 시작 이후여야 합니다.");
+const sourceInput = z.object({
+  kind: z.enum(["youtube", "local"]), videoId: z.string().optional(), videoPath: z.string().optional(),
+  title: z.string().max(300).optional(), segments: z.array(interval).max(REVIEW_MAX_FRAMES).optional(),
+  transcriptSegments: z.array(transcript).max(200).optional(),
+}).superRefine((source, ctx) => {
+  if (source.kind === "local" ? (!source.videoPath || source.videoId) : (!canonicalYoutubeWatchUrl(source.videoId) || source.videoPath)) {
+    ctx.addIssue({ code: z.ZodIssueCode.custom, message: "local은 videoPath만, youtube는 videoId 또는 YouTube URL만 지정하세요." });
+  }
+});
+const result = value => ({ content: [{ type: "text", text: JSON.stringify(value, null, 2) }] });
+const COVERAGE_WARNING = "대표 프레임과 제공된 구간 메모/대본만 분석했습니다. 원작 전체를 시청·전사한 결과가 아니며 사건·대사·스포일러는 공개 전에 직접 확인해야 합니다.";
+
+function processReviewResponse(receipt, process) {
+  try { return process(); }
+  catch (error) {
+    for (const key of ["accountCostEvents", "acceptedTaskCosts", "operationId", "costUsd", "usage", "partialProviderUsage"]) {
+      if (receipt?.[key] !== undefined) error[key] = receipt[key];
+    }
+    throw error;
+  }
+}
+
+async function companionJson(config, route, body, timeoutMs = 240_000, retryBusy = true) {
+  if (!config.companionUrl) throw new Error("리뷰 원본 분석에는 로컬 컴패니언이 필요합니다.");
+  const response = await fetch(`${config.companionUrl}${route}`, {
+    method: route === "/health" ? "GET" : "POST", headers: { "Content-Type": "application/json" }, ...(body !== undefined ? { body: JSON.stringify(body) } : {}), signal: AbortSignal.timeout(timeoutMs),
+  });
+  if (response.status === 429 && retryBusy && route.startsWith("/api/review/")) {
+    // Local extraction cooldown only; never retry a paid cloud request.
+    await new Promise(resolve => setTimeout(resolve, 550));
+    return companionJson(config, route, body, timeoutMs, false);
+  }
+  if (!response.ok) {
+    let details = {};
+    try { details = await response.json(); } catch { /* no usable local diagnostic */ }
+    throw Object.assign(new Error(`컴패니언 원본 분석 실패 (HTTP ${response.status}). ${details.message || "원본 파일과 로컬 처리기를 확인하세요."}`), { status: response.status, code: details.code || details.errorCode || details.error || "REVIEW_COMPANION_FAILED" });
+  }
+  const bodyText = await response.text();
+  if (Buffer.byteLength(bodyText) > 15 * 1024 * 1024) throw new Error("컴패니언 분석 응답이 15MiB를 초과했습니다. 전체 영상 대신 제한된 크기 청크가 필요합니다.");
+  return JSON.parse(bodyText);
+}
+
+function checkedSamples(samples, durationMs) {
+  if (!samples.length || samples.length > REVIEW_MAX_FRAMES) throw new Error("유효한 리뷰 샘플이 없습니다.");
+  return samples.map((sample, index) => {
+    const startMs = Math.round(Number(sample.startMs)), endMs = Math.round(Number(sample.endMs));
+    if (!Number.isFinite(startMs) || !Number.isFinite(endMs) || startMs < 0 || endMs <= startMs || endMs > durationMs + 1) throw new Error("리뷰 샘플 구간이 원본 길이를 벗어납니다.");
+    return { ...sample, startMs, endMs, shotId: `R-${index + 1}`, representativeMs: Math.round(Math.max(startMs, Math.min(endMs, Number(sample.representativeMs) || (startMs + endMs) / 2))) };
+  });
+}
+
+function safeImage(sample) {
+  const mimeType = String(sample.mimeType || "image/jpeg").toLowerCase();
+  const imageBase64 = String(sample.imageBase64 || "");
+  if (!["image/jpeg", "image/png", "image/webp"].includes(mimeType) || !/^[A-Za-z0-9+/]+={0,2}$/.test(imageBase64) || imageBase64.length > 700_000) throw new Error("리뷰 샘플 이미지 형식 또는 크기가 잘못되었습니다.");
+  return { mimeType, imageBase64 };
+}
+
+function uniqueIntervalSeconds(intervals) {
+  let total = 0, end = 0;
+  for (const item of [...intervals].sort((a, b) => a.startMs - b.startMs)) {
+    total += Math.max(0, item.endMs - Math.max(end, item.startMs));
+    end = Math.max(end, item.endMs);
+  }
+  return Math.round(total) / 1000;
+}
+
+export function registerReviewTools(server, config, api, { wrap = handler => handler } = {}) {
+  const wrapReview = handler => wrap(async (args, extra) => {
+    try { return await handler(args, extra); }
+    catch (error) {
+      return { ...result({ error: error.errorCode || error.code || "REVIEW_OPERATION_FAILED", message: String(error?.message || error),
+        operationId: error.operationId || "", accountCostEvents: error.accountCostEvents || [], acceptedTaskCosts: error.acceptedTaskCosts || [], costUsd: error.costUsd || 0,
+        usage: error.usage || null, partialProviderUsage: error.partialProviderUsage === true,
+        warning: "자동 재시도하지 않았습니다. 이미 접수된 합성과 비용 원장을 확인한 뒤 재실행 여부를 결정하세요." }), isError: true };
+    }
+  });
+  server.tool("analyze_review_sources",
+    "영화·드라마 전체 영상+오디오를 Gemini 3.8로 분석하고 서사와 원본 근거를 재검증합니다. 기본 full은 모든 구간을 최대300초 MP4로 압축하여 클라우드에 전송하므로 사용자 업로드·과금 동의 후 allowCloudVideoUpload:true 필수. 첫 호출은 무료 원본 검사/범위 준비만, 이후 resumePath로 기본1단계씩 계속하세요. 완료된 청크는 재과금하지 않으며 실패 재시도는 명시 승인 필요. 대표 프레임 점검만 원하면 analysisScope:'sample'을 명시하세요(전체 이해가 아님).",
+    { sources: z.array(sourceInput).min(1).max(5).optional(), analysisScope: z.enum(["full", "sample"]).optional(),
+      allowCloudVideoUpload: z.boolean().optional(), resumePath: z.string().optional(), workTitle: z.string().max(200).optional(),
+      maxSteps: z.number().int().min(1).max(4).optional(), retryFailedStage: z.boolean().optional(),
+      maxFrames: z.number().int().min(3).max(REVIEW_MAX_FRAMES).optional() },
+    wrapReview(async (args, extra) => {
+      if (args.analysisScope !== "sample") return result(await runFullReviewAnalysis({ config, api, args, companionJson,
+        onProgress: extra?._meta?.progressToken !== undefined && extra?.sendNotification ? value => extra.sendNotification({ method: "notifications/progress", params: {
+          progressToken: extra._meta.progressToken, progress: value.progress.completedChunks + value.progress.completedVerifications + (["verifying", "finalizing", "complete"].includes(value.progress.stage) ? 1 : 0),
+          total: value.progress.totalChunks + 1 + (value.progress.totalVerifications || value.progress.totalChunks),
+          message: `${value.progress.stage}: ${value.progress.completedChunks}/${value.progress.totalChunks} 청크, 검증 ${value.progress.completedVerifications}. 체크포인트 ${value.resumePath}`,
+        } }) : undefined,
+      }));
+      if (args.resumePath) throw new Error("전체 분석 resumePath를 sample 점검으로 바꿀 수 없습니다.");
+      const { sources: inputs, maxFrames = 12 } = args;
+      if (!inputs?.length) throw new Error("샘플 점검할 sources가 필요합니다.");
+      const sources = [], preDetectedShots = {}, videos = [], samplesById = new Map(), coverage = [];
+      // Validate every local file before any provider call.
+      const fingerprints = inputs.map(source => source.kind === "local" ? inspectReviewLocalFile(source.videoPath) : null);
+      for (const [index, input] of inputs.entries()) {
+        const id = `review-${randomUUID().slice(0, 8)}`;
+        const source = { id, kind: input.kind, title: input.title || `리뷰 원본 ${index + 1}` };
+        let samples;
+        if (input.kind === "local") {
+          source.localPath = fingerprints[index].path;
+          source.fingerprint = fingerprints[index];
+          const inspected = await companionJson(config, "/api/moviepy/inspect", { sources: [{ id, path: source.localPath, kind: "video" }] });
+          const info = inspected.sources?.find(item => item.id === id);
+          if (info?.ok !== true || !(info.durationSec > 0) || info.kind !== "video") throw new Error("로컬 원본의 실제 영상 길이를 확인하지 못했습니다.");
+          source.durationSec = Number(info.durationSec);
+          const durationMs = source.durationSec * 1000;
+          samples = checkedSamples(input.segments?.length ? input.segments : Array.from({ length: maxFrames }, (_, i) => {
+            const center = durationMs * (i + 0.5) / maxFrames;
+            return { startMs: Math.max(0, center - 3000), endMs: Math.min(durationMs, center + 3000) };
+          }), durationMs);
+          const frames = await companionJson(config, "/api/frames", { videoPath: source.localPath, timestampsMs: samples.map(item => item.representativeMs), width: 480, quality: 5 });
+          if (!Array.isArray(frames.frames) || frames.frames.length !== samples.length) throw new Error("필요한 리뷰 프레임을 모두 추출하지 못했습니다.");
+          samples = samples.map((sample, i) => ({ ...sample, ...safeImage(frames.frames[i]) }));
+        } else {
+          source.youtubeUrl = canonicalYoutubeWatchUrl(input.videoId);
+          source.videoId = new URL(source.youtubeUrl).searchParams.get("v");
+          const shots = await companionJson(config, "/api/shots", { url: source.youtubeUrl, maxShots: maxFrames, minGapMs: 1400, sceneThreshold: 0.22, width: 480, quality: 5 });
+          if (!Array.isArray(shots.shots) || !shots.shots.length) throw new Error("YouTube 원본에서 리뷰 구간을 찾지 못했습니다.");
+          source.durationSec = Number(shots.durationMs || Math.max(...shots.shots.map(item => Number(item.endMs) || 0))) / 1000;
+          if (input.segments?.length) {
+            samples = checkedSamples(input.segments, source.durationSec * 1000);
+            const frames = await companionJson(config, "/api/frames", { url: source.youtubeUrl, timestampsMs: samples.map(item => item.representativeMs), width: 480, quality: 5 });
+            if (frames.frames?.length !== samples.length) throw new Error("YouTube 리뷰 구간 프레임이 누락되었습니다.");
+            samples = samples.map((sample, i) => ({ ...sample, ...safeImage(frames.frames[i]) }));
+          } else samples = checkedSamples(shots.shots, source.durationSec * 1000).map(sample => ({ ...sample, ...safeImage(sample) }));
+        }
+        const transcriptSegments = (input.transcriptSegments || []).map(item => ({ startMs: item.startMs, endMs: item.endMs, text: item.text }));
+        if (transcriptSegments.some(item => item.startMs < 0 || item.endMs <= item.startMs || item.endMs > source.durationSec * 1000 + 1)) throw new Error("제공된 대본 구간이 원본 길이를 벗어납니다.");
+        samples = samples.map(sample => ({ ...sample, dialogueText: sample.dialogueText || transcriptSegments
+          .filter(item => item.startMs >= sample.startMs && item.endMs <= sample.endMs)
+          .sort((a, b) => a.startMs - b.startMs).map(item => item.text).join(" ").slice(0, 3000) }));
+        coverage.push({ reviewSourceId: id, durationSec: source.durationSec, representativeFrameCount: samples.length,
+          sampledWindowSeconds: uniqueIntervalSeconds(samples), transcriptSeconds: uniqueIntervalSeconds(transcriptSegments),
+          explicitWindows: Boolean(input.segments?.length), completeSourceObserved: false });
+        source.videoId ||= "";
+        sources.push(source);
+        samplesById.set(id, samples);
+        preDetectedShots[id] = samples.map(sample => ({ shotId: sample.shotId, startMs: sample.startMs, endMs: sample.endMs, representativeMs: sample.representativeMs, ...safeImage(sample) }));
+        for (const sample of samples) if (sample.dialogueText) transcriptSegments.push({ startMs: sample.startMs, endMs: sample.endMs, text: sample.dialogueText });
+        videos.push({ id, title: source.title, durationSeconds: source.durationSec, frameSamples: [], transcriptSegments,
+          description: samples.map(sample => sample.note || "").filter(Boolean).join(" / ").slice(0, 500),
+        });
+      }
+      validateReviewSources(sources);
+      const body = { videos, preDetectedShots };
+      assertReviewBudget(body);
+      const analysis = await api.request("/api/tracker/gemini/video-analysis", { body, method: "POST", timeoutMs: 240_000 });
+      return processReviewResponse(analysis, () => {
+      const sourceCatalog = [];
+      for (const source of sources) {
+        const analyzed = analysis.videos?.find(video => video.id === source.id);
+        for (const sample of samplesById.get(source.id)) {
+          const scene = analyzed?.sceneCatalog?.find(item => item.shotId === sample.shotId || (Number(item.startMs) === sample.startMs && Number(item.endMs) === sample.endMs));
+          // The legacy analyzer fills shortLabel with a timestamp even when no
+          // observation was produced. A time label is not narrative evidence.
+          const description = [String(scene?.visualSummary || "").trim().slice(0, 800), sample.note?.trim() ? `제공된 구간 메모: ${sample.note.trim().slice(0, 350)}` : ""].filter(Boolean).join(" / ");
+          if (!description) continue;
+          sourceCatalog.push({ sourceId: `${source.id}:${sample.shotId}`, reviewSourceId: source.id, videoId: source.videoId,
+            startMs: sample.startMs, endMs: sample.endMs, description: description.slice(0, 1200),
+            dialogueText: sample.dialogueText || "", spoilerLevel: sample.spoilerLevel || "unknown",
+          });
+        }
+      }
+      if (!sourceCatalog.length) throw new Error("확인 가능한 리뷰 장면 설명을 얻지 못했습니다. 주요 구간과 메모를 제공하세요.");
+      const warnings = [COVERAGE_WARNING, "스포일러 등급은 사용자가 지정한 구간만 확인됨으로 취급합니다. unknown 구간은 none/limited 기획에서 제외됩니다.",
+        ...coverage.map(item => `원본 ${item.reviewSourceId}: ${item.durationSec}초 중 대표 프레임 ${item.representativeFrameCount}장, 선택 구간 합계(중복 제외) ${item.sampledWindowSeconds}초, 제공 대본 ${item.transcriptSeconds}초. 구간 전체를 관찰했다는 뜻은 아닙니다.${item.explicitWindows ? "" : " 로컬 기본 샘플은 원본당 12개 × 6초(총 72초) 수준이므로 긴 리뷰에는 핵심 장면 구간·대본·메모를 추가하세요."}`)];
+      const reviewSourcePath = savePayloadHandle(config.stateDir, { kind: "aimakeall-review-sources", version: 1, analysisScope: "sample", sources, sourceCatalog, coverage, warnings }, "review-sources").filePath;
+      return result({ analysisScope: "sample", completeSourceObserved: false, reviewSourcePath, sources: reviewPublicSources(sources), sourceCatalog, coverage, warnings, requiresHumanReview: true,
+        usage: analysis.usage, accountCostEvents: analysis.accountCostEvents || [], costUsd: analysis.costUsd });
+      });
+    }));
+
+  server.tool("review_analysis_status", "전체 원작 분석의 최신 진행률·청크 완료·원본 검증·누적 비용을 조회합니다. 유료 API를 호출하지 않습니다. 오래된 resumePath도 최신 체크포인트를 찾아 반환합니다.",
+    { resumePath: z.string() }, wrapReview(async ({ resumePath }) => result(fullReviewStatus(config, resumePath))));
+
+  server.tool("plan_review_video",
+    "검토한 영화·드라마 원본 카탈로그로 60~900초 리뷰를 기획합니다. 원작 사실·해석·가상해석을 구분하며 spoilerPolicy를 지킵니다. reviewSourcePath는 analyze_review_sources 결과. 영화 전체를 봤다고 가정하지 않으며 기획에 분석 과금이 발생할 수 있습니다. 반환 productionPath를 보이스 추천·리뷰 편집에 전달하세요.",
+    { reviewSourcePath: z.string(), workType: z.enum(["film", "drama"]), workTitle: z.string().min(1).max(200), episode: z.string().max(100).optional(),
+      targetDurationSec: z.number().min(60).max(900), spoilerPolicy: z.enum(["none", "limited", "full"]),
+      deliveryStyle: z.enum(["casual-social", "standard", "news-briefing"]).optional(), reviewAngle: z.string().max(2000).optional(),
+      provider: z.enum(["auto", ...TTS_PROVIDERS]).optional(), voiceId: z.string().optional(),
+      allowPartialSourceReview: z.boolean().optional().describe("명시 sample 점검 자료만으로 부분 구간 리뷰를 만드는 경우에만 true. 원작 전체 리뷰로 표현하지 않음"),
+      sourceIds: z.array(z.string()).min(1).max(500).optional().describe("이번 편집에 사용할 장면 sourceId 후보만 명시 선택. 전편 줄거리·전사는 그대로 보존"),
+    }, wrapReview(async ({ reviewSourcePath, provider, voiceId, allowPartialSourceReview, sourceIds, ...input }) => {
+      const handle = readReviewHandle(config.stateDir, reviewSourcePath);
+      validateReviewSources(handle.sources);
+      if (handle.analysisScope !== "full" && allowPartialSourceReview !== true) throw new Error("원작 전체 리뷰에는 full 분석 및 원본 재검증이 완료된 핸들이 필요합니다. 샘플만으로 전체를 이해했다고 가정하지 않습니다. 부분 구간 리뷰라면 allowPartialSourceReview:true를 명시하세요.");
+      if (handle.analysisScope === "full" && handle.originalVerification?.complete !== true) throw new Error("전체 원본 재검증이 완료되지 않아 리뷰 기획을 진행할 수 없습니다.");
+      if (voiceId && (!provider || provider === "auto")) throw new Error("명시한 보이스 ID의 공급자도 함께 지정하세요.");
+      const selection = selectReviewPlanningCatalog(handle, sourceIds);
+      const plan = await api.request("/api/tracker/review/plan", { body: { ...input, deliveryStyle: input.deliveryStyle || "casual-social", sourceCatalog: selection.sourceCatalog,
+        ...(handle.analysisScope === "full" ? { analysisScope: "full", globalStory: handle.globalStory, fullTranscriptSegments: handle.fullTranscriptSegments, originalVerification: handle.originalVerification, sourceCoverage: handle.coverage } : { analysisScope: "sample" }),
+      }, method: "POST", timeoutMs: 600_000 });
+      return processReviewResponse(plan, () => {
+      if (!plan?.reviewProfile || !Array.isArray(plan.version?.rows) || !plan.version.rows.length) throw new Error("리뷰 기획 응답에 프로필 또는 편집 행이 없습니다.");
+      const productionPath = saveProductionContext(config.stateDir, { reviewSourcePath, reviewProfile: plan.reviewProfile, topic: input.workTitle,
+        productionProfile: plan.productionProfile, reviewVersion: plan.version, sourceCatalog: selection.sourceCatalog, catalogSelection: selection.catalogSelection,
+        ...(handle.analysisScope === "full" ? { globalStory: handle.globalStory, fullTranscriptSegments: handle.fullTranscriptSegments, originalVerification: handle.originalVerification, analysisScope: "full" } : { analysisScope: "sample" }),
+        narrationScript: plan.version.rows.filter(row => row.mode === "N").map(row => row.audioContent || "").join("\n"),
+        warnings: [...handle.warnings, ...(plan.warnings || [])],
+        ...(provider && provider !== "auto" ? { voice: { provider, ...(voiceId ? { voiceId } : {}) } } : {}),
+      });
+      return result({ ...plan, productionPath, catalogSelection: selection.catalogSelection, warnings: [...handle.warnings, ...(plan.warnings || [])], requiresHumanReview: true });
+      });
+    }));
+
+  server.tool("prepare_review_timeline",
+    "영화·드라마 리뷰 기획 핸들에서 원본 컷·실측 TTS·자막·자동 라이브러리 편집을 준비합니다. N행은 TTS 과금이 있으므로 사용자에게 비용을 알리고 실행하세요. 실패한 합성을 자동 재시도하거나 다른 공급자로 바꾸지 않습니다. 로컬 원본 경로는 서버에 보내지 않으며 반환 payloadPath를 render_start에 전달하세요.",
+    { productionPath: z.string(), provider: z.enum(["auto", ...TTS_PROVIDERS]).optional(), voiceId: z.string().optional(),
+      aspectRatio: z.enum(["16:9", "9:16", "1:1"]).optional(), autoCompose: z.boolean().optional(),
+      decorationRationale: z.string().max(1500).optional(),
+      titleStylePresetId: z.string().optional(), subtitleStylePresetId: z.string().optional(), titleStyle: composerTextStyle.optional(), subtitleStyle: composerTextStyle.optional(),
+      overlays: z.array(composerOverlay).max(40).optional(),
+    }, wrapReview(async ({ productionPath, provider, voiceId, ...options }) => {
+      const context = readProductionContext(config.stateDir, productionPath);
+      if (!context?.reviewProfile || !context.reviewVersion || !context.reviewSourcePath) throw new Error("plan_review_video가 반환한 리뷰 제작 핸들이 필요합니다.");
+      const sourcesHandle = readReviewHandle(config.stateDir, context.reviewSourcePath);
+      validateReviewSources(sourcesHandle.sources);
+      const hasNarration = context.reviewVersion.rows.some(row => row.mode === "N" && row.audioContent?.trim());
+      const explicitVoice = String(voiceId || "").trim();
+      const knownVoice = context.voice?.voiceId || context.voice?.id;
+      if (explicitVoice && (!provider || provider === "auto") && !(context.voice?.provider && explicitVoice === knownVoice)) throw new Error("명시한 보이스 ID의 공급자도 함께 지정하세요. 기존 제작 핸들에 저장된 동일 보이스만 공급자 생략이 가능합니다.");
+      const selection = hasNarration ? await resolveTtsSelection(api, config, { provider: explicitVoice && (!provider || provider === "auto") ? context.voice.provider : provider, context }) : { provider: "typecast", executionTarget: "server" };
+      if (!explicitVoice && knownVoice && selection.provider !== context.voice.provider) throw new Error("공급자를 변경하려면 해당 공급자의 보이스 ID를 명시하세요.");
+      const selectedVoice = explicitVoice || context.voice?.voiceId || context.voice?.id || "";
+      if (hasNarration && !selectedVoice && context.reviewProfile.deliveryStyle === "casual-social") throw new Error("먼저 recommend_voice에 productionPath를 전달하여 리뷰형 보이스를 선택하거나 voiceId를 명시하세요.");
+      let preSynthesizedNarrations;
+      if (hasNarration && selection.executionTarget === "companion") {
+        const narrations = {};
+        for (const [index, row] of context.reviewVersion.rows.entries()) {
+          if (row.mode !== "N" || !row.audioContent?.trim()) continue;
+          const audio = await requestTtsBinary(api, config, selection, buildTtsRequestBody(selection.provider, { text: row.audioContent, voice: selectedVoice, productionProfile: context.productionProfile }));
+          const durationSec = audio.buffer.toString("ascii", 0, 4) === "RIFF" ? wavDurationSec(audio.buffer) : mp3DurationSec(audio.buffer);
+          if (!(durationSec > 0)) throw new Error("리뷰 내레이션 길이를 측정하지 못했습니다. 자동 재합성하지 않습니다.");
+          narrations[index] = { dataUrl: `data:${audio.contentType};base64,${audio.buffer.toString("base64")}`, durationSec,
+            charCount: Array.from(row.audioContent).length, provider: selection.provider, voiceId: selectedVoice };
+        }
+        preSynthesizedNarrations = { narrations, attempted: Object.keys(narrations).length, succeeded: Object.keys(narrations).length, lastError: "" };
+      }
+      const body = { ...options, aspectRatio: options.aspectRatio || "16:9", autoCompose: options.autoCompose ?? true,
+        reviewProfile: context.reviewProfile, productionProfile: context.productionProfile, version: context.reviewVersion,
+        sourceCatalog: selectReviewPlanningCatalog(sourcesHandle, context.sourceCatalog?.map(scene => scene.sourceId)).sourceCatalog, sources: reviewPublicSources(sourcesHandle.sources),
+        provider: selection.provider, voiceId: selectedVoice, costEventId: createUsageEventId("mcp-review-tts"),
+        ...(preSynthesizedNarrations ? { preSynthesizedNarrations } : {}),
+      };
+      assertReviewBudget(body);
+      const prepared = await api.request("/api/tracker/review/prepare", { body, method: "POST", timeoutMs: 600_000 });
+      return processReviewResponse(prepared, () => {
+      if (!prepared?.payload) throw new Error("리뷰 렌더 타임라인을 준비하지 못했습니다.");
+      const { payload, warnings } = bindReviewRenderSources(config.stateDir, prepared.payload, context.reviewSourcePath);
+      payload.productionContext = { productionProfile: context.productionProfile, reviewProfile: context.reviewProfile,
+        decorationRationale: options.decorationRationale || payload.compositionReport?.autoComposition?.omissions?.join(" / ") || (options.autoCompose === false ? "사용자가 자동 소재·애니메이션 편집을 명시적으로 비활성화했습니다. 추가 장식 없이 원작 중심으로 편집합니다." : "") };
+      const handle = savePayloadHandle(config.stateDir, payload, "review");
+      const nextPath = saveProductionContext(config.stateDir, { ...context, reviewPayloadPath: handle.filePath, voice: { provider: selection.provider, voiceId: selectedVoice } });
+      return result({ payloadPath: handle.filePath, productionPath: nextPath, compositionReport: payload.compositionReport,
+        totalDurationMs: prepared.totalDurationMs, costUsd: prepared.costUsd ?? 0,
+        accountCostEvents: prepared.accountCostEvents || [], acceptedTaskCosts: prepared.acceptedTaskCosts || [], operationId: prepared.operationId || "",
+        warnings: [...(context.warnings || []), ...warnings, ...(prepared.warnings || [])], requiresHumanReview: true,
+        next: "render_start({payloadPath})로 로컬 렌더 후 영상·음성·스포일러를 직접 확인하세요." });
+      });
+    }));
+}

package/lib/tts-workflow.mjs

@@ -1,12 +1,12 @@
 export const TTS_PROVIDERS = Object.freeze(["typecast", "elevenlabs", "supertone", "edge", "supertonic2"]);
 
-export async function resolveTtsSelection(api, config, { provider = "auto", context = null } = {}) {
+export async function resolveTtsSelection(api, config, { provider = "auto", context = null, validateCredentials = true } = {}) {
   provider = provider === "auto" || !provider ? context?.voice?.provider || "auto" : provider;
   if (provider === "edge-tts") provider = "edge";
   if (provider !== "auto" && !TTS_PROVIDERS.includes(provider)) throw new Error("지원하지 않는 TTS provider입니다.");
   // Explicit paid providers and saved castings must not silently change voice.
   if (provider !== "auto" && provider !== "edge") return { provider, executionTarget: "server" };
-  const availability = await api.request("/api/tracker/tts/providers", { method: "GET", timeoutMs: 15_000 });
+  const availability = await api.request(`/api/tracker/tts/providers${validateCredentials ? "?verify=1" : ""}`, { method: "GET", timeoutMs: validateCredentials ? 60_000 : 15_000 });
   if (!Array.isArray(availability?.providers)) throw new Error("TTS 공급자 설정 응답이 없습니다. 자동 선택을 중단합니다.");
   const providers = availability.providers;
   const available = (id) => providers.some((entry) => entry.id === id && entry.available === true);
@@ -27,9 +27,9 @@ export async function resolveTtsSelection(api, config, { provider = "auto", cont
 }
 
 export function buildTtsRequestBody(provider, args = {}) {
-  const { productionProfile, text, voice = "", speed, costEventId, modelId, stability, style, similarityBoost, speakerBoost } = args;
+  const { productionProfile, text, voice = "", speed, costEventId, modelId, stability, style, similarityBoost, speakerBoost, fallbackVoices, allowProviderFallback } = args;
   const resolvedSpeed = speed ?? (productionProfile?.deliveryStyle === "casual-social" ? 1.1 : undefined);
-  const common = { productionProfile, text, voice, voiceId: voice, speed: resolvedSpeed, costEventId, fileName: "mcp-narration", modelId };
+  const common = { productionProfile, text, voice, voiceId: voice, speed: resolvedSpeed, costEventId, fileName: "mcp-narration", modelId, fallbackVoices, allowProviderFallback };
   if (provider === "typecast") return { ...common, language: "kor", emotion: "neutral", smartEmotion: true };
   if (provider === "elevenlabs") return { ...common, languageCode: "ko", stability, style, similarityBoost, speakerBoost };
   if (provider === "edge") {
@@ -41,7 +41,21 @@ export function buildTtsRequestBody(provider, args = {}) {
 }
 
 export async function requestTtsBinary(api, config, selection, body) {
-  if (selection.executionTarget !== "companion") return api.requestBinary(`/api/tracker/tts/${selection.provider}`, { body, method: "POST", timeoutMs: selection.provider === "supertonic2" ? 600_000 : 180_000 });
+  if (selection.executionTarget !== "companion") {
+    const result = await api.requestBinary(`/api/tracker/tts/${selection.provider}`, { body, method: "POST", timeoutMs: selection.provider === "supertonic2" ? 600_000 : 180_000 });
+    const actual = result.headers?.get?.("x-aimakeall-tts-provider");
+    const provider = TTS_PROVIDERS.includes(actual) ? actual : selection.provider;
+    const eventId = result.headers?.get?.("x-aio-cost-event-id");
+    const accountCostEvents = eventId ? [{ accountCostEventId: eventId,
+      createdAt: Number(result.headers.get("x-aio-cost-created-at")) || undefined,
+      costUsd: Number(result.headers.get("x-aio-cost-usd")) || 0,
+      model: result.headers.get("x-aio-cost-model") || "",
+      accountCostRecorded: result.headers.get("x-aio-cost-recorded") === "1",
+      accountCostSuppressedByReset: result.headers.get("x-aio-cost-suppressed-by-reset") === "1" }] : [];
+    return { ...result, provider, voiceId: result.headers?.get?.("x-aimakeall-tts-voice-id") || body.voiceId || "",
+      primaryProvider: selection.provider, providerFallback: provider !== selection.provider,
+      accountCostEvents, hasAccountCostEvents: true };
+  }
   const voiceId = body.voiceId || selection.localVoices?.find((voice) => voice.voiceId === "ko-KR-SunHiNeural")?.voiceId || selection.localVoices?.find((voice) => String(voice.locale || "").startsWith("ko"))?.voiceId;
   if (!voiceId) throw new Error("사용 가능한 한국어 Edge 보이스를 찾지 못했습니다. 보이스를 직접 지정하세요.");
   const response = await fetch(`${config.companionUrl}/api/edge-tts/synthesize`, { body: JSON.stringify({ ...body, voiceId }), headers: { "Content-Type": "application/json" }, method: "POST", signal: AbortSignal.timeout(180_000) });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aimakeall-mcp",
-  "version": "0.12.0",
+  "version": "0.13.0",
   "description": "AImakeAll MCP 서버 — Claude Code/Codex에서 자연어로 영상 기획·생성·렌더·퍼블리시 (렌더는 로컬 컴패니언)",
   "type": "module",
   "bin": {