chore: bump version to 1.9.1

Enabling reqwest's `http2` feature pulled in h2 0.4.15, which accepts
unbounded empty DATA frames — a remote peer could make the bot queue them
without limit (memory growth, or a panic on length overflow). Low severity,
but the CI dependency-audit gate fails on it, and the fix is a patch bump:
`cargo update -p h2` → 0.4.19.

`cargo audit` against the advisory database is now clean of vulnerabilities
(the two remaining entries are pre-existing `unmaintained` warnings for
`dotenv` and `proc-macro-error2`, which the gate allows), and the full suite,
the live suite and a release build pass on the new lock.

.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=

.github/workflows/docker.yml

@@ -80,6 +80,11 @@ jobs:
             echo "build=true" >> "$GITHUB_OUTPUT"
           fi
 
+  # No `actions/checkout` here on purpose: `docker/build-push-action` defaults
+  # to the Git context (`https://github.com/<owner>/<repo>.git#<ref>`), so
+  # BuildKit clones the repo itself and authenticates with the automatic
+  # github.token. Adding `context: .` below without a checkout step would hand
+  # BuildKit an empty workspace.
   docker:
     needs: should-build
     if: needs.should-build.outputs.build == 'true'

.gitignore

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

AGENTS.md

@@ -2,9 +2,9 @@
 
 ## Project Overview
 
-Telegram bot (teloxide) that turns post links from X/Twitter, Pixiv, Bluesky, and Misskey (misskey.io) 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`).
+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.6.0, edition 2024, resolver 3):
+Two-crate Cargo workspace (both v1.9.1, 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,31 +18,37 @@ 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 ≤ 9, 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).
+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.
 
-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). Both commands use a custom `parse_arg_remainder` parser (whole remainder, trimmed) because teloxide's built-in `split` parser takes exactly one space-separated token.
+User-facing failure text is a function of the error class, never one generic sentence: `urls::fetch_error_message` maps `FetchError::NotFound` (post gone), `Sensitive` (withheld, needs `TWITTER_AUTH_TOKEN`), `Blocked` (source risk control), `Disabled { site }` (a registered site switched off — pixiv without a token, the one case `fetch` answers `Err` instead of `Ok(None)`) and `Transient`/`Http` (source down) apart. The same distinction drives the group hint: a supported link posted in a group (not a channel) gets one `GROUP_LINK_HINT` reply, because the link pipeline is private-chat only.
 
-The `x-media` library: `site::fetch(url)` dispatches through the `SITES` registry (per-site `impl Site`, in order twitter → bsky → misskey → pixiv) and returns `Ok(None)` for unmatched URLs. `Fetched { source_url, caption, title, media: Vec<Media>, sensitive, site_id, … }`; `caption_with(format)` substitutes `{url} {author} {author_url} {title} {tags}`.
+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, 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.
+
+The `x-media` library: `site::fetch(url)` dispatches through the `SITES` registry (per-site `impl Site`, in order twitter → bsky → misskey → pixiv → bilibili) and returns `Ok(None)` for unmatched URLs (`Err(FetchError::Disabled { site })` when the URL matches a registered site whose `enabled()` is false — see `disabled_site`). `Fetched { source_url, caption, title, content, media: Vec<Media>, sensitive, site_id, … }` (title and content are split per platform: a pixiv artwork's title and description, a bilibili headline and body, and text-only posts whose text is all `content`); `caption_with(format)` substitutes `{url} {author} {author_url} {title} {content} {tags}`.
 
 ## Key Directories
 
 | 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>/` | 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`). Misskey targets misskey.io only (`POST /api/notes/show`, 400+`NO_SUCH_NOTE` → NotFound). 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 escapes exactly once |
-| `crates/xmedia-bot/src/main.rs` | Entry point: env/log init, command registration (`register_commands`), shared `send::BOT` force-init, queue worker start, site login validation (`site::validate_all`), 300 s edit-expiry sweep, 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`), `commands.rs` (teloxide `BotCommands` enum + command executor, incl. `/test <url>` (send-only) / `/debug <url>` (parse-only) and the admin-only `/bot_dict` state dump), `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), `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
 
@@ -60,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`) 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, and the admin-only `/bot_dict` state dump); `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; `callback.rs` = edit-before-forward buttons (dptree entry + testable `handle_callback` core) |
-| `crates/xmedia-bot/src/send/` | `mod.rs`: constants `MAX_MEDIA_GROUP = 9`; `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, 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/x-media/src/site/mod.rs` | Dispatcher, `Fetched`/`FetchError`, shared `CLIENT`, `download_media` (adds `Referer: https://www.pixiv.net/` for `pximg.net` hotlink protection) |
+| `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) |
 
@@ -90,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), `BOT_ADMIN` (comma-separated ids), `EDIT_MESSAGE_TTL_SECONDS` (default 86400), `LINK_CACHE_TTL_SECONDS` (default 604800), `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
 
-- **~135 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/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. 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). 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

@@ -10,25 +10,13 @@ checksum = "320119579fcad9c21884f5c4861d16174d0e06250625266f50fe6898340abefa"
 
 [[package]]
 name = "aes"
-version = "0.8.4"
+version = "0.9.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b169f7a6d4742236a0a00c541b845991d0ac43e546831af1249753ab4c3aa3a0"
+checksum = "35f0f96ce78e38c3dc6d8948aa8163d06385be74000f3c7a95bf1eef35d3ea32"
 dependencies = [
- "cfg-if",
  "cipher",
- "cpufeatures 0.2.17",
-]
-
-[[package]]
-name = "ahash"
-version = "0.8.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5a15f179cd60c4584b8a8c596927aadc462e27f2ca70c04e0071964a73ba7a75"
-dependencies = [
- "cfg-if",
- "once_cell",
- "version_check",
- "zerocopy",
+ "cpubits",
+ "cpufeatures",
 ]
 
 [[package]]
@@ -73,12 +61,15 @@ dependencies = [
 ]
 
 [[package]]
-name = "arbitrary"
-version = "1.4.2"
+name = "async-compression"
+version = "0.4.43"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c3d036a3c4ab069c7b410a2ce876bd74808d2d0888a82667669f8e783a898bf1"
+checksum = "3976abdc8fe7d1133d43d304afd42abdf5bc3e1319d263d223bde07b5efc4be8"
 dependencies = [
- "derive_arbitrary",
+ "compression-codecs",
+ "compression-core",
+ "pin-project-lite",
+ "tokio",
 ]
 
 [[package]]
@@ -171,11 +162,12 @@ checksum = "3ded4057c258ba199e2d26386d3af3780957ecaee6c4ef4041c6b4b8b97c0b06"
 
 [[package]]
 name = "block-buffer"
-version = "0.10.4"
+version = "0.12.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3078c7629b62d3f0439517fa394996acacc5cbc91c5a20d8c658e77abd503a71"
+checksum = "d2f6c7dbe95a6ed67ad9f18e57daf93a2f034c524b99fd2b76d18fdfeb6660aa"
 dependencies = [
- "generic-array",
+ "hybrid-array",
+ "zeroize",
 ]
 
 [[package]]
@@ -199,12 +191,6 @@ version = "1.25.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "95832e849adfb21180ccb6826a99da14e5d266ae5c2e668e1602cf234f153797"
 
-[[package]]
-name = "byteorder"
-version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1fd0f2584146f6f2ef48085050886acf353beff7305ebd1ae69500e27c67f64b"
-
 [[package]]
 name = "bytes"
 version = "1.12.1"
@@ -213,21 +199,11 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "bzip2"
-version = "0.5.2"
+version = "0.6.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "49ecfb22d906f800d4fe833b6282cf4dc1c298f5057ca0b5445e5c209735ca47"
+checksum = "f3a53fac24f34a81bc9954b5d6cfce0c21e18ec6959f44f56e8e90e4bb7c346c"
 dependencies = [
- "bzip2-sys",
-]
-
-[[package]]
-name = "bzip2-sys"
-version = "0.1.13+1.0.8"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "225bff33b2141874fe80d71e07d6eec4f85c5c216453dd96388240f96e1acc14"
-dependencies = [
- "cc",
- "pkg-config",
+ "libbz2-rs-sys",
 ]
 
 [[package]]
@@ -261,7 +237,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "65c35e4b699c7e15ccbe7ee35c005e4fc0a278d22238a2857e6ce2dadeda1b06"
 dependencies = [
  "cfg-if",
- "cpufeatures 0.3.1",
+ "cpufeatures",
  "rand_core 0.10.1",
 ]
 
@@ -279,28 +255,57 @@ dependencies = [
 
 [[package]]
 name = "cipher"
-version = "0.4.4"
+version = "0.5.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "773f3b9af64447d2ce9850330c473515014aa235e6a783b02db81ff39e4a3dad"
+checksum = "e8cf2a2c93cd704877c0858356ed03480ff301ee950b43f1cbe4573b088bfa6c"
 dependencies = [
  "crypto-common",
  "inout",
 ]
 
+[[package]]
+name = "cmov"
+version = "0.5.4"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "0c9ea0ac24bc397ab3c98583a3c9ba74fa56b09a4449bbe172b9b1ddb016027a"
+
 [[package]]
 name = "colored"
 version = "3.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "faf9468729b8cbcea668e36183cb69d317348c2e08e994829fb56ebfdfbaac34"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
-name = "constant_time_eq"
-version = "0.3.1"
+name = "compression-codecs"
+version = "0.4.38"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7c74b8349d32d297c9134b8c88677813a227df8f779daa29bfc29c183fe3dca6"
+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"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "a6ef517f0926dd24a1582492c791b6a4818a4d94e789a334894aa15b0d12f55c"
+
+[[package]]
+name = "constant_time_eq"
+version = "0.4.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "3d52eff69cd5e647efe296129160853a42795992097e8af39800e1060caeea9b"
 
 [[package]]
 name = "core-foundation-sys"
@@ -309,13 +314,10 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "773648b94d0e5d620f64f280777445740e61fe701025087ec8b57f45c791888b"
 
 [[package]]
-name = "cpufeatures"
-version = "0.2.17"
+name = "cpubits"
+version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "59ed5838eebb26a2bb2e58f6d5b5316989ae9d08bab10e0e6d103e656d1b0280"
-dependencies = [
- "libc",
-]
+checksum = "15b85f9c39137c3a891689859392b1bd49812121d0d61c9caf00d46ed5ce06ae"
 
 [[package]]
 name = "cpufeatures"
@@ -326,21 +328,6 @@ dependencies = [
  "libc",
 ]
 
-[[package]]
-name = "crc"
-version = "3.4.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5eb8a2a1cd12ab0d987a5d5e825195d372001a4094a0376319d5a0ad71c1ba0d"
-dependencies = [
- "crc-catalog",
-]
-
-[[package]]
-name = "crc-catalog"
-version = "2.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "217698eaf96b4a3f0bc4f3662aaa55bdf913cd54d7204591faa790070c6d0853"
-
 [[package]]
 name = "crc32fast"
 version = "1.5.2"
@@ -351,19 +338,21 @@ dependencies = [
 ]
 
 [[package]]
-name = "crossbeam-utils"
-version = "0.8.23"
+name = "crypto-common"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a31eee39dddec8330830986fcd7625edb5a24ec90ea038215273bbc3adb08ac6"
+checksum = "ce6e4c961d6cd6c9a86db418387425e8bdeaf05b3c8bc1411e6dca4c252f1453"
+dependencies = [
+ "hybrid-array",
+]
 
 [[package]]
-name = "crypto-common"
-version = "0.1.7"
+name = "ctutils"
+version = "0.4.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "78c8292055d1c1df0cce5d180393dc8cce0abec0a7102adb6c7b1eef6016d60a"
+checksum = "7d5515a3834141de9eafb9717ad39eea8247b5674e6066c404e8c4b365d2a29e"
 dependencies = [
- "generic-array",
- "typenum",
+ "cmov",
 ]
 
 [[package]]
@@ -446,17 +435,6 @@ dependencies = [
  "serde_core",
 ]
 
-[[package]]
-name = "derive_arbitrary"
-version = "1.4.2"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1e567bd82dcff979e4b03460c307b3cdc9e96fde3d73bed1496d2bc75d9dd62a"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
-
 [[package]]
 name = "derive_more"
 version = "1.0.0"
@@ -480,13 +458,15 @@ dependencies = [
 
 [[package]]
 name = "digest"
-version = "0.10.7"
+version = "0.11.3"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9ed9a281f7bc9b7576e61468ba615a66a5c8cfdff42420a70aa82701a3b1e292"
+checksum = "f1dd6dbb5841937940781866fa1281a1ff7bd3bf827091440879f9994983d5c2"
 dependencies = [
  "block-buffer",
+ "const-oid",
  "crypto-common",
- "subtle",
+ "ctutils",
+ "zeroize",
 ]
 
 [[package]]
@@ -573,7 +553,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "39cab71617ae0d63f51a36d69f866391735b51691dbda63cf6f96d042b63efeb"
 dependencies = [
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -632,6 +612,18 @@ 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"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "77ce24cb58228fbb8aa041425bb1050850ac19177686ea6e0f41a70416f56fdb"
+
 [[package]]
 name = "form_urlencoded"
 version = "1.2.2"
@@ -729,16 +721,6 @@ dependencies = [
  "slab",
 ]
 
-[[package]]
-name = "generic-array"
-version = "0.14.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "85649ca51fd72272d7821adaf274ad91c288277713d9c18820d8499a7ff69e9a"
-dependencies = [
- "typenum",
- "version_check",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.2.17"
@@ -752,20 +734,6 @@ dependencies = [
  "wasm-bindgen",
 ]
 
-[[package]]
-name = "getrandom"
-version = "0.3.4"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "899def5c37c4fd7b2664648c28120ecec138e4d395b459e5ca34f9cce2dd77fd"
-dependencies = [
- "cfg-if",
- "js-sys",
- "libc",
- "r-efi 5.3.0",
- "wasip2",
- "wasm-bindgen",
-]
-
 [[package]]
 name = "getrandom"
 version = "0.4.3"
@@ -775,11 +743,30 @@ dependencies = [
  "cfg-if",
  "js-sys",
  "libc",
- "r-efi 6.0.0",
+ "r-efi",
  "rand_core 0.10.1",
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "h2"
+version = "0.4.19"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "ef8e5e5a340588f4452631496976cf8636d4a7ecf600239fdc27615d2530bc16"
+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"
@@ -788,11 +775,11 @@ checksum = "8a9ee70c43aaf417c914396645a0fa852624801b24ebb7ae78fe8272889ac888"
 
 [[package]]
 name = "hashbrown"
-version = "0.14.5"
+version = "0.16.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e5274423e17b7c9fc20b6e7e208532f9b19825d82dfd615708b70edd83df41f1"
+checksum = "841d1cc9bed7f9236f321df977030373f4a4163ae1a7dbfe1a51a2c1a51d9100"
 dependencies = [
- "ahash",
+ "foldhash",
 ]
 
 [[package]]
@@ -800,14 +787,17 @@ name = "hashbrown"
 version = "0.17.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
+dependencies = [
+ "foldhash",
+]
 
 [[package]]
 name = "hashlink"
-version = "0.9.1"
+version = "0.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6ba4ff7128dee98c7dc9794b6a411377e1404dba1c97deb8d1a55297bd25d8af"
+checksum = "a596f1b20ed2cc5ecac41a164aaebc7258057060f06c0cf7a2ba3991ee7990fb"
 dependencies = [
- "hashbrown 0.14.5",
+ "hashbrown 0.17.1",
 ]
 
 [[package]]
@@ -830,9 +820,9 @@ checksum = "7f24254aa9a54b5c858eaee2f5bccdb46aaf0e486a595ed5fd8f86ba55232a70"
 
 [[package]]
 name = "hmac"
-version = "0.12.1"
+version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "6c49c37c09c17a53d937dfbb742eb3a961d65a994e6bcdcf37e7399d0cc8ab5e"
+checksum = "6303bc9732ae41b04cb554b844a762b4115a61bfaa81e3e83050991eeb56863f"
 dependencies = [
  "digest",
 ]
@@ -894,6 +884,15 @@ version = "2.4.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "15cdd26707701c53297e2fa6afb323d55fbc1d0810c3aec078ae3ef0424c3c15"
 
+[[package]]
+name = "hybrid-array"
+version = "0.4.15"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "27f864f10dfb56725ce5ce5472bc52252c8f93a4ab86327122cebf62c5f59a17"
+dependencies = [
+ "typenum",
+]
+
 [[package]]
 name = "hyper"
 version = "1.11.1"
@@ -904,6 +903,7 @@ dependencies = [
  "bytes",
  "futures-channel",
  "futures-core",
+ "h2",
  "http",
  "http-body",
  "httparse",
@@ -1132,11 +1132,11 @@ dependencies = [
 
 [[package]]
 name = "inout"
-version = "0.1.4"
+version = "0.2.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "879f10e63c20629ecabbb64a8010319738c66a5cd0c29b02d63d272b03751d01"
+checksum = "4250ce6452e92010fdf7268ccc5d14faa80bb12fc741938534c58f16804e03c7"
 dependencies = [
- "generic-array",
+ "hybrid-array",
 ]
 
 [[package]]
@@ -1153,7 +1153,7 @@ checksum = "3640c1c38b8e4e43584d8df18be5fc6b0aa314ce6ebf51b53313d4306cca8e46"
 dependencies = [
  "hermit-abi",
  "libc",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -1252,6 +1252,12 @@ dependencies = [
  "wasm-bindgen",
 ]
 
+[[package]]
+name = "libbz2-rs-sys"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "34b357333733e8260735ba5894eb928c02ecc69c78715f01a8019e7fa7f2db4c"
+
 [[package]]
 name = "libc"
 version = "0.2.189"
@@ -1260,9 +1266,9 @@ checksum = "3eaf3ede3fee6db1a4c2ee091bf8a8b4dccdc6d17f656fb07896ee72867612f2"
 
 [[package]]
 name = "libsqlite3-sys"
-version = "0.30.1"
+version = "0.38.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "2e99fb7a497b1e3339bc746195567ed8d3e24945ecd636e3619d20b9de9e9149"
+checksum = "f1d20bef17f513b9b3004532233187769cd072d790971f4e4da0e346eb6401e8"
 dependencies = [
  "cc",
  "pkg-config",
@@ -1309,24 +1315,12 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "4050469837a6ff301cd14c1f8f24f88549e6d548f24f64e2148eb0f72cebc51f"
 
 [[package]]
-name = "lzma-rs"
-version = "0.3.0"
+name = "lzma-rust2"
+version = "0.16.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "297e814c836ae64db86b36cf2a557ba54368d03f6afcd7d947c266692f71115e"
+checksum = "ca93e534d1142d1d0dcca6d25fe302508a5dfb40b302802904577725ea0b695b"
 dependencies = [
- "byteorder",
- "crc",
-]
-
-[[package]]
-name = "lzma-sys"
-version = "0.1.20"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "5fda04ab3764e6cde78b9974eec4f779acaba7c4e84b36eca3cf77c581b85d27"
-dependencies = [
- "cc",
- "libc",
- "pkg-config",
+ "sha2",
 ]
 
 [[package]]
@@ -1443,9 +1437,9 @@ dependencies = [
 
 [[package]]
 name = "pbkdf2"
-version = "0.12.2"
+version = "0.13.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f8ed6a7761f76e3b9f92dfb0a60a6a6477c61024b775147ff0973a02653abaf2"
+checksum = "112d82ceb8c5bf524d9af484d4e4970c9fd5a0cc15ba14ad93dccd28873b0629"
 dependencies = [
  "digest",
  "hmac",
@@ -1532,6 +1526,12 @@ version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "439ee305def115ba05938db6eb1644ff94165c5ab5e9420d1c1bcedbba909391"
 
+[[package]]
+name = "ppmd-rust"
+version = "1.5.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "196a7c80b9a7652aba7cc070827516c2abe4ccdf53d128e1944003cf5726cff1"
+
 [[package]]
 name = "ppv-lite86"
 version = "0.2.21"
@@ -1644,7 +1644,7 @@ dependencies = [
  "once_cell",
  "socket2",
  "tracing",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -1656,12 +1656,6 @@ dependencies = [
  "proc-macro2",
 ]
 
-[[package]]
-name = "r-efi"
-version = "5.3.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "69cdb34c158ceb288df11e18b4bd39de994f6657d83847bdffdbd7f346754b0f"
-
 [[package]]
 name = "r-efi"
 version = "6.0.0"
@@ -1801,6 +1795,7 @@ dependencies = [
  "bytes",
  "futures-core",
  "futures-util",
+ "h2",
  "http",
  "http-body",
  "http-body-util",
@@ -1857,10 +1852,20 @@ dependencies = [
 ]
 
 [[package]]
-name = "rusqlite"
-version = "0.32.1"
+name = "rsqlite-vfs"
+version = "0.1.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "7753b721174eb8ff87a9a0e799e2d7bc3749323e773db92e0984debb00019d6e"
+checksum = "c51c9ae4df8a7fba42103df5c621fa3c37eccf3a3c650879e90fc48b11cc192c"
+dependencies = [
+ "hashbrown 0.16.1",
+ "thiserror",
+]
+
+[[package]]
+name = "rusqlite"
+version = "0.40.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "23f2a97da3e3873c73cb2a2e71b35c40ff95e0b1eefa8d72d8499a6928c3b5b3"
 dependencies = [
  "bitflags 2.13.2",
  "fallible-iterator",
@@ -1868,6 +1873,7 @@ dependencies = [
  "hashlink",
  "libsqlite3-sys",
  "smallvec",
+ "sqlite-wasm-rs",
 ]
 
 [[package]]
@@ -1886,7 +1892,7 @@ dependencies = [
  "errno",
  "libc",
  "linux-raw-sys",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -2067,12 +2073,23 @@ dependencies = [
 
 [[package]]
 name = "sha1"
-version = "0.10.7"
+version = "0.11.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "a978451301f4db1d02937a4ab3ccce137717b81826e79b7d49ffe3244a13c3b8"
+checksum = "aacc4cc499359472b4abe1bf11d0b12e688af9a805fa5e3016f9a386dc2d0214"
 dependencies = [
  "cfg-if",
- "cpufeatures 0.2.17",
+ "cpufeatures",
+ "digest",
+]
+
+[[package]]
+name = "sha2"
+version = "0.11.0"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "446ba717509524cb3f22f17ecc096f10f4822d76ab5c0b9822c5f9c284e825f4"
+dependencies = [
+ "cfg-if",
+ "cpufeatures",
  "digest",
 ]
 
@@ -2120,6 +2137,18 @@ dependencies = [
  "windows-sys 0.61.2",
 ]
 
+[[package]]
+name = "sqlite-wasm-rs"
+version = "0.5.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "dc3efc0da82635d7e1ced0053bbbfa8c7ab9645d0bf36ceb4f7127bb85315d75"
+dependencies = [
+ "cc",
+ "js-sys",
+ "rsqlite-vfs",
+ "wasm-bindgen",
+]
+
 [[package]]
 name = "stable_deref_trait"
 version = "1.2.1"
@@ -2289,7 +2318,7 @@ dependencies = [
  "getrandom 0.4.3",
  "once_cell",
  "rustix",
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -2328,6 +2357,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "cdb87b95ec50ddfa440816d227a17b2ccbdda963a316a727fda0fc4334f7d134"
 dependencies = [
  "deranged",
+ "js-sys",
  "num-conv",
  "powerfmt",
  "serde_core",
@@ -2451,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",
@@ -2502,6 +2537,12 @@ version = "0.2.5"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e421abadd41a4225275504ea4d6566923418b7f05506fbc9c0fe86ba7396114b"
 
+[[package]]
+name = "typed-path"
+version = "0.12.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+checksum = "8e28f89b80c87b8fb0cf04ab448d5dd0dd0ade2f8891bae878de66a75a28600e"
+
 [[package]]
 name = "typenum"
 version = "1.20.1"
@@ -2568,12 +2609,6 @@ version = "0.2.15"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "accd4ea62f7bb7a82fe23066fb0957d48ef677f6eeb8215f372f52e48bb32426"
 
-[[package]]
-name = "version_check"
-version = "0.9.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "0b928f33d975fc6ad9f86c8f283853ad26bdd5b10b7f1542aa2fa15e2289105a"
-
 [[package]]
 name = "want"
 version = "0.3.1"
@@ -2589,15 +2624,6 @@ version = "0.11.1+wasi-snapshot-preview1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "ccf3ec651a847eb01de73ccad15eb7d99f80485de043efb2f370cd654f4ea44b"
 
-[[package]]
-name = "wasip2"
-version = "1.0.4+wasi-0.2.12"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b67efb37e106e55ce722a510d6b5f9c17f083e5fc79afc2badeb12cc313d9487"
-dependencies = [
- "wit-bindgen",
-]
-
 [[package]]
 name = "wasm-bindgen"
 version = "0.2.128"
@@ -2701,7 +2727,7 @@ version = "0.1.11"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "c2a7b1c03c876122aa43f3020e6c3c3ee5c05081c9a00739faf7503aeba10d22"
 dependencies = [
- "windows-sys 0.61.2",
+ "windows-sys 0.52.0",
 ]
 
 [[package]]
@@ -2845,12 +2871,6 @@ version = "0.52.6"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "589f6da84c646204747d1270a2a5661ea66ed1cced2631d546fdfb155959f9ec"
 
-[[package]]
-name = "wit-bindgen"
-version = "0.57.1"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "1ebf944e87a7c253233ad6766e082e3cd714b5d03812acc24c318f549614536e"
-
 [[package]]
 name = "writeable"
 version = "0.6.4"
@@ -2859,13 +2879,13 @@ checksum = "3ad82d2a33cdc9674dc7465672f271e096168fcdbe0f799d9e6db8c5892679dc"
 
 [[package]]
 name = "x-media"
-version = "1.6.0"
+version = "1.9.1"
 dependencies = [
  "bytes",
  "dotenv",
  "html-escape",
  "log",
- "rand 0.8.8",
+ "rand 0.10.2",
  "regex",
  "reqwest",
  "serde",
@@ -2879,7 +2899,7 @@ dependencies = [
 
 [[package]]
 name = "xmedia-bot"
-version = "1.6.0"
+version = "1.9.1"
 dependencies = [
  "bytes",
  "dotenv",
@@ -2890,7 +2910,7 @@ dependencies = [
  "parking_lot",
  "png",
  "pretty_env_logger",
- "rand 0.8.8",
+ "rand 0.10.2",
  "rusqlite",
  "serde",
  "serde_json",
@@ -2902,15 +2922,6 @@ dependencies = [
  "zune-jpeg",
 ]
 
-[[package]]
-name = "xz2"
-version = "0.1.7"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "388c44dc09d76f1536602ead6d325eb532f5c122f17782bd57fb47baeeb767e2"
-dependencies = [
- "lzma-sys",
-]
-
 [[package]]
 name = "yoke"
 version = "0.8.3"
@@ -2980,20 +2991,6 @@ name = "zeroize"
 version = "1.9.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "e13c156562582aa81c60cb29407084cdb54c4164760106ab78e6c5b0858cf64e"
-dependencies = [
- "zeroize_derive",
-]
-
-[[package]]
-name = "zeroize_derive"
-version = "1.5.0"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "3c50655cbb0fe3fc43170059e702f1ce5e19b84cec58dc87b037a09935c2f328"
-dependencies = [
- "proc-macro2",
- "quote",
- "syn 2.0.119",
-]
 
 [[package]]
 name = "zerotrie"
@@ -3030,29 +3027,26 @@ dependencies = [
 
 [[package]]
 name = "zip"
-version = "2.4.2"
+version = "8.6.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fabe6324e908f85a1c52063ce7aa26b68dcb7eb6dbc83a2d148403c9bc3eba50"
+checksum = "2d04a6b5381502aa6087c94c669499eb1602eb9c5e8198e534de571f7154809b"
 dependencies = [
  "aes",
- "arbitrary",
  "bzip2",
  "constant_time_eq",
  "crc32fast",
- "crossbeam-utils",
  "deflate64",
- "displaydoc",
  "flate2",
- "getrandom 0.3.4",
+ "getrandom 0.4.3",
  "hmac",
  "indexmap 2.14.2",
- "lzma-rs",
+ "lzma-rust2",
  "memchr",
  "pbkdf2",
+ "ppmd-rust",
  "sha1",
- "thiserror",
  "time",
- "xz2",
+ "typed-path",
  "zeroize",
  "zopfli",
  "zstd",

README.en.md

@@ -1,14 +1,18 @@
 # TelegramXMediaBot
 
-A Telegram bot that turns post links from X / Twitter, Pixiv, Bluesky, and Misskey (misskey.io) into media messages (images, video, GIF) with the post's title, author, and tags.
+A Telegram bot 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.
 
 ## Features
 
-- Sending a link in a private chat fetches and sends the images, videos and GIFs automatically; oversized media is split into batches
-- Text-only posts report "no media"; unsupported links are silently ignored
-- Inline queries (`@bot <link>`)
-- Bind a forward channel for automatic forwarding; edit the caption before forwarding and apply custom templates
-- Failed sends are retried automatically with persistence; the user is notified after retries are exhausted
+- 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 (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)
+- Failed sends are retried automatically with persistence; the notice names which link failed, how long the retry waits, or the final cause
+- The chat action stays on screen for the whole fetch, so long jobs (ugoira transcode, large uploads) do not look stalled
 - Pixiv ugoira animations are transcoded to MP4; Bluesky videos are remuxed (HLS stream → MP4)
 - Photos exceeding Telegram's size/dimension limits are compressed automatically (original format kept, JPEG fallback only when needed)
 - Link-result cache: after a successful send the Telegram file ids and caption fields are cached locally, so a repeated link is re-sent from local state — no source-site request, no media file stored (expiry controlled by `LINK_CACHE_TTL_SECONDS`, default 7 days)
@@ -23,24 +27,29 @@ 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).
+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).
 
-NSFW tweets: the public syndication endpoint does not return sensitive content. Setting `TWITTER_AUTH_TOKEN` (the `auth_token` cookie value of a logged-in x.com session) lets the bot fetch NSFW media in the logged-in state only when it hits a withheld tweet; without it, the bot reports no media.
+NSFW tweets: the public syndication endpoint does not return sensitive content. Setting `TWITTER_AUTH_TOKEN` (the `auth_token` cookie value of a logged-in x.com session) lets the bot fetch NSFW media in the logged-in state only when it hits a withheld tweet; without it the bot answers that the post's media is withheld and needs `TWITTER_AUTH_TOKEN`.
+
+Bilibili dynamics are fetched anonymously by default (no login; the bot fetches bilibili's anonymous `buvid3`/`buvid4` device cookies itself to raise the success rate). If the server's egress IP gets hard-flagged by bilibili (persistent `risk control (-352)` log lines or HTTP 412), set `BILIBILI_COOKIE` (the whole cookie string from a logged-in browser, e.g. `SESSDATA=…; bili_jct=…`) to restore access. Only a dynamic's images and animations are sent; an attached video degrades to its cover image.
 
 ### 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**
@@ -68,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.
 
@@ -80,15 +89,18 @@ Telegram only accepts ports 443/80/88/8443.
 | Variable | Description |
 |---|---|
 | `TELOXIDE_TOKEN` | Bot token (required) |
-| `PIXIV_REFRESH_TOKEN` | Pixiv refresh token; Pixiv is disabled without it |
+| `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 |
+| `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) |
@@ -109,15 +121,17 @@ Telegram only accepts ports 443/80/88/8443.
 | `/help` | List all commands and usage (this command table) |
 | `/set_forward_channel <channel>` | Set the forward channel: `@channel` or channel ID; media messages are forwarded to it automatically afterwards |
 | `/remove_forward_channel` | Remove the forward channel |
-| `/edit_before_forward` | Toggle "edit before forward": when enabled, the bot posts a prompt after forwarding; replying to it edits the first forwarded message's caption (or taps a template button to apply one) |
+| `/edit_before_forward` | Toggle "edit before forward": when enabled, the bot posts a prompt after forwarding; replying to it edits the first forwarded message's caption (or tapping a template button applies one), then `↩️ Confirm` forwards and `🛑 Skip` drops this forward; the prompt states its expiry and is marked expired in place when it lapses (nothing is forwarded) |
 | `/set_template <name>` | Reply to a message containing `[]` to save it as a named template; `[]` is replaced by the original post link when forwarding (used with "edit before forward") |
-| `/set_format <site> <format>` | Customize the caption format for one site. Sites: `twitter` / `bsky` / `pixiv` / `misskey`. Placeholders: `{url}` `{author}` `{author_url}` `{title}` `{tags}` |
+| `/remove_template <name>` | Remove a template (names are listed by `/settings`; the prompt's keyboard shows at most 60) |
+| `/settings` | Show this chat's configuration: forward channel, edit-before-forward, per-site caption formats, saved templates |
+| `/set_format <site> <format>` | Customize the caption format for one site. Sites: `twitter` / `bsky` / `pixiv` / `misskey` / `bilibili`. Placeholders: `{url}` `{author}` `{author_url}` `{title}` `{content}` `{tags}`; unknown placeholders are rejected with the list of valid ones, and `-` restores the site's built-in format (preview with `/debug <link>`) |
 | `/clear_cache [link]` | Clear the link cache (admin only); with a link only that entry, otherwise everything |
 | `/bot_dict` | Show the current chat state (debugging; admin only) |
 | `/test <link>` | Parse a link and send its media; no channel forward, no edit-before-forward prompt (send only) |
 | `/debug <link>` | Debug: parse a link and report the parse result only (site, title, author, tags, media list) — no media is sent |
 
-Link processing works only in private chats; commands work in any chat.
+Link processing works only in private chats; commands work in any chat. A supported link posted in a group gets a one-line hint to use the private chat or inline mode; channels stay silent.
 
 ## Notes
 

README.md

@@ -1,14 +1,18 @@
 # TelegramXMediaBot
 
-Telegram 机器人，将 X / Twitter、Pixiv、Bluesky、Misskey (misskey.io) 的帖子链接转换为媒体消息发送，附带帖子标题、作者与标签。
+Telegram 机器人，将 X / Twitter、Pixiv、Bluesky、Misskey (misskey.io)、Bilibili 动态的帖子链接转换为媒体消息发送，附带帖子标题、作者与标签。
 
 ## 功能
 
-- 私聊发送链接后自动抓取并发送图片、视频与 GIF，超量图片自动分批
-- 纯文字帖提示无媒体；不支持的链接静默忽略
-- 支持内联查询（`@机器人 <链接>`）
-- 可绑定转发频道自动转发；支持转发前编辑 caption 与自定义模板
-- 发送失败自动重试并持久化，重试耗尽后通知用户
+- 私聊发送链接后自动抓取并发送图片、视频与 GIF，超量图片自动分批（每批 10 张）
+- 纯文字帖提示无媒体；不支持的链接静默忽略。抓取失败会按原因分别提示（帖子已删除 / 内容受限 / 源站风控 / 站点未启用）
+- 长帖（正文 ≥ `CAPTION_QUOTE_TEXT_CHARS`，默认 200）的**正文部分**用可折叠引用块展示，链接与作者行留在引用块外
+- 支持内联查询（`@机器人 <链接>`；Pixiv 图片与本地转码的动图不支持内联 —— Telegram 取图时无法携带 Referer，会显示破图，因此跳过；这类查询直接返回空结果，不会一直转圈或反复请求）；在群聊里发链接会提示改用私聊或内联查询（频道内保持静默）
+- `/start` 说明支持的站点与用法，`/help` 列出命令、参数格式、caption 占位符与私聊限制；bot 资料页（description / short description）启动时一并设置
+- `/settings` 查看本聊天配置（转发频道、转发前编辑开关、各站点 caption 格式、模板列表）；模板可用 `/set_template` 增、`/remove_template` 删
+- 可绑定转发频道自动转发；支持转发前编辑 caption 与自定义模板（提示消息带 Confirm / Skip 按钮并写明过期时间，过期后就地标记为已过期）
+- 发送失败自动重试并持久化，重试耗尽后通知用户；提示会写明是哪条链接、重试等待多久、或最终失败的原因
+- 抓取期间持续显示"正在输入 / 正在发送"状态，长任务（ugoira 转码、大图上传）不会看起来卡死
 - Pixiv ugoira 动图自动转码为 MP4；Bluesky 视频自动转码（HLS 流 → MP4）
 - 超过 Telegram 尺寸/大小限制的图片自动压缩（保持原格式，必要时转 JPEG）
 - 链接结果本地缓存：成功发送后缓存 Telegram file id 与 caption 等，再次收到相同链接直接本地重发，不再请求源站、不保存媒体文件（`LINK_CACHE_TTL_SECONDS` 控制过期，默认 7 天）
@@ -23,24 +27,29 @@ 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`（可选）。
+环境变量：`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`（可选）。
 
-NSFW 推文：公开的 syndication 接口不返回敏感内容。设置 `TWITTER_AUTH_TOKEN`（登录 x.com 后浏览器 Cookie 里的 `auth_token` 值）后，bot 会仅在遇到 NSFW 推文时以登录态获取媒体；未设置则提示无媒体。
+NSFW 推文：公开的 syndication 接口不返回敏感内容。设置 `TWITTER_AUTH_TOKEN`（登录 x.com 后浏览器 Cookie 里的 `auth_token` 值）后，bot 会仅在遇到 NSFW 推文时以登录态获取媒体；未设置则回复该推文内容受限（需要配置 `TWITTER_AUTH_TOKEN`）。
+
+Bilibili 动态默认匿名抓取（无需登录，bot 会自动从 B 站的匿名指纹接口取 `buvid3`/`buvid4` 设备 cookie 以提高成功率）。若服务器出口 IP 被 B 站重度风控（日志里的 `risk control (-352)` 或 HTTP 412，且持续出现），设置 `BILIBILI_COOKIE`（登录后浏览器里整条 Cookie 串，如 `SESSDATA=…; bili_jct=…`）可恢复访问。当前只发送动态里的图片与动图，动态内嵌视频发送其封面。
 
 ### 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**
@@ -68,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` 试签，成功后再切正式服务器。
 
@@ -80,15 +89,18 @@ Telegram 只接受 443/80/88/8443 端口。
 | 变量 | 说明 |
 |---|---|
 | `TELOXIDE_TOKEN` | Bot token（必填） |
-| `PIXIV_REFRESH_TOKEN` | Pixiv 刷新令牌；未设置则禁用 Pixiv |
+| `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 |
+| `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 访问时需要） |
@@ -109,15 +121,17 @@ Telegram 只接受 443/80/88/8443 端口。
 | `/help` | 查看全部命令及用法（即本文档的命令表） |
 | `/set_forward_channel <频道>` | 设置转发频道，参数为 `@频道名` 或频道 ID；设置后发送的媒体消息会自动转发到该频道 |
 | `/remove_forward_channel` | 取消转发频道 |
-| `/edit_before_forward` | 开关「转发前编辑」：开启后，转发成功后 bot 会发一条提示消息，回复它可修改第一条转发消息的 caption（或点击模板按钮套用模板） |
+| `/edit_before_forward` | 开关「转发前编辑」：开启后，转发成功后 bot 会发一条提示消息，回复它可修改第一条转发消息的 caption（或点击模板按钮套用模板），再点 `↩️ Confirm` 才会真正转发，`🛑 Skip` 放弃本次转发；提示消息写明过期时间，过期后原地标记为已过期且不会转发 |
 | `/set_template <名称>` | 回复一条含 `[]` 的消息，将其保存为命名模板；转发时 `[]` 会被替换为原帖链接（配合「转发前编辑」使用） |
-| `/set_format <站点> <格式>` | 自定义某站点的 caption 格式。站点：`twitter` / `bsky` / `pixiv` / `misskey`。占位符：`{url}` `{author}` `{author_url}` `{title}` `{tags}` |
+| `/remove_template <名称>` | 删除某个模板（名称见 `/settings`；提示消息的模板按钮最多显示 60 个） |
+| `/settings` | 查看本聊天配置：转发频道、转发前编辑开关、各站点 caption 格式、模板列表 |
+| `/set_format <站点> <格式>` | 自定义某站点的 caption 格式。站点：`twitter` / `bsky` / `pixiv` / `misskey` / `bilibili`。占位符：`{url}` `{author}` `{author_url}` `{title}` `{content}` `{tags}`；未识别的占位符会被拒绝并列出可用项，格式填 `-` 恢复站点默认格式（可用 `/debug <链接>` 预览效果） |
 | `/clear_cache [链接]` | 清空链接缓存（仅管理员）；带链接只清该条，否则清空全部 |
 | `/bot_dict` | 查看当前聊天状态（调试用；仅管理员） |
 | `/test <链接>` | 解析链接并发送媒体；不转发到频道、不弹转发前编辑提示（仅发送） |
 | `/debug <链接>` | 调试：只解析链接并返回解析结果（站点、标题、作者、标签、媒体列表），不发送任何媒体 |
 
-链接处理仅限私聊；命令在任意聊天可用。
+链接处理仅限私聊；命令在任意聊天可用。在群聊里发受支持的链接会回复一条提示（改用私聊或内联查询），频道内保持静默。
 
 ## 备注
 

crates/x-media/Cargo.toml

@@ -1,22 +1,22 @@
 [package]
 name = "x-media"
-version = "1.6.0"
+version = "1.9.1"
 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"
 html-escape = "0.2"
 url = "2.5.2"
 bytes = "1"
-zip = "2"
+zip = "8"
 tempfile = "3"
 thiserror = "2"
-rand = "0.8"
+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/mod.rs

@@ -0,0 +1,6 @@
+mod interface;
+mod model;
+
+pub use interface::{
+    BilibiliSite, PATTERN, cache_key, enabled, fetch_from_url, is_retryable, media_headers,
+};

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

@@ -0,0 +1,158 @@
+//! Serde DTOs for the Bilibili dynamic detail endpoint
+//! (`/x/polymer/web-dynamic/v1/detail`), mirroring live responses
+//! (field paths verified 2026-09-17). Every field is optional so an API
+//! shape change degrades to "no media" instead of a parse failure.
+
+use serde::Deserialize;
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Detail {
+    /// Business code: `0` = OK, `-352`/`-412` = risk control, `500`/`4101147`
+    /// = gone.
+    pub(crate) code: i64,
+    #[serde(default)]
+    pub(crate) message: Option<String>,
+    #[serde(default)]
+    pub(crate) data: Option<Data>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Data {
+    #[serde(default)]
+    pub(crate) item: Option<Box<Item>>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Item {
+    /// The dynamic id, same numeric id as in the URL.
+    #[serde(default)]
+    pub(crate) id_str: String,
+    #[serde(default)]
+    pub(crate) modules: Option<Modules>,
+    /// The quoted dynamic when this item is a forward. A forward shell often
+    /// carries no media of its own — the original holds it.
+    #[serde(default)]
+    pub(crate) orig: Option<Box<Item>>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Modules {
+    #[serde(default)]
+    pub(crate) module_author: Option<Author>,
+    #[serde(default)]
+    pub(crate) module_dynamic: Option<Dynamic>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Author {
+    #[serde(default)]
+    pub(crate) name: String,
+    #[serde(default)]
+    pub(crate) mid: Option<i64>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Dynamic {
+    #[serde(default)]
+    pub(crate) desc: Option<Desc>,
+    #[serde(default)]
+    pub(crate) major: Option<Major>,
+    /// A single topic (`{"id":…,"name":…}`), the dynamic's only tag source.
+    #[serde(default)]
+    pub(crate) topic: Option<Topic>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Desc {
+    #[serde(default)]
+    pub(crate) text: String,
+}
+
+/// `major` is a tagged union: `type` (`MAJOR_TYPE_DRAW` / `_OPUS` /
+/// `_ARCHIVE` / …) plus one payload object per type. Only the three payloads
+/// this adapter reads are modeled; an unknown major simply yields no media.
+#[derive(Deserialize, Debug)]
+pub(crate) struct Major {
+    #[serde(default)]
+    pub(crate) draw: Option<Draw>,
+    #[serde(default)]
+    pub(crate) opus: Option<Opus>,
+    #[serde(default)]
+    pub(crate) archive: Option<Archive>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Draw {
+    #[serde(default)]
+    pub(crate) items: Vec<Pic>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Pic {
+    /// `major.draw` image URL.
+    #[serde(default)]
+    pub(crate) src: Option<String>,
+    /// `major.opus.pics` image URL — the opus shape names the field
+    /// differently while carrying the same image.
+    #[serde(default)]
+    pub(crate) url: Option<String>,
+}
+
+impl Pic {
+    /// The image URL, whichever key this serialization put it under.
+    pub(crate) fn url(&self) -> Option<&str> {
+        self.src.as_deref().or(self.url.as_deref())
+    }
+}
+
+/// `major.opus`: the serialization of an image/text post the web client asks
+/// for (`features=itemOpusStyle`). It carries the parts the legacy shape drops
+/// entirely — the document title and body of an opus post, whose
+/// `module_dynamic.desc` comes back `null`.
+#[derive(Deserialize, Debug)]
+pub(crate) struct Opus {
+    /// Document headline; often absent.
+    #[serde(default)]
+    pub(crate) title: Option<String>,
+    /// Document body (untruncated: a 307-char sample came back whole).
+    #[serde(default)]
+    pub(crate) summary: Option<Desc>,
+    #[serde(default)]
+    pub(crate) pics: Vec<Pic>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Archive {
+    /// The attached video's cover — the only image an AV dynamic has (the
+    /// video itself is deliberately not resolved, see the module docs).
+    #[serde(default)]
+    pub(crate) cover: Option<String>,
+    /// The video's title. An AV dynamic has no body of its own (`desc` comes
+    /// back `null`), so this card title is the post's content.
+    #[serde(default)]
+    pub(crate) title: Option<String>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct Topic {
+    #[serde(default)]
+    pub(crate) name: String,
+}
+
+/// Response of the anonymous fingerprint endpoint (`/x/frontend/finger/spi`),
+/// the source of the adapter's device cookies.
+#[derive(Deserialize, Debug)]
+pub(crate) struct Fingerprint {
+    #[serde(default)]
+    pub(crate) data: Option<FingerprintData>,
+}
+
+#[derive(Deserialize, Debug)]
+pub(crate) struct FingerprintData {
+    /// Sent as the `buvid3` cookie.
+    #[serde(default, rename = "b_3")]
+    pub(crate) buvid3: String,
+    /// Sent as the `buvid4` cookie.
+    #[serde(default, rename = "b_4")]
+    pub(crate) buvid4: String,
+}

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}"))),
         };
     }
@@ -330,13 +421,16 @@ impl From<Post> for Fetched {
             url: url.clone(),
             author: encode_text(&post.author).into_owned(),
             author_url: author_url.clone(),
-            title: encode_text(&post.text).into_owned(),
+            // A post has no title: its text is all content.
+            title: String::new(),
+            content: encode_text(&post.text).into_owned(),
             tags: String::new(),
         });
         Fetched {
             source_url: url,
             caption: post.caption(),
-            title: post.text.clone(),
+            title: String::new(),
+            content: post.text.clone(),
             media: post.media,
             sensitive: post.sensitive,
             site_id: "bsky",
@@ -357,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 = [
@@ -389,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!({
@@ -410,7 +532,8 @@ mod tests {
             fetched.source_url,
             "https://bsky.app/profile/user.bsky.social/post/3xxxx"
         );
-        assert_eq!(fetched.title, "hello <world>");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "hello <world>");
         assert_eq!(fetched.media.len(), 1);
         assert!(!fetched.sensitive);
         // display_name absent -> empty fallback
@@ -456,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}")),
         });
     }
@@ -123,21 +125,23 @@ impl From<model::Note> for Fetched {
         let cw = content.cw.as_deref().unwrap_or_default();
         // Notes carry hashtags inline in the text (no structured tags array);
         // a CW note gets the marker prefixed so recipients see the spoiler.
-        let mut title = cw.to_string();
-        if !cw.is_empty() && !title.ends_with(' ') {
-            title.push(' ');
+        let mut text = cw.to_string();
+        if !cw.is_empty() && !text.ends_with(' ') {
+            text.push(' ');
         }
-        title.push_str(content.text.as_deref().unwrap_or_default().trim());
-        let title = title.trim().to_string();
+        text.push_str(content.text.as_deref().unwrap_or_default().trim());
+        let text = text.trim().to_string();
 
-        let caption = caption(&url, &author_url, &author, &title);
+        let caption = caption(&url, &author_url, &author, &text);
         let sensitive = content.cw.is_some() || content.files.iter().any(|f| f.is_sensitive);
         let media: Vec<Media> = content.files.iter().filter_map(media_from_file).collect();
 
         Fetched {
             source_url: url.clone(),
             caption,
-            title: title.clone(),
+            // A note has no title: its text (CW marker included) is content.
+            title: String::new(),
+            content: text.clone(),
             media,
             sensitive,
             site_id: "misskey",
@@ -145,7 +149,8 @@ impl From<model::Note> for Fetched {
                 url,
                 author: encode_text(&author).into_owned(),
                 author_url: author_url.clone(),
-                title: encode_text(&title).into_owned(),
+                title: String::new(),
+                content: encode_text(&text).into_owned(),
                 tags: String::new(),
             }),
             _keep_alive: None,
@@ -257,7 +262,8 @@ mod tests {
             "https://misskey.io/notes/aotihl10lqrs015s"
         );
         assert_eq!(fetched.site_id, "misskey");
-        assert_eq!(fetched.title, "hello");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "hello");
         assert!(fetched.sensitive);
         assert_eq!(fetched.media.len(), 1);
         match &fetched.media[0] {
@@ -308,7 +314,8 @@ mod tests {
         note["text"] = serde_json::json!("body");
         let fetched: Fetched = note_json(note).into();
         assert!(fetched.sensitive);
-        assert_eq!(fetched.title, "spoiler body");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "spoiler body");
     }
 
     #[test]
@@ -341,7 +348,8 @@ mod tests {
             }
         });
         let fetched: Fetched = note_json(note).into();
-        assert_eq!(fetched.title, "inner text");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "inner text");
         assert_eq!(fetched.media.len(), 1);
         // The source URL still points at the renote shell the user posted.
         assert_eq!(

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

@@ -1,8 +1,8 @@
 //! Site fetching dispatcher and unified result types.
 //!
-//! Dispatch order: twitter → bsky → misskey → pixiv. Each site module
-//! exports a `PATTERN`, `enabled()` and `fetch_from_url()`; a future site
-//! plugs in by adding one guarded entry in `SITES`.
+//! Dispatch order: twitter → bsky → misskey → pixiv → bilibili. Each site
+//! module exports a `PATTERN`, `enabled()` and `fetch_from_url()`; a future
+//! site plugs in by adding one guarded entry in `SITES`.
 
 use std::future::Future;
 use std::pin::Pin;
@@ -13,6 +13,7 @@ use std::time::Duration;
 use regex::Regex;
 use thiserror::Error;
 
+pub mod bilibili;
 pub mod bsky;
 pub mod misskey;
 pub mod pixiv;
@@ -20,50 +21,76 @@ pub mod twitter;
 
 pub use pixiv::PixivError;
 
-/// The result of fetching a post: canonical URL, HTML caption, raw text,
-/// media list and spoiler flag. Produced by [`fetch`].
+/// The result of fetching a post: canonical URL, HTML caption, the post's
+/// title and body, media list and spoiler flag. Produced by [`fetch`].
 #[derive(Debug)]
 pub struct Fetched {
     /// Canonical URL: `x.com/{author}/status/{id}` |
     /// `https://www.pixiv.net/artworks/{id}` |
-    /// `https://bsky.app/profile/{handle}/post/{rkey}`
+    /// `https://bsky.app/profile/{handle}/post/{rkey}` |
+    /// `https://www.bilibili.com/opus/{id}`
     pub source_url: String,
     /// The exact HTML produced by the site's caption().
     pub caption: String,
-    /// Raw post text (tweet text / bsky text / pixiv title).
+    /// The post's own title, where the platform has one: a pixiv artwork's
+    /// title, the headline of a bilibili opus post or the title of the video
+    /// an AV dynamic attaches. Empty on the platforms whose posts are text
+    /// only (x/twitter, bsky, misskey) and on bilibili posts without a
+    /// headline.
     pub title: String,
+    /// The post's body text, as the platform exposes it: a tweet, a bsky or
+    /// misskey post, a bilibili dynamic's text, a pixiv artwork's description
+    /// (HTML flattened). Empty when the post has no text at all.
+    pub content: String,
     pub media: Vec<crate::media::Media>,
     /// Spoiler flag for all media of this post.
     pub sensitive: bool,
-    /// Site id (`"twitter"` / `"bsky"` / `"pixiv"`): the single source of
+    /// Site id (`"twitter"` / `"bsky"` / `"pixiv"` / `"bilibili"`): the single source of
     /// truth for site identity — caption-format lookup, cache-key prefix and
     /// the SetFormat whitelist all derive from it. Set by the producing site.
     pub site_id: &'static str,
     /// 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} {tags}` placeholders in
-/// user-supplied caption formats, substituted by [`caption_from_fields`] as
-/// HTML text (never as an attribute value).
+/// Values for the `{url} {author} {author_url} {title} {content} {tags}`
+/// placeholders in user-supplied caption formats, substituted by
+/// [`caption_from_fields`] as HTML text (never as an attribute value).
 ///
-/// `author`, `title` and `tags` come from the site API (post text, display
-/// names) and are HTML-escaped at construction. `url` and `author_url` stay
-/// raw: they are canonical URLs the adapter builds from numeric ids and
-/// API-constrained handles/DIDs, so they carry no escapable character — the
-/// bot's `/test` report relies on that when it embeds them.
+/// `author`, `title`, `content` and `tags` come from the site API (post
+/// text, display names, descriptions) and are HTML-escaped at construction.
+/// `url` and `author_url` stay raw: they are canonical URLs the adapter
+/// builds from numeric ids and API-constrained handles/DIDs, so they carry
+/// no escapable character — the bot's `/test` report relies on that when it
+/// embeds them.
 #[derive(Debug)]
 pub(crate) struct RenderData {
     pub url: String,
     pub author: String,
     pub author_url: String,
     pub title: String,
+    pub content: String,
     pub tags: String,
 }
 
+/// The post's text as one string: title and content joined by a line break,
+/// each only when it is non-empty. This is what the sites' built-in captions
+/// show after the author line, and what the bot quotes when it is long.
+pub fn compose_text(title: &str, content: &str) -> String {
+    match (title.is_empty(), content.is_empty()) {
+        (false, false) => format!("{title}\n{content}"),
+        (false, true) => title.to_string(),
+        (true, false) => content.to_string(),
+        (true, true) => String::new(),
+    }
+}
+
 impl Fetched {
     /// The site this post came from (used for per-site format overrides).
     /// A thin alias over [`Fetched::site_id`] kept for callers that read the
@@ -87,32 +114,36 @@ impl Fetched {
                 &data.author,
                 &data.author_url,
                 &data.title,
+                &data.content,
                 &data.tags,
             ),
             _ => truncate_caption(&self.caption),
         }
     }
 
-    /// The pre-escaped placeholder values (author, author_url, title, tags)
-    /// a caller needs to rebuild a caption later, e.g. for a cached post
-    /// where the [`Fetched`] is no longer available.
-    pub fn render_fields(&self) -> Option<(&str, &str, &str, &str)> {
+    /// The pre-escaped placeholder values (author, author_url, title,
+    /// content, tags) a caller needs to rebuild a caption later, e.g. for a
+    /// cached post where the [`Fetched`] is no longer available.
+    pub fn render_fields(&self) -> Option<(&str, &str, &str, &str, &str)> {
         self.render_data.as_ref().map(|d| {
             (
                 d.author.as_str(),
                 d.author_url.as_str(),
                 d.title.as_str(),
+                d.content.as_str(),
                 d.tags.as_str(),
             )
         })
     }
 
-    /// 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()
     }
 }
 
@@ -147,6 +178,11 @@ pub fn truncate_caption(caption: &str) -> String {
 /// [`Fetched::caption_with`]. An empty format returns `built_in` unchanged.
 /// The result is truncated to [`MAX_CAPTION_CHARS`] (Telegram's caption
 /// limit for HTML parse mode).
+///
+/// One flat argument per placeholder keeps the two callers (the fresh and the
+/// cached caption path) mirroring each other; the same shape as the bot's
+/// `debug_report`.
+#[allow(clippy::too_many_arguments)]
 pub fn caption_from_fields(
     format: &str,
     built_in: &str,
@@ -154,6 +190,7 @@ pub fn caption_from_fields(
     author: &str,
     author_url: &str,
     title: &str,
+    content: &str,
     tags: &str,
 ) -> String {
     if format.is_empty() {
@@ -166,6 +203,7 @@ pub fn caption_from_fields(
             .replace("{author}", author)
             .replace("{author_url}", author_url)
             .replace("{title}", title)
+            .replace("{content}", content)
             .replace("{tags}", tags),
     )
 }
@@ -214,6 +252,12 @@ pub enum FetchError {
     NotFound,
     #[error("blocked")]
     Blocked,
+    /// The URL matches a registered site that is disabled right now (pixiv
+    /// without `PIXIV_REFRESH_TOKEN`, or after a failed login). Distinct from
+    /// `Ok(None)` — an unsupported link — so the bot can tell the user why
+    /// the link was not handled instead of silently ignoring it.
+    #[error("{site} support is disabled")]
+    Disabled { site: &'static str },
     /// The post exists but its content is withheld (twitter NSFW /
     /// age-restricted tweets come back as an empty `{}` from syndication).
     #[error("content withheld (sensitive)")]
@@ -221,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),
@@ -230,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.
@@ -256,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.
@@ -283,7 +424,7 @@ pub(crate) fn log_once_ffmpeg_missing() {
 }
 
 /// Site adapter: one impl per supported site (twitter / bsky / misskey /
-/// pixiv), registered in `SITES`. All site-specific knowledge — URL pattern,
+/// pixiv / bilibili), registered in `SITES`. All site-specific knowledge — URL pattern,
 /// cache-key format, fetch, retry policy, media-host headers, startup
 /// validation — lives in the site module; the central dispatcher only
 /// iterates the registry.
@@ -294,9 +435,9 @@ pub(crate) fn log_once_ffmpeg_missing() {
 /// site structs are stateless unit structs, so the boxed futures never
 /// borrow from `self` beyond the call's scope.
 pub trait Site: Send + Sync {
-    /// Stable site id (`"twitter"` / `"bsky"` / `"misskey"` / `"pixiv"`):
-    /// caption-format lookup, cache-key prefixes and the SetFormat whitelist
-    /// derive from it.
+    /// Stable site id (`"twitter"` / `"bsky"` / `"misskey"` / `"pixiv"` /
+    /// `"bilibili"`): caption-format lookup, cache-key prefixes and the
+    /// SetFormat whitelist derive from it.
     fn id(&self) -> &'static str;
     /// URL pattern; the dispatcher's first match wins (dispatch order).
     fn pattern(&self) -> &'static Regex;
@@ -332,14 +473,15 @@ pub trait Site: Send + Sync {
 type SiteFuture<'a, T, E = FetchError> = Pin<Box<dyn Future<Output = Result<T, E>> + Send + 'a>>;
 
 /// The one registry of supported sites, in dispatch order (twitter → bsky →
-/// misskey → pixiv). Adding a site = new module + one `Box::new(...)` entry
-/// here; the bot crate never lists sites itself.
+/// misskey → pixiv → bilibili). Adding a site = new module + one
+/// `Box::new(...)` entry here; the bot crate never lists sites itself.
 static SITES: LazyLock<Vec<Box<dyn Site>>> = LazyLock::new(|| {
     vec![
         Box::new(twitter::TwitterSite),
         Box::new(bsky::BskySite),
         Box::new(misskey::MisskeySite),
         Box::new(pixiv::PixivSite),
+        Box::new(bilibili::BilibiliSite),
     ]
 });
 
@@ -351,6 +493,17 @@ fn find_site(url: &str) -> Option<&'static dyn Site> {
         .map(|site| site.as_ref())
 }
 
+/// The site whose pattern matches `url` but which is disabled right now.
+/// `None` when no site matches the URL at all, or when the matching site is
+/// enabled. Lets the dispatcher tell "unsupported link" (silently ignored)
+/// apart from "this bot has that site switched off" (reported to the user).
+fn disabled_site(url: &str) -> Option<&'static str> {
+    SITES
+        .iter()
+        .find(|site| !site.enabled() && site.pattern().is_match(url))
+        .map(|site| site.id())
+}
+
 /// Every supported site id, in dispatch order. The bot's SetFormat whitelist
 /// derives from this list.
 pub fn site_ids() -> Vec<&'static str> {
@@ -374,7 +527,9 @@ pub async fn validate_all() -> Vec<(&'static str, String)> {
 }
 
 /// Fetches a post from its URL. Returns `Ok(None)` when no site pattern
-/// matches (unsupported links are silently ignored by the bot).
+/// matches (unsupported links are silently ignored by the bot) and
+/// [`FetchError::Disabled`] when the URL belongs to a registered site that is
+/// switched off right now — the two are different answers for the user.
 ///
 /// Transient failures are retried: 3 total attempts with 1s then 2s delays.
 /// What counts as transient is the matched site's own policy (`is_retryable`
@@ -397,18 +552,28 @@ 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 {
-        return Ok(None);
+        // A registered-but-disabled site (pixiv without a token) is not an
+        // unsupported link: report it, so the bot answers the user instead of
+        // ignoring the message.
+        return match disabled_site(url) {
+            Some(site) => Err(FetchError::Disabled { site }),
+            None => Ok(None),
+        };
     };
     for attempt in 0..attempts.max(1) {
         match site.fetch_from_url(url).await {
             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));
             }
@@ -424,9 +589,96 @@ async fn fetch_with_attempts(url: &str, attempts: u32) -> Result<Option<Fetched>
     unreachable!("retry loop always returns")
 }
 
+/// Whether fetching `url` requires site-specific headers (pixiv's `Referer`
+/// for `pximg.net` hotlink protection, see [`Site::media_headers`]). Telegram's
+/// own fetch of a media URL sends none of them, so a URL that needs them fails
+/// there — callers that hand a URL to Telegram (inline query results) must
+/// skip such media instead of shipping a broken item.
+pub fn needs_media_headers(url: &str) -> bool {
+    SITES.iter().any(|site| site.media_headers(url).is_some())
+}
+
 /// 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) {
@@ -438,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
     {
@@ -469,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);
@@ -494,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
     {
@@ -505,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);
@@ -519,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!(
@@ -541,6 +831,10 @@ mod tests {
             cache_key("https://bsky.app/profile/handle.example/post/3lorem"),
             Some("bsky:handle.example/3lorem".into())
         );
+        assert_eq!(
+            cache_key("https://t.bilibili.com/1245284537985925159"),
+            Some("bilibili:1245284537985925159".into())
+        );
         assert_eq!(cache_key("https://example.com/not-a-post"), None);
     }
 
@@ -549,16 +843,21 @@ mod tests {
         assert_eq!(site_id_from_key("twitter:123"), "twitter");
         assert_eq!(site_id_from_key("pixiv:123"), "pixiv");
         assert_eq!(site_id_from_key("bsky:handle.example/3lorem"), "bsky");
+        assert_eq!(site_id_from_key("bilibili:123"), "bilibili");
         assert_eq!(site_id_from_key("unknown:1"), "unknown");
         assert_eq!(site_id_from_key("no-colon"), "unknown");
     }
 
     #[test]
     fn registry_lists_all_sites_in_dispatch_order() {
-        assert_eq!(site_ids(), vec!["twitter", "bsky", "misskey", "pixiv"]);
+        assert_eq!(
+            site_ids(),
+            vec!["twitter", "bsky", "misskey", "pixiv", "bilibili"]
+        );
         // Enabled sites dispatch; unsupported URLs never match.
         assert!(find_site("https://x.com/u/status/1").is_some());
         assert!(find_site("https://misskey.io/notes/abc").is_some());
+        assert!(find_site("https://t.bilibili.com/1245284537985925159").is_some());
         assert!(find_site("https://example.com/x").is_none());
         // Cache keys are pattern-driven, independent of the enabled() gate
         // (pixiv is disabled in tests without PIXIV_REFRESH_TOKEN).
@@ -586,25 +885,34 @@ mod tests {
         // The format string is escaped, the field values are substituted
         // verbatim (callers pass the already-escaped render data).
         let out = caption_from_fields(
-            "see {author} at {url} — {title}",
+            "see {author} at {url} — {title}: {content}",
             "",
             "https://x.com/u/status/1",
             "A &amp; B",
             "https://x.com/u",
             "hello <world>",
+            "the body",
             "",
         );
         assert_eq!(
             out,
-            "see A &amp; B at https://x.com/u/status/1 — hello <world>"
+            "see A &amp; B at https://x.com/u/status/1 — hello <world>: the body"
         );
         // Empty format keeps the built-in caption untouched.
         assert_eq!(
-            caption_from_fields("", "built-in", "u", "a", "au", "t", "g"),
+            caption_from_fields("", "built-in", "u", "a", "au", "t", "c", "g"),
             "built-in"
         );
     }
 
+    #[test]
+    fn compose_text_joins_title_and_content() {
+        assert_eq!(compose_text("标题", "正文"), "标题\n正文");
+        assert_eq!(compose_text("标题", ""), "标题");
+        assert_eq!(compose_text("", "正文"), "正文");
+        assert_eq!(compose_text("", ""), "");
+    }
+
     #[test]
     fn truncate_caption_keeps_short_text() {
         assert_eq!(truncate_caption("short"), "short");
@@ -627,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]
@@ -644,16 +964,151 @@ 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]
+    fn media_headers_are_reported_only_where_telegram_would_fail() {
+        // pixiv's CDN needs a Referer, which only the bot can send: an inline
+        // result pointing at it renders broken, so callers skip it.
+        assert!(needs_media_headers(
+            "https://i.pximg.net/img-original/img/2024/01/01/00/00/00/1_p0.jpg"
+        ));
+        // The rest serve direct requests (verified per site in their modules).
+        for url in [
+            "https://pbs.twimg.com/media/1.jpg",
+            "https://cdn.bsky.app/img/1.jpg",
+            "https://media.misskeyusercontent.jp/io/1.webp",
+            "https://i0.hdslb.com/bfs/1.jpg",
+        ] {
+            assert!(!needs_media_headers(url), "{url}");
+        }
+    }
+
+    #[tokio::test]
+    async fn disabled_site_is_reported_not_ignored() {
+        // pixiv is the only token-gated site; with PIXIV_REFRESH_TOKEN set it
+        // is enabled and this link would hit the network, so skip then.
+        if std::env::var("PIXIV_REFRESH_TOKEN")
+            .ok()
+            .filter(|s| !s.is_empty())
+            .is_some()
+        {
+            eprintln!("skipping: PIXIV_REFRESH_TOKEN is set");
+            return;
+        }
+        let result = fetch("https://www.pixiv.net/artworks/1").await;
+        assert!(
+            matches!(result, Err(FetchError::Disabled { site: "pixiv" })),
+            "got {result:?}"
+        );
+        // The cache key still resolves: the bot keys the reply and the link
+        // cache off it even when the site is off.
+        assert_eq!(
+            cache_key("https://www.pixiv.net/artworks/1"),
+            Some("pixiv:1".into())
+        );
     }
 
     #[tokio::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`.
@@ -107,17 +121,67 @@ pub fn media_headers(url: &str) -> Option<Vec<(&'static str, String)>> {
     }
 }
 
+/// Flattens the app API's HTML description into plain text: `<br>` (and `<p>`)
+/// become line breaks, other tags are dropped, entities decoded, the ends
+/// trimmed. A caption shows text, not markup, so the author's `<a href>` links
+/// contribute their link text only.
+fn flatten_html(raw: &str) -> String {
+    let mut out = String::with_capacity(raw.len());
+    let mut chars = raw.chars().peekable();
+    while let Some(c) = chars.next() {
+        // Only `<` followed by `/` or a letter opens a tag — a bare `<` in
+        // prose ("2 < 3") is text.
+        let opens_tag = c == '<'
+            && chars
+                .peek()
+                .is_some_and(|next| *next == '/' || next.is_ascii_alphabetic());
+        if !opens_tag {
+            out.push(c);
+            continue;
+        }
+        let mut tag = String::new();
+        let mut closed = false;
+        for c in chars.by_ref() {
+            if c == '>' {
+                closed = true;
+                break;
+            }
+            tag.push(c);
+        }
+        if !closed {
+            // Unclosed `<…`: keep it as text rather than dropping the tail.
+            out.push('<');
+            out.push_str(&tag);
+            break;
+        }
+        // `<br>`, `<br/>`, `<br />` with or without attributes, and both
+        // halves of a paragraph break the line; everything else is dropped.
+        let tag = tag
+            .trim()
+            .trim_start_matches('/')
+            .trim_end_matches('/')
+            .trim()
+            .to_ascii_lowercase();
+        if tag == "p" || tag.starts_with("br") {
+            out.push('\n');
+        }
+    }
+    html_escape::decode_html_entities(&out).trim().to_string()
+}
+
 #[derive(Debug)]
 pub struct Illustration {
     id: String,
     title: String,
+    /// The artwork's description, HTML flattened to plain text.
+    content: String,
     author: String,
     author_id: String,
     tags: Vec<String>,
     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 {
@@ -150,6 +214,7 @@ impl Illustration {
     pub fn from_model(model: &IllustrationModel) -> Self {
         let id = model.id.to_string();
         let title = model.title.clone();
+        let content = flatten_html(&model.caption);
         let author = model.user.name.clone();
         let author_id = model.user.id.to_string();
         let mut tags: Vec<String> = model.tags.iter().map(|tag| tag.name.clone()).collect();
@@ -193,6 +258,7 @@ impl Illustration {
         Self {
             id,
             title,
+            content,
             author,
             author_id,
             tags,
@@ -218,12 +284,14 @@ impl From<Illustration> for Fetched {
             author: encode_text(&illustration.author).into_owned(),
             author_url: author_url.clone(),
             title: encode_text(&illustration.title).into_owned(),
+            content: encode_text(&illustration.content).into_owned(),
             tags: encode_text(&tags).into_owned(),
         });
         Fetched {
             source_url: url,
             caption: illustration.caption(),
             title: illustration.title.clone(),
+            content: illustration.content.clone(),
             media: illustration.media,
             sensitive: illustration.nsfw,
             site_id: "pixiv",
@@ -262,6 +330,7 @@ mod tests {
             "illust": {
                 "id": 123,
                 "title": "Art <title>",
+                "caption": "一行说明<br />二行 <a href=\"https://x.example/\">链接</a> &amp; 结尾",
                 "type": type_,
                 "image_urls": {
                     "medium": "medium.jpg",
@@ -284,6 +353,44 @@ mod tests {
         Illustration::from_model(&model)
     }
 
+    /// The description arrives as HTML and becomes plain-text content: breaks
+    /// kept, tags dropped (links keep their text), entities decoded.
+    #[test]
+    fn from_json_maps_description_to_content() {
+        let v = illust_json("illust", 1, None, Some("o.jpg"), vec![], 0);
+        let illustration = parse(v);
+        assert_eq!(illustration.content, "一行说明\n二行 链接 & 结尾");
+
+        let fetched: Fetched = illustration.into();
+        assert_eq!(fetched.title, "Art <title>");
+        assert_eq!(fetched.content, "一行说明\n二行 链接 & 结尾");
+        // The built-in caption keeps its layout: the description stays out of
+        // it and is available through `{content}`.
+        assert!(!fetched.caption.contains("一行说明"), "{}", fetched.caption);
+        assert_eq!(
+            fetched.render_fields().unwrap().3,
+            "一行说明\n二行 链接 &amp; 结尾"
+        );
+        assert!(
+            fetched
+                .caption_with("{title}: {content}")
+                .ends_with("一行说明\n二行 链接 &amp; 结尾")
+        );
+    }
+
+    #[test]
+    fn flatten_html_handles_common_markup() {
+        assert_eq!(flatten_html(""), "");
+        assert_eq!(flatten_html("plain"), "plain");
+        assert_eq!(flatten_html("a<br />b<br/>c<br>d"), "a\nb\nc\nd");
+        // A paragraph break is a blank line, exactly like `<br /><br />` —
+        // writing it as one newline would flatten the author's paragraphs.
+        assert_eq!(flatten_html("<p>one</p><p>two</p>"), "one\n\ntwo");
+        assert_eq!(flatten_html("a &amp; b &lt;c&gt;"), "a & b <c>");
+        // Nothing to strip: angle brackets that are not a tag survive.
+        assert_eq!(flatten_html("2 < 3"), "2 < 3");
+    }
+
     #[test]
     fn pattern_matches_all_forms() {
         let cases = [
@@ -317,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/pixiv/model.rs

@@ -6,6 +6,10 @@ use serde::Deserialize;
 pub struct IllustrationModel {
     pub id: u64,
     pub title: String,
+    /// The artwork's description as the app API returns it — HTML in most
+    /// works (`<br />`, `<a href>`, sometimes `<p>`), empty for many.
+    #[serde(default)]
+    pub caption: String,
     pub r#type: TypeModel,
     pub image_urls: ImageUrlsModel,
     pub user: UserInfoModel,

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);
@@ -327,7 +330,8 @@ mod tests {
             "https://x.com/nsfw_author/status/2083868672721039569"
         );
         // The appended media short link (no URL-entity mapping) is stripped.
-        assert_eq!(fetched.title, "nsfw content");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "nsfw content");
     }
 
     #[test]

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

@@ -43,27 +43,25 @@ pub async fn fetch_from_url(url: &str) -> Result<Fetched, FetchError> {
     match fetch(id).await {
         Ok(tweet) => Ok(tweet.into()),
         // Syndication withholds NSFW/age-restricted tweets (empty `{}`).
-        // Retry as the logged-in user when TWITTER_AUTH_TOKEN is set;
-        // otherwise degrade to an empty result (the bot replies
-        // "No media found").
+        // Retry as the logged-in user when TWITTER_AUTH_TOKEN is set; without
+        // the token the withholding is reported as `Sensitive`, so the bot can
+        // answer "age-restricted / needs TWITTER_AUTH_TOKEN" instead of the
+        // misleading "No media found".
         Err(FetchError::Sensitive) => {
             if super::auth::enabled() {
                 match super::auth::fetch(id).await {
                     Ok(tweet) => Ok(tweet.into()),
-                    // The tweet is genuinely gone (deleted / suspended /
-                    // tombstoned): report it instead of degrading to an
-                    // empty result ("No media found"). Only unexpected
-                    // fallback failures (network, parse) keep the NSFW
-                    // placeholder.
-                    Err(FetchError::NotFound) => Err(FetchError::NotFound),
+                    // Deleted/suspended (tombstoned) and unexpected fallback
+                    // failures keep their own class: the bot reports what
+                    // actually happened rather than "No media found".
                     Err(e) => {
                         log::warn!("twitter auth fallback failed for {id}: {e}");
-                        Ok(empty_fetched(url))
+                        Err(e)
                     }
                 }
             } else {
                 log::debug!("tweet {id} is sensitive; set TWITTER_AUTH_TOKEN to fetch NSFW media");
-                Ok(empty_fetched(url))
+                Err(FetchError::Sensitive)
             }
         }
         Err(e) => Err(e),
@@ -90,23 +88,6 @@ pub fn media_headers(_url: &str) -> Option<Vec<(&'static str, String)>> {
     None
 }
 
-/// A Fetched with no media for withheld tweets: the bot replies
-/// "No media found" and moves on instead of erroring.
-fn empty_fetched(url: &str) -> Fetched {
-    Fetched {
-        source_url: url.to_string(),
-        // The raw user-supplied URL goes into an HTML caption; escape it so
-        // crafted links cannot break the parse (Telegram 400).
-        caption: encode_text(url).into_owned(),
-        title: String::new(),
-        media: vec![],
-        sensitive: true,
-        site_id: "twitter",
-        render_data: None,
-        _keep_alive: None,
-    }
-}
-
 /// Fetches a tweet from the syndication endpoint. Deleted/blocked tweets
 /// surface as `FetchError::NotFound`; withheld content (empty tombstone,
 /// age-restricted) as `FetchError::Sensitive`.
@@ -124,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).
@@ -165,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)
 }
@@ -232,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
@@ -352,17 +355,20 @@ impl From<Tweet> for Fetched {
     fn from(tweet: Tweet) -> Self {
         let url = tweet.url();
         let author_url = tweet.author_url();
+        // A tweet has no title: its text is all content.
         let render_data = Some(crate::site::RenderData {
             url: url.clone(),
             author: encode_text(&tweet.author).into_owned(),
             author_url: author_url.clone(),
-            title: encode_text(&tweet.text).into_owned(),
+            title: String::new(),
+            content: encode_text(&tweet.text).into_owned(),
             tags: String::new(),
         });
         Fetched {
             source_url: url,
             caption: tweet.caption(),
-            title: tweet.text.clone(),
+            title: String::new(),
+            content: tweet.text.clone(),
             media: tweet.media,
             sensitive: tweet.sensitive,
             site_id: "twitter",
@@ -432,12 +438,13 @@ 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");
         let fetched: Fetched = tweet.into();
-        assert_eq!(fetched.title, ">^ω^< & more 'quoted'");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, ">^ω^< & more 'quoted'");
         // The caption escapes the raw text exactly once (encode_text covers
         // & < >; apostrophes stay literal — they are harmless in text).
         assert!(
@@ -490,13 +497,14 @@ 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,
             "https://x.com/author_handle/status/861627479294746624"
         );
-        assert_eq!(fetched.title, "a & b <c>");
+        assert_eq!(fetched.title, "");
+        assert_eq!(fetched.content, "a & b <c>");
         assert!(fetched.sensitive);
         assert_eq!(fetched.media.len(), 2);
         match &fetched.media[0] {
@@ -524,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!([
@@ -543,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]
@@ -619,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"
@@ -638,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");
     }
 
@@ -661,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!(
@@ -706,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]
@@ -776,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.6.0"
+version = "1.9.1"
 edition = "2024"
 
 [dependencies]
@@ -13,8 +13,8 @@ pretty_env_logger = "0.5"
 dotenv = "0.15"
 url = "2.5.2"
 html-escape = "0.2"
-rusqlite = { version = "0.32", features = ["bundled"] }
-rand = "0.8"
+rusqlite = { version = "0.40", features = ["bundled"] }
+rand = "0.10"
 tempfile = "3"
 parking_lot = "0.12"
 bytes = "1"

crates/xmedia-bot/src/config.rs

@@ -1,5 +1,6 @@
 //! Central env handling. The only other places that read env are
-//! `Bot::from_env` (TELOXIDE_TOKEN) and x-media (PIXIV_REFRESH_TOKEN).
+//! `Bot::from_env` (TELOXIDE_TOKEN) and x-media (PIXIV_REFRESH_TOKEN,
+//! TWITTER_AUTH_TOKEN, BILIBILI_COOKIE).
 
 use std::env;
 use std::net::IpAddr;
@@ -12,6 +13,10 @@ pub struct Config {
     pub edit_message_ttl: Duration,
     /// LINK_CACHE_TTL_SECONDS, default 604800 (7 days).
     pub link_cache_ttl: Duration,
+    /// CAPTION_QUOTE_TEXT_CHARS, default 200: a post whose text (title plus
+    /// content) is at least this many characters gets that text wrapped in an
+    /// expandable blockquote inside its caption. `0` disables the wrap.
+    pub caption_quote_text_chars: usize,
     // Webhook settings (moved out of main; names/defaults unchanged).
     pub webhook_enabled: bool,
     pub webhook_url: Option<url::Url>,
@@ -57,6 +62,7 @@ impl Config {
             Duration::from_secs(parse_u64("EDIT_MESSAGE_TTL_SECONDS", 24 * 3600));
         let link_cache_ttl =
             Duration::from_secs(parse_u64("LINK_CACHE_TTL_SECONDS", 7 * 24 * 3600));
+        let caption_quote_text_chars = parse_u64("CAPTION_QUOTE_TEXT_CHARS", 200) as usize;
 
         let webhook_enabled = env::var("WEBHOOK")
             .is_ok_and(|v| matches!(v.to_lowercase().as_str(), "true" | "yes" | "1"));
@@ -92,6 +98,7 @@ impl Config {
             admin_ids,
             edit_message_ttl,
             link_cache_ttl,
+            caption_quote_text_chars,
             webhook_enabled,
             webhook_url,
             webhook_listen,

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,
@@ -88,10 +148,20 @@ pub(crate) mod test_support {
             &self.chat_store
         }
 
+        /// The parsed config, mutable so a test can pin a knob (e.g. the
+        /// caption-quote threshold) instead of depending on the environment.
+        pub(crate) fn config_mut(&mut self) -> &mut Config {
+            &mut self.config
+        }
+
         pub(crate) fn link_cache(&self) -> &LinkCache {
             &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

@@ -14,6 +14,8 @@ use teloxide::types::{CallbackQuery, CallbackQueryId, MessageId};
 
 /// The `"forward"` button's data.
 const FORWARD: &str = "forward";
+/// The `"skip"` button's data: drop the prompt without forwarding.
+const SKIP: &str = "skip";
 /// Prefix of a template button's data: `"template|<name>"`.
 const TEMPLATE_PREFIX: &str = "template|";
 
@@ -70,6 +72,29 @@ async fn handle_callback(
     }
 
     log::info!("callback from {chat_id} on prompt {prompt_message_id}: {data}");
+    if data == SKIP {
+        // Skip works with or without a forward channel: it is the explicit
+        // "do not forward this" answer, and it drops the record so the forward
+        // can never happen later.
+        log::info!("edit-before-forward prompt {prompt_message_id} skipped");
+        ctx.chat_store
+            .update(chat_id, |data| {
+                data.edit_message.remove(&prompt_message_id);
+            })
+            .await;
+        let _ = ctx
+            .sender
+            .delete_message(ChatId(chat_id), MessageId(prompt_message_id as i32))
+            .await;
+        let _ = ctx
+            .sender
+            .answer_callback_query(
+                callback_query_id,
+                Some("Skipped — nothing was forwarded.".to_string()),
+            )
+            .await;
+        return;
+    }
     if data == FORWARD {
         match chat_data.forward_channel_id {
             Some(channel_id) => {
@@ -92,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}");
@@ -133,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;
     }
 }
@@ -164,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;
 
@@ -225,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;
 
@@ -245,11 +291,63 @@ mod tests {
     }
 
     #[tokio::test]
-    async fn forward_without_a_channel_is_reported() {
-        let sender = MockSender::scripted(vec![], api_error);
+    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(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;
+
+        assert_eq!(
+            sender.calls(),
+            vec!["delete_message", "answer_callback_query"]
+        );
+        assert_eq!(
+            sender.answers(),
+            vec![Some("Skipped — nothing was forwarded.".to_string())]
+        );
+        assert!(
+            ctx.chat_store.get(1).await.edit_message.is_empty(),
+            "a skipped prompt must drop its record"
+        );
+    }
+
+    /// 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(API_ERROR));
+        let stores = TestStores::new();
+        let ctx = stores.ctx(&sender);
+        seed_prompt(&ctx, "", crate::db::unix_now()).await;
         ctx.chat_store
             .update(1, |data| data.forward_channel_id = None)
             .await;
@@ -264,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);
 
@@ -306,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

@@ -4,6 +4,7 @@
 use super::urls::{PostSend, url_media};
 use super::{CHAT_STORE, CONFIG, LINK_CACHE, log_key, reply, reply_html};
 use crate::ctx::AppContext;
+use crate::state::ChatData;
 use teloxide::RequestError;
 use teloxide::prelude::*;
 use teloxide::types::{ChatId, Message, Recipient};
@@ -33,13 +34,20 @@ pub(crate) enum Command {
         parse_with = "split"
     )]
     SetTemplate(String),
+    #[command(description = "Remove a saved template", parse_with = "split")]
+    RemoveTemplate(String),
+    #[command(description = "Show this chat's settings")]
+    Settings,
     #[command(description = "Show chat state (debug; admin only)")]
     BotDict,
-    #[command(description = "Set site caption format", parse_with = "split")]
+    #[command(
+        description = "Set site caption format (- to reset)",
+        parse_with = parse_arg_remainder
+    )]
     SetFormat(String),
     #[command(
         description = "Clear link cache (admin; optional URL, else all)",
-        parse_with = "split"
+        parse_with = parse_arg_remainder
     )]
     ClearCache(String),
     #[command(
@@ -62,6 +70,118 @@ fn parse_arg_remainder(s: String) -> Result<(String,), ParseError> {
     Ok((s.trim().to_string(),))
 }
 
+/// Placeholders `/set_format` accepts, mirroring what
+/// `x_media::site::caption_from_fields` substitutes.
+const FORMAT_PLACEHOLDERS: [&str; 6] = ["url", "author", "author_url", "title", "content", "tags"];
+
+/// `/start`'s welcome: what the bot is for, where links work, where to look
+/// next. The old "Hello!" left a first-time user with nothing.
+const START_TEXT: &str = "\
+Send me a post link and I'll send back its images, videos and GIFs with the title, author and tags.
+
+Supported: X/Twitter, Pixiv, Bluesky, Misskey (misskey.io), Bilibili.
+In a private chat just paste the link. In a group, use inline mode (type @, pick me, then the link).
+
+/help lists every command.";
+
+/// Appended to `/help`'s command list: argument syntax, caption
+/// placeholders and the private-chat rule — none of which teloxide's
+/// `descriptions()` renders (it prints `/command — description` only).
+const HELP_FOOTER: &str = "\
+Arguments
+  /set_forward_channel <@channel or channel id>
+  /set_template <name> — reply to a message containing [] to save it
+  /remove_template <name> — see /settings for the saved names
+  /set_format <site> <format> — '-' restores the built-in format
+  /test <link> / /debug <link>
+
+Caption placeholders (for /set_format)
+  {url} {author} {author_url} {title} {content} {tags}
+  A template's [] is replaced by the post link when forwarding.
+
+Links are handled in private chats only; in a group use inline mode.";
+
+/// Cap on template names echoed by `/settings`: a chat with hundreds of
+/// templates must not produce a message Telegram rejects for length.
+const MAX_SETTINGS_TEMPLATE_NAMES: usize = 30;
+
+/// Sorted template names: the order `/settings`, `/remove_template` and the
+/// prompt's buttons all show.
+fn sorted_template_names(data: &ChatData) -> Vec<String> {
+    let mut names: Vec<String> = data.template.keys().cloned().collect();
+    names.sort();
+    names
+}
+
+/// `/settings`: what this chat is configured to do, readable by anyone in it
+/// (unlike `/bot_dict`, which dumps the raw state and is admin-only).
+fn settings_text(data: &ChatData) -> String {
+    let mut lines = Vec::new();
+    match data.forward_channel_id {
+        Some(id) => lines.push(format!("Forward channel: {id}")),
+        None => lines.push(
+            "Forward channel: not set (use /set_forward_channel <@channel or id>)".to_string(),
+        ),
+    }
+    lines.push(format!(
+        "Edit before forward: {}",
+        if data.edit_before_forward {
+            "on"
+        } else {
+            "off"
+        }
+    ));
+    let mut formats: Vec<String> = data
+        .message_format
+        .iter()
+        .map(|(site, format)| format!("{site} => {format}"))
+        .collect();
+    formats.sort();
+    lines.push(if formats.is_empty() {
+        "Caption formats: built-in for every site".to_string()
+    } else {
+        format!("Caption formats:\n  {}", formats.join("\n  "))
+    });
+    let names = sorted_template_names(data);
+    lines.push(match names.len() {
+        0 => "Templates: none".to_string(),
+        n => format!(
+            "Templates ({n}): {}{}",
+            names
+                .iter()
+                .take(MAX_SETTINGS_TEMPLATE_NAMES)
+                .cloned()
+                .collect::<Vec<_>>()
+                .join(", "),
+            if n > MAX_SETTINGS_TEMPLATE_NAMES {
+                format!(", +{} more", n - MAX_SETTINGS_TEMPLATE_NAMES)
+            } else {
+                String::new()
+            }
+        ),
+    });
+    lines.join("\n")
+}
+
+/// The first `{…}` token in a caption format that is not a known placeholder
+/// (`None` when all of them are). The renderer replaces exact keys only, so an
+/// unknown token would be published verbatim in every caption of that site —
+/// caught here instead.
+fn unknown_placeholder(format: &str) -> Option<&str> {
+    let mut rest = format;
+    while let Some(open) = rest.find('{') {
+        let after = &rest[open + 1..];
+        // An unclosed `{` is not a placeholder token at all.
+        let close = after.find('}')?;
+        let token = &after[..close];
+        if !FORMAT_PLACEHOLDERS.contains(&token) {
+            return Some(token);
+        }
+        rest = &after[close + 1..];
+    }
+    None
+}
+
 enum SetForwardChannelError {
     EmptyParameter,
     NotChannel,
@@ -140,11 +260,17 @@ pub(crate) async fn execute_command(
 ) -> Result<(), RequestError> {
     match command {
         Command::Start => {
-            bot.send_message(message.chat.id, "Hello!").await?;
+            bot.send_message(message.chat.id, START_TEXT).await?;
         }
         Command::Help => {
-            bot.send_message(message.chat.id, Command::descriptions().to_string())
-                .await?;
+            // The command list plus the parts teloxide's `descriptions()`
+            // cannot show: argument syntax, caption placeholders, and where a
+            // link actually works.
+            bot.send_message(
+                message.chat.id,
+                format!("{}\n\n{}", Command::descriptions(), HELP_FOOTER),
+            )
+            .await?;
         }
         Command::SetForwardChannel(channel) => {
             let result = match set_forward_channel_handler(bot, message, channel).await {
@@ -232,6 +358,41 @@ pub(crate) async fn execute_command(
             };
             reply(bot, message.chat.id.0, message.id, text).await?;
         }
+        Command::RemoveTemplate(name) => {
+            let chat_id = message.chat.id.0;
+            let name = name.trim().to_string();
+            if name.is_empty() {
+                reply(
+                    bot,
+                    chat_id,
+                    message.id,
+                    "Usage: /remove_template <name> (see /settings for the saved names)",
+                )
+                .await?;
+                return Ok(());
+            }
+            let removed = CHAT_STORE
+                .update(chat_id, |data| data.template.remove(&name).is_some())
+                .await;
+            let text = if removed {
+                format!("Template '{name}' removed.")
+            } else {
+                // Name the live templates: a typo would otherwise look like a
+                // successful delete.
+                let names = sorted_template_names(&CHAT_STORE.get(chat_id).await);
+                if names.is_empty() {
+                    format!("No template named '{name}'. None are saved yet.")
+                } else {
+                    format!("No template named '{name}'. Saved: {}", names.join(", "))
+                }
+            };
+            reply(bot, chat_id, message.id, text).await?;
+        }
+        Command::Settings => {
+            let chat_id = message.chat.id.0;
+            let data = CHAT_STORE.get(chat_id).await;
+            reply(bot, chat_id, message.id, settings_text(&data)).await?;
+        }
         Command::BotDict => {
             // Debug dump of the chat's persisted state: admin only (it echoes
             // forward-channel ids and templates to whoever asks).
@@ -279,7 +440,45 @@ pub(crate) async fn execute_command(
                     bot,
                     message.chat.id.0,
                     message.id,
-                    "Unknown site. Use twitter, bsky, pixiv or misskey.",
+                    "Unknown site. Use twitter, bsky, pixiv, misskey or bilibili.",
+                )
+                .await?;
+                return Ok(());
+            }
+            // `-` resets to the site's built-in caption: without it a chat that
+            // set a format once could never get back to the default (the
+            // built-in format string is not something a user can retype).
+            if format == "-" {
+                CHAT_STORE
+                    .update(chat_id, |data| {
+                        data.message_format.remove(site);
+                    })
+                    .await;
+                reply(
+                    bot,
+                    message.chat.id.0,
+                    message.id,
+                    "Format reset to the built-in one.",
+                )
+                .await?;
+                return Ok(());
+            }
+            // A typo like {titel} would otherwise be rendered literally into
+            // every caption of that site (the renderer only substitutes the
+            // exact keys), which is invisible until a post arrives.
+            if let Some(token) = unknown_placeholder(&format) {
+                reply(
+                    bot,
+                    message.chat.id.0,
+                    message.id,
+                    format!(
+                        "Unknown placeholder {{{token}}}. Available: {}",
+                        FORMAT_PLACEHOLDERS
+                            .iter()
+                            .map(|name| format!("{{{name}}}"))
+                            .collect::<Vec<_>>()
+                            .join(" ")
+                    ),
                 )
                 .await?;
                 return Ok(());
@@ -289,7 +488,13 @@ pub(crate) async fn execute_command(
                     data.message_format.insert(site.to_string(), format);
                 })
                 .await;
-            reply(bot, message.chat.id.0, message.id, "Format set.").await?;
+            reply(
+                bot,
+                message.chat.id.0,
+                message.id,
+                "Format set. Use /debug <link> to preview the caption.",
+            )
+            .await?;
         }
         Command::ClearCache(arg) => {
             let sender_id = message
@@ -320,7 +525,7 @@ pub(crate) async fn execute_command(
                             bot,
                             message.chat.id.0,
                             message.id,
-                            "Unrecognized link. Use a twitter/x, pixiv, bsky or misskey post URL.",
+                            "Unrecognized link. Use a twitter/x, pixiv, bsky, misskey or bilibili post URL.",
                         )
                         .await?;
                         return Ok(());
@@ -358,7 +563,7 @@ pub(crate) async fn execute_command(
                     bot,
                     message.chat.id.0,
                     message.id,
-                    "No enabled site matches this link (twitter/x, pixiv, bsky or misskey).",
+                    "No enabled site matches this link (twitter/x, pixiv, bsky, misskey or bilibili).",
                 )
                 .await?;
                 return Ok(());
@@ -400,7 +605,7 @@ pub(crate) async fn execute_command(
                         bot,
                         message.chat.id.0,
                         message.id,
-                        "No enabled site matches this link (twitter/x, pixiv, bsky or misskey).",
+                        "No enabled site matches this link (twitter/x, pixiv, bsky, misskey or bilibili).",
                     )
                     .await?;
                 }
@@ -414,14 +619,33 @@ pub(crate) async fn execute_command(
                     .await?;
                 }
                 Ok(Some(fetched)) => {
+                    // The preview must show what a link would actually send:
+                    // the chat's per-site format override plus the long-post
+                    // quoting. Rendering the raw built-in caption here made
+                    // `/set_format` look like it did nothing.
+                    let format = CHAT_STORE
+                        .get(message.chat.id.0)
+                        .await
+                        .message_format
+                        .get(fetched.site_name())
+                        .cloned()
+                        .unwrap_or_default();
+                    let caption = preview_caption(
+                        &format,
+                        &fetched.caption,
+                        &fetched.source_url,
+                        fetched.render_fields(),
+                        CONFIG.caption_quote_text_chars,
+                    );
                     let report = debug_report(
                         url,
                         fetched.site_name(),
                         &fetched.source_url,
                         &fetched.title,
+                        &fetched.content,
                         fetched.render_fields(),
                         fetched.sensitive,
-                        &fetched.caption,
+                        &caption,
                         &fetched.media,
                     );
                     // HTML report: the caption renders inside a <blockquote>
@@ -439,12 +663,32 @@ fn plural(n: usize) -> &'static str {
     if n == 1 { "y" } else { "ies" }
 }
 
+/// Bot profile texts (Bot API `setMyDescription` / `setMyShortDescription`):
+/// shown on the bot's profile page and in the share sheet. Without them a
+/// shared link says nothing about what the bot does.
+const BOT_DESCRIPTION: &str = "\
+Send a post link from X/Twitter, Pixiv, Bluesky, Misskey (misskey.io) or Bilibili and get its images, videos and GIFs back with the title, author and tags.
+Links are handled in private chats; a group can use inline mode. /help lists every command.";
+const BOT_SHORT_DESCRIPTION: &str =
+    "Post links (X, Pixiv, Bluesky, Misskey, Bilibili) -> media messages";
+
 /// Registers the bot's command list with Telegram so clients show it in the
-/// `/` menu (Bot API `setMyCommands`).
+/// `/` menu (Bot API `setMyCommands`), plus its profile description texts.
 pub async fn register_commands(bot: &Bot) -> Result<(), RequestError> {
     let commands = Command::bot_commands();
     bot.set_my_commands(commands.clone()).await?;
     log::info!("registered {} commands", commands.len());
+    // Profile texts are cosmetic: a failure (rare) must not abort startup.
+    if let Err(e) = bot.set_my_description().description(BOT_DESCRIPTION).await {
+        log::warn!("failed to set the bot description: {e}");
+    }
+    if let Err(e) = bot
+        .set_my_short_description()
+        .short_description(BOT_SHORT_DESCRIPTION)
+        .await
+    {
+        log::warn!("failed to set the bot short description: {e}");
+    }
     Ok(())
 }
 
@@ -456,6 +700,31 @@ const MAX_DEBUG_REPORT_CHARS: usize = 4000;
 /// message, so it must stay under Telegram's 4096-char limit.
 const MAX_DEBUG_DUMP_CHARS: usize = 3500;
 
+/// The caption a link would actually send for this chat: the per-site format
+/// override (empty = the site's built-in caption) and, on a long post, the
+/// same text quoting the send paths apply. `/debug` shows this so the preview
+/// cannot drift from what the send paths produce.
+fn preview_caption(
+    format: &str,
+    built_in: &str,
+    url: &str,
+    fields: Option<(&str, &str, &str, &str, &str)>,
+    quote_chars: usize,
+) -> String {
+    let caption = match fields {
+        // Same call the send paths make through `Fetched::caption_with`: an
+        // empty format falls back to the built-in caption.
+        Some((author, author_url, title, content, tags)) => x_media::site::caption_from_fields(
+            format, built_in, url, author, author_url, title, content, tags,
+        ),
+        None => x_media::site::truncate_caption(built_in),
+    };
+    let text = fields
+        .map(|(_, _, title, content, _)| x_media::site::compose_text(title, content))
+        .unwrap_or_default();
+    crate::send::quote_long_caption(&caption, &text, quote_chars).into_owned()
+}
+
 /// Builds the HTML report for the `/debug` command: what the parser produced
 /// for a link (site, canonical URL, title/author/tags, caption and the media
 /// list) — no media is sent and nothing is cached or forwarded. Sent with
@@ -471,7 +740,8 @@ fn debug_report(
     site_id: &str,
     source_url: &str,
     title: &str,
-    render: Option<(&str, &str, &str, &str)>,
+    content: &str,
+    render: Option<(&str, &str, &str, &str, &str)>,
     sensitive: bool,
     caption: &str,
     media: &[x_media::media::Media],
@@ -491,7 +761,8 @@ fn debug_report(
         html_escape::encode_text(source_url)
     ));
     lines.push(format!("title: {}", html_escape::encode_text(title)));
-    if let Some((author, author_url, _title, tags)) = render {
+    lines.push(format!("content: {}", html_escape::encode_text(content)));
+    if let Some((author, author_url, _title, _content, tags)) = render {
         // The render fields are already pre-escaped for HTML captions; embed
         // them as-is so the report renders them exactly like the final
         // caption. `author_url` is raw and gets escaped here.
@@ -536,7 +807,9 @@ fn debug_report(
 
 #[cfg(test)]
 mod tests {
-    use super::{MAX_DEBUG_REPORT_CHARS, debug_report};
+    use super::{
+        MAX_DEBUG_REPORT_CHARS, debug_report, preview_caption, settings_text, unknown_placeholder,
+    };
     use x_media::media::Media;
 
     #[test]
@@ -559,17 +832,22 @@ mod tests {
             "twitter",
             "https://x.com/u/status/1",
             "My title",
-            Some(("Author", "https://x.com/u", "My title", "tag1 tag2")),
+            "My content",
+            Some((
+                "Author",
+                "https://x.com/u",
+                "My title",
+                "My content",
+                "tag1 tag2",
+            )),
             false,
             "<a href=\"https://x.com/u\">Author</a> · My title",
             &media,
         );
         assert!(report.contains("site: twitter"), "{report}");
         assert!(report.contains("key: twitter:1"), "{report}");
-        assert!(report.contains("title: My title"), "{report}");
-        assert!(report.contains("author: Author"), "{report}");
+        assert!(report.contains("content: My content"), "{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!(
@@ -583,11 +861,12 @@ mod tests {
     }
 
     #[test]
-    fn debug_report_without_render_data_and_no_media() {
-        let report = debug_report("u", "pixiv", "s", "t", None, true, "c", &[]);
+    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]
@@ -601,10 +880,12 @@ mod tests {
             "twitter",
             "https://x.com/u/status/1",
             "A & B <C>",
+            "body & <more>",
             Some((
                 "A &amp; B",
                 "https://x.com/u",
                 "A &amp; B &lt;C&gt;",
+                "body &amp; &lt;more&gt;",
                 "#a &amp; #b",
             )),
             false,
@@ -640,8 +921,251 @@ mod tests {
                 fallback_url: None,
             })
             .collect();
-        let report = debug_report("u", "twitter", "s", "t", None, false, "c", &media);
+        let report = debug_report("u", "twitter", "s", "t", "c", None, false, "p", &media);
         assert!(report.chars().count() <= MAX_DEBUG_REPORT_CHARS, "{report}");
         assert!(report.ends_with('…'), "{report}");
     }
+
+    #[test]
+    fn settings_text_reports_the_chat_configuration() {
+        use crate::state::ChatData;
+
+        // A fresh chat: the defaults must be spelled out, including how to set
+        // the channel (an empty field is not a status).
+        let empty = settings_text(&ChatData::default());
+        assert!(empty.contains("Forward channel: not set"), "{empty}");
+        assert!(empty.contains("/set_forward_channel"), "{empty}");
+        assert!(empty.contains("Edit before forward: off"), "{empty}");
+        assert!(empty.contains("built-in for every site"), "{empty}");
+        assert!(empty.contains("Templates: none"), "{empty}");
+
+        let configured = ChatData {
+            forward_channel_id: Some(-100123),
+            edit_before_forward: true,
+            template: [("b", "[]"), ("a", "[]")]
+                .into_iter()
+                .map(|(k, v)| (k.to_string(), v.to_string()))
+                .collect(),
+            message_format: [("twitter", "{author}: {content}")]
+                .into_iter()
+                .map(|(k, v)| (k.to_string(), v.to_string()))
+                .collect(),
+            ..ChatData::default()
+        };
+        let text = settings_text(&configured);
+        assert!(text.contains("Forward channel: -100123"), "{text}");
+        assert!(text.contains("Edit before forward: on"), "{text}");
+        assert!(text.contains("twitter => {author}: {content}"), "{text}");
+        // Sorted, so the same chat always reports the same thing.
+        assert!(text.contains("Templates (2): a, b"), "{text}");
+    }
+
+    #[test]
+    fn help_and_start_cover_what_the_command_list_cannot() {
+        // The placeholders the renderer substitutes must be the ones the help
+        // lists: a stale list is worse than none.
+        for placeholder in super::FORMAT_PLACEHOLDERS {
+            assert!(
+                super::HELP_FOOTER.contains(&format!("{{{placeholder}}}")),
+                "help does not document {{{placeholder}}}"
+            );
+        }
+        // The private-chat rule and the template placeholder semantics are the
+        // two things users got wrong most often.
+        assert!(super::HELP_FOOTER.contains("private chats only"));
+        assert!(super::HELP_FOOTER.contains("[]"));
+        assert!(super::START_TEXT.contains("inline mode"));
+        assert!(super::START_TEXT.contains("/help"));
+        // Both must stay inside Telegram's message limit.
+        assert!(super::HELP_FOOTER.chars().count() < 2000);
+        assert!(super::START_TEXT.chars().count() < 2000);
+    }
+
+    #[test]
+    fn every_command_is_registered_and_parses() {
+        use teloxide::utils::command::BotCommands;
+
+        use super::Command;
+
+        let registered: Vec<String> = Command::bot_commands()
+            .into_iter()
+            .map(|command| command.command.trim_start_matches('/').to_string())
+            .collect();
+        for expected in [
+            "start",
+            "help",
+            "settings",
+            "set_forward_channel",
+            "remove_template",
+            "set_format",
+            "test",
+            "debug",
+        ] {
+            assert!(
+                registered.iter().any(|name| name == expected),
+                "{expected} missing from {registered:?}"
+            );
+        }
+        // Telegram caps a command description at 256 chars.
+        for command in Command::bot_commands() {
+            assert!(
+                command.description.chars().count() <= 256,
+                "{}: description too long",
+                command.command
+            );
+        }
+    }
+
+    #[test]
+    fn every_documented_invocation_parses() {
+        use teloxide::utils::command::BotCommands;
+
+        use super::Command;
+
+        // The README's forms, verbatim. teloxide's `split` parser accepts
+        // EXACTLY one token per `String` field, so a command documented with
+        // two arguments (or an optional one) silently stops parsing — and a
+        // command that does not parse falls through to the URL flow in
+        // silence.
+        type Check = fn(&Command) -> bool;
+        let cases: Vec<(&str, Check)> = vec![
+            ("/start", |c| matches!(c, Command::Start)),
+            ("/help", |c| matches!(c, Command::Help)),
+            ("/settings", |c| matches!(c, Command::Settings)),
+            ("/edit_before_forward", |c| {
+                matches!(c, Command::EditBeforeForward)
+            }),
+            ("/remove_forward_channel", |c| {
+                matches!(c, Command::RemoveForwardChannel)
+            }),
+            ("/bot_dict", |c| matches!(c, Command::BotDict)),
+            (
+                "/set_forward_channel @a_channel",
+                |c| matches!(c, Command::SetForwardChannel(a) if a == "@a_channel"),
+            ),
+            (
+                "/set_template tpl",
+                |c| matches!(c, Command::SetTemplate(a) if a == "tpl"),
+            ),
+            (
+                "/remove_template tpl",
+                |c| matches!(c, Command::RemoveTemplate(a) if a == "tpl"),
+            ),
+            (
+                "/set_format twitter {author}: {title}",
+                |c| matches!(c, Command::SetFormat(a) if a == "twitter {author}: {title}"),
+            ),
+            (
+                "/set_format twitter -",
+                |c| matches!(c, Command::SetFormat(a) if a == "twitter -"),
+            ),
+            // Documented as "clear everything" when called without a link.
+            (
+                "/clear_cache",
+                |c| matches!(c, Command::ClearCache(a) if a.is_empty()),
+            ),
+            (
+                "/clear_cache https://x.com/u/status/1",
+                |c| matches!(c, Command::ClearCache(a) if a == "https://x.com/u/status/1"),
+            ),
+            (
+                "/test https://x.com/u/status/1",
+                |c| matches!(c, Command::Test(a) if a == "https://x.com/u/status/1"),
+            ),
+            (
+                "/debug https://x.com/u/status/1",
+                |c| matches!(c, Command::Debug(a) if a == "https://x.com/u/status/1"),
+            ),
+        ];
+
+        for (text, ok) in cases {
+            match Command::parse(text, "") {
+                Ok(parsed) => assert!(ok(&parsed), "{text} parsed as the wrong variant"),
+                Err(e) => panic!("{text} did not parse: {e}"),
+            }
+        }
+    }
+
+    #[test]
+    fn preview_caption_applies_the_chat_format_and_the_long_post_quote() {
+        let fields = Some((
+            "Author",
+            "https://x.com/u",
+            "Pinned title",
+            "Pinned body",
+            "#tag",
+        ));
+
+        // No format override → the site's built-in caption, untouched.
+        assert_eq!(
+            preview_caption(
+                "",
+                "built-in caption",
+                "https://x.com/u/status/1",
+                fields,
+                200
+            ),
+            "built-in caption"
+        );
+
+        // The bug this pins: `/debug` used to print the built-in caption even
+        // with a format set, so `/set_format` looked like it did nothing.
+        let formatted = preview_caption(
+            "{author} · {title}",
+            "built-in caption",
+            "https://x.com/u/status/1",
+            fields,
+            200,
+        );
+        assert_eq!(formatted, "Author · Pinned title");
+
+        // `{url}` comes from the canonical post URL, as in the send paths.
+        assert_eq!(
+            preview_caption(
+                "{url} {title}",
+                "built-in",
+                "https://x.com/u/status/1",
+                fields,
+                200
+            ),
+            "https://x.com/u/status/1 Pinned title"
+        );
+
+        // A long post's text is quoted exactly like the send paths quote it.
+        let long = "正".repeat(300);
+        let fields = Some(("Author", "https://x.com/u", "", long.as_str(), ""));
+        let quoted = preview_caption(
+            "",
+            "https://x.com/u/status/1\n<a href=\"https://x.com/u\">Author</a>: 正…",
+            "https://x.com/u/status/1",
+            fields,
+            200,
+        );
+        assert!(quoted.contains("<blockquote expandable>"), "{quoted}");
+
+        // Without render fields (a site that does not expose them) the
+        // built-in caption is all there is.
+        assert_eq!(
+            preview_caption("", "built-in", "https://x.com/u/status/1", None, 200),
+            "built-in"
+        );
+    }
+
+    #[test]
+    fn unknown_placeholder_finds_typos_only() {
+        assert_eq!(unknown_placeholder("{author} — {title}"), None);
+        // Every key the renderer substitutes must pass, in any combination.
+        assert_eq!(
+            unknown_placeholder("{url}{author}{author_url}{title}{content}{tags}"),
+            None
+        );
+        // Plain text and braces Telegram renders literally are not tokens.
+        assert_eq!(unknown_placeholder("no placeholders here"), None);
+        assert_eq!(unknown_placeholder("{unclosed"), None);
+
+        assert_eq!(unknown_placeholder("{titel}"), Some("titel"));
+        assert_eq!(unknown_placeholder("{title} {Content}"), Some("Content"));
+        // A typo after a valid token is still found.
+        assert_eq!(unknown_placeholder("{url} {tag}"), Some("tag"));
+    }
 }

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,21 +148,44 @@ 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 {
         Ok(Some(fetched)) => {
             let mut results: Vec<InlineQueryResult> = Vec::new();
             // Inline results have the same 1024-char caption limit as regular
-            // messages; truncate once here for all items.
+            // messages; truncate once here for all items, then apply the same
+            // long-post quoting as the send paths. `answer_inline_query` has no
+            // `AppContext` (the debounce spawns it), so the parsed config comes
+            // from the process-wide static, and the text is the *escaped*
+            // title/content the built-in caption embeds (the raw
+            // `Fetched.title`/`content` differ whenever the post contains
+            // `<`/`&`).
             let caption = x_media::site::truncate_caption(&fetched.caption);
+            let text = fetched
+                .render_fields()
+                .map(|(_, _, title, content, _)| x_media::site::compose_text(title, content))
+                .unwrap_or_default();
+            let caption = crate::send::quote_long_caption(
+                &caption,
+                &text,
+                super::CONFIG.caption_quote_text_chars,
+            );
             for (i, media) in fetched.media.iter().enumerate() {
                 let id = format!("{i}");
+                // Telegram fetches an inline result's URL itself and cannot
+                // send site-specific headers, so hotlink-protected media
+                // (pixiv's pximg.net) would render as a broken file there.
+                // Locally produced media (ugoira MP4, bsky remux) is a local
+                // path and does not parse as a URL at all — same skip.
+                if x_media::site::needs_media_headers(media.url()) {
+                    log::debug!("inline: skipping hotlink-protected media {id}");
+                    continue;
+                }
                 let Some(url) = url::Url::parse(media.url()).ok() else {
                     continue;
                 };
@@ -138,7 +193,7 @@ async fn answer_inline_query(bot: Bot, query: InlineQuery) -> Result<bool, Reque
                     .thumbnail_url()
                     .and_then(|t| url::Url::parse(t).ok())
                     .unwrap_or_else(|| url.clone());
-                let caption = caption.clone();
+                let caption = caption.clone().into_owned();
                 let result = match media {
                     Media::Illustration { .. } => {
                         // Inline photo results have their own (smaller) size
@@ -180,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";
@@ -218,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;
@@ -23,7 +27,9 @@ use crate::media_sender::MediaSender;
 use commands::{Command, execute_command};
 use teloxide::RequestError;
 use teloxide::prelude::*;
-use teloxide::types::{ChatId, ChatKind, Message, MessageId, ParseMode, ReplyParameters};
+use teloxide::types::{
+    ChatId, ChatKind, Message, MessageId, ParseMode, PublicChatKind, ReplyParameters,
+};
 use teloxide::utils::command::BotCommands;
 use urls::{URL_JOBS, extract_urls};
 
@@ -60,12 +66,63 @@ pub(crate) async fn reply_html(
 
 /// Log prefix tying the whole lifecycle of one link (fetch → send → cache →
 /// forward) together: the normalized cache key (`twitter:123…`, `pixiv:123`,
-/// `bsky:handle/rkey`) instead of the raw URL, so logs stay short and do not
-/// echo full user-submitted URLs at info level.
+/// `bsky:handle/rkey`, `bilibili:123…`) instead of the raw URL, so logs stay
+/// short and do not echo full user-submitted URLs at info level.
 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
@@ -97,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
@@ -128,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
@@ -175,52 +267,55 @@ pub async fn message_handler(bot: Bot, message: Message) -> Result<(), RequestEr
                 break;
             }
         }
+    } else if is_group(&message.chat.kind)
+        && extract_urls(&message)
+            .iter()
+            .any(|url| x_media::site::cache_key(url).is_some())
+    {
+        // A supported link in a group used to be dropped in silence, which
+        // reads as a broken bot (the command menu is registered globally, so
+        // 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(ctx.sender, message.chat.id.0, message.id, GROUP_LINK_HINT).await;
     }
     respond(())
 }
 
+/// Answer for a link posted where the pipeline does not run (a group): links
+/// are private-chat only, inline mode is the group path.
+const GROUP_LINK_HINT: &str =
+    "Links are handled in private chat only — send me this link there, or use inline mode here.";
+
+/// Groups and supergroups, as opposed to private chats and channels.
+fn is_group(kind: &ChatKind) -> bool {
+    matches!(
+        kind,
+        ChatKind::Public(chat)
+            if matches!(
+                chat.kind,
+                PublicChatKind::Group | PublicChatKind::Supergroup(_)
+            )
+    )
+}
+
 #[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;
 
@@ -233,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;
 
@@ -248,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);
 
@@ -271,4 +407,95 @@ mod tests {
         assert!(!edit_message_handler(&ctx, 1, PROMPT_ID, "hello").await);
         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};
+
+        let group = ChatKind::Public(ChatPublic {
+            title: None,
+            kind: PublicChatKind::Group,
+        });
+        let supergroup = ChatKind::Public(ChatPublic {
+            title: None,
+            kind: PublicChatKind::Supergroup(PublicChatSupergroup {
+                username: None,
+                is_forum: false,
+            }),
+        });
+        // A channel must stay silent: the hint reply would be posted into the
+        // channel itself.
+        let channel = ChatKind::Public(ChatPublic {
+            title: None,
+            kind: PublicChatKind::Channel(PublicChatChannel { username: None }),
+        });
+        let private = ChatKind::Private(ChatPrivate {
+            username: None,
+            first_name: None,
+            last_name: None,
+        });
+
+        assert!(is_group(&group));
+        assert!(is_group(&supergroup));
+        assert!(!is_group(&channel));
+        assert!(!is_group(&private));
+    }
 }

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:
@@ -38,6 +44,10 @@ pub struct CachedPost {
     /// override).
     pub caption: String,
     pub title: String,
+    /// The post's body text. Defaulted on read: entries written before the
+    /// title/content split carry it inside `title`.
+    #[serde(default)]
+    pub content: String,
     pub author: String,
     pub author_url: String,
     pub tags: String,
@@ -92,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
             }
         }
@@ -112,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}");
         }
     }
 
@@ -127,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}");
         }
     }
 
@@ -146,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
             }
         }
@@ -166,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
             }
         }
@@ -176,21 +186,49 @@ impl LinkCache {
 #[cfg(test)]
 mod tests {
     use super::*;
+    use crate::ctx::test_support::cached_photo;
 
-    fn entry() -> CachedPost {
-        CachedPost {
-            url: "https://x.com/u/status/1".into(),
-            caption: "cap".into(),
-            title: "t".into(),
-            author: "a".into(),
-            author_url: "au".into(),
-            tags: "".into(),
-            sensitive: true,
-            media: vec![CachedMedia {
-                kind: CachedMediaKind::Photo,
-                file_id: "AgAC...".into(),
-            }],
+    /// A payload written before the title/content split has no `content`
+    /// field. It must still read back — the cache deletes what it cannot
+    /// parse — with its text left where it was stored (`title`) and the
+    /// caption it replays untouched. No migration: a self-hosted cache entry
+    /// lives one TTL, and moving the text would only reshuffle `/set_format`
+    /// placeholders until it expires.
+    #[tokio::test]
+    async fn pre_split_entry_still_parses() {
+        let dir = tempfile::tempdir().unwrap();
+        let cache = LinkCache::new(
+            crate::db::open_store(dir.path().join("c.db").to_str().unwrap()).unwrap(),
+        );
+        let legacy = serde_json::json!({
+            "url": "https://x.com/u/status/1",
+            "caption": "https://x.com/u/status/1\n<a href=\"au\">a</a>: old text",
+            "title": "old text",
+            "author": "a",
+            "author_url": "au",
+            "tags": "",
+            "sensitive": false,
+            "media": [{"kind": "photo", "file_id": "AgAC..."}]
+        });
+        {
+            let conn = rusqlite::Connection::open(dir.path().join("c.db")).unwrap();
+            conn.execute(
+                "INSERT INTO link_cache (url, payload, created_at) VALUES (?1, ?2, ?3)",
+                params!["twitter:1", legacy.to_string(), now_f64()],
+            )
+            .unwrap();
         }
+
+        let got = cache
+            .get("twitter:1", Duration::from_secs(3600))
+            .await
+            .expect("a pre-split payload must not be dropped");
+        assert_eq!(got.title, "old text");
+        assert_eq!(got.content, "");
+        assert_eq!(
+            got.caption,
+            "https://x.com/u/status/1\n<a href=\"au\">a</a>: old text"
+        );
     }
 
     #[tokio::test]
@@ -199,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]
@@ -213,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();
@@ -266,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
@@ -301,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,4 +1,5 @@
 use dotenv::dotenv;
+use std::time::Duration;
 use teloxide::dptree::endpoint;
 use teloxide::prelude::*;
 use teloxide::stop::StopToken;
@@ -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,45 +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 {
-                    // 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_reply_markup(
-                            ChatId(chat_id),
-                            MessageId(prompt_message_id as i32),
-                        )
-                        .await
-                    {
-                        log::info!("edit-expiry sweep: prompt message gone: {e}");
-                    }
-                }
-            }
+            periodic_sweep(
+                &bot,
+                &CHAT_STORE,
+                &LINK_CACHE,
+                &TASK_QUEUE,
+                &CONFIG,
+                stop_rx,
+            )
+            .await;
         });
     }
 
@@ -211,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();
@@ -327,9 +558,20 @@ pub(crate) mod test_support {
             &self,
             _chat_id: ChatId,
             _reply_to: MessageId,
-            _items: Vec<InputMedia>,
+            items: Vec<InputMedia>,
         ) -> BoxFuture<'_, Result<Vec<Message>, RequestError>> {
             Box::pin(async move {
+                // Record the captions exactly as Telegram receives them (only
+                // the first item of a group carries one), so tests can assert
+                // what a recipient sees.
+                self.captions
+                    .lock()
+                    .extend(items.iter().filter_map(|item| match item {
+                        InputMedia::Photo(photo) => photo.caption.clone(),
+                        InputMedia::Video(video) => video.caption.clone(),
+                        InputMedia::Animation(animation) => animation.caption.clone(),
+                        _ => None,
+                    }));
                 match self.next("send_media_group") {
                     Outcome::GroupOk => Ok(Vec::new()),
                     Outcome::GroupErr => Err(self.error()),
@@ -400,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,41 +489,72 @@ 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,
                 payload,
             }) => {
                 if row.attempts as u32 >= MAX_RETRIES {
-                    let message = format!("task failed after {MAX_RETRIES} retries");
-                    log::error!("dead-lettering {}: {message}", row.id);
-                    self.delete_row(&row.id).await;
+                    // The queue keeps only the payload, not the last error, so
+                    // the cause of an exhausted retry is just that: exhausted.
+                    // (The dead-letter message is read by the user, so it must
+                    // not restate its own wrapper — see `failure_text`.)
+                    let message = "retries exhausted".to_string();
+                    log::error!(
+                        "dead-lettering {} {fields}: {message} after {} attempt(s)",
+                        row.id,
+                        row.attempts + 1
+                    );
+                    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;
             }
         }
@@ -370,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));
@@ -378,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()
+        );
     }
 }
 
@@ -447,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) {
@@ -481,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;
@@ -520,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;
@@ -590,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));
@@ -605,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(
@@ -616,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

@@ -17,8 +17,8 @@ use crate::link_cache::{CachedMedia, CachedMediaKind, CachedPost};
 use crate::media_sender::MediaSender;
 use input_media::{build_media_group, input_file_for, item_url};
 use post_send::{cache_animation_send, cache_sent_task};
-use rand::Rng;
 use serde::{Deserialize, Serialize};
+use std::borrow::Cow;
 use std::sync::LazyLock;
 use teloxide::prelude::*;
 use teloxide::types::{ChatId, InputFile, InputMedia, MessageId};
@@ -28,8 +28,8 @@ use upload::{FallbackError, PreparedItem, prepare_upload_item, send_batch_via_up
 // The crate-facing API of this module lives in its submodules; re-export the
 // parts other modules use so call sites stay `send::x`.
 pub(crate) use post_send::{
-    KEEP_ALIVE, Settled, dead_letter_notify, enqueue_retry, handle_task, post_send_actions,
-    settle_task,
+    EDIT_PROMPT_EXPIRED_TEXT, KEEP_ALIVE, Settled, dead_letter_notify, enqueue_retry, handle_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,12 +258,17 @@ 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(),
             });
         }
     }
 }
 
-pub const MAX_MEDIA_GROUP: usize = 9;
+/// Telegram's `sendMediaGroup` accepts 2–10 items per group; 10 (not the older
+/// 9) means a 10-image post arrives as one album instead of two messages.
+pub const MAX_MEDIA_GROUP: usize = 10;
 
 /// Splits media into batches of at most [`MAX_MEDIA_GROUP`] items, moving the
 /// items out (no per-item clone).
@@ -261,7 +299,7 @@ pub fn photos_first(items: Vec<MediaItemPayload>) -> Vec<MediaItemPayload> {
 
 /// Exponential backoff with jitter, capped at 30s.
 pub fn retry_delay_seconds(attempts: u32) -> f64 {
-    let jitter: f64 = rand::thread_rng().gen_range(0.2..0.8);
+    let jitter: f64 = rand::random_range(0.2..0.8);
     (2f64.powi(attempts as i32) + jitter).min(30.0)
 }
 
@@ -269,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",
@@ -278,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))
@@ -318,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 {
@@ -330,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 {
@@ -389,6 +468,61 @@ fn updated_sequence_task(task: &Task, batch_index: usize, sent_message_ids: Vec<
     updated
 }
 
+/// The caption's text tail: everything after the author link, provided it
+/// really is the post's text.
+///
+/// `text` is the *escaped* title + content the caption embeds; the caption may
+/// have been truncated inside it, in which case only its prefix is present, so
+/// the tail only has to match the text's start. `None` for a caption with
+/// another layout — pixiv's title-inside-a-link, a `/set_format` that moves
+/// `{title}`/`{content}` off the author line — which is left unquoted instead
+/// of guessing where the text begins.
+fn text_tail<'c>(caption: &'c str, text: &str) -> Option<&'c str> {
+    let (_, tail) = caption.rsplit_once("</a>: ")?;
+    let visible = tail.strip_suffix('\u{2026}').unwrap_or(tail);
+    (!visible.is_empty() && text.starts_with(visible)).then_some(tail)
+}
+
+/// The text a task's caption embeds, read from the same cache snapshot the
+/// caption came from: `title` and `content` joined the way the sites' built-in
+/// captions join them.
+fn task_text(task: &Task) -> String {
+    task.cache_data()
+        .map(|data| x_media::site::compose_text(&data.title, &data.content))
+        .unwrap_or_default()
+}
+
+/// Wraps the post's text inside the caption in an expandable blockquote once
+/// that text is long enough that the message would otherwise be a wall of text
+/// (`threshold` is `CAPTION_QUOTE_TEXT_CHARS`; `0` disables the wrap). The URL
+/// and the author line stay outside the quote.
+///
+/// Applied at the send boundary, after the caller's `truncate_caption`:
+/// Telegram measures a caption *after entities parsing*, so the tags cost no
+/// length and a wrapped caption cannot exceed the 1024-character limit.
+/// Retries replay the task's (unwrapped) caption, so the decision is remade on
+/// every attempt — changing the threshold takes effect immediately.
+///
+/// A caption that already carries a blockquote is left as it is: the API
+/// rejects nested ones ("all other entities can't contain each other"), and a
+/// user-written `/set_format` template may contain one.
+pub(crate) fn quote_long_caption<'a>(
+    caption: &'a str,
+    text: &str,
+    threshold: usize,
+) -> Cow<'a, str> {
+    if threshold == 0 || caption.contains("<blockquote") || text.chars().count() < threshold {
+        return Cow::Borrowed(caption);
+    }
+    let Some(tail) = text_tail(caption, text) else {
+        return Cow::Borrowed(caption);
+    };
+    let prefix = &caption[..caption.len() - tail.len()];
+    Cow::Owned(format!(
+        "{prefix}<blockquote expandable>{tail}</blockquote>"
+    ))
+}
+
 /// Sends the media batches starting at `task.batch_index`, extending
 /// `sent_message_ids`. Returns all sent message ids on full success; on
 /// failure returns a [`SendError`] whose task carries the resumed state.
@@ -407,6 +541,10 @@ pub async fn send_media_sequence(ctx: &AppContext<'_>, task: &Task) -> Result<Ve
     };
     let chat_id = *chat_id;
     let reply_to = *reply_to_message_id;
+    // A long post is quoted so the message reads as a card rather than a wall
+    // of text; the text comes from the same cache snapshot as the caption.
+    let text = task_text(task);
+    let caption = quote_long_caption(caption, &text, ctx.config.caption_quote_text_chars);
     let mut sent = sent_message_ids.clone();
     // File ids accumulated across batches for the link cache. Only a fresh
     // (non-resumed) full send populates the cache.
@@ -415,7 +553,7 @@ pub async fn send_media_sequence(ctx: &AppContext<'_>, task: &Task) -> Result<Ve
     for idx in *batch_index..media_batches.len() {
         let batch = &media_batches[idx];
         let caption = if idx == 0 {
-            Some(caption.as_str())
+            Some(caption.as_ref())
         } else {
             None
         };
@@ -516,6 +654,10 @@ pub async fn send_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Vec<i64
     };
     let chat_id = *chat_id;
     let reply_to = *reply_to_message_id;
+    // Same long-post quoting as the media-group path (see
+    // `quote_long_caption`); both sends below share this string.
+    let text = task_text(task);
+    let caption = quote_long_caption(caption, &text, ctx.config.caption_quote_text_chars);
     let (media_url, has_spoiler) = match animation {
         MediaItemPayload::Animation {
             media, has_spoiler, ..
@@ -537,7 +679,7 @@ pub async fn send_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Vec<i64
         ctx.sender,
         chat_id,
         reply_to,
-        caption,
+        &caption,
         has_spoiler,
         url_file,
     )
@@ -545,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) => {
@@ -572,7 +714,7 @@ pub async fn send_animation(ctx: &AppContext<'_>, task: &Task) -> Result<Vec<i64
                         ctx.sender,
                         chat_id,
                         reply_to,
-                        caption,
+                        &caption,
                         has_spoiler,
                         animation.media,
                     )
@@ -580,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(
@@ -645,33 +787,33 @@ 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]
     fn chunk_media_items_sizes() {
         assert_eq!(chunk_media_items::<i32>(vec![]), Vec::<Vec<i32>>::new());
         assert_eq!(chunk_media_items((0..9).collect()).len(), 1);
-        assert_eq!(chunk_media_items((0..10).collect()).len(), 2);
+        assert_eq!(chunk_media_items((0..10).collect()).len(), 1);
+        assert_eq!(chunk_media_items((0..11).collect()).len(), 2);
         assert_eq!(chunk_media_items((0..25).collect()).len(), 3);
-        assert_eq!(chunk_media_items((0..25).collect())[2].len(), 7);
+        assert_eq!(chunk_media_items((0..25).collect())[2].len(), 5);
         assert!(
             chunk_media_items((0..25).collect())
                 .iter()
-                .all(|c| c.len() <= 9)
+                .all(|c| c.len() <= MAX_MEDIA_GROUP)
         );
     }
 
@@ -744,7 +886,88 @@ mod tests {
             .flatten()
             .map(|button| button.text.clone())
             .collect();
-        assert_eq!(labels, ["a", "b", "m", "q", "y", "z", "↩️ Confirm"]);
+        assert_eq!(
+            labels,
+            ["a", "b", "m", "q", "y", "z", "↩️ Confirm", "🛑 Skip"]
+        );
+    }
+
+    #[test]
+    fn edit_markup_folds_and_caps_the_template_buttons() {
+        // Telegram rejects a keyboard over 100 buttons, which would drop the
+        // whole prompt; the cap keeps it well under that.
+        let templates: HashMap<String, String> = (0..200)
+            .map(|i| (format!("t{i:03}"), "[]".to_string()))
+            .collect();
+        let keyboard = build_edit_markup(&templates);
+        let buttons: usize = keyboard.inline_keyboard.iter().map(Vec::len).sum();
+        assert!(
+            buttons <= 100,
+            "a keyboard Telegram rejects would lose the prompt: {buttons}"
+        );
+        assert_eq!(
+            buttons,
+            super::post_send::MAX_TEMPLATE_BUTTONS + 2,
+            "the cap plus the confirm/skip pair"
+        );
+        // Names are folded, not one per row.
+        assert_eq!(keyboard.inline_keyboard[0].len(), 3);
+        assert_eq!(keyboard.inline_keyboard.last().unwrap().len(), 2);
+        assert_eq!(super::post_send::hidden_template_count(&templates), 140);
+        // Under the cap nothing is hidden and every name gets a button.
+        let few: HashMap<String, String> = (0..4)
+            .map(|i| (format!("t{i}"), "[]".to_string()))
+            .collect();
+        assert_eq!(super::post_send::hidden_template_count(&few), 0);
+        assert_eq!(
+            build_edit_markup(&few)
+                .inline_keyboard
+                .iter()
+                .map(Vec::len)
+                .sum::<usize>(),
+            6
+        );
+    }
+
+    #[test]
+    fn failure_text_names_the_post_and_the_cause() {
+        // 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(task.source_url(), "retries exhausted");
+        assert!(text.contains("twitter:1"), "{text}");
+        assert!(text.contains("retries exhausted"), "{text}");
+
+        // A channel-forward failure has no source URL: it must not claim a
+        // post failed.
+        let forward = Task::ForwardMessages {
+            from_chat_id: 1,
+            to_chat_id: 2,
+            message_ids: vec![1],
+            notify_chat_id: None,
+            notify_message_id: None,
+        };
+        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}");
+    }
+
+    #[test]
+    fn edit_prompt_text_states_the_ttl_and_the_confirm_requirement() {
+        use std::time::Duration;
+
+        let text = super::post_send::edit_prompt_text(Duration::from_secs(24 * 3600));
+        assert!(text.contains("Expires in 24h"), "{text}");
+        assert!(text.contains("Confirm"), "{text}");
+        // The wording of the whole point: no Confirm, no forward.
+        assert!(text.contains("Nothing is forwarded"), "{text}");
+        // Sub-hour TTLs must not render "0h".
+        assert!(
+            super::post_send::edit_prompt_text(Duration::from_secs(90)).contains("Expires in 1m")
+        );
+        assert!(
+            super::post_send::edit_prompt_text(Duration::from_secs(30)).contains("Expires in 30s")
+        );
     }
 
     #[test]
@@ -771,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.
@@ -832,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!(
@@ -931,10 +1196,16 @@ mod tests {
     }
 
     fn sequence_task(media: &str) -> Task {
+        sequence_task_with(media, "cap", None)
+    }
+
+    /// A media-group task; `text` (when given) rides in the link-cache
+    /// snapshot as `content`, which is where the quote threshold reads it.
+    fn sequence_task_with(media: &str, caption: &str, text: Option<&str>) -> Task {
         Task::SendMediaSequence {
             chat_id: 1,
             reply_to_message_id: 2,
-            caption: "cap".into(),
+            caption: caption.into(),
             media_batches: vec![vec![MediaItemPayload::Photo {
                 media: media.to_string(),
                 has_spoiler: false,
@@ -948,7 +1219,99 @@ mod tests {
             forward_channel_id: None,
             notify_chat_id: Some(1),
             notify_message_id: Some(2),
-            cache_data: None,
+            // The snapshot splits the post's text into title/content the way a
+            // real fetch does; the quote threshold joins them again.
+            cache_data: text.map(|text| CachedPost {
+                url: "https://x.com/u/status/1".into(),
+                caption: caption.into(),
+                title: String::new(),
+                content: text.into(),
+                author: "me".into(),
+                author_url: "https://x.com/u".into(),
+                tags: String::new(),
+                sensitive: false,
+                media: vec![],
+            }),
+        }
+    }
+
+    /// A media-group task whose built-in caption carries `text` behind the
+    /// author link — the shape the quote threshold locates the text in.
+    fn sequence_task_with_text(media: &str, text: &str) -> Task {
+        let caption =
+            format!("https://x.com/u/status/1\n<a href=\"https://x.com/u\">me</a>: {text}");
+        sequence_task_with(media, &caption, Some(text))
+    }
+
+    #[test]
+    fn quote_long_caption_wraps_only_the_text_tail() {
+        let text = "一二三四五";
+        let prefix = "https://x.com/u/status/1\n<a href=\"https://x.com/u\">me</a>: ";
+        let caption = format!("{prefix}{text}");
+
+        // Only the text goes inside the quote; the URL and author line stay
+        // outside.
+        assert_eq!(
+            quote_long_caption(&caption, text, 5),
+            format!("{prefix}<blockquote expandable>{text}</blockquote>")
+        );
+        // One char below the threshold, disabled, and a short text: untouched.
+        assert_eq!(
+            quote_long_caption(&caption, text, 6),
+            format!("{prefix}{text}")
+        );
+        assert_eq!(quote_long_caption(&caption, text, 0), caption);
+        // No author-line anchor means no text to locate — a pixiv caption
+        // (title inside the link) and a `{content}`-first format stay as they
+        // are rather than risking a blockquote nested in a tag.
+        let pixiv =
+            format!("<a href=\"https://pixiv.net/1\">{text}</a> / <a href=\"u\">me</a>\ntag");
+        assert_eq!(quote_long_caption(&pixiv, text, 5), pixiv);
+        let content_first = format!("{text}\nhttps://x.com/u/status/1");
+        assert_eq!(quote_long_caption(&content_first, text, 5), content_first);
+        // An empty body has nothing to quote.
+        assert_eq!(quote_long_caption(prefix, text, 5), prefix);
+        // A caption that already carries a blockquote is never nested.
+        let quoted = format!("<blockquote>{caption}</blockquote>");
+        assert_eq!(quote_long_caption(&quoted, text, 5), quoted);
+    }
+
+    /// `truncate_caption` cuts inside the text and appends an ellipsis; the
+    /// visible prefix still marks it, so the long-text case that most needs
+    /// quoting is still quoted.
+    #[test]
+    fn quote_long_caption_wraps_a_truncated_text() {
+        let text = "一二三四五六七八九十";
+        let prefix = "https://x.com/u/status/1\n<a href=\"https://x.com/u\">me</a>: ";
+        let caption = format!("{prefix}一二三四五…");
+        assert_eq!(
+            quote_long_caption(&caption, text, 5),
+            format!("{prefix}<blockquote expandable>一二三四五…</blockquote>")
+        );
+    }
+
+    #[tokio::test]
+    async fn long_text_caption_reaches_telegram_quoted() {
+        // The threshold is pinned here instead of read from the environment.
+        let dir = tempfile::tempdir().unwrap();
+        let file = dir.path().join("media.jpg");
+        std::fs::write(&file, b"not-a-real-jpeg").unwrap();
+        let mut stores = TestStores::new();
+        stores.config_mut().caption_quote_text_chars = 5;
+        let prefix = "https://x.com/u/status/1\n<a href=\"https://x.com/u\">me</a>: ";
+
+        for (text, expected) in [
+            (
+                "一二三四五",
+                format!("{prefix}<blockquote expandable>一二三四五</blockquote>"),
+            ),
+            ("一二三四", format!("{prefix}一二三四")),
+        ] {
+            let sender = MockSender::scripted(vec![Outcome::GroupOk], media_fetch_error);
+            let ctx = stores.ctx(&sender);
+            let task = sequence_task_with_text(file.to_str().unwrap(), text);
+            assert!(send_media_sequence(&ctx, &task).await.is_ok());
+            assert_eq!(sender.captions(), vec![expected], "text {text:?}");
         }
     }
 
@@ -1036,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]
@@ -1117,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).
@@ -1150,7 +1531,11 @@ mod tests {
         post_send_actions(&ctx, &task, vec![10, 11]).await;
 
         assert_eq!(sender.calls(), vec!["send_message"]);
-        assert_eq!(sender.messages(), vec!["Reply to edit message."]);
+        // The prompt explains the Confirm requirement and the TTL (see the
+        // pure `edit_prompt_text` test for the exact wording).
+        let prompt_text = sender.messages().first().cloned().unwrap_or_default();
+        assert!(prompt_text.contains("Expires in"), "{prompt_text}");
+        assert!(prompt_text.contains("Confirm"), "{prompt_text}");
         // The prompt's own message id keys the record the reply will edit.
         let data = stores.chat_store().get(1).await;
         let record = data
@@ -1256,32 +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(),
-                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;
 
@@ -1296,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
@@ -103,29 +142,79 @@ pub(crate) fn release_keep_alive(task: &Task) {
     });
 }
 
-/// One button per template name (column layout), then the confirm button.
-/// Sorted by name: the templates live in a `HashMap`, so an unsorted walk
-/// would reshuffle the buttons between prompts.
+/// The edit-before-forward prompt's text. It names both controls and the TTL,
+/// because the buttons alone left users waiting for a forward that never came
+/// (nothing is forwarded until Confirm).
+pub(super) fn edit_prompt_text(ttl: std::time::Duration) -> String {
+    format!(
+        "Reply to edit the caption, or tap a template, then ↩️ Confirm to forward. \
+         Expires in {}. Nothing is forwarded until you confirm.",
+        coarsest_unit(ttl)
+    )
+}
+
+/// Text the prompt is rewritten to once its record expires. The sweep edits
+/// the prompt in place (see `main`): announcing the expiry with a new message
+/// would wake the chat up to a full TTL later about a prompt nobody is
+/// waiting on.
+pub(crate) const EDIT_PROMPT_EXPIRED_TEXT: &str = "⌛ Expired — nothing was forwarded.";
+
+/// `24h` / `90m` / `45s`: the coarsest whole unit, so the prompt stays short.
+fn coarsest_unit(ttl: std::time::Duration) -> String {
+    let secs = ttl.as_secs();
+    if secs >= 3600 {
+        format!("{}h", secs / 3600)
+    } else if secs >= 60 {
+        format!("{}m", secs / 60)
+    } else {
+        format!("{secs}s")
+    }
+}
+
+/// Templates per keyboard row. Telegram rejects a keyboard with more than 100
+/// buttons *outright*, which would silently drop the whole prompt, so the
+/// names are folded and capped rather than listed one per row.
+pub(super) const TEMPLATE_BUTTONS_PER_ROW: usize = 3;
+/// Hard cap on template buttons; the prompt text names the ones not shown.
+pub(super) const MAX_TEMPLATE_BUTTONS: usize = 60;
+
+/// Template buttons ([`TEMPLATE_BUTTONS_PER_ROW`] per row, at most
+/// [`MAX_TEMPLATE_BUTTONS`]), then the confirm/skip pair. Sorted by name: the
+/// templates live in a `HashMap`, so an unsorted walk would reshuffle the
+/// buttons between prompts.
 pub(super) fn build_edit_markup(templates: &HashMap<String, String>) -> InlineKeyboardMarkup {
     let mut names: Vec<&String> = templates.keys().collect();
     names.sort();
-    let mut rows = Vec::with_capacity(names.len() + 1);
-    for name in names {
-        rows.push(vec![InlineKeyboardButton::callback(
-            name.clone(),
-            format!("template|{name}"),
-        )]);
+    let shown = names.len().min(MAX_TEMPLATE_BUTTONS);
+    let mut rows = Vec::with_capacity(shown / TEMPLATE_BUTTONS_PER_ROW + 2);
+    for chunk in names[..shown].chunks(TEMPLATE_BUTTONS_PER_ROW) {
+        rows.push(
+            chunk
+                .iter()
+                .map(|name| {
+                    InlineKeyboardButton::callback(name.as_str(), format!("template|{name}"))
+                })
+                .collect(),
+        );
     }
-    rows.push(vec![InlineKeyboardButton::callback(
-        "↩️ Confirm",
-        "forward",
-    )]);
+    // Skip exists because the prompt holds the forward hostage until Confirm:
+    // without it the only escape was deleting the message and waiting out the
+    // TTL for a forward that then never happens.
+    rows.push(vec![
+        InlineKeyboardButton::callback("↩️ Confirm", "forward"),
+        InlineKeyboardButton::callback("🛑 Skip", "skip"),
+    ]);
     InlineKeyboardMarkup::new(rows)
 }
 
+/// How many templates the markup could not fit, for the prompt text.
+pub(super) fn hidden_template_count(templates: &HashMap<String, String>) -> usize {
+    templates.len().saturating_sub(MAX_TEMPLATE_BUTTONS)
+}
+
 /// 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>,
@@ -185,12 +274,21 @@ pub(crate) async fn post_send_actions(ctx: &AppContext<'_>, task: &Task, message
     };
 
     if edit_before_forward {
-        let keyboard = build_edit_markup(&ctx.chat_store.get(chat_id).await.template);
+        let templates = ctx.chat_store.get(chat_id).await.template;
+        let keyboard = build_edit_markup(&templates);
+        let mut text = edit_prompt_text(ctx.config.edit_message_ttl);
+        let hidden = hidden_template_count(&templates);
+        if hidden > 0 {
+            // The keyboard is capped; say so instead of silently hiding them.
+            text.push_str(&format!(
+                "\n({hidden} more templates not shown — /remove_template to prune.)"
+            ));
+        }
         let prompt = ctx
             .sender
             .send_message(
                 ChatId(chat_id),
-                "Reply to edit message.".to_string(),
+                text,
                 Some(MessageId(reply_to as i32)),
                 Some(keyboard),
             )
@@ -198,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
@@ -217,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,
@@ -240,14 +353,24 @@ 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(
                     ctx.sender,
                     notify_chat_id,
                     notify_message_id,
-                    &format!("Task failed after retries: {message}"),
+                    &failure_text(None, &message),
                 )
                 .await;
             }
@@ -255,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.
@@ -341,6 +472,36 @@ 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(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 (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(
@@ -351,8 +512,21 @@ pub(crate) async fn dead_letter_notify(
     // A dead-lettered task never runs again, and the queue dead-letters retry
     // exhaustion itself (the handler is not called again), so this is the only
     // place that sees the final payload.
-    if let Ok(task) = serde_json::from_value::<Task>(payload.clone()) {
-        settle_task(ctx, &task, Settled::Failed).await;
+    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());
@@ -360,7 +534,12 @@ pub(crate) async fn dead_letter_notify(
         ctx.sender,
         notify_chat_id,
         notify_message_id,
-        &format!("Task failed after retries: {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

@@ -17,8 +17,8 @@ pub struct ChatData {
     pub edit_message: HashMap<i64, EditMessage>,
     /// name -> HTML template containing "[]"
     pub template: HashMap<String, String>,
-    /// site name (twitter/bsky/misskey/pixiv) -> user-supplied caption format
-    /// with {url} {author} {author_url} {title} {tags} placeholders.
+    /// site name (twitter/bsky/misskey/pixiv/bilibili) -> user-supplied caption format
+    /// with {url} {author} {author_url} {title} {content} {tags} placeholders.
     pub message_format: HashMap<String, String>,
 }
 
@@ -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

docs/BILIBILI_PLAN.md

@@ -0,0 +1,168 @@
+# Bilibili 动态支持：研究与实现记录
+
+状态：已实现（`crates/x-media/src/site/bilibili/`）。本文记录上游调研、实测数据与最终设计；
+长期契约以 `AGENTS.md` 为准。
+
+范围：**只发动态里的图片与动图**。动态内嵌视频不发流，降级为封面图；`b23.tv` 短链不匹配；
+视频页 / 番剧 / 直播间 / 专栏 / 音频均不支持。
+
+---
+
+## 1. 上游实现研究
+
+### 1.1 nazurin（`nazurin/sites/bilibili/`，4 个文件 ~6 KB）
+
+- 入口正则：`t\.bilibili\.com/(\d+)`、`t\.bilibili\.com/h5/dynamic/detail/(\d+)`、`bilibili\.com/opus/(\d+)`。
+- 请求：`GET https://api.bilibili.com/x/polymer/web-dynamic/v1/detail?id={id}`，仅加 `Referer: https://t.bilibili.com/{id}`。
+  **无 cookie、无 WBI 签名、无 `build` 参数**。
+- 错误：`code == 4101147` → not found；`code != 0` 或缺 `data` → 报错。
+- 媒体：只取 `item.modules.module_dynamic.major.draw.items[].src`；缩略图 `src + "@518w.jpg"`；
+  `size` 字段单位是 **KB**。`major` 为空或 `draw.items` 为空 → "No image found"。
+  **忽略视频、转发（forward）与纯文字动态**。
+- caption：`"#" + module_author.name` + `module_dynamic.desc.text`，链接写死 `https://www.bilibili.com/opus/{id}`。
+
+### 1.2 telegram-bili-feed-helper（`biliparser/provider/bilibili/`，9 个文件 ~57 KB）
+
+- 9 个策略类（Video/Opus/Live/Audio/Read + Feed 基类 + Credential + api 工具）：门禁正则
+  `bilibili\.com|b23\.tv|BV\w{10}|av\d+`，再分流，兜底 `client.head(url)` 跟随重定向后按子串分流。
+- 动态：`GET /x/polymer/web-dynamic/desktop/v1/detail?id={id}&build=11605`（**单条，无分页**）；
+  客户端带桌面 UA、随机 `buvid3={uuid}infoc`；登录态用 `bilibili-api-python` 的 `Credential`
+  （Redis 持久化 `SESSDATA/bili_jct/buvid3/buvid4/ac_time_value/DedeUserID`，扫码登录）。
+- **同样没有 WBI 签名 / appkey 签名**：playurl 用的是非 WBI 的 `/x/player/playurl`。
+- 媒体：`major.type` 分派 —— DRAW 取全部 `items[].src`；ARCHIVE/PGC/ARTICLE/MUSIC/COMMON/LIVE
+  只取一张 `cover`；FORWARD 取原动态作者/正文并递归进 `orig` 找媒体。
+- 视频：仅独立 video 策略解析（`qn` 720P→480P→360P 试 durl，再退 DASH + ffmpeg 合并）；
+  **动态内嵌视频只发封面**。
+- 错误：要求 `status==200 && code==0`；风控 `-352`/`-412` 无特殊处理。
+
+### 1.3 取舍
+
+| 维度 | nazurin | bff | 本仓库 |
+|---|---|---|---|
+| 接口 | `v1/detail?id=` | `desktop/v1/detail?id=&build=` | `v1/detail?id=`（实测可用） |
+| 认证 | 无 | buvid3 + SESSDATA | 默认匿名；可选 `BILIBILI_COOKIE` |
+| WBI | 无 | 无 | 不实现（无需求） |
+| 图片 | `major.draw.items` | 同 + forward 递归 | 同，加 `orig` 递归、`http→https`、`.gif → Animated` |
+| 视频 | 完全忽略 | 动态内嵌视频发封面 | 发封面（不发流） |
+| 短链 | 不匹配 | 跟随重定向 | 不匹配（多数短链是视频，会让"静默忽略"变成失败提示） |
+
+---
+
+## 2. 实测验证（2026-09-17，真实请求）
+
+| 验证项 | 结果 |
+|---|---|
+| `v1/detail?id=`（无 cookie、UA `Mozilla/5.0`、带 Referer） | `200 {"code":0}` ✅ |
+| 同上，不带 cookie 也不带 Referer | `200 {"code":0}` ✅（无强制鉴权） |
+| bff 的 `bilibili_pc/…Electron/22.3.27` UA | `code:-352` ❌ → **不要抄它的 UA** |
+| `desktop/v1/detail?build=11605` | `code:-352` ❌ |
+| `feed/space?host_mid=`（用户时间线） | 首次成功、随后 `-352`，也见过 HTTP 412 → **不碰** |
+| 不存在 / 已删除的动态 | `code:500` "Cannot read property 'only_fans' of undefined"（nazurin 的 4101147 已失效） |
+| 非数字 id | `code:-400` param parsing failed |
+| 图片 `i0.hdslb.com/bfs/new_dyn/*.jpg` | `HEAD 200 image/jpeg`，带/不带 Referer 均可；`+@518w.jpg` → 25–42 KB ✅ |
+| `t.bilibili.com/h5/dynamic/detail/<id>` | `200` ✅ |
+| `m.bilibili.com/dynamic/<id>` | `302 → t.bilibili.com/<id>` ✅ |
+| `www.bilibili.com/opus/<id>` | `200`，转发动态 `302 → t.bilibili.com/<id>` ✅ |
+| `b23.tv/BV1JTtt6JEZu` | `302 → www.bilibili.com/video/BV…`（视频） |
+| `b23.tv/<无效码>` | **HTTP 200** + `{"code":-404}` ⚠️ 短链判定不能只看状态码 |
+| `playurl`（仅调研用，未采用） | `fnval=1` 匿名给 durl：720P=9.18 MiB / 360P=2.97 MiB；`fnval=4048` 匿名 DASH 上限仅 480P |
+| `dyn_archive` 字段 | 有 `aid/bvid/cover/title/duration_text`，**没有 `cid`**（所以发流要再来一次 `view` 请求） |
+| **风控阶梯（同一 IP 连续请求后实测）** | ① 无 cookie → `-352`；② 仅 `buvid3` → 仍 `-352`；③ `buvid3`+`buvid4`（取自匿名 `/x/frontend/finger/spi`）→ **`code:0` 恢复**；④ 继续高频请求后 → 连同 buvid 一起 `-352`（此时只有登录 cookie 或换 IP） |
+| **正文位置（24 条真实动态逐条审计）** | 有正文的动态都在 `module_dynamic.desc.text`（图文/转发/纯文字，含 34–193 字样本）；**AV（视频投稿）动态 `desc` 恒为 `null`**，内容在 `major.archive.title` / `.desc` 卡片里 → 已做 title 回退 |
+| **`features=itemOpusStyle` 的效果** | 同一端点带此参数后，图文帖改为 `major.opus` 形态：`pics[]`（图，key 是 `url`）、`summary.text`（正文，未截断，实测 307 字整段）、`title`（可选标题）；不带参数则是 legacy `major.draw` + `desc`，而 **opus 图文帖的 `desc` 为 `null`、正文与标题完全丢失**（`opus/1248857553488576532`：legacy `desc:null`，带参数 `summary.text="[doge_金箍]黑白搭配"`）。AV / 转发帖不受该参数影响 → 适配器改为请求时带参数，并保留 legacy 形态兜底 |
+| feed 与 detail 的差异 | `feed/space` 的 item 会把 `desc.text` 挖空，**只有 detail 有正文** → 排查时不要用 feed 数据判断正文缺失 |
+| 不存在的 19 位 id | `4101105 请求数据发生错误`（提示可重试，但只出现在不可能存在的 id 上）→ 仍归入永久错误，见 `code_error` 注释 |
+
+测试样本（live 测试用）：
+
+| 样本 | id | 期望 |
+|---|---|---|
+| 图片动态（2 图 + 话题） | `1245284537985925159` | 2 个 `Illustration`，`{tags}` = `ALin出道20周年快乐` |
+| 转发动态 | `1248982077447077907` | 媒体来自 `orig`（1 图），正文可含 `//@` |
+| 视频动态 | `1248717597691609105` | 封面 1 张 `Illustration` |
+| 纯文字动态 | `1246767523595026450` | `media` 为空 |
+
+关键字段路径：
+
+```
+data.item.id_str
+data.item.modules.module_author.{name,mid}
+data.item.modules.module_dynamic.desc.text
+data.item.modules.module_dynamic.topic.{id,name}            # 单话题，{tags} 来源
+data.item.modules.module_dynamic.major.{draw.items[].src, archive.cover}
+data.item.orig                                              # 转发时存在，结构与 item 相同
+```
+
+---
+
+## 3. 实现
+
+```
+crates/x-media/src/site/bilibili/mod.rs        # re-export
+crates/x-media/src/site/bilibili/interface.rs  # PATTERN / cache_key / enabled / is_retryable /
+                                               # media_headers / BilibiliSite / fetch / code_error /
+                                               # From<Item> for Fetched / caption / 12 单测 + 2 live
+crates/x-media/src/site/bilibili/model.rs      # 纯 Deserialize DTO（全 Option）
+```
+
+- **正则**（同时用于分发、抽 id、缓存键，一个正则三用）：
+  `^(?:https?://)?(?:www|t|m)\.bilibili\.com/(?:opus/|dynamic/|h5/dynamic/detail/)?(\d+)`
+- **缓存键**：`bilibili:<动态 id>`；`source_url` 统一 `https://www.bilibili.com/opus/{id}`。
+- **请求**：`GET /x/polymer/web-dynamic/v1/detail?id=` + `Referer: https://www.bilibili.com/`；
+  `Cookie` 头按优先级取：`BILIBILI_COOKIE` → 缓存的设备 cookie（`GET /x/frontend/finger/spi` 取 `buvid3`/`buvid4`，
+  进程内缓存一次；取不到就不带 cookie，仅 debug 日志）→ 无。指纹接口本身失败**不**让抓取失败。
+  走共享 `CLIENT`（UA `Mozilla/5.0`，30s 超时，`TELOXIDE_PROXY` 透传）。
+- **错误映射**：`0` → 成功；`-352/-412` 与 HTTP 412 → `Transient`（可重试，队列退避；首次记一条 warn 提示
+  `BILIBILI_COOKIE`）；`500`/`4101147` → `NotFound`（永久）；其他 code → `Site`（永久）。
+- **媒体**：
+  - `major.opus.pics[]`（带 `features=itemOpusStyle` 时的图文帖形态，字段名是 `url`）→ 每张一张图；
+    其次 `major.draw.items[]`（legacy，字段名 `src`）→ 同样逐张；`http://` / `//` → `https://`，非 https 开头直接丢弃。
+    `.gif` → `Media::Animated`（`thumbnail_url` 留空，Telegram 自己取首帧——`@518w.jpg` 只对 jpg/webp 实测过），
+    其余 → `Media::Illustration`（`thumbnail_url = url + "@518w.jpg"`，兼作超大时的降级 URL）。
+  - `major.archive.cover` → 1 张 `Illustration`（视频不发流）。
+  - 转发且自身无媒体 → 递归取 `orig` 的媒体；正文拼 `//@{原作者}:\n{原文}`。
+  - 其他 major（PGC/ARTICLE/MUSIC/LIVE/COMMON）不建模 → 无媒体，走既有 "No media found"。
+- **正文 / title**（按信息量从多到少回退）：`major.opus.title` + `major.opus.summary.text`
+  → `module_dynamic.desc.text` → `major.archive.title`。三者分别对应：图文文档（标题+正文）、
+  legacy/转发帖正文、视频投稿卡片标题。开头结尾空白做 trim；整体再由既有 `truncate_caption` 截断。
+- **caption**（与 misskey 同形）：`{opus 链接}\n<a href="space.bilibili.com/{mid}">{name}</a>: {正文}`；
+  `RenderData` 的 `{tags}` 来自话题名；正文由既有 `truncate_caption` 截断。
+- **注册表**：`SITES` 末尾追加 → `/set_format` 白名单、链接缓存、启动校验、日志前缀全部自动生效。
+- **bot 侧仅文案**：`handlers/commands.rs` 三处站点清单字符串 + `state.rs`/`handlers/mod.rs` 注释。
+
+### 与原计划的偏差（及原因）
+
+| 原计划 | 实际 | 原因 |
+|---|---|---|
+| `x/web-interface/view` + `playurl` 发视频 | 不做 | 需求收窄为图片/动图；视频只发封面 |
+| `site/mod.rs` 加 `MAX_MEDIA_UPLOAD_BYTES` 常量 | 不加 | 没有视频尺寸决策就不需要该常量，避免跨 crate 耦合 |
+| `b23.tv` 短链（跟随重定向） | 不匹配 | 多数短链指向视频，匹配后会把"静默忽略"变成用户的 "Failed to fetch media" |
+| `validate()` 校验 cookie | 不做 | 匿名可用，cookie 失效不致命；校验要额外请求一个端点，收益低 |
+| `media_headers` 给 hdslb 加 Referer | 返回 `None` | 实测图片与 durl 均无需 Referer（注释里记了这条验证） |
+| 计划阶段认为设备 cookie 是 YAGNI，不实现 | **实现**（`buvid3`+`buvid4`） | 计划之后做了对照实验：同一 IP 上"无 cookie → -352、只有 buvid3 → -352、buvid3+buvid4 → code:0"，说明这是对本适配器主要失败模式的直接修复，而不是冗余保险 |
+| 只用不带参数的 `v1/detail` | 加 `features=itemOpusStyle` | 用户实测反馈"有内容的动态没有 title"：不带参数时 opus 图文帖返回 legacy 形态，`desc` 为 `null`，正文与标题整个丢失。带参数后同一 ID 返回 `major.opus.summary.text` / `title` / `pics`。AV / 转发帖不受影响，legacy 形态仍保留为兜底 |
+
+---
+
+## 4. 测试与验证
+
+- 单元（13）：正则匹配/拒绝/忽略短链、缓存键归一、图片映射（https 归一 + 缩略图 + `.gif → Animated`）、
+  封面、转发取 `orig` 媒体与正文拼接、纯文字无媒体、caption 转义、业务 code 分类（可重试性）、URL 归一、
+  设备 cookie 拼装。
+- live（3，`#[ignore = "live network: …"]`）：设备 cookie 可取、图片动态 2 图、纯文字动态无媒体。
+  CI 的 `live` job 已覆盖。动态接口被风控时这两条 live 测试打印 `skipping:` 并提前返回（与 pixiv 的
+  token 门控同款约定），设备 cookie 那条仍会真实执行。
+- 实测命令：
+  `cargo run -p x-media --example fetch -- https://www.bilibili.com/opus/1245284537985925159`
+  （输出 2 张 `https://i0.hdslb.com/…jpg` + `@518w.jpg` 缩略图 + 话题 tags）。
+- 全套：`cargo fmt --check`、`cargo clippy --workspace --all-targets -- -D warnings`、`cargo test --workspace` 全绿。
+
+## 5. 已知限制
+
+- 风控按 IP/请求量漂移，阶梯见 §2 最后一行：轻度靠设备 cookie 自愈，重度需 `BILIBILI_COOKIE` 或换 IP。
+  被拦时按**可重试**失败处理（队列退避）+ 一条 warn，不会静默丢帖。
+- 接口 schema 会漂移（`module_dynamic.major` 实测可为 `null` 而正文留在 `desc`）；DTO 全 `Option`，
+  未知形态降级为"无媒体"，不 panic。
+- 动态内嵌视频只发封面图（与 bff 同策略），不下载流。
+- 纯文字动态复用既有 "No media found" 回复。
+- `b23.tv` 短链不被匹配（见上表）。