fix(update): show why a startup update failed, and how to move an install from the old package name

[soustruh]

Refs #771

What was wrong

• The package was renamed from keboola-agent-cli to keboola-cli in 0.63.0. Both packages install the kbagent executable. On an install made under the old name, uv treats the update as a new tool and stops with Executable already exists: kbagent.
• The startup update printed only Auto-update failed; continuing with current version. It dropped the uv error, so the user could not see the cause.
• On such an install, kbagent update and the upgrade_command of kbagent version --json run the same failing command.

What changed

• A failed startup update prints a Cause: line with the last line of the uv output, then Recover with: <command>, on stderr.
• README: a section on the old package name, with the two commands and how to check the install with uv tool list.
• gotchas.md: an entry for agents, tagged (since vNEXT, #771).
• kbagent update is unchanged. Its update FAILED: summary already ends with the last uv line.

Limits

• kbagent 0.59.x and older cannot get this fix, because the update code runs from the old install. Those users need the two commands from the README.
• The configuration folder keeps the name keboola-agent-cli on purpose. The move does not touch the configuration.

Tests

• tests/test_auto_update.py: the banner is checked line by line (failure line, Cause: with the last uv line, Recover with:), and no installer output means no Cause: line. A failed update carries the installer output.
• tests/test_version_service.py: summarize_install_failure.
• make check passes.

Update 2026-10-10

The banner no longer prints the two move commands. The startup update always runs uv tool install --force --reinstall, and --force takes the kbagent executable over from the old tool entry, so uv never stops with Executable already exists there. Checked with uv 0.12.15 in a throwaway tool directory. The banner shows the Cause: line and Recover with:. The README keeps the manual two-command move for installs that cannot update at all (0.59.x and older).

[keboola-pr-reviewer-bot]

Verdict: needs_human (risk 2/5) · profile _default

Safe, well-tested auto-update messaging fix, but it edits an agent-instruction file (gotchas.md), which policy bars from auto-approval.

Concerns:

• plugins/kbagent/skills/kbagent/references/gotchas.md: Agent-instruction file change: policy requires human review, cannot auto-approve.

[soustruh]

No blocking findings. Checked:

• Banner: _format_update_failure prints the last non-empty uv line as Cause:, then either the legacy advice or Recover with:. The installer output reaches it because run_install merges stderr into the captured output, and the banner is written to sys.stderr. A banner test captures stderr and fails if the Cause: line is missing or the output is empty.
• Legacy detection: APP_NAME != LEGACY_APP_NAME matches the dynamic name resolution in constants.py, so the advice appears only when the bridge wheel under the old name runs this code. The advice is withheld when there is no recovery command, so an uninstall is never shown without the install after it.
• Order: uninstall comes before install. Both the service test and the banner test assert this by string index, so a swapped order fails them.
• Docs and claim: README and gotchas.md match the code and carry vNEXT. The claim about kbagent update is correct: _update_kbagent puts run.output in the message and _summarize_failure_tail takes its last line. tests/test_auto_update.py and tests/test_version_service.py pass locally (179 passed).

One observation, not a finding: on a legacy install the advice replaces Recover with: for every failed install, not only for the Executable already exists conflict. A plain network failure on such an install is also told to uninstall first. The Cause: line is shown, so the user can tell the difference.

[keboola-pr-reviewer-bot]

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

Contained bug-fix to the auto-update failure banner, fully covered by new regression tests.

[zajca]

Actionable findings from the automated review.

Dismissing prior approval — a new commit was pushed and this review was for an earlier SHA. Run @keboola-pr-reviewer-bot review to get a fresh verdict.

[keboola-pr-reviewer-bot]

New commit on 08b894d — dismissed 1 stale bot approval. Comment @keboola-pr-reviewer-bot review when you want a fresh review.