## MODIFIED Requirements

### Requirement: Восстановление зависшей загрузки при оживлении источника

Система SHALL возвращать в активный поток задачу, упавшую из-за нашей
нетерпеливости (`failed`/`magnet_timeout` или `stuck`/`stalled`), если её
источник в qBittorrent жив и продвинулся: переход выводится из текущего
состояния торрента так же, как при штатной сверке загрузки
(`uploading`/`stalledUP`/… → `completed`; `downloading`/`metaDL`/… →
`downloading`). Восстановление SHALL опираться на фактическое состояние
торрента в qBittorrent, а не на время с момента создания записи.

После возврата в любое нетерминальное состояние (`downloading` или
`completed`) повторный приём того же infohash SHALL снова дедуплицироваться
на эту задачу: активность задачи выводится только из её `state`, отдельный
восстанавливаемый ключ идемпотентности отсутствует. Если за время простоя в
`failed`/`stuck` тем же infohash (любым из хешей задачи) уже завладела
другая активная задача (новый приём, пока эта лежала упавшей), система
SHALL NOT воскрешать упавшую задачу и SHALL оставить её в `failed`/`stuck`,
сохраняя инвариант «не более одной активной задачи на infohash».

`magnet_timeout`/`stalled` SHALL быть редким страховочным исходом, а не
рабочим механизмом. Две страховочные меры при этом РАЗНЫЕ: `magnet_timeout`
SHALL мериться по **возрасту** торрента (время от добавления в qBittorrent,
`added_on`, с фолбэком на `created_at` задачи), а `stuck_after` — по
**длительности простоя** (время от `last_activity` qBittorrent — момента
последнего движения данных), а НЕ по возрасту. Пока торрент в
`metaDL`/`forcedMetaDL` или иным образом прогрессирует в пределах
страховочного таймаута, задача в `failed`/`stuck` из-за него оказаться
SHALL NOT; в частности, торрент со свежим `last_activity` в `stuck` система
пометить SHALL NOT, даже если его общий возраст превышает `stuck_after` (см.
требование о терпеливости к долгим метаданным и меры таймаутов в
`docs/specs/workflow.md`).

#### Scenario: Метаданные пришли после magnet_timeout

- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
  в qBittorrent уже получил метаданные и качается (`downloading`)
- **WHEN** срабатывает фоновая сверка
- **THEN** задача возвращается в `downloading`
- **AND** повторный приём того же infohash снова дедуплицируется на неё

#### Scenario: Торрент уже завершился, пока задача была в failed

- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
  в qBittorrent уже готов к раскладке (`uploading`/`stalledUP`)
- **WHEN** срабатывает фоновая сверка
- **THEN** задача переходит в `completed` и продолжает обычный поток
  (распознавание/раскладка)

#### Scenario: Источник так и не ожил — состояние не меняется

- **GIVEN** задача в `failed` с `error_code` `magnet_timeout`, а её торрент
  всё ещё висит в `metaDL` без метаданных (или отсутствует в qBittorrent)
- **WHEN** срабатывает фоновая сверка
- **THEN** задача остаётся в `failed`

#### Scenario: infohash уже занят другой активной задачей

- **GIVEN** задача #1 в `failed`/`magnet_timeout`, а тем же infohash уже
  владеет другая активная задача #2 (приём повторили, пока #1 лежала упавшей)
- **WHEN** источник ожил (торрент получил метаданные или готов) и сверка
  пытается воскресить #1
- **THEN** #1 остаётся в `failed` (восстановление не выполняется)
- **AND** активной по этому infohash остаётся #2

#### Scenario: Долго качавшийся торрент на миг зашёл в stalledDL

- **GIVEN** торрент качался часами и двигал данные только что (свежий
  `last_activity`), но на текущем тике qBittorrent показывает его `stalledDL`
- **WHEN** `worker` проверяет таймаут зависания
- **THEN** задача остаётся в `downloading` (простой меньше `stuck_after`),
  несмотря на большой возраст торрента
- **AND** ложного `stuck` со «stalled for <возраст>» и уведомления о падении
  не возникает

### Requirement: Ручной повтор зависшей/упавшей загрузки из транспортов

Система SHALL предоставлять пользователю команду повторной попытки (retry)
для задач в `failed`/`stuck` из веб-UI и Telegram (не только через REST API).
Retry SHALL переводить задачу обратно в `downloading`, не вызывая её
немедленного повторного падения по таймауту: базис отсчёта таймаутов SHALL
сбрасываться.

Сброс базиса система SHALL выполнять сохранением времени retry в поле задачи
(`retried_at`, RFC 3339 UTC), которое приподнимает пол ОБОИХ страховочных мер
(`magnet_timeout` по возрасту и `stuck_after` по простою): отсчёт ведётся от
`max(базис, retried_at)`. `retried_at` SHALL храниться в задаче (не в памяти
процесса), чтобы сброс базиса пережил интервал поллинга и рестарт процесса.
Благодаря этому даже живой, но давно добавленный либо давно простаивающий
торрент после retry SHALL получать свежее окно и на ближайшем тике сверки
падать снова SHALL NOT.

Если источник задачи уже жив и ЗДОРОВ в qBittorrent, retry SHALL перецепляться
к существующему торренту, а не добавлять источник повторно вслепую. Если же
живой торрент в состоянии ошибки qBittorrent (`error`/`missingFiles`), retry
перецепляться к нему SHALL NOT (перецепка к сломанному торренту тут же вернула
бы задачу в `failed` по сверке) и SHALL повторно отдать источник, как при
отсутствии раздачи. Повторный `Add` выполняется, только когда раздачи в
qBittorrent нет ЛИБО она сломана.

Повторный `Add` при retry система SHALL выполнять **по типу источника**
(`source_type`), как и добавление пойманной загрузки (см. `download-tracking`
«Добавление пойманной загрузки в qBittorrent»): magnet/url — ссылкой; torrent —
сохранёнными байтами `.torrent` файлом. Для torrent-источника retry БЕЗ живой
раздачи система SHALL добавлять раздачу байтами и SHALL NOT активировать задачу
в `downloading`, не добавив её (иначе задача повиснет как «нет в qBittorrent»).

#### Scenario: Retry упавшей magnet-загрузки из веб-UI

- **GIVEN** задача в `failed`, её торрент жив и здоров в qBittorrent
- **WHEN** пользователь нажимает retry в веб-UI
- **THEN** задача возвращается в `downloading` без повторного `Add`
- **AND** не падает снова на ближайшем тике сверки по таймауту

#### Scenario: Retry живого, но давно простаивающего торрента не падает снова

- **GIVEN** задача в `stuck`/`stalled`, её торрент жив в qBittorrent, но
  добавлен давно и данные не двигались дольше `stuck_after`
- **WHEN** пользователь нажимает retry
- **THEN** задача возвращается в `downloading` без повторного `Add`
- **AND** на ближайшем тике сверки НЕ падает снова в `stuck` (базис сброшен
  через `retried_at`)

#### Scenario: Retry доступен в Telegram

- **WHEN** для задачи в `failed`/`stuck` пользователь вызывает retry в
  Telegram-боте
- **THEN** задача возвращается в `downloading`

#### Scenario: Retry без живого источника добавляет источник заново

- **GIVEN** задача в `failed`, раздачи в qBittorrent нет
- **WHEN** пользователь инициирует retry
- **THEN** источник добавляется в qBittorrent заново — magnet/url ссылкой,
  torrent сохранёнными байтами файлом
- **AND** задача переходит в `downloading`

#### Scenario: Retry сломанного живого торрента повторно отдаёт источник

- **GIVEN** задача в `failed`, её торрент присутствует в qBittorrent, но в
  состоянии ошибки (`error`/`missingFiles`)
- **WHEN** пользователь инициирует retry
- **THEN** источник отдаётся заново (перецепка к сломанному торренту не
  выполняется)
- **AND** задача переходит в `downloading`

#### Scenario: Retry torrent-загрузки без живого источника

- **GIVEN** задача с `source_type = torrent` в `failed`, раздачи в qBittorrent
  нет, байты `.torrent` сохранены
- **WHEN** пользователь инициирует retry
- **THEN** сохранённые байты добавляются в qBittorrent файлом
- **AND** задача переходит в `downloading` (не остаётся без раздачи)