pixivflow 3.2.0 → 3.3.0

package/dist/scheduler/ScheduleTriggerServer.js

@@ -9,6 +9,8 @@ exports.scheduleProvider = scheduleProvider;
 const express_1 = __importDefault(require("express"));
 const node_crypto_1 = require("node:crypto");
 const logger_1 = require("../logger");
+const JobFacade_1 = require("./JobFacade");
+const ProtocolErrors_1 = require("./ProtocolErrors");
 const version_1 = require("../version");
 const TRIGGER_OUTCOMES = {
     accepted: { event: 'schedule.trigger_accepted', httpStatus: 202, status: 'accepted', note: 'queued' },
@@ -93,6 +95,7 @@ class ScheduleTriggerServer {
     static resolveToken(configured) {
         return (configured ?? process.env.SCHEDULER_TRIGGER_TOKEN ?? '').trim() || undefined;
     }
+    /** `start` returns the listening server so tests/callers can read the port. */
     start(host, port) {
         const app = (0, express_1.default)();
         app.use(express_1.default.json());
@@ -108,6 +111,139 @@ class ScheduleTriggerServer {
                 commit: version_1.BUILD.commit,
             });
         });
+        // ---------------------------------------------------------------------
+        // Generic job facade — Workflow Protocol v1 (Task -> Job).
+        //
+        // Same server, same bearer token as the manual-work family (`refetchAuth`):
+        // this is not a second HTTP system and not a second execution path. Both
+        // this surface and the legacy `/internal/targets/:targetId/refetch` shim
+        // funnel into ONE shared admission function, so identity, idempotency and
+        // the terminal state can never diverge between entry points.
+        //
+        // No `refetch*` vocabulary appears on this surface, and nothing here reads
+        // `slot_name` or any consumer/business label: it is a projection adapter.
+        // ---------------------------------------------------------------------
+        app.get('/capabilities', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                res.json(jobs.capabilities());
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'capabilities failed');
+            }
+        });
+        app.post('/jobs', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                const { job, replayed } = jobs.submitJob(req.body);
+                this.triggerOutcome('schedule.job_admitted', replayed ? 200 : 202, req, res, {
+                    job_id: job.job_id,
+                    job_type: job.job_type,
+                    status: job.status,
+                    disposition: replayed ? 'replayed' : 'accepted',
+                });
+                // 202 on first admission, 200 when the idempotency key resolved to an
+                // already-existing Job. Both carry the identical `job` body.
+                res.status(replayed ? 200 : 202).json({ job });
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job admission failed');
+            }
+        });
+        app.get('/jobs', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                const idempotencyKey = req.query.idempotency_key;
+                if (typeof idempotencyKey !== 'string' || idempotencyKey.trim() === '') {
+                    throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 400, {
+                        message: 'idempotency_key is required',
+                    });
+                }
+                res.json({ jobs: jobs.jobsByIdempotencyKey(idempotencyKey), server_time: Date.now() });
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job lookup failed');
+            }
+        });
+        app.get('/jobs/:jobId', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                const job = jobs.jobStatus(req.params.jobId);
+                if (!job) {
+                    throw new ProtocolErrors_1.ProtocolRequestError('invalid_params', 404, { message: 'unknown job' });
+                }
+                res.json(job);
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job lookup failed');
+            }
+        });
+        app.post('/jobs/:jobId/cancel', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                const job = jobs.cancelJob(req.params.jobId);
+                this.triggerOutcome('schedule.job_cancelled', 200, req, res, {
+                    job_id: job.job_id,
+                    status: job.status,
+                });
+                res.json(job);
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job cancel failed');
+            }
+        });
+        // The durable event stream (§events). Read-only projection of the ledger the
+        // cancel/status routes already read, so a consumer can follow a job to its
+        // terminal event instead of polling status.
+        app.get('/jobs/:jobId/events', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                const query = (0, JobFacade_1.parseEventQuery)(req.query);
+                res.json(jobs.jobEvents(req.params.jobId, query));
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job events failed');
+            }
+        });
+        // Ack is a cursor write, never a job mutation: the body carries only
+        // `ack_through`, and an unknown or older cursor is accepted as a no-op.
+        app.post('/jobs/:jobId/events/ack', this.refetchAuth, (req, res) => {
+            const jobs = this.handlers.jobs;
+            if (!jobs) {
+                res.status(503).json(this.jobUnavailableResponse());
+                return;
+            }
+            try {
+                res.json(jobs.ackJobEvents(req.params.jobId, req.body));
+            }
+            catch (error) {
+                this.jobFailure(req, res, error, 'job ack failed');
+            }
+        });
         // Read-only: list enabled schedules + their current occurrence status.
         app.get('/internal/schedules', this.auth, (_req, res) => {
             const schedules = this.handlers.listSchedules().map((id) => this.handlers.status(id));
@@ -291,9 +427,11 @@ class ScheduleTriggerServer {
                 res.status(500).json({ status: 'error', error: 'outbox drain failed; rows remain durable and retry' });
             }
         });
-        this.server = app.listen(port, host, () => {
+        const server = app.listen(port, host, () => {
             logger_1.logger.info('Schedule trigger server listening', { host, port, auth: this.token ? 'bearer' : 'DISABLED (no token)' });
         });
+        this.server = server;
+        return server;
     }
     /**
      * Per-request correlation, installed before every route. It records only the
@@ -345,6 +483,33 @@ class ScheduleTriggerServer {
             elapsed_ms: Date.now() - startedAt,
         };
     }
+    /**
+     * Every generic-surface failure is written as a protocol `Error`: a closed-enum
+     * `code`, a `retryable` boolean from the published defaults, and a `detail`
+     * object. Nothing here judges a failure by its message text.
+     */
+    jobFailure(req, res, error, stage) {
+        const { status, body } = (0, ProtocolErrors_1.protocolErrorResponse)(error);
+        if (status >= 500) {
+            logger_1.logger.error('Job API request failed', {
+                ...this.attemptMeta(req, res),
+                stage,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+        this.triggerOutcome('schedule.job_rejected', status, req, res, { code: body.code, stage });
+        // §3: protocol failures are reported as `{ error: <$defs/Error> }`.
+        res.status(status).json({ error: body });
+    }
+    /** Fail closed when the generic surface is not mounted in this runtime. */
+    jobUnavailableResponse() {
+        return {
+            error: (0, ProtocolErrors_1.protocolErrorBody)('internal_error', {
+                message: 'job API is unavailable',
+                detail: { reason: 'job_api_disabled' },
+            }),
+        };
+    }
     auth = (req, res, next) => {
         this.authenticate(this.token, req, res, next);
     };

package/dist/scheduler/SlotBusinessStatus.d.ts

@@ -6,12 +6,14 @@
  * - System failures (pixiv/network/download/processing/delivery) must be kept
  *   disjoint from business no-content states so monitoring and Mini App never
  *   show "internal_error" for an empty but healthy run.
+ * - A CONSUMER CANCEL is an intentional stop, not a system failure: it must
+ *   never be alertable, or every cancel would page an operator.
  *
  * This is a DERIVED verdict over the existing terminal cell ledger; it does not
  * change the persisted slot phase machine (pending/running/success/partial/
  * failed remain untouched for ledger compatibility).
  */
-export type SlotBusinessStatus = 'success' | 'partial_success' | 'no_candidate' | 'duplicate_only' | 'failed';
+export type SlotBusinessStatus = 'success' | 'partial_success' | 'no_candidate' | 'duplicate_only' | 'cancelled' | 'failed';
 export interface SlotBusinessCounts {
     total: number;
     submitted: number;
@@ -21,6 +23,8 @@ export interface SlotBusinessCounts {
     duplicate_exhausted?: number;
     executor_failed: number;
     delivery_failed: number;
+    /** Cells terminalised by a consumer/operator cancel (`cancelled_by_consumer`). */
+    cancelled?: number;
 }
 /** Pure projection: durable cell counts -> one business verdict. No I/O. */
 export declare function classifySlotBusinessStatus(counts: SlotBusinessCounts): SlotBusinessStatus;

package/dist/scheduler/SlotBusinessStatus.js

@@ -13,6 +13,10 @@ function classifySlotBusinessStatus(counts) {
         return 'partial_success';
     if (nonSubmitted === 0)
         return 'success'; // defensive: 0 targets / all submitted
+    // A cancel is deliberate. It is only reported as such while nothing else in
+    // the occurrence actually failed — a real failure must stay visible.
+    if ((counts.cancelled ?? 0) > 0 && !systemFailed)
+        return 'cancelled';
     if (!systemFailed) {
         // Every non-submitted cell was a BUSINESS no-content verdict; all of them
         // came from already-delivered candidates => duplicate_only.
@@ -36,6 +40,8 @@ function userMessageForSlotBusinessStatus(status) {
             return '本轮没有发现新的可发布作品。任务已正常完成。';
         case 'duplicate_only':
             return '本轮没有发现新的可发布作品。任务已正常完成。';
+        case 'cancelled':
+            return '本轮任务已被取消，不会继续发布。';
         case 'failed':
             return '本轮任务遇到系统异常，请稍后重试或检查日志。';
     }

package/dist/scheduler/SlotCoordinator.d.ts

@@ -57,6 +57,13 @@ export interface SlotContext {
     recoveryRequestId?: string;
     /** Recovery policy preset ('normal' | 'relaxed'); null for non-recovery slots. */
     recoveryMode?: 'normal' | 'relaxed';
+    /**
+     * Occurrence-scoped retrieval view of a generic `candidate_search` job (§6),
+     * serialized as JSON. Persisted with the slot so a worker that recovers the
+     * occurrence re-applies the requester's retrieval instead of quietly falling
+     * back to the plan defaults. Absent for scheduled occurrences.
+     */
+    paramsJson?: string;
 }
 export interface SlotCellSummary {
     targetId: string;
@@ -94,10 +101,13 @@ export interface ScheduleOutcomeTarget {
  * healthy run look broken, and a broken one look routine.
  *
  * Each cell lands in exactly ONE category, in this precedence:
- * submitted -> no_match -> duplicate -> delivery_failed -> executor_failed.
+ * submitted -> no_match -> duplicate -> delivery_failed -> cancelled -> executor_failed.
  * `delivery_failed` is checked before `executor_failed` because a terminally
  * lost delivery ALSO leaves the cell in the `failed` state — counting it twice
- * would invent a second failure that does not exist.
+ * would invent a second failure that does not exist. `cancelled` comes before
+ * `executor_failed` for the same reason: a consumer cancel also ends as a
+ * `failed` cell, and counting it as an executor failure would page an operator
+ * for a deliberate stop.
  */
 export interface ScheduleOutcomeCells {
     total: number;
@@ -108,6 +118,8 @@ export interface ScheduleOutcomeCells {
     all_duplicates: boolean;
     executor_failed: number;
     delivery_failed: number;
+    /** Cells stopped by a consumer/operator cancel — deliberate, never alertable. */
+    cancelled: number;
     targets: ScheduleOutcomeTarget[];
 }
 /**
@@ -119,13 +131,13 @@ export interface ScheduleOutcomeCells {
 export interface ScheduleOutcomeRecord {
     event: 'schedule.outcome';
     /** Outcome taxonomy version; bump when business_status/reason gains codes. */
-    outcome_version: 1;
+    outcome_version: 2;
     schedule_id: string;
     slot_id: string;
     occurrence_at: string | undefined;
     occurrence_date: string;
     status: ScheduleOutcomeStatus;
-    /** Derived business verdict: success / partial_success / no_candidate / duplicate_only / failed. */
+    /** Derived business verdict: success / partial_success / no_candidate / duplicate_only / cancelled / failed. */
     business_status: SlotBusinessStatus;
     /** Monitoring gate: true only for system failures (business_status === 'failed'). */
     alertable: boolean;
@@ -305,7 +317,35 @@ export declare class SlotCoordinator {
      * terminal outcome apply).
      */
     advanceFallback(slotId: string, targetId: string, reason: string, maxStages: number): number;
-    finish(slot: SlotContext, schedule: ScheduleConfig, targets: TargetConfig[]): SlotRunSummary;
+    /**
+     * True when the cell's durable delivery intent can no longer be completed by
+     * any worker: at least one intent row exists (so this IS a delivery that was
+     * handed off, not an unstarted cell), none is confirmed, and none still has an
+     * actionable outbox row (dead / cancelled / lost with the process).
+     *
+     * Answered from the LEDGER rather than from the injected delivery port on
+     * purpose: `finish` is also called by the schedule-summary reconciler, which
+     * has no port, and "will anything still deliver this?" is a durable fact.
+     * `unknown` (no intent at all) must never converge a cell — an unstarted or
+     * port-less rollup keeps today's behaviour.
+     */
+    private abandonedDelivery;
+    /**
+     * A LIVE lease owned by someone other than the finishing run. Blocking on it
+     * is what stops a rollup (or the reconciler, which passes no owner) from
+     * converging cells that a concurrently running worker still owns.
+     */
+    private foreignLiveLease;
+    /**
+     * @param options.leaseOwner the lease owner of the run that is finishing.
+     *   A LIVE lease held by a DIFFERENT owner means another worker owns this slot
+     *   right now, so an abandoned-looking cell must be left to that worker
+     *   instead of being converged from here (the reconciler path passes nothing,
+     *   so any live lease blocks convergence for it).
+     */
+    finish(slot: SlotContext, schedule: ScheduleConfig, targets: TargetConfig[], options?: {
+        leaseOwner?: string;
+    }): SlotRunSummary;
     /**
      * Project the terminal slot row into the one structured outcome record. Every
      * field comes from durable state — the slot row, its cells, and the delivery
@@ -317,6 +357,10 @@ export declare class SlotCoordinator {
      * durable delivery ledger through the SAME port the FSM already uses, never
      * from an error string, and it is decided BEFORE `executor_failed` because a
      * terminally lost delivery also leaves the cell `failed`: one cause, one count.
+     *
+     * A consumer cancel is decided before both: it also ends as a `failed` cell,
+     * but it is a deliberate stop rather than a system failure, so it must not be
+     * counted as an executor failure (which would make it alertable).
      */
     private classifyCell;
     /**

package/dist/scheduler/SlotCoordinator.js

@@ -5,7 +5,9 @@ exports.timezoneForSchedule = timezoneForSchedule;
 const logger_1 = require("../logger");
 const OccurrenceResolver_1 = require("./OccurrenceResolver");
 const TargetOutcome_1 = require("./TargetOutcome");
+const ledger_time_1 = require("./ledger-time");
 const SlotBusinessStatus_1 = require("./SlotBusinessStatus");
+const ProtocolErrors_1 = require("./ProtocolErrors");
 const WorkIdentity_1 = require("./WorkIdentity");
 const targetRoutes_1 = require("../delivery/targetRoutes");
 /**
@@ -31,20 +33,6 @@ function deliveryTargetsOf(target) {
         return [];
     return (0, targetRoutes_1.targetDeliveryNames)(target);
 }
-/**
- * SQLite `CURRENT_TIMESTAMP` is UTC "YYYY-MM-DD HH:MM:SS". It carries no zone
- * marker, and `Date.parse` reads that shape as LOCAL time — so the zone is
- * added explicitly instead of being trusted to the engine.
- */
-function sqliteUtcMs(value) {
-    if (!value)
-        return undefined;
-    const normalized = /^\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}$/.test(value)
-        ? `${value.replace(' ', 'T')}Z`
-        : value;
-    const ms = Date.parse(normalized);
-    return Number.isNaN(ms) ? undefined : ms;
-}
 /**
  * Epoch ms -> ISO 8601 UTC, or undefined when it is not a usable instant.
  * `toISOString` throws on an out-of-range Date, and a throw here would abort the
@@ -135,6 +123,7 @@ class SlotCoordinator {
             slotName: slot.slotName,
             manualRequestId: slot.manualRequestId ?? null,
             correlationId: slot.correlationId ?? null,
+            paramsJson: slot.paramsJson ?? null,
             recoveryRequestId: slot.recoveryRequestId ?? null,
             recoveryMode: slot.recoveryMode ?? null,
         });
@@ -434,17 +423,82 @@ class SlotCoordinator {
         });
         return next;
     }
-    finish(slot, schedule, targets) {
+    /**
+     * True when the cell's durable delivery intent can no longer be completed by
+     * any worker: at least one intent row exists (so this IS a delivery that was
+     * handed off, not an unstarted cell), none is confirmed, and none still has an
+     * actionable outbox row (dead / cancelled / lost with the process).
+     *
+     * Answered from the LEDGER rather than from the injected delivery port on
+     * purpose: `finish` is also called by the schedule-summary reconciler, which
+     * has no port, and "will anything still deliver this?" is a durable fact.
+     * `unknown` (no intent at all) must never converge a cell — an unstarted or
+     * port-less rollup keeps today's behaviour.
+     */
+    abandonedDelivery(slotId, targetId) {
+        const intents = this.database.deliveries.listForSlotCell(slotId, targetId);
+        if (intents.length === 0)
+            return false;
+        if (intents.some((row) => row.status === 'delivered' || row.status === 'duplicate'))
+            return false;
+        return !intents.some((row) => row.status === 'pending' && this.database.outbox.hasActionableDelivery(row.id));
+    }
+    /**
+     * A LIVE lease owned by someone other than the finishing run. Blocking on it
+     * is what stops a rollup (or the reconciler, which passes no owner) from
+     * converging cells that a concurrently running worker still owns.
+     */
+    foreignLiveLease(slotId, ownOwner) {
+        const lease = this.database.slots.getSlotLease(slotId);
+        if (lease.owner === null || lease.until === null || lease.until <= Date.now())
+            return false;
+        return ownOwner === undefined || lease.owner !== ownOwner;
+    }
+    /**
+     * @param options.leaseOwner the lease owner of the run that is finishing.
+     *   A LIVE lease held by a DIFFERENT owner means another worker owns this slot
+     *   right now, so an abandoned-looking cell must be left to that worker
+     *   instead of being converged from here (the reconciler path passes nothing,
+     *   so any live lease blocks convergence for it).
+     */
+    finish(slot, schedule, targets, options = {}) {
         const membership = this.database.slots.getSlotTargetIds(slot.slotId);
         const ids = membership.length > 0 ? membership : targets.map((t) => t.id).filter(Boolean);
+        const foreignLiveLease = this.foreignLiveLease(slot.slotId, options.leaseOwner);
         for (const targetId of ids) {
             const cell = this.database.slots.getCell(slot.slotId, targetId);
             if (!cell)
                 continue;
             // delivery_pending / artifact_ready are recoverable: the OutboxWorker (or
-            // the next trigger) resumes the SAME work, so the slot stays running.
-            if (cell.status === 'delivery_pending' || cell.status === 'artifact_ready')
+            // the next trigger) resumes the SAME work, so the slot stays running — but
+            // ONLY while a durable delivery intent still has an actionable outbox row.
+            // A dead-lettered/cancelled intent (or one lost with the process) has no
+            // worker left to converge it, so the cell would stay non-terminal forever
+            // and `deriveSlotStatus` would keep reporting `running`.
+            if (cell.status === 'delivery_pending' || cell.status === 'artifact_ready') {
+                if (foreignLiveLease)
+                    continue;
+                if (!this.abandonedDelivery(slot.slotId, targetId))
+                    continue;
+                const error = cell.lastError ?? TargetOutcome_1.TERMINAL_REASON_MESSAGES.delivery_abandoned;
+                try {
+                    this.database.slots.transitionCell(slot.slotId, targetId, 'failed', error);
+                    this.database.slots.setCellTerminalReason(slot.slotId, targetId, 'delivery_abandoned', TargetOutcome_1.TERMINAL_REASON_MESSAGES.delivery_abandoned);
+                }
+                catch (reasonError) {
+                    logger_1.logger.debug('Failed to converge an abandoned delivery cell', {
+                        slot: slot.slotId, target: targetId,
+                        error: reasonError instanceof Error ? reasonError.message : String(reasonError),
+                    });
+                    continue;
+                }
+                logger_1.logger.warn('Converged an abandoned delivery cell: no actionable outbox row remained', {
+                    slot: slot.slotId,
+                    target: targetId,
+                    manualRequestId: slot.manualRequestId ?? null,
+                });
                 continue;
+            }
             if (cell.status === 'pending' || cell.status === 'selected') {
                 // Ran but never reached a terminal state (target threw before delivery).
                 // Persist a normalized reason so the operator sees a first-level cause,
@@ -503,8 +557,9 @@ class SlotCoordinator {
         let duplicate = 0;
         let executor_failed = 0;
         let delivery_failed = 0;
+        let cancelled = 0;
         const targetsDetail = cellRows.map((cell) => {
-            const classified = this.classifyCell(cell.status, slot.slotId, cell.targetId, deliveryTargetsByTargetId);
+            const classified = this.classifyCell(cell, slot.slotId, deliveryTargetsByTargetId);
             if (classified === 'submitted')
                 submitted += 1;
             else if (classified === 'no_match')
@@ -513,6 +568,8 @@ class SlotCoordinator {
                 duplicate += 1;
             else if (classified === 'delivery_failed')
                 delivery_failed += 1;
+            else if (classified === 'cancelled')
+                cancelled += 1;
             else if (classified === 'executor_failed')
                 executor_failed += 1;
             return {
@@ -529,8 +586,8 @@ class SlotCoordinator {
         // `all_duplicates` there would be a lie — so the count must be non-zero.
         const nonSubmitted = cellRows.length - submitted;
         const all_duplicates = nonSubmitted > 0 && duplicate === nonSubmitted;
-        const startedMs = sqliteUtcMs(slotRec?.startedAt);
-        const completedMs = sqliteUtcMs(slotRec?.completedAt);
+        const startedMs = (0, ledger_time_1.sqliteUtcMs)(slotRec?.startedAt);
+        const completedMs = (0, ledger_time_1.sqliteUtcMs)(slotRec?.completedAt);
         const duration_ms = startedMs !== undefined && completedMs !== undefined
             ? Math.max(0, completedMs - startedMs)
             : undefined;
@@ -543,10 +600,11 @@ class SlotCoordinator {
             duplicate_exhausted: targetsDetail.filter((t) => t.terminal_reason_code === 'duplicate_exhausted').length,
             executor_failed,
             delivery_failed,
+            cancelled,
         });
         return {
             event: 'schedule.outcome',
-            outcome_version: 1,
+            outcome_version: 2,
             schedule_id: slotRec?.scheduleId ?? slot.scheduleId,
             slot_id: slot.slotId,
             occurrence_at: isoUtcOrUndefined(occurrenceAt),
@@ -563,6 +621,7 @@ class SlotCoordinator {
                 all_duplicates,
                 executor_failed,
                 delivery_failed,
+                cancelled,
                 targets: targetsDetail,
             },
         };
@@ -572,14 +631,22 @@ class SlotCoordinator {
      * durable delivery ledger through the SAME port the FSM already uses, never
      * from an error string, and it is decided BEFORE `executor_failed` because a
      * terminally lost delivery also leaves the cell `failed`: one cause, one count.
+     *
+     * A consumer cancel is decided before both: it also ends as a `failed` cell,
+     * but it is a deliberate stop rather than a system failure, so it must not be
+     * counted as an executor failure (which would make it alertable).
      */
-    classifyCell(cellStatus, slotId, targetId, deliveryTargetsByTargetId) {
+    classifyCell(cell, slotId, deliveryTargetsByTargetId) {
+        const cellStatus = cell.status;
+        const targetId = cell.targetId;
         if (cellStatus === 'submitted')
             return 'submitted';
         if (cellStatus === 'no_candidate')
             return 'no_match';
         if (cellStatus === 'duplicate')
             return 'duplicate';
+        if (cellStatus === 'failed' && cell.terminalReasonCode === ProtocolErrors_1.CANCELLED_BY_CONSUMER)
+            return 'cancelled';
         const deliveryTargets = deliveryTargetsByTargetId.get(targetId);
         if (deliveryTargets && deliveryTargets.length > 0 && this.delivery) {
             try {

package/dist/scheduler/StallSweep.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Liveness sweep for the durable Slot ledger (§liveness).
+ *
+ * Accepted work must not be able to sit in a non-terminal state forever. Two
+ * situations can strand a Slot that no worker will ever touch again:
+ *
+ *  - `queued_too_long`: the Slot was admitted (202) but nothing ever claimed it
+ *    — the plan is disabled, its Scheduler is stopped, or the resource wait
+ *    queue never drained. `recoverableSlots()` retries such rows on every tick,
+ *    which keeps reporting them as "unfinished" forever when admission keeps
+ *    failing.
+ *  - `stalled_no_heartbeat`: a worker claimed the Slot and then stopped
+ *    heartbeating (crash, OOM, redeploy window). Its lease expires, but nothing
+ *    terminalises the row, so `countActiveSlots()` keeps the worker alive and a
+ *    caller polling the job state sees a frozen `running`.
+ *
+ * Both rules are LIVENESS-based and deliberately generous: a genuinely
+ * progressing job renews its lease every 30s and writes a heartbeat, so it can
+ * never be selected — however long a real Pixiv search takes (production runs of
+ * 10-40 minutes, occasionally queued hours behind a busy account).
+ *
+ * The sweep only ever writes terminal states for cells that never made progress
+ * (`pending`/`selected`). A cell already handed to the delivery ledger keeps its
+ * own lifecycle; `SlotCoordinator.finish` is what converges an abandoned one.
+ */
+import type { Database } from '../storage/Database';
+/** Nothing is ever stalled before this: a floor against a misconfigured budget. */
+export declare const STALL_SWEEP_MIN_TIMEOUT_MS: number;
+/** Admitted but never claimed for this long -> `queued_too_long`. */
+export declare const DEFAULT_QUEUED_TIMEOUT_MS: number;
+/** No heartbeat/lease for this long while `running` -> `stalled_no_heartbeat`. */
+export declare const DEFAULT_STALL_TIMEOUT_MS: number;
+/** Bounded batch: one tick must stay cheap on a large ledger. */
+export declare const STALL_SWEEP_BATCH_LIMIT = 100;
+export interface StallTimeouts {
+    queuedTimeoutMs: number;
+    stallTimeoutMs: number;
+}
+/** The two budgets as configured, each clamped to the floor / its default. */
+export declare function resolveStallTimeouts(rt?: {
+    queuedTimeoutMs?: unknown;
+    stallTimeoutMs?: unknown;
+}): StallTimeouts;
+export interface StallSweepOptions extends Partial<StallTimeouts> {
+    /** Injectable clock (tests). */
+    now?: number;
+    /** Max rows examined per rule per tick. */
+    limit?: number;
+    /**
+     * Slots recovery re-dispatched on this same tick. They are owned by an
+     * asynchronous run that has not claimed its lease yet, so they are excluded
+     * here: crash-resume must not be turned into a failure by the sweep that runs
+     * right after it.
+     */
+    skipSlotIds?: ReadonlySet<string>;
+}
+export interface StallSweepResult {
+    /** Rows examined (both rules together). */
+    scanned: number;
+    queuedTooLong: number;
+    stalledNoHeartbeat: number;
+}
+/** One bounded, liveness-aware sweep. Never throws for a single bad row. */
+export declare function sweepStalledSlots(database: Database, options?: StallSweepOptions): StallSweepResult;
+//# sourceMappingURL=StallSweep.d.ts.map