fix(update): retry post-install smoke check and surface verification failure

The smoke check ran once, immediately after the package-manager upgrade.
Homebrew can report success moments before its opt launcher symlink is
repointed at the new keg, so the probe exercised the old binary, reported
the old version, and recorded a false VERIFICATION_FAILED — leaving the
footer stuck on the stale update notice while the screen said "Updated
successfully!".

Retry the smoke check up to 3 times, 1s apart, off the event loop
(asyncio.to_thread) so the probe can no longer block the shell either.
When verification genuinely fails after all attempts, print the failure
where the install success was shown so the on-screen outcome matches the
recorded status.

Author: elkaix

CHANGELOG.md

@@ -15,6 +15,8 @@ GitHub Releases page; `0.8.0` is the new starting line.
 
 ## Unreleased
 
+- Retry the post-update smoke check briefly before recording `VERIFICATION_FAILED`, absorbing the Homebrew launcher-relink race that falsely failed successful upgrades, and print the verification failure on screen instead of leaving "Updated successfully!" as the last word when verification genuinely fails.
+
 ## 0.62.0 (2026-07-22)
 
 - Treat the repository-root `.agents/` directory as local agent configuration and keep it out of version control.

src/pythinker_code/ui/shell/update_orchestrator.py

@@ -1,5 +1,6 @@
 from __future__ import annotations
 
+import asyncio
 import contextlib
 import json
 import os
@@ -408,7 +409,7 @@ async def run_update_job(
                 append_update_log(message)
                 _write_last_success(job_id=job_id, message=message)
             else:
-                smoke_ok, smoke_message = run_post_install_smoke_check(
+                smoke_ok, smoke_message = await _run_smoke_check_with_retry(
                     target_version=_read_target_version()
                 )
                 append_update_log(smoke_message)
@@ -422,6 +423,13 @@ async def run_update_job(
                     final_state = _result_state(reported_result)
                     # Never promote a staged binary that can't even print --version.
                     _finalize_native_staging(promote=False)
+                    # The install step has already printed its own success line;
+                    # leaving the screen at "Updated successfully!" while the
+                    # recorded state is VERIFICATION_FAILED would misreport the
+                    # outcome (the footer keeps the update notice for the same
+                    # reason). Surface the failure where the success was shown.
+                    if print_output:
+                        console.print(f"[{_get_tui_tokens().warning}]{message}[/]")
 
         write_update_status(
             _new_status(
@@ -548,6 +556,35 @@ def _smoke_check_env() -> dict[str, str]:
     return env
 
 
+_SMOKE_CHECK_ATTEMPTS = 3
+_SMOKE_CHECK_RETRY_DELAY_SECONDS = 1.0
+
+
+async def _run_smoke_check_with_retry(target_version: str | None) -> tuple[bool, str]:
+    """Run the post-install smoke check, retrying transient failures.
+
+    Package managers can report success moments before the launcher they manage
+    is repointed at the new install (observed with Homebrew's ``opt`` symlink):
+    an immediate probe then exercises the OLD binary, reports the old version,
+    and records a false ``VERIFICATION_FAILED``. A short retry window absorbs
+    that race; a real bad install still fails every attempt. The subprocess
+    probe runs off the event loop so a slow/hung binary cannot stall the shell.
+    """
+    smoke_ok, smoke_message = False, "Smoke check did not run."
+    for attempt in range(1, _SMOKE_CHECK_ATTEMPTS + 1):
+        smoke_ok, smoke_message = await asyncio.to_thread(
+            run_post_install_smoke_check, target_version=target_version
+        )
+        if smoke_ok or attempt == _SMOKE_CHECK_ATTEMPTS:
+            break
+        append_update_log(
+            f"Smoke check attempt {attempt}/{_SMOKE_CHECK_ATTEMPTS} failed "
+            f"({smoke_message}); retrying in {_SMOKE_CHECK_RETRY_DELAY_SECONDS:g}s..."
+        )
+        await asyncio.sleep(_SMOKE_CHECK_RETRY_DELAY_SECONDS)
+    return smoke_ok, smoke_message
+
+
 def run_post_install_smoke_check(target_version: str | None = None) -> tuple[bool, str]:
     command = _smoke_check_command()
     try:

tests/ui_and_conv/test_update_orchestrator.py

@@ -173,17 +173,23 @@ async def fake_do_update(
         return update.UpdateResult.UPDATED
 
     monkeypatch.setattr(update, "do_update", fake_do_update)
-    monkeypatch.setattr(
-        orchestrator,
-        "run_post_install_smoke_check",
-        lambda **_kw: (False, "Smoke check failed: broken"),
-    )
+    monkeypatch.setattr(orchestrator, "_SMOKE_CHECK_RETRY_DELAY_SECONDS", 0.0)
+    attempts = 0
+
+    def fake_smoke(**_kw):
+        nonlocal attempts
+        attempts += 1
+        return (False, "Smoke check failed: broken")
+
+    monkeypatch.setattr(orchestrator, "run_post_install_smoke_check", fake_smoke)
 
     result = await orchestrator.run_update_job(
         print_output=False, intent=update.UpdateIntent.INSTALL, source="test"
     )
 
     assert result is update.UpdateResult.VERIFICATION_FAILED
+    # A hard failure is retried before being reported — every attempt failed.
+    assert attempts == orchestrator._SMOKE_CHECK_ATTEMPTS
     status = orchestrator.read_update_status()
     assert status is not None
     assert status.state is orchestrator.UpdateJobState.FAILED
@@ -192,6 +198,44 @@ async def fake_do_update(
     assert not orchestrator.UPDATE_LAST_SUCCESS_FILE.exists()
 
 
+@pytest.mark.asyncio
+async def test_update_job_smoke_check_retry_absorbs_launcher_relink_race(monkeypatch, tmp_path):
+    """A transiently stale launcher (e.g. brew's opt link mid-relink) must not
+    record VERIFICATION_FAILED when a later attempt passes."""
+    _isolate_update_files(monkeypatch, tmp_path)
+
+    async def fake_do_update(
+        *, print_output: bool, intent: update.UpdateIntent, output_callback=None
+    ):
+        return update.UpdateResult.UPDATED
+
+    monkeypatch.setattr(update, "do_update", fake_do_update)
+    monkeypatch.setattr(orchestrator, "_SMOKE_CHECK_RETRY_DELAY_SECONDS", 0.0)
+    attempts = 0
+
+    def fake_smoke(**_kw):
+        nonlocal attempts
+        attempts += 1
+        if attempts == 1:
+            return (False, "Smoke check reported 0.60.0, expected 0.62.0")
+        return (True, "Smoke check passed: pythinker, version 0.62.0")
+
+    monkeypatch.setattr(orchestrator, "run_post_install_smoke_check", fake_smoke)
+
+    result = await orchestrator.run_update_job(
+        print_output=False, intent=update.UpdateIntent.INSTALL, source="test"
+    )
+
+    assert result is update.UpdateResult.UPDATED
+    assert attempts == 2
+    status = orchestrator.read_update_status()
+    assert status is not None
+    assert status.state is orchestrator.UpdateJobState.UPDATED
+    assert orchestrator.UPDATE_LAST_SUCCESS_FILE.exists()
+    log = "\n".join(orchestrator.read_update_log_tail())
+    assert "retrying" in log
+
+
 @pytest.mark.asyncio
 async def test_run_update_prompt_routes_check_through_runner(monkeypatch):
     calls: list[update.UpdateIntent] = []