@vfrey/vfrey 0.0.1 → 1.0.0-beta.1

package/src/queue/desk-ops.ts

@@ -0,0 +1,1170 @@
+import os from "node:os";
+import { randomUUID } from "node:crypto";
+import { copyFileSync, existsSync, mkdirSync, readdirSync, statSync } from "node:fs";
+import path from "node:path";
+import { pathToFileURL } from "node:url";
+import type { DatabaseSync } from "node:sqlite";
+import { credentialsKey, encryptSecret } from "@vfrey/contracts";
+import { secretFieldError } from "../desk/secrets.js";
+import { cadenceHealth } from "../analytics/dashboard.js";
+import { mp4For } from "../project/videos.js";
+import { redact } from "./seal.js";
+
+export const CREDENTIALS_KEY_REFUSAL = "CREDENTIALS_KEY must be 32 bytes, base64.";
+
+export type DeskResult = { ok: true } | { ok: false; refusal: string };
+
+export interface JobEventRow {
+  id: number;
+  jobId: string;
+  at: string;
+  stage: string;
+  status: string;
+  attempt: number | null;
+  code: string | null;
+  message: string | null;
+  durationMs: number | null;
+}
+
+export interface EventInput {
+  stage: string;
+  status: string;
+  code: string | null;
+  message: string | null;
+  durationMs: number | null;
+  attempt?: number | null;
+}
+
+const refused = (refusal: string): DeskResult => ({ ok: false, refusal });
+const ok = (): DeskResult => ({ ok: true });
+
+function redactDeep(value: unknown): unknown {
+  if (typeof value === "string") return redact(value);
+  if (Array.isArray(value)) return value.map((item) => redactDeep(item));
+  if (!value || typeof value !== "object") return value;
+  const out: Record<string, unknown> = {};
+  for (const [key, item] of Object.entries(value as Record<string, unknown>)) {
+    if (/token|secret|key|authorization|ciphertext/i.test(key)) continue;
+    out[key] = redactDeep(item);
+  }
+  return out;
+}
+
+export function recordEvent(db: DatabaseSync, jobId: string, event: EventInput): void {
+  db.prepare(
+    `INSERT INTO job_events (job_id, at, stage, status, code, message, duration_ms, attempt) VALUES (?, ?, ?, ?, ?, ?, ?, ?)`,
+  ).run(
+    jobId,
+    new Date().toISOString(),
+    event.stage,
+    event.status,
+    event.code,
+    event.message ? redact(event.message) : null,
+    event.durationMs,
+    event.attempt ?? null,
+  );
+}
+
+/** Records the terminal event of a stage, timed from that stage's latest `running` event. */
+export function recordTerminal(db: DatabaseSync, jobId: string, event: Omit<EventInput, "durationMs">): void {
+  const started = db
+    .prepare(`SELECT at FROM job_events WHERE job_id = ? AND stage = ? AND status = 'running' ORDER BY id DESC LIMIT 1`)
+    .get(jobId, event.stage) as { at: string } | undefined;
+  const durationMs = started ? Math.max(0, Date.now() - Date.parse(started.at)) : null;
+  recordEvent(db, jobId, { ...event, durationMs });
+}
+
+export function eventsFor(db: DatabaseSync, jobId: string): JobEventRow[] {
+  const rows = db
+    .prepare(`SELECT * FROM job_events WHERE job_id = ? ORDER BY id ASC`)
+    .all(jobId) as Array<Record<string, unknown>>;
+  return rows.map((row) => ({
+    id: Number(row.id),
+    jobId: String(row.job_id),
+    at: String(row.at),
+    stage: String(row.stage),
+    status: String(row.status),
+    attempt: row.attempt == null ? null : Number(row.attempt),
+    code: row.code ? String(row.code) : null,
+    message: row.message ? redact(String(row.message)) : null,
+    durationMs: row.duration_ms == null ? null : Number(row.duration_ms),
+  }));
+}
+
+export function createAccount(db: DatabaseSync, input: { id: string; name: string; ownerId?: string | null }): void {
+  db.prepare(`INSERT INTO desk_accounts (id, name, owner_id, paused) VALUES (?, ?, ?, 0)`).run(
+    input.id,
+    input.name,
+    input.ownerId ?? null,
+  );
+}
+
+export function renameAccount(db: DatabaseSync, id: string, name: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_accounts SET name = ? WHERE id = ?`).run(name, id);
+  return changed.changes ? ok() : refused(`Account ${id} was not found.`);
+}
+
+export function deleteAccount(db: DatabaseSync, id: string): DeskResult {
+  const open = db
+    .prepare(
+      `SELECT id FROM jobs WHERE status IN ('pending', 'leased', 'awaiting_review')
+       AND (account_id = ? OR account_id IN (SELECT id FROM desk_series WHERE account_id = ?)) LIMIT 1`,
+    )
+    .get(id, id);
+  if (open) return refused("Cancel or finish the open job before deleting this account.");
+  db.prepare(`DELETE FROM desk_secrets WHERE owner_kind = 'account' AND owner_id = ?`).run(id);
+  const series = db.prepare(`SELECT id FROM desk_series WHERE account_id = ?`).all(id) as Array<{ id: string }>;
+  for (const row of series) deleteSeriesRows(db, row.id);
+  db.prepare(`DELETE FROM desk_accounts WHERE id = ?`).run(id);
+  return ok();
+}
+
+function deleteSeriesRows(db: DatabaseSync, id: string): void {
+  db.prepare(`DELETE FROM desk_secrets WHERE owner_kind = 'series' AND owner_id = ?`).run(id);
+  db.prepare(`DELETE FROM desk_sources WHERE series_id = ?`).run(id);
+  db.prepare(`DELETE FROM desk_platforms WHERE series_id = ?`).run(id);
+  db.prepare(`DELETE FROM desk_series WHERE id = ?`).run(id);
+}
+
+export function listAccounts(db: DatabaseSync): Array<Record<string, unknown>> {
+  return db.prepare(`SELECT id, name, owner_id FROM desk_accounts ORDER BY id`).all() as Array<Record<string, unknown>>;
+}
+
+export function setSecret(
+  db: DatabaseSync,
+  input: { ownerKind: "account" | "series"; ownerId: string; field: string; plaintext: string; key: string },
+): { present: boolean } | DeskResult {
+  let key: Buffer;
+  try {
+    key = credentialsKey(input.key);
+  } catch {
+    return refused(CREDENTIALS_KEY_REFUSAL);
+  }
+  const bad = secretFieldError(input.ownerKind, input.field);
+  if (bad) return refused(bad.refusal);
+  if (!input.plaintext.trim()) {
+    return { present: secretPresent(db, input.ownerKind, input.ownerId, input.field) };
+  }
+  const ciphertext = encryptSecret(input.plaintext.trim(), key);
+  db.prepare(
+    `INSERT INTO desk_secrets (owner_kind, owner_id, field, ciphertext, set_at) VALUES (?, ?, ?, ?, ?)
+     ON CONFLICT (owner_kind, owner_id, field) DO UPDATE SET ciphertext = excluded.ciphertext, set_at = excluded.set_at`,
+  ).run(input.ownerKind, input.ownerId, input.field, ciphertext, new Date().toISOString());
+  return { present: true };
+}
+
+function secretPresent(db: DatabaseSync, ownerKind: string, ownerId: string, field: string): boolean {
+  return Boolean(
+    db.prepare(`SELECT field FROM desk_secrets WHERE owner_kind = ? AND owner_id = ? AND field = ?`).get(ownerKind, ownerId, field),
+  );
+}
+
+export function clearSecret(
+  db: DatabaseSync,
+  input: { ownerKind: "account" | "series"; ownerId: string; field: string },
+): { present: false } {
+  db.prepare(`DELETE FROM desk_secrets WHERE owner_kind = ? AND owner_id = ? AND field = ?`).run(
+    input.ownerKind,
+    input.ownerId,
+    input.field,
+  );
+  return { present: false };
+}
+
+export function secretPresence(db: DatabaseSync, ownerKind: string, ownerId: string): Record<string, boolean> {
+  const rows = db
+    .prepare(`SELECT field FROM desk_secrets WHERE owner_kind = ? AND owner_id = ?`)
+    .all(ownerKind, ownerId) as Array<{ field: string }>;
+  const out: Record<string, boolean> = {};
+  for (const row of rows) out[row.field] = true;
+  return out;
+}
+
+export interface SeriesInput {
+  id: string;
+  accountId: string;
+  niche: string;
+  language?: string;
+  timezone?: string;
+  autopilot?: boolean;
+  minHoursBetweenPosts?: number;
+  maxPostsPerDay?: number;
+  windows?: string[];
+  voices?: string[];
+  hashtagPool?: string[];
+  engageEnabled?: boolean;
+  allowSpicy?: boolean;
+  maxRepliesPerDay?: number;
+  minSecondsBetween?: number;
+  youtubeDailyUploadCap?: number;
+  stylePath?: string;
+  /** A render engine id, or "" to follow the machine default. */
+  engine?: string;
+  /** New series are dry-run. Only a test or an import of a proven series passes true. The verbs go live with a typed channel id. */
+  live?: boolean;
+  /** Off: the video is made and kept, nothing uploads. Default on. */
+  publishEnabled?: boolean;
+  /** On: a job waits for approval before render (slice D). Default off. */
+  reviewEnabled?: boolean;
+}
+
+export function createSeries(db: DatabaseSync, input: SeriesInput): void {
+  db.prepare(
+    `INSERT INTO desk_series (
+      id, account_id, niche, language, autopilot, timezone, min_hours, max_posts, windows_json, voices_json,
+      hashtags_json, engage_enabled, allow_spicy, max_replies, min_seconds, upload_cap, style_path, paused
+    ) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, 0)`,
+  ).run(
+    input.id,
+    input.accountId,
+    input.niche,
+    input.language ?? "en",
+    input.autopilot === false ? 0 : 1,
+    input.timezone ?? "UTC",
+    input.minHoursBetweenPosts ?? 18,
+    input.maxPostsPerDay ?? 1,
+    JSON.stringify(input.windows ?? []),
+    JSON.stringify(input.voices ?? []),
+    JSON.stringify(input.hashtagPool ?? []),
+    input.engageEnabled === false ? 0 : 1,
+    input.allowSpicy ? 1 : 0,
+    input.maxRepliesPerDay ?? 20,
+    input.minSecondsBetween ?? 45,
+    input.youtubeDailyUploadCap ?? 90,
+    input.stylePath ?? "",
+  );
+  if (input.engine) db.prepare(`UPDATE desk_series SET engine = ? WHERE id = ?`).run(input.engine, input.id);
+  db.prepare(`UPDATE desk_series SET live = ?, publish_on = ?, review_on = ? WHERE id = ?`).run(
+    input.live ? 1 : 0,
+    input.publishEnabled === false ? 0 : 1,
+    input.reviewEnabled ? 1 : 0,
+    input.id,
+  );
+}
+
+export interface SeriesGates {
+  live: boolean;
+  publishEnabled: boolean;
+  reviewEnabled: boolean;
+}
+
+export function seriesGates(db: DatabaseSync, seriesId: string): SeriesGates {
+  const row = db.prepare(`SELECT live, publish_on, review_on FROM desk_series WHERE id = ?`).get(seriesId) as
+    | { live: number; publish_on: number; review_on: number }
+    | undefined;
+  if (!row) return { live: false, publishEnabled: true, reviewEnabled: false };
+  return { live: Number(row.live) === 1, publishEnabled: Number(row.publish_on) === 1, reviewEnabled: Number(row.review_on) === 1 };
+}
+
+export function recordSeriesEvent(db: DatabaseSync, seriesId: string, code: string, message: string): void {
+  db.prepare(`INSERT INTO series_events (series_id, at, code, message) VALUES (?, ?, ?, ?)`).run(seriesId, new Date().toISOString(), code, redact(message));
+}
+
+export function seriesEvents(db: DatabaseSync, seriesId: string, limit: number): Array<{ id: number; at: string; code: string; message: string }> {
+  const rows = db.prepare(`SELECT id, at, code, message FROM series_events WHERE series_id = ? ORDER BY id DESC LIMIT ?`).all(seriesId, limit) as Array<Record<string, unknown>>;
+  return rows.map((row) => ({ id: Number(row.id), at: String(row.at), code: String(row.code), message: String(row.message) }));
+}
+
+export function setLive(db: DatabaseSync, seriesId: string, live: boolean, message: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_series SET live = ? WHERE id = ?`).run(live ? 1 : 0, seriesId);
+  if (!changed.changes) return refused(`Series ${seriesId} was not found.`);
+  recordSeriesEvent(db, seriesId, live ? "went_live" : "went_dry_run", message);
+  return ok();
+}
+
+/**
+ * Series that existed before the live flag keep their behaviour only when they already made a real upload
+ * (a publication with an external id other than dry-run). Every other series starts in dry-run.
+ */
+export function backfillLive(db: DatabaseSync): void {
+  const rows = db
+    .prepare(
+      `SELECT id FROM desk_series WHERE id IN (
+         SELECT account_id FROM publications WHERE external_id IS NOT NULL AND external_id != 'dry-run'
+       )`,
+    )
+    .all() as Array<{ id: string }>;
+  for (const row of rows) {
+    db.prepare(`UPDATE desk_series SET live = 1 WHERE id = ?`).run(row.id);
+    recordSeriesEvent(db, row.id, "migrated_live", "Kept live: this series already had a real upload before the live flag existed.");
+  }
+}
+
+export function updateSeries(db: DatabaseSync, id: string, patch: Partial<SeriesInput>): DeskResult {
+  const current = db.prepare(`SELECT id FROM desk_series WHERE id = ?`).get(id);
+  if (!current) return refused(`Series ${id} was not found.`);
+  const sets: string[] = [];
+  const values: Array<string | number> = [];
+  const assign = (column: string, value: string | number) => {
+    sets.push(`${column} = ?`);
+    values.push(value);
+  };
+  if (patch.niche !== undefined) assign("niche", patch.niche);
+  if (patch.language !== undefined) assign("language", patch.language);
+  if (patch.timezone !== undefined) assign("timezone", patch.timezone);
+  if (patch.autopilot !== undefined) assign("autopilot", patch.autopilot ? 1 : 0);
+  if (patch.minHoursBetweenPosts !== undefined) assign("min_hours", patch.minHoursBetweenPosts);
+  if (patch.maxPostsPerDay !== undefined) assign("max_posts", patch.maxPostsPerDay);
+  if (patch.windows !== undefined) assign("windows_json", JSON.stringify(patch.windows));
+  if (patch.voices !== undefined) assign("voices_json", JSON.stringify(patch.voices));
+  if (patch.hashtagPool !== undefined) assign("hashtags_json", JSON.stringify(patch.hashtagPool));
+  if (patch.engageEnabled !== undefined) assign("engage_enabled", patch.engageEnabled ? 1 : 0);
+  if (patch.allowSpicy !== undefined) assign("allow_spicy", patch.allowSpicy ? 1 : 0);
+  if (patch.maxRepliesPerDay !== undefined) assign("max_replies", patch.maxRepliesPerDay);
+  if (patch.minSecondsBetween !== undefined) assign("min_seconds", patch.minSecondsBetween);
+  if (patch.youtubeDailyUploadCap !== undefined) assign("upload_cap", patch.youtubeDailyUploadCap);
+  if (patch.stylePath !== undefined) assign("style_path", patch.stylePath);
+  const before = seriesGates(db, id);
+  if (patch.publishEnabled !== undefined) assign("publish_on", patch.publishEnabled ? 1 : 0);
+  if (patch.reviewEnabled !== undefined) assign("review_on", patch.reviewEnabled ? 1 : 0);
+  if (patch.engine !== undefined) {
+    sets.push("engine = ?");
+    values.push(patch.engine === "" ? (null as unknown as string) : patch.engine);
+  }
+  if (sets.length === 0) return ok();
+  values.push(id);
+  db.prepare(`UPDATE desk_series SET ${sets.join(", ")} WHERE id = ?`).run(...values);
+  if (patch.publishEnabled !== undefined && patch.publishEnabled !== before.publishEnabled) {
+    recordSeriesEvent(db, id, patch.publishEnabled ? "publish_on" : "publish_off", patch.publishEnabled ? "Publish switched on." : "Publish switched off. Videos are made and kept; nothing uploads.");
+  }
+  if (patch.reviewEnabled !== undefined && patch.reviewEnabled !== before.reviewEnabled) {
+    recordSeriesEvent(db, id, patch.reviewEnabled ? "review_on" : "review_off", patch.reviewEnabled ? "Review switched on." : "Review switched off.");
+  }
+  return ok();
+}
+
+export function deleteSeries(db: DatabaseSync, id: string): DeskResult {
+  const row = db.prepare(`SELECT account_id FROM desk_series WHERE id = ?`).get(id) as { account_id: string } | undefined;
+  if (!row) return refused(`Series ${id} was not found.`);
+  // jobs.account_id stores the series id
+  const open = db.prepare(`SELECT id FROM jobs WHERE account_id = ? AND status IN ('pending', 'leased', 'awaiting_review') LIMIT 1`).get(id);
+  if (open) return refused("Cancel or finish the open job before deleting this series.");
+  deleteSeriesRows(db, id);
+  return ok();
+}
+
+export function pauseSeries(db: DatabaseSync, id: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_series SET paused = 1 WHERE id = ?`).run(id);
+  return changed.changes ? ok() : refused(`Series ${id} was not found.`);
+}
+
+export function resumeSeries(db: DatabaseSync, id: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_series SET paused = 0 WHERE id = ?`).run(id);
+  return changed.changes ? ok() : refused(`Series ${id} was not found.`);
+}
+
+export function seriesPaused(db: DatabaseSync, seriesId: string): boolean {
+  const row = db
+    .prepare(
+      `SELECT s.paused AS series_paused, a.paused AS account_paused
+       FROM desk_series s LEFT JOIN desk_accounts a ON a.id = s.account_id WHERE s.id = ?`,
+    )
+    .get(seriesId) as { series_paused: number; account_paused: number | null } | undefined;
+  if (row) return Number(row.series_paused) === 1 || Number(row.account_paused ?? 0) === 1;
+  return Boolean(db.prepare(`SELECT id FROM desk_accounts WHERE paused = 1 AND id = ?`).get(seriesId));
+}
+
+const secretKey = /token|secret|key/i;
+
+export function setPlatform(
+  db: DatabaseSync,
+  input: { seriesId: string; platform: string; enabled: boolean; config?: Record<string, unknown> },
+): DeskResult {
+  const config = input.config ?? {};
+  for (const key of Object.keys(config)) {
+    if (secretKey.test(key)) return refused(`Platform config cannot store ${key}. Use secret set.`);
+  }
+  db.prepare(
+    `INSERT INTO desk_platforms (series_id, platform, enabled, config_json) VALUES (?, ?, ?, ?)
+     ON CONFLICT (series_id, platform) DO UPDATE SET enabled = excluded.enabled, config_json = excluded.config_json`,
+  ).run(input.seriesId, input.platform, input.enabled ? 1 : 0, JSON.stringify(config));
+  return ok();
+}
+
+export function disablePlatform(db: DatabaseSync, seriesId: string, platform: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_platforms SET enabled = 0 WHERE series_id = ? AND platform = ?`).run(seriesId, platform);
+  return changed.changes ? ok() : refused(`Platform ${platform} was not found on ${seriesId}.`);
+}
+
+export function removePlatform(db: DatabaseSync, seriesId: string, platform: string): DeskResult {
+  const series = db.prepare(`SELECT account_id FROM desk_series WHERE id = ?`).get(seriesId) as { account_id: string } | undefined;
+  if (!series) return refused(`Series ${seriesId} was not found.`);
+  const published = db
+    .prepare(`SELECT id FROM publications WHERE account_id = ? AND platform = ? LIMIT 1`)
+    .get(seriesId, platform);
+  if (published) return refused("A publication exists for this platform. Disable it instead of deleting the config.");
+  db.prepare(`DELETE FROM desk_platforms WHERE series_id = ? AND platform = ?`).run(seriesId, platform);
+  return ok();
+}
+
+export function addSource(db: DatabaseSync, input: { seriesId: string; kind: string; value: string }): { id: string } {
+  const id = randomUUID();
+  db.prepare(`INSERT INTO desk_sources (id, series_id, kind, value, last_status) VALUES (?, ?, ?, ?, NULL)`).run(
+    id,
+    input.seriesId,
+    input.kind,
+    input.value,
+  );
+  return { id };
+}
+
+export function updateSource(db: DatabaseSync, id: string, value: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_sources SET value = ?, last_status = NULL, last_fetch_at = NULL, last_count = NULL, last_code = NULL WHERE id = ?`).run(value, id);
+  return changed.changes ? ok() : refused(`Source ${id} was not found.`);
+}
+
+export function removeSource(db: DatabaseSync, id: string): DeskResult {
+  const changed = db.prepare(`DELETE FROM desk_sources WHERE id = ?`).run(id);
+  return changed.changes ? ok() : refused(`Source ${id} was not found.`);
+}
+
+export function setMode(db: DatabaseSync, userId: string, mode: string, llmKeyPresent: boolean): DeskResult {
+  const value = mode === "api" ? "api" : mode === "agent" ? "agent" : "";
+  if (!value) return refused("Mode is agent or api.");
+  if (value === "api" && !llmKeyPresent) return refused("LLM_API_KEY is not set.");
+  const key = `${userId}:orchestrator.mode`;
+  db.prepare(
+    `INSERT INTO desk_settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`,
+  ).run(key, value);
+  return ok();
+}
+
+export function clearMode(db: DatabaseSync, userId: string): DeskResult {
+  db.prepare(`DELETE FROM desk_settings WHERE key = ?`).run(`${userId}:orchestrator.mode`);
+  return ok();
+}
+
+const ENGINE_DEFAULT_KEY = "engine.default";
+
+/** The machine's default engine id, or null when the person never chose one. */
+export function readEngineDefault(db: DatabaseSync): string | null {
+  const row = db.prepare(`SELECT value FROM desk_settings WHERE key = ?`).get(ENGINE_DEFAULT_KEY) as { value: string } | undefined;
+  return row?.value ?? null;
+}
+
+export function writeEngineDefault(db: DatabaseSync, engine: string): void {
+  db.prepare(
+    `INSERT INTO desk_settings (key, value) VALUES (?, ?) ON CONFLICT (key) DO UPDATE SET value = excluded.value`,
+  ).run(ENGINE_DEFAULT_KEY, engine);
+}
+
+/** The engine a series names, or null when it follows the machine default. */
+export function readSeriesEngine(db: DatabaseSync, seriesId: string): string | null {
+  const row = db.prepare(`SELECT engine FROM desk_series WHERE id = ?`).get(seriesId) as { engine: string | null } | undefined;
+  return row?.engine || null;
+}
+
+export function readMode(db: DatabaseSync, userId: string): "agent" | "api" {
+  const row = db.prepare(`SELECT value FROM desk_settings WHERE key = ?`).get(`${userId}:orchestrator.mode`) as
+    | { value: string }
+    | undefined;
+  return row?.value === "api" ? "api" : "agent";
+}
+
+export function setCadence(
+  db: DatabaseSync,
+  seriesId: string,
+  input: { timezone: string; minHoursBetweenPosts: number; maxPostsPerDay: number; windows: string[] },
+): DeskResult {
+  const changed = db
+    .prepare(`UPDATE desk_series SET timezone = ?, min_hours = ?, max_posts = ?, windows_json = ? WHERE id = ?`)
+    .run(input.timezone, input.minHoursBetweenPosts, input.maxPostsPerDay, JSON.stringify(input.windows), seriesId);
+  return changed.changes ? ok() : refused(`Series ${seriesId} was not found.`);
+}
+
+export function clearCadence(): DeskResult {
+  return refused("A series always has a cadence. Use cadence set to change it.");
+}
+
+export function setQuota(
+  db: DatabaseSync,
+  seriesId: string,
+  input: { youtubeDailyUploadCap: number; maxRepliesPerDay: number; minSecondsBetween: number },
+): DeskResult {
+  const changed = db
+    .prepare(`UPDATE desk_series SET upload_cap = ?, max_replies = ?, min_seconds = ? WHERE id = ?`)
+    .run(input.youtubeDailyUploadCap, input.maxRepliesPerDay, input.minSecondsBetween, seriesId);
+  return changed.changes ? ok() : refused(`Series ${seriesId} was not found.`);
+}
+
+export function clearQuota(): DeskResult {
+  return refused("Clearing a cap is refused. Set the cap to 0 to stop posts or replies.");
+}
+
+export function insertWarning(
+  db: DatabaseSync,
+  input: { accountId: string | null; jobId: string | null; code: string; message: string },
+): { id: string } {
+  const id = randomUUID();
+  db.prepare(
+    `INSERT INTO desk_warnings (id, account_id, job_id, code, message, created_at, acked_at) VALUES (?, ?, ?, ?, ?, ?, NULL)`,
+  ).run(id, input.accountId, input.jobId, input.code, redact(input.message), new Date().toISOString());
+  return { id };
+}
+
+export function insertWarningOnce(
+  db: DatabaseSync,
+  input: { accountId: string | null; jobId: string | null; code: string; message: string },
+): { id: string } {
+  const existing = db
+    .prepare(
+      `SELECT id FROM desk_warnings WHERE code = ? AND ifnull(account_id, '') = ? AND acked_at IS NULL LIMIT 1`,
+    )
+    .get(input.code, input.accountId ?? "") as { id: string } | undefined;
+  if (existing) return { id: existing.id };
+  return insertWarning(db, input);
+}
+
+export interface DeskOverlay {
+  id: string;
+  accountId: string;
+  niche: string;
+  language: string;
+  voices: string[];
+  hashtagPool: string[];
+  timezone: string;
+  minHoursBetweenPosts: number;
+  maxPostsPerDay: number;
+  windows: string[];
+  engageEnabled: boolean;
+  allowSpicy: boolean;
+  maxRepliesPerDay: number;
+  minSecondsBetween: number;
+  youtubeDailyUploadCap: number;
+  platforms: Array<{ platform: string; enabled: boolean; config: Record<string, unknown> }>;
+}
+
+export function deskOverlay(db: DatabaseSync, accountId: string): DeskOverlay | null {
+  const row = db
+    .prepare(
+      `SELECT * FROM desk_series WHERE id = ?`,
+    )
+    .get(accountId) as Record<string, unknown> | undefined;
+  if (!row) return null;
+  const platforms = db.prepare(`SELECT * FROM desk_platforms WHERE series_id = ?`).all(String(row.id)) as Array<
+    Record<string, unknown>
+  >;
+  return {
+    id: String(row.id),
+    accountId: String(row.account_id),
+    niche: String(row.niche),
+    language: String(row.language),
+    voices: JSON.parse(String(row.voices_json)) as string[],
+    hashtagPool: JSON.parse(String(row.hashtags_json)) as string[],
+    timezone: String(row.timezone),
+    minHoursBetweenPosts: Number(row.min_hours),
+    maxPostsPerDay: Number(row.max_posts),
+    windows: JSON.parse(String(row.windows_json)) as string[],
+    engageEnabled: Number(row.engage_enabled) === 1,
+    allowSpicy: Number(row.allow_spicy) === 1,
+    maxRepliesPerDay: Number(row.max_replies),
+    minSecondsBetween: Number(row.min_seconds),
+    youtubeDailyUploadCap: Number(row.upload_cap),
+    platforms: platforms.map((item) => ({
+      platform: String(item.platform),
+      enabled: Number(item.enabled) === 1,
+      config: JSON.parse(String(item.config_json)) as Record<string, unknown>,
+    })),
+  };
+}
+
+export function ackWarning(db: DatabaseSync, id: string): DeskResult {
+  const changed = db.prepare(`UPDATE desk_warnings SET acked_at = ? WHERE id = ?`).run(new Date().toISOString(), id);
+  return changed.changes ? ok() : refused(`Warning ${id} was not found.`);
+}
+
+export function deleteWarning(): DeskResult {
+  return refused("Warnings are acknowledged, not deleted.");
+}
+
+export function deleteJob(): DeskResult {
+  return refused("Jobs are cancelled, not deleted.");
+}
+
+export function deletePublication(): DeskResult {
+  return refused("Publications are the disclosure proof and cannot be deleted.");
+}
+
+export function deleteMetric(): DeskResult {
+  return refused("Metric snapshots cannot be deleted.");
+}
+
+export function deleteComment(): DeskResult {
+  return refused("The comment ledger cannot be deleted.");
+}
+
+function ownerAlive(owner: string): boolean {
+  const at = owner.lastIndexOf(":");
+  const pid = Number(owner.slice(at + 1));
+  if (owner.slice(0, at) !== os.hostname() || !Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "EPERM";
+  }
+}
+
+export function retryJob(db: DatabaseSync, id: string, now: Date): DeskResult {
+  const row = db.prepare(`SELECT status, stage FROM jobs WHERE id = ?`).get(id) as { status: string; stage: string } | undefined;
+  if (!row) return refused(`Job ${id} was not found.`);
+  if (row.status === "awaiting_review") return refused("This job waits for review. Approve or reject it instead of retrying it.");
+  if (row.status === "leased" || row.status === "succeeded") {
+    return refused(`A ${row.status} job cannot be retried. Cancel a leased job first.`);
+  }
+  // A cancelled job whose worker is still running may be mid-upload. Starting it again now could post the video twice.
+  const owner = db.prepare(`SELECT lease_owner, last_error FROM jobs WHERE id = ?`).get(id) as { lease_owner: string | null; last_error: string | null } | undefined;
+  if (row.status === "blocked" && owner?.last_error?.startsWith("operator_cancel") && owner.lease_owner && ownerAlive(owner.lease_owner)) {
+    return refused("The worker that held this job is still running and may be uploading. Wait for it to stop, then retry.");
+  }
+  db.prepare(
+    `UPDATE jobs SET status = 'pending', attempt = 0, lease_until = NULL, lease_owner = NULL, lease_token = NULL, run_after = ?, last_error = NULL, updated_at = ? WHERE id = ?`,
+  ).run(now.toISOString(), now.toISOString(), id);
+  recordEvent(db, id, { stage: row.stage, status: "pending", code: "retry", message: null, durationMs: null, attempt: 0 });
+  return ok();
+}
+
+export function cancelJob(db: DatabaseSync, id: string, now: Date): DeskResult {
+  const row = db.prepare(`SELECT status, stage, attempt FROM jobs WHERE id = ?`).get(id) as
+    | { status: string; stage: string; attempt: number }
+    | undefined;
+  if (!row) return refused(`Job ${id} was not found.`);
+  if (row.status !== "leased") return refused("Only a leased job can be cancelled.");
+  const message = "operator_cancel: the operator cancelled the leased job";
+  // The claim token is cleared so the running worker's next write is refused. lease_owner stays until that worker says it stopped.
+  db.prepare(`UPDATE jobs SET status = 'blocked', lease_until = NULL, lease_token = NULL, last_error = ?, updated_at = ? WHERE id = ?`).run(
+    message,
+    now.toISOString(),
+    id,
+  );
+  recordTerminal(db, id, { stage: row.stage, status: "blocked", code: "operator_cancel", message, attempt: Number(row.attempt) });
+  return ok();
+}
+
+/** The code on a job that a person rejected in review. It lives in `last_error` and in the `render` stage's event. */
+export const REVIEW_REJECTED = "review_rejected";
+
+/** The review note a job keeps in its payload: who is waiting, and how the person decided. */
+interface ReviewNote {
+  state: "waiting" | "approved" | "rejected";
+  at: string;
+  reason?: string;
+}
+
+function readPayload(raw: unknown): Record<string, unknown> {
+  try {
+    const parsed: unknown = JSON.parse(String(raw));
+    return parsed && typeof parsed === "object" ? (parsed as Record<string, unknown>) : {};
+  } catch {
+    return {};
+  }
+}
+
+/**
+ * A person approves a job that waits for review. The job goes back to `pending` and the next tick renders it from where
+ * it stopped. The update only matches a job that is still `awaiting_review`, so two approvals (two tabs, two workers)
+ * release it once and the second is refused.
+ */
+export function approveJob(db: DatabaseSync, id: string, now: Date): DeskResult {
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const row = db.prepare(`SELECT status, stage, payload FROM jobs WHERE id = ?`).get(id) as { status: string; stage: string; payload: string } | undefined;
+    if (!row) {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} was not found.`);
+    }
+    if (row.status !== "awaiting_review") {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} is ${row.status}, not waiting for review.`);
+    }
+    const payload = readPayload(row.payload);
+    const note: ReviewNote = { state: "approved", at: now.toISOString() };
+    payload.review = note;
+    const changed = db
+      .prepare(
+        `UPDATE jobs SET status = 'pending', payload = ?, run_after = ?, lease_until = NULL, lease_owner = NULL, lease_token = NULL, last_error = NULL, updated_at = ?
+         WHERE id = ? AND status = 'awaiting_review'`,
+      )
+      .run(JSON.stringify(payload), now.toISOString(), now.toISOString(), id);
+    if (Number(changed.changes) === 0) {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} is no longer waiting for review.`);
+    }
+    recordEvent(db, id, { stage: row.stage, status: "approved", code: "review_approved", message: "Approved in review. The next tick renders it.", durationMs: null, attempt: 0 });
+    db.exec("COMMIT");
+    return ok();
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+/** A person rejects a job that waits for review. It ends `rejected` with `review_rejected: <reason>`; it never renders. */
+export function rejectJob(db: DatabaseSync, id: string, reason: string | null, now: Date): DeskResult {
+  const text = (reason ?? "").trim() || "Rejected in review.";
+  db.exec("BEGIN IMMEDIATE");
+  try {
+    const row = db.prepare(`SELECT status, stage, payload FROM jobs WHERE id = ?`).get(id) as { status: string; stage: string; payload: string } | undefined;
+    if (!row) {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} was not found.`);
+    }
+    if (row.status !== "awaiting_review") {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} is ${row.status}, not waiting for review.`);
+    }
+    const payload = readPayload(row.payload);
+    const note: ReviewNote = { state: "rejected", at: now.toISOString(), reason: text };
+    payload.review = note;
+    const message = `${REVIEW_REJECTED}: ${text}`;
+    const changed = db
+      .prepare(
+        `UPDATE jobs SET status = 'rejected', payload = ?, lease_until = NULL, lease_owner = NULL, lease_token = NULL, last_error = ?, finished_at = ?, updated_at = ?
+         WHERE id = ? AND status = 'awaiting_review'`,
+      )
+      .run(JSON.stringify(payload), message, now.toISOString(), now.toISOString(), id);
+    if (Number(changed.changes) === 0) {
+      db.exec("ROLLBACK");
+      return refused(`Job ${id} is no longer waiting for review.`);
+    }
+    recordTerminal(db, id, { stage: row.stage, status: "rejected", code: REVIEW_REJECTED, message: text, attempt: 0 });
+    db.exec("COMMIT");
+    return ok();
+  } catch (error) {
+    db.exec("ROLLBACK");
+    throw error;
+  }
+}
+
+export function awaitingReviewCount(db: DatabaseSync, seriesId?: string): number {
+  const row = (seriesId
+    ? db.prepare(`SELECT COUNT(*) AS n FROM jobs WHERE status = 'awaiting_review' AND account_id = ?`).get(seriesId)
+    : db.prepare(`SELECT COUNT(*) AS n FROM jobs WHERE status = 'awaiting_review'`).get()) as { n: number };
+  return Number(row.n);
+}
+
+type Row = Record<string, unknown>;
+
+const str = (value: unknown): string => String(value);
+const strOrNull = (value: unknown): string | null => (value ? String(value) : null);
+const numOrNull = (value: unknown): number | null => (value == null ? null : Number(value));
+
+function eventView(row: JobEventRow) {
+  return {
+    id: row.id,
+    at: row.at,
+    stage: row.stage,
+    attempt: row.attempt ?? 1,
+    status: row.status,
+    code: row.code,
+    message: row.message,
+    durationMs: row.durationMs,
+  };
+}
+
+interface RenderedFacts {
+  durationSec: number | null;
+  width: number | null;
+  height: number | null;
+}
+
+function outputFor(dataDir: string | null, jobId: string, rendered: RenderedFacts = { durationSec: null, width: null, height: null }, stored: unknown = null) {
+  if (!dataDir) return { mp4: false, transcript: false, bytes: null, ...rendered };
+  const mp4 = mp4For(dataDir, jobId, stored);
+  const hasMp4 = existsSync(mp4);
+  return {
+    mp4: hasMp4,
+    transcript: existsSync(mp4.replace(/\.mp4$/, ".txt")),
+    bytes: hasMp4 ? statSync(mp4).size : null,
+    ...rendered,
+  };
+}
+
+/** One quality-gate result, as the run page shows it. */
+export interface CheckView {
+  id: string;
+  phase: "before" | "after";
+  severity: "quality" | "compliance";
+  status: "pass" | "fail" | "skipped";
+  message: string;
+  fix: string | null;
+  attempt: number;
+}
+
+function checksView(raw: unknown): CheckView[] {
+  if (!Array.isArray(raw)) return [];
+  const out: CheckView[] = [];
+  for (const item of raw as Array<Record<string, unknown>>) {
+    if (!item || typeof item.id !== "string" || typeof item.message !== "string") continue;
+    out.push({
+      id: item.id,
+      phase: item.phase === "after" ? "after" : "before",
+      severity: item.severity === "compliance" ? "compliance" : "quality",
+      status: item.status === "fail" || item.status === "skipped" ? item.status : "pass",
+      message: redact(item.message),
+      fix: typeof item.fix === "string" ? redact(item.fix) : null,
+      attempt: typeof item.attempt === "number" ? item.attempt : 1,
+    });
+  }
+  return out;
+}
+
+function jobSummary(db: DatabaseSync, row: Row, dataDir: string | null) {
+  const id = str(row.id);
+  let title: string | null = null;
+  let storedPath: unknown = null;
+  let engine: { id: string; label: string } | null = null;
+  let rendered: RenderedFacts = { durationSec: null, width: null, height: null };
+  let scene: { source: "agent" | "default"; dir: string | null; kind: "html" | "tsx" | null } | null = null;
+  let checks: CheckView[] = [];
+  try {
+    const payload = JSON.parse(str(row.payload)) as {
+      content?: { title?: unknown; outputPath?: unknown } | null;
+      engine?: { id?: unknown; label?: unknown } | null;
+      rendered?: { durationSec?: unknown; width?: unknown; height?: unknown } | null;
+      scene?: { source?: unknown; dir?: unknown; kind?: unknown } | null;
+      checks?: unknown;
+    };
+    checks = checksView(payload.checks);
+    if (payload.scene && (payload.scene.source === "agent" || payload.scene.source === "default")) {
+      scene = {
+        source: payload.scene.source,
+        dir: typeof payload.scene.dir === "string" ? payload.scene.dir : null,
+        kind: payload.scene.kind === "html" || payload.scene.kind === "tsx" ? payload.scene.kind : null,
+      };
+    }
+    const facts = payload.rendered;
+    if (facts && typeof facts.durationSec === "number" && typeof facts.width === "number" && typeof facts.height === "number") {
+      rendered = { durationSec: facts.durationSec, width: facts.width, height: facts.height };
+    }
+    if (typeof payload.content?.title === "string") title = redact(payload.content.title);
+    storedPath = payload.content?.outputPath ?? null;
+    if (typeof payload.engine?.id === "string" && typeof payload.engine.label === "string") {
+      engine = { id: payload.engine.id, label: payload.engine.label };
+    }
+  } catch {
+    title = null;
+  }
+  return {
+    id,
+    seriesId: str(row.account_id),
+    accountId: str(row.account_id),
+    kind: str(row.kind),
+    stage: str(row.stage),
+    status: str(row.status),
+    attempt: Number(row.attempt),
+    maxAttempts: Number(row.max_attempts),
+    createdAt: str(row.created_at),
+    updatedAt: str(row.updated_at),
+    runAfter: str(row.run_after),
+    leaseUntil: strOrNull(row.lease_until),
+    lastError: row.last_error ? redact(str(row.last_error)) : null,
+    title,
+    engine,
+    scene,
+    checks,
+    events: eventsFor(db, id).map(eventView),
+    output: outputFor(dataDir, id, rendered, storedPath),
+  };
+}
+
+function publicationView(row: Row) {
+  return {
+    id: str(row.id),
+    jobId: str(row.job_id),
+    accountId: str(row.account_id),
+    platform: str(row.platform),
+    externalId: strOrNull(row.external_id),
+    disclosure: redactDeep(JSON.parse(str(row.disclosure))),
+    title: redact(str(row.title)),
+    hook: redact(str(row.hook)),
+    hashtags: redactDeep(JSON.parse(str(row.hashtags))),
+    publishedAt: str(row.published_at),
+  };
+}
+
+export function buildRunDetail(db: DatabaseSync, id: string, dataDir: string | null) {
+  const row = db.prepare(`SELECT * FROM jobs WHERE id = ?`).get(id) as Row | undefined;
+  if (!row) return null;
+  let data: {
+    content?: { title?: string; hook?: string; voiceoverScript?: string; hashtags?: string[] } | null;
+    platforms?: Record<string, { phase?: string; errorCode?: string | null; errorMessage?: string | null; externalId?: string | null }>;
+  } = {};
+  try {
+    data = JSON.parse(str(row.payload));
+  } catch {
+    data = {};
+  }
+  const content = data.content
+    ? {
+        title: redact(data.content.title ?? ""),
+        hook: redact(data.content.hook ?? ""),
+        script: redact(data.content.voiceoverScript ?? ""),
+        hashtags: (data.content.hashtags ?? []).map((item) => redact(String(item))),
+      }
+    : null;
+  const publish = Object.entries(data.platforms ?? {}).map(([platform, session]) => ({
+    platform,
+    phase: session?.phase ?? "idle",
+    errorCode: session?.errorCode ?? null,
+    errorMessage: session?.errorMessage ? redact(session.errorMessage) : null,
+    externalId: session?.externalId ?? null,
+  }));
+  const publications = (
+    db.prepare(`SELECT * FROM publications WHERE job_id = ? ORDER BY published_at`).all(id) as Row[]
+  ).map(publicationView);
+  return { ...jobSummary(db, row, dataDir), content, publish, publications };
+}
+
+/** What the Review screen shows for each job that waits: the script, the scene, and every check that ran. */
+export function reviewQueue(db: DatabaseSync, dataDir: string | null) {
+  const rows = db.prepare(`SELECT id FROM jobs WHERE status = 'awaiting_review' ORDER BY updated_at ASC, rowid ASC`).all() as Array<{ id: string }>;
+  const items = [];
+  for (const row of rows) {
+    const detail = buildRunDetail(db, row.id, dataDir);
+    if (!detail) continue;
+    items.push({
+      id: detail.id,
+      seriesId: detail.seriesId,
+      title: detail.title,
+      waitingSince: detail.updatedAt,
+      content: detail.content,
+      scene: detail.scene,
+      engine: detail.engine,
+      checks: detail.checks,
+      approve: `npx vfrey desk job approve --id ${detail.id}`,
+      reject: `npx vfrey desk job reject --id ${detail.id} --reason "<why>"`,
+    });
+  }
+  return items;
+}
+
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+function seriesView(db: DatabaseSync, row: Row, now: Date) {
+  const id = str(row.id);
+  const weekAgo = new Date(now.getTime() - 7 * DAY_MS).toISOString();
+  const posts = db
+    .prepare(`SELECT COUNT(DISTINCT job_id) AS n FROM publications WHERE account_id = ? AND published_at >= ?`)
+    .get(id, weekAgo) as { n: number };
+  const postsLast7d = Number(posts.n);
+  const target = Number(row.max_posts) * 7;
+  const day = now.toISOString().slice(0, 10);
+  const uploads = db
+    .prepare(`SELECT COUNT(*) AS n FROM rate_events WHERE bucket LIKE 'youtube:uploads:%' AND bucket LIKE ?`)
+    .get(`%:${day}`) as { n: number };
+  const replies = db
+    .prepare(`SELECT COUNT(*) AS n FROM comments_handled WHERE account_id = ? AND action = 'replied' AND created_at >= ?`)
+    .get(id, `${day}T00:00:00.000Z`) as { n: number };
+  const lastReply = db
+    .prepare(`SELECT created_at FROM comments_handled WHERE account_id = ? AND action = 'replied' ORDER BY created_at DESC LIMIT 1`)
+    .get(id) as { created_at: string } | undefined;
+  return {
+    id,
+    accountId: str(row.account_id),
+    niche: str(row.niche),
+    language: str(row.language),
+    autopilot: Number(row.autopilot) === 1,
+    paused: Number(row.paused) === 1,
+    timezone: str(row.timezone),
+    minHoursBetweenPosts: Number(row.min_hours),
+    maxPostsPerDay: Number(row.max_posts),
+    windows: JSON.parse(str(row.windows_json)) as string[],
+    voices: JSON.parse(str(row.voices_json)) as string[],
+    hashtagPool: JSON.parse(str(row.hashtags_json)) as string[],
+    engageEnabled: Number(row.engage_enabled) === 1,
+    allowSpicy: Number(row.allow_spicy) === 1,
+    maxRepliesPerDay: Number(row.max_replies),
+    minSecondsBetween: Number(row.min_seconds),
+    youtubeDailyUploadCap: Number(row.upload_cap),
+    stylePath: str(row.style_path),
+    engine: strOrNull(row.engine),
+    live: Number(row.live) === 1,
+    publishEnabled: Number(row.publish_on) === 1,
+    reviewEnabled: Number(row.review_on) === 1,
+    events: seriesEvents(db, id, 8),
+    cadence: { label: cadenceHealth(postsLast7d, target), postsLast7d, target },
+    quota: {
+      uploadsToday: Number(uploads.n),
+      repliesToday: Number(replies.n),
+      lastReplyAt: lastReply?.created_at ?? null,
+    },
+  };
+}
+
+/** The database-derived fields of `State` in docs/spec/contracts/desk-api.md. */
+export function buildSnapshot(db: DatabaseSync, userId: string, dataDir: string | null = null): Record<string, unknown> {
+  const now = new Date();
+  const accounts = (db.prepare(`SELECT id, name, owner_id FROM desk_accounts ORDER BY id`).all() as Row[]).map((row) => ({
+    id: str(row.id),
+    name: str(row.name),
+    ownerId: strOrNull(row.owner_id),
+    seriesCount: Number(
+      (db.prepare(`SELECT COUNT(*) AS n FROM desk_series WHERE account_id = ?`).get(str(row.id)) as { n: number }).n,
+    ),
+  }));
+  const credentials = (
+    db.prepare(`SELECT owner_kind, owner_id, field, set_at FROM desk_secrets ORDER BY owner_kind, owner_id, field`).all() as Row[]
+  ).map((row) => ({ ownerKind: str(row.owner_kind), ownerId: str(row.owner_id), field: str(row.field), present: true, setAt: strOrNull(row.set_at) }));
+  const series = (db.prepare(`SELECT * FROM desk_series ORDER BY id`).all() as Row[]).map((row) => seriesView(db, row, now));
+  const platforms = (db.prepare(`SELECT * FROM desk_platforms ORDER BY series_id, platform`).all() as Row[]).map((row) => ({
+    seriesId: str(row.series_id),
+    platform: str(row.platform),
+    enabled: Number(row.enabled) === 1,
+    config: redactDeep(JSON.parse(str(row.config_json))),
+  }));
+  const sources = (db.prepare(`SELECT * FROM desk_sources ORDER BY id`).all() as Row[]).map((row) => ({
+    id: str(row.id),
+    seriesId: str(row.series_id),
+    kind: str(row.kind),
+    value: str(row.value),
+    lastStatus: strOrNull(row.last_status),
+    lastFetchAt: strOrNull(row.last_fetch_at),
+    lastCount: numOrNull(row.last_count),
+    lastCode: strOrNull(row.last_code),
+  }));
+  const jobs = (db.prepare(`SELECT * FROM jobs ORDER BY created_at DESC, rowid DESC LIMIT 200`).all() as Row[]).map((row) =>
+    jobSummary(db, row, dataDir),
+  );
+  const publications = (db.prepare(`SELECT * FROM publications ORDER BY published_at`).all() as Row[]).map(publicationView);
+  const seenPosts = new Set<string>();
+  const metrics: Array<Record<string, unknown>> = [];
+  for (const row of db.prepare(`SELECT * FROM metrics ORDER BY captured_at DESC, rowid DESC`).all() as Row[]) {
+    const post = `${str(row.platform)}:${str(row.external_id)}`;
+    if (seenPosts.has(post)) continue;
+    seenPosts.add(post);
+    metrics.push({
+      id: str(row.id),
+      accountId: str(row.account_id),
+      platform: str(row.platform),
+      externalId: str(row.external_id),
+      capturedAt: str(row.captured_at),
+      views: numOrNull(row.views),
+      watchTimeSec: numOrNull(row.watch_time_sec),
+      retention: numOrNull(row.retention),
+      estimatedRevenue: str(row.revenue_status) === "present" ? numOrNull(row.estimated_revenue) : null,
+      revenueStatus: str(row.revenue_status),
+    });
+  }
+  const comments = (db.prepare(`SELECT * FROM comments_handled ORDER BY created_at`).all() as Row[]).map((row) => ({
+    platform: str(row.platform),
+    commentId: str(row.comment_id),
+    accountId: str(row.account_id),
+    action: str(row.action),
+    tone: strOrNull(row.tone),
+    replyText: row.reply_text ? redact(str(row.reply_text)) : null,
+    createdAt: str(row.created_at),
+  }));
+  const warnings = (
+    db.prepare(`SELECT * FROM desk_warnings ORDER BY (acked_at IS NOT NULL), created_at DESC, rowid DESC`).all() as Row[]
+  ).map((row) => ({
+    id: str(row.id),
+    accountId: strOrNull(row.account_id),
+    jobId: strOrNull(row.job_id),
+    code: str(row.code),
+    message: redact(str(row.message)),
+    createdAt: str(row.created_at),
+    ackedAt: strOrNull(row.acked_at),
+  }));
+  return {
+    accounts,
+    credentials,
+    series,
+    platforms,
+    sources,
+    mode: readMode(db, userId),
+    jobs,
+    publications,
+    metrics,
+    comments,
+    warnings,
+  };
+}
+
+/** Tables copied from a legacy per-folder database. Every one has a primary key, so OR IGNORE keeps existing rows. */
+const IMPORT_TABLES = [
+  "jobs",
+  "publications",
+  "metrics",
+  "comments_handled",
+  "source_seen",
+  "account_health",
+  "desk_warnings",
+  "desk_accounts",
+  "desk_series",
+  "desk_platforms",
+  "desk_sources",
+  "desk_settings",
+];
+
+function sharedColumns(db: DatabaseSync, table: string, skip: string[] = []): string[] {
+  const names = (schema: string) =>
+    (db.prepare(`PRAGMA ${schema}.table_info(${table})`).all() as Array<{ name: string }>).map((row) => row.name);
+  const legacy = new Set(names("legacy"));
+  return names("main").filter((name) => legacy.has(name) && !skip.includes(name));
+}
+
+/**
+ * Merges a legacy `<dir>/pipeline.sqlite` into this database. Existing rows are kept, so a second run adds nothing.
+ * `rate_events` and `desk_secrets` are not copied: rate windows are short, and old secrets use a cipher nothing reads.
+ */
+export function importLegacy(
+  db: DatabaseSync,
+  targetDir: string | null,
+  fromDir: string,
+): { imported: Record<string, number>; files: number } {
+  const file = path.join(fromDir, "pipeline.sqlite");
+  db.prepare(`ATTACH DATABASE ? AS legacy`).run(`${pathToFileURL(file).href}?mode=ro`);
+  const imported: Record<string, number> = {};
+  try {
+    const present = new Set(
+      (db.prepare(`SELECT name FROM legacy.sqlite_master WHERE type = 'table'`).all() as Array<{ name: string }>).map((row) => row.name),
+    );
+    db.exec("BEGIN");
+    try {
+      for (const table of IMPORT_TABLES) {
+        if (!present.has(table)) continue;
+        const columns = sharedColumns(db, table);
+        const list = columns.join(", ");
+        imported[table] = Number(
+          db.prepare(`INSERT OR IGNORE INTO main.${table} (${list}) SELECT ${list} FROM legacy.${table}`).run().changes,
+        );
+      }
+      if (present.has("job_events")) {
+        const columns = sharedColumns(db, "job_events", ["id"]);
+        const list = columns.join(", ");
+        imported.job_events = Number(
+          db
+            .prepare(
+              `INSERT INTO main.job_events (${list}) SELECT ${list} FROM legacy.job_events l
+               WHERE NOT EXISTS (
+                 SELECT 1 FROM main.job_events m
+                 WHERE m.job_id = l.job_id AND m.at = l.at AND m.stage = l.stage AND m.status = l.status
+               )`,
+            )
+            .run().changes,
+        );
+      }
+      db.exec("COMMIT");
+    } catch (error) {
+      db.exec("ROLLBACK");
+      throw error;
+    }
+  } finally {
+    db.exec("DETACH DATABASE legacy");
+  }
+  let files = 0;
+  const rendersFrom = path.join(fromDir, "renders");
+  if (targetDir && existsSync(rendersFrom)) {
+    const rendersTo = path.join(targetDir, "renders");
+    for (const name of readdirSync(rendersFrom)) {
+      if (!/\.(mp4|txt)$/.test(name)) continue;
+      const to = path.join(rendersTo, name);
+      if (existsSync(to)) continue;
+      mkdirSync(rendersTo, { recursive: true });
+      copyFileSync(path.join(rendersFrom, name), to);
+      files += 1;
+    }
+  }
+  return { imported, files };
+}