@kaydash9999/banker-plugins 0.21.0 → 0.23.0

package/skills/3d-intro-build/references/video-pool.mjs

@@ -28,7 +28,9 @@
  *
  * Pool state lives in ~/.config/banker/3d-intro/video-pool-state.json (0600). It holds
  * FINGERPRINTS (sha256 of endpoint+key+model), never a key, so a rotated key or a changed model
- * starts with a clean record. State is advisory: a failed write is reported, never fatal.
+ * starts with a clean record. A Sora deployment that answered 410 (retired) is recorded under the
+ * fingerprint of its endpoint origin and deployment name, and Sora is skipped for 24 h.
+ * State is advisory: a failed write is reported, never fatal.
  * Concurrent processes share the file last-write-wins; the per-key in-flight limit is per process.
  *
  * Runtime: Node >=18 builtins only. globalThis.fetch and cp.spawnSync are read at call time so
@@ -40,7 +42,7 @@ import os from 'node:os';
 import crypto from 'node:crypto';
 import cp from 'node:child_process';
 import {
-  createVideo, pollVideo, downloadVideo, resolveFfmpeg, redact, fetchGuarded, safeForKey, keyHeldBack,
+  createVideo, pollVideo, downloadVideo, resolveFfmpeg, redact, fetchGuarded, safeForKey, keyHeldBack, probeSoraDeployment,
   API_TIMEOUT_MS, DOWNLOAD_TIMEOUT_MS, HELD_KEY, errnoOf, timeLeft,
 } from './azure-adapter.mjs';
 
@@ -213,13 +215,17 @@ function updateEntry(file, entry, fn, emit) {
   }
 }
 
-/** Clear recorded state for all entries, or only for the given labels (e.g. ['WAN_2']). */
+/**
+ * Clear recorded state for all entries, or only for the given labels (e.g. ['WAN_2']). 'AZURE_SORA'
+ * clears the Sora retirement record (every Sora deployment's, so creds are not needed for it).
+ */
 export function resetPoolState({ statePath = defaultStatePath(), creds, labels } = {}) {
   const state = loadPoolState(statePath);
   if (!labels) state.entries = {};
   else {
     const fps = new Set(loadWanPool(creds).filter((e) => labels.includes(e.label)).map((e) => e.fp));
-    for (const fp of Object.keys(state.entries)) if (fps.has(fp)) delete state.entries[fp];
+    const sora = labels.includes(SORA_LABEL);
+    for (const [fp, st] of Object.entries(state.entries)) if (fps.has(fp) || (sora && st?.label === SORA_LABEL)) delete state.entries[fp];
   }
   return savePoolState(state, statePath);
 }
@@ -235,14 +241,62 @@ function entryStatus(st, t) {
   return { status: 'ok' };
 }
 
-/** Per-entry availability for reporting. Never includes a key, nor a malformed endpoint or model. */
+/**
+ * Per-entry availability for reporting: one row per WAN entry (provider 'wan'), then one Sora row
+ * (label AZURE_SORA, provider 'sora', status ok | retired | unset | malformed). Never includes a key,
+ * nor a malformed endpoint or model.
+ */
 export function poolSummary({ creds = {}, statePath = defaultStatePath(), now = Date.now() } = {}) {
   const state = loadPoolState(statePath);
-  return loadWanPool(creds).map((e) => {
+  const wan = loadWanPool(creds).map((e) => {
     const st = state.entries[e.fp];
     const field = malformedField(e);
-    return { ...shownEntry(e), okCount: st?.okCount || 0, ...(field ? { status: 'malformed', reason: field } : entryStatus(st, now)) };
+    return { ...shownEntry(e), provider: 'wan', okCount: st?.okCount || 0, ...(field ? { status: 'malformed', reason: field } : entryStatus(st, now)) };
   });
+  return [...wan, soraSummary(creds, state, now)];
+}
+
+// The Sora row of poolSummary.
+function soraSummary(creds, state, t) {
+  const conn = soraConn(creds);
+  const base = { label: SORA_LABEL, provider: 'sora', model: isModelId(conn.model) ? conn.model : '(invalid model)' };
+  if (!conn.endpoint || !conn.key) return { ...base, host: null, status: 'unset' };
+  if (!originOf(conn.endpoint)) return { ...base, host: '(invalid endpoint)', status: 'malformed', reason: 'endpoint' };
+  const rec = retiredIn(state, conn, t);
+  const status = rec ? { status: 'retired', reason: rec.reason, retiredAt: rec.retiredAt, until: rec.retiredAt + SORA_RETIRED_TTL_MS } : { status: 'ok' };
+  return { ...base, host: hostOf(originOf(conn.endpoint)), ...status };
+}
+
+/**
+ * The CLIP_MODE a run starts with (FREE, nothing is sent): dive without exits on any provider (the user
+ * found it the most natural of the three on the sora-2 comparison page). Returns { mode, exit, provider,
+ * measured, reason }: provider is the first one generateClip would really use (VIDEO_PROVIDER_ORDER), and
+ * measured is false on WAN (dive on WAN is not measured; say so when the user picks). mode is null when
+ * no leg could be made: every WAN entry refused (generateClip stops there and does not use Sora), a Sora
+ * endpoint that is not https, or nothing set up (no WAN entry, Sora unset or recorded retired).
+ */
+export function defaultClipMode(creds = {}, { statePath = defaultStatePath(), now = Date.now() } = {}) {
+  for (const p of parseProviderOrder(creds.VIDEO_PROVIDER_ORDER)) {
+    const r = p === 'wan' ? wanMode(creds) : soraMode(creds, loadPoolState(statePath), now);
+    if (r) return r;
+  }
+  return { mode: null, provider: null, reason: 'no video provider: no WAN entry, and Sora is unset or recorded retired' };
+}
+
+function wanMode(creds) {
+  const pool = loadWanPool(creds);
+  if (!pool.length) return null;
+  if (pool.every((e) => entryRefusal(e))) return { mode: null, provider: 'wan', reason: 'every WAN entry is malformed or held back: generateClip stops there and does not use Sora' };
+  return { mode: 'dive', exit: false, provider: 'wan', measured: false, reason: 'the video runs on WAN: dive without exits (dive on WAN is not measured)' };
+}
+
+function soraMode(creds, state, t) {
+  const conn = soraConn(creds);
+  if (!conn.endpoint || !conn.key) return null;
+  const origin = originOf(conn.endpoint);
+  if (!origin || proxyHolds(origin)) return { mode: null, provider: 'sora', reason: 'AZURE_SORA_ENDPOINT is not an https URL (or the env proxy holds the key back): the leg stops before sending' };
+  if (retiredIn(state, conn, t)) return null;
+  return { mode: 'dive', exit: false, provider: 'sora', measured: true, reason: 'the video runs on Sora: dive without exits (measured on sora-2 2025-12-08)' };
 }
 
 // In-process in-flight counter per fingerprint (the documented limit is per key).
@@ -728,6 +782,60 @@ function soraConn(creds) {
   };
 }
 
+// ---------------------------------------------------------------------------
+// Sora retirement (HTTP 410). A 410 on the submit is the model's retirement at once. A 410 on a poll
+// or a download may also be a job that expired, so it counts only when the free deployment probe says
+// retired. The record keeps Sora from being sent the next legs for 24 h.
+// ---------------------------------------------------------------------------
+
+const SORA_LABEL = 'AZURE_SORA';
+const SORA_RETIRED_TTL_MS = 24 * 3_600_000;
+// The Sora record's name in the state file: endpoint origin and deployment, never the key.
+const soraFp = (conn) => `sora:${crypto.createHash('sha256').update(`${originOf(conn.endpoint)}\n${conn.model}`).digest('hex').slice(0, 16)}`;
+
+function retiredIn(state, conn, t) {
+  const st = state.entries[soraFp(conn)];
+  return st?.status === 'retired' && t - st.retiredAt < SORA_RETIRED_TTL_MS ? st : null;
+}
+
+function recordSoraRetired(ctx, conn, stage) {
+  const t = ctx.now();
+  updateEntry(ctx.statePath, { fp: soraFp(conn), label: SORA_LABEL }, (st) => ({ ...st, status: 'retired', retiredAt: t, reason: `HTTP 410 (${stage})` }), ctx.emit);
+  ctx.emit({ type: 'fail', provider: 'sora', label: SORA_LABEL, kind: 'retired', status: 410, stage });
+}
+
+const soraWhere = (conn) => `Sora deployment ${isModelId(conn.model) ? conn.model : '(invalid model)'} on ${hostOf(originOf(conn.endpoint))}`;
+const SORA_RETIRED_NEXT = "add a WAN key (3d-intro-setup), or deploy a newer Sora model and clear the record with resetPoolState({ labels: ['AZURE_SORA'] })";
+
+function soraRetiredStop(conn, stage, taskId) {
+  const job = taskId ? `job ${taskId} may have billed` : 'no job was made';
+  return stopError('retired', `${soraWhere(conn)} is retired (HTTP 410 on the ${stage}); ${job}; Sora is skipped for 24 h — ${SORA_RETIRED_NEXT}`, { provider: 'sora', label: SORA_LABEL, status: 410, ...(taskId ? { taskId } : {}) });
+}
+
+// Sora was skipped for its record, and no other provider took the leg.
+function soraSkippedStop(conn, rec) {
+  return stopError('retired', `${soraWhere(conn)} was recorded retired (${rec.reason}) at ${new Date(rec.retiredAt).toISOString()}, and no WAN key could take the leg; nothing was sent — ${SORA_RETIRED_NEXT}`, { provider: 'sora', label: SORA_LABEL, retiredAt: rec.retiredAt });
+}
+
+// One free probe per process and deployment.
+const soraProbes = new Map();
+function probeSoraOnce(conn, now) {
+  const fp = soraFp(conn);
+  if (!soraProbes.has(fp)) {
+    soraProbes.set(fp, probeSoraDeployment({ endpoint: conn.endpoint, key: conn.key, deployment: conn.model, now }).catch(() => ({ state: 'unknown', status: null })));
+  }
+  return soraProbes.get(fp);
+}
+
+// The retired stop for a 410 on a poll or a download when the probe confirms it, else null.
+async function confirmRetired(ctx, conn, stage, jobId) {
+  const p = await probeSoraOnce(conn, ctx.now);
+  ctx.emit({ type: 'probe', provider: 'sora', label: SORA_LABEL, stage, state: p.state, status: p.status ?? null });
+  if (p.state !== 'retired') return null;
+  recordSoraRetired(ctx, conn, stage);
+  return soraRetiredStop(conn, stage, jobId);
+}
+
 // Poll an accepted Sora job to a downloaded clip; same stop rules as finishWanTask.
 async function finishSoraJob(ctx, jobId, secs) {
   const conn = soraConn(ctx.creds);
@@ -737,13 +845,14 @@ async function finishSoraJob(ctx, jobId, secs) {
   if (!st || !SORA_DONE.has(st.status)) {
     throw stopError('timeout', `Sora job ${jobId} still ${st?.status ?? 'unknown'} after polling for ${ctx.now() - t0} ms; resume with resumeClip`, { provider: 'sora', taskId: jobId, label: 'AZURE_SORA', seconds: secs });
   }
-  const mp4 = await downloadSoraClip(conn, jobId, secs);
+  const mp4 = await downloadSoraClip(ctx, conn, jobId, secs);
   ctx.emit({ type: 'done', provider: 'sora', label: 'AZURE_SORA', taskId: jobId });
   return { mp4, provider: 'sora', label: 'AZURE_SORA', model: conn.model, seconds: secs, taskId: jobId, usage: null };
 }
 
 // pollVideo throws on a 4xx other than 408/429 (the job is gone, or the key is refused): such a job
-// never turns terminal, so the leg ends at once as task_lost instead of polling to the deadline.
+// never turns terminal, so the leg ends at once as task_lost instead of polling to the deadline. A 410
+// the deployment probe calls retired ends it as retired.
 async function pollSoraJob(ctx, conn, jobId) {
   const interval = Math.max(0, ctx.pollIntervalMs);
   try {
@@ -754,6 +863,8 @@ async function pollSoraJob(ctx, conn, jobId) {
     });
   } catch (e) {
     if (!e.status) throw e;
+    const retired = e.status === 410 && await confirmRetired(ctx, conn, 'poll', jobId);
+    if (retired) throw retired;
     throw stopError('task_lost', `Sora poll for job ${jobId} failed: HTTP ${e.status}${e.code ? ` ${e.code}` : ''}; check the job in Azure before resubmitting`, { provider: 'sora', taskId: jobId, label: 'AZURE_SORA', status: e.status, code: e.code });
   }
 }
@@ -764,10 +875,12 @@ function soraFailure(st, jobId) {
   return stopError('failed', `Sora job ${jobId} ended ${st.status}: ${JSON.stringify(st.error || '')}`, { provider: 'sora', taskId: jobId, code });
 }
 
-async function downloadSoraClip(conn, jobId, secs) {
+async function downloadSoraClip(ctx, conn, jobId, secs) {
   try {
     return await downloadVideo({ endpoint: conn.endpoint, key: conn.key, id: jobId, apiVersion: conn.apiVersion });
   } catch (err) {
+    const retired = err.status === 410 && await confirmRetired(ctx, conn, 'download', jobId);
+    if (retired) throw retired;
     throw stopError('download', `${err.message} for Sora job ${jobId}; resume with resumeClip`, { provider: 'sora', taskId: jobId, label: 'AZURE_SORA', seconds: secs });
   }
 }
@@ -784,7 +897,8 @@ const SORA_SUBMIT_TRIES = 5;
 
 // A 429 is a refusal, so retrying it cannot double-bill; a lost connection or a bare 5xx can. Each
 // wait is the server's Retry-After, else 30 s doubling, from 1 s to 10 min. A Retry-After longer
-// than maxRateWaitMs is not waited out: the leg stops as `rate` at once, as WAN's waits do.
+// than maxRateWaitMs is not waited out: the leg stops as `rate` at once, as WAN's waits do. A 410 is
+// the deployment's retirement: recorded, and the leg stops as `retired`.
 async function submitSora(ctx, conn, secs) {
   for (let i = 0; ; i++) {
     try {
@@ -793,6 +907,7 @@ async function submitSora(ctx, conn, secs) {
         endpoint: conn.endpoint, key: conn.key, model: conn.model, prompt: ctx.prompt, size: ctx.size, seconds: secs, inputReferencePng: ctx.firstFramePng, apiVersion: conn.apiVersion,
       });
     } catch (e) {
+      if (e.status === 410) { recordSoraRetired(ctx, conn, 'submit'); throw soraRetiredStop(conn, 'submit'); }
       if (e.status !== 429 || i >= SORA_SUBMIT_TRIES - 1) throw soraSubmitError(e);
       const want = e.retryAfterMs ?? RATE_BASE_MS * 2 ** i;
       if (want > ctx.maxRateWaitMs) throw soraRateStop(want, ctx.maxRateWaitMs, e.retryAfterMs != null);
@@ -815,6 +930,10 @@ function soraSubmitError(e) {
   if (e.status === 429) {
     return stopError('rate', `Sora still answered HTTP 429 after ${SORA_SUBMIT_TRIES} tries; no job was made — wait, then generate the leg again`, { provider: 'sora', status: 429 });
   }
+  if (e.status === 404) {
+    // only the status and the code field are read: a message is no contract
+    return stopError('invalid_request', `${e.message}; the deployment name may be wrong, or the deployment was removed after its model retired — check AZURE_SORA_DEPLOYMENT (3d-intro-setup §4 checks it for free)`, { provider: 'sora', status: 404, code: e.code || null });
+  }
   if (soraMayHaveJob(e)) {
     const answer = e.status === 0 ? e.errno || 'network' : `HTTP ${e.status}`;
     return stopError('submit_unknown', `Sora submit got no usable answer (${answer}); the job may exist — check Azure before resubmitting`, { provider: 'sora', status: e.status });
@@ -851,6 +970,10 @@ const DEFAULTS = { size: '720x1280', seconds: 5, pollIntervalMs: 15_000, pollTim
  *   kind 'unreachable'                  Sora host refused the connection (nothing was sent)
  *   kind 'rate'                         Sora kept answering 429, or asked (Retry-After, err.retryAfterMs) for a
  *                                       wait past maxRateWaitMs (no job was made); wait, then call again
+ *   kind 'retired'                      the Sora deployment answered 410 (on the submit, or on a poll or a
+ *                                       download the free deployment probe confirmed), or was recorded so in
+ *                                       the last 24 h and no WAN key could take the leg; add a WAN key, or
+ *                                       deploy a newer model and resetPoolState({ labels: ['AZURE_SORA'] })
  * @returns {Promise<{mp4:Buffer, provider:'wan'|'sora', label:string, model:string, seconds:number, taskId:string, usage:object|null}>}
  */
 export async function generateClip(opts = {}) {
@@ -867,17 +990,24 @@ export async function generateClip(opts = {}) {
     const clip = await tryProvider(ctx, p, tried);
     if (clip) return clip;
   }
+  if (ctx.soraRetired) throw soraSkippedStop(soraConn(o.creds), ctx.soraRetired);
   throw new Error(`generateClip: no video provider available (tried: ${tried.join(', ') || 'none'})`);
 }
 
 // One provider's go at the leg: the clip, or null to go on to the next. Sora, once it runs, ends the
-// leg (with a clip or a throw).
+// leg (with a clip or a throw). A Sora deployment recorded retired is skipped before anything is sent.
 async function tryProvider(ctx, p, tried) {
   if (p === 'wan') {
     tried.push('wan');
     return runWan(ctx);
   }
   if (p !== 'sora' || !soraReady(ctx)) return null;
+  const rec = retiredIn(loadPoolState(ctx.statePath), soraConn(ctx.creds), ctx.now());
+  if (rec) {
+    ctx.emit({ type: 'skip', provider: 'sora', label: SORA_LABEL, reason: 'retired', retiredAt: rec.retiredAt });
+    ctx.soraRetired = rec;
+    return null;
+  }
   tried.push('sora');
   ctx.emit({ type: 'fallback', provider: 'sora', from: tried.slice(0, -1) });
   return runSora(ctx);

package/skills/3d-intro-setup/SKILL.md

@@ -69,7 +69,7 @@ curl --ssl-no-revoke -sSI -o /dev/null --connect-timeout 5 --max-time 10 https:/
 OS별 상세 설치 절차(Ubuntu NodeSource·RHEL8/Rocky8 dnf 모듈·Windows winget·PATH 충돌 등)는 반복하지 않고 **`setup-node` 스킬로 위임**한다 — 이 스킬은 결과(`node -v` ≥18)만 확인한다.
 
 ## 2. ffmpeg 확보
-어댑터의 프레임 추출·컬러 매치·크로스페이드·이어붙이기(`extractLastFrame`·`colorMatch`·`crossfade`·`concatClips`, forward-chaining 이음새 처리)가 `ffmpeg` 바이너리를 요구한다.
+어댑터의 프레임 추출·크로스페이드·이어붙이기(`extractLastFrame`·`crossfade`·`concatClips`, forward-chaining 이음새 처리)와 build 의 클립 후처리(`clip-post.mjs` 의 `reverseClip`·`landOnStill`·`cameraMotion`)가 `ffmpeg` 바이너리를 요구한다.
 설치 절차는 `motion-graphic-setup` §2 와 같으므로 반복하지 않고 요약만 남긴다(전체 함정은 그 스킬 참조. 마지막 폴백의 설치 위치만 다르다):
 - macOS: `brew install ffmpeg`
 - Ubuntu/Debian: `sudo apt-get install -y ffmpeg`
@@ -110,7 +110,10 @@ node -e "
   const c = resolveCreds({ projectDir: process.cwd() });
   const need = ['AZURE_SORA_ENDPOINT','AZURE_SORA_API_KEY','AZURE_IMAGE_OPENAI_ENDPOINT','AZURE_IMAGE_API_KEY','AZURE_GPT_IMAGE_DEPLOYMENT'];
   const missing = need.filter(k => !c[k]);
-  if (c._tracked) console.log('주의: 이 프로젝트 키 파일은 git 이 추적한다(' + c._source + '). 키를 적으면 커밋에 실린다. git rm --cached 로 추적을 풀거나 홈 키 파일을 쓴다');
+  if (c._tracked) {   // 값을 하나도 내주지 않으므로 '누락' 보다 먼저 알리고 멈춘다
+    console.log('주의: 이 프로젝트 키 파일은 git 이 추적한다(' + c._source + '). 저장소와 함께 온 값일 수 있어 읽지 않았다(적힌 이름: ' + c._names.join(',') + '). 키를 적으면 커밋에도 실린다. git rm --cached 로 추적을 풀거나 홈 키 파일을 쓴다');
+    process.exit(1);
+  }
   if (c._source && missing.length === 0) {
     console.log('기존 크레덴셜 발견:', c._source, '| Sora key', redact(c.AZURE_SORA_API_KEY), '| Image key', redact(c.AZURE_IMAGE_API_KEY));
     process.exit(0);
@@ -243,11 +246,11 @@ FLUX 는 이 스킬의 §4 프리플라이트 대상이 아니다(무과금으
 
 ## 4. 프리플라이트 (무과금)
 **여기서는 어떤 유료 생성도 실행하지 않는다** — 이미지 생성, Sora-2·WAN 영상 생성 어느 쪽도 호출하지 않는다.
-아래 세 가지만 수행한다: (1) Sora `listVideos` GET(목록 조회는 무료) (2) Image 는 `azFetch` 로 **body `{model:<배포명>}` (프롬프트 누락) POST** — 배포로 라우팅된 뒤 프롬프트 누락으로 생성 전 `400 missing_required_parameter` 로 거부되므로 과금 0이고, 엔드포인트·인증에 더해 **배포명까지** 무료로 검증된다. (빈 `{}` 는 model 이 없어 `404 DeploymentNotFound` 로 갈려 배포명을 확인하지 못한다.) (3) WAN 은 키마다 존재하지 않는 task 를 GET(`probeWanPool`) — 맞는 키는 200(`task_status: UNKNOWN`), 틀린 키는 `401 InvalidApiKey` 다(2026-10-09 실측).
+아래 네 가지만 수행한다: (1) Sora `listVideos` GET(목록 조회는 무료) (2) Image 는 `azFetch` 로 **body `{model:<배포명>}` (프롬프트 누락) POST** — 배포로 라우팅된 뒤 프롬프트 누락으로 생성 전 `400 missing_required_parameter` 로 거부되므로 과금 0이고, 엔드포인트·인증에 더해 **배포명까지** 무료로 검증된다. (빈 `{}` 는 model 이 없어 `404 DeploymentNotFound` 로 갈려 배포명을 확인하지 못한다.) (3) WAN 은 키마다 존재하지 않는 task 를 GET(`probeWanPool`) — 맞는 키는 200(`task_status: UNKNOWN`), 틀린 키는 `401 InvalidApiKey` 다(2026-10-09 실측). (4) Sora 배포는 `probeSoraDeployment` 의 GET 두 번 — `GET /openai/deployments/<배포명>?api-version=2022-12-01`(있으면 200 과 `status`, 없으면 404 `notFound`)과 `GET /openai/v1/models?api-version=preview` 의 그 모델 항목(`lifecycle_status`, `deprecation.inference` 퇴역일). Sora 는 이미지와 달리 프롬프트 없는 POST 로 배포를 가르지 못한다. `/openai/v1/videos` 는 모든 인자를 배포 확인보다 먼저 검사해, 없는 배포명에도 같은 400 을 준다(2026-10-29 실측). 인자 검사를 통과하는 POST 는 실제 생성(과금)이다.
 ```bash
 node -e "
 (async () => {
-  const { resolveCreds, listVideos, azFetch, redact } = await import('$ADAPTER');
+  const { resolveCreds, listVideos, azFetch, redact, probeSoraDeployment } = await import('$ADAPTER');
   const c = resolveCreds({ projectDir: process.cwd() });
   if (!c._source) { console.log('크레덴셜 없음 -- §3 먼저 실행'); process.exit(2); }
   const how = (r) => (r.error ? r.errno || r.error.name : r.authStyle);   // status 0 이면 이유(ENOTFOUND, TimeoutError 등)
@@ -261,7 +264,13 @@ node -e "
   const wan = await probeWanPool({ creds: c });
   for (const w of wan) console.log('wan.probe', w.label, w.host, w.model, '->', w.status, w.code || '', '| key', w.key);
   if (!wan.length) console.log('wan.probe -> WAN 항목 없음 (영상은 Sora 만 사용)');
-  const pass = sora.status === 200 && img.status === 400 && wan.every((w) => w.authOk);
+  const dep = await probeSoraDeployment({ endpoint: c.AZURE_SORA_ENDPOINT, key: c.AZURE_SORA_API_KEY, deployment: c.AZURE_SORA_DEPLOYMENT || 'sora-2' });
+  const until = dep.retiresAt ? new Date(dep.retiresAt).toISOString().slice(0, 10) : '-';
+  console.log('sora.deploy ->', dep.status, dep.state, '| model', dep.modelVersion || dep.model || '-', dep.versionInferred ? '(판 추정)' : '', '| 퇴역', until);
+  if (dep.state === 'retired') console.log('경고: Sora 퇴역 -- 영상은 WAN 키로만 만든다(§3 WAN 영상 풀)');
+  if (dep.soon) console.log('안내: Sora 모델이 ' + until + ' 에 퇴역 예정(' + dep.daysLeft + '일 남음) -- 그 뒤에는 WAN 키나 새 Sora 배포가 필요');
+  const soraOk = dep.state === 'deployed' || (dep.state === 'retired' && wan.length > 0);
+  const pass = sora.status === 200 && soraOk && img.status === 400 && wan.every((w) => w.authOk);
   console.log(pass ? 'PREFLIGHT PASS -- \$0 과금' : 'PREFLIGHT FAIL');
   console.log('source:', c._source, '| Sora key', redact(c.AZURE_SORA_API_KEY), '| Image key', redact(c.AZURE_IMAGE_API_KEY));
   process.exit(pass ? 0 : 1);
@@ -272,6 +281,10 @@ node -e "
 | 체크 | 기대 | 의미 |
 |---|---|---|
 | `sora.listVideos` | HTTP 200 | Sora 엔드포인트 살아있음 + 키 인증됨 |
+| `sora.deploy` | HTTP 200, `deployed` | 그 배포명이 이 리소스에 있음(GET 이라 과금 0). 모델 판과 퇴역일을 함께 보인다. 배포가 모델 이름만 알려 주면 가장 새 판을 쓴다고 보고 `(판 추정)` 을 붙인다 |
+| `sora.deploy` 가 404 `no_deployment` | - | 배포명이 틀렸거나, 모델 퇴역 뒤 배포가 지워짐 — Azure 포털의 배포 목록과 `AZURE_SORA_DEPLOYMENT` 를 대조 |
+| `sora.deploy` 가 `retired` | - | 배포가 410 으로 답했거나 퇴역일이 지남. WAN 항목이 있으면 경고만 하고 통과(영상은 WAN 으로), 없으면 FAIL. 새 Sora 배포를 만들거나 WAN 키를 넣는다 |
+| `안내: ... 퇴역 예정` | - | 퇴역일이 14일 안. 그 날짜 뒤에는 Sora 가 410 을 준다(Foundry 모델 수명 문서: 서비스에서 빠진 모델은 410 Gone). 날짜는 리소스마다 다르니 프로브가 준 값만 쓴다 |
 | `images.badreq` | HTTP 400 (`missing_required_parameter`) | Image 엔드포인트 살아있음 + 키 인증됨 + **배포명 라우팅됨**(프롬프트 누락이라 생성 전 거부) |
 | `wan.probe` (항목마다) | HTTP 200 | WAN workspace 엔드포인트 + 키 인증됨. 남은 할당량은 이 방법으로 알 수 없다 |
 | `wan.probe` 가 401 `InvalidApiKey` | - | 키가 틀렸거나 엔드포인트와 리전이 다름 — 그 `WAN_<n>` 을 재입력 |
@@ -287,9 +300,9 @@ node -e "
 ```bash
 node -v                      # 18 이상 기대
 command -v ffmpeg >/dev/null && ffmpeg -version | head -1 || echo "시스템 ffmpeg 없음 -- resolveFfmpeg() 폴백 확인(§2)"
-# 위 §4 프리플라이트를 재실행해 PASS 문자열 + 두 status 코드를 그대로 증거로 남긴다
+# 위 §4 프리플라이트를 재실행해 출력한 확인 줄 전부(listVideos, sora.deploy, images.badreq, wan)를 그대로 증거로 남긴다
 ```
-4-field 보고: 변경(Node/ffmpeg 확보 방식 · 크레덴셜 저장 경로 — 파일 내용 아님) / Evidence(§0 감지 출력 · §4 status 코드 전부) / 검증(`listVideos`=200 **AND** `images.badreq`=400 **AND** WAN 항목 전부 200 이어야 PASS) / Unknown(FLUX 미검증 · WAN 키별 남은 할당량(조회 API 없음 — 소진은 첫 생성에서 드러나고 풀이 자동으로 다음 키·Sora 로 넘어감) · 배포명이 실제 존재하는지는 이 무과금 프리플라이트로 확인 불가하며 첫 실제 생성 시점에만 드러남 · 관리자 권한 제약으로 ffmpeg 시스템 설치 불가 등, 가짜 성공 금지).
+4-field 보고: 변경(Node/ffmpeg 확보 방식 · 크레덴셜 저장 경로 — 파일 내용 아님) / Evidence(§0 감지 출력 · §4 status 코드 전부) / 검증(`listVideos`=200 **AND** `sora.deploy`=`deployed`(WAN 이 있으면 `retired` 도 경고와 함께 허용) **AND** `images.badreq`=400 **AND** WAN 항목 전부 200 이어야 PASS) / Unknown(FLUX 미검증 · WAN 키별 남은 할당량(조회 API 없음 — 소진은 첫 생성에서 드러나고 풀이 자동으로 다음 키·Sora 로 넘어감) · Sora 배포가 실제로 생성하는지(배포 GET 은 있음과 퇴역일까지만 알려 줌)는 첫 실제 생성 시점에만 드러남 · 관리자 권한 제약으로 ffmpeg 시스템 설치 불가 등, 가짜 성공 금지).
 크레덴셜은 어떤 필드도 원문으로 보고하지 않고 항상 `redact()` 출력(길이만)만 남긴다.
 
 ## 함정

package/skills/3d-intro-setup/references/azure-adapter.mjs

@@ -173,6 +173,9 @@ const MACHINE_ONLY = ['FFMPEG_PATH'];
  * Load creds from `.env.3d-intro.local` in projectDir, else `~/.config/banker/3d-intro/env`.
  * Returns the parsed KEY=VALUE map plus `_source` (the file used, or null if none found). From a
  * project file, FFMPEG_PATH is left out and returned under `_ignored` so the caller can say why.
+ * A project file git tracks gives no value at all: only `_source`, `_tracked: true` and `_names`
+ * (the names it sets). It may have come with the repository, so its endpoint would receive the
+ * prompts, the frames and the key; the calls refuse creds without an endpoint and a key.
  */
 export function resolveCreds({ projectDir } = {}) {
   const home = homeCredsPath();
@@ -183,7 +186,14 @@ export function resolveCreds({ projectDir } = {}) {
   if (!p) return { _source: null };
   const creds = { ...parseEnvFile(fs.readFileSync(p, 'utf8')), _source: p };
   if (p === home) return creds;
-  return trackedByGit(p) ? { ...withoutMachineOnly(creds), _tracked: true } : withoutMachineOnly(creds);
+  if (trackedByGit(p)) return { _source: p, _tracked: true, _names: Object.keys(creds).filter((k) => k !== '_source') };
+  return withoutMachineOnly(creds);
+}
+
+// The paid and listing calls need both; resolveCreds gives neither from a project key file git tracks.
+function requireConn(fn, endpoint, key) {
+  if (endpoint && key) return;
+  throw new Error(`${fn}: endpoint and key are required; nothing was sent (resolveCreds gives no value from a project key file git tracks: untrack it with git rm --cached, or use the home key file)`);
 }
 
 function withoutMachineOnly(creds) {
@@ -615,6 +625,7 @@ export async function generateImage({
   endpoint, key, deployment, apiVersion = 'preview',
   prompt, size = '720x1280', quality = 'low', n = 1, onNote, retry429 = 3,
 } = {}) {
+  requireConn('generateImage', endpoint, key);
   const genBody = { model: deployment, prompt, size, quality, n };
   const post = (url, body) => postJsonWith429Retry(url, { key, body: JSON.stringify(body), retries: retry429, onNote });
   let r = await post(`${endpoint}/openai/v1/images/generations?api-version=${apiVersion}`, genBody);
@@ -641,6 +652,7 @@ function pngFrom(r, b64, failed) {
 export async function editImage({
   endpoint, key, deployment, apiVersion = 'preview', prompt, imageBuf, maskBuf, size,
 } = {}) {
+  requireConn('editImage', endpoint, key);
   const r = await azFetch(`${endpoint}/openai/v1/images/edits?api-version=${apiVersion}`, {
     key, method: 'POST', body: editForm({ deployment, prompt, imageBuf, maskBuf, size }), timeoutMs: IMAGE_TIMEOUT_MS,
   });
@@ -659,6 +671,7 @@ function editForm({ deployment, prompt, imageBuf, maskBuf, size }) {
 
 /** Generate a still via the Black Forest Labs FLUX provider path. Returns a PNG Buffer. */
 export async function generateImageFlux({ endpoint, key, prompt, width, height, apiVersion = 'preview' } = {}) {
+  requireConn('generateImageFlux', endpoint, key);
   const r = await azFetch(`${endpoint}/providers/blackforestlabs/v1/flux-2-pro?api-version=${apiVersion}`, {
     key, method: 'POST', headers: { 'Content-Type': 'application/json' },
     body: JSON.stringify({ prompt, width, height }), timeoutMs: IMAGE_TIMEOUT_MS,
@@ -684,6 +697,7 @@ export async function listVideos({ endpoint, key, apiVersion = 'preview' } = {})
 export async function createVideo({
   endpoint, key, model = 'sora-2', prompt, size = '720x1280', seconds = 4, inputReferencePng, apiVersion = 'preview',
 } = {}) {
+  requireConn('createVideo', endpoint, key);
   const body = videoForm({ model, prompt, size, seconds, inputReferencePng });
   const r = await azFetch(`${endpoint}/openai/v1/videos?api-version=${apiVersion}`, { key, method: 'POST', body });
   if (!(r.ok && r.body?.id)) throw createVideoError(r);
@@ -704,11 +718,14 @@ function videoForm({ model, prompt, size, seconds, inputReferencePng }) {
 
 // status 0 = network error; errno tells a refused connection (nothing sent) from a lost one.
 // retryAfterMs is the server's wait for a 429.
+// code is the answer's error.code (DeploymentNotFound and the like), for a 404 or 410 the caller reads.
 function createVideoError(r) {
   const err = new Error(`createVideo failed: HTTP ${r.status}${why(r)} ${truncate(r.body)}`);
-  return Object.assign(err, { status: r.status, errno: r.errno || null, retryAfterMs: r.retryAfterMs ?? null });
+  return Object.assign(err, { status: r.status, errno: r.errno || null, retryAfterMs: r.retryAfterMs ?? null, code: errorCodeOf(r) });
 }
 
+const errorCodeOf = (r) => (typeof r.body?.error?.code === 'string' ? r.body.error.code : null);
+
 const POLL_DEFAULTS = { apiVersion: 'preview', intervalMs: 5000, maxTicks: 180, now: Date.now };
 const POLL_RETRY_4XX = new Set([408, 429]);
 const withoutUndefined = (obj) => Object.fromEntries(Object.entries(obj).filter(([, v]) => v !== undefined));
@@ -758,15 +775,87 @@ function throwIfRefused(r, id) {
   throw Object.assign(new Error(`pollVideo: job ${id} answered HTTP ${r.status}${code ? ` ${code}` : ''}`), { status: r.status, code });
 }
 
-/** Download finished video bytes. Returns an mp4 Buffer; throws on non-200 / empty body. */
+/** Download finished video bytes. Returns an mp4 Buffer; throws on non-200 / empty body, with err.status. */
 export async function downloadVideo({ endpoint, key, id, apiVersion = 'preview' } = {}) {
   const r = await azFetch(`${endpoint}/openai/v1/videos/${id}/content?api-version=${apiVersion}`, {
     key, method: 'GET', binary: true,
   });
-  if (!(r.status === 200 && r.body?.length)) throw new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`);
+  if (!(r.status === 200 && r.body?.length)) throw Object.assign(new Error(`downloadVideo failed: HTTP ${r.status}${why(r)}`), { status: r.status });
   return r.body;
 }
 
+// ---------------------------------------------------------------------------
+// Sora deployment probe (FREE: two GETs, nothing is generated)
+// ---------------------------------------------------------------------------
+
+const DEPLOYMENT_API_VERSION = '2022-12-01';
+/** A retirement date this many days away or nearer is reported (`soon`). */
+export const RETIRE_SOON_DAYS = 14;
+const DAY_MS = 86_400_000;
+const RETIRED_LIFECYCLE = new Set(['retired', 'removed']);
+
+/**
+ * FREE check of a Sora deployment that makes no job. POST /openai/v1/videos checks every parameter
+ * before it looks the deployment up (a deployment that does not exist answers the same 400 as one
+ * that does, measured 2026-10-29), and a POST that passes the checks is a paid generation. So the
+ * check is two GETs:
+ *   GET /openai/deployments/<name>?api-version=2022-12-01   200 {model, status}, or 404 when there is none
+ *   GET /openai/v1/models?api-version=preview                 the model's lifecycle_status and deprecation.inference
+ * state: deployed | no_deployment | retired | auth | unreachable | unknown | unset (no endpoint or key: nothing sent). `retired` means the
+ * deployment answered 410, the model list calls the model retired, or its inference retirement date
+ * has passed. `retiresAt` (ms) and `daysLeft` come from the model list; when the deployment names the
+ * model without its version, the newest dated version is taken (`versionInferred`). `soon` is true
+ * within RETIRE_SOON_DAYS. The result holds no key and no URL.
+ */
+export async function probeSoraDeployment({ endpoint, key, deployment = 'sora-2', now = Date.now } = {}) {
+  // no endpoint or key (unset, or creds from a key file git tracks, which give no values): nothing is sent
+  if (!endpoint || !key) return { deployment, status: null, code: null, errno: null, state: 'unset' };
+  const d = await azFetch(`${endpoint}/openai/deployments/${encodeURIComponent(deployment)}?api-version=${DEPLOYMENT_API_VERSION}`, { key, method: 'GET' });
+  const base = { deployment, status: d.status, code: errorCodeOf(d), errno: d.errno || null };
+  if (d.status !== 200) return { ...base, state: deploymentState(d.status) };
+  const { model, deploymentStatus } = deploymentOf(d.body);
+  const life = model ? await modelLifecycle(endpoint, key, model) : {};
+  return withSchedule({ ...base, deploymentStatus, model, ...life }, now());
+}
+
+const deploymentOf = (b) => ({ model: typeof b?.model === 'string' ? b.model : null, deploymentStatus: b?.status ?? null });
+
+const DEPLOYMENT_STATE = new Map([[404, 'no_deployment'], [410, 'retired'], [401, 'auth'], [403, 'auth'], [0, 'unreachable']]);
+const deploymentState = (status) => DEPLOYMENT_STATE.get(status) || 'unknown';
+
+// The model's entry in the resource's model list: its lifecycle and inference retirement date.
+async function modelLifecycle(endpoint, key, model) {
+  const r = await azFetch(`${endpoint}/openai/v1/models?api-version=preview`, { key, method: 'GET' });
+  const m = r.ok ? modelEntry(r.body?.data, model) : null;
+  if (!m) return { modelVersion: null, lifecycle: null, retiresAt: null };
+  return { modelVersion: m.entry.id, versionInferred: m.inferred, lifecycle: m.entry.lifecycle_status ?? null, retiresAt: msOf(m.entry.deprecation?.inference) };
+}
+
+// The entry named exactly `model`, else the newest `<model>-YYYY-MM-DD` one (a deployment names only the model).
+function modelEntry(list, model) {
+  if (!Array.isArray(list)) return null;
+  const exact = list.find((x) => x?.id === model);
+  if (exact) return { entry: exact, inferred: false };
+  const dated = (id) => typeof id === 'string' && id.startsWith(`${model}-`) && /^\d{4}-\d{2}-\d{2}$/.test(id.slice(model.length + 1));
+  const versions = list.filter((x) => dated(x?.id)).sort((a, b) => b.id.localeCompare(a.id));
+  return versions.length ? { entry: versions[0], inferred: true } : null;
+}
+
+// deprecation.inference is unix seconds; an ISO date is read too.
+function msOf(v) {
+  if (typeof v === 'number' && Number.isFinite(v)) return v * 1000;
+  const t = typeof v === 'string' ? Date.parse(v) : NaN;
+  return Number.isFinite(t) ? t : null;
+}
+
+function withSchedule(r, t) {
+  const daysLeft = r.retiresAt == null ? null : Math.ceil((r.retiresAt - t) / DAY_MS);
+  const gone = (r.retiresAt != null && r.retiresAt <= t) || RETIRED_LIFECYCLE.has(r.lifecycle);
+  const ready = !r.deploymentStatus || r.deploymentStatus === 'succeeded';
+  const state = gone ? 'retired' : ready ? 'deployed' : 'unknown';
+  return { ...r, state, daysLeft, soon: !gone && daysLeft != null && daysLeft <= RETIRE_SOON_DAYS };
+}
+
 /**
  * Probe whether the legacy two-image jobs API is available. Never throws.
  * @returns {Promise<boolean>} true when the legacy jobs endpoint exists and is authorized.
@@ -792,6 +881,7 @@ export async function detectTwoImageSupport({ endpoint, key, apiVersion = 'previ
 export async function createVideoTwoImage({
   endpoint, key, model = 'sora-2', prompt = '', firstPng, lastPng, size = '720x1280', seconds = 4, apiVersion = 'preview',
 } = {}) {
+  requireConn('createVideoTwoImage', endpoint, key);
   const r = await azFetch(`${endpoint}/openai/v1/video/generations/jobs?api-version=${apiVersion}`, {
     key, method: 'POST', body: twoImageForm({ model, prompt, firstPng, lastPng, size, seconds }),
   });
@@ -900,21 +990,6 @@ export async function extractFirstFrame(mp4, out, { ffmpeg } = {}) {
   return out;
 }
 
-/**
- * Tone/color continuity pass on srcPng. Stock ffmpeg has no true "match A's histogram to B"
- * filter, so this uses histeq — per-channel histogram equalization — the simplest robust
- * histogram normalization, which keeps a chained clip's first frame from drifting in
- * contrast/tone. refPng is accepted for API symmetry and a future CLUT-based exact match; it
- * is not fed to ffmpeg today (an unmapped extra input would make ffmpeg error). Returns out.
- */
-export async function colorMatch(srcPng, refPng, out, { ffmpeg } = {}) {
-  const bin = ffmpeg || await resolveFfmpeg();
-  void refPng; // reserved (see doc comment)
-  const r = runFf(bin, ['-y', '-i', srcPng, '-vf', 'format=rgb24,histeq', '-frames:v', '1', out]);
-  if (r.code !== 0 && !fs.existsSync(out)) throw new Error(`colorMatch failed: ${tail(r.stderr)}`);
-  return out;
-}
-
 /**
  * Crossfade clip A into clip B with an `xfade` transition of `sec` seconds. `offset` (opts) is
  * where the fade starts in A; when omitted it is derived from A's probed duration (dur - sec).
@@ -988,15 +1063,26 @@ const IMAGE_USD_EACH = 0.02;
  * Rough budget for an intro of `nScenes` scenes. Video billed at $0.10/sec/clip (the Sora rate:
  * WAN rates cannot be read through an API); one image gen per scene (two per scene in two-image
  * mode). mode 'chain' (default) makes one clip of `seconds` per scene; 'holdFlight' makes one
- * flight of `flightSeconds` between each pair of scenes, the holds being encoded stills (free).
+ * flight of `flightSeconds` between each pair of scenes, the holds being encoded stills (free);
+ * 'dive' makes one clip of `diveSeconds` per scene (the dives and the finale) and, with `exit`, one
+ * exit of `exitSeconds` between each pair of scenes (6 scenes: $4.8 without, the default, $6.8 with `exit: true`).
  * Returns per-category USD sub-costs and the total.
  * @returns {{images:number, videos:number, usd:number}}
  */
-export function estimateCost({ nScenes, seconds = 4, twoImage = false, mode = 'chain', flightSeconds = 5 } = {}) {
-  const n = Number(nScenes) || 0;
-  const imageCount = twoImage ? n * 2 : n;
+const COST_DEFAULTS = { seconds: 4, twoImage: false, mode: 'chain', flightSeconds: 5, diveSeconds: 8, exitSeconds: 4, exit: false };
+// The clip seconds an intro bills, by mode.
+const CLIP_SECONDS = {
+  chain: (n, o) => n * o.seconds,
+  holdFlight: (n, o) => Math.max(0, n - 1) * o.flightSeconds,
+  dive: (n, o) => n * o.diveSeconds + (o.exit ? Math.max(0, n - 1) * o.exitSeconds : 0),
+};
+
+export function estimateCost(opts = {}) {
+  const o = { ...COST_DEFAULTS, ...Object.fromEntries(Object.entries(opts).filter(([, v]) => v !== undefined)) };
+  const n = Number(o.nScenes) || 0;
+  const imageCount = o.twoImage ? n * 2 : n;
   const images = round2(imageCount * IMAGE_USD_EACH);
-  const clipSeconds = mode === 'holdFlight' ? Math.max(0, n - 1) * flightSeconds : n * seconds;
+  const clipSeconds = (CLIP_SECONDS[o.mode] || CLIP_SECONDS.chain)(n, o);
   const videos = round2(clipSeconds * VIDEO_USD_PER_SEC);
   const usd = round2(images + videos);
   return { images, videos, usd };