@clipit-ai/cli 0.2.4 → 0.2.6

package/bin/clipit.mjs

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { createHash, randomBytes } from 'node:crypto';
+import { createHash, randomBytes, randomUUID } from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { createReadStream } from 'node:fs';
 import { Transform } from 'node:stream';
@@ -9,7 +9,7 @@ import path from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
 
-const VERSION = '0.2.4';
+const VERSION = '0.2.6';
 const DEFAULT_BASE_URL = 'https://clipit.dev';
 const DEFAULT_SCOPES = [
   'clippy_agent',
@@ -23,6 +23,7 @@ const DEFAULT_SCOPES = [
   'broll_generation',
   'audio_generation',
   'video_alteration',
+  'social_publishing',
 ];
 
 const GET_RETRY_DELAYS_MS = [500, 2000];
@@ -31,7 +32,24 @@ const RETRYABLE_GET_STATUSES = new Set([429, 502, 503, 504]);
 const RECENT_LIMIT = 20;
 const REMOTION_ESTIMATED_USD_PER_VIDEO_SECOND = 0.0015;
 const BYTES_PER_GB = 1024 * 1024 * 1024;
-const DIRECT_VIDEO_UPLOAD_MAX_BYTES = readPositiveIntegerEnv('CLIPIT_CLI_DIRECT_UPLOAD_MAX_BYTES', 100 * 1024 * 1024);
+const VIDEO_UPLOAD_PART_CONCURRENCY = readPositiveIntegerEnv('CLIPIT_CLI_UPLOAD_CONCURRENCY', 4, 100);
+const VIDEO_UPLOAD_PART_ATTEMPTS = 3;
+const VIDEO_UPLOAD_PART_SIGN_BATCH = 100;
+const VIDEO_UPLOAD_STALL_TIMEOUT_MS = readPositiveIntegerEnv(
+  'CLIPIT_CLI_UPLOAD_STALL_TIMEOUT_MS',
+  60_000,
+  10 * 60_000,
+);
+const VIDEO_UPLOAD_RETRY_BASE_MS = readPositiveIntegerEnv(
+  'CLIPIT_CLI_UPLOAD_RETRY_BASE_MS',
+  1_000,
+  10_000,
+);
+const API_REQUEST_TIMEOUT_MS = readPositiveIntegerEnv(
+  'CLIPIT_CLI_REQUEST_TIMEOUT_MS',
+  60_000,
+  5 * 60_000,
+);
 const MAX_CREDITS_ESTIMATE_MAP = Object.freeze({
   'exports start': [{ operationType: 'lambda_render', provider: 'aws_lambda', modelId: 'remotion-4.0', metrics: 'remotion-render' }],
   'thumbnails generate': [{ operationType: 'thumbnail_generation', provider: 'replicate', modelId: 'openai/gpt-image-2', metrics: 'one-generation' }],
@@ -202,9 +220,15 @@ const KNOWN_AGENT_TARGETS = ['codex', 'claude', 'hermes', 'generic'];
 const TRUSTED_HOSTS = new Set(['clipit.dev', 'www.clipit.dev', 'localhost', '127.0.0.1', '::1', '[::1]']);
 const AGENT_SKILL_META_FILENAME = 'SKILL.meta.json';
 
-function readPositiveIntegerEnv(name, fallback) {
+function readPositiveIntegerEnv(name, fallback, maximum = Number.MAX_SAFE_INTEGER) {
   const parsed = Number(process.env[name]);
-  return Number.isFinite(parsed) && parsed > 0 ? Math.floor(parsed) : fallback;
+  return Number.isFinite(parsed) && parsed > 0
+    ? Math.min(maximum, Math.max(1, Math.floor(parsed)))
+    : fallback;
+}
+
+function shellQuote(value) {
+  return `'${String(value).replace(/'/g, "'\"'\"'")}'`;
 }
 
 function configDir() {
@@ -239,6 +263,7 @@ function legacyProfile(config) {
     baseUrl: config.baseUrl,
     apiKey: config.apiKey,
     keyInfo: config.keyInfo,
+    scope: config.scope,
     loginSource: config.loginSource,
     activeContext: config.activeContext,
     recent: config.recent,
@@ -252,6 +277,14 @@ function profileData(config, options) {
   return name === 'default' ? { ...legacyProfile(config), ...fromProfiles } : fromProfiles;
 }
 
+function profileIsAuthoritative(config, options) {
+  return Boolean(
+    options.profile
+    || process.env.CLIPIT_PROFILE
+    || (config.currentProfile && config.currentProfile !== 'default'),
+  );
+}
+
 function updateProfile(config, options, updates) {
   const name = profileName(config, options);
   const profiles = { ...(config.profiles || {}) };
@@ -421,6 +454,7 @@ function usage() {
     '  clipit auth status [--json]',
     '  clipit auth set-key --stdin',
     '  clipit auth profiles',
+    '  clipit auth use <profile>',
     '  clipit context use [--video-id id] [--clip-id id] [--project-id id] [--sequence-id id]',
     '  clipit context show|clear|build [--json]',
     '  clipit skills list [--json]',
@@ -431,8 +465,8 @@ function usage() {
     '  clipit workflow approve <jobId> --approval-id id [--decision approved|cheaper|cancelled]',
     '  clipit mcp [stdio]',
     '  clipit run <functionName> [--params @file.json] [--clip-id id] [--video-id id] [--confirm] [--max-credits n]',
-    '  clipit videos list|get|upload|import-url|transcribe|transcript|suggest-clips|delete ...',
-    '  clipit clips list|get|create|update|render|download|delete ...',
+    '  clipit videos list|get|upload|abort-upload|import-url|transcribe|transcript|suggest-clips|delete ...',
+    '  clipit clips list|get|delivery-state|create|update|render|download|delete ...',
     '  clipit jobs get|wait <jobId>',
     '  clipit credits balance|usage|estimate ...',
     '  clipit billing capabilities|catalog|create-attempt|attempt|receipt|subscription ...',
@@ -451,12 +485,36 @@ function usage() {
 
 function getBaseUrl(config, options) {
   const profile = profileData(config, options);
-  return String(options['base-url'] || process.env.CLIPPER_BASE_URL || profile.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, '');
+  const selected = profileIsAuthoritative(config, options);
+  return String(
+    options['base-url']
+    || (selected ? profile.baseUrl : process.env.CLIPPER_BASE_URL)
+    || profile.baseUrl
+    || (!selected ? process.env.CLIPPER_BASE_URL : undefined)
+    || DEFAULT_BASE_URL,
+  ).replace(/\/+$/, '');
 }
 
-function getApiKey(config, options) {
+function resolveApiCredential(config, options) {
   const profile = profileData(config, options);
-  return process.env.CLIPPER_API_KEY || options['api-key'] || profile.apiKey || null;
+  if (typeof options['api-key'] === 'string' && options['api-key'].trim()) {
+    return { apiKey: options['api-key'].trim(), source: 'argument' };
+  }
+  if (profileIsAuthoritative(config, options)) {
+    return profile.apiKey
+      ? { apiKey: profile.apiKey, source: 'profile' }
+      : { apiKey: null, source: 'missing' };
+  }
+  if (process.env.CLIPPER_API_KEY) {
+    return { apiKey: process.env.CLIPPER_API_KEY, source: 'environment' };
+  }
+  return profile.apiKey
+    ? { apiKey: profile.apiKey, source: 'profile' }
+    : { apiKey: null, source: 'missing' };
+}
+
+function getApiKey(config, options) {
+  return resolveApiCredential(config, options).apiKey;
 }
 
 async function readStdin() {
@@ -465,6 +523,97 @@ async function readStdin() {
   return Buffer.concat(chunks).toString('utf8');
 }
 
+async function readSecretLine(input = process.stdin, promptOutput = process.stderr) {
+  if (!input.isTTY || typeof input.setRawMode !== 'function') {
+    return new Promise((resolve, reject) => {
+      let value = '';
+      let settled = false;
+      const cleanup = () => {
+        input.off('data', onData);
+        input.off('end', onEnd);
+        input.off('error', onError);
+      };
+      const finish = (result) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        input.pause?.();
+        resolve(result);
+      };
+      const onData = (chunk) => {
+        value += Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk);
+        const newline = value.search(/[\r\n]/);
+        if (newline !== -1) finish(value.slice(0, newline));
+      };
+      const onEnd = () => finish(value);
+      const onError = (error) => {
+        if (settled) return;
+        settled = true;
+        cleanup();
+        reject(error);
+      };
+      input.on('data', onData);
+      input.once('end', onEnd);
+      input.once('error', onError);
+      input.resume?.();
+    });
+  }
+
+  return new Promise((resolve, reject) => {
+    let value = '';
+    let settled = false;
+    const wasRaw = Boolean(input.isRaw);
+    const wasPaused = input.isPaused?.() ?? false;
+    const cleanup = () => {
+      input.off('data', onData);
+      input.off('end', onEnd);
+      input.off('error', onError);
+      input.setRawMode(wasRaw);
+      if (wasPaused) input.pause?.();
+      promptOutput.write('\n');
+    };
+    const finish = () => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      resolve(value);
+    };
+    const onData = (chunk) => {
+      for (const character of (Buffer.isBuffer(chunk) ? chunk.toString('utf8') : String(chunk))) {
+        if (character === '\u0003') {
+          if (settled) return;
+          settled = true;
+          cleanup();
+          reject(Object.assign(new Error('API key entry cancelled.'), { exitCode: 130 }));
+          return;
+        }
+        if (character === '\r' || character === '\n' || character === '\u0004') {
+          finish();
+          return;
+        }
+        if (character === '\u007f' || character === '\b') {
+          value = value.slice(0, -1);
+          continue;
+        }
+        if (character >= ' ') value += character;
+      }
+    };
+    const onEnd = () => finish();
+    const onError = (error) => {
+      if (settled) return;
+      settled = true;
+      cleanup();
+      reject(error);
+    };
+    promptOutput.write('API key: ');
+    input.setRawMode(true);
+    input.on('data', onData);
+    input.once('end', onEnd);
+    input.once('error', onError);
+    input.resume?.();
+  });
+}
+
 function boolOption(value) {
   return value === true || value === 'true' || value === '1' || value === 'yes';
 }
@@ -581,39 +730,67 @@ async function apiFetch(config, options, method, endpoint, body, extra = {}) {
   };
   const isFormData = typeof FormData !== 'undefined' && body instanceof FormData;
   if (body !== undefined && !isFormData && !extra.rawBody) headers['Content-Type'] = 'application/json';
-  const apiKey = extra.noAuth ? null : getApiKey(config, options);
+  const apiKey = extra.noAuth
+    ? null
+    : extra.authApiKey !== undefined
+      ? extra.authApiKey
+      : getApiKey(config, options);
   if (apiKey) headers.Authorization = `Bearer ${apiKey}`;
 
   let response;
+  let responseTimeout;
   for (let attempt = 0; attempt <= GET_RETRY_DELAYS_MS.length; attempt++) {
+    const controller = new AbortController();
+    const timeoutMs = Math.min(
+      readPositiveIntegerEnv('CLIPIT_CLI_REQUEST_TIMEOUT_MS', API_REQUEST_TIMEOUT_MS, 5 * 60_000),
+      5 * 60_000,
+    );
+    const timeout = setTimeout(() => {
+      controller.abort(new Error(`ClipIt API request timed out after ${timeoutMs} ms`));
+    }, timeoutMs);
+    timeout.unref?.();
     try {
       const request = {
         method: methodName,
         headers,
         body: body === undefined ? undefined : extra.rawBody ? body : isFormData ? body : JSON.stringify(body),
+        signal: controller.signal,
       };
       if (extra.rawBody && body !== undefined) {
         request.duplex = 'half';
       }
       response = await fetch(`${baseUrl}${endpoint}`, request);
     } catch (error) {
+      clearTimeout(timeout);
       if (canRetry && attempt < GET_RETRY_DELAYS_MS.length) {
         await sleep(GET_RETRY_DELAYS_MS[attempt]);
         continue;
       }
-      throw Object.assign(new Error(`Network error: ${error.message}`), { exitCode: EXIT.NETWORK });
+      const reason = controller.signal.aborted && controller.signal.reason instanceof Error
+        ? controller.signal.reason
+        : error;
+      throw Object.assign(new Error(`Network error: ${reason.message}`), { exitCode: EXIT.NETWORK });
     }
 
     if (canRetry && RETRYABLE_GET_STATUSES.has(response.status) && attempt < GET_RETRY_DELAYS_MS.length) {
       await response.arrayBuffer().catch(() => undefined);
+      clearTimeout(timeout);
       await sleep(retryDelayMs(response, attempt));
       continue;
     }
+    responseTimeout = timeout;
     break;
   }
 
   const requestId = response.headers.get('x-request-id') || response.headers.get('X-Request-Id') || undefined;
-  const text = await response.text();
+  let text;
+  try {
+    text = await response.text();
+  } catch (error) {
+    throw Object.assign(new Error(`Network error: ${error.message}`), { exitCode: EXIT.NETWORK });
+  } finally {
+    if (responseTimeout) clearTimeout(responseTimeout);
+  }
   let data = null;
   if (text.trim()) {
     try {
@@ -638,6 +815,13 @@ async function apiFetch(config, options, method, endpoint, body, extra = {}) {
       requestId,
     });
   }
+  if (extra.includeResponseMetadata) {
+    return {
+      data,
+      status: response.status,
+      headers: Object.fromEntries(response.headers.entries()),
+    };
+  }
   return data;
 }
 
@@ -813,15 +997,6 @@ async function fetchClipForEstimate(config, options, clipId) {
   return apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(clipId)}`);
 }
 
-function progressTransform(progress) {
-  return new Transform({
-    transform(chunk, encoding, callback) {
-      progress.track(chunk);
-      callback(null, chunk);
-    },
-  });
-}
-
 async function buildMaxCreditsEstimateRequest(config, options, spec, context = {}) {
   if (spec.metrics === 'url-import') {
     const youtube = isYoutubeUrl(requiredString(context.url, 'URL'));
@@ -1294,7 +1469,7 @@ async function setKey(config, options) {
   if (!options.stdin) {
     throw Object.assign(new Error('Use --stdin to avoid shell history leaks.'), { exitCode: EXIT.USAGE });
   }
-  const apiKey = (await readStdin()).trim();
+  const apiKey = (await readSecretLine()).trim();
   if (!apiKey) {
     throw Object.assign(new Error('No API key received on stdin.'), { exitCode: EXIT.USAGE });
   }
@@ -1303,17 +1478,50 @@ async function setKey(config, options) {
     apiKey,
     loginSource: 'manual',
   });
-  const me = await apiFetch(nextConfig, options, 'GET', '/api/v1/agent/me');
-  await writeConfig(updateProfile(nextConfig, options, { keyInfo: me.apiKey }));
-  output({ success: true, message: 'API key stored', profile: profileName(config, options), account: me.user, apiKey: me.apiKey }, options);
+  const me = await apiFetch(nextConfig, options, 'GET', '/api/v1/agent/me', undefined, { authApiKey: apiKey });
+  await writeConfig(updateProfile(nextConfig, options, { keyInfo: me.apiKey, scope: me.scope ?? null }));
+  output({
+    success: true,
+    message: 'API key stored',
+    profile: profileName(config, options),
+    account: me.user,
+    apiKey: me.apiKey,
+    scope: me.scope ?? null,
+  }, options);
 }
 
 async function logout(config, options) {
-  const next = removeProfileFields(config, options, ['apiKey', 'keyInfo', 'loginSource']);
+  const next = removeProfileFields(config, options, ['apiKey', 'keyInfo', 'scope', 'loginSource']);
   await writeConfig(next);
   output({ success: true, message: 'Local ClipIt CLI credentials removed', profile: profileName(config, options) }, options);
 }
 
+async function useProfile(config, options, requestedName) {
+  const name = String(requestedName || '').trim();
+  if (!name) {
+    throw Object.assign(new Error('Profile name is required.'), { exitCode: EXIT.USAGE });
+  }
+  if (process.env.CLIPIT_PROFILE && process.env.CLIPIT_PROFILE !== name) {
+    throw Object.assign(
+      new Error(`CLIPIT_PROFILE is set to ${process.env.CLIPIT_PROFILE}; unset it or select that profile explicitly.`),
+      { exitCode: EXIT.USAGE },
+    );
+  }
+  const selectedOptions = { ...options, profile: name };
+  const profile = profileData(config, selectedOptions);
+  if (!profile.apiKey) {
+    throw Object.assign(new Error(`Profile ${name} does not have a stored credential.`), { exitCode: EXIT.AUTH });
+  }
+  const next = { ...config, currentProfile: name, updatedAt: new Date().toISOString() };
+  await writeConfig(next);
+  output({
+    success: true,
+    currentProfile: name,
+    keyName: profile.keyInfo?.keyName ?? null,
+    scope: profile.scope ?? null,
+  }, options);
+}
+
 async function listProfiles(config, options) {
   const profiles = config.profiles || {};
   const names = [...new Set(['default', ...Object.keys(profiles)])];
@@ -1329,6 +1537,7 @@ async function listProfiles(config, options) {
         hasCredential: Boolean(data.apiKey),
         loginSource: data.loginSource || null,
         keyName: data.keyInfo?.keyName || null,
+        scope: data.scope || null,
         updatedAt: data.updatedAt || null,
       };
     }),
@@ -1336,6 +1545,7 @@ async function listProfiles(config, options) {
 }
 
 async function doctor(config, options) {
+  const credential = resolveApiCredential(config, options);
   const checks = {
     version: VERSION,
     node: process.version,
@@ -1343,8 +1553,8 @@ async function doctor(config, options) {
     configPath: configPath(),
     profile: profileName(config, options),
     baseUrl: getBaseUrl(config, options),
-    hasCredential: Boolean(getApiKey(config, options)),
-    credentialSource: process.env.CLIPPER_API_KEY ? 'env' : getApiKey(config, options) ? 'config' : 'missing',
+    hasCredential: Boolean(credential.apiKey),
+    credentialSource: credential.source,
     auth: null,
   };
   try {
@@ -1650,11 +1860,33 @@ async function pollWorkflow(config, options, jobId) {
   }
 }
 
+function promptNamesNewSourceUrl(userMessage) {
+  const urls = userMessage.match(/https?:\/\/[^\s<>"'`]+/gi) || [];
+  if (urls.length !== 1) return false;
+  const messageWithoutUrls = userMessage
+    .replace(/https?:\/\/[^\s<>"'`]+/gi, ' ')
+    .replace(/[^a-z0-9]+/gi, ' ')
+    .trim()
+    .toLowerCase();
+  const isUrlOnly = messageWithoutUrls.length === 0;
+  const hasStrongSourceIntent = /\b(import|process|source|transcrib\w*|download|extract)\b/.test(messageWithoutUrls)
+    || /\b(clip|clips|video)\b.*\b(from|using|this|that)\b/.test(messageWithoutUrls)
+    || /\b(use|using)\b.*\b(link|url|source|video|this|that)\b/.test(messageWithoutUrls);
+  const isReferenceOnly = /\b(reference|inspiration|example|style)\b/.test(messageWithoutUrls)
+    && !/\b(import|process|source|transcrib\w*|clip|clips|extract)\b/.test(messageWithoutUrls);
+  return isUrlOnly || (hasStrongSourceIntent && !isReferenceOnly);
+}
+
 async function askWorkflow(config, options, promptParts) {
   const userMessage = promptParts.filter((part) => part !== undefined).join(' ').trim();
   if (!userMessage) throw Object.assign(new Error('Prompt is required.'), { exitCode: EXIT.USAGE });
 
   const context = await buildContext(config, options);
+  if (promptNamesNewSourceUrl(userMessage)) {
+    if (!options['video-id']) delete context.videoId;
+    if (!options['clip-id']) delete context.clipId;
+    if (!options['selected-clip-ids']) delete context.selectedClipIds;
+  }
   const payload = { userMessage };
   for (const field of ['videoId', 'clipId', 'projectId', 'sequenceId']) {
     if (context[field]) payload[field] = context[field];
@@ -1733,16 +1965,19 @@ function mimeForPath(filePath) {
   if (ext === '.webm') return 'video/webm';
   if (ext === '.mkv') return 'video/x-matroska';
   if (ext === '.m4v') return 'video/x-m4v';
+  if (ext === '.avi') return 'video/x-msvideo';
+  if (ext === '.wmv' || ext === '.asf') return 'video/x-ms-asf';
+  if (ext === '.flv') return 'video/x-flv';
+  if (ext === '.mpeg' || ext === '.mpg') return 'video/mpeg';
+  if (ext === '.ts' || ext === '.m2ts') return 'video/mp2t';
+  if (ext === '.mxf') return 'video/mxf';
+  if (ext === '.ogv') return 'video/ogg';
   if (ext === '.mp3') return 'audio/mpeg';
   if (ext === '.m4a') return 'audio/mp4';
   if (ext === '.wav') return 'audio/wav';
   return 'video/mp4';
 }
 
-function multipartFilename(value) {
-  return String(value).replace(/["\r\n]/g, '_');
-}
-
 function shouldReportUploadProgress(options) {
   return Boolean(process.stderr.isTTY) && !wantJson(options);
 }
@@ -1751,24 +1986,6 @@ function formatMb(bytes) {
   return (bytes / (1024 * 1024)).toFixed(1);
 }
 
-function assertDirectVideoUploadSize(filePath, sizeBytes) {
-  if (sizeBytes <= DIRECT_VIDEO_UPLOAD_MAX_BYTES) return;
-  throw Object.assign(
-    new Error(
-      `Video file is ${formatMb(sizeBytes)} MB, above the direct CLI upload limit of ${formatMb(DIRECT_VIDEO_UPLOAD_MAX_BYTES)} MB. ` +
-      'Use `clipit videos import-url` for URL sources or a server-side/resumable upload path; direct CLI upload is likely to fail with 413 before ClipIt can process it.',
-    ),
-    {
-      exitCode: EXIT.USAGE,
-      data: {
-        filePath,
-        sizeBytes,
-        maxBytes: DIRECT_VIDEO_UPLOAD_MAX_BYTES,
-      },
-    },
-  );
-}
-
 function createUploadProgress(options, totalBytes) {
   if (!shouldReportUploadProgress(options) || !Number.isFinite(totalBytes) || totalBytes <= 0) {
     return { track() {}, finish() {} };
@@ -1797,15 +2014,259 @@ function createUploadProgress(options, totalBytes) {
   };
 }
 
-async function* multipartFileBody(filePath, filename, contentType, boundary, progress) {
-  yield Buffer.from(
-    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${multipartFilename(filename)}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+const VIDEO_UPLOAD_RESUME_MAX_AGE_MS = 25 * 60 * 60 * 1000;
+
+function videoUploadResumeDirectory() {
+  return path.join(configDir(), 'video-upload-resumes');
+}
+
+function videoUploadResumePath(idempotencyKey) {
+  const digest = createHash('sha256').update(String(idempotencyKey)).digest('hex');
+  return path.join(videoUploadResumeDirectory(), `${digest}.json`);
+}
+
+async function readVideoUploadResumes() {
+  const resumes = {};
+  await fs.mkdir(videoUploadResumeDirectory(), { recursive: true, mode: 0o700 });
+  const files = await fs.readdir(videoUploadResumeDirectory()).catch(() => []);
+  for (const file of files) {
+    if (!file.endsWith('.json')) continue;
+    const recordPath = path.join(videoUploadResumeDirectory(), file);
+    try {
+      const value = JSON.parse(await fs.readFile(recordPath, 'utf8'));
+      const updatedAt = Date.parse(value?.updatedAt);
+      if (
+        !value
+        || typeof value !== 'object'
+        || Array.isArray(value)
+        || typeof value.idempotencyKey !== 'string'
+        || !Number.isFinite(updatedAt)
+        || Date.now() - updatedAt > VIDEO_UPLOAD_RESUME_MAX_AGE_MS
+      ) {
+        await fs.rm(recordPath, { force: true });
+        continue;
+      }
+      resumes[value.idempotencyKey] = value;
+    } catch {
+      await fs.rm(recordPath, { force: true }).catch(() => undefined);
+    }
+  }
+
+  const legacyPath = path.join(configDir(), 'video-upload-resume.json');
+  try {
+    const legacy = JSON.parse(await fs.readFile(legacyPath, 'utf8'));
+    if (legacy && typeof legacy === 'object' && !Array.isArray(legacy)) {
+      for (const [idempotencyKey, value] of Object.entries(legacy)) {
+        if (!value || typeof value !== 'object' || Array.isArray(value)) continue;
+        await saveVideoUploadResume(idempotencyKey, value);
+        resumes[idempotencyKey] = { ...value, idempotencyKey };
+      }
+    }
+    await fs.rm(legacyPath, { force: true });
+  } catch {}
+
+  return resumes;
+}
+
+async function saveVideoUploadResume(idempotencyKey, value) {
+  await fs.mkdir(videoUploadResumeDirectory(), { recursive: true, mode: 0o700 });
+  const destination = videoUploadResumePath(idempotencyKey);
+  const temporary = `${destination}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  await fs.writeFile(
+    temporary,
+    `${JSON.stringify({ ...value, idempotencyKey }, null, 2)}\n`,
+    { mode: 0o600 },
+  );
+  await fs.rename(temporary, destination);
+}
+
+async function removeVideoUploadResume(idempotencyKey) {
+  await fs.rm(videoUploadResumePath(idempotencyKey), { force: true });
+}
+
+async function removeVideoUploadResumeByIntent(intentId) {
+  const resumes = await readVideoUploadResumes();
+  await Promise.all(Object.entries(resumes).map(async ([key, value]) => {
+    if (value?.intentId === intentId) await removeVideoUploadResume(key);
+  }));
+}
+
+function defaultVideoUploadIdempotencyKey(resolved, stat, filename, contentType) {
+  const fingerprint = createHash('sha256').update(JSON.stringify({
+    path: resolved,
+    size: stat.size,
+    mtimeMs: stat.mtimeMs,
+    ctimeMs: stat.ctimeMs,
+    filename,
+    contentType,
+  })).digest('hex');
+  return `cli-video:${fingerprint}`;
+}
+
+function createMultipartUploadProgress(options, totalBytes, completedParts) {
+  if (!shouldReportUploadProgress(options) || totalBytes <= 0) {
+    return { updatePart() {}, completePart() {}, resetPart() {}, finish() {} };
+  }
+  const completed = new Map(completedParts.map((part) => [part.partNumber, part.sizeBytes]));
+  const inFlight = new Map();
+  let lastPrintedAt = 0;
+
+  const print = (force = false) => {
+    const now = Date.now();
+    if (!force && now - lastPrintedAt < 500) return;
+    lastPrintedAt = now;
+    const uploaded = Math.min(
+      totalBytes,
+      [...completed.values(), ...inFlight.values()].reduce((sum, value) => sum + value, 0),
+    );
+    const percent = Math.min(100, Math.round((uploaded / totalBytes) * 100));
+    process.stderr.write(`\ruploaded ${formatMb(uploaded)} / ${formatMb(totalBytes)} MB (${percent}%)`);
+  };
+
+  return {
+    updatePart(partNumber, bytes) {
+      inFlight.set(partNumber, bytes);
+      print(false);
+    },
+    completePart(partNumber, bytes) {
+      inFlight.delete(partNumber);
+      completed.set(partNumber, bytes);
+      print(false);
+    },
+    resetPart(partNumber) {
+      inFlight.delete(partNumber);
+      print(false);
+    },
+    finish() {
+      print(true);
+      process.stderr.write('\n');
+    },
+  };
+}
+
+function createUploadActivityWatchdog(controller, onTimeout) {
+  let timer;
+  const arm = () => {
+    if (timer) clearTimeout(timer);
+    timer = setTimeout(() => {
+      const error = Object.assign(
+        new Error(`Storage upload made no progress for ${VIDEO_UPLOAD_STALL_TIMEOUT_MS} ms`),
+        { code: 'UPLOAD_STALLED' },
+      );
+      controller.abort(error);
+      onTimeout?.();
+    }, VIDEO_UPLOAD_STALL_TIMEOUT_MS);
+    timer.unref?.();
+  };
+  arm();
+  return {
+    activity: arm,
+    stop() {
+      if (timer) clearTimeout(timer);
+      timer = undefined;
+    },
+  };
+}
+
+async function putSignedVideoPart(part, filePath, start, size, progress) {
+  for (let attempt = 0; attempt < VIDEO_UPLOAD_PART_ATTEMPTS; attempt += 1) {
+    let transferred = 0;
+    const controller = new AbortController();
+    let source;
+    let tracker;
+    const watchdog = createUploadActivityWatchdog(controller, () => {
+      source?.destroy();
+      tracker?.destroy();
+    });
+    tracker = new Transform({
+      transform(chunk, encoding, callback) {
+        transferred += Buffer.byteLength(chunk);
+        watchdog.activity();
+        progress.updatePart(part.partNumber, transferred);
+        callback(null, chunk);
+      },
+    });
+    try {
+      source = createReadStream(filePath, { start, end: start + size - 1 });
+      const response = await fetch(part.url, {
+        method: 'PUT',
+        headers: { 'Content-Length': String(size) },
+        body: source.pipe(tracker),
+        duplex: 'half',
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw new Error(`Part ${part.partNumber} failed: ${response.status} ${redact(text || response.statusText)}`);
+      }
+      progress.completePart(part.partNumber, size);
+      return;
+    } catch (error) {
+      progress.resetPart(part.partNumber);
+      const reason = controller.signal.aborted && controller.signal.reason instanceof Error
+        ? controller.signal.reason
+        : error;
+      if (attempt === VIDEO_UPLOAD_PART_ATTEMPTS - 1) throw reason;
+      await sleep(VIDEO_UPLOAD_RETRY_BASE_MS * (2 ** attempt));
+    } finally {
+      watchdog.stop();
+      source?.destroy();
+      tracker?.destroy();
+    }
+  }
+}
+
+async function uploadVideoMultipart(config, options, resolved, initialized, totalBytes) {
+  const status = await apiFetch(
+    config,
+    options,
+    'GET',
+    `/api/v1/videos/uploads/${encodeURIComponent(initialized.intentId)}`,
   );
-  for await (const chunk of createReadStream(filePath)) {
-    progress?.track(chunk);
-    yield chunk;
+  const uploadedParts = Array.isArray(status.uploadedParts) ? status.uploadedParts : [];
+  const uploadedNumbers = new Set(uploadedParts.map((part) => Number(part.partNumber)));
+  const missing = Array.from({ length: Number(initialized.partCount) }, (_, index) => index + 1)
+    .filter((partNumber) => !uploadedNumbers.has(partNumber));
+  const progress = createMultipartUploadProgress(options, totalBytes, uploadedParts);
+
+  try {
+    for (let offset = 0; offset < missing.length; offset += VIDEO_UPLOAD_PART_SIGN_BATCH) {
+      const partNumbers = missing.slice(offset, offset + VIDEO_UPLOAD_PART_SIGN_BATCH);
+      const signed = await apiFetch(
+        config,
+        options,
+        'POST',
+        `/api/v1/videos/uploads/${encodeURIComponent(initialized.intentId)}/parts`,
+        { partNumbers },
+      );
+      const queue = [...(signed.signedPartUrls || [])];
+      const signedNumbers = new Set(queue.map((part) => Number(part?.partNumber)));
+      if (
+        queue.length !== partNumbers.length
+        || signedNumbers.size !== partNumbers.length
+        || partNumbers.some((partNumber) => !signedNumbers.has(partNumber))
+        || queue.some((part) => typeof part?.url !== 'string' || !part.url)
+      ) {
+        throw new Error('Server returned an incomplete multipart signing batch.');
+      }
+      let cursor = 0;
+      const worker = async () => {
+        while (cursor < queue.length) {
+          const part = queue[cursor++];
+          const start = (part.partNumber - 1) * initialized.partSizeBytes;
+          const size = Math.min(initialized.partSizeBytes, totalBytes - start);
+          if (size !== Number(part.expectedSizeBytes)) {
+            throw new Error(`Server returned an invalid size for upload part ${part.partNumber}.`);
+          }
+          await putSignedVideoPart(part, resolved, start, size, progress);
+        }
+      };
+      const workerCount = Math.min(VIDEO_UPLOAD_PART_CONCURRENCY, queue.length);
+      await Promise.all(Array.from({ length: workerCount }, () => worker()));
+    }
+  } finally {
+    progress.finish();
   }
-  yield Buffer.from(`\r\n--${boundary}--\r\n`);
 }
 
 async function uploadVideo(config, options, filePath) {
@@ -1815,26 +2276,147 @@ async function uploadVideo(config, options, filePath) {
   if (!stat.isFile()) {
     throw Object.assign(new Error(`Upload path is not a file: ${resolved}`), { exitCode: EXIT.USAGE });
   }
-  assertDirectVideoUploadSize(resolved, stat.size);
-  const filename = options.filename || path.basename(resolved);
+  const filename = String(options.filename || path.basename(resolved));
   const contentType = mimeForPath(resolved);
-  const boundary = `clipit-cli-${randomBytes(12).toString('hex')}`;
-  const headerLength = Buffer.byteLength(
-    `--${boundary}\r\nContent-Disposition: form-data; name="file"; filename="${multipartFilename(filename)}"\r\nContent-Type: ${contentType}\r\n\r\n`,
+  const title = options.title === undefined || options.title === null
+    ? null
+    : String(options.title);
+  const idempotencyKey = String(
+    options['idempotency-key']
+      || defaultVideoUploadIdempotencyKey(resolved, stat, filename, contentType),
   );
-  const footerLength = Buffer.byteLength(`\r\n--${boundary}--\r\n`);
-  const progress = createUploadProgress(options, stat.size);
-  const body = multipartFileBody(resolved, filename, contentType, boundary, progress);
+  const uploadIdentity = {
+    filePath: resolved,
+    filename,
+    title,
+    profile: profileName(config, options),
+    baseUrl: getBaseUrl(config, options),
+    allowCustomHost: allowCustomHost(options),
+    contentType,
+    size: stat.size,
+    mtimeMs: stat.mtimeMs,
+  };
+  const resumes = await readVideoUploadResumes();
+  const existingResume = resumes[idempotencyKey];
+  if (existingResume && typeof existingResume === 'object') {
+    const mismatchedFields = Object.entries(uploadIdentity)
+      .filter(([key, value]) => {
+        const existingValue = existingResume[key];
+        if (key === 'title') return (existingValue ?? null) !== value;
+        return existingValue !== value;
+      })
+      .map(([key]) => key);
+    if (mismatchedFields.length > 0) {
+      const abortArgs = existingResume.intentId
+        ? ['videos', 'abort-upload', String(existingResume.intentId), '--profile', String(existingResume.profile || uploadIdentity.profile), '--base-url', String(existingResume.baseUrl || uploadIdentity.baseUrl), '--confirm']
+        : null;
+      if (abortArgs && existingResume.allowCustomHost === true) abortArgs.push('--allow-custom-host');
+      throw Object.assign(
+        new Error('The file or upload identity changed since this resumable upload began. Abort the prior upload and retry with a new idempotency key.'),
+        {
+          exitCode: EXIT.USAGE,
+          data: {
+            idempotencyKey,
+            uploadIntentId: existingResume.intentId,
+            mismatchedFields,
+            abortArgs,
+            abortCommand: abortArgs ? `clipit ${abortArgs.map(shellQuote).join(' ')}` : undefined,
+          },
+        },
+      );
+    }
+  }
   await enforceMaxCredits(config, options, 'videos upload', { bytes: stat.size });
   confirmPaid(options, 'Uploading a video');
+  await saveVideoUploadResume(idempotencyKey, {
+    ...uploadIdentity,
+    intentId: existingResume?.intentId,
+    jobId: existingResume?.jobId,
+    updatedAt: new Date().toISOString(),
+  });
+
+  let initialized;
   try {
-    const result = await apiFetch(config, options, 'POST', '/api/v1/videos', body, {
-      rawBody: true,
-      headers: {
-        'Content-Type': `multipart/form-data; boundary=${boundary}`,
-        'Content-Length': String(headerLength + stat.size + footerLength),
-      },
+    initialized = await apiFetch(config, options, 'POST', '/api/v1/videos/uploads', {
+      filename,
+      contentType,
+      size: stat.size,
+      title: title ?? undefined,
+      idempotencyKey,
     });
+    if (!initialized?.intentId || !initialized?.jobId) {
+      throw Object.assign(new Error('Video upload initialization returned an unexpected response.'), {
+        exitCode: EXIT.SERVER,
+        data: initialized,
+      });
+    }
+    if (!initialized.readyForUpload) {
+      await removeVideoUploadResume(idempotencyKey);
+      if (initialized.videoId) {
+        await persistActiveContext(
+          config,
+          options,
+          { videoId: initialized.videoId },
+          [{ type: 'video', id: initialized.videoId }],
+        );
+      }
+      output(initialized, options);
+      return;
+    }
+
+    await saveVideoUploadResume(idempotencyKey, {
+      ...uploadIdentity,
+      intentId: initialized.intentId,
+      jobId: initialized.jobId,
+      updatedAt: new Date().toISOString(),
+    });
+
+    if (initialized.transport === 'single') {
+      if (!initialized.uploadUrl || Number(initialized.expectedSizeBytes) !== stat.size) {
+        throw new Error('Direct upload initialization returned invalid transfer metadata.');
+      }
+      await putSignedUpload(
+        initialized.uploadUrl,
+        resolved,
+        contentType,
+        stat.size,
+        options,
+        initialized.requiredHeaders,
+      );
+    } else if (initialized.transport === 'multipart') {
+      if (
+        !Number.isInteger(initialized.partCount)
+        || !Number.isInteger(initialized.partSizeBytes)
+        || Number(initialized.expectedSizeBytes) !== stat.size
+      ) {
+        throw new Error('Multipart upload initialization returned invalid transfer metadata.');
+      }
+      await uploadVideoMultipart(config, options, resolved, initialized, stat.size);
+    } else {
+      throw new Error('Video upload initialization returned no supported transport.');
+    }
+
+    const completedStat = await fs.stat(resolved);
+    if (
+      !completedStat.isFile()
+      || completedStat.size !== stat.size
+      || completedStat.mtimeMs !== stat.mtimeMs
+      || completedStat.ctimeMs !== stat.ctimeMs
+    ) {
+      throw Object.assign(
+        new Error('The video file changed while it was uploading. Abort this upload and retry with a new idempotency key.'),
+        { exitCode: EXIT.USAGE, data: { fileChangedDuringUpload: true } },
+      );
+    }
+
+    const result = await apiFetch(
+      config,
+      options,
+      'POST',
+      `/api/v1/videos/uploads/${encodeURIComponent(initialized.intentId)}/complete`,
+      {},
+    );
+    await removeVideoUploadResume(idempotencyKey);
     if (result?.videoId) {
       await persistActiveContext(
         config,
@@ -1844,8 +2426,42 @@ async function uploadVideo(config, options, filePath) {
       );
     }
     output(result, options);
-  } finally {
-    progress.finish();
+  } catch (error) {
+    if (error && typeof error === 'object') {
+      const requiresNewIdempotencyKey = error.data?.requiresNewIdempotencyKey === true
+        || error.data?.code === 'IDEMPOTENCY_KEY_TERMINAL';
+      if (requiresNewIdempotencyKey) {
+        await removeVideoUploadResume(idempotencyKey);
+        error.data = {
+          ...(error.data && typeof error.data === 'object' ? error.data : {}),
+          uploadIntentId: initialized?.intentId ?? existingResume?.intentId,
+          idempotencyKey,
+        };
+        throw error;
+      }
+      const resumeArgs = [
+        'videos',
+        'upload',
+        resolved,
+        '--idempotency-key',
+        idempotencyKey,
+      ];
+      resumeArgs.push('--filename', filename);
+      if (title) resumeArgs.push('--title', title);
+      resumeArgs.push('--profile', uploadIdentity.profile);
+      resumeArgs.push('--base-url', uploadIdentity.baseUrl);
+      if (uploadIdentity.allowCustomHost) resumeArgs.push('--allow-custom-host');
+      if (boolOption(options.confirm) || boolOption(options.yes)) resumeArgs.push('--confirm');
+      if (wantJson(options)) resumeArgs.push('--json');
+      error.data = {
+        ...(error.data && typeof error.data === 'object' ? error.data : {}),
+        uploadIntentId: initialized?.intentId ?? existingResume?.intentId,
+        idempotencyKey,
+        resumeArgs,
+        resumeCommand: `clipit ${resumeArgs.map(shellQuote).join(' ')}`,
+      };
+    }
+    throw error;
   }
 }
 
@@ -1866,13 +2482,30 @@ async function videos(config, options, action, args) {
     if (!url) throw Object.assign(new Error('URL is required.'), { exitCode: EXIT.USAGE });
     await enforceMaxCredits(config, options, 'videos import-url', { url });
     confirmPaid(options, 'Importing a video from URL');
-    output(await apiFetch(config, options, 'POST', '/api/v1/videos/from-url', { url, title: options.title }), options);
+    output(await apiFetch(config, options, 'POST', '/api/v1/videos/from-url', {
+      url,
+      title: options.title,
+      idempotencyKey: options['idempotency-key'] || randomUUID(),
+    }), options);
     return;
   }
   if (action === 'upload') {
     await uploadVideo(config, options, args[0] || options.file);
     return;
   }
+  if (action === 'abort-upload') {
+    const intentId = requiredString(args[0] || options['intent-id'], 'Upload intent id');
+    requireConfirm(options, 'Aborting a video upload');
+    const result = await apiFetch(
+      config,
+      options,
+      'DELETE',
+      `/api/v1/videos/uploads/${encodeURIComponent(intentId)}`,
+    );
+    await removeVideoUploadResumeByIntent(intentId);
+    output(result, options);
+    return;
+  }
   if (action === 'transcribe') {
     if (!args[0]) throw Object.assign(new Error('Video id is required.'), { exitCode: EXIT.USAGE });
     await enforceMaxCredits(config, options, 'videos transcribe', { videoId: args[0] });
@@ -1911,6 +2544,119 @@ async function videos(config, options, action, args) {
   throw Object.assign(new Error(`Unknown videos command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
+function formatClipDeliveryState(state) {
+  const editor = state?.editorState;
+  const selected = state?.selectedExport;
+  const candidates = Array.isArray(state?.exports) ? state.exports : [];
+  const blockers = Array.isArray(state?.deliveryBlockers) ? state.deliveryBlockers : [];
+  const lines = [
+    `Clip: ${state?.clipId || 'unknown'}`,
+    editor
+      ? `Editor snapshot: ${editor.snapshotId}`
+      : `Editor: ${state?.editorStateStatus || 'unavailable'}`,
+    editor ? `Editor version: ${editor.editorVersion}` : null,
+    editor ? `Editor state hash: ${editor.editorStateHash}` : null,
+    editor ? `Source object fingerprint: ${editor.sourceObjectFingerprint || 'unavailable'}` : null,
+    editor ? `Saved: ${editor.saveOrigin} at ${editor.savedAt}` : null,
+    editor
+      ? `Edit: ${editor.aspectRatio}; captions ${editor.caption?.enabled ? 'on' : 'off'}${editor.caption?.presetId ? `/${editor.caption.presetId}` : ''}; crop ${editor.cropSegmentCount}; keyframes ${editor.keyframeCount}; layout ${editor.layout || 'none'}`
+      : null,
+    `Selection: ${state?.selection?.status || 'unknown'}${state?.selection?.selectedExportId ? ` (${state.selection.selectedExportId})` : ''}`,
+    selected
+      ? `Selected export: ${selected.exportId}; snapshot ${selected.snapshotId || 'unavailable'}; exact current match ${selected.exactlyMatchesEditor === true ? 'yes' : 'no'}`
+      : `Artifacts: ${candidates.length}`,
+    selected ? `Output object fingerprint: ${selected.outputObjectFingerprint || 'unavailable'}` : null,
+    selected ? `Storage item: ${selected.storageItemId || 'unavailable'}` : null,
+    selected
+      ? `Artifact: ${selected.width || '?'}x${selected.height || '?'} ${selected.duration || '?'}s; audio ${selected.hasAudio === true ? 'yes' : selected.hasAudio === false ? 'no' : 'unknown'}; probe ${selected.inspectionStatus}`
+      : null,
+    `Ready to publish: ${state?.readyToPublish === true ? 'yes' : 'no'}`,
+  ].filter(Boolean);
+  if (candidates.length > 1) {
+    lines.push(`Export ids: ${candidates.map((candidate) => candidate.exportId).join(', ')}`);
+  }
+  if (blockers.length) {
+    lines.push('Blockers:');
+    lines.push(...blockers.map((blocker) => `- ${blocker}`));
+  }
+  return lines.join('\n');
+}
+
+function requireVerifiedEditorState(deliveryState, clipId) {
+  const editor = deliveryState?.editorState;
+  if (
+    deliveryState?.schema !== 'clipit_clip_delivery_state'
+    || deliveryState?.version !== 2
+    || deliveryState?.clipId !== clipId
+    || deliveryState?.editorStateStatus !== 'verified'
+    || !editor
+    || typeof editor.snapshotId !== 'string'
+    || !editor.snapshotId
+    || !Number.isInteger(editor.editorVersion)
+    || editor.editorVersion < 1
+    || typeof editor.editorStateHash !== 'string'
+    || !/^[a-f0-9]{64}$/i.test(editor.editorStateHash)
+    || editor.stateSource !== 'current_editor_snapshot'
+  ) {
+    throw Object.assign(
+      new Error('Clip does not have a verified canonical editor snapshot. Save and verify the editor state before continuing.'),
+      { exitCode: EXIT.SERVER, data: deliveryState },
+    );
+  }
+  return editor;
+}
+
+function requireExactCurrentExport(deliveryState, editorState, options = {}) {
+  const requestedExportId = options.requestedExportId
+    ? String(options.requestedExportId)
+    : null;
+  const selection = deliveryState?.selection;
+  const selected = deliveryState?.selectedExport;
+  const blockers = Array.isArray(deliveryState?.deliveryBlockers)
+    ? deliveryState.deliveryBlockers
+    : [];
+  const selectedBlockers = Array.isArray(selected?.blockers) ? selected.blockers : [];
+  const responseRequestedExportId = selection?.requestedExportId ?? null;
+  const exact = Boolean(
+    selection?.status === 'selected'
+    && selected
+    && typeof selected.exportId === 'string'
+    && selected.exportId
+    && selection.selectedExportId === selected.exportId
+    && responseRequestedExportId === requestedExportId
+    && (!requestedExportId || selected.exportId === requestedExportId)
+    && selected.snapshotId === editorState.snapshotId
+    && selected.editorVersion === editorState.editorVersion
+    && selected.editorStateHash === editorState.editorStateHash
+    && selected.exactlyMatchesEditor === true
+    && selected.inspectionStatus === 'verified'
+    && typeof selected.outputObjectFingerprint === 'string'
+    && /^[a-f0-9]{64}$/i.test(selected.outputObjectFingerprint)
+    && selectedBlockers.length === 0
+  );
+  const publishReady = !options.requireReadyToPublish
+    || (deliveryState?.readyToPublish === true && blockers.length === 0);
+  if (!exact || !publishReady) {
+    const detail = blockers.length
+      ? blockers.join(' ')
+      : `Selection status is ${selection?.status || 'unknown'}.`;
+    throw Object.assign(
+      new Error(`Clip does not have one verified exact-current export: ${detail}`),
+      { exitCode: EXIT.SERVER, data: deliveryState },
+    );
+  }
+  return selected;
+}
+
+async function fetchCanonicalClipDeliveryState(config, options, clipId, exportId) {
+  return apiFetch(
+    config,
+    options,
+    'GET',
+    `/api/v1/clips/${encodeURIComponent(clipId)}/delivery-state${queryString({ exportId })}`,
+  );
+}
+
 async function clips(config, options, action, args) {
   if (action === 'list') {
     output(await apiFetch(config, options, 'GET', `/api/v1/clips${queryString({
@@ -1927,6 +2673,19 @@ async function clips(config, options, action, args) {
     output(result, options);
     return;
   }
+  if (action === 'delivery-state') {
+    if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
+    const result = await apiFetch(
+      config,
+      options,
+      'GET',
+      `/api/v1/clips/${encodeURIComponent(args[0])}/delivery-state${queryString({
+        exportId: options['export-id'],
+      })}`,
+    );
+    output(wantJson(options) ? result : formatClipDeliveryState(result), options);
+    return;
+  }
   if (action === 'create') {
     const body = options.params
       ? await readJsonOption(String(options.params))
@@ -1994,9 +2753,34 @@ async function clips(config, options, action, args) {
   }
   if (action === 'download') {
     if (!args[0]) throw Object.assign(new Error('Clip id is required.'), { exitCode: EXIT.USAGE });
-    const result = await apiFetch(config, options, 'GET', `/api/v1/clips/${encodeURIComponent(args[0])}/download`);
+    const clipId = args[0];
+    const requestedExportId = options['export-id'];
+    const deliveryState = await fetchCanonicalClipDeliveryState(
+      config,
+      options,
+      clipId,
+      requestedExportId,
+    );
+    const editorState = requireVerifiedEditorState(deliveryState, clipId);
+    const selectedExport = requireExactCurrentExport(deliveryState, editorState, {
+      requestedExportId,
+    });
+    const result = await apiFetch(
+      config,
+      options,
+      'GET',
+      `/api/v1/exports/${encodeURIComponent(selectedExport.exportId)}/download`,
+    );
     if (options.open && result?.downloadUrl) openBrowser(result.downloadUrl);
-    output(result, options);
+    output({
+      ...result,
+      clipId,
+      exportId: selectedExport.exportId,
+      snapshotId: editorState.snapshotId,
+      editorVersion: editorState.editorVersion,
+      editorStateHash: editorState.editorStateHash,
+      outputObjectFingerprint: selectedExport.outputObjectFingerprint,
+    }, options);
     return;
   }
   if (action === 'delete') {
@@ -2139,6 +2923,17 @@ function defaultExportStartBody(clipId) {
   };
 }
 
+function buildCanonicalExportStartBody(clipId, params, editorState, idempotencyKey) {
+  return {
+    ...defaultExportStartBody(clipId),
+    ...params,
+    clipId,
+    idempotencyKey,
+    expectedEditorVersion: editorState.editorVersion,
+    expectedEditorStateHash: editorState.editorStateHash,
+  };
+}
+
 async function pollExport(config, options, jobId) {
   const startedAt = Date.now();
   const timeoutMs = numberOption(options['timeout-ms'], '--timeout-ms');
@@ -2161,14 +2956,32 @@ async function exportsCommand(config, options, action, args) {
   if (action === 'start') {
     const clipId = requiredString(options['clip-id'], '--clip-id');
     const params = options.params ? await readJsonOption(String(options.params)) : {};
-    const body = {
-      ...defaultExportStartBody(clipId),
-      ...params,
+    if (!params || typeof params !== 'object' || Array.isArray(params)) {
+      throw Object.assign(new Error('--params must contain a JSON object.'), { exitCode: EXIT.USAGE });
+    }
+    const deliveryState = await fetchCanonicalClipDeliveryState(config, options, clipId);
+    const editorState = requireVerifiedEditorState(deliveryState, clipId);
+    const idempotencyKey = requiredString(
+      options['idempotency-key'] || params.idempotencyKey || `cli-export:${randomUUID()}`,
+      '--idempotency-key',
+    );
+    const body = buildCanonicalExportStartBody(
       clipId,
-    };
+      params,
+      editorState,
+      idempotencyKey,
+    );
     await enforceMaxCredits(config, options, 'exports start', { clipId, body });
     confirmPaid(options, 'Starting an export');
-    output(await apiFetch(config, options, 'POST', '/api/v1/exports', body), options);
+    const result = await apiFetch(config, options, 'POST', '/api/v1/exports', body);
+    output({
+      ...result,
+      clipId,
+      snapshotId: editorState.snapshotId,
+      expectedEditorVersion: body.expectedEditorVersion,
+      expectedEditorStateHash: body.expectedEditorStateHash,
+      idempotencyKey: body.idempotencyKey,
+    }, options);
     return;
   }
   if (action === 'list') {
@@ -2200,32 +3013,76 @@ async function exportsCommand(config, options, action, args) {
   throw Object.assign(new Error(`Unknown exports command: ${action || ''}`), { exitCode: EXIT.USAGE });
 }
 
-function objectPathFromKey(key) {
-  return String(key).startsWith('/objects/') ? String(key) : `/objects/${key}`;
-}
-
-async function putSignedUpload(uploadUrl, filePath, contentType, size, options) {
-  let response;
-  const progress = createUploadProgress(options, size);
-  const body = createReadStream(filePath).pipe(progressTransform(progress));
-  try {
-    response = await fetch(uploadUrl, {
-      method: 'PUT',
-      headers: {
+async function putSignedUpload(uploadUrl, filePath, contentType, size, options, requiredHeaders) {
+  const headers = requiredHeaders && typeof requiredHeaders === 'object'
+    ? Object.fromEntries(Object.entries(requiredHeaders).map(([key, value]) => [key, String(value)]))
+    : {
         'Content-Type': contentType,
         'Content-Length': String(size),
-      },
-      body,
-      duplex: 'half',
-    });
-  } catch (error) {
-    throw Object.assign(new Error(`Upload failed: ${error.message}`), { exitCode: EXIT.NETWORK });
-  } finally {
-    progress.finish();
+      };
+  const requiredContentType = headers['Content-Type'] ?? headers['content-type'];
+  const requiredContentLength = headers['Content-Length'] ?? headers['content-length'];
+  if (requiredContentType !== contentType || requiredContentLength !== String(size)) {
+    throw Object.assign(
+      new Error('Upload signing response did not preserve the requested Content-Type and Content-Length headers.'),
+      { exitCode: EXIT.SERVER },
+    );
   }
-  if (!response.ok) {
-    const text = await response.text().catch(() => '');
-    throw Object.assign(new Error(`Upload failed: ${response.status} ${redact(text || response.statusText)}`), { exitCode: EXIT.SERVER });
+
+  for (let attempt = 0; attempt < VIDEO_UPLOAD_PART_ATTEMPTS; attempt += 1) {
+    const progress = createUploadProgress(options, size);
+    const controller = new AbortController();
+    let source;
+    let tracker;
+    const watchdog = createUploadActivityWatchdog(controller, () => {
+      source?.destroy();
+      tracker?.destroy();
+    });
+    try {
+      tracker = new Transform({
+        transform(chunk, encoding, callback) {
+          watchdog.activity();
+          progress.track(chunk);
+          callback(null, chunk);
+        },
+      });
+      source = createReadStream(filePath);
+      const response = await fetch(uploadUrl, {
+        method: 'PUT',
+        headers,
+        body: source.pipe(tracker),
+        duplex: 'half',
+        signal: controller.signal,
+      });
+      if (!response.ok) {
+        const text = await response.text().catch(() => '');
+        throw Object.assign(
+          new Error(`Upload failed: ${response.status} ${redact(text || response.statusText)}`),
+          { exitCode: EXIT.SERVER, status: response.status },
+        );
+      }
+      return;
+    } catch (error) {
+      const reason = controller.signal.aborted && controller.signal.reason instanceof Error
+        ? controller.signal.reason
+        : error;
+      const retryable = reason?.status === undefined
+        || reason.status === 408
+        || reason.status === 429
+        || reason.status >= 500;
+      if (attempt === VIDEO_UPLOAD_PART_ATTEMPTS - 1 || !retryable) {
+        throw Object.assign(new Error(`Upload failed: ${reason.message}`), {
+          exitCode: reason.exitCode || EXIT.NETWORK,
+          status: reason.status,
+        });
+      }
+      await sleep(VIDEO_UPLOAD_RETRY_BASE_MS * (2 ** attempt));
+    } finally {
+      watchdog.stop();
+      source?.destroy();
+      tracker?.destroy();
+      progress.finish();
+    }
   }
 }
 
@@ -2242,28 +3099,35 @@ async function uploadAsset(config, options, filePath) {
     contentType,
     size: stat.size,
     kind: options.kind,
+    idempotencyKey: `cli-library:${randomUUID()}`,
   });
   requireConfirm(options, 'Uploading an asset');
   const signed = await apiFetch(config, options, 'POST', '/api/v1/assets/sign-upload', signBody);
-  if (!signed?.uploadUrl || !signed?.key || !signed?.assetId) {
+  const uploadUrl = signed?.uploadUrl || signed?.url;
+  if (!uploadUrl || !signed?.intentId || !signed?.assetId) {
     throw Object.assign(new Error('Asset sign-upload returned an unexpected response.'), { exitCode: EXIT.SERVER, data: signed });
   }
-  await putSignedUpload(signed.uploadUrl, resolved, contentType, stat.size, options);
-  const objectPath = objectPathFromKey(signed.key);
+  await putSignedUpload(uploadUrl, resolved, contentType, stat.size, options);
   output(await apiFetch(config, options, 'POST', `/api/v1/assets/${encodeURIComponent(signed.assetId)}/finalize`, {
-    objectPath,
-    fileSize: stat.size,
-    duration: options.duration === undefined ? null : numberOption(options.duration, '--duration'),
+    uploadIntentId: signed.intentId,
   }), options);
 }
 
 async function assets(config, options, action, args) {
   if (action === 'list') {
-    output(await apiFetch(config, options, 'GET', `/api/v1/assets${queryString({
+    const response = await apiFetch(config, options, 'GET', `/api/v1/assets${queryString({
       type: options.type,
       limit: options.limit,
       offset: options.offset,
-    })}`), options);
+    })}`, undefined, { includeResponseMetadata: true });
+    const items = Array.isArray(response.data) ? response.data : [];
+    const headerTotal = Number(response.headers['x-total-count']);
+    output({
+      items,
+      total: Number.isFinite(headerTotal) ? headerTotal : items.length,
+      limit: numberOption(options.limit, '--limit') ?? items.length,
+      offset: numberOption(options.offset, '--offset') ?? 0,
+    }, options);
     return;
   }
   if (action === 'upload') {
@@ -2370,13 +3234,83 @@ function socialPlatformList(value) {
   return platforms.map((platform) => platform.toLowerCase() === 'x' ? 'twitter' : platform);
 }
 
-function socialPostBody(options, scheduled) {
+function socialAccountIdPins(value) {
+  if (!value) return {};
+  const raw = String(value).trim();
+  if (!raw) return {};
+  if (raw.startsWith('{')) {
+    const parsed = JSON.parse(raw);
+    if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+      throw Object.assign(new Error('--account-ids JSON must be an object of platform to account id.'), { exitCode: EXIT.USAGE });
+    }
+    return Object.fromEntries(Object.entries(parsed).map(([platform, accountId]) => [
+      platform.toLowerCase() === 'x' ? 'twitter' : platform.toLowerCase(),
+      requiredString(accountId, `account id for ${platform}`),
+    ]));
+  }
+  return Object.fromEntries(raw.split(',').filter(Boolean).map((entry) => {
+    const separator = entry.indexOf('=');
+    if (separator <= 0 || separator === entry.length - 1) {
+      throw Object.assign(new Error('--account-ids must use platform=accountId pairs.'), { exitCode: EXIT.USAGE });
+    }
+    const platform = entry.slice(0, separator).trim().toLowerCase();
+    const accountId = entry.slice(separator + 1).trim();
+    return [platform === 'x' ? 'twitter' : platform, accountId];
+  }));
+}
+
+async function socialPostBody(config, options, scheduled) {
+  const clipId = requiredString(options['clip-id'], '--clip-id');
+  const platforms = socialPlatformList(options.platforms);
+  const caption = requiredString(options.caption, '--caption');
+  const requestedExportId = options['export-id'];
+  const deliveryState = await fetchCanonicalClipDeliveryState(
+    config,
+    options,
+    clipId,
+    requestedExportId,
+  );
+  const editorState = requireVerifiedEditorState(deliveryState, clipId);
+  const selectedExport = requireExactCurrentExport(deliveryState, editorState, {
+    requestedExportId,
+    requireReadyToPublish: true,
+  });
+  const accountsResponse = await apiFetch(config, options, 'GET', '/api/v1/social/accounts');
+  const connectedAccounts = Array.isArray(accountsResponse?.accounts)
+    ? accountsResponse.accounts.filter((account) => account?.connected && typeof account?.accountId === 'string')
+    : [];
+  const requestedAccountIds = socialAccountIdPins(options['account-ids']);
+  const expectedAccountIds = Object.fromEntries(platforms.map((platform) => {
+    const choices = Array.from(new Set(connectedAccounts
+      .filter((account) => account.platform === platform)
+      .map((account) => account.accountId)));
+    const requestedAccountId = requestedAccountIds[platform];
+    if (requestedAccountId) {
+      if (!choices.includes(requestedAccountId)) {
+        throw Object.assign(new Error(`The selected ${platform} account id is not connected.`), { exitCode: EXIT.USAGE });
+      }
+      return [platform, requestedAccountId];
+    }
+    if (choices.length !== 1) {
+      const reason = choices.length === 0 ? 'no connected account' : 'multiple connected accounts';
+      throw Object.assign(
+        new Error(`${platform} has ${reason}. Run "clipit social accounts --json" and pass --account-ids ${platform}=<accountId>.`),
+        { exitCode: EXIT.USAGE },
+      );
+    }
+    return [platform, choices[0]];
+  }));
   const body = compactObject({
-    clipId: requiredString(options['clip-id'], '--clip-id'),
-    platforms: socialPlatformList(options.platforms),
-    caption: requiredString(options.caption, '--caption'),
+    clipId,
+    platforms,
+    caption,
     title: options.title,
     hashtags: stringList(options.hashtags),
+    exportId: selectedExport.exportId,
+    expectedSnapshotId: editorState.snapshotId,
+    expectedOutputObjectFingerprint: selectedExport.outputObjectFingerprint,
+    expectedAccountIds,
+    publishExactCurrentArtifact: true,
   });
   if (scheduled) body.scheduledFor = requiredString(options.at, '--at');
   return body;
@@ -2388,14 +3322,14 @@ async function social(config, options, action, args) {
     return;
   }
   if (action === 'post') {
-    const body = socialPostBody(options, false);
+    const body = await socialPostBody(config, options, false);
     await enforceMaxCredits(config, options, 'social post', { body });
     confirmPaid(options, 'Publishing a social post');
     output(await apiFetch(config, options, 'POST', '/api/v1/social/post', body), options);
     return;
   }
   if (action === 'schedule') {
-    const body = socialPostBody(options, true);
+    const body = await socialPostBody(config, options, true);
     await enforceMaxCredits(config, options, 'social schedule', { body });
     confirmPaid(options, 'Scheduling a social post');
     output(await apiFetch(config, options, 'POST', '/api/v1/social/schedule', body), options);
@@ -2437,6 +3371,19 @@ async function jobs(config, options, action, args) {
   while (true) {
     const job = await apiFetch(config, options, 'GET', `/api/v1/jobs/${encodeURIComponent(jobId)}`);
     if (action === 'get' || TERMINAL_JOB_STATUSES.has(job.status)) {
+      const videoId = job.videoId || job.result?.videoId;
+      const clipId = job.clipId || job.result?.clipId;
+      if (videoId || clipId) {
+        await persistActiveContext(
+          config,
+          options,
+          compactObject({ videoId, clipId }),
+          [
+            videoId ? { type: 'video', id: videoId } : null,
+            clipId ? { type: 'clip', id: clipId } : null,
+          ].filter(Boolean),
+        );
+      }
       output(job, options);
       return;
     }
@@ -3029,7 +3976,7 @@ async function examples(options) {
     uploadAsset: 'clipit assets upload ./brand-logo.png --kind image --confirm --json',
     thumbnail: 'clipit thumbnails generate --clip-id <clipId> --prompt "Expressive high-contrast thumbnail" --confirm --json',
     brollPlan: 'clipit broll plan <clipId> --count 3 --confirm --json',
-    socialPost: 'clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json',
+    socialPost: 'clipit social post --clip-id <clipId> --platforms x,tiktok --account-ids x=<xAccountId>,tiktok=<tiktokAccountId> --caption "New clip" --confirm --json',
     runTool: 'clipit run <functionName> --clip-id <clipId> --params @params.json --json',
     reviewLink: 'clipit links clip <clipId> --json',
   };
@@ -3062,6 +4009,7 @@ Rules:
 - Credits from subscriptions and top-ups stack; paid features are credit-gated, so verify the payment receipt or balance before running paid ClipIt tools.
 - Use \`clipit open clip <id>\` when the user should review work in ClipIt.
 - Use \`clipit context use --video-id <id>\` or \`clipit context use --clip-id <id>\` to persist the current target for later commands.
+- Run \`clipit social accounts --json\` before posting. If a platform has multiple connected accounts, pin the intended one with \`--account-ids platform=accountId\`; ClipIt will not guess.
 - Do not write API keys into this skill file or any project files.
 
 Useful commands:
@@ -3095,7 +4043,7 @@ clipit billing receipt <attemptId> --json
 clipit analytics overview --days 30 --json
 clipit exports start --clip-id <clipId> --confirm --json
 clipit thumbnails generate --clip-id <clipId> --prompt "High contrast thumbnail" --confirm --json
-clipit social post --clip-id <clipId> --platforms x,tiktok --caption "New clip" --confirm --json
+clipit social post --clip-id <clipId> --platforms x,tiktok --account-ids x=<xAccountId>,tiktok=<tiktokAccountId> --caption "New clip" --confirm --json
 clipit run renderClipWithRemotion --clip-id <clipId> --params @params.json --confirm --json
 \`\`\`
 
@@ -3377,6 +4325,7 @@ async function main() {
   if (command === 'auth' && subcommand === 'set-key') return setKey(config, options);
   if (command === 'auth' && subcommand === 'open-settings') return openCommand(config, options, 'settings');
   if (command === 'auth' && subcommand === 'profiles') return listProfiles(config, options);
+  if (command === 'auth' && subcommand === 'use') return useProfile(config, options, rest[0]);
   if (command === 'context') return contextCommand(config, options, subcommand);
   if (command === 'skills' && subcommand === 'list') return listSkills(config, options);
   if (command === 'tools' && subcommand === 'list') return listTools(config, options);
@@ -3416,6 +4365,9 @@ function handleMainError(error) {
     }), null, 2));
   } else {
     console.error(message);
+    const details = redactDeep(error.data);
+    if (details?.resumeCommand) console.error(`Resume with: ${details.resumeCommand}`);
+    if (details?.abortCommand) console.error(`Abort the prior upload with: ${details.abortCommand}`);
   }
   process.exit(exitCode);
 }
@@ -3438,4 +4390,18 @@ if (await isDirectRun()) {
   main().catch(handleMainError);
 }
 
-export { main, redact, clipCostLabel, handleMcpRequest };
+export {
+  buildCanonicalExportStartBody,
+  main,
+  redact,
+  clipCostLabel,
+  requireExactCurrentExport,
+  requireVerifiedEditorState,
+  handleMcpRequest,
+  readPositiveIntegerEnv,
+  readSecretLine,
+  readVideoUploadResumes,
+  removeVideoUploadResume,
+  saveVideoUploadResume,
+  shellQuote,
+};