@sogni-ai/sogni-creative-agent-skill 3.3.5 → 3.4.0

package/sogni-agent.mjs

@@ -4,11 +4,15 @@
  * Usage: sogni-agent [options] "prompt"
  */
 
+// Must be first: a zero-dependency Node.js version guard that runs before
+// `sharp` / the Sogni SDK load, so an unsupported Node prints a clear message
+// instead of a cryptic native/ESM crash.
+import './node-version-check.mjs';
 import JSON5 from 'json5';
 import { createHash, randomBytes } from 'crypto';
 import { createRequire } from 'module';
 import { readFileSync, writeFileSync, existsSync, mkdirSync, mkdtempSync, statSync, readdirSync, realpathSync, lstatSync, unlinkSync, rmdirSync } from 'fs';
-import { join, dirname, basename, extname, sep } from 'path';
+import { join, dirname, basename, extname, sep, resolve } from 'path';
 import { homedir, tmpdir } from 'os';
 import sharp from 'sharp';
 import { getEnv, hasEnv } from './env.mjs';
@@ -78,6 +82,9 @@ import {
   validateSeedanceReferenceCounts
 } from '@sogni-ai/sogni-intelligence-client/tools';
 
+const SPARK_PACKS_PURCHASE_URL = 'https://docs.sogni.ai/pricing/#spark-packs';
+const SPARK_PACKS_PURCHASE_HINT = `Buy Spark Packs to continue: ${SPARK_PACKS_PURCHASE_URL}`;
+
 const require = createRequire(import.meta.url);
 const rootClientModule = process.env.SOGNI_AGENT_TEST_STATE_PATH
   ? await import('@sogni-ai/sogni-intelligence-client')
@@ -119,7 +126,9 @@ function sanitizePath(p, label) {
     err.code = 'INVALID_PATH';
     throw err;
   }
-  return p;
+  // Expand a leading `~`/`~/` so quoted paths (where the shell didn't expand it,
+  // e.g. --ref "~/face.jpg") and agent-passed literals resolve to the home dir.
+  return expandHomePath(p);
 }
 
 const DEFAULT_CREDENTIALS_PATH = join(homedir(), '.config', 'sogni', 'credentials');
@@ -242,6 +251,13 @@ function buildCliErrorPayload({ message, code, details, hint, prompt }) {
   if (code) payload.errorCode = code;
   if (details) payload.errorDetails = details;
   if (hint) payload.hint = hint;
+  if (classified.category === 'insufficient_credits') {
+    payload.purchaseAction = true;
+    payload.purchaseLabel = 'Buy Spark Packs';
+    payload.purchaseUrl = SPARK_PACKS_PURCHASE_URL;
+    payload.purchaseReason = SPARK_PACKS_PURCHASE_HINT;
+    if (!payload.hint) payload.hint = SPARK_PACKS_PURCHASE_HINT;
+  }
   payload.timestamp = new Date().toISOString();
   payload.node = process.versions.node;
   payload.cwd = process.cwd();
@@ -314,6 +330,13 @@ function addCanonicalErrorFields(payload, error) {
   if (classified.technicalError && classified.technicalError !== classified.message) {
     payload.technicalError = classified.technicalError;
   }
+  if (classified.category === 'insufficient_credits') {
+    payload.purchaseAction = true;
+    payload.purchaseLabel = 'Buy Spark Packs';
+    payload.purchaseUrl = SPARK_PACKS_PURCHASE_URL;
+    payload.purchaseReason = SPARK_PACKS_PURCHASE_HINT;
+    if (!payload.hint) payload.hint = SPARK_PACKS_PURCHASE_HINT;
+  }
   return payload;
 }
 
@@ -349,6 +372,76 @@ function fatalCliError(message, opts = {}) {
   process.exit(1);
 }
 
+// Friendly guidance shown when the Sogni API key is missing or rejected.
+const INVALID_API_KEY_HINT =
+  'Your Sogni API key was rejected. Verify it — or generate a new one — by ' +
+  'logging into https://dashboard.sogni.ai and opening the account menu. ' +
+  "If you don't have a Sogni account yet, create one there first, then add its API key.";
+
+// Detect an invalid/rejected API key across the several shapes the SDK can
+// surface it in. The SDK reports the REST 401 directly (ApiError with
+// status/errorCode), but it can also cascade: a 401 triggers
+// ApiKeyAuthManager.clear(), which tears down the socket and re-throws as an
+// unhandled "WebSocket was closed before the connection was established"
+// error whose only auth fingerprint is the stack frame.
+function isInvalidApiKeyError(error) {
+  if (!error) return false;
+  const status = error.status ?? error.statusCode ?? error?.payload?.status;
+  const apiCode = error?.payload?.errorCode ?? error?.errorCode;
+  if (status === 401 || apiCode === 101) return true;
+  const message = (cliErrorMessage(error) || '').toLowerCase();
+  if (message.includes('invalid api key')) return true;
+  const stack = (typeof error?.stack === 'string' ? error.stack : '').toLowerCase();
+  if (stack.includes('apikeyauthmanager') || stack.includes('handleauthupdated')) return true;
+  return false;
+}
+
+// Last line of defense. The SDK can reject from a detached promise or emit an
+// unhandled 'error' event during connect, which escapes main()'s try/catch and
+// crashes the process with a raw stack trace. These handlers turn any such
+// fatal into the same clean `Error:`/`Hint:` (or JSON) output as every other
+// CLI error path, and exit 1.
+let __fatalReported = false;
+function reportFatalError(error) {
+  if (__fatalReported) {
+    try { process.exit(1); } catch (_) { /* already exiting */ }
+    return;
+  }
+  __fatalReported = true;
+  if (getEnv('SOGNI_DEBUG') || getEnv('DEBUG')) {
+    console.error(error?.stack || String(error));
+  }
+  if (isInvalidApiKeyError(error)) {
+    fatalCliError('Invalid Sogni API key.', {
+      code: 'INVALID_API_KEY',
+      hint: INVALID_API_KEY_HINT
+    });
+    return;
+  }
+  fatalCliError(cliErrorMessage(error), {
+    code: error?.code,
+    details: error?.details,
+    hint: error?.hint
+  });
+}
+process.on('uncaughtException', reportFatalError);
+process.on('unhandledRejection', reportFatalError);
+
+// Connect to Sogni, mapping a rejected connection into a clean auth error
+// where we can. (Detached SDK failures that never reach this await are caught
+// by the global handlers above.)
+async function connectSogniClient(client) {
+  try {
+    await client.connect();
+  } catch (error) {
+    if (isInvalidApiKeyError(error) && !error.hint) {
+      error.hint = INVALID_API_KEY_HINT;
+      if (!error.code) error.code = 'INVALID_API_KEY';
+    }
+    throw error;
+  }
+}
+
 function applyVideoPromptGuardrails() {
   if (!options.video || !options.prompt) return;
   if (options._literalPrompt) return;
@@ -678,7 +771,7 @@ function parseIntegerValue(raw, flagName) {
   return num;
 }
 
-function parsePositiveIntegerValue(raw, flagName, min = 1) {
+function parsePositiveIntegerValue(raw, flagName, min = 1, max = Infinity) {
   const num = parseIntegerValue(raw, flagName);
   if (num < min) {
     fatalCliError(`${flagName} must be >= ${min}.`, {
@@ -686,9 +779,20 @@ function parsePositiveIntegerValue(raw, flagName, min = 1) {
       details: { flag: flagName, value: raw, min }
     });
   }
+  if (num > max) {
+    fatalCliError(`${flagName} must be <= ${max}.`, {
+      code: 'INVALID_ARGUMENT',
+      details: { flag: flagName, value: raw, max }
+    });
+  }
   return num;
 }
 
+// Sanity ceiling for image dimensions — well above any model's real maximum,
+// just large enough to catch obvious typos (e.g. a stray extra zero) before
+// they waste a round-trip or blow up local memory.
+const MAX_IMAGE_DIMENSION = 8192;
+
 function parseSeedValue(raw, flagName) {
   const num = parseIntegerValue(raw, flagName);
   if (num < 0 || num > 0xFFFFFFFF) {
@@ -718,6 +822,7 @@ function buildBalanceError(message, details) {
   const err = new Error(message);
   err.code = 'INSUFFICIENT_BALANCE';
   err.details = details || null;
+  err.hint = SPARK_PACKS_PURCHASE_HINT;
   return err;
 }
 
@@ -725,6 +830,27 @@ function isStructuredInsufficientBalanceError(error) {
   return Boolean(error && typeof error === 'object' && error.code === 'INSUFFICIENT_BALANCE');
 }
 
+/**
+ * Build an Error from an SDK project result that signals failure via
+ * `{ error, message, code, details, hint }` fields instead of throwing.
+ * Preserving `code` is critical — without it, downstream classification
+ * (auto-fallback retry via `isStructuredInsufficientBalanceError`, and
+ * the `insufficient_credits` payload enrichment in `buildCliErrorPayload`
+ * / `addCanonicalErrorFields`) cannot tell that the failure is e.g.
+ * `INSUFFICIENT_BALANCE`, so the "Buy Spark Packs" CTA silently no-ops.
+ */
+function buildProjectResultError(projectResult) {
+  const message = projectResult?.error || projectResult?.message || 'Project failed';
+  const err = new Error(message);
+  if (projectResult?.code) err.code = projectResult.code;
+  if (projectResult?.details) err.details = projectResult.details;
+  if (projectResult?.hint) err.hint = projectResult.hint;
+  if (classifyCliError(err).category === 'insufficient_credits' && !err.hint) {
+    err.hint = SPARK_PACKS_PURCHASE_HINT;
+  }
+  return err;
+}
+
 function gcdInt(a, b) {
   let x = Math.abs(Math.trunc(a));
   let y = Math.abs(Math.trunc(b));
@@ -1132,6 +1258,9 @@ function loadOpenClawPluginConfig() {
     try {
       return JSON5.parse(openclawPluginConfig);
     } catch (e) {
+      // Warn (don't crash): a malformed inline config silently dropping all the
+      // user's defaults is a confusing trap.
+      console.error(`Warning: OPENCLAW_PLUGIN_CONFIG is not valid JSON5 (${e?.message || e}); ignoring it and using defaults.`);
       return null;
     }
   }
@@ -1141,6 +1270,7 @@ function loadOpenClawPluginConfig() {
     const parsed = JSON5.parse(raw);
     return parsed?.plugins?.entries?.['sogni-creative-agent-skill']?.config || null;
   } catch (e) {
+    console.error(`Warning: could not parse ${OPENCLAW_CONFIG_PATH} (${e?.message || e}); ignoring it and using defaults.`);
     return null;
   }
 }
@@ -1243,6 +1373,19 @@ const options = {
   concatVideosClips: null,
   concatAudio: null, // Optional audio file to mux over concatenated clips
   concatAudioStart: null,
+  concatFps: null, // --concat-fps <n>: override target fps for concat normalization
+  extractFirstFrame: null, // --extract-first-frame <video> <image>
+  extractFirstFrameOutput: null,
+  // Audio remix (--remix-audio <in_video> <out_video>): loop/fade/mix without re-encoding video
+  remixAudio: null,
+  remixAudioOutput: null,
+  bedAudio: null, // --bed-audio <path|video>: audio bed (defaults to input video's own audio)
+  audioLoop: false, // --audio-loop: loop the bed to cover the full video duration
+  audioFadeIn: null, // --audio-fade-in <sec>
+  audioFadeOut: null, // --audio-fade-out <sec>
+  mixAudio: null, // --mix-audio <path|video>: one extra track to overlay
+  mixAt: null, // --mix-at <sec>: offset for the mix track (default 0)
+  mixGain: null, // --mix-gain <db>: gain applied to the mix track (default 0)
   listMedia: null, // --list-media [images|audio|all]
   // Memory, personality, persona commands
   memoryAction: null, // set|get|list|remove
@@ -1394,7 +1537,7 @@ for (let i = 0; i < args.length; i++) {
   if (arg === '-o' || arg === '--output') {
     const raw = requireFlagValue(args, i, arg);
     i++;
-    options.output = raw;
+    options.output = expandHomePath(raw);
     cliSet.output = true;
   } else if (arg === '-m' || arg === '--model') {
     const raw = requireFlagValue(args, i, arg);
@@ -1404,12 +1547,12 @@ for (let i = 0; i < args.length; i++) {
   } else if (arg === '-w' || arg === '--width') {
     const raw = requireFlagValue(args, i, arg);
     i++;
-    options.width = parsePositiveIntegerValue(raw, arg);
+    options.width = parsePositiveIntegerValue(raw, arg, 1, MAX_IMAGE_DIMENSION);
     cliSet.width = true;
   } else if (arg === '-h' || arg === '--height') {
     const raw = requireFlagValue(args, i, arg);
     i++;
-    options.height = parsePositiveIntegerValue(raw, arg);
+    options.height = parsePositiveIntegerValue(raw, arg, 1, MAX_IMAGE_DIMENSION);
     cliSet.height = true;
   } else if (arg === '-n' || arg === '--count') {
     const raw = requireFlagValue(args, i, arg);
@@ -1630,17 +1773,17 @@ for (let i = 0; i < args.length; i++) {
     options.autoResizeVideoAssets = false;
     cliSet.autoResizeVideoAssets = true;
   } else if (arg === '--ref' || arg === '--reference') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     options.refImage = raw;
     cliSet.refImage = true;
   } else if (arg === '--ref-end' || arg === '--end') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     options.refImageEnd = raw;
     cliSet.refImageEnd = true;
   } else if (arg === '--ref-audio' || arg === '--audio') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     if (!options.refAudio) {
       options.refAudio = raw;
@@ -1660,7 +1803,7 @@ for (let i = 0; i < args.length; i++) {
     options.audioDuration = parseNonNegativeNumberValue(raw, arg);
     cliSet.audioDuration = true;
   } else if (arg === '--reference-audio-identity' || arg === '--voice-identity') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     options.referenceAudioIdentity = raw;
     cliSet.referenceAudioIdentity = true;
@@ -1670,7 +1813,7 @@ for (let i = 0; i < args.length; i++) {
     options.voicePersonaName = raw;
     cliSet.voicePersonaName = true;
   } else if (arg === '--ref-video') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     if (!options.refVideo) {
       options.refVideo = raw;
@@ -1688,7 +1831,7 @@ for (let i = 0; i < args.length; i++) {
     options.looping = true;
     cliSet.looping = true;
   } else if (arg === '-c' || arg === '--context') {
-    const raw = requireFlagValue(args, i, arg);
+    const raw = expandHomePath(requireFlagValue(args, i, arg));
     i++;
     options.contextImages.push(raw);
     cliSet.context = true;
@@ -1775,6 +1918,50 @@ for (let i = 0; i < args.length; i++) {
     const raw = requireFlagValue(args, i, arg);
     i++;
     options.concatAudioStart = parseNonNegativeNumberValue(raw, arg);
+  } else if (arg === '--concat-fps') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.concatFps = parseNumberValue(raw, arg);
+  } else if (arg === '--extract-first-frame') {
+    const videoArg = requireFlagValue(args, i, arg);
+    i++;
+    const imageArg = requireFlagValue(args, i, arg + ' (output image)');
+    i++;
+    options.extractFirstFrame = videoArg;
+    options.extractFirstFrameOutput = imageArg;
+  } else if (arg === '--remix-audio') {
+    const inArg = requireFlagValue(args, i, arg + ' (input video)');
+    i++;
+    const outArg = requireFlagValue(args, i, arg + ' (output video)');
+    i++;
+    options.remixAudio = inArg;
+    options.remixAudioOutput = outArg;
+  } else if (arg === '--bed-audio') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.bedAudio = raw;
+  } else if (arg === '--audio-loop') {
+    options.audioLoop = true;
+  } else if (arg === '--audio-fade-in') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.audioFadeIn = parseNonNegativeNumberValue(raw, arg);
+  } else if (arg === '--audio-fade-out') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.audioFadeOut = parseNonNegativeNumberValue(raw, arg);
+  } else if (arg === '--mix-audio') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.mixAudio = raw;
+  } else if (arg === '--mix-at') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.mixAt = parseNonNegativeNumberValue(raw, arg);
+  } else if (arg === '--mix-gain') {
+    const raw = requireFlagValue(args, i, arg);
+    i++;
+    options.mixGain = parseNumberValue(raw, arg);
   } else if (arg === '--list-media') {
     // Optional type argument (images|audio|all), default: images
     const next = args[i + 1];
@@ -2030,7 +2217,7 @@ for (let i = 0; i < args.length; i++) {
   } else if (arg === '--voice') {
     options.personaVoice = requireFlagValue(args, i, arg); i++;
   } else if (arg === '--voice-clip') {
-    options.personaVoiceClip = requireFlagValue(args, i, arg); i++;
+    options.personaVoiceClip = expandHomePath(requireFlagValue(args, i, arg)); i++;
   // --- Content filter ---
   } else if (arg === '--no-filter') {
     options.noFilter = true;
@@ -2221,9 +2408,21 @@ General:
   --no-update-check     Skip the once-daily npm update check for this run
   self-update           Upgrade sogni-agent in place (npm/pnpm/yarn/bun auto-detected)
   --extract-last-frame <video> <image>  Extract last frame from a video (safe ffmpeg wrapper)
-  --concat-videos <out> <clips...>      Concatenate video clips (safe ffmpeg wrapper, min 2 clips)
+  --extract-first-frame <video> <image> Extract first frame from a video (safe ffmpeg wrapper)
+  --concat-videos <out> <clips...>      Concatenate video clips (safe ffmpeg wrapper, min 2 clips).
+                        Normalizes fps/size and fills silent audio so mismatched clips stitch cleanly.
+  --concat-fps <n>      Override target fps for --concat-videos (default: highest clip fps)
   --concat-audio <path> Optional audio track to mux over --concat-videos output
   --concat-audio-start <sec> Start offset into --concat-audio
+  --remix-audio <in> <out>  Rebuild a video's audio without re-encoding video (safe ffmpeg wrapper).
+                        Combine with the audio flags below.
+  --bed-audio <path>    Audio bed for --remix-audio (path or video; defaults to input's own audio)
+  --audio-loop          Loop the bed to cover the full video duration (--remix-audio)
+  --audio-fade-in <sec> Fade the bed in over <sec> seconds (--remix-audio)
+  --audio-fade-out <sec> Fade the bed out over <sec> seconds at the tail (--remix-audio)
+  --mix-audio <path>    Overlay one extra audio track, mixed with the bed (--remix-audio)
+  --mix-at <sec>        Start offset for --mix-audio (default: 0)
+  --mix-gain <db>       Gain in dB applied to --mix-audio (default: 0)
   --list-media [type]   List recent inbound media files (images|audio|all, default: images)
   --no-filter           Disable NSFW content filter
   --last                Show last render info (JSON)
@@ -2944,7 +3143,9 @@ const commandUsesGenerationSeed = !options.apiChat &&
   !options.showBalance &&
   !options.showVersion &&
   !options.extractLastFrame &&
+  !options.extractFirstFrame &&
   !options.concatVideos &&
+  !options.remixAudio &&
   !options.listMedia &&
   !options.memoryAction &&
   !options.personalityAction &&
@@ -2955,7 +3156,12 @@ if (apiWorkflowStartAction && apiWorkflowTemplate === 'generated_keyframe_video'
 if (apiWorkflowStartAction && apiWorkflowTemplate === 'storyboard_video' && !options.prompt && !apiWorkflowStartHasExternalInput) {
   fatalCliError('--api-workflow storyboard-video preset requires a prompt or --workflow-input JSON.', { code: 'INVALID_ARGUMENT' });
 }
-if (!options.prompt && !options.apiChat && !apiWorkflowUtilityAction && !apiWorkflowStartAction && !apiModelUtilityAction && !apiReplayUtilityAction && !contractUtilityAction && !storyboardPlanUtilityAction && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.concatVideos && !options.listMedia && !options.memoryAction && !options.personalityAction && !personaUtilityAction) {
+// Normalize a whitespace-only prompt to empty so the guard below treats it as
+// "no prompt" rather than silently sending blank text to the server.
+if (typeof options.prompt === 'string' && options.prompt.trim() === '') {
+  options.prompt = '';
+}
+if (!options.prompt && !options.apiChat && !apiWorkflowUtilityAction && !apiWorkflowStartAction && !apiModelUtilityAction && !apiReplayUtilityAction && !contractUtilityAction && !storyboardPlanUtilityAction && !options.estimateVideoCost && !options.multiAngle && !options.showBalance && !options.showVersion && !options.extractLastFrame && !options.extractFirstFrame && !options.concatVideos && !options.remixAudio && !options.listMedia && !options.memoryAction && !options.personalityAction && !personaUtilityAction) {
   fatalCliError('No prompt provided. Use --help for usage.', { code: 'INVALID_ARGUMENT' });
 }
 
@@ -3366,14 +3572,48 @@ if (commandUsesGenerationSeed && (options.seed === null || options.seed === unde
 }
 
 // Load credentials
+// Parse a `KEY=value` credentials file robustly. Tolerates: a UTF-8 BOM, an
+// optional `export ` prefix, `#` comments, blank lines, CRLF endings, surrounding
+// whitespace, surrounding single/double quotes, and `=` characters inside the
+// value (only the first `=` splits). Hand-edited files are the norm here.
+function parseCredentialsFile(content) {
+  const creds = {};
+  const text = content.charCodeAt(0) === 0xfeff ? content.slice(1) : content; // strip BOM
+  for (const rawLine of text.split('\n')) {
+    let line = rawLine.trim();
+    if (!line || line.startsWith('#')) continue;
+    if (line.startsWith('export ')) line = line.slice('export '.length).trim();
+    const eq = line.indexOf('=');
+    if (eq === -1) continue;
+    const key = line.slice(0, eq).trim();
+    let value = line.slice(eq + 1).trim();
+    if (value.length >= 2 &&
+        ((value.startsWith('"') && value.endsWith('"')) ||
+         (value.startsWith("'") && value.endsWith("'")))) {
+      value = value.slice(1, -1);
+    }
+    if (key) creds[key] = value;
+  }
+  return creds;
+}
+
 function loadCredentials() {
+  let credentialsFileExisted = false;
   if (existsSync(CREDENTIALS_PATH)) {
-    const content = readFileSync(CREDENTIALS_PATH, 'utf8');
-    const creds = {};
-    for (const line of content.split('\n')) {
-      const [key, val] = line.split('=');
-      if (key && val) creds[key.trim()] = val.trim();
+    credentialsFileExisted = true;
+    let content;
+    try {
+      content = readFileSync(CREDENTIALS_PATH, 'utf8');
+    } catch (readErr) {
+      const err = new Error(`Could not read Sogni credentials file at ${CREDENTIALS_PATH}.`);
+      err.code = 'CREDENTIALS_UNREADABLE';
+      err.hint = readErr?.code === 'EACCES'
+        ? 'Fix the file permissions (e.g. `chmod 600 ' + CREDENTIALS_PATH + '`), or set SOGNI_API_KEY in the environment instead.'
+        : 'Check the file, or set SOGNI_API_KEY in the environment instead.';
+      err.details = { triedFile: CREDENTIALS_PATH, cause: readErr?.code || String(readErr) };
+      throw err;
     }
+    const creds = parseCredentialsFile(content);
     if (creds.SOGNI_API_KEY) {
       return {
         SOGNI_API_KEY: creds.SOGNI_API_KEY
@@ -3387,12 +3627,17 @@ function loadCredentials() {
     };
   }
 
+  // Distinguish "file exists but has no usable key" from "no file at all" —
+  // the former is a common hand-edit mistake (typo, wrong line, stray quotes).
   const err = new Error('No Sogni API key found.');
   err.code = 'MISSING_CREDENTIALS';
-  err.hint = 'Set SOGNI_API_KEY, or configure SOGNI_CREDENTIALS_PATH with SOGNI_API_KEY. You can find your API key by logging into https://dashboard.sogni.ai and opening the account menu.';
+  err.hint = credentialsFileExisted
+    ? `Found ${CREDENTIALS_PATH} but it has no usable "SOGNI_API_KEY=..." line. Check for typos/extra quotes, or set SOGNI_API_KEY in the environment. Get your key at https://dashboard.sogni.ai (account menu).`
+    : 'Set SOGNI_API_KEY, or configure SOGNI_CREDENTIALS_PATH with SOGNI_API_KEY. You can find your API key by logging into https://dashboard.sogni.ai and opening the account menu.';
   err.details = {
     triedEnv: ['SOGNI_API_KEY'],
-    triedFile: CREDENTIALS_PATH
+    triedFile: CREDENTIALS_PATH,
+    credentialsFileExisted
   };
   throw err;
 }
@@ -3614,6 +3859,40 @@ async function dispatchMediaReferenceUrlViaSdk({ ref, file, index, jobId, action
   );
 }
 
+// Default HTTP timeout for plain REST calls and downloads. Without this, a
+// black-holing proxy / captive portal makes the CLI hang forever with no
+// output. Override via SOGNI_HTTP_TIMEOUT_MS. (The SDK generation wait is
+// governed separately by --timeout.)
+const DEFAULT_HTTP_TIMEOUT_MS = (() => {
+  const raw = Number.parseInt(getEnv('SOGNI_HTTP_TIMEOUT_MS') || '', 10);
+  return Number.isFinite(raw) && raw > 0 ? raw : 30000;
+})();
+
+// Uploads keep the timer running for the whole request-body send (the fetch
+// promise only resolves once the server responds), so they get a longer budget
+// than the connect-phase default that suffices for GET/download/stream calls.
+const UPLOAD_HTTP_TIMEOUT_MS = Math.max(DEFAULT_HTTP_TIMEOUT_MS, 120000);
+
+// fetch() with an AbortController-based timeout that maps a timeout/abort into a
+// clean, coded error instead of a hang or an opaque "aborted" stack.
+async function fetchWithTimeout(resource, init = {}, timeoutMs = DEFAULT_HTTP_TIMEOUT_MS) {
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), timeoutMs);
+  try {
+    return await fetch(resource, { ...init, signal: controller.signal });
+  } catch (error) {
+    if (error?.name === 'AbortError') {
+      const err = new Error(`Sogni network request timed out after ${Math.round(timeoutMs / 1000)}s.`);
+      err.code = 'NETWORK_TIMEOUT';
+      err.hint = 'Check your internet connection. If you are behind a corporate proxy/VPN or firewall, it may be blocking api.sogni.ai. You can raise the limit with SOGNI_HTTP_TIMEOUT_MS.';
+      throw err;
+    }
+    throw error;
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
 async function fetchApiJson(path, { apiKey, method = 'GET', body = undefined, headers = {} } = {}) {
   const url = await buildSafeApiUrl(path);
   const init = {
@@ -3622,7 +3901,7 @@ async function fetchApiJson(path, { apiKey, method = 'GET', body = undefined, he
     ...(body === undefined ? {} : { body: JSON.stringify(body) })
   };
 
-  const response = await fetch(url, init);
+  const response = await fetchWithTimeout(url, init);
   const text = await response.text();
   let payload = {};
   if (text) {
@@ -3692,6 +3971,13 @@ function mimeTypeForMediaReference(ref) {
 
 function localApiMediaReferenceFile(ref) {
   const filePath = sanitizePath(String(ref.value || ''), `${ref.flag} media reference`);
+  if (!existsSync(filePath)) {
+    const err = new Error(`${ref.flag} file not found: ${filePath}`);
+    err.code = 'MEDIA_REFERENCE_NOT_FOUND';
+    err.hint = `Check the path is correct and relative to your current directory (${process.cwd()}). Use ~ for your home directory, or pass an http(s) URL.`;
+    err.details = { flag: ref.flag, path: filePath };
+    throw err;
+  }
   const stat = statSync(filePath);
   if (!stat.isFile()) {
     const err = new Error(`${ref.flag} must point to a file when using local API media references.`);
@@ -3792,10 +4078,10 @@ async function postApiMediaUploadForm(uploadPayload, file) {
   const body = file.buffer || readFileSync(file.filePath);
   form.append('file', new Blob([body], { type: file.mimeType }), file.filename);
 
-  const response = await fetch(url, {
+  const response = await fetchWithTimeout(url, {
     method: 'POST',
     body: form,
-  });
+  }, UPLOAD_HTTP_TIMEOUT_MS);
   if (!response.ok) {
     const err = new Error(`Failed to upload ${file.filename} (${response.status} ${response.statusText}).`);
     err.code = 'MEDIA_UPLOAD_FAILED';
@@ -3805,11 +4091,11 @@ async function postApiMediaUploadForm(uploadPayload, file) {
 }
 
 async function putApiMediaUpload(uploadUrl, file) {
-  const response = await fetch(uploadUrl, {
+  const response = await fetchWithTimeout(uploadUrl, {
     method: 'PUT',
     headers: { 'Content-Type': file.mimeType },
     body: file.buffer || readFileSync(file.filePath),
-  });
+  }, UPLOAD_HTTP_TIMEOUT_MS);
   if (!response.ok) {
     const err = new Error(`Failed to upload ${file.filename} (${response.status} ${response.statusText}).`);
     err.code = 'MEDIA_UPLOAD_FAILED';
@@ -5067,7 +5353,7 @@ function parseWorkflowSseChunk(raw) {
 async function streamApiWorkflowEvents(apiKey, workflowId) {
   const url = await buildSafeApiUrl(`/v1/creative-agent/workflows/${encodeURIComponent(workflowId)}/events/stream`);
 
-  const response = await fetch(url, {
+  const response = await fetchWithTimeout(url, {
     method: 'GET',
     headers: apiRequestHeaders(apiKey, { Accept: 'text/event-stream' })
   });
@@ -5487,7 +5773,7 @@ function applyPersonaAndVoiceReferences() {
 async function fetchMediaBuffer(pathOrUrl) {
   if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
     await assertSafeUrl(pathOrUrl);
-    const response = await fetch(pathOrUrl);
+    const response = await fetchWithTimeout(pathOrUrl);
     if (!response.ok) {
       const err = new Error(`Failed to fetch media (${response.status} ${response.statusText})`);
       err.code = 'FETCH_FAILED';
@@ -5510,7 +5796,7 @@ async function fetchMediaBuffer(pathOrUrl) {
 async function fetchMediaBlob(pathOrUrl, fallbackMimeType = 'application/octet-stream') {
   if (pathOrUrl.startsWith('http://') || pathOrUrl.startsWith('https://')) {
     await assertSafeUrl(pathOrUrl);
-    const response = await fetch(pathOrUrl);
+    const response = await fetchWithTimeout(pathOrUrl);
     if (!response.ok) {
       const err = new Error(`Failed to fetch media (${response.status} ${response.statusText})`);
       err.code = 'FETCH_FAILED';
@@ -5968,13 +6254,41 @@ function resolveMultiAngleOutputConfig(outputPath, outputFormat) {
   return { dir, prefix, ext: ext.replace('.', '') || desiredExt };
 }
 
+// Write a generated result to disk, mapping common filesystem errors into
+// clear, coded messages. Losing a paid-for render to a raw "EACCES" is exactly
+// the kind of cryptic failure a first-time user can't recover from.
+function writeOutputFileSafe(filePath, buffer, label = 'output') {
+  try {
+    const dir = dirname(filePath);
+    if (dir && dir !== '.' && !existsSync(dir)) mkdirSync(dir, { recursive: true });
+    writeFileSync(filePath, buffer);
+  } catch (e) {
+    const code = e?.code;
+    const err = new Error(`Could not write ${label} to ${filePath}.`);
+    err.code = 'OUTPUT_WRITE_FAILED';
+    if (code === 'EACCES' || code === 'EPERM' || code === 'EROFS') {
+      err.hint = 'The output path is not writable. Choose a different --output location or fix the directory permissions.';
+    } else if (code === 'ENOSPC') {
+      err.hint = 'No space left on the device. Free up disk space or choose another --output location.';
+    } else if (code === 'ENOENT') {
+      err.hint = 'The output directory does not exist and could not be created. Check the --output path.';
+    } else if (code === 'EISDIR') {
+      err.hint = '--output points to a directory; pass a file path instead.';
+    } else {
+      err.hint = 'Check the --output path and permissions.';
+    }
+    err.details = { filePath, cause: code || String(e) };
+    throw err;
+  }
+}
+
 async function downloadUrlToFile(url, filePath) {
-  const response = await fetch(url);
+  const response = await fetchWithTimeout(url);
   if (!response.ok) {
     throw new Error(`Failed to download image: ${response.statusText}`);
   }
   const buffer = Buffer.from(await response.arrayBuffer());
-  writeFileSync(filePath, buffer);
+  writeOutputFileSafe(filePath, buffer);
 }
 
 function removeClientListener(client, event, handler) {
@@ -5993,14 +6307,14 @@ async function loadExeca() {
   return execaPromise;
 }
 
-async function ensureFfmpegAvailable() {
+async function ensureFfmpegAvailable(operation = 'this audio/video operation') {
   const ffmpegPath = getEnv('FFMPEG_PATH') || 'ffmpeg';
   sanitizePath(ffmpegPath, 'FFMPEG_PATH');
   const result = await runCommand(ffmpegPath, ['-version'], { captureOutput: true });
   if (result.error || result.status !== 0) {
-    const err = new Error('ffmpeg is required to assemble the 360 video.');
+    const err = new Error(`ffmpeg is required for ${operation}.`);
     err.code = 'MISSING_FFMPEG';
-    err.hint = 'Install ffmpeg or set FFMPEG_PATH to a working ffmpeg binary.';
+    err.hint = 'Install ffmpeg (e.g. `brew install ffmpeg` / `apt install ffmpeg`) or set FFMPEG_PATH to a working ffmpeg binary.';
     err.details = { ffmpegPath };
     throw err;
   }
@@ -6016,15 +6330,22 @@ async function ensureFfmpegAvailable() {
   return ffmpegPath;
 }
 
+// ffmpeg's concat demuxer resolves relative `file` entries against the list
+// file's own directory, so always write absolute paths to avoid path doubling
+// (e.g. ./dir/out.concat.txt referencing ./dir/clip.mp4 -> ./dir/./dir/clip.mp4).
+function escapeConcatPath(p) {
+  return resolve(p).replace(/'/g, "'\\''");
+}
+
 function writeConcatList(filePath, frames, frameDuration) {
   const lines = [];
   frames.forEach((frame) => {
-    lines.push(`file '${frame.replace(/'/g, "'\\''")}'`);
+    lines.push(`file '${escapeConcatPath(frame)}'`);
     lines.push(`duration ${frameDuration}`);
   });
   if (frames.length > 0) {
     const last = frames[frames.length - 1];
-    lines.push(`file '${last.replace(/'/g, "'\\''")}'`);
+    lines.push(`file '${escapeConcatPath(last)}'`);
   }
   writeFileSync(filePath, lines.join('\n'));
 }
@@ -6100,23 +6421,8 @@ async function buildAngles360Video(outputPath, frames, fps) {
   }
 }
 
-async function extractLastFrameFromVideo(videoPath, outputImagePath) {
-  sanitizePath(videoPath, 'video path');
-  sanitizePath(outputImagePath, 'output image path');
+async function runFrameExtraction(args, { videoPath, outputImagePath, which }) {
   const ffmpegPath = await ensureFfmpegAvailable();
-
-  // Extract the last frame by reading through the video with update mode
-  // This processes all frames but only keeps the last one
-  const args = [
-    '-i', videoPath,
-    '-vf', 'select=gte(n\\,0)',  // Select all frames (just pass-through)
-    '-vsync', '0',
-    '-update', '1',  // Update same output file (keeps only last frame)
-    '-q:v', '1',  // Best quality
-    '-y',
-    outputImagePath
-  ];
-
   const result = await runCommand(ffmpegPath, args, { captureOutput: true });
 
   if (result.error || result.status !== 0 || !isNonEmptyFile(outputImagePath)) {
@@ -6134,43 +6440,167 @@ async function extractLastFrameFromVideo(videoPath, outputImagePath) {
       console.error('  Output file size:', statSync(outputImagePath).size);
     }
 
-    const err = new Error('Failed to extract last frame from video.');
+    const err = new Error(`Failed to extract ${which} frame from video.`);
     err.code = 'FFMPEG_EXTRACT_FAILED';
     err.details = { videoPath, outputImagePath, stderr, stdout, status: result.status };
     throw err;
   }
 }
 
-async function buildConcatVideoFromClips(outputPath, clips, { audioPath = null, audioStart = null } = {}) {
+async function extractLastFrameFromVideo(videoPath, outputImagePath) {
+  sanitizePath(videoPath, 'video path');
+  sanitizePath(outputImagePath, 'output image path');
+
+  // Seek to ~1s before the end so we only decode the tail of the video
+  // (vastly faster than decoding every frame), then keep updating the same
+  // output so the final write is the genuine last frame.
+  const args = [
+    '-sseof', '-1',
+    '-i', videoPath,
+    '-update', '1',  // Keep overwriting -> output is the last decoded frame
+    '-q:v', '1',  // Best quality
+    '-y',
+    outputImagePath
+  ];
+
+  await runFrameExtraction(args, { videoPath, outputImagePath, which: 'last' });
+}
+
+async function extractFirstFrameFromVideo(videoPath, outputImagePath) {
+  sanitizePath(videoPath, 'video path');
+  sanitizePath(outputImagePath, 'output image path');
+
+  // First decoded frame only.
+  const args = [
+    '-i', videoPath,
+    '-frames:v', '1',
+    '-q:v', '1',  // Best quality
+    '-y',
+    outputImagePath
+  ];
+
+  await runFrameExtraction(args, { videoPath, outputImagePath, which: 'first' });
+}
+
+function parseFrameRate(raw) {
+  if (typeof raw === 'number') return Number.isFinite(raw) && raw > 0 ? raw : null;
+  if (typeof raw !== 'string') return null;
+  if (!raw.includes('/')) {
+    const n = Number(raw);
+    return Number.isFinite(n) && n > 0 ? n : null;
+  }
+  const [num, den] = raw.split('/').map(Number);
+  if (!Number.isFinite(num) || !Number.isFinite(den) || den === 0) return null;
+  const v = num / den;
+  return Number.isFinite(v) && v > 0 ? v : null;
+}
+
+// Probe a media file's primary video stream + whether it has any audio.
+// Returns { width, height, fps, duration, hasAudio }. Fields are null when the
+// probe fails (e.g. ffprobe missing); callers fall back to safe defaults.
+async function probeVideoStreamInfo(filePath) {
+  const info = { width: null, height: null, fps: null, duration: null, hasAudio: false };
+  const ffprobePath = getEnv('FFPROBE_PATH') || 'ffprobe';
+  sanitizePath(ffprobePath, 'FFPROBE_PATH');
+  const result = await runCommand(ffprobePath, [
+    '-v', 'error',
+    '-show_entries', 'stream=codec_type,width,height,avg_frame_rate,r_frame_rate',
+    '-show_entries', 'format=duration',
+    '-of', 'json',
+    filePath,
+  ], { captureOutput: true });
+  if (result.error || result.status !== 0) return info;
+  let parsed;
+  try { parsed = JSON.parse(result.stdout || '{}'); } catch { return info; }
+  const streams = Array.isArray(parsed.streams) ? parsed.streams : [];
+  const video = streams.find((s) => s.codec_type === 'video');
+  info.hasAudio = streams.some((s) => s.codec_type === 'audio');
+  if (video) {
+    info.width = Number(video.width) || null;
+    info.height = Number(video.height) || null;
+    info.fps = parseFrameRate(video.avg_frame_rate) || parseFrameRate(video.r_frame_rate) || null;
+  }
+  const dur = Number(parsed?.format?.duration);
+  info.duration = Number.isFinite(dur) && dur > 0 ? dur : null;
+  return info;
+}
+
+// Concatenate clips using the concat *filter* (not the concat demuxer). The
+// demuxer corrupts timestamps when clips differ in fps/timebase and desyncs
+// audio when a clip has no audio track. Here we probe each clip, normalize every
+// video stream to a common fps/size/sar/pixel-format, and synthesize silent
+// audio for clips that have none, so heterogeneous clips stitch cleanly.
+async function buildConcatVideoFromClips(outputPath, clips, { audioPath = null, audioStart = null, targetFps = null } = {}) {
   sanitizePath(outputPath, '--output path');
   clips.forEach((c, i) => sanitizePath(c, `clip[${i}]`));
   if (audioPath) sanitizePath(audioPath, '--concat-audio');
   const ffmpegPath = await ensureFfmpegAvailable();
-  const tempListPath = outputPath.replace(/\.mp4$/i, '') + '.concat.txt';
-  const lines = clips.map((clip) => `file '${clip.replace(/'/g, "'\\''")}'`);
-  writeFileSync(tempListPath, lines.join('\n'));
 
-  const args = [
-    '-y',
-    '-f', 'concat',
-    '-safe', '0',
-    '-i', tempListPath,
-  ];
+  const infos = [];
+  for (const clip of clips) {
+    infos.push(await probeVideoStreamInfo(clip));
+  }
+  const widths = infos.map((x) => x.width).filter(Boolean);
+  const heights = infos.map((x) => x.height).filter(Boolean);
+  const fpsList = infos.map((x) => x.fps).filter(Boolean);
+  const targetW = widths.length ? widths[0] : 1280;
+  const targetH = heights.length ? heights[0] : 720;
+  let fps = Number.isFinite(targetFps) && targetFps > 0
+    ? targetFps
+    : (fpsList.length ? Math.max(...fpsList) : 24);
+  fps = Math.max(1, Math.round(fps));
+  const totalDuration = infos.reduce((sum, x) => sum + (x.duration || 0), 0);
+
+  const filterParts = [];
+  const concatInputs = [];
+  infos.forEach((info, idx) => {
+    filterParts.push(
+      `[${idx}:v]fps=${fps},scale=${targetW}:${targetH}:force_original_aspect_ratio=decrease,` +
+      `pad=${targetW}:${targetH}:(ow-iw)/2:(oh-ih)/2,setsar=1,format=yuv420p[v${idx}]`
+    );
+    if (info.hasAudio) {
+      filterParts.push(`[${idx}:a]aresample=async=1:first_pts=0,aformat=sample_rates=44100:channel_layouts=stereo[a${idx}]`);
+    } else {
+      const dur = info.duration && info.duration > 0 ? info.duration : (1 / fps);
+      filterParts.push(`anullsrc=channel_layout=stereo:sample_rate=44100,atrim=duration=${dur.toFixed(6)},asetpts=PTS-STARTPTS[a${idx}]`);
+    }
+    concatInputs.push(`[v${idx}][a${idx}]`);
+  });
+  filterParts.push(`${concatInputs.join('')}concat=n=${infos.length}:v=1:a=1[cv][ca]`);
+
+  const args = ['-y'];
+  clips.forEach((clip) => { args.push('-i', clip); });
+
+  let mapAudio = '[ca]';
   if (audioPath) {
+    // External soundtrack replaces the stitched audio. Pad/trim it to the video
+    // length so we never silently truncate the video (the old -shortest footgun).
     if (Number.isFinite(audioStart) && audioStart > 0) {
       args.push('-ss', String(audioStart));
     }
-    args.push('-i', audioPath, '-map', '0:v:0', '-map', '1:a:0');
+    args.push('-i', audioPath);
+    const extIdx = clips.length;
+    let extChain = `[${extIdx}:a]aformat=sample_rates=44100:channel_layouts=stereo,apad`;
+    if (totalDuration > 0) {
+      extChain += `,atrim=duration=${totalDuration.toFixed(6)},asetpts=PTS-STARTPTS`;
+    }
+    extChain += '[xa]';
+    filterParts.push(extChain);
+    mapAudio = '[xa]';
   }
+
+  args.push('-filter_complex', filterParts.join(';'));
+  args.push('-map', '[cv]', '-map', mapAudio);
   args.push(
     '-c:v', 'libx264',
+    '-crf', '18',
+    '-preset', 'medium',
     '-pix_fmt', 'yuv420p',
     '-c:a', 'aac',
     '-b:a', '192k',
-    '-movflags', '+faststart'
+    '-movflags', '+faststart',
+    outputPath
   );
-  if (audioPath) args.push('-shortest');
-  args.push(outputPath);
 
   const result = await runCommand(ffmpegPath, args);
   if (result.error || result.status !== 0) {
@@ -6178,13 +6608,108 @@ async function buildConcatVideoFromClips(outputPath, clips, { audioPath = null,
       console.warn('Warning: ffmpeg exited non-zero, but output video exists and is non-empty. Continuing.');
       return;
     }
-    const err = new Error('ffmpeg failed to concatenate 360 video clips.');
+    const err = new Error('ffmpeg failed to concatenate video clips.');
     err.code = 'FFMPEG_FAILED';
     err.details = { outputPath, clips: clips?.length ?? null };
     throw err;
   }
 }
 
+// Rebuild a video's audio track without re-encoding the video stream. Supports
+// an optional looping bed (the input's own audio by default, or --bed-audio),
+// fade in/out, and overlaying one extra track at an offset/gain. The video is
+// stream-copied, so this is cheap and lossless on the picture.
+async function remixVideoAudio(inputVideo, outputVideo, opts = {}) {
+  const {
+    bedAudio = null, loop = false, fadeIn = null, fadeOut = null,
+    mixAudio = null, mixAt = null, mixGain = null,
+  } = opts;
+  sanitizePath(inputVideo, '--remix-audio input');
+  sanitizePath(outputVideo, '--remix-audio output');
+  if (bedAudio) sanitizePath(bedAudio, '--bed-audio');
+  if (mixAudio) sanitizePath(mixAudio, '--mix-audio');
+  const ffmpegPath = await ensureFfmpegAvailable();
+
+  const info = await probeVideoStreamInfo(inputVideo);
+  const totalDuration = info.duration && info.duration > 0 ? info.duration : null;
+
+  const args = ['-y', '-i', inputVideo];
+
+  // Resolve the bed source. With --audio-loop we re-open the source as a
+  // -stream_loop input (the only robust, duration-based loop in ffmpeg).
+  let bedRef;
+  let nextIndex = 1;
+  const bedSourceFile = bedAudio || inputVideo;
+  if (loop) {
+    args.push('-stream_loop', '-1', '-i', bedSourceFile);
+    bedRef = `[${nextIndex}:a]`;
+    nextIndex += 1;
+  } else if (bedAudio) {
+    args.push('-i', bedAudio);
+    bedRef = `[${nextIndex}:a]`;
+    nextIndex += 1;
+  } else {
+    bedRef = '[0:a]';
+  }
+
+  let mixIndex = null;
+  if (mixAudio) {
+    mixIndex = nextIndex;
+    args.push('-i', mixAudio);
+    nextIndex += 1;
+  }
+
+  const filterParts = [];
+  let bed = `${bedRef}aformat=sample_rates=44100:channel_layouts=stereo`;
+  if (loop && totalDuration) {
+    bed += `,atrim=duration=${totalDuration.toFixed(6)},asetpts=PTS-STARTPTS`;
+  }
+  if (Number.isFinite(fadeIn) && fadeIn > 0) {
+    bed += `,afade=t=in:st=0:d=${fadeIn}`;
+  }
+  if (Number.isFinite(fadeOut) && fadeOut > 0 && totalDuration) {
+    const st = Math.max(0, totalDuration - fadeOut);
+    bed += `,afade=t=out:st=${st.toFixed(6)}:d=${fadeOut}`;
+  }
+  bed += '[bed]';
+  filterParts.push(bed);
+
+  let finalAudio = '[bed]';
+  if (mixAudio) {
+    let mix = `[${mixIndex}:a]aformat=sample_rates=44100:channel_layouts=stereo`;
+    if (Number.isFinite(mixGain) && mixGain !== 0) {
+      mix += `,volume=${mixGain}dB`;
+    }
+    const delayMs = Number.isFinite(mixAt) && mixAt > 0 ? Math.round(mixAt * 1000) : 0;
+    if (delayMs > 0) {
+      mix += `,adelay=${delayMs}|${delayMs}`;
+    }
+    mix += '[mix]';
+    filterParts.push(mix);
+    // normalize=0 keeps both tracks at full level; alimiter guards against clipping.
+    filterParts.push('[bed][mix]amix=inputs=2:duration=longest:normalize=0,alimiter=limit=0.95[outa]');
+    finalAudio = '[outa]';
+  }
+
+  args.push('-filter_complex', filterParts.join(';'));
+  args.push('-map', '0:v:0', '-map', finalAudio);
+  args.push('-c:v', 'copy', '-c:a', 'aac', '-b:a', '192k', '-movflags', '+faststart');
+  if (totalDuration) args.push('-t', totalDuration.toFixed(6));
+  args.push(outputVideo);
+
+  const result = await runCommand(ffmpegPath, args);
+  if (result.error || result.status !== 0) {
+    if (isNonEmptyFile(outputVideo)) {
+      console.warn('Warning: ffmpeg exited non-zero, but output video exists and is non-empty. Continuing.');
+      return;
+    }
+    const err = new Error('ffmpeg failed to remix audio.');
+    err.code = 'FFMPEG_FAILED';
+    err.details = { inputVideo, outputVideo };
+    throw err;
+  }
+}
+
 async function runImageEditProjectWithEvents(client, editConfig, expectedCount, log, timeoutMs, label) {
   const results = [];
   let completed = 0;
@@ -6243,7 +6768,7 @@ async function runImageEditProjectWithEvents(client, editConfig, expectedCount,
     // Check for errors in the response (e.g., insufficient tokens)
     if (projectResult?.error || projectResult?.message) {
       cleanup();
-      throw new Error(projectResult.error || projectResult.message);
+      throw buildProjectResultError(projectResult);
     }
     if (!projectId) {
       cleanup();
@@ -6542,7 +7067,7 @@ async function runMultiAngleFlow(client, log) {
 
       // Check for errors in the response (e.g., insufficient tokens)
       if (clipResult?.error || clipResult?.message) {
-        throw new Error(clipResult.error || clipResult.message);
+        throw buildProjectResultError(clipResult);
       }
 
       const clipUrl = clipResult?.videoUrls?.[0];
@@ -6896,6 +7421,28 @@ async function main() {
       return;
     }
 
+    if (options.extractFirstFrame) {
+      const videoPath = sanitizePath(options.extractFirstFrame, '--extract-first-frame video');
+      const outputPath = sanitizePath(options.extractFirstFrameOutput, '--extract-first-frame output');
+      if (!existsSync(videoPath)) {
+        const err = new Error(`Video file not found: ${videoPath}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      await extractFirstFrameFromVideo(videoPath, outputPath);
+      if (options.json || JSON_ERROR_MODE) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'extract-first-frame',
+          outputPath,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(`Extracted first frame to: ${outputPath}`);
+      }
+      return;
+    }
+
     if (options.concatVideos) {
       const outputPath = sanitizePath(options.concatVideos, '--concat-videos output');
       const clips = options.concatVideosClips.map((c, i) => sanitizePath(c, `clip[${i}]`));
@@ -6914,7 +7461,8 @@ async function main() {
       }
       await buildConcatVideoFromClips(outputPath, clips, {
         audioPath: concatAudio,
-        audioStart: options.concatAudioStart
+        audioStart: options.concatAudioStart,
+        targetFps: options.concatFps
       });
       if (options.json || JSON_ERROR_MODE) {
         console.log(JSON.stringify({
@@ -6924,6 +7472,7 @@ async function main() {
           clipCount: clips.length,
           audioPath: concatAudio || null,
           audioStart: options.concatAudioStart ?? null,
+          targetFps: options.concatFps ?? null,
           timestamp: new Date().toISOString()
         }));
       } else {
@@ -6932,6 +7481,55 @@ async function main() {
       return;
     }
 
+    if (options.remixAudio) {
+      const inputVideo = sanitizePath(options.remixAudio, '--remix-audio input');
+      const outputVideo = sanitizePath(options.remixAudioOutput, '--remix-audio output');
+      const bedAudio = options.bedAudio ? sanitizePath(options.bedAudio, '--bed-audio') : null;
+      const mixAudio = options.mixAudio ? sanitizePath(options.mixAudio, '--mix-audio') : null;
+      if (!existsSync(inputVideo)) {
+        const err = new Error(`Video file not found: ${inputVideo}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      if (bedAudio && !existsSync(bedAudio)) {
+        const err = new Error(`Bed audio file not found: ${bedAudio}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      if (mixAudio && !existsSync(mixAudio)) {
+        const err = new Error(`Mix audio file not found: ${mixAudio}`);
+        err.code = 'FILE_NOT_FOUND';
+        throw err;
+      }
+      await remixVideoAudio(inputVideo, outputVideo, {
+        bedAudio,
+        loop: options.audioLoop,
+        fadeIn: options.audioFadeIn,
+        fadeOut: options.audioFadeOut,
+        mixAudio,
+        mixAt: options.mixAt,
+        mixGain: options.mixGain
+      });
+      if (options.json || JSON_ERROR_MODE) {
+        console.log(JSON.stringify({
+          success: true,
+          type: 'remix-audio',
+          outputPath: outputVideo,
+          bedAudio: bedAudio || null,
+          loop: Boolean(options.audioLoop),
+          fadeIn: options.audioFadeIn ?? null,
+          fadeOut: options.audioFadeOut ?? null,
+          mixAudio: mixAudio || null,
+          mixAt: options.mixAt ?? null,
+          mixGain: options.mixGain ?? null,
+          timestamp: new Date().toISOString()
+        }));
+      } else {
+        console.log(`Remixed audio to: ${outputVideo}`);
+      }
+      return;
+    }
+
     if (options.listMedia) {
       const mediaType = options.listMedia;
       const baseDir = MEDIA_INBOUND_DIR;
@@ -7007,7 +7605,7 @@ async function main() {
       authType: 'apiKey'
     });
 
-    await client.connect();
+    await connectSogniClient(client);
     await disableLiveModelAvailabilityEvents(client);
     log('Connected.');
 
@@ -7430,7 +8028,7 @@ async function main() {
 
       // Check for errors in the response (e.g., insufficient tokens)
       if (videoResult?.error || videoResult?.message) {
-        throw new Error(videoResult.error || videoResult.message);
+        throw buildProjectResultError(videoResult);
       }
     } else if (options.music) {
       log(`Generating music with ${options.model}...`);
@@ -7491,7 +8089,7 @@ async function main() {
       const audioResult = await client.createAudioProject(projectConfig);
 
       if (audioResult?.error || audioResult?.message) {
-        throw new Error(audioResult.error || audioResult.message);
+        throw buildProjectResultError(audioResult);
       }
     } else if (options.contextImages.length > 0) {
       // Image editing with context images
@@ -7550,10 +8148,11 @@ async function main() {
         editConfig.seed = options.seed;
       }
       
-      if (isGptImage2ModelSelection(options.model)) {
-        await client.createImageProject(editConfig);
-      } else {
-        await client.createImageEditProject(editConfig);
+      const editResult = isGptImage2ModelSelection(options.model)
+        ? await client.createImageProject(editConfig)
+        : await client.createImageEditProject(editConfig);
+      if (editResult?.error || editResult?.message) {
+        throw buildProjectResultError(editResult);
       }
     } else if (options.photobooth) {
       // Photobooth: face transfer with InstantID ControlNet
@@ -7600,7 +8199,7 @@ async function main() {
 
       // Check for errors in the response (e.g., insufficient tokens)
       if (projectResult?.error || projectResult?.message) {
-        throw new Error(projectResult.error || projectResult.message);
+        throw buildProjectResultError(projectResult);
       }
     } else {
       // Standard image generation
@@ -7665,7 +8264,10 @@ async function main() {
           projectConfig.seed = options.seed;
         }
 
-        await client.createImageProject(projectConfig);
+        const imageResult = await client.createImageProject(projectConfig);
+        if (imageResult?.error || imageResult?.message) {
+          throw buildProjectResultError(imageResult);
+        }
       }
     }
     
@@ -7774,7 +8376,7 @@ async function main() {
       
       // Save to file if requested
       if (options.output && urls[0]) {
-        const response = await fetch(urls[0]);
+        const response = await fetchWithTimeout(urls[0]);
         const buffer = Buffer.from(await response.arrayBuffer());
 
         const dir = dirname(options.output);
@@ -7832,7 +8434,7 @@ async function main() {
             apiKey: creds.SOGNI_API_KEY,
             authType: 'apiKey'
           });
-          await client2.connect();
+          await connectSogniClient(client2);
           await disableLiveModelAvailabilityEvents(client2);
 
           // Create second clip and wait for completion via events
@@ -7851,7 +8453,7 @@ async function main() {
                 }
 
                 // Download second clip
-                const response2 = await fetch(clip2Url);
+                const response2 = await fetchWithTimeout(clip2Url);
                 const buffer2 = Buffer.from(await response2.arrayBuffer());
                 writeFileSync(clip2Path, buffer2);
 
@@ -7885,7 +8487,7 @@ async function main() {
 
           // Check for errors in the response (e.g., insufficient tokens)
           if (clip2Result?.error || clip2Result?.message) {
-            throw new Error(clip2Result.error || clip2Result.message);
+            throw buildProjectResultError(clip2Result);
           }
 
           await clip2Promise;
@@ -7894,7 +8496,7 @@ async function main() {
           await buildConcatVideoFromClips(options.output, [clip1Path, clip2Path]);
           log(`Saved looping video to ${options.output}`);
         } else {
-          writeFileSync(options.output, buffer);
+          writeOutputFileSafe(options.output, buffer, options.video ? 'video' : options.music ? 'audio' : 'image');
           log(`Saved to ${options.output}`);
         }
       }
@@ -8030,6 +8632,11 @@ async function main() {
       return main();
     }
 
+    if (isInvalidApiKeyError(error)) {
+      if (!error.hint) error.hint = INVALID_API_KEY_HINT;
+      if (!error.code) error.code = 'INVALID_API_KEY';
+    }
+
     exitCode = 1;
     const shouldJson = options.json || IS_OPENCLAW_INVOCATION;
     if (shouldJson) {
@@ -8040,7 +8647,10 @@ async function main() {
       }, error);
       if (error.code) payload.errorCode = error.code;
       if (error.details) payload.errorDetails = error.details;
-      if (error.hint) payload.hint = error.hint;
+      // Don't let a stale per-error hint overwrite the canonical
+      // "Buy Spark Packs" hint that addCanonicalErrorFields already
+      // stamped via the insufficient_credits enrichment branch.
+      if (error.hint && !payload.purchaseAction) payload.hint = error.hint;
       payload.timestamp = new Date().toISOString();
       payload.node = process.versions.node;
       payload.cwd = process.cwd();
@@ -8091,8 +8701,5 @@ async function main() {
 
 main().then(
   () => process.exit(0),
-  (error) => {
-    console.error(`Error: ${error?.message || error}`);
-    process.exit(1);
-  }
+  (error) => reportFatalError(error)
 );