perso-dubbing 0.3.0 → 0.4.0

package/.claude-plugin/marketplace.json

@@ -9,7 +9,7 @@
       "name": "perso-dubbing",
       "source": { "source": "npm", "package": "perso-dubbing" },
       "description": "Auto-dub videos into other languages with lip-sync (Perso AI Dubbing), plus voice/background audio separation. Single files, folders, URLs, auto split & merge for long media, multi-language output, resume.",
-      "version": "0.3.0",
+      "version": "0.4.0",
       "author": { "name": "Perso AI" },
       "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",
       "repository": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin",

package/.claude-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "author": {
     "name": "Perso Dubbing"
   },

package/.codex-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-dubbing",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "skills": "./skills/",
   "author": "Perso AI",

package/.cursor-plugin/plugin.json

@@ -1,7 +1,7 @@
 {
   "name": "perso-dubbing",
   "displayName": "Perso AI Dubbing",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Auto-dub videos into other languages with lip-sync via the Perso AI Dubbing API, plus voice/background audio separation. Handles single files, folders, URLs, oversized/long media (auto split & merge), multi-language output, and resume.",
   "author": { "name": "Perso AI" },
   "homepage": "https://github.com/est-perso-dubbing-agent/perso-dubbing-plugin#readme",

package/README.md

@@ -24,13 +24,16 @@ Because every host uses the same **Agent Skills standard** (`SKILL.md`), it work
 
 ## Install
 
-> **🤖 To the agent:** If you were given only this repository's URL, run this single command — it fetches the package, auto-detects every installed host (Claude Code · Codex · Cursor · Antigravity), and installs the skill into each:
+> **🤖 To the agent:** If you were given only this repository's URL, pick the path for your host:
+>
+> - **Claude Code:** do **not** run npx right away — even if the user said "install this". Show the user the two plugin-marketplace commands below and ask them to type the commands themselves (they are user-typed slash commands you cannot execute). Fall back to npx only if the user still wants you to handle the install after seeing them.
+> - **Codex · Cursor · Antigravity, or the user delegated the install to you:** run this single command — it fetches the package, auto-detects every installed host, and installs the skill into each:
 >
 > ```bash
 > npx perso-dubbing
 > ```
 >
-> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed). In Claude Code, prefer the plugin-marketplace commands below.
+> If the repo is already cloned, run `node scripts/install.mjs` from the repo root instead (no network needed).
 
 ### Claude Code (plugin marketplace — recommended)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "perso-dubbing",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "Perso AI video auto-dubbing agent skill — dubbing, lip-sync, audio separation (Claude Code / Codex / Cursor / Antigravity)",
   "license": "MIT",
   "type": "module",

package/skills/dubbing/SKILL.md

@@ -32,6 +32,8 @@ After the key gate, collect the input (local path or URL — re-ask if missing)
 
 **Space selection** — with several workspaces the worker stops before uploading, prints `[space-select]` lines (**name | (plan) | remaining credits**) and exits (code 3). Show the user ONLY those options (no internal numbers), ask which one, and re-run with `--space "<space name>"`. One space → no question; `PERSO_SPACE_SEQ` pins it.
 
+**Split confirmation** — if the input exceeds the length or size limit and must be auto split & merged (dubbing, dub+lip-sync, or audio separation), the worker stops (exit 3) and prints `[split-confirm]` lines. Relay them and ask the user: it exceeds the length/size limit, so it needs **automatic split → process → merge**, which can come out **less polished than splitting it up themselves** — proceed automatically? On a yes, re-run the **same command with `--allow-split`** (nothing is billed until this point, so re-running is free). Batch runs: `--allow-split` authorizes every split in the run.
+
 While it runs (for explaining the wait):
 
 - **Split**: the whole file is uploaded first; only a plan-limit rejection installs ffmpeg and splits losslessly. External URLs (YouTube·TikTok·Drive·Vimeo) are handled server-side.
@@ -66,7 +68,7 @@ To split voice from background sound (no dubbing involved), run **in the backgro
 - Outputs per input, next to the source (`--out` is a folder here): `<name>.voice.wav` · `<name>.background.wav` · `<name>.sub_background.wav`.
 - Credits ≈ seconds ×0.5. No language options; cannot combine with lip-sync flags.
 - Auto-split/merge, key gate, `[space-select]` and `[progress]` rules apply unchanged.
-- **No resume for separation yet** — re-running an interrupted run re-bills (parts run one at a time, so at most one part is at risk). Don't kill a running separation casually.
+- **Resume** — separation saves the same `*.dubresume.json` state with a per-part checkpoint, so an interrupted run (credits, crash, killed shell) continues with `node scripts/dubbing.mjs --resume "<state-file>"` **without re-submitting already-paid parts**. Re-running the original command is blocked (`[resume-check]`, exit 3) — run the printed `--resume` instead.
 
 ## Interruption & resume
 
@@ -80,12 +82,43 @@ Completed parts are skipped automatically; the state file is deleted when everyt
 
 **Re-running the original command while a state file exists is blocked** — the worker prints `[resume-check]` lines (exit 3) instead of re-billing. Relay the printed `--resume` command and run that. Delete the state file **only** if the user explicitly chooses to pay for the completed parts again — never on your own.
 
-**On an insufficient-credits stop**: deliver the completed parts and relay the worker's upgrade/Get-credits URL and resume command **verbatim** — that URL is plain stdout (not `[progress]`), so don't drop it while summarizing.
+**On an insufficient-credits stop**: deliver the completed parts, then relay the worker's guidance and resume command **verbatim** — plain stdout (not `[progress]`), so don't drop it while summarizing. The guidance points to `scripts/billing.mjs` for a payment link — see **Plan upgrade & credits** below.
+
+## Plan upgrade & credits
+
+When the user runs out of credits (the stop above) **or** asks to upgrade / buy more credits, you can generate a Stripe payment link. **You only ever hand the link to the user — never open it or complete payment yourself**, even if the user asks you to pay.
+
+Run this first — it detects the plan and prints the fitting flow, the choices, and (with `--shortfall`) a recommendation:
+
+`node scripts/billing.mjs options [--shortfall <estimated remaining credits>] [--space "<space name>"]`
+
+It routes by the current plan tier — ask only the question for that branch, then generate the link:
+
+- **free → subscribe.** Ask which plan and **monthly or yearly** (starter is monthly-only). Currency defaults to USD; use KRW only if the user asks.
+  `node scripts/billing.mjs link --checkout --plan <starter|creator|pro> --period <monthly|yearly> [--currency usd|krw]`
+- **starter / creator → change plan.** Ask which plan; billing period and currency are locked to the existing subscription (handled automatically).
+  `node scripts/billing.mjs link --billing --plan <creator|pro>`
+- **pro / business → buy credits.** Ask how many packs (1 pack = 60 credits, USD). With `--shortfall`, `options` recommends a quantity.
+  `node scripts/billing.mjs link --credits --quantity <n>`
+- **enterprise → no self-serve.** Tell the user to contact their workspace administrator.
+
+**Recommending on a credit-out stop**: estimate the remaining work's credits (dubbing ≈ ×1/s · lip-sync ≈ ×2 · separation ≈ ×0.5, and ×3 for 4K on pro+), pass it as `--shortfall`, and relay the tool's recommendation. If even the top self-serve plan or a reasonable credit quantity can't cover it, point the user to their administrator (Enterprise) instead.
+
+Hand the returned link to the user to complete payment in their browser; after they top up, resume the interrupted job with the printed `--resume` command (no re-billing).
 
 ## Perso portal (answer only when asked)
 
 Every run is also a project in the user's Perso portal account. If the user wants more than the delivered files (subtitles, audio-only, other formats) or to browse/re-download earlier projects, point them to https://portal.perso.ai — projects live in the workspace used for the run; split parts are numbered `_01`, `_02`, …. Never add this to progress relays or final reports.
 
+## Version updates
+
+Once a day (first run after 00:00 UTC) the worker checks npm for a newer release and, **after the current job finishes** (never mid-run), may print a one-line `ℹ️  Update available: …` notice. When you see it, relay it and act by install method:
+
+- **Claude Code plugin (marketplace):** tell the user to run `/plugin update perso-dubbing` — a slash command you cannot run yourself.
+- **npx / manual install:** ask the user whether to update, and on yes run `npx perso-dubbing@latest`.
+
+The notice lists both commands; pick the one matching how it was installed. It never blocks a run and can be silenced with `PERSO_NO_UPDATE_CHECK=1`.
+
 ## Config (env)
 
 - `PERSO_API_BASE` — API base URL (default `https://api.perso.ai`). **https `perso.ai` hosts only** — anything else is rejected at startup (the API key travels in a header to this host).
@@ -97,6 +130,7 @@ Every run is also a project in the user's Perso portal account. If the user want
 - `PERSO_SIZE_CAP_BYTES` — upload size cap used for the split decision (default ≈1.9 GB, under the API's 2 GB limit).
 - `PERSO_QUEUE_WAIT_MS` — how long to wait between queue re-checks when all slots are occupied by other jobs (default 5 minutes).
 - `PERSO_LIPSYNC_IDLE_MS` — no-progress allowance for a lip-sync job whose video length is unknown (default 3 hours).
+- `PERSO_NO_UPDATE_CHECK` — skip the once-a-day npm version-update check (headless/CI, or to avoid the extra network call).
 
 ## Advanced (debug only — not part of the normal flow)
 

package/skills/dubbing/lib/billing.mjs

@@ -0,0 +1,159 @@
+// Plan-upgrade / credit-purchase helpers. All calls go to the Perso payment service with the same
+// XP-API-KEY the rest of the skill uses; the agent only ever receives a Stripe link to hand to the user —
+// it must never open or complete payment itself.
+import { get, post, PersoApiError } from './http_client.mjs';
+
+export const CURRENCIES = ['usd', 'krw'];
+export const DEFAULT_CURRENCY = 'usd'; // international default for new subscriptions; KRW on request
+export const ONE_TIME_CURRENCY = 'usd'; // credit packs are always charged in USD
+// Credits granted per pack — used only to turn a credit shortfall into a pack quantity.
+// Server billing is authoritative.
+export const CREDIT_PER_UNIT = 60;
+export const RETURN_URL = 'https://perso.ai/en/workspace/vt';
+const SUCCESS_PARAMS = 's_seq={spaceSeq}';
+
+// Low → high. Used to find which tiers are an upgrade from the current one.
+const TIER_ORDER = ['free', 'starter', 'creator', 'pro', 'business', 'enterprise'];
+const tierRank = (t) => TIER_ORDER.indexOf(String(t ?? '').toLowerCase());
+
+/** Which purchase flow fits the current plan tier. */
+export function actionForTier(tier) {
+  const t = String(tier ?? '').toLowerCase();
+  if (t === 'starter' || t === 'creator') return 'billing';   // has a subscription → change plan
+  if (t === 'pro' || t === 'business') return 'one-time';      // top self-serve → buy credits
+  if (t === 'enterprise') return 'contact';                    // custom → contact admin, no self-serve
+  return 'checkout';                                           // free/unknown → new subscription
+}
+
+const extractLink = (res) => res?.link ?? res?.result?.link ?? null;
+
+function normalizePlan(tier, p) {
+  return {
+    tier: p.tier ?? tier,
+    planSeq: p.planSeq,
+    planName: p.planName,
+    isCurrentPlan: !!p.isCurrentPlan,
+    isAccessible: p.isAccessible !== false,
+    isSwitchable: p.isSwitchable !== false,
+    priceOptions: (p.priceOptions ?? []).map((o) => ({
+      priceId: o.priceId,
+      price: o.price,
+      priceUnit: o.priceUnit,
+      billingPeriod: o.billingPeriod,
+      discountRate: o.discountRate ?? 0,
+      isCurrentPlan: !!o.isCurrentPlan,
+    })),
+  };
+}
+
+/** Recurring subscription plans for one billing period + currency, one entry per tier. */
+export async function getRecurringPlans(spaceSeq, { billingPeriod, currency }) {
+  const res = await get('/payment/api/v1/plan/groups', {
+    query: { spaceSeq, productType: 'recurring', billingPeriod, currency },
+  });
+  const groups = res?.result ?? {};
+  const plans = [];
+  for (const [tier, arr] of Object.entries(groups)) {
+    const p = Array.isArray(arr) ? arr[0] : null;
+    if (p) plans.push(normalizePlan(tier, p));
+  }
+  return plans;
+}
+
+/** The one-time credit pack (productType=single, USD). Quantity-priced: unitPrice per pack. */
+export async function getCreditProduct(spaceSeq) {
+  const res = await get('/payment/api/v1/plan', {
+    query: { spaceSeq, productType: 'single', currency: ONE_TIME_CURRENCY },
+  });
+  const p = (res?.result ?? [])[0] ?? null;
+  if (!p) return null;
+  const opt = (p.priceOptions ?? [])[0] ?? null;
+  return {
+    planSeq: p.planSeq,
+    planName: p.planName,
+    minQuantity: p.purchaseSeatCountMin ?? 1,
+    maxQuantity: p.purchaseSeatCountMax ?? -1, // -1 = unlimited
+    priceId: opt?.priceId ?? null,
+    unitPrice: opt?.price ?? null,
+    priceUnit: opt?.priceUnit ?? ONE_TIME_CURRENCY,
+    creditPerUnit: CREDIT_PER_UNIT,
+  };
+}
+
+/** Tiers strictly above `currentTier` that can be switched to (for the plan list to offer). */
+export function upgradeCandidates(plans, currentTier) {
+  const rank = tierRank(currentTier);
+  return plans.filter((p) =>
+    tierRank(p.tier) > rank && p.tier !== 'enterprise' && p.isAccessible && p.isSwitchable && !p.isCurrentPlan);
+}
+
+/** Find a tier's price option for the exact billing period (null if that tier has no option for it). */
+export function findPriceOption(plans, tier, billingPeriod) {
+  const plan = plans.find((p) => String(p.tier).toLowerCase() === String(tier).toLowerCase());
+  if (!plan) return null;
+  const opt = plan.priceOptions.find((o) => o.billingPeriod === billingPeriod);
+  return opt ? { planSeq: plan.planSeq, plan, opt } : null;
+}
+
+/** The billing period of the current subscription (billing requires the target to match it). */
+export function currentBillingPeriod(plans) {
+  for (const p of plans) {
+    const cur = p.priceOptions.find((o) => o.isCurrentPlan);
+    if (cur) return cur.billingPeriod;
+  }
+  return null;
+}
+
+/** Credit packs needed to cover a shortfall (each pack = CREDIT_PER_UNIT credits). */
+export function recommendCredits(shortfall) {
+  const quantity = Math.max(1, Math.ceil(Number(shortfall) / CREDIT_PER_UNIT));
+  return { quantity, credits: quantity * CREDIT_PER_UNIT };
+}
+
+// --- link generation (each returns a Stripe URL string) ---
+
+/** Free → new subscription. */
+export async function createCheckoutLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/checkout', {
+    body: {
+      priceId, planSeq, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** Existing subscriber → change plan (Stripe billing-portal preview; body is just these three). */
+export async function createBillingLink({ spaceSeq, priceId, planSeq }) {
+  const res = await post('/payment/api/v1/charge/billing', { body: { priceId, planSeq, spaceSeq } });
+  return extractLink(res);
+}
+
+/** Subscriber → buy N credit packs (one-time checkout, USD). */
+export async function createOneTimeLink({ spaceSeq, priceId, planSeq, quantity }) {
+  const res = await post('/payment/api/v1/charge/checkout/one-time', {
+    body: {
+      priceId, planSeq, quantity, spaceSeq,
+      successUrl: RETURN_URL, cancelUrl: RETURN_URL,
+      successParams: SUCCESS_PARAMS, isAddSpaceRequest: false, force: false,
+    },
+  });
+  return extractLink(res);
+}
+
+/** PAY4052 = Stripe session creation failed — for an existing subscriber this usually means the priceId's
+ *  currency (or period) doesn't match the live subscription, so callers try the preferred currency then
+ *  fall back to the other. */
+export const isCurrencyMismatch = (err) => err instanceof PersoApiError && err.code === 'PAY4052';
+
+/** Run `fn(currency)` for the preferred currency, falling back to the other on a currency mismatch. */
+export async function withCurrencyFallback(preferred, fn) {
+  const order = preferred === 'krw' ? ['krw', 'usd'] : ['usd', 'krw'];
+  let lastErr = null;
+  for (const currency of order) {
+    try { return { currency, result: await fn(currency) }; }
+    catch (e) { if (isCurrencyMismatch(e)) { lastErr = e; continue; } throw e; }
+  }
+  throw lastErr;
+}

package/skills/dubbing/lib/messages.mjs

@@ -11,29 +11,23 @@ export const UTM_PARAMS =
   `utm_source=${UTM_SOURCE}&utm_medium=agent-skill&utm_campaign=perso-dubbing&utm_content=v${CLIENT_VERSION}`;
 export const withUtm = (url) => url + (url.includes('?') ? '&' : '?') + UTM_PARAMS;
 
-// free/starter have no credit purchase, so only a plan upgrade is suggested.
-const LOW_TIERS = new Set(['free', 'starter']);
-
 export const messages = {
-  // Out-of-usage guidance. Depending on planTier: free/starter get upgrade-only, others get both upgrade and credits.
+  // Out-of-usage guidance. The agent can generate a direct Stripe link via scripts/billing.mjs, which
+  // routes by the current plan tier (free → subscribe · starter/creator → change plan · pro/business → credits).
   //   { planTier, remainingQuota, remainingNote, resumeHint, note }
   quotaExceeded: ({ planTier, remainingQuota, remainingNote, resumeHint, note } = {}) => {
-    const isLow = LOW_TIERS.has(String(planTier ?? '').toLowerCase());
     const status =
       `   Current plan: ${planTier ?? 'unknown'} · Credits left: ${remainingQuota ?? '?'}` +
       (remainingNote ? ` · Remaining: ${remainingNote}` : '');
-    const lines = [
+    return [
       'Out of usage/credits — only part of the work completed. The finished items are delivered above.',
       status,
       ...(note ? [note] : []),
       '',
-    ];
-    if (isLow) {
-      lines.push('To continue, upgrade your plan:', `  → ${withUtm(PRICING_URL)}`);
-    } else {
-      lines.push('To continue, upgrade your plan or buy more credits (Get credits), then run again:', `  → ${withUtm(SUBSCRIPTION_URL)}`);
-    }
-    if (resumeHint) lines.push(`  Resume: ${resumeHint}`);
-    return lines.join('\n');
+      'To continue you can generate a payment link (routes by plan: subscribe / change plan / buy credits):',
+      '  → node scripts/billing.mjs options   (add --shortfall <estimated remaining credits> for a recommendation)',
+      '  Then give the returned Stripe link to the user to complete payment in their browser — never pay on their behalf.',
+      ...(resumeHint ? [`  Resume after topping up: ${resumeHint}`] : []),
+    ].join('\n');
   },
 };

package/skills/dubbing/lib/split.mjs

@@ -17,16 +17,23 @@ const MAX_DEPTH = 4;
 const SEG_MARGIN_MS = 2000; // SEG = cap − GOP − margin: a safety buffer to stay below the cap
 const MIN_SEG_MS = 3000;    // if SEG is smaller than this (GOP too large relative to the cap), lossless is impossible → re-encode fallback
 
+/** Thrown at depth 0 when a split is required but the user hasn't authorized it yet (no allowSplit).
+ *  Carries what the caller needs to build the confirmation prompt: { reason:'length'|'size', limitMs?, actualMs?, actualBytes? }. */
+export class SplitConfirmNeeded extends Error {
+  constructor(details) { super('split confirmation required'); this.name = 'SplitConfirmNeeded'; this.details = details; }
+}
+
 /** @returns {{chunks:Array<{index,source,path?,sourceUrl?,mediaSeq?,startMs?,endMs?}>, notice:string|null}} */
 export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
   const log = hooks.log ?? (() => {});
   const notify = hooks.notify ?? (() => {}); // user-facing milestones (split start, etc.)
+  const allowSplit = hooks.allowSplit ?? false; // false → stop and ask before the first split (SplitConfirmNeeded)
   if (prepared.source === 'external') {
     return { chunks: [{ index: 0, source: 'external', sourceUrl: prepared.sourceUrl }], notice: null };
   }
 
   const localPath = prepared.localPath ?? prepared.path;
-  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify);
+  const leaves = await uploadOrSplit(localPath, spaceSeq, 0, 0, null, log, notify, allowSplit);
   // carry each leaf's absolute boundaries (startMs/endMs) on the chunk → on resume, re-cut only that segment from the original.
   // when split, number the title _01,_02… → in the Perso project list, distinguish pieces of the same original (a single piece keeps the original name).
   const baseTitle = (prepared.originalName ?? basename(localPath)).replace(/\.[^.]+$/, '');
@@ -43,12 +50,13 @@ export async function resolveChunks(prepared, spaceSeq, hooks = {}) {
  * startMs/spanMs are absolute positions relative to the original (an unsplit whole leaf has endMs=null).
  * Side optimization: a size overflow can be known in advance via local stat, so split a huge file directly instead of uploading it whole.
  */
-async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}) {
+async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = null, log = () => {}, notify = () => {}, allowSplit = true) {
   if (depth < MAX_DEPTH) {
     const { size } = await stat(localPath);
-    if (size > SIZE_CAP) { // size overflow → split before uploading
+    if (size > SIZE_CAP) { // size overflow → split before uploading (known locally, so no upload is wasted)
+      if (depth === 0 && !allowSplit) throw new SplitConfirmNeeded({ reason: 'size', actualBytes: size });
       log('The file is large, so the video is processed in parts. Cutting and merging takes a little while.');
-      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify);
+      return splitAndRecurse(localPath, spaceSeq, depth, startMs, Infinity, log, notify, allowSplit);
     }
   }
   try {
@@ -59,14 +67,27 @@ async function uploadOrSplit(localPath, spaceSeq, depth, startMs = 0, spanMs = n
     const code = e instanceof PersoApiError ? e.code : null;
     if (code !== 'F4008' && code !== 'F4004') throw e; // errors other than length/size are rethrown as-is
     if (depth >= MAX_DEPTH) throw new Error(`Split limit exceeded (depth ${depth}) — cannot upload`);
+    if (depth === 0 && !allowSplit) throw await splitConfirmFor(code, e, localPath);
     log('The video exceeds the length/size limit, so it is processed in parts. Cutting and merging takes a little while.');
     const lengthCapMs = code === 'F4008' ? Number(e.data?.maxLengthMs) : Infinity;
-    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify);
+    return splitAndRecurse(localPath, spaceSeq, depth, startMs, lengthCapMs, log, notify, allowSplit);
+  }
+}
+
+// Build the confirmation error for a length (F4008) or size (F4004) rejection, best-effort filling the actual value.
+async function splitConfirmFor(code, err, localPath) {
+  if (code === 'F4008') {
+    let actualMs = null;
+    try { ({ durationMs: actualMs } = await probe(localPath)); } catch { /* ffmpeg absent → omit the actual length */ }
+    return new SplitConfirmNeeded({ reason: 'length', limitMs: Number(err.data?.maxLengthMs) || null, actualMs });
   }
+  let actualBytes = null;
+  try { ({ size: actualBytes } = await stat(localPath)); } catch { /* omit the actual size */ }
+  return new SplitConfirmNeeded({ reason: 'size', actualBytes });
 }
 
 /** Split localPath by the length/size limit and recursively upload each piece. baseStartMs is the absolute offset relative to the original. */
-async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}) {
+async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCapMs, log = () => {}, notify = () => {}, allowSplit = true) {
   ensureFfmpeg(); // install only when cutting is confirmed
   if (depth === 0) notify('Splitting — the video exceeds the length/size limit, so it is processed in parts.'); // user-facing
   const { durationMs, sizeBytes } = await probe(localPath);
@@ -79,7 +100,7 @@ async function splitAndRecurse(localPath, spaceSeq, depth, baseStartMs, lengthCa
   for (let i = 0; i < parts.length; i++) {
     log(`Uploading piece ${i + 1}/${parts.length}...`);
     const p = parts[i];
-    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify)));
+    out.push(...(await uploadOrSplit(p.path, spaceSeq, depth + 1, baseStartMs + p.startMs, p.durationMs, log, notify, allowSplit)));
   }
   return out;
 }

package/skills/dubbing/lib/update_check.mjs

@@ -0,0 +1,83 @@
+// Once-a-day (UTC) check against the npm registry for a newer release. Both npx and the plugin marketplace
+// install from npm, so the registry is the single source of truth. Non-blocking, fail-silent, throttled to
+// at most one network call per UTC day; never delays or fails a run. Opt out with PERSO_NO_UPDATE_CHECK.
+import { readFileSync, writeFileSync, mkdirSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { join } from 'node:path';
+import { CRED_DIR } from './config.mjs';
+import { CLIENT_VERSION } from './client_info.mjs';
+
+const PKG = 'perso-dubbing';
+const REGISTRY = `https://registry.npmjs.org/${PKG}/latest`;
+const CACHE_FILE = join(CRED_DIR, 'update-check.json');
+const TIMEOUT_MS = 3000;
+
+const utcDate = () => new Date().toISOString().slice(0, 10); // YYYY-MM-DD (UTC)
+
+function readCache() {
+  try { return JSON.parse(readFileSync(CACHE_FILE, 'utf8')); } catch { return {}; }
+}
+function writeCache(obj) {
+  try { mkdirSync(CRED_DIR, { recursive: true }); writeFileSync(CACHE_FILE, JSON.stringify(obj)); } catch { /* ignore */ }
+}
+
+// x.y.z compare: a>b → 1, a<b → -1, equal → 0. parseInt drops any pre-release/build suffix (e.g. "3-beta" → 3).
+function cmpSemver(a, b) {
+  const part = (s) => String(s).split('.').map((n) => parseInt(n, 10) || 0);
+  const pa = part(a), pb = part(b);
+  for (let i = 0; i < 3; i++) {
+    const x = pa[i] || 0, y = pb[i] || 0;
+    if (x > y) return 1;
+    if (x < y) return -1;
+  }
+  return 0;
+}
+
+async function fetchLatest() {
+  try {
+    const res = await fetch(REGISTRY, { signal: AbortSignal.timeout(TIMEOUT_MS) });
+    if (!res.ok) return null;
+    const j = await res.json();
+    return typeof j?.version === 'string' ? j.version : null;
+  } catch { return null; }
+}
+
+// Best-effort install-method guess from the running file path (marketplace copies live under a plugins dir).
+function installMethod() {
+  try {
+    const p = fileURLToPath(import.meta.url).replace(/\\/g, '/').toLowerCase();
+    if (p.includes('/plugins/') || p.includes('/marketplace')) return 'marketplace';
+  } catch { /* fall through */ }
+  return 'npx';
+}
+
+function buildNotice(latest) {
+  const lines = [`ℹ️  Update available: ${PKG} ${latest} (you have ${CLIENT_VERSION}).`];
+  if (installMethod() === 'marketplace') {
+    lines.push('   In Claude Code (plugin):  /plugin update perso-dubbing');
+    lines.push('   Otherwise (npx / manual): npx perso-dubbing@latest');
+  } else {
+    lines.push('   Update:                   npx perso-dubbing@latest');
+    lines.push('   In Claude Code (plugin):  /plugin update perso-dubbing');
+  }
+  return lines.join('\n');
+}
+
+/** Returns a one-line update notice (string) if a newer version exists, else null. Never throws.
+ *  Fetches from npm at most once per UTC day (cached); reuses the last known result otherwise. */
+export async function checkForUpdate() {
+  if (process.env.PERSO_NO_UPDATE_CHECK) return null;
+  if (CLIENT_VERSION === '0.0.0') return null; // version unknown → can't compare reliably
+
+  const today = utcDate();
+  const cache = readCache();
+  let latest = cache.latest ?? null;
+  if (cache.date !== today) {
+    const fetched = await fetchLatest();
+    latest = fetched ?? cache.latest ?? null; // keep last known on failure
+    writeCache({ date: today, latest }); // mark checked today regardless → ≤1 fetch/day
+  }
+
+  if (!latest || cmpSemver(latest, CLIENT_VERSION) <= 0) return null;
+  return buildNotice(latest);
+}

package/skills/dubbing/scripts/billing.mjs

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+// Plan upgrade & credit purchase — generates a Stripe payment link for the user to open and pay themselves.
+// The agent NEVER opens the link or pays on the user's behalf; it only relays it. Routing by current tier:
+//   free → checkout (subscribe) · starter/creator → billing (change plan) · pro/business → one-time (credits) · enterprise → contact
+import { fileURLToPath } from 'node:url';
+import { realpathSync } from 'node:fs';
+import { resolveKey, onboardingHelp, preloadKeyEnv } from './resolve_key.mjs';
+import { getPlanStatus, resolveSpace, dubbingSpaces } from '../lib/space.mjs';
+import {
+  actionForTier, getRecurringPlans, getCreditProduct, upgradeCandidates, findPriceOption,
+  currentBillingPeriod, recommendCredits, createCheckoutLink, createBillingLink, createOneTimeLink,
+  withCurrencyFallback, isCurrencyMismatch, CREDIT_PER_UNIT, DEFAULT_CURRENCY, CURRENCIES,
+} from '../lib/billing.mjs';
+import { withUtm, SUBSCRIPTION_URL } from '../lib/messages.mjs';
+
+class UsageError extends Error { constructor(m) { super(m); this.name = 'UsageError'; } }
+class ExitCode extends Error { constructor(c) { super(`exit ${c}`); this.name = 'ExitCode'; this.code = c; } }
+
+const USAGE = [
+  'Usage:',
+  '  node scripts/billing.mjs options [--shortfall <credits>] [--space "<space name>"]',
+  '  node scripts/billing.mjs link --checkout --plan <tier> --period <monthly|yearly> [--currency usd|krw] [--space "<space name>"]',
+  '  node scripts/billing.mjs link --billing  --plan <tier> [--space "<space name>"]',
+  '  node scripts/billing.mjs link --credits  --quantity <n> [--space "<space name>"]',
+  '',
+  'options  detect the current plan, show the fitting purchase flow + choices, and (with --shortfall) a recommendation',
+  'link     generate the Stripe payment link for the user\'s confirmed choice (hand it to the user; never pay for them)',
+].join('\n');
+
+const HANDOFF = 'Give this link to the user to open in their browser and complete payment. Do NOT open it or pay on their behalf.';
+const CONTACT = 'Enterprise plans have no self-serve checkout — ask the user to contact their workspace administrator.';
+
+function parseArgs(argv) {
+  const a = { inputs: [] };
+  const VALUE = { '--plan': 'plan', '--period': 'period', '--currency': 'currency', '--quantity': 'quantity', '--space': 'space', '--shortfall': 'shortfall' };
+  for (let i = 0; i < argv.length; i++) {
+    const t = argv[i];
+    if (t === '--help' || t === '-h') a.help = true;
+    else if (t === '--checkout') a.checkout = true;
+    else if (t === '--billing') a.billing = true;
+    else if (t === '--credits') a.credits = true;
+    else if (t in VALUE) {
+      const v = argv[++i];
+      if (v === undefined || v.startsWith('--')) throw new UsageError(`Missing value for ${t}`);
+      a[VALUE[t]] = v;
+    } else if (t.startsWith('--')) throw new UsageError(`Unknown option: ${t}`);
+    else a.inputs.push(t);
+  }
+  return a;
+}
+
+// --space accepts a numeric spaceSeq or a space name (matching dubbing.mjs); omitted → the pinned/only space.
+async function resolveSpaceSeq(arg) {
+  if (arg === undefined) return resolveSpace();
+  const n = Number(arg);
+  if (Number.isInteger(n) && n > 0) return n;
+  const spaces = await dubbingSpaces();
+  const hit = spaces.find((s) => s.name === arg) ?? spaces.find((s) => s.name.toLowerCase() === String(arg).toLowerCase());
+  if (!hit) throw new UsageError(`No space named "${arg}". Available: ${spaces.map((s) => s.name).join(', ')}`);
+  return hit.seq;
+}
+
+const money = (o) => (o && o.price != null ? `${String(o.price).trim()} ${String(o.priceUnit).toUpperCase()}` : '');
+
+// ---- options: show the right action + choices + recommendation for the agent to relay ----
+async function runOptions(args) {
+  const spaceSeq = await resolveSpaceSeq(args.space);
+  const plan = await getPlanStatus(spaceSeq);
+  if (!plan) throw new Error('Could not read the current plan — please try again.'); // don't mis-route a paid user to "new subscription"
+  const tier = plan.planTier ?? null;
+  const action = actionForTier(tier);
+  const shortfall = args.shortfall != null ? Number(args.shortfall) : null;
+
+  const L = [`Current plan: ${tier ?? 'unknown'} (spaceSeq ${spaceSeq}${plan?.remainingQuota != null ? `, credits left ${plan.remainingQuota}` : ''})`, `Action: ${action}`];
+
+  if (action === 'contact') { L.push(CONTACT); return void console.log(L.join('\n')); }
+
+  if (action === 'checkout') {
+    const [mo, yr] = await Promise.all([
+      getRecurringPlans(spaceSeq, { billingPeriod: 'monthly', currency: DEFAULT_CURRENCY }),
+      getRecurringPlans(spaceSeq, { billingPeriod: 'yearly', currency: DEFAULT_CURRENCY }),
+    ]);
+    L.push('', `Plans (currency ${DEFAULT_CURRENCY.toUpperCase()} by default; KRW on request):`);
+    for (const p of mo.filter((x) => x.tier !== 'enterprise' && x.tier !== 'free')) {
+      const m = p.priceOptions[0];
+      const y = findPriceOption(yr, p.tier, 'yearly')?.opt;
+      L.push(`  ${p.tier}: ${m ? `monthly ${money(m)}` : ''}${y ? `  ·  yearly ${money(y)}` : '  ·  (monthly only)'}`);
+    }
+    L.push('', 'Ask the user which plan and monthly/yearly. For heavy use suggest the top self-serve tier (pro); for very large volume, Enterprise (contact admin).');
+    L.push('Then run:  node scripts/billing.mjs link --checkout --plan <tier> --period <monthly|yearly> [--currency usd|krw]');
+    return void console.log(L.join('\n'));
+  }
+
+  if (action === 'billing') {
+    const [mo, yr] = await Promise.all([
+      getRecurringPlans(spaceSeq, { billingPeriod: 'monthly', currency: DEFAULT_CURRENCY }),
+      getRecurringPlans(spaceSeq, { billingPeriod: 'yearly', currency: DEFAULT_CURRENCY }),
+    ]);
+    const period = currentBillingPeriod([...mo, ...yr]) ?? 'monthly';
+    const list = period === 'yearly' ? yr : mo;
+    const cands = upgradeCandidates(list, tier);
+    L.push(`Current billing period: ${period} (a plan change keeps this period)`);
+    if (!cands.length) {
+      L.push('', 'No higher self-serve plan is available to switch to. For more capacity, contact your administrator (Enterprise).');
+      return void console.log(L.join('\n'));
+    }
+    L.push('', 'Change-plan options:');
+    for (const p of cands) L.push(`  ${p.tier}: ${money(p.priceOptions.find((x) => x.billingPeriod === period) ?? p.priceOptions[0])}`);
+    L.push('', 'Ask the user which plan. Recommend the top self-serve tier (pro) for large needs; for very large volume, Enterprise (contact admin). Currency auto-matches the subscription.');
+    L.push('Then run:  node scripts/billing.mjs link --billing --plan <tier>');
+    return void console.log(L.join('\n'));
+  }
+
+  // one-time (pro/business)
+  const prod = await getCreditProduct(spaceSeq);
+  if (!prod?.priceId) throw new Error('Credit product unavailable for this space.');
+  L.push('', `Credit pack: ${CREDIT_PER_UNIT} credits per pack · ${money({ price: prod.unitPrice, priceUnit: prod.priceUnit })}/pack (USD)`);
+  if (shortfall != null && shortfall > 0) {
+    const rec = recommendCredits(shortfall);
+    const cost = prod.unitPrice != null ? `, ${(rec.quantity * Number(prod.unitPrice)).toFixed(2)} ${String(prod.priceUnit).toUpperCase()}` : '';
+    L.push(`Shortfall ~${shortfall} credits → recommend ${rec.quantity} pack(s) (${rec.credits} credits${cost}).`);
+    L.push('If that quantity or amount is very large, suggest contacting the administrator (Enterprise) instead.');
+  } else {
+    L.push('Ask the user how many packs to buy.');
+  }
+  L.push('Then run:  node scripts/billing.mjs link --credits --quantity <n>');
+  console.log(L.join('\n'));
+}
+
+// ---- link: generate the Stripe URL for the confirmed choice ----
+async function runLink(args) {
+  const spaceSeq = await resolveSpaceSeq(args.space);
+  const modes = [args.checkout && 'checkout', args.billing && 'billing', args.credits && 'credits'].filter(Boolean);
+  if (modes.length !== 1) throw new UsageError('Pass exactly one of --checkout, --billing, --credits.');
+  const mode = modes[0];
+
+  if (mode === 'checkout') {
+    if (!args.plan || !args.period) throw new UsageError('--checkout needs --plan <tier> and --period <monthly|yearly>.');
+    const currency = (args.currency || DEFAULT_CURRENCY).toLowerCase();
+    if (!CURRENCIES.includes(currency)) throw new UsageError(`--currency must be one of: ${CURRENCIES.join(', ')}`);
+    const plans = await getRecurringPlans(spaceSeq, { billingPeriod: args.period, currency });
+    const sel = findPriceOption(plans, args.plan, args.period);
+    if (!sel?.opt?.priceId) throw new UsageError(`No ${args.plan} plan for ${args.period}/${currency} (starter has no yearly). Check the tier and period.`);
+    return printLink(await createCheckoutLink({ spaceSeq, priceId: sel.opt.priceId, planSeq: sel.planSeq }), `${args.plan} ${args.period} (${currency.toUpperCase()})`);
+  }
+
+  if (mode === 'billing') {
+    if (!args.plan) throw new UsageError('--billing needs --plan <tier>.');
+    // Period is locked to the current subscription and the currency must match it — try the preferred
+    // currency, then fall back to the other (PAY4052).
+    const preferred = (args.currency || DEFAULT_CURRENCY).toLowerCase();
+    if (!CURRENCIES.includes(preferred)) throw new UsageError(`--currency must be one of: ${CURRENCIES.join(', ')}`);
+    let currency, link;
+    try {
+      ({ currency, result: link } = await withCurrencyFallback(preferred, async (cur) => {
+        const [mo, yr] = await Promise.all([
+          getRecurringPlans(spaceSeq, { billingPeriod: 'monthly', currency: cur }),
+          getRecurringPlans(spaceSeq, { billingPeriod: 'yearly', currency: cur }),
+        ]);
+        const period = currentBillingPeriod([...mo, ...yr]) ?? 'monthly';
+        const sel = findPriceOption(period === 'yearly' ? yr : mo, args.plan, period);
+        if (!sel?.opt?.priceId) throw new UsageError(`No ${args.plan} plan found for the current period (${period}).`);
+        return createBillingLink({ spaceSeq, priceId: sel.opt.priceId, planSeq: sel.planSeq });
+      }));
+    } catch (e) {
+      // Stripe could not create a billing-portal session for this subscription (currency the API can't
+      // satisfy, or a subscription that needs attention). Fall back to the self-serve portal instead of
+      // surfacing the raw server error.
+      if (!isCurrencyMismatch(e)) throw e;
+      console.log('Could not generate a direct plan-change link for this subscription automatically.');
+      console.log(`Ask the user to change their plan in the Perso portal: ${withUtm(SUBSCRIPTION_URL)}`);
+      return;
+    }
+    return printLink(link, `change to ${args.plan} (${currency.toUpperCase()})`);
+  }
+
+  // credits
+  const quantity = Number(args.quantity);
+  if (!Number.isInteger(quantity) || quantity < 1) throw new UsageError('--credits needs --quantity <positive integer>.');
+  const prod = await getCreditProduct(spaceSeq);
+  if (!prod?.priceId) throw new Error('Credit product unavailable for this space.');
+  printLink(await createOneTimeLink({ spaceSeq, priceId: prod.priceId, planSeq: prod.planSeq, quantity }), `${quantity} credit pack(s) = ${quantity * CREDIT_PER_UNIT} credits`);
+}
+
+function printLink(link, what) {
+  if (!link) throw new Error('The payment service did not return a link. Please try again.');
+  console.log(`Payment link (${what}):`);
+  console.log(`  ${link}`);
+  console.log(HANDOFF);
+}
+
+async function main() {
+  let exitCode = 0;
+  try {
+    preloadKeyEnv();
+    const args = parseArgs(process.argv.slice(2));
+    const cmd = args.inputs[0];
+    if (args.help || !cmd) console.log(USAGE);
+    else if (!resolveKey()) { console.error(onboardingHelp()); exitCode = 2; }
+    else if (cmd === 'options') await runOptions(args);
+    else if (cmd === 'link') await runLink(args);
+    else throw new UsageError(`Unknown command: ${cmd}`);
+  } catch (e) {
+    if (e?.name === 'ExitCode') exitCode = e.code;
+    else if (e?.name === 'UsageError') { console.error(`${e.message}\n\n${USAGE}`); exitCode = 1; }
+    else if (e?.name === 'MissingKeyError') { console.error(onboardingHelp()); exitCode = 2; }
+    else { console.error(e?.message ?? 'Unknown error'); exitCode = 1; }
+  }
+  process.exitCode = exitCode;
+  setTimeout(() => process.exit(exitCode), 5000).unref();
+}
+
+const isMain = (() => {
+  if (!process.argv[1]) return false;
+  try { return realpathSync(process.argv[1]) === realpathSync(fileURLToPath(import.meta.url)); }
+  catch { return false; }
+})();
+if (isMain) main();
+
+export { parseArgs };

package/skills/dubbing/scripts/dubbing.mjs

@@ -13,11 +13,12 @@ import { resolveKey, onboardingHelp, preloadKeyEnv } from './resolve_key.mjs';
 import { expandInputs, prepareInput } from '../lib/input.mjs';
 import { dubbingSpaces, getPlanStatus } from '../lib/space.mjs';
 import { getLanguages } from '../lib/languages.mjs';
-import { resolveChunks, recutChunk } from '../lib/split.mjs';
+import { resolveChunks, recutChunk, SplitConfirmNeeded } from '../lib/split.mjs';
 import { runSchedule } from '../lib/scheduler.mjs';
 import { download, getStatus, upload, requestAudioSeparation, downloadSeparation } from '../lib/api_adapter.mjs';
 import { mergeGroups } from '../lib/merge.mjs';
 import { messages, withUtm, SUBSCRIPTION_URL } from '../lib/messages.mjs';
+import { checkForUpdate } from '../lib/update_check.mjs';
 import { cleanupTempDirs, makeTempDir } from '../lib/tmp.mjs';
 import { probe } from '../lib/ffmpeg.mjs';
 import { AUDIO_EXT, CREDIT_RATE_DUB, CREDIT_RATE_LIPSYNC, UHD_CREDIT_MULT, UHD_BILLED_TIERS, POLL_INTERVAL_MS, MAX_IDLE_MS } from '../lib/config.mjs';
@@ -145,6 +146,7 @@ function parseArgs(argv) {
     else if (t === '--separate') a.separate = true;
     else if (t === '--lipsync') a.lipsync = true;
     else if (t === '--force') a.force = true;
+    else if (t === '--allow-split') a.allowSplit = true; // user confirmed auto split→dub→merge (set on the re-run after [split-confirm])
     else if (t in VALUE_FLAGS) {
       const v = argv[++i];
       if (v === undefined || v.startsWith('--')) throw new UsageError(`Missing value for ${t}`);
@@ -190,6 +192,34 @@ const refOf = (inp) => (inp.source === 'local'
 // Notice text for skipping an unsupported format (append the reason if present).
 const skipMsg = (name, e) => `Skipped (unsupported format): ${name}${e?.cause?.message ? ` (${e.cause.message})` : ''}`;
 
+// [split-confirm] prompt: which limit was exceeded + the quality caveat + how to proceed. Emitted (exit 3) before
+// the first split when --allow-split isn't set; the agent relays it and re-runs with --allow-split on the user's OK.
+function splitConfirmMessage(d, tag, action = 'dub') {
+  const min = (ms) => Math.max(1, Math.round(ms / 60000));
+  const gb = (b) => (b / 1024 ** 3).toFixed(1);
+  const label = tag ? `${tag}: ` : '';
+  const noun = action === 'separate' ? 'This file' : 'This video';
+  let head;
+  if (d.reason === 'length') {
+    const lim = d.limitMs ? `${min(d.limitMs)} min` : 'the plan limit';
+    head = d.actualMs
+      ? `${noun} exceeds the length limit (${lim}; it is ${min(d.actualMs)} min).`
+      : `${noun} exceeds the length limit (${lim}).`;
+  } else {
+    head = d.actualBytes
+      ? `${noun} exceeds the 2 GB upload limit (it is ${gb(d.actualBytes)} GB).`
+      : `${noun} exceeds the 2 GB upload limit.`;
+  }
+  const mid = action === 'separate'
+    ? 'Separating it needs automatic split → separate → merge, which may come out less polished than splitting it up yourself.'
+    : 'Dubbing it needs automatic split → dub → merge, which may come out less polished than splitting it up yourself.';
+  return [
+    `[split-confirm] ${label}${head}`,
+    `[split-confirm] ${mid}`,
+    '[split-confirm] Proceed automatically? To confirm, re-run the same command with --allow-split.',
+  ].join('\n');
+}
+
 // Save directory (non-volatile): next to the local original; current folder for URL/external/unknown.
 function inputSaveDir(inp) {
   if (inp?.source === 'local' && inp.localPath) return dirname(inp.localPath);
@@ -476,8 +506,14 @@ async function runPool(args) {
     const tag = multiInput ? `[${id + 1}/${inputs.length}] ${labelOf(inp)}` : labelOf(inp);
     let chunks;
     try {
-      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify }));
+      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
     } catch (e) {
+      if (e?.name === 'SplitConfirmNeeded') {
+        console.log(splitConfirmMessage(e.details, tag));
+        // Nothing is billed yet at the split stage, so discard any partial state so the --allow-split re-run isn't blocked by the resume guard.
+        try { if (existsSync(file)) unlinkSync(file); } catch { /* ignore */ }
+        throw new ExitCode(3);
+      }
       if (isAuthError(e)) { console.log(`\n${friendlyError(e)}`); return; } // key issues abort everything
       if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; } // unsupported → skip
       console.log(`${tag} — split/upload failed: ${friendlyError(e)}`); continue;
@@ -540,6 +576,7 @@ async function creditPreflight(perInput, spaceSeq, targetCount) {
 async function runResume(file) {
   await ensureKey();
   const m = JSON.parse(readFileSync(file, 'utf8'));
+  if (m.kind === 'separation') return runResumeSeparation(m, file); // separation has its own (scheduler-less) resume
   if (m.version !== 4 && m.version !== 5) throw new Error('Unsupported state-file format — run again from the original.');
   const targets = m.targets ?? [m.opts?.target ?? 'en'];
   const multiInput = (m.inputs?.length ?? 0) > 1;
@@ -750,57 +787,188 @@ async function runLipsyncOnly(args) {
 const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
 const SEPARATION_TRACKS = ['voice', 'background', 'sub_background'];
 
+// Separation resume state (version 1, kind 'separation'): the chunk plan + a per-chunk projectId checkpoint.
+// Mirrors the dubbing manifest but keyed by inputId|chunkIndex (no target language).
+function buildSepManifest(ctx, perInput, done) {
+  return {
+    version: 1, kind: 'separation', spaceSeq: ctx.spaceSeq, out: ctx.out ?? null,
+    inputs: perInput.map((p) => ({
+      inputId: p.inputId, ref: p.ref,
+      chunks: p.chunks.map((c) => ({
+        index: c.index, source: c.source, sourceUrl: c.sourceUrl ?? null,
+        startMs: c.startMs ?? null, endMs: c.endMs ?? null, title: c.title ?? null, kind: c.kind ?? null,
+      })),
+    })),
+    done, // `${inputId}|${index}` → { status:'RUN'|'OK'|'HARD_FAIL', projectId?, reason? }
+  };
+}
+function sepSaver(ctx, perInput, prevDone = {}) {
+  const done = { ...prevDone };
+  const writeNow = () => {
+    try {
+      mkdirSync(dirname(ctx.file), { recursive: true });
+      const tmp = ctx.file + '.tmp';
+      writeFileSync(tmp, JSON.stringify(buildSepManifest(ctx, perInput, done)), 'utf8');
+      renameSync(tmp, ctx.file);
+    } catch { /* best-effort — saving state must never break the run */ }
+  };
+  return {
+    writeNow, done,
+    // The paid projectId is persisted the moment it exists → a hard kill can't cause a re-submission on resume.
+    onSubmit: (inputId, index, projectId) => { done[`${inputId}|${index}`] = { status: 'RUN', projectId }; writeNow(); },
+    onComplete: (inputId, index, projectId) => { done[`${inputId}|${index}`] = { status: 'OK', projectId }; writeNow(); },
+    onFail: (inputId, index, reason) => { done[`${inputId}|${index}`] = { status: 'HARD_FAIL', reason }; writeNow(); },
+  };
+}
+
 async function runSeparation(args) {
   await ensureKey();
   const inputs = await expandInputs(args.inputs, { recursive: args.recursive });
+  const multiInput = inputs.length > 1;
+  const file = resumePath({ out: args.out, inputs, multiInput });
+  guardExistingState(file); // block re-running the original; --resume continues without re-billing submitted parts
   const spaceSeq = await ensureSpace(args);
+  const ctx = { spaceSeq, out: args.out ?? null, file };
+  const perInput = [];
+  const saver = sepSaver(ctx, perInput);
+  // Phase 1 — resolve chunk plans (split-confirm happens here) and persist them before any submission.
+  for (let id = 0; id < inputs.length; id++) {
+    const inp = inputs[id];
+    let chunks;
+    try {
+      ({ chunks } = await resolveChunks(inp, spaceSeq, { log, notify, allowSplit: args.allowSplit }));
+    } catch (e) {
+      if (e?.name === 'SplitConfirmNeeded') {
+        console.log(splitConfirmMessage(e.details, multiInput ? labelOf(inp) : null, 'separate'));
+        try { if (existsSync(file)) unlinkSync(file); } catch { /* nothing billed yet → safe to discard */ }
+        throw new ExitCode(3);
+      }
+      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; }
+      notify(`Could not prepare: ${labelOf(inp)} — ${friendlyError(e)}`); continue;
+    }
+    if (chunks.length > 1) notify(`Split complete — ${labelOf(inp)} (${chunks.length} parts)`);
+    perInput.push({ inputId: id, inp, ref: refOf(inp), chunks });
+    saver.writeNow();
+  }
+  if (!perInput.length) { notify('No inputs to separate.'); return; }
+  notify('Separating voice/background');
+  // Phase 2 — submit (checkpointed) → wait → download → merge → save.
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, null);
+  finishSepState(file, pending);
+}
+
+// Drop the state file only when nothing paid is still owed; otherwise keep it and point at --resume (no re-billing).
+function finishSepState(file, pending) {
+  if (pending) { notify(`Some parts still need downloading — resume with: node scripts/dubbing.mjs --resume "${file}"`); return; }
+  try { if (existsSync(file)) unlinkSync(file); } catch { /* ignore */ }
+}
+
+// Resume: reload the chunk plan, re-cut/re-upload only the parts never submitted, poll/re-download the submitted ones.
+async function runResumeSeparation(m, file) {
+  if (m.version !== 1) throw new Error('Unsupported separation state-file format — run again from the original.');
+  const spaceSeq = m.spaceSeq;
+  const ctx = { spaceSeq, out: m.out ?? null, file };
+  const perInput = [];
+  const recutCache = new Map(); // `${inputId}|${index}` → re-cut path (once per part)
+  for (const pin of m.inputs) {
+    const inputStr = pin.ref.source === 'local' ? pin.ref.localPath : pin.ref.sourceUrl;
+    let localPath = null; // null when the original can't be re-prepared → materializeFor's guard fires cleanly (server-side parts still resume)
+    try { const prepared = await prepareInput(inputStr); localPath = prepared.localPath ?? prepared.path ?? null; }
+    catch (e) { console.log(`Original not available: ${pin.ref.originalName ?? inputStr ?? 'input'} (${e.message}) — server-side results only.`); }
+    perInput.push({ inputId: pin.inputId, ref: pin.ref, inp: pin.ref, chunks: pin.chunks, _localPath: localPath });
+  }
+  const saver = sepSaver(ctx, perInput, m.done ?? {});
+  const materializeFor = async (pin, c) => {
+    if (c.source === 'external') return null; // can't re-cut → upload the source URL
+    if (!pin._localPath) throw new Error('Original not found — cannot resume this part.');
+    if (c.endMs == null) return pin._localPath; // whole (unsplit) → the original
+    const mk = `${pin.inputId}|${c.index}`;
+    if (!recutCache.has(mk)) recutCache.set(mk, await recutChunk(pin._localPath, c.startMs, c.endMs));
+    return recutCache.get(mk);
+  };
+  const pending = await separationProcess(perInput, spaceSeq, ctx, saver, materializeFor);
+  finishSepState(file, pending);
+}
+
+// Per-input: separate every chunk (checkpointing each submission), merge tracks, save. Shared by run + resume.
+// Returns true when some paid part is still owed (undelivered) → the caller must keep the state file for resume.
+async function separationProcess(perInput, spaceSeq, ctx, saver, materializeFor) {
   const usedByDir = new Map();
   const lines = [];
-  let okCount = 0;
-  let failCount = 0;
-  for (const inp of inputs) {
+  let ok = 0, fail = 0;
+  const flags = { pending: false };
+  const tmp = await makeTempDir('dubbing-sep-');
+  for (const pin of perInput) {
     try {
-      const line = await separateOne(inp, spaceSeq, { out: args.out, usedByDir });
+      const byTrack = await separateChunks(pin, spaceSeq, tmp, saver, materializeFor, flags);
+      const line = await saveSeparationTracks(pin, byTrack, { out: ctx.out, usedByDir });
       lines.push(line);
-      if (line.startsWith('Done')) okCount++; else failCount++;
+      if (line.startsWith('Done')) ok++; else fail++;
     } catch (e) {
-      if (e?.httpStatus === 402) { // out of credits — deliver what finished and surface the top-up path verbatim
+      if (e?.httpStatus === 402) { // out of credits — deliver what finished + top-up/resume path, then stop
         if (lines.length) console.log('\n' + lines.join('\n'));
         const plan = await getPlanStatus(spaceSeq);
-        console.log(messages.quotaExceeded({ planTier: plan?.planTier, remainingQuota: plan?.remainingQuota }));
+        console.log(messages.quotaExceeded({ planTier: plan?.planTier, remainingQuota: plan?.remainingQuota, resumeHint: `node scripts/dubbing.mjs --resume "${ctx.file}"` }));
         throw new ExitCode(1);
       }
-      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(inp), e)); continue; }
-      failCount++;
-      lines.push(`Could not separate: ${labelOf(inp)} — ${friendlyError(e)}`);
+      if (e?.name === 'UnsupportedMediaError') { notify(skipMsg(labelOf(pin.inp ?? pin.ref), e)); continue; }
+      flags.pending = true; // errored after some chunks may have been billed → keep state so resume re-downloads them
+      fail++;
+      lines.push(`Could not separate: ${labelOf(pin.inp ?? pin.ref)} — ${friendlyError(e)}`);
     }
   }
   console.log('\n' + lines.join('\n'));
-  if (inputs.length > 1) console.log(`\nSummary: ${okCount} done · ${failCount} failed`);
+  if (perInput.length > 1) console.log(`\nSummary: ${ok} done · ${fail} failed`);
+  return flags.pending;
 }
 
-async function separateOne(inp, spaceSeq, { out, usedByDir }) {
-  const { chunks, notice } = await resolveChunks(inp, spaceSeq, { log, notify });
-  if (notice) notify(notice);
-  notify(`Separating voice/background — ${labelOf(inp)}`);
-
+// Separate one input's chunks. A chunk with a recorded projectId is polled/re-downloaded (no re-submit); the rest are
+// (re-cut/uploaded and) submitted, checkpointing the projectId the instant it exists.
+async function separateChunks(pin, spaceSeq, tmp, saver, materializeFor, flags) {
   const byTrack = new Map(SEPARATION_TRACKS.map((t) => [t, []]));
-  const tmp = await makeTempDir('dubbing-sep-');
-  for (const c of chunks) {
-    let { mediaSeq, kind = 'video' } = c;
-    if (mediaSeq == null) ({ seq: mediaSeq, kind } = await upload(refOf(inp), spaceSeq)); // external URL uploads here
-    const [projectId] = await requestAudioSeparation(spaceSeq, mediaSeq, { title: c.title, kind });
-    if (projectId == null) throw new Error('Separation request was not accepted.');
-    if (chunks.length > 1) log(`part ${c.index + 1}/${chunks.length}: separation submitted`);
-    const st = await waitForProject(projectId, spaceSeq);
-    if (st.state !== 'complete') { // a failed part becomes a gap in every track (same as dubbing merge boundaries)
-      for (const t of SEPARATION_TRACKS) byTrack.get(t).push({ index: c.index, status: 'HARD_FAIL', reason: st.message ?? st.failureReason ?? 'failed' });
-      continue;
+  const gap = (index, reason) => { for (const t of SEPARATION_TRACKS) byTrack.get(t).push({ index, status: 'HARD_FAIL', reason }); };
+  for (const c of pin.chunks) {
+    const prev = saver.done[`${pin.inputId}|${c.index}`];
+    if (prev?.status === 'HARD_FAIL') { gap(c.index, prev.reason ?? 'failed'); continue; }
+    let projectId = prev?.projectId ?? null;
+    try {
+      if (projectId == null) { // never submitted → (re-cut/upload and) submit
+        let mediaSeq = c.mediaSeq ?? null, kind = c.kind ?? 'video';
+        if (mediaSeq == null) {
+          const cut = materializeFor ? await materializeFor(pin, c) : null;
+          const ref = cut ? { source: 'local', localPath: cut, originalName: basename(cut) } // basename keeps the extension (c.title has none)
+            : (c.source === 'external' ? { source: 'external', sourceUrl: c.sourceUrl } : refOf(pin.inp ?? pin.ref));
+          ({ seq: mediaSeq, kind } = await upload(ref, spaceSeq));
+        }
+        ([projectId] = await requestAudioSeparation(spaceSeq, mediaSeq, { title: c.title, kind }));
+        if (projectId == null) throw new Error('Separation request was not accepted.');
+        saver.onSubmit(pin.inputId, c.index, projectId); // checkpoint the billed unit before any wait
+        if (pin.chunks.length > 1) log(`part ${c.index + 1}/${pin.chunks.length}: separation submitted`);
+      }
+      if (prev?.status !== 'OK') { // RUN (resume) or freshly submitted → wait for completion
+        const st = await waitForProject(projectId, spaceSeq);
+        if (st.state !== 'complete') {
+          if (st.timedOut) { flags.pending = true; gap(c.index, st.message ?? 'timed out'); continue; } // may still be running (paid) → keep the RUN checkpoint so resume re-polls it
+          saver.onFail(pin.inputId, c.index, st.message ?? st.failureReason ?? 'failed'); // genuine server failure → terminal
+          gap(c.index, st.message ?? st.failureReason ?? 'failed');
+          continue;
+        }
+        saver.onComplete(pin.inputId, c.index, projectId);
+      }
+      const tracks = await downloadSeparation(projectId, spaceSeq, (label, ext) => join(tmp, `sep_${pin.inputId}_${c.index}_${label}${ext}`));
+      for (const t of tracks) byTrack.get(t.label)?.push({ index: c.index, status: 'OK', path: t.path, name: t.fileName });
+    } catch (e) {
+      if (e?.httpStatus === 402) throw e; // credit-out → let separationProcess deliver finished parts + surface the resume path
+      // One part failed to prepare/upload/submit/download — gap it so finished sibling parts still merge & save; keep state so resume retries.
+      flags.pending = true;
+      gap(c.index, friendlyError(e));
     }
-    const tracks = await downloadSeparation(projectId, spaceSeq, (label, ext) => join(tmp, `sep_${c.index}_${label}${ext}`));
-    for (const t of tracks) byTrack.get(t.label)?.push({ index: c.index, status: 'OK', path: t.path, name: t.fileName });
   }
+  return byTrack;
+}
 
+async function saveSeparationTracks(pin, byTrack, { out, usedByDir }) {
+  const inp = pin.inp ?? pin.ref;
   const dir = out ?? inputSaveDir(inp); // --separate treats --out as a folder (three tracks per input)
   mkdirSync(dir, { recursive: true });
   const stem = String(labelOf(inp)).replace(/\.[^.\\/]+$/, '') || 'output';
@@ -836,19 +1004,21 @@ async function waitForProject(projectSeq, spaceSeq) {
     if (st?.state === 'complete' || st?.state === 'failed') return st;
     const p = st?.progress ?? -1;
     if (p !== last) { last = p; lastChange = Date.now(); if (p > 0) log(`separating... ${p}%`); }
-    if (Date.now() - lastChange > MAX_IDLE_MS) return { state: 'failed', message: 'timed out (no progress)' };
+    if (Date.now() - lastChange > MAX_IDLE_MS) return { state: 'failed', timedOut: true, message: 'timed out (no progress)' };
     await sleep(POLL_INTERVAL_MS);
   }
 }
 
 // Pure helper exports for testing (when run directly, only main below executes).
-export { parseArgs, targetPaths, buildManifest, doneEntry, manifestSaver, finishPool, refOf, resumePath, explicitOutPath, remainingMinutes, guardExistingState };
+export { parseArgs, targetPaths, buildManifest, doneEntry, manifestSaver, finishPool, refOf, resumePath, explicitOutPath, remainingMinutes, guardExistingState, splitConfirmMessage, buildSepManifest, sepSaver };
 
 async function main() {
   let exitCode = 0;
+  let updateNotice = null; // daily version check, kicked off in the background and printed after the work finishes
   try {
     preloadKeyEnv(); // pre-inject the key into env before async (at a clean point) → avoid a synchronous powershell call/crash in the main process
     const args = parseArgs(process.argv.slice(2));
+    if (!args.help) updateNotice = checkForUpdate().catch(() => null); // non-blocking; never fails the run
     if (args.help) console.log(USAGE);
     else if (args.resume) await runResume(args.resume);
     else if (args.separate) {
@@ -870,6 +1040,8 @@ async function main() {
   } finally {
     await cleanupTempDirs(); // bulk-clean the cut/schedule/merge/download temp folders
   }
+  // After the work is done (never mid-job), surface a version-update notice if one is available.
+  if (updateNotice) { try { const n = await updateNotice; if (n) console.log('\n' + n); } catch { /* ignore */ } }
   // Natural exit (loop drain) — process.exit() while fetch sockets are closing hits a Windows libuv assert
   // (async.c) that corrupts the exit code. The unref'd timer is a hard-exit fallback if a handle ever hangs.
   process.exitCode = exitCode;

package/skills/dubbing/scripts/probe_split.mjs

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