@animastor/orchestration 0.2.0 → 0.3.1

package/CHANGELOG.md

@@ -1,5 +1,78 @@
 # Changelog
 
+## 0.3.1 (2026-11-01) — результат GPU обрабатывается один раз
+
+Основание: `reports/2026-11-01/gpu-audio-image-run-analysis.md`, P1 — каждый
+результат обрабатывался дважды (HTTP-push hub → backend, затем Phase A
+reconcile подбирал оставшийся `animastor:result:*` мимо
+`animastor:result-processed:*`). Описание: animastor-docs
+`architecture/GPU_HUB_CONTRACT.md` §«Result ACK».
+
+### Changed (поведение)
+
+- `reconciliation-engine.recoverResultKeys` (Phase A): перед
+  `handleTaskResult` читает маркер `animastor:result-processed:{job}:{build}`.
+  Значение `done:<dispatch_id>` того же dispatch, что в result-ключе, —
+  ключ удаляется молча (без лога), handler не вызывается.
+  Маркер `'1'` (в работе / старый формат), маркер другого dispatch
+  (перегенерация audio/video в пределах TTL) или его отсутствие — как
+  раньше, через fenced handler.
+- Терминальный отказ (`no_active_dispatch` и др.) для дубля доставленного
+  результата (маркер есть) — уровень info; для сироты (маркера нет) — warn.
+- `orchestrator.resetScenes` вместе с `iu-progress` удаляет
+  `animastor:iu-progress-ids:*` (множество IU×fence, хост task-handler).
+
+Fence, dedup-ключ маршрута и command-gate (Stage 155) не меняются.
+
+## 0.3.0 (2026-10-31) — генерация только по явной команде
+
+Правило владельца: GPU-генерация запускается только кнопками «аудио» /
+«картинки» / «всё»; никаких автозапусков следующих стадий и фоновых
+запусков; задачи только на включённые слои. Основание — разбор
+`reports/2026-10-31/auto-image-task-ba-incident.md` (§6, §8). Описание:
+animastor-docs `architecture/COMMAND_ONLY_GENERATION.md`.
+
+**Инвариант:** сцена×стадия попадает в active index / dispatch только при
+активной задаче реестра (создана явной командой, стадия = type задачи), при
+включённом слое и без отмены (cancel flag / tombstone).
+
+### Added
+
+- `runtime/command-gate.js` — единственная точка вычисления инварианта
+  (`getAuthorizedStages`, `isStageAuthorized`), force-набор сцена×стадия,
+  `rollbackGeneratingToDirty`, `blockStageNoWorker`. Экспорт
+  `runtime.commandGate`.
+- ProgressEventsPort: операция `blockSceneStage` (хост помечает команду
+  blocked в реестре и PG).
+
+### Changed (поведение)
+
+- `active-scenes-index.addActiveScene` — запись в active index только при
+  авторизованной стадии; иначе `{ added:false, denied:true }`.
+- `runtime-scheduler.shouldScheduleAssets` — стадии только по гейту; убраны
+  fallback на layer-config без задачи и `isInFlight`-override.
+- `runtime-scheduler.tick/attemptDispatch` — force только для сцен×стадий
+  команды (ключ `animastor:force-dispatch-stages:<book>`, вместо книжного
+  `animastor:force-dispatch:<book>`); `no_worker_available` → стадия blocked
+  (GENERATING → DIRTY, задача blocked), без автоповтора.
+- `markVersionStaleDirty` — только помечает stale, в работу не ставит.
+- `orchestrator.resetScenes` — пишет force-набор вместо книжного флага.
+- `scene-orchestrator.dispatchStage` — NEW-сцена переводит в PENDING только
+  диспатчимую стадию; при `no_worker_available` откат в DIRTY, не PENDING.
+- `reconciliation-engine`:
+  - удалены `PROGRESS_TO_IMAGE` / `PROGRESS_TO_VIDEO`; partial build — только
+    диагностика;
+  - `REGENERATE_MISSING_ASSET`, `MOVE_TO_PENDING`, `RELEASE_STALE_LEASE`,
+    перезапуск аудио в `RECOVER_ORPHAN_ASSETS` — только под активной командой
+    стадии, иначе диагностика; осиротевший GENERATING без команды → DIRTY;
+  - C5 вызывает `deps.interruptIncompleteSessions` (возобновления нет);
+  - C8 `rebuildWorkList` пересобирает только факты asset-state, PENDING и
+    active index не пишет.
+- `scene-window.startScene` — без авторизованной стадии сцену не стартует;
+  `trySlideWindowOnComplete` — за флагом хоста `windowAutoNextEnabled()`
+  (по умолчанию выкл.).
+- `dispatch-engine.repairOrphanGeneratingStates` — опция `target: 'dirty'`.
+
 ## 0.2.0 (2026-10-27)
 
 Version-line split for `stage143a-foundation-phase1`: the branch line moves

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@animastor/orchestration",
-    "version": "0.2.0",
+    "version": "0.3.1",
     "description": "Animastor Orchestration — the generation orchestration/runtime contour of the Animastor backend, physically extracted from the host (§32.30): the unified generation lifecycle owner (orchestrator facade, stage executor, scene callbacks/restoration), the dispatch engine and its lease/quota/retry managers, the reconciliation engine and counter reconciliation, the scene window/scheduler/worker-health, the runtime-result emitter/consumer, and the eight O-2..O-10 port contracts (Persistence, SceneData, PlaceholderAudio, ProgressEvents, AudioFsm, VideoFsm, HubCancel, LayerConfig). The package reaches the host (runtime config slices, Redis-domain state layer, media facades, the S-5 seam registry, the artifact root, the PW-2 workspace resolver) ONLY through the composition-root host-bindings seam — no backend/src require, no storage/book/routes/services, no Redis, no PG, no Express inside.",
     "keywords": [
         "animastor",

package/src/index.js

@@ -75,6 +75,7 @@ const EAGER_EXPORTS = {
 const RUNTIME_NS = {
     scheduler: './runtime/runtime-scheduler',
     activeScenes: './runtime/active-scenes-index',
+    commandGate: './runtime/command-gate',
     reconciliation: './runtime/reconciliation-engine',
     dispatch: './runtime/dispatch-engine',
     leaseManager: './runtime/lease-manager',

package/src/orchestration/orchestrator.js

@@ -465,7 +465,7 @@ async function reconcile(redis, bookId, chapterId, sceneId) {
 //   options.readdToActiveIndex — вернуть сцены планировщику после reset (default true)
 //
 // Что делает:
-//   1. force-dispatch флаг
+//   1. force-набор: только сцены×стадии этой регенерации
 //   2. событие SCENE_RESET в journal
 //   3. удаление из active index
 //   4. снятие dispatch leases только для сбрасываемых стадий
@@ -497,11 +497,18 @@ async function resetScenes(redis, bookId, buildId, scenes, layerCfg, options = {
     const scopeDisplay = `${scope}${chapterId ? '/' + chapterId : ''}${sceneId ? '/' + sceneId : ''}`;
     log(`[RESET-SCENES] ${bookId}: ${scenes.length} scenes, scope=${scopeDisplay}`);
 
-    // 1. Force-dispatch flag (T1: TTL из TIMEOUTS)
-        await redis.set(
-        `animastor:force-dispatch:${bookId}`, '1',
-        'EX', runtimeConfig.TIMEOUTS.FORCE_DISPATCH_TTL_S
-    );
+    // 1. Force set (T1: TTL из TIMEOUTS). Command-only generation: force
+    // covers EXACTLY the scene×stage pairs reset here (dirty_layers ∩ enabled
+    // layers of the request) — never the whole book (incident 2026-10-30:
+    // one-scene audio regenerate force-dispatched an unrelated image stage).
+    const commandGate = require('../runtime/command-gate');
+    await commandGate.addForceStages(redis, bookId, scenes.map(ds => ({
+        chapter_id: ds.chapter_id,
+        scene_id: ds.scene_id,
+        stages: (ds.dirty_layers || mediaRegistry.listMediaTypes()).filter(stage =>
+            layerCfg?.[`${stage}_enabled`] !== false
+        ),
+    })), runtimeConfig.TIMEOUTS.FORCE_DISPATCH_TTL_S);
 
     // 2. Event journal — start
     await journal.appendSceneEvent(redis, bookId, chapterId || bookId, sceneId || 'all',
@@ -568,6 +575,8 @@ async function resetScenes(redis, bookId, buildId, scenes, layerCfg, options = {
 
         const progKey = `animastor:iu-progress:${bookId}:${ds.chapter_id}:${ds.scene_id}:image`;
         try { await redis.del(progKey); } catch (_) {}
+        // SYNC: backend task-handler — the IU×fence set behind the counter.
+        try { await redis.del(`animastor:iu-progress-ids:${bookId}:${ds.chapter_id}:${ds.scene_id}:image`); } catch (_) {}
 
         try {
             let cursor = '0';
@@ -601,10 +610,13 @@ async function resetScenes(redis, bookId, buildId, scenes, layerCfg, options = {
     // Selective generation can defer this until its task registry is ready.
     // Гарантированно выполняется даже при ошибке markDirty (шаг 8).
     if (readdToActiveIndex) {
+        // Command-gated write: only scenes with an authorized stage enter.
+        let readded = 0;
         for (const ds of scenes) {
-            await scheduler.addSceneToActiveIndex(redis, bookId, ds.chapter_id, ds.scene_id);
+            const r = await scheduler.addSceneToActiveIndex(redis, bookId, ds.chapter_id, ds.scene_id);
+            if (r && !r.denied) readded++;
         }
-        log(`[RESET-SCENES] ${bookId}: ${scenes.length} scenes re-added to active index`);
+        log(`[RESET-SCENES] ${bookId}: ${readded}/${scenes.length} scenes re-added to active index (command-gated)`);
     } else {
         log(`[RESET-SCENES] ${bookId}: activation deferred for ${scenes.length} scenes`);
     }

package/src/orchestration/scene-orchestrator.js

@@ -68,19 +68,21 @@ const EXECUTORS = {
     video: executeVideoDispatch,
 };
 
-async function startScene(redis, scene, loadedBook, buildId) {
+async function startScene(redis, scene, loadedBook, buildId, stage = 'audio') {
     const bookId = scene.book_id;
     const chapterId = scene.chapter_id;
     const sceneId = scene.scene_id;
 
-    log(`START SCENE: ${bookId}/${chapterId}/${sceneId}`);
+    log(`START SCENE: ${bookId}/${chapterId}/${sceneId} (stage=${stage})`);
 
-    await logEvent(redis, scene, 'SCENE_STARTED', 'audio_pending', {
+    await logEvent(redis, scene, 'SCENE_STARTED', `${stage}_pending`, {
         buildId, bookId, chapterId, sceneId
     });
 
-    // T7: через фасад — единый владелец PENDING
-    await setScenePending(redis, bookId, chapterId, sceneId, 'audio', buildId);
+    // T7: через фасад — единый владелец PENDING. Command-only generation:
+    // only the stage being dispatched becomes PENDING — a NEW scene asked for
+    // `image` must not get an unrequested `audio` PENDING.
+    await setScenePending(redis, bookId, chapterId, sceneId, stage, buildId);
     await runtimeScheduler.addSceneToActiveIndex(redis, bookId, chapterId, sceneId);
     log(`ADDED TO ACTIVE: ${bookId}/${chapterId}/${sceneId}`);
 
@@ -652,7 +654,7 @@ async function dispatchStage(redis, scene, loadedBook, buildId, overrideStage, d
     );
     if (isNewScene) {
         log(`NEW SCENE: ${bookId}/${chapterId}/${sceneId} (asset-state)`);
-        await startScene(redis, scene, loadedBook, buildId);
+        await startScene(redis, scene, loadedBook, buildId, overrideStage || 'audio');
     }
 
     if (!overrideStage) {
@@ -673,7 +675,19 @@ async function dispatchStage(redis, scene, loadedBook, buildId, overrideStage, d
     result = await executor(redis, scene, loadedBook, buildId, dispatchId);
 
     result = result || { dispatched: false, reason: 'no_result', jobs: 0 };
-    if (!result.dispatched && !result.completed) {
+    if (!result.dispatched && !result.completed && result.reason === 'no_worker_available') {
+        // Command-only generation: no live worker of this type → the stage is
+        // BLOCKED, not re-queued. GENERATING → DIRTY only (never PENDING): the
+        // scheduler marks the command blocked and nothing retries it until a
+        // new command arrives (incident 2026-10-30: endless no_worker loop).
+        const rollback = await require('../runtime/command-gate').rollbackGeneratingToDirty(
+            redis, bookId, chapterId, sceneId, overrideStage, 'no_worker_available');
+        if (!rollback.changed && rollback.reason !== 'state_dirty' && rollback.reason !== 'state_ready') {
+            warn(`DISPATCH_ROLLBACK_FAILED: ${bookId}/${chapterId}/${sceneId} ${overrideStage}: ${rollback.reason} — blocked stage not released`);
+            result.rollbackFailed = true;
+            result.rollbackReason = rollback.reason;
+        }
+    } else if (!result.dispatched && !result.completed) {
         // FSM-валидный rollback (GENERATING → DIRTY → PENDING). Прямой
         // generating→pending запрещён FSM; раньше здесь вызывался setScenePending,
         // rejection молча проглатывался — и сцена навсегда оставалась в GENERATING

package/src/runtime/active-scenes-index.js

@@ -33,12 +33,28 @@ async function getActiveCount(redis) {
 }
 
 /**
- * Add scene to active index when it enters generating/pending state.
+ * Add scene to active index — COMMAND-GATED (generation only by explicit
+ * command, see ./command-gate). The scene enters the index only when at
+ * least one of its stages is authorized: an ACTIVE task-registry task of that
+ * stage targets the scene, the layer is enabled and the book is not
+ * cancelled. Otherwise nothing is written and `{ added:false, denied:true }`
+ * is returned with the per-stage denial reasons.
+ *
+ * This is the ONE write path into the index (scheduler wrapper, regenerate,
+ * reconcile, scene-window, host services and the player all reach it), so
+ * no background path can queue work without a command.
  */
 async function addActiveScene(redis, bookId, chapterId, sceneId) {
     const sceneKey = `${bookId}:${chapterId}:${sceneId}`;
+    // Lazy: command-gate → scene-window → this module (acyclic at load time).
+    const auth = await require('./command-gate').getAuthorizedStages(redis, bookId, chapterId, sceneId);
+    if (auth.stages.size === 0) {
+        const reasons = require('./command-gate').describeDenied(auth.denied);
+        console.log(`[ACTIVE-INDEX] GATE_DENY ${sceneKey}: no command-authorized stage (${reasons}) — not added`);
+        return { added: false, denied: true, sceneKey, reasons: auth.denied };
+    }
     const added = await redis.sadd(ACTIVE_SCENES_KEY, sceneKey);
-    return { added: added > 0, sceneKey };
+    return { added: added > 0, sceneKey, stages: [...auth.stages] };
 }
 
 /**

package/src/runtime/command-gate.js

@@ -0,0 +1,270 @@
+// ======================================================
+// COMMAND GATE — «генерация только по явной команде»
+// ======================================================
+// Правило владельца (2026-10-31, разбор reports/2026-10-31/
+// auto-image-task-ba-incident.md §6/§8): GPU-генерация запускается ТОЛЬКО
+// кнопками «аудио» / «картинки» / «всё». Никаких автозапусков следующих
+// стадий, никаких фоновых запусков, задачи только на включённые слои.
+//
+// ИНВАРИАНТ. Сцена×стадия попадает в active index / dispatch ТОЛЬКО когда
+// одновременно:
+//   1. есть АКТИВНАЯ задача реестра (generation-progress, создаётся явной
+//      командой POST /regenerate), в targets которой есть эта сцена и чей
+//      type — эта стадия;
+//   2. слой стадии включён в layer-config книги;
+//   3. у книги нет отмены (cancel flag в Redis / tombstone в PG).
+//
+// Этот модуль — единственное место, где инвариант вычисляется. Им пользуются:
+//   • active-scenes-index.addActiveScene  — запись в active index;
+//   • runtime-scheduler.shouldScheduleAssets — выбор стадий для dispatch;
+//   • reconciliation-engine — ремонтные фиксы, которые раньше ставили работу;
+//   • scene-window.startScene — оконный старт сцены.
+//
+// Реестр задач читается ТОЛЬКО через ProgressEventsPort (O-5), отмена — через
+// PersistencePort (O-2) и cancel flag scene-window; Redis-ключи хост-сервисов
+// здесь не появляются. Ошибка чтения реестра — fail-closed (стадия НЕ
+// авторизована): без доказанной команды работы нет.
+//
+// Docs: animastor-docs/architecture/COMMAND_ONLY_GENERATION.md
+// ======================================================
+
+const mediaRegistry = require('@animastor/generation').mediaRegistry;
+const { lazyHostBinding } = require('../host/host-bindings');
+const state = lazyHostBinding('state');
+const progressEventsOp = require('./progress-events-port').progressEventsOp;
+const persist = require('./persistence-port').persist;
+
+const logPrefix = '[COMMAND-GATE]';
+
+function log(msg) {
+    console.log(`${logPrefix} ${msg}`);
+}
+
+function warn(msg) {
+    console.warn(`${logPrefix} ⚠️ ${msg}`);
+}
+
+// ======================================================
+// LAYER CONFIG
+// ======================================================
+
+/**
+ * Read the book layer config (Redis `animastor:layer-config:<book>`).
+ * Missing/broken config → every registered layer enabled (registry default).
+ */
+async function getLayerConfig(redis, bookId) {
+    const layerRaw = await redis.get(`animastor:layer-config:${bookId}`);
+    if (layerRaw) {
+        try { return JSON.parse(layerRaw); } catch (_) { /* fall through to defaults */ }
+    }
+    const defaults = {};
+    for (const t of mediaRegistry.listMediaTypes()) { defaults[`${t}_enabled`] = true; }
+    return defaults;
+}
+
+function isLayerEnabled(layerCfg, stage) {
+    return !layerCfg || layerCfg[`${stage}_enabled`] !== false;
+}
+
+// ======================================================
+// CANCELLATION
+// ======================================================
+
+/**
+ * True if the user explicitly cancelled generation for this book (Redis
+ * cancel flag and/or PG tombstone). A PG error reads as "not cancelled"
+ * (the Redis flag is still honoured) — the same semantics the reconcile
+ * resurrection guard always had.
+ */
+async function isBookCancelled(redis, bookId) {
+    try {
+        // Lazy: scene-window requires active-scenes-index, which requires
+        // this module — resolve at call time to keep the module graph acyclic.
+        if (await require('./scene-window').isCancelled(redis, bookId)) return true;
+    } catch (_) { /* flag unreadable — fall through to tombstone */ }
+    try {
+        return !!(await persist('cancel.isCancelled')(bookId));
+    } catch (_) {
+        return false;
+    }
+}
+
+// ======================================================
+// AUTHORIZATION
+// ======================================================
+
+/** Per-pass memo (one scheduler tick / one reconcile pass). */
+function createGateCache() {
+    return { layer: new Map(), cancelled: new Map() };
+}
+
+async function memo(cache, bucket, bookId, fn) {
+    if (!cache) return fn();
+    if (cache[bucket].has(bookId)) return cache[bucket].get(bookId);
+    const value = await fn();
+    cache[bucket].set(bookId, value);
+    return value;
+}
+
+const EMPTY_TASK_STATE = Object.freeze({ managed: false, activeTypes: new Set() });
+
+/**
+ * Which stages of one scene are authorized by an explicit command right now.
+ *
+ * @returns {Promise<{stages:Set<string>, denied:Object<string,string>,
+ *   cancelled:boolean, layerCfg:object, taskState:{managed:boolean, activeTypes:Set<string>}}>}
+ *   `denied[stage]` ∈ 'cancelled' | 'no_active_task' | 'layer_disabled'.
+ */
+async function getAuthorizedStages(redis, bookId, chapterId, sceneId, cache = null) {
+    const cancelled = await memo(cache, 'cancelled', bookId, () => isBookCancelled(redis, bookId));
+    const layerCfg = await memo(cache, 'layer', bookId, () => getLayerConfig(redis, bookId));
+
+    let taskState = EMPTY_TASK_STATE;
+    try {
+        const ts = await progressEventsOp('getSceneTaskState')(redis, bookId, chapterId, sceneId);
+        if (ts && ts.activeTypes instanceof Set) taskState = ts;
+    } catch (err) {
+        // Fail-closed: an unreadable registry proves no command.
+        warn(`task registry unreadable for ${bookId}/${chapterId}/${sceneId}: ${err.message} — no stage authorized`);
+    }
+
+    const stages = new Set();
+    const denied = {};
+    for (const stage of mediaRegistry.listMediaTypes()) {
+        if (cancelled) { denied[stage] = 'cancelled'; continue; }
+        if (!taskState.activeTypes.has(stage)) { denied[stage] = 'no_active_task'; continue; }
+        if (!isLayerEnabled(layerCfg, stage)) { denied[stage] = 'layer_disabled'; continue; }
+        stages.add(stage);
+    }
+    return { stages, denied, cancelled, layerCfg, taskState };
+}
+
+/** Is ONE stage of a scene authorized? */
+async function isStageAuthorized(redis, bookId, chapterId, sceneId, stage, cache = null) {
+    const auth = await getAuthorizedStages(redis, bookId, chapterId, sceneId, cache);
+    return auth.stages.has(stage);
+}
+
+function describeDenied(denied) {
+    return Object.entries(denied || {}).map(([s, r]) => `${s}:${r}`).join(',') || 'none';
+}
+
+// ======================================================
+// STATE HYGIENE WITHOUT WORK
+// ======================================================
+
+/**
+ * GENERATING → DIRTY (FSM-valid edge). Used where a dead/unsent generation
+ * must be released WITHOUT re-queueing it: without a command a stage may not
+ * sit in PENDING (PENDING is "queued work" — the incident's mine).
+ * Only GENERATING is touched; every other state is left as-is.
+ */
+async function rollbackGeneratingToDirty(redis, bookId, chapterId, sceneId, stage, reason) {
+    const states = await state.getAssetStates(redis, bookId, chapterId, sceneId);
+    const current = states?.[stage];
+    if (current !== state.AssetState.GENERATING) {
+        return { changed: false, reason: `state_${current || 'new'}` };
+    }
+    const check = state.validateAssetTransition(current, state.AssetState.DIRTY);
+    if (!check.valid) {
+        return { changed: false, reason: `invalid_transition:${current}->dirty` };
+    }
+    await state.unsafeRestoreAssetState(redis, bookId, chapterId, sceneId, stage, state.AssetState.DIRTY);
+    log(`${bookId}/${chapterId}/${sceneId} ${stage}: generating → dirty (reason=${reason}) — not re-queued`);
+    return { changed: true, from: current, to: state.AssetState.DIRTY };
+}
+
+// ======================================================
+// NO WORKER → BLOCKED (no auto-retry)
+// ======================================================
+
+/**
+ * A stage could not be enqueued because no live worker of its type exists.
+ * The command that asked for it is BLOCKED (task registry + PG) with the
+ * reason «нет воркера <type>»; the stage loses its authorization, so the
+ * scheduler never retries it. Only a NEW command retries.
+ * Storage writes happen host-side behind ProgressEventsPort.blockSceneStage.
+ */
+async function blockStageNoWorker(redis, bookId, chapterId, sceneId, stage) {
+    const reason = `no_worker:${stage}`;
+    let result = { tasks: [] };
+    try {
+        result = (await progressEventsOp('blockSceneStage')(redis, bookId, chapterId, sceneId, stage, reason)) || result;
+    } catch (err) {
+        warn(`blockSceneStage failed for ${bookId}/${chapterId}/${sceneId}:${stage}: ${err.message}`);
+    }
+    const ids = (result.tasks || []).map(t => t.task_id || t).join(',') || 'none';
+    log(`BLOCKED ${bookId}/${chapterId}/${sceneId}:${stage} — нет воркера ${stage}; tasks=[${ids}] — no auto-retry, a new command is required`);
+    return { reason, ...result };
+}
+
+// ======================================================
+// FORCE — only for the scene×stage pairs of the command
+// ======================================================
+// The former `animastor:force-dispatch:<book>` flag bypassed the duplicate/
+// lease guards for the WHOLE book for 120 s (incident §6 item 7). The force
+// set below holds exactly the scene×stage pairs reset by one regeneration.
+
+const FORCE_STAGES_KEY_PREFIX = 'animastor:force-dispatch-stages:';
+
+function forceStagesKey(bookId) {
+    return `${FORCE_STAGES_KEY_PREFIX}${bookId}`;
+}
+
+function forceMember(chapterId, sceneId, stage) {
+    return JSON.stringify([String(chapterId), String(sceneId), String(stage)]);
+}
+
+async function addForceStages(redis, bookId, pairs, ttlSeconds) {
+    const members = [];
+    for (const p of pairs || []) {
+        for (const stage of p.stages || []) members.push(forceMember(p.chapter_id, p.scene_id, stage));
+    }
+    if (members.length === 0) return 0;
+    const key = forceStagesKey(bookId);
+    await redis.sadd(key, ...members);
+    await redis.expire(key, ttlSeconds);
+    return members.length;
+}
+
+/** @returns {Promise<Set<string>>} force members of the book (see forceMember). */
+async function getForceStages(redis, bookId) {
+    try {
+        return new Set(await redis.smembers(forceStagesKey(bookId)) || []);
+    } catch (_) {
+        return new Set();
+    }
+}
+
+/** Stages of one scene present in a book force set. */
+function forcedStagesForScene(forceSet, chapterId, sceneId) {
+    const out = new Set();
+    if (!forceSet || forceSet.size === 0) return out;
+    for (const stage of mediaRegistry.listMediaTypes()) {
+        if (forceSet.has(forceMember(chapterId, sceneId, stage))) out.add(stage);
+    }
+    return out;
+}
+
+async function clearForceStages(redis, bookId) {
+    try { await redis.del(forceStagesKey(bookId)); } catch (_) { /* best effort */ }
+}
+
+module.exports = {
+    getLayerConfig,
+    isLayerEnabled,
+    isBookCancelled,
+    createGateCache,
+    getAuthorizedStages,
+    isStageAuthorized,
+    describeDenied,
+    rollbackGeneratingToDirty,
+    blockStageNoWorker,
+    FORCE_STAGES_KEY_PREFIX,
+    forceStagesKey,
+    forceMember,
+    addForceStages,
+    getForceStages,
+    forcedStagesForScene,
+    clearForceStages,
+};

package/src/runtime/dispatch-engine.js

@@ -498,7 +498,8 @@ async function getDispatchEvidence(redis, bookId, chapterId, sceneId, stage) {
  *
  * @param {Object} redis
  * @param {string} bookId
- * @param {{reason?: string}} [opts]
+ * @param {{reason?: string, target?: 'pending'|'dirty'}} [opts] — target 'dirty'
+ *        (command-only generation, Stop All) releases to DIRTY without re-queueing.
  * @returns {Promise<{repaired: Array<{chapterId, sceneId, stage, path}>}>}
  */
 async function repairOrphanGeneratingStates(redis, bookId, opts = {}) {
@@ -530,6 +531,16 @@ async function repairOrphanGeneratingStates(redis, bookId, opts = {}) {
                 if (states[stage] !== stateModule.AssetState.GENERATING) continue;
                 const evidence = await getDispatchEvidence(redis, bookId, chapterId, sceneId, stage);
                 if (evidence.alive) continue;
+                if (opts.target === 'dirty') {
+                    // Command-only generation (Stop All): release the ghost
+                    // to DIRTY without re-queueing it (no PENDING).
+                    const released = await require('./command-gate').rollbackGeneratingToDirty(
+                        redis, bookId, chapterId, sceneId, stage, reason);
+                    if (released.changed) {
+                        repaired.push({ chapterId, sceneId, stage, path: [stateModule.AssetState.DIRTY] });
+                    }
+                    continue;
+                }
                 const rollback = await rollbackStageToPending(
                     redis, bookId, chapterId, sceneId, stage, null, reason
                 );

package/src/runtime/progress-events-port.js

@@ -39,6 +39,11 @@
 //                           pre-pass; the getAssetStates callback arrives
 //                           as an argument exactly as pre-O-5)
 //
+//   blockSceneStage       — command-only generation (2026-10-31): no live
+//                           worker of a stage's type → block the command
+//                           that asked for it (registry + PG are host-side;
+//                           runtime-scheduler via command-gate)
+//
 // Deliberately NOT in the port: createTasks/listTasks/getTask/updateTask/
 // markCompleted/markCancelled/removeTask/clear (routes-side task CRUD —
 // the HTTP contour owns task lifecycle), getActiveTasksByType,
@@ -53,6 +58,7 @@ const OPS = [
     'getSceneTaskState',
     'hasActiveTasks',
     'reconcileCompletedTasks',
+    'blockSceneStage',
 ];
 
 let impl = null;