telepost-bot 2.83.2__tar.gz → 2.84.0__tar.gz

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/CHANGELOG.md

@@ -8,6 +8,24 @@
 > 发布说明面向普通用户：写「对用户有什么改变」，不写内部实现细节（模块名、函数名、配置键）；
 > 技术细节放进代码注释或 `docs/`。每个 Release 的正文由本文件对应版本段自动生成。
 
+## [2.84.0](https://github.com/redtidev1918/TelePost/compare/v2.83.2...v2.84.0) (2026-10-21)
+
+
+### Features
+
+* **review:** bound review preview media by Telegram's 48h deletion window ([b480e4a](https://github.com/redtidev1918/TelePost/commit/b480e4a7e0b1675ba22dc802b94a67fc67e67b9c))
+* **review:** bound review preview media by Telegram's deletion window ([65da48b](https://github.com/redtidev1918/TelePost/commit/65da48bd59e92d25c94d762752a4f7f39795b5c7))
+
+
+### Bug Fixes
+
+* durable Telegram update inbox with recoverable submission conversations ([1b7f66d](https://github.com/redtidev1918/TelePost/commit/1b7f66d72fa5797a1ffb99fd45a4353a41eb201c))
+* durable webhook inbox with recoverable submission conversations ([6d6b5ec](https://github.com/redtidev1918/TelePost/commit/6d6b5ec5988d42d458136f18a548e6fdb311f509))
+* harden webhook payload admission and miniapp static guard ([a0cf21d](https://github.com/redtidev1918/TelePost/commit/a0cf21d697f21e2535b5ece6d5cb47fe2955857c))
+* harden webhook payload admission and miniapp static guard ([a621807](https://github.com/redtidev1918/TelePost/commit/a621807264311ef58908741bad4a0d5c5fc77552))
+* make review expiry recoverable with durable submitter notifications ([f6189d2](https://github.com/redtidev1918/TelePost/commit/f6189d2f5f1f86e3c44bc549f24941b6e8be1bdf))
+* make review expiry recoverable with durable submitter notifications ([c322d40](https://github.com/redtidev1918/TelePost/commit/c322d40c6402ea3fd809cbc87fc3459c34631dd6))
+
 ## [2.83.2](https://github.com/redtidev1918/TelePost/compare/v2.83.1...v2.83.2) (2026-10-15)
 
 

{telepost_bot-2.83.2/telepost_bot.egg-info → telepost_bot-2.84.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: telepost-bot
-Version: 2.83.2
+Version: 2.84.0
 Summary: Telegram submission, review, and publication bot with a Mini App, HTTP API, and multi-bot supervisor.
 Author: redtidev1918
 License-Expression: MIT

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/database/db_manager.py

@@ -76,6 +76,52 @@ async def init_db():
             except Exception:
                 pass  # 字段已存在
 
+            # 投稿会话代数：/submit 重建会话时递增。媒体追加的 update_id
+            # 去重以（user_id, epoch, update_id）为键，重放只会命中同一代，
+            # 旧代重放不会污染新会话（§durable-inbox）。
+            try:
+                await conn.execute(
+                    "ALTER TABLE submissions ADD COLUMN epoch INTEGER NOT NULL DEFAULT 0")
+                logger.info("已添加 epoch 字段到 submissions 表")
+            except Exception:
+                pass  # 字段已存在
+
+            # Durable webhook inbox（§durable-inbox）：Telegram Update 在 HTTP 200
+            # 之前先落库；进程崩溃后由启动恢复按 update_id 顺序重放。
+            # 每个 Bot 独立数据库，update_id 主键即 (bot, update_id) 唯一。
+            await conn.execute('''
+                CREATE TABLE IF NOT EXISTS webhook_inbox (
+                    update_id INTEGER PRIMARY KEY,
+                    payload TEXT NOT NULL,
+                    state TEXT NOT NULL DEFAULT 'pending',
+                    attempts INTEGER NOT NULL DEFAULT 0,
+                    last_error TEXT DEFAULT '',
+                    received_at REAL NOT NULL,
+                    updated_at REAL NOT NULL,
+                    lease_until REAL,
+                    next_attempt_at REAL NOT NULL DEFAULT 0,
+                    done_at REAL
+                )
+            ''')
+            await conn.execute(
+                'CREATE INDEX IF NOT EXISTS idx_webhook_inbox_due '
+                'ON webhook_inbox(state, next_attempt_at, update_id)')
+
+            # 媒体追加去重日志：同一 (user, update) 跨投稿代只应用一次
+            # （epoch 仅作审计），与 submissions 行的更新同事务提交，崩溃后
+            # 重放收敛。worker 严格按 update_id 头部顺序处理，正常路径不会
+            # 出现「旧代 update 在新会话之后执行」；跨代匹配是乱序的硬防线。
+            await conn.execute('''
+                CREATE TABLE IF NOT EXISTS submission_media_log (
+                    user_id INTEGER NOT NULL,
+                    update_id INTEGER NOT NULL,
+                    epoch INTEGER NOT NULL DEFAULT 0,
+                    entry TEXT NOT NULL,
+                    applied_at REAL NOT NULL,
+                    PRIMARY KEY (user_id, update_id)
+                )
+            ''')
+
             # API 访问令牌（用于 /api/v1 自动化投稿，仅存哈希不存明文）
             await conn.execute('''
                 CREATE TABLE IF NOT EXISTS api_tokens (
@@ -138,6 +184,41 @@ async def init_db():
                 logger.info("已添加 target_id 字段到 pending_reviews 表")
             except Exception:
                 pass  # 字段已存在
+            # NULL leaves historical expiry untouched; new expirations checkpoint
+            # their Telegram effects independently of the terminal review state.
+            columns = {r[1] for r in await (await conn.execute(
+                'PRAGMA table_info(pending_reviews)')).fetchall()}
+            for column, ddl in (
+                ('expiry_progress', 'TEXT'),
+                ('expiry_next_attempt_at', 'REAL'),
+            ):
+                if column not in columns:
+                    await conn.execute(f'ALTER TABLE pending_reviews ADD COLUMN {column} {ddl}')
+            await conn.execute(
+                'CREATE INDEX IF NOT EXISTS idx_review_expiry_due '
+                'ON pending_reviews(expiry_next_attempt_at) '
+                'WHERE expiry_next_attempt_at IS NOT NULL')
+
+            # Time-bounded review-media lifecycle (§review-media-ttl):
+            # preview media is deleted ~36h after sending (Telegram only allows
+            # deletion within 48h) while the control card stays actionable;
+            # admins regenerate previews on demand from the stored file_ids.
+            # NULL preview_state on legacy rows means 'present' with the
+            # review's created_at as the TTL anchor.
+            columns = {r[1] for r in await (await conn.execute(
+                'PRAGMA table_info(pending_reviews)')).fetchall()}
+            for column, ddl in (
+                ('preview_state', 'TEXT'),
+                ('preview_sent_at', 'REAL'),
+                ('preview_attempts', 'INTEGER NOT NULL DEFAULT 0'),
+            ):
+                if column not in columns:
+                    await conn.execute(f'ALTER TABLE pending_reviews ADD COLUMN {column} {ddl}')
+            await conn.execute(
+                'CREATE INDEX IF NOT EXISTS idx_review_preview_due '
+                "ON pending_reviews(COALESCE(preview_sent_at, created_at)) "
+                "WHERE status='pending'")
+
             # Generic, bounded provenance for API submissions (any client).
             # TelePost only stores/displays these; it never interprets them.
             for column, ddl in (
@@ -961,7 +1042,8 @@ async def cleanup_old_data():
                     c = await conn.cursor()
                     await c.execute(
                         "DELETE FROM pending_reviews "
-                        "WHERE status IN ('rejected','published','deleted','failed','expired') AND updated_at < ?",
+                        "WHERE status IN ('rejected','published','deleted','failed','expired') AND updated_at < ? "
+                        "AND expiry_next_attempt_at IS NULL",
                         (review_cutoff,),
                     )
                     logger.info("已清理过期审核记录（保留 %d 天）", review_retention_days)
@@ -973,6 +1055,21 @@ async def cleanup_old_data():
                     )
                     logger.info("已清理过期 API 通知幂等记录（保留 %d 天）", review_retention_days)
 
+        # Durable inbox 保留策略：已完成记录 7 天后清理；dead（永久失败、需
+        # 人工核对）保留 30 天。pending/processing 与未过期重试行绝不由这里的
+        # 普通过期清理删除——它们只属于启动恢复与 worker。
+        now_ts = datetime.now().timestamp()
+        async with get_db() as conn:
+            await conn.execute(
+                "DELETE FROM webhook_inbox WHERE state='done' AND done_at < ?",
+                (now_ts - 7 * 86400,))
+            await conn.execute(
+                "DELETE FROM webhook_inbox WHERE state='dead' AND updated_at < ?",
+                (now_ts - 30 * 86400,))
+            await conn.execute(
+                "DELETE FROM submission_media_log WHERE applied_at < ?",
+                (now_ts - 7 * 86400,))
+
         # Append-only audit: prune old rows, but keep every event attached to a
         # still-open review (preparing/pending/publishing/failed) regardless of
         # age. Unattached events (review_id IS NULL) follow the age cutoff.

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/handlers/callback_handlers.py

@@ -19,7 +19,7 @@ from handlers.search_handlers import (
 logger = logging.getLogger(__name__)
 
 GLOBAL_CALLBACK_PATTERNS = (
-    r"^review_(?:approve|reject|spoiler|refetch|block_user|block_api):",
+    r"^review_(?:approve|reject|spoiler|preview|refetch|block_user|block_api):",
     r"^admin_block:",
     r"^sched_recover\|",
     r"^(?:hot_filter_|hot_limit_|hot_refresh$)",
@@ -74,6 +74,9 @@ async def handle_callback_query(update: Update, context: CallbackContext):
         elif data.startswith("review_spoiler:"):
             from handlers.review import toggle_review_spoiler
             return await toggle_review_spoiler(update, context)
+        elif data.startswith("review_preview:"):
+            from handlers.review import restore_review_preview
+            return await restore_review_preview(update, context)
         elif data.startswith("review_refetch:"):
             from handlers.review import refetch_review
             return await refetch_review(update, context)

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/handlers/conversation.py

@@ -34,8 +34,13 @@ def _exclusive(callback):
     return exclusive
 
 
-def build_submission_conversation() -> ConversationHandler:
-    """构建投稿 ConversationHandler：唯一入口 /submit 与「开始投稿」按钮。"""
+def build_submission_conversation(*, persistent: bool = False) -> ConversationHandler:
+    """构建投稿 ConversationHandler：唯一入口 /submit 与「开始投稿」按钮。
+
+    persistent=True 需要宿主 Application 已挂载 persistence（PTB 硬性要求）；
+    生产 main.py 总是先挂 PicklePersistence 再 setup_application，由后者按
+    ``application.persistence`` 决定传值。
+    """
     media_filters = (
         filters.PHOTO | filters.VIDEO | filters.ANIMATION | filters.AUDIO
         | filters.Document.ALL
@@ -71,4 +76,8 @@ def build_submission_conversation() -> ConversationHandler:
         },
         fallbacks=[CommandHandler("cancel", _exclusive(cancel))],
         name="submission_conversation",
+        # §durable-inbox：会话状态经已挂载的 PicklePersistence 落盘，重启后
+        # 投稿会话可继续。inbox worker 在标记 Update 完成前显式刷新持久化，
+        # 使「业务已写库、状态未落盘」的崩溃窗口由重放收敛而不是丢失。
+        persistent=persistent,
     )

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/handlers/review.py

@@ -200,14 +200,15 @@ def _stager(bot) -> TelegramReviewStager:
 # ---- back-compat UI names -------------------------------------------------
 def _review_keyboard(review_id, link="", *, spoiler=False, source="api",
                      work_id="", failed=False, submitter_user_id=None,
-                     actor_kind="user", actor_subject=""):
+                     actor_kind="user", actor_subject="",
+                     media_cleared=False):
     # §submission-entrypoint: review/staging cards never expose the public
     # submission acquisition CTA (it belongs only to final Channel Publications).
     return review_keyboard.review_keyboard(
         review_id, link, spoiler=spoiler, source=source,
         work_id=work_id, failed=failed,
         submitter_user_id=submitter_user_id, actor_kind=actor_kind,
-        actor_subject=actor_subject,
+        actor_subject=actor_subject, media_cleared=media_cleared,
     )
 
 
@@ -496,41 +497,30 @@ async def _find_published_work(target_id, work_type, work_id):
     )
 
 
-async def _notify_chat_submitter(bot, row, text: str):
-    if row["source"] != "chat":
-        return
-    try:
-        await bot.send_message(chat_id=row["user_id"], text=text)
-    except Exception:
-        logger.warning("通知聊天投稿人审核结果失败: review_id=%s", row["id"],
-                       exc_info=True)
+_expiry_lock = asyncio.Lock()
 
 
 async def expire_stale_reviews(bot, *, now: Optional[float] = None) -> int:
-    """Expire stale pending reviews and remove their Telegram preview messages."""
-    if PENDING_REVIEW_RETENTION_DAYS <= 0:
-        return 0
+    """Expire new rows and resume incomplete effects, including after disabling expiry."""
     from telepost.storage.sqlite.reviews import ReviewRepository
+    from telepost.telegram.review_expiry import finish_expiry
 
     current_time = time.time() if now is None else now
-    cutoff = current_time - PENDING_REVIEW_RETENTION_DAYS * 86400
-    error = (
-        f"pending review expired after {PENDING_REVIEW_RETENTION_DAYS} days"
-    )
-    rows = await ReviewRepository().expire_pending(
-        cutoff=cutoff, now=current_time,
-        batch_size=PENDING_REVIEW_CLEANUP_BATCH_SIZE, error=error,
-    )
-    for row in rows:
-        await _delete_messages(bot, _review_message_ids(row))
-        await _notify_chat_submitter(
-            bot, row,
-            tr('⌛ 你的投稿超过 {p0} 天未审核，已自动过期。').format(p0=PENDING_REVIEW_RETENTION_DAYS),
-        )
-    if rows:
-        logger.info("已过期并清理 %d 条待审核投稿（保留 %d 天）",
-                    len(rows), PENDING_REVIEW_RETENTION_DAYS)
-    return len(rows)
+    async with _expiry_lock:
+        repo = ReviewRepository()
+        rows = []
+        if PENDING_REVIEW_RETENTION_DAYS > 0:
+            rows = await repo.expire_pending(
+                cutoff=current_time - PENDING_REVIEW_RETENTION_DAYS * 86400,
+                now=current_time, batch_size=PENDING_REVIEW_CLEANUP_BATCH_SIZE,
+                error=f"pending review expired after {PENDING_REVIEW_RETENTION_DAYS} days")
+        for row in await repo.expiry_due(now=current_time, limit=PENDING_REVIEW_CLEANUP_BATCH_SIZE):
+            try:
+                await finish_expiry(bot, row, now=current_time)
+            except Exception as exc:
+                logger.warning('Expiry checkpoint failed: review_id=%s error_class=%s',
+                               row['id'], type(exc).__name__)
+        return len(rows)
 
 
 async def cleanup_superseded_reviews(bot, *, now: Optional[float] = None) -> int:
@@ -1734,6 +1724,7 @@ async def toggle_review_spoiler(update, context):
                 submitter_user_id=_row_value(row, "submitter_user_id"),
                 actor_kind=_row_value(row, "actor_kind") or "user",
                 actor_subject=_row_value(row, "actor_subject") or "",
+                media_cleared=_row_value(row, "preview_state") == "cleared",
             )
         )
     except Exception:
@@ -1756,6 +1747,75 @@ async def toggle_review_spoiler(update, context):
         )
 
 
+async def restore_review_preview(update, context):
+    """§review-media-ttl: regenerate a cleaned preview from stored file_ids.
+
+    Only a still-pending review with cleared media can regenerate (the CAS in
+    begin_preview_regen); expired/rejected/published/superseded rows keep
+    their history untouched. A failure keeps whatever was actually sent as
+    the current preview, so repeated clicks never duplicate media."""
+    query = update.callback_query
+    if update.effective_user.id not in ADMIN_IDS:
+        await _answer(query, tr('你没有审核权限'), show_alert=True)
+        return
+    try:
+        review_id = int(query.data.split(":", 1)[1])
+    except (ValueError, IndexError):
+        await _answer(query, tr('无效的审核记录'), show_alert=True)
+        return
+
+    from telepost.storage.sqlite.reviews import ReviewRepository
+    row = await review_service.get_row(review_id)
+    if row is None:
+        await _answer(query, tr('审核记录不存在'), show_alert=True)
+        return
+    if _row_value(row, "status") != "pending":
+        await _answer(query, tr('该投稿已处理，无法恢复预览'), show_alert=True)
+        return
+    state = _row_value(row, "preview_state")
+    if state != "cleared":
+        # Each non-cleared state has its own honest answer; never resend.
+        if state == "regenerating":
+            await _answer(query, tr('预览正在恢复中，请稍候。'))
+        elif state == "restricted":
+            await _answer(query, tr('预览媒体已超出 Telegram 删除时限，仍在审核群中，'
+                                    '需人工清理。'), show_alert=True)
+        elif state == "uncertain":
+            await _answer(query, tr('上次恢复结果不确定，请在审核群核对媒体是否已重发。'),
+                          show_alert=True)
+        elif state == "partial":
+            await _answer(query, tr('预览媒体正在清理，暂不可恢复。'))
+        else:  # 'present' / NULL: media is still on screen
+            await _answer(query, tr('预览媒体当前可用，无需恢复。'))
+        return
+    if not await ReviewRepository().begin_preview_regen(review_id):
+        await _answer(query, tr('预览正在恢复中，请稍候。'))
+        return
+
+    from telepost.telegram.review_media import regenerate_review_preview
+    result = await regenerate_review_preview(context.bot, row)
+    if not result["ok"]:
+        await _answer(query, result["message"], show_alert=True)
+        return
+    await _answer(query, tr('预览已恢复（{p0} 条消息），将按同样的时限自动清理。').format(
+        p0=len(result["message_ids"])))
+    try:
+        await query.edit_message_reply_markup(
+            reply_markup=_review_keyboard(
+                review_id, row["link"], spoiler=bool(row["spoiler"]),
+                source=row["source"],
+                work_id=_work_id_from_link(row["link"] or ""),
+                submitter_user_id=_row_value(row, "submitter_user_id"),
+                actor_kind=_row_value(row, "actor_kind") or "user",
+                actor_subject=_row_value(row, "actor_subject") or "",
+                media_cleared=False,
+            )
+        )
+    except Exception:
+        logger.debug("恢复预览后刷新审核卡键盘失败: review_id=%s", review_id,
+                     exc_info=True)
+
+
 def _submit_pixivflow_refetch(target_id: str, request_id: str,
                               correlation_id: str = "") -> dict:
     """Submit through the PixivFlow JOB PORT (no URL building here).

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/handlers/upload.py

@@ -91,7 +91,8 @@ async def handle_upload(update: Update, context: CallbackContext) -> int:
         )
         return STATE["UPLOAD"]
 
-    count = await append_entry(user_id, entry)
+    count = await append_entry(user_id, entry,
+                               update_id=getattr(update, "update_id", None))
     if count == 0:
         await message.reply_text(MessageFormatter.session_expired(), parse_mode="HTML")
         return ConversationHandler.END

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/main.py

@@ -461,6 +461,14 @@ async def main():
 
     # Review DB is the source of truth. Repair any row left between preview
     # staging and control-message creation before exposing /ready to producers.
+    # §durable-inbox 先于一切恢复：重放的 Update 会重建其业务写入，之后
+    # reconcile 才能扫到完整的审核/发布状态。Webhook 模式下这是 200 确认后
+    # 崩溃不丢稿的恢复通道；Polling 模式下表为空、worker 空转（无副作用）。
+    from telepost.telegram.inbox_worker import UpdateInboxWorker
+    update_inbox = UpdateInboxWorker(application)
+    await update_inbox.recover()
+    update_inbox.start()
+    application.bot_data["update_inbox_worker"] = update_inbox
     await reconcile_incomplete_reviews(application.bot, stale_seconds=0)
     # §refetch-lifecycle 启动即扫：重抓是一等持久 Job，重启后台账是唯一真相。
     # 在 /ready 之前一次性接管所有非终态 attempt（远端已终态的经状态机收敛），
@@ -652,6 +660,15 @@ async def shutdown(
             await application.updater.stop()
     except Exception as e:
         logger.warning(f"停止 Updater 失败（可忽略）: {e}")
+    # §durable-inbox 停机：先停 Update worker，再走 Application 的收尾
+    # （stop 会等待队列与 create_task 任务收敛，持久化随后落盘）。
+    try:
+        inbox_worker = application.bot_data.get("update_inbox_worker")
+        if inbox_worker is not None:
+            await inbox_worker.stop()
+            logger.info("Update inbox worker 已停止")
+    except Exception as e:
+        logger.warning(f"停止 Update inbox worker 失败（可忽略）: {e}")
     # §refetch-lifecycle 停机：显式停掉 30 秒心跳作业并留下「心跳已停止」的持久
     # 事实，在途 attempt 保持非终态（重启后由启动即扫接管），绝不静默消失。
     try:
@@ -791,8 +808,14 @@ def setup_application(application):
         # 添加会话处理器
         logger.info("注册会话处理器...")
         from handlers.conversation import build_submission_conversation
-        conv_handler = build_submission_conversation()
+        # §durable-inbox：挂了 persistence 就让投稿会话持久化（重启可恢复）。
+        # PTB 要求宿主 Application 必须已有 persistence，故按实际情况传值；
+        # 无 persistence 的裸 Application（测试/嵌入）保持内存态旧行为。
+        conv_handler = build_submission_conversation(
+            persistent=bool(application.persistence))
         application.add_handler(conv_handler, group=2)
+        if application.persistence:
+            logger.info("投稿会话已启用持久化（PicklePersistence）")
         logger.info("会话处理器注册完成")
     except Exception as e:
         logger.error(f"注册会话处理器失败: {e}", exc_info=True)
@@ -833,6 +856,14 @@ def setup_application(application):
             await cleanup_old_data()
             await expire_stale_reviews(context.bot)
             await cleanup_superseded_reviews(context.bot)
+            # §review-media-ttl：先把崩溃遗留的「恢复中」claim 收敛成可见的
+            # uncertain，再删到期（默认 36h）的审核预览媒体；控制卡保留。
+            from telepost.telegram.review_media import (
+                clean_review_preview_media,
+                resolve_stale_preview_regens,
+            )
+            await resolve_stale_preview_regens()
+            await clean_review_preview_media(context.bot)
             await poll_refetch_jobs(context.bot, force=True)
             await reconcile_incomplete_reviews(context.bot)
             from telepost.application.submitter_notify import (

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/telepost/application/submitter_notify.py

@@ -277,7 +277,12 @@ async def flush_submitter_notifications(bot, *, limit: int = 20) -> int:
     for row in rows:
         try:
             payload = json.loads(row["payload"] or "{}")
-            text = format_publication_message(payload, include_changes)
+            if row['kind'] == 'review_expired':
+                days = str(payload['reason']).split(' after ')[-1].split(' ')[0]
+                text = tr('你的投稿 #{review_id} 因超过 {days} 天未审核，已自动过期。\n\n这不代表稿件被管理员拒绝。\n如仍需要投稿，可以重新提交。').format(
+                    review_id=payload['review_id'], days=days)
+            else:
+                text = format_publication_message(payload, include_changes)
             result = await bot.send_message(
                 chat_id=int(row["telegram_user_id"]), text=text
             )

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/telepost/build_info.py

@@ -8,7 +8,7 @@ to the entry points; when present it overrides these committed defaults.
 # Bumped automatically by release-please (extra-files in
 # release-please-config.json). Release bundles and images override it at build
 # time with the exact version/commit; this constant is the local-dev fallback.
-RELEASE_VERSION = "2.83.2"  # x-release-please-version
+RELEASE_VERSION = "2.84.0"  # x-release-please-version
 RELEASE_COMMIT = "dev"
 BUILD_DATE = "dev"
 SERVICE = "telepost"

{telepost_bot-2.83.2 → telepost_bot-2.84.0}/telepost/observability/doctor.py

@@ -53,10 +53,12 @@ CHECK_CODES: Tuple[str, ...] = (
     "db_integrity",
     "refetch_stuck",
     "refetch_jobs",
+    "webhook_inbox",
     "refetch_active_invariant",
     "review_queue_orphans",
     "review_queue_publishing",
     "review_queue_counts",
+    "review_preview_lifecycle",
     "delivery_outbox",
     "audit_events_recent",
 )
@@ -576,6 +578,62 @@ def _check_refetch_jobs(
     collector.add("refetch_jobs", level, _prefix(db_path, message), details)
 
 
+# ---- check 2b: durable update inbox (§durable-inbox) ------------------------
+
+
+def _check_webhook_inbox(
+    db_path: str, conn: sqlite3.Connection, collector: _Collector
+) -> None:
+    """Webhook durable inbox: backlog age and permanently failed updates."""
+    columns = _table_columns(conn, "webhook_inbox")
+    if not columns:
+        collector.add(
+            "webhook_inbox", SKIP,
+            _prefix(db_path, "webhook_inbox 表不存在（旧库或 Polling-only 部署），跳过"),
+        )
+        return
+
+    pending = processing = dead = 0
+    oldest_pending_age: Optional[float] = None
+    for row in conn.execute(
+        "SELECT state, COUNT(*) AS n, MIN(next_attempt_at) AS oldest "
+        "FROM webhook_inbox GROUP BY state"
+    ).fetchall():
+        if row["state"] == "pending":
+            pending = int(row["n"])
+            if row["oldest"] is not None:
+                oldest_pending_age = max(0.0, collector.now - float(row["oldest"]))
+        elif row["state"] == "processing":
+            processing = int(row["n"])
+        elif row["state"] == "dead":
+            dead = int(row["n"])
+
+    summary = f"Inbox: pending: {pending} processing: {processing} dead: {dead}"
+    details: Dict[str, Any] = {
+        "path": db_path,
+        "pending": pending,
+        "processing": processing,
+        "dead": dead,
+        "oldest_pending_age_seconds": (
+            round(oldest_pending_age, 1) if oldest_pending_age is not None else None
+        ),
+        "summary": summary,
+    }
+    # dead = 已确认接收但重试耗尽的 Update：用户可见的丢稿，必须报红。
+    # pending 积压超过 1 小时说明 worker 停摆或持续失败，先黄后查。
+    if dead:
+        level = CRIT
+    elif pending and oldest_pending_age is not None and oldest_pending_age > 3600:
+        level = WARN
+    else:
+        level = OK
+    age_text = (
+        f"{oldest_pending_age:.0f}s" if oldest_pending_age is not None else "-"
+    )
+    message = f"{summary}｜最老待处理年龄 {age_text}"
+    collector.add("webhook_inbox", level, _prefix(db_path, message), details)
+
+
 # ---- check 3: one-active-attempt-per-chain invariant -----------------------
 
 
@@ -869,6 +927,60 @@ def _check_review_queue_counts(
     )
 
 
+# ---- check 6b: review preview media lifecycle (§review-media-ttl) ----------
+
+
+def _check_review_preview_lifecycle(
+    db_path: str, conn: sqlite3.Connection, collector: _Collector
+) -> None:
+    """Surface preview media that cleanup could not (or could not safely) delete.
+
+    ``restricted`` = Telegram refuses deletion (past 48h / permission);
+    ``uncertain`` = a regeneration died before recording message ids, so a
+    human must check the review group. Both are permanent, visible states —
+    WARN, never a silently "cleaned" review.
+    """
+    columns = _table_columns(conn, "pending_reviews")
+    if not columns or "preview_state" not in columns:
+        collector.add(
+            "review_preview_lifecycle",
+            SKIP,
+            _prefix(db_path, "pending_reviews.preview_state 列不存在，跳过"),
+        )
+        return
+    counts = {
+        str(row["state"]): int(row["n"])
+        for row in conn.execute(
+            "SELECT COALESCE(preview_state, 'present') AS state, "
+            "COUNT(*) AS n FROM pending_reviews "
+            "WHERE status='pending' GROUP BY state"
+        ).fetchall()
+    }
+    restricted = counts.get("restricted", 0)
+    uncertain = counts.get("uncertain", 0)
+    needs_manual = restricted + uncertain
+    summary = ", ".join(f"{key}={counts[key]}" for key in sorted(counts)) or "空"
+    collector.add(
+        "review_preview_lifecycle",
+        WARN if needs_manual else OK,
+        _prefix(
+            db_path,
+            f"审核预览媒体按状态计数：{summary}"
+            + (
+                f"；{needs_manual} 条需人工处理"
+                f"（restricted={restricted} uncertain={uncertain}）"
+                if needs_manual
+                else ""
+            ),
+        ),
+        {
+            "path": db_path,
+            "counts": counts,
+            "needs_manual": needs_manual,
+        },
+    )
+
+
 # ---- check 7: delivery ledger / outbox -------------------------------------
 
 
@@ -1078,10 +1190,12 @@ def _check_database(db_path: str, collector: _Collector) -> None:
             return
         has_active = _check_refetch_stuck(db_path, conn, collector)
         _check_refetch_jobs(db_path, conn, collector)
+        _check_webhook_inbox(db_path, conn, collector)
         _check_refetch_active_invariant(db_path, conn, collector)
         _check_review_queue_orphans(db_path, conn, collector)
         _check_review_queue_publishing(db_path, conn, collector)
         _check_review_queue_counts(db_path, conn, collector)
+        _check_review_preview_lifecycle(db_path, conn, collector)
         _check_delivery_outbox(db_path, conn, collector)
         _check_audit_events_recent(db_path, conn, collector, has_active)
     except sqlite3.Error as exc: