Add pooled partial cross-seed completion automation for hardlink/reflink mode

[Audionut]

Summary

When cross-seeding in hardlink/reflink mode, qui already knows when a torrent is a valid partial match: enough files can be reused, the remaining differences are acceptable under the existing size tolerance and safety checks, and only a subset of files still need to be acquired.

At that point, qui should be able to automate completion of the missing files across the entire related cross-seed set, instead of leaving each partial torrent isolated and requiring manual start/recheck handling.

This issue proposes a new user-facing automation mode that:

• allows eligible partial hardlink/reflink cross-seeds to enter a started/downloading state,
• groups related cross-seeds into a shared pool,
• chooses the best torrent in that pool to download each missing file,
• hardlinks/reflinks completed missing files into the other related cross-seeds that need them,
• triggers rechecks on those other cross-seeds,
• and starts them automatically once they reach 100%.

This should minimize duplicate physical downloads and turn partial reuse into a coordinated completion workflow.

Related: #1589

Problem

Today, when multiple cross-seeds are all related to the same original source content, partial reuse can leave several torrents in a state where:

• each torrent already reuses most of the data,
• each torrent is missing one or more additional files,
• several torrents may need the same missing file,
• and the user must manually decide which torrent to start, wait for it to complete, then rely on manual or ad hoc follow-up behavior for the others.

That misses a large automation opportunity.

If four related cross-seeds all need the same missing file, the ideal outcome is:

• one torrent downloads the real bytes,
• the other three get those bytes via hardlink/reflink,
• all related torrents are rechecked,
• all become complete without downloading duplicate copies.

More generally, if one cross-seed adds some missing files and another cross-seed adds even more, qui should continue coordinating the pool until all possible shared files have been propagated and all eligible torrents have been completed.

Proposed feature

Add a user-facing option for hardlink/reflink mode that enables automated pooled completion for partial matches.

Suggested behavior:

1. When a cross-seed candidate passes the existing partial-reuse safety checks, qui may allow it to be added in a started/downloading state instead of always leaving the user to handle it manually.
2. qui groups all related cross-seeds into a pool based on the original source content that triggered the cross-seed search.
3. qui tracks which files are:
   • already present,
   • missing,
   • being downloaded by one torrent in the pool,
   • or available to be linked/cloned into other torrents in the pool.
4. Before auto-starting a partial torrent, qui evaluates the pool and chooses the best torrent to acquire the missing files.
5. Once a missing file completes in one torrent, qui hardlinks/reflinks that file into every other eligible torrent in the same pool that needs it.
6. qui triggers rechecks on those dependent torrents.
7. Torrents that become complete are automatically started or resumed when they reach 100%.
8. If later torrents in the same pool contain additional missing files not yet acquired, the process repeats until the pool is fully resolved or no further safe automation is possible.

Key idea

qui should treat related partial cross-seeds as a coordinated data-sharing pool, not as independent torrents that happen to overlap.

The system should aim to ensure that each distinct missing file is physically downloaded only once whenever that is possible under the existing matching and safety rules.

User-facing option

Add a setting for cross-seed automation, conceptually similar to:

Automatically complete eligible partial hardlink/reflink cross-seeds

Expected semantics:

• only applies when hardlink or reflink mode is enabled,
• only applies when the torrent already passed the existing reuse acceptance rules,
• only applies when qui can safely coordinate the remaining files,
• allows qui to start one or more selected pool members automatically,
• and allows qui to finish the rest of the pool through link/clone propagation plus rechecks.

This should be opt-in.

Pool model

A pool should represent cross-seeds that are all ultimately related to the same original source content.

At minimum, the pool likely needs to track:

• the source torrent that triggered the search or completion workflow,
• all cross-seeds derived from that source,
• their hashes and current states,
• the files each torrent already has,
• the files each torrent is missing,
• which missing files overlap across torrents,
• which torrent is currently designated to acquire each missing file,
• and whether a completed file has already been propagated to dependent torrents.

The grouping needs to survive beyond the initial add so that later completions can continue benefiting the earlier pool members.

Selection strategy

Before starting a partial torrent, qui should ideally determine which pool member is the best downloader for the remaining missing files.

That decision could consider:

• which torrent covers the largest number of currently missing shared files,
• which torrent would unlock the most other pool members,
• which torrent minimizes total duplicate download volume,
• and whether one torrent is effectively a superset of another.

The earlier file comparison step already has most of the information needed to estimate this. It would be better to make the decision there rather than after several partial torrents have already been added without coordination.

Completion workflow

A high-level workflow could be:

1. Build or update the pool when cross-seeds are added.
2. Compute the file overlap graph for related torrents.
3. Select the best torrent(s) to auto-start for missing-file acquisition.
4. Wait for file completion events.
5. For each newly completed file, propagate it via hardlink/reflink into other eligible pool members.
6. Recheck affected torrents.
7. Auto-start/resume any torrents that now reach 100%.
8. Re-evaluate the pool for remaining missing files and repeat if needed.

Safety constraints

This automation should still respect the existing acceptance rules.

It should not bypass:

• size mismatch tolerance,
• piece-boundary safety checks,
• any rules that currently reject unsafe partial reuse,
• or any constraints on when hardlinking/reflinking is valid.

This feature is about automating the completion of already-accepted partial matches, not relaxing the safety model.

Why this belongs with #1589

Issue #1589 fixes a lower-level prerequisite: preserving the intended managed destination root across hardlink/reflink fallback and reuse chains.

This issue builds on that. A pooled completion workflow only works reliably if each incoming torrent keeps its own intended managed destination root instead of collapsing into another related torrent's save path when modes change.

In short:

• Preserve tracker-isolated destination roots across partial hardlink/reflink fallback and reuse chains #1589 is about correct destination-root ownership
• this issue is about coordinated lifecycle automation across related partial cross-seeds

Expected behavior

With this feature enabled:

• qui may automatically start the best eligible partial torrent in a related pool,
• missing files downloaded by that torrent are reused across the other eligible pool members,
• duplicate physical downloads are minimized,
• dependent torrents are rechecked automatically,
• and related cross-seeds become complete and startable with minimal manual intervention.

Acceptance criteria

• A new opt-in user-facing setting exists for pooled partial completion automation in hardlink/reflink mode.
• Related cross-seeds are grouped into a persistent pool keyed to shared source content.
• qui can identify overlapping missing files across pool members.
• qui can choose a preferred torrent to acquire missing files automatically.
• When a missing file completes in one torrent, qui can propagate it to other eligible pool members via hardlink/reflink.
• qui rechecks dependent torrents after propagation.
• qui auto-starts or resumes dependent torrents once they become complete.
• The process can repeat when later pool members contain additional files not yet acquired.
• The automation respects all existing size and safety checks.
• The workflow preserves each torrent's intended managed destination root as described in Preserve tracker-isolated destination roots across partial hardlink/reflink fallback and reuse chains #1589.

[Audionut]

Additional consideration for #1590:

For disc-style content, especially Blu-ray structures, the initial partial-match size tolerance can be a useful admission check, but it is not always a reliable predictor of the final qBittorrent recheck result.

A torrent might pass the pre-add tolerance threshold and be accepted into qui, but after injection and recheck it can land at a much lower completion percentage than expected because large files with similar sizes still differ materially on disk.

Example:

• pre-add tolerance allows a torrent that appears to be ~95% reusable,
• but after qBittorrent performs the real verification, the torrent may only recheck to something much lower,
• because large files such as m2ts files are not actually close enough at the byte level even though the earlier matching logic allowed the add.

That suggests the pooled automation in this issue should include a second safety gate based on the post-recheck result, not just the pre-add matching result.

Suggested addition:

Add another user-facing option for pooled automation, based on the actual missing data after recheck.

Conceptually:

Maximum missing data after recheck for pooled automation

Why this should be based on missing bytes, not only percentage:

• percentage can be misleading on very large disc torrents,
• a low recheck percentage delta may still represent a very large amount of actual data,
• and the real automation question is whether the remaining missing bytes are still reasonable to acquire and coordinate across the pool.

Suggested behavior:

1. Let the torrent pass the existing pre-add checks and be added.
2. Let qBittorrent perform the real recheck.
3. Measure the actual missing data after recheck.
4. If the missing data is within the configured automation threshold, continue pooled automation.
5. If it exceeds the threshold, stop automated pooled handling for that torrent and leave it for manual handling.

This is especially important for the hardlink vs reflink distinction:

• In hardlink mode, if the recheck reveals that a reused file is actually too divergent, automation would need to detach that hardlink before allowing that torrent to maintain its own unique copy of the problematic file.
• In reflink mode, this is much more workable because the filesystem can preserve shared extents while allowing the differing regions to become unique as writes occur, so only the divergent parts need unique storage.

So a practical interpretation may be:

• hardlink pooled automation should become more conservative when post-recheck divergence is high,
• reflink pooled automation can safely tolerate more post-recheck divergence because it can still preserve most of the shared physical storage benefits.

I think this belongs in the overall design of #1590, because the automation should not assume that passing the initial partial-match checks is sufficient. The actual qBittorrent recheck result should be treated as a second-stage validation before qui commits to automated completion behavior.

[hugolalouve]

Hit this exact scenario today: cross-seed on a tracker matched a torrent with extra files (Sample/, .nfo, .srr) not present in the source. Qui injected with fileCount=1, only the .mkv was hardlinked, and the torrent got stuck in Error with no way for qBittorrent to download the missing pieces since the files/directories didn't exist on disk. Had to manually touch the missing files to unblock it.

Looking forward to this being solved properly!

EDIT: Just realized my problem was coming from a permission issue, nevermind me.