pixivflow 2.16.1 → 2.18.0

package/dist/commands/DiagnoseEgressCommand.js

@@ -0,0 +1,327 @@
+"use strict";
+/**
+ * `pixivflow diagnose egress` — minimal Pixiv data-plane egress probe.
+ *
+ * Reachability is not suitability: a datacenter egress can pass OAuth and still be
+ * rate-limit-starved on the production search workload (2026-09-11, GitHub-hosted
+ * runners). This command answers, with a handful of tiny requests, three INDEPENDENT
+ * questions about the network it runs on:
+ *
+ *   1. OAuth   oauth.secure.pixiv.net  — one real refresh-token exchange
+ *   2. App API app-api.pixiv.net       — 1 small fixed request, status + Retry-After
+ *   3. Media   i.pximg.net             — 64 KiB Range request with the app Referer
+ *
+ * It never runs the business workload (no 12 tags / 100 samples / pagination), so it
+ * cannot by itself drive the account into a penalty. Output is a findings list plus a
+ * uniform verdict (PASS / DEGRADED / FAIL) suitable for a provider-qualification matrix.
+ *
+ * Exit codes: 0 = no findings above warn, 1 = warn (degraded evidence), 2 = critical
+ * (a data plane is unusable from this egress).
+ *
+ * The OAuth probe performs ONE real token refresh. PixivAuth persists a rotated refresh
+ * token (database + unified storage + config), which is the desired durable behaviour —
+ * run this probe only when no production execution holds the credential, exactly like
+ * `account rotate`.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DiagnoseEgressCommand = void 0;
+const Command_1 = require("./Command");
+const metadata_1 = require("./metadata");
+const Database_1 = require("../storage/Database");
+const PixivAuth_1 = require("../auth/PixivAuth");
+const errors_1 = require("../utils/errors");
+/** The documented placeholder rules: empty, the template string, or implausibly short. */
+function isPlaceholderToken(token) {
+    const value = typeof token === 'string' ? token.trim() : '';
+    return value.length === 0 || value === 'YOUR_REFRESH_TOKEN' || value.length < 10;
+}
+const PROBE_TIMEOUT_MS = 15_000;
+/** this-safe fetch wrapper (Cloudflare/undici reject `this.fetch(...)`). */
+const defaultFetch = (input, init) => globalThis.fetch(input, init);
+class DiagnoseEgressCommand extends Command_1.BaseCommand {
+    deps;
+    name = 'diagnose';
+    description = 'Minimal Pixiv data-plane egress probe (usage: diagnose egress)';
+    aliases = ['diag'];
+    requiresToken = false;
+    metadata = {
+        category: metadata_1.CommandCategory.MONITORING,
+        requiresAuth: false,
+        longRunning: false,
+        examples: ['pixivflow diagnose egress', 'pixivflow diagnose egress --json', 'pixivflow diagnose egress --illust-id 12345'],
+        relatedCommands: ['health', 'doctor'],
+    };
+    constructor(
+    /** Injectable for tests; defaults to a this-safe global fetch. */
+    deps = {}) {
+        super();
+        this.deps = deps;
+    }
+    getUsage() {
+        return [
+            'diagnose egress [--json] [--illust-id <id>] [--provider <name>] [--region <code>]',
+            '  Minimal Pixiv egress probe: OAuth refresh, one small App API request,',
+            '  one 64 KiB media Range request. Exit 0/1/2 = ok/warn/critical.',
+        ].join('\n');
+    }
+    async execute(context, args) {
+        const sub = args.positional[0] || 'egress';
+        if (sub !== 'egress') {
+            return this.failure(`Unknown diagnose target: ${sub}. Try: pixivflow diagnose egress`);
+        }
+        const findings = [];
+        const fetchImpl = this.deps.fetchImpl ?? defaultFetch;
+        const provider = String(args.options.provider ?? this.deps.provider ?? 'local');
+        const region = String(args.options.region ?? this.deps.region ?? 'unknown');
+        const illustId = String(args.options['illust-id'] ?? '92421724');
+        const proxy = context.config?.network?.proxy;
+        // --no-proxy tests the DIRECT egress even when a proxy is configured: a
+        // qualification matrix wants both paths, and a stale proxy setting must not
+        // mask what the network itself can do.
+        const noProxy = args.options['no-proxy'] === true;
+        const useProxy = !noProxy && !!(proxy?.enabled && proxy.host && proxy.port);
+        // The OAuth probe builds its own client from config.network — hand it the same
+        // overridden view so all three probes test the SAME egress path.
+        const networkForAuth = noProxy
+            ? { ...(context.config?.network ?? {}), proxy: undefined }
+            : context.config?.network ?? {};
+        // --- 1. General reachability (pixiv.net answers 403 to probes; that IS a pass) ---
+        await this.probeReachable(fetchImpl, useProxy ? proxy : undefined, findings);
+        // --- 2. OAuth: one real refresh exchange ---
+        let accessToken = null;
+        let db = null;
+        const refreshToken = context.config?.pixiv?.refreshToken;
+        if (isPlaceholderToken(refreshToken)) {
+            findings.push({
+                level: 'skipped',
+                code: 'oauth-skipped',
+                message: 'no usable refresh token in config; OAuth data plane not tested',
+            });
+        }
+        else {
+            try {
+                db = new Database_1.Database(context.config.storage?.databasePath ?? './data/pixiv-downloader.db');
+                db.migrate();
+                const auth = new PixivAuth_1.PixivAuth(context.config.pixiv, networkForAuth, db, context.configPath);
+                const started = performance.now();
+                accessToken = (0, PixivAuth_1.isAuthReadOnly)()
+                    ? await auth.getAccessToken() // readonly: cache only; the token endpoint is NOT tested
+                    : await auth.refreshAccessTokenForClient();
+                const latencyMs = Math.round(performance.now() - started);
+                const fromCache = (0, PixivAuth_1.isAuthReadOnly)();
+                findings.push({
+                    level: 'ok',
+                    code: fromCache ? 'oauth-cache-ok' : 'oauth-refresh-ok',
+                    message: fromCache
+                        ? `OAuth access token served from cache in ${latencyMs}ms (PIXIV_AUTH_READONLY: the token endpoint was NOT tested)`
+                        : `OAuth refresh succeeded in ${latencyMs}ms`,
+                    data: { latencyMs },
+                });
+            }
+            catch (error) {
+                if ((0, PixivAuth_1.isAuthReadOnly)() || error instanceof errors_1.AuthenticationError) {
+                    findings.push({
+                        level: 'warn',
+                        code: 'oauth-readonly-blocked',
+                        message: 'PIXIV_AUTH_READONLY blocks the token endpoint; OAuth data plane NOT tested. ' +
+                            'Re-run without the flag (and with no production execution holding the credential).',
+                        data: { error: error instanceof Error ? error.message : String(error) },
+                    });
+                }
+                else {
+                    findings.push({
+                        level: 'critical',
+                        code: 'oauth-failed',
+                        message: `OAuth refresh failed: ${error instanceof Error ? error.message : String(error)}`,
+                    });
+                }
+            }
+        }
+        // --- 3. App API: one small fixed request ---
+        let mediaUrl = null;
+        const appApi = await this.probeAppApi(fetchImpl, accessToken, illustId, findings);
+        if (appApi?.mediaUrl)
+            mediaUrl = appApi.mediaUrl;
+        // --- 4. Media CDN: 64 KiB Range request with the app Referer ---
+        const media = await this.probeMedia(fetchImpl, mediaUrl, findings);
+        if (db)
+            db.close();
+        const summary = this.summarize(provider, region, findings, appApi, media);
+        this.print(context, summary, args.options.json === true);
+        const exitCode = findings.some((f) => f.level === 'critical') ? 2 : findings.some((f) => f.level === 'warn') ? 1 : 0;
+        return this.withExitCode(this.success(`egress verdict: ${summary.verdict}`, summary), exitCode);
+    }
+    /** pixiv.net answers 403 to anonymous probes; any HTTP response proves reachability. */
+    async probeReachable(fetchImpl, proxy, findings) {
+        try {
+            const init = { signal: AbortSignal.timeout(PROBE_TIMEOUT_MS) };
+            if (proxy) {
+                // Same proxy path the download pipeline uses (see HealthCommand.checkNetwork).
+                const undici = require('undici');
+                const protocol = (proxy.protocol || 'http').toLowerCase();
+                const auth = proxy.username && proxy.password
+                    ? `${encodeURIComponent(proxy.username)}:${encodeURIComponent(proxy.password)}@`
+                    : '';
+                init.dispatcher = new undici.ProxyAgent(`${protocol}://${auth}${proxy.host}:${proxy.port}`);
+            }
+            const started = performance.now();
+            const res = await fetchImpl('https://www.pixiv.net/', init);
+            const latencyMs = Math.round(performance.now() - started);
+            findings.push({
+                level: 'ok',
+                code: 'pixiv-net-ok',
+                message: `pixiv.net reachable (HTTP ${res.status}) in ${latencyMs}ms`,
+                data: { status: res.status, latencyMs },
+            });
+        }
+        catch (error) {
+            findings.push({
+                level: 'critical',
+                code: 'pixiv-net-unreachable',
+                message: `pixiv.net unreachable: ${error instanceof Error ? error.message : String(error)}`,
+            });
+        }
+    }
+    /**
+     * One small App API request. Any HTTP response proves the data plane is reachable;
+     * 429 is the starvation signal this probe exists to surface.
+     */
+    async probeAppApi(fetchImpl, accessToken, illustId, findings) {
+        if (!accessToken) {
+            findings.push({
+                level: 'skipped',
+                code: 'appapi-skipped',
+                message: 'no access token (OAuth skipped/failed); App API data plane not tested authenticated',
+            });
+            return null;
+        }
+        const url = `https://app-api.pixiv.net/v1/illust/detail?illust_id=${encodeURIComponent(illustId)}`;
+        try {
+            const started = performance.now();
+            const res = await fetchImpl(url, {
+                headers: {
+                    authorization: `Bearer ${accessToken}`,
+                    // The App API rejects requests without an app User-Agent.
+                    'user-agent': 'PixivAndroidApp/5.0.234 (Android 11; Pixel 5)',
+                    'app-os': 'android',
+                    'app-os-version': '11',
+                },
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
+            const ttfbMs = Math.round(performance.now() - started);
+            const retryAfter = res.headers.get('retry-after');
+            const retryAfterMs = retryAfter !== null ? Number(retryAfter) * 1000 || null : null;
+            let mediaUrl = null;
+            try {
+                const body = (await res.json());
+                mediaUrl =
+                    body.illust?.meta_single_page?.original_image_url ??
+                        body.illust?.meta_pages?.[0]?.image_urls?.original ??
+                        null;
+            }
+            catch {
+                // A non-JSON body is recorded via status; the media probe then reports skipped.
+            }
+            const rateLimited = res.status === 429;
+            findings.push({
+                level: rateLimited ? 'warn' : 'ok',
+                code: rateLimited ? 'appapi-429' : 'appapi-ok',
+                message: `App API responded HTTP ${res.status} in ${ttfbMs}ms${retryAfter ? ` (retry-after ${retryAfter}s)` : ''}`,
+                data: { status: res.status, ttfbMs, retryAfterMs },
+            });
+            return { status: res.status, ttfbMs, durationMs: ttfbMs, rateLimited, retryAfterMs, mediaUrl };
+        }
+        catch (error) {
+            findings.push({
+                level: 'critical',
+                code: 'appapi-failed',
+                message: `App API request failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return null;
+        }
+    }
+    /** 64 KiB Range request — never a full media download. */
+    async probeMedia(fetchImpl, mediaUrl, findings) {
+        if (!mediaUrl) {
+            findings.push({
+                level: 'skipped',
+                code: 'media-skipped',
+                message: 'no media URL from the App API response; media CDN not tested',
+            });
+            return { status: null, ttfbMs: null, bytes64kDurationMs: null, timedOut: false };
+        }
+        try {
+            const started = performance.now();
+            const res = await fetchImpl(mediaUrl, {
+                headers: {
+                    range: 'bytes=0-65535',
+                    // i.pximg.net requires the app referer or it answers 403.
+                    referer: 'https://app-api.pixiv.net/',
+                },
+                signal: AbortSignal.timeout(PROBE_TIMEOUT_MS),
+            });
+            const durationMs = Math.round(performance.now() - started);
+            await res.arrayBuffer().catch(() => null);
+            const ok = res.status === 200 || res.status === 206;
+            findings.push({
+                level: ok ? 'ok' : res.status === 429 ? 'warn' : 'critical',
+                code: ok ? 'media-ok' : res.status === 429 ? 'media-429' : 'media-blocked',
+                message: `media CDN responded HTTP ${res.status} in ${durationMs}ms (64 KiB Range)`,
+                data: { status: res.status, bytes64kDurationMs: durationMs },
+            });
+            return { status: res.status, ttfbMs: durationMs, bytes64kDurationMs: durationMs, timedOut: false };
+        }
+        catch (error) {
+            const timedOut = error instanceof Error && /timeout|abort/i.test(error.message);
+            findings.push({
+                level: 'critical',
+                code: timedOut ? 'media-timeout' : 'media-failed',
+                message: `media CDN request failed: ${error instanceof Error ? error.message : String(error)}`,
+            });
+            return { status: null, ttfbMs: null, bytes64kDurationMs: null, timedOut };
+        }
+    }
+    summarize(provider, region, findings, appApi, media) {
+        const oauth = findings.find((f) => f.code.startsWith('oauth-'));
+        const incomplete = findings.some((f) => f.level === 'skipped');
+        const critical = findings.some((f) => f.level === 'critical');
+        const degraded = findings.some((f) => f.level === 'warn');
+        const verdict = critical ? 'FAIL' : degraded ? 'DEGRADED' : incomplete ? 'INCOMPLETE' : 'PASS';
+        return {
+            provider,
+            region,
+            network: 'datacenter-egress',
+            oauth: {
+                status: oauth ? oauth.code : 'oauth-skipped',
+                latencyMs: oauth?.data?.latencyMs ?? null,
+                refreshed: oauth?.code === 'oauth-refresh-ok',
+            },
+            appApi: {
+                status: appApi?.status ?? null,
+                ttfbMs: appApi?.ttfbMs ?? null,
+                durationMs: appApi?.durationMs ?? null,
+                rateLimited: appApi?.rateLimited ?? false,
+                retryAfterMs: appApi?.retryAfterMs ?? null,
+            },
+            media,
+            verdict,
+            incomplete,
+            findings,
+        };
+    }
+    print(context, summary, asJson) {
+        if (asJson) {
+            context.logger.info(JSON.stringify(summary, null, 2));
+            return;
+        }
+        context.logger.info('━━━ Pixiv egress probe ━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        for (const f of summary.findings) {
+            const mark = f.level === 'ok' ? '✓' : f.level === 'warn' ? '⚠' : f.level === 'critical' ? '✗' : '·';
+            context.logger.info(`  ${mark} [${f.level.toUpperCase()}] ${f.code}: ${f.message}`);
+        }
+        context.logger.info('━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━');
+        context.logger.info(`  verdict: ${summary.verdict}${summary.incomplete ? ' (incomplete: some probes were skipped)' : ''}`);
+    }
+}
+exports.DiagnoseEgressCommand = DiagnoseEgressCommand;
+//# sourceMappingURL=DiagnoseEgressCommand.js.map

package/dist/commands/DiagnoseEgressCommand.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"DiagnoseEgressCommand.js","sourceRoot":"","sources":["../../src/commands/DiagnoseEgressCommand.ts"],"names":[],"mappings":"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"}

package/dist/commands/ExecuteSlotCommand.d.ts

@@ -0,0 +1,37 @@
+/**
+ * execute-slot: run ONE canonical occurrence as a disposable batch job.
+ *
+ * This is the execution plane of the serverless production architecture. The
+ * control plane has already decided *which* occurrence is due and hands the runner
+ * its canonical identity; the runner never re-derives "what should run today" and
+ * never opens a long-lived daemon:
+ *
+ *   control plane → workflow_dispatch(slot_id, schedule_id, occurrence_at, ...)
+ *     → this command runs exactly that slot's targets once
+ *     → writes one machine-readable result document
+ *     → exits with a status-bearing code
+ *
+ * Deliberately NOT `pixivflow scheduler`: no cron, no slots, no leases, no local
+ * ledger requirement. Duplicate history still comes from the local database when
+ * one is present, and the control plane owns cross-runner duplicate state.
+ */
+import { BaseCommand } from './Command';
+import { CommandCategory } from './metadata';
+import { CommandContext, CommandArgs, CommandResult } from './types';
+export declare class ExecuteSlotCommand extends BaseCommand {
+    readonly name = "execute-slot";
+    readonly description = "Execute one canonical occurrence once (batch/CI execution plane)";
+    readonly aliases: string[];
+    readonly metadata: {
+        category: CommandCategory;
+        requiresAuth: boolean;
+        longRunning: boolean;
+    };
+    validate(args: CommandArgs): {
+        valid: boolean;
+        errors: string[];
+    };
+    execute(context: CommandContext, args: CommandArgs): Promise<CommandResult>;
+    getUsage(): string;
+}
+//# sourceMappingURL=ExecuteSlotCommand.d.ts.map

package/dist/commands/ExecuteSlotCommand.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ExecuteSlotCommand.d.ts","sourceRoot":"","sources":["../../src/commands/ExecuteSlotCommand.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAIH,OAAO,EAAE,WAAW,EAAE,MAAM,WAAW,CAAC;AACxC,OAAO,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAC7C,OAAO,EAAE,cAAc,EAAE,WAAW,EAAE,aAAa,EAAE,MAAM,SAAS,CAAC;AAiCrE,qBAAa,kBAAmB,SAAQ,WAAW;IACjD,QAAQ,CAAC,IAAI,kBAAkB;IAC/B,QAAQ,CAAC,WAAW,sEAAsE;IAC1F,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,CAAa;IACvC,QAAQ,CAAC,QAAQ;;;;MAIf;IAEF,QAAQ,CAAC,IAAI,EAAE,WAAW;;;;IAqBpB,OAAO,CAAC,OAAO,EAAE,cAAc,EAAE,IAAI,EAAE,WAAW,GAAG,OAAO,CAAC,aAAa,CAAC;IA+IjF,QAAQ,IAAI,MAAM;CAqCnB"}

package/dist/commands/ExecuteSlotCommand.js

@@ -0,0 +1,267 @@
+"use strict";
+/**
+ * execute-slot: run ONE canonical occurrence as a disposable batch job.
+ *
+ * This is the execution plane of the serverless production architecture. The
+ * control plane has already decided *which* occurrence is due and hands the runner
+ * its canonical identity; the runner never re-derives "what should run today" and
+ * never opens a long-lived daemon:
+ *
+ *   control plane → workflow_dispatch(slot_id, schedule_id, occurrence_at, ...)
+ *     → this command runs exactly that slot's targets once
+ *     → writes one machine-readable result document
+ *     → exits with a status-bearing code
+ *
+ * Deliberately NOT `pixivflow scheduler`: no cron, no slots, no leases, no local
+ * ledger requirement. Duplicate history still comes from the local database when
+ * one is present, and the control plane owns cross-runner duplicate state.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.ExecuteSlotCommand = void 0;
+const node_fs_1 = require("node:fs");
+const Command_1 = require("./Command");
+const metadata_1 = require("./metadata");
+const schedules_1 = require("../scheduler/schedules");
+const Scheduler_1 = require("../scheduler/Scheduler");
+const scheduler_runtime_1 = require("./scheduler-runtime");
+const runDiagnostics_1 = require("../batch/runDiagnostics");
+const executionResult_1 = require("../batch/executionResult");
+function stringOption(args, ...names) {
+    for (const name of names) {
+        const value = args.options[name];
+        if (typeof value === 'string' && value.trim().length > 0)
+            return value.trim();
+    }
+    return undefined;
+}
+class ExecuteSlotCommand extends Command_1.BaseCommand {
+    name = 'execute-slot';
+    description = 'Execute one canonical occurrence once (batch/CI execution plane)';
+    aliases = ['batch'];
+    metadata = {
+        category: metadata_1.CommandCategory.DOWNLOAD,
+        requiresAuth: true,
+        longRunning: false,
+    };
+    validate(args) {
+        const errors = [];
+        const scheduleId = stringOption(args, 'schedule-id', 'scheduleId');
+        if (!scheduleId)
+            errors.push('--schedule-id is required (which schedule to execute)');
+        const slotId = stringOption(args, 'slot-id', 'slotId');
+        if (!slotId)
+            errors.push('--slot-id is required (canonical occurrence identity)');
+        const mode = stringOption(args, 'mode') ?? 'live';
+        if (!scheduler_runtime_1.EXECUTION_MODES.includes(mode)) {
+            errors.push(`--mode must be one of ${scheduler_runtime_1.EXECUTION_MODES.join(', ')}`);
+        }
+        const attempt = stringOption(args, 'attempt');
+        if (attempt && (!Number.isInteger(Number(attempt)) || Number(attempt) < 1)) {
+            errors.push('--attempt must be a positive integer');
+        }
+        const timeout = stringOption(args, 'timeout-ms', 'timeoutMs');
+        if (timeout && (!Number.isFinite(Number(timeout)) || Number(timeout) <= 0)) {
+            errors.push('--timeout-ms must be a positive number');
+        }
+        return { valid: errors.length === 0, errors };
+    }
+    async execute(context, args) {
+        const scheduleId = stringOption(args, 'schedule-id', 'scheduleId');
+        const slotId = stringOption(args, 'slot-id', 'slotId');
+        const mode = (stringOption(args, 'mode') ?? 'live');
+        const attempt = Number(stringOption(args, 'attempt') ?? '1');
+        const botId = stringOption(args, 'bot-id', 'botId');
+        const occurrenceAtRaw = stringOption(args, 'occurrence-at', 'occurrenceAt');
+        const occurrenceAt = occurrenceAtRaw ? Number(occurrenceAtRaw) : undefined;
+        const resultFile = stringOption(args, 'result-file', 'resultFile');
+        const excludeFile = stringOption(args, 'exclude-work-ids', 'excludeWorkIds');
+        const timeoutMs = Number(stringOption(args, 'timeout-ms', 'timeoutMs') ?? Scheduler_1.DEFAULT_SCHEDULE_TIMEOUT_MS);
+        const targetFilter = (stringOption(args, 'targets') ?? '')
+            .split(',')
+            .map((value) => value.trim())
+            .filter(Boolean);
+        const startedAt = new Date();
+        const startedMs = Date.now();
+        // Counts must not leak between runs (the scheduler calls this in-process too).
+        (0, runDiagnostics_1.resetRunDiagnostics)();
+        const outcomes = [];
+        let runtime;
+        let expectedTargetIds = [];
+        let outbox;
+        let fatal;
+        try {
+            runtime = await (0, scheduler_runtime_1.createSchedulerRuntime)(args.options.config);
+            const schedule = (0, schedules_1.resolveSchedules)(runtime.config).find((plan) => plan.id === scheduleId);
+            if (!schedule) {
+                throw new Error(`unknown schedule: ${scheduleId}`);
+            }
+            if (schedule.enabled === false) {
+                throw new Error(`schedule is disabled: ${scheduleId}`);
+            }
+            // The canonical target list comes from the schedule (and may be narrowed by
+            // the dispatcher). It is the expectation set: anything missing from the
+            // outcomes is reported as `missing`, never silently dropped.
+            const scheduleTargets = schedule.targetIds ?? [];
+            expectedTargetIds = targetFilter.length > 0
+                ? (scheduleTargets.length > 0
+                    ? scheduleTargets.filter((id) => targetFilter.includes(id))
+                    : targetFilter)
+                : scheduleTargets;
+            if (expectedTargetIds.length === 0) {
+                throw new Error(`no targets resolved for schedule ${scheduleId}`);
+            }
+            context.logger.info('Executing canonical occurrence', {
+                slotId,
+                scheduleId,
+                attempt,
+                mode,
+                targets: expectedTargetIds,
+            });
+            // Durable duplicate history: works this bot already handled, fetched by the
+            // caller (the batch runner asks the control plane). Without it a disposable
+            // runner re-selects work that was delivered weeks ago.
+            const excludedWorkIds = excludeFile ? readExcludedWorkIds(excludeFile, context) : undefined;
+            await (0, scheduler_runtime_1.runWithTimeout)(runtime.runJob(runtime.config, schedule, {
+                // Ad-hoc by design: the control plane owns the occurrence ledger now, so
+                // this run must not open or resume a local scheduled Slot.
+                adhoc: true,
+                triggerSource: 'http',
+                deliveryMode: mode,
+                onTargetOutcome: (targetId, outcome) => {
+                    outcomes.push((0, executionResult_1.outcomeToTargetResult)(targetId, outcome));
+                    // The typed Pixiv errors are recorded where they are raised; this catches
+                    // the paths that only keep a message.
+                    if (outcome.kind === 'failed' && outcome.error)
+                        (0, runDiagnostics_1.recordRunError)(outcome.error);
+                },
+                ...(excludedWorkIds ? { excludedWorkIds } : {}),
+            }), timeoutMs, () => runtime.cancelActive(`batch timeout after ${timeoutMs}ms`), `slot ${slotId}`);
+            // Bounded drain: deliveries created by this run get one chance to confirm
+            // before we report. Rows that cannot finish now stay durable and are
+            // resolved by the control plane's reconciliation, never by a blind resend.
+            outbox = await runtime.drainOutbox();
+        }
+        catch (error) {
+            fatal = error instanceof Error ? error.message : String(error);
+            context.logger.error('Batch execution failed', { slotId, error: fatal });
+        }
+        finally {
+            try {
+                runtime?.close();
+            }
+            catch {
+                // Closing must never mask the real failure above.
+            }
+        }
+        const summary = (0, executionResult_1.summarizeExecution)(outcomes, expectedTargetIds);
+        const finishedAt = new Date();
+        if (fatal)
+            (0, runDiagnostics_1.recordRunError)(fatal);
+        const diagnostics = (0, runDiagnostics_1.runDiagnostics)();
+        const result = {
+            slotId,
+            scheduleId,
+            ...(botId ? { botId } : {}),
+            attempt,
+            mode,
+            ...(occurrenceAt !== undefined && Number.isFinite(occurrenceAt) ? { occurrenceAt } : {}),
+            status: fatal ? 'failed' : summary.status,
+            exitCode: fatal ? executionResult_1.EXIT_ERROR : summary.exitCode,
+            startedAt: startedAt.toISOString(),
+            finishedAt: finishedAt.toISOString(),
+            durationMs: finishedAt.getTime() - startedMs,
+            targets: summary.targets,
+            ...(outbox ? { outbox } : {}),
+            ...(fatal ? { error: fatal } : {}),
+            // What went wrong, in a form the control plane can act on: a rate-limited
+            // account needs to wait for the server, a broken provider must not be retried
+            // on the same schedule, and the exit code cannot tell them apart.
+            ...(diagnostics.dominantCategory ? { errorClass: diagnostics.dominantCategory } : {}),
+            ...(diagnostics.maxRetryAfterMs !== null ? { retryAfterMs: diagnostics.maxRetryAfterMs } : {}),
+            ...(diagnostics.rateLimitHits > 0 ? { rateLimitHits: diagnostics.rateLimitHits } : {}),
+        };
+        const serialized = JSON.stringify(result, null, 2);
+        if (resultFile) {
+            (0, node_fs_1.writeFileSync)(resultFile, serialized, 'utf8');
+            context.logger.info('Wrote batch result', { resultFile });
+        }
+        else {
+            // stdout is the machine interface when no file is requested; keep it clean
+            // (all human logging goes to stderr/the logger).
+            process.stdout.write(`${serialized}\n`);
+        }
+        if (fatal) {
+            return this.withExitCode(this.failure(fatal, result), executionResult_1.EXIT_ERROR);
+        }
+        return this.withExitCode(this.success(`slot ${slotId}: ${result.status}`, result), result.exitCode);
+    }
+    getUsage() {
+        return `execute-slot
+
+Execute ONE canonical occurrence once and exit. This is the batch/CI execution
+plane: the control plane decides which occurrence is due, this command runs it.
+
+Required:
+  --schedule-id <id>       Schedule to execute (e.g. bot1-daily)
+  --slot-id <id>           Canonical occurrence (e.g. bot1-daily@2026-09-11T1800)
+
+Optional:
+  --occurrence-at <ms>     Canonical occurrence instant (epoch ms), for audit
+  --attempt <n>            Attempt number, echoed into the result (default 1)
+  --bot-id <id>            Bot identity, echoed into the result
+  --targets <a,b>          Restrict to these target ids (default: schedule targets)
+  --mode live|shadow|dry-run  Downstream publishing mode (default live)
+  --result-file <path>     Write the result JSON here
+  --timeout-ms <n>         Hard bound for the run (default: schedule timeout)
+  --exclude-work-ids <f>   JSON file of works this bot already handled:
+                           {"illustration":["id",...],"novel":[...]} (or the control
+                           plane's {"works":{...}} response). Durable duplicate
+                           history a disposable runner cannot know by itself.
+
+Machine interface: pass --result-file and read that file. Stdout also carries the
+process logger's lines, so it is NOT a strict JSON channel.
+
+Exit codes (the exit code IS the execution status):
+  0 success    every target was delivered/stored/deduplicated
+  2 partial    some targets delivered, some did not (incl. all-no-candidate)
+  3 failed     nothing was delivered
+  4 uncertain  a send was not confirmed; never auto-retried
+  1 error      the process itself could not run the slot
+
+Examples:
+  pixivflow execute-slot --schedule-id bot1-daily --slot-id bot1-daily@2026-09-11T1800 \\
+    --mode shadow --result-file /tmp/slot-result.json`;
+    }
+}
+exports.ExecuteSlotCommand = ExecuteSlotCommand;
+/**
+ * Read durable duplicate history. Accepts either the bare map or the control
+ * plane's envelope, and tolerates a missing/garbled file by logging loudly rather
+ * than silently running without history — that would re-post old work.
+ */
+function readExcludedWorkIds(path, context) {
+    try {
+        const parsed = JSON.parse((0, node_fs_1.readFileSync)(path, 'utf8'));
+        const source = (parsed.works && typeof parsed.works === 'object' ? parsed.works : parsed);
+        const toIds = (value) => Array.isArray(value) ? value.filter((id) => typeof id === 'string') : undefined;
+        const illustration = toIds(source.illustration);
+        const novel = toIds(source.novel);
+        if (!illustration && !novel) {
+            context.logger.warn('Duplicate-history file had no usable ids', { path });
+            return undefined;
+        }
+        context.logger.info('Loaded durable duplicate history', {
+            illustration: illustration?.length ?? 0,
+            novel: novel?.length ?? 0,
+        });
+        return { ...(illustration ? { illustration } : {}), ...(novel ? { novel } : {}) };
+    }
+    catch (error) {
+        context.logger.warn('Could not read the duplicate-history file; continuing without it', {
+            path,
+            error: error instanceof Error ? error.message : String(error),
+        });
+        return undefined;
+    }
+}
+//# sourceMappingURL=ExecuteSlotCommand.js.map