pixivflow 2.20.1 → 2.20.3

package/dist/commands/SchedulerCommand.js

@@ -166,6 +166,14 @@ class SchedulerCommand extends Command_1.BaseCommand {
                             throw new Error('ambiguous target');
                         const plan = plans[0];
                         const target = (0, schedules_1.selectScheduleTargets)(cfg.targets, plan).find((item) => item.id === targetId);
+                        const deliveryName = target.delivery?.target;
+                        const delivery = deliveryName ? cfg.delivery?.targets?.[deliveryName] : undefined;
+                        if (delivery?.type !== 'httpMultipart' || !delivery.refetchOutcomeUrl?.trim()) {
+                            throw new Error('refetch outcome endpoint not configured');
+                        }
+                        if ((target.delivery?.fields?.refetch_request_id ?? delivery.fields?.refetch_request_id) !== '{{refetchRequestId}}') {
+                            throw new Error('refetch_request_id delivery field not configured');
+                        }
                         const now = new Date();
                         const date = new Intl.DateTimeFormat('en-CA', {
                             timeZone: plan.timezone ?? 'UTC', year: 'numeric', month: '2-digit', day: '2-digit',
@@ -193,6 +201,13 @@ class SchedulerCommand extends Command_1.BaseCommand {
                         const started = manager.triggerSchedule(plan.id, { slot, onlyTarget: targetId, triggerSource: 'manual' });
                         return { slotId: slot.slotId, disposition: started ? 'accepted' : 'queued' };
                     },
+                    refetchStatus: (targetId, requestId) => {
+                        const slot = runtime.database.slots.findManualSlot(requestId, targetId);
+                        const cell = slot && runtime.database.slots.getCell(slot.id, targetId);
+                        return slot && cell
+                            ? { requestId, slotId: slot.id, state: cell.status, slotStatus: slot.status }
+                            : null;
+                    },
                     status: (scheduleId) => {
                         const cfg = resolveConfig();
                         const plan = findPlan(cfg, scheduleId);

package/dist/commands/scheduler-runtime.d.ts

@@ -111,6 +111,14 @@ export interface SchedulerRuntime {
     close(): void;
 }
 export declare function notifyScheduleFailure(config: StandaloneConfig, database: Database, schedule: ScheduleConfig, failure: JobFailure): Promise<void>;
+/**
+ * Expanded, still-bounded candidate scan bound for one fallback stage
+ * (§schedule-recovery). Stage 0 is the primary pass; stage N scans
+ * `base * (N + 1)` candidates, hard-capped so a fallback can never become an
+ * unbounded scan of the whole tag. `undefined` (no declared bound) stays
+ * `undefined`: the handler's own default applies, not a fabricated number.
+ */
+export declare function fallbackScanLimit(base: number | undefined, stage: number): number | undefined;
 export declare function createSchedulerRuntime(configPathArg?: string): Promise<SchedulerRuntime>;
 /**
  * Watchdog for a single plan run (used by `run-once`; the daemon's cron runs

package/dist/commands/scheduler-runtime.js

@@ -45,6 +45,7 @@ exports.EXECUTION_MODES = void 0;
 exports.withDeliveryMode = withDeliveryMode;
 exports.shouldTerminaliseAbortedSlot = shouldTerminaliseAbortedSlot;
 exports.notifyScheduleFailure = notifyScheduleFailure;
+exports.fallbackScanLimit = fallbackScanLimit;
 exports.createSchedulerRuntime = createSchedulerRuntime;
 exports.runWithTimeout = runWithTimeout;
 const config_1 = require("../config");
@@ -199,6 +200,16 @@ function buildProxyUrl(network) {
     const auth = proxy.username ? `${proxy.username}:${proxy.password ?? ''}@` : '';
     return `${protocol}://${auth}${proxy.host}:${proxy.port}`;
 }
+/**
+ * Expanded, still-bounded candidate scan bound for one fallback stage
+ * (§schedule-recovery). Stage 0 is the primary pass; stage N scans
+ * `base * (N + 1)` candidates, hard-capped so a fallback can never become an
+ * unbounded scan of the whole tag. `undefined` (no declared bound) stays
+ * `undefined`: the handler's own default applies, not a fabricated number.
+ */
+function fallbackScanLimit(base, stage) {
+    return base === undefined ? undefined : Math.min(Math.max(base, 1) * (stage + 1), 100);
+}
 async function createSchedulerRuntime(configPathArg) {
     logger_1.logger.info('PixivFlow runtime starting', { component: 'pixivflow', version: version_1.BUILD.version, commit: version_1.BUILD.commit });
     // Keep TODAY/YESTERDAY placeholders intact. They are resolved afresh for
@@ -239,6 +250,7 @@ async function createSchedulerRuntime(configPathArg) {
     // Independently-pumped durable outbox (content + notifications). Started in
     // the long-running scheduler daemon; run-once drains explicitly before exit.
     const deliveryDispatcher = new DeliveryDispatcher_1.DeliveryDispatcher(config.delivery, buildProxyUrl(config.network));
+    const notificationPolicy = new NotificationPolicy_1.NotificationPolicy(database, config);
     const outboxWorker = new OutboxWorker_1.OutboxWorker(database, deliveryDispatcher, {
         retryBaseMs: config.delivery?.outboxRetryBaseMs,
         retryMaxMs: config.delivery?.outboxRetryMaxMs,
@@ -246,9 +258,22 @@ async function createSchedulerRuntime(configPathArg) {
         // failed); see settleDeliveryTerminal for the invariant it enforces.
         onDeliveryTerminal: (deliveryId, ack) => {
             (0, settleDeliveryTerminal_1.settleDeliveryTerminal)(database, deliveryId, ack);
+            const delivery = database.deliveries.getById(deliveryId);
+            if (delivery?.slotId && delivery.targetId)
+                notificationPolicy.noteTerminalRefetchCell(delivery.slotId, delivery.targetId);
+        },
+        onDead: (row, error) => {
+            if (!row.deliveryId)
+                return;
+            const delivery = database.deliveries.getById(row.deliveryId);
+            if (!delivery?.slotId || !delivery.targetId)
+                return;
+            new SlotCoordinator_1.SlotCoordinator(database).applyOutcome(delivery.slotId, delivery.targetId, {
+                kind: 'failed', retryable: false, error,
+            });
+            notificationPolicy.noteTerminalRefetchCell(delivery.slotId, delivery.targetId);
         },
     });
-    const notificationPolicy = new NotificationPolicy_1.NotificationPolicy(database, config);
     const runJob = async (snapshot, schedule, options = {}) => {
         const { onlyTarget, adhoc = false, slot: providedSlot } = options;
         // A scheduled run is cron by default; an HTTP/manual trigger passes its own.
@@ -363,6 +388,14 @@ async function createSchedulerRuntime(configPathArg) {
                     cancelled = true;
                     slotAbandoned = true;
                     clearInterval(heartbeat);
+                    for (const target of targets) {
+                        if (!target.id)
+                            continue;
+                        if (database.slots.getCell(activeSlot.slotId, target.id)?.status === 'delivery_pending')
+                            continue;
+                        coordinator.applyOutcome(activeSlot.slotId, target.id, { kind: 'failed', retryable: false, error: reason });
+                        notificationPolicy.noteTerminalRefetchCell(activeSlot.slotId, target.id);
+                    }
                     database.slots.markSlotStatus(activeSlot.slotId, 'failed', `abandoned after scheduler timeout; no delivery (${reason})`);
                     coordinator.releaseRunLease(activeSlot.slotId, runOwner);
                     activeLeaseHooks = null;
@@ -384,6 +417,9 @@ async function createSchedulerRuntime(configPathArg) {
         if (slotCtx && runTargets.length === 0) {
             logger_1.logger.info('All slot cells already complete', { slot: slotCtx.slotId });
             coordinator.finish(slotCtx, schedule, targets);
+            for (const target of targets)
+                if (target.id)
+                    notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);
             // Release LAST: the slot must stay owned until its aggregate state has
             // been rolled up, otherwise a concurrent trigger could claim and re-run it
             // against a half-finished ledger.
@@ -420,21 +456,53 @@ async function createSchedulerRuntime(configPathArg) {
                 targets: runTargets.map((t) => t.id),
             });
         }
-        const downloadManager = new DownloadManager_1.DownloadManager(scopedConfig, pixivClient, database, fileService);
-        if (targetExecutionContexts)
-            downloadManager.setTargetExecutionContexts(targetExecutionContexts);
-        if (options.excludedWorkIds)
-            downloadManager.setProcessedWorkIds(options.excludedWorkIds);
-        activeDownloadManager = downloadManager;
-        await downloadManager.initialise();
         const scheduleSlot = slotCtx; // stable for callbacks; null for ad-hoc runs
+        // Bounded candidate fallback budget (§schedule-recovery): a missing required
+        // target must exhaust its recovery stages before the occurrence may roll up
+        // as a degraded (partial) terminal result.
+        const maxFallbackStages = Math.max(0, Math.min(10, Number(runtimeConfig.download?.maxFallbackStages ?? 3)));
+        const boostScanLimit = fallbackScanLimit;
+        const boostedTargets = (list, stage) => stage === 0
+            ? list
+            : list.map((t) => ({
+                ...t,
+                candidateScanLimit: boostScanLimit(t.candidateScanLimit ?? runtimeConfig.download?.candidateScanLimit, stage),
+            }));
+        const buildManager = (list) => {
+            const scoped = {
+                ...runtimeConfig,
+                targets: withDeliveryMode(list.map((t) => ({
+                    ...t,
+                    delivery: t.delivery
+                        ? { ...t.delivery, slotContext: slotCtx ?? undefined, executionContext }
+                        : t.delivery,
+                })), options.deliveryMode),
+            };
+            const manager = new DownloadManager_1.DownloadManager(scoped, pixivClient, database, fileService);
+            if (targetExecutionContexts)
+                manager.setTargetExecutionContexts(targetExecutionContexts);
+            if (options.excludedWorkIds)
+                manager.setProcessedWorkIds(options.excludedWorkIds);
+            manager.setTargetOutcomeHook(outcomeHook);
+            if (scheduleSlot) {
+                manager.slotContext = {
+                    slotId: scheduleSlot.slotId,
+                    scheduleId: scheduleSlot.scheduleId,
+                    occurrenceAtIso: new Date(scheduleSlot.occurrenceAt).toISOString(),
+                    triggerSource: scheduleSlot.triggerSource,
+                    slotName: scheduleSlot.slotName,
+                    slotDate: scheduleSlot.slotDate,
+                };
+            }
+            return manager;
+        };
         // TYPED outcome -> explicit FSM transition. No message regex, no
         // "no throw => submitted". Only a confirmed ACK yields 'submitted'.
         //
         // Registered for EVERY run, not just scheduled ones: the batch runner
         // (execute-slot) runs without a Slot and still has to report a
         // machine-readable per-target result to its caller.
-        downloadManager.setTargetOutcomeHook((target, outcome) => {
+        const outcomeHook = (target, outcome) => {
             if (!target.id)
                 return;
             options.onTargetOutcome?.(target.id, outcome);
@@ -442,33 +510,33 @@ async function createSchedulerRuntime(configPathArg) {
                 // No durable slot (run-once CLI): nothing to converge or report.
                 return;
             }
+            // A scheduled (non-manual) target with nothing to submit advances to its
+            // next bounded fallback stage instead of terminalising: the cell returns
+            // to `pending` and the next pass re-selects it with expanded scan bounds.
+            // The FINAL stage (stage == maxFallbackStages - 1) does NOT advance: its
+            // real terminal outcome (no_candidate / duplicate / failed) is applied, so
+            // an exhausted occurrence reports the true cause — never a generic
+            // "target did not complete".
+            if (!scheduleSlot.manualRequestId &&
+                (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate') &&
+                coordinator.cellFallbackStage(scheduleSlot.slotId, target.id) < maxFallbackStages - 1) {
+                coordinator.advanceFallback(scheduleSlot.slotId, target.id, outcome.kind === 'duplicate'
+                    ? `duplicate candidates (stage ${coordinator.cellFallbackStage(scheduleSlot.slotId, target.id)})`
+                    : outcome.reason ?? 'no eligible candidate', maxFallbackStages);
+                return;
+            }
             coordinator.applyOutcome(scheduleSlot.slotId, target.id, outcome);
             notificationPolicy.noteOutcome(scheduleSlot.slotId, scheduleSlot, schedule, target, outcome);
-            // A remote manual replacement ("重抓") must report its terminal verdict
-            // back to the reviewer. Only terminal outcomes are reported: a candidate
-            // the scan skipped is not a verdict, and a durable delivery intent
-            // ('delivery_pending' / later 'submitted') is reported through the
-            // replacement submission itself (the caller correlates on requestId).
-            const manualRequestId = scheduleSlot.manualRequestId;
-            if (manualRequestId) {
-                const terminal = outcome.kind === 'no_candidate' ||
-                    outcome.kind === 'duplicate' ||
-                    (outcome.kind === 'failed' && !outcome.retryable);
-                if (terminal) {
-                    notificationPolicy.noteRefetchOutcome(scheduleSlot, schedule, target, manualRequestId, outcome);
-                }
+            if (scheduleSlot.manualRequestId && (outcome.kind === 'no_candidate' || outcome.kind === 'duplicate' ||
+                (outcome.kind === 'failed' && !outcome.retryable))) {
+                // Preserve scan bookkeeping; later durable-cell reporting is the
+                // fallback for retry exhaustion, timeout, and outbox dead-letter.
+                notificationPolicy.noteRefetchOutcome(scheduleSlot, schedule, target, scheduleSlot.manualRequestId, outcome);
             }
-        });
-        if (scheduleSlot) {
-            downloadManager.slotContext = {
-                slotId: scheduleSlot.slotId,
-                scheduleId: scheduleSlot.scheduleId,
-                occurrenceAtIso: new Date(scheduleSlot.occurrenceAt).toISOString(),
-                triggerSource: scheduleSlot.triggerSource,
-                slotName: scheduleSlot.slotName,
-                slotDate: scheduleSlot.slotDate,
-            };
-        }
+        };
+        let downloadManager = buildManager(boostedTargets(runTargets, 0));
+        activeDownloadManager = downloadManager;
+        await downloadManager.initialise();
         // Apply initial delay if configured
         if (runtimeConfig.initialDelay && runtimeConfig.initialDelay > 0) {
             logger_1.logger.info(`Waiting ${runtimeConfig.initialDelay}ms before starting download...`, {
@@ -490,7 +558,25 @@ async function createSchedulerRuntime(configPathArg) {
         if (slotCtx && varReleaseLease)
             releaseLease = varReleaseLease;
         try {
-            await downloadManager.runAllTargets();
+            // Candidate fallback passes (§schedule-recovery): after each pass, cells
+            // still mid-fallback (advanced stages) are re-selected with expanded,
+            // still-bounded scan limits. Successful sibling cells are NEVER re-run:
+            // pendingTargets only returns unconverged cells of this slot.
+            for (let pass = 0;; pass += 1) {
+                await downloadManager.runAllTargets();
+                if (!slotCtx || pass >= maxFallbackStages - 1)
+                    break;
+                const pendingFallback = coordinator
+                    .pendingTargets(slotCtx.slotId, targets)
+                    .filter((p) => p.cell &&
+                    p.cell.fallback_stage > 0 &&
+                    p.cell.fallback_stage < maxFallbackStages);
+                if (pendingFallback.length === 0)
+                    break;
+                downloadManager = buildManager(boostedTargets(pendingFallback.map((p) => p.target), pass + 1));
+                activeDownloadManager = downloadManager;
+                await downloadManager.initialise();
+            }
         }
         catch (error) {
             if (!slotCtx || !(error instanceof Error) || !/^All \d+ target\(s\) failed\./.test(error.message)) {
@@ -509,6 +595,9 @@ async function createSchedulerRuntime(configPathArg) {
                 //    non-terminal so recovery resumes the same occurrence after restart.
                 if (slotCtx && shouldTerminaliseAbortedSlot(activeAbortOrigin, slotAbandoned)) {
                     coordinator.finish(slotCtx, schedule, targets);
+                    for (const target of targets)
+                        if (target.id)
+                            notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);
                 }
                 // Hand the lease back either way: a terminal Slot cannot be re-dispatched,
                 // and a non-terminal one (shutdown) must not wait for its TTL to expire.
@@ -527,6 +616,9 @@ async function createSchedulerRuntime(configPathArg) {
         const duration = Math.round((Date.now() - startTime) / 1000);
         if (slotCtx && !slotAbandoned) {
             const summary = coordinator.finish(slotCtx, schedule, targets);
+            for (const target of targets)
+                if (target.id)
+                    notificationPolicy.noteTerminalRefetchCell(slotCtx.slotId, target.id);
             notificationPolicy.sendSlotSummary(slotCtx, schedule, summary.cells.map((c) => {
                 const t = targets.find((x) => x.id === c.targetId);
                 return {

package/dist/config/types.d.ts

@@ -524,6 +524,12 @@ export interface HttpMultipartDeliveryConfig {
      * `headers` for auth, so no extra credential is needed.
      */
     refetchOutcomeUrl?: string;
+    /**
+     * Optional JSON endpoint for TERMINAL SCHEDULE occurrence summaries
+     * (success/partial/failed) — delivered by the durable outbox to TelePost,
+     * which relays a user/operator-visible message. Reuses `headers` for auth.
+     */
+    scheduleOutcomeUrl?: string;
     method?: 'POST' | 'PUT';
     /** 支持 ${ENV_NAME} 环境变量插值 */
     headers?: Record<string, string>;
@@ -683,6 +689,12 @@ export interface StandaloneConfig {
          * Default: 5 (clamped to 1..100)
          */
         candidateScanLimit?: number;
+        /**
+         * Bounded candidate-fallback budget for SCHEDULED occurrences
+         * (§schedule-recovery). 0 disables fallback (no_candidate/duplicate
+         * terminalises immediately). Default: 3.
+         */
+        maxFallbackStages?: number;
     };
 }
 //# sourceMappingURL=types.d.ts.map

package/dist/config/validation.js

@@ -312,6 +312,16 @@ function validateConfig(config, location, databasePath) {
                     errors.push(`${prefix}.refetchOutcomeUrl: Must be a valid HTTP or HTTPS URL`);
                 }
             }
+            if (delivery.scheduleOutcomeUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.scheduleOutcomeUrl)) {
+                try {
+                    const url = new URL(delivery.scheduleOutcomeUrl);
+                    if (!['http:', 'https:'].includes(url.protocol))
+                        throw new Error('unsupported protocol');
+                }
+                catch {
+                    errors.push(`${prefix}.scheduleOutcomeUrl: Must be a valid HTTP or HTTPS URL`);
+                }
+            }
             if (delivery.readinessUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.readinessUrl)) {
                 try {
                     const url = new URL(delivery.readinessUrl);

package/dist/delivery/DeliveryDispatcher.js

@@ -53,8 +53,13 @@ class DeliveryDispatcher {
         if (target.type !== 'httpMultipart') {
             throw new errors_1.ConfigError(`Unsupported delivery target type: ${target.type}`);
         }
-        if (!target.notificationUrl?.trim()) {
-            throw new errors_1.ConfigError(`Delivery target does not configure notificationUrl: ${name}`);
+        const urlKey = request.refetchOutcome
+            ? 'refetchOutcomeUrl'
+            : request.scheduleOutcome
+                ? 'scheduleOutcomeUrl'
+                : 'notificationUrl';
+        if (!target[urlKey]?.trim()) {
+            throw new errors_1.ConfigError(`Delivery target does not configure ${urlKey}: ${name}`);
         }
         return new HttpMultipartDelivery_1.HttpMultipartDelivery(target, this.proxyUrl).notifyOnce(request);
     }

package/dist/delivery/DeliveryService.d.ts

@@ -39,6 +39,19 @@ export interface RefetchOutcomePayload {
         unavailable: number;
     };
 }
+/** Terminal SCHEDULE occurrence verdict (success/partial/failed), reported via
+ * the durable outbox to TelePost, which relays the user-visible summary. */
+export interface ScheduleOutcomePayload {
+    scheduleId: string;
+    slotId: string;
+    status: 'success' | 'partial' | 'failed';
+    targets?: Array<{
+        targetId: string;
+        workType: string;
+        status: string;
+        workId?: string | null;
+    }>;
+}
 export declare class DeliveryService {
     private readonly database;
     constructor(database: Database);
@@ -96,7 +109,7 @@ export declare class DeliveryService {
         created: boolean;
     };
     /** Enqueue a durable notification (retried independently; never affects content). */
-    enqueueNotification(deliveryTarget: string, text: string, idempotencyKey: string, refetchOutcome?: RefetchOutcomePayload): void;
+    enqueueNotification(deliveryTarget: string, text: string, idempotencyKey: string, refetchOutcome?: RefetchOutcomePayload, scheduleOutcome?: ScheduleOutcomePayload): void;
     private guardCell;
     private contextFrom;
 }

package/dist/delivery/DeliveryService.js

@@ -175,12 +175,16 @@ class DeliveryService {
         return { deliveryId: row.id, created };
     }
     /** Enqueue a durable notification (retried independently; never affects content). */
-    enqueueNotification(deliveryTarget, text, idempotencyKey, refetchOutcome) {
+    enqueueNotification(deliveryTarget, text, idempotencyKey, refetchOutcome, scheduleOutcome) {
         this.database.outbox.enqueue({
             kind: 'notification',
             deliveryTarget,
             idempotencyKey,
-            payload: refetchOutcome ? { text, refetchOutcome } : { text },
+            payload: refetchOutcome
+                ? { text, refetchOutcome }
+                : scheduleOutcome
+                    ? { text, scheduleOutcome }
+                    : { text },
         });
     }
     guardCell(slotId, targetId, next) {

package/dist/delivery/HttpMultipartDelivery.js

@@ -134,18 +134,23 @@ class HttpMultipartDelivery {
     /** Single notification attempt; the outbox owns retries. */
     async notifyOnce(request) {
         const outcome = request.refetchOutcome;
-        const url = (outcome ? this.config.refetchOutcomeUrl?.trim() : this.config.notificationUrl?.trim());
+        const scheduleOutcome = request.scheduleOutcome;
+        const url = (outcome ? this.config.refetchOutcomeUrl?.trim()
+            : scheduleOutcome ? this.config.scheduleOutcomeUrl?.trim()
+                : this.config.notificationUrl?.trim());
         if (!url) {
             throw new Error(outcome
                 ? 'HTTP delivery refetchOutcomeUrl is not configured'
-                : 'HTTP delivery notificationUrl is not configured');
+                : scheduleOutcome
+                    ? 'HTTP delivery scheduleOutcomeUrl is not configured'
+                    : 'HTTP delivery notificationUrl is not configured');
         }
         const headers = {
             ...this.resolveHeaders(this.config.headers ?? {}),
             'Content-Type': 'application/json',
         };
-        // Refetch verdicts are machine-readable JSON (the requester's review state
-        // machine consumes disposition, not prose). Plain notifications remain
+        // Refetch verdicts and schedule outcomes are machine-readable JSON for
+        // TelePost's state machines/relays. Plain notifications remain
         // {text, idempotency_key}.
         const body = outcome
             ? {
@@ -156,11 +161,24 @@ class HttpMultipartDelivery {
                 scanned: outcome.scanned,
                 skipped: outcome.skipped,
             }
-            : { text: request.text, idempotency_key: request.idempotencyKey };
+            : scheduleOutcome
+                ? {
+                    schedule_id: scheduleOutcome.scheduleId,
+                    slot_id: scheduleOutcome.slotId,
+                    status: scheduleOutcome.status,
+                    targets: (scheduleOutcome.targets ?? []).map((t) => ({
+                        target_id: t.targetId,
+                        work_type: t.workType,
+                        status: t.status,
+                        work_id: t.workId ?? null,
+                    })),
+                }
+                : { text: request.text, idempotency_key: request.idempotencyKey };
         const options = {
             method: 'POST',
             headers,
             body: JSON.stringify(body),
+            signal: AbortSignal.timeout(5 * 60_000),
         };
         if (this.dispatcher)
             options.dispatcher = this.dispatcher;
@@ -195,6 +213,7 @@ class HttpMultipartDelivery {
             body: multipart.body,
             headers,
             duplex: 'half',
+            signal: AbortSignal.timeout(5 * 60_000),
         };
         if (this.dispatcher)
             options.dispatcher = this.dispatcher;
@@ -255,6 +274,9 @@ class HttpMultipartDelivery {
         return Object.fromEntries(Object.entries(fields).map(([name, value]) => {
             const values = Array.isArray(value) ? value : [value];
             const rendered = values.map((item) => renderDeliveryTemplate(String(item), variables));
+            if (name === 'refetch_request_id' && rendered.some((item) => /\{\{[^{}]+\}\}/.test(item))) {
+                throw new Error('Unresolved refetch_request_id template');
+            }
             switch (this.config.arrayFormat ?? 'comma') {
                 case 'repeat':
                     return [name, rendered];

package/dist/delivery/OutboxWorker.d.ts

@@ -31,6 +31,8 @@ export interface NotificationPayload {
     text: string;
     /** Optional structured remote-manual-replacement verdict (refetch outcome). */
     refetchOutcome?: unknown;
+    /** Optional structured terminal SCHEDULE occurrence verdict. */
+    scheduleOutcome?: unknown;
 }
 /** Exponential backoff with jitter, capped. */
 export declare function backoffDelayMs(attempt: number, base: number, max: number): number;

package/dist/delivery/OutboxWorker.js

@@ -214,6 +214,9 @@ class OutboxWorker {
                     refetchOutcome: payload.refetchOutcome !== undefined
                         ? payload.refetchOutcome
                         : undefined,
+                    scheduleOutcome: payload.scheduleOutcome !== undefined
+                        ? payload.scheduleOutcome
+                        : undefined,
                 });
             }
             else {

package/dist/delivery/types.d.ts

@@ -113,6 +113,22 @@ export interface DeliveryNotificationRequest {
             unavailable: number;
         };
     };
+    /**
+     * Structured terminal schedule verdict for a SCHEDULED occurrence. When
+     * present the delivery posts JSON to `scheduleOutcomeUrl` instead of
+     * `notificationUrl` (auth reuses `headers`).
+     */
+    scheduleOutcome?: {
+        scheduleId: string;
+        slotId: string;
+        status: 'success' | 'partial' | 'failed';
+        targets?: Array<{
+            targetId: string;
+            workType: string;
+            status: string;
+            workId?: string | null;
+        }>;
+    };
 }
 export interface DeliveryProvider {
     deliver(request: DeliveryRequest): Promise<DeliveryResult>;

package/dist/notification/NotificationPolicy.d.ts

@@ -45,6 +45,12 @@ export declare class NotificationPolicy {
         workId: string | null;
         error: string | null;
     }>): void;
+    /**
+     * Delivery targets whose HTTP target declares the given outcome URL.
+     * Schedule summaries require `scheduleOutcomeUrl`; manual refetch outcomes
+     * use `refetchOutcomeUrl`; generic notifications use `notificationUrl`.
+     */
+    private targetsWithUrl;
     private send;
     /**
      * Report the terminal verdict of a REMOTE MANUAL replacement ("重抓") back to
@@ -56,6 +62,8 @@ export declare class NotificationPolicy {
      * never enqueue a second verdict for the same logical attempt, and helpers
      * that already returned remain idempotent.
      */
-    noteRefetchOutcome(slot: SlotContext, _schedule: ScheduleConfig, target: TargetConfig, requestId: string, outcome: TargetOutcome): void;
+    noteRefetchOutcome(slot: Pick<SlotContext, 'slotId'>, _schedule: ScheduleConfig, target: TargetConfig, requestId: string, outcome: TargetOutcome): void;
+    /** Report the durable terminal cell, including failures finalized after retry exhaustion. */
+    noteTerminalRefetchCell(slotId: string, targetId: string): void;
 }
 //# sourceMappingURL=NotificationPolicy.d.ts.map

package/dist/notification/NotificationPolicy.js

@@ -76,8 +76,8 @@ class NotificationPolicy {
     }
     /** One consolidated summary per slot, delivered to every notifying target's endpoint. */
     sendSlotSummary(slot, schedule, rows) {
-        const notifiable = this.notifiableTargets();
-        if (notifiable.size === 0 || rows.length === 0)
+        const targets = this.targetsWithUrl('scheduleOutcomeUrl');
+        if (targets.size === 0 || rows.length === 0)
             return;
         const icon = (s) => s === 'submitted' ? '✅' : s === 'no_candidate' ? '⚠️' : s === 'duplicate' ? '♱' : s === 'delivery_pending' ? '🕓' : '❌';
         const lines = rows.map((r) => `${icon(r.status)} ${r.label}（${r.workType === 'novel' ? '小说' : '插画'}）` +
@@ -91,10 +91,39 @@ class NotificationPolicy {
             ...lines,
             `结果：${submitted === rows.length ? 'success' : submitted > 0 ? 'partial' : 'failed'}（${submitted}/${rows.length} 已确认投递）`,
         ].join('\n');
+        const outcomeStatus = submitted === rows.length ? 'success' : submitted > 0 ? 'partial' : 'failed';
         const service = new DeliveryService_1.DeliveryService(this.database);
-        for (const name of notifiable) {
-            service.enqueueNotification(name, text, NotificationPolicy.keys.summary(slot.slotId));
+        for (const name of targets) {
+            service.enqueueNotification(name, text, NotificationPolicy.keys.summary(slot.slotId), undefined, {
+                scheduleId: schedule.id,
+                slotId: slot.slotId,
+                status: outcomeStatus,
+                targets: rows.map((r) => ({
+                    targetId: r.targetId,
+                    workType: r.workType,
+                    status: r.status,
+                    workId: r.workId,
+                })),
+            });
+        }
+    }
+    /**
+     * Delivery targets whose HTTP target declares the given outcome URL.
+     * Schedule summaries require `scheduleOutcomeUrl`; manual refetch outcomes
+     * use `refetchOutcomeUrl`; generic notifications use `notificationUrl`.
+     */
+    targetsWithUrl(urlKey) {
+        const result = new Set();
+        for (const target of this.config.targets ?? []) {
+            const deliveryTarget = target.delivery?.target;
+            if (!deliveryTarget)
+                continue;
+            const delivery = this.config.delivery?.targets?.[deliveryTarget];
+            if (delivery?.type === 'httpMultipart' && delivery[urlKey]?.trim()) {
+                result.add(deliveryTarget);
+            }
         }
+        return result;
     }
     send(targetName, key, text) {
         try {
@@ -172,6 +201,25 @@ class NotificationPolicy {
             });
         }
     }
+    /** Report the durable terminal cell, including failures finalized after retry exhaustion. */
+    noteTerminalRefetchCell(slotId, targetId) {
+        const slot = this.database.slots.getSlot(slotId);
+        const cell = this.database.slots.getCell(slotId, targetId);
+        if (!slot?.manualRequestId || !cell)
+            return;
+        const target = this.config.targets.find((item) => item.id === targetId);
+        if (!target)
+            return;
+        const outcome = cell.status === 'no_candidate'
+            ? { kind: 'no_candidate', reason: cell.lastError ?? 'no eligible candidate' }
+            : cell.status === 'duplicate'
+                ? { kind: 'duplicate', workId: cell.workId ?? '', reason: cell.lastError ?? 'historical duplicate' }
+                : cell.status === 'failed'
+                    ? { kind: 'failed', retryable: false, error: cell.lastError ?? slot.lastError ?? 'manual refetch failed' }
+                    : null;
+        if (outcome)
+            this.noteRefetchOutcome({ slotId }, { id: slot.scheduleId }, target, slot.manualRequestId, outcome);
+    }
 }
 exports.NotificationPolicy = NotificationPolicy;
 /** Fold a CandidateScanSummary into the refetch-outcome bookkeeping (bounded). */

package/dist/package.json

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

package/dist/scheduler/ScheduleTriggerServer.d.ts

@@ -105,6 +105,12 @@ export interface TriggerHandlers {
         slotId: string;
         disposition: string;
     }>;
+    refetchStatus?(targetId: string, requestId: string): {
+        requestId: string;
+        slotId: string;
+        state: string;
+        slotStatus: string;
+    } | null;
 }
 export declare class ScheduleTriggerServer {
     private readonly token;

package/dist/scheduler/ScheduleTriggerServer.js

@@ -194,6 +194,19 @@ class ScheduleTriggerServer {
                 res.status(status).json({ status: 'error', error: status === 500 ? 'refetch admission failed' : message });
             }
         });
+        app.get('/internal/targets/:targetId/refetch/:requestId', this.refetchAuth, (req, res) => {
+            const { targetId, requestId } = req.params;
+            if (!/^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(requestId)) {
+                res.status(400).json({ status: 'error', error: 'requestId must be a UUID' });
+                return;
+            }
+            const status = this.handlers.refetchStatus?.(targetId, requestId);
+            if (!status) {
+                res.status(404).json({ status: 'error', error: 'manual refetch not found' });
+                return;
+            }
+            res.json(status);
+        });
         // Convergence endpoint: after a machine stop/start, an operator or an
         // external watcher can ask the process to flush due deliveries/notifications
         // without running candidate selection. Deployment-agnostic (no platform refs).

package/dist/scheduler/SlotCoordinator.d.ts

@@ -252,7 +252,20 @@ export declare class SlotCoordinator {
     claimRunLease(slotId: string, owner: string, leaseMs: number): boolean;
     heartbeatLease(slotId: string, owner: string, leaseMs: number): void;
     releaseRunLease(slotId: string, owner: string): void;
-    /** Roll cell results up into the slot status (one place computes the aggregate). */
+    /**
+     * Current durable fallback stage of a cell (0 = primary selection pass).
+     * Mirrors the repository accessor so scheduler-runtime reads one surface.
+     */
+    cellFallbackStage(slotId: string, targetId: string): number;
+    /**
+     * Advance a recoverable candidate cell to its next durable fallback stage
+     * (§schedule-recovery). no_candidate/duplicate from a non-final stage MUST
+     * NOT terminalize: pendingTargets then re-selects the same target with
+     * expanded, still-bounded scan parameters. Returns the new stage, or the
+     * previous stage when the budget was already exhausted (callers then let the
+     * terminal outcome apply).
+     */
+    advanceFallback(slotId: string, targetId: string, reason: string, maxStages: number): number;
     finish(slot: SlotContext, schedule: ScheduleConfig, targets: TargetConfig[]): SlotRunSummary;
     /**
      * Project the terminal slot row into the one structured outcome record. Every

package/dist/scheduler/SlotCoordinator.js

@@ -168,7 +168,7 @@ class SlotCoordinator {
             const cell = this.database.slots.getCell(slotId, target.id);
             if (!cell)
                 continue;
-            if (cell.status === 'submitted' || cell.status === 'no_candidate')
+            if (cell.status === 'submitted' || cell.status === 'no_candidate' || cell.status === 'duplicate' || cell.status === 'failed')
                 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
@@ -355,7 +355,31 @@ class SlotCoordinator {
     releaseRunLease(slotId, owner) {
         this.database.slots.releaseSlotLease(slotId, owner);
     }
-    /** Roll cell results up into the slot status (one place computes the aggregate). */
+    /**
+     * Current durable fallback stage of a cell (0 = primary selection pass).
+     * Mirrors the repository accessor so scheduler-runtime reads one surface.
+     */
+    cellFallbackStage(slotId, targetId) {
+        return this.database.slots.cellFallbackStage(slotId, targetId);
+    }
+    /**
+     * Advance a recoverable candidate cell to its next durable fallback stage
+     * (§schedule-recovery). no_candidate/duplicate from a non-final stage MUST
+     * NOT terminalize: pendingTargets then re-selects the same target with
+     * expanded, still-bounded scan parameters. Returns the new stage, or the
+     * previous stage when the budget was already exhausted (callers then let the
+     * terminal outcome apply).
+     */
+    advanceFallback(slotId, targetId, reason, maxStages) {
+        const current = this.database.slots.cellFallbackStage(slotId, targetId);
+        if (current >= maxStages)
+            return current;
+        const next = this.database.slots.bumpFallbackStage(slotId, targetId, reason);
+        logger_1.logger.info('Candidate fallback advanced', {
+            slot: slotId, target: targetId, stage: next, reason: String(reason).slice(0, 160),
+        });
+        return next;
+    }
     finish(slot, schedule, targets) {
         const membership = this.database.slots.getSlotTargetIds(slot.slotId);
         const ids = membership.length > 0 ? membership : targets.map((t) => t.id).filter(Boolean);

package/dist/storage/DatabaseMigration.js

@@ -124,6 +124,7 @@ class DatabaseMigration {
             work_type TEXT,
             status TEXT NOT NULL DEFAULT 'pending',
             attempt_count INTEGER NOT NULL DEFAULT 0,
+            fallback_stage INTEGER NOT NULL DEFAULT 0,
             last_error TEXT,
             created_at DATETIME DEFAULT CURRENT_TIMESTAMP,
             updated_at DATETIME DEFAULT CURRENT_TIMESTAMP,
@@ -244,6 +245,10 @@ class DatabaseMigration {
                 if (!slotCols.includes(col))
                     columnAlters.push(sql);
             }
+            const itemCols = this.db.prepare(`PRAGMA table_info(schedule_slot_items)`).all().map((c) => c.name);
+            if (!itemCols.includes('fallback_stage')) {
+                columnAlters.push(`ALTER TABLE schedule_slot_items ADD COLUMN fallback_stage INTEGER NOT NULL DEFAULT 0`);
+            }
             // Create indexes for better query performance
             const indexes = [
                 `CREATE INDEX IF NOT EXISTS idx_downloads_pixiv_id_type ON downloads(pixiv_id, type)`,

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

@@ -38,6 +38,12 @@ export interface SlotItemRecord {
     workType: string | null;
     status: CellStatus;
     attemptCount: number;
+    /**
+     * Bounded candidate-fallback depth for this cell (§schedule-recovery). 0 means
+     * the primary selection pass; each advance re-selects the SAME target with
+     * expanded scan bounds. Durable so a crash-resume re-enters at the same stage.
+     */
+    fallback_stage: number;
     lastError: string | null;
     createdAt: string;
     updatedAt: string;
@@ -53,6 +59,8 @@ export interface SlotItemRecord {
  * the same row instead of emitting a second work for the same slot/target.
  */
 export declare class SlotRepository extends BaseRepository {
+    /** Exact manual request/target lookup for authenticated convergence checks. */
+    findManualSlot(requestId: string, targetId: string): SlotRecord | null;
     /**
      * Fetch an existing slot or create it. On creation the schedule's target
      * membership is snapshotted (target_ids); a later config reload never mutates
@@ -129,6 +137,9 @@ export declare class SlotRepository extends BaseRepository {
     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;
+    /** Durable candidate-fallback bookkeeping (§schedule-recovery). */
+    bumpFallbackStage(slotId: string, targetId: string, reason: string): number;
+    cellFallbackStage(slotId: string, targetId: string): number;
     setCellStatus(slotId: string, targetId: string, status: CellStatus, error?: string): void;
     /**
      * Transition a cell with FSM validation. Never downgrades a confirmed cell;

package/dist/storage/repositories/SlotRepository.js

@@ -12,6 +12,11 @@ const BaseRepository_1 = require("./BaseRepository");
  * the same row instead of emitting a second work for the same slot/target.
  */
 class SlotRepository extends BaseRepository_1.BaseRepository {
+    /** Exact manual request/target lookup for authenticated convergence checks. */
+    findManualSlot(requestId, targetId) {
+        const rows = this.db.prepare(`SELECT * FROM schedule_slots WHERE manual_request_id = ?`).all(requestId);
+        return rows.map((row) => this.toSlot(row)).find((slot) => slot.targetIds.includes(targetId)) ?? null;
+    }
     /**
      * Fetch an existing slot or create it. On creation the schedule's target
      * membership is snapshotted (target_ids); a later config reload never mutates
@@ -193,6 +198,28 @@ class SlotRepository extends BaseRepository_1.BaseRepository {
          WHERE slot_id = @slotId AND target_id = @targetId`)
             .run({ slotId, targetId });
     }
+    /** Durable candidate-fallback bookkeeping (§schedule-recovery). */
+    bumpFallbackStage(slotId, targetId, reason) {
+        const item = this.db
+            .prepare(`SELECT fallback_stage FROM schedule_slot_items WHERE slot_id = ? AND target_id = ?`)
+            .get(slotId, targetId);
+        const stage = Number(item?.fallback_stage ?? 0);
+        this.db
+            .prepare(`UPDATE schedule_slot_items
+            SET fallback_stage = ?, last_error = ?,
+                status = 'pending',
+                updated_at = CURRENT_TIMESTAMP,
+                completed_at = NULL
+          WHERE slot_id = ? AND target_id = ?`)
+            .run(stage + 1, String(reason).slice(0, 400), slotId, targetId);
+        return stage + 1;
+    }
+    cellFallbackStage(slotId, targetId) {
+        const item = this.db
+            .prepare(`SELECT fallback_stage FROM schedule_slot_items WHERE slot_id = ? AND target_id = ?`)
+            .get(slotId, targetId);
+        return Number(item?.fallback_stage ?? 0);
+    }
     setCellStatus(slotId, targetId, status, error) {
         const terminal = status === 'submitted' ||
             status === 'no_candidate' ||
@@ -374,6 +401,7 @@ class SlotRepository extends BaseRepository_1.BaseRepository {
             workType: row.work_type,
             status: row.status,
             attemptCount: row.attempt_count,
+            fallback_stage: Number(row.fallback_stage ?? 0),
             lastError: row.last_error,
             createdAt: row.created_at,
             updatedAt: row.updated_at,

package/dist/utils/config-validator-unified.js

@@ -261,6 +261,20 @@ class ConfigValidator {
                     });
                 }
             }
+            if (delivery.scheduleOutcomeUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.scheduleOutcomeUrl)) {
+                try {
+                    const url = new URL(delivery.scheduleOutcomeUrl);
+                    if (!['http:', 'https:'].includes(url.protocol))
+                        throw new Error('unsupported protocol');
+                }
+                catch {
+                    errors.push({
+                        code: 'CONFIG_VALIDATION_DELIVERY_SCHEDULE_OUTCOME_URL_INVALID',
+                        field: `${prefix}.scheduleOutcomeUrl`,
+                        message: `Delivery target '${name}': scheduleOutcomeUrl must be valid HTTP or HTTPS`,
+                    });
+                }
+            }
             if (delivery.readinessUrl && !/\$\{[A-Za-z_][A-Za-z0-9_]*\}/.test(delivery.readinessUrl)) {
                 try {
                     const url = new URL(delivery.readinessUrl);

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.20.1', commit: '834a545f7368' };
+exports.BUILD = { version: '2.20.3', commit: '6ebffc579194' };
 //# sourceMappingURL=version.js.map

package/dist/webui/package.json

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

package/package.json

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