Rebuild reliability core: SQLite store, durable queue, contained errors

[miridius]

Problem

The bot's job queue, pending confirmations, and video cache were all coordinated through raw files under /storage: job JSONs sorted by filename, pending-download files taken and put back, an info-cache directory with symlink aliases, and videos named by a title-based template with .id sidecar files. Coordinating concurrent access that way kept producing whole classes of user-visible failures:

• "yt-dlp output file not found" on perfectly good downloads: the bot predicted the output path from scrape-time metadata, and anything that shifted between scrape and download (Instagram carousels, format re-selection, title changes) made it look for a file that was never produced.
• Races between confirm and cancel, between duplicate requests for one video, and between retries and cleanup, each patched individually as they bit.
• A restart lost or duplicated in-flight work; failures burned retries on permanently-dead URLs (or gave up on transient ones) and spammed chats with per-attempt noise.
• Instagram stopped working entirely: yt-dlp's stable channel carries a broken Instagram extractor, and the self-updater tracked stable.

Fix

One embedded bun:sqlite database becomes the durable coordination store (jobs, parked confirmations, an identity-keyed blob index, a URL info cache), so every multi-step state change is a transaction instead of a rename/unlink dance.

• Blobs are keyed by yt-dlp's stable identity (extractor:id:format, with a URL-salted fallback for identity-less extractors). Downloads write into a private per-download staging dir and the bot takes whatever file actually appeared, so path prediction, and its whole failure class, is gone. Bytes are refcounted: dropped only when nothing references them, kept as a file_id cache after upload.
• A durable job queue dispatches up to 3 downloads in parallel with at-least-once recovery on boot, exponential-backoff retries for transient failures, and fail-fast classification of permanent ones (live-verified wordings). Each attempt continues one status message instead of spawning threads; groups see only a terminal report.
• Dup-free shutdown: SIGTERM kills in-flight downloads immediately (they re-run next boot; bytes not yet sent can't duplicate) and drains in-flight sends (a started send completes server-side, verified live), with the process held alive until both queue and inline work finish.
• yt-dlp self-updates every 5 minutes on the nightly channel (version pre-check against the nightly release tag, update on a copy, atomic rename). Nightly is where extractor fixes land first; the switch is what restores Instagram.
• Boot and hourly sweeps reconcile storage: legacy-era layouts, orphaned bytes, expired info/pending/handled rows; dev and prod get separate DB/blob/staging paths on the shared volume.
• Failure reporting is delivery-reliable: flushes retry transiently-failed sends within bounded passes, deterministically-rejected HTML is sanitized in place and repaired in the same flush, and oversize lines are hard-split tag-aware so a chunk can never become permanently unsendable.

Testing

Tests mock only unowned boundaries (Telegram at the fetch layer via a parity-checked MockBotApi, GitHub releases): real SQLite, real filesystem, real child processes via on-PATH stubs. 342 unit tests plus a network-free restart-recovery e2e; ./e2e.sh full exercises real downloads (youtube, reddit, instagram) against the real yt-dlp, self-updated to the channel prod runs. Live QA against the dev bot covered the happy path, group confirmations, permanent/transient error classification, and mid-download/mid-upload SIGTERM.

The .claude workflow now enforces review deterministically: commit and merge gates verify content-bound approvals minted only by fresh attestation agents.

🤖 Generated with Claude Code