fix(update): retry the Windows self-update in copy link mode after a hardlink error (#786)

[padak]

What

On Windows, the self-update keeps the default uv link mode (hardlink). If the install fails and the uv output contains failed to hardlink file, the background helper runs the same install once more with --link-mode copy. The log pending_update.log contains the output of both attempts.

The recovery command that kbagent prints after a failure also includes --link-mode copy. If the user set UV_LINK_MODE, kbagent adds no retry and no flag. POSIX command lines do not change.

Why

In #786, the background self-update failed with uv os error 396 (ERROR_CLOUD_FILE_INCOMPATIBLE_HARDLINKS). The uv cache or the tool directory was on a cloud-synced volume (OneDrive Files-On-Demand). That volume cannot hardlink between the two paths. uv tool install --force --reinstall removes the old tool venv before it creates the new one. When the install failed, kbagent was gone. The printed recovery command failed in the same way. The reporter confirmed that the same command works with UV_LINK_MODE=copy.

Copy mode is slower than hardlinks and uses more disk space. With copy mode on every update, the update is slower for every Windows user. Only users with a cloud-synced setup need copy mode, so the retry runs only after a failure.

The match is case-sensitive. uv prints warning: Failed to hardlink files; falling back to full copy when its own fallback works. That warning must not start a retry. The matched text comes from the error line, where it is lowercase: Caused by: failed to hardlink file from ... (os error 396).

Testing

• make check passes: lint, format, ty, version gates, command sync and the full test suite.
• tests/test_update_runner.py: the helper script contains the retry only when the request has a retry command. The retry comes after the first attempt and before the log write.
• On the Windows CI runner, three new tests run the real helper script. The fake installers write to stderr, as uv does.
  • A hardlink error starts the retry, and the helper records the exit code of the retry.
  • An unrelated error starts no retry.
  • The fallback warning together with an unrelated error starts no retry.
• tests/test_version_service.py:
  • The install commands have no --link-mode.
  • The retry command has --link-mode copy before the package spec.
  • A pip command, a POSIX host and a user-set UV_LINK_MODE produce no retry command.
  • The recovery commands contain --link-mode copy one time.
• Manual check: the generated helper ran in Windows PowerShell 5.1 (through WSL interop) with fake installers. All six cases gave the expected exit code and retry decision:
  • hardlink error, the retry passes
  • hardlink error, the retry fails
  • hardlink error, the retry prints nothing
  • unrelated error
  • fallback warning, the install passes
  • fallback warning with an unrelated error

Not in this PR

• Limit retries per session. After a background update fails, do not start it again on every later kbagent call in the same session. The reporter saw three identical failures, one after another.
• Atomic install. Keep the old tool venv until the new one installs successfully. Then any install failure leaves the old version working. Today, only the known hardlink failure has a recovery.
• Show the uv error to the user, not only in the log (see Auto-update permanently broken for installs made under the old keboola-agent-cli package name (executable conflict, cause swallowed) #771).
• Release notes. The update into the release with this fix still runs the old code. The old code has no retry. The release notes should tell affected users to set UV_LINK_MODE=copy before they update.

This PR uses Refs #786, not Fixes. The issue stays open for the atomic install.

Refs #786

---

[keboola-pr-reviewer-bot]

Verdict: auto_approve (risk 2/5) · profile keboola-mcp-server

duplicate-not-used

[devin-ai-integration]

✅ Devin Review: No Issues Found

Devin Review analyzed this PR and found no bugs or issues to report.

[soustruh]

Changed the approach: the install keeps the default uv link mode, and copy mode runs only as a retry after a hardlink error. Windows users whose disks can hardlink keep the faster update. The description is updated to match.