chore: bump version to 1.9.0

Degrading a link-cache entry (previous commit) closed the "user retries right
after a failure" case, but left a new one open: the entry could never regain
file ids. `cache_sent_task` skipped *every* cached send — its rule was "the
entry already holds the ids the next repeat wants" — which is true for a
healthy entry and false for a degraded one. So a degraded entry (pixiv's
hotlink-protected media, say) kept sending by URL forever, and every repeat
paid a download and an upload through the fallback that the file ids would
have avoided. Worse than the re-fetch it replaced.

The rule is now the one it always meant: a send whose cache snapshot still
carries file ids leaves the entry alone, and a send served from a degraded
entry writes back the ids it produced (the URLs in the rewritten entry come
from that send's own items, so they stay correct).

Verified by a test that drives `cache_sent_task` directly with both task
shapes: the degraded one updates the entry to the fresh id, the healthy one
leaves it untouched. 125 bot tests + 91 x-media tests, live suite (14) pass.

`cargo fmt --check`, `cargo clippy --workspace --all-targets --locked -- -D
warnings` and `cargo test --workspace --locked` clean.

.env.example

@@ -0,0 +1,76 @@
+# Copy to `.env` (gitignored) and fill in:
+#
+#   cp .env.example .env
+#
+# `docker compose` reads it for the `${VAR}` substitutions in
+# docker-compose.yml, and `cargo run` reads it through dotenv. Every variable is
+# described in README.md ("环境变量说明" / "Environment variables") — this file
+# only shows the shape, with the defaults the code would use anyway.
+
+# --- required -------------------------------------------------------------
+# Token from @BotFather. Without it the bot exits at startup.
+TELOXIDE_TOKEN=
+
+# --- sites (all optional) -------------------------------------------------
+# Pixiv: refresh token. Unset = pixiv links answer "support is disabled".
+PIXIV_REFRESH_TOKEN=
+# Twitter/X: the `auth_token` cookie of a logged-in session, used only for
+# NSFW tweets that the public syndication endpoint withholds.
+TWITTER_AUTH_TOKEN=
+# bilibili: the whole cookie string; only needed when the egress IP stays
+# risk-controlled (device cookies are fetched automatically).
+BILIBILI_COOKIE=
+
+# --- bot behaviour --------------------------------------------------------
+# Admin chat IDs, comma-separated: start/stop notices, admin-only commands.
+BOT_ADMIN=
+# Log level. Leave the line commented out for the default
+# (`info,hyper_util=warn,reqwest=warn`); do not set it to an empty value.
+# RUST_LOG=info,xmedia_bot=debug,x_media=debug
+# Edit-before-forward record TTL (seconds).
+EDIT_MESSAGE_TTL_SECONDS=86400
+# Link-result cache TTL (seconds).
+LINK_CACHE_TTL_SECONDS=604800
+# Wrap a post's text in a collapsible blockquote from this many characters on;
+# 0 disables the wrap.
+CAPTION_QUOTE_TEXT_CHARS=200
+# State directory (local runs only — the container uses /app/data).
+DATA_DIR=data
+
+# --- network --------------------------------------------------------------
+# HTTP proxy for the Bot API and site fetches. Two traps: teloxide panics on a
+# *blank* value, so comment the line out rather than leaving it empty; and
+# inside a container the proxy must be reachable from there (use
+# host.docker.internal, not 127.0.0.1 — that is the container itself).
+# docker-compose.yml does not pass this variable unless you add it to the bot
+# service's `environment:` block.
+# TELOXIDE_PROXY=http://127.0.0.1:10808
+
+# --- webhook deployment (docker-compose.yml) ------------------------------
+# false = long polling (no public URL needed). true = webhook behind the
+# bundled nginx-proxy — and then WEBHOOK_LISTEN/PORT/URL are required.
+WEBHOOK=false
+# WEBHOOK_LISTEN=0.0.0.0
+# WEBHOOK_PORT=8443
+# WEBHOOK_URL=https://your.domain/
+# Validation token Telegram echoes back as X-Telegram-Bot-Api-Secret-Token.
+# WEBHOOK_SECRET_TOKEN=
+# Self-signed certificate path, used only for Telegram-side validation (TLS is
+# terminated by the reverse proxy); unneeded with acme-companion. Not passed by
+# docker-compose.yml — add the line there if this deployment needs it.
+# WEBHOOK_CERT=/app/cert/cert.pem
+
+# --- reverse proxy (docker-compose.yml) -----------------------------------
+# Public domain or IP that nginx-proxy routes for; empty = do not route.
+VIRTUAL_HOST=
+# Port inside the bot container nginx-proxy forwards to.
+VIRTUAL_PORT=8443
+# Certificate notification address for acme-companion.
+DEFAULT_EMAIL=
+# UID the container runs as; it must be able to write ./data on the host.
+LOCAL_USER_ID=1000
+# Uncomment (here and the matching line in docker-compose.yml) to have
+# acme-companion issue the certificate for VIRTUAL_HOST.
+# ACME_HOST=
+# Send requests with an unknown Host to this vhost (needed for plain-IP access).
+# DEFAULT_HOST=

.gitignore

@@ -6,8 +6,6 @@ nginx-certs/
 nginx-vhost.d/
 nginx-html/
 nginx-acme/
-docker-compose.yml
-
 .env
 
 

AGENTS.md

@@ -4,7 +4,7 @@
 
 Telegram bot (teloxide) that turns post links from X/Twitter, Pixiv, Bluesky, Misskey (misskey.io), and Bilibili dynamics into media messages (images, video, GIF) with the post's title, author, and tags. It supports batch media splitting, retry with persistence, inline queries, forward-channel rebinding with caption templates, and Pixiv ugoira→MP4 transcoding. README is in Chinese; user-facing bot strings are in English. The project is a Rust port of a Python predecessor (see `queue.rs` comments referencing `utils/task_queue.py`).
 
-Two-crate Cargo workspace (both v1.8.0, edition 2024, resolver 3):
+Two-crate Cargo workspace (both v1.9.0, edition 2024, resolver 3):
 
 - **`crates/x-media`** — library that fetches and normalizes media from the four sites. Pure, no Telegram knowledge.
 - **`crates/xmedia-bot`** — the bot binary: teloxide dispatcher, SQLite-backed chat state, persistent task queue.
@@ -18,7 +18,7 @@ Telegram update → Dispatcher (polling or axum webhook) → dptree branches
   └─ callback_query → "forward" (copy to channel) / "template|<name>" (apply caption template)
 ```
 
-Message flow: `message_handler` extracts URLs (from `url`/`text_link` entities, text + caption, deduped) → `x_media::site::fetch(url)` → `Fetched` → builds a `Task` → `send::send_media_sequence` (media groups ≤ 10, caption on first item) or `send::send_animation`. On Telegram URL-fetch failure or size error (`send_batch_via_upload`): download via `x_media::site::download_media` to a temp file (≤ 10 MiB), sniff magic bytes (`sniff_ext`), upload via multipart; oversized items fall back to `fallback_url`. On failure: `enqueue_retry` persists resume-state `Task` into the SQLite queue → workers lease (120 s lock TTL) → retry with exponential backoff (≤ 30 s, `MAX_RETRIES = 2`) → dead-letter → `notify_failure`. Success → `post_send_actions`: edit-before-forward prompt with inline buttons, or `copy_messages` to the bound forward channel.
+Message flow: `message_handler` extracts URLs (from `url`/`text_link` entities, text + caption, deduped) → `x_media::site::fetch(url)` → `Fetched` → builds a `Task` → `send::send_media_sequence` (media groups ≤ 10, caption on first item) or `send::send_animation`. On Telegram URL-fetch failure or size error (`send_batch_via_upload`): download via `x_media::site::download_media` to a temp file (≤ 10 MiB), sniff magic bytes (`sniff_ext`), upload via multipart; oversized items fall back to `fallback_url`. On failure: `enqueue_retry` persists resume-state `Task` into the SQLite queue (it reports whether the row was really written, and only then does the user get the "retrying in Ns" notice — an enqueue that fails says so instead) → workers lease (120 s lock TTL) → retry with exponential backoff (≤ 30 s for the bot's own delays, `MAX_RETRIES = 2`) → dead-letter → `notify_failure`. Success → `post_send_actions`: edit-before-forward prompt with inline buttons, or `copy_messages` to the bound forward channel.
 
 Debug command: `/debug <url>` runs the same `x_media::site::fetch` and replies with `debug_report` (`handlers/commands.rs`) — site id, normalized cache key, source URL, title/author/tags, sensitive flag, caption and the media list — nothing is sent, cached or forwarded; the report is capped at 4000 chars and sent with HTML parse mode: raw fields are escaped, and the caption is wrapped in a `<blockquote>` so it renders exactly like the sent media caption (escaped text and links included). The caption it shows is `preview_caption`'s: the chat's per-site format override plus the long-post quoting, i.e. exactly what the send paths produce — showing the raw built-in caption made `/set_format` look like a no-op, and the `/set_format` success reply points users at `/debug` to preview.
 
@@ -26,7 +26,7 @@ User-facing failure text is a function of the error class, never one generic sen
 
 The `/test <url>` command runs the ordinary link pipeline (`urls::url_media`) with `PostSend::Suppressed`: the media is sent and cached like any other link, but the chat's `forward_channel_id`/`edit_before_forward` are ignored, so a test never forwards to the channel and never opens the edit prompt (retries and dead-letter notifications behave as usual). `/test`, `/debug`, `/set_format` and `/clear_cache` use the custom `parse_arg_remainder` parser (whole remainder, trimmed) because teloxide's built-in `split` parser takes exactly one space-separated token per field: `/set_format <site> <format>` never parsed with it (and `/clear_cache` without an argument did not either), and a command that fails to parse falls through to the URL flow in silence. `commands::tests::every_documented_invocation_parses` pins every documented form against exactly that.
 
-The inline path (`handlers/inline.rs`) hands media URLs straight to Telegram, which fetches them itself and cannot send site-specific headers — so `x_media::site::needs_media_headers(url)` (true exactly where a site's `media_headers` is non-empty, i.e. pixiv's pximg.net) marks the media that must be skipped instead of shipped broken; locally produced media (ugoira MP4, bsky remux) fails `Url::parse` and is skipped the same way. Inline results are therefore URL-only by construction.
+The inline path (`handlers/inline.rs`) hands media URLs straight to Telegram, which fetches them itself and cannot send site-specific headers — so `x_media::site::needs_media_headers(url)` (true exactly where a site's `media_headers` is non-empty, i.e. pixiv's pximg.net) marks the media that must be skipped instead of shipped broken; locally produced media (ugoira MP4, bsky remux) fails `Url::parse` and is skipped the same way. Inline results are therefore URL-only by construction, and a query whose every item was skipped is answered *empty* (with a cache window) rather than left unanswered — an unanswered query keeps the client spinning and, through the debounce's release, re-runs the fetch on every keystroke.
 
 `url_media` is a thin wrapper over `url_media_inner`: `run_with_chat_action` sends the chat action, then re-sends it every `ACTION_REFRESH` (4 s) while the pipeline future is pending, because Telegram drops an action after ~5 s and a fetch (ugoira encode, HLS remux) plus an upload routinely outlasts that. The pipeline flips the shared `ActionHint` from `Typing` to `UploadPhoto`/`UploadVideo` once the media kinds are known. The `select!` is `biased` on the pipeline branch so a finished pipeline never emits a stray action.
 
@@ -36,19 +36,19 @@ The `x-media` library: `site::fetch(url)` dispatches through the `SITES` registr
 
 | Path | Purpose |
 |---|---|
-| `crates/x-media/src/` | Fetch library. `site/mod.rs` = dispatcher + `Fetched`/`FetchError`/`download_media`/`media_size`; `media.rs` = `Media` enum; `examples/fetch.rs` = end-to-end usage sample |
-| `crates/x-media/src/site/<twitter\|pixiv\|bsky\|misskey\|bilibili>/` | One directory per site: `mod.rs` (re-exports), `interface.rs` (PATTERN, `enabled()`, `fetch_from_url()`, `cache_key`/`is_retryable`/`media_headers`, unit struct `<Name>Site` implementing `site::Site`, `From<SiteStruct> for Fetched`), `model.rs` (serde DTOs). Pixiv adds `api.rs` (auth + transport); twitter adds `auth.rs` (logged-in GraphQL `TweetDetail` fallback for NSFW tweets, gated on `TWITTER_AUTH_TOKEN`; without the token a withheld tweet stays `FetchError::Sensitive` and the bot reports it as age-restricted instead of "no media"). Misskey targets misskey.io only (`POST /api/notes/show`, 400+`NO_SUCH_NOTE` → NotFound). Bilibili fetches dynamics (images/animated images only — an attached video degrades to its cover, and its title stands in for the post text, which AV dynamics do not have) from `/x/polymer/web-dynamic/v1/detail` sent with `features=itemOpusStyle` (without that flag the legacy serialization drops an image/text post's body and headline entirely — `desc` comes back `null`; the adapter still parses the legacy `major.draw`/`desc`/`archive` shapes as a fallback). No WBI signature is involved; device cookies `buvid3`/`buvid4` are fetched automatically from `/x/frontend/finger/spi` because bilibili's `-352` risk control starts rejecting plain requests, `BILIBILI_COOKIE` is the escalation when an IP stays blocked; `b23.tv` short links are deliberately unmatched. Twitter's `from_syndication_json` HTML-decodes the API text — syndication and GraphQL `full_text` both arrive pre-escaped (`&gt;` `&lt;` `&amp;` `&#39;`) — so the stored text is raw and the caption escap…
-| `crates/xmedia-bot/src/main.rs` | Entry point: env/log init, command registration (`register_commands` — `setMyCommands` plus the profile description texts), shared `send::BOT` force-init, queue worker start, site login validation (`site::validate_all`), 300 s edit-expiry sweep (expired prompts are rewritten in place to `EDIT_PROMPT_EXPIRED_TEXT` with an empty keyboard — an edit, never a new message, so a background timer cannot wake a chat), dptree handler tree, webhook vs polling dispatch |
+| `crates/x-media/src/` | Fetch library. `site/mod.rs` = dispatcher + `Fetched`/`FetchError`/`download_media*` (the streaming `download_media_to_file` and the capped `download_media_limited`, which is where a download's size and its total time budget are enforced); `media.rs` = `Media` enum; `examples/fetch.rs` = end-to-end usage sample |
+| `crates/x-media/src/site/<twitter\|pixiv\|bsky\|misskey\|bilibili>/` | One directory per site: `mod.rs` (re-exports), `interface.rs` (PATTERN, `enabled()`, `fetch_from_url()`, `cache_key`/`is_retryable`/`media_headers`, unit struct `<Name>Site` implementing `site::Site`, `From<SiteStruct> for Fetched`), `model.rs` (serde DTOs). Pixiv adds `api.rs` (auth + transport); twitter adds `auth.rs` (logged-in GraphQL `TweetDetail` fallback for NSFW tweets, gated on `TWITTER_AUTH_TOKEN`; without the token a withheld tweet stays `FetchError::Sensitive` and the bot reports it as age-restricted instead of "no media"). Misskey targets misskey.io only (`POST /api/notes/show`, 400+`NO_SUCH_NOTE` → NotFound). Bilibili fetches dynamics (images/animated images only — an attached video degrades to its cover, and its title stands in for the post text, which AV dynamics do not have) from `/x/polymer/web-dynamic/v1/detail` sent with `features=itemOpusStyle` (without that flag the legacy serialization drops an image/text post's body and headline entirely — `desc` comes back `null`; the adapter still parses the legacy `major.draw`/`desc`/`archive` shapes as a fallback). No WBI signature is involved; device cookies `buvid3`/`buvid4` are fetched automatically from `/x/frontend/finger/spi` because bilibili's `-352` risk control starts rejecting plain requests, `BILIBILI_COOKIE` is the escalation when an IP stays blocked; `b23.tv` short links are deliberately unmatched. Twitter's `from_syndication_value` HTML-decodes the API text — syndication and GraphQL `full_text` both arrive pre-escaped (`&gt;` `&lt;` `&amp;` `&#39;`) — so the stored text is raw and the caption escap…
+| `crates/xmedia-bot/src/main.rs` | Entry point: env/log init, command registration (`register_commands` — `setMyCommands` plus the profile description texts), shared `send::BOT` force-init, startup sweep of this project's leftover temp files (`x_media::TEMP_FILE_PREFIX` + an age gate, since a killed process runs no destructors), startup repair of queued retries whose local media did not survive a restart (`handlers::repair_lost_local_media`, before any worker can lease: those rows are re-fetched from their `source_url`), queue worker start, site login validation (`site::validate_all`), `periodic_sweep` (`SWEEP_INTERVAL` 300 s): expired prompts are rewritten in place to `EDIT_PROMPT_EXPIRED_TEXT` with an empty keyboard — an edit, never a new message, so a background timer cannot wake a chat — plus the link-cache prune, the idle rate-limit buckets and the idle inline-query entries, and the queue backlog line (only when non-empty). Takes its collaborators rather than the statics so its loop is testable with a paused clock, dptree handler tree, webhook vs polling dispatch |
 | `crates/xmedia-bot/src/config.rs` | Manual env parsing into `Config` |
-| `crates/xmedia-bot/src/db.rs` | `DbPool`: one shared SQLite connection pool (`POOL_SIZE = 4`, WAL, busy_timeout) for all three tables over `$DATA_DIR/task_queue.db` (default `data/`) — the three stores share it; `open_store` creates file + schema, `with_conn` runs all rusqlite I/O in `spawn_blocking` |
-| `crates/xmedia-bot/src/handlers/` | Handler modules: `mod.rs` (message entry point, `reply`, `log_key`, the group-only `GROUP_LINK_HINT` for a supported link posted outside a private chat), `commands.rs` (teloxide `BotCommands` enum + command executor, incl. `/test <url>` (send-only) / `/debug <url>` (parse-only) and the admin-only `/bot_dict` state dump; `/set_format` rejects unknown `{…}` placeholders and resets with `-`), `urls.rs` (URL extraction + bounded job channel (256) drained by `URL_WORKERS = 8` workers (`start_url_workers`) — backpressure instead of unbounded spawns; teloxide's per-chat workers are sequential — batch-forwards need concurrency), `inline.rs`/`callback.rs` (inline queries / edit-before-forward buttons, incl. `skip`), `statics.rs` (global statics) |
-| `crates/xmedia-bot/src/state.rs` | `ChatStore`: parking_lot `Mutex<HashMap>` cache + SQLite write-through (`chat_state` table) |
-| `crates/xmedia-bot/src/link_cache.rs` | `LinkCache`: SQLite-backed cache (`link_cache` table) of successfully sent posts — raw caption fields + Telegram `file_id`s; repeat links re-send locally (no fetch/upload), TTL + prune, invalidated on permanent send failure |
-| `crates/xmedia-bot/src/queue.rs` | `PersistentTaskQueue`: SQLite-backed queue (`tasks` table), `QUEUE_WORKERS = 4` concurrent workers (lease via `BEGIN IMMEDIATE` + `locked_until` TTL), retry→dead-letter, `notify_one` worker wakeup plus a separate `Notify` for the 30 s lease-expiry sweep (a shared one let the sweep steal the workers' wakeup permit), `busy_timeout` on all connections |
-| `crates/xmedia-bot/src/ctx.rs` | `AppContext`: the injected collaborators (`sender` + `ChatStore`/`PersistentTaskQueue`/`LinkCache`/`Config`), `from_statics` for production and the `CONTEXT` static the worker closures hold. `test_support::TestStores` backs handler tests with a tempdir store set |
+| `crates/xmedia-bot/src/db.rs` | `DbPool`: one shared SQLite connection pool (`POOL_SIZE = 4`, WAL, busy_timeout) for all three tables over `$DATA_DIR/task_queue.db` (default `data/`) — the three stores share it; `open_store` creates file + schema and then applies the `PRAGMA user_version` migration chain (`MIGRATIONS` + `migrate` — append-only; `schema_init` is the version-0 baseline and must not gain columns an existing database would never receive — `db.rs`'s tests pin a pre-migration database upgrading intact, the shipped migration text frozen (appending is the only allowed change) and a fresh database landing at the latest version), `with_conn` runs all rusqlite I/O in `spawn_blocking` |
+| `crates/xmedia-bot/src/handlers/` | Handler modules: `mod.rs` (message entry point, `reply`, `log_key`, the group-only `GROUP_LINK_HINT` for a supported link posted outside a private chat), `commands.rs` (teloxide `BotCommands` enum + command executor, incl. `/test <url>` (send-only) / `/debug <url>` (parse-only) and the admin-only `/bot_dict` state dump; `/set_format` rejects unknown `{…}` placeholders and resets with `-`), `urls.rs` (URL extraction + bounded job channel (256) drained by `URL_WORKERS = 8` workers (`start_url_workers`) — backpressure instead of unbounded spawns; teloxide's per-chat workers are sequential — batch-forwards need concurrency; one *shared* in-flight fetch per cache key (`fetch_shared`: a second chat, a batch forward or a retry asking for the same post meanwhile waits for the first caller's result, the entry is dropped the moment the fetch settles so nothing is ever answered from an old fetch, and a waiter whose sharer was cancelled fetches for itself); plus the startup repair `repair_lost_local_media`, whose decision (`needs_refetch`) and rewrite (`apply_refresh`) are pure and tested while the fetch itself is a live test), `inline.rs`/`callback.rs` (inline queries / edit-before-forward buttons, incl. `skip`; a forward that fails retryably is both queued *and* settles the prompt — the queued row carries the message ids itself, and a prompt left live let a second Confirm copy the same messages twice and let Skip answer "nothing was forwarded" while the row still delivered), `statics.rs` (global statics) |
+| `crates/xmedia-bot/src/state.rs` | `ChatStore`: parking_lot `Mutex<HashMap>` cache + SQLite write-through (`chat_state` table); the 300 s sweep's `prune_expired` evicts any chat with no live edit-before-forward prompt, so the cache (and the per-chat lock map) stays bounded to active prompts — durable settings reload from the DB on next use |
+| `crates/xmedia-bot/src/link_cache.rs` | `LinkCache`: SQLite-backed cache (`link_cache` table) of successfully sent posts — raw caption fields + the source media URLs + Telegram `file_id`s; repeat links re-send locally (no fetch/upload), TTL + prune; a permanent send failure *degrades* the entry instead of dropping it (the file ids go, the URLs stay, so the next request re-sends from those without a fetch), and a degraded entry that fails again is removed |
+| `crates/xmedia-bot/src/queue.rs` | `PersistentTaskQueue`: SQLite-backed queue (`tasks` table), `QUEUE_WORKERS = 4` concurrent workers (lease via `BEGIN IMMEDIATE` + `locked_until` TTL), retry→dead-letter, a `lease_token` fence: `lease_next` stamps a random token and every write-back (heartbeat, `delete`, `reschedule`, `mark_done`) is guarded by it, so a lease that expired and was re-leased cannot be written by its former holder — a lost lease stops the attempt instead; a finished row's `DELETE`/reschedule retried and a failed delete falling back to a `done` tombstone (the lease query and the sweep only look at `pending`/`in_progress`, so a task that already ran cannot be resurrected and re-run), `runnable_rows`/`replace_payload` (the startup repair's read/rewrite path: it runs before the workers exist, which is why it needs no lease token), `notify_one` worker wakeup plus a separate `Notify` for the 30 s lease-expiry sweep (a shared one let the sweep steal the workers' wakeup permit; the sweep does notify the workers after it actually recovered a row, since a recovered task is due immediately while every worker may be parked on `notify` with no pending row to sleep on), `busy_timeout` on all connections |
+| `crates/xmedia-bot/src/ctx.rs` | `AppContext`: the injected collaborators (`sender` + `ChatStore`/`PersistentTaskQueue`/`LinkCache`/`Config`), `from_statics` for production and the `CONTEXT` static the worker closures hold. `test_support::TestStores` backs handler tests with a tempdir store set, and the module also carries the fixtures those tests share — the canonical cached post (`cached_photo`), the edit-before-forward prompt (`seed_prompt` with its `PROMPT_ID`/`FORWARDED_ID`) and a scripted API error (`api_error`) — so no two test modules keep their own copies |
 | `crates/xmedia-bot/src/send/` | `send/mod.rs`: `Task`/`MediaItemPayload` payloads, `SendError`/`Classification`, `send_media_sequence`/`send_animation`/`forward_messages`; `send/input_media.rs`: payload → `InputFile`/`InputMedia` + `build_media_group` (caption on the first item only); `send/upload.rs`: the download-and-reupload fallback (`prepare_upload_item`/`send_batch_via_upload`, photo downscale handoff); `send/post_send.rs`: link-cache write, `KEEP_ALIVE` registry, `settle_task`, `post_send_actions`, `handle_task`/`dead_letter_notify` |
-| `crates/xmedia-bot/src/media_sender.rs` | `MediaSender` trait: the user-flow surface (`send_media_group`/`send_animation`/`copy_messages`/`send_message`/`answer_callback_query`/`edit_message_caption`/`delete_message`/`send_chat_action`) implemented by teloxide `Bot` (per-chat rate-limited) and by a recording `MockSender` in tests. Admin/setup APIs (`get_chat`, `set_my_commands`, …) stay on the concrete `Bot` |
-| `crates/xmedia-bot/src/rate_limit.rs` | Per-chat token bucket (`CAPACITY = 20`, ~20 msg/min refill) paced before sends reach the API so batch forwards don't trip flood control |
+| `crates/xmedia-bot/src/media_sender.rs` | `MediaSender` trait: the user-flow surface (`send_media_group`/`send_animation`/`copy_messages`/`send_message`/`answer_callback_query`/`edit_message_text`/`edit_message_caption`/`delete_message`/`send_chat_action`) implemented by teloxide `Bot` (per-chat rate-limited) and by a recording `MockSender` in tests. Admin/setup APIs (`get_chat`, `set_my_commands`, …) stay on the concrete `Bot`. `test_support` holds the scripted `MockSender` and `fake_api` (the stand-in API the real-`Bot` tests drive) |
+| `crates/xmedia-bot/src/rate_limit.rs` | Two token buckets paced before sends reach the API so batch forwards don't trip flood control: one per chat (`CAPACITY = 20`, ~20 msg/min refill) and one bot-wide (`acquire_global`, 30/s — Telegram's per-bot ceiling, invisible to any per-chat bucket and only binding when a batch fans out over many chats). `prune_idle` drops the per-chat buckets that refilled while unheld |
 
 ## Development Commands
 
@@ -66,29 +66,29 @@ Docker: `docker build -t tgxmb .` then `docker run --rm -d --name tgxmb --env-fi
 
 ## Code Conventions & Common Patterns
 
-- **Errors via `thiserror` derive** (no anyhow): the public, stringified errors — `FetchError` (`Http`/`Json`/`Pixiv`/`Site`/`NotFound`/`Blocked`/`Disabled`/`Sensitive`/`TooLarge`/`Transient`/`Io`) and `PixivError` — derive `thiserror::Error` with `#[from]` conversions; `Display`/`source()` come from the derive. The internal control-flow enums — `QueueError` (`Retryable { delay_seconds, payload }` / `Permanent`), `SendError` (Retryable/Permanent), `Classification`, `FallbackError` — carry no `Display` and are handled by direct variant matching. New errors should follow the same split: stringified/public errors derive `thiserror`, internal flow enums stay plain.
+- **Errors via `thiserror` derive** (no anyhow): the public, stringified errors — `FetchError` (`Http`/`Json`/`Pixiv`/`Site`/`NotFound`/`Blocked`/`Disabled`/`Sensitive`/`TooLarge`/`MediaPrep`/`Transient`/`Io`) and `PixivError` — derive `thiserror::Error` with `#[from]` conversions; `Display`/`source()` come from the derive. The internal control-flow enums — `QueueError` (`Retryable { delay_seconds, payload }` / `Permanent`), `SendError` (Retryable/Permanent), `Classification`, `FallbackError` — carry no `Display` and are handled by direct variant matching. New errors should follow the same split: stringified/public errors derive `thiserror`, internal flow enums stay plain.
 - **Global state via `std::sync::LazyLock` statics**, not DI: `CONFIG`, `CHAT_STORE`, `TASK_QUEUE` in `handlers/statics.rs`; shared reqwest `CLIENT` in `x-media/src/site/mod.rs`. `Bot` is passed/cloned into handlers; queue workers share the process-wide `send::BOT` (`LazyLock<Bot>`, force-initialized in `main` so a missing token fails at startup).
 - **Async**: tokio multi-thread runtime (`#[tokio::main]` default). All rusqlite I/O inside `tokio::task::spawn_blocking`. Long loops use `tokio::select!` with `tokio::sync::{watch, Notify}` stop/wake channels. No streams.
 - **Blocking sync primitives**: `parking_lot::Mutex` for hot caches, `tokio::sync::Mutex` for async-shared state (pixiv token cache), `AtomicBool` for feature gates.
 - **Site adapter convention**: each site module exports `PATTERN: LazyLock<Regex>`, `enabled() -> bool`, `fetch_from_url(url) -> Result<Fetched, FetchError>`, plus `cache_key`/`is_retryable`/`media_headers`, and a unit struct `<Name>Site` implementing `site::Site`; the central dispatcher (`site/mod.rs`) only iterates the `SITES` registry. Adding a site = new `site/<name>/{mod.rs,interface.rs,model.rs}` + one `Box::new(...)` entry in `SITES` — the bot crate never lists sites (SetFormat whitelist, cache-key site lookup and startup validation all derive from the registry). Async trait methods return `SiteFuture` (a boxed `Pin<Box<dyn Future + Send>>`) because `async fn` in traits is not dyn-compatible.
 - **Serde**: per-site `model.rs` are pure `Deserialize` DTOs mirroring API JSON; site structs in `interface.rs` have private fields, a `caption()` builder, and `impl From<SiteStruct> for Fetched`. Persisted payloads use internally-tagged enums (`#[serde(tag = "kind")]` / `type`).
 - **Naming**: module-per-concern, snake_case files, `CamelCase` types, `snake_case` fns. `//!` module docs and `///` docs on non-obvious logic (syndication token, ugoira encoding, `display_text_range`).
-- **Retries**: only `x-media::site::fetch` retries (3 attempts, `1 << attempt` backoff, HTTP errors only); `site::fetch_once` is the same code path with a single attempt, used by inline queries whose answer window is shorter than the backoff. Queue retries are explicit `QueueError::Retryable` with computed delay (`retry_delay_seconds`).
-- Logging via `log` macros (`pretty_env_logger`, level from `RUST_LOG`). Level convention: `info` = lifecycle + per-post business results (`sent`/`forwarded`/`copied`), admin/operator actions and anomalies (fallback, retry enqueue, dead-letter is `error`); `debug` = per-request detail (message/command/URL extraction, `fetching`/`fetched`, batch sends, queue processing, photo processing, inline queries). Full user-submitted URLs and message text only appear at `debug`; at `info` and above links are printed via the normalized cache key (`handlers::log_key`, e.g. `[key=twitter:123...]`) so logs stay short and do not echo user data.
+- **Retries**: only `x-media::site::fetch` retries (3 attempts, `1 << attempt` backoff, HTTP errors only); `site::fetch_once` is the same code path with a single attempt, used by inline queries whose answer window is shorter than the backoff. A status a site answers with is classified by what a *retry* can change: 404/410 are `NotFound` and 401/403 are `Blocked` (permanent, reported at once), 429/5xx are `Transient` and retried. Queue retries are explicit `QueueError::Retryable` with computed delay (`retry_delay_seconds`), scaled per attempt by `scaled_retry_delay` — which only ever scales **up**, so a delay the server asked for (Telegram `retry_after`) is never shortened. `send::classify_request_error` is the send-side counterpart: `RetryAfter` and `Network` are retryable, and so is a 5xx — teloxide sleeps 10 s on a server error and then parses the body, so by then the HTTP status is gone and the condition is recognised by shape instead (a JSON server-error description, or an `InvalidJson` whose raw body is not JSON, i.e. a proxy/error page).
+- Logging via `log` macros (`pretty_env_logger`, level from `RUST_LOG`). `main.rs` initializes the **timed** builder with a default filter of `info,hyper_util=warn,reqwest=warn` when `RUST_LOG` is unset: the plain `init` had no timestamps and fell back to `error`, so a deployment that forgot the variable logged nothing at all, and at `debug` the HTTP client's own lines outnumbered the bot's two to one. An explicit `RUST_LOG` overrides the default wholesale. Level convention: `info` = lifecycle + per-post business results (`sent`/`forwarded`/`copied`, with `chat=` and the total `ms`), admin/operator actions and anomalies (fallback, retry enqueue, dead-letter is `error`); `debug` = per-request detail (URL extraction, `fetching`/`fetched` with the fetch duration, batch sends, queue processing with the row's `chat=`/`key=` and per-attempt `ms`, photo processing, inline queries); `trace` = user data (the full URL, the message text, the inline query). At `debug` and above links are printed via the normalized cache key (`handlers::log_key`, e.g. `[key=twitter:123...]`), so a `debug` log can be shared without echoing what users pasted, and degradations that leave the user served (a failed cache read/write, a failed chat action) are `warn`, not `error`. The only queue/sweep aggregate is the 300 s sweep's queue line, and it speaks only when the queue is non-empty.
 
 ## Important Files
 
 | File | Why it matters |
 |---|---|
 | `crates/xmedia-bot/src/main.rs` | Startup sequence, webhook vs polling, graceful shutdown (SIGINT via teloxide ctrlc / SIGTERM via `stop_token` for docker, → sweep stop → admin msg → queue stop) |
-| `crates/xmedia-bot/src/handlers/` | `statics.rs` = `CHAT_STORE`/`TASK_QUEUE`/`CONFIG` singletons (open `$DATA_DIR/task_queue.db`, default `data/` **relative to CWD**, dir auto-created); `commands.rs` = command dispatch (incl. `/test <url>` send-only, `/debug <url>` parse-only, the read-only `/settings` every chat member can read — unlike the admin-only `/bot_dict` raw dump — and template removal; `/start`/`/help` carry the guidance teloxide's `descriptions()` cannot render, and `/set_format` rejects unknown `{…}` placeholders, resetting with `-`); `urls.rs` = URL extraction + the per-URL pipeline (`url_media` takes a `PostSend` mode: chat settings vs `/test`'s suppressed actions); `inline.rs` = debounced inline queries (hotlink-protected and local media skipped); `callback.rs` = edit-before-forward buttons (dptree entry + testable `handle_callback` core, incl. `skip`) |
-| `crates/xmedia-bot/src/send/` | `mod.rs`: constants `MAX_MEDIA_GROUP = 10`; `classify_request_error`; the senders. `upload.rs`: download-and-reupload fallback triggered only by Telegram API errors (`is_media_fetch_failure` / `is_size_error`). `post_send.rs`: settlement (`settle_task`), cache write, post-send actions (dead-letter text via `failure_text`: post key + cause, since the raw error alone does not say which link died), queue handlers. `input_media.rs`: payload → `InputMedia` |
-| `crates/xmedia-bot/src/photo.rs` | Pure-Rust photo processing (no ffmpeg): `png` (image-png) decode/encode + `zune-jpeg` decode + `fast_image_resize` Lanczos3 downscale + `jpeg-encoder`. Photos over Telegram's limits (width + height > 10000 px → `PHOTO_INVALID_DIMENSIONS`; bytes > 10 MiB) are decoded, downscaled keeping the format, PNG bit depth > 24 (RGBA 32-bit / 16-bit per channel) reduced to 24-bit RGB with alpha flattened white (≤24-bit untouched, never upconverted), and transcoded to JPEG only if still over the cap; memory budget guarded, otherwise the item's smaller fallback URL |
+| `crates/xmedia-bot/src/handlers/` | `statics.rs` = `CHAT_STORE`/`TASK_QUEUE`/`CONFIG` singletons (open `$DATA_DIR/task_queue.db`, default `data/` **relative to CWD**, dir auto-created); `mod.rs` also holds `apply_caption_edit`, the one place a caption edit is applied and its failure classified: a short retryable delay is retried once, anything else is reported to the user instead of being swallowed (`callback.rs`'s template button answers its toast with the failure and leaves the record alone); `commands.rs` = command dispatch (incl. `/test <url>` send-only, `/debug <url>` parse-only, the read-only `/settings` every chat member can read — unlike the admin-only `/bot_dict` raw dump — and template removal; `/start`/`/help` carry the guidance teloxide's `descriptions()` cannot render, and `/set_format` rejects unknown `{…}` placeholders, resetting with `-`); `urls.rs` = URL extraction + the per-URL pipeline (`url_media` takes a `PostSend` mode: chat settings vs `/test`'s suppressed actions); `inline.rs` = debounced inline queries (hotlink-protected and local media skipped); `callback.rs` = edit-before-forward buttons (dptree entry + testable `handle_callback` core, incl. `skip`) |
+| `crates/xmedia-bot/src/send/` | `mod.rs`: constants `MAX_MEDIA_GROUP = 10`; `classify_request_error` (5xx/non-JSON bodies retry, see the Retries bullet) and the media-fetch markers that route a URL send into the reupload fallback — including `failed to get HTTP url content`, the description single-media URL sends answer with; the senders. `upload.rs`: download-and-reupload fallback triggered only by Telegram API errors (`is_media_fetch_failure` / `is_size_error`), with a download's class from `classify_download_error` (transport/429/5xx retry; 4xx is permanent — the media itself is gone or refused — and a temp-file *write* failure retries, being resource exhaustion far more often than a broken temp dir). Item preparation is bounded **process-wide** (`PREP_SLOTS` in `upload.rs`: URL workers and queue workers can each be inside a batch, so a per-batch bound is not a memory bound), and the check that routes an oversized item to `fallback_url` is the download's own declared-Content-Length abort (`FetchError::TooLarge` → `MediaTooLarge`) — there is no separate size probe, which used to cost a second request per item. `post_send.rs`: settlement (`settle_task`), cache write, post-send actions (dead-letter text via `failure_text`: post key + cause, since the raw error alone does not say which link died), queue handlers. `input_media.rs`: payload → `InputMedia` |
+| `crates/xmedia-bot/src/photo.rs` | Pure-Rust photo processing (no ffmpeg): `png` (image-png) decode/encode + `zune-jpeg` decode + `fast_image_resize` Lanczos3 downscale + `jpeg-encoder`. Photos over Telegram's limits (width + height > 10000 px → `PHOTO_INVALID_DIMENSIONS`; bytes > 10 MiB) are decoded, downscaled keeping the format, PNG bit depth > 24 (RGBA 32-bit / 16-bit per channel) reduced to 24-bit RGB with alpha flattened white (≤24-bit untouched, never upconverted), and transcoded to JPEG only if still over the cap; memory budget guarded, otherwise the item's smaller fallback URL. Two budgets, not one: `MAX_PHOTO_DOWNLOAD_BYTES` (32 MiB) caps the *download* in the send fallback — the whole body is buffered, once per prep slot — while `MAX_DECODE_BYTES` (512 MiB) stays the pre-allocation guard that decides whether a decoded photo can be processed at all; over either one the item degrades to its smaller URL |
 | `crates/x-media/src/site/mod.rs` | Dispatcher, `Fetched`/`FetchError`, shared `CLIENT`, `download_media` (adds `Referer: https://www.pixiv.net/` for `pximg.net` hotlink protection), `needs_media_headers` (the same per-site rule, asked by the inline path to skip what Telegram cannot fetch) |
 | `crates/x-media/src/site/pixiv/api.rs` | OAuth token exchange (hardcoded app client id/secret), access-token cache, ugoira zip→MP4 via ffmpeg in `spawn_blocking` |
 | `Dockerfile` | Multi-stage: cached dep layer via stub sources + `touch *.rs` mtime bump (cargo's freshness is mtime-based and `cargo clean -p` removes 0 files — the touch is what forces the real sources to rebuild while deps stay cached), static ffmpeg from ffmpeg.martin-riedl.de (`FFMPEG_URL` arg, optional `FFMPEG_SHA256` checksum, `unzip -t` integrity check), `debian:bookworm-slim` runtime, entrypoint. Runtime ships **no libssl/libcrypto/CA bundle** — rustls webpki-roots handles all TLS, and the static ffmpeg only processes local files (downloads go through reqwest) |
 | `docker-entrypoint.sh` | Privilege drop: `useradd` with `LOCAL_USER_ID` (default 9001) + `setpriv` (no gosu on bookworm-slim) |
-| `docker-compose.yml.example` | Deployment env reference (real `docker-compose.yml` is gitignored). Ships nginx-proxy + acme-companion: webhook mode needs TLS termination in front (teloxide's axum listener is HTTP-only; `WEBHOOK_CERT` only feeds `set_webhook`), bot exposes `VIRTUAL_HOST`/`VIRTUAL_PORT` on the shared `proxy` network, no host port; container names `nginx-proxy`/`acme-companion`/`tgxmb`, start order via `depends_on` (proxy → acme → bot) |
+| `docker-compose.yml` | The deployment composition, committed as-is: every instance value (token, admins, site credentials, domain) is a `${VAR}` substitution read from the gitignored `.env` beside it, so the file needs no per-deployment edit — and a variable not listed in a service's `environment:` never reaches that container. Ships nginx-proxy + acme-companion: webhook mode needs TLS termination in front (teloxide's axum listener is HTTP-only; `WEBHOOK_CERT` only feeds `set_webhook`), bot exposes `VIRTUAL_HOST`/`VIRTUAL_PORT` on the shared `proxy` network, no host port; container names `nginx-proxy`/`acme-companion`/`tgxmb`, start order via `depends_on` (proxy → acme → bot) |
 | `.github/workflows/docker.yml` | CI: build+push to Docker Hub on tag `v*`/master, plus a build-only check on PRs touching the build inputs; **no test step**; verifies a release tag matches both crate versions; buildx gha cache (`cache-from` always, `cache-to` except on PRs, scope `tgxmb-build`, `mode=max`) so cargo deps + ffmpeg layers are restored across runs; `FFMPEG_URL`/`FFMPEG_SHA256` come from repo variables when set |
 | `README.md` | Feature docs + command table (Chinese) |
 
@@ -96,19 +96,19 @@ Docker: `docker build -t tgxmb .` then `docker run --rm -d --name tgxmb --env-fi
 
 - **Rust, stable, edition 2024**, workspace resolver 3. No `rust-version`/MSRV pin, no `rust-toolchain.toml` — recent stable is assumed. No nightly features.
 - Package manager: **Cargo** (workspace with path dep `x-media` ← `xmedia-bot`). No `[workspace.package]`/shared deps — each crate lists deps independently.
-- **TLS is rustls end-to-end** (no native-tls/openssl in the tree, no libssl in the Docker runtime image): `teloxide` is declared `default-features = false` with `["webhooks-axum", "macros", "rustls", "ctrlc_handler"]` (the removed `default` also carried `native-tls` and `ctrlc_handler` — the latter must stay); x-media's reqwest is `default-features = false` with `["json", "rustls-tls"]` (webpki-roots baked in, so the image ships no CA bundle). One reqwest 0.12.28 in the lock.
+- **TLS is rustls end-to-end** (no native-tls/openssl in the tree, no libssl in the Docker runtime image): `teloxide` is declared `default-features = false` with `["webhooks-axum", "macros", "rustls", "ctrlc_handler"]` (the removed `default` also carried `native-tls` and `ctrlc_handler` — the latter must stay); x-media's reqwest is `default-features = false` with `["json", "rustls-tls", "gzip", "http2"]` (webpki-roots baked in, so the image ships no CA bundle; `gzip` because the site APIs answer their JSON compressed — twitter's syndication body is 4469 bytes identity vs 1066 gzipped — and `http2` because every site CDN here negotiates h2). One reqwest 0.12.28 in the lock.
 - **Versioning**: bump the version in all three places (`crates/x-media/Cargo.toml`, `crates/xmedia-bot/Cargo.toml`, `Cargo.lock`) and **keep `README.md`, `README.en.md` and `AGENTS.md` in sync with the code on every bump**, then commit (`chore: bump version to X.Y.Z`), create an annotated tag `vX.Y.Z`, and push branch + tag (the tag push triggers the Docker Hub build). The tag must equal both crate versions: `.github/workflows/docker.yml` verifies that before building, and `--locked` verifies the lock file.
-- Config is **environment-variable driven** (dotenv loads `.env`, gitignored; no `.env.example` exists). Key vars: `TELOXIDE_TOKEN` (required), `PIXIV_REFRESH_TOKEN`, `TWITTER_AUTH_TOKEN` (optional; x.com `auth_token` cookie — enables the logged-in GraphQL fallback that fetches NSFW tweets syndication withholds), `BILIBILI_COOKIE` (optional; whole bilibili cookie string — bilibili dynamics fetch anonymously and add their own device cookies, this only rescues an egress IP that bilibili has hard-flagged with `-352`/412), `BOT_ADMIN` (comma-separated ids), `EDIT_MESSAGE_TTL_SECONDS` (default 86400), `LINK_CACHE_TTL_SECONDS` (default 604800), `CAPTION_QUOTE_TEXT_CHARS` (default 200; a post whose text — the `title` plus `content` joined, see `site::compose_text` — reaches this length gets that text wrapped in an expandable blockquote inside its caption, the URL and author line staying outside; `0` disables it. Applied at the send boundary in `send::quote_long_caption`, which locates the text as what follows the author link, so a `/set_format` that moves `{title}`/`{content}` elsewhere and pixiv's title-inside-a-link layout opt out; `copy_messages` forwards and queued retries inherit the wrap, while the edit-before-forward rewrite stays unquoted by design), `DATA_DIR` (default `data`, CWD-relative; the SQLite dir, auto-created), `WEBHOOK`/`WEBHOOK_URL`/`WEBHOOK_LISTEN`/`WEBHOOK_PORT`/`WEBHOOK_CERT`/`WEBHOOK_SECRET_TOKEN` (webhook mode requires URL/listen/port, `.expect`ed; `WEBHOOK_CERT` is Telegram-facing self-signed validation only — TLS must be terminated by a reverse proxy), `RUST_LOG`, `TELOXIDE_PROXY`, `LOCAL_USER_ID` (entrypoint only).
+- Config is **environment-variable driven** (dotenv loads `.env`, which is gitignored; `.env.example` is the tracked template — `cp .env.example .env` — and is also the file `docker compose` substitutes `${VAR}` from, so every variable the compose passes must be documented there). Key vars: `TELOXIDE_TOKEN` (required), `PIXIV_REFRESH_TOKEN`, `TWITTER_AUTH_TOKEN` (optional; x.com `auth_token` cookie — enables the logged-in GraphQL fallback that fetches NSFW tweets syndication withholds), `BILIBILI_COOKIE` (optional; whole bilibili cookie string — bilibili dynamics fetch anonymously and add their own device cookies, this only rescues an egress IP that bilibili has hard-flagged with `-352`/412), `BOT_ADMIN` (comma-separated ids), `EDIT_MESSAGE_TTL_SECONDS` (default 86400), `LINK_CACHE_TTL_SECONDS` (default 604800), `CAPTION_QUOTE_TEXT_CHARS` (default 200; a post whose text — the `title` plus `content` joined, see `site::compose_text` — reaches this length gets that text wrapped in an expandable blockquote inside its caption, the URL and author line staying outside; `0` disables it. Applied at the send boundary in `send::quote_long_caption`, which locates the text as what follows the author link, so a `/set_format` that moves `{title}`/`{content}` elsewhere and pixiv's title-inside-a-link layout opt out; `copy_messages` forwards and queued retries inherit the wrap, while the edit-before-forward rewrite stays unquoted by design), `DATA_DIR` (default `data`, CWD-relative; the SQLite dir, auto-created), `WEBHOOK`/`WEBHOOK_URL`/`WEBHOOK_LISTEN`/`WEBHOOK_PORT`/`WEBHOOK_CERT`/`WEBHOOK_SECRET_TOKEN` (webhook mode requires URL/listen/port, `.expect`ed; `WEBHOOK_CERT` is Telegram-facing self-signed validation only — TLS must be terminated by a reverse proxy), `RUST_LOG`, `TELOXIDE_PROXY`, `LOCAL_USER_ID` (entrypoint only).
 - SQLite via `rusqlite` with `bundled` feature (no system libsqlite needed). DB file `$DATA_DIR/task_queue.db` (default `data/task_queue.db`, CWD-relative — run from the workspace root, or `/app` in Docker; set `DATA_DIR` to pin state anywhere). Mount `./data` and `./cert` volumes.
-- `.gitattributes` enforces LF for `*.sh` (CRLF breaks shebangs in containers). `.gitignore`: `.env`, `data/`, `cert/`, `docker-compose.yml`, `/target`, `.idea/`.
+- `.gitattributes` enforces LF for `*.sh` (CRLF breaks shebangs in containers). `.gitignore`: `.env`, `data/`, `cert/`, `nginx-*` (proxy state), `/target`, `.idea/` (the compose file is tracked; only `.env` carries the deployment's own values).
 - Docs are in Chinese (README, AGENTS.md); user-facing bot strings are in English. Keep that split when editing user-facing strings and docs.
 
 ## Testing & QA
 
-- **~200 tests, all inline `#[cfg(test)] mod tests`** — no `tests/` integration directories. Framework: built-in Rust test + `#[tokio::test]` (dev-deps only in `x-media`: tokio macros/rt-multi-thread, dotenv).
-- No mocking framework anywhere (no mockito/wiremock/mockall). Conventions: pure-function units (regex parsing, serde round-trips, chunking, retry math) tested synchronously; async tests use real dependencies — file-backed SQLite via `tempfile` (`queue.rs::new_queue()` helper), live network fetches.
-- Live-network tests exist in `site/twitter/interface.rs` (5), `site/bsky/interface.rs` (2), `site/misskey/interface.rs` (1), `site/bilibili/interface.rs` (4), `site/pixiv/api.rs` (1); `photo.rs` adds one `#[ignore = "heavy: …"]` test. `site/mod.rs` also has a **token-gated but not `#[ignore]`d** pixiv download test (`download_media_pixiv_original_with_referer`): it hits `i.pximg.net` whenever `PIXIV_REFRESH_TOKEN` is set, so a local `cargo test --workspace` is not fully offline and can flake on a pixiv CDN body timeout. `disabled_site_is_reported_not_ignored` (same file) is gated the other way round: it asserts `fetch` answers `FetchError::Disabled { site: "pixiv" }` for a pixiv link and early-returns when `PIXIV_REFRESH_TOKEN` **is** set (the site is then enabled). Test gating convention (enforced by `.github/workflows/ci.yml`): pure unit tests always run; live-network tests carry `#[ignore = "live network: ..."]` (run via `cargo test --workspace -- --ignored live`); token-gated pixiv tests early-return when `PIXIV_REFRESH_TOKEN` is absent **or empty** (an unset GitHub secret arrives as `""` — `is_err()` alone would run them tokenless and fail), and the bilibili live tests early-return when the API answers risk control (`-352`, which bilibili applies per IP by request volume). Run the full offline suite with `cargo test --workspace`.
+- **~180 tests, all inline `#[cfg(test)] mod tests`** — no `tests/` integration directories. Framework: built-in Rust test + `#[tokio::test]` (dev-deps only in `x-media`: tokio macros/rt-multi-thread, dotenv).
+- No mocking framework anywhere (no mockito/wiremock/mockall). Conventions: pure-function units (regex parsing, serde round-trips, chunking, retry math) tested synchronously; async tests use real dependencies — file-backed SQLite via `tempfile` (`queue.rs::new_queue()` helper), live network fetches. Tests that must go through a **real `Bot`** (its URL/multipart building, the per-chat limiter and the bot-wide budget) talk to a stand-in API instead (`media_sender::test_support::fake_api::FakeApi`, a `tokio` TCP listener that records every call and answers the smallest result each method needs — teloxide keys methods by payload type, so the recorded name is `SendMediaGroup`, not `sendMediaGroup`): a media group, the edit-before-forward prompt through the real callback path, and `handlers::handle_message` (the context-taking body of `message_handler`, split out for exactly this).
+- Live-network tests exist in `site/twitter/interface.rs` (5), `site/bsky/interface.rs` (1), `site/misskey/interface.rs` (1), `site/bilibili/interface.rs` (5), `site/pixiv/api.rs` (1); `photo.rs` adds one `#[ignore = "heavy: …"]` test. `site/mod.rs` also has a **token-gated but not `#[ignore]`d** pixiv download test (`download_media_pixiv_original_with_referer`): it hits `i.pximg.net` whenever `PIXIV_REFRESH_TOKEN` is set, so a local `cargo test --workspace` is not fully offline and can flake on a pixiv CDN body timeout. `disabled_site_is_reported_not_ignored` (same file) is gated the other way round: it asserts `fetch` answers `FetchError::Disabled { site: "pixiv" }` for a pixiv link and early-returns when `PIXIV_REFRESH_TOKEN` **is** set (the site is then enabled). Test gating convention (enforced by `.github/workflows/ci.yml`): pure unit tests always run; live-network tests carry `#[ignore = "live network: ..."]` (run via `cargo test --workspace -- --ignored live`); token-gated pixiv tests early-return when `PIXIV_REFRESH_TOKEN` is absent **or empty** (an unset GitHub secret arrives as `""` — `is_err()` alone would run them tokenless and fail), and the bilibili live tests early-return when the API answers risk control (`-352`, which bilibili applies per IP by request volume). Run the full offline suite with `cargo test --workspace`.
 - Fixtures are inline `serde_json::json!` builder fns (`fixture()`, `thread_json()`, `illust_json()`), not files. The shared `CLIENT` sets `pool_max_idle_per_host(0)` under `#[cfg(test)]` to avoid cross-runtime `DispatchGone`.
 - **CI** — `.github/workflows/ci.yml` (actions pinned to commit SHAs, `--locked` on every cargo invocation, `concurrency` cancels superseded runs, `RUST_BACKTRACE=1`) runs `cargo fmt --check` + `cargo clippy --workspace --all-targets --locked -- -D warnings` + `cargo test --workspace --locked` + a release-profile `cargo build --release --locked` + an `actions-rust-lang/audit` dependency-vulnerability gate (offline, no secrets, on every push/PR) and a `live` job (schedule/manual/tag only, `-p x-media` since every network/secret-gated test lives there, `continue-on-error`) for the `#[ignore]`d live + token tests. `.github/workflows/docker.yml` builds and pushes the image on master/tag and runs a **build-only check on pull requests touching the build inputs** (`Dockerfile`, entrypoint, manifests, `.dockerignore`); a release tag must match both crate versions or the build stops, and `FFMPEG_URL`/`FFMPEG_SHA256` are taken from repository variables when set (a release can pin an exact ffmpeg build). `.github/dependabot.yml` keeps crates, the pinned actions and the Docker base images current.
-- Untested and hard to test without a mock seam: `main.rs`, `config.rs`, `db.rs`, `handlers/statics.rs`, `media_sender.rs` (holds the `MockSender` itself); in `x-media`: `media.rs`, `lib.rs`, all `model.rs`. The `commands.rs` *executor* needs a real `Bot` (only its pure report builder is tested). Everything else — `handlers/{mod,callback,inline,urls}.rs`, `send/*`, `ctx.rs`, `state.rs`, `queue.rs`, `link_cache.rs`, `rate_limit.rs` — is driven through `TestStores`/`ctx::test_support` and the scripted `MockSender`.
+- Untested and hard to test without a mock seam: `config.rs`, `handlers/statics.rs`; `db.rs` is covered for the migration chain but not for pool behaviour under contention; `main.rs` is covered where it was split out (`periodic_sweep`, `sweep_temp_dir`) but not for startup/shutdown or its `dptree` branch tree (the handlers themselves are, through the stand-in API); in `x-media`: `media.rs`, `lib.rs`, all `model.rs`. The `commands.rs` *executor* needs a real `Bot` (only its pure report builder is tested). Everything else — `handlers/{mod,callback,inline,urls}.rs`, `send/*`, `ctx.rs`, `state.rs`, `queue.rs`, `link_cache.rs`, `rate_limit.rs` — is driven through `TestStores`/`ctx::test_support` and the scripted `MockSender`.
 - No coverage tracking.

Cargo.lock

@@ -60,6 +60,18 @@ dependencies = [
  "object",
 ]
 
+[[package]]
+name = "async-compression"
+version = "0.4.43"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3976abdc8fe7d1133d43d304afd42abdf5bc3e1319d263d223bde07b5efc4be8"
+dependencies = [
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
+]
+
 [[package]]
 name = "atomic-waker"
 version = "1.1.2"
@@ -266,6 +278,23 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "compression-codecs"
+version = "0.4.38"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ce2548391e9c1929c21bf6aa2680af86fe4c1b33e6cea9ac1cfeec0bd11218cf"
+dependencies = [
+ "compression-core",
+ "flate2",
+ "memchr",
+]
+
+[[package]]
+name = "compression-core"
+version = "0.4.32"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "cc14f565cf027a105f7a44ccf9e5b424348421a1d8952a8fc9d499d313107789"
+
 [[package]]
 name = "const-oid"
 version = "0.10.2"
@@ -583,6 +612,12 @@ dependencies = [
  "zlib-rs",
 ]
 
+[[package]]
+name = "fnv"
+version = "1.0.7"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
+
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -713,6 +748,25 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "h2"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "6cb093c84e8bd9b188d4c4a8cb6579fc016968d14c99882163cd3ff402a4f155"
+dependencies = [
+ "atomic-waker",
+ "bytes",
+ "fnv",
+ "futures-core",
+ "futures-sink",
+ "http",
+ "indexmap 2.14.2",
+ "slab",
+ "tokio",
+ "tokio-util",
+ "tracing",
+]
+
 [[package]]
 name = "hashbrown"
 version = "0.12.3"
@@ -849,6 +903,7 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-core",
+ "h2",
  "http",
  "http-body",
  "httparse",
@@ -1740,6 +1795,7 @@ dependencies = [
  "bytes",
  "futures-core",
  "futures-util",
+ "h2",
  "http",
  "http-body",
  "http-body-util",
@@ -2425,12 +2481,17 @@ version = "0.6.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4cfcf7e2740e6fc6d4d688b4ef00650406bb94adf4731e43c096c3a19fe40840"
 dependencies = [
+ "async-compression",
  "bitflags 2.13.2",
  "bytes",
+ "futures-core",
  "futures-util",
  "http",
  "http-body",
+ "http-body-util",
  "pin-project-lite",
+ "tokio",
+ "tokio-util",
  "tower",
  "tower-layer",
  "tower-service",
@@ -2818,7 +2879,7 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
 [[package]]
 name = "x-media"
-version = "1.8.0"
+version = "1.9.0"
 dependencies = [
  "bytes",
  "dotenv",
@@ -2838,7 +2899,7 @@ dependencies = [
 
 [[package]]
 name = "xmedia-bot"
-version = "1.8.0"
+version = "1.9.0"
 dependencies = [
  "bytes",
  "dotenv",

README.en.md

@@ -7,7 +7,7 @@ A Telegram bot that turns post links from X / Twitter, Pixiv, Bluesky, Misskey (
 - Sending a link in a private chat fetches and sends the images, videos and GIFs automatically; oversized media is split into batches (10 items per group)
 - Text-only posts report "no media"; unsupported links are silently ignored. Fetch failures name the reason (post gone / content withheld / source risk control / site not enabled)
 - Long posts (text ≥ `CAPTION_QUOTE_TEXT_CHARS`, default 200) show **the text part** of their caption inside a collapsible blockquote, with the link and author line left outside it
-- Inline queries (`@bot <link>`) — except Pixiv images and locally transcoded animations, which Telegram cannot fetch (no Referer) and would show broken, so they are skipped; a supported link posted in a group gets a one-line hint to use the private chat or inline mode (channels stay silent)
+- Inline queries (`@bot <link>`) — except Pixiv images and locally transcoded animations, which Telegram cannot fetch (no Referer) and would show broken, so they are skipped (such a query answers empty rather than spinning or re-fetching); a supported link posted in a group gets a one-line hint to use the private chat or inline mode (channels stay silent)
 - `/start` explains the supported sites and how to use it; `/help` lists the commands plus argument syntax, the caption placeholders and the private-chat rule; the bot's profile description texts are set at startup
 - `/settings` shows this chat's configuration (forward channel, edit-before-forward, per-site caption formats, saved templates); templates are added with `/set_template` and removed with `/remove_template`
 - Bind a forward channel for automatic forwarding; edit the caption before forwarding and apply custom templates (the prompt carries Confirm / Skip buttons, states its expiry, and is marked expired in place once it lapses)
@@ -27,11 +27,14 @@ export PIXIV_REFRESH_TOKEN=<token>
 cargo run -p xmedia-bot
 ```
 
-Docker deployment (see `docker-compose.yml.example`):
+Docker deployment (`docker-compose.yml` in this repo is the orchestration; instance values live in the `.env` next to it, and compose substitutes every `${VAR}` from there):
 
 ```bash
+cp .env.example .env   # fill in TELOXIDE_TOKEN and the rest; every line is commented
 docker build -t tgxmb .
 docker run --rm -d --name tgxmb --env-file .env -v ./data:/app/data tgxmb
+# or use the bundled orchestration (nginx-proxy + acme-companion):
+docker compose up -d
 ```
 
 Environment variables: `TELOXIDE_TOKEN` (required), `PIXIV_REFRESH_TOKEN`, `BOT_ADMIN`, `EDIT_MESSAGE_TTL_SECONDS`, `LINK_CACHE_TTL_SECONDS`, `RUST_LOG`, `TELOXIDE_PROXY`, `WEBHOOK*`, `TWITTER_AUTH_TOKEN` (optional), `BILIBILI_COOKIE` (optional).
@@ -42,11 +45,11 @@ Bilibili dynamics are fetched anonymously by default (no login; the bot fetches
 
 ### Webhook deployment (needs a reverse proxy)
 
-`docker-compose.yml.example` ships an [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) + [acme-companion](https://github.com/nginx-proxy/acme-companion) reverse-proxy orchestration. Pick one deployment shape:
+`docker-compose.yml` ships an [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) + [acme-companion](https://github.com/nginx-proxy/acme-companion) reverse-proxy orchestration. The committed file needs **no editing**: domain, tokens and admins are instance values and live in the `.env` beside it (compose reads and substitutes `${VAR}` at startup). Pick one deployment shape:
 
 **With a domain**
 1. Point a DNS A record at the server
-2. In compose set `VIRTUAL_HOST` and `WEBHOOK_URL` to the domain, and uncomment `ACME_HOST` (set it to the domain)
+2. In `.env` set `VIRTUAL_HOST` and `WEBHOOK_URL` to the domain; to have acme-companion issue the certificate, also uncomment the `ACME_HOST` line in `docker-compose.yml` and set `ACME_HOST` in `.env`
 3. acme-companion issues and renews certificates automatically — nothing manual
 
 **IP only**
@@ -74,7 +77,7 @@ Let's Encrypt can issue certificates for public IPs (available since 2026, valid
      --key-file /acme.sh/<SERVER_IP>.key \
      --reloadcmd "curl --unix-socket /var/run/docker.sock -X POST http://localhost/containers/nginx-proxy/kill?signal=HUP"
    ```
-3. In compose set `VIRTUAL_HOST: '<SERVER_IP>'` and `WEBHOOK_URL: 'https://<SERVER_IP>/'`; no `WEBHOOK_CERT` needed. Renewal is handled by the acme.sh daemon (`--days 3` = renew every 3 days, buffer against the 7-day validity), and a successful renewal HUP-notifies nginx-proxy to load the new certificate.
+3. In `.env` set `VIRTUAL_HOST=<SERVER_IP>` and `WEBHOOK_URL=https://<SERVER_IP>/`; no `WEBHOOK_CERT` needed. Renewal is handled by the acme.sh daemon (`--days 3` = renew every 3 days, buffer against the 7-day validity), and a successful renewal HUP-notifies nginx-proxy to load the new certificate.
 
    Limitations: certificate validity ~7 days; only http-01/tls-alpn-01 validation (port 80 must be publicly reachable); no DNS-01, private IPs or IP ranges; at most 5 certificates per 168 hours for the same IP set. It is recommended to trial-issue with `--server letsencrypt_test` first, then switch to the production server.
 
@@ -87,16 +90,17 @@ Telegram only accepts ports 443/80/88/8443.
 |---|---|
 | `TELOXIDE_TOKEN` | Bot token (required) |
 | `PIXIV_REFRESH_TOKEN` | Pixiv refresh token; Pixiv is disabled without it (a pixiv link then gets an explicit "site not enabled" reply instead of silence) |
+| `TWITTER_AUTH_TOKEN` | Optional; the `auth_token` cookie of a logged-in x.com session, used only to fetch NSFW tweets' media |
 | `BILIBILI_COOKIE` | Optional bilibili cookie string (`SESSDATA=…; bili_jct=…`); only needed when the egress IP stays risk-controlled (device cookies are fetched automatically) |
 | `BOT_ADMIN` | Admin chat IDs, comma-separated; receives start/stop notifications |
 | `EDIT_MESSAGE_TTL_SECONDS` | Edit-before-forward record expiry in seconds, default 86400; once lapsed the prompt is rewritten in place to "expired — nothing was forwarded" (no extra message) |
 | `LINK_CACHE_TTL_SECONDS` | Link-result cache expiry in seconds, default 604800 (7 days) |
 | `CAPTION_QUOTE_TEXT_CHARS` | **The text part** of the caption (the joined `{title}` + `{content}`) is wrapped in a collapsible blockquote once it reaches this many characters, default 200; `0` disables |
 | `DATA_DIR` | Data directory (where the SQLite `task_queue.db` lives), default `data` (relative to the working directory, created automatically) |
-| `RUST_LOG` | Log level |
-| `TELOXIDE_PROXY` | HTTP proxy (e.g. `http://127.0.0.1:10808`); applies to both the Telegram Bot API and site fetches — required on restricted networks (e.g. behind the GFW) |
+| `RUST_LOG` | Log level, default `info,hyper_util=warn,reqwest=warn` (an unset variable no longer silences the log). Recipes: `info,xmedia_bot=debug,x_media=debug` (app detail, no dependency noise) / `debug,hyper_util=off` (everything) / `trace` (also prints full links and message text — **user data**) |
+| `TELOXIDE_PROXY` | HTTP proxy (e.g. `http://127.0.0.1:10808`); applies to both the Telegram Bot API and site fetches — required on restricted networks (e.g. behind the GFW). **Never leave it blank** (`TELOXIDE_PROXY=`) — teloxide panics on a value it cannot parse; omit the line when unused. `docker-compose.yml` deliberately does not pass it to the container (a `127.0.0.1` proxy there is the container itself): add the line and use `host.docker.internal:<port>` when a deployment needs one |
 | `LOCAL_USER_ID` | UID the container runs as, default 9001 |
-| `VIRTUAL_HOST` | Public domain or IP; nginx-proxy routes by this |
+| `VIRTUAL_HOST` | Public domain or IP; nginx-proxy routes by this (set it in `.env`, which compose reads) |
 | `VIRTUAL_PORT` | Port the bot listens on inside the container; nginx-proxy's forwarding target |
 | `ACME_HOST` | Domain deployment: when set to the domain, acme-companion issues/renews certificates automatically |
 | `DEFAULT_HOST` | nginx-proxy routes requests with unknown Host headers to this vhost (needed for IP access) |

README.md

@@ -7,7 +7,7 @@ Telegram 机器人，将 X / Twitter、Pixiv、Bluesky、Misskey (misskey.io)、
 - 私聊发送链接后自动抓取并发送图片、视频与 GIF，超量图片自动分批（每批 10 张）
 - 纯文字帖提示无媒体；不支持的链接静默忽略。抓取失败会按原因分别提示（帖子已删除 / 内容受限 / 源站风控 / 站点未启用）
 - 长帖（正文 ≥ `CAPTION_QUOTE_TEXT_CHARS`，默认 200）的**正文部分**用可折叠引用块展示，链接与作者行留在引用块外
-- 支持内联查询（`@机器人 <链接>`；Pixiv 图片与本地转码的动图不支持内联 —— Telegram 取图时无法携带 Referer，会显示破图，因此跳过）；在群聊里发链接会提示改用私聊或内联查询（频道内保持静默）
+- 支持内联查询（`@机器人 <链接>`；Pixiv 图片与本地转码的动图不支持内联 —— Telegram 取图时无法携带 Referer，会显示破图，因此跳过；这类查询直接返回空结果，不会一直转圈或反复请求）；在群聊里发链接会提示改用私聊或内联查询（频道内保持静默）
 - `/start` 说明支持的站点与用法，`/help` 列出命令、参数格式、caption 占位符与私聊限制；bot 资料页（description / short description）启动时一并设置
 - `/settings` 查看本聊天配置（转发频道、转发前编辑开关、各站点 caption 格式、模板列表）；模板可用 `/set_template` 增、`/remove_template` 删
 - 可绑定转发频道自动转发；支持转发前编辑 caption 与自定义模板（提示消息带 Confirm / Skip 按钮并写明过期时间，过期后就地标记为已过期）
@@ -27,11 +27,14 @@ export PIXIV_REFRESH_TOKEN=<token>
 cargo run -p xmedia-bot
 ```
 
-Docker 部署（参考 `docker-compose.yml.example`）：
+Docker 部署（编排见仓库里的 `docker-compose.yml`，实例相关的值写在同目录的 `.env`，compose 会自动替换其中的 `${VAR}`）：
 
 ```bash
+cp .env.example .env   # 填 TELOXIDE_TOKEN 等，逐项都有注释
 docker build -t tgxmb .
 docker run --rm -d --name tgxmb --env-file .env -v ./data:/app/data tgxmb
+# 或者用仓库里的编排（含 nginx-proxy + acme-companion）：
+docker compose up -d
 ```
 
 环境变量：`TELOXIDE_TOKEN`（必填）、`PIXIV_REFRESH_TOKEN`、`BOT_ADMIN`、`EDIT_MESSAGE_TTL_SECONDS`、`LINK_CACHE_TTL_SECONDS`、`RUST_LOG`、`TELOXIDE_PROXY`、`WEBHOOK*`、`TWITTER_AUTH_TOKEN`（可选）、`BILIBILI_COOKIE`（可选）。
@@ -42,11 +45,11 @@ Bilibili 动态默认匿名抓取（无需登录，bot 会自动从 B 站的匿
 
 ### Webhook 部署（需要反向代理）
 
-`docker-compose.yml.example` 内置了 [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) + [acme-companion](https://github.com/nginx-proxy/acme-companion) 反向代理编排，按部署环境二选一：
+`docker-compose.yml` 内置了 [nginx-proxy](https://github.com/nginx-proxy/nginx-proxy) + [acme-companion](https://github.com/nginx-proxy/acme-companion) 反向代理编排，仓库里的这份文件**不需要改动**：域名、令牌、管理员等实例相关的值都写在同目录的 `.env` 里（compose 启动时自动读取并替换 `${VAR}`）。按部署环境二选一：
 
 **有域名**
 1. DNS A 记录指向服务器
-2. compose 里设 `VIRTUAL_HOST`、`WEBHOOK_URL` 为域名，并取消注释 `ACME_HOST`（设为域名）
+2. `.env` 里设 `VIRTUAL_HOST`、`WEBHOOK_URL` 为域名；要由 acme-companion 自动签发证书时，再取消 `docker-compose.yml` 里 `ACME_HOST` 那行的注释，并在 `.env` 里把 `ACME_HOST` 设为域名
 3. acme-companion 自动签发与续期证书，无需手动处理
 
 **只有 IP**
@@ -74,7 +77,7 @@ Let's Encrypt 支持为公网 IP 签发证书（2026 年起可用，有效期约
      --key-file /acme.sh/<SERVER_IP>.key \
      --reloadcmd "curl --unix-socket /var/run/docker.sock -X POST http://localhost/containers/nginx-proxy/kill?signal=HUP"
    ```
-3. compose 里设 `VIRTUAL_HOST: '<SERVER_IP>'`、`WEBHOOK_URL: 'https://<SERVER_IP>/'`，无需 `WEBHOOK_CERT`。续期由 acme.sh daemon 自动完成（`--days 3` = 每 3 天续一次，证书 7 天有效有缓冲），续期成功后自动 HUP 通知 nginx-proxy 加载新证书。
+3. `.env` 里设 `VIRTUAL_HOST=<SERVER_IP>`、`WEBHOOK_URL=https://<SERVER_IP>/`，无需 `WEBHOOK_CERT`。续期由 acme.sh daemon 自动完成（`--days 3` = 每 3 天续一次，证书 7 天有效有缓冲），续期成功后自动 HUP 通知 nginx-proxy 加载新证书。
 
    限制：证书约 7 天有效；验证仅支持 http-01/tls-alpn-01（80 端口必须公网可达）；不支持 DNS-01、私有 IP 与 IP 段；同一 IP 集合每 168 小时限签发 5 张。建议先用 `--server letsencrypt_test` 试签，成功后再切正式服务器。
 
@@ -87,16 +90,17 @@ Telegram 只接受 443/80/88/8443 端口。
 |---|---|
 | `TELOXIDE_TOKEN` | Bot token（必填） |
 | `PIXIV_REFRESH_TOKEN` | Pixiv 刷新令牌；未设置则禁用 Pixiv（此时收到 pixiv 链接会明确回复「站点未启用」，不会静默忽略） |
+| `TWITTER_AUTH_TOKEN` | 可选；登录 x.com 后浏览器 Cookie 里的 `auth_token`，仅在遇到 NSFW 推文时以登录态获取媒体 |
 | `BILIBILI_COOKIE` | 可选的 B 站 Cookie 串（`SESSDATA=…; bili_jct=…`），仅在出口 IP 被持续风控时才需要（设备 cookie 由 bot 自动获取） |
 | `BOT_ADMIN` | 管理员聊天 ID，逗号分隔；接收启动/停止通知 |
 | `EDIT_MESSAGE_TTL_SECONDS` | 转发前编辑记录过期秒数，默认 86400；过期后提示消息会被就地改写为「已过期，未转发」（不额外发消息打扰） |
 | `LINK_CACHE_TTL_SECONDS` | 链接结果缓存过期秒数，默认 604800（7 天） |
 | `CAPTION_QUOTE_TEXT_CHARS` | 正文（`{title}` + `{content}` 合计）达到该长度（字符）时，caption 的**正文部分**用可折叠引用块包裹，默认 200；`0` 关闭 |
 | `DATA_DIR` | 数据目录（SQLite 数据库 `task_queue.db` 所在目录），默认 `data`（相对工作目录，会自动创建） |
-| `RUST_LOG` | 日志级别 |
-| `TELOXIDE_PROXY` | HTTP 代理（如 `http://127.0.0.1:10808`）；同时作用于 Telegram Bot API 与站点抓取请求，网络受限环境（如 GFW）必需 |
+| `RUST_LOG` | 日志级别，默认 `info,hyper_util=warn,reqwest=warn`（未设置也**不会**哑掉）。排障配方：`info,xmedia_bot=debug,x_media=debug`（应用细节，无依赖噪音）/ `debug,hyper_util=off`（全量）/ `trace`（额外打印完整链接与消息原文，**含用户数据**） |
+| `TELOXIDE_PROXY` | HTTP 代理（如 `http://127.0.0.1:10808`）；同时作用于 Telegram Bot API 与站点抓取请求，网络受限环境（如 GFW）必需。**不要留空值**（`TELOXIDE_PROXY=`）——teloxide 对无法解析的值会直接 panic；不用代理就别写这一行。容器里要用代理时，`docker-compose.yml` 的 `environment` 里默认没有它（容器内的 `127.0.0.1` 是容器自己），需要时手动加上并把地址换成 `host.docker.internal:<port>` |
 | `LOCAL_USER_ID` | 容器内运行用户 UID，默认 9001 |
-| `VIRTUAL_HOST` | 对外域名或 IP，nginx-proxy 按此路由 |
+| `VIRTUAL_HOST` | 对外域名或 IP，nginx-proxy 按此路由（写在 `.env`，compose 读取） |
 | `VIRTUAL_PORT` | bot 容器内监听端口，nginx-proxy 的转发目标 |
 | `ACME_HOST` | 域名部署：设为域名时由 acme-companion 自动签发/续期证书 |
 | `DEFAULT_HOST` | nginx-proxy 将未知 Host 的请求路由到该 vhost（IP 访问时需要） |

crates/x-media/Cargo.toml

@@ -1,10 +1,10 @@
 [package]
 name = "x-media"
-version = "1.8.0"
+version = "1.9.0"
 edition = "2024"
 
 [dependencies]
-reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls"] }
+reqwest = { version = "0.12", default-features = false, features = ["json", "rustls-tls", "gzip", "http2"] }
 serde = { version = "1", features = ["derive"] }
 serde_json = "1"
 regex = "1.12"
@@ -16,7 +16,7 @@ tempfile = "3"
 thiserror = "2"
 rand = "0.10"
 log = "0.4"
-tokio = { version = "1.40", features = ["time"] }
+tokio = { version = "1.40", features = ["time", "rt", "fs"] }
 
 [dev-dependencies]
 tokio = { version = "1.40", features = ["macros", "rt-multi-thread"] }

crates/x-media/src/lib.rs

@@ -1,2 +1,9 @@
 pub mod media;
 pub mod site;
+
+/// Prefix every temp file and temp dir this project creates, so a startup
+/// sweep can recognise its own leftovers: a killed process leaves them behind
+/// (`TempDir`/`NamedTempFile` clean up on drop, and a killed process runs no
+/// destructors), and without a marker the only safe assumption about the OS
+/// temp directory is "not mine".
+pub const TEMP_FILE_PREFIX: &str = "tgxmb-";

crates/x-media/src/site/bilibili/interface.rs

@@ -72,10 +72,14 @@ static COOKIE: LazyLock<Option<String>> = LazyLock::new(|| {
         .filter(|s| !s.is_empty())
 });
 
-/// Cached `buvid3`/`buvid4` header value from [`SPI_URL`], or `None` when the
-/// fingerprint endpoint was unavailable (requests then go out without a
-/// cookie, as before).
-static BUVID: LazyLock<tokio::sync::Mutex<Option<String>>> = LazyLock::new(Default::default);
+/// Cached `buvid3`/`buvid4` header value from [`SPI_URL`]. The outer `Option`
+/// is "an attempt has been made", the inner one "it produced a cookie": a
+/// failed attempt is remembered too, since it arrives at the request path as
+/// no cookie either way. Caching only success meant every later post asked the
+/// fingerprint endpoint again — one extra round trip per post, and on a
+/// flagged IP the endpoint is what fails.
+static BUVID: LazyLock<tokio::sync::Mutex<Option<Option<String>>>> =
+    LazyLock::new(Default::default);
 
 /// Registry entry for the bilibili adapter (see [`crate::site::Site`]).
 pub struct BilibiliSite;
@@ -154,20 +158,28 @@ async fn cookie() -> Option<String> {
     if let Some(cookie) = COOKIE.as_deref() {
         return Some(cookie.to_string());
     }
-    // ponytail: cached for the process lifetime. Refetching after a `-352`
-    // would mint a new device id for the same flagged IP — the escalation
-    // path is BILIBILI_COOKIE.
-    let mut cached = BUVID.lock().await;
-    if cached.is_none() {
-        *cached = match fetch_buvid().await {
-            Ok(cookie) => cookie,
-            Err(e) => {
-                log::debug!("bilibili fingerprint unavailable: {e}");
-                None
-            }
-        };
+    // ponytail: cached for the process lifetime, a failed attempt included.
+    // Refetching after a `-352` would mint a new device id for the same
+    // flagged IP — the escalation path is BILIBILI_COOKIE.
+    {
+        // The guard is released before the request below: held across it, the
+        // first fingerprint call serialized every concurrent bilibili fetch
+        // behind one round trip.
+        let cached = BUVID.lock().await;
+        if let Some(cookie) = cached.as_ref() {
+            return cookie.clone();
+        }
     }
-    cached.clone()
+    let fetched = match fetch_buvid().await {
+        Ok(cookie) => cookie,
+        Err(e) => {
+            log::debug!("bilibili fingerprint unavailable: {e}");
+            None
+        }
+    };
+    // A caller that got there first wins (`get_or_insert`): two requests racing
+    // the first time cost a duplicate fingerprint call, never a wrong cookie.
+    BUVID.lock().await.get_or_insert(fetched).clone()
 }
 
 /// Fetches the device cookies bilibili hands to any visitor. The result is
@@ -214,6 +226,9 @@ pub async fn fetch(dynamic_id: &str) -> Result<model::Item, FetchError> {
     if !status.is_success() {
         return Err(match status.as_u16() {
             412 => risk_control("412"),
+            // A refusal or an auth demand is not a bad moment (412 above is
+            // bilibili's risk control, which does clear on its own).
+            401 | 403 => FetchError::Blocked,
             _ => FetchError::Transient(format!("bilibili status {status}")),
         });
     }
@@ -560,7 +575,8 @@ mod tests {
     /// bot keeps ignoring them instead of answering with a failure.
     #[test]
     fn pattern_ignores_short_links() {
-        assert!(!PATTERN.is_match("https://b23.tv/abc123"));
+        // Short links usually point at videos, so they stay unmatched: no cache
+        // key, and the fetch dispatcher answers `Ok(None)` (silence).
         assert_eq!(cache_key("https://b23.tv/abc123"), None);
     }
 
@@ -580,6 +596,8 @@ mod tests {
         }
     }
 
+    /// The legacy `major.draw` shape stays supported alongside the
+    /// `itemOpusStyle` serialization that moves pictures to `major.opus.pics`.
     #[test]
     fn from_item_maps_draw_images_and_topic() {
         let fetched = parse(item_json(
@@ -743,24 +761,6 @@ mod tests {
         }
     }
 
-    /// The legacy shape stays supported: bilibili's `itemOpusStyle` flag is
-    /// what moves the pictures to `major.opus.pics`, but `major.draw` items
-    /// and a text-only `desc` must keep working if it is retired.
-    #[test]
-    fn from_item_legacy_draw_shape_still_parses() {
-        let fetched = parse(item_json(
-            draw_item("http://i0.hdslb.com/bfs/new_dyn/l.jpg"),
-            "legacy 正文",
-        ));
-        assert_eq!(fetched.title, "");
-        assert_eq!(fetched.content, "legacy 正文");
-        assert_eq!(fetched.media.len(), 1);
-        assert_eq!(
-            fetched.media[0].url(),
-            "https://i0.hdslb.com/bfs/new_dyn/l.jpg"
-        );
-    }
-
     /// The video stream is out of scope; an AV dynamic still yields its cover.
     #[test]
     fn from_item_maps_archive_cover() {

crates/x-media/src/site/bsky/interface.rs

@@ -51,6 +51,17 @@ pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
     // encode path — the temp file stays alive via `_keep_alive`). On any
     // failure the video item is dropped and the post degrades to its text.
     let mut media = Vec::with_capacity(fetched.media.len());
+    // The remux warnings below name the post, not the CDN URL they were
+    // working on: the media URL is derived from what the user pasted, and
+    // `warn` is a level operators share.
+    let key = cache_key(url).unwrap_or_else(|| "?".into());
+    // A failed remux is remembered: if it leaves the post with no media at
+    // all, returning `Ok` would read as "this post has no media". It is
+    // reported as `FetchError::MediaPrep` rather than a transient failure —
+    // the download legs already got their own retry in place ([`fetch_hls`]),
+    // and the fetch loop's retry would only download every segment again to
+    // fail the same way.
+    let mut remux_failure: Option<String> = None;
     for item in fetched.media {
         let is_hls = matches!(&item, Media::Video { url, .. }
             if url.contains("playlist") || url.ends_with(".m3u8"));
@@ -70,12 +81,25 @@ pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
                     url: mp4_path.to_string_lossy().into_owned(),
                     thumbnail_url,
                 });
-                fetched._keep_alive = Some(keep_alive);
+                fetched._keep_alive = Some(std::sync::Arc::new(keep_alive));
+            }
+            // No ffmpeg: a deployment gap, not a bad moment — retrying it
+            // would only waste the fetch budget, so the post degrades (and an
+            // all-video post reports the media type as unsupported).
+            Ok(None) => log::warn!("bsky video remux unavailable for [key={key}]"),
+            Err(e) => {
+                log::warn!("bsky video remux failed for [key={key}]: {e}");
+                remux_failure = Some(e);
             }
-            Ok(None) => log::warn!("bsky video remux unavailable for {url}"),
-            Err(e) => log::warn!("bsky video remux failed for {url}: {e}"),
         }
     }
+    if media.is_empty()
+        && let Some(reason) = remux_failure
+    {
+        return Err(FetchError::MediaPrep(format!(
+            "bsky video remux failed: {reason}"
+        )));
+    }
     fetched.media = media;
     Ok(fetched)
 }
@@ -99,6 +123,41 @@ pub fn media_headers(_url: &str) -> Option<Vec<(&'static str, String)>> {
     None
 }
 
+/// Segments fetched (and written) at once while remuxing an HLS video. Small
+/// on purpose: a segment can be up to 20 MiB and the whole playlist is capped
+/// at 256 MiB, so this is also what bounds the remux's peak memory.
+const SEGMENT_CONCURRENCY: usize = 4;
+
+/// The ffmpeg concat list for the downloaded segments, **in segment order**.
+/// The downloads complete in completion order (`JoinSet`), and ffmpeg would
+/// happily concatenate them in whatever order the list holds: an out-of-order
+/// list produces a silently scrambled video, not an error.
+fn concat_list(files: &mut [(usize, std::path::PathBuf)]) -> String {
+    files.sort_by_key(|(i, _)| *i);
+    files
+        .iter()
+        .map(|(_, path)| format!("file '{}'\n", path.to_string_lossy()))
+        .collect()
+}
+
+/// One HLS fetch (a playlist or a segment) with an in-place retry for a
+/// retryable class (transport, 429/5xx). These used to get their retry from the
+/// outer fetch loop, which pays for it by replaying the whole post: master
+/// playlist, variant playlist and every segment again. A segment failing near
+/// the end of a 500-segment video meant downloading the entire thing twice
+/// more, so the second attempt belongs on the request that actually failed.
+async fn fetch_hls(url: &str, cap: u64) -> Result<bytes::Bytes, String> {
+    match crate::site::download_media_limited(url, cap).await {
+        Err(FetchError::Http(_) | FetchError::Transient(_)) => {
+            tokio::time::sleep(std::time::Duration::from_secs(1)).await;
+            crate::site::download_media_limited(url, cap)
+                .await
+                .map_err(|e| e.to_string())
+        }
+        other => other.map_err(|e| e.to_string()),
+    }
+}
+
 /// Downloads an HLS playlist (master or media) and remuxes its segments to a
 /// single MP4 via ffmpeg. Returns the MP4 path plus the temp dir that must
 /// stay alive until the file is uploaded. `Ok(None)` when ffmpeg is missing.
@@ -114,7 +173,7 @@ async fn resolve_bsky_video(
         crate::site::log_once_ffmpeg_missing();
         return Ok(None);
     }
-    let master = crate::site::download_media_limited(playlist_url, 1_048_576)
+    let master = fetch_hls(playlist_url, 1_048_576)
         .await
         .map_err(|e| format!("bsky video master playlist: {e}"))?;
     let master = String::from_utf8_lossy(&master);
@@ -149,7 +208,7 @@ async fn resolve_bsky_video(
         playlist_url.to_string()
     };
 
-    let variant = crate::site::download_media_limited(&playlist_url, 1_048_576)
+    let variant = fetch_hls(&playlist_url, 1_048_576)
         .await
         .map_err(|e| format!("bsky video media playlist: {e}"))?;
     let variant = String::from_utf8_lossy(&variant);
@@ -169,24 +228,53 @@ async fn resolve_bsky_video(
         return Err("bsky video has too many segments".to_string());
     }
 
-    let frames_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
-    let out_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
+    let frames_dir = tempfile::Builder::new()
+        .prefix(crate::TEMP_FILE_PREFIX)
+        .tempdir()
+        .map_err(|e| e.to_string())?;
+    let out_dir = tempfile::Builder::new()
+        .prefix(crate::TEMP_FILE_PREFIX)
+        .tempdir()
+        .map_err(|e| e.to_string())?;
+    // Segments are fetched concurrently under a small bound, and written with
+    // `tokio::fs` (a multi-megabyte `std::fs::write` blocks the executor
+    // thread). Serially, a several-hundred-segment video made the user wait
+    // for every round trip in turn — the dominant cost of a remux.
     let mut total: u64 = 0;
-    let mut list = String::new();
-    for (i, seg) in segments.iter().enumerate() {
-        let bytes = crate::site::download_media_limited(seg, 20 * 1024 * 1024)
-            .await
-            .map_err(|e| format!("bsky segment {i}: {e}"))?;
-        total += bytes.len() as u64;
+    let mut written: Vec<(usize, std::path::PathBuf)> = Vec::with_capacity(segments.len());
+    let mut next = 0;
+    let mut set = tokio::task::JoinSet::new();
+    loop {
+        while set.len() < SEGMENT_CONCURRENCY && next < segments.len() {
+            let i = next;
+            next += 1;
+            let seg = segments[i].clone();
+            let path = frames_dir.path().join(format!("seg_{i:04}.ts"));
+            set.spawn(async move {
+                let bytes = fetch_hls(&seg, 20 * 1024 * 1024)
+                    .await
+                    .map_err(|e| format!("bsky segment {i}: {e}"))?;
+                tokio::fs::write(&path, &bytes)
+                    .await
+                    .map_err(|e| format!("bsky segment {i}: {e}"))?;
+                Ok::<_, String>((i, bytes.len() as u64, path))
+            });
+        }
+        let Some(joined) = set.join_next().await else {
+            break;
+        };
+        let (i, len, path) = joined.map_err(|e| format!("bsky segment task panicked: {e}"))??;
+        total += len;
         if total > 256 * 1024 * 1024 {
             return Err("bsky video exceeds total size cap".to_string());
         }
-        let path = frames_dir.path().join(format!("seg_{i:04}.ts"));
-        std::fs::write(&path, &bytes).map_err(|e| e.to_string())?;
-        list.push_str(&format!("file '{}'\n", path.to_string_lossy()));
+        written.push((i, path));
     }
+    let list = concat_list(&mut written);
     let list_path = frames_dir.path().join("list.txt");
-    std::fs::write(&list_path, &list).map_err(|e| e.to_string())?;
+    tokio::fs::write(&list_path, &list)
+        .await
+        .map_err(|e| e.to_string())?;
 
     let output = out_dir.path().join("video.mp4");
     let list_str = list_path.to_string_lossy().into_owned();
@@ -235,6 +323,9 @@ pub async fn fetch(handle: &str, rkey: &str) -> Result<Post, FetchError> {
     if !status.is_success() {
         return match status.as_u16() {
             404 | 410 => Err(FetchError::NotFound),
+            // A refusal or an auth demand is not a bad moment: retrying it
+            // three times only delays an error the user has to see.
+            401 | 403 => Err(FetchError::Blocked),
             _ => Err(FetchError::Transient(format!("bsky status {status}"))),
         };
     }
@@ -360,6 +451,22 @@ mod tests {
         serde_json::json!({ "thread": post_json })
     }
 
+    /// The downloads finish in completion order; ffmpeg concatenates whatever
+    /// order `list.txt` holds, so an unsorted list is a scrambled video rather
+    /// than an error.
+    #[test]
+    fn concat_list_is_in_segment_order() {
+        let mut files = vec![
+            (2, std::path::PathBuf::from("/t/seg_0002.ts")),
+            (0, std::path::PathBuf::from("/t/seg_0000.ts")),
+            (1, std::path::PathBuf::from("/t/seg_0001.ts")),
+        ];
+        assert_eq!(
+            concat_list(&mut files),
+            "file '/t/seg_0000.ts'\nfile '/t/seg_0001.ts'\nfile '/t/seg_0002.ts'\n"
+        );
+    }
+
     #[test]
     fn pattern_matches_handle_and_did() {
         let cases = [
@@ -392,6 +499,18 @@ mod tests {
         }
     }
 
+    /// A remux failure is a `MediaPrep`, which the fetch loop does not retry:
+    /// replaying the post means downloading every HLS segment again, when the
+    /// request that failed already got its second attempt in place
+    /// ([`fetch_hls`]). The classes below are the ones still retried there.
+    #[test]
+    fn media_prep_failure_is_not_retried() {
+        assert!(!is_retryable(&FetchError::MediaPrep(
+            "bsky video remux failed: segment 400: 503".into()
+        )));
+        assert!(is_retryable(&FetchError::Transient("429".into())));
+    }
+
     #[test]
     fn from_json_images_with_missing_defaults() {
         let raw = thread_json(serde_json::json!({
@@ -460,31 +579,18 @@ mod tests {
         ));
     }
 
+    /// The one live bsky check: a labelled post with photos — source URL,
+    /// caption, media and the sensitive label all survive the parse. This
+    /// replaced a second byte-identical live test whose URL is a *text-only*
+    /// post, so neither copy pinned any media.
     #[tokio::test]
     #[ignore = "live network: requires outbound HTTPS to public.api.bsky.app"]
     async fn live_fetch_with_photos() {
-        let fetched =
-            fetch_from_url("https://bsky.app/profile/asagi0398.bsky.social/post/3mqkhrq5w6k2m")
-                .await
-                .unwrap();
-        assert_eq!(
-            fetched.source_url,
-            "https://bsky.app/profile/asagi0398.bsky.social/post/3mqkhrq5w6k2m"
-        );
-        assert!(!fetched.caption.is_empty());
-    }
-
-    #[tokio::test]
-    #[ignore = "live network: requires outbound HTTPS to public.api.bsky.app"]
-    async fn live_fetch_smoke() {
-        let fetched =
-            fetch_from_url("https://bsky.app/profile/fu-futa.bsky.social/post/3laoveufjv224")
-                .await
-                .unwrap();
-        assert_eq!(
-            fetched.source_url,
-            "https://bsky.app/profile/fu-futa.bsky.social/post/3laoveufjv224"
-        );
+        let url = "https://bsky.app/profile/fu-futa.bsky.social/post/3laoveufjv224";
+        let fetched = fetch_from_url(url).await.unwrap();
+        assert_eq!(fetched.source_url, url);
         assert!(!fetched.caption.is_empty());
+        assert!(!fetched.media.is_empty(), "expected photos in {url}");
+        assert!(fetched.sensitive, "expected a label on {url}");
     }
 }

crates/x-media/src/site/misskey/interface.rs

@@ -77,6 +77,8 @@ pub async fn fetch(note_id: &str) -> Result<model::Note, FetchError> {
     if !status.is_success() {
         return Err(match status.as_u16() {
             400 => not_found_or_invalid(response).await,
+            // A refusal or an auth demand is not a bad moment.
+            401 | 403 => FetchError::Blocked,
             _ => FetchError::Transient(format!("misskey status {status}")),
         });
     }

crates/x-media/src/site/mod.rs

@@ -52,8 +52,11 @@ pub struct Fetched {
     /// Raw values (pre-escaped) for user-customizable caption formats.
     pub(crate) render_data: Option<RenderData>,
     /// Keeps temp files (e.g. an encoded ugoira MP4) alive until the caller
-    /// finishes uploading; not part of the public contract.
-    pub(crate) _keep_alive: Option<tempfile::TempDir>,
+    /// finishes uploading; not part of the public contract. Shared rather than
+    /// owned because one fetched post can serve several sends — the bot shares
+    /// one in-flight fetch between concurrent duplicates of the same link — and
+    /// the files have to outlive every one of them.
+    pub(crate) _keep_alive: Option<std::sync::Arc<tempfile::TempDir>>,
 }
 
 /// Values for the `{url} {author} {author_url} {title} {content} {tags}`
@@ -133,12 +136,14 @@ impl Fetched {
         })
     }
 
-    /// Hands over the temp dir keeping locally produced media (ugoira MP4,
+    /// A reference to the temp dir keeping locally produced media (ugoira MP4,
     /// bsky remux MP4) alive. The bot keeps it while its task may still be
     /// retried by the queue, which runs after this [`Fetched`] is dropped and
-    /// its temp files would otherwise be gone. `None` when no such dir exists.
-    pub fn take_keep_alive(&mut self) -> Option<tempfile::TempDir> {
-        self._keep_alive.take()
+    /// its temp files would otherwise be gone. `None` when no such dir exists;
+    /// each clone keeps the directory alive for as long as it lives, so two
+    /// sends of one post can each hold the same files.
+    pub fn keep_alive(&self) -> Option<std::sync::Arc<tempfile::TempDir>> {
+        self._keep_alive.clone()
     }
 }
 
@@ -260,6 +265,13 @@ pub enum FetchError {
     /// A download exceeded the caller's size cap (see [`download_media_limited`]).
     #[error("media too large")]
     TooLarge,
+    /// The post was fetched, but its media could not be prepared locally — a
+    /// download or encode step that runs *after* the site's own response
+    /// (bsky's HLS remux, say). Deliberately not retryable: the retry would
+    /// replay the whole fetch, redoing the download work that just failed
+    /// instead of the request that failed.
+    #[error("media could not be prepared: {0}")]
+    MediaPrep(String),
     /// A transient server-side failure (429 / 5xx); [`fetch`] retries these.
     #[error("transient: {0}")]
     Transient(String),
@@ -269,15 +281,57 @@ pub enum FetchError {
     Io(std::io::Error),
 }
 
-/// Shared HTTP client (browser User-Agent) for twitter/bsky fetches and
-/// [`download_media`].
-pub(crate) static CLIENT: LazyLock<reqwest::Client> = LazyLock::new(|| {
+/// How long a download may make no progress: the response head, and then each
+/// individual chunk, must arrive within this window. Not a total timeout — see
+/// [`DOWNLOAD_TOTAL_TIMEOUT`].
+const DOWNLOAD_IDLE_TIMEOUT: Duration = Duration::from_secs(30);
+
+/// Absolute ceiling for one media download, on top of the idle window. A server
+/// that drips a byte every 29 s keeps [`next_chunk`] satisfied indefinitely, and
+/// on the bot's side each such download holds one of the process-wide upload-prep
+/// slots (`send::upload`'s `PREP_SLOTS`) for as long as it lasts. Generous on
+/// purpose: the legitimate cases are big — an ugoira frame zip runs to hundreds
+/// of MB and an HLS remux pulls a whole video — and a slow link is not an error.
+/// Checked between chunks, so a transfer that completes just over the budget is
+/// kept rather than thrown away.
+const DOWNLOAD_TOTAL_TIMEOUT: Duration = Duration::from_secs(600);
+
+/// The error a download reports when it spends its whole budget without
+/// finishing. Retryable: the transfer may simply have been unlucky, and a retry
+/// of the post restarts the download.
+fn download_too_slow() -> FetchError {
+    FetchError::Transient(format!(
+        "download exceeded {}s",
+        DOWNLOAD_TOTAL_TIMEOUT.as_secs()
+    ))
+}
+
+/// Builds a client with the shared configuration (browser User-Agent, the
+/// Bot API's proxy, per-runtime pools under test). `total_timeout` is what
+/// differs between the two clients below.
+fn build_client(total_timeout: Option<Duration>) -> reqwest::Client {
     let mut builder = reqwest::Client::builder()
         .user_agent("Mozilla/5.0")
+        .connect_timeout(Duration::from_secs(10));
+    // Redirects stay allowed (site CDNs use them), but every hop goes through
+    // the same guard as the initial URL, and the cap stays reqwest's default:
+    // a third-party response must not be able to walk the bot into the host's
+    // own network.
+    builder = builder.redirect(reqwest::redirect::Policy::custom(|attempt| {
+        if !media_url_allowed(attempt.url()) {
+            log::warn!("refusing a media redirect into the host's own network");
+            return attempt.error(FetchError::Blocked);
+        }
+        if attempt.previous().len() >= 10 {
+            return attempt.stop();
+        }
+        attempt.follow()
+    }));
+    if let Some(total) = total_timeout {
         // reqwest has no total timeout by default; a stalled connection
         // would otherwise pin a fetch/handler forever.
-        .timeout(Duration::from_secs(30))
-        .connect_timeout(Duration::from_secs(10));
+        builder = builder.timeout(total);
+    }
     // Route site fetches through the same proxy the Bot API uses, so a
     // network that needs TELOXIDE_PROXY (e.g. behind the GFW) does not
     // leave site fetches dead while the bot itself works.
@@ -295,7 +349,55 @@ pub(crate) static CLIENT: LazyLock<reqwest::Client> = LazyLock::new(|| {
     #[cfg(test)]
     let builder = builder.pool_max_idle_per_host(0);
     builder.build().expect("failed to build HTTP client")
-});
+}
+
+/// Shared HTTP client (browser User-Agent) for the site fetches — metadata
+/// requests, where 30s is generous.
+pub(crate) static CLIENT: LazyLock<reqwest::Client> =
+    LazyLock::new(|| build_client(Some(Duration::from_secs(30))));
+
+/// Client for media *downloads*, with no reqwest-level total timeout: a 10 MiB
+/// fallback download, or an ugoira frame zip that may be hundreds of MB,
+/// legitimately takes minutes on a slow link — a 30s total cap made those posts
+/// impossible to deliver at all (the size cap said 512 MiB, the clock said 30s).
+/// What a stalled connection cannot do is hang a worker: the head and every
+/// chunk are bounded by [`DOWNLOAD_IDLE_TIMEOUT`] (see [`next_chunk`]), and a
+/// transfer that keeps trickling but never finishes is bounded by
+/// [`DOWNLOAD_TOTAL_TIMEOUT`].
+static MEDIA_CLIENT: LazyLock<reqwest::Client> = LazyLock::new(|| build_client(None));
+
+/// The error a download reports when it stops making progress.
+fn download_stalled() -> FetchError {
+    FetchError::Transient(format!(
+        "download stalled for {}s",
+        DOWNLOAD_IDLE_TIMEOUT.as_secs()
+    ))
+}
+
+/// Sends a media-download request: the response head must arrive within the
+/// idle window, and a non-2xx status is classified by [`download_status_error`].
+async fn send_download(request: reqwest::RequestBuilder) -> Result<reqwest::Response, FetchError> {
+    let response = match tokio::time::timeout(DOWNLOAD_IDLE_TIMEOUT, request.send()).await {
+        Ok(Ok(response)) => response,
+        Ok(Err(e)) => return Err(e.into()),
+        Err(_) => return Err(download_stalled()),
+    };
+    if response.status().is_success() {
+        Ok(response)
+    } else {
+        Err(download_status_error(response.status()))
+    }
+}
+
+/// One body chunk, or `None` at the end. A body that stops delivering is a
+/// transient download error rather than a hang.
+async fn next_chunk(response: &mut reqwest::Response) -> Result<Option<bytes::Bytes>, FetchError> {
+    match tokio::time::timeout(DOWNLOAD_IDLE_TIMEOUT, response.chunk()).await {
+        Ok(Ok(chunk)) => Ok(chunk),
+        Ok(Err(e)) => Err(e.into()),
+        Err(_) => Err(download_stalled()),
+    }
+}
 
 /// Whether a usable `ffmpeg` binary is on PATH (probed once). Shared by the
 /// pixiv ugoira encoder and the bsky HLS remuxer.
@@ -450,6 +552,9 @@ pub async fn fetch_once(url: &str) -> Result<Option<Fetched>, FetchError> {
 const MAX_FETCH_ATTEMPTS: u32 = 3;
 
 async fn fetch_with_attempts(url: &str, attempts: u32) -> Result<Option<Fetched>, FetchError> {
+    // Wall time of the whole fetch, retry backoff included: the ugoira encode
+    // and the HLS remux live inside it, so this is where a slow fetch shows.
+    let started = std::time::Instant::now();
     let Some(site) = find_site(url) else {
         // A registered-but-disabled site (pixiv without a token) is not an
         // unsupported link: report it, so the bot answers the user instead of
@@ -464,10 +569,11 @@ async fn fetch_with_attempts(url: &str, attempts: u32) -> Result<Option<Fetched>
             Ok(fetched) => {
                 // Per-request detail: debug only, keyed by the post id.
                 log::debug!(
-                    "fetched [key={}]: site {} returned {} media",
+                    "fetched [key={}]: site {} returned {} media in {}ms",
                     cache_key(url).unwrap_or_else(|| "?".into()),
                     fetched.site_name(),
-                    fetched.media.len()
+                    fetched.media.len(),
+                    started.elapsed().as_millis()
                 );
                 return Ok(Some(fetched));
             }
@@ -495,6 +601,84 @@ pub fn needs_media_headers(url: &str) -> bool {
 /// Applies every site's media-header rule to a download request (pixiv's
 /// `Referer` for pximg.net hotlink protection). Sites contribute via their
 /// `media_headers(url)` — the central download code carries no per-site logic.
+/// Whether an address must never be fetched. Media URLs come from a site's own
+/// API response and the bytes are uploaded to Telegram, so following one into
+/// the host's own network would turn the bot into a proxy for it: a cloud
+/// metadata endpoint read back into a chat.
+fn blocked_ip(addr: std::net::IpAddr) -> bool {
+    use std::net::IpAddr;
+    match addr {
+        IpAddr::V4(v4) => {
+            let [a, b, ..] = v4.octets();
+            v4.is_private()           // 10/8, 172.16/12, 192.168/16
+                || v4.is_loopback()   // 127/8
+                || v4.is_link_local() // 169.254/16 — the cloud metadata range
+                || v4.is_unspecified()
+                || v4.is_broadcast()
+                || v4.is_documentation()
+                || v4.is_multicast()
+                // Ranges the std helpers do not cover: carrier-grade NAT and
+                // benchmarking.
+                || (a == 100 && (64..=127).contains(&b))
+                || (a == 198 && (18..=19).contains(&b))
+        }
+        IpAddr::V6(v6) => {
+            let [first, ..] = v6.segments();
+            v6.is_loopback()
+                || v6.is_unspecified()
+                || v6.is_multicast()
+                || (first & 0xfe00) == 0xfc00 // unique local fc00::/7
+                || (first & 0xffc0) == 0xfe80 // link local fe80::/10
+                || v6.to_ipv4_mapped().is_some_and(|v4| blocked_ip(IpAddr::V4(v4)))
+        }
+    }
+}
+
+/// `localhost` (and anything under it) plus the mDNS `.local` suffix: names that
+/// only ever mean this machine.
+fn is_local_name(name: &str) -> bool {
+    let name = name.trim_end_matches('.').to_ascii_lowercase();
+    name == "localhost" || name.ends_with(".localhost") || name.ends_with(".local")
+}
+
+/// Whether a media URL may be requested at all: http(s), and a host that is no
+/// address or name of the host's own network. Applied to the URL a download
+/// starts from *and* to every redirect hop.
+///
+/// The residual gap is DNS rebinding — a name the site controls that resolves to
+/// a private address. Closing it needs a `reqwest::dns::Resolve` wrapper
+/// filtering resolved addresses; it is deliberately not installed, because the
+/// same resolver also resolves the operator's proxy host and `TELOXIDE_PROXY`
+/// is routinely a LAN address, so the guard would take down a working
+/// deployment to block a far less likely attack.
+fn media_url_allowed(url: &url::Url) -> bool {
+    if !matches!(url.scheme(), "http" | "https") {
+        return false;
+    }
+    match url.host() {
+        Some(url::Host::Ipv4(v4)) => !blocked_ip(v4.into()),
+        Some(url::Host::Ipv6(v6)) => !blocked_ip(v6.into()),
+        Some(url::Host::Domain(name)) => !is_local_name(name),
+        None => false,
+    }
+}
+
+/// Prepares a media download: refuses a URL pointing inside the host's own
+/// network ([`FetchError::Blocked`], permanent — the same URL would be refused
+/// again), then applies the site's media headers. One choke point so every
+/// download path gets the guard.
+fn media_request(url: &str) -> Result<reqwest::RequestBuilder, FetchError> {
+    let parsed = url::Url::parse(url).map_err(|e| {
+        log::warn!("media url is not a url: {e}");
+        FetchError::Blocked
+    })?;
+    if !media_url_allowed(&parsed) {
+        log::warn!("refusing to fetch media from the host's own network");
+        return Err(FetchError::Blocked);
+    }
+    Ok(apply_media_headers(MEDIA_CLIENT.get(parsed), url))
+}
+
 fn apply_media_headers(mut request: reqwest::RequestBuilder, url: &str) -> reqwest::RequestBuilder {
     for site in SITES.iter() {
         if let Some(headers) = site.media_headers(url) {
@@ -506,30 +690,31 @@ fn apply_media_headers(mut request: reqwest::RequestBuilder, url: &str) -> reqwe
     request
 }
 
-/// Downloads media bytes for the bot's upload fallback: when Telegram's own
-/// fetch of a media URL is blocked (hotlink protection), the bot downloads
-/// the file itself and uploads it via multipart. Site-appropriate headers
-/// come from each site's `media_headers` (pixiv image hosts need `Referer`).
-/// Returns the Content-Length of a media URL, or `None` when the server does
-/// not report one. Used to check whether a file fits Telegram's size limits
-/// before downloading/uploading it.
-pub async fn media_size(url: &str) -> Result<Option<u64>, FetchError> {
-    let response = apply_media_headers(CLIENT.get(url), url)
-        .send()
-        .await?
-        .error_for_status()?;
-    Ok(response.content_length())
+/// Maps a media download's HTTP status onto the same classes the site
+/// adapters use, so callers can tell "try again" from "this URL is dead":
+/// 4xx is a property of the media (gone, refused by the host), while 429/5xx
+/// is a property of the moment. A transport error never reaches this — it
+/// fails in `send()` and stays [`FetchError::Http`].
+fn download_status_error(status: reqwest::StatusCode) -> FetchError {
+    match status.as_u16() {
+        401 | 403 => FetchError::Blocked,
+        404 | 410 => FetchError::NotFound,
+        _ => FetchError::Transient(format!("media status {status}")),
+    }
 }
 
 /// Downloads a media file with a hard size cap: the body is streamed and the
 /// download aborts with [`FetchError::TooLarge`] the moment the cap is
 /// crossed (or when a declared Content-Length already exceeds it). Keeps the
-/// bot from buffering arbitrarily large bodies into memory.
+/// bot from buffering arbitrarily large bodies into memory — the size check
+/// the bot's upload fallback needs is the one here, not a probe of its own.
+///
+/// This is the bot's download path for the upload fallback: when Telegram
+/// cannot fetch a media URL itself (hotlink protection), the bot downloads
+/// the file and uploads it via multipart. Site-appropriate headers come from
+/// each site's `media_headers` (pixiv image hosts need `Referer`).
 pub async fn download_media_limited(url: &str, max_bytes: u64) -> Result<bytes::Bytes, FetchError> {
-    let response = apply_media_headers(CLIENT.get(url), url)
-        .send()
-        .await?
-        .error_for_status()?;
+    let response = send_download(media_request(url)?).await?;
     if let Some(len) = response.content_length()
         && len > max_bytes
     {
@@ -537,7 +722,11 @@ pub async fn download_media_limited(url: &str, max_bytes: u64) -> Result<bytes::
     }
     let mut response = response;
     let mut buf = Vec::new();
-    while let Some(chunk) = response.chunk().await? {
+    let started = std::time::Instant::now();
+    while let Some(chunk) = next_chunk(&mut response).await? {
+        if started.elapsed() > DOWNLOAD_TOTAL_TIMEOUT {
+            return Err(download_too_slow());
+        }
         buf.extend_from_slice(&chunk);
         if buf.len() as u64 > max_bytes {
             return Err(FetchError::TooLarge);
@@ -562,10 +751,7 @@ pub async fn download_media_to_file(
     out: &mut std::fs::File,
 ) -> Result<u64, FetchError> {
     use std::io::Write;
-    let response = apply_media_headers(CLIENT.get(url), url)
-        .send()
-        .await?
-        .error_for_status()?;
+    let response = send_download(media_request(url)?).await?;
     if let Some(len) = response.content_length()
         && len > max_bytes
     {
@@ -573,7 +759,11 @@ pub async fn download_media_to_file(
     }
     let mut response = response;
     let mut total: u64 = 0;
-    while let Some(chunk) = response.chunk().await? {
+    let started = std::time::Instant::now();
+    while let Some(chunk) = next_chunk(&mut response).await? {
+        if started.elapsed() > DOWNLOAD_TOTAL_TIMEOUT {
+            return Err(download_too_slow());
+        }
         total += chunk.len() as u64;
         if total > max_bytes {
             return Err(FetchError::TooLarge);
@@ -587,6 +777,38 @@ pub async fn download_media_to_file(
 mod tests {
     use super::*;
 
+    /// Locally produced media (ugoira MP4, bsky remux MP4) lives in a temp dir
+    /// whose lifetime is refcounted: one fetch result can serve several sends
+    /// (the bot shares one in-flight fetch between concurrent duplicates), and
+    /// the files must outlive all of them — but no longer than the last one.
+    #[test]
+    fn a_keep_alive_clone_outlives_the_fetched() {
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("media.mp4");
+        std::fs::write(&file, b"mp4").unwrap();
+        let fetched = Fetched {
+            source_url: "https://x.com/u/status/1".into(),
+            caption: String::new(),
+            title: String::new(),
+            content: String::new(),
+            media: Vec::new(),
+            sensitive: false,
+            site_id: "twitter",
+            render_data: None,
+            _keep_alive: Some(std::sync::Arc::new(dir)),
+        };
+
+        let shared = fetched.keep_alive().expect("a temp dir to share");
+        drop(fetched);
+        assert!(file.exists(), "the file must survive the fetched post");
+
+        let second = shared.clone();
+        drop(shared);
+        assert!(file.exists(), "another holder keeps it alive");
+        drop(second);
+        assert!(!file.exists(), "the last holder releases the directory");
+    }
+
     #[test]
     fn cache_key_normalizes_domain_variants() {
         assert_eq!(
@@ -713,13 +935,25 @@ mod tests {
 
     #[test]
     fn truncate_caption_does_not_split_an_html_entity() {
-        // An entity crossing the cut must not be left half-open (&amp without ;).
-        let mut long = "a".repeat(MAX_CAPTION_CHARS - 4);
-        long.push_str("&amp;bbbb");
-        let out = truncate_caption(&long);
-        assert!(out.chars().count() <= MAX_CAPTION_CHARS);
-        assert!(!out.contains("&amp"), "half entity left: {out:?}");
-        assert!(!out.ends_with('&'));
+        // The exact output is what pins the guard: a cut that keeps `&am` (no
+        // `;`) leaves a half-open entity that `!contains("&amp")` cannot see,
+        // so the old assertions stayed green with the guard deleted. Both
+        // directions matter — an entity the cut falls inside is dropped whole,
+        // one the cut falls after is kept whole.
+        for (long, expected) in [
+            (
+                "a".repeat(MAX_CAPTION_CHARS - 4) + "&amp;bbbb",
+                "a".repeat(MAX_CAPTION_CHARS - 4) + "…",
+            ),
+            (
+                "a".repeat(MAX_CAPTION_CHARS - 6) + "&amp;bbbb",
+                "a".repeat(MAX_CAPTION_CHARS - 6) + "&amp;…",
+            ),
+        ] {
+            let out = truncate_caption(&long);
+            assert_eq!(out, expected);
+            assert!(out.chars().count() <= MAX_CAPTION_CHARS, "{out:?}");
+        }
     }
 
     #[test]
@@ -730,16 +964,108 @@ mod tests {
         assert!(out.chars().count() <= MAX_CAPTION_CHARS);
     }
 
+    #[test]
+    fn blocked_addresses_are_the_hosts_own_network() {
+        for addr in [
+            "127.0.0.1",
+            "10.0.0.1",
+            "172.16.0.1",
+            "192.168.1.1",
+            "169.254.169.254", // cloud metadata
+            "0.0.0.0",
+            "255.255.255.255",
+            "100.64.0.1", // carrier-grade NAT
+            "198.18.0.1", // benchmarking
+            "::1",
+            "::",
+            "fc00::1",
+            "fe80::1",
+            "::ffff:127.0.0.1",
+        ] {
+            assert!(blocked_ip(addr.parse().unwrap()), "{addr}");
+        }
+        for addr in [
+            "1.1.1.1",
+            "93.184.216.34",
+            "2606:4700::1111",
+            "::ffff:1.1.1.1",
+        ] {
+            assert!(!blocked_ip(addr.parse().unwrap()), "{addr}");
+        }
+    }
+
+    #[test]
+    fn media_urls_inside_the_host_are_refused() {
+        for url in [
+            "http://127.0.0.1:9/x",
+            "http://169.254.169.254/latest/meta-data/",
+            "http://[::1]:9/x",
+            "https://localhost/",
+            "https://prompt.localhost/x",
+            "https://printer.local/x",
+            "file:///etc/passwd",
+            "gopher://example.com/1",
+        ] {
+            let parsed = url::Url::parse(url).unwrap();
+            assert!(!media_url_allowed(&parsed), "{url}");
+        }
+        // Real media hosts and any public address stay fetchable.
+        for url in [
+            "https://i.pximg.net/img-original/img/1.jpg",
+            "https://cdn.bsky.app/img/feed_thumbnail/plain/x",
+            "http://example.com/a",
+            "https://93.184.216.34/a",
+        ] {
+            let parsed = url::Url::parse(url).unwrap();
+            assert!(media_url_allowed(&parsed), "{url}");
+        }
+    }
+
+    /// The redirect-hop guard, against a public redirector: the initial URL is
+    /// checked by [`media_request`], but a redirect is the part of the path a
+    /// third-party response actually controls.
     #[tokio::test]
-    async fn unsupported_url_returns_none() {
-        let result = fetch("https://example.com/some/article").await;
-        assert!(matches!(result, Ok(None)), "got {result:?}");
+    #[ignore = "live network: requires outbound HTTPS to httpbin.org"]
+    async fn live_redirect_into_the_hosts_network_is_refused() {
+        let url = "https://httpbin.org/redirect-to?url=http://169.254.169.254/latest/meta-data/";
+        match download_media(url).await.unwrap_err() {
+            // A policy refusal reaches the caller wrapped by reqwest.
+            FetchError::Http(e) => assert!(e.is_redirect(), "got {e}"),
+            FetchError::Blocked => {}
+            other => panic!("expected a refusal, got {other:?}"),
+        }
     }
 
     #[tokio::test]
-    async fn unknown_scheme_returns_none() {
-        let result = fetch("not a url at all").await;
-        assert!(matches!(result, Ok(None)), "got {result:?}");
+    async fn a_download_into_the_hosts_network_is_refused() {
+        // Refused on the URL alone: nothing has to be listening (or leaking) at
+        // the metadata endpoint for this to hold, and the class is permanent so
+        // the send path does not retry it.
+        for url in [
+            "http://169.254.169.254/latest/meta-data/",
+            "http://127.0.0.1:9/secret",
+        ] {
+            let err = download_media(url).await.unwrap_err();
+            assert!(matches!(err, FetchError::Blocked), "{url}: got {err:?}");
+        }
+        // A malformed URL is refused the same way instead of becoming a
+        // retryable transport error.
+        assert!(matches!(
+            download_media("not a url").await.unwrap_err(),
+            FetchError::Blocked
+        ));
+    }
+
+    #[tokio::test]
+    async fn unsupported_urls_return_none() {
+        // Neither a URL no site pattern matches nor a string that is no URL at
+        // all is an error: both answer `Ok(None)`, which is what keeps the bot
+        // silent on links it cannot handle (only a registered-but-disabled site
+        // gets a reply).
+        for url in ["https://example.com/some/article", "not a url at all"] {
+            let result = fetch(url).await;
+            assert!(matches!(result, Ok(None)), "{url}: got {result:?}");
+        }
     }
 
     #[test]

crates/x-media/src/site/pixiv/api.rs

@@ -76,6 +76,13 @@ impl PixivAPI {
             .header("User-Agent", AUTH_USER_AGENT)
             .send()
             .await?;
+        // Check the status *before* reading the body: a 429/5xx from the
+        // token endpoint is worth retrying (the class comes from
+        // `is_retryable`), while parsing a maintenance page as JSON turned it
+        // into a permanent `Api`/`Json` error with no retry at all.
+        if !response.status().is_success() {
+            return Err(PixivError::Status(response.status().as_u16()));
+        }
         let json: serde_json::Value = serde_json::from_str(&response.text().await?)?;
         let access_token = json
             .get("access_token")
@@ -134,8 +141,11 @@ impl PixivAPI {
         let mut illustration = Illustration::from_model(&model);
         if matches!(&model.r#type, TypeModel::Ugoira) {
             // Real ugoira support: download the frame zip and encode an MP4.
-            // Without ffmpeg (or on encode failure) the post stays
-            // unsupported (empty media, like Python).
+            // Without ffmpeg the post stays unsupported (empty media, like
+            // Python) — but a *failed* download/encode is reported instead:
+            // a ugoira post has no static image to fall back to, so
+            // swallowing it would present a transient zip-download error as
+            // "this post has no media", with the retries skipped.
             match self.ugoira_video(illust_id).await {
                 Ok(Some((mp4_path, _keep_alive))) => {
                     illustration.media.push(Media::Video {
@@ -143,10 +153,13 @@ impl PixivAPI {
                         url: mp4_path,
                         thumbnail_url: model.image_urls.medium.clone(),
                     });
-                    illustration._keep_alive = Some(_keep_alive);
+                    illustration._keep_alive = Some(std::sync::Arc::new(_keep_alive));
                 }
                 Ok(None) => {}
-                Err(e) => log::error!("ugoira encode failed for {illust_id}: {e}"),
+                Err(e) => {
+                    log::error!("ugoira encode failed for {illust_id}: {e}");
+                    return Err(FetchError::Pixiv(e));
+                }
             }
         }
         Ok(illustration)
@@ -208,6 +221,7 @@ impl PixivAPI {
         // memory: ugoira zips can be hundreds of MB, and the old
         // download_media_limited path spiked RAM up to the size cap.
         let mut zip_file = tempfile::Builder::new()
+            .prefix(crate::TEMP_FILE_PREFIX)
             .suffix(".zip")
             .tempfile()
             .map_err(|e| PixivError::Api(format!("temp zip failed: {e}")))?;
@@ -220,8 +234,14 @@ impl PixivAPI {
         let frame_delays = metadata.frames.iter().map(|f| f.delay).collect::<Vec<_>>();
         let result =
             tokio::task::spawn_blocking(move || -> Result<(String, tempfile::TempDir), String> {
-                let frames_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
-                let out_dir = tempfile::tempdir().map_err(|e| e.to_string())?;
+                let frames_dir = tempfile::Builder::new()
+                    .prefix(crate::TEMP_FILE_PREFIX)
+                    .tempdir()
+                    .map_err(|e| e.to_string())?;
+                let out_dir = tempfile::Builder::new()
+                    .prefix(crate::TEMP_FILE_PREFIX)
+                    .tempdir()
+                    .map_err(|e| e.to_string())?;
 
                 // Extract frames to canonical zero-padded names; pixiv ugoira
                 // frames are uniformly jpg or png per artwork. The zip is read
@@ -378,35 +398,20 @@ mod tests {
     use super::*;
     use dotenv::dotenv;
 
-    /// Skips when `PIXIV_REFRESH_TOKEN` is absent or empty (CI without the
-    /// secret must stay green; GitHub Actions exposes an unset secret as an
-    /// empty string, so `is_err()` alone is not enough).
-    fn require_pixiv_token() -> bool {
-        std::env::var("PIXIV_REFRESH_TOKEN")
-            .ok()
-            .filter(|s| !s.is_empty())
-            .is_some()
-    }
-
-    #[tokio::test]
-    async fn test_fetch() {
-        dotenv().ok();
-        if !require_pixiv_token() {
-            eprintln!("skipping: no PIXIV_REFRESH_TOKEN");
-            return;
-        }
-        let result = fetch(126839080).await;
-        assert!(result.is_ok());
-        println!("{:#?}", result);
-    }
-
     #[tokio::test]
     #[ignore = "live network: requires outbound HTTPS to oauth.secure.pixiv.net"]
     async fn live_validate_with_bogus_token_fails() {
         dotenv().ok();
-        // A bogus token must surface as Api error (invalid_grant), not panic.
+        // A rejected credential must surface as a permanent status, not a panic
+        // and not a retryable class: the exchange answers 4xx and the status is
+        // checked before the body is read (api.rs, `get_access_token`). This
+        // used to assert `Api`, which that check made unreachable — `Api` is
+        // only reached from a 2xx body without an `access_token`.
         let client = PixivAPI::new("bogus_token_for_testing".to_string());
         let result = client.get_access_token().await;
-        assert!(matches!(result, Err(PixivError::Api(_))), "got {result:?}");
+        assert!(
+            matches!(result, Err(PixivError::Status(code)) if (400..500).contains(&code)),
+            "got {result:?}"
+        );
     }
 }

crates/x-media/src/site/pixiv/interface.rs

@@ -46,17 +46,25 @@ impl Site for PixivSite {
     }
 
     fn validate(&self) -> SiteFuture<'static, (), String> {
-        Box::pin(async {
-            match super::api::validate().await {
-                Ok(()) => Ok(()),
-                Err(e) => {
-                    // Keep the old behavior: a failed login disables pixiv
-                    // for the rest of this process.
-                    super::api::disable();
-                    Err(format!("{e}"))
-                }
-            }
-        })
+        Box::pin(async { startup_validation(super::api::validate().await) })
+    }
+}
+
+/// Turns the startup token exchange's outcome into what the bot reports, and
+/// disables pixiv only for a rejected credential. A bad *moment* — a 5xx or a
+/// network error while the container comes up — must not disable it: disabling
+/// on any error turned every later pixiv link into "support is disabled".
+/// Separate from the network call so the decision is testable.
+fn startup_validation(result: Result<(), PixivError>) -> Result<(), String> {
+    match result {
+        Ok(()) => Ok(()),
+        Err(e) if pixiv_error_is_retryable(&e) => {
+            Err(format!("{e} (transient — pixiv stays enabled)"))
+        }
+        Err(e) => {
+            super::api::disable();
+            Err(format!("{e}"))
+        }
     }
 }
 
@@ -84,18 +92,24 @@ pub fn cache_key(url: &str) -> Option<String> {
 pub fn is_retryable(err: &FetchError) -> bool {
     match err {
         FetchError::Http(_) | FetchError::Transient(_) => true,
-        FetchError::Pixiv(e) => match e {
-            PixivError::Http(_) => true,
-            PixivError::Status(code) if *code == 429 || *code >= 500 => true,
-            PixivError::Status(_)
-            | PixivError::Api(_)
-            | PixivError::Json(_)
-            | PixivError::NoAuth => false,
-        },
+        FetchError::Pixiv(e) => pixiv_error_is_retryable(e),
         _ => false,
     }
 }
 
+/// The pixiv-specific half of the retry policy, shared with startup
+/// validation: a bad moment (429/5xx, a network error) is retryable, a
+/// rejected credential is not.
+fn pixiv_error_is_retryable(err: &PixivError) -> bool {
+    match err {
+        PixivError::Http(_) => true,
+        PixivError::Status(code) if *code == 429 || *code >= 500 => true,
+        PixivError::Status(_) | PixivError::Api(_) | PixivError::Json(_) | PixivError::NoAuth => {
+            false
+        }
+    }
+}
+
 /// pximg.net is hotlink-protected: downloads must carry the pixiv Referer.
 /// The match is on the media host, not the site PATTERN — pixiv's PATTERN
 /// only matches `pixiv.net/artworks/...`, never `i.pximg.net`.
@@ -167,7 +181,7 @@ pub struct Illustration {
     pub(crate) media: Vec<Media>,
     nsfw: bool,
     /// Keeps a temp dir (ugoira MP4) alive until the send completes.
-    pub(crate) _keep_alive: Option<tempfile::TempDir>,
+    pub(crate) _keep_alive: Option<std::sync::Arc<tempfile::TempDir>>,
 }
 
 impl Illustration {
@@ -410,6 +424,29 @@ mod tests {
         }
     }
 
+    #[test]
+    fn startup_validation_keeps_the_site_enabled_on_a_bad_moment() {
+        use super::super::api;
+
+        // The startup decision, not the retry policy: a 5xx/429 while the
+        // container comes up must leave pixiv enabled and say so in the message
+        // the admin gets. The rejected-credential half is not exercised here —
+        // it calls `disable()`, a process-wide flag with no reset, so a test
+        // touching it would order-couple every other pixiv test (the predicate
+        // it keys on is covered by the table below).
+        for err in [PixivError::Status(429), PixivError::Status(503)] {
+            let enabled_before = api::enabled();
+            let message = startup_validation(Err(err)).unwrap_err();
+            assert!(message.contains("stays enabled"), "{message}");
+            assert_eq!(
+                api::enabled(),
+                enabled_before,
+                "a bad moment must not disable the site"
+            );
+        }
+        assert!(startup_validation(Ok(())).is_ok());
+    }
+
     #[test]
     fn is_retryable_classifies_transient_and_permanent() {
         // Transient: network errors, explicit transient, pixiv 429/5xx.

crates/x-media/src/site/twitter/auth.rs

@@ -132,6 +132,9 @@ pub async fn fetch(id: &str) -> Result<Tweet, FetchError> {
         log::warn!("twitter auth fetch {id}: HTTP {status}");
         return match status.as_u16() {
             404 | 410 => Err(FetchError::NotFound),
+            // A stale/refused `auth_token` is not a bad moment: retrying it
+            // three times only delays the report.
+            401 | 403 => Err(FetchError::Blocked),
             _ => Err(FetchError::Transient(format!(
                 "twitter auth status {status}"
             ))),
@@ -146,7 +149,7 @@ pub async fn fetch(id: &str) -> Result<Tweet, FetchError> {
             "missing tweet fields in GraphQL response",
         )))
     })?;
-    Tweet::from_syndication_json(&syndication_shape.to_string()).map_err(FetchError::Json)
+    Tweet::from_syndication_value(syndication_shape).map_err(FetchError::Json)
 }
 
 /// Locates the tweet for `id` in a `TweetDetail` response and unwraps
@@ -220,7 +223,7 @@ fn normalize_tweet_result(result: &Value) -> Result<Value, FetchError> {
 }
 
 /// Maps a GraphQL `{core, legacy, ...}` tweet onto the syndication JSON
-/// shape [`Tweet::from_syndication_json`] parses, so the existing text /
+/// shape [`Tweet::from_syndication_value`] parses, so the existing text /
 /// media handling (t.co expansion, `name=orig`, mp4 variant) is reused.
 fn to_syndication_shape(tweet: &Value) -> Option<Value> {
     let legacy = tweet.get("legacy")?;
@@ -305,7 +308,7 @@ mod tests {
         let json = conversation(tweet_result());
         let result = parse_tweet_result(&json, "2083868672721039569").unwrap();
         let shape = to_syndication_shape(&result).unwrap();
-        let tweet = Tweet::from_syndication_json(&shape.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(shape).unwrap();
         let fetched: crate::site::Fetched = tweet.into();
 
         assert!(fetched.sensitive);

crates/x-media/src/site/twitter/interface.rs

@@ -105,17 +105,23 @@ pub async fn fetch(id: &str) -> Result<Tweet, FetchError> {
     if !status.is_success() {
         return match status.as_u16() {
             404 | 410 => Err(FetchError::NotFound),
+            // A refusal or an auth demand is not a bad moment: retrying it
+            // three times only delays an error the user has to see.
+            401 | 403 => Err(FetchError::Blocked),
             _ => Err(FetchError::Transient(format!("twitter status {status}"))),
         };
     }
     let text = response.text().await?;
-    // Classify before parsing the tweet (see [`parse_syndication_body`]).
-    parse_syndication_body(&text)?;
-    Tweet::from_syndication_json(&text).map_err(FetchError::Json)
+    // Classify before building the tweet (see [`parse_syndication_body`]), and
+    // build it from the value that classification already parsed: this used to
+    // scan and allocate the whole body twice.
+    let body = parse_syndication_body(&text)?;
+    Tweet::from_syndication_value(body).map_err(FetchError::Json)
 }
 
-/// Parses and classifies a syndication response body. `Ok` means the body is
-/// a real tweet payload; `Err` carries the permanent error class:
+/// Parses and classifies a syndication response body. `Ok` carries the parsed
+/// body on for the caller to build the tweet from — the same value, so the
+/// text is never parsed twice; `Err` carries the permanent error class:
 /// - `NotFound`: an `errors` array (deleted/blocked) or a `TweetTombstone`
 ///   **with a reason** — "This Post was deleted by the Post author." /
 ///   "This Post is from a suspended account." (the tweet is gone).
@@ -146,7 +152,18 @@ fn parse_syndication_body(text: &str) -> Result<serde_json::Value, FetchError> {
         return Err(FetchError::NotFound);
     }
     if body.get("id_str").is_none() {
-        return Err(FetchError::Sensitive);
+        // Syndication answers an empty `{}` for withheld (NSFW /
+        // age-restricted) tweets: the documented case, kept as `Sensitive`
+        // because it is what triggers the logged-in auth fallback.
+        if body.as_object().is_some_and(|object| object.is_empty()) {
+            return Err(FetchError::Sensitive);
+        }
+        // Any other shape is not a tweet: an interstitial, a truncated body,
+        // a change on their side. Reporting that as withheld content told the
+        // user to set TWITTER_AUTH_TOKEN for something auth cannot fix.
+        return Err(FetchError::Transient(
+            "unexpected syndication body".to_string(),
+        ));
     }
     Ok(body)
 }
@@ -213,8 +230,13 @@ impl Tweet {
         )
     }
 
-    pub fn from_syndication_json(raw_json: &str) -> Result<Self, serde_json::Error> {
-        let json: model::SyndicationTweet = serde_json::from_str(raw_json)?;
+    /// Builds a tweet from an already-parsed syndication body. Takes the value
+    /// rather than JSON text so a caller that had to parse it anyway (the
+    /// fetch path classifies the raw shape; the auth fallback builds the shape
+    /// itself) does not pay for a second scan — `from_value` moves the strings
+    /// out instead.
+    pub fn from_syndication_value(body: serde_json::Value) -> Result<Self, serde_json::Error> {
+        let json: model::SyndicationTweet = serde_json::from_value(body)?;
         let id = json.id_str;
         // Expand the user's t.co short links to their real destinations and
         // strip the appended media short link, mirroring FxEmbed's linkFixer
@@ -416,7 +438,7 @@ mod tests {
             "entities": { "urls": [] },
             "mediaDetails": []
         });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         // The appended media short link is stripped, then entities decoded.
         assert_eq!(tweet.text, ">^ω^< & more 'quoted'");
         assert_eq!(tweet.author, "O'Brien");
@@ -475,7 +497,7 @@ mod tests {
                 }
             }
         ]));
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         let fetched: Fetched = tweet.into();
         assert_eq!(
             fetched.source_url,
@@ -510,14 +532,6 @@ mod tests {
         );
     }
 
-    #[test]
-    fn syndication_text_only_has_no_media() {
-        let raw = fixture(serde_json::json!([]));
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
-        let fetched: Fetched = tweet.into();
-        assert!(fetched.media.is_empty());
-    }
-
     #[test]
     fn syndication_gif_maps_to_animated() {
         let raw = fixture(serde_json::json!([
@@ -529,61 +543,37 @@ mod tests {
                 }
             }
         ]));
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         assert!(matches!(&tweet.media[0], Media::Animated { .. }));
     }
 
     #[test]
     fn syndication_text_strips_trailing_media_short_link() {
         // Real syndication shape: the appended media short link sits after the
-        // visible text; the unmapped t.co link is stripped by content.
-        let raw = serde_json::json!({
-            "__typename": "Tweet",
-            "id_str": "1",
-            "text": "hello world https://t.co/abc123",
-            "user": { "name": "N", "screen_name": "h" },
-            "mediaDetails": []
-        });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
-        assert_eq!(tweet.text, "hello world");
-        assert!(!tweet.caption().contains("t.co"));
-    }
-
-    #[test]
-    fn syndication_text_strips_trailing_link_regardless_of_index_units() {
-        // Real tweet 2084567054481571919: the visible text is 30 code points
-        // but 41 UTF-16 units, and the two endpoints historically reported
-        // display_text_range in different units (UTF-16 on syndication, code
-        // points on GraphQL). The FxEmbed-style content-based strip ignores
-        // the range entirely, so the appended media link is removed for any
-        // response shape.
-        let text = "妄想𝑨𝒅𝒅𝒊𝒄𝒕𝒊𝒐𝒏…🩷💚❤️\n#ゼンゼロ　#zzzero https://t.co/XnIi83EkEB";
-        let visible = "妄想𝑨𝒅𝒅𝒊𝒄𝒕𝒊𝒐𝒏…🩷💚❤️\n#ゼンゼロ　#zzzero";
-        let raw = serde_json::json!({
-            "__typename": "Tweet",
-            "id_str": "2084567054481571919",
-            "text": text,
-            "user": { "name": "N", "screen_name": "h" },
-            "mediaDetails": []
-        });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
-        assert_eq!(tweet.text, visible, "left a partial link");
-        assert!(!tweet.caption().contains("t.co"));
-    }
-
-    #[test]
-    fn syndication_text_strips_trailing_short_link_without_entities() {
-        // No URL entities at all: the leftover t.co link is stripped by the
-        // content regex.
-        let raw = serde_json::json!({
-            "__typename": "Tweet",
-            "id_str": "1",
-            "text": "hello https://t.co/abc123",
-            "user": { "name": "N", "screen_name": "h" },
-            "mediaDetails": []
-        });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
-        assert_eq!(tweet.text, "hello");
+        // visible text and there are no URL entities, so the unmapped t.co link
+        // is stripped by content alone. The second row is real tweet
+        // 2084567054481571919 (30 code points but 41 UTF-16 units, and the two
+        // endpoints historically reported `display_text_range` in different
+        // units): a content-based strip cannot leave a partial link behind for
+        // either unit system.
+        for (text, visible) in [
+            ("hello world https://t.co/abc123", "hello world"),
+            (
+                "妄想𝑨𝒅𝒅𝒊𝒄𝒕𝒊𝒐𝒏…🩷💚❤️\n#ゼンゼロ　#zzzero https://t.co/XnIi83EkEB",
+                "妄想𝑨𝒅𝒅𝒊𝒄𝒕𝒊𝒐𝒏…🩷💚❤️\n#ゼンゼロ　#zzzero",
+            ),
+        ] {
+            let raw = serde_json::json!({
+                "__typename": "Tweet",
+                "id_str": "1",
+                "text": text,
+                "user": { "name": "N", "screen_name": "h" },
+                "mediaDetails": []
+            });
+            let tweet = Tweet::from_syndication_value(raw).unwrap();
+            assert_eq!(tweet.text, visible, "left a partial link in {text:?}");
+            assert!(!tweet.caption().contains("t.co"), "{text:?}");
+        }
     }
 
     #[test]
@@ -605,7 +595,7 @@ mod tests {
             },
             "mediaDetails": []
         });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         assert_eq!(
             tweet.text,
             "Test Tweet with @mentionThis $twtr http://bit.ly/2pUk4be #hashtag"
@@ -624,7 +614,7 @@ mod tests {
             "user": { "name": "N", "screen_name": "h" },
             "mediaDetails": []
         });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         assert_eq!(tweet.text, "check #tag");
     }
 
@@ -647,28 +637,11 @@ mod tests {
             },
             "mediaDetails": []
         });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
+        let tweet = Tweet::from_syndication_value(raw).unwrap();
         assert_eq!(tweet.text, "see  for context");
         assert!(!tweet.caption().contains("t.co"));
     }
 
-    #[test]
-    fn syndication_text_keeps_multibyte_text() {
-        // Text-only tweet: no short links, the multibyte text is untouched.
-        let text = "コミティア落ちたので、明日は行きません。🙏ごめんなさい";
-        let units: Vec<u16> = text.encode_utf16().collect();
-        assert_eq!(units.len(), 28);
-        let raw = serde_json::json!({
-            "__typename": "Tweet",
-            "id_str": "1",
-            "text": text,
-            "user": { "name": "N", "screen_name": "h" },
-            "mediaDetails": []
-        });
-        let tweet = Tweet::from_syndication_json(&raw.to_string()).unwrap();
-        assert_eq!(tweet.text, text, "full text kept intact");
-    }
-
     #[test]
     fn original_twimg_url_rewrites_photo_urls() {
         assert_eq!(
@@ -692,9 +665,14 @@ mod tests {
 
     #[test]
     fn syndication_token_matches_js_formula() {
-        // JS: ((861627479294746624 / 1e15) * PI).toString(36) == "236.vrsocvda"
-        let token = syndication_token(861627479294746624);
-        assert!(token.starts_with("236.v"), "got {token}");
+        // JS: ((861627479294746624 / 1e15) * PI).toString(36) == "236.vrsocvda".
+        // This loop truncates ten base-36 fraction digits instead of rendering
+        // the shortest round-tripping one, so it agrees with JS on the stem and
+        // diverges in the tail (`…d9ui` vs `…da`). Pinned exactly, because the
+        // token is a fixed function of the id: a stub or a wrong constant must
+        // not pass. The endpoint currently serves public tweets regardless of
+        // the token, which is why the tail is left as is.
+        assert_eq!(syndication_token(861627479294746624), "236.vrsocvd9ui");
     }
 
     #[test]
@@ -762,6 +740,17 @@ mod tests {
         ));
     }
 
+    #[test]
+    fn syndication_unexpected_shape_is_transient_not_withheld() {
+        // A 200 that is not a tweet at all (an interstitial, a truncated
+        // body) must not be reported as withheld content: that message tells
+        // the user to set TWITTER_AUTH_TOKEN, which cannot fix it.
+        match parse_syndication_body("{\"foo\":1}") {
+            Err(FetchError::Transient(_)) => {}
+            other => panic!("expected Transient, got {other:?}"),
+        }
+    }
+
     #[test]
     fn syndication_tweet_body_passes() {
         let raw = fixture(serde_json::json!([]));

crates/xmedia-bot/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "xmedia-bot"
-version = "1.8.0"
+version = "1.9.0"
 edition = "2024"
 
 [dependencies]

crates/xmedia-bot/src/ctx.rs

@@ -49,7 +49,67 @@ pub static CONTEXT: LazyLock<AppContext<'static>> =
 #[cfg(test)]
 pub(crate) mod test_support {
     use super::*;
+    use crate::link_cache::{CachedMedia, CachedMediaKind, CachedPost};
+    use crate::state::EditMessage;
     use std::sync::Arc;
+    use teloxide::{ApiError, RequestError};
+
+    /// The edit-before-forward prompt's message id, and the message the prompt
+    /// refers to (the one whose caption a reply swaps).
+    pub(crate) const PROMPT_ID: i64 = 7;
+    pub(crate) const FORWARDED_ID: i64 = 9;
+
+    /// A Telegram API error, for the tests that script a failure.
+    pub(crate) fn api_error(message: &str) -> RequestError {
+        RequestError::Api(ApiError::Unknown(message.to_string()))
+    }
+
+    /// The cached post every test that touches the link cache starts from: one
+    /// photo with a Telegram file id at the canonical URL (key `twitter:1`).
+    /// Tests that need another field mutate the returned value.
+    pub(crate) fn cached_photo() -> CachedPost {
+        CachedPost {
+            url: "https://x.com/u/status/1".into(),
+            caption: "cap".into(),
+            title: "t".into(),
+            content: "c".into(),
+            author: "a".into(),
+            author_url: "au".into(),
+            tags: String::new(),
+            sensitive: false,
+            media: vec![CachedMedia {
+                kind: CachedMediaKind::Photo,
+                file_id: "AgAC-file-id".into(),
+                url: "https://pbs.twimg.com/media/photo.jpg".into(),
+            }],
+        }
+    }
+
+    /// Seeds the live prompt a post-send leaves behind in chat 1: the chat's
+    /// template, a bound forward channel (the prompt's "forward" button
+    /// branches on it) and the record for [`PROMPT_ID`] pointing at
+    /// [`FORWARDED_ID`]. `template` is the record's template — what a reply
+    /// swaps the caption through, `""` for none — and `created_at` backdates
+    /// the record for the expiry cases.
+    pub(crate) async fn seed_prompt(ctx: &AppContext<'_>, template: &str, created_at: i64) {
+        ctx.chat_store
+            .update(1, |data| {
+                data.forward_channel_id = Some(2);
+                data.template
+                    .insert("tpl".to_string(), "<b>[]</b>".to_string());
+                data.edit_message.insert(
+                    PROMPT_ID,
+                    EditMessage {
+                        url: "https://x.com/u/status/1".into(),
+                        chat_id: 1,
+                        forward_message_ids: vec![FORWARDED_ID],
+                        template: template.to_string(),
+                        created_at,
+                    },
+                );
+            })
+            .await;
+    }
 
     pub(crate) struct TestStores {
         _dir: tempfile::TempDir,
@@ -98,6 +158,10 @@ pub(crate) mod test_support {
             &self.link_cache
         }
 
+        pub(crate) fn task_queue(&self) -> &PersistentTaskQueue {
+            &self.task_queue
+        }
+
         /// Rows persisted in the task queue: what "queued for retry" looks like
         /// from the outside.
         pub(crate) async fn queued_tasks(&self) -> i64 {

crates/xmedia-bot/src/db.rs

@@ -124,9 +124,44 @@ pub fn open_store(path: &str) -> rusqlite::Result<Arc<DbPool>> {
     }
     let conn = open_db(path)?;
     schema_init(&conn)?;
+    migrate(&conn)?;
     Ok(Arc::new(DbPool::new(path)))
 }
 
+/// Schema migrations, applied in order and tracked by `PRAGMA user_version`
+/// (the index in this array + 1 is the version a statement brings the
+/// database to). Append only — never edit or reorder an entry, or databases
+/// already past it would skip or repeat work.
+const MIGRATIONS: &[&str] = &[
+    // 1: lease fencing. A worker's write-backs (`delete`/`reschedule`/the
+    // lease heartbeat) are guarded by the token it was leased with, so a
+    // lease that expired and was re-leased by another worker can no longer be
+    // written by its former holder — which used to duplicate a send or drop
+    // the new holder's retry state, silently.
+    "ALTER TABLE tasks ADD COLUMN lease_token TEXT",
+    // 2: the 300 s sweep prunes the link cache by `created_at`
+    // (`DELETE FROM link_cache WHERE created_at < ?`). Without an index that
+    // is a full scan of every post sent inside the TTL window — up to a week
+    // of them — on every sweep; the `url` primary key cannot serve it.
+    "CREATE INDEX IF NOT EXISTS idx_link_cache_created_at ON link_cache(created_at)",
+];
+
+/// Brings an existing database up to [`MIGRATIONS`]. Idempotent: a database
+/// already at the latest version does no work.
+fn migrate(conn: &Connection) -> rusqlite::Result<()> {
+    let version: i64 = conn.query_row("PRAGMA user_version", [], |row| row.get(0))?;
+    for (index, statement) in MIGRATIONS.iter().enumerate() {
+        let target = index as i64 + 1;
+        if version >= target {
+            continue;
+        }
+        conn.execute_batch(statement)?;
+        // `PRAGMA` does not take bind parameters; the value is our own index.
+        conn.execute_batch(&format!("PRAGMA user_version = {target}"))?;
+    }
+    Ok(())
+}
+
 fn rusqlite_error(e: std::io::Error) -> rusqlite::Error {
     rusqlite::Error::ToSqlConversionFailure(Box::new(e))
 }
@@ -135,11 +170,11 @@ fn rusqlite_error(e: std::io::Error) -> rusqlite::Error {
 /// The three stores used to own their own schema; keeping it in one place
 /// means one initialization for the whole database file.
 ///
-/// ⚠️ Schema-change reminder (deferred, see `docs/architecture-refactor.md`
-/// §5): this is a plain `CREATE TABLE IF NOT EXISTS` with no versioning.
-/// Before any column/table change that must migrate existing databases, land
-/// the `PRAGMA user_version` migration chain first (`MIGRATIONS: &[&str]` +
-/// `migrate(conn)`), then restructure this function.
+/// This is the **baseline** schema (version 0): a fresh database is created
+/// exactly like this, and anything that must *change* an existing one is
+/// appended to [`MIGRATIONS`] instead of being edited in here — otherwise a
+/// database created before the change would never gain the new column and a
+/// freshly created one would try to apply the migration a second time.
 pub fn schema_init(conn: &Connection) -> rusqlite::Result<()> {
     conn.execute_batch(
         "CREATE TABLE IF NOT EXISTS tasks (id TEXT PRIMARY KEY, payload TEXT NOT NULL, \
@@ -166,3 +201,143 @@ pub fn now_f64() -> f64 {
 pub fn unix_now() -> i64 {
     now_f64() as i64
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use rusqlite::Connection;
+
+    /// The schema as it shipped *before* the first migration: what an existing
+    /// deployment has on disk when it starts on the new binary. Written out
+    /// literally rather than derived from `schema_init`, so an edit to the
+    /// baseline shows up here instead of being followed silently.
+    const V0_SCHEMA: &str = "CREATE TABLE tasks (id TEXT PRIMARY KEY, payload TEXT NOT NULL, \
+         run_after REAL NOT NULL, attempts INTEGER NOT NULL, status TEXT NOT NULL, \
+         locked_until REAL NOT NULL, created_at REAL NOT NULL); \
+         CREATE INDEX idx_tasks_pending ON tasks(status, run_after); \
+         CREATE TABLE chat_state (chat_id TEXT PRIMARY KEY, payload TEXT NOT NULL); \
+         CREATE TABLE link_cache (url TEXT PRIMARY KEY, payload TEXT NOT NULL, \
+         created_at REAL NOT NULL);";
+
+    /// The migrations that have already shipped, verbatim. Appending is the only
+    /// allowed change: editing one that a database has already applied leaves
+    /// deployments on different schemas with nothing to notice it — the version
+    /// counter says "done" and skips the new text.
+    const SHIPPED_MIGRATIONS: &[&str] = &["ALTER TABLE tasks ADD COLUMN lease_token TEXT"];
+
+    fn columns(conn: &Connection, table: &str) -> Vec<String> {
+        let mut stmt = conn
+            .prepare(&format!("PRAGMA table_info({table})"))
+            .unwrap();
+        let mut names: Vec<String> = stmt
+            .query_map([], |row| row.get::<_, String>(1))
+            .unwrap()
+            .map(Result::unwrap)
+            .collect();
+        names.sort();
+        names
+    }
+
+    fn user_version(conn: &Connection) -> i64 {
+        conn.query_row("PRAGMA user_version", [], |row| row.get(0))
+            .unwrap()
+    }
+
+    #[tokio::test]
+    async fn a_pre_migration_database_upgrades_and_keeps_its_rows() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("old.db");
+        {
+            let conn = Connection::open(&path).unwrap();
+            conn.execute_batch(V0_SCHEMA).unwrap();
+            conn.execute(
+                "INSERT INTO tasks (id, payload, run_after, attempts, status, locked_until, created_at) \
+                 VALUES ('task_old', '{\"chat_id\":1}', 0, 0, 'pending', 0, 0)",
+                [],
+            )
+            .unwrap();
+            assert_eq!(user_version(&conn), 0, "the fixture starts un-migrated");
+            assert!(
+                !columns(&conn, "tasks").contains(&"lease_token".to_string()),
+                "the fixture is the pre-migration shape"
+            );
+        }
+
+        let pool = open_store(path.to_str().unwrap()).unwrap();
+        pool.with_conn(|conn| {
+            assert_eq!(user_version(conn), MIGRATIONS.len() as i64);
+            let mut expected = vec![
+                "id",
+                "payload",
+                "run_after",
+                "attempts",
+                "status",
+                "locked_until",
+                "created_at",
+                "lease_token",
+            ];
+            expected.sort();
+            assert_eq!(
+                columns(conn, "tasks"),
+                expected,
+                "an upgrade must add the migration's column and nothing else"
+            );
+            let payload: String = conn
+                .query_row(
+                    "SELECT payload FROM tasks WHERE id = 'task_old'",
+                    [],
+                    |row| row.get(0),
+                )
+                .unwrap();
+            assert_eq!(payload, "{\"chat_id\":1}", "rows survive the upgrade");
+            // The link-cache prune's index arrives with the migrations (the
+            // baseline schema has none): without it every sweep scans the
+            // whole table.
+            let index: i64 = conn
+                .query_row(
+                    "SELECT COUNT(*) FROM sqlite_master \
+                     WHERE type = 'index' AND name = 'idx_link_cache_created_at'",
+                    [],
+                    |row| row.get(0),
+                )
+                .unwrap();
+            assert_eq!(index, 1, "the migration's index must exist");
+            Ok(())
+        })
+        .await
+        .unwrap();
+    }
+
+    #[test]
+    fn shipped_migrations_are_frozen() {
+        assert!(
+            MIGRATIONS.len() >= SHIPPED_MIGRATIONS.len(),
+            "migrations were removed or reordered, not appended"
+        );
+        for (index, (shipped, current)) in SHIPPED_MIGRATIONS.iter().zip(MIGRATIONS).enumerate() {
+            assert_eq!(
+                shipped,
+                current,
+                "migration {} already shipped: append a new one instead of editing it",
+                index + 1
+            );
+        }
+    }
+
+    #[tokio::test]
+    async fn a_fresh_database_lands_at_the_latest_version() {
+        let dir = tempfile::tempdir().unwrap();
+        let path = dir.path().join("fresh.db");
+        let pool = open_store(path.to_str().unwrap()).unwrap();
+        // Every migration is applied on creation, so a deployment that only ever
+        // saw fresh databases is on the same schema as an upgraded one.
+        pool.with_conn(|conn| {
+            assert_eq!(user_version(conn), MIGRATIONS.len() as i64);
+            Ok(())
+        })
+        .await
+        .unwrap();
+        // Opening the same file again is a no-op (the version gate skips it).
+        open_store(path.to_str().unwrap()).unwrap();
+    }
+}

crates/xmedia-bot/src/handlers/callback.rs

@@ -117,9 +117,24 @@ async fn handle_callback(
                         delay_seconds,
                         task,
                     }) => {
-                        log::info!("forward queued for retry in {delay_seconds:.1}s");
-                        send::enqueue_retry(ctx.task_queue, *task, delay_seconds).await;
-                        ("Forward queued for retry.".to_string(), false)
+                        // The queued row owns the forward from here (it carries
+                        // the message ids itself), so the prompt is settled
+                        // either way: leaving it live let a second Confirm copy
+                        // the same messages to the channel twice, and let Skip
+                        // answer "nothing was forwarded" while the row still
+                        // delivered it.
+                        let queued =
+                            send::enqueue_retry(ctx.task_queue, &task, delay_seconds).await;
+                        if queued {
+                            log::info!("forward queued for retry in {delay_seconds:.1}s");
+                            ("Forward queued for retry.".to_string(), true)
+                        } else {
+                            log::error!("forward retry could not be queued");
+                            (
+                                "Forward failed and the retry could not be queued.".to_string(),
+                                true,
+                            )
+                        }
                     }
                     Err(send::SendError::Permanent { message, .. }) => {
                         log::error!("forward failed permanently: {message}");
@@ -158,30 +173,42 @@ async fn handle_callback(
     }
 
     if let Some(name) = data.strip_prefix(TEMPLATE_PREFIX) {
+        let mut answer = None;
         if let Some(template_html) = chat_data.template.get(name).cloned()
             && let Some(first_forward_id) = edit.forward_message_ids.first().copied()
         {
             // Raw template including the [] placeholder (Python parity).
-            let _ = ctx
-                .sender
-                .edit_message_caption(
-                    ChatId(chat_id),
-                    MessageId(first_forward_id as i32),
-                    template_html,
-                )
-                .await;
-            ctx.chat_store
-                .update(chat_id, |data| {
-                    if let Some(entry) = data.edit_message.get_mut(&prompt_message_id) {
-                        entry.template = name.to_string();
-                    }
-                })
-                .await;
-            log::info!("template '{name}' applied to prompt {prompt_message_id}");
+            match super::apply_caption_edit(
+                ctx.sender,
+                ChatId(chat_id),
+                MessageId(first_forward_id as i32),
+                template_html,
+            )
+            .await
+            {
+                super::EditOutcome::Applied => {
+                    ctx.chat_store
+                        .update(chat_id, |data| {
+                            if let Some(entry) = data.edit_message.get_mut(&prompt_message_id) {
+                                entry.template = name.to_string();
+                            }
+                        })
+                        .await;
+                    log::info!("template '{name}' applied to prompt {prompt_message_id}");
+                }
+                // Nothing was applied, so nothing is recorded either: the
+                // prompt keeps rendering through whatever it used before, and
+                // the toast says why (a silently "successful" press left the
+                // caption unchanged).
+                super::EditOutcome::Failed(reason) => {
+                    log::error!("template '{name}' could not be applied: {reason}");
+                    answer = Some(format!("Could not apply the template: {reason}"));
+                }
+            }
         }
         let _ = ctx
             .sender
-            .answer_callback_query(callback_query_id, None)
+            .answer_callback_query(callback_query_id, answer)
             .await;
     }
 }
@@ -189,52 +216,22 @@ async fn handle_callback(
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::ctx::test_support::TestStores;
+    use crate::ctx::test_support::{FORWARDED_ID, PROMPT_ID, TestStores, api_error, seed_prompt};
     use crate::media_sender::test_support::{MockSender, Outcome};
-    use crate::state::EditMessage;
-    use teloxide::ApiError;
 
-    /// The edit-before-forward prompt's message id in these tests.
-    const PROMPT_ID: i64 = 7;
-    /// The message the prompt refers to (the one whose caption is swapped).
-    const FORWARDED_ID: i64 = 9;
-
-    fn api_error() -> RequestError {
-        RequestError::Api(ApiError::Unknown("Bad Request: chat not found".into()))
-    }
+    /// The Telegram wording the mocks answer with: a chat the bot cannot reach.
+    const API_ERROR: &str = "Bad Request: chat not found";
 
     fn callback_id() -> CallbackQueryId {
         CallbackQueryId("cb-1".to_string())
     }
 
-    /// Seeds a live prompt record plus a forward channel and a template;
-    /// `created_at` backdates the record for the expiry cases.
-    async fn seed_prompt(ctx: &AppContext<'_>, created_at: i64) {
-        ctx.chat_store
-            .update(1, |data| {
-                data.forward_channel_id = Some(2);
-                data.template
-                    .insert("tpl".to_string(), "<b>[]</b>".to_string());
-                data.edit_message.insert(
-                    PROMPT_ID,
-                    EditMessage {
-                        url: "https://x.com/u/status/1".into(),
-                        chat_id: 1,
-                        forward_message_ids: vec![FORWARDED_ID],
-                        template: String::new(),
-                        created_at,
-                    },
-                );
-            })
-            .await;
-    }
-
     #[tokio::test]
     async fn template_button_swaps_the_caption_and_records_the_choice() {
-        let sender = MockSender::scripted(vec![Outcome::EditOk], api_error);
+        let sender = MockSender::scripted(vec![Outcome::EditOk], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, crate::db::unix_now()).await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
 
         handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "template|tpl").await;
 
@@ -250,11 +247,35 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn forward_button_copies_then_clears_the_prompt() {
-        let sender = MockSender::scripted(vec![Outcome::CopyOk], api_error);
+    async fn a_failed_template_swap_is_reported_in_the_toast() {
+        let sender = MockSender::scripted(vec![Outcome::EditErr], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, crate::db::unix_now()).await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
+
+        handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "template|tpl").await;
+
+        // The caption never changed, so the toast says so and the record does
+        // not claim the template was applied.
+        let toast = sender.answers().last().cloned().flatten();
+        assert!(
+            toast
+                .as_deref()
+                .is_some_and(|t| t.contains("Could not apply the template")),
+            "{toast:?}"
+        );
+        assert_eq!(
+            ctx.chat_store.get(1).await.edit_message[&PROMPT_ID].template,
+            ""
+        );
+    }
+
+    #[tokio::test]
+    async fn forward_button_copies_then_clears_the_prompt() {
+        let sender = MockSender::scripted(vec![Outcome::CopyOk], || api_error(API_ERROR));
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&sender);
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
 
         handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "forward").await;
 
@@ -273,10 +294,10 @@ mod tests {
     async fn skip_drops_the_prompt_without_forwarding() {
         // "skip" needs no forward channel and no scripted outcomes: it deletes
         // the prompt and drops the record, so no forward can ever happen.
-        let sender = MockSender::scripted(vec![], api_error);
+        let sender = MockSender::scripted(vec![], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, crate::db::unix_now()).await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
 
         handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "skip").await;
 
@@ -294,12 +315,39 @@ mod tests {
         );
     }
 
+    /// The whole callback path against a stand-in API through a real `Bot`:
+    /// copy, delete, toast, carrying the ids the prompt held. The scripted
+    /// mock records that a call happened; this records what the API received.
+    #[tokio::test]
+    async fn the_forward_button_talks_to_the_api_through_a_real_bot() {
+        use crate::media_sender::test_support::fake_api::FakeApi;
+        use teloxide::Bot;
+
+        let api = FakeApi::start().await;
+        let bot = Bot::new("42:TEST").set_api_url(api.url());
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&bot);
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
+
+        handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "forward").await;
+
+        assert_eq!(
+            api.methods(),
+            vec!["CopyMessages", "DeleteMessage", "AnswerCallbackQuery"]
+        );
+        let copy = api.body("CopyMessages");
+        assert_eq!(copy["chat_id"], 2, "the prompt's channel");
+        assert_eq!(copy["from_chat_id"], 1);
+        assert_eq!(copy["message_ids"], serde_json::json!([FORWARDED_ID]));
+        assert_eq!(api.body("AnswerCallbackQuery")["text"], "✅ Forwarded");
+    }
+
     #[tokio::test]
     async fn forward_without_a_channel_is_reported() {
-        let sender = MockSender::scripted(vec![], api_error);
+        let sender = MockSender::scripted(vec![], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, crate::db::unix_now()).await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
         ctx.chat_store
             .update(1, |data| data.forward_channel_id = None)
             .await;
@@ -314,39 +362,61 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn retryable_forward_is_queued_and_keeps_the_prompt() {
+    async fn retryable_forward_is_queued_and_settles_the_prompt() {
         use teloxide::types::Seconds;
         let sender = MockSender::scripted(vec![Outcome::CopyErr], || {
             RequestError::RetryAfter(Seconds::from_seconds(7))
         });
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, crate::db::unix_now()).await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
 
         handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "forward").await;
 
+        // The queued row carries the message ids itself, so it owns the
+        // forward from here and the prompt is closed with it. Keeping it live
+        // (the old behaviour) let a second Confirm copy the same messages to
+        // the channel twice, and let Skip answer "nothing was forwarded" while
+        // the row still delivered it.
         assert_eq!(
             sender.calls(),
-            vec!["copy_messages", "answer_callback_query"]
+            vec!["copy_messages", "delete_message", "answer_callback_query"]
         );
         assert_eq!(
             sender.answers(),
             vec![Some("Forward queued for retry.".to_string())]
         );
         assert_eq!(stores.queued_tasks().await, 1);
-        // The prompt is not settled: the queued retry still needs the record.
         assert!(
-            ctx.chat_store
+            !ctx.chat_store
                 .get(1)
                 .await
                 .edit_message
-                .contains_key(&PROMPT_ID)
+                .contains_key(&PROMPT_ID),
+            "the record must be dropped so the prompt cannot be used again"
         );
+
+        // A second tap finds no record: it cannot enqueue a duplicate copy.
+        handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "forward").await;
+        assert_eq!(
+            sender.calls(),
+            vec![
+                "copy_messages",
+                "delete_message",
+                "answer_callback_query",
+                "answer_callback_query"
+            ]
+        );
+        assert_eq!(
+            sender.answers().last().map(|a| a.as_deref()),
+            Some(Some("Expired"))
+        );
+        assert_eq!(stores.queued_tasks().await, 1, "no second forward row");
     }
 
     #[tokio::test]
     async fn unknown_and_expired_prompts_answer_expired() {
-        let sender = MockSender::scripted(vec![], api_error);
+        let sender = MockSender::scripted(vec![], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
 
@@ -356,7 +426,7 @@ mod tests {
 
         // A record past its TTL (nothing swept it yet) is dropped on use.
         let stale = crate::db::unix_now() - ctx.config.edit_message_ttl.as_secs() as i64 - 1;
-        seed_prompt(&ctx, stale).await;
+        seed_prompt(&ctx, "", stale).await;
         handle_callback(&ctx, callback_id(), 1, PROMPT_ID, "forward").await;
         assert_eq!(
             sender.answers(),

crates/xmedia-bot/src/handlers/commands.rs

@@ -846,11 +846,8 @@ mod tests {
         );
         assert!(report.contains("site: twitter"), "{report}");
         assert!(report.contains("key: twitter:1"), "{report}");
-        assert!(report.contains("title: My title"), "{report}");
         assert!(report.contains("content: My content"), "{report}");
-        assert!(report.contains("author: Author"), "{report}");
         assert!(report.contains("author_url: https://x.com/u"), "{report}");
-        assert!(report.contains("tags: tag1 tag2"), "{report}");
         assert!(report.contains("sensitive: false"), "{report}");
         assert!(report.contains("media (2):"), "{report}");
         assert!(
@@ -864,11 +861,12 @@ mod tests {
     }
 
     #[test]
-    fn debug_report_without_render_data_and_no_media() {
+    fn debug_report_without_render_data_has_no_author_line() {
         let report = debug_report("u", "pixiv", "s", "t", "c", None, true, "p", &[]);
+        // The `None` branch above is the point: with no render fields there is
+        // no author line to print. The `sensitive`/`media` lines are the same
+        // format sites the escaping test already pins with values.
         assert!(!report.contains("author:"), "{report}");
-        assert!(report.contains("sensitive: true"), "{report}");
-        assert!(report.contains("media (0):"), "{report}");
     }
 
     #[test]
@@ -1016,20 +1014,6 @@ mod tests {
                 command.command
             );
         }
-
-        // A command with a `String` argument must parse with its whole
-        // argument: without `parse_with`, teloxide's default parser rejects
-        // `/remove_template x` and the command silently falls through to the
-        // URL flow.
-        assert!(matches!(
-            Command::parse("/settings", ""),
-            Ok(Command::Settings)
-        ));
-        match Command::parse("/remove_template tpl", "") {
-            Ok(Command::RemoveTemplate(name)) => assert_eq!(name, "tpl"),
-            Ok(_) => panic!("/remove_template parsed as another command"),
-            Err(e) => panic!("parse error: {e}"),
-        }
     }
 
     #[test]

crates/xmedia-bot/src/handlers/inline.rs

@@ -20,6 +20,12 @@ use x_media::media::Media;
 /// post id. Only answer once the query has been stable for this long.
 const INLINE_DEBOUNCE: std::time::Duration = std::time::Duration::from_millis(800);
 
+/// How long a debounce entry is worth keeping: the window Telegram caches an
+/// inline answer for (`answer_inline_query` asks for `cache_time(300)`). Past
+/// it a repeat is sent to the bot again and has to be answered fresh, so the
+/// entry would only suppress a fetch the user is waiting for.
+const INLINE_STATE_TTL: std::time::Duration = std::time::Duration::from_secs(300);
+
 /// Last seen inline query per user and whether it was already answered.
 /// Guards the debounce timer: a repeat of an answered query is served by
 /// Telegram's inline cache (see `cache_time`), not by another fetch. Keyed by
@@ -28,6 +34,10 @@ const INLINE_DEBOUNCE: std::time::Duration = std::time::Duration::from_millis(80
 struct InlineDebounceState {
     query: String,
     answered: bool,
+    /// When a query last touched this entry, so the periodic sweep can drop
+    /// one per user who ever used inline mode (the map had no eviction at all,
+    /// unlike the rate limiter's buckets and the chat store).
+    last_seen: std::time::Instant,
 }
 
 #[derive(Default)]
@@ -49,11 +59,21 @@ impl DebounceStates {
             InlineDebounceState {
                 query: query.to_string(),
                 answered: false,
+                last_seen: std::time::Instant::now(),
             },
         );
         true
     }
 
+    /// Drops entries no query has touched for `idle_for`. Split from the clock
+    /// so the boundary is testable without ageing a monotonic instant.
+    fn prune_idle_at(&mut self, now: std::time::Instant, idle_for: std::time::Duration) -> usize {
+        let before = self.0.len();
+        self.0
+            .retain(|_, state| now.saturating_duration_since(state.last_seen) < idle_for);
+        before - self.0.len()
+    }
+
     /// Claims the answer for the user's newest query; false when a newer query
     /// superseded it or the answer was already claimed.
     fn claim(&mut self, user_id: u64, query: &str) -> bool {
@@ -64,6 +84,7 @@ impl DebounceStates {
             return false;
         }
         state.answered = true;
+        state.last_seen = std::time::Instant::now();
         true
     }
 
@@ -73,10 +94,19 @@ impl DebounceStates {
             && state.query == query
         {
             state.answered = false;
+            state.last_seen = std::time::Instant::now();
         }
     }
 }
 
+/// Drops debounce entries idle for [`INLINE_STATE_TTL`]; the 300 s sweep calls
+/// this next to the rate limiter's prune. Returns how many were dropped.
+pub(crate) fn prune_idle_states() -> usize {
+    INLINE_DEBOUNCE_STATE
+        .lock()
+        .prune_idle_at(std::time::Instant::now(), INLINE_STATE_TTL)
+}
+
 static INLINE_DEBOUNCE_STATE: LazyLock<parking_lot::Mutex<DebounceStates>> =
     LazyLock::new(|| parking_lot::Mutex::new(DebounceStates::default()));
 
@@ -105,8 +135,10 @@ pub async fn inline_query_handler(bot: Bot, query: InlineQuery) -> Result<(), Re
         }
         match answer_inline_query(bot, query).await {
             Ok(true) => {}
-            // No results produced (or nothing to answer): let a repeat of the
-            // same query retry the fetch.
+            // The fetch or the answer call failed: release so a repeat of the
+            // same query may retry it. An *empty* answer is a real answer
+            // (`Ok(true)`), so a link whose media Telegram cannot fetch is not
+            // re-fetched on every keystroke.
             Ok(false) | Err(_) => INLINE_DEBOUNCE_STATE.lock().release(user_id, &query_text),
         }
     });
@@ -116,11 +148,10 @@ pub async fn inline_query_handler(bot: Bot, query: InlineQuery) -> Result<(), Re
 /// Fetches the post behind an inline query and answers it. The caller has
 /// already applied the debounce. Returns `true` when an answer was sent.
 async fn answer_inline_query(bot: Bot, query: InlineQuery) -> Result<bool, RequestError> {
-    log::debug!(
-        "inline query: {} [key={}]",
-        query.query,
-        log_key(&query.query)
-    );
+    // The query is user input: `debug` keeps only its normalized key, the
+    // text itself is `trace` (same split as the message handler).
+    log::debug!("inline query [key={}]", log_key(&query.query));
+    log::trace!("inline query: {}", query.query);
     // No retries: the debounce plus a 1s/2s backoff would outlast the inline
     // query the answer belongs to.
     match x_media::site::fetch_once(&query.query).await {
@@ -204,16 +235,28 @@ async fn answer_inline_query(bot: Bot, query: InlineQuery) -> Result<bool, Reque
                     .await?;
                 return Ok(true);
             }
+            // Every item was skipped: Telegram fetches an inline result's URL
+            // itself, so pixiv's hotlink-protected media (and a local ugoira /
+            // bsky MP4) can never be one. Answer *empty* — the client stops
+            // spinning, and the same query is not re-fetched on every
+            // keystroke: an unanswered query releases the debounce below
+            // (`Ok(false)`), which is what made this re-run the fetch each
+            // time, and the window lets Telegram serve the repeats itself.
+            log::debug!("inline: nothing Telegram can fetch for the query; answering empty");
+            bot.answer_inline_query(query.id, Vec::new())
+                .cache_time(300)
+                .await?;
+            return Ok(true);
         }
         Ok(None) => {}
-        Err(e) => log::error!("inline fetch {}: {e}", query.query),
+        Err(e) => log::error!("inline fetch [key={}]: {e}", log_key(&query.query)),
     }
     Ok(false)
 }
 
 #[cfg(test)]
 mod tests {
-    use super::DebounceStates;
+    use super::{DebounceStates, INLINE_STATE_TTL};
 
     const URL_A: &str = "https://x.com/a/status/1";
     const URL_B: &str = "https://x.com/b/status/2";
@@ -242,6 +285,29 @@ mod tests {
         assert!(states.claim(2, URL_A));
     }
 
+    #[test]
+    fn idle_states_are_pruned_and_live_ones_kept() {
+        let mut states = DebounceStates::default();
+        assert!(states.note(1, URL_A));
+        let first = states.0[&1].last_seen;
+        // Entry 2 is strictly newer, so one timestamp can sit exactly on the
+        // window's edge for one and comfortably inside it for the other.
+        std::thread::sleep(std::time::Duration::from_millis(2));
+        assert!(states.note(2, URL_B));
+
+        assert_eq!(
+            states.prune_idle_at(first + INLINE_STATE_TTL, INLINE_STATE_TTL),
+            1
+        );
+        assert!(
+            !states.0.contains_key(&1),
+            "the entry past the window must go"
+        );
+        assert!(states.0.contains_key(&2), "the live entry must stay");
+        // A pruned user's repeat is answered fresh instead of suppressed.
+        assert!(states.note(1, URL_A));
+    }
+
     #[test]
     fn newer_query_supersedes_and_failed_answer_is_released() {
         let mut states = DebounceStates::default();

crates/xmedia-bot/src/handlers/mod.rs

@@ -15,7 +15,11 @@ mod urls;
 pub use callback::callback_query_handler;
 pub use commands::register_commands;
 pub use inline::inline_query_handler;
+pub(crate) use inline::prune_idle_states;
+/// The resolved `$DATA_DIR/task_queue.db` path, for the startup config line.
+pub(crate) use statics::db_path;
 pub use statics::{CHAT_STORE, CONFIG, LINK_CACHE, TASK_QUEUE};
+pub(crate) use urls::repair_lost_local_media;
 pub use urls::{start_url_workers, stop_url_workers};
 
 use crate::ctx::AppContext;
@@ -68,6 +72,57 @@ pub fn log_key(url: &str) -> String {
     x_media::site::cache_key(url).unwrap_or_else(|| "<unsupported>".to_string())
 }
 
+/// How long a caption edit may sleep before it gives up on retrying: the reply
+/// (or button press) that carried the text is already consumed, so the update
+/// must not stall the chat's queue behind a long flood-control wait — the user
+/// is told to send it again instead.
+const CAPTION_EDIT_MAX_RETRY_WAIT: std::time::Duration = std::time::Duration::from_secs(2);
+
+/// Whether a caption edit landed.
+enum EditOutcome {
+    Applied,
+    /// The API's reason, for the message the user gets.
+    Failed(String),
+}
+
+/// Applies a caption edit, retrying once when the API names a short retryable
+/// delay (`RetryAfter`/network/5xx). A failed edit used to be logged and
+/// swallowed while the record was updated anyway: the user saw nothing, the
+/// caption never changed, and the text they typed was gone. Callers report
+/// [`EditOutcome::Failed`] instead.
+async fn apply_caption_edit(
+    sender: &dyn MediaSender,
+    chat_id: ChatId,
+    message_id: MessageId,
+    caption: String,
+) -> EditOutcome {
+    let mut attempt = 0;
+    loop {
+        match sender
+            .edit_message_caption(chat_id, message_id, caption.clone())
+            .await
+        {
+            Ok(()) => return EditOutcome::Applied,
+            Err(e) => {
+                let reason = e.to_string();
+                if attempt == 0
+                    && let crate::send::Classification::Retryable { delay_seconds } =
+                        crate::send::classify_request_error(&e)
+                    && std::time::Duration::from_secs_f64(delay_seconds)
+                        <= CAPTION_EDIT_MAX_RETRY_WAIT
+                {
+                    attempt = 1;
+                    log::debug!("caption edit failed ({reason}), retrying once");
+                    tokio::time::sleep(std::time::Duration::from_secs_f64(delay_seconds)).await;
+                    continue;
+                }
+                log::error!("edit_message_caption failed: {reason}");
+                return EditOutcome::Failed(reason);
+            }
+        }
+    }
+}
+
 /// Edit-before-forward: a reply to the prompt swaps the caption of the first
 /// forwarded message. Returns true when the message was consumed as an edit.
 /// Body of [`message_handler`]'s edit branch, without teloxide update types so
@@ -99,24 +154,48 @@ async fn edit_message_handler(
             .map(|template| template.replace("[]", &link))
             .unwrap_or(link)
     };
-    match ctx
-        .sender
-        .edit_message_caption(
-            ChatId(chat_id),
-            MessageId(*first_forward_id as i32),
-            new_text,
-        )
-        .await
+    match apply_caption_edit(
+        ctx.sender,
+        ChatId(chat_id),
+        MessageId(*first_forward_id as i32),
+        new_text,
+    )
+    .await
     {
-        Ok(()) => log::info!(
+        EditOutcome::Applied => log::info!(
             "edit-before-forward: caption swapped on message {first_forward_id} for prompt {reply_to_message_id}"
         ),
-        Err(e) => log::error!("edit_message_caption failed: {e}"),
+        // The reply was a caption for this prompt, so it stays consumed either
+        // way — but the user is told the swap failed instead of losing it
+        // silently (and can send it again).
+        EditOutcome::Failed(reason) => {
+            let _ = reply(
+                ctx.sender,
+                chat_id,
+                MessageId(reply_to_message_id as i32),
+                format!("Could not update the caption ({reason}). Send it again to retry."),
+            )
+            .await;
+        }
     }
     true
 }
 
+/// The `dptree` entry point: the process-wide context, plus the bot the
+/// dispatcher handed us (used for the replies this module sends itself).
 pub async fn message_handler(bot: Bot, message: Message) -> Result<(), RequestError> {
+    handle_message(&AppContext::from_statics(&bot), &bot, message).await
+}
+
+/// Body of [`message_handler`], taking its context. Every branch here — the
+/// edit-reply interception, the command path, the private-chat link enqueue and
+/// the group hint — is otherwise reachable only through the process-wide
+/// statics, which is why none of them had a test.
+pub(crate) async fn handle_message(
+    ctx: &AppContext<'_>,
+    bot: &Bot,
+    message: Message,
+) -> Result<(), RequestError> {
     let is_private = matches!(message.chat.kind, ChatKind::Private(_));
     let sender = message
         .from
@@ -130,38 +209,49 @@ pub async fn message_handler(bot: Bot, message: Message) -> Result<(), RequestEr
             &t[..end]
         })
         .unwrap_or("<no text>");
-    // Per-request detail: debug only (message text is user data).
+    // Per-request detail: who and where at `debug`; the message text itself is
+    // user data and only ever appears at `trace`, so a `debug` log can be
+    // shared without leaking what people pasted.
     log::debug!(
-        "message from {sender} in {} (private={is_private}): {text_preview}",
+        "message from {sender} in {} (private={is_private})",
         message.chat.id
     );
+    log::trace!("message text: {text_preview}");
     // URL/edit flows only run in private chats; commands run in any chat.
     if is_private
         && let Some(reply) = message.reply_to_message()
         && let Some(text) = message.text()
-        && edit_message_handler(
-            &AppContext::from_statics(&bot),
-            message.chat.id.0,
-            reply.id.0 as i64,
-            text,
-        )
-        .await
+        && edit_message_handler(ctx, message.chat.id.0, reply.id.0 as i64, text).await
     {
         return respond(());
     }
     if let Some(text) = message.text()
         && let Ok(command) = Command::parse(text, "")
     {
-        log::debug!("command from {}: {text_preview}", message.chat.id);
-        execute_command(&bot, &message, command).await?;
+        // The command name is what the operator needs at `debug`; its argument
+        // may be a user-supplied URL, which stays at `trace`.
+        log::debug!(
+            "command from {}: {}",
+            message.chat.id,
+            text.split_whitespace().next().unwrap_or("<empty>")
+        );
+        log::trace!("command text: {text_preview}");
+        execute_command(bot, &message, command).await?;
         return respond(());
     }
     if is_private {
-        let urls = extract_urls(&message);
+        // Only links a site adapter claims: an unsupported URL never gets a
+        // media message, so enqueuing it would spend a queue slot, a worker
+        // wake-up and (through `run_with_chat_action`) a Telegram call on
+        // nothing. Same test the group branch below makes for its hint.
+        let urls: Vec<String> = extract_urls(&message)
+            .into_iter()
+            .filter(|url| x_media::site::cache_key(url).is_some())
+            .collect();
         if !urls.is_empty() {
             // Debug only, and echo the normalized keys instead of the raw URLs.
             let keys: Vec<String> = urls.iter().map(|u| log_key(u)).collect();
-            log::debug!("extracted {} URL(s): {keys:?}", urls.len());
+            log::debug!("queuing {} supported URL(s): {keys:?}", urls.len());
         }
         for url in urls {
             // Clone out of the lock: the parking_lot guard is !Send and must
@@ -187,7 +277,7 @@ pub async fn message_handler(bot: Bot, message: Message) -> Result<(), RequestEr
         // the expectation is there). Unsupported links stay ignored; the hint
         // names the two paths that do work. Channels are excluded — the reply
         // would be posted into the channel itself.
-        let _ = reply(&bot, message.chat.id.0, message.id, GROUP_LINK_HINT).await;
+        let _ = reply(ctx.sender, message.chat.id.0, message.id, GROUP_LINK_HINT).await;
     }
     respond(())
 }
@@ -212,45 +302,20 @@ fn is_group(kind: &ChatKind) -> bool {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::ctx::test_support::TestStores;
+    use crate::ctx::test_support::{FORWARDED_ID, PROMPT_ID, TestStores, api_error, seed_prompt};
     use crate::media_sender::test_support::{MockSender, Outcome};
-    use crate::state::EditMessage;
-    use teloxide::ApiError;
+    use teloxide::RequestError;
 
-    const PROMPT_ID: i64 = 7;
-    const FORWARDED_ID: i64 = 9;
-
-    fn api_error() -> RequestError {
-        RequestError::Api(ApiError::Unknown("Bad Request: message not found".into()))
-    }
-
-    /// Seeds a prompt record; `template` names the chat template used for it
-    /// (empty = none, the caption gets the bare link).
-    async fn seed_prompt(ctx: &AppContext<'_>, template: &str) {
-        ctx.chat_store
-            .update(1, |data| {
-                data.template
-                    .insert("tpl".to_string(), "<b>[]</b>".to_string());
-                data.edit_message.insert(
-                    PROMPT_ID,
-                    EditMessage {
-                        url: "https://x.com/u/status/1".into(),
-                        chat_id: 1,
-                        forward_message_ids: vec![FORWARDED_ID],
-                        template: template.to_string(),
-                        created_at: crate::db::unix_now(),
-                    },
-                );
-            })
-            .await;
-    }
+    /// The Telegram wording the mocks answer with: a message the bot cannot
+    /// edit (the prompt was deleted).
+    const API_ERROR: &str = "Bad Request: message not found";
 
     #[tokio::test]
     async fn reply_to_a_prompt_swaps_the_caption_through_its_template() {
-        let sender = MockSender::scripted(vec![Outcome::EditOk], api_error);
+        let sender = MockSender::scripted(vec![Outcome::EditOk], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, "tpl").await;
+        seed_prompt(&ctx, "tpl", crate::db::unix_now()).await;
 
         let consumed = edit_message_handler(&ctx, 1, PROMPT_ID, "new caption").await;
 
@@ -263,10 +328,10 @@ mod tests {
 
     #[tokio::test]
     async fn reply_text_and_url_are_escaped_into_the_caption() {
-        let sender = MockSender::scripted(vec![Outcome::EditOk], api_error);
+        let sender = MockSender::scripted(vec![Outcome::EditOk], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, "").await;
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
 
         edit_message_handler(&ctx, 1, PROMPT_ID, "<script>alert(1)</script>").await;
 
@@ -278,21 +343,62 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn a_failed_caption_swap_still_consumes_the_reply() {
-        let sender = MockSender::scripted(vec![Outcome::EditErr], api_error);
+    async fn a_failed_caption_swap_is_reported_and_consumed() {
+        // The script is per call, in order: the edit fails, the notice follows.
+        let sender = MockSender::scripted(vec![Outcome::EditErr, Outcome::MessageOk], || {
+            api_error(API_ERROR)
+        });
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
-        seed_prompt(&ctx, "tpl").await;
+        seed_prompt(&ctx, "tpl", crate::db::unix_now()).await;
 
         // The edit failed (message deleted etc.); the reply must still be
-        // swallowed instead of being treated as a link to fetch.
+        // swallowed instead of being treated as a link to fetch — and the user
+        // must be told, because the text they sent is gone either way.
         assert!(edit_message_handler(&ctx, 1, PROMPT_ID, "new caption").await);
-        assert_eq!(sender.calls(), vec!["edit_message_caption"]);
+        assert_eq!(sender.calls(), vec!["edit_message_caption", "send_message"]);
+        let notice = sender.messages().join(" ");
+        assert!(notice.contains("Could not update the caption"), "{notice}");
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_short_retryable_caption_failure_is_retried_once() {
+        use teloxide::types::Seconds;
+        // A one-second flood-control wait is worth honouring: the retry lands
+        // and the user never hears about it.
+        let sender = MockSender::scripted(vec![Outcome::EditErr, Outcome::EditOk], || {
+            RequestError::RetryAfter(Seconds::from_seconds(1))
+        });
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&sender);
+        seed_prompt(&ctx, "tpl", crate::db::unix_now()).await;
+
+        assert!(edit_message_handler(&ctx, 1, PROMPT_ID, "new caption").await);
+        assert_eq!(
+            sender.calls(),
+            vec!["edit_message_caption", "edit_message_caption"]
+        );
+    }
+
+    #[tokio::test(start_paused = true)]
+    async fn a_long_retryable_caption_failure_is_not_retried() {
+        use teloxide::types::Seconds;
+        // A minute-long wait must not stall the chat's update queue behind it:
+        // the user is told to send the caption again instead.
+        let sender = MockSender::scripted(vec![Outcome::EditErr, Outcome::MessageOk], || {
+            RequestError::RetryAfter(Seconds::from_seconds(60))
+        });
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&sender);
+        seed_prompt(&ctx, "tpl", crate::db::unix_now()).await;
+
+        assert!(edit_message_handler(&ctx, 1, PROMPT_ID, "new caption").await);
+        assert_eq!(sender.calls(), vec!["edit_message_caption", "send_message"]);
     }
 
     #[tokio::test]
     async fn reply_to_an_unrelated_message_is_not_consumed() {
-        let sender = MockSender::scripted(vec![], api_error);
+        let sender = MockSender::scripted(vec![], || api_error(API_ERROR));
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
 
@@ -302,6 +408,64 @@ mod tests {
         assert!(sender.calls().is_empty());
     }
 
+    /// A reply driven through the real message entry point into a real `Bot`:
+    /// the routing (reply-to-prompt → caption swap, before the command and URL
+    /// branches) and the request teloxide builds.
+    #[tokio::test]
+    async fn a_prompt_reply_reaches_the_api_as_a_caption_edit() {
+        use crate::media_sender::test_support::fake_api::FakeApi;
+        use teloxide::Bot;
+
+        let api = FakeApi::start().await;
+        let bot = Bot::new("42:TEST").set_api_url(api.url());
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&bot);
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
+        let message: Message = serde_json::from_value(serde_json::json!({
+            "message_id": PROMPT_ID + 1,
+            "date": 0,
+            "chat": { "id": 1, "type": "private" },
+            "from": { "id": 5, "is_bot": false, "first_name": "u" },
+            "reply_to_message": {
+                "message_id": PROMPT_ID,
+                "date": 0,
+                "chat": { "id": 1, "type": "private" },
+                "text": "prompt",
+            },
+            "text": "new caption",
+        }))
+        .expect("a minimal message deserializes");
+
+        handle_message(&ctx, &bot, message).await.unwrap();
+
+        assert_eq!(api.methods(), vec!["EditMessageCaption"]);
+        let body = api.body("EditMessageCaption");
+        assert_eq!(body["chat_id"], 1);
+        assert_eq!(body["message_id"], FORWARDED_ID);
+        assert_eq!(
+            body["caption"],
+            "<a href=\"https://x.com/u/status/1\">new caption</a>"
+        );
+
+        // The other branch of the same entry point: a supported link in a group
+        // gets the one explanatory reply (the link pipeline is private-chat only,
+        // and dropping it in silence reads as a broken bot).
+        let group: Message = serde_json::from_value(serde_json::json!({
+            "message_id": 2,
+            "date": 0,
+            "chat": { "id": -100, "type": "group", "title": "g" },
+            "from": { "id": 5, "is_bot": false, "first_name": "u" },
+            "text": "https://x.com/u/status/1",
+            "entities": [{ "type": "url", "offset": 0, "length": 24 }],
+        }))
+        .expect("a minimal group message deserializes");
+
+        handle_message(&ctx, &bot, group).await.unwrap();
+
+        assert_eq!(api.methods(), vec!["EditMessageCaption", "SendMessage"]);
+        assert_eq!(api.body("SendMessage")["text"], GROUP_LINK_HINT);
+    }
+
     #[test]
     fn the_link_hint_is_for_groups_only() {
         use teloxide::types::{ChatPrivate, ChatPublic, PublicChatChannel, PublicChatSupergroup};

crates/xmedia-bot/src/handlers/statics.rs

@@ -23,8 +23,9 @@ static DB: LazyLock<Arc<db::DbPool>> = LazyLock::new(|| {
 /// create parent dirs, so the old hardcoded `data/task_queue.db` failed with
 /// a confusing error when started from a directory without `data/`, and a
 /// CWD-relative path is a footgun for systemd / cron deployments — `DATA_DIR`
-/// lets them pin the state anywhere.
-fn db_path() -> std::path::PathBuf {
+/// lets them pin the state anywhere. Also read by the startup config line, so
+/// the log says where the state actually landed.
+pub(crate) fn db_path() -> std::path::PathBuf {
     let dir = std::env::var("DATA_DIR").unwrap_or_else(|_| "data".to_string());
     let dir_path = std::path::Path::new(&dir);
     std::fs::create_dir_all(dir_path).expect("failed to create data directory");

crates/xmedia-bot/src/link_cache.rs

@@ -26,6 +26,12 @@ pub enum CachedMediaKind {
 pub struct CachedMedia {
     pub kind: CachedMediaKind,
     pub file_id: String,
+    /// The media URL the send used, kept so an entry whose file ids stopped
+    /// working can still be re-sent without touching the source site (see the
+    /// bot's `invalidate_cache`). Empty for entries written before this field
+    /// existed — those can only be dropped and re-fetched.
+    #[serde(default)]
+    pub url: String,
 }
 
 /// Everything needed to re-send a post without touching the source site:
@@ -96,7 +102,7 @@ impl LinkCache {
         match result {
             Ok(v) => v,
             Err(e) => {
-                log::error!("link cache read failed: {e}");
+                log::warn!("link cache read failed: {e}");
                 None
             }
         }
@@ -116,7 +122,7 @@ impl LinkCache {
             })
             .await;
         if let Err(e) = result {
-            log::error!("link cache write failed: {e}");
+            log::warn!("link cache write failed: {e}");
         }
     }
 
@@ -131,7 +137,7 @@ impl LinkCache {
             })
             .await;
         if let Err(e) = result {
-            log::error!("link cache delete failed: {e}");
+            log::warn!("link cache delete failed: {e}");
         }
     }
 
@@ -150,7 +156,7 @@ impl LinkCache {
         match result {
             Ok(n) => n,
             Err(e) => {
-                log::error!("link cache prune failed: {e}");
+                log::warn!("link cache prune failed: {e}");
                 0
             }
         }
@@ -170,7 +176,7 @@ impl LinkCache {
         match result {
             Ok(n) => n,
             Err(e) => {
-                log::error!("link cache clear failed: {e}");
+                log::warn!("link cache clear failed: {e}");
                 0
             }
         }
@@ -180,23 +186,7 @@ impl LinkCache {
 #[cfg(test)]
 mod tests {
     use super::*;
-
-    fn entry() -> CachedPost {
-        CachedPost {
-            url: "https://x.com/u/status/1".into(),
-            caption: "cap".into(),
-            title: "t".into(),
-            content: "c".into(),
-            author: "a".into(),
-            author_url: "au".into(),
-            tags: "".into(),
-            sensitive: true,
-            media: vec![CachedMedia {
-                kind: CachedMediaKind::Photo,
-                file_id: "AgAC...".into(),
-            }],
-        }
-    }
+    use crate::ctx::test_support::cached_photo;
 
     /// A payload written before the title/content split has no `content`
     /// field. It must still read back — the cache deletes what it cannot
@@ -247,12 +237,14 @@ mod tests {
         let cache = LinkCache::new(
             crate::db::open_store(dir.path().join("c.db").to_str().unwrap()).unwrap(),
         );
-        cache.put("twitter:1", &entry()).await;
+        cache.put("twitter:1", &cached_photo()).await;
         let got = cache.get("twitter:1", Duration::from_secs(3600)).await;
         assert!(got.is_some());
         let got = got.unwrap();
         assert_eq!(got.url, "https://x.com/u/status/1");
-        assert_eq!(got.media[0].file_id, "AgAC...");
+        assert_eq!(got.media[0].file_id, "AgAC-file-id");
+        // The source URL rides along: it is what a degraded entry falls back to.
+        assert_eq!(got.media[0].url, "https://pbs.twimg.com/media/photo.jpg");
     }
 
     #[tokio::test]
@@ -261,7 +253,7 @@ mod tests {
         let cache = LinkCache::new(
             crate::db::open_store(dir.path().join("c.db").to_str().unwrap()).unwrap(),
         );
-        cache.put("twitter:1", &entry()).await;
+        cache.put("twitter:1", &cached_photo()).await;
         // Force the row into the past so a 1s TTL expires it.
         {
             let conn = rusqlite::Connection::open(dir.path().join("c.db")).unwrap();
@@ -314,8 +306,8 @@ mod tests {
         let cache = LinkCache::new(
             crate::db::open_store(dir.path().join("c.db").to_str().unwrap()).unwrap(),
         );
-        cache.put("twitter:1", &entry()).await;
-        cache.put("pixiv:2", &entry()).await;
+        cache.put("twitter:1", &cached_photo()).await;
+        cache.put("pixiv:2", &cached_photo()).await;
         cache.remove("twitter:1").await;
         assert!(
             cache
@@ -349,8 +341,8 @@ mod tests {
         let cache = LinkCache::new(
             crate::db::open_store(dir.path().join("c.db").to_str().unwrap()).unwrap(),
         );
-        cache.put("twitter:1", &entry()).await;
-        cache.put("pixiv:2", &entry()).await;
+        cache.put("twitter:1", &cached_photo()).await;
+        cache.put("pixiv:2", &cached_photo()).await;
         // By key: only the matching row is removed.
         assert_eq!(cache.clear(Some("twitter:1")).await, 1);
         assert!(

crates/xmedia-bot/src/main.rs

@@ -1,8 +1,9 @@
 use dotenv::dotenv;
+use std::time::Duration;
 use teloxide::dptree::endpoint;
 use teloxide::prelude::*;
 use teloxide::stop::StopToken;
-use teloxide::types::{ChatId, InlineKeyboardMarkup, InputFile, MessageId};
+use teloxide::types::{ChatId, InputFile, MessageId};
 use teloxide::update_listeners::{self, UpdateListener, webhooks};
 use tokio::sync::watch;
 use x_media::site;
@@ -40,12 +41,85 @@ fn spawn_sigterm_handler(stop_token: StopToken) {
 #[cfg(not(unix))]
 fn spawn_sigterm_handler(_stop_token: StopToken) {}
 
+/// A leftover temp file must be at least this old before the startup sweep
+/// touches it. Orphans come from a *previous* run; anything younger could
+/// belong to a second instance sharing the temp directory (a misconfiguration,
+/// but one that must not cost it its in-flight download).
+const ORPHAN_TEMP_AGE: Duration = Duration::from_secs(3600);
+
+/// Removes this project's own leftover temp entries (`x_media::TEMP_FILE_PREFIX`)
+/// from `dir` once they are older than `older_than`. Returns how many were
+/// removed. Entries that are not ours, or are too young, or cannot be dated,
+/// are left alone: the OS temp directory is shared, and the marker prefix plus
+/// the age gate are the only two things that make deleting here safe.
+fn sweep_temp_dir(dir: &std::path::Path, older_than: Duration) -> usize {
+    let Ok(entries) = std::fs::read_dir(dir) else {
+        return 0;
+    };
+    let cutoff = std::time::SystemTime::now() - older_than;
+    let mut removed = 0;
+    for entry in entries.flatten() {
+        let name = entry.file_name();
+        if !name
+            .to_string_lossy()
+            .starts_with(x_media::TEMP_FILE_PREFIX)
+        {
+            continue;
+        }
+        let old_enough = entry
+            .metadata()
+            .and_then(|meta| meta.modified())
+            .is_ok_and(|modified| modified < cutoff);
+        if !old_enough {
+            continue;
+        }
+        let path = entry.path();
+        let result = if entry.file_type().is_ok_and(|kind| kind.is_dir()) {
+            std::fs::remove_dir_all(&path)
+        } else {
+            std::fs::remove_file(&path)
+        };
+        match result {
+            Ok(()) => removed += 1,
+            // Not worth a warning per entry: a file another process removed
+            // first (or one we may not delete) is not a problem here.
+            Err(e) => log::debug!("could not remove orphaned temp entry {path:?}: {e}"),
+        }
+    }
+    removed
+}
+
 #[tokio::main]
 async fn main() {
     dotenv().ok();
-    pretty_env_logger::init();
+    // Without RUST_LOG nothing at all was logged (env_logger falls back to
+    // `error`), so a deployment that forgot the variable looked like a bot
+    // with no logs; and at `debug` the HTTP client's own lines (hyper_util,
+    // reqwest) outnumbered the bot's by two to one. The timed builder adds
+    // the timestamp the plain `init` omitted, so a line can be compared with
+    // a user's report. An explicit RUST_LOG still wins outright — but a blank
+    // one (`RUST_LOG=` in `.env`, which is not "unset") must not silence the
+    // log the way its absence used to.
+    let filter = std::env::var("RUST_LOG")
+        .ok()
+        .filter(|value| !value.trim().is_empty())
+        .unwrap_or_else(|| "info,hyper_util=warn,reqwest=warn".to_string());
+    pretty_env_logger::formatted_timed_builder()
+        .parse_filters(&filter)
+        .init();
     log::info!("Starting bot");
 
+    // Temp media (downloaded files, ugoira/remux dirs) is cleaned up by
+    // `TempDir`/`NamedTempFile` on drop — which a killed process never runs.
+    // Without this sweep every hard restart left its downloads behind (up to
+    // hundreds of MB each) and nothing could tell them apart from a live
+    // process's files or from anything else in the OS temp dir. See
+    // [`sweep_temp_dir`] for why the age gate makes that safe.
+    let orphans = sweep_temp_dir(&std::env::temp_dir(), ORPHAN_TEMP_AGE);
+    if orphans > 0 {
+        log::info!("swept {orphans} orphaned temp file(s) from a previous run");
+    }
+
     let bot = Bot::from_env();
     // Force the queue workers' shared Bot to initialize now so a missing
     // token fails at startup, not on the first queued task.
@@ -56,11 +130,37 @@ async fn main() {
         log::warn!("failed to register commands: {e}");
     }
 
+    // The effective tunables, so an operator can see what the process actually
+    // resolved (a mistyped DATA_DIR or a forgotten TTL override is otherwise
+    // invisible until it bites). The proxy URL is never printed — it may embed
+    // credentials — and admin ids are chat identifiers, so they stay at debug.
+    let quote_chars = match CONFIG.caption_quote_text_chars {
+        0 => "off".to_string(),
+        n => format!("{n} chars"),
+    };
     log::info!(
-        "config: {} admin(s), edit-message TTL {}s",
+        "config: {} admin(s), state {}, edit-message TTL {}s, link cache TTL {}s, caption quote {quote_chars}, proxy={}",
         CONFIG.admin_ids.len(),
-        CONFIG.edit_message_ttl.as_secs()
+        crate::handlers::db_path().display(),
+        CONFIG.edit_message_ttl.as_secs(),
+        CONFIG.link_cache_ttl.as_secs(),
+        if std::env::var("TELOXIDE_PROXY").is_ok() {
+            "yes"
+        } else {
+            "no"
+        }
     );
+    log::debug!("config: admin ids {:?}", CONFIG.admin_ids);
+
+    // Startup repair, before any worker runs: a queued retry whose media was a
+    // local file (ugoira MP4, bsky remux, a downloaded temp file) can never
+    // succeed after a restart — the registry that kept those files alive is in
+    // memory — so those rows are re-fetched from their post instead of
+    // dead-lettering the user's link.
+    let repaired = handlers::repair_lost_local_media(&CONTEXT).await;
+    if repaired > 0 {
+        log::info!("startup repair: re-fetched {repaired} queued task(s)");
+    }
 
     // Queue worker: handles typed tasks, dead-letters failed sends to the
     // task's chat. Both closures use the shared context (the queue requires
@@ -93,51 +193,25 @@ async fn main() {
         }
     }
 
-    // Edit-expiry sweep: clears the prompt's buttons once the record expires.
+    // Background sweep: expires the edit prompts and prunes what has aged out.
     log::info!(
-        "edit-expiry sweep: every 300s, ttl {}",
+        "edit-expiry sweep: every {}s, ttl {}",
+        SWEEP_INTERVAL.as_secs(),
         CONFIG.edit_message_ttl.as_secs()
     );
     let (stop_tx, stop_rx) = watch::channel(false);
     {
         let bot = bot.clone();
-        let mut stop_rx = stop_rx;
         tokio::spawn(async move {
-            loop {
-                tokio::select! {
-                    _ = stop_rx.changed() => break,
-                    _ = tokio::time::sleep(std::time::Duration::from_secs(300)) => {}
-                }
-                let ttl = CONFIG.edit_message_ttl;
-                let removed = CHAT_STORE.prune_expired(ttl).await;
-                let pruned = LINK_CACHE.prune(CONFIG.link_cache_ttl).await;
-                if pruned > 0 {
-                    log::info!("link cache: pruned {pruned} expired entr(ies)");
-                }
-                let idle_limiters = crate::rate_limit::prune_idle();
-                if idle_limiters > 0 {
-                    log::debug!("rate limiter: dropped {idle_limiters} idle bucket(s)");
-                }
-                for (chat_id, prompt_message_id) in removed {
-                    // Rewritten in place, not announced: the sweep is a
-                    // background timer, and a fresh message would wake the chat
-                    // up to a full TTL later about a prompt the user already
-                    // walked away from. The edit drops the buttons too. If the
-                    // prompt was already deleted this fails with a 400
-                    // "message to edit not found" — log and ignore.
-                    if let Err(e) = bot
-                        .edit_message_text(
-                            ChatId(chat_id),
-                            MessageId(prompt_message_id as i32),
-                            send::EDIT_PROMPT_EXPIRED_TEXT,
-                        )
-                        .reply_markup(InlineKeyboardMarkup::default())
-                        .await
-                    {
-                        log::info!("edit-expiry sweep: prompt message gone: {e}");
-                    }
-                }
-            }
+            periodic_sweep(
+                &bot,
+                &CHAT_STORE,
+                &LINK_CACHE,
+                &TASK_QUEUE,
+                &CONFIG,
+                stop_rx,
+            )
+            .await;
         });
     }
 
@@ -217,3 +291,224 @@ async fn main() {
         log::info!("Bot stopped");
     }
 }
+
+/// How often [`periodic_sweep`] runs.
+const SWEEP_INTERVAL: Duration = Duration::from_secs(300);
+
+/// The background sweep: rewrites the expired edit prompts in place, prunes the
+/// link cache, the idle rate-limit buckets and the idle inline-query entries,
+/// and reports the queue only when it is not empty.
+///
+/// Takes its collaborators instead of reaching for the statics so a test can
+/// drive a tick with a paused clock: a sleeping task nothing drives is how the
+/// queue's own sweep kept a missing worker wake-up.
+async fn periodic_sweep(
+    sender: &dyn crate::media_sender::MediaSender,
+    chat_store: &crate::state::ChatStore,
+    link_cache: &crate::link_cache::LinkCache,
+    task_queue: &crate::queue::PersistentTaskQueue,
+    config: &crate::config::Config,
+    mut stop: watch::Receiver<bool>,
+) {
+    loop {
+        tokio::select! {
+            _ = stop.changed() => break,
+            _ = tokio::time::sleep(SWEEP_INTERVAL) => {}
+        }
+        let removed = chat_store.prune_expired(config.edit_message_ttl).await;
+        let pruned = link_cache.prune(config.link_cache_ttl).await;
+        if pruned > 0 {
+            log::info!("link cache: pruned {pruned} expired entr(ies)");
+        }
+        let idle_limiters = crate::rate_limit::prune_idle();
+        if idle_limiters > 0 {
+            log::debug!("rate limiter: dropped {idle_limiters} idle bucket(s)");
+        }
+        // Entries past Telegram's own inline cache window: a repeat is sent to
+        // the bot again anyway, so keeping them would suppress a fetch the user
+        // is waiting for (and the map grew one entry per user, forever).
+        let idle_inline = handlers::prune_idle_states();
+        if idle_inline > 0 {
+            log::debug!("inline queries: dropped {idle_inline} idle entry(ies)");
+        }
+        // Only speaks up when the queue is not empty: a healthy bot has nothing
+        // to report, and a periodic "0 pending" line is noise that hides the
+        // lines that matter.
+        if let Some((pending, oldest_run_after)) = task_queue.pending_backlog().await {
+            let overdue = crate::db::now_f64() - oldest_run_after;
+            if overdue >= 0.0 {
+                log::info!("queue: {pending} pending task(s), oldest {overdue:.0}s overdue");
+            } else {
+                log::info!(
+                    "queue: {pending} pending task(s), oldest retry in {:.0}s",
+                    -overdue
+                );
+            }
+        }
+        for (chat_id, prompt_message_id) in removed {
+            // Rewritten in place, not announced: the sweep is a background
+            // timer, and a fresh message would wake the chat up to a full TTL
+            // later about a prompt the user already walked away from. The edit
+            // drops the buttons too. If the prompt was already deleted this
+            // fails with a 400 "message to edit not found" — log and ignore.
+            if let Err(e) = sender
+                .edit_message_text(
+                    ChatId(chat_id),
+                    MessageId(prompt_message_id as i32),
+                    send::EDIT_PROMPT_EXPIRED_TEXT.to_string(),
+                )
+                .await
+            {
+                log::info!("edit-expiry sweep: prompt message gone: {e}");
+            }
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn sweep_removes_only_our_old_temp_entries() {
+        let dir = tempfile::tempdir().unwrap();
+        let old = std::time::SystemTime::now() - Duration::from_secs(7200);
+        let make = |name: &str, aged: bool| {
+            let path = dir.path().join(name);
+            std::fs::write(&path, b"x").unwrap();
+            if aged {
+                let file = std::fs::File::options().write(true).open(&path).unwrap();
+                file.set_modified(old).unwrap();
+            }
+            path
+        };
+        let ours_old = make(&format!("{}photo-old.jpg", x_media::TEMP_FILE_PREFIX), true);
+        let ours_fresh = make(
+            &format!("{}photo-new.jpg", x_media::TEMP_FILE_PREFIX),
+            false,
+        );
+        let theirs = make("someone-elses-file", true);
+
+        assert_eq!(sweep_temp_dir(dir.path(), Duration::from_secs(3600)), 1);
+        assert!(!ours_old.exists(), "an old leftover of ours is removed");
+        assert!(ours_fresh.exists(), "a fresh file may belong to a live run");
+        assert!(
+            theirs.exists(),
+            "files without our prefix are never touched"
+        );
+
+        // A caller with no age gate also reaches the directory branch (aging a
+        // *directory* is not portable, so the gate is what the first half
+        // above proves): the fresh dir and file go, the unrelated file stays.
+        let leftover_dir = dir
+            .path()
+            .join(format!("{}ugoira", x_media::TEMP_FILE_PREFIX));
+        std::fs::create_dir(&leftover_dir).unwrap();
+        std::fs::write(leftover_dir.join("frame.png"), b"x").unwrap();
+        assert_eq!(sweep_temp_dir(dir.path(), Duration::ZERO), 2);
+        assert!(
+            !leftover_dir.exists(),
+            "leftover dirs go with their contents"
+        );
+        assert!(!ours_fresh.exists(), "no age gate: ours, however fresh");
+        assert!(theirs.exists());
+    }
+
+    /// The sweep's tick: an expired prompt is rewritten in place (buttons
+    /// dropped) while a live one is left alone. Driven through the loop's own
+    /// timer on a paused clock — the loop is what a hand-called helper would
+    /// leave untested, which is how the queue's sweep kept a missing wake-up.
+    #[tokio::test(start_paused = true)]
+    async fn the_sweep_expires_only_the_prompts_past_their_ttl() {
+        use crate::ctx::test_support::{
+            FORWARDED_ID, PROMPT_ID, TestStores, api_error, seed_prompt,
+        };
+        use crate::media_sender::test_support::MockSender;
+        use crate::state::EditMessage;
+
+        // The interval is pinned here because no assertion on the edits can see
+        // it: a shorter interval produces the same single edit (the record is
+        // gone after the first tick), and the paused clock can jump past the
+        // boundary while a tick's DB work is in flight.
+        assert_eq!(SWEEP_INTERVAL, Duration::from_secs(300));
+
+        let config = crate::config::Config::load();
+        let stores = TestStores::new();
+        let sender = MockSender::scripted(vec![], || {
+            api_error("Bad Request: message to edit not found")
+        });
+        let ctx = stores.ctx(&sender);
+        // Chat 1 holds a prompt past its ttl; chat 2 a live one.
+        let stale = crate::db::unix_now() - config.edit_message_ttl.as_secs() as i64 - 1;
+        seed_prompt(&ctx, "", stale).await;
+        stores
+            .chat_store()
+            .update(2, |data| {
+                data.edit_message.insert(
+                    PROMPT_ID,
+                    EditMessage {
+                        url: "https://x.com/u/status/1".into(),
+                        chat_id: 2,
+                        forward_message_ids: vec![FORWARDED_ID],
+                        template: String::new(),
+                        created_at: crate::db::unix_now(),
+                    },
+                );
+            })
+            .await;
+
+        let (stop_tx, stop_rx) = watch::channel(false);
+        let sweep = periodic_sweep(
+            &sender,
+            stores.chat_store(),
+            stores.link_cache(),
+            stores.task_queue(),
+            &config,
+            stop_rx,
+        );
+        tokio::pin!(sweep);
+
+        // One second short of the interval: nothing has been touched. The
+        // select is what polls the loop (a pinned future nobody awaits never
+        // runs), and the paused clock makes this the loop's own timer.
+        tokio::select! {
+            _ = &mut sweep => unreachable!("the sweep only returns on stop"),
+            _ = tokio::time::sleep(SWEEP_INTERVAL - Duration::from_secs(1)) => {}
+        }
+        assert!(
+            sender.edited_texts().is_empty(),
+            "the sweep ran before its interval"
+        );
+
+        // The second that crosses the interval: the tick fires.
+        tokio::select! {
+            _ = &mut sweep => unreachable!("the sweep only returns on stop"),
+            _ = tokio::time::sleep(Duration::from_secs(2)) => {}
+        }
+
+        assert_eq!(
+            sender.edited_texts(),
+            vec![(1, PROMPT_ID, send::EDIT_PROMPT_EXPIRED_TEXT.to_string())],
+            "exactly the expired prompt, rewritten in place"
+        );
+        assert!(
+            !ctx.chat_store
+                .get(1)
+                .await
+                .edit_message
+                .contains_key(&PROMPT_ID),
+            "the expired record is gone"
+        );
+        assert!(
+            ctx.chat_store
+                .get(2)
+                .await
+                .edit_message
+                .contains_key(&PROMPT_ID),
+            "a live prompt keeps its record and its buttons"
+        );
+
+        stop_tx.send(true).unwrap();
+        sweep.await;
+    }
+}

crates/xmedia-bot/src/media_sender.rs

@@ -68,6 +68,16 @@ pub trait MediaSender: Send + Sync {
         text: Option<String>,
     ) -> BoxFuture<'_, Result<(), RequestError>>;
 
+    /// Rewrites a message's text and drops its inline keyboard: the
+    /// edit-expiry sweep rewriting a prompt whose record expired (a button left
+    /// behind could only answer "Expired").
+    fn edit_message_text(
+        &self,
+        chat_id: ChatId,
+        message_id: MessageId,
+        text: String,
+    ) -> BoxFuture<'_, Result<(), RequestError>>;
+
     /// Rewrites a message's caption, always with HTML parse mode (every caller
     /// in this bot renders escaped HTML: templates and edit-before-forward
     /// links).
@@ -106,6 +116,9 @@ impl MediaSender for Bot {
             crate::rate_limit::limiter_for(chat_id.0)
                 .acquire(items.len() as f64)
                 .await;
+            // Same spend against the bot-wide budget: a fan-out over chats is
+            // invisible to the per-chat buckets.
+            crate::rate_limit::acquire_global(items.len() as f64).await;
             // `<Bot as Requester>::` disambiguates from this trait's same-named
             // method (teloxide's API lives in the `Requester` trait).
             <Bot as Requester>::send_media_group(self, chat_id, items)
@@ -124,6 +137,7 @@ impl MediaSender for Bot {
     ) -> BoxFuture<'a, Result<Message, RequestError>> {
         Box::pin(async move {
             crate::rate_limit::limiter_for(chat_id.0).acquire(1.0).await;
+            crate::rate_limit::acquire_global(1.0).await;
             let mut request = <Bot as Requester>::send_animation(self, chat_id, file)
                 .caption(caption)
                 .parse_mode(ParseMode::Html)
@@ -147,6 +161,7 @@ impl MediaSender for Bot {
             crate::rate_limit::limiter_for(to.0)
                 .acquire(ids.len() as f64)
                 .await;
+            crate::rate_limit::acquire_global(ids.len() as f64).await;
             <Bot as Requester>::copy_messages(self, to, from, ids).await
         })
     }
@@ -185,6 +200,20 @@ impl MediaSender for Bot {
         })
     }
 
+    fn edit_message_text(
+        &self,
+        chat_id: ChatId,
+        message_id: MessageId,
+        text: String,
+    ) -> BoxFuture<'_, Result<(), RequestError>> {
+        Box::pin(async move {
+            <Bot as Requester>::edit_message_text(self, chat_id, message_id, text)
+                .reply_markup(InlineKeyboardMarkup::default())
+                .await
+                .map(|_| ())
+        })
+    }
+
     fn edit_message_caption(
         &self,
         chat_id: ChatId,
@@ -251,6 +280,200 @@ pub(crate) mod test_support {
         EditErr,
     }
 
+    /// A stand-in for `api.telegram.org` for the tests that must drive a real
+    /// `Bot` — its request building, the per-chat limiter, the bot-wide budget
+    /// — which the scripted mock bypasses entirely. Records every call and
+    /// answers the smallest result each method needs.
+    pub(crate) mod fake_api {
+        use parking_lot::Mutex;
+        use std::sync::Arc;
+        use tokio::io::{AsyncReadExt, AsyncWriteExt};
+        use tokio::net::{TcpListener, TcpStream};
+
+        pub(crate) struct FakeApi {
+            url: url::Url,
+            calls: Arc<Mutex<Vec<(String, serde_json::Value)>>>,
+            server: tokio::task::JoinHandle<()>,
+        }
+
+        impl FakeApi {
+            /// Binds an ephemeral port and serves until dropped.
+            pub(crate) async fn start() -> FakeApi {
+                let listener = TcpListener::bind("127.0.0.1:0").await.unwrap();
+                let addr = listener.local_addr().unwrap();
+                let calls = Arc::new(Mutex::new(Vec::new()));
+                let recorded = Arc::clone(&calls);
+                let server = tokio::spawn(async move {
+                    while let Ok((mut socket, _)) = listener.accept().await {
+                        let recorded = Arc::clone(&recorded);
+                        tokio::spawn(async move {
+                            let Some((method, body)) = read_request(&mut socket).await else {
+                                return;
+                            };
+                            recorded.lock().push((method.clone(), body));
+                            let payload = serde_json::json!({
+                                "ok": true,
+                                "result": canned_result(&method),
+                            })
+                            .to_string();
+                            let response = format!(
+                                "HTTP/1.1 200 OK\r\ncontent-type: application/json\r\n\
+                                 content-length: {}\r\nconnection: close\r\n\r\n{}",
+                                payload.len(),
+                                payload
+                            );
+                            let _ = socket.write_all(response.as_bytes()).await;
+                            let _ = socket.flush().await;
+                        });
+                    }
+                });
+                FakeApi {
+                    // Trailing slash: teloxide appends `bot<token>/<method>`.
+                    url: url::Url::parse(&format!("http://{addr}/")).unwrap(),
+                    calls,
+                    server,
+                }
+            }
+
+            /// Where to point a `Bot`: `Bot::new(token).set_api_url(api.url())`.
+            pub(crate) fn url(&self) -> url::Url {
+                self.url.clone()
+            }
+
+            /// Method names in call order.
+            pub(crate) fn methods(&self) -> Vec<String> {
+                self.calls.lock().iter().map(|(m, _)| m.clone()).collect()
+            }
+
+            /// The JSON body of the first call to `method` (`Null` for a body
+            /// that is not JSON, i.e. a multipart upload).
+            pub(crate) fn body(&self, method: &str) -> serde_json::Value {
+                self.calls
+                    .lock()
+                    .iter()
+                    .find(|(m, _)| m == method)
+                    .map(|(_, body)| body.clone())
+                    .unwrap_or(serde_json::Value::Null)
+            }
+        }
+
+        impl Drop for FakeApi {
+            fn drop(&mut self) {
+                self.server.abort();
+            }
+        }
+
+        /// The smallest result teloxide can deserialize for a method. The names
+        /// arrive as the payload type's own — `SendMediaGroup`, not
+        /// `sendMediaGroup`: teloxide builds the URL from that, and the Bot API
+        /// accepts the spelling.
+        fn canned_result(method: &str) -> serde_json::Value {
+            match method {
+                "CopyMessages" => serde_json::json!([{ "message_id": 11 }]),
+                "SendMediaGroup" => serde_json::json!([minimal_message()]),
+                "SendMessage" | "SendAnimation" | "EditMessageCaption" => minimal_message(),
+                _ => serde_json::Value::Bool(true),
+            }
+        }
+
+        fn minimal_message() -> serde_json::Value {
+            serde_json::json!({
+                "message_id": 1,
+                "date": 0,
+                "chat": { "id": 1, "type": "private" },
+            })
+        }
+
+        /// One HTTP/1.1 request: the head up to the blank line, then
+        /// `content-length` bytes of body — JSON for most methods, multipart
+        /// for the media ones (teloxide sends `SendMediaGroup` that way).
+        async fn read_request(socket: &mut TcpStream) -> Option<(String, serde_json::Value)> {
+            let mut buf = Vec::new();
+            let mut chunk = [0u8; 4096];
+            loop {
+                let n = socket.read(&mut chunk).await.ok()?;
+                if n == 0 {
+                    return None;
+                }
+                buf.extend_from_slice(&chunk[..n]);
+                let Some(headers_end) = find(&buf, b"\r\n\r\n") else {
+                    continue;
+                };
+                let head = String::from_utf8_lossy(&buf[..headers_end]).to_string();
+                let length: usize = head
+                    .lines()
+                    .find_map(|line| {
+                        line.to_ascii_lowercase()
+                            .strip_prefix("content-length:")
+                            .and_then(|v| v.trim().parse().ok())
+                    })
+                    .unwrap_or(0);
+                let body_start = headers_end + 4;
+                while buf.len() < body_start + length {
+                    let n = socket.read(&mut chunk).await.ok()?;
+                    if n == 0 {
+                        break;
+                    }
+                    buf.extend_from_slice(&chunk[..n]);
+                }
+                let method = head
+                    .lines()
+                    .next()
+                    // `POST /bot<token>/<method>`
+                    .and_then(|line| line.split(' ').nth(1))
+                    .and_then(|path| path.rsplit('/').next())
+                    .unwrap_or_default()
+                    .to_string();
+                let body = parse_body(&buf[body_start..], &head);
+                return Some((method, body));
+            }
+        }
+
+        /// The request body as JSON: either the JSON body itself, or a
+        /// multipart form flattened into an object (each part's value parsed as
+        /// JSON when it is one, so `media` comes back as its array).
+        fn parse_body(body: &[u8], head: &str) -> serde_json::Value {
+            let content_type = head
+                .lines()
+                .find(|line| line.to_ascii_lowercase().starts_with("content-type:"))
+                .unwrap_or_default()
+                .to_ascii_lowercase();
+            let Some(boundary) = content_type
+                .split("boundary=")
+                .nth(1)
+                .map(|b| b.trim().trim_matches('"').to_string())
+            else {
+                return serde_json::from_slice(body).unwrap_or_default();
+            };
+            let text = String::from_utf8_lossy(body);
+            let mut fields = serde_json::Map::new();
+            for part in text.split(&format!("--{boundary}")).skip(1) {
+                let Some((part_head, value)) = part.split_once("\r\n\r\n") else {
+                    continue;
+                };
+                let Some(name) = part_head
+                    .split("name=\"")
+                    .nth(1)
+                    .and_then(|rest| rest.split('"').next())
+                else {
+                    continue;
+                };
+                let value = value.trim_end_matches("\r\n");
+                fields.insert(
+                    name.to_string(),
+                    serde_json::from_str(value).unwrap_or_else(|_| value.into()),
+                );
+            }
+            serde_json::Value::Object(fields)
+        }
+
+        fn find(haystack: &[u8], needle: &[u8]) -> Option<usize> {
+            haystack
+                .windows(needle.len())
+                .position(|window| window == needle)
+        }
+    }
+
     /// Replays a script and records what was sent, so tests can assert the
     /// user-visible text a path produced.
     pub(crate) struct MockSender {
@@ -260,6 +483,8 @@ pub(crate) mod test_support {
         messages: Mutex<Vec<String>>,
         captions: Mutex<Vec<String>>,
         answers: Mutex<Vec<Option<String>>>,
+        /// `(chat, message, text)` of every text rewrite, in order.
+        edited_texts: Mutex<Vec<(i64, i64, String)>>,
         /// Builds the error every `*Err` outcome returns (RequestError is not
         /// cloneable, so the factory recreates it per call).
         error: Box<dyn Fn() -> RequestError + Send + Sync>,
@@ -280,6 +505,7 @@ pub(crate) mod test_support {
                 messages: Mutex::new(Vec::new()),
                 captions: Mutex::new(Vec::new()),
                 answers: Mutex::new(Vec::new()),
+                edited_texts: Mutex::new(Vec::new()),
                 error: Box::new(error),
             }
         }
@@ -305,6 +531,11 @@ pub(crate) mod test_support {
             self.answers.lock().clone()
         }
 
+        /// `(chat, message, text)` of every `edit_message_text`, in order.
+        pub(crate) fn edited_texts(&self) -> Vec<(i64, i64, String)> {
+            self.edited_texts.lock().clone()
+        }
+
         fn next(&self, kind: &'static str) -> Outcome {
             self.calls.lock().push(kind);
             let script = self.script.lock();
@@ -411,6 +642,24 @@ pub(crate) mod test_support {
             })
         }
 
+        fn edit_message_text(
+            &self,
+            chat_id: ChatId,
+            message_id: MessageId,
+            text: String,
+        ) -> BoxFuture<'_, Result<(), RequestError>> {
+            // Always succeeds: the only caller is the expiry sweep, which
+            // tolerates a failure (a prompt the user already deleted), so the
+            // script stays free for the call the test is about.
+            Box::pin(async move {
+                self.calls.lock().push("edit_message_text");
+                self.edited_texts
+                    .lock()
+                    .push((chat_id.0, message_id.0 as i64, text));
+                Ok(())
+            })
+        }
+
         fn edit_message_caption(
             &self,
             _chat_id: ChatId,

crates/xmedia-bot/src/photo.rs

@@ -12,6 +12,7 @@
 //! and 24-bit RGB have no alpha channel).
 
 use std::io::Write;
+use std::sync::LazyLock;
 
 use fast_image_resize as fir;
 use tempfile::NamedTempFile;
@@ -26,9 +27,100 @@ pub const PHOTO_TARGET_DIMENSION_SUM: u32 = 9900;
 /// to a smaller media URL instead.
 pub const MAX_UPLOAD_BYTES: u64 = 10 * 1024 * 1024;
 /// Decode budget (bytes): a larger intermediate buffer is not worth the peak
-/// memory; the photo degrades to the smaller URL instead. Also the cap for
-/// downloading photos in the send fallback (they must be downloaded whole).
+/// memory; the photo degrades to the smaller URL instead.
 pub(crate) const MAX_DECODE_BYTES: u64 = 512 * 1024 * 1024;
+/// Cap for *downloading* a photo in the send fallback, kept separate from the
+/// decode budget above: the whole body is buffered before it is processed, once
+/// per download slot in flight, while the decode budget is about a single
+/// buffer. Telegram's upload cap is 10 MiB, so a photo this large can only be
+/// sent after a downscale that its reduced variant serves just as well — over
+/// the cap the item degrades to the smaller URL
+/// (`FallbackError::MediaTooLarge`), it is never an error.
+pub(crate) const MAX_PHOTO_DOWNLOAD_BYTES: u64 = 32 * 1024 * 1024;
+
+/// Size of one memory-budget unit. Small enough that ordinary photos do not
+/// queue behind each other, coarse enough that the semaphore is not a counter
+/// per megabyte.
+const MEMORY_UNIT_BYTES: u64 = 64 * 1024 * 1024;
+
+/// Process-wide memory budget for photo preparation, in [`MEMORY_UNIT_BYTES`]
+/// units: 512 MiB. `PREP_SLOTS` bounds how many items are prepared at once but
+/// not how much memory they hold — one photo's decode buffer can be up to
+/// [`MAX_DECODE_BYTES`] (512 MiB), and the guard that refuses a bigger one is
+/// per photo, so six concurrent photos could peak near 3 GiB on a host sized
+/// for a fraction of that. Each item charges what it actually holds (its
+/// downloaded bytes plus the decode buffer its header predicts), so a 10-image
+/// album of ordinary photos still runs several at a time while huge ones
+/// serialize.
+const MEMORY_UNITS: u32 = 8;
+
+static MEMORY_BUDGET: LazyLock<std::sync::Arc<tokio::sync::Semaphore>> =
+    LazyLock::new(|| std::sync::Arc::new(tokio::sync::Semaphore::new(MEMORY_UNITS as usize)));
+
+/// The buffer `w`×`h` needs in `channels` output channels — the one number the
+/// per-photo guards and the reservation below both use, so they cannot drift.
+fn decode_bytes(w: u32, h: u32, channels: usize) -> u64 {
+    (w as u64) * (h as u64) * channels as u64
+}
+
+/// Units to charge for `bytes`, clamped to the whole budget: an item must never
+/// ask for more than exists, or it would wait for itself forever.
+fn memory_units(bytes: u64) -> u32 {
+    bytes
+        .div_ceil(MEMORY_UNIT_BYTES)
+        .clamp(1, MEMORY_UNITS as u64) as u32
+}
+
+/// Reserves `bytes` of the preparation budget until the returned permit drops.
+pub(crate) async fn reserve_memory(bytes: u64) -> tokio::sync::OwnedSemaphorePermit {
+    reserve(std::sync::Arc::clone(&MEMORY_BUDGET), bytes).await
+}
+
+/// [`reserve_memory`] against a caller-chosen budget; the tests pass their own
+/// so they do not fight over the process-wide one.
+async fn reserve(
+    budget: std::sync::Arc<tokio::sync::Semaphore>,
+    bytes: u64,
+) -> tokio::sync::OwnedSemaphorePermit {
+    budget
+        .acquire_many_owned(memory_units(bytes))
+        .await
+        .expect("memory budget semaphore closed")
+}
+
+/// The decode buffer a downloaded photo will allocate, from its header alone —
+/// zero when it is already within Telegram's limits and is uploaded as-is, zero
+/// for a format [`prepare_photo`] does not decode. Mirrors the early return and
+/// the guard of the two branches below.
+pub(crate) fn decode_budget_bytes(bytes: &[u8]) -> u64 {
+    if let Some((w, h, _depth, color)) = parse_png_header(bytes) {
+        if within_limits(w, h, bytes) {
+            return 0;
+        }
+        return decode_bytes(w, h, output_channels(color));
+    }
+    if let Some((w, h)) = jpeg_dims(bytes) {
+        if within_limits(w, h, bytes) {
+            return 0;
+        }
+        return decode_bytes(w, h, 3);
+    }
+    0
+}
+
+/// Whether a photo is uploaded untouched (Telegram's dimension sum, and the
+/// upload cap its bytes are compared against).
+fn within_limits(w: u32, h: u32, bytes: &[u8]) -> bool {
+    w + h <= PHOTO_MAX_DIMENSION_SUM && bytes.len() as u64 <= MAX_UPLOAD_BYTES
+}
+
+/// JPEG dimensions from the headers, without decoding any pixels.
+fn jpeg_dims(bytes: &[u8]) -> Option<(u32, u32)> {
+    let mut decoder = zune_jpeg::JpegDecoder::new(std::io::Cursor::new(bytes));
+    decoder.decode_headers().ok()?;
+    let info = decoder.info()?;
+    Some((info.width as u32, info.height as u32))
+}
 /// JPEG output quality (1-100).
 const JPEG_QUALITY: u8 = 90;
 
@@ -199,6 +291,7 @@ fn encode_jpeg(pix: &PixBuf, w: u32, h: u32) -> Result<Vec<u8>, String> {
 
 fn write_temp(bytes: &[u8], ext: &str) -> Result<NamedTempFile, String> {
     let mut file = tempfile::Builder::new()
+        .prefix(x_media::TEMP_FILE_PREFIX)
         .suffix(&format!(".{ext}"))
         .tempfile()
         .map_err(|e| format!("temp file failed: {e}"))?;
@@ -231,7 +324,7 @@ fn prepare_png(file: NamedTempFile, bytes: &[u8]) -> Result<PhotoPrep, String> {
     );
 
     let channels = output_channels(color_type);
-    if (w as u64) * (h as u64) * channels as u64 > MAX_DECODE_BYTES {
+    if decode_bytes(w, h, channels) > MAX_DECODE_BYTES {
         log::warn!("photo decode buffer exceeds the memory budget; falling back to smaller media");
         return Ok(PhotoPrep::UseFallback);
     }
@@ -302,7 +395,7 @@ fn prepare_jpeg(file: NamedTempFile, bytes: &[u8]) -> Result<PhotoPrep, String>
     if w + h <= PHOTO_MAX_DIMENSION_SUM && !size_over {
         return Ok(PhotoPrep::Upload(file));
     }
-    if (w as u64) * (h as u64) * 3 > MAX_DECODE_BYTES {
+    if decode_bytes(w, h, 3) > MAX_DECODE_BYTES {
         log::warn!("photo decode buffer exceeds the memory budget; falling back to smaller media");
         return Ok(PhotoPrep::UseFallback);
     }
@@ -326,6 +419,7 @@ fn prepare_jpeg(file: NamedTempFile, bytes: &[u8]) -> Result<PhotoPrep, String>
 #[cfg(test)]
 mod tests {
     use super::*;
+    use std::time::Duration;
 
     fn png_header(w: u32, h: u32, depth: u8, color: u8) -> Vec<u8> {
         let mut bytes = b"\x89PNG\r\n\x1a\n\x00\x00\x00\rIHDR".to_vec();
@@ -335,6 +429,100 @@ mod tests {
         bytes
     }
 
+    /// The budget is a *process-wide* memory bound: `PREP_SLOTS` (6) caps how
+    /// many photos are prepared at once, but six max-size photos would still
+    /// hold six decode buffers of up to 512 MiB each.
+    #[tokio::test]
+    async fn huge_decodes_cannot_overlap_but_do_run_alone() {
+        let budget = std::sync::Arc::new(tokio::sync::Semaphore::new(MEMORY_UNITS as usize));
+        let max_photo = MAX_DECODE_BYTES + MAX_PHOTO_DOWNLOAD_BYTES;
+
+        // One max-size photo fits (clamped to the whole budget), so it can
+        // never wait for budget that cannot exist.
+        let first = tokio::time::timeout(
+            Duration::from_millis(50),
+            reserve(budget.clone(), max_photo),
+        )
+        .await
+        .expect("a max-size photo must not wait");
+        // A second one of the same size has to wait for the first to finish.
+        assert!(
+            tokio::time::timeout(
+                Duration::from_millis(50),
+                reserve(budget.clone(), max_photo)
+            )
+            .await
+            .is_err(),
+            "two max-size decodes overlapped"
+        );
+        drop(first);
+        assert!(
+            tokio::time::timeout(
+                Duration::from_millis(50),
+                reserve(budget.clone(), max_photo)
+            )
+            .await
+            .is_ok(),
+            "the budget was not released"
+        );
+    }
+
+    /// A 10-image album of ordinary photos must not serialize: they charge
+    /// their real (small) buffers, not a fixed heavyweight slot.
+    #[tokio::test]
+    async fn ordinary_photos_share_the_budget() {
+        let budget = std::sync::Arc::new(tokio::sync::Semaphore::new(MEMORY_UNITS as usize));
+        // A 4 MiB photo that decodes to ~36 MiB (4000x3000 RGB).
+        let ordinary = 4 * 1024 * 1024 + 36 * 1024 * 1024;
+        let mut held = Vec::new();
+        for i in 0..MEMORY_UNITS {
+            held.push(
+                tokio::time::timeout(Duration::from_millis(50), reserve(budget.clone(), ordinary))
+                    .await
+                    .unwrap_or_else(|_| panic!("ordinary photo {i} waited for budget")),
+            );
+        }
+    }
+
+    #[test]
+    fn memory_units_round_up_and_clamp() {
+        assert_eq!(memory_units(1), 1);
+        assert_eq!(memory_units(MEMORY_UNIT_BYTES), 1);
+        assert_eq!(memory_units(MEMORY_UNIT_BYTES + 1), 2);
+        // Never more than exists, or the item waits for itself forever.
+        assert_eq!(memory_units(u64::MAX), MEMORY_UNITS);
+        // One item's worst case (a max download plus a max decode) takes the
+        // whole budget by itself.
+        assert_eq!(
+            memory_units(MAX_DECODE_BYTES + MAX_PHOTO_DOWNLOAD_BYTES),
+            MEMORY_UNITS
+        );
+    }
+
+    /// What the reservation is charged is decided by the header, and it has to
+    /// agree with what the pipeline does: a photo uploaded as-is costs nothing,
+    /// one that gets processed costs its decoded buffer.
+    #[test]
+    fn decode_budget_follows_the_processing_decision() {
+        // 9999x2 (sum 10001) is over the dimension cap → processed → charged.
+        let oversized = png_header(9999, 2, 8, 2); // 8-bit RGB
+        assert_eq!(decode_budget_bytes(&oversized), 9999 * 2 * 3);
+        // Inside the limits (dimensions *and* bytes) → uploaded as-is.
+        let small = png_header(100, 100, 8, 2);
+        assert_eq!(decode_budget_bytes(&small), 0);
+        // A format the pipeline does not decode costs nothing either.
+        assert_eq!(decode_budget_bytes(b"GIF89a not a photo"), 0);
+
+        // JPEG: 9999x2 is over the cap, so its RGB decode buffer is charged.
+        let (w, h) = (9999u16, 2u16);
+        let rgb = vec![90u8; w as usize * h as usize * 3];
+        let mut bytes = Vec::new();
+        jpeg_encoder::Encoder::new(&mut bytes, 90)
+            .encode(&rgb, w, h, jpeg_encoder::ColorType::Rgb)
+            .unwrap();
+        assert_eq!(decode_budget_bytes(&bytes), 9999 * 2 * 3);
+    }
+
     #[test]
     fn parses_png_header() {
         let bytes = png_header(8979, 5316, 16, 6); // 16-bit RGBA
@@ -459,7 +647,10 @@ mod tests {
 
     #[test]
     fn pipeline_resizes_oversized_jpeg() {
-        // Build a small over-dimension JPEG with jpeg-encoder.
+        // Build a small over-dimension JPEG with jpeg-encoder: 9999x2 sums to
+        // one over the cap. The output's own headers are what must show the
+        // resize — a copy-through is a perfectly valid JPEG, so magic bytes
+        // and a non-empty buffer used to pass for nothing.
         let (w, h) = (9999u16, 2u16);
         let rgb = vec![90u8; (w as usize) * (h as usize) * 3];
         let mut bytes = Vec::new();
@@ -475,8 +666,15 @@ mod tests {
             PhotoPrep::Upload(file) => {
                 let out = std::fs::read(file.path()).unwrap();
                 assert!(out.starts_with(&[0xFF, 0xD8]), "output must stay jpeg");
-                // 9999x2 downscaled: the buffer length tells the new dims.
-                assert!(out.len() > 100);
+                let mut decoder = zune_jpeg::JpegDecoder::new(std::io::Cursor::new(out.as_slice()));
+                decoder.decode_headers().unwrap();
+                let info = decoder.info().unwrap();
+                let (nw, nh) = (info.width as u32, info.height as u32);
+                assert!(
+                    nw + nh <= PHOTO_MAX_DIMENSION_SUM,
+                    "still over the cap: {nw}x{nh}"
+                );
+                assert_ne!((nw, nh), (w as u32, h as u32), "output was not resized");
             }
             PhotoPrep::UseFallback => panic!("over-dimension JPEG should have been resized"),
         }

crates/xmedia-bot/src/queue.rs

@@ -17,6 +17,17 @@ use tokio::sync::Notify;
 use tokio::task::JoinHandle;
 
 pub const MAX_RETRIES: u32 = 2;
+
+/// Attempts for a *terminal* row write (delete / reschedule). These are not
+/// like a task retry: failing them leaves the row in `in_progress`, where the
+/// expiry sweep can re-run a task that already ran, so a contended DB gets a
+/// few quick chances before the caller falls back to a terminal state.
+const TERMINAL_WRITE_ATTEMPTS: u32 = 3;
+
+/// 100ms, 200ms, … between terminal write attempts.
+fn terminal_write_backoff(attempt: u32) -> Duration {
+    Duration::from_millis(100 * (1u64 << attempt.min(4)))
+}
 pub const LOCK_TTL_SECONDS: f64 = 120.0;
 
 /// Number of concurrent worker loops. Tasks are independent (retries and
@@ -57,8 +68,19 @@ struct LeasedRow {
     id: String,
     payload: String,
     attempts: i32,
+    /// Random token for *this* lease. Every write-back the worker makes is
+    /// guarded by it, so a lease that expired (heartbeat starved, host
+    /// suspended) and was re-leased by another worker cannot be written by
+    /// its former holder.
+    lease_token: String,
 }
 
+/// The row is no longer ours: its lease expired and another worker took it.
+/// The former holder must not write anything back — a `delete` would erase the
+/// new holder's row (or a `reschedule` would overwrite its retry state) — so
+/// the attempt stops at the next heartbeat instead.
+struct LeaseLost;
+
 /// Owned worker state so the spawned loop does not borrow the queue handle.
 #[derive(Clone)]
 struct QueueWorker {
@@ -70,21 +92,39 @@ struct QueueWorker {
 }
 
 /// Resets rows left `in_progress` with an expired lock TTL back to `pending`
-/// so they can be leased again (crash/panic recovery).
-fn recover_update(conn: &rusqlite::Connection) -> rusqlite::Result<()> {
+/// so they can be leased again (crash/panic recovery). Returns how many rows
+/// came back, which is what decides whether a worker needs waking.
+fn recover_update(conn: &rusqlite::Connection) -> rusqlite::Result<usize> {
     conn.execute(
         "UPDATE tasks SET status='pending', locked_until=0 WHERE status='in_progress' AND locked_until < ?1",
         params![now_f64()],
-    )?;
-    Ok(())
+    )
+}
+
+/// Runs [`recover_update`] and wakes a worker when something actually came
+/// back. A recovered row is due immediately, but every worker may be parked on
+/// `notify` — with no pending row there is no `earliest_run_after` to sleep on
+/// — so without this the recovered task waits for the next unrelated enqueue.
+/// Same permit semantics as `enqueue`: `notify_one` stores a permit when no
+/// worker is registered.
+async fn recover_expired(pool: &std::sync::Arc<crate::db::DbPool>, notify: &Notify) {
+    match pool.with_conn(move |conn| recover_update(conn)).await {
+        Ok(recovered) if recovered > 0 => {
+            log::warn!("queue: recovered {recovered} row(s) from an expired lease");
+            notify.notify_one();
+        }
+        Ok(_) => {}
+        Err(e) => log::error!("queue recovery failed: {e}"),
+    }
 }
 
 /// Base delay × 2^attempts (attempts = retries already done), capped at 300s.
 /// Applied at the queue layer so the attempt count actually reaches the
-/// backoff computation; Telegram `RetryAfter` delays get the same treatment
-/// (conservatively larger wait, no API change needed).
+/// backoff computation. The cap only ever scales *up*: a delay the server
+/// asked for (Telegram `RetryAfter`) must not be shortened, retrying earlier
+/// than allowed just re-triggers the flood control it came from.
 fn scaled_retry_delay(base: f64, attempts: i32) -> f64 {
-    (base * 2f64.powi(attempts)).min(300.0)
+    (base * 2f64.powi(attempts)).min(300.0).max(base)
 }
 
 impl PersistentTaskQueue {
@@ -113,7 +153,7 @@ impl PersistentTaskQueue {
         let handler: Arc<Handler> = Arc::new(move |payload| Box::pin(handler(payload)));
         let dead_letter: Arc<DeadLetter> =
             Arc::new(move |payload, message| Box::pin(dead_letter(payload, message)));
-        self.recover_stale().await;
+        recover_expired(&self.pool, &self.notify).await;
         let mut handles = Vec::with_capacity(QUEUE_WORKERS + 1);
         for _ in 0..QUEUE_WORKERS {
             let worker = QueueWorker {
@@ -133,6 +173,7 @@ impl PersistentTaskQueue {
         let sweep_pool = std::sync::Arc::clone(&self.pool);
         let sweep_notify = Arc::clone(&self.sweep_notify);
         let sweep_stop = Arc::clone(&self.stop);
+        let sweep_workers = Arc::clone(&self.notify);
         handles.push(tokio::spawn(async move {
             let mut interval = tokio::time::interval(Duration::from_secs(30));
             loop {
@@ -145,10 +186,7 @@ impl PersistentTaskQueue {
                 if sweep_stop.load(Ordering::Relaxed) {
                     break;
                 }
-                let result = sweep_pool.with_conn(move |conn| recover_update(conn)).await;
-                if let Err(e) = result {
-                    log::error!("queue sweep failed: {e}");
-                }
+                recover_expired(&sweep_pool, &sweep_workers).await;
             }
         }));
         *self.worker.lock() = handles;
@@ -192,16 +230,140 @@ impl PersistentTaskQueue {
         Ok(())
     }
 
-    async fn recover_stale(&self) {
-        self.recover_sweep().await;
+    /// Pending task count and the oldest `run_after`, for the periodic sweep's
+    /// health line. Deliberately separate from the worker's own
+    /// `earliest_run_after`: that one runs on every idle worker cycle and must
+    /// stay a single indexed `MIN`, while the count is only asked for once per
+    /// sweep.
+    /// `(id, payload)` of every row that can still run (`pending`,
+    /// `in_progress`). The startup repair reads these before the workers start:
+    /// with no worker running, no row can be leased while it writes.
+    pub async fn runnable_rows(&self) -> Vec<(String, String)> {
+        let result = self
+            .pool
+            .with_conn(|conn| {
+                let mut stmt = conn.prepare(
+                    "SELECT id, payload FROM tasks WHERE status IN ('pending', 'in_progress') ORDER BY run_after",
+                )?;
+                let rows = stmt.query_map([], |row| Ok((row.get(0)?, row.get(1)?)))?;
+                rows.collect::<rusqlite::Result<Vec<(String, String)>>>()
+            })
+            .await;
+        match result {
+            Ok(rows) => rows,
+            Err(e) => {
+                log::error!("queue row scan failed: {e}");
+                Vec::new()
+            }
+        }
     }
 
-    async fn recover_sweep(&self) {
-        let result = self.pool.with_conn(move |conn| recover_update(conn)).await;
-        if let Err(e) = result {
-            log::error!("queue recovery failed: {e}");
+    /// Replaces a runnable row's payload and restarts its attempt budget: the
+    /// new payload is a fresh delivery of the same task, so the retries it has
+    /// already spent do not carry over. Startup repair only — a worker's
+    /// write-back is lease-token guarded instead (`replace_payload` cannot race
+    /// one: it runs before any worker does).
+    pub async fn replace_payload(&self, id: &str, payload: &Value) -> bool {
+        let logged_id = id.to_string();
+        let (id, payload) = (id.to_string(), payload.to_string());
+        let result = self
+            .pool
+            .with_conn(move |conn| {
+                let affected = conn.execute(
+                    "UPDATE tasks SET payload=?1, attempts=0, run_after=?2, status='pending', locked_until=0 \
+                     WHERE id=?3 AND status IN ('pending', 'in_progress')",
+                    params![payload, now_f64(), id],
+                )?;
+                Ok(affected == 1)
+            })
+            .await;
+        match result {
+            Ok(true) => true,
+            Ok(false) => {
+                log::warn!("queue: row {logged_id} vanished before its payload could be replaced");
+                false
+            }
+            Err(e) => {
+                log::error!("queue payload replace failed for {logged_id}: {e}");
+                false
+            }
         }
     }
+
+    pub async fn pending_backlog(&self) -> Option<(i64, f64)> {
+        let result = self
+            .pool
+            .with_conn(|conn| {
+                let mut stmt = conn
+                    .prepare("SELECT COUNT(*), MIN(run_after) FROM tasks WHERE status='pending'")?;
+                let mut rows = stmt.query([])?;
+                match rows.next()? {
+                    Some(row) => {
+                        let count = row.get::<_, i64>(0)?;
+                        match row.get::<_, Option<f64>>(1)? {
+                            Some(oldest) if count > 0 => Ok(Some((count, oldest))),
+                            _ => Ok(None),
+                        }
+                    }
+                    None => Ok(None),
+                }
+            })
+            .await;
+        match result {
+            Ok(v) => v,
+            Err(e) => {
+                log::error!("queue backlog query failed: {e}");
+                None
+            }
+        }
+    }
+}
+
+/// Last-resort terminal state for a row whose `DELETE` would not go through:
+/// `done` is invisible to `lease_next` (`status='pending'`), to the expiry
+/// sweep (`status='in_progress'`) and to the backlog line, so a task that
+/// already ran cannot be leased and run again. Token-guarded like every other
+/// write-back: `Ok(false)` means the row was re-leased and is not ours to
+/// tombstone.
+async fn mark_done(
+    pool: &std::sync::Arc<crate::db::DbPool>,
+    id: &str,
+    lease_token: &str,
+) -> rusqlite::Result<bool> {
+    let id = id.to_string();
+    let lease_token = lease_token.to_string();
+    pool.with_conn(move |conn| {
+        let affected = conn.execute(
+            "UPDATE tasks SET status='done', locked_until=0 WHERE id = ?1 AND lease_token = ?2",
+            params![id, lease_token],
+        )?;
+        Ok(affected == 1)
+    })
+    .await
+}
+
+/// Which task a lease/retry/dead-letter line is about: the chat from the
+/// stored payload, plus the post's normalized cache key when the payload
+/// carries one (`ForwardMessages` has no source URL). Without these a queue
+/// line named only a row id, which is useless to whoever reads the log — the
+/// row id is assigned at insert time and appears nowhere else.
+///
+/// Built only when the line is actually logged (log arguments are lazy).
+fn row_fields(payload: &Value) -> String {
+    let chat = payload
+        .get("chat_id")
+        .or_else(|| payload.get("from_chat_id"))
+        .and_then(Value::as_i64);
+    let key = payload
+        .get("source_url")
+        .and_then(Value::as_str)
+        .map(crate::handlers::log_key);
+    match (chat, key) {
+        (Some(chat), Some(key)) => format!("chat={chat} [key={key}]"),
+        (Some(chat), None) => format!("chat={chat}"),
+        (None, Some(key)) => format!("[key={key}]"),
+        (None, None) => String::new(),
+    }
 }
 
 impl QueueWorker {
@@ -279,15 +441,17 @@ impl QueueWorker {
                 }
                 Err(e) => return Err(e),
             };
+            let lease_token = format!("{:016x}", rand::random::<u64>());
             tx.execute(
-                "UPDATE tasks SET status='in_progress', locked_until=?1 WHERE id=?2",
-                params![now + LOCK_TTL_SECONDS, id],
+                "UPDATE tasks SET status='in_progress', locked_until=?1, lease_token=?2 WHERE id=?3",
+                params![now + LOCK_TTL_SECONDS, lease_token, id],
             )?;
             tx.commit()?;
             Ok(Some(LeasedRow {
                 id,
                 payload,
                 attempts,
+                lease_token,
             }))
         })
         .await
@@ -325,17 +489,40 @@ impl QueueWorker {
             Ok(value) => value,
             Err(e) => {
                 log::error!("queue: unparseable payload for {}: {e}", row.id);
-                self.delete_row(&row.id).await;
+                self.delete_row(&row.id, &row.lease_token).await;
                 (self.dead_letter)(Value::Null, format!("invalid stored payload: {e}")).await;
                 return;
             }
         };
-        log::debug!("processing {} (attempt {})", row.id, row.attempts + 1);
-        let outcome = self.run_with_lease(&row.id, payload).await;
+        let fields = row_fields(&payload);
+        log::debug!(
+            "processing {} {fields} (attempt {})",
+            row.id,
+            row.attempts + 1
+        );
+        let attempt_started = std::time::Instant::now();
+        let outcome = match self
+            .run_with_lease(&row.id, &row.lease_token, payload)
+            .await
+        {
+            Ok(outcome) => outcome,
+            Err(LeaseLost) => {
+                // Another worker owns this row now and is delivering the same
+                // task: write nothing (no delete, no reschedule, no
+                // dead-letter) and leave it to them.
+                log::warn!(
+                    "queue: lost the lease on {} {fields} (attempt {}); abandoning this attempt",
+                    row.id,
+                    row.attempts + 1
+                );
+                return;
+            }
+        };
+        let attempt_ms = attempt_started.elapsed().as_millis();
         match outcome {
             Ok(()) => {
-                log::debug!("task {} completed", row.id);
-                self.delete_row(&row.id).await;
+                log::debug!("task {} {fields} completed in {attempt_ms}ms", row.id);
+                self.delete_row(&row.id, &row.lease_token).await;
             }
             Err(QueueError::Retryable {
                 delay_seconds,
@@ -348,26 +535,26 @@ impl QueueWorker {
                     // not restate its own wrapper — see `failure_text`.)
                     let message = "retries exhausted".to_string();
                     log::error!(
-                        "dead-lettering {}: {message} after {} attempt(s)",
+                        "dead-lettering {} {fields}: {message} after {} attempt(s)",
                         row.id,
                         row.attempts + 1
                     );
-                    self.delete_row(&row.id).await;
+                    self.delete_row(&row.id, &row.lease_token).await;
                     (self.dead_letter)(payload, message).await;
                 } else {
                     let delay = scaled_retry_delay(delay_seconds, row.attempts);
                     log::debug!(
-                        "task {} rescheduled in {delay:.1}s (attempt {})",
+                        "task {} {fields} attempt {} took {attempt_ms}ms, rescheduled in {delay:.1}s",
                         row.id,
                         row.attempts + 1
                     );
-                    self.reschedule(&row.id, payload, delay, row.attempts + 1)
+                    self.reschedule(&row.id, &row.lease_token, payload, delay, row.attempts + 1)
                         .await;
                 }
             }
             Err(QueueError::Permanent { message, payload }) => {
-                log::error!("dead-lettering {}: {message}", row.id);
-                self.delete_row(&row.id).await;
+                log::error!("dead-lettering {} {fields}: {message}", row.id);
+                self.delete_row(&row.id, &row.lease_token).await;
                 (self.dead_letter)(payload, message).await;
             }
         }
@@ -378,7 +565,12 @@ impl QueueWorker {
     /// The heartbeat is part of this future, not a separate spawned task: if
     /// the worker task dies (panic) the heartbeat dies with it and the sweep
     /// recovers the row exactly as before.
-    async fn run_with_lease(&self, id: &str, payload: Value) -> Result<(), QueueError> {
+    async fn run_with_lease(
+        &self,
+        id: &str,
+        lease_token: &str,
+        payload: Value,
+    ) -> Result<Result<(), QueueError>, LeaseLost> {
         let fut = (self.handler)(payload);
         tokio::pin!(fut);
         let mut interval = tokio::time::interval(Duration::from_secs(30));
@@ -386,59 +578,152 @@ impl QueueWorker {
         // just set by lease_next).
         interval.tick().await;
         let id_owned = id.to_string();
+        let token_owned = lease_token.to_string();
         loop {
             tokio::select! {
-                result = &mut fut => return result,
+                result = &mut fut => return Ok(result),
                 _ = interval.tick() => {
                     let now = now_f64();
                     let id = id_owned.clone();
+                    let token = token_owned.clone();
                     let result = self
                         .pool
                         .with_conn(move |conn| {
                             conn.execute(
-                                "UPDATE tasks SET locked_until=?1 WHERE id=?2 AND status='in_progress'",
-                                params![now + LOCK_TTL_SECONDS, id],
+                                "UPDATE tasks SET locked_until=?1 \
+                                 WHERE id=?2 AND status='in_progress' AND lease_token=?3",
+                                params![now + LOCK_TTL_SECONDS, id, token],
                             )
                         })
                         .await;
-                    if let Err(e) = result {
-                        log::error!("queue lease heartbeat failed: {e}");
+                    match result {
+                        // Still ours: the lease is extended.
+                        Ok(1) => {}
+                        // The row is no longer leased to us (another worker
+                        // re-leased it, or it is gone): dropping the handler
+                        // future here stops this attempt instead of racing the
+                        // new holder through the same send.
+                        Ok(_) => return Err(LeaseLost),
+                        Err(e) => log::error!("queue lease heartbeat failed: {e}"),
                     }
                 }
             }
         }
     }
 
-    async fn delete_row(&self, id: &str) {
-        let id = id.to_string();
-        let result = self
-            .pool
-            .with_conn(move |conn| {
-                conn.execute("DELETE FROM tasks WHERE id = ?1", params![id])?;
-                Ok(())
-            })
-            .await;
-        if let Err(e) = result {
-            log::error!("queue delete failed: {e}");
+    /// Deletes a finished row. A failure here is not cosmetic: the row would
+    /// stay `in_progress` with a live lease, the next sweep would flip it back
+    /// to `pending`, and the *completed* task would run again — a second album,
+    /// a second edit prompt, a second channel copy. So the delete is retried
+    /// (a busy/contended DB is the usual cause and clears), and if the DB still
+    /// refuses, the row is marked `done` — a status neither the lease query
+    /// (`pending`) nor the sweep (`in_progress`) looks at — so a task that
+    /// already ran can never be re-leased. Both writes failing is logged at
+    /// error level with the row id, since that is the one case where a
+    /// duplicate send stays possible.
+    async fn delete_row(&self, id: &str, lease_token: &str) {
+        for attempt in 0..TERMINAL_WRITE_ATTEMPTS {
+            match self.try_delete_row(id, lease_token).await {
+                Ok(true) => return,
+                // The row is not ours any more (re-leased while we worked):
+                // leaving it alone *is* the clean outcome — retrying or
+                // tombstoning here would erase the new holder's work.
+                Ok(false) => {
+                    log::warn!("queue: row {id} was re-leased; not deleting it");
+                    return;
+                }
+                Err(e) => {
+                    log::error!("queue delete failed (attempt {}): {e}", attempt + 1);
+                    tokio::time::sleep(terminal_write_backoff(attempt)).await;
+                }
+            }
+        }
+        match mark_done(&self.pool, id, lease_token).await {
+            Ok(true) => log::warn!("queue: row {id} marked done instead of deleted"),
+            Ok(false) => log::warn!("queue: row {id} was re-leased; nothing to tombstone"),
+            Err(e) => log::error!(
+                "queue: row {id} could not be deleted or marked done ({e}); \
+                 the expiry sweep may run this finished task again"
+            ),
         }
     }
 
-    async fn reschedule(&self, id: &str, payload: Value, delay_seconds: f64, attempts: i32) {
+    /// `Ok(false)` when the `WHERE` matched no row — the lease is not ours.
+    async fn try_delete_row(&self, id: &str, lease_token: &str) -> rusqlite::Result<bool> {
         let id = id.to_string();
+        let lease_token = lease_token.to_string();
+        self.pool
+            .with_conn(move |conn| {
+                let affected = conn.execute(
+                    "DELETE FROM tasks WHERE id = ?1 AND lease_token = ?2 AND status='in_progress'",
+                    params![id, lease_token],
+                )?;
+                Ok(affected == 1)
+            })
+            .await
+    }
+
+    /// Writes back a retryable attempt's state. A failure is retried: the row
+    /// would otherwise stay `in_progress`, and the expiry sweep would re-run
+    /// the attempt from its *previous* payload — re-sending batches the last
+    /// attempt had already delivered. Unlike [`Self::delete_row`] there is no
+    /// safe terminal fallback here (marking it done would drop the retry
+    /// without telling anyone), so a persistent failure is logged loudly and
+    /// the sweep's re-run — at-least-once, the documented trade — is named.
+    async fn reschedule(
+        &self,
+        id: &str,
+        lease_token: &str,
+        payload: Value,
+        delay_seconds: f64,
+        attempts: i32,
+    ) {
+        let row_id = id.to_string();
+        let lease_token = lease_token.to_string();
         let payload = payload.to_string();
-        let result = self.pool.with_conn(move |conn| {
-            conn.execute(
-                "UPDATE tasks SET payload=?1, run_after=?2, attempts=?3, status='pending', locked_until=0 WHERE id=?4",
-                params![payload, now_f64() + delay_seconds, attempts, id],
-            )?;
-            Ok(())
-        })
-        .await;
-        if let Err(e) = result {
-            log::error!("queue reschedule failed: {e}");
+        let run_after = now_f64() + delay_seconds;
+        let mut last_error = None;
+        for attempt in 0..TERMINAL_WRITE_ATTEMPTS {
+            let id = row_id.clone();
+            let lease_token = lease_token.clone();
+            let payload = payload.clone();
+            let result = self
+                .pool
+                .with_conn(move |conn| {
+                    let affected = conn.execute(
+                        "UPDATE tasks SET payload=?1, run_after=?2, attempts=?3, status='pending', locked_until=0 \
+                         WHERE id=?4 AND lease_token=?5 AND status='in_progress'",
+                        params![payload, run_after, attempts, id, lease_token],
+                    )?;
+                    Ok(affected == 1)
+                })
+                .await;
+            match result {
+                Ok(true) => {
+                    // Same permit semantics as enqueue: never lose the wakeup.
+                    self.notify.notify_one();
+                    return;
+                }
+                // Re-leased while we worked: the new holder owns the row and
+                // its retry, so writing our payload would overwrite progress.
+                Ok(false) => {
+                    log::warn!(
+                        "queue: row {row_id} was re-leased; not rescheduling it (the new holder decides)"
+                    );
+                    return;
+                }
+                Err(e) => {
+                    log::error!("queue reschedule failed (attempt {}): {e}", attempt + 1);
+                    last_error = Some(e.to_string());
+                    tokio::time::sleep(terminal_write_backoff(attempt)).await;
+                }
+            }
         }
-        // Same permit semantics as enqueue: never lose the wakeup.
-        self.notify.notify_one();
+        log::error!(
+            "queue: row {row_id} could not be rescheduled ({}); the expiry sweep will \
+             re-run this attempt from its previous state",
+            last_error.unwrap_or_default()
+        );
     }
 }
 
@@ -455,6 +740,26 @@ mod tests {
         assert_eq!(scaled_retry_delay(1.5, 1), 3.0);
         assert_eq!(scaled_retry_delay(1.0, 10), 300.0, "capped at 300s");
         assert_eq!(scaled_retry_delay(300.0, 0), 300.0);
+        // A server-asked delay above the cap is honoured, not truncated: a
+        // 1800s flood-control wait used to become 300s and earn another 429.
+        assert_eq!(scaled_retry_delay(1800.0, 0), 1800.0);
+        assert_eq!(scaled_retry_delay(1800.0, 1), 1800.0);
+    }
+
+    /// Puts a row into the state a worker holds while running it.
+    async fn set_lease(queue: &PersistentTaskQueue, id: &str, token: &str) {
+        let (id, token) = (id.to_string(), token.to_string());
+        queue
+            .pool
+            .with_conn(move |conn| {
+                conn.execute(
+                    "UPDATE tasks SET status='in_progress', lease_token=?1 WHERE id=?2",
+                    params![token, id],
+                )?;
+                Ok(())
+            })
+            .await
+            .unwrap();
     }
 
     async fn new_queue() -> (PersistentTaskQueue, tempfile::TempDir) {
@@ -489,6 +794,122 @@ mod tests {
         queue.stop().await;
     }
 
+    #[test]
+    fn row_fields_name_the_chat_and_the_post() {
+        // The payload shapes the three task variants store.
+        assert_eq!(
+            row_fields(&serde_json::json!({
+                "chat_id": 111,
+                "source_url": "https://x.com/u/status/1"
+            })),
+            "chat=111 [key=twitter:1]"
+        );
+        // A forward has no source URL; a chat id alone must still name the line.
+        assert_eq!(
+            row_fields(&serde_json::json!({"from_chat_id": 111, "to_chat_id": 222})),
+            "chat=111"
+        );
+        // Garbage in the payload must not panic a log line.
+        assert_eq!(row_fields(&serde_json::json!({"chat_id": "111"})), "");
+        assert_eq!(row_fields(&serde_json::Value::Null), "");
+    }
+
+    /// The row a leaked deletion would resurrect: `done` is invisible to the
+    /// lease query, so a task that already ran cannot be run again.
+    #[tokio::test]
+    async fn done_rows_are_never_leased() {
+        let (queue, _dir) = new_queue().await;
+        let runs = Arc::new(AtomicUsize::new(0));
+        queue
+            .enqueue(serde_json::json!({"chat_id": 1}), now_f64())
+            .await
+            .unwrap();
+        let id: String = queue
+            .pool
+            .with_conn(|conn| conn.query_row("SELECT id FROM tasks", [], |r| r.get(0)))
+            .await
+            .unwrap();
+        // A token that is not the row's is refused: only the lease holder can
+        // write the row back.
+        assert!(
+            !mark_done(&queue.pool, &id, "someone-elses-token")
+                .await
+                .unwrap(),
+            "a foreign lease must not be able to tombstone the row"
+        );
+        set_lease(&queue, &id, "ours").await;
+        assert!(mark_done(&queue.pool, &id, "ours").await.unwrap());
+
+        assert_eq!(
+            queue.pending_backlog().await,
+            None,
+            "a done row is not pending work"
+        );
+        let runs_worker = runs.clone();
+        queue
+            .start(
+                move |_payload| {
+                    runs_worker.fetch_add(1, AtomicOrdering::SeqCst);
+                    async { Ok(()) }
+                },
+                |_payload, _message| async {},
+            )
+            .await;
+        tokio::time::sleep(Duration::from_millis(300)).await;
+        assert_eq!(
+            runs.load(AtomicOrdering::SeqCst),
+            0,
+            "the finished row must not run again"
+        );
+        queue.stop().await;
+    }
+
+    #[tokio::test]
+    async fn pending_backlog_counts_only_unleased_rows() {
+        let (queue, _dir) = new_queue().await;
+        assert_eq!(queue.pending_backlog().await, None, "empty queue");
+
+        let due = now_f64();
+        queue
+            .enqueue(serde_json::json!({"chat_id": 1}), due)
+            .await
+            .unwrap();
+        queue
+            .enqueue(serde_json::json!({"chat_id": 2}), due + 600.0)
+            .await
+            .unwrap();
+        // Hold the first row in the handler so it is leased, not pending: a
+        // health line that reported work already in flight as backlog would be
+        // lying about the queue.
+        let release = Arc::new(tokio::sync::Notify::new());
+        let held = release.clone();
+        queue
+            .start(
+                move |_payload| {
+                    let held = held.clone();
+                    async move {
+                        held.notified().await;
+                        Ok(())
+                    }
+                },
+                |_payload, _message| async {},
+            )
+            .await;
+        tokio::time::sleep(Duration::from_millis(300)).await;
+        assert_eq!(
+            queue.pending_backlog().await.map(|(n, _)| n),
+            Some(1),
+            "the leased row is not pending"
+        );
+        let (_, oldest) = queue.pending_backlog().await.unwrap();
+        assert!(
+            (oldest - (due + 600.0)).abs() < 1.0,
+            "oldest is the earliest run_after: {oldest}"
+        );
+        release.notify_one();
+        queue.stop().await;
+    }
+
     #[tokio::test]
     async fn retryable_reschedules_then_dead_letters() {
         let (queue, _dir) = new_queue().await;
@@ -528,6 +949,51 @@ mod tests {
         queue.stop().await;
     }
 
+    #[tokio::test]
+    async fn runnable_rows_and_payload_replacement() {
+        let (queue, _dir) = new_queue().await;
+        queue
+            .enqueue(serde_json::json!({"s": 1}), now_f64())
+            .await
+            .unwrap();
+        let rows = queue.runnable_rows().await;
+        assert_eq!(rows.len(), 1);
+        let (id, payload) = rows[0].clone();
+        assert_eq!(payload, "{\"s\":1}");
+
+        // A replacement restarts the attempt budget (the new payload is a fresh
+        // delivery, not the continuation of the old one).
+        {
+            let id_owned = id.clone();
+            queue
+                .pool
+                .with_conn(move |conn| {
+                    conn.execute("UPDATE tasks SET attempts=2 WHERE id=?1", params![id_owned])?;
+                    Ok(())
+                })
+                .await
+                .unwrap();
+        }
+        assert!(
+            queue
+                .replace_payload(&id, &serde_json::json!({"s": 2}))
+                .await
+        );
+        let rows = queue.runnable_rows().await;
+        assert_eq!(rows[0].1, "{\"s\":2}");
+        assert_eq!(
+            queue.pending_backlog().await.map(|(n, _)| n),
+            Some(1),
+            "a repaired row is pending work again"
+        );
+        // A row that is gone (or done) is not rewritten.
+        assert!(
+            !queue
+                .replace_payload("task_missing", &serde_json::json!({}))
+                .await
+        );
+    }
+
     #[tokio::test]
     async fn permanent_error_dead_letters_immediately() {
         let (queue, _dir) = new_queue().await;
@@ -598,7 +1064,12 @@ mod tests {
         queue.stop().await;
     }
 
-    #[tokio::test]
+    /// A row that goes stale *after* startup is picked up by the periodic
+    /// sweep — the spawned task, its 30 s interval included — and the worker
+    /// that sweeps it gets woken. The paused clock is what makes this the real
+    /// test: this used to call the recovery by hand, which proved the SQL but
+    /// left the wiring free to be deleted.
+    #[tokio::test(start_paused = true)]
     async fn runtime_sweep_recovers_expired_lease() {
         let (queue, _dir) = new_queue().await;
         let calls = Arc::new(AtomicUsize::new(0));
@@ -613,8 +1084,12 @@ mod tests {
                 |_payload, _message| async {},
             )
             .await;
-        // Insert a stale leased row AFTER startup: without a runtime sweep it
-        // would stay `in_progress` forever (only start() used to recover).
+        // Let every worker park and the sweep consume its immediate first tick,
+        // so only a later tick can see the row. The clock is paused: yields do
+        // not advance it, and the sleep below does.
+        for _ in 0..16 {
+            tokio::task::yield_now().await;
+        }
         {
             let conn = rusqlite::Connection::open(queue.pool.path()).unwrap();
             conn.execute(
@@ -624,12 +1099,18 @@ mod tests {
             )
             .unwrap();
         }
-        queue.recover_sweep().await;
-        tokio::time::sleep(Duration::from_millis(300)).await;
+        assert_eq!(
+            calls.load(AtomicOrdering::SeqCst),
+            0,
+            "the row is stale but no sweep has run since it appeared"
+        );
+
+        tokio::time::sleep(Duration::from_secs(31)).await;
+
         assert_eq!(
             calls.load(AtomicOrdering::SeqCst),
             1,
-            "expired lease must be recovered and processed exactly once"
+            "the periodic sweep must recover the row and wake a worker"
         );
         queue.stop().await;
     }

crates/xmedia-bot/src/rate_limit.rs

@@ -1,12 +1,13 @@
 //! Per-chat token-bucket rate limiting.
 //!
-//! Telegram throttles bots that burst past a chat's message budget
-//! (roughly 20 messages/min for channels/groups); today the bot absorbs
-//! those 429s with queue retries. This limiter smooths the burst *before*
-//! it reaches the API: media sends to a chat consume one token per
-//! message, refilled at [`REFILL_PER_SEC`], so a batch forward paces itself
-//! instead of tripping flood control. The queue retry stays as the safety
-//! net for limits this bucket does not model (global per-bot limits etc.).
+//! Telegram throttles bots on two budgets: one per chat (roughly 20
+//! messages/min for channels/groups) and a bot-wide one (~30 messages per
+//! second). Both are smoothed here *before* the burst reaches the API — the
+//! per-chat bucket charges one token per message, and [`acquire_global`]
+//! charges the same spend against the bot-wide budget, which no per-chat
+//! bucket can see (a forward fanned out over many chats spends one token in
+//! each and nothing anywhere). The queue retry stays as the safety net for
+//! whatever neither bucket models.
 
 use parking_lot::Mutex;
 use std::collections::HashMap;
@@ -19,6 +20,12 @@ const CAPACITY: f64 = 20.0;
 /// Sustained refill: ~20 messages per minute.
 const REFILL_PER_SEC: f64 = 20.0 / 60.0;
 
+/// The bot-wide budget: Telegram allows roughly 30 messages per second for a
+/// bot in total, independently of the per-chat limits. Set to the documented
+/// ceiling, so it only ever binds on a cross-chat burst.
+const GLOBAL_CAPACITY: f64 = 30.0;
+const GLOBAL_REFILL_PER_SEC: f64 = 30.0;
+
 struct State {
     /// Current token balance; may go negative (debt from an acquire larger
     /// than the capacity, repaid by subsequent refills).
@@ -84,6 +91,15 @@ impl TokenBucket {
         tokio::time::sleep(Duration::from_secs_f64(wait)).await;
     }
 
+    /// Current balance, for the tests that assert a call site charged the
+    /// bucket (a charge is otherwise only observable as a delay).
+    #[cfg(test)]
+    pub(crate) fn tokens(&self) -> f64 {
+        let mut state = self.state.lock();
+        self.refill(&mut state);
+        state.tokens
+    }
+
     /// True when the bucket has refilled to capacity: no debt outstanding, so
     /// the chat has not sent anything recently.
     fn is_idle(&self) -> bool {
@@ -107,6 +123,17 @@ pub fn limiter_for(chat_id: i64) -> Arc<TokenBucket> {
         .clone()
 }
 
+/// The one bucket every chat shares: Telegram's bot-wide budget.
+static GLOBAL_LIMITER: LazyLock<TokenBucket> =
+    LazyLock::new(|| TokenBucket::new(GLOBAL_CAPACITY, GLOBAL_REFILL_PER_SEC));
+
+/// Waits for `n` messages' worth of the bot-wide budget. Called by the send
+/// paths next to their per-chat [`limiter_for`]: at ~30/s it does not bind on
+/// a single chat, but a batch fanned out over many chats has no other guard.
+pub async fn acquire_global(n: f64) {
+    GLOBAL_LIMITER.acquire(n).await;
+}
+
 /// Drops limiters that are idle (refilled to capacity, so the chat has not
 /// sent recently) and are not still held by an in-flight sender. The map
 /// would otherwise keep one bucket per chat that ever sent media, forever.
@@ -160,6 +187,21 @@ mod tests {
         );
     }
 
+    #[tokio::test(start_paused = true)]
+    async fn the_global_budget_is_paced_and_shared() {
+        // Drain the process-wide budget (no other test touches it: the send
+        // paths that use it are mocked), then prove the next message waits for
+        // the refill instead of going out instantly.
+        acquire_global(GLOBAL_CAPACITY).await;
+        let start = tokio::time::Instant::now();
+        acquire_global(1.0).await;
+        assert!(
+            start.elapsed() >= Duration::from_secs_f64(1.0 / GLOBAL_REFILL_PER_SEC),
+            "a fanned-out burst must be paced: elapsed {:?}",
+            start.elapsed()
+        );
+    }
+
     #[tokio::test(start_paused = true)]
     async fn prune_idle_drops_full_unheld_buckets_only() {
         // Held by this task: kept even at full capacity, a sender has it.

crates/xmedia-bot/src/send/mod.rs

@@ -29,7 +29,7 @@ use upload::{FallbackError, PreparedItem, prepare_upload_item, send_batch_via_up
 // parts other modules use so call sites stay `send::x`.
 pub(crate) use post_send::{
     EDIT_PROMPT_EXPIRED_TEXT, KEEP_ALIVE, Settled, dead_letter_notify, enqueue_retry, handle_task,
-    post_send_actions, settle_task,
+    notify_failure, post_send_actions, settle_task,
 };
 
 /// One process-wide Bot for queue workers. Building a fresh Bot (and its HTTP
@@ -143,7 +143,7 @@ impl Task {
         }
     }
 
-    fn source_url(&self) -> Option<&str> {
+    pub(crate) fn source_url(&self) -> Option<&str> {
         match self {
             Task::SendMediaSequence { source_url, .. } | Task::SendAnimation { source_url, .. } => {
                 Some(source_url)
@@ -173,9 +173,42 @@ impl Task {
         }
     }
 
+    /// The chat this task delivers media to (`None` for a channel copy, which
+    /// names two chats instead).
+    pub(crate) fn chat_id(&self) -> Option<i64> {
+        match self {
+            Task::SendMediaSequence { chat_id, .. } | Task::SendAnimation { chat_id, .. } => {
+                Some(*chat_id)
+            }
+            Task::ForwardMessages { .. } => None,
+        }
+    }
+
+    /// Where a failure notice for this task goes (both `None` for a copy with
+    /// nothing to notify).
+    pub(crate) fn notify_target(&self) -> (Option<i64>, Option<i64>) {
+        match self {
+            Task::SendMediaSequence {
+                notify_chat_id,
+                notify_message_id,
+                ..
+            }
+            | Task::SendAnimation {
+                notify_chat_id,
+                notify_message_id,
+                ..
+            }
+            | Task::ForwardMessages {
+                notify_chat_id,
+                notify_message_id,
+                ..
+            } => (*notify_chat_id, *notify_message_id),
+        }
+    }
+
     /// Local file paths referenced by this task's media (ugoira / bsky remux
     /// MP4 and the like); empty for URL or Telegram file-id sends.
-    fn local_media_paths(&self) -> Vec<std::path::PathBuf> {
+    pub(crate) fn local_media_paths(&self) -> Vec<std::path::PathBuf> {
         let mut out = Vec::new();
         for item in self.media_items() {
             let is_file_id = match item {
@@ -225,6 +258,9 @@ fn collect_file_ids(messages: &[Message], batch: &[MediaItemPayload], out: &mut
             out.push(CachedMedia {
                 kind: kind_of_item(item),
                 file_id,
+                // A fresh send's item is the source URL (file ids only appear
+                // in a *cached* send, and `cache_sent_task` skips those).
+                url: item_url(item).to_string(),
             });
         }
     }
@@ -271,7 +307,7 @@ pub fn retry_delay_seconds(attempts: u32) -> f64 {
 /// these errors are handled by the download-and-reupload fallback, NOT by a
 /// queue retry (resending the URL cannot succeed).
 pub fn is_media_fetch_failure(e: &ApiError) -> bool {
-    const MARKERS: [&str; 6] = [
+    const MARKERS: [&str; 7] = [
         "webpage_media_empty",
         "media_empty",
         "empty_web_media",
@@ -280,6 +316,11 @@ pub fn is_media_fetch_failure(e: &ApiError) -> bool {
         // Oversized photos (width + height > 10000 px) are rejected on URL
         // sends too; route them to the download-and-resize fallback.
         "photo_invalid_dimensions",
+        // Telegram refused to fetch the URL it was handed. Single-media URL
+        // sends answer with this one (the media-group verbs use the
+        // `webpage_*`/`media_empty` markers above), and it is exactly the
+        // case the download-and-reupload fallback exists for.
+        "failed to get http url content",
     ];
     let description = e.to_string().to_lowercase();
     MARKERS.iter().any(|marker| description.contains(marker))
@@ -320,10 +361,31 @@ pub fn classify_request_error(e: &RequestError) -> Classification {
         RequestError::Network(_) => Classification::Retryable {
             delay_seconds: retry_delay_seconds(0),
         },
+        // A 5xx from the API — or from a proxy in front of it — is transient.
+        // teloxide only sleeps 10s on a server error and then parses whatever
+        // body came back, so by the time we see the error the HTTP status is
+        // gone: a JSON 5xx body arrives as an unknown description, an HTML
+        // error page as `InvalidJson`. Both used to be Permanent, which
+        // dead-lettered a post over a Telegram-side blip.
+        RequestError::Api(api) if is_server_error_text(&api.to_string()) => {
+            Classification::Retryable {
+                delay_seconds: retry_delay_seconds(0),
+            }
+        }
         RequestError::Api(api) if is_media_fetch_failure(api) => Classification::MediaFetchFailure,
         RequestError::Api(api) => Classification::Permanent {
             message: api.to_string(),
         },
+        // An unparsable body can only come from something that is not the Bot
+        // API (which always answers JSON): a 5xx/error page from an
+        // intermediary, cut off mid-response. A JSON body that merely does not
+        // match the expected type cannot be fixed by retrying, so that case
+        // stays permanent.
+        RequestError::InvalidJson { raw, .. } if !raw.trim_start().starts_with('{') => {
+            Classification::Retryable {
+                delay_seconds: retry_delay_seconds(0),
+            }
+        }
         RequestError::MigrateToChatId(_)
         | RequestError::InvalidJson { .. }
         | RequestError::Io(_) => Classification::Permanent {
@@ -332,6 +394,21 @@ pub fn classify_request_error(e: &RequestError) -> Classification {
     }
 }
 
+/// Descriptions a 5xx carries when its body *is* JSON (teloxide keeps only the
+/// description text, never the status code). Matched like the media-fetch
+/// markers below; anything unmatched stays permanent, so a new permanent API
+/// error is not retried just because it is unfamiliar.
+fn is_server_error_text(description: &str) -> bool {
+    const MARKERS: [&str; 4] = [
+        "server error",
+        "bad gateway",
+        "gateway timeout",
+        "service unavailable",
+    ];
+    let description = description.to_lowercase();
+    MARKERS.iter().any(|marker| description.contains(marker))
+}
+
 /// Task boxed to keep the error size within `result_large_err` limits.
 #[derive(Debug)]
 pub enum SendError {
@@ -610,7 +687,7 @@ pub async fn send_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Vec<i64
     {
         Ok(message) => {
             let id = message.id.0 as i64;
-            cache_animation_send(ctx, task, &message).await;
+            cache_animation_send(ctx, task, &message, media_url).await;
             Ok(vec![id])
         }
         Err(RequestError::Api(api)) if is_media_fetch_failure(&api) || is_size_error(&api) => {
@@ -645,7 +722,7 @@ pub async fn send_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Vec<i64
                     {
                         Ok(message) => {
                             let id = message.id.0 as i64;
-                            cache_animation_send(ctx, task, &message).await;
+                            cache_animation_send(ctx, task, &message, media_url).await;
                             Ok(vec![id])
                         }
                         Err(e) => Err(classify_to_send_error(
@@ -710,20 +787,19 @@ pub async fn forward_messages(ctx: &AppContext<'_>, task: &Task) -> Result<(), S
 
 #[cfg(test)]
 mod tests {
-    use super::post_send::build_edit_markup;
+    use super::post_send::{build_edit_markup, cache_sent_task};
     use super::upload::sniff_ext;
     use super::*;
-    use crate::ctx::test_support::TestStores;
+    use crate::ctx::test_support::{TestStores, cached_photo};
     use std::collections::HashMap;
     use std::time::Duration;
 
     #[test]
     fn oversized_photo_boundary() {
-        // The empirical Telegram limit: sum 10000 passes, 10001 fails.
+        // The empirical Telegram limit: sum 10000 passes, 10001 fails. Pinned
+        // cross-crate because `photo.rs` and `upload.rs` both branch on it.
         // Const-block asserts so clippy's assertions_on_constants stays quiet.
         const { assert!(crate::photo::PHOTO_MAX_DIMENSION_SUM == 10000) };
-        const { assert!(6100 + 3900 <= crate::photo::PHOTO_MAX_DIMENSION_SUM) };
-        const { assert!(6300 + 3730 > crate::photo::PHOTO_MAX_DIMENSION_SUM) };
     }
 
     #[test]
@@ -858,7 +934,7 @@ mod tests {
         // A send failure names the post (the cache key) and the cause, so the
         // user knows which of their links died.
         let task = sequence_task("https://x.com/u/status/1");
-        let text = super::post_send::failure_text(Some(&task), "retries exhausted");
+        let text = super::post_send::failure_text(task.source_url(), "retries exhausted");
         assert!(text.contains("twitter:1"), "{text}");
         assert!(text.contains("retries exhausted"), "{text}");
 
@@ -871,7 +947,7 @@ mod tests {
             notify_chat_id: None,
             notify_message_id: None,
         };
-        let text = super::post_send::failure_text(Some(&forward), "chat not found");
+        let text = super::post_send::failure_text(forward.source_url(), "chat not found");
         assert!(text.starts_with("Forward failed permanently"), "{text}");
         assert!(text.contains("chat not found"), "{text}");
     }
@@ -918,6 +994,15 @@ mod tests {
         }
     }
 
+    #[test]
+    fn is_media_fetch_failure_matches_the_single_media_url_description() {
+        // `sendPhoto`/`sendAnimation`-style URL sends answer with this one
+        // instead of the `webpage_*` markers; without it the URL send failed
+        // permanently instead of going through the reupload fallback.
+        let api = ApiError::Unknown("Bad Request: failed to get HTTP URL content".into());
+        assert!(is_media_fetch_failure(&api));
+    }
+
     #[test]
     fn is_size_error_matches_known_errors() {
         // 413 upload cap.
@@ -979,6 +1064,39 @@ mod tests {
             classify_request_error(&e),
             Classification::MediaFetchFailure
         ));
+        // A server-error description (teloxide drops the HTTP status, so a
+        // JSON 5xx arrives as an unknown description) -> Retryable. Without
+        // this a Telegram 502 dead-lettered the post.
+        let e = RequestError::Api(ApiError::Unknown("Internal Server Error".into()));
+        assert!(matches!(
+            classify_request_error(&e),
+            Classification::Retryable { .. }
+        ));
+        // An HTML/proxy error page in place of the API's JSON -> Retryable.
+        let e = RequestError::InvalidJson {
+            source: std::sync::Arc::new(
+                serde_json::from_str::<serde_json::Value>("<html>502</html>").unwrap_err(),
+            ),
+            raw: "<html>502 Bad Gateway</html>".into(),
+        };
+        assert!(matches!(
+            classify_request_error(&e),
+            Classification::Retryable { .. }
+        ));
+        // A JSON body of the wrong shape is a type mismatch, not a transport
+        // problem: still permanent.
+        // (The `source` is only ever rendered, so an unrelated parse error
+        // stands in for the shape mismatch; `raw` is what the classifier reads.)
+        let e = RequestError::InvalidJson {
+            source: std::sync::Arc::new(
+                serde_json::from_str::<serde_json::Value>("x").unwrap_err(),
+            ),
+            raw: "{\"ok\":true,\"result\":true}".into(),
+        };
+        assert!(matches!(
+            classify_request_error(&e),
+            Classification::Permanent { .. }
+        ));
         // MigrateToChatId -> Permanent
         let e = RequestError::MigrateToChatId(ChatId(123));
         assert!(matches!(
@@ -1281,30 +1399,48 @@ mod tests {
         assert_eq!(sender.calls(), vec!["send_animation", "send_animation"]);
     }
 
+    /// A media group through a **real** `Bot` — its request building, the
+    /// per-chat limiter, the bot-wide budget — against a stand-in API. The
+    /// scripted mock bypasses `media_sender`'s implementation entirely, so a
+    /// call site that stops charging the limiters (or a broken request shape)
+    /// is invisible to every other test.
     #[tokio::test]
-    async fn media_group_success_and_forward_ok() {
-        // GroupOk: the group send succeeds (empty message list → no file ids
-        // collected, the batch counts as sent). CopyOk: the forward succeeds.
-        let dir = tempfile::tempdir().unwrap();
-        let file = dir.path().join("media.jpg");
-        std::fs::write(&file, b"not-a-real-jpeg").unwrap();
-        let sender = MockSender::scripted(vec![Outcome::GroupOk], media_fetch_error);
-        let stores = TestStores::new();
-        let ctx = stores.ctx(&sender);
-        let task = sequence_task(file.to_str().unwrap());
-        let result = send_media_sequence(&ctx, &task).await;
-        assert!(result.is_ok(), "got {result:?}");
+    async fn a_media_group_reaches_the_api_through_a_real_bot() {
+        use crate::media_sender::test_support::fake_api::FakeApi;
+        use teloxide::Bot;
 
-        let sender = MockSender::scripted(vec![Outcome::CopyOk], media_fetch_error);
-        let ctx = stores.ctx(&sender);
-        let task = Task::ForwardMessages {
-            from_chat_id: 1,
-            to_chat_id: 2,
-            message_ids: vec![3],
-            notify_chat_id: None,
-            notify_message_id: None,
-        };
-        assert!(forward_messages(&ctx, &task).await.is_ok());
+        let api = FakeApi::start().await;
+        let bot = Bot::new("42:TEST").set_api_url(api.url());
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&bot);
+        // A chat of its own: the limiter buckets are process-wide.
+        let mut task = sequence_task("https://cdn.example/1.jpg");
+        if let Task::SendMediaSequence { chat_id, .. } = &mut task {
+            *chat_id = 987_654;
+        }
+        let bucket = crate::rate_limit::limiter_for(987_654);
+        let before = bucket.tokens();
+
+        let outcome = send_media_sequence(&ctx, &task).await;
+        eprintln!(
+            "SCRATCH send methods={:?} outcome={outcome:?}",
+            api.methods()
+        );
+        assert!(outcome.is_ok());
+
+        // The request teloxide built: one group, the URL, the caption on the
+        // first item.
+        assert_eq!(api.methods(), vec!["SendMediaGroup"]);
+        let body = api.body("SendMediaGroup");
+        assert_eq!(body["chat_id"], 987_654);
+        assert_eq!(body["media"][0]["media"], "https://cdn.example/1.jpg");
+        assert_eq!(body["media"][0]["caption"], "cap");
+        // …and the send charged the pace limiter before it went out.
+        let after = bucket.tokens();
+        assert!(
+            after < before,
+            "a send must charge the chat's budget ({before} -> {after})"
+        );
     }
 
     #[tokio::test]
@@ -1362,7 +1498,7 @@ mod tests {
             *notify_message_id = None;
         }
         let dir_path = dir.path().to_path_buf();
-        KEEP_ALIVE.lock().push(dir);
+        KEEP_ALIVE.lock().push(std::sync::Arc::new(dir));
 
         // No chat to notify → the notify path sends nothing (its mock would
         // have no scripted outcome left).
@@ -1505,33 +1641,78 @@ mod tests {
             forward_channel_id: None,
             notify_chat_id: None,
             notify_message_id: None,
-            cache_data: Some(CachedPost {
-                url: "https://x.com/u/status/1".into(),
-                caption: "cap".into(),
-                title: "t".into(),
-                content: "c".into(),
-                author: "a".into(),
-                author_url: "au".into(),
-                tags: String::new(),
-                sensitive: false,
-                media: vec![CachedMedia {
-                    kind: CachedMediaKind::Photo,
-                    file_id: "AgAC-file-id".into(),
-                }],
-            }),
+            cache_data: Some(cached_photo()),
         }
     }
 
+    #[tokio::test]
+    async fn a_degraded_entry_regains_the_file_ids_a_send_produced() {
+        let sender = MockSender::scripted(vec![], media_fetch_error);
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&sender);
+        // A degraded entry: no file ids, URL only (what `invalidate_cache`
+        // leaves behind).
+        let mut degraded = cached_photo();
+        degraded.media[0].file_id.clear();
+        stores.link_cache().put("twitter:1", &degraded).await;
+        let mut task = cached_sequence_task();
+        if let Task::SendMediaSequence { cache_data, .. } = &mut task {
+            *cache_data = Some(degraded.clone());
+        }
+
+        cache_sent_task(
+            &ctx,
+            &task,
+            vec![CachedMedia {
+                kind: CachedMediaKind::Photo,
+                file_id: "fresh-id".into(),
+                url: "https://pbs.twimg.com/media/photo.jpg".into(),
+            }],
+        )
+        .await;
+
+        let entry = stores
+            .link_cache()
+            .get("twitter:1", Duration::from_secs(3600))
+            .await
+            .expect("the entry must still be there");
+        assert_eq!(
+            entry.media[0].file_id, "fresh-id",
+            "a degraded entry must take the ids its send produced"
+        );
+
+        // A send served from a healthy entry must not rewrite it: the ids it
+        // already holds are exactly what the next repeat wants. Which of the
+        // two a send was is the *task's* cache snapshot — a healthy one carries
+        // file ids.
+        cache_sent_task(
+            &ctx,
+            &cached_sequence_task(),
+            vec![CachedMedia {
+                kind: CachedMediaKind::Photo,
+                file_id: "other-id".into(),
+                url: String::new(),
+            }],
+        )
+        .await;
+        let entry = stores
+            .link_cache()
+            .get("twitter:1", Duration::from_secs(3600))
+            .await
+            .unwrap();
+        assert_eq!(
+            entry.media[0].file_id, "fresh-id",
+            "a healthy entry is left alone"
+        );
+    }
+
     #[tokio::test]
     async fn settled_sent_keeps_the_cache_entry() {
         let sender = MockSender::scripted(vec![], media_fetch_error);
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
         let task = cached_sequence_task();
-        stores
-            .link_cache()
-            .put("twitter:1", &cached_sequence_cache_data())
-            .await;
+        stores.link_cache().put("twitter:1", &cached_photo()).await;
 
         settle_task(&ctx, &task, Settled::Sent).await;
 
@@ -1546,35 +1727,36 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn settled_failed_drops_the_cache_entry() {
+    async fn settled_failed_degrades_the_cache_entry_then_drops_it() {
         let sender = MockSender::scripted(vec![], media_fetch_error);
         let stores = TestStores::new();
         let ctx = stores.ctx(&sender);
         let task = cached_sequence_task();
-        stores
-            .link_cache()
-            .put("twitter:1", &cached_sequence_cache_data())
-            .await;
+        stores.link_cache().put("twitter:1", &cached_photo()).await;
 
         settle_task(&ctx, &task, Settled::Failed).await;
 
+        // The file id is what failed, not the media: the entry survives with
+        // its source URLs, so the next request re-sends without a fetch.
+        let entry = stores
+            .link_cache()
+            .get("twitter:1", Duration::from_secs(3600))
+            .await
+            .expect("a failed cached send must not drop the entry outright");
+        assert_eq!(entry.media.len(), 1);
+        assert!(entry.media[0].file_id.is_empty(), "the stale id must go");
+        assert_eq!(entry.media[0].url, "https://pbs.twimg.com/media/photo.jpg");
+        assert_eq!(entry.caption, "cap", "the text is still good");
+
+        // A second failure — this time the URLs did not work either — drops it.
+        settle_task(&ctx, &task, Settled::Failed).await;
         assert!(
             stores
                 .link_cache()
                 .get("twitter:1", Duration::from_secs(3600))
                 .await
                 .is_none(),
-            "a permanently failed cached send must drop the entry"
+            "a degraded entry that fails again must be dropped"
         );
     }
-
-    fn cached_sequence_cache_data() -> CachedPost {
-        match cached_sequence_task() {
-            Task::SendMediaSequence {
-                cache_data: Some(post),
-                ..
-            } => post,
-            other => panic!("expected a cached sequence task, got {other:?}"),
-        }
-    }
 }

crates/xmedia-bot/src/send/post_send.rs

@@ -7,7 +7,7 @@ use super::{SendError, Task, forward_messages, send_animation, send_media_sequen
 use crate::ctx::AppContext;
 use crate::db::{now_f64, unix_now};
 use crate::handlers::log_key;
-use crate::link_cache::{CachedMedia, CachedMediaKind, LinkCache};
+use crate::link_cache::{CachedMedia, CachedMediaKind};
 use crate::media_sender::MediaSender;
 use crate::queue::{PersistentTaskQueue, QueueError};
 use crate::state::EditMessage;
@@ -15,13 +15,17 @@ use std::collections::HashMap;
 use std::sync::LazyLock;
 use teloxide::types::{ChatId, InlineKeyboardButton, InlineKeyboardMarkup, Message, MessageId};
 
-/// Persists a successful send under the post's cache key. Only runs for a
-/// fresh (non-resumed) task that carried raw cache data with no file ids yet.
+/// Persists a successful send under the post's cache key. Skips a send that was
+/// served from the cache — its entry already holds the file ids the next repeat
+/// wants — *unless* the entry was degraded (no file ids left, see
+/// `invalidate_cache`): then the ids this send just produced are written back,
+/// which is what returns a degraded entry to the fast path instead of leaving
+/// it to re-upload the media on every repeat.
 pub(super) async fn cache_sent_task(ctx: &AppContext<'_>, task: &Task, media: Vec<CachedMedia>) {
     let Some(cache_data) = task.cache_data() else {
         return;
     };
-    if !cache_data.media.is_empty() || media.is_empty() {
+    if cache_data.media.iter().any(|m| !m.file_id.is_empty()) || media.is_empty() {
         return;
     }
     let mut post = cache_data.clone();
@@ -33,7 +37,12 @@ pub(super) async fn cache_sent_task(ctx: &AppContext<'_>, task: &Task, media: Ve
 }
 
 /// Persists a lone animation send under the post's cache key.
-pub(super) async fn cache_animation_send(ctx: &AppContext<'_>, task: &Task, message: &Message) {
+pub(super) async fn cache_animation_send(
+    ctx: &AppContext<'_>,
+    task: &Task,
+    message: &Message,
+    source_url: &str,
+) {
     if let Some(file_id) = message.animation().map(|a| a.file.id.to_string()) {
         cache_sent_task(
             ctx,
@@ -41,6 +50,7 @@ pub(super) async fn cache_animation_send(ctx: &AppContext<'_>, task: &Task, mess
             vec![CachedMedia {
                 kind: CachedMediaKind::Animation,
                 file_id,
+                url: source_url.to_string(),
             }],
         )
         .await;
@@ -57,35 +67,64 @@ pub(crate) enum Settled {
 /// Every path that ends a task's life — sent, permanently failed, or
 /// dead-lettered after the last retry — funnels through here, so the cleanup a
 /// settled task owes cannot be forgotten by a new path: release the keep-alive
-/// temp media (retryable tasks keep it, they will be resent) and drop the
-/// link-cache entry that a failed send's stale file ids would keep poisoning.
+/// temp media (retryable tasks keep it, they will be resent) and deal with the
+/// link-cache entry a failed send's stale file ids would keep poisoning
+/// (degraded to its source URLs, dropped once those fail too).
 pub(crate) async fn settle_task(ctx: &AppContext<'_>, task: &Task, outcome: Settled) {
     if matches!(outcome, Settled::Failed) {
-        invalidate_cache(ctx.link_cache, task).await;
+        invalidate_cache(ctx, task).await;
     }
     release_keep_alive(task);
 }
 
-/// A cached Telegram file id failed permanently (stale/expired); drop the
-/// cache entry so the next request re-fetches instead of repeating it.
-async fn invalidate_cache(cache: &LinkCache, task: &Task) {
-    if task.is_cached_send()
-        && let Some(url) = task.source_url()
-        && let Some(key) = x_media::site::cache_key(url)
-    {
-        log::debug!("removing stale link cache entry for [key={}]", log_key(url));
-        cache.remove(&key).await;
+/// A cached Telegram file id failed permanently (stale/expired). The media
+/// itself is usually fine, so the entry is *degraded* rather than dropped: its
+/// file ids go away and the source URLs stay, and the next request re-sends the
+/// post from those — no source request, no ugoira encode, no HLS remux — with
+/// the media fetched by Telegram (or by the upload fallback). An entry that is
+/// already degraded, or whose older rows carry no URLs, is removed instead: its
+/// URLs did not work either, and the next request should fetch the post again
+/// and report what the source says.
+async fn invalidate_cache(ctx: &AppContext<'_>, task: &Task) {
+    if !task.is_cached_send() {
+        return;
     }
+    let Some(url) = task.source_url() else {
+        return;
+    };
+    let Some(key) = x_media::site::cache_key(url) else {
+        return;
+    };
+    let Some(mut entry) = ctx.link_cache.get(&key, ctx.config.link_cache_ttl).await else {
+        return;
+    };
+    let degradable = entry.media.iter().all(|m| !m.url.is_empty())
+        && entry.media.iter().any(|m| !m.file_id.is_empty());
+    if !degradable {
+        log::debug!("removing stale link cache entry for [key={}]", log_key(url));
+        ctx.link_cache.remove(&key).await;
+        return;
+    }
+    log::debug!(
+        "degrading stale link cache entry to its source URLs for [key={}]",
+        log_key(url)
+    );
+    for media in &mut entry.media {
+        media.file_id.clear();
+    }
+    ctx.link_cache.put(&key, &entry).await;
 }
 
 /// Locally produced media files (ugoira MP4, bsky remux MP4) whose temp dirs
 /// must stay alive while their task may be retried by the queue. The fetch
-/// pipeline hands ownership here via
-/// [`x_media::site::Fetched::take_keep_alive`] before that
-/// [`x_media::site::Fetched`] is dropped; a queued retry runs after that drop,
-/// so without this the local file would be gone by the time the retry sends
-/// it. Entries are removed when the task settles (see [`release_keep_alive`]).
-pub(crate) static KEEP_ALIVE: LazyLock<parking_lot::Mutex<Vec<tempfile::TempDir>>> =
+/// pipeline hands a reference here via [`x_media::site::Fetched::keep_alive`]
+/// before that [`x_media::site::Fetched`] is dropped; a queued retry runs after
+/// that drop, so without this the local file would be gone by the time the
+/// retry sends it. `Arc` because one fetch can serve several tasks (a
+/// concurrent duplicate of the same link shares it): each holder keeps the
+/// directory alive until its own task settles. Entries are removed when the
+/// task settles (see [`release_keep_alive`]).
+pub(crate) static KEEP_ALIVE: LazyLock<parking_lot::Mutex<Vec<std::sync::Arc<tempfile::TempDir>>>> =
     LazyLock::new(|| parking_lot::Mutex::new(Vec::new()));
 
 /// Drops the keep-alive temp dirs holding media referenced by `task` (matched
@@ -175,7 +214,7 @@ pub(super) fn hidden_template_count(templates: &HashMap<String, String>) -> usiz
 
 /// Notifies a chat about a dead-lettered task (skips when `notify_chat_id` is
 /// absent).
-pub(super) async fn notify_failure(
+pub(crate) async fn notify_failure(
     sender: &dyn MediaSender,
     chat_id: Option<i64>,
     message_id: Option<i64>,
@@ -257,8 +296,9 @@ pub(crate) async fn post_send_actions(ctx: &AppContext<'_>, task: &Task, message
         match prompt {
             Ok(prompt_id) => {
                 log::info!(
-                    "edit-before-forward prompt {prompt_id} opened for {} message(s)",
-                    message_ids.len()
+                    "edit-before-forward prompt {prompt_id} opened for {} message(s) [key={}] chat={chat_id}",
+                    message_ids.len(),
+                    log_key(&source_url)
                 );
                 let source_url = source_url.clone();
                 ctx.chat_store
@@ -276,15 +316,29 @@ pub(crate) async fn post_send_actions(ctx: &AppContext<'_>, task: &Task, message
                     })
                     .await;
             }
-            Err(e) => log::error!("failed to send edit prompt: {e}"),
+            Err(e) => {
+                log::error!("failed to send edit prompt: {e}");
+                // Nothing is forwarded until the prompt is confirmed, so a
+                // prompt that never arrived means this post is never forwarded.
+                // Tell the chat instead of letting it wait for a prompt that
+                // will not come.
+                notify_failure(
+                    ctx.sender,
+                    notify_chat_id,
+                    notify_message_id,
+                    "Could not open the edit-before-forward prompt — nothing was forwarded.",
+                )
+                .await;
+            }
         }
         return;
     }
 
     if let Some(channel_id) = forward_channel_id {
         log::info!(
-            "forwarding {} message(s) to channel {channel_id}",
-            message_ids.len()
+            "forwarding {} message(s) to channel {channel_id} from chat {chat_id} [key={}]",
+            message_ids.len(),
+            log_key(&source_url)
         );
         let forward_task = Task::ForwardMessages {
             from_chat_id: chat_id,
@@ -299,7 +353,17 @@ pub(crate) async fn post_send_actions(ctx: &AppContext<'_>, task: &Task, message
                 delay_seconds,
                 task,
             }) => {
-                enqueue_retry(ctx.task_queue, *task, delay_seconds).await;
+                // The forward is already committed from the user's side; if it
+                // cannot be queued, say so rather than going quiet.
+                if !enqueue_retry(ctx.task_queue, &task, delay_seconds).await {
+                    notify_failure(
+                        ctx.sender,
+                        notify_chat_id,
+                        notify_message_id,
+                        &failure_text(task.source_url(), "retry could not be queued"),
+                    )
+                    .await;
+                }
             }
             Err(SendError::Permanent { message, .. }) => {
                 notify_failure(
@@ -314,16 +378,24 @@ pub(crate) async fn post_send_actions(ctx: &AppContext<'_>, task: &Task, message
     }
 }
 
-/// Enqueues a task for a later attempt (retry / forward resume). When the
-/// enqueue itself fails the task can never be sent again, so its keep-alive
-/// temp media is released instead of leaking until process exit.
-pub(crate) async fn enqueue_retry(queue: &PersistentTaskQueue, task: Task, delay_seconds: f64) {
-    let payload = serde_json::to_value(&task).expect("task serializes");
+/// Enqueues a task for a later attempt (retry / forward resume). Returns
+/// whether the retry is actually persisted: when the enqueue itself fails the
+/// task can never run again, so its keep-alive temp media is released instead
+/// of leaking until process exit — and the caller must not tell the user a
+/// retry is coming (nothing would ever deliver it).
+pub(crate) async fn enqueue_retry(
+    queue: &PersistentTaskQueue,
+    task: &Task,
+    delay_seconds: f64,
+) -> bool {
+    let payload = serde_json::to_value(task).expect("task serializes");
     let run_after = now_f64() + delay_seconds;
     if let Err(e) = queue.enqueue(payload, run_after).await {
         log::error!("failed to enqueue retry: {e}");
-        release_keep_alive(&task);
+        release_keep_alive(task);
+        return false;
     }
+    true
 }
 
 /// Queue entry point: parses the stored task and dispatches.
@@ -402,15 +474,34 @@ async fn send_media_or_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Ve
 
 /// User-facing text for a task that will never run again: which link died and
 /// why. The raw error alone left the user guessing which post it was about.
-pub(super) fn failure_text(task: Option<&Task>, message: &str) -> String {
-    match task.and_then(|task| task.source_url()).map(log_key) {
+pub(super) fn failure_text(source_url: Option<&str>, message: &str) -> String {
+    match source_url.map(log_key) {
         Some(key) => format!("Send failed permanently for {key}: {message}"),
-        // `ForwardMessages` carries no source URL: that failure is about the
-        // channel copy, not about a post.
+        // `ForwardMessages` carries no source URL (and neither does an
+        // unparsable payload): that failure is about the channel copy, not
+        // about a post.
         None => format!("Forward failed permanently: {message}"),
     }
 }
 
+/// The post a stored payload is about, without parsing it into a [`Task`]:
+/// used when the payload no longer deserializes (written by an older version,
+/// or corrupted) but its identity fields are still readable.
+fn payload_source_url(payload: &serde_json::Value) -> Option<&str> {
+    payload.get("source_url").and_then(|v| v.as_str())
+}
+
+/// Whether a stored payload was a *cached* send (see `Task::is_cached_send`),
+/// read straight off the JSON — the unparsable case still has to know whether
+/// a link-cache entry may be holding the media that failed.
+fn payload_is_cached_send(payload: &serde_json::Value) -> bool {
+    payload
+        .get("cache_data")
+        .and_then(|data| data.get("media"))
+        .and_then(|media| media.as_array())
+        .is_some_and(|media| !media.is_empty())
+}
+
 /// Dead-letter callback wired to the queue in main: settles the task and
 /// notifies its chat.
 pub(crate) async fn dead_letter_notify(
@@ -424,6 +515,18 @@ pub(crate) async fn dead_letter_notify(
     let task = serde_json::from_value::<Task>(payload.clone()).ok();
     if let Some(task) = &task {
         settle_task(ctx, task, Settled::Failed).await;
+    } else {
+        // A payload that no longer parses (an older version's row shape, a
+        // corrupted one) still says which post it was about: drop the stale
+        // cache entry the same way, instead of leaving a bad file id to be
+        // re-sent forever — and name the post in the notification rather than
+        // reporting a *forward* failure for a send task.
+        if payload_is_cached_send(&payload)
+            && let Some(key) = payload_source_url(&payload).and_then(x_media::site::cache_key)
+        {
+            log::debug!("removing stale link cache entry for [key={key}]");
+            ctx.link_cache.remove(&key).await;
+        }
     }
     let notify_chat_id = payload.get("notify_chat_id").and_then(|v| v.as_i64());
     let notify_message_id = payload.get("notify_message_id").and_then(|v| v.as_i64());
@@ -431,7 +534,12 @@ pub(crate) async fn dead_letter_notify(
         ctx.sender,
         notify_chat_id,
         notify_message_id,
-        &failure_text(task.as_ref(), &message),
+        &failure_text(
+            task.as_ref()
+                .and_then(|task| task.source_url())
+                .or_else(|| payload_source_url(&payload)),
+            &message,
+        ),
     )
     .await;
 }

crates/xmedia-bot/src/send/upload.rs

@@ -6,11 +6,23 @@ use super::input_media::{animation_media, input_file_for, item_url, photo_media,
 use super::{MediaItemPayload, SendError, Task, classify_to_send_error, retry_delay_seconds};
 use crate::media_sender::MediaSender;
 use crate::photo::{self, MAX_UPLOAD_BYTES, PhotoPrep};
+use std::sync::LazyLock;
 use teloxide::prelude::*;
 use teloxide::types::{ChatId, InputFile, InputMedia, MessageId};
 use tempfile::NamedTempFile;
 use x_media::site::FetchError;
 
+/// How many fallback items may be downloaded and processed at once, across the
+/// whole process. A per-batch bound is not a memory bound: `URL_WORKERS` (8)
+/// and the queue's workers (4) can each be inside a batch, so a per-batch three
+/// allowed two dozen downloads in flight, each buffering a whole photo
+/// (up to [`photo::MAX_PHOTO_DOWNLOAD_BYTES`]) before it is processed. This is
+/// the only admission control on the media path; the send itself is paced by
+/// the rate limiter.
+const PREP_CONCURRENCY: usize = 6;
+static PREP_SLOTS: LazyLock<tokio::sync::Semaphore> =
+    LazyLock::new(|| tokio::sync::Semaphore::new(PREP_CONCURRENCY));
+
 /// Infers a file extension from magic bytes so Telegram detects the mime type
 /// on multipart uploads.
 pub(super) fn sniff_ext(bytes: &[u8]) -> &'static str {
@@ -62,45 +74,60 @@ async fn download_to_temp(
         | MediaItemPayload::Animation { media, .. } => media,
     };
     // Photos are downloaded even over the upload cap so `prepare_photo` can
-    // downscale / transcode them (cap = decode budget); videos/animations
-    // abort as soon as the upload cap is crossed mid-stream.
+    // downscale / transcode them, up to their own download cap; videos and
+    // animations are refused as soon as the declared size crosses the upload
+    // cap. The limit is that cap, not `cap + 1`: a file of exactly the cap is
+    // admitted (`len > max_bytes` is false), and one byte over is not — the
+    // same boundary the size probe this replaced drew.
     let limit = if matches!(item, MediaItemPayload::Photo { .. }) {
-        photo::MAX_DECODE_BYTES
+        photo::MAX_PHOTO_DOWNLOAD_BYTES
     } else {
-        MAX_UPLOAD_BYTES + 1
+        MAX_UPLOAD_BYTES
     };
     let bytes = match x_media::site::download_media_limited(media_url, limit).await {
         Ok(bytes) => bytes,
-        Err(FetchError::Http(_)) => {
-            return Err(FallbackError::Retryable {
-                delay_seconds: retry_delay_seconds(0),
-            });
-        }
-        Err(FetchError::TooLarge) => {
-            return Err(FallbackError::MediaTooLarge);
-        }
-        Err(e) => {
-            return Err(FallbackError::Permanent {
-                message: format!("download failed: {e}"),
-            });
-        }
+        Err(e) => return Err(classify_download_error(e)),
     };
     let ext = sniff_ext(&bytes);
     let mut file = tempfile::Builder::new()
+        .prefix(x_media::TEMP_FILE_PREFIX)
         .suffix(&format!(".{ext}"))
         .tempfile()
         .map_err(|e| FallbackError::Permanent {
             message: format!("temp file failed: {e}"),
         })?;
     use std::io::Write;
-    file.as_file_mut()
-        .write_all(&bytes)
-        .map_err(|e| FallbackError::Permanent {
-            message: format!("temp file write failed: {e}"),
-        })?;
+    // A write failure is resource exhaustion far more often than a broken temp
+    // dir (ENOSPC / EDQUOT), and that clears on its own — worth an attempt
+    // instead of dropping the post on the first try. Creating the file (above)
+    // stays permanent: a temp dir that cannot be created at all is a
+    // deployment fault that should fail loudly and immediately. `Retryable`
+    // carries no message, so the cause is logged here.
+    file.as_file_mut().write_all(&bytes).map_err(|e| {
+        log::error!("temp file write failed: {e}");
+        FallbackError::Retryable {
+            delay_seconds: retry_delay_seconds(0),
+        }
+    })?;
     Ok((file, bytes))
 }
 
+/// Which failure class a media download belongs to. Transport errors and
+/// server-side hiccups (429/5xx, see `download_media_limited`) are worth
+/// another attempt; a 4xx means the media itself is gone or refused, and a
+/// retry could only ask the same URL again.
+fn classify_download_error(err: FetchError) -> FallbackError {
+    match err {
+        FetchError::Http(_) | FetchError::Transient(_) => FallbackError::Retryable {
+            delay_seconds: retry_delay_seconds(0),
+        },
+        FetchError::TooLarge => FallbackError::MediaTooLarge,
+        e => FallbackError::Permanent {
+            message: format!("download failed: {e}"),
+        },
+    }
+}
+
 /// Builds the media group item from an uploaded file.
 fn media_from_file(
     item: &MediaItemPayload,
@@ -185,28 +212,13 @@ pub(super) async fn prepare_upload_item(
             keep_alive: None,
         });
     }
-    // Size check before downloading/uploading: over the cap, use the
-    // smaller URL instead of the file. Photos are exempt — they are
-    // downloaded and processed (downscale / PNG→JPEG) before uploading.
-    let too_large = match x_media::site::media_size(media_url).await {
-        Ok(Some(size)) => size > MAX_UPLOAD_BYTES,
-        _ => false,
-    };
-    let too_large = too_large && !matches!(item, MediaItemPayload::Photo { .. });
-    if too_large {
-        let url = item
-            .fallback_url()
-            .ok_or_else(|| FallbackError::Permanent {
-                message: "media too large".into(),
-            })?;
-        let media = media_from_url(&item, url, caption, item.thumbnail_url())
-            .map_err(|message| FallbackError::Permanent { message })?;
-        return Ok(PreparedItem {
-            index,
-            media,
-            keep_alive: None,
-        });
-    }
+    // Whether a file is over the cap is settled by the download itself:
+    // `download_media_limited` reads the declared Content-Length before any
+    // body byte and aborts with `FetchError::TooLarge`, which arrives here as
+    // `FallbackError::MediaTooLarge` — turned into the item's smaller URL by
+    // the match below. A separate size probe used to issue a second GET of the
+    // same URL for an answer this path already has (and issued it for photos,
+    // whose answer was discarded one line later).
     match download_to_temp(&item).await {
         Ok((file, bytes)) => {
             if matches!(item, MediaItemPayload::Photo { .. }) {
@@ -215,6 +227,22 @@ pub(super) async fn prepare_upload_item(
                 // before uploading; photos that cannot be brought within the
                 // limits degrade to the smaller URL. CPU-heavy work runs off
                 // the async executor thread.
+                //
+                // The header decides what that will cost in memory, so the
+                // probe travels with the downloaded bytes (both stay alive
+                // through the decode) and the reservation covers their sum:
+                // `PREP_SLOTS` bounds how many photos are prepared at once,
+                // this bounds what they hold between them — 512 MiB, whatever
+                // the batch looks like.
+                let (bytes, decode) = tokio::task::spawn_blocking(move || {
+                    let decode = photo::decode_budget_bytes(&bytes);
+                    (bytes, decode)
+                })
+                .await
+                .map_err(|e| FallbackError::Permanent {
+                    message: format!("photo worker panicked: {e}"),
+                })?;
+                let _budget = photo::reserve_memory(bytes.len() as u64 + decode).await;
                 let prep = tokio::task::spawn_blocking(move || photo::prepare_photo(file, &bytes))
                     .await
                     .map_err(|e| FallbackError::Permanent {
@@ -277,10 +305,12 @@ pub(super) async fn prepare_upload_item(
 
 /// Download-and-reupload fallback for one media batch. Files over the upload
 /// cap are not downloaded/uploaded; the item falls back to its smaller URL
-/// (which Telegram fetches itself). Items are prepared concurrently (bounded)
-/// because the downloads are network-bound; the batch is then uploaded in its
-/// original order. Returns the fallback-error without the task attached;
-/// callers wrap it with the updated task state.
+/// (which Telegram fetches itself). Items are prepared concurrently because the
+/// downloads are network-bound, under one process-wide bound ([`PREP_SLOTS`] —
+/// the URL and queue workers can each be inside a batch, so a per-batch bound
+/// would multiply); the batch is then uploaded in its original order. Returns
+/// the fallback-error without the task attached; callers wrap it with the
+/// updated task state.
 pub(super) async fn send_batch_via_upload(
     sender: &dyn MediaSender,
     chat_id: i64,
@@ -289,7 +319,6 @@ pub(super) async fn send_batch_via_upload(
     caption: Option<&str>,
     task: Task,
 ) -> Result<Vec<Message>, SendError> {
-    let sem = std::sync::Arc::new(tokio::sync::Semaphore::new(3));
     let mut set = tokio::task::JoinSet::new();
     for (i, item) in batch.iter().enumerate() {
         let item_caption = if i == 0 {
@@ -298,9 +327,8 @@ pub(super) async fn send_batch_via_upload(
             None
         };
         let item = item.clone();
-        let sem = std::sync::Arc::clone(&sem);
         set.spawn(async move {
-            let _permit = sem.acquire().await.expect("upload semaphore closed");
+            let _permit = PREP_SLOTS.acquire().await.expect("upload semaphore closed");
             prepare_upload_item(item, i, item_caption.as_deref()).await
         });
     }
@@ -343,3 +371,31 @@ pub(super) async fn send_batch_via_upload(
         Err(e) => Err(classify_to_send_error(&e, task, "upload failed")),
     }
 }
+
+#[cfg(test)]
+mod download_class_tests {
+    use super::*;
+
+    #[test]
+    fn download_errors_split_by_whether_a_retry_can_help() {
+        // Transport failure and a server-side hiccup: try again.
+        assert!(matches!(
+            classify_download_error(FetchError::Transient("media status 503".into())),
+            FallbackError::Retryable { .. }
+        ));
+        // The media is gone / the host refuses us: a retry repeats the 4xx.
+        assert!(matches!(
+            classify_download_error(FetchError::NotFound),
+            FallbackError::Permanent { .. }
+        ));
+        assert!(matches!(
+            classify_download_error(FetchError::Blocked),
+            FallbackError::Permanent { .. }
+        ));
+        // Over the cap: degrade to the smaller URL, never retry.
+        assert!(matches!(
+            classify_download_error(FetchError::TooLarge),
+            FallbackError::MediaTooLarge
+        ));
+    }
+}

crates/xmedia-bot/src/state.rs

@@ -73,7 +73,7 @@ impl ChatStore {
             })
             .await
             .unwrap_or_else(|e| {
-                log::error!("chat_state read failed: {e}");
+                log::warn!("chat_state read failed: {e}");
                 None
             })
             .unwrap_or_default();
@@ -98,7 +98,7 @@ impl ChatStore {
             })
             .await;
         if let Err(e) = result {
-            log::error!("chat_state write failed: {e}");
+            log::warn!("chat_state write failed: {e}");
         }
     }
 
@@ -131,18 +131,24 @@ impl ChatStore {
     pub async fn prune_expired(&self, ttl: Duration) -> Vec<(i64, i64)> {
         let now = unix_now();
         let ttl_secs = ttl.as_secs() as i64;
-        // Chats that may have an expired record, from a cache snapshot; the
-        // pruning itself re-reads and writes under the per-chat lock below
-        // (see the eviction note). Takes no lock of its own, so a chat
-        // appearing later is simply picked up by the next sweep.
+        // Chats worth looking at, from a cache snapshot: the ones with an
+        // expired record, plus the ones holding no record at all. The latter
+        // used to be left alone for the process lifetime — every chat that ever
+        // sent a message or ran a command stayed in the cache and in the
+        // per-chat lock map — even though a chat with no live prompt is exactly
+        // what the eviction below is for. The pruning itself re-reads and
+        // writes under the per-chat lock below; taking no lock here means a
+        // chat appearing later is simply picked up by the next sweep.
         let candidates: Vec<i64> = {
             let cache = self.cache.lock();
             cache
                 .iter()
                 .filter(|(_, data)| {
-                    data.edit_message
-                        .values()
-                        .any(|entry| entry.created_at + ttl_secs <= now)
+                    data.edit_message.is_empty()
+                        || data
+                            .edit_message
+                            .values()
+                            .any(|entry| entry.created_at + ttl_secs <= now)
                 })
                 .map(|(chat_id, _)| *chat_id)
                 .collect()
@@ -265,6 +271,58 @@ mod tests {
         );
     }
 
+    #[tokio::test]
+    async fn an_idle_chat_is_evicted_and_its_state_reloads() {
+        let dir = tempfile::tempdir().unwrap();
+        let pool = crate::db::open_store(dir.path().join("e.db").to_str().unwrap()).unwrap();
+        let store = ChatStore::new(pool);
+        // Durable settings and no prompt at all: this chat used to sit in the
+        // cache (and in the per-chat lock map) for the process lifetime,
+        // because the sweep only ever looked at chats with an *expired* record.
+        store
+            .update(9, |data| {
+                data.forward_channel_id = Some(-100);
+                data.message_format.insert("twitter".into(), "{url}".into());
+            })
+            .await;
+        assert!(store.cache.lock().contains_key(&9));
+
+        let removed = store.prune_expired(Duration::from_secs(60)).await;
+
+        assert!(removed.is_empty(), "nothing had expired");
+        assert!(
+            !store.cache.lock().contains_key(&9),
+            "a chat with no live prompt must leave the cache"
+        );
+        assert!(!store.locks.lock().contains_key(&9), "…and its lock");
+        // The DB kept the row, so the next use reloads everything it held.
+        let data = store.get(9).await;
+        assert_eq!(data.forward_channel_id, Some(-100));
+        assert_eq!(
+            data.message_format.get("twitter").map(String::as_str),
+            Some("{url}")
+        );
+    }
+
+    #[tokio::test]
+    async fn a_live_prompt_keeps_its_chat_cached() {
+        let dir = tempfile::tempdir().unwrap();
+        let pool = crate::db::open_store(dir.path().join("k.db").to_str().unwrap()).unwrap();
+        let store = ChatStore::new(pool);
+        store
+            .update(10, |data| {
+                data.edit_message.insert(1, edit_entry(10, unix_now()));
+            })
+            .await;
+
+        store.prune_expired(Duration::from_secs(3600)).await;
+
+        assert!(
+            store.cache.lock().contains_key(&10),
+            "a live prompt holds its chat in the cache"
+        );
+    }
+
     #[tokio::test]
     async fn prune_eviction_keeps_the_persisted_state() {
         // Every record expires → the chat is evicted from the cache; the

docker-compose.yml

@@ -0,0 +1,108 @@
+# Deployment reference for the Docker Hub image. Instance values (token, admins,
+# site credentials, domain) live in `.env` next to this file — `docker compose`
+# substitutes every `${VAR}` from it automatically — so this file stays in the
+# repository unmodified. A variable that is not listed here is not passed into
+# the container at all.
+#
+# JSON-file logs grow without limit by default: a long-running bot (and the
+# proxy in front of it) will fill the disk. One cap, applied to every service
+# below via the anchor.
+x-logging: &default-logging
+  driver: json-file
+  options:
+    max-size: '10m'
+    max-file: '3'
+
+services:
+  nginx-proxy:
+    image: nginxproxy/nginx-proxy:1.11.6-alpine
+    restart: always
+    environment:
+      # Routes requests with an unknown Host (i.e. plain IP access) here; set
+      # DEFAULT_HOST in .env to use it.
+      DEFAULT_HOST: '${DEFAULT_HOST:-}'
+    ports:
+      - '80:80'
+      - '443:443'
+    volumes:
+      - /var/run/docker.sock:/tmp/docker.sock:ro
+      - certs:/etc/nginx/certs:ro
+      - html:/usr/share/nginx/html:ro
+    networks: [proxy]
+    labels:
+      - 'com.github.nginx-proxy.nginx'
+    container_name: nginx-proxy
+    logging: *default-logging
+
+  acme-companion:
+    image: nginxproxy/acme-companion
+    restart: always
+    environment:
+      DEFAULT_EMAIL: '${DEFAULT_EMAIL:-}'
+    volumes:
+      - /var/run/docker.sock:/var/run/docker.sock:ro
+      - certs:/etc/nginx/certs:rw
+      - html:/usr/share/nginx/html:rw
+      - acme:/etc/acme.sh
+    networks: [proxy]
+    container_name: acme-companion
+    depends_on:
+      - nginx-proxy
+    logging: *default-logging
+
+  tgxmb:
+    image: yoursfunny/telegram-twitter-media-bot:latest
+    restart: always
+    environment:
+      # From .env (the instance's own values; see the env table in README.md).
+      TELOXIDE_TOKEN: '${TELOXIDE_TOKEN:-}'
+      BOT_ADMIN: '${BOT_ADMIN:-}'
+      PIXIV_REFRESH_TOKEN: '${PIXIV_REFRESH_TOKEN:-}'
+      TWITTER_AUTH_TOKEN: '${TWITTER_AUTH_TOKEN:-}'
+      BILIBILI_COOKIE: '${BILIBILI_COOKIE:-}'
+      VIRTUAL_HOST: '${VIRTUAL_HOST:-}'
+      WEBHOOK_URL: '${WEBHOOK_URL:-}'
+      WEBHOOK_SECRET_TOKEN: '${WEBHOOK_SECRET_TOKEN:-}'
+      # Defaults, listed so they are discoverable; override in .env when needed.
+      LOCAL_USER_ID: '${LOCAL_USER_ID:-1000}'
+      RUST_LOG: '${RUST_LOG:-info}'
+      EDIT_MESSAGE_TTL_SECONDS: '${EDIT_MESSAGE_TTL_SECONDS:-86400}'
+      LINK_CACHE_TTL_SECONDS: '${LINK_CACHE_TTL_SECONDS:-604800}'
+      CAPTION_QUOTE_TEXT_CHARS: '${CAPTION_QUOTE_TEXT_CHARS:-200}'
+      VIRTUAL_PORT: '${VIRTUAL_PORT:-8443}'
+      WEBHOOK: '${WEBHOOK:-true}'
+      WEBHOOK_LISTEN: '${WEBHOOK_LISTEN:-0.0.0.0}'
+      WEBHOOK_PORT: '${WEBHOOK_PORT:-8443}'
+      # For a certificate on a bare IP: uncomment and set ACME_HOST in .env.
+      # ACME_HOST: '${ACME_HOST:-}'
+      #
+      # Not listed on purpose: TELOXIDE_PROXY. Docker Desktop reaches a host
+      # proxy through host.docker.internal (a loopback address inside the
+      # container is the container itself), and teloxide panics on an *empty*
+      # value, so add the line deliberately when this deployment needs one:
+      #   TELOXIDE_PROXY: '${TELOXIDE_PROXY}'
+    volumes:
+      - ./data:/app/data
+    networks: [proxy]
+    depends_on:
+      - nginx-proxy
+    container_name: tgxmb
+    logging: *default-logging
+    # Webhook mode only (in polling mode there is no listener, so drop this
+    # block or set WEBHOOK=true): the bot listens on WEBHOOK_PORT; nginx-proxy
+    # shows 502s while this is down, so surface it to the orchestrator.
+    healthcheck:
+      test: ["CMD-SHELL", "bash -c 'exec 3<>/dev/tcp/127.0.0.1/${WEBHOOK_PORT:-8443}'"]
+      interval: 30s
+      timeout: 5s
+      retries: 3
+      start_period: 10s
+
+volumes:
+  certs:
+  html:
+  acme:
+
+networks:
+  proxy:
+    name: proxy

docker-compose.yml.example

@@ -1,74 +0,0 @@
-services:
-  nginx-proxy:
-    image: nginxproxy/nginx-proxy:1.11.6-alpine
-    restart: always
-    ports:
-      - '80:80'
-      - '443:443'
-    volumes:
-      - /var/run/docker.sock:/tmp/docker.sock:ro
-      - certs:/etc/nginx/certs:ro
-      - html:/usr/share/nginx/html:ro
-    networks: [proxy]
-    labels:
-      - 'com.github.nginx-proxy.nginx'
-    container_name: nginx-proxy
-
-  acme-companion:
-    image: nginxproxy/acme-companion
-    restart: always
-    environment:
-      DEFAULT_EMAIL: ''
-    volumes:
-      - /var/run/docker.sock:/var/run/docker.sock:ro
-      - certs:/etc/nginx/certs:rw
-      - html:/usr/share/nginx/html:rw
-      - acme:/etc/acme.sh
-    networks: [proxy]
-    container_name: acme-companion
-    depends_on:
-      - nginx-proxy
-
-  tgxmb:
-    image: yoursfunny/telegram-twitter-media-bot:latest
-    restart: always
-    environment:
-      LOCAL_USER_ID: '1000'
-      TELOXIDE_TOKEN: ''
-      BOT_ADMIN: ''
-      PIXIV_REFRESH_TOKEN: ''
-      TWITTER_AUTH_TOKEN: ''
-      EDIT_MESSAGE_TTL_SECONDS: '86400'
-      LINK_CACHE_TTL_SECONDS: '604800'
-      RUST_LOG: 'info'
-      VIRTUAL_HOST: '<YOUR_DOMAIN>'
-      VIRTUAL_PORT: '8443'
-      # ACME_HOST: 'your.domain.com'
-      WEBHOOK: 'true'
-      WEBHOOK_LISTEN: '0.0.0.0'
-      WEBHOOK_PORT: '8443'
-      WEBHOOK_URL: 'https://<YOUR_DOMAIN>/'
-      WEBHOOK_SECRET_TOKEN: ''
-    volumes:
-      - ./data:/app/data
-    networks: [proxy]
-    depends_on:
-      - nginx-proxy
-    container_name: tgxmb
-    # Webhook mode only: the bot listens on WEBHOOK_PORT; nginx-proxy shows
-    # 502s while this is down, so surface it to the orchestrator.
-    healthcheck:
-      test: ["CMD-SHELL", "bash -c 'exec 3<>/dev/tcp/127.0.0.1/8443'"]
-      interval: 30s
-      timeout: 5s
-      retries: 3
-      start_period: 10s
-
-volumes:
-  certs:
-  html:
-  acme:
-
-networks:
-  proxy:
-    name: proxy