@vfrey/vfrey 0.0.1 → 1.0.0-beta.0

package/src/pipeline/stages.ts

@@ -0,0 +1,728 @@
+import path from "node:path";
+import { readableVideoPath } from "../project/names.js";
+import { storedVideoPath } from "../project/videos.js";
+import { mkdir, writeFile } from "node:fs/promises";
+import { randomUUID } from "node:crypto";
+import { ComplianceError, ConfigError, QualityError, asAppError, backoffMs } from "@vfrey/contracts";
+import { assertQualityVariation, selectVariation } from "@vfrey/contracts";
+import type { Account, Candidate, ContentPackage, PipelineData, Platform, VariationSnapshot } from "@vfrey/contracts";
+import { writePackage } from "../generate/index.js";
+import { packageFromScript, type ScriptFile } from "../generate/script.js";
+import { localDayKey } from "@vfrey/contracts";
+import { log } from "../log.js";
+import { accessToken } from "../oauth/tokens.js";
+import { TokenVault } from "../oauth/vault.js";
+import {
+  MAX_FREE_DEFERRALS,
+  POLL_WAIT_MS,
+  deferralOf,
+  proofOf,
+  publishFacebook,
+  publishInstagram,
+  publishTikTok,
+  publishYouTube,
+  type PublishContext,
+  type StoredSession,
+} from "../publish/index.js";
+import { LeaseLost, type Store, type JobRecord } from "../queue/store.js";
+import { assertScore, interpretScore } from "@vfrey/ingest";
+import { collectPerSource } from "./source-fetch.js";
+import { synthesize } from "../tts.js";
+import { engageAccount, type OwnedPost } from "../engage/index.js";
+import { captureAnalytics, writeDashboard } from "../analytics/index.js";
+import { probeVideo, type RenderedVideo } from "../render/probe.js";
+import type { Runtime, SceneRecord, SceneRenderContext } from "./run.js";
+import { readProjectEngine, chooseEngine, failedMessage, unavailableMessage } from "../product/engine-choice.js";
+import { engineStatus, type EngineProbes } from "../product/engines.js";
+import { defaultProbes } from "../product/probes.js";
+import { canonicalPath } from "../project/canonical.js";
+import { deskAccounts } from "../desk/series.js";
+import { checkScene, SceneError, storeScene } from "../scene/scene.js";
+import { topicCandidates, type UsedTopic } from "./topics-source.js";
+import { wordTotal, failureMessage, gateOutcome, mergeChecks, realTools, reviewPackage, reviewRendered, type CheckResult } from "./review.js";
+
+const PLATFORMS: Platform[] = ["youtube", "tiktok", "instagram", "facebook"];
+
+/** True when a platform session holds a real upload: a stored upload address, container, log or id. A dry-run id is not one. */
+export function hasRealSession(session: StoredSession | undefined): boolean {
+  if (!session) return false;
+  const realId = Boolean(session.externalId) && session.externalId !== "dry-run";
+  return realId || Boolean(session.uploadUrl) || Boolean(session.creationId) || Boolean(session.logId) || (session.uploadedBytes ?? 0) > 0;
+}
+
+/** Thrown at a safe point when the worker was asked to stop. The caller releases the lease. */
+export class StopRequested extends Error {
+  constructor() {
+    super("stop requested");
+    this.name = "StopRequested";
+  }
+}
+
+/** The publish stage did not finish: some platform is paused or still processing. */
+export interface PublishDeferral {
+  until: Date;
+  /** True when a platform failed in a way that should spend one of the job's attempts. */
+  countsAttempt: boolean;
+  code: string;
+  message: string;
+}
+
+export async function stageSource(runtime: Runtime, account: Account, data: PipelineData, job?: Pick<JobRecord, "id" | "attempt">): Promise<void> {
+  const manual = data.candidates.filter((candidate) => candidate.provider === "manual");
+  let fetched: Candidate[];
+  let topicsByFingerprint = new Map<string, UsedTopic>();
+  if (manual.length > 0) fetched = manual;
+  else {
+    // vfrey Topics come first: ranked, with their evidence. A failure skips only that source.
+    const topics = await topicCandidates(runtime, account, job);
+    const others = await collectPerSource(runtime, account).catch((error: unknown) => {
+      if (topics.length === 0) throw error;
+      log("warn", "other sources failed", { accountId: account.id, message: error instanceof Error ? error.message : String(error) });
+      return [] as Candidate[];
+    });
+    fetched = [...topics.map((t) => t.candidate), ...others];
+    topicsByFingerprint = new Map(topics.map((t) => [t.candidate.fingerprint, t.topic]));
+  }
+  const fresh = fetched.filter((candidate) => !runtime.store.seen(account.id, candidate.fingerprint));
+  if (fresh.length === 0) throw new QualityError("no_source", "No unseen candidates. This is a quality stop, not a compliance block.");
+  let chosen: Candidate | null = null;
+  for (const candidate of fresh) {
+    const raw = await runtime.llm.complete({
+      system: "Score a topic for an original short. Return JSON only.",
+      user: [
+        "TASK:SCORE",
+        `NICHE: ${account.niche}`,
+        `TITLE: ${candidate.title}`,
+        `EXCERPT: ${candidate.excerpt}`,
+        "Keys: score, safety, reason, riskClass, complianceTags.",
+        "complianceTags may include medical_advice_persona, legal_advice_persona, financial_advice_persona, impersonation, scam, copyrighted_transcript.",
+      ].join("\n"),
+      temperature: 0,
+      maxTokens: 400,
+    });
+    const score = interpretScore(JSON.parse(stripFence(raw)));
+    if (score.riskClass === "compliance") {
+      data.rejectedFingerprints.push(candidate.fingerprint);
+      runtime.store.markSeen(account.id, candidate.fingerprint, runtime.now());
+      log("info", "source compliance reject", { accountId: account.id, fingerprint: candidate.fingerprint, tags: score.complianceTags });
+      continue;
+    }
+    if (score.riskClass === "quality" || score.score < 70) {
+      data.rejectedFingerprints.push(candidate.fingerprint);
+      runtime.store.markSeen(account.id, candidate.fingerprint, runtime.now());
+      continue;
+    }
+    try {
+      assertScore(score);
+    } catch (error) {
+      if (error instanceof ComplianceError) {
+        data.rejectedFingerprints.push(candidate.fingerprint);
+        continue;
+      }
+      throw error;
+    }
+    chosen = candidate;
+    break;
+  }
+  if (!chosen) throw new QualityError("no_source", "Every candidate failed the score gate.");
+  data.candidates = [chosen];
+  const usedTopic = topicsByFingerprint.get(chosen.fingerprint);
+  // The agent and the script cite this: the topic, its evidence, and which topic id was used.
+  if (usedTopic) (data as PipelineData & { topic?: UsedTopic }).topic = usedTopic;
+  runtime.store.markSeen(account.id, chosen.fingerprint, runtime.now());
+}
+
+export async function stageGenerate(runtime: Runtime, account: Account, data: PipelineData): Promise<void> {
+  const candidate = data.candidates[0];
+  if (!candidate) throw new QualityError("no_source", "Generate ran without a candidate.");
+  const history = loadHistory(runtime.store, account.id, null);
+  const plan = selectVariation({
+    history,
+    voices: account.voices,
+    waiveAudioRotation: account.waiveAudioRotation,
+  });
+  // A script the agent wrote replaces the writer; every check below still runs on it.
+  const script = (data as PipelineData & { script?: ScriptFile }).script;
+  const drafted = script
+    ? packageFromScript({ script, candidate, plan, hashtagPool: account.hashtagPool })
+    : await writePackage({
+        llm: runtime.llm,
+        candidate,
+        plan,
+        niche: account.niche,
+        language: account.language,
+        hashtagPool: account.hashtagPool,
+      });
+  assertQualityVariation({
+    plan: drafted.plan,
+    hook: drafted.hook,
+    title: drafted.title,
+    hashtags: drafted.hashtags,
+    previous: history[0] ?? null,
+    voicePoolSize: account.voices.length,
+    waiveAudioRotation: account.waiveAudioRotation,
+    durationSec: drafted.durationSec,
+  });
+  data.content = { ...drafted, voiceoverPath: null, outputPath: null };
+}
+
+/**
+ * Renders the video. With the series' review switch on, the first pass stops after the script, scene and pre-render
+ * checks and returns `awaiting_review` (the caller parks the job); after Approve the same stage runs again and renders.
+ */
+export async function stageRender(runtime: Runtime, account: Account, job: JobRecord, data: PipelineData): Promise<"rendered" | "awaiting_review"> {
+  const content = data.content;
+  if (!content) throw new QualityError("no_package", "Render ran without a package.");
+  const history = loadHistory(runtime.store, account.id, job.id);
+  assertQualityVariation({
+    plan: content.plan,
+    hook: content.hook,
+    title: content.title,
+    hashtags: content.hashtags,
+    previous: history[0] ?? null,
+    voicePoolSize: account.voices.length,
+    waiveAudioRotation: account.waiveAudioRotation,
+    durationSec: content.durationSec,
+  });
+  const rendering = !runtime.skipRender && !runtime.dryRun;
+  const pending = (data as PipelineData & { scene?: SceneRecord }).scene;
+  // A scene the agent wrote: this run's flag, or the copy an earlier attempt of this job already stored.
+  const sceneSource = rendering ? (runtime.scene ?? (pending?.source === "agent" ? pending.dir : null)) : null;
+  const choice = rendering
+    ? chooseEngine({ command: runtime.engine, series: runtime.store.seriesEngine(account.id), project: readProjectEngine(), machine: runtime.store.engineDefault() })
+    : null;
+  // The quality gate, before anything is rendered. A compliance failure blocks; a quality failure rejects.
+  const before = await reviewPackage({ content, account, scene: sceneSource && choice ? { dir: sceneSource, engineId: choice.engine.id } : null });
+  recordChecks(runtime, job, data, before);
+  assertGate(before);
+  let sceneKind: SceneRecord["kind"] = null;
+  if (sceneSource && choice) {
+    try {
+      sceneKind = (await checkScene(sceneSource, choice.engine.id)).kind;
+    } catch (error) {
+      if (error instanceof SceneError) throw new ConfigError(error.code, `${error.message} Fix: ${error.fix}`);
+      throw error;
+    }
+  }
+  const holder = data as PipelineData & { review?: { state?: string } };
+  if (runtime.store.seriesGates(account.id).reviewEnabled && holder.review?.state !== "approved") {
+    // Keep the scene with the job so the person can look at it, and so the render after Approve uses this exact copy.
+    if (sceneSource && choice) {
+      const dest = path.join(runtime.config.dataDir, "scenes", job.id);
+      const stored = canonicalPath(sceneSource) === canonicalPath(dest) ? { warnings: [], bytes: pending?.bytes ?? 0, files: pending?.files ?? 0 } : await storeScene(sceneSource, dest);
+      for (const message of stored.warnings) {
+        runtime.store.recordEvent(job.id, { stage: "render", status: "warning", code: "scene_warning", message, durationMs: null, attempt: job.attempt });
+      }
+      (data as PipelineData & { scene?: SceneRecord }).scene = { source: "agent", dir: dest, kind: sceneKind, bytes: stored.bytes, files: stored.files };
+    }
+    holder.review = { state: "waiting" };
+    data.content = content;
+    return "awaiting_review";
+  }
+  const audioDir = path.join(runtime.config.dataDir, "audio");
+  const audioExt = String(runtime.config.tts.provider) === "openai" ? "mp3" : "wav";
+  const voicePath = path.join(audioDir, `${job.id}.${audioExt}`);
+  content.voiceoverPath = await synthesize({
+    provider: runtime.config.tts.provider,
+    baseUrl: runtime.config.tts.baseUrl,
+    apiKey: runtime.config.tts.apiKey,
+    model: runtime.config.tts.model,
+    voice: content.plan.voiceId,
+    text: content.voiceoverScript,
+    outputPath: voicePath,
+    fetchImpl: runtime.fetchImpl,
+  });
+  if (runtime.config.tts.provider !== "none" && !content.voiceoverPath) {
+    throw new QualityError("audio_voice", "TTS produced no file.");
+  }
+  // A real render in a project is `videos/<date> <title>.mp4`, stored relative to the project root so the folder can move.
+  // The machine desk, and any dry run or skipped render (a placeholder file), use `renders/<jobId>.mp4` in the data folder.
+  const finished = Boolean(runtime.project) && rendering;
+  const outputPath = finished
+    ? readableVideoPath(path.join(runtime.project!.root, "videos"), runtime.now(), content.title)
+    : path.join(runtime.config.dataDir, "renders", `${job.id}.mp4`);
+  content.outputPath = finished ? path.relative(runtime.project!.root, outputPath).split(path.sep).join("/") : outputPath;
+  await mkdir(path.dirname(outputPath), { recursive: true });
+  if (content.voiceoverScript.trim()) {
+    await writeFile(outputPath.replace(/\.mp4$/, ".txt"), `${content.voiceoverScript.trim()}\n`);
+  }
+  if (rendering && choice) {
+    const probe = async (): Promise<EngineProbes> => (runtime.probes ? runtime.probes() : defaultProbes(runtime.env));
+    // Remotion needs no probe. Any other engine is checked first, so a missing one fails before a render starts.
+    if (choice.engine.id !== "remotion") {
+      const probes = await probe();
+      if (engineStatus(choice.engine, probes).availability === "unavailable") {
+        throw new ConfigError("engine_unavailable", unavailableMessage(choice.engine, probes) + (choice.source === "project" ? " (This engine is the one in vfrey.json.)" : ""));
+      }
+    }
+    let sceneCtx: SceneRenderContext | undefined;
+    if (sceneSource) {
+      const dest = path.join(runtime.config.dataDir, "scenes", job.id);
+      const stored = canonicalPath(sceneSource) === canonicalPath(dest) ? { warnings: [], bytes: pending?.bytes ?? 0, files: pending?.files ?? 0 } : await storeScene(sceneSource, dest);
+      const warn = (message: string) =>
+        runtime.store.recordEvent(job.id, { stage: "render", status: "warning", code: "scene_warning", message, durationMs: null, attempt: job.attempt });
+      for (const message of stored.warnings) warn(message);
+      (data as PipelineData & { scene?: SceneRecord }).scene = { source: "agent", dir: dest, kind: sceneKind, bytes: stored.bytes, files: stored.files };
+      sceneCtx = { dir: dest, warn };
+    } else {
+      (data as PipelineData & { scene?: SceneRecord }).scene = { source: "default", dir: null, kind: null, bytes: 0, files: 0 };
+    }
+    const renderOnce = async () => {
+      try {
+        await runtime.render(content, outputPath, choice.engine.id, sceneCtx);
+      } catch (error) {
+        if (error instanceof StopRequested) throw error;
+        throw new ConfigError("engine_failed", failedMessage(choice.engine, error, await probe()));
+      }
+      (data as PipelineData & { engine?: { id: string; label: string; source?: string } }).engine = { id: choice.engine.id, label: choice.engine.label, ...(choice.source === "project" ? { source: "project" } : {}) };
+      // The length shown anywhere is the rendered file's, not the template's plan.
+      (data as PipelineData & { rendered?: RenderedVideo | null }).rendered = await probeVideo(outputPath, runtime.env);
+    };
+    await renderOnce();
+    // The quality gate, on the finished file. One re-render when only quality checks failed: a render can change that.
+    const tools = runtime.review ?? realTools(runtime.env);
+    const inspect = (attempt: number) =>
+      reviewRendered({ file: outputPath, voicePath: content.voiceoverPath, labelBurned: Boolean(sceneSource), words: wordTotal(content.voiceoverScript), tools, attempt });
+    let after = await inspect(1);
+    recordChecks(runtime, job, data, after);
+    const first = gateOutcome(after);
+    if (first.kind === "rejected" && first.retry) {
+      runtime.store.recordEvent(job.id, {
+        stage: "review",
+        status: "retrying",
+        code: failureMessage(first.failed).code,
+        message: "The finished video failed a quality check. Rendering it once more.",
+        durationMs: null,
+        attempt: job.attempt,
+      });
+      await renderOnce();
+      after = await inspect(2);
+      recordChecks(runtime, job, data, after);
+    }
+    assertGate(after);
+    log("info", "rendered", { jobId: job.id, engine: choice.engine.id, source: choice.source });
+  } else {
+    await mkdir(path.dirname(outputPath), { recursive: true });
+    await writeFile(outputPath, Buffer.from("dry-run-mp4"));
+  }
+  data.content = content;
+  return "rendered";
+}
+
+/** Keeps the latest result of each check in the payload and writes one event per failure, or one for a clean pass. */
+function recordChecks(runtime: Runtime, job: JobRecord, data: PipelineData, results: CheckResult[]): void {
+  const holder = data as PipelineData & { checks?: CheckResult[] };
+  holder.checks = mergeChecks(holder.checks, results);
+  const failed = results.filter((item) => item.status === "fail");
+  for (const item of failed) {
+    runtime.store.recordEvent(job.id, {
+      stage: "review",
+      status: "failed",
+      code: item.id,
+      message: `${item.severity}: ${item.message}${item.fix ? ` Fix: ${item.fix}` : ""}`,
+      durationMs: null,
+      attempt: job.attempt,
+    });
+  }
+  if (failed.length === 0 && results.length > 0) {
+    const phase = results[0]!.phase === "before" ? "before the render" : "on the finished video";
+    runtime.store.recordEvent(job.id, {
+      stage: "review",
+      status: "passed",
+      code: null,
+      message: `${results.filter((item) => item.status === "pass").length} checks passed ${phase}.`,
+      durationMs: null,
+      attempt: job.attempt,
+    });
+  }
+}
+
+/** Compliance failure: blocked, no retry. Quality failure: rejected. Both carry the first Fix. */
+function assertGate(results: CheckResult[]): void {
+  const outcome = gateOutcome(results);
+  if (outcome.kind === "pass") return;
+  const { code, message } = failureMessage(outcome.failed);
+  if (outcome.kind === "blocked") throw new ComplianceError(code, message);
+  throw new QualityError(code, message);
+}
+
+export async function stagePublish(
+  runtime: Runtime,
+  account: Account,
+  job: JobRecord,
+  data: PipelineData,
+): Promise<PublishDeferral | null> {
+  const content = data.content;
+  if (!content?.outputPath) throw new QualityError("no_render", "Publish ran without a file.");
+  // This job's own earlier rows are not "the previous video".
+  const history = loadHistory(runtime.store, account.id, job.id);
+  assertQualityVariation({
+    plan: content.plan,
+    hook: content.hook,
+    title: content.title,
+    hashtags: content.hashtags,
+    previous: history[0] ?? null,
+    voicePoolSize: account.voices.length,
+    waiveAudioRotation: account.waiveAudioRotation,
+    durationSec: content.durationSec,
+  });
+  const vault = new TokenVault(path.join(runtime.config.dataDir, "tokens.json"));
+  const nowMs = runtime.now().getTime();
+  // The posting cap is checked here, so a video made on request still never exceeds it. A job that
+  // already published somewhere is finishing its own video, not adding one.
+  const day = localDayKey(runtime.now(), account.cadence.timezone);
+  const postedToday = runtime.store
+    .publicationTimes(account.id, 200)
+    .filter((time) => localDayKey(time, account.cadence.timezone) === day).length;
+  const capped = !runtime.store.jobHasPublication(job.id) && postedToday >= account.cadence.maxPostsPerDay;
+  // A series that is not live runs the whole pipeline and records a dry-run publication, but never uploads.
+  const gates = runtime.store.seriesGates(account.id);
+  const dry = runtime.dryRun || !gates.live;
+  for (const platform of PLATFORMS) {
+    if (runtime.shouldStop?.()) throw new StopRequested();
+    // A cancelled or taken-over claim never starts an upload.
+    if (!runtime.store.holdsLease(job)) throw new LeaseLost(job.id);
+    const existing = data.platforms[platform] as StoredSession | undefined;
+    if (existing?.phase === "done" || existing?.phase === "skipped" || existing?.phase === "failed") {
+      if (existing.phase === "done" && existing.disclosure) recordPublication(runtime, account, job, content, platform, existing);
+      continue;
+    }
+    const enabled = account.platforms[platform]?.enabled;
+    if (!enabled) {
+      data.platforms[platform] = {
+        phase: "skipped",
+        externalId: null,
+        uploadUrl: null,
+        creationId: null,
+        logId: null,
+        disclosure: null,
+        errorCode: null,
+        errorMessage: null,
+        uploadedBytes: 0,
+      };
+      runtime.store.save(job);
+      continue;
+    }
+    // A publication row means this platform already has the video, whatever the stored session says.
+    if (runtime.store.publicationExists(job.id, platform)) {
+      data.platforms[platform] = { ...blankSession(), phase: "done", externalId: existing?.externalId ?? null };
+      runtime.store.save(job);
+      continue;
+    }
+    if (existing?.resumeAt && Date.parse(existing.resumeAt) > nowMs) continue;
+    // Publish off keeps the video and uploads nothing. A session that is not live any more is abandoned with its ids kept,
+    // never overwritten by a dry run and never started again.
+    if (!gates.publishEnabled || (dry && hasRealSession(existing))) {
+      const off = !gates.publishEnabled;
+      data.platforms[platform] = {
+        ...(existing ?? blankSession()),
+        phase: "skipped",
+        errorCode: off ? "publish_off" : "not_live",
+        errorMessage: off
+          ? "The series' publish switch is off. The video is kept and not uploaded."
+          : "The series is not live, so this unfinished upload was left alone. It will not be started again.",
+      };
+      delete (data.platforms[platform] as StoredSession).resumeAt;
+      runtime.store.save(job);
+      log("info", "publish skipped", { accountId: account.id, platform, reason: off ? "publish_off" : "not_live" });
+      continue;
+    }
+    if (capped) {
+      data.platforms[platform] = {
+        ...blankSession(),
+        phase: "skipped",
+        errorCode: "daily_cap",
+        errorMessage: `The series reached its posting cap of ${account.cadence.maxPostsPerDay} for today. The video is kept and not uploaded.`,
+      };
+      runtime.store.save(job);
+      log("info", "publish skipped", { accountId: account.id, platform, reason: "daily_cap" });
+      continue;
+    }
+    if (!dry && platformKeyMissing(account, platform, runtime.env)) {
+      const name = platform === "youtube" ? "YouTube" : platform;
+      data.platforms[platform] = {
+        ...blankSession(),
+        phase: "skipped",
+        errorCode: "missing_key",
+        errorMessage: `The ${name} key is not configured. This video cannot be pushed there.`,
+      };
+      runtime.store.save(job);
+      log("info", "publish skipped", { accountId: account.id, platform, reason: "missing_key" });
+      continue;
+    }
+    try {
+      const token = dry
+        ? "dry-run"
+        : await accessToken({
+            config: runtime.config,
+            account,
+            platform,
+            env: runtime.env,
+            vault,
+            fetchImpl: runtime.fetchImpl,
+            now: runtime.now(),
+          });
+      const ctx: PublishContext = {
+        config: runtime.config,
+        account,
+        content,
+        filePath: storedVideoPath(runtime.config.dataDir, content.outputPath),
+        fetchImpl: runtime.fetchImpl,
+        store: runtime.store,
+        now: runtime.now(),
+        env: runtime.env,
+        token,
+        dryRun: dry,
+        session: existing ?? blankSession(),
+        uploadIdleMs: runtime.uploadIdleMs,
+        checkpoint: (next) => {
+          data.platforms[platform] = next;
+          job.payload = data;
+          runtime.store.save(job);
+        },
+      };
+      const session: StoredSession =
+        platform === "youtube"
+          ? await publishYouTube(ctx)
+          : platform === "tiktok"
+            ? await publishTikTok(ctx)
+            : platform === "instagram"
+              ? await publishInstagram(ctx)
+              : await publishFacebook(ctx);
+      delete session.resumeAt;
+      delete session.resumeFree;
+      data.platforms[platform] = session;
+      data.dryRunPayloads[platform] = session.disclosure;
+      runtime.store.save(job);
+      if (session.phase === "done") recordPublication(runtime, account, job, content, platform, session);
+    } catch (error) {
+      if (error instanceof StopRequested || error instanceof LeaseLost) throw error;
+      const appError = asAppError(error);
+      const saved = (data.platforms[platform] ?? existing) as StoredSession | undefined;
+      const stored: StoredSession = {
+        phase: saved?.phase && saved.phase !== "idle" ? saved.phase : "idle",
+        externalId: saved?.externalId ?? null,
+        uploadUrl: saved?.uploadUrl ?? null,
+        creationId: saved?.creationId ?? null,
+        logId: saved?.logId ?? null,
+        disclosure: saved?.disclosure ?? null,
+        uploadedBytes: saved?.uploadedBytes ?? 0,
+        errorCode: appError.code,
+        errorMessage: appError.message,
+        errorRisk: appError.risk,
+        deferrals: saved?.deferrals ?? 0,
+      };
+      if (appError.retryable) {
+        const info = deferralOf(appError);
+        const free = info.free && stored.deferrals! < MAX_FREE_DEFERRALS;
+        if (free) stored.deferrals = stored.deferrals! + 1;
+        // Our own wait: a server pause is used as given, not cut to the backoff cap.
+        const wait = free
+          ? info.retryAfterMs ?? POLL_WAIT_MS
+          : backoffMs({ attempt: job.attempt, retryAfterMs: info.retryAfterMs, random: () => 0.5 });
+        stored.resumeAt = new Date(runtime.now().getTime() + wait).toISOString();
+        stored.resumeFree = free;
+      } else {
+        stored.phase = "failed";
+      }
+      data.platforms[platform] = stored;
+      runtime.store.save(job);
+      runtime.store.setHealth(account.id, platform, appError.retryable ? "retrying" : "blocked", appError.code, runtime.now());
+      if (!appError.retryable) {
+        log("error", "platform isolated", { accountId: account.id, platform, code: appError.code, risk: appError.risk });
+      }
+    }
+  }
+  const pending = PLATFORMS.filter((platform) => {
+    if (!account.platforms[platform]?.enabled) return false;
+    const phase = data.platforms[platform]?.phase;
+    return phase !== "done" && phase !== "skipped" && phase !== "failed";
+  });
+  if (pending.length > 0) {
+    const sessions = pending.map((platform) => data.platforms[platform] as StoredSession | undefined);
+    const times = sessions.map((item) => (item?.resumeAt ? Date.parse(item.resumeAt) : nowMs));
+    const first = sessions[times.indexOf(Math.min(...times))];
+    const summary = pending.map((platform) => `${platform}: ${data.platforms[platform]?.errorCode ?? "waiting"}`).join("; ");
+    return {
+      until: new Date(Math.min(...times)),
+      countsAttempt: sessions.some((item) => item?.resumeFree !== true),
+      code: first?.errorCode ?? "publish_pending",
+      message: summary,
+    };
+  }
+  const anyDone = PLATFORMS.some((platform) => data.platforms[platform]?.phase === "done");
+  if (!anyDone) {
+    const enabled = PLATFORMS.filter((platform) => account.platforms[platform]?.enabled);
+    if (enabled.length === 0) return null;
+    // A platform with no key never tried; it says nothing about the video.
+    const failed = enabled.filter((platform) => data.platforms[platform]?.phase === "failed");
+    if (failed.length === 0) return null;
+    const detail = "Every enabled platform failed. See per-platform error codes on the job.";
+    const risks = failed.map((platform) => data.platforms[platform]?.errorRisk);
+    // An unknown risk is treated as compliance: disclosure stays fail-closed.
+    if (risks.some((risk) => risk === "compliance" || !risk)) throw new ComplianceError("publish_all_failed", detail);
+    if (risks.some((risk) => risk === "config")) throw new ConfigError("publish_all_failed", detail);
+    throw new QualityError("publish_all_failed", detail);
+  }
+  return null;
+}
+
+function blankSession(): StoredSession {
+  return {
+    phase: "idle",
+    externalId: null,
+    uploadUrl: null,
+    creationId: null,
+    logId: null,
+    disclosure: null,
+    errorCode: null,
+    errorMessage: null,
+    uploadedBytes: 0,
+  };
+}
+
+function recordPublication(
+  runtime: Runtime,
+  account: Account,
+  job: JobRecord,
+  content: ContentPackage,
+  platform: Platform,
+  session: NonNullable<PipelineData["platforms"][Platform]>,
+): void {
+  if (!session.disclosure || runtime.store.publicationExists(job.id, platform)) return;
+  proofOf(session);
+  runtime.store.insertPublication({
+    id: randomUUID(),
+    jobId: job.id,
+    accountId: account.id,
+    platform,
+    externalId: session.externalId,
+    disclosure: session.disclosure,
+    variation: content.plan,
+    hook: content.hook,
+    title: content.title,
+    hashtags: content.hashtags,
+    script: content.voiceoverScript,
+    publishedAt: runtime.now().toISOString(),
+    audit: { logId: session.logId, uploadUrlPresent: Boolean(session.uploadUrl), ...(session.externalId === "dry-run" ? { dryRun: true } : {}) },
+  });
+}
+
+export async function runEngage(runtime: Runtime, account: Account, data: PipelineData | null): Promise<number> {
+  const posts = ownedPosts(runtime, account, data);
+  const vault = new TokenVault(path.join(runtime.config.dataDir, "tokens.json"));
+  return engageAccount({
+    config: runtime.config,
+    account,
+    posts,
+    llm: runtime.llm,
+    store: runtime.store,
+    fetchImpl: runtime.fetchImpl,
+    now: runtime.now(),
+    // Replies are public. A series that is not live drafts nothing and sends nothing.
+    dryRun: runtime.dryRun || !runtime.store.seriesGates(account.id).live,
+    tokenFor: (platform) =>
+      accessToken({
+        config: runtime.config,
+        account,
+        platform,
+        env: runtime.env,
+        vault,
+        fetchImpl: runtime.fetchImpl,
+        now: runtime.now(),
+      }),
+  });
+}
+
+/** True when no platform of this series has a key, so there is nobody to read comments from or reply to. */
+export function noPlatformKeys(runtime: Runtime, account: Account): boolean {
+  if (runtime.dryRun) return false;
+  return PLATFORMS.every((platform) => platformKeyMissing(account, platform, runtime.env));
+}
+
+function platformKeyMissing(account: Account, platform: Platform, env: Runtime["env"]): boolean {
+  const row = account.platforms[platform] as { refreshTokenEnv?: string; accessTokenEnv?: string; pageTokenEnv?: string } | undefined;
+  if (!row) return true;
+  const envName =
+    platform === "youtube" || platform === "tiktok"
+      ? row.refreshTokenEnv
+      : platform === "instagram"
+        ? row.accessTokenEnv
+        : row.pageTokenEnv;
+  if (!envName) return true;
+  return !env[envName]?.trim();
+}
+
+function ownedPosts(runtime: Runtime, account: Account, data: PipelineData | null): OwnedPost[] {
+  const posts: OwnedPost[] = [];
+  const rows = runtime.store.recentPublications(account.id, 10);
+  for (const row of rows) {
+    const platform = String(row.platform);
+    const externalId = row.external_id ? String(row.external_id) : "";
+    if (!externalId || externalId === "dry-run") continue;
+    if (platform === "youtube" || platform === "instagram" || platform === "facebook") {
+      posts.push({ platform, externalId });
+    }
+  }
+  if (data) {
+    for (const platform of ["youtube", "instagram", "facebook"] as const) {
+      const externalId = data.platforms[platform]?.externalId;
+      if (externalId && externalId !== "dry-run" && !posts.some((post) => post.externalId === externalId)) {
+        posts.push({ platform, externalId });
+      }
+    }
+  }
+  return posts;
+}
+
+export async function runAnalytics(runtime: Runtime, account: Account): Promise<void> {
+  const posts = runtime.store.recentPublications(account.id, 20).map((row) => ({
+    platform: String(row.platform),
+    externalId: row.external_id ? String(row.external_id) : "",
+  }));
+  const vault = new TokenVault(path.join(runtime.config.dataDir, "tokens.json"));
+  if (!runtime.dryRun) {
+    await captureAnalytics({
+      config: runtime.config,
+      account,
+      posts,
+      store: runtime.store,
+      fetchImpl: runtime.fetchImpl,
+      now: runtime.now(),
+      tokenFor: (platform) =>
+        accessToken({
+          config: runtime.config,
+          account,
+          platform: platform as Platform,
+          env: runtime.env,
+          vault,
+          fetchImpl: runtime.fetchImpl,
+          now: runtime.now(),
+        }),
+    });
+  }
+  await writeDashboard({
+    store: runtime.store,
+    accounts: deskAccounts(runtime.store),
+    dataDir: runtime.config.dataDir,
+    now: runtime.now(),
+  });
+}
+
+function loadHistory(store: Store, accountId: string, excludeJobId: string | null): VariationSnapshot[] {
+  return store.recentVideos(accountId, 8, excludeJobId).map((row) => {
+    const plan = JSON.parse(String(row.variation)) as VariationSnapshot;
+    return {
+      ...plan,
+      hook: String(row.hook),
+      title: String(row.title),
+      hashtags: JSON.parse(String(row.hashtags)) as string[],
+      script: String(row.script),
+    };
+  });
+}
+
+function stripFence(text: string): string {
+  const fenced = text.match(/```(?:json)?\s*([\s\S]*?)```/);
+  return (fenced?.[1] ?? text).trim();
+}