feat(fsops): skip an existing hardlink target the exec tier can prove is the same file

Description

The remote HardlinkTree refused every target that already existed, because sftp attrs carry no inode and it could not tell its own earlier link from a stranger's file. On the exec tier the backend can run stat on both sides, so a target that is already a link to its source is now skipped the way the local backend skips it. The sftp tier is unchanged.

Decisions, from the grill on the ticket:

• Link first, compare on failure. The identity stats run only after Link has failed and an sftp lstat has shown the target exists, so the happy path keeps its one round trip and the diff stays inside the existing failure branch. One stat pair per collision; BatchStater (#2971) is the named upgrade if a season-pack retry is ever measured.
• Same file means fsops.SameFile between the target read unfollowed and the source read either way. The target is never followed, so a symlink planted there reports its own inode and never passes. The source is matched both ways because link(2) follows a symlinked source on macOS and not on Linux, so the link an earlier run made carries either identity depending on the host; one stat over both paths also reports each file's type, and only a symlinked source pays a second, followed stat. The local backend got the same two-way match, which it had lacked. Only a cancelled job or a lost connection passes through as the plan's error. Every other stat failure — the sftp tier, a source that vanished after the plan was built — reads as "not the source" and refuses with ErrTargetExists, because any other error would reach link mode's generic create-error path and, with the regular-mode fallback on, add the torrent in regular mode into the matched torrent's path, which is what #2942 prevents.
• A skipped target is counted in SkippedExists and never recorded in Files, matching the local contract, so a later failure in the same plan cannot roll back a link another run owns (discussion #2282). That contract is now stated on HardlinkTree in the Backend interface for every implementation, and the local backend was brought in line with it: link(2) does not follow a symlinked source on Linux (it does on macOS), so targetSatisfiesPlan now matches the source read either way instead of refusing the link an earlier run made.
• The reuse count rides the existing cross-seed created link tree log line as skippedExists, which covers the local backend too. The cross-seed result message is unchanged: linkedFiles is the plan size, so files: N/N stays accurate for an all-skipped plan.

This also fixes a symptom hit during the #3238 field test: a link tree left on disk without its torrent made cross-seed unable to recreate that torrent, because its own tree occupied the target it would build.

Closes #3237.

Breaking change

No breaking change.

Behaviour change

On a remote instance where qui has the exec tier, a cross-seed whose link target already holds qui's own link to the source now completes instead of failing with hardlink_error. A target holding any other file still fails, with no regular-mode fallback. The sftp tier behaves exactly as before.

How has this been tested?

Red-green at each seam, all five new tests run on the exec tier (newExecBackend skips off Linux, so they ran in a golang:1.27 container here and run in CI):

• TestHardlinkTree_ExecTierSkipsOwnLink: a pre-existing link to the source is skipped, counted, not recorded, and both targets end up linking their source.
• TestHardlinkTree_ExecTierStrangerStillRefuses: a different file at the target still answers ErrTargetExists, the link made before it is rolled back, the stranger's file is untouched.
• TestHardlinkTree_ExecTierSymlinkAtTargetRefuses: a symlink to the source at the target is refused.
• TestHardlinkTree_ExecTierSkippedLinkSurvivesLaterFailure: a skipped link is still in place after a later file in the same plan fails.
• TestHardlinkTree_ExecTierReusesWholeTree: the same plan applied twice reports Created=0 SkippedExists=2, and removing that result is a no-op.
• TestHardlinkTree_ExecTierSymlinkedSourceReuses: a plan whose source is a symlink is recognised on a re-run, because both sides are read unfollowed the way link(2) made the link.
• TestTargetIsSource_JobStoppedDuringStatIsAnError: the connection is opened and probed, the fake then hangs every command, and a job stopped while the stat runs surfaces as the context's error, not as ErrTargetExists.
• TestHardlinkTree_ExecTierMissingSourceStillRefuses: a source removed after the plan was built, with an old link at the target, still answers ErrTargetExists rather than an error link mode would turn into a regular add.
• TestHardlinkTree_StaleStoredTierStillReusesOnExecHost: a row that still says sftp against a host that answers exec reuses the link on the first try, because the live connection decides the tier.
• TestHardlinkTree_LstatFailureAfterLinkIsReported: when the lstat after a failed Link fails for a reason other than an absent target, that reason is the error, not the Link failure. Skips as root, so it runs on macOS and not in the container.
• TestTargetSatisfiesPlan (local backend) gains two rows: a symlink planted at the target still refuses, and the link an earlier run made from a symlinked source reads as done. Both pass on macOS and Linux, which answer link(2) on a symlink differently.

TestHardlinkTree_ExistingTargetFailsAndRollsBack keeps its assertions and its comment, but its fake now refuses exec: the pool reads the tier from a probe of the live connection, and every test fake is ExecGNU, so before this change the test only passed because HardlinkTree never asked for identity. It now exercises the sftp tier it names, on Linux and macOS both.

Field test, exec tier (passed)

Run on the smoke instance with the pr-3322 image (/api/version reports it) against the same seedbox as the #3238 field test, on the exec tier (identity=true). Paths, release names and infohashes are masked per the repo rule.

Fresh build first: a cross-seed search found a match on a second tracker for a single-copy release, and the apply answered:

status: added_hardlink   (1s)   save_path: <base>/<tracker>/<release>--<shorthash>
progress=1  amount_left=0  downloaded=0

Then the reuse case this PR adds: the new torrent was removed from the client with its files kept, so the link tree stayed on disk with no torrent, and the same cross-seed was applied again once the removal was visible:

remove (keep files)     16:49:57Z
re-apply                16:50:57Z  ->  status: added_hardlink  (2s)
same save_path, progress=1, downloaded=0, seeding again at 16:50:59Z

On pr-3238 the same setup answered hardlink_error: target already exists (recorded in the #3238 field test). The torrent was off its tracker for 62 seconds.

Documentation

No change in this PR. The hardlink-mode page's sentence that a remote instance cannot compare file identity becomes capability wording once the SSH setup screen exists; until then AGENTS.md sends a docs change that describes only remote instances to #3330, where it is listed as an item for this PR.

Performance

No change on the happy path: Link succeeds and nothing new runs. On a collision the remote backend now pays one exec session (a single stat over both paths) on the exec tier before deciding, where it previously refused after the sftp lstat; the sftp tier pays one pool.Exec call per collision that answers ErrNoExec without opening a session, because the live connection decides the tier (the stored row lags a key that just gained a shell, and would refuse the first reuse after it). A collision is rare and ends the plan either way except in the reuse case this PR adds, where the cost buys a successful cross-seed instead of a failure.

The one shape where the per-file cost compounds is a retry that collides on every file: a tree already on disk for a 100-file season pack costs, per file, a failed Link, an sftp lstat and one exec session, so on a host 100 ms away roughly 300 round trips and half a minute for an add that creates nothing. Before this PR the same retry failed on its first file. That shape is named in a ponytail: comment with BatchStater (#2971) as the upgrade, which could answer every identity in two finds before the first Link, and is left unmeasured until someone has that shape to measure. No benchmark taken.

Checklist

• My PR title follows the Conventional Commits format (it becomes the squashed commit message)
• If this changes the database schema, I have added migrations for both SQLite and PostgreSQL
• I completed the mandatory performance checks and recorded the outcome in Performance

AI disclosure

Yes. Claude (Fable 5.1, via Claude Code) wrote the implementation and tests from the decision ledger on #3237, which came out of a grill with me; I reviewed every line and the container and local test runs.