Add tag-only handoff mode with deferred ARR follow-up

[tomerh2001]

Summary

Implements a configurable tag-only handoff workflow so Decluttarr can defer cleanup ownership to an external service (for example qbit_manage), while optionally triggering ARR follow-up only after external removal is detected.

What Changed

• Added new ARR-removal job controls:
  • action_mode: remove | skip | tag_only
  • handoff_tag
  • deferred_arr_followup
  • followup_trigger (currently on_download_removed)
• Extended JobDefaults and job-level parsing for the above fields.
• Added env parsing support for job-default keys (ACTION_MODE, HANDOFF_TAG, DEFERRED_ARR_FOLLOWUP, FOLLOWUP_TRIGGER).
• Implemented tag_only path in RemovalHandler:
  • Apply handoff tag to matching torrent.
  • If deferred_arr_followup: true, detect whether the download hash is gone from qBittorrent.
  • Trigger ARR queue removal/blocklist follow-up once external removal is detected.
• Added config/docs updates in config/config_example.yaml and README.md.

Tests

• Added new tests for:
  • tag-only handoff waiting behavior
  • deferred follow-up trigger after external removal
  • safe skip when tag handoff is unsupported
  • job defaults + job-level override parsing for new fields
  • env-loading for new job-default keys
• Full suite run locally:
  • python3 -m pytest -q

Related

• Closes Feature: tag-only handoff mode with deferred ARR follow-up (single cleanup owner) #335

[ManiMatter]

@tomerh2001 Hi - I am not sure how this is from what the "Obsolete_Tag" already does.
https://github.com/ManiMatter/decluttarr#private_tracker_handling--public_tracker_handling

Could you please explain?

[ManiMatter]

@lolimmlost : would you be clear what the added benefit is of this compared to what we already have? If not, I would suggest to close this PR in absence of feedback from @tomerh2001

[lolimmlost]

Reviewed the diff. The concept has merit but there are a few issues that would need to be addressed before this could move forward:

1. Unrelated CI/CD changes -- The workflow modifications (Docker Hub push, permissions, branch patterns, setup-python bump, tag normalization) should be split into a separate PR.

2. Tracker protection bypass -- _resolve_effective_handling_method returns "tag_only" unconditionally, ignoring the tracker handling method. A private tracker torrent with private_tracker_handling: skip would still get tagged and potentially removed via deferred follow-up.

3. Deferred follow-up timing -- The download is added to arr.tracker.deleted even when still present in the client (the "waiting" case). If that list persists across cycles, the deferred follow-up can never trigger on a later cycle because the download gets skipped at the top of the loop.

4. Premature abstraction -- followup_trigger only supports one value (on_download_removed). A config option with a single valid value adds complexity without benefit; hardcode it until a second trigger type actually exists.

To answer @ManiMatter's question: the key difference from Obsolete_Tag is that tag_only overrides tracker handling as an action mode (not a tracker handling method) and adds deferred ARR follow-up. Whether that distinction justifies the added surface area depends on how many users actually need the two-phase handoff workflow.

[ManiMatter]

I struggle - tbh - in explaining this feature, and thus see added complexity with limited benefit. I suggest we go with your judgement, @lolimmlost. Concretely, I propose: If we hear any loud voices asking for this in the next 2 months, and @tomerh2001 addresses your feedback, we add it, else we close the PR. Sounds ok?

[lolimmlost]

Sounds good. 2 months, no loud voices, no feedback from tomerh2001 — we close it.

[lolimmlost]

Closing this out. The added complexity here was hard to justify against what the existing tag/tracker handling already provides, and the feedback needed to move it forward never came. No objection to revisiting if there's a clear use case the current behavior can't handle — happy to reopen. Thanks for the work that went into it.