perso-dubbing 0.3.0 → 0.5.0

package/skills/dubbing/scripts/dubbing.mjs

@@ -13,11 +13,13 @@ import { resolveKey, onboardingHelp, preloadKeyEnv } from './resolve_key.mjs';
 import { expandInputs, prepareInput } from '../lib/input.mjs';
 import { dubbingSpaces, getPlanStatus } from '../lib/space.mjs';
 import { getLanguages } from '../lib/languages.mjs';
-import { resolveChunks, recutChunk } from '../lib/split.mjs';
+import { resolveChunks, recutChunk, SplitConfirmNeeded } from '../lib/split.mjs';
 import { runSchedule } from '../lib/scheduler.mjs';
 import { download, getStatus, upload, requestAudioSeparation, downloadSeparation } from '../lib/api_adapter.mjs';
 import { mergeGroups } from '../lib/merge.mjs';
 import { messages, withUtm, SUBSCRIPTION_URL } from '../lib/messages.mjs';
+import { checkForUpdate } from '../lib/update_check.mjs';
+import { track, initTelemetry } from '../lib/telemetry.mjs';
 import { cleanupTempDirs, makeTempDir } from '../lib/tmp.mjs';
 import { probe } from '../lib/ffmpeg.mjs';
 import { AUDIO_EXT, CREDIT_RATE_DUB, CREDIT_RATE_LIPSYNC, UHD_CREDIT_MULT, UHD_BILLED_TIERS, POLL_INTERVAL_MS, MAX_IDLE_MS } from '../lib/config.mjs';
@@ -38,17 +40,51 @@ function friendlyError(e) {
   return e?.message ?? 'Unknown error';
 }
 
+// Coarse error bucket for telemetry — never the raw message/code.
+function errorClass(e) {
+  if (e?.name === 'MissingKeyError' || isAuthError(e)) return 'auth';
+  if (e?.name === 'UnsupportedMediaError') return 'unsupported';
+  if (e?.name === 'PersoApiError') return 'network';
+  return 'unknown';
+}
+
+// split-confirm telemetry props: real units + an ESTIMATED part count (the exact split isn't computed until the confirmed re-run).
+function splitConfirmProps(d = {}) {
+  const SIZE_CAP = 1.9 * 1024 ** 3; // mirrors split.mjs SIZE_CAP (estimate only)
+  if (d.reason === 'length') {
+    return {
+      reason: 'length',
+      duration_sec: Number.isFinite(d.actualMs) ? Math.round(d.actualMs / 1000) : null,
+      parts_est: (Number.isFinite(d.actualMs) && d.limitMs) ? Math.ceil(d.actualMs / d.limitMs) : null,
+    };
+  }
+  return {
+    reason: 'size',
+    size_mb: Number.isFinite(d.actualBytes) ? Math.round(d.actualBytes / 1024 ** 2) : null,
+    parts_est: Number.isFinite(d.actualBytes) ? Math.ceil(d.actualBytes / SIZE_CAP) : null,
+  };
+}
+
+// Sum of known chunk spans across inputs → seconds (null when no boundaries are known, e.g. an unsplit whole).
+function totalDurationSec(perInput) {
+  const ms = (perInput || []).reduce((s, p) => s + (p.chunks || []).reduce(
+    (a, c) => a + (Number.isFinite(c.startMs) && Number.isFinite(c.endMs) ? c.endMs - c.startMs : 0), 0), 0);
+  return ms > 0 ? Math.round(ms / 1000) : null;
+}
+
 // Key gate with self-healing: when no key is registered, hand off to `resolve_key.mjs --watch` in a child
 // process (creates the key file, opens it in the editor, encrypts on save, deletes the file) and continue
 // once registered. Runs in a child because Windows DPAPI work (powershell) must not run in this main process.
 // PERSO_NO_WATCH=1 restores the old fail-fast behavior (headless/CI).
 async function ensureKey() {
-  if (resolveKey()) return;
+  if (resolveKey()) { track('key_check', { has_key: true }); return; }
+  track('key_check', { has_key: false });
   if (process.env.PERSO_NO_WATCH) {
     console.error(onboardingHelp());
     throw new ExitCode(2);
   }
   notify('No API key registered — a key file will open; paste just your Perso API key and save it. (Get one: https://developers.perso.ai/api-keys)');
+  track('key_onboarding_started');
   const watcher = fileURLToPath(new URL('./resolve_key.mjs', import.meta.url));
   const code = await new Promise((res) => {
     const child = spawn(process.execPath, [watcher, '--watch'], { stdio: 'inherit' });
@@ -60,6 +96,7 @@ async function ensureKey() {
     console.error(onboardingHelp());
     throw new ExitCode(2);
   }
+  track('key_registered');
   notify('API key registered — continuing.');
 }
 
@@ -70,9 +107,9 @@ async function ensureKey() {
 // --space "<space name>".
 async function ensureSpace(args) {
   const wanted = args.space != null ? String(args.space).trim() : '';
-  if (/^\d+$/.test(wanted)) return Number(wanted); // raw seq — power users/scripts; not shown to end users
+  if (/^\d+$/.test(wanted)) { track('space_resolved'); return Number(wanted); } // raw seq — power users/scripts; not shown to end users
   const pinned = Number(process.env.PERSO_SPACE_SEQ);
-  if (!wanted && pinned) return pinned;
+  if (!wanted && pinned) { track('space_resolved'); return pinned; }
 
   const spaces = await dubbingSpaces();
   // Options shown to the user carry "name | (plan) | remaining credits" — never the internal seq.
@@ -83,7 +120,7 @@ async function ensureSpace(args) {
 
   if (wanted) {
     const hits = spaces.filter((s) => s.name.toLowerCase() === wanted.toLowerCase());
-    if (hits.length === 1) { console.log(`Space: ${brief(hits[0])}`); return hits[0].seq; }
+    if (hits.length === 1) { track('space_resolved', { plan_tier: hits[0].tier ?? null }); console.log(`Space: ${brief(hits[0])}`); return hits[0].seq; }
     if (hits.length > 1) {
       console.log(`[space-select] Several spaces share the name "${wanted}" — rename one in Perso, or pin PERSO_SPACE_SEQ:`);
       for (const s of await enrich(hits)) console.log(`  PERSO_SPACE_SEQ=${s.seq}  →  ${label(s)}`);
@@ -94,7 +131,7 @@ async function ensureSpace(args) {
     throw new ExitCode(3);
   }
 
-  if (spaces.length === 1) return spaces[0].seq;
+  if (spaces.length === 1) { track('space_resolved', { plan_tier: spaces[0].tier ?? null }); return spaces[0].seq; }
   const options = await enrich(spaces);
   if (process.stdin.isTTY && process.stdout.isTTY) {
     console.log('Several spaces are available. Which one should this dubbing run in?');
@@ -104,6 +141,7 @@ async function ensureSpace(args) {
     rl.close();
     const chosen = options[Number(answer) - 1] ?? options.find((s) => s.name.toLowerCase() === answer.toLowerCase());
     if (!chosen) { console.error('Invalid selection — run again.'); throw new ExitCode(1); }
+    track('space_resolved', { plan_tier: chosen.tier ?? null });
     console.log(`Space: ${brief(chosen)}`);
     return chosen.seq;
   }
@@ -113,7 +151,7 @@ async function ensureSpace(args) {
 }
 
 const USAGE = [
-  'Usage: node scripts/dubbing.mjs "<file|folder|URL>" ["<another input>" ...] [--source auto] [--target en,ja] [--space "space name"] [--out path|folder] [--recursive] [--lipsync] [--force]',
+  'Usage: node scripts/dubbing.mjs "<file|folder|URL>" ["<another input>" ...] [--source auto] [--target en,ja] [--space "space name"] [--out path|folder] [--recursive] [--lipsync] [--force] [--no-save]',
   '       node scripts/dubbing.mjs --lipsync-only "<project-ref JSON | projectSeq[,projectSeq...]>" [--space "space name"] [--out path|folder]',
   '       node scripts/dubbing.mjs --separate "<file|folder|URL>" ["<another input>" ...] [--space "space name"] [--out folder]',
   '       node scripts/dubbing.mjs --resume "<state-file>"',
@@ -122,6 +160,7 @@ const USAGE = [
   '  --lipsync-only  lip-sync an already-dubbed project (uses the [project-ref] line printed by a finished run; no re-dub charge)',
   '  --separate      split the source into voice / background / sub-background audio tracks (no dubbing; ~0.5 credit per second)',
   '  --force         skip the upfront credit-estimate gate of --lipsync',
+  '  --no-save       leave the result on the server without downloading it (single/unsplit input only; not with --lipsync)',
 ].join('\n');
 
 class UsageError extends Error {
@@ -145,6 +184,8 @@ function parseArgs(argv) {
     else if (t === '--separate') a.separate = true;
     else if (t === '--lipsync') a.lipsync = true;
     else if (t === '--force') a.force = true;
+    else if (t === '--allow-split') a.allowSplit = true; // user confirmed auto split→dub→merge (set on the re-run after [split-confirm])
+    else if (t === '--no-save') a.noSave = true; // server-only: skip downloading the result (single/unsplit input only)
     else if (t in VALUE_FLAGS) {
       const v = argv[++i];
       if (v === undefined || v.startsWith('--')) throw new UsageError(`Missing value for ${t}`);
@@ -166,6 +207,7 @@ async function validateLanguages(targets, source) {
   const fixed = targets.map((t) => {
     const hit = canon.get(t.toLowerCase());
     if (!hit) {
+      track('lang_invalid', { field: 'target' });
       console.error(`Unsupported target language code: "${t}"\nSupported: ${codes.join(', ')}`);
       throw new ExitCode(1);
     }
@@ -175,6 +217,7 @@ async function validateLanguages(targets, source) {
   if (source && source !== 'auto') {
     const hit = canon.get(source.toLowerCase());
     if (!hit) {
+      track('lang_invalid', { field: 'source' });
       console.error(`Unsupported source language code: "${source}" (use "auto" to detect)\nSupported: ${codes.join(', ')}`);
       throw new ExitCode(1);
     }
@@ -190,6 +233,34 @@ const refOf = (inp) => (inp.source === 'local'
 // Notice text for skipping an unsupported format (append the reason if present).
 const skipMsg = (name, e) => `Skipped (unsupported format): ${name}${e?.cause?.message ? ` (${e.cause.message})` : ''}`;
 
+// [split-confirm] prompt: which limit was exceeded + the quality caveat + how to proceed. Emitted (exit 3) before
+// the first split when --allow-split isn't set; the agent relays it and re-runs with --allow-split on the user's OK.
+function splitConfirmMessage(d, tag, action = 'dub') {
+  const min = (ms) => Math.max(1, Math.round(ms / 60000));
+  const gb = (b) => (b / 1024 ** 3).toFixed(1);
+  const label = tag ? `${tag}: ` : '';
+  const noun = action === 'separate' ? 'This file' : 'This video';
+  let head;
+  if (d.reason === 'length') {
+    const lim = d.limitMs ? `${min(d.limitMs)} min` : 'the plan limit';
+    head = d.actualMs
+      ? `${noun} exceeds the length limit (${lim}; it is ${min(d.actualMs)} min).`
+      : `${noun} exceeds the length limit (${lim}).`;
+  } else {
+    head = d.actualBytes
+      ? `${noun} exceeds the 2 GB upload limit (it is ${gb(d.actualBytes)} GB).`
+      : `${noun} exceeds the 2 GB upload limit.`;
+  }
+  const mid = action === 'separate'
+    ? 'Separating it needs automatic split → separate → merge, which may come out less polished than splitting it up yourself.'
+    : 'Dubbing it needs automatic split → dub → merge, which may come out less polished than splitting it up yourself.';
+  return [
+    `[split-confirm] ${label}${head}`,
+    `[split-confirm] ${mid}`,
+    '[split-confirm] Proceed automatically? To confirm, re-run the same command with --allow-split.',
+  ].join('\n');
+}
+
 // Save directory (non-volatile): next to the local original; current folder for URL/external/unknown.
 function inputSaveDir(inp) {
   if (inp?.source === 'local' && inp.localPath) return dirname(inp.localPath);
@@ -294,7 +365,7 @@ function buildManifest(ctx, perInput, results, prevDone = {}) {
   }
   return {
     version: 5, spaceSeq: ctx.spaceSeq, opts: { source: ctx.source }, targets: ctx.targets, out: ctx.out ?? null,
-    lipsync: !!ctx.lipsync,
+    lipsync: !!ctx.lipsync, stop_reason: ctx.stopReason ?? null,
     inputs: perInput.map((p) => ({
       inputId: p.inputId, ref: p.ref,
       chunks: p.chunks.map((c) => ({
@@ -390,6 +461,13 @@ async function finishPool(allResults, perInput, ctx) {
         failCount++;
         continue;
       }
+      if (mergeable.length && mergeable.every((r) => r.serverOnly)) {
+        // --no-save: the dubbed result was left on the server and never downloaded → report + reference, don't merge/save.
+        lines.push(`Kept on server, not saved: ${tlab} → project ${mergeable[0].projectId}`);
+        okCount++;
+        emitProjectRef(pin, tRes, target, ctx, { lipsync: false });
+        continue;
+      }
       const hasLs = mergeable.some((r) => r.lipsync);
       const lsFailed = mergeable.some((r) => r.lipsyncFailed);
       const lsPending = mergeable.some((r) => r.lipsyncPending);
@@ -424,12 +502,14 @@ async function finishPool(allResults, perInput, ctx) {
   const dlPending = allResults.some((r) => r.status === 'DLFAIL');
   const stopped = !!ctx.sched?.stopped;
   if (stopped || dlPending) {
+    ctx.stopReason = stopped ? 'quota' : 'download'; // recorded in the manifest → resume reports why it stopped
     if (ctx.multiInput && ctx.out) mkdirSync(ctx.out, { recursive: true });
     writeFileSync(ctx.file, JSON.stringify(buildManifest(ctx, perInput, allResults, ctx.prevDone ?? {})), 'utf8');
     if (stopped) {
       const plan = await getPlanStatus(ctx.spaceSeq);
       const min = remainingMinutes(ctx.sched.pendingLeft);
       const lsOwed = allResults.some((r) => r.lipsyncPending);
+      track('quota_exceeded', { plan_tier: plan?.planTier ?? null, remaining_min: min });
       console.log('\n' + messages.quotaExceeded({
         planTier: plan?.planTier,
         remainingQuota: plan?.remainingQuota,
@@ -443,10 +523,21 @@ async function finishPool(allResults, perInput, ctx) {
   } else {
     try { unlinkSync(ctx.file); } catch { /* done → clean up resume state-file (ignore if absent) */ }
   }
+  if (!ctx.lipsyncOnly) { // lipsync-only runs report via lipsync_only_started, not dubbing_completed
+    track('dubbing_completed', {
+      input_count: perInput.length, ok_count: okCount, fail_count: failCount,
+      had_split: perInput.some((p) => (p.chunks?.length ?? 0) > 1),
+      had_lipsync: allResults.some((r) => r.lipsync),
+      duration_sec: totalDurationSec(perInput),
+      source_lang: ctx.source, target_lang: (ctx.targets || []).join(','),
+      is_resume: !!ctx.isResume, recovered: !!ctx.isResume && ctx.resumedFrom === 'quota' && okCount > 0,
+    });
+  }
 }
 
 // New run: schedule all inputs as a single pool. Per-input split/upload happens once (secures mediaSeq) → reused per language.
 async function runPool(args) {
+  if (args.noSave && args.lipsync) throw new UsageError('--no-save cannot be combined with --lipsync (the lip-synced video must be downloaded).');
   await ensureKey();
   const wantedTargets = String(args.target).split(',').map((t) => t.trim()).filter(Boolean); // --target en,ja,ko
   if (!wantedTargets.length) throw new UsageError('No target language specified (--target en,ja,...)');
@@ -476,14 +567,23 @@ async function runPool(args) {
     const tag = multiInput ? `[${id + 1}/${inputs.length}] ${labelOf(inp)}` : labelOf(inp);
     let chunks;
     try {
-      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify }));
+      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
     } catch (e) {
-      if (isAuthError(e)) { console.log(`\n${friendlyError(e)}`); return; } // key issues abort everything
+      if (e?.name === 'SplitConfirmNeeded') {
+        track('split_confirm_needed', splitConfirmProps(e.details));
+        console.log(splitConfirmMessage(e.details, tag));
+        // Nothing is billed yet at the split stage, so discard any partial state so the --allow-split re-run isn't blocked by the resume guard.
+        try { if (existsSync(file)) unlinkSync(file); } catch { /* ignore */ }
+        throw new ExitCode(3);
+      }
+      if (isAuthError(e)) { track('error', { error_class: 'auth' }); console.log(`\n${friendlyError(e)}`); return; } // key issues abort everything
       if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; } // unsupported → skip
       console.log(`${tag} — split/upload failed: ${friendlyError(e)}`); continue;
     }
     if (chunks.length > 1) notify(`Split complete — ${labelOf(inp)} (${chunks.length} parts)`);
-    for (const c of chunks) pool.push({ ...c, inputId: id });
+    const noDownload = !!args.noSave && chunks.length === 1; // --no-save is single-input only; a split video's merged file needs a local download
+    if (args.noSave && chunks.length > 1) notify(`--no-save is not available for split videos (merging needs a local download) — ${labelOf(inp)} will be saved normally.`);
+    for (const c of chunks) pool.push({ ...c, inputId: id, noDownload });
     perInput.push({ inputId: id, inp, ref: refOf(inp), chunks });
     saver.writeNow(); // the chunk plan (boundaries) survives a crash from this point on
   }
@@ -491,6 +591,7 @@ async function runPool(args) {
 
   if (args.lipsync && !args.force) await creditPreflight(perInput, spaceSeq, targets.length);
 
+  track('dub_submitted', { input_count: perInput.length, parts: pool.length, target_count: targets.length, has_lipsync: !!args.lipsync });
   notify(`Translating${targets.length > 1 ? ` (${targets.join(', ')})` : ''}`);
   // Fill all inputs×parts×languages into one queue for concurrent processing. Submit as many as there are empty slots and add more every 5 minutes.
   const sched = await runSchedule(pool, spaceSeq, { source, targets, lipsync: !!args.lipsync }, { log, notify, onResult: saver.onResult, onSubmit: saver.onSubmit });
@@ -529,6 +630,7 @@ async function creditPreflight(perInput, spaceSeq, targetCount) {
     needed += Math.ceil(inputMs / 1000) * (CREDIT_RATE_DUB + CREDIT_RATE_LIPSYNC) * targetCount * mult;
   }
   if (!needed || remaining >= needed) return;
+  track('credit_check_blocked', { credits_needed: needed, credits_remaining: remaining, plan_tier: plan?.planTier ?? null });
   console.log(`[credit-check] Estimated credits for dubbing + lip-sync: ~${needed}${anyUhd ? ` (includes the ×${UHD_CREDIT_MULT} 4K surcharge)` : ''}. Credits left: ${remaining}.`);
   console.log('[credit-check] The run would stop part-way. Ask the user to top up first, or approve continuing anyway — then re-run the same command with --force (whatever completes is kept; the rest resumes later):');
   console.log(`  → ${withUtm(SUBSCRIPTION_URL)}`);
@@ -540,11 +642,13 @@ async function creditPreflight(perInput, spaceSeq, targetCount) {
 async function runResume(file) {
   await ensureKey();
   const m = JSON.parse(readFileSync(file, 'utf8'));
+  if (m.kind === 'separation') return runResumeSeparation(m, file); // separation has its own (scheduler-less) resume
   if (m.version !== 4 && m.version !== 5) throw new Error('Unsupported state-file format — run again from the original.');
   const targets = m.targets ?? [m.opts?.target ?? 'en'];
   const multiInput = (m.inputs?.length ?? 0) > 1;
   const lipsync = !!m.lipsync;
-  const ctx = { spaceSeq: m.spaceSeq, source: m.opts?.source ?? 'auto', targets, out: m.out, multiInput, file, prevDone: m.done ?? {}, lipsync };
+  const ctx = { spaceSeq: m.spaceSeq, source: m.opts?.source ?? 'auto', targets, out: m.out, multiInput, file, prevDone: m.done ?? {}, lipsync, isResume: true, resumedFrom: m.stop_reason ?? 'manual' };
+  track('resume_started', { mode: 'resume', resumed_from: m.stop_reason ?? 'manual' });
   const outDir = await makeTempDir('dubbing-resume-');
   const matCache = new Map(); // `${inputId}|${index}` → re-cut path (once per part, shared across languages)
 
@@ -707,6 +811,8 @@ async function runLipsyncOnly(args) {
   }
   const parts = Array.isArray(ref.parts) ? ref.parts : [];
   if (!parts.some((p) => p?.seq != null)) throw new UsageError('No dubbed project found in the --lipsync-only reference.');
+  const lsMs = parts.reduce((s, p) => { const r = p?.ms ?? p?.pt; return s + (Array.isArray(r) && r.length === 2 ? Math.max(0, r[1] - r[0]) : 0); }, 0);
+  track('lipsync_only_started', { input_count: 1, parts: parts.length, duration_sec: lsMs > 0 ? Math.round(lsMs / 1000) : null });
 
   const target = ref.lang ?? 'out';
   const localPath = ref.input && !/^[a-z]+:\/\//i.test(ref.input) ? ref.input : null;
@@ -714,7 +820,7 @@ async function runLipsyncOnly(args) {
   const file = resumePath({ out: args.out, inputs: [inp], multiInput: false });
   guardExistingState(file); // an interrupted earlier run owns this state file — resume it instead of re-billing
   const spaceSeq = Number(ref.space) || await ensureSpace(args);
-  const ctx = { spaceSeq, source: 'auto', targets: [target], out: args.out, multiInput: false, file, prevDone: {}, lipsync: true };
+  const ctx = { spaceSeq, source: 'auto', targets: [target], out: args.out, multiInput: false, file, prevDone: {}, lipsync: true, lipsyncOnly: true };
 
   const chunks = parts.map((p, i) => ({
     index: i, source: 'local',
@@ -750,57 +856,190 @@ async function runLipsyncOnly(args) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const SEPARATION_TRACKS = ['voice', 'background', 'sub_background'];
 
+// Separation resume state (version 1, kind 'separation'): the chunk plan + a per-chunk projectId checkpoint.
+// Mirrors the dubbing manifest but keyed by inputId|chunkIndex (no target language).
+function buildSepManifest(ctx, perInput, done) {
+  return {
+    version: 1, kind: 'separation', spaceSeq: ctx.spaceSeq, out: ctx.out ?? null,
+    inputs: perInput.map((p) => ({
+      inputId: p.inputId, ref: p.ref,
+      chunks: p.chunks.map((c) => ({
+        index: c.index, source: c.source, sourceUrl: c.sourceUrl ?? null,
+        startMs: c.startMs ?? null, endMs: c.endMs ?? null, title: c.title ?? null, kind: c.kind ?? null,
+      })),
+    })),
+    done, // `${inputId}|${index}` → { status:'RUN'|'OK'|'HARD_FAIL', projectId?, reason? }
+  };
+}
+function sepSaver(ctx, perInput, prevDone = {}) {
+  const done = { ...prevDone };
+  const writeNow = () => {
+    try {
+      mkdirSync(dirname(ctx.file), { recursive: true });
+      const tmp = ctx.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(buildSepManifest(ctx, perInput, done)), 'utf8');
+      renameSync(tmp, ctx.file);
+    } catch { /* best-effort — saving state must never break the run */ }
+  };
+  return {
+    writeNow, done,
+    // The paid projectId is persisted the moment it exists → a hard kill can't cause a re-submission on resume.
+    onSubmit: (inputId, index, projectId) => { done[`${inputId}|${index}`] = { status: 'RUN', projectId }; writeNow(); },
+    onComplete: (inputId, index, projectId) => { done[`${inputId}|${index}`] = { status: 'OK', projectId }; writeNow(); },
+    onFail: (inputId, index, reason) => { done[`${inputId}|${index}`] = { status: 'HARD_FAIL', reason }; writeNow(); },
+  };
+}
+
 async function runSeparation(args) {
   await ensureKey();
   const inputs = await expandInputs(args.inputs, { recursive: args.recursive });
+  const multiInput = inputs.length > 1;
+  const file = resumePath({ out: args.out, inputs, multiInput });
+  guardExistingState(file); // block re-running the original; --resume continues without re-billing submitted parts
   const spaceSeq = await ensureSpace(args);
+  const ctx = { spaceSeq, out: args.out ?? null, file };
+  const perInput = [];
+  const saver = sepSaver(ctx, perInput);
+  // Phase 1 — resolve chunk plans (split-confirm happens here) and persist them before any submission.
+  for (let id = 0; id < inputs.length; id++) {
+    const inp = inputs[id];
+    let chunks;
+    try {
+      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
+    } catch (e) {
+      if (e?.name === 'SplitConfirmNeeded') {
+        track('split_confirm_needed', splitConfirmProps(e.details));
+        console.log(splitConfirmMessage(e.details, multiInput ? labelOf(inp) : null, 'separate'));
+        try { if (existsSync(file)) unlinkSync(file); } catch { /* nothing billed yet → safe to discard */ }
+        throw new ExitCode(3);
+      }
+      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; }
+      notify(`Could not prepare: ${labelOf(inp)} — ${friendlyError(e)}`); continue;
+    }
+    if (chunks.length > 1) notify(`Split complete — ${labelOf(inp)} (${chunks.length} parts)`);
+    perInput.push({ inputId: id, inp, ref: refOf(inp), chunks });
+    saver.writeNow();
+  }
+  if (!perInput.length) { notify('No inputs to separate.'); return; }
+  notify('Separating voice/background');
+  // Phase 2 — submit (checkpointed) → wait → download → merge → save.
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, null, false);
+  finishSepState(file, pending);
+}
+
+// Drop the state file only when nothing paid is still owed; otherwise keep it and point at --resume (no re-billing).
+function finishSepState(file, pending) {
+  if (pending) { notify(`Some parts still need downloading — resume with: node scripts/dubbing.mjs --resume "${file}"`); return; }
+  try { if (existsSync(file)) unlinkSync(file); } catch { /* ignore */ }
+}
+
+// Resume: reload the chunk plan, re-cut/re-upload only the parts never submitted, poll/re-download the submitted ones.
+async function runResumeSeparation(m, file) {
+  if (m.version !== 1) throw new Error('Unsupported separation state-file format — run again from the original.');
+  const spaceSeq = m.spaceSeq;
+  const ctx = { spaceSeq, out: m.out ?? null, file };
+  const perInput = [];
+  const recutCache = new Map(); // `${inputId}|${index}` → re-cut path (once per part)
+  for (const pin of m.inputs) {
+    const inputStr = pin.ref.source === 'local' ? pin.ref.localPath : pin.ref.sourceUrl;
+    let localPath = null; // null when the original can't be re-prepared → materializeFor's guard fires cleanly (server-side parts still resume)
+    try { const prepared = await prepareInput(inputStr); localPath = prepared.localPath ?? prepared.path ?? null; }
+    catch (e) { console.log(`Original not available: ${pin.ref.originalName ?? inputStr ?? 'input'} (${e.message}) — server-side results only.`); }
+    perInput.push({ inputId: pin.inputId, ref: pin.ref, inp: pin.ref, chunks: pin.chunks, _localPath: localPath });
+  }
+  const saver = sepSaver(ctx, perInput, m.done ?? {});
+  const materializeFor = async (pin, c) => {
+    if (c.source === 'external') return null; // can't re-cut → upload the source URL
+    if (!pin._localPath) throw new Error('Original not found — cannot resume this part.');
+    if (c.endMs == null) return pin._localPath; // whole (unsplit) → the original
+    const mk = `${pin.inputId}|${c.index}`;
+    if (!recutCache.has(mk)) recutCache.set(mk, await recutChunk(pin._localPath, c.startMs, c.endMs));
+    return recutCache.get(mk);
+  };
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, materializeFor, true);
+  finishSepState(file, pending);
+}
+
+// Per-input: separate every chunk (checkpointing each submission), merge tracks, save. Shared by run + resume.
+// Returns true when some paid part is still owed (undelivered) → the caller must keep the state file for resume.
+async function separationProcess(perInput, spaceSeq, ctx, saver, materializeFor, isResume = false) {
   const usedByDir = new Map();
   const lines = [];
-  let okCount = 0;
-  let failCount = 0;
-  for (const inp of inputs) {
+  let ok = 0, fail = 0;
+  const flags = { pending: false };
+  const tmp = await makeTempDir('dubbing-sep-');
+  for (const pin of perInput) {
     try {
-      const line = await separateOne(inp, spaceSeq, { out: args.out, usedByDir });
+      const byTrack = await separateChunks(pin, spaceSeq, tmp, saver, materializeFor, flags);
+      const line = await saveSeparationTracks(pin, byTrack, { out: ctx.out, usedByDir });
       lines.push(line);
-      if (line.startsWith('Done')) okCount++; else failCount++;
+      if (line.startsWith('Done')) ok++; else fail++;
     } catch (e) {
-      if (e?.httpStatus === 402) { // out of credits — deliver what finished and surface the top-up path verbatim
+      if (e?.httpStatus === 402) { // out of credits — deliver what finished + top-up/resume path, then stop
         if (lines.length) console.log('\n' + lines.join('\n'));
         const plan = await getPlanStatus(spaceSeq);
-        console.log(messages.quotaExceeded({ planTier: plan?.planTier, remainingQuota: plan?.remainingQuota }));
+        console.log(messages.quotaExceeded({ planTier: plan?.planTier, remainingQuota: plan?.remainingQuota, resumeHint: `node scripts/dubbing.mjs --resume "${ctx.file}"` }));
         throw new ExitCode(1);
       }
-      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; }
-      failCount++;
-      lines.push(`Could not separate: ${labelOf(inp)} — ${friendlyError(e)}`);
+      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(pin.inp ?? pin.ref), e)); continue; }
+      flags.pending = true; // errored after some chunks may have been billed → keep state so resume re-downloads them
+      fail++;
+      lines.push(`Could not separate: ${labelOf(pin.inp ?? pin.ref)} — ${friendlyError(e)}`);
     }
   }
   console.log('\n' + lines.join('\n'));
-  if (inputs.length > 1) console.log(`\nSummary: ${okCount} done · ${failCount} failed`);
+  if (perInput.length > 1) console.log(`\nSummary: ${ok} done · ${fail} failed`);
+  track('separation_completed', { input_count: perInput.length, ok_count: ok, fail_count: fail, duration_sec: totalDurationSec(perInput), is_resume: isResume });
+  return flags.pending;
 }
 
-async function separateOne(inp, spaceSeq, { out, usedByDir }) {
-  const { chunks, notice } = await resolveChunks(inp, spaceSeq, { log, notify });
-  if (notice) notify(notice);
-  notify(`Separating voice/background — ${labelOf(inp)}`);
-
+// Separate one input's chunks. A chunk with a recorded projectId is polled/re-downloaded (no re-submit); the rest are
+// (re-cut/uploaded and) submitted, checkpointing the projectId the instant it exists.
+async function separateChunks(pin, spaceSeq, tmp, saver, materializeFor, flags) {
   const byTrack = new Map(SEPARATION_TRACKS.map((t) => [t, []]));
-  const tmp = await makeTempDir('dubbing-sep-');
-  for (const c of chunks) {
-    let { mediaSeq, kind = 'video' } = c;
-    if (mediaSeq == null) ({ seq: mediaSeq, kind } = await upload(refOf(inp), spaceSeq)); // external URL uploads here
-    const [projectId] = await requestAudioSeparation(spaceSeq, mediaSeq, { title: c.title, kind });
-    if (projectId == null) throw new Error('Separation request was not accepted.');
-    if (chunks.length > 1) log(`part ${c.index + 1}/${chunks.length}: separation submitted`);
-    const st = await waitForProject(projectId, spaceSeq);
-    if (st.state !== 'complete') { // a failed part becomes a gap in every track (same as dubbing merge boundaries)
-      for (const t of SEPARATION_TRACKS) byTrack.get(t).push({ index: c.index, status: 'HARD_FAIL', reason: st.message ?? st.failureReason ?? 'failed' });
-      continue;
+  const gap = (index, reason) => { for (const t of SEPARATION_TRACKS) byTrack.get(t).push({ index, status: 'HARD_FAIL', reason }); };
+  for (const c of pin.chunks) {
+    const prev = saver.done[`${pin.inputId}|${c.index}`];
+    if (prev?.status === 'HARD_FAIL') { gap(c.index, prev.reason ?? 'failed'); continue; }
+    let projectId = prev?.projectId ?? null;
+    try {
+      if (projectId == null) { // never submitted → (re-cut/upload and) submit
+        let mediaSeq = c.mediaSeq ?? null, kind = c.kind ?? 'video';
+        if (mediaSeq == null) {
+          const cut = materializeFor ? await materializeFor(pin, c) : null;
+          const ref = cut ? { source: 'local', localPath: cut, originalName: basename(cut) } // basename keeps the extension (c.title has none)
+            : (c.source === 'external' ? { source: 'external', sourceUrl: c.sourceUrl } : refOf(pin.inp ?? pin.ref));
+          ({ seq: mediaSeq, kind } = await upload(ref, spaceSeq));
+        }
+        ([projectId] = await requestAudioSeparation(spaceSeq, mediaSeq, { title: c.title, kind }));
+        if (projectId == null) throw new Error('Separation request was not accepted.');
+        saver.onSubmit(pin.inputId, c.index, projectId); // checkpoint the billed unit before any wait
+        if (pin.chunks.length > 1) log(`part ${c.index + 1}/${pin.chunks.length}: separation submitted`);
+      }
+      if (prev?.status !== 'OK') { // RUN (resume) or freshly submitted → wait for completion
+        const st = await waitForProject(projectId, spaceSeq);
+        if (st.state !== 'complete') {
+          if (st.timedOut) { flags.pending = true; gap(c.index, st.message ?? 'timed out'); continue; } // may still be running (paid) → keep the RUN checkpoint so resume re-polls it
+          saver.onFail(pin.inputId, c.index, st.message ?? st.failureReason ?? 'failed'); // genuine server failure → terminal
+          gap(c.index, st.message ?? st.failureReason ?? 'failed');
+          continue;
+        }
+        saver.onComplete(pin.inputId, c.index, projectId);
+      }
+      const tracks = await downloadSeparation(projectId, spaceSeq, (label, ext) => join(tmp, `sep_${pin.inputId}_${c.index}_${label}${ext}`));
+      for (const t of tracks) byTrack.get(t.label)?.push({ index: c.index, status: 'OK', path: t.path, name: t.fileName });
+    } catch (e) {
+      if (e?.httpStatus === 402) throw e; // credit-out → let separationProcess deliver finished parts + surface the resume path
+      // One part failed to prepare/upload/submit/download — gap it so finished sibling parts still merge & save; keep state so resume retries.
+      flags.pending = true;
+      gap(c.index, friendlyError(e));
     }
-    const tracks = await downloadSeparation(projectId, spaceSeq, (label, ext) => join(tmp, `sep_${c.index}_${label}${ext}`));
-    for (const t of tracks) byTrack.get(t.label)?.push({ index: c.index, status: 'OK', path: t.path, name: t.fileName });
   }
+  return byTrack;
+}
 
+async function saveSeparationTracks(pin, byTrack, { out, usedByDir }) {
+  const inp = pin.inp ?? pin.ref;
   const dir = out ?? inputSaveDir(inp); // --separate treats --out as a folder (three tracks per input)
   mkdirSync(dir, { recursive: true });
   const stem = String(labelOf(inp)).replace(/\.[^.\\/]+$/, '') || 'output';
@@ -836,19 +1075,31 @@ async function waitForProject(projectSeq, spaceSeq) {
     if (st?.state === 'complete' || st?.state === 'failed') return st;
     const p = st?.progress ?? -1;
     if (p !== last) { last = p; lastChange = Date.now(); if (p > 0) log(`separating... ${p}%`); }
-    if (Date.now() - lastChange > MAX_IDLE_MS) return { state: 'failed', message: 'timed out (no progress)' };
+    if (Date.now() - lastChange > MAX_IDLE_MS) return { state: 'failed', timedOut: true, message: 'timed out (no progress)' };
     await sleep(POLL_INTERVAL_MS);
   }
 }
 
 // Pure helper exports for testing (when run directly, only main below executes).
-export { parseArgs, targetPaths, buildManifest, doneEntry, manifestSaver, finishPool, refOf, resumePath, explicitOutPath, remainingMinutes, guardExistingState };
+export { parseArgs, targetPaths, buildManifest, doneEntry, manifestSaver, finishPool, refOf, resumePath, explicitOutPath, remainingMinutes, guardExistingState, splitConfirmMessage, buildSepManifest, sepSaver };
 
 async function main() {
   let exitCode = 0;
+  let updateNotice = null; // daily version check, kicked off in the background and printed after the work finishes
   try {
     preloadKeyEnv(); // pre-inject the key into env before async (at a clean point) → avoid a synchronous powershell call/crash in the main process
     const args = parseArgs(process.argv.slice(2));
+    if (!args.help) {
+      updateNotice = checkForUpdate().catch(() => null); // non-blocking; never fails the run
+      initTelemetry(); // emits first_run once per install
+      track('run_started', {
+        mode: args.resume ? 'resume' : args.separate ? 'separate' : args.lipsyncOnly ? 'lipsync-only' : args.lipsync ? 'lipsync' : 'dub',
+        input_count: args.inputs.length || null,
+        target_count: String(args.target).split(',').map((s) => s.trim()).filter(Boolean).length || null,
+        has_lipsync: !!(args.lipsync || args.lipsyncOnly),
+        source_lang: args.source,
+      });
+    }
     if (args.help) console.log(USAGE);
     else if (args.resume) await runResume(args.resume);
     else if (args.separate) {
@@ -866,10 +1117,12 @@ async function main() {
   } catch (e) {
     if (e?.name === 'ExitCode') exitCode = e.code; // message already printed at the throw site
     else if (e?.name === 'UsageError') { console.error(`${e.message}\n${USAGE}`); exitCode = 1; }
-    else { console.error(friendlyError(e)); exitCode = 1; }
+    else { track('error', { error_class: errorClass(e) }); console.error(friendlyError(e)); exitCode = 1; }
   } finally {
     await cleanupTempDirs(); // bulk-clean the cut/schedule/merge/download temp folders
   }
+  // After the work is done (never mid-job), surface a version-update notice if one is available.
+  if (updateNotice) { try { const n = await updateNotice; if (n) console.log('\n' + n); } catch { /* ignore */ } }
   // Natural exit (loop drain) — process.exit() while fetch sockets are closing hits a Windows libuv assert
   // (async.c) that corrupts the exit code. The unref'd timer is a hard-exit fallback if a handle ever hangs.
   process.exitCode = exitCode;

package/skills/dubbing/scripts/probe_split.mjs

@@ -18,7 +18,7 @@ function parseArg(arg) {
 try {
   const prepared = parseArg(process.argv[2]);
   const spaceSeq = Number(process.env.PERSO_SPACE_SEQ) || (await resolveSpace());
-  const result = await resolveChunks(prepared, spaceSeq);
+  const result = await resolveChunks(prepared, spaceSeq, { allowSplit: true }); // debug tool: split without the pre-confirm gate
   console.log(JSON.stringify(result));
 } catch (e) {
   console.error(e.message);