pixivflow 2.19.2 → 2.19.3

package/dist/commands/scheduler-runtime.js

@@ -57,6 +57,7 @@ const DeliveryDispatcher_1 = require("../delivery/DeliveryDispatcher");
 const token_maintenance_1 = require("../utils/token-maintenance");
 const schedules_1 = require("../scheduler/schedules");
 const SlotCoordinator_1 = require("../scheduler/SlotCoordinator");
+const DeliveryLedgerPort_1 = require("../delivery/DeliveryLedgerPort");
 const OutboxWorker_1 = require("../delivery/OutboxWorker");
 const LegacyOutboxMigration_1 = require("../delivery/LegacyOutboxMigration");
 const NotificationPolicy_1 = require("../notification/NotificationPolicy");
@@ -276,7 +277,7 @@ async function createSchedulerRuntime(configPathArg) {
             });
             return;
         }
-        const coordinator = new SlotCoordinator_1.SlotCoordinator(database);
+        const coordinator = new SlotCoordinator_1.SlotCoordinator(database, (0, DeliveryLedgerPort_1.createDeliveryLedgerPort)(database));
         // Ad-hoc/manual execution (run-once / explicit refetch) runs the download
         // plan WITHOUT a scheduled Slot: it can never mark a scheduled occurrence
         // complete or be resumed as one. Scheduled runs (cron/http/catchup) always
@@ -383,7 +384,14 @@ async function createSchedulerRuntime(configPathArg) {
         // re-runs a finished cell — that is what prevents a second post). Membership
         // comes from the materialized snapshot, so a config reload cannot add cells.
         const pending = slotCtx ? coordinator.pendingTargets(slotCtx.slotId, targets) : targets.map((target) => ({ target, cell: null }));
-        let runTargets = (onlyTarget ? pending.filter((p) => p.target.id === onlyTarget) : pending).map((p) => p.target);
+        const selected = onlyTarget ? pending.filter((p) => p.target.id === onlyTarget) : pending;
+        // Hand each cell its durable identity. Without this the handler cannot tell a
+        // first selection from a recovery, and would re-rank on resume — silently
+        // re-pointing the logical item at a different work than the one it owns.
+        const targetExecutionContexts = slotCtx
+            ? coordinator.executionContextsFor(slotCtx.slotId, selected)
+            : undefined;
+        let runTargets = selected.map((p) => p.target);
         if (slotCtx && runTargets.length === 0) {
             logger_1.logger.info('All slot cells already complete', { slot: slotCtx.slotId });
             coordinator.finish(slotCtx, schedule, targets);
@@ -424,6 +432,8 @@ async function createSchedulerRuntime(configPathArg) {
             });
         }
         const downloadManager = new DownloadManager_1.DownloadManager(scopedConfig, pixivClient, database, fileService);
+        if (targetExecutionContexts)
+            downloadManager.setTargetExecutionContexts(targetExecutionContexts);
         if (options.excludedWorkIds)
             downloadManager.setProcessedWorkIds(options.excludedWorkIds);
         activeDownloadManager = downloadManager;

package/dist/delivery/DeliveryLedgerPort.d.ts

@@ -0,0 +1,14 @@
+import { Database } from '../storage/Database';
+import { SchedulerDeliveryPort } from '../scheduler/SlotCoordinator';
+/**
+ * Answers the slot FSM's only delivery question — "does this cell still have an
+ * owner downstream?" — from the durable delivery ledger.
+ *
+ * The distinction matters after a crash: a `delivery_pending` cell whose intent
+ * is still live must be left alone (the OutboxWorker retries THAT work to a
+ * terminal ACK), while one whose intent is terminally failed must be failed
+ * explicitly. Both are read from committed rows, so the answer is the same
+ * before and after a restart — which is exactly what a recovery decision needs.
+ */
+export declare function createDeliveryLedgerPort(database: Database): SchedulerDeliveryPort;
+//# sourceMappingURL=DeliveryLedgerPort.d.ts.map

package/dist/delivery/DeliveryLedgerPort.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createDeliveryLedgerPort = createDeliveryLedgerPort;
+/**
+ * Answers the slot FSM's only delivery question — "does this cell still have an
+ * owner downstream?" — from the durable delivery ledger.
+ *
+ * The distinction matters after a crash: a `delivery_pending` cell whose intent
+ * is still live must be left alone (the OutboxWorker retries THAT work to a
+ * terminal ACK), while one whose intent is terminally failed must be failed
+ * explicitly. Both are read from committed rows, so the answer is the same
+ * before and after a restart — which is exactly what a recovery decision needs.
+ */
+function createDeliveryLedgerPort(database) {
+    return {
+        stateFor({ deliveryTarget, slotId, targetId }) {
+            const rows = database.deliveries.listForCell(deliveryTarget, slotId, targetId);
+            if (rows.length === 0)
+                return { kind: 'unknown' };
+            const confirmed = rows.find((r) => r.status === 'delivered' || r.status === 'duplicate');
+            if (confirmed) {
+                return { kind: 'confirmed', workId: confirmed.pixivId, workType: confirmed.workType };
+            }
+            const pending = rows.filter((r) => r.status === 'pending');
+            // Still actionable = the outbox is going to try again. Its retry budget is
+            // the only thing that may converge this delivery, so keep hands off.
+            if (pending.some((r) => database.outbox.hasActionableDelivery(r.id))) {
+                return { kind: 'live' };
+            }
+            // Either the outbox exhausted its retries (dead/failed) or the intent was
+            // never queued. Nobody will converge it, and re-running selection would
+            // re-point the logical item at a different work — so fail it as-is.
+            if (pending.length > 0 || rows.some((r) => r.status === 'failed')) {
+                return {
+                    kind: 'lost',
+                    reason: 'delivery intent reached a terminal failure without an ACK; failing the cell instead of re-selecting a different work',
+                };
+            }
+            return { kind: 'unknown' };
+        },
+    };
+}
+//# sourceMappingURL=DeliveryLedgerPort.js.map

package/dist/download/DownloadManager.d.ts

@@ -5,6 +5,7 @@ import { IDatabase } from '../interfaces/IDatabase';
 import { IFileService } from '../interfaces/IFileService';
 import { DeliveryService } from '../delivery/DeliveryService';
 import { TargetOutcome } from '../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../scheduler/WorkIdentity';
 /**
  * Download Manager with Concurrency Control
  *
@@ -76,6 +77,10 @@ export declare class DownloadManager implements IDownloadManager {
         slotName: string;
         slotDate: string;
     };
+    /** Per-cell work identity for THIS run, keyed by target id (scheduled runs only). */
+    private targetExecutionContexts;
+    /** Publish the durable cell identity each handler must honour (scheduled runs). */
+    setTargetExecutionContexts(contexts: Map<string, TargetExecutionContext>): void;
     /**
      * Request cooperative cancellation of the current run. In-flight item
      * finishes; no further targets/items are started. runAllTargets() will

package/dist/download/DownloadManager.js

@@ -86,6 +86,12 @@ class DownloadManager {
     }
     /** Slot context propagated to delivery templates/outcomes for scheduled runs. */
     slotContext;
+    /** Per-cell work identity for THIS run, keyed by target id (scheduled runs only). */
+    targetExecutionContexts = new Map();
+    /** Publish the durable cell identity each handler must honour (scheduled runs). */
+    setTargetExecutionContexts(contexts) {
+        this.targetExecutionContexts = contexts;
+    }
     /**
      * Request cooperative cancellation of the current run. In-flight item
      * finishes; no further targets/items are started. runAllTargets() will
@@ -216,11 +222,15 @@ class DownloadManager {
         }
     }
     async dispatchTarget(target) {
+        // The cell identity must reach the handler or it cannot tell a first
+        // selection from a recovery: it would re-rank and silently re-point the
+        // logical item at a different work.
+        const execution = target.id ? this.targetExecutionContexts.get(target.id) : undefined;
         switch (target.type) {
             case 'illustration':
-                return await this.illustrationHandler.handle(target);
+                return await this.illustrationHandler.handle(target, execution);
             case 'novel':
-                return await this.novelHandler.handle(target);
+                return await this.novelHandler.handle(target, execution);
             default:
                 logger_1.logger.warn(`Unsupported target type ${target.type}`);
                 return { kind: 'failed', retryable: false, error: `unsupported target type ${target.type}` };

package/dist/download/handlers/IllustrationTargetHandler.d.ts

@@ -6,6 +6,7 @@ import { IllustrationDownloader } from '../IllustrationDownloader';
 import { DownloadPipeline } from '../pipeline/DownloadPipeline';
 import { DeliveryService } from '../../delivery/DeliveryService';
 import { TargetOutcome } from '../../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../../scheduler/WorkIdentity';
 import type { TopicPipelineFactory } from '../../topic/createTopicPipeline';
 export declare class IllustrationTargetHandler {
     private readonly client;
@@ -17,8 +18,14 @@ export declare class IllustrationTargetHandler {
     private readonly deliveryService?;
     /** Outcomes produced during this handle() call (deliveries + terminal non-matches). */
     private outcomes;
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    private execution;
     constructor(client: IPixivClient, database: IDatabase, rankingService: RankingService, illustrationDownloader: IllustrationDownloader, pipeline: DownloadPipeline, topicPipelineFactory?: TopicPipelineFactory | undefined, deliveryService?: DeliveryService | undefined);
-    handle(target: TargetConfig): Promise<TargetOutcome>;
+    handle(target: TargetConfig, execution?: TargetExecutionContext): Promise<TargetOutcome>;
     /** Reduce the outcomes collected while processing one target to one cell result. */
     private summarize;
     private classifyError;
@@ -35,6 +42,25 @@ export declare class IllustrationTargetHandler {
     private handleUserIllustrations;
     private sortByPopularityAndLog;
     private logError;
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    private recoverLockedWork;
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `illust` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
     private downloadAndDeliver;
     /**
      * Turn a downloaded artifact into the target's business outcome. In cache

package/dist/download/handlers/IllustrationTargetHandler.js

@@ -5,6 +5,7 @@ const logger_1 = require("../../logger");
 const pixiv_date_utils_1 = require("../../utils/pixiv-date-utils");
 const errors_1 = require("../../utils/errors");
 const pixiv_utils_1 = require("../../utils/pixiv-utils");
+const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 class IllustrationTargetHandler {
     client;
@@ -16,6 +17,12 @@ class IllustrationTargetHandler {
     deliveryService;
     /** Outcomes produced during this handle() call (deliveries + terminal non-matches). */
     outcomes = [];
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    execution = null;
     constructor(client, database, rankingService, illustrationDownloader, pipeline, topicPipelineFactory, deliveryService) {
         this.client = client;
         this.database = database;
@@ -25,8 +32,17 @@ class IllustrationTargetHandler {
         this.topicPipelineFactory = topicPipelineFactory;
         this.deliveryService = deliveryService;
     }
-    async handle(target) {
+    async handle(target, execution) {
         this.outcomes = [];
+        this.execution = execution && (0, WorkIdentity_1.isSingleWorkCell)(target) ? execution : null;
+        // A cell that already owns a work is in RECOVERY, not in a new selection.
+        // Crash/shutdown recovery is not an intentional second run: running the
+        // candidate pipeline here would re-rank and could bind this logical item to a
+        // different work than the one it already committed to.
+        if (this.execution?.lockedWorkId) {
+            await this.recoverLockedWork(target, this.execution.lockedWorkId);
+            return this.summarize(target);
+        }
         if (target.illustId) {
             await this.handleSingleIllustration(target);
             return this.summarize(target);
@@ -361,14 +377,96 @@ class IllustrationTargetHandler {
             stack: error instanceof Error ? error.stack : undefined,
         });
     }
-    async downloadAndDeliver(illust, tag, target) {
-        const artifact = await this.illustrationDownloader.downloadIllustration(illust, tag, {
-            aiMetadataCheck: target.aiMetadataCheck === true,
-            maxPageCount: target.maxPageCount,
-            includeDeliveryPreviews: Boolean(target.storageMode === 'cache' && target.delivery?.target?.trim()),
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    async recoverLockedWork(target, lockedWorkId) {
+        const displayTag = (0, target_label_1.getTargetLabel)(target);
+        logger_1.logger.info(`Recovering locked work ${lockedWorkId} for ${displayTag}; candidate selection is skipped`, {
+            slotId: this.execution?.slotId,
+            targetId: this.execution?.targetId,
+            lockedWorkId,
         });
-        if (!artifact)
+        const illustId = Number(lockedWorkId);
+        if (!Number.isFinite(illustId)) {
+            this.outcomes.push({
+                kind: 'failed',
+                retryable: false,
+                error: `LOCKED_WORK_UNAVAILABLE: cell work id "${lockedWorkId}" is not a valid illustration id`,
+            });
             return;
+        }
+        try {
+            const detail = await this.client.getIllustration(illustId);
+            await this.downloadAndDeliver(detail, displayTag, target);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const retryable = (0, errors_1.isRetryableNetworkError)(error);
+            this.logError(error, `Failed to recover locked illustration ${lockedWorkId}`);
+            this.outcomes.push({
+                kind: 'failed',
+                retryable,
+                error: retryable
+                    ? `locked work ${lockedWorkId} could not be fetched (will retry the SAME work): ${message}`
+                    : `LOCKED_WORK_UNAVAILABLE: locked work ${lockedWorkId} is no longer fetchable: ${message}`,
+            });
+        }
+    }
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `illust` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
+    async downloadAndDeliver(illust, tag, target) {
+        const execution = this.execution;
+        const workId = String(illust.id);
+        // Recovery continues a work the cell already bound; it must never be released.
+        const recovering = Boolean(execution?.lockedWorkId);
+        if (execution && !recovering) {
+            const binding = execution.bind(workId, 'illustration');
+            if (!binding.won) {
+                // Another writer elected a different work for this cell. First selection
+                // is authoritative: never process a work the cell does not own.
+                logger_1.logger.warn(`Cell is bound to work ${binding.workId}; declining to select ${workId}`, {
+                    slotId: execution.slotId,
+                    targetId: execution.targetId,
+                    boundWorkId: binding.workId,
+                });
+                return;
+            }
+        }
+        let artifact = null;
+        try {
+            artifact = await this.illustrationDownloader.downloadIllustration(illust, tag, {
+                aiMetadataCheck: target.aiMetadataCheck === true,
+                maxPageCount: target.maxPageCount,
+                includeDeliveryPreviews: Boolean(target.storageMode === 'cache' && target.delivery?.target?.trim()),
+            });
+        }
+        catch (error) {
+            // Nothing was persisted, so the cell may still pick another candidate.
+            if (execution && !recovering)
+                execution.release(workId);
+            throw error;
+        }
+        if (!artifact) {
+            if (execution && !recovering)
+                execution.release(workId);
+            return;
+        }
+        // Committed: the artifact is durable and this work now defines the cell. Even
+        // if enqueue throws below, recovery must resume THIS work — never release.
         this.recordArtifactOutcome(artifact, target);
     }
     /**

package/dist/download/handlers/NovelTargetHandler.d.ts

@@ -6,6 +6,7 @@ import { DownloadPipeline } from '../pipeline/DownloadPipeline';
 import { NovelDownloader } from '../NovelDownloader';
 import { DeliveryService } from '../../delivery/DeliveryService';
 import { TargetOutcome } from '../../scheduler/TargetOutcome';
+import { TargetExecutionContext } from '../../scheduler/WorkIdentity';
 import type { TopicPipelineFactory } from '../../topic/createTopicPipeline';
 export declare class NovelTargetHandler {
     private readonly client;
@@ -16,8 +17,14 @@ export declare class NovelTargetHandler {
     private readonly topicPipelineFactory?;
     private readonly deliveryService?;
     private outcomes;
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    private execution;
     constructor(client: IPixivClient, database: IDatabase, rankingService: RankingService, pipeline: DownloadPipeline, novelDownloader: NovelDownloader, topicPipelineFactory?: TopicPipelineFactory | undefined, deliveryService?: DeliveryService | undefined);
-    handle(target: TargetConfig): Promise<TargetOutcome>;
+    handle(target: TargetConfig, execution?: TargetExecutionContext): Promise<TargetOutcome>;
     private summarize;
     private classifyError;
     private fetchNovels;
@@ -34,6 +41,25 @@ export declare class NovelTargetHandler {
     private handleUserNovels;
     private sortByPopularityAndLog;
     private logError;
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    private recoverLockedWork;
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `novel` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
     private downloadAndDeliver;
 }
 //# sourceMappingURL=NovelTargetHandler.d.ts.map

package/dist/download/handlers/NovelTargetHandler.js

@@ -5,6 +5,7 @@ const logger_1 = require("../../logger");
 const errors_1 = require("../../utils/errors");
 const pixiv_date_utils_1 = require("../../utils/pixiv-date-utils");
 const pixiv_utils_1 = require("../../utils/pixiv-utils");
+const WorkIdentity_1 = require("../../scheduler/WorkIdentity");
 const target_label_1 = require("../../utils/target-label");
 class NovelTargetHandler {
     client;
@@ -15,6 +16,12 @@ class NovelTargetHandler {
     topicPipelineFactory;
     deliveryService;
     outcomes = [];
+    /**
+     * Cell identity for this handle() call. Set only for a single-work cell of a
+     * scheduled occurrence; null for ad-hoc runs and N-works-per-run targets, which
+     * have no single (slotId,targetId) -> workId identity to honour.
+     */
+    execution = null;
     constructor(client, database, rankingService, pipeline, novelDownloader, topicPipelineFactory, deliveryService) {
         this.client = client;
         this.database = database;
@@ -24,8 +31,17 @@ class NovelTargetHandler {
         this.topicPipelineFactory = topicPipelineFactory;
         this.deliveryService = deliveryService;
     }
-    async handle(target) {
+    async handle(target, execution) {
         this.outcomes = [];
+        this.execution = execution && (0, WorkIdentity_1.isSingleWorkCell)(target) ? execution : null;
+        // A cell that already owns a work is in RECOVERY, not in a new selection.
+        // Crash/shutdown recovery is not an intentional second run: running the
+        // candidate pipeline here would re-rank and could bind this logical item to a
+        // different work than the one it already committed to.
+        if (this.execution?.lockedWorkId) {
+            await this.recoverLockedWork(target, this.execution.lockedWorkId);
+            return this.summarize();
+        }
         if (target.novelId !== undefined && target.novelId !== null && target.novelId !== '') {
             const novelNum = typeof target.novelId === 'number' ? target.novelId : Number(target.novelId);
             if (!Number.isFinite(novelNum)) {
@@ -410,10 +426,98 @@ class NovelTargetHandler {
             stack: error instanceof Error ? error.stack : undefined,
         });
     }
+    /**
+     * Continue the work this cell ALREADY owns. Selection is deliberately skipped:
+     * no search, no ranking, no topic expansion, no backfill pool, and no
+     * "already downloaded / already delivered" exclusion — the cell's own work must
+     * never be filtered out of its own recovery.
+     *
+     * A locked work that is permanently gone is a terminal failure of THIS logical
+     * item (`LOCKED_WORK_UNAVAILABLE`). It is never silently replaced by another
+     * candidate; that would mutate the item's identity behind the operator's back.
+     */
+    async recoverLockedWork(target, lockedWorkId) {
+        const displayTag = (0, target_label_1.getTargetLabel)(target);
+        logger_1.logger.info(`Recovering locked work ${lockedWorkId} for ${displayTag}; candidate selection is skipped`, {
+            slotId: this.execution?.slotId,
+            targetId: this.execution?.targetId,
+            lockedWorkId,
+        });
+        const novelId = Number(lockedWorkId);
+        if (!Number.isFinite(novelId)) {
+            this.outcomes.push({
+                kind: 'failed',
+                retryable: false,
+                error: `LOCKED_WORK_UNAVAILABLE: cell work id "${lockedWorkId}" is not a valid novel id`,
+            });
+            return;
+        }
+        try {
+            const detail = await this.client.getNovelDetail(novelId);
+            const novel = {
+                id: detail.id,
+                title: detail.title,
+                user: detail.user,
+                create_date: detail.create_date,
+            };
+            await this.downloadAndDeliver(novel, `novel-${novelId}`, target);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            const retryable = (0, errors_1.isRetryableNetworkError)(error);
+            this.logError(error, `Failed to recover locked novel ${lockedWorkId}`);
+            this.outcomes.push({
+                kind: 'failed',
+                retryable,
+                error: retryable
+                    ? `locked work ${lockedWorkId} could not be fetched (will retry the SAME work): ${message}`
+                    : `LOCKED_WORK_UNAVAILABLE: locked work ${lockedWorkId} is no longer fetchable: ${message}`,
+            });
+        }
+    }
+    /**
+     * Process ONE candidate work for this cell.
+     *
+     * The cell is bound to `novel` BEFORE any side effect: it is the binding, not
+     * the candidate list, that decides what a later recovery resumes. The binding
+     * is only rolled back when the attempt produced no artifact at all, so in-run
+     * backfill still works for a cell that has committed to nothing.
+     */
     async downloadAndDeliver(novel, tag, target) {
-        const artifact = await this.novelDownloader.download(novel, tag, target);
-        if (!artifact)
+        const execution = this.execution;
+        const workId = String(novel.id);
+        // Recovery continues a work the cell already bound; it must never be released.
+        const recovering = Boolean(execution?.lockedWorkId);
+        if (execution && !recovering) {
+            const binding = execution.bind(workId, 'novel');
+            if (!binding.won) {
+                // Another writer elected a different work for this cell. First selection
+                // is authoritative: never process a work the cell does not own.
+                logger_1.logger.warn(`Cell is bound to work ${binding.workId}; declining to select ${workId}`, {
+                    slotId: execution.slotId,
+                    targetId: execution.targetId,
+                    boundWorkId: binding.workId,
+                });
+                return;
+            }
+        }
+        let artifact;
+        try {
+            artifact = await this.novelDownloader.download(novel, tag, target);
+        }
+        catch (error) {
+            // Nothing was persisted, so the cell may still pick another candidate.
+            if (execution && !recovering)
+                execution.release(workId);
+            throw error;
+        }
+        if (!artifact) {
+            if (execution && !recovering)
+                execution.release(workId);
             return;
+        }
+        // Committed: the artifact is durable and this work now defines the cell. Even
+        // if the delivery below throws, recovery must resume THIS work — never release.
         const isDelivery = target.storageMode === 'cache' && target.delivery?.target?.trim();
         if (!isDelivery || !this.deliveryService) {
             this.outcomes.push({ kind: 'stored', workId: artifact.pixivId, workType: artifact.type });

package/dist/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow",
-  "version": "2.19.2",
+  "version": "2.19.3",
   "private": true
 }

package/dist/pixiv-client/TargetSearchRunner.js

@@ -56,10 +56,10 @@ class TargetSearchRunner {
         return target.limit ? sorted.slice(0, target.limit) : sorted;
     }
     async searchSingleIllust(target, tag, requestDelayMs, signal) {
-        return this.searchWithPagination(target, tag, requestDelayMs, (options) => this.kit.illustrations.searchPage(options), (t, g) => (0, query_mapper_1.mapTargetToIllustQuery)({ ...t, tag: g }), signal);
+        return this.searchWithPagination(target, tag, requestDelayMs, (options, cursor) => this.kit.illustrations.searchPage(options, cursor), (t, g) => (0, query_mapper_1.mapTargetToIllustQuery)({ ...t, tag: g }), signal);
     }
     async searchSingleNovel(target, tag, requestDelayMs, signal) {
-        return this.searchWithPagination(target, tag, requestDelayMs, (options) => this.kit.novels.searchPage(options), (t, g) => (0, query_mapper_1.mapTargetToNovelQuery)({ ...t, tag: g }), signal);
+        return this.searchWithPagination(target, tag, requestDelayMs, (options, cursor) => this.kit.novels.searchPage(options, cursor), (t, g) => (0, query_mapper_1.mapTargetToNovelQuery)({ ...t, tag: g }), signal);
     }
     /**
      * Date-aware pagination. Mirrors the legacy SearchService semantics:
@@ -96,23 +96,39 @@ class TargetSearchRunner {
         let cursor = null;
         let pageCount = 0;
         let shouldStop = false;
+        // Progress invariant: every iteration must terminate, advance to a cursor we
+        // have never fetched, or fail explicitly. A cursor that repeats (same `next`
+        // twice, or an A -> B -> A cycle) proves the upstream adapter is not making
+        // progress; re-requesting would spin forever, so we refuse instead.
+        const seenCursors = new Set();
         while ((!fetchLimit || results.length < fetchLimit) && !shouldStop) {
             (0, errors_1.throwIfAborted)(signal, 'search cancelled');
             pageCount++;
             // Dates are intentionally filtered CLIENT-side below (legacy behavior;
             // PixivFlow needs the early-stop walk on create_date).
+            //
+            // The cursor must travel as searchPage's SECOND POSITIONAL argument: the
+            // kit reads `options.cursor` only inside its own `search()`. Putting it in
+            // the options object left the cursor permanently null, so page 1 (the
+            // newest works) was re-fetched on every iteration and a search that found
+            // no in-range work on that page never terminated.
             const page = await fetchOne({
                 word: base.word,
                 sort: base.sort,
                 searchTarget: base.searchTarget,
                 includeR18: base.includeR18,
-                cursor,
-                // Threaded into the kit transport, which combines it with its per-request
-                // timeout and honours it in retry back-off. Without this the pager could
-                // stay blocked in a single hung request for the rest of the run.
                 signal,
-            });
-            cursor = page.next;
+            }, cursor);
+            const nextCursor = page.next;
+            if (nextCursor !== null) {
+                if (nextCursor === cursor || seenCursors.has(nextCursor)) {
+                    throw new errors_1.PaginationError(`Search pager for tag "${tag}" did not advance: page ${pageCount} returned a cursor that ` +
+                        (nextCursor === cursor ? 'equals the one just fetched' : 'was already fetched') +
+                        `. Refusing to re-request it indefinitely.`);
+                }
+                seenCursors.add(nextCursor);
+            }
+            cursor = nextCursor;
             for (const item of page.items) {
                 const decision = this.filterItemByDate(item, target, startDate, endDate, sortMode);
                 if (decision.shouldStop) {

package/dist/scheduler/SlotCoordinator.d.ts

@@ -3,6 +3,7 @@ import { Database } from '../storage/Database';
 import { CellStatus, SlotItemRecord, SlotRecord, SlotStatus } from '../storage/repositories/SlotRepository';
 import { TriggerSource } from './OccurrenceResolver';
 import { TargetOutcome } from './TargetOutcome';
+import { TargetExecutionContext, WorkBinding } from './WorkIdentity';
 /**
  * Execution-lease TTL and heartbeat cadence.
  *
@@ -54,6 +55,40 @@ export interface SlotResolveResult {
     error?: string;
     status?: number;
 }
+/**
+ * What a `delivery_pending` cell still owes downstream, read from the durable
+ * delivery ledger.
+ *
+ *  - `live`      : a non-terminal intent still owns the cell — the outbox is
+ *                  retrying THAT work toward a terminal ACK.
+ *  - `confirmed` : the ACK already landed but the cell promotion was lost.
+ *  - `lost`      : the intent is terminally failed; nobody will converge it.
+ *  - `unknown`   : no delivery fact for this cell (not a delivery cell).
+ */
+export type CellDeliveryState = {
+    kind: 'live';
+} | {
+    kind: 'confirmed';
+    workId: string;
+    workType: string;
+} | {
+    kind: 'lost';
+    reason: string;
+} | {
+    kind: 'unknown';
+};
+/**
+ * Port for the delivery ledger, injected by the runtime. It lets the slot FSM
+ * hand a `delivery_pending` cell to whoever owns its delivery without this class
+ * learning anything about TelePost, bots or any hosting platform (see below).
+ */
+export interface SchedulerDeliveryPort {
+    stateFor(input: {
+        deliveryTarget: string;
+        slotId: string;
+        targetId: string;
+    }): CellDeliveryState;
+}
 /**
  * Owns the Schedule Slot ledger for one scheduler run. A Slot is one durable
  * execution occurrence of a Schedule (NOT a morning/evening row). It ensures
@@ -66,7 +101,8 @@ export interface SlotResolveResult {
  */
 export declare class SlotCoordinator {
     private readonly database;
-    constructor(database: Database);
+    private readonly delivery?;
+    constructor(database: Database, delivery?: SchedulerDeliveryPort | undefined);
     /**
      * Resolve + validate the canonical occurrence for a trigger. Uses ONLY the
      * schedule's cron + timezone and the trigger instant (never a client-supplied
@@ -103,8 +139,33 @@ export declare class SlotCoordinator {
         target: TargetConfig;
         cell: SlotItemRecord;
     }[];
+    /**
+     * Build the per-target execution contexts for one run, so every handler
+     * receives the cell's durable identity instead of just a TargetConfig.
+     *
+     * This is the boundary where the identity used to be dropped (`pending` was
+     * reduced to `p.target`), which is what let a resume re-rank and re-point the
+     * logical item at a different work.
+     */
+    executionContextsFor(slotId: string, entries: {
+        target: TargetConfig;
+        cell: SlotItemRecord | null;
+    }[]): Map<string, TargetExecutionContext>;
     /** Lock the selected work for a cell (first selection wins; retries keep it). */
     lockWork(slotId: string, targetId: string, workId: string, workType: string): void;
+    /**
+     * CAS-bind a cell to the work a handler is about to process. Returns the
+     * authoritative binding: when another worker already elected a different work,
+     * `won` is false and the caller MUST continue with the returned `workId`
+     * instead of its own candidate.
+     */
+    lockWorkCas(slotId: string, targetId: string, workId: string, workType: string): WorkBinding;
+    /**
+     * Release a provisional binding whose work produced no local artifact, so the
+     * next candidate of an UNBOUND cell can be tried. Refused once anything was
+     * committed (see SlotRepository.releaseCellWork).
+     */
+    releaseWorkCas(slotId: string, targetId: string, workId: string): void;
     /** Record a cell's terminal state from the download/delivery outcome. */
     markCell(slotId: string, targetId: string, status: CellStatus, error?: string): void;
     /**
@@ -116,6 +177,18 @@ export declare class SlotCoordinator {
     applyOutcome(slotId: string, targetId: string, outcome: TargetOutcome): void;
     /** Promote a delivery_pending cell to submitted from a confirmed ACK. */
     markDelivered(slotId: string, targetId: string, workId: string, workType: string): void;
+    /**
+     * Decide what a `delivery_pending` cell owes, from the durable delivery
+     * ledger, and converge the FSM accordingly. Returns true when the scheduler
+     * must NOT run the target handler for it.
+     *
+     * Once an intent is durable the outbox owns the delivery: re-running selection
+     * could only produce a DIFFERENT work for the same logical item (and a second
+     * delivery, since the delivery idempotency key is work-scoped). A terminally
+     * failed delivery is converged explicitly — never "repaired" by picking
+     * another work behind the operator's back.
+     */
+    private settlePendingDelivery;
     private safeTransition;
     /** Cross-process execution lease. Duplicate triggers converge, never parallel-run. */
     claimRunLease(slotId: string, owner: string, leaseMs: number): boolean;

package/dist/scheduler/SlotCoordinator.js

@@ -4,6 +4,7 @@ exports.SlotCoordinator = exports.SLOT_HEARTBEAT_MS = exports.SLOT_LEASE_TTL_MS
 exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
+const WorkIdentity_1 = require("./WorkIdentity");
 /**
  * Execution-lease TTL and heartbeat cadence.
  *
@@ -17,6 +18,13 @@ const OccurrenceResolver_1 = require("./OccurrenceResolver");
  */
 exports.SLOT_LEASE_TTL_MS = 3 * 60 * 1000;
 exports.SLOT_HEARTBEAT_MS = 30 * 1000;
+/** The delivery channel a scheduled cell publishes to (null = download-only). */
+function deliveryTargetOf(target) {
+    if (target.storageMode !== 'cache')
+        return null;
+    const name = target.delivery?.target;
+    return typeof name === 'string' && name.trim() ? name.trim() : null;
+}
 /**
  * Owns the Schedule Slot ledger for one scheduler run. A Slot is one durable
  * execution occurrence of a Schedule (NOT a morning/evening row). It ensures
@@ -29,8 +37,10 @@ exports.SLOT_HEARTBEAT_MS = 30 * 1000;
  */
 class SlotCoordinator {
     database;
-    constructor(database) {
+    delivery;
+    constructor(database, delivery) {
         this.database = database;
+        this.delivery = delivery;
     }
     /**
      * Resolve + validate the canonical occurrence for a trigger. Uses ONLY the
@@ -133,15 +143,65 @@ class SlotCoordinator {
                 continue;
             if (cell.status === 'submitted' || cell.status === 'no_candidate')
                 continue;
+            // A cell whose work already has a durable delivery intent is NOT the
+            // scheduler's to re-run: the OutboxWorker retries the SAME work to a
+            // terminal ACK. Re-selecting here is what let recovery stop pointing at the
+            // cell's own work (or enqueue a second one), so it is delegated instead.
+            if (cell.status === 'delivery_pending' && (0, WorkIdentity_1.isSingleWorkCell)(target) && this.settlePendingDelivery(slotId, target)) {
+                continue;
+            }
             out.push({ target, cell });
         }
         return out;
     }
+    /**
+     * Build the per-target execution contexts for one run, so every handler
+     * receives the cell's durable identity instead of just a TargetConfig.
+     *
+     * This is the boundary where the identity used to be dropped (`pending` was
+     * reduced to `p.target`), which is what let a resume re-rank and re-point the
+     * logical item at a different work.
+     */
+    executionContextsFor(slotId, entries) {
+        const contexts = new Map();
+        for (const { target, cell } of entries) {
+            if (!target.id || !cell)
+                continue;
+            const targetId = target.id;
+            contexts.set(targetId, {
+                slotId,
+                targetId,
+                lockedWorkId: cell.workId,
+                bind: (workId, workType) => this.lockWorkCas(slotId, targetId, workId, workType),
+                release: (workId) => this.releaseWorkCas(slotId, targetId, workId),
+            });
+        }
+        return contexts;
+    }
     /** Lock the selected work for a cell (first selection wins; retries keep it). */
     lockWork(slotId, targetId, workId, workType) {
         this.database.slots.ensureCell(slotId, targetId, workType);
         this.database.slots.lockCellWork(slotId, targetId, workId, workType);
     }
+    /**
+     * CAS-bind a cell to the work a handler is about to process. Returns the
+     * authoritative binding: when another worker already elected a different work,
+     * `won` is false and the caller MUST continue with the returned `workId`
+     * instead of its own candidate.
+     */
+    lockWorkCas(slotId, targetId, workId, workType) {
+        this.database.slots.ensureCell(slotId, targetId, workType);
+        const { cell, won } = this.database.slots.tryLockCellWork(slotId, targetId, workId, workType);
+        return { workId: cell.workId ?? workId, won };
+    }
+    /**
+     * Release a provisional binding whose work produced no local artifact, so the
+     * next candidate of an UNBOUND cell can be tried. Refused once anything was
+     * committed (see SlotRepository.releaseCellWork).
+     */
+    releaseWorkCas(slotId, targetId, workId) {
+        this.database.slots.releaseCellWork(slotId, targetId, workId);
+    }
     /** Record a cell's terminal state from the download/delivery outcome. */
     markCell(slotId, targetId, status, error) {
         const cell = this.database.slots.getCell(slotId, targetId);
@@ -203,6 +263,53 @@ class SlotCoordinator {
         this.database.slots.lockCellWork(slotId, targetId, workId, workType);
         this.safeTransition(slotId, targetId, 'submitted');
     }
+    /**
+     * Decide what a `delivery_pending` cell owes, from the durable delivery
+     * ledger, and converge the FSM accordingly. Returns true when the scheduler
+     * must NOT run the target handler for it.
+     *
+     * Once an intent is durable the outbox owns the delivery: re-running selection
+     * could only produce a DIFFERENT work for the same logical item (and a second
+     * delivery, since the delivery idempotency key is work-scoped). A terminally
+     * failed delivery is converged explicitly — never "repaired" by picking
+     * another work behind the operator's back.
+     */
+    settlePendingDelivery(slotId, target) {
+        const deliveryTarget = deliveryTargetOf(target);
+        if (!deliveryTarget || !this.delivery || !target.id)
+            return false;
+        const state = this.delivery.stateFor({ deliveryTarget, slotId, targetId: target.id });
+        switch (state.kind) {
+            case 'live':
+                logger_1.logger.info('Cell delivery still owned by the outbox; selection not re-run', {
+                    slot: slotId,
+                    target: target.id,
+                    deliveryTarget,
+                });
+                return true;
+            case 'confirmed':
+                // The ACK landed but the promotion was lost (crash between the delivery
+                // ledger write and the cell transition). Heal from the ledger — the work
+                // IS delivered, so re-selecting would post a second one.
+                logger_1.logger.info('Cell delivery already confirmed; promoting the cell from the ledger', {
+                    slot: slotId,
+                    target: target.id,
+                    workId: state.workId,
+                });
+                this.markDelivered(slotId, target.id, state.workId, state.workType);
+                return true;
+            case 'lost':
+                logger_1.logger.warn('Cell delivery failed terminally; failing the cell instead of re-selecting', {
+                    slot: slotId,
+                    target: target.id,
+                    reason: state.reason,
+                });
+                this.applyOutcome(slotId, target.id, { kind: 'failed', retryable: false, error: state.reason });
+                return true;
+            case 'unknown':
+                return false;
+        }
+    }
     safeTransition(slotId, targetId, next, error) {
         try {
             this.database.slots.transitionCell(slotId, targetId, next, error);

package/dist/scheduler/WorkIdentity.d.ts

@@ -0,0 +1,49 @@
+import { TargetConfig } from '../config';
+/**
+ * Work identity for a scheduled cell.
+ *
+ * Invariant: (slotId, targetId) -> ONE stable workId. The first selection wins,
+ * and every later crash / shutdown / lease recovery continues with THAT work.
+ * Re-running candidate selection on resume silently re-points the logical item
+ * at a different work (A -> B): the item then reports success while A sits
+ * downloaded-but-never-delivered, and if A's delivery intent was already
+ * durable both A and B get posted under different idempotency identities.
+ */
+export interface WorkBinding {
+    /** Authoritative work id for the cell after the attempt (the CAS winner). */
+    workId: string;
+    /** True when this caller established — or already held — the binding. */
+    won: boolean;
+}
+/**
+ * Per-cell execution context handed to a target handler, so the cell's identity
+ * travels with the work instead of being dropped at the dispatch boundary.
+ *
+ * `lockedWorkId` is an authoritative INPUT: when it is set, the handler must
+ * continue exactly that work and must not run ranking / topic selection /
+ * backfill / already-seen filtering. `bind()` is called for a candidate BEFORE
+ * any of its side effects, so a crash during the download can never resume the
+ * cell onto a different work.
+ */
+export interface TargetExecutionContext {
+    readonly slotId: string;
+    readonly targetId: string;
+    /** The work this logical item is already bound to; null for a fresh cell. */
+    readonly lockedWorkId: string | null;
+    /** CAS-bind the cell to `workId`; returns the authoritative binding. */
+    bind(workId: string, workType: string): WorkBinding;
+    /** Roll back a provisional binding for a work that produced no artifact. */
+    release(workId: string): void;
+}
+/**
+ * True when one cell of this target selects at most ONE work per run — the only
+ * shape the (slotId, targetId) -> workId invariant can hold for.
+ *
+ * A target that intentionally pulls N works per run (limit > 1, a novel series,
+ * a user feed) owns N works inside a single cell, so pinning that cell to one
+ * locked id on resume would silently shrink the run to a single work. Those keep
+ * per-run candidate selection; the work-identity contract covers single-work
+ * cells, which is what a scheduled "one post per slot" target is.
+ */
+export declare function isSingleWorkCell(target: TargetConfig): boolean;
+//# sourceMappingURL=WorkIdentity.d.ts.map

package/dist/scheduler/WorkIdentity.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isSingleWorkCell = isSingleWorkCell;
+/**
+ * True when one cell of this target selects at most ONE work per run — the only
+ * shape the (slotId, targetId) -> workId invariant can hold for.
+ *
+ * A target that intentionally pulls N works per run (limit > 1, a novel series,
+ * a user feed) owns N works inside a single cell, so pinning that cell to one
+ * locked id on resume would silently shrink the run to a single work. Those keep
+ * per-run candidate selection; the work-identity contract covers single-work
+ * cells, which is what a scheduled "one post per slot" target is.
+ */
+function isSingleWorkCell(target) {
+    // An explicit limit is the operator's own answer to "how many per run?".
+    if (typeof target.limit === 'number' && target.limit > 0)
+        return target.limit === 1;
+    // Pinned single-work targets.
+    if (target.type === 'novel' && target.novelId !== undefined && target.novelId !== null)
+        return true;
+    if (target.type !== 'novel' && target.illustId)
+        return true;
+    // N-work containers never collapse into a single identity.
+    if (target.userId)
+        return false;
+    if (target.type === 'novel' && target.seriesId)
+        return false;
+    // Search/ranking default to ten works per run; a topic run defaults to one.
+    return target.mode === 'topic';
+}
+//# sourceMappingURL=WorkIdentity.js.map

package/dist/storage/repositories/DeliveryRepository.d.ts

@@ -43,6 +43,15 @@ export declare class DeliveryRepository extends BaseRepository {
     };
     getById(id: string): DeliveryRow | null;
     getByIdempotencyKey(key: string): DeliveryRow | null;
+    /**
+     * Every delivery intent this ledger recorded for ONE slot cell, oldest first.
+     *
+     * Scoped by (slot_id, target_id) on purpose: the dedup key above is per WORK,
+     * so it structurally cannot answer "does this logical item still owe a
+     * delivery?" — which is the question crash recovery has to ask before it is
+     * allowed to re-run selection for a `delivery_pending` cell.
+     */
+    listForCell(deliveryTarget: string, slotId: string, targetId: string): DeliveryRow[];
     /**
      * True when this exact work is already CONFIRMED (delivered, or an attested
      * historical duplicate) for this target. Pending/failed intents do not block

package/dist/storage/repositories/DeliveryRepository.js

@@ -39,6 +39,22 @@ class DeliveryRepository extends BaseRepository_1.BaseRepository {
         const row = this.db.prepare(`SELECT * FROM deliveries WHERE idempotency_key = ?`).get(key);
         return row ? this.toRow(row) : null;
     }
+    /**
+     * Every delivery intent this ledger recorded for ONE slot cell, oldest first.
+     *
+     * Scoped by (slot_id, target_id) on purpose: the dedup key above is per WORK,
+     * so it structurally cannot answer "does this logical item still owe a
+     * delivery?" — which is the question crash recovery has to ask before it is
+     * allowed to re-run selection for a `delivery_pending` cell.
+     */
+    listForCell(deliveryTarget, slotId, targetId) {
+        const rows = this.db
+            .prepare(`SELECT * FROM deliveries
+         WHERE delivery_target = ? AND slot_id = ? AND target_id = ?
+         ORDER BY created_at ASC`)
+            .all(deliveryTarget, slotId, targetId);
+        return rows.map((r) => this.toRow(r));
+    }
     /**
      * True when this exact work is already CONFIRMED (delivered, or an attested
      * historical duplicate) for this target. Pending/failed intents do not block

package/dist/storage/repositories/OutboxRepository.d.ts

@@ -72,6 +72,15 @@ export declare class OutboxRepository extends BaseRepository {
     enqueue(input: NewOutboxItem, now?: number): OutboxRow;
     get(id: string): OutboxRow | null;
     getByKey(kind: OutboxKind, key: string): OutboxRow | null;
+    /**
+     * True when this delivery intent still has a row the worker can act on
+     * (pending / claimed / waiting to retry).
+     *
+     * This is the "the outbox still owns it" test. A delivery whose outbox row is
+     * done/dead/cancelled is NOT actionable: whatever happened downstream is
+     * terminal, so nobody is going to converge that delivery by retrying it.
+     */
+    hasActionableDelivery(deliveryId: string): boolean;
     list(status?: OutboxStatus, limit?: number): OutboxRow[];
     /**
      * Claim up to `limit` due rows for `owner`. Due = pending/retry_wait whose

package/dist/storage/repositories/OutboxRepository.js

@@ -53,6 +53,23 @@ class OutboxRepository extends BaseRepository_1.BaseRepository {
             .get(kind, key);
         return row ? this.toRow(row) : null;
     }
+    /**
+     * True when this delivery intent still has a row the worker can act on
+     * (pending / claimed / waiting to retry).
+     *
+     * This is the "the outbox still owns it" test. A delivery whose outbox row is
+     * done/dead/cancelled is NOT actionable: whatever happened downstream is
+     * terminal, so nobody is going to converge that delivery by retrying it.
+     */
+    hasActionableDelivery(deliveryId) {
+        const row = this.db
+            .prepare(`SELECT 1 FROM outbox
+         WHERE delivery_id = ? AND kind = 'delivery'
+           AND status IN ('pending','processing','retry_wait')
+         LIMIT 1`)
+            .get(deliveryId);
+        return Boolean(row);
+    }
     list(status, limit = 100) {
         const bounded = Math.max(1, Math.min(Math.trunc(limit), 500));
         const rows = status

package/dist/storage/repositories/SlotRepository.d.ts

@@ -92,6 +92,33 @@ export declare class SlotRepository extends BaseRepository {
      * candidate replacement is a separate explicit operator action (clearCellWork).
      */
     lockCellWork(slotId: string, targetId: string, workId: string, workType: string): SlotItemRecord;
+    /**
+     * Compare-and-set the cell's work binding, with real concurrency semantics.
+     *
+     * `lockCellWork` above only stops *this* process from overwriting an existing
+     * id (COALESCE); it cannot elect a winner between two callers that both read
+     * "no binding". This one can: the write is guarded by `work_id IS NULL OR
+     * work_id = @workId`, so if two workers select A and B at the same instant
+     * exactly one UPDATE lands. The returned record is authoritative — a losing
+     * caller MUST continue with `cell.workId`, never with its own candidate, or
+     * the cell would process a work it does not own.
+     */
+    tryLockCellWork(slotId: string, targetId: string, workId: string, workType: string): {
+        cell: SlotItemRecord;
+        won: boolean;
+    };
+    /**
+     * Roll back a PROVISIONAL binding taken for a work that produced no local
+     * artifact (a candidate that failed while the cell was still unbound).
+     *
+     * Deliberately narrow: it only clears the row while it still holds exactly
+     * `workId` AND is still `selected`. Once the cell moved on (an artifact was
+     * persisted -> delivery_pending/submitted/..., or another writer rebound it)
+     * the release is refused, so it can never erase a committed work identity.
+     * Re-selecting is only ever allowed while nothing was committed — that is what
+     * keeps (slotId,targetId) -> workId stable.
+     */
+    releaseCellWork(slotId: string, targetId: string, workId: string): boolean;
     /** Explicit operator action: forget the locked work so a re-run picks another candidate. */
     clearCellWork(slotId: string, targetId: string): void;
     setCellStatus(slotId: string, targetId: string, status: CellStatus, error?: string): void;

package/dist/storage/repositories/SlotRepository.js

@@ -137,6 +137,51 @@ class SlotRepository extends BaseRepository_1.BaseRepository {
             .run({ slotId, targetId, workId, workType });
         return this.getCell(slotId, targetId);
     }
+    /**
+     * Compare-and-set the cell's work binding, with real concurrency semantics.
+     *
+     * `lockCellWork` above only stops *this* process from overwriting an existing
+     * id (COALESCE); it cannot elect a winner between two callers that both read
+     * "no binding". This one can: the write is guarded by `work_id IS NULL OR
+     * work_id = @workId`, so if two workers select A and B at the same instant
+     * exactly one UPDATE lands. The returned record is authoritative — a losing
+     * caller MUST continue with `cell.workId`, never with its own candidate, or
+     * the cell would process a work it does not own.
+     */
+    tryLockCellWork(slotId, targetId, workId, workType) {
+        this.db
+            .prepare(`UPDATE schedule_slot_items
+         SET work_id = @workId,
+             work_type = CASE WHEN work_id IS NULL THEN @workType ELSE work_type END,
+             status = CASE WHEN status = 'pending' THEN 'selected' ELSE status END,
+             attempt_count = CASE WHEN work_id IS NULL THEN attempt_count + 1 ELSE attempt_count END,
+             updated_at = CURRENT_TIMESTAMP
+         WHERE slot_id = @slotId AND target_id = @targetId
+           AND (work_id IS NULL OR work_id = @workId)`)
+            .run({ slotId, targetId, workId, workType });
+        const cell = this.getCell(slotId, targetId);
+        return { cell, won: cell.workId === workId };
+    }
+    /**
+     * Roll back a PROVISIONAL binding taken for a work that produced no local
+     * artifact (a candidate that failed while the cell was still unbound).
+     *
+     * Deliberately narrow: it only clears the row while it still holds exactly
+     * `workId` AND is still `selected`. Once the cell moved on (an artifact was
+     * persisted -> delivery_pending/submitted/..., or another writer rebound it)
+     * the release is refused, so it can never erase a committed work identity.
+     * Re-selecting is only ever allowed while nothing was committed — that is what
+     * keeps (slotId,targetId) -> workId stable.
+     */
+    releaseCellWork(slotId, targetId, workId) {
+        const info = this.db
+            .prepare(`UPDATE schedule_slot_items
+         SET work_id = NULL, status = 'pending', updated_at = CURRENT_TIMESTAMP
+         WHERE slot_id = @slotId AND target_id = @targetId
+           AND work_id = @workId AND status = 'selected'`)
+            .run({ slotId, targetId, workId });
+        return info.changes > 0;
+    }
     /** Explicit operator action: forget the locked work so a re-run picks another candidate. */
     clearCellWork(slotId, targetId) {
         this.db

package/dist/topic/TopicPipeline.js

@@ -123,6 +123,10 @@ class TopicPipeline {
             // A cancellation must not be degraded into "no results for this tag": that
             // would silently continue the cancelled run across the remaining tags.
             (0, errors_1.rethrowIfCancelled)(error, this.signal);
+            // A broken pager contract must not degrade either: reporting "no works
+            // today" would hide the failure and let the run claim success.
+            if (error instanceof errors_1.PaginationError)
+                throw error;
             logger_1.logger.warn('[TopicCollector] search failed tag=' + tag + ' type=' + contentType + ': ' + (error instanceof Error ? error.message : String(error)));
             return [];
         }

package/dist/utils/errors.d.ts

@@ -33,6 +33,15 @@ export declare class NetworkError extends PixivFlowError {
         waitTime?: number;
     });
 }
+/**
+ * The pagination adapter returned a cursor it had already handed back (the same
+ * `next` twice, or a cycle). Re-requesting would repeat the previous page
+ * forever, which is exactly the Attempt 2 fallback-day failure, so the pager
+ * fails deterministically instead of spinning.
+ */
+export declare class PaginationError extends PixivFlowError {
+    constructor(message: string, cause?: Error);
+}
 export declare class DownloadError extends PixivFlowError {
     readonly itemId?: number | undefined;
     readonly itemType?: "illustration" | "novel" | undefined;

package/dist/utils/errors.js

@@ -4,7 +4,7 @@
  * Provides consistent error types and handling patterns across the application
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ErrorRecoveryStrategy = exports.HelpRequest = exports.VersionRequest = exports.OperationCancelledError = exports.DatabaseError = exports.PendingDeliveryError = exports.DownloadError = exports.NetworkError = exports.AuthenticationError = exports.ConfigError = exports.PixivFlowError = exports.PixivTimeoutError = exports.PixivRateLimitError = exports.PixivNotFoundError = exports.PixivNetworkError = exports.PixivHttpError = exports.PixivError = void 0;
+exports.ErrorRecoveryStrategy = exports.HelpRequest = exports.VersionRequest = exports.OperationCancelledError = exports.DatabaseError = exports.PendingDeliveryError = exports.DownloadError = exports.PaginationError = exports.NetworkError = exports.AuthenticationError = exports.ConfigError = exports.PixivFlowError = exports.PixivTimeoutError = exports.PixivRateLimitError = exports.PixivNotFoundError = exports.PixivNetworkError = exports.PixivHttpError = exports.PixivError = void 0;
 exports.isPixivKitError = isPixivKitError;
 exports.toNetworkError = toNetworkError;
 exports.isOperationCancelled = isOperationCancelled;
@@ -92,6 +92,19 @@ class NetworkError extends PixivFlowError {
     }
 }
 exports.NetworkError = NetworkError;
+/**
+ * The pagination adapter returned a cursor it had already handed back (the same
+ * `next` twice, or a cycle). Re-requesting would repeat the previous page
+ * forever, which is exactly the Attempt 2 fallback-day failure, so the pager
+ * fails deterministically instead of spinning.
+ */
+class PaginationError extends PixivFlowError {
+    constructor(message, cause) {
+        super(message, 'PAGINATION_ERROR', undefined, cause);
+        this.name = 'PaginationError';
+    }
+}
+exports.PaginationError = PaginationError;
 class DownloadError extends PixivFlowError {
     itemId;
     itemType;

package/dist/version.js

@@ -2,5 +2,5 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.BUILD = void 0;
 // GENERATED by scripts/write-version.js — do not edit manually.
-exports.BUILD = { version: '2.19.2', commit: '4b6938041a10' };
+exports.BUILD = { version: '2.19.3', commit: '699f027bb45a' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

@@ -1,6 +1,6 @@
 {
   "type": "commonjs",
   "name": "pixivflow-webui-backend",
-  "version": "2.19.2",
+  "version": "2.19.3",
   "description": "PixivFlow WebUI Backend - CommonJS module"
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pixivflow",
-  "version": "2.19.2",
+  "version": "2.19.3",
   "description": "🎨 智能的 Pixiv 自动化下载工具 - 支持批量下载插画和小说、定时任务、Docker部署 | Intelligent Pixiv Automation Downloader with batch download, scheduler, and Docker support",
   "repository": {
     "type": "git",