animastor-worker 2.1.0

package/.env.example

@@ -0,0 +1,34 @@
+# Animastor Private Worker — environment (copy to .env next to worker.cjs)
+# worker.cjs (and start-worker.sh) load this file automatically; you can also
+# export these variables directly. NEVER commit a real credential.
+
+# ── REQUIRED ──────────────────────────────────────────────────────────────
+# GPU Hub base URL — the same origin you use in the browser, plus /gpu.
+HUB_URL=https://animastor.in/gpu
+
+# Private Worker credential — shown ONCE in Settings → Private Workers at
+# creation/rotation. Fail-closed: without it the worker refuses to start.
+ANIMASTOR_WORKER_TOKEN=<your-worker-key>
+
+# Worker type: image | audio | video (must match the type chosen in the UI).
+WORKER_TYPE=image
+
+# Worker label (any short id; with a token, identity comes from the token).
+WORKER_ID=my-private-worker
+
+# ── OPTIONAL (defaults shown) ─────────────────────────────────────────────
+# ComfyUI HTTP API port (auto-detected from a running ComfyUI if unset).
+#COMFY_PORT=8188
+# ComfyUI input directory (default: $HOME/ComfyUI/input).
+#COMFY_INPUT_DIR=/home/you/ComfyUI/input
+# Worker-local cleanup journal dir (crash-safe recovery; default: next to worker.cjs).
+#WORKER_JOURNAL_DIR=/home/you/animastor/cleanup-journal
+# Reverse-proxy base path in front of ComfyUI (e.g. notebook deployments).
+#NOTEBOOK_PATH=
+#
+# ── Hugging Face (for gated/private models) ────────────────────────────────
+# System HF token — used by the installer to download gated models.
+# Set via environment variable; never commit the token to a file.
+# The installer uses HF_TOKEN or HUGGINGFACE_HUB_TOKEN (either works).
+# HF_TOKEN=
+# HUGGINGFACE_HUB_TOKEN=

package/job-protocol-v2.cjs

@@ -0,0 +1,291 @@
+// ======================================================
+// GENERATED FILE — DO NOT EDIT BY HAND
+// ======================================================
+// Generated copy of the canonical Job Protocol v2 implementation:
+//   package:   @animastor/contracts
+//   source:    contracts/src/job-protocol-v2.js
+//   sha256:    b005fafc01614e643e325b3433f657c6bd197ee6f76dca4d36eb1bf7de2b5a84
+//   generated: 0.1.0 snapshot
+// Generator:  worker/tools/sync-protocol.cjs (Phase 9D — blocker B2, option B)
+//
+// The worker bundle ships with zero runtime npm dependencies (Phase 9B
+// freeze) and is delivered to GPU machines without an npm registry, so it
+// cannot require @animastor/contracts at runtime. This file is a byte-exact
+// copy of the canonical source below the marker line — it is NOT a second
+// implementation. Any edit here diverges the wire contract and will be
+// caught by the parity guards:
+//   worker/tests/job-protocol.test.cjs
+//   backend/tests/architecture/phase9d-worker-package.test.js
+//
+// Regenerate after any change to the canonical source:
+//   node worker/tools/sync-protocol.cjs
+
+// ===8<=== canonical source (verbatim, do not edit) ====================
+// ======================================================
+// @animastor/contracts — Job Protocol v2 (canonical implementation)
+// ======================================================
+// CANONICAL SOURCE OF TRUTH for the frozen Job Protocol v2 wire contract
+// (docs/architecture/JOB_PROTOCOL_V2.md — NORMATIVE, FROZEN, Phase 9A).
+//
+// Extracted verbatim from backend/src/runtime/job-schema.js (Phase 9C).
+// Consumers: backend (via the job-schema.js facade), gpu-hub, worker.
+//
+// NO business logic lives here: only protocol constants, job_id grammar,
+// stage mapping and envelope/error contract helpers — exactly the surface
+// the protocol defines, no more.
+//
+// Versioning: PROTOCOL_VERSION changes only via the versioning policy
+// (JOB_PROTOCOL_V2.md §4) — coordinated bump in backend + gpu-hub + worker
+// after old workers stop receiving tasks. Mixed-version rollout is NOT
+// supported. ======================================================
+
+// Job Protocol version backend ↔ gpu-hub ↔ worker. Sent in the task and
+// callback payloads. All three components reject a mismatching version:
+// mixed-version rollout is allowed only after old workers stop receiving
+// tasks. [NORMATIVE — FROZEN: value 2 for the entire Phase 9]
+const PROTOCOL_VERSION = 2; // T4: dispatch_id added
+
+// Asset-type family carried by the job_id suffix (`${assetId}:${type}`).
+// `iu_image` is an asset type only: on the transport it travels as
+// job_type = 'image', stage = 'image' (JOB_PROTOCOL_V2.md §3.4).
+const JOB_TYPES = ['audio', 'image', 'iu_image', 'video'];
+
+// Transport-type family of the hub scan queues / queue keys
+// (`queue:{type}...`). `iu_image` never appears here as a type: it is
+// routed with job_type 'image'. Mirrors gpu-hub SYSTEM_JOB_TYPES.
+const SYSTEM_JOB_TYPES = ['audio', 'image', 'video'];
+
+// kind (parse result) → stage (envelope / result-key segment).
+const STAGE_BY_KIND = {
+    audio_chunk: 'audio',
+    iu_image: 'image',
+    scene_image: 'image',
+    scene_video: 'video',
+};
+
+// job_id grammar regexes [NORMATIVE — FROZEN]:
+//   audio chunk:     {bookId}_{chapterId}_{sceneId}_{NNNN}:audio   (NNNN = pad(4))
+//   IU image:        {bookId}_{chapterId}_{sceneId}_{iuId}:iu_image
+//   scene image:     {bookId}_{chapterId}_{sceneId}:image          (legacy; assetId
+//                    containing '_iu' = old-format IU image)
+//   video:           {bookId}_{chapterId}_{sceneId}[_gN]:video     (_gN = group)
+// bookId may contain '_'; chapterId/sceneId/chunkIndex/iuId may not, so
+// parsing always goes from the end.
+const CHUNK_INDEX_RE = /^\d{4}$/;
+const GROUP_SUFFIX_RE = /^(.+?)(_g\d+)$/;
+// Worker-side input-file naming split family (worker.cjs inline literals).
+const JOB_ID_SPLIT_RE = /:(iu_image|image|audio|video)$/;
+
+const JOB_TYPES_SET = new Set(JOB_TYPES);
+
+function buildJobId(assetId, type) {
+    if (!assetId || typeof assetId !== 'string') {
+        throw new Error(`buildJobId: invalid assetId: ${assetId}`);
+    }
+    if (!JOB_TYPES.includes(type)) {
+        throw new Error(`buildJobId: unknown job type: ${type}`);
+    }
+    return `${assetId}:${type}`;
+}
+
+// Strips the type suffix. Returns { assetId, type } or null.
+function splitJobId(jobId) {
+    if (!jobId || typeof jobId !== 'string') return null;
+    const idx = jobId.lastIndexOf(':');
+    if (idx === -1) return null;
+    const type = jobId.slice(idx + 1);
+    if (!JOB_TYPES_SET.has(type)) return null;
+    return { assetId: jobId.slice(0, idx), type };
+}
+
+// Full parse. Returns null for unrecognizable ids (never throws).
+// kind: 'audio_chunk' | 'iu_image' | 'scene_image' | 'scene_video'
+function parseJobId(jobId) {
+    const split = splitJobId(jobId);
+    if (!split) return null;
+    const { assetId, type } = split;
+
+    if (type === 'audio') {
+        const parts = assetId.split('_');
+        if (parts.length < 4) return null;
+        const chunkIndex = parts.pop();
+        if (!CHUNK_INDEX_RE.test(chunkIndex)) return null;
+        const sceneId = parts.pop();
+        const chapterId = parts.pop();
+        return {
+            kind: 'audio_chunk', type, assetId,
+            bookId: parts.join('_'), chapterId, sceneId, chunkIndex,
+        };
+    }
+
+    if (type === 'iu_image' || (type === 'image' && assetId.includes('_iu'))) {
+        const parts = assetId.split('_');
+        if (parts.length < 4) return null;
+        const iuId = parts.pop();
+        const sceneId = parts.pop();
+        const chapterId = parts.pop();
+        return {
+            kind: 'iu_image', type, assetId,
+            bookId: parts.join('_'), chapterId, sceneId, iuId,
+        };
+    }
+
+    if (type === 'image') {
+        const parts = assetId.split('_');
+        if (parts.length < 3) return null;
+        const sceneId = parts.pop();
+        const chapterId = parts.pop();
+        return {
+            kind: 'scene_image', type, assetId,
+            bookId: parts.join('_'), chapterId, sceneId,
+        };
+    }
+
+    if (type === 'video') {
+        let base = assetId;
+        let groupSuffix = '';
+        const groupMatch = base.match(GROUP_SUFFIX_RE);
+        if (groupMatch) {
+            base = groupMatch[1];
+            groupSuffix = groupMatch[2];
+        }
+        const parts = base.split('_');
+        if (parts.length < 3) return null;
+        const sceneId = parts.pop();
+        const chapterId = parts.pop();
+        return {
+            kind: 'scene_video', type, assetId,
+            bookId: parts.join('_'), chapterId, sceneId, groupSuffix,
+        };
+    }
+
+    return null;
+}
+
+function getStageForJobId(jobId) {
+    const parsed = parseJobId(jobId);
+    if (!parsed) return null;
+    return STAGE_BY_KIND[parsed.kind] || null;
+}
+
+// ------------------------------------------------------
+// Envelope contract helpers (JOB_PROTOCOL_V2.md §3.2, §3.10, §3.11, §3.12)
+// ------------------------------------------------------
+// Field-sets copied from the frozen envelope tables. They document the
+// contract and let consumers cross-check their payloads without importing
+// business logic. The hub's runtime validation order/behavior is NOT
+// reproduced here — helpers are advisory (unknown fields must be ignored,
+// JOB_PROTOCOL_V2.md §3.20).
+
+// Task envelope (backend → hub → worker). Identity fields below are the
+// hub's formal required set; the hub does not validate job_id/job_type/
+// params (completeness is guaranteed by the backend dispatcher).
+const TASK_ENVELOPE_REQUIRED_FIELDS = [
+    'dispatch_id', 'build_id', 'book_id', 'chapter_id', 'scene_id',
+    'stage', 'protocol_version',
+];
+const TASK_ENVELOPE_FIELDS = [
+    'job_id', 'params', 'job_type', 'assets', 'build_id',
+    'protocol_version', 'book_id', 'chapter_id', 'scene_id', 'stage',
+    'dispatch_id', 'workspace_id', 'policy_id', 'timeout_ms',
+];
+
+// Result envelope (worker → hub → backend), required field set.
+const RESULT_ENVELOPE_REQUIRED_FIELDS = [
+    'job_id', 'build_id', 'dispatch_id', 'protocol_version', 'result_base64',
+];
+
+// Error envelope (worker → hub → backend), required field set.
+const ERROR_ENVELOPE_REQUIRED_FIELDS = [
+    'job_id', 'build_id', 'dispatch_id', 'protocol_version',
+];
+
+// Beacon envelope (worker → hub), required field set.
+const BEACON_ENVELOPE_REQUIRED_FIELDS = ['protocol_version'];
+
+// Canonical error tokens of the wire contract (JOB_PROTOCOL_V2.md §3.13).
+const ERROR_TOKENS = {
+    PROTOCOL_VERSION_MISMATCH: 'protocol_version_mismatch',
+    INCOMPLETE_DISPATCH_IDENTITY: 'incomplete_dispatch_identity',
+    INVALID_WORKSPACE_ID: 'invalid_workspace_id',
+    INVALID_POLICY_ID: 'invalid_policy_id',
+    INVALID_POLICY_ROUTING: 'invalid_policy_routing',
+    INVALID: 'invalid',
+    NOT_TASK_CLAIMER: 'not_task_claimer',
+    STALE_OR_UNKNOWN_DISPATCH: 'stale_or_unknown_dispatch',
+    WORKER_PROTOCOL_MISMATCH: 'worker_protocol_mismatch',
+    WORKER_TYPE_MISMATCH: 'worker_type_mismatch',
+    WORKER_IDENTITY_REQUIRED: 'worker_identity_required',
+    HUB_API_KEY_NOT_CONFIGURED: 'hub_api_key_not_configured',
+};
+
+/**
+ * Validates the identity block of a task envelope. Advisory helper that
+ * mirrors the hub's required-set check (gpu-hub.js /task):
+ * dispatch_id, build_id, book_id, chapter_id, scene_id, stage must be
+ * truthy and protocol_version must equal PROTOCOL_VERSION. Returns an
+ * error-token string or null. job_id / job_type / params are NOT checked
+ * here (hub does not validate them — JOB_PROTOCOL_V2.md §3.2).
+ */
+function validateTaskEnvelopeIdentity(task) {
+    if (!task || typeof task !== 'object') {
+        return ERROR_TOKENS.INCOMPLETE_DISPATCH_IDENTITY;
+    }
+    if (task.protocol_version !== PROTOCOL_VERSION) {
+        return ERROR_TOKENS.PROTOCOL_VERSION_MISMATCH;
+    }
+    for (const field of ['dispatch_id', 'build_id', 'book_id', 'chapter_id', 'scene_id', 'stage']) {
+        if (!task[field]) {
+            return ERROR_TOKENS.INCOMPLETE_DISPATCH_IDENTITY;
+        }
+    }
+    return null;
+}
+
+/**
+ * Validates the identity block of a result/error envelope (worker → hub):
+ * job_id, build_id, dispatch_id present (for results also result_base64)
+ * and protocol_version === PROTOCOL_VERSION. Mirrors the hub's
+ * /task/result and /task/error guard. Returns an error token or null.
+ */
+function validateResultEnvelopeIdentity(payload, { requireResultBase64 = false } = {}) {
+    if (!payload || typeof payload !== 'object') {
+        return ERROR_TOKENS.INVALID;
+    }
+    if (payload.protocol_version !== PROTOCOL_VERSION) {
+        return ERROR_TOKENS.INVALID;
+    }
+    const required = ['job_id', 'build_id', 'dispatch_id'];
+    if (requireResultBase64) required.push('result_base64');
+    for (const field of required) {
+        if (!payload[field]) {
+            return ERROR_TOKENS.INVALID;
+        }
+    }
+    return null;
+}
+
+module.exports = {
+    // protocol constants
+    PROTOCOL_VERSION,
+    JOB_TYPES,
+    SYSTEM_JOB_TYPES,
+    STAGE_BY_KIND,
+    // job_id grammar
+    CHUNK_INDEX_RE,
+    GROUP_SUFFIX_RE,
+    JOB_ID_SPLIT_RE,
+    buildJobId,
+    splitJobId,
+    parseJobId,
+    getStageForJobId,
+    // envelope contract
+    TASK_ENVELOPE_REQUIRED_FIELDS,
+    TASK_ENVELOPE_FIELDS,
+    RESULT_ENVELOPE_REQUIRED_FIELDS,
+    ERROR_ENVELOPE_REQUIRED_FIELDS,
+    BEACON_ENVELOPE_REQUIRED_FIELDS,
+    ERROR_TOKENS,
+    validateTaskEnvelopeIdentity,
+    validateResultEnvelopeIdentity,
+};

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "animastor-worker",
+  "version": "2.1.0",
+  "description": "Animastor GPU Worker runtime bundle. The version field is the canonical worker bundle version: the hub publishes it with the bundle artifact (GET /worker-bundle) and worker.cjs reports it in beacons when WORKER_VERSION is not set.",
+  "main": "worker.cjs",
+  "files": [
+    "worker.cjs",
+    "worker-env.cjs",
+    "worker-cleanup.cjs",
+    "worker-cleanup-journal.cjs",
+    "job-protocol-v2.cjs",
+    ".env.example"
+  ],
+  "scripts": {
+    "start": "node worker.cjs",
+    "test": "node ../tests/run-all.cjs",
+    "sync:protocol": "node ../tools/sync-protocol.cjs",
+    "check:protocol": "node ../tools/sync-protocol.cjs --check"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Animastor/animastor.git",
+    "directory": "worker/worker"
+  },
+  "bugs": {
+    "url": "https://github.com/Animastor/animastor/issues"
+  },
+  "homepage": "https://animastor.in",
+  "keywords": [],
+  "author": "",
+  "license": "MIT",
+  "type": "module"
+}

package/worker-cleanup-journal.cjs

@@ -0,0 +1,239 @@
+// ======================================================
+// Worker Cleanup Journal — crash-safe recovery временных файлов ComfyUI
+// ======================================================
+// Worker-local persistent journal lifecycle одной job:
+//   CREATED → GENERATED → DELIVERED → (CLEANED удаляет запись)
+//
+// Хранит ТОЛЬКО конкретные absolute paths (никаких glob/prefix). Записи
+// пишутся атомарно (tmp → fsync → rename), поэтому crash не повреждает JSON.
+// Живёт на persistent-диске worker'а (рядом с runtime data), переживает и
+// worker-restart, и Redis-restart (не зависит от Redis/PG).
+//
+// ВАЖНЫЙ ПРИНЦИП recovery: если нет доказательства DELIVERED — output не
+// удаляется (защита единственной копии результата). input_files можно
+// удалять всегда — они пересоздаются из task.assets при re-dispatch.
+//
+// Повреждённый journal НЕ расшифровывается и НЕ приводит к удалению файлов:
+// записывается warning, файл остаётся для диагностики.
+// Orphan-файлы без journal не трогаются (нет доказательства принадлежности).
+
+const fs = require("fs");
+const fsp = require("fs").promises;
+const path = require("path");
+const { cleanupJobArtifacts } = require("./worker-cleanup.cjs");
+
+const PHASES = ["created", "generated", "delivered"];
+
+function defaultLog(level, msg) {
+  console.log(`[${new Date().toISOString()}] [${level}] ${msg}`);
+}
+
+function resolveJournalDir(journalDir) {
+  return journalDir || process.env.WORKER_JOURNAL_DIR || path.join(__dirname, "cleanup-journal");
+}
+
+function sanitizeFilePart(str) {
+  return String(str).replace(/[^A-Za-z0-9._-]/g, "_");
+}
+
+function journalFilePath(journalDir, jobId, dispatchId) {
+  return path.join(journalDir, `${sanitizeFilePart(jobId)}__${sanitizeFilePart(dispatchId)}.json`);
+}
+
+// ── Atomic JSON write: tmp file → fsync → rename ──
+async function atomicWriteJson(filePath, data) {
+  const tmpPath = `${filePath}.tmp`;
+  const fh = await fsp.open(tmpPath, "w");
+  try {
+    await fh.writeFile(JSON.stringify(data, null, 2));
+    await fh.sync();
+  } finally {
+    await fh.close();
+  }
+  await fsp.rename(tmpPath, filePath);
+}
+
+// ── Read + validate a journal record. Returns null on any corruption. ──
+function readRecord(filePath) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    const record = JSON.parse(raw);
+    if (!record || typeof record !== "object") return null;
+    if (!record.job_id || !record.dispatch_id) return null;
+    if (!PHASES.includes(record.phase)) return null;
+    if (!Array.isArray(record.input_files)) record.input_files = [];
+    return record;
+  } catch (_) {
+    return null;
+  }
+}
+
+async function ensureDir(dir) {
+  await fsp.mkdir(dir, { recursive: true });
+}
+
+/**
+ * Создать journal-запись job (phase=created). ДОЛЖЕН вызываться ДО создания
+ * первого временного input-файла. Best-effort: возвращает record или null.
+ */
+async function createJob({ journalDir, jobId, dispatchId, log } = {}) {
+  const logFn = log || defaultLog;
+  if (!jobId || !dispatchId) return null;
+  try {
+    const dir = resolveJournalDir(journalDir);
+    await ensureDir(dir);
+    const record = {
+      job_id: jobId,
+      dispatch_id: dispatchId,
+      phase: "created",
+      input_files: [],
+      output_file: null,
+      created_at: new Date().toISOString(),
+      updated_at: new Date().toISOString(),
+    };
+    await atomicWriteJson(journalFilePath(dir, jobId, dispatchId), record);
+    return record;
+  } catch (err) {
+    logFn("warn", `Journal create failed for ${jobId}: ${err.message}`);
+    return null;
+  }
+}
+
+async function mutate({ journalDir, jobId, dispatchId, log } = {}, mutateFn) {
+  const logFn = log || defaultLog;
+  if (!jobId || !dispatchId) return null;
+  try {
+    const dir = resolveJournalDir(journalDir);
+    const filePath = journalFilePath(dir, jobId, dispatchId);
+    const record = readRecord(filePath);
+    if (!record) {
+      logFn("warn", `Journal record missing for ${jobId} (${filePath})`);
+      return null;
+    }
+    const changed = await mutateFn(record);
+    if (changed === false) return record;
+    record.updated_at = new Date().toISOString();
+    await atomicWriteJson(filePath, record);
+    return record;
+  } catch (err) {
+    logFn("warn", `Journal update failed for ${jobId}: ${err.message}`);
+    return null;
+  }
+}
+
+/** Добавить фактически созданный input path в journal. */
+async function addInputFile(opts, filePath) {
+  return mutate(opts, (record) => {
+    if (!filePath) return false;
+    if (!record.input_files.includes(filePath)) record.input_files.push(filePath);
+  });
+}
+
+/** После waitResult: зафиксировать конкретный output-файл → phase=generated. */
+async function setOutputAndGenerated(opts, outputFile) {
+  return mutate(opts, (record) => {
+    if (!outputFile) return false;
+    record.output_file = outputFile;
+    record.phase = "generated";
+  });
+}
+
+/** После успешного sendResult (HTTP 200) → phase=delivered. */
+async function setDelivered(opts) {
+  return mutate(opts, (record) => {
+    record.phase = "delivered";
+  });
+}
+
+/** Удалить journal-запись (после полного CLEANED). Идемпотентно. */
+async function removeJob({ journalDir, jobId, dispatchId, log } = {}) {
+  try {
+    const dir = resolveJournalDir(journalDir);
+    await fsp.unlink(journalFilePath(dir, jobId, dispatchId)).catch(() => {});
+    return true;
+  } catch (_) {
+    return false;
+  }
+}
+
+function listJournalFiles(journalDir) {
+  let files = [];
+  try {
+    files = fs.readdirSync(resolveJournalDir(journalDir));
+  } catch (_) {}
+  return files.filter((f) => f.endsWith(".json") && !f.endsWith(".tmp.json"));
+}
+
+/**
+ * Crash-safe startup recovery. Для каждой записи:
+ *   delivered  → удалить input_files + output_file;
+ *   created/generated → удалить ТОЛЬКО input_files (output сохраняется).
+ * Запись удаляется только когда ВСЕ удаления успешны; при частичном cleanup
+ * запись остаётся — следующий прогон дочистит. Повреждённые записи
+ * пропускаются (warning) и не ломают startup.
+ *
+ * @returns {Promise<{found:number, cleaned:number, kept:number, corrupt:number}>}
+ */
+async function recoverCleanupJournal({ journalDir, log } = {}) {
+  const logFn = log || defaultLog;
+  const dir = resolveJournalDir(journalDir);
+  const files = listJournalFiles(journalDir);
+  const result = { found: files.length, cleaned: 0, kept: 0, corrupt: 0 };
+
+  if (files.length > 0) logFn("info", `Cleanup recovery: found ${files.length} journal(s)`);
+
+  for (const file of files) {
+    const filePath = path.join(dir, file);
+    const record = readRecord(filePath);
+    if (!record) {
+      result.corrupt++;
+      logFn("warn", `Cleanup recovery: corrupt journal skipped ${file} (kept for diagnostics)`);
+      continue;
+    }
+    const { job_id, dispatch_id } = record;
+    logFn("info", `Cleanup recovery: job_id=${job_id} phase=${record.phase}`);
+
+    // Без proof DELIVERED output не трогаем (единственная копия результата).
+    const outputFile = record.phase === "delivered" ? record.output_file : null;
+    let cleanupResult;
+    try {
+      cleanupResult = await cleanupJobArtifacts({
+        inputFiles: record.input_files,
+        outputFile,
+      });
+    } catch (err) {
+      result.kept++;
+      logFn("warn", `Cleanup recovery: job_id=${job_id} failed path=(${err.message})`);
+      continue;
+    }
+
+    result.cleaned += cleanupResult.cleaned;
+    for (const fail of cleanupResult.failed) {
+      logFn("warn", `Cleanup recovery: failed path=${fail.path} reason=${fail.reason}`);
+    }
+
+    if (cleanupResult.failed.length === 0) {
+      await removeJob({ journalDir: dir, jobId: job_id, dispatchId: dispatch_id });
+      logFn("info", `Cleanup recovery: job_id=${job_id} cleaned ${cleanupResult.cleaned} artifact(s)`);
+    } else {
+      result.kept++;
+      logFn("info", `Cleanup recovery: job_id=${job_id} partial cleanup, journal kept`);
+    }
+  }
+
+  return result;
+}
+
+module.exports = {
+  createJob,
+  addInputFile,
+  setOutputAndGenerated,
+  setDelivered,
+  removeJob,
+  recoverCleanupJournal,
+  readRecord,
+  atomicWriteJson,
+  journalFilePath,
+  resolveJournalDir,
+  sanitizeFilePart,
+};

package/worker-cleanup.cjs

@@ -0,0 +1,60 @@
+// ======================================================
+// Worker Cleanup — точечная уборка временных файлов ComfyUI
+// ======================================================
+// Удаляет ТОЛЬКО файлы конкретной job (input-файлы, созданные worker'ом, и
+// output-файл, реально прочитанный как результат). Никогда не бросает:
+// - отсутствующий файл (ENOENT) считается успехом;
+// - ошибка удаления одного файла не останавливает уборку остальных.
+// Это НЕ глобальная чистка input/output — только явно переданные пути.
+
+const fsp = require("fs").promises;
+
+/**
+ * Safe unlink — никогда не бросает.
+ * @param {string} filePath абсолютный путь
+ * @returns {Promise<{ok:boolean, path:string, missing?:boolean, error?:string}>}
+ */
+async function safeUnlink(filePath) {
+  try {
+    await fsp.unlink(filePath);
+    return { ok: true, path: filePath };
+  } catch (err) {
+    if (err && err.code === "ENOENT") {
+      return { ok: true, path: filePath, missing: true };
+    }
+    return { ok: false, path: filePath, error: (err && err.message) || String(err) };
+  }
+}
+
+/**
+ * Cleanup артефактов одной job: input-файлы (всегда) + output-файл
+ * (только когда он передан — т.е. результат уже доставлен).
+ * @param {{inputFiles?: string[], outputFile?: string|null}} opts
+ * @returns {Promise<{cleaned:number, failed:Array<{path:string, reason:string}>, outputFile:string|null}>}
+ */
+async function cleanupJobArtifacts({ inputFiles = [], outputFile = null } = {}) {
+  const failed = [];
+  let cleaned = 0;
+
+  for (const filePath of inputFiles) {
+    const res = await safeUnlink(filePath);
+    if (res.ok) {
+      cleaned++;
+    } else {
+      failed.push({ path: filePath, reason: res.error });
+    }
+  }
+
+  if (outputFile) {
+    const res = await safeUnlink(outputFile);
+    if (res.ok) {
+      cleaned++;
+    } else {
+      failed.push({ path: outputFile, reason: res.error });
+    }
+  }
+
+  return { cleaned, failed, outputFile: outputFile || null };
+}
+
+module.exports = { safeUnlink, cleanupJobArtifacts };