From 96a4c3eb5dbe6f90cbeb3b68736ea4dde4c5a293 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:30:35 +0200
Subject: [PATCH 1/7] fix(update): defer the Windows self-update out of the
 running environment (#528)

`uv tool install` recreates a tool environment by removing it and then
building a fresh venv at the same path (`uv-tool/src/lib.rs`:
create_environment -> "Remove any existing environment" -> create_venv).
It is not atomic and has no rollback.

On POSIX that is harmless -- unlinking a file another process holds open
leaves that process's inode intact. On Windows uv's `kbagent.exe`
trampoline loads the venv interpreter in-process, so those files are
locked: the removal deletes what it can, hits a locked file, and aborts,
leaving a gutted venv. That is the reported failure -- `rich` present but
`rich/_windows.py` gone, `typer` present but `typer/rich_utils.py` gone.
Upstream: astral-sh/uv#11930.

The v0.76.2 fix reordered discovery ahead of mutation, which was a real
ordering bug, but the installer still ran from inside the environment it
replaces -- so the corruption survived it and reproduced on 0.76.2 ->
0.76.3.

Windows now hands the reinstall to a detached PowerShell helper that
waits for every kbagent process to exit and only then installs; the
outcome is reported once by the next launch, with a recovery command on
failure. When no helper can be spawned the user gets the exact command --
never a fallback to the unsafe inline install. POSIX keeps the inline
install plus re-exec unchanged.

Also removes a second, independent corruption vector: both paths ran the
installer through `subprocess.run(timeout=...)`, which kills the child on
expiry -- on Windows a hard TerminateProcess of uv mid-write, producing
the same half-deleted environment from our own code. The deadline now
bounds only how long kbagent waits.

`KBAGENT_DEFER_UPDATE=1|0` overrides the platform default.
---
 ...528-deferred-windows-self-update-design.md | 184 +++++++
 .../skills/kbagent/references/gotchas.md      |  33 ++
 src/keboola_agent_cli/auto_update.py          | 130 ++++-
 src/keboola_agent_cli/commands/version.py     |  13 +
 src/keboola_agent_cli/constants.py            |  34 ++
 .../services/version_service.py               |  98 +++-
 src/keboola_agent_cli/update_runner.py        | 508 ++++++++++++++++++
 tests/test_auto_update.py                     | 240 +++++++--
 tests/test_update_runner.py                   | 357 ++++++++++++
 tests/test_version_service.py                 | 103 +++-
 10 files changed, 1619 insertions(+), 81 deletions(-)
 create mode 100644 docs/superpowers/specs/2026-07-29-issue-528-deferred-windows-self-update-design.md
 create mode 100644 src/keboola_agent_cli/update_runner.py
 create mode 100644 tests/test_update_runner.py

diff --git a/docs/superpowers/specs/2026-07-29-issue-528-deferred-windows-self-update-design.md b/docs/superpowers/specs/2026-07-29-issue-528-deferred-windows-self-update-design.md
new file mode 100644
index 00000000..61716cd3
--- /dev/null
+++ b/docs/superpowers/specs/2026-07-29-issue-528-deferred-windows-self-update-design.md
@@ -0,0 +1,184 @@
+# Design: defer the Windows self-update out of the running environment
+
+**Issue:** [#528](https://github.com/keboola/cli/issues/528)
+**Supersedes:** `2026-07-23-issue-528-safe-self-update-design.md` (shipped in v0.76.2)
+**Status:** Implemented
+**Target:** `kbagent update` and the startup auto-update hook
+
+## Why the v0.76.2 fix was not enough
+
+v0.76.2 moved every network call, probe, and command construction ahead of any
+mutation, updated the independent MCP environment first, and made the kbagent
+reinstall a terminal `uv tool install --force --reinstall` from an exact
+release artifact. That was a correct fix for a real ordering bug -- the missing
+`certifi/cacert.pem` in incident 2 -- and it did not fix the reported
+corruption. The reporter hit it again on v0.76.2 -> v0.76.3.
+
+The reason is that ordering was never the mechanism.
+
+`uv tool install` recreates a tool environment **in place**. From
+`crates/uv-tool/src/lib.rs`, `create_environment` removes any existing
+environment and then calls `create_venv` at the same path. There is no
+temporary build directory, no atomic swap, and no rollback.
+
+On POSIX this is safe by accident of the filesystem semantics: unlinking a file
+another process holds open leaves that process's inode intact, so a running
+kbagent survives having its own venv deleted and rebuilt underneath it. That is
+why nobody on macOS or Linux ever saw this.
+
+On Windows it cannot work. uv's `kbagent.exe` trampoline loads the tool venv's
+interpreter in-process, so those files are locked for as long as kbagent runs.
+The removal deletes every file it can, reaches a locked one, and aborts. What
+is left is not a mixture of old and new distributions -- it is a **partially
+deleted** venv, which is exactly what the reported symptoms describe: `rich`
+still present but `rich/_windows.py` gone, `typer` still present but
+`typer/rich_utils.py` gone. Upstream tracks the same class of failure as
+astral-sh/uv#11930 (`uv tool upgrade` of an in-use tool leaves the environment
+inconsistent and the receipt lying about it).
+
+Running the installer from inside the environment it replaces is therefore
+unsafe on Windows *by construction*, with any combination of uv flags.
+
+### The second, independent corruption vector
+
+Both update paths ran the installer through `subprocess.run(..., timeout=...)`,
+which **kills the child** when the deadline expires -- on Windows a
+`TerminateProcess`. Killing uv part-way through recreating a venv produces the
+same half-deleted environment a file lock does, from our own code, on every
+platform. The default deadline was 300s; a cold resolution of the `[server]`
+extra on a Windows machine with real-time AV scanning is not reliably under
+that.
+
+## Goals
+
+- Never run the installer from a process whose own environment is the target.
+- Never terminate an installer mid-transaction.
+- Never fall back to the unsafe path when the safe one is unavailable.
+- Keep the POSIX behaviour that demonstrably works today.
+- Report a deferred outcome exactly once, with recovery guidance on failure.
+- Be verifiable in CI on macOS/Linux, where the failure cannot be reproduced.
+
+## Non-goals
+
+- Making `uv tool install` atomic. That is uv's to own.
+- Updating while a long-lived kbagent (`serve`, `repl`) refuses to exit. The
+  helper declines and retries later; declining is always safe.
+- A persistent background update daemon.
+- Reworking the MCP environment, which is separate and never the one we run from.
+
+## Design
+
+### 1. `update_runner.run_install` -- bound the wait, not the installer
+
+A single execution helper for both entry points. Output goes to a log file
+rather than a pipe (a pipe whose reader is gone would block a child we intend
+to outlive), and on timeout it returns `STILL_RUNNING` **without killing**. The
+caller reports that the install continues in the background and deliberately
+offers no recovery command: a second installer aimed at an environment a live
+uv is rewriting is the corruption, not the cure.
+
+### 2. `update_runner.request_deferred_update` -- install after we are gone
+
+On Windows (`should_defer()`, overridable with `KBAGENT_DEFER_UPDATE`) the
+prepared install command is handed to a detached helper:
+
+1. Write a marker file first, so a helper that dies immediately still leaves
+   evidence a later run can report instead of a silent no-op.
+2. Spawn `powershell.exe -NoProfile -NonInteractive -WindowStyle Hidden
+   -Command <script>` with `DETACHED_PROCESS | CREATE_NEW_PROCESS_GROUP`,
+   `close_fds=True`, and all stdio at `DEVNULL`.
+3. The script waits twice -- `Wait-Process -Id <pid>` for the scheduling
+   process (which may not be named `kbagent`, e.g. `python -m
+   keboola_agent_cli`), then a `Get-Process -Name kbagent` loop for every other
+   kbagent holding the environment open -- and only then runs the installer,
+   recording `$LASTEXITCODE`.
+4. If kbagent is still running when the window closes, it installs **nothing**
+   and records that it gave up.
+
+Windows PowerShell 5.1 is an in-box OS component on every supported Windows
+10/11 edition and cannot be uninstalled, and `ExecutionPolicy` governs script
+*files*, not `-Command` strings, so no policy can block the helper. If no
+interpreter is found at all, scheduling fails and the caller prints the exact
+install command -- it never falls back to the in-place install.
+
+A single-flight guard (`is_update_pending`) stops several shells opened in a
+row from each spawning a helper and racing each other into the corruption.
+
+### 3. Report on the next launch
+
+The process that schedules an update exits before it runs, so it can never
+report it. `report_finished_deferred_update()` runs at the top of
+`maybe_auto_update`, **before** the skip gates -- the user is owed the outcome
+even on a run that will not update anything (a dev install, an opt-out,
+`kbagent version`). Success also prints the changelog the in-place path prints
+after its re-exec. The bookkeeping files are cleared, so a result is reported
+exactly once.
+
+Outcomes are deliberately distinguished:
+
+| Outcome | Meaning | Recovery offered |
+|---|---|---|
+| `SUCCEEDED` | installed | no |
+| `ABANDONED` | kbagent never exited; nothing installed | no -- nothing to recover |
+| `FAILED` | installer exited non-zero, or an unreadable result | yes |
+| `LOST` | helper never reported and the marker went stale | yes |
+
+An unparseable result counts as a failure: that is precisely when the user
+needs the recovery command, so it must not be optimistic.
+
+### 4. POSIX is untouched
+
+`should_defer()` is False there, so the inline install plus `os.execvpe`
+re-exec stays exactly as it is. `execve` genuinely replaces the process image,
+and unlinking open files is safe -- the majority path keeps its instant
+upgrade with no new failure mode.
+
+## Implementation map
+
+- `src/keboola_agent_cli/update_runner.py` (new) -- `run_install`, the deferred
+  scheduler, the waiter-script builders, and the marker/report lifecycle.
+  A new module rather than growth in `version_service.py`, which is already
+  past the 1000-LOC soft ceiling.
+- `src/keboola_agent_cli/constants.py` -- deferred-update filenames, wait and
+  poll windows, staleness horizon, `KBAGENT_DEFER_UPDATE`.
+- `src/keboola_agent_cli/auto_update.py` -- report a finished deferred update;
+  schedule instead of installing when deferring; truthful timeout banner.
+- `src/keboola_agent_cli/services/version_service.py` -- `_update_kbagent`
+  schedules on Windows, reports `deferred`, and never inline-installs there;
+  `_compose_update_summary` renders `(scheduled)` rather than `FAILED`.
+- `src/keboola_agent_cli/commands/version.py` -- surface the actionable stage
+  message in human mode.
+
+## Validation
+
+Unit-testable on POSIX CI, and covered:
+
+- `run_install` leaves a slow child alive (a real subprocess writing a sentinel
+  after the wait expires) -- the one behaviour that *is* directly observable
+  everywhere.
+- The waiter script's exact contract: PID wait, process-name loop, give-up
+  branch ordering, the quoted install argv, exit-code recording.
+- Scheduling: marker contents, detached spawn flags, single-flight, no-helper
+  refusal, spawn-failure cleanup.
+- Report lifecycle for every outcome, reported once.
+- `kbagent update` on the deferred platform never reaches `run_install`.
+- POSIX still installs inline and re-execs.
+
+Not reproducible in CI, and stated as such: the Windows file lock itself.
+Before release, on Windows 11 with `uv tool install "keboola-cli[server] @
+<previous release wheel>"`: run `kbagent update`, confirm it reports
+`(scheduled)` and that the next launch reports success; repeat through the
+startup hook; and confirm that with `kbagent serve` left running the update is
+reported as skipped with the environment intact.
+
+## Risks and follow-up
+
+- The helper is a detached PowerShell process. Enterprise EDR may flag or block
+  that; the failure mode is benign (scheduling fails, the user is told the
+  command) but it should be watched for in the field.
+- `Get-Process -Name kbagent` does not see a kbagent running as
+  `python -m keboola_agent_cli`. The PID wait covers the scheduling process;
+  another such process running concurrently is not covered.
+- The standalone PyInstaller distribution (Chocolatey / `cli-dist`) has no
+  `sys.frozen` guard anywhere in `src/`, so a frozen binary would still plan a
+  `uv tool install`. Out of scope here; filed separately.
diff --git a/plugins/kbagent/skills/kbagent/references/gotchas.md b/plugins/kbagent/skills/kbagent/references/gotchas.md
index 49e270d5..cb6f8347 100644
--- a/plugins/kbagent/skills/kbagent/references/gotchas.md
+++ b/plugins/kbagent/skills/kbagent/references/gotchas.md
@@ -2138,6 +2138,39 @@ transparent -- no user action is normally required.
 - Never crashes the CLI -- update failures leave the current invocation running
   and print a recovery command (since v0.76.2)
 
+### Windows updates are deferred, not immediate (since v0.76.4)
+
+`uv tool install` recreates a tool environment by **removing** it and then
+building a fresh venv at the same path. It is not atomic and has no rollback.
+On POSIX that is harmless; on Windows uv's `kbagent.exe` trampoline holds the
+venv's interpreter locked, so the removal deletes what it can, hits a locked
+file, and aborts -- leaving a **gutted** venv (`No module named
+'rich._windows'`, `cannot import name 'rich_utils' from 'typer'`). Upstream:
+astral-sh/uv#11930.
+
+So on Windows kbagent never installs into its own live environment:
+
+- Both `kbagent update` and the startup hook hand the reinstall to a detached
+  helper, which waits until **every** kbagent process has exited and installs
+  then. The current invocation continues on the old version.
+- Consequence: the new version is active on the **next** launch, not this one.
+  `kbagent update --json` marks this with `kbagent.deferred: true`; the summary
+  line reads `(scheduled)`, which is **not** a failure.
+- If a kbagent process (typically `kbagent serve` or `kbagent repl`) never
+  exits, the helper installs nothing and reports `skipped` -- also not a
+  failure; the environment is untouched and the next launch retries.
+- The outcome is printed by the next launch, including a copy-paste recovery
+  command when the install failed.
+- `KBAGENT_DEFER_UPDATE=1` / `=0` forces the deferred path on or off,
+  overriding the platform default.
+
+A slow install is never killed on any platform (also since v0.76.4): the
+timeout bounds only how long kbagent waits, because terminating uv mid-write
+produces the same half-deleted environment a file lock does. When that happens
+the banner says the install is *still running* and deliberately offers no
+recovery command -- starting a second installer against an environment a live
+uv is rewriting is the corruption itself.
+
 ## `lineage build` and sync layouts
 
 `lineage build` reads synced data from disk and supports both layouts produced by
diff --git a/src/keboola_agent_cli/auto_update.py b/src/keboola_agent_cli/auto_update.py
index 3255b176..1f8e719d 100644
--- a/src/keboola_agent_cli/auto_update.py
+++ b/src/keboola_agent_cli/auto_update.py
@@ -13,7 +13,6 @@
 import logging
 import os
 import shutil
-import subprocess
 import sys
 import time
 from importlib.metadata import distribution
@@ -48,6 +47,16 @@
     prepare_mcp_update_plan,
     resolve_kbagent_wheel_url,
 )
+from .update_runner import (
+    DeferredUpdateReport,
+    DeferredUpdateRequest,
+    DeferredUpdateStatus,
+    InstallStatus,
+    collect_finished_deferred_update,
+    request_deferred_update,
+    run_install,
+    should_defer,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -286,8 +295,9 @@ def _perform_update(
 
     Returns:
         :class:`UpdateOutcome`: ``SUCCESS`` on a clean install, ``TIMEOUT`` when
-        the install subprocess outran :func:`get_update_timeout` (a slow git+
-        build -- retried next run, not a real failure), ``FAILED`` otherwise.
+        the install outran :func:`get_update_timeout` -- it is still running and
+        will finish on its own, so the next launch picks it up -- and ``FAILED``
+        otherwise.
     """
     # ``command`` is supplied by the startup planner. Keep the fallback only
     # for direct legacy callers; it must never be used after another stage has
@@ -300,18 +310,15 @@ def _perform_update(
     if cmd is None:
         return UpdateOutcome.FAILED
 
-    try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=get_update_timeout(),
-        )
-        return UpdateOutcome.SUCCESS if result.returncode == 0 else UpdateOutcome.FAILED
-    except subprocess.TimeoutExpired:
+    # Deliberately does NOT kill the installer when the deadline passes -- see
+    # ``update_runner.run_install``. A terminated uv leaves the same
+    # half-removed venv a Windows file lock does (issue #528).
+    run = run_install(tuple(cmd), timeout=get_update_timeout())
+    if run.status is InstallStatus.SUCCEEDED:
+        return UpdateOutcome.SUCCESS
+    if run.status is InstallStatus.STILL_RUNNING:
         return UpdateOutcome.TIMEOUT
-    except OSError:
-        return UpdateOutcome.FAILED
+    return UpdateOutcome.FAILED
 
 
 def _re_exec() -> None:
@@ -484,6 +491,80 @@ def _apply_prepared_mcp_update(plan: McpUpdatePlan) -> None:
         )
 
 
+def report_finished_deferred_update() -> None:
+    """Print the outcome of a deferred update scheduled by an earlier run.
+
+    The deferred path (Windows) installs from a detached helper *after* this
+    process is gone, so the process that scheduled the update can never report
+    it. Whoever starts next does -- exactly once -- and on success also shows
+    the changelog the in-place path shows after its re-exec.
+    """
+    try:
+        report = collect_finished_deferred_update()
+    except Exception:
+        logger.debug("Could not collect the deferred-update result", exc_info=True)
+        return
+    if report is None:
+        return
+    sys.stderr.write(_format_deferred_report(report))
+
+
+def _format_deferred_report(report: DeferredUpdateReport) -> str:
+    """Render a finished deferred update as one stderr block.
+
+    An abandoned update is *not* a failure and must not read like one: nothing
+    was installed because another kbagent kept running, so the environment is
+    untouched and the next launch simply tries again.
+    """
+    if report.status is DeferredUpdateStatus.SUCCEEDED:
+        message = f"Updated kbagent to v{report.target_version}.\n"
+        whats_new = format_whats_new(report.from_version, __version__) or ""
+        return message + whats_new
+    if report.status is DeferredUpdateStatus.ABANDONED:
+        return (
+            f"Background update to v{report.target_version} was skipped: another kbagent "
+            "process kept running. It will be retried.\n"
+        )
+    recovery = f" Recover with: {report.recovery_command}" if report.recovery_command else ""
+    exit_note = f" (exit code {report.exit_code})" if report.exit_code is not None else ""
+    return (
+        f"Background update to v{report.target_version} did not complete{exit_note}. "
+        f"Log: {report.log_path}.{recovery}\n"
+    )
+
+
+def _schedule_deferred_update(plan: KbagentUpdatePlan) -> None:
+    """Hand the terminal reinstall to a detached helper instead of running it here.
+
+    On Windows an in-place ``uv tool install`` deletes the venv this process is
+    executing from and cannot finish, leaving it gutted (issue #528). The helper
+    waits until no kbagent is left and only then installs, so this process just
+    keeps going on the current version -- the update lands for the next launch.
+
+    When no helper can be spawned we say so and print the exact command. Falling
+    back to an in-place install here would reintroduce the corruption.
+    """
+    target = plan.latest_version or __version__
+    if plan.command is None:
+        return
+    request = DeferredUpdateRequest(
+        from_version=__version__,
+        target_version=target,
+        install_command=plan.command,
+        recovery_command=plan.recovery_command,
+    )
+    if request_deferred_update(request):
+        sys.stderr.write(
+            f"Updating kbagent v{__version__} -> v{target} in the background; "
+            "it applies once every kbagent process has exited.\n"
+        )
+        return
+    sys.stderr.write(
+        f"kbagent v{target} is available but cannot be installed safely while kbagent is "
+        f"running. Install it with: {plan.recovery_command}\n"
+    )
+
+
 def _prepare_auto_kbagent_plan(latest_version: str | None) -> KbagentUpdatePlan:
     """Adapt the shared plan to the startup comparison seam used by tests."""
     prepared = prepare_kbagent_update_plan(latest_version)
@@ -539,6 +620,12 @@ def maybe_auto_update() -> None:
             return
         _AUTO_UPDATE_RAN = True
 
+        # A deferred update scheduled by an earlier run installs after that run
+        # exits, so its outcome has to be reported by someone else. Do it before
+        # the skip gates: the user is owed the result -- especially a failure and
+        # its recovery command -- even on a run that will not update anything.
+        report_finished_deferred_update()
+
         # Wide gates (dev install / opt-out / update|version commands)
         # skip BOTH stages -- there is nothing reasonable to do.
         if _should_skip_all():
@@ -607,6 +694,14 @@ def maybe_auto_update() -> None:
             )
             return
 
+        # Where the reinstall runs is the whole fix for issue #528: an in-place
+        # `uv tool install` deletes the venv this process runs from, which
+        # Windows cannot survive. Defer there; keep the proven inline install +
+        # re-exec on POSIX, where replacing an open file is safe.
+        if should_defer():
+            _schedule_deferred_update(kbagent_plan)
+            return
+
         sys.stderr.write(f"Updating kbagent v{__version__} -> v{kbagent_plan.latest_version}...\n")
         outcome = _perform_update(
             kbagent_plan.latest_version or __version__, command=kbagent_plan.command
@@ -617,9 +712,12 @@ def maybe_auto_update() -> None:
             _re_exec()
             return
         if outcome is UpdateOutcome.TIMEOUT:
+            # The installer was NOT killed -- it is still working. Saying
+            # "recover with ..." here would invite the user to start a second
+            # installer against the same environment.
             sys.stderr.write(
-                f"Update timed out after {int(get_update_timeout())}s. Recover with: "
-                f"{kbagent_plan.recovery_command}\n"
+                f"Update still running after {int(get_update_timeout())}s; it continues in the "
+                "background and applies on the next launch.\n"
             )
         else:
             sys.stderr.write(
diff --git a/src/keboola_agent_cli/commands/version.py b/src/keboola_agent_cli/commands/version.py
index 6a85ca36..2c991a20 100644
--- a/src/keboola_agent_cli/commands/version.py
+++ b/src/keboola_agent_cli/commands/version.py
@@ -150,6 +150,13 @@ def update_command(
        the whole tool environment and preserves ``[server]`` extras. On a
        failure the result includes a copy/paste recovery command.
 
+    On Windows the kbagent stage is **scheduled, not run here** (issue #528).
+    ``uv tool install`` removes the tool environment before recreating it, so
+    running it from inside that environment deletes files the live process has
+    locked and aborts half-way. A detached helper waits until every kbagent has
+    exited and installs then; ``deferred: true`` marks that in JSON and the next
+    launch reports the outcome.
+
     JSON output reports both stages independently. Human mode prints a
     one-line summary such as
     ``kbagent v0.30.0 -> v0.30.1 | keboola-mcp-server v1.49.0 -> v1.59.1``.
@@ -171,6 +178,12 @@ def update_command(
             formatter.success(result["message"])
         else:
             formatter.console.print(result["message"])
+        # The summary line only says "(scheduled)". What the user has to *do*
+        # -- close other kbagent processes -- lives on the stage result, so
+        # print that too rather than leave the instruction in JSON only.
+        kbagent_stage = result.get("kbagent", {})
+        if kbagent_stage.get("deferred") is not None and not kbagent_stage.get("updated"):
+            formatter.console.print(kbagent_stage["message"])
 
 
 def _env_opted_into_prerelease() -> bool:
diff --git a/src/keboola_agent_cli/constants.py b/src/keboola_agent_cli/constants.py
index cc3e07d1..327ef517 100644
--- a/src/keboola_agent_cli/constants.py
+++ b/src/keboola_agent_cli/constants.py
@@ -317,6 +317,40 @@ def _resolve_app_name() -> str:
 UPDATE_TIMEOUT_SECONDS: int = 300
 ENV_UPDATE_TIMEOUT: str = "KBAGENT_UPDATE_TIMEOUT"
 
+# --- Deferred (out-of-process) self-update -- issue #528 ---
+#
+# `uv tool install` recreates a tool environment by REMOVING it and then
+# creating a fresh venv at the same path (`uv-tool/src/lib.rs`:
+# create_environment -> "Remove any existing environment" -> create_venv).
+# The removal is not atomic and has no rollback. On POSIX that is harmless --
+# unlinking a file another process holds open leaves that process's inode
+# intact. On Windows the running `kbagent.exe` trampoline keeps the tool
+# venv's interpreter DLL and extension modules locked, so the removal deletes
+# whatever it can and then aborts, leaving a GUTTED venv (upstream: astral-sh/
+# uv#11930). That is exactly the reported corruption -- `rich/_windows.py` and
+# `typer/rich_utils.py` missing from packages that otherwise still exist.
+#
+# The only safe sequencing is therefore to run the reinstall from a process
+# that does NOT live in the environment being replaced, once no kbagent
+# process is left holding it open.
+ENV_DEFER_UPDATE: str = "KBAGENT_DEFER_UPDATE"
+DEFERRED_UPDATE_MARKER_FILENAME: str = "pending_update.json"
+DEFERRED_UPDATE_EXIT_FILENAME: str = "pending_update.exit"
+DEFERRED_UPDATE_LOG_FILENAME: str = "pending_update.log"
+# Written by the helper into the exit file when kbagent never stopped running
+# within the wait window, so nothing was installed and nothing was mutated.
+DEFERRED_UPDATE_ABANDONED_MARKER: str = "abandoned"
+# Executable name the helper waits on. uv's Windows trampoline loads the venv
+# interpreter in-process, so the shim keeps the process named `kbagent`.
+DEFERRED_UPDATE_PROCESS_NAME: str = "kbagent"
+DEFERRED_UPDATE_POLL_SECONDS: int = 2
+# Give up (without installing anything) if a kbagent process is still alive
+# after this long -- e.g. a long-lived `kbagent serve` or `kbagent repl`.
+DEFERRED_UPDATE_MAX_WAIT_SECONDS: int = 900
+# A marker older than this whose helper never wrote an exit file is treated as
+# lost (helper killed, machine rebooted mid-wait) and reported once.
+DEFERRED_UPDATE_STALE_SECONDS: int = 86400
+
 # --- AI Service ---
 AI_SERVICE_TIMEOUT: httpx.Timeout = httpx.Timeout(connect=5.0, read=15.0, write=5.0, pool=5.0)
 
diff --git a/src/keboola_agent_cli/services/version_service.py b/src/keboola_agent_cli/services/version_service.py
index d6eb2c1e..09cf967f 100644
--- a/src/keboola_agent_cli/services/version_service.py
+++ b/src/keboola_agent_cli/services/version_service.py
@@ -33,6 +33,13 @@
     UPDATE_TIMEOUT_SECONDS,
     VERSION_CHECK_TIMEOUT,
 )
+from ..update_runner import (
+    DeferredUpdateRequest,
+    InstallStatus,
+    request_deferred_update,
+    run_install,
+    should_defer,
+)
 
 logger = logging.getLogger(__name__)
 
@@ -984,6 +991,12 @@ def _compose_update_summary(
                 f"kbagent v{kbagent_result.get('current_version')}"
                 f" -> v{kbagent_result.get('latest_version')}"
             )
+        elif kbagent_result.get("deferred"):
+            # Scheduled, not failed: the install runs once this process exits.
+            parts.append(
+                f"kbagent v{kbagent_result.get('current_version')}"
+                f" -> v{kbagent_result.get('latest_version')} (scheduled)"
+            )
         elif kbagent_result.get("up_to_date"):
             parts.append(f"kbagent v{kbagent_result.get('current_version')} (already up to date)")
         elif kbagent_result.get("current_version"):
@@ -1007,7 +1020,15 @@ def _compose_update_summary(
 
     @staticmethod
     def _update_kbagent(plan: KbagentUpdatePlan) -> dict[str, Any]:
-        """Apply a precomputed terminal self-reinstall without new probes."""
+        """Apply a precomputed terminal self-reinstall without new probes.
+
+        Where the reinstall runs is platform-dependent (issue #528). On Windows
+        an in-place ``uv tool install`` deletes the very environment this
+        process is executing from, cannot finish, and leaves it gutted -- so the
+        install is handed to a detached helper that waits for kbagent to exit.
+        POSIX keeps the inline install, which is safe because unlinking an open
+        file leaves the running process's inode intact.
+        """
         old_version = plan.current_version
         kbagent_latest = plan.latest_version
         up_to_date = plan.up_to_date
@@ -1036,57 +1057,86 @@ def _update_kbagent(plan: KbagentUpdatePlan) -> dict[str, Any]:
                 "recovery_command": plan.recovery_command,
             }
 
-        try:
-            result = subprocess.run(
-                list(plan.command),
-                capture_output=True,
-                text=True,
-                timeout=get_update_timeout(),
+        if should_defer():
+            scheduled = request_deferred_update(
+                DeferredUpdateRequest(
+                    from_version=old_version,
+                    target_version=kbagent_latest or old_version,
+                    install_command=plan.command,
+                    recovery_command=plan.recovery_command,
+                )
             )
-            if result.returncode == 0:
+            if scheduled:
                 return {
                     "planned": True,
-                    "updated": True,
+                    "updated": False,
+                    "deferred": True,
                     "up_to_date": False,
                     "current_version": old_version,
                     "latest_version": kbagent_latest,
-                    "message": f"Updated kbagent from v{old_version} to v{kbagent_latest}. "
-                    "Restart your shell to use the new version.",
-                    "output": result.stdout.strip(),
+                    "message": (
+                        f"kbagent v{kbagent_latest} will be installed as soon as every kbagent "
+                        "process has exited -- replacing the environment while it is in use is "
+                        "what corrupts it on Windows. Close other kbagent processes; the result "
+                        "is reported on the next launch."
+                    ),
+                    "recovery_command": plan.recovery_command,
                 }
+            # No helper could be spawned. Running the install here anyway is the
+            # exact corruption this branch exists to avoid, so hand the user the
+            # command instead of taking the risk on their behalf.
             return {
                 "planned": True,
                 "updated": False,
+                "deferred": False,
                 "up_to_date": False,
                 "current_version": old_version,
                 "latest_version": kbagent_latest,
-                "message": f"Update failed: {result.stderr.strip()}",
-                "output": result.stderr.strip(),
+                "message": (
+                    "Update could not be scheduled safely while kbagent is running. "
+                    f"Install it from a shell with no kbagent running: {plan.recovery_command}"
+                ),
                 "recovery_command": plan.recovery_command,
             }
-        except subprocess.TimeoutExpired:
-            timeout_s = int(get_update_timeout())
+
+        run = run_install(plan.command, timeout=get_update_timeout())
+        if run.status is InstallStatus.SUCCEEDED:
             return {
                 "planned": True,
-                "updated": False,
+                "updated": True,
                 "up_to_date": False,
                 "current_version": old_version,
                 "latest_version": kbagent_latest,
-                "message": (
-                    f"Update timed out after {timeout_s}s. Recover with: {plan.recovery_command}"
-                ),
-                "recovery_command": plan.recovery_command,
+                "message": f"Updated kbagent from v{old_version} to v{kbagent_latest}. "
+                "Restart your shell to use the new version.",
+                "output": run.output,
             }
-        except OSError as exc:
+        if run.status is InstallStatus.STILL_RUNNING:
+            # Not killed, still installing -- offering a recovery command here
+            # would invite a second installer into the same environment.
+            timeout_s = int(get_update_timeout())
             return {
                 "planned": True,
                 "updated": False,
                 "up_to_date": False,
                 "current_version": old_version,
                 "latest_version": kbagent_latest,
-                "message": f"Update failed: {exc}",
-                "recovery_command": plan.recovery_command,
+                "message": (
+                    f"Update still running after {timeout_s}s; it continues in the background "
+                    f"and applies on the next launch. Log: {run.log_path}"
+                ),
+                "output": run.output,
             }
+        return {
+            "planned": True,
+            "updated": False,
+            "up_to_date": False,
+            "current_version": old_version,
+            "latest_version": kbagent_latest,
+            "message": f"Update failed: {run.output}",
+            "output": run.output,
+            "recovery_command": plan.recovery_command,
+        }
 
     @staticmethod
     def _update_mcp(plan: McpUpdatePlan) -> dict[str, Any]:
diff --git a/src/keboola_agent_cli/update_runner.py b/src/keboola_agent_cli/update_runner.py
new file mode 100644
index 00000000..858f1d85
--- /dev/null
+++ b/src/keboola_agent_cli/update_runner.py
@@ -0,0 +1,508 @@
+"""How the kbagent self-reinstall is actually executed (issue #528).
+
+Both self-update entry points -- the startup hook in :mod:`.auto_update` and
+the explicit ``kbagent update`` command -- ultimately run one install command.
+*Where* that command runs is a correctness question, not a detail:
+
+``uv tool install`` recreates a tool environment by **removing** it and then
+creating a fresh venv at the same path (``uv-tool/src/lib.rs``:
+``create_environment`` -> *"Remove any existing environment"* -> ``create_venv``).
+The removal is neither atomic nor rollback-able. On POSIX that is harmless --
+unlinking a file another process holds open leaves that process's inode intact,
+so a running kbagent survives having its own venv replaced under it. On Windows
+it is fatal: uv's trampoline (``kbagent.exe``) loads the tool venv's interpreter
+DLL **in-process**, so those files are locked; the removal deletes everything it
+can, hits a locked file, and aborts -- leaving a gutted venv. Upstream tracks the
+same failure as astral-sh/uv#11930.
+
+This module therefore provides two things:
+
+* :func:`run_install` -- a subprocess runner that **never kills the installer**.
+  ``subprocess.run(timeout=...)`` terminates the child on timeout, which on
+  Windows is ``TerminateProcess`` -- a hard kill of uv mid-write produces exactly
+  the same gutted venv as a lock failure. When the deadline passes we stop
+  *waiting*; we do not stop *uv*.
+* :func:`request_deferred_update` -- schedules the install to run from a detached
+  helper **after** every kbagent process has exited, so nothing holds the target
+  environment open. The result is reported by the next kbagent startup.
+
+The helper is a PowerShell one-liner: Windows PowerShell 5.1 is an in-box OS
+component on every supported Windows 10/11 edition, and ``ExecutionPolicy``
+governs script *files*, not ``-Command`` strings, so no policy can block it.
+Its script text is built by pure functions so the exact contract is unit-testable
+on POSIX CI.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+import shutil
+import subprocess
+import time
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+import platformdirs
+
+from .constants import (
+    DEFERRED_UPDATE_ABANDONED_MARKER,
+    DEFERRED_UPDATE_EXIT_FILENAME,
+    DEFERRED_UPDATE_LOG_FILENAME,
+    DEFERRED_UPDATE_MARKER_FILENAME,
+    DEFERRED_UPDATE_MAX_WAIT_SECONDS,
+    DEFERRED_UPDATE_POLL_SECONDS,
+    DEFERRED_UPDATE_PROCESS_NAME,
+    DEFERRED_UPDATE_STALE_SECONDS,
+    ENV_DEFER_UPDATE,
+)
+
+logger = logging.getLogger(__name__)
+
+# Windows-only process-creation flags. Absent on POSIX, where the detached
+# helper path is never taken; `getattr` keeps the module importable there.
+_DETACHED_PROCESS = getattr(subprocess, "DETACHED_PROCESS", 0)
+_CREATE_NEW_PROCESS_GROUP = getattr(subprocess, "CREATE_NEW_PROCESS_GROUP", 0)
+
+# Fallback location of the in-box Windows PowerShell, used when PATH lookup
+# fails (a stripped PATH in a service context, a broken shell profile).
+_WINDOWS_POWERSHELL_RELATIVE = r"System32\WindowsPowerShell\v1.0\powershell.exe"
+
+
+class InstallStatus(Enum):
+    """Terminal state of one install-command execution.
+
+    ``STILL_RUNNING`` is deliberately not a failure: the installer outran our
+    patience, not our expectations. We stopped waiting and left it working.
+    """
+
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    STILL_RUNNING = "still_running"
+
+
+@dataclass(frozen=True)
+class InstallRun:
+    """Outcome of running one install command, plus whatever it printed."""
+
+    status: InstallStatus
+    exit_code: int | None
+    output: str
+    log_path: Path
+
+
+@dataclass(frozen=True)
+class DeferredUpdateRequest:
+    """Everything the detached helper needs; nothing it can re-derive."""
+
+    from_version: str
+    target_version: str
+    install_command: tuple[str, ...]
+    recovery_command: str | None
+
+
+class DeferredUpdateStatus(Enum):
+    """What became of a previously scheduled deferred update."""
+
+    SUCCEEDED = "succeeded"
+    FAILED = "failed"
+    ABANDONED = "abandoned"
+    LOST = "lost"
+
+
+@dataclass(frozen=True)
+class DeferredUpdateReport:
+    """A finished deferred update, ready to be reported to the user once."""
+
+    status: DeferredUpdateStatus
+    from_version: str
+    target_version: str
+    exit_code: int | None
+    recovery_command: str | None
+    log_path: Path
+
+
+def state_dir() -> Path:
+    """Directory holding deferred-update bookkeeping files.
+
+    The global config directory, matching the version cache in
+    :mod:`.auto_update` -- deferred state must outlive the process that
+    scheduled it and must be found by an unrelated later invocation.
+    """
+    return Path(platformdirs.user_config_dir("keboola-agent-cli"))
+
+
+def _marker_path() -> Path:
+    return state_dir() / DEFERRED_UPDATE_MARKER_FILENAME
+
+
+def _exit_path() -> Path:
+    return state_dir() / DEFERRED_UPDATE_EXIT_FILENAME
+
+
+def log_path() -> Path:
+    """Path the installer's combined output is appended to."""
+    return state_dir() / DEFERRED_UPDATE_LOG_FILENAME
+
+
+def should_defer() -> bool:
+    """Whether the install must run out-of-process rather than inline.
+
+    Windows by default, because there the in-place venv removal performed by
+    ``uv tool install`` cannot survive the running process holding it open.
+    ``KBAGENT_DEFER_UPDATE`` forces the decision either way -- ``1`` to exercise
+    the deferred path on POSIX (how CI covers it end to end), ``0`` as an escape
+    hatch for a Windows user who would rather take the in-place risk.
+    """
+    raw = os.environ.get(ENV_DEFER_UPDATE, "").strip().lower()
+    if raw in {"1", "true", "yes", "on"}:
+        return True
+    if raw in {"0", "false", "no", "off"}:
+        return False
+    return os.name == "nt"
+
+
+def run_install(command: tuple[str, ...], *, timeout: float) -> InstallRun:
+    """Run an install command, waiting at most ``timeout`` -- and never killing it.
+
+    ``subprocess.run(..., timeout=...)`` kills the child when the deadline
+    passes. For a package installer that is the worst possible response: uv is
+    then terminated part-way through recreating a venv, which leaves the same
+    half-deleted environment a Windows file lock would (issue #528). Here the
+    deadline only bounds *our* waiting; the installer keeps running and finishes
+    the transaction it started.
+
+    Output goes to :func:`log_path` rather than a pipe, for the same reason --
+    ``PIPE`` would deadlock once the OS buffer filled and we stopped reading,
+    and a child we intend to outlive must not be writing into a pipe whose
+    reader is gone.
+
+    Args:
+        command: Full argv of the installer.
+        timeout: Seconds to wait before giving up on the wait (not on the child).
+
+    Returns:
+        :class:`InstallRun` describing the outcome and the captured output.
+    """
+    destination = log_path()
+    try:
+        destination.parent.mkdir(parents=True, exist_ok=True)
+    except OSError:
+        logger.debug("Could not create the update log directory", exc_info=True)
+
+    try:
+        with destination.open("a", encoding="utf-8", errors="replace") as sink:
+            process = subprocess.Popen(
+                list(command),
+                stdin=subprocess.DEVNULL,
+                stdout=sink,
+                stderr=subprocess.STDOUT,
+                close_fds=True,
+            )
+            try:
+                exit_code = process.wait(timeout=timeout)
+            except subprocess.TimeoutExpired:
+                return InstallRun(
+                    status=InstallStatus.STILL_RUNNING,
+                    exit_code=None,
+                    output=_tail(destination),
+                    log_path=destination,
+                )
+    except OSError as exc:
+        return InstallRun(
+            status=InstallStatus.FAILED,
+            exit_code=None,
+            output=str(exc),
+            log_path=destination,
+        )
+
+    return InstallRun(
+        status=InstallStatus.SUCCEEDED if exit_code == 0 else InstallStatus.FAILED,
+        exit_code=exit_code,
+        output=_tail(destination),
+        log_path=destination,
+    )
+
+
+def _tail(path: Path, *, max_chars: int = 4000) -> str:
+    """Return the end of the install log, or an empty string if unreadable."""
+    try:
+        text = path.read_text(encoding="utf-8", errors="replace")
+    except OSError:
+        return ""
+    return text[-max_chars:].strip()
+
+
+def quote_for_powershell(value: str) -> str:
+    """Wrap ``value`` in a PowerShell single-quoted literal.
+
+    Single quotes are the only PowerShell string form with no escape sequences
+    at all -- no ``$`` expansion, no backtick escapes -- so a Windows path full
+    of backslashes passes through untouched. The one character needing care is
+    the quote itself, which is escaped by doubling.
+    """
+    return "'" + value.replace("'", "''") + "'"
+
+
+def build_waiter_script(
+    request: DeferredUpdateRequest,
+    *,
+    pid: int,
+    exit_file: Path,
+    install_log: Path,
+    max_wait_seconds: int = DEFERRED_UPDATE_MAX_WAIT_SECONDS,
+    poll_seconds: int = DEFERRED_UPDATE_POLL_SECONDS,
+    process_name: str = DEFERRED_UPDATE_PROCESS_NAME,
+    abandoned_marker: str = DEFERRED_UPDATE_ABANDONED_MARKER,
+) -> str:
+    """Build the PowerShell program the detached helper runs.
+
+    It waits twice, deliberately. ``Wait-Process -Id`` covers the process that
+    scheduled the update even when it is not named ``kbagent`` (``python -m
+    keboola_agent_cli``); the ``Get-Process -Name`` loop then covers every
+    *other* kbagent still holding the environment open, which is the case the
+    PID wait cannot see. Only when both are clear is the installer allowed to
+    touch the venv.
+
+    If kbagent is still running when the window closes -- a ``kbagent serve``
+    left open for the day -- the helper installs **nothing** and records that
+    it gave up. Doing nothing is always safe here; the update simply retries on
+    a later run.
+
+    Returns:
+        A self-contained script suitable for ``powershell.exe -Command``.
+    """
+    quoted_argv = " ".join(quote_for_powershell(part) for part in request.install_command)
+    exit_literal = quote_for_powershell(str(exit_file))
+    log_literal = quote_for_powershell(str(install_log))
+    name_literal = quote_for_powershell(process_name)
+    abandoned_literal = quote_for_powershell(abandoned_marker)
+
+    return "\n".join(
+        [
+            f"$exitFile = {exit_literal}",
+            f"$logFile = {log_literal}",
+            "try {",
+            f"  Wait-Process -Id {pid} -Timeout {max_wait_seconds} -ErrorAction SilentlyContinue",
+            f"  $deadline = (Get-Date).AddSeconds({max_wait_seconds})",
+            f"  while ((Get-Process -Name {name_literal} -ErrorAction SilentlyContinue)"
+            " -and ((Get-Date) -lt $deadline)) {",
+            f"    Start-Sleep -Seconds {poll_seconds}",
+            "  }",
+            f"  if (Get-Process -Name {name_literal} -ErrorAction SilentlyContinue) {{",
+            f"    Set-Content -LiteralPath $exitFile -Value {abandoned_literal}",
+            "    exit 0",
+            "  }",
+            f"  & {quoted_argv} *>> $logFile",
+            "  Set-Content -LiteralPath $exitFile -Value ([string]$LASTEXITCODE)",
+            "} catch {",
+            "  $_ | Out-File -FilePath $logFile -Append",
+            "  Set-Content -LiteralPath $exitFile -Value 'failed'",
+            "}",
+        ]
+    )
+
+
+def resolve_powershell() -> str | None:
+    """Locate an interpreter for the detached helper.
+
+    Prefers in-box Windows PowerShell, falling back to PowerShell 7 (``pwsh``)
+    and finally to the absolute ``System32`` path for the case where PATH has
+    been stripped. ``None`` means we must not schedule anything -- the caller
+    then tells the user the exact command instead of risking an in-place
+    install.
+    """
+    for candidate in ("powershell", "pwsh"):
+        found = shutil.which(candidate)
+        if found:
+            return found
+    # `os.environ` upper-cases its keys on Windows, so the canonical spelling
+    # of `%SystemRoot%` here is the all-caps one.
+    system_root = os.environ.get("SYSTEMROOT")
+    if system_root:
+        fallback = Path(system_root) / _WINDOWS_POWERSHELL_RELATIVE
+        if fallback.is_file():
+            return str(fallback)
+    return None
+
+
+def build_helper_command(powershell: str, script: str) -> list[str]:
+    """Build the argv that launches the waiter script detached from any console."""
+    return [
+        powershell,
+        "-NoProfile",
+        "-NonInteractive",
+        "-WindowStyle",
+        "Hidden",
+        "-Command",
+        script,
+    ]
+
+
+def is_update_pending() -> bool:
+    """Whether a scheduled deferred update is still waiting to run.
+
+    Single-flight guard: every kbagent startup evaluates the same update, so
+    without this a handful of shells opened in a row would each spawn their own
+    helper and they would race each other into the very corruption this module
+    exists to prevent.
+    """
+    marker = _read_marker()
+    if marker is None:
+        return False
+    if _exit_path().is_file():
+        return False
+    return not _marker_is_stale(marker)
+
+
+def _marker_is_stale(marker: dict) -> bool:
+    try:
+        return (time.time() - float(marker["requested_at"])) > DEFERRED_UPDATE_STALE_SECONDS
+    except (KeyError, TypeError, ValueError):
+        return True
+
+
+def _read_marker() -> dict | None:
+    path = _marker_path()
+    try:
+        if not path.is_file():
+            return None
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, ValueError):
+        return None
+    return data if isinstance(data, dict) else None
+
+
+def request_deferred_update(request: DeferredUpdateRequest) -> bool:
+    """Schedule ``request`` to be installed once no kbagent process is left.
+
+    Writes the marker *before* spawning, so a helper that dies immediately still
+    leaves evidence a later run can report rather than a silent no-op.
+
+    Returns:
+        True when a helper was spawned (or one is already pending). False when
+        scheduling is impossible -- no PowerShell, unwritable state directory --
+        which the caller must surface as "run this command yourself", never as a
+        reason to fall back to an in-place install.
+    """
+    if is_update_pending():
+        return True
+
+    powershell = resolve_powershell()
+    if powershell is None:
+        logger.debug("No PowerShell interpreter found; cannot defer the update")
+        return False
+
+    exit_file = _exit_path()
+    install_log = log_path()
+    script = build_waiter_script(
+        request,
+        pid=os.getpid(),
+        exit_file=exit_file,
+        install_log=install_log,
+    )
+
+    try:
+        state_dir().mkdir(parents=True, exist_ok=True)
+        exit_file.unlink(missing_ok=True)
+        _marker_path().write_text(
+            json.dumps(
+                {
+                    "requested_at": time.time(),
+                    "pid": os.getpid(),
+                    "from_version": request.from_version,
+                    "target_version": request.target_version,
+                    "recovery_command": request.recovery_command,
+                }
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        logger.debug("Could not persist the deferred-update marker", exc_info=True)
+        return False
+
+    try:
+        subprocess.Popen(
+            build_helper_command(powershell, script),
+            stdin=subprocess.DEVNULL,
+            stdout=subprocess.DEVNULL,
+            stderr=subprocess.DEVNULL,
+            close_fds=True,
+            creationflags=_DETACHED_PROCESS | _CREATE_NEW_PROCESS_GROUP,
+        )
+    except OSError:
+        logger.debug("Could not spawn the deferred-update helper", exc_info=True)
+        _marker_path().unlink(missing_ok=True)
+        return False
+
+    return True
+
+
+def collect_finished_deferred_update() -> DeferredUpdateReport | None:
+    """Consume the result of a previously scheduled deferred update.
+
+    Called once per startup. Clears the bookkeeping files so a result is
+    reported exactly once, whatever it was.
+
+    Returns:
+        A report when a scheduled update has reached a terminal state, or None
+        when nothing was scheduled or the helper is still waiting.
+    """
+    marker = _read_marker()
+    if marker is None:
+        return None
+
+    exit_file = _exit_path()
+    raw_exit: str | None = None
+    if exit_file.is_file():
+        try:
+            raw_exit = exit_file.read_text(encoding="utf-8").strip()
+        except OSError:
+            raw_exit = None
+    elif not _marker_is_stale(marker):
+        return None  # helper is still waiting for kbagent to exit
+
+    _clear_deferred_state()
+
+    status, exit_code = _classify_exit(raw_exit, marker_is_stale=raw_exit is None)
+    return DeferredUpdateReport(
+        status=status,
+        from_version=str(marker.get("from_version") or "unknown"),
+        target_version=str(marker.get("target_version") or "unknown"),
+        exit_code=exit_code,
+        recovery_command=marker.get("recovery_command"),
+        log_path=log_path(),
+    )
+
+
+def _classify_exit(
+    raw_exit: str | None, *, marker_is_stale: bool
+) -> tuple[DeferredUpdateStatus, int | None]:
+    """Map the helper's exit file to a status.
+
+    Anything that is neither a clean exit code nor the explicit "gave up"
+    marker counts as a failure -- an unparseable result is exactly the case
+    where the user needs the recovery command, so it must not be optimistic.
+    """
+    if raw_exit is None:
+        return (DeferredUpdateStatus.LOST if marker_is_stale else DeferredUpdateStatus.FAILED), None
+    if raw_exit == DEFERRED_UPDATE_ABANDONED_MARKER:
+        return DeferredUpdateStatus.ABANDONED, None
+    try:
+        exit_code = int(raw_exit)
+    except ValueError:
+        return DeferredUpdateStatus.FAILED, None
+    if exit_code == 0:
+        return DeferredUpdateStatus.SUCCEEDED, 0
+    return DeferredUpdateStatus.FAILED, exit_code
+
+
+def _clear_deferred_state() -> None:
+    """Remove the marker and exit files; the log is kept for diagnosis."""
+    for path in (_marker_path(), _exit_path()):
+        try:
+            path.unlink(missing_ok=True)
+        except OSError:
+            logger.debug("Could not clear deferred-update state at %s", path, exc_info=True)
diff --git a/tests/test_auto_update.py b/tests/test_auto_update.py
index 46b5714d..78ee46d8 100644
--- a/tests/test_auto_update.py
+++ b/tests/test_auto_update.py
@@ -3,6 +3,7 @@
 import json
 import os
 import time
+from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -21,9 +22,16 @@
     _top_level_subcommand_is_versioning,
     _write_cache,
     maybe_auto_update,
+    report_finished_deferred_update,
 )
 from keboola_agent_cli.constants import ENV_AUTO_UPDATE, ENV_SKIP_UPDATE, MCP_UPGRADE_TIMEOUT
 from keboola_agent_cli.services.version_service import KbagentUpdatePlan, McpUpdatePlan
+from keboola_agent_cli.update_runner import (
+    DeferredUpdateReport,
+    DeferredUpdateStatus,
+    InstallRun,
+    InstallStatus,
+)
 
 
 # ---------------------------------------------------------------------------
@@ -237,37 +245,45 @@ def test_cache_fresh_with_bad_data(self):
 # ---------------------------------------------------------------------------
 # _perform_update
 # ---------------------------------------------------------------------------
+def _finished_install(status: InstallStatus, exit_code: int | None = 0) -> InstallRun:
+    """An :class:`InstallRun` stand-in for a mocked installer execution."""
+    return InstallRun(status=status, exit_code=exit_code, output="", log_path=Path("update.log"))
+
+
 class TestPerformUpdate:
-    """Tests for the _perform_update() function."""
+    """Tests for the _perform_update() function.
+
+    The installer subprocess itself is owned by ``update_runner.run_install``
+    (issue #528), so these tests assert the command _perform_update hands it --
+    the contract that actually matters here -- rather than reaching through to
+    ``subprocess``.
+    """
 
     @patch("shutil.which")
-    @patch("subprocess.run")
-    def test_update_with_uv_success(self, mock_run, mock_which):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_update_with_uv_success(self, mock_install, mock_which):
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
-        # Verify uv was called
-        call_args = mock_run.call_args
-        assert "uv" in call_args[0][0][0]
+        assert "uv" in mock_install.call_args.args[0][0]
 
     @patch("shutil.which")
-    @patch("subprocess.run")
-    def test_update_with_uv_failure(self, mock_run, mock_which):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_update_with_uv_failure(self, mock_install, mock_which):
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.return_value = MagicMock(returncode=1, stderr="error")
+        mock_install.return_value = _finished_install(InstallStatus.FAILED, exit_code=1)
         assert _perform_update("2.0.0") is UpdateOutcome.FAILED
 
     @patch("shutil.which")
-    @patch("subprocess.run")
-    def test_update_pip_fallback(self, mock_run, mock_which):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_update_pip_fallback(self, mock_install, mock_which):
         # uv not found, pip found
         mock_which.side_effect = lambda cmd: (
             None if cmd == "uv" else "/usr/bin/pip" if cmd == "pip" else None
         )
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
-        call_args = mock_run.call_args
-        assert "pip" in call_args[0][0][0]
+        assert "pip" in mock_install.call_args.args[0][0]
 
     @patch("shutil.which")
     def test_update_no_tools(self, mock_which):
@@ -275,12 +291,15 @@ def test_update_no_tools(self, mock_which):
         assert _perform_update("2.0.0") is UpdateOutcome.FAILED
 
     @patch("shutil.which")
-    @patch("subprocess.run")
-    def test_update_timeout(self, mock_run, mock_which):
-        import subprocess as sp
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_still_running_maps_to_timeout(self, mock_install, mock_which):
+        """An installer that outran the wait is TIMEOUT, not FAILED.
 
+        It was not killed (issue #528) -- it is still recreating the
+        environment and the next launch picks up the result.
+        """
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.side_effect = sp.TimeoutExpired(cmd="uv", timeout=120)
+        mock_install.return_value = _finished_install(InstallStatus.STILL_RUNNING, exit_code=None)
         assert _perform_update("2.0.0") is UpdateOutcome.TIMEOUT
 
     @patch(
@@ -288,8 +307,8 @@ def test_update_timeout(self, mock_run, mock_which):
         return_value=True,
     )
     @patch("shutil.which", return_value="/usr/local/bin/uv")
-    @patch("subprocess.run")
-    def test_update_preserves_server_extras(self, mock_run, mock_which, mock_has_server):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_update_preserves_server_extras(self, mock_install, mock_which, mock_has_server):
         """Bug fix (v0.41.1): startup auto-update must preserve [server] extras.
 
         Before v0.41.1, ``_perform_update`` ran a bare
@@ -301,9 +320,9 @@ def test_update_preserves_server_extras(self, mock_run, mock_which, mock_has_ser
         :func:`build_kbagent_upgrade_command`, which pairs ``--with`` and
         ``--force`` when ``fastapi`` is importable.
         """
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
-        argv = mock_run.call_args[0][0]
+        argv = mock_install.call_args.args[0]
         # The extras live in the primary PEP 508 requirement so the complete
         # environment is resolved in one forced reinstall.
         assert "--force" in argv
@@ -316,12 +335,14 @@ def test_update_preserves_server_extras(self, mock_run, mock_which, mock_has_ser
         return_value=False,
     )
     @patch("shutil.which", return_value="/usr/local/bin/uv")
-    @patch("subprocess.run")
-    def test_update_without_server_extras_uses_upgrade(self, mock_run, mock_which, mock_has_server):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_update_without_server_extras_uses_upgrade(
+        self, mock_install, mock_which, mock_has_server
+    ):
         """No-extras installs are also a full forced reinstall."""
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
-        argv = mock_run.call_args[0][0]
+        argv = mock_install.call_args.args[0]
         assert "--force" in argv
         assert "--reinstall" in argv
         assert "keboola-cli[server]" not in argv
@@ -336,17 +357,17 @@ class TestPerformUpdateWheel:
         return_value=False,
     )
     @patch("shutil.which", return_value="/usr/local/bin/uv")
-    @patch("subprocess.run")
+    @patch("keboola_agent_cli.auto_update.run_install")
     def test_installs_wheel_when_asset_present(
-        self, mock_run, mock_which, mock_has_server, mock_head
+        self, mock_install, mock_which, mock_has_server, mock_head
     ):
         """A 200 HEAD on the asset -> install the prebuilt wheel, not git+."""
         mock_head.return_value = MagicMock(status_code=200)
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
 
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
 
-        argv = mock_run.call_args[0][0]
+        argv = mock_install.call_args.args[0]
         # PEP 508 direct ref to the versioned wheel, --force, and no git+ source.
         assert "--force" in argv
         assert any(part.endswith("keboola_cli-2.0.0-py3-none-any.whl") for part in argv)
@@ -354,15 +375,15 @@ def test_installs_wheel_when_asset_present(
 
     @patch("keboola_agent_cli.services.version_service.httpx.head")
     @patch("shutil.which", return_value="/usr/local/bin/uv")
-    @patch("subprocess.run")
-    def test_falls_back_to_git_when_no_asset(self, mock_run, mock_which, mock_head):
+    @patch("keboola_agent_cli.auto_update.run_install")
+    def test_falls_back_to_git_when_no_asset(self, mock_install, mock_which, mock_head):
         """A 404 HEAD (older release without an asset) -> git+ source build."""
         mock_head.return_value = MagicMock(status_code=404)
-        mock_run.return_value = MagicMock(returncode=0)
+        mock_install.return_value = _finished_install(InstallStatus.SUCCEEDED)
 
         assert _perform_update("2.0.0") is UpdateOutcome.SUCCESS
 
-        argv = mock_run.call_args[0][0]
+        argv = mock_install.call_args.args[0]
         assert any("git+" in part for part in argv)
 
 
@@ -580,12 +601,17 @@ def test_timeout_outcome_is_not_a_failure(
         The banner should say the build is still running, not that it failed --
         the wheel fast path makes timeouts rare, but when the git+ fallback runs
         long the next invocation finishes it.
+
+        Since issue #528 the installer is not killed when the wait expires, so
+        the banner must NOT offer a recovery command either: a second installer
+        started against the environment a live uv is rewriting is precisely the
+        corruption being fixed.
         """
         maybe_auto_update()
         mock_reexec.assert_not_called()
         err = capsys.readouterr().err
-        assert "timed out" in err
-        assert "Recover with:" in err
+        assert "still running" in err
+        assert "Recover with:" not in err
 
     @patch("keboola_agent_cli.auto_update._read_cache", return_value=None)
     @patch("keboola_agent_cli.auto_update._fetch_kbagent_latest_version", return_value=None)
@@ -1149,3 +1175,143 @@ def reexec() -> None:
         ]
         # Sentinel was flipped before the crash.
         assert auto_update_module._AUTO_UPDATE_RAN is True
+
+
+# ---------------------------------------------------------------------------
+# Deferred (out-of-process) startup update -- issue #528
+# ---------------------------------------------------------------------------
+class TestStartupDefersTheReinstall:
+    """On Windows the startup hook must not replace its own live environment.
+
+    `uv tool install` removes the tool venv before recreating it, so running it
+    from inside that venv on Windows deletes the files the running process has
+    locked and aborts part-way -- the gutted `rich`/`typer` the reporter saw.
+    """
+
+    @pytest.fixture(autouse=True)
+    def _quiet_mcp_and_cache(self):
+        auto_update_module._AUTO_UPDATE_RAN = False
+        with (
+            patch("keboola_agent_cli.auto_update._read_cache", return_value=None),
+            patch("keboola_agent_cli.auto_update._write_cache"),
+            patch("keboola_agent_cli.auto_update._apply_prepared_mcp_update"),
+            patch("keboola_agent_cli.auto_update._fetch_mcp_latest_version", return_value=None),
+            patch("keboola_agent_cli.auto_update._get_local_mcp_version", return_value=None),
+            patch("keboola_agent_cli.auto_update._detect_mcp_install_method", return_value="none"),
+            patch("keboola_agent_cli.auto_update._should_skip_all", return_value=False),
+            patch("keboola_agent_cli.auto_update._should_skip_kbagent_stage", return_value=False),
+            patch(
+                "keboola_agent_cli.auto_update.report_finished_deferred_update",
+            ),
+            patch(
+                "keboola_agent_cli.auto_update._fetch_kbagent_latest_version",
+                return_value="2.0.0",
+            ),
+            patch("keboola_agent_cli.auto_update._is_up_to_date", return_value=False),
+            patch("keboola_agent_cli.auto_update.__version__", "1.0.0"),
+        ):
+            yield
+
+    @patch("keboola_agent_cli.auto_update.should_defer", return_value=True)
+    @patch("keboola_agent_cli.auto_update.request_deferred_update", return_value=True)
+    @patch("keboola_agent_cli.auto_update._perform_update")
+    @patch("keboola_agent_cli.auto_update._re_exec")
+    def test_schedules_instead_of_installing_in_place(
+        self, mock_reexec, mock_perform, mock_request, mock_defer, capsys
+    ):
+        maybe_auto_update()
+
+        mock_perform.assert_not_called()
+        mock_reexec.assert_not_called()
+        request = mock_request.call_args.args[0]
+        assert request.from_version == "1.0.0"
+        assert request.target_version == "2.0.0"
+        assert "background" in capsys.readouterr().err
+
+    @patch("keboola_agent_cli.auto_update.should_defer", return_value=True)
+    @patch("keboola_agent_cli.auto_update.request_deferred_update", return_value=False)
+    @patch("keboola_agent_cli.auto_update._perform_update")
+    def test_unschedulable_prints_the_command_and_installs_nothing(
+        self, mock_perform, mock_request, mock_defer, capsys
+    ):
+        """Falling back to the in-place install would reintroduce the corruption."""
+        maybe_auto_update()
+
+        mock_perform.assert_not_called()
+        assert "cannot be installed safely" in capsys.readouterr().err
+
+    @patch("keboola_agent_cli.auto_update.should_defer", return_value=False)
+    @patch("keboola_agent_cli.auto_update.request_deferred_update")
+    @patch("keboola_agent_cli.auto_update._perform_update", return_value=UpdateOutcome.SUCCESS)
+    @patch("keboola_agent_cli.auto_update._re_exec")
+    def test_posix_keeps_the_inline_install_and_re_exec(
+        self, mock_reexec, mock_perform, mock_request, mock_defer
+    ):
+        """The path that works today must not regress for the majority of users."""
+        maybe_auto_update()
+
+        mock_request.assert_not_called()
+        mock_perform.assert_called_once()
+        mock_reexec.assert_called_once()
+
+
+class TestReportFinishedDeferredUpdate:
+    """The run that schedules an update can never report it -- the next one does."""
+
+    def _report(self, status):
+        return DeferredUpdateReport(
+            status=status,
+            from_version="0.76.3",
+            target_version="0.76.4",
+            exit_code=2 if status is DeferredUpdateStatus.FAILED else None,
+            recovery_command="uv tool install --force --reinstall x",
+            log_path=Path("update.log"),
+        )
+
+    @patch("keboola_agent_cli.auto_update.collect_finished_deferred_update", return_value=None)
+    def test_nothing_to_report_prints_nothing(self, mock_collect, capsys):
+        report_finished_deferred_update()
+        assert capsys.readouterr().err == ""
+
+    @patch("keboola_agent_cli.auto_update.collect_finished_deferred_update")
+    def test_success_is_announced(self, mock_collect, capsys):
+        mock_collect.return_value = self._report(DeferredUpdateStatus.SUCCEEDED)
+        report_finished_deferred_update()
+        assert "Updated kbagent to v0.76.4" in capsys.readouterr().err
+
+    @patch("keboola_agent_cli.auto_update.collect_finished_deferred_update")
+    def test_failure_carries_the_recovery_command(self, mock_collect, capsys):
+        mock_collect.return_value = self._report(DeferredUpdateStatus.FAILED)
+        err = capsys.readouterr()  # drain
+        report_finished_deferred_update()
+        err = capsys.readouterr().err
+        assert "did not complete" in err
+        assert "uv tool install --force --reinstall x" in err
+
+    @patch("keboola_agent_cli.auto_update.collect_finished_deferred_update")
+    def test_abandoned_does_not_read_as_a_failure(self, mock_collect, capsys):
+        """Nothing was installed, so nothing needs recovering."""
+        mock_collect.return_value = self._report(DeferredUpdateStatus.ABANDONED)
+        report_finished_deferred_update()
+        err = capsys.readouterr().err
+        assert "skipped" in err
+        assert "Recover with" not in err
+
+    @patch(
+        "keboola_agent_cli.auto_update.collect_finished_deferred_update",
+        side_effect=OSError("unreadable"),
+    )
+    def test_never_raises(self, mock_collect):
+        report_finished_deferred_update()
+
+    @patch("keboola_agent_cli.auto_update._should_skip_all", return_value=True)
+    @patch("keboola_agent_cli.auto_update.report_finished_deferred_update")
+    def test_reported_even_when_the_run_will_not_update(self, mock_report, mock_skip):
+        """The result is owed to the user on the very next run, whatever it is.
+
+        Gating it behind the skip check would swallow a failed background
+        update on a dev install, an opt-out, or `kbagent version`.
+        """
+        auto_update_module._AUTO_UPDATE_RAN = False
+        maybe_auto_update()
+        mock_report.assert_called_once()
diff --git a/tests/test_update_runner.py b/tests/test_update_runner.py
new file mode 100644
index 00000000..3b17f9a9
--- /dev/null
+++ b/tests/test_update_runner.py
@@ -0,0 +1,357 @@
+"""Tests for the self-reinstall runner (issue #528).
+
+The failure these guard against is not observable on the CI platforms: it needs
+a Windows file lock on a running `uv tool` environment. So the contracts are
+pinned structurally instead -- the waiter script's text, the scheduling
+bookkeeping, and the one behaviour that *is* directly observable everywhere:
+that a slow installer is never killed.
+"""
+
+import json
+import subprocess
+import sys
+import time
+from pathlib import Path
+
+import pytest
+
+from keboola_agent_cli.constants import (
+    DEFERRED_UPDATE_ABANDONED_MARKER,
+    DEFERRED_UPDATE_EXIT_FILENAME,
+    DEFERRED_UPDATE_MARKER_FILENAME,
+    DEFERRED_UPDATE_STALE_SECONDS,
+    ENV_DEFER_UPDATE,
+)
+from keboola_agent_cli.update_runner import (
+    DeferredUpdateRequest,
+    DeferredUpdateStatus,
+    InstallStatus,
+    build_helper_command,
+    build_waiter_script,
+    collect_finished_deferred_update,
+    is_update_pending,
+    quote_for_powershell,
+    request_deferred_update,
+    run_install,
+    should_defer,
+)
+
+REQUEST = DeferredUpdateRequest(
+    from_version="0.76.3",
+    target_version="0.76.4",
+    install_command=(
+        r"C:\tools\uv.exe",
+        "tool",
+        "install",
+        "--force",
+        "--reinstall",
+        "keboola-cli[server] @ https://example.invalid/keboola_cli-0.76.4-py3-none-any.whl",
+    ),
+    recovery_command="uv tool install --force --reinstall ...",
+)
+
+
+@pytest.fixture(autouse=True)
+def _isolated_state(tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+    """Point every bookkeeping file at a scratch directory."""
+    monkeypatch.setattr("keboola_agent_cli.update_runner.state_dir", lambda: tmp_path)
+
+
+class TestShouldDefer:
+    """Which platforms must not install into their own live environment."""
+
+    def test_defaults_to_windows(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv(ENV_DEFER_UPDATE, raising=False)
+        monkeypatch.setattr("keboola_agent_cli.update_runner.os.name", "nt")
+        assert should_defer() is True
+
+    def test_defaults_off_on_posix(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.delenv(ENV_DEFER_UPDATE, raising=False)
+        monkeypatch.setattr("keboola_agent_cli.update_runner.os.name", "posix")
+        assert should_defer() is False
+
+    @pytest.mark.parametrize("value", ["1", "true", "YES", "on"])
+    def test_env_forces_on(self, value: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv(ENV_DEFER_UPDATE, value)
+        monkeypatch.setattr("keboola_agent_cli.update_runner.os.name", "posix")
+        assert should_defer() is True
+
+    @pytest.mark.parametrize("value", ["0", "false", "NO", "off"])
+    def test_env_forces_off(self, value: str, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setenv(ENV_DEFER_UPDATE, value)
+        monkeypatch.setattr("keboola_agent_cli.update_runner.os.name", "nt")
+        assert should_defer() is False
+
+
+class TestRunInstall:
+    """The installer subprocess is waited on, never terminated."""
+
+    def test_success(self) -> None:
+        run = run_install((sys.executable, "-c", "print('ok')"), timeout=30)
+        assert run.status is InstallStatus.SUCCEEDED
+        assert run.exit_code == 0
+        assert "ok" in run.output
+
+    def test_failure_reports_exit_code_and_output(self) -> None:
+        run = run_install(
+            (sys.executable, "-c", "import sys; sys.stderr.write('boom'); sys.exit(3)"),
+            timeout=30,
+        )
+        assert run.status is InstallStatus.FAILED
+        assert run.exit_code == 3
+        assert "boom" in run.output
+
+    def test_missing_executable_is_a_failure_not_a_crash(self, tmp_path: Path) -> None:
+        run = run_install((str(tmp_path / "definitely-not-here"),), timeout=30)
+        assert run.status is InstallStatus.FAILED
+        assert run.exit_code is None
+
+    def test_slow_installer_is_left_running(self, tmp_path: Path) -> None:
+        """The deadline bounds our waiting, not the installer's work.
+
+        ``subprocess.run(timeout=...)`` would kill the child here. For a package
+        installer that is the corruption itself: uv terminated mid-transaction
+        leaves the same half-removed environment a Windows lock does (#528).
+        """
+        sentinel = tmp_path / "finished.txt"
+        program = (
+            "import time, pathlib, sys;"
+            "time.sleep(1.5);"
+            f"pathlib.Path({str(sentinel)!r}).write_text('done')"
+        )
+
+        run = run_install((sys.executable, "-c", program), timeout=0.2)
+
+        assert run.status is InstallStatus.STILL_RUNNING
+        assert run.exit_code is None
+        assert not sentinel.exists(), "precondition: the child cannot have finished yet"
+
+        deadline = time.monotonic() + 20
+        while time.monotonic() < deadline and not sentinel.exists():
+            time.sleep(0.1)
+        assert sentinel.exists(), "the installer was killed instead of being left to finish"
+
+
+class TestQuoteForPowershell:
+    """Single-quoted PowerShell literals: no expansion, quotes doubled."""
+
+    def test_windows_path_passes_through_untouched(self) -> None:
+        assert quote_for_powershell(r"C:\tools\uv.exe") == r"'C:\tools\uv.exe'"
+
+    def test_embedded_quote_is_doubled(self) -> None:
+        assert quote_for_powershell("it's") == "'it''s'"
+
+    def test_dollar_is_not_expanded_because_it_is_single_quoted(self) -> None:
+        assert quote_for_powershell("$env:PATH") == "'$env:PATH'"
+
+
+class TestBuildWaiterScript:
+    """The helper's contract: wait for every kbagent, then install once."""
+
+    @pytest.fixture
+    def script(self, tmp_path: Path) -> str:
+        return build_waiter_script(
+            REQUEST,
+            pid=4321,
+            exit_file=tmp_path / DEFERRED_UPDATE_EXIT_FILENAME,
+            install_log=tmp_path / "install.log",
+            max_wait_seconds=900,
+            poll_seconds=2,
+            process_name="kbagent",
+        )
+
+    def test_waits_for_the_scheduling_process_by_pid(self, script: str) -> None:
+        """Covers a scheduler not named `kbagent` (`python -m keboola_agent_cli`)."""
+        assert "Wait-Process -Id 4321 -Timeout 900" in script
+
+    def test_then_waits_for_every_other_kbagent(self, script: str) -> None:
+        """The PID wait cannot see a second shell holding the same venv open."""
+        assert "Get-Process -Name 'kbagent'" in script
+        assert "Start-Sleep -Seconds 2" in script
+
+    def test_gives_up_without_installing_when_kbagent_never_exits(self, script: str) -> None:
+        """Doing nothing is always safe; a partial install never is."""
+        abandon = f"Set-Content -LiteralPath $exitFile -Value '{DEFERRED_UPDATE_ABANDONED_MARKER}'"
+        assert abandon in script
+        # The abandon branch must precede the installer invocation.
+        assert script.index(abandon) < script.index("$LASTEXITCODE")
+
+    def test_installs_the_exact_prepared_command(self, script: str) -> None:
+        expected = " ".join(quote_for_powershell(part) for part in REQUEST.install_command)
+        assert f"& {expected} *>> $logFile" in script
+
+    def test_records_the_installer_exit_code(self, script: str) -> None:
+        assert "Set-Content -LiteralPath $exitFile -Value ([string]$LASTEXITCODE)" in script
+
+    def test_a_powershell_level_error_is_recorded_as_a_failure(self, script: str) -> None:
+        assert "Set-Content -LiteralPath $exitFile -Value 'failed'" in script
+
+
+class TestBuildHelperCommand:
+    """The helper must not read a profile, prompt, or show a window."""
+
+    def test_flags(self) -> None:
+        argv = build_helper_command("powershell.exe", "Write-Output 1")
+        assert argv[0] == "powershell.exe"
+        assert "-NoProfile" in argv
+        assert "-NonInteractive" in argv
+        assert argv[-2:] == ["-Command", "Write-Output 1"]
+
+
+class TestRequestDeferredUpdate:
+    """Scheduling writes evidence first, then spawns a detached helper."""
+
+    @pytest.fixture(autouse=True)
+    def _powershell_available(self, monkeypatch: pytest.MonkeyPatch) -> None:
+        monkeypatch.setattr(
+            "keboola_agent_cli.update_runner.resolve_powershell", lambda: "powershell.exe"
+        )
+
+    def test_spawns_detached_and_records_the_marker(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        spawned: list[dict] = []
+
+        def fake_popen(argv: list[str], **kwargs: object) -> object:
+            spawned.append({"argv": argv, "kwargs": kwargs})
+            return object()
+
+        monkeypatch.setattr("keboola_agent_cli.update_runner.subprocess.Popen", fake_popen)
+
+        assert request_deferred_update(REQUEST) is True
+
+        assert len(spawned) == 1
+        # No inherited console, no inherited descriptors: the helper has to
+        # outlive this process, and a pipe whose reader is gone would block it.
+        assert spawned[0]["kwargs"]["close_fds"] is True
+        assert spawned[0]["kwargs"]["stdin"] is subprocess.DEVNULL
+        assert spawned[0]["kwargs"]["stdout"] is subprocess.DEVNULL
+
+        marker = json.loads((tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).read_text())
+        assert marker["from_version"] == "0.76.3"
+        assert marker["target_version"] == "0.76.4"
+        assert marker["recovery_command"] == REQUEST.recovery_command
+
+    def test_second_request_does_not_spawn_a_second_helper(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """Single-flight: two helpers would race into the corruption we prevent."""
+        spawns = 0
+
+        def fake_popen(argv: list[str], **kwargs: object) -> object:
+            nonlocal spawns
+            spawns += 1
+            return object()
+
+        monkeypatch.setattr("keboola_agent_cli.update_runner.subprocess.Popen", fake_popen)
+
+        assert request_deferred_update(REQUEST) is True
+        assert request_deferred_update(REQUEST) is True
+        assert spawns == 1
+
+    def test_without_powershell_nothing_is_scheduled(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The caller must be told, not silently given an unsafe inline install."""
+        monkeypatch.setattr("keboola_agent_cli.update_runner.resolve_powershell", lambda: None)
+
+        assert request_deferred_update(REQUEST) is False
+        assert not (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).exists()
+
+    def test_spawn_failure_clears_the_marker(
+        self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        def failing_popen(argv: list[str], **kwargs: object) -> object:
+            raise OSError("no such file")
+
+        monkeypatch.setattr("keboola_agent_cli.update_runner.subprocess.Popen", failing_popen)
+
+        assert request_deferred_update(REQUEST) is False
+        assert not (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).exists()
+
+
+class TestCollectFinishedDeferredUpdate:
+    """A scheduled update is reported exactly once, and never optimistically."""
+
+    @staticmethod
+    def _write_marker(tmp_path: Path, *, age_seconds: float = 0.0) -> None:
+        (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).write_text(
+            json.dumps(
+                {
+                    "requested_at": time.time() - age_seconds,
+                    "pid": 1,
+                    "from_version": "0.76.3",
+                    "target_version": "0.76.4",
+                    "recovery_command": "uv tool install --force --reinstall x",
+                }
+            )
+        )
+
+    def test_nothing_scheduled(self) -> None:
+        assert collect_finished_deferred_update() is None
+
+    def test_still_waiting_reports_nothing_yet(self, tmp_path: Path) -> None:
+        self._write_marker(tmp_path)
+        assert collect_finished_deferred_update() is None
+        assert (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).exists()
+        assert is_update_pending() is True
+
+    def test_success(self, tmp_path: Path) -> None:
+        self._write_marker(tmp_path)
+        (tmp_path / DEFERRED_UPDATE_EXIT_FILENAME).write_text("0")
+
+        report = collect_finished_deferred_update()
+
+        assert report is not None
+        assert report.status is DeferredUpdateStatus.SUCCEEDED
+        assert report.from_version == "0.76.3"
+        assert report.target_version == "0.76.4"
+        # Reported once: the bookkeeping is gone afterwards.
+        assert not (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).exists()
+        assert not (tmp_path / DEFERRED_UPDATE_EXIT_FILENAME).exists()
+        assert collect_finished_deferred_update() is None
+
+    def test_non_zero_exit_is_a_failure_carrying_recovery(self, tmp_path: Path) -> None:
+        self._write_marker(tmp_path)
+        (tmp_path / DEFERRED_UPDATE_EXIT_FILENAME).write_text("2")
+
+        report = collect_finished_deferred_update()
+
+        assert report is not None
+        assert report.status is DeferredUpdateStatus.FAILED
+        assert report.exit_code == 2
+        assert report.recovery_command == "uv tool install --force --reinstall x"
+
+    def test_abandoned_is_not_a_failure(self, tmp_path: Path) -> None:
+        """Nothing was installed, so the environment is untouched."""
+        self._write_marker(tmp_path)
+        (tmp_path / DEFERRED_UPDATE_EXIT_FILENAME).write_text(DEFERRED_UPDATE_ABANDONED_MARKER)
+
+        report = collect_finished_deferred_update()
+
+        assert report is not None
+        assert report.status is DeferredUpdateStatus.ABANDONED
+
+    def test_unparseable_result_is_treated_as_a_failure(self, tmp_path: Path) -> None:
+        """An unreadable outcome is exactly when the recovery command matters."""
+        self._write_marker(tmp_path)
+        (tmp_path / DEFERRED_UPDATE_EXIT_FILENAME).write_text("something went sideways")
+
+        report = collect_finished_deferred_update()
+
+        assert report is not None
+        assert report.status is DeferredUpdateStatus.FAILED
+
+    def test_helper_that_never_reported_is_reported_as_lost(self, tmp_path: Path) -> None:
+        """Machine rebooted mid-wait: report it once rather than wait forever."""
+        self._write_marker(tmp_path, age_seconds=DEFERRED_UPDATE_STALE_SECONDS + 60)
+
+        report = collect_finished_deferred_update()
+
+        assert report is not None
+        assert report.status is DeferredUpdateStatus.LOST
+        assert not (tmp_path / DEFERRED_UPDATE_MARKER_FILENAME).exists()
+
+    def test_a_stale_marker_does_not_block_a_new_schedule(self, tmp_path: Path) -> None:
+        self._write_marker(tmp_path, age_seconds=DEFERRED_UPDATE_STALE_SECONDS + 60)
+        assert is_update_pending() is False
diff --git a/tests/test_version_service.py b/tests/test_version_service.py
index 0409ae1b..8db32f35 100644
--- a/tests/test_version_service.py
+++ b/tests/test_version_service.py
@@ -1,6 +1,7 @@
 """Tests for VersionService - version detection and update checks."""
 
 import subprocess
+from pathlib import Path
 from unittest.mock import MagicMock, patch
 
 import pytest
@@ -27,6 +28,7 @@
     get_update_timeout,
     resolve_kbagent_wheel_url,
 )
+from keboola_agent_cli.update_runner import DeferredUpdateRequest, InstallRun, InstallStatus
 
 
 class TestIsUvxAvailable:
@@ -766,12 +768,17 @@ def probe_mcp() -> str:
             events.append("mcp_probe")
             return "2.0.0"
 
-        def run(command: list[str], **kwargs: object) -> MagicMock:
+        def install(command: tuple[str, ...], **kwargs: object) -> InstallRun:
             nonlocal mutated
-            assert command == ["uv", "tool", "install"]
+            assert command == ("uv", "tool", "install")
             mutated = True
             events.append("kbagent")
-            return MagicMock(returncode=1, stdout="", stderr="locked")
+            return InstallRun(
+                status=InstallStatus.FAILED,
+                exit_code=1,
+                output="locked",
+                log_path=Path("update.log"),
+            )
 
         monkeypatch.setattr(
             "keboola_agent_cli.services.version_service.prepare_update_plan", prepare
@@ -782,7 +789,10 @@ def run(command: list[str], **kwargs: object) -> MagicMock:
         monkeypatch.setattr(
             "keboola_agent_cli.services.version_service._get_local_mcp_version", probe_mcp
         )
-        monkeypatch.setattr("keboola_agent_cli.services.version_service.subprocess.run", run)
+        monkeypatch.setattr(
+            "keboola_agent_cli.services.version_service.should_defer", lambda: False
+        )
+        monkeypatch.setattr("keboola_agent_cli.services.version_service.run_install", install)
 
         result = VersionService().self_update()
 
@@ -791,6 +801,91 @@ def run(command: list[str], **kwargs: object) -> MagicMock:
         assert result["kbagent"]["updated"] is False
         assert result["kbagent"]["recovery_command"].endswith("exact")
 
+
+class TestSelfUpdateDefersOnWindows:
+    """`kbagent update` must not replace the venv it is running from (#528)."""
+
+    @staticmethod
+    def _plan() -> UpdatePlan:
+        return UpdatePlan(
+            kbagent=KbagentUpdatePlan(
+                current_version="1.0.0",
+                latest_version="2.0.0",
+                up_to_date=False,
+                command=("uv", "tool", "install", "--force", "--reinstall", "keboola-cli @ x"),
+                recovery_command="uv tool install --force --reinstall 'keboola-cli @ x'",
+            ),
+            mcp=McpUpdatePlan(
+                current_version="1.0.0",
+                latest_version="1.0.0",
+                install_method="uv_tool",
+                up_to_date=True,
+                command=None,
+            ),
+        )
+
+    def test_schedules_helper_and_never_installs_inline(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """The install is handed to the detached helper, not run here.
+
+        Running it inline is what deletes the live environment mid-flight and
+        leaves a gutted venv behind, so `run_install` must never be reached.
+        """
+        requests: list[DeferredUpdateRequest] = []
+
+        def schedule(request: DeferredUpdateRequest) -> bool:
+            requests.append(request)
+            return True
+
+        def refuse_inline(*args: object, **kwargs: object) -> InstallRun:
+            raise AssertionError("the installer must not run inside the target environment")
+
+        monkeypatch.setattr(
+            "keboola_agent_cli.services.version_service.prepare_update_plan",
+            lambda **_: self._plan(),
+        )
+        monkeypatch.setattr("keboola_agent_cli.services.version_service.should_defer", lambda: True)
+        monkeypatch.setattr(
+            "keboola_agent_cli.services.version_service.request_deferred_update", schedule
+        )
+        monkeypatch.setattr("keboola_agent_cli.services.version_service.run_install", refuse_inline)
+
+        result = VersionService().self_update()
+
+        assert len(requests) == 1
+        assert requests[0].target_version == "2.0.0"
+        assert requests[0].install_command == self._plan().kbagent.command
+        assert result["kbagent"]["deferred"] is True
+        assert result["kbagent"]["updated"] is False
+        # A scheduled update is not a failure and must not be summarised as one.
+        assert "FAILED" not in result["message"]
+        assert "scheduled" in result["message"]
+
+    def test_unschedulable_hands_the_user_the_command(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """No helper -> tell the user, never fall back to the unsafe install."""
+
+        def refuse_inline(*args: object, **kwargs: object) -> InstallRun:
+            raise AssertionError("the installer must not run inside the target environment")
+
+        monkeypatch.setattr(
+            "keboola_agent_cli.services.version_service.prepare_update_plan",
+            lambda **_: self._plan(),
+        )
+        monkeypatch.setattr("keboola_agent_cli.services.version_service.should_defer", lambda: True)
+        monkeypatch.setattr(
+            "keboola_agent_cli.services.version_service.request_deferred_update", lambda _: False
+        )
+        monkeypatch.setattr("keboola_agent_cli.services.version_service.run_install", refuse_inline)
+
+        result = VersionService().self_update()
+
+        assert result["kbagent"]["deferred"] is False
+        assert result["kbagent"]["updated"] is False
+        assert result["kbagent"]["recovery_command"] in result["kbagent"]["message"]
+
     @patch("keboola_agent_cli.services.version_service._fetch_kbagent_latest_version")
     @patch("keboola_agent_cli.services.version_service._fetch_mcp_latest_version")
     @patch("keboola_agent_cli.services.version_service._get_local_mcp_version")

From 9cfbd4c47363213e59910f84fac98a174485e977 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:31:52 +0200
Subject: [PATCH 2/7] chore(release): 0.77.1 -- deferred Windows self-update
 (#528)

---
 .claude-plugin/marketplace.json               |  2 +-
 plugins/kbagent/.claude-plugin/plugin.json    |  2 +-
 .../skills/kbagent/references/gotchas.md      |  4 ++--
 pyproject.toml                                |  2 +-
 src/keboola_agent_cli/changelog.py            | 24 +++++++++++++++++++
 uv.lock                                       |  2 +-
 6 files changed, 30 insertions(+), 6 deletions(-)

diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index 4469bd24..df5119fd 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -10,7 +10,7 @@
   "plugins": [
     {
       "name": "kbagent",
-      "version": "0.77.0",
+      "version": "0.77.1",
       "source": "./plugins/kbagent",
       "description": "AI-friendly interface to Keboola Connection projects — explore configs, jobs, lineage, call MCP tools, manage dev branches, and debug SQL in workspaces",
       "category": "development"
diff --git a/plugins/kbagent/.claude-plugin/plugin.json b/plugins/kbagent/.claude-plugin/plugin.json
index 55ac266e..64982931 100644
--- a/plugins/kbagent/.claude-plugin/plugin.json
+++ b/plugins/kbagent/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
 {
   "name": "kbagent",
-  "version": "0.77.0",
+  "version": "0.77.1",
   "description": "AI-friendly interface to Keboola Connection projects — explore configs, jobs, lineage, call MCP tools, manage dev branches, and debug SQL in workspaces",
   "author": {
     "name": "Keboola",
diff --git a/plugins/kbagent/skills/kbagent/references/gotchas.md b/plugins/kbagent/skills/kbagent/references/gotchas.md
index cb6f8347..dd3057c6 100644
--- a/plugins/kbagent/skills/kbagent/references/gotchas.md
+++ b/plugins/kbagent/skills/kbagent/references/gotchas.md
@@ -2138,7 +2138,7 @@ transparent -- no user action is normally required.
 - Never crashes the CLI -- update failures leave the current invocation running
   and print a recovery command (since v0.76.2)
 
-### Windows updates are deferred, not immediate (since v0.76.4)
+### Windows updates are deferred, not immediate (since v0.77.1)
 
 `uv tool install` recreates a tool environment by **removing** it and then
 building a fresh venv at the same path. It is not atomic and has no rollback.
@@ -2164,7 +2164,7 @@ So on Windows kbagent never installs into its own live environment:
 - `KBAGENT_DEFER_UPDATE=1` / `=0` forces the deferred path on or off,
   overriding the platform default.
 
-A slow install is never killed on any platform (also since v0.76.4): the
+A slow install is never killed on any platform (also since v0.77.1): the
 timeout bounds only how long kbagent waits, because terminating uv mid-write
 produces the same half-deleted environment a file lock does. When that happens
 the banner says the install is *still running* and deliberately offers no
diff --git a/pyproject.toml b/pyproject.toml
index f38557b2..5dea558e 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "keboola-cli"
-version = "0.77.0"
+version = "0.77.1"
 description = "AI-friendly CLI for managing Keboola projects"
 readme = "README.md"
 requires-python = ">=3.12"
diff --git a/src/keboola_agent_cli/changelog.py b/src/keboola_agent_cli/changelog.py
index 479b4a8f..df9b67d3 100644
--- a/src/keboola_agent_cli/changelog.py
+++ b/src/keboola_agent_cli/changelog.py
@@ -24,6 +24,30 @@
 
 # Ordered newest-first.  Each value is a list of brief one-line descriptions.
 CHANGELOG: dict[str, list[str]] = {
+    "0.77.1": [
+        "Fix (#528): the Windows self-update no longer corrupts the uv tool environment. "
+        "`uv tool install` recreates a tool environment by REMOVING it and then building a fresh "
+        "venv at the same path -- it is not atomic and has no rollback. On POSIX that is harmless, "
+        "but on Windows uv's `kbagent.exe` trampoline holds the venv interpreter locked, so the "
+        "removal deletes what it can, hits a locked file, and aborts -- leaving a gutted venv "
+        "(`No module named 'rich._windows'`, `cannot import name 'rich_utils' from 'typer'`). "
+        "The v0.76.2 fix reordered the update but still ran the install from inside the "
+        "environment being replaced, so the corruption survived it. kbagent now hands the "
+        "reinstall to a detached helper that waits until every kbagent process has exited and "
+        "only then installs; the outcome (including a copy-paste recovery command on failure) is "
+        "reported on the next launch. POSIX keeps the proven inline install plus re-exec. "
+        "Thanks to @papousek-radan for three rounds of precise Windows reports.",
+        "Fix (#528): a slow install is no longer killed mid-write. Both update paths used "
+        "`subprocess.run(timeout=...)`, which terminates the child when the deadline passes -- on "
+        "Windows a hard `TerminateProcess` of uv part-way through recreating a venv, producing "
+        "exactly the same half-deleted environment a file lock does. The deadline now bounds only "
+        "how long kbagent waits; the installer is left to finish the transaction it started, and "
+        "the banner says so instead of offering a recovery command that would start a second "
+        "installer against the same environment.",
+        "New (#528): `KBAGENT_DEFER_UPDATE` forces the out-of-process update path on (`1`) or off "
+        "(`0`), overriding the platform default. Intended for reproducing the deferred flow on "
+        "POSIX and as an escape hatch on Windows.",
+    ],
     "0.77.0": [
         "New (#505): `kbagent config update` and `kbagent config row-update` accept "
         "`--change-description TEXT`, which writes the new config version's "
diff --git a/uv.lock b/uv.lock
index 4e9766b7..da3555e0 100644
--- a/uv.lock
+++ b/uv.lock
@@ -590,7 +590,7 @@ wheels = [
 
 [[package]]
 name = "keboola-cli"
-version = "0.77.0"
+version = "0.77.1"
 source = { editable = "." }
 dependencies = [
     { name = "croniter" },

From 043c81580c7adbcd6ac53ebf6b1d519027cb001f Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:37:50 +0200
Subject: [PATCH 3/7] test(update): run the deferred-update helper for real on
 Windows CI (#528)

The waiter is a PowerShell script authored on machines that cannot execute
it, so the unit tests can only pin its text. The repo already runs a
windows-latest job for the #320/#529 regressions; extend it to run the
update-runner suite, plus three Windows-only tests that execute the
generated script against a stand-in installer:

- the installer's exit code is recorded,
- a failing installer is reported rather than swallowed,
- nothing is installed while a watched process is still alive -- the
  branch that actually protects the environment.

This also exercises `should_defer()` returning its real Windows default
and a real detached spawn.
---
 .github/workflows/ci.yml    |  12 +++-
 tests/test_update_runner.py | 110 ++++++++++++++++++++++++++++++++++++
 2 files changed, 121 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
index 780b7273..5130eb34 100644
--- a/.github/workflows/ci.yml
+++ b/.github/workflows/ci.yml
@@ -136,7 +136,7 @@ jobs:
   # `npm.cmd` invocation (Bug 1) and the force-include path resolution (Bug 2)
   # are exercised against a real `uv build` rather than mocks.
   build-windows:
-    name: Windows wheel build and export regression (issues #320, #529)
+    name: Windows wheel build, export and self-update regressions (issues #320, #529, #528)
     runs-on: windows-latest
     steps:
       - uses: actions/checkout@v5
@@ -172,6 +172,16 @@ jobs:
       - name: Test semantic-layer export on Windows (issue #529)
         run: uv run pytest tests/test_semantic_layer_service.py -k "export" -v
 
+      # The self-update helper is a PowerShell script authored on machines that
+      # cannot execute it. This suite runs it for real: it proves the script
+      # parses, that it records the installer's exit code, and -- the branch
+      # that actually protects the environment -- that it installs NOTHING
+      # while a watched process is still alive (issue #528). The rest of the
+      # suite also runs here with `should_defer()` returning its real Windows
+      # default and a real detached spawn.
+      - name: Test the deferred self-update helper on Windows (issue #528)
+        run: uv run pytest tests/test_update_runner.py -v
+
       - name: Assert the SPA is bundled (Bug 1 fixed)
         run: python scripts/check_wheel_ui.py --expect-ui
 
diff --git a/tests/test_update_runner.py b/tests/test_update_runner.py
index 3b17f9a9..99cb8eba 100644
--- a/tests/test_update_runner.py
+++ b/tests/test_update_runner.py
@@ -8,6 +8,7 @@
 """
 
 import json
+import os
 import subprocess
 import sys
 import time
@@ -32,6 +33,7 @@
     is_update_pending,
     quote_for_powershell,
     request_deferred_update,
+    resolve_powershell,
     run_install,
     should_defer,
 )
@@ -355,3 +357,111 @@ def test_helper_that_never_reported_is_reported_as_lost(self, tmp_path: Path) ->
     def test_a_stale_marker_does_not_block_a_new_schedule(self, tmp_path: Path) -> None:
         self._write_marker(tmp_path, age_seconds=DEFERRED_UPDATE_STALE_SECONDS + 60)
         assert is_update_pending() is False
+
+
+@pytest.mark.skipif(os.name != "nt", reason="exercises the real PowerShell helper")
+class TestWaiterScriptOnWindows:
+    """Run the generated helper for real on the Windows CI runner.
+
+    Everything above pins the script's *text*. This runs it, which is the only
+    way to know the PowerShell actually parses and behaves -- the script is
+    authored on machines that cannot execute it.
+    """
+
+    @staticmethod
+    def _already_exited_pid() -> int:
+        """A PID that is guaranteed gone, so `Wait-Process` takes its error path."""
+        process = subprocess.Popen([sys.executable, "-c", "pass"])
+        process.wait()
+        return process.pid
+
+    def _run_helper(self, script: str) -> None:
+        powershell = resolve_powershell()
+        assert powershell is not None, "Windows must always provide an in-box PowerShell"
+        subprocess.run(build_helper_command(powershell, script), check=True, timeout=180)
+
+    def test_installer_exit_code_is_recorded(self, tmp_path: Path) -> None:
+        exit_file = tmp_path / DEFERRED_UPDATE_EXIT_FILENAME
+        install_log = tmp_path / "install.log"
+        request = DeferredUpdateRequest(
+            from_version="1.0.0",
+            target_version="2.0.0",
+            install_command=(sys.executable, "-c", "print('installed')"),
+            recovery_command=None,
+        )
+
+        self._run_helper(
+            build_waiter_script(
+                request,
+                pid=self._already_exited_pid(),
+                exit_file=exit_file,
+                install_log=install_log,
+                max_wait_seconds=60,
+                poll_seconds=1,
+                # Nothing is named `kbagent` on the runner, so the wait loop
+                # falls straight through to the install.
+                process_name="kbagent",
+            )
+        )
+
+        assert exit_file.read_text().strip() == "0"
+        assert "installed" in install_log.read_text()
+
+    def test_failing_installer_is_reported_not_swallowed(self, tmp_path: Path) -> None:
+        exit_file = tmp_path / DEFERRED_UPDATE_EXIT_FILENAME
+        request = DeferredUpdateRequest(
+            from_version="1.0.0",
+            target_version="2.0.0",
+            install_command=(sys.executable, "-c", "import sys; sys.exit(3)"),
+            recovery_command=None,
+        )
+
+        self._run_helper(
+            build_waiter_script(
+                request,
+                pid=self._already_exited_pid(),
+                exit_file=exit_file,
+                install_log=tmp_path / "install.log",
+                max_wait_seconds=60,
+                poll_seconds=1,
+                process_name="kbagent",
+            )
+        )
+
+        assert exit_file.read_text().strip() == "3"
+
+    def test_gives_up_without_installing_while_a_process_is_still_running(
+        self, tmp_path: Path
+    ) -> None:
+        """The branch that protects the environment: something is still holding it.
+
+        Watching this very interpreter's own name guarantees the loop keeps
+        finding a live process, which is the situation a `kbagent serve` creates.
+        """
+        exit_file = tmp_path / DEFERRED_UPDATE_EXIT_FILENAME
+        sentinel = tmp_path / "must-not-exist.txt"
+        request = DeferredUpdateRequest(
+            from_version="1.0.0",
+            target_version="2.0.0",
+            install_command=(
+                sys.executable,
+                "-c",
+                f"import pathlib; pathlib.Path({str(sentinel)!r}).write_text('ran')",
+            ),
+            recovery_command=None,
+        )
+
+        self._run_helper(
+            build_waiter_script(
+                request,
+                pid=self._already_exited_pid(),
+                exit_file=exit_file,
+                install_log=tmp_path / "install.log",
+                max_wait_seconds=3,
+                poll_seconds=1,
+                process_name=Path(sys.executable).stem,
+            )
+        )
+
+        assert exit_file.read_text().strip() == DEFERRED_UPDATE_ABANDONED_MARKER
+        assert not sentinel.exists(), "the installer must not touch a live environment"

From f54ee5a612501e3475b1df8ff61be9eced39b7f6 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:43:38 +0200
Subject: [PATCH 4/7] fix(update): write the deferred-update log as UTF-8, not
 UTF-16LE (#528)

Caught by the Windows CI job added in the previous commit -- the only
place the helper actually executes.

Windows PowerShell 5.1 writes redirection operators (`>`, `>>`, `*>>`) as
UTF-16LE with a BOM. The helper redirected the installer's output into
the shared install log with `*>>`, but every other writer and reader of
that file -- `run_install`, `_tail`, and the user we point at it --
assumes UTF-8. The log came out as mojibake.

The installer's output now goes through
`[System.IO.File]::AppendAllText` with `UTF8Encoding($false)`, so the log
is plain UTF-8 with no BOM regardless of writer. `$LASTEXITCODE` is
captured into `$code` immediately after the installer, before anything
else can run.

The Windows test now asserts the log is UTF-8 and carries no UTF-16 BOM,
so this cannot regress silently.
---
 src/keboola_agent_cli/update_runner.py | 19 ++++++++++--
 tests/test_update_runner.py            | 41 +++++++++++++++++++-------
 2 files changed, 46 insertions(+), 14 deletions(-)

diff --git a/src/keboola_agent_cli/update_runner.py b/src/keboola_agent_cli/update_runner.py
index 858f1d85..e4335e7f 100644
--- a/src/keboola_agent_cli/update_runner.py
+++ b/src/keboola_agent_cli/update_runner.py
@@ -271,6 +271,12 @@ def build_waiter_script(
     it gave up. Doing nothing is always safe here; the update simply retries on
     a later run.
 
+    The installer's output is appended through ``UTF8Encoding($false)`` rather
+    than a ``*>>`` redirection. Windows PowerShell 5.1 writes redirections as
+    **UTF-16LE with a BOM**, which made the shared install log unreadable as the
+    UTF-8 every other writer and reader of that file assumes -- caught by the
+    Windows CI job, which is the only place the helper actually executes.
+
     Returns:
         A self-contained script suitable for ``powershell.exe -Command``.
     """
@@ -295,10 +301,17 @@ def build_waiter_script(
             f"    Set-Content -LiteralPath $exitFile -Value {abandoned_literal}",
             "    exit 0",
             "  }",
-            f"  & {quoted_argv} *>> $logFile",
-            "  Set-Content -LiteralPath $exitFile -Value ([string]$LASTEXITCODE)",
+            # -Width keeps Out-String from wrapping uv's output at the default
+            # console width and mangling long requirement lines in the log.
+            f"  $output = (& {quoted_argv} 2>&1 | Out-String -Width 4096)",
+            # Captured before anything else runs, so nothing can clobber it.
+            "  $code = $LASTEXITCODE",
+            "  [System.IO.File]::AppendAllText("
+            "$logFile, $output, (New-Object System.Text.UTF8Encoding $false))",
+            "  Set-Content -LiteralPath $exitFile -Value ([string]$code)",
             "} catch {",
-            "  $_ | Out-File -FilePath $logFile -Append",
+            "  [System.IO.File]::AppendAllText("
+            "$logFile, ($_ | Out-String -Width 4096), (New-Object System.Text.UTF8Encoding $false))",
             "  Set-Content -LiteralPath $exitFile -Value 'failed'",
             "}",
         ]
diff --git a/tests/test_update_runner.py b/tests/test_update_runner.py
index 99cb8eba..21ca37a3 100644
--- a/tests/test_update_runner.py
+++ b/tests/test_update_runner.py
@@ -1,10 +1,15 @@
 """Tests for the self-reinstall runner (issue #528).
 
-The failure these guard against is not observable on the CI platforms: it needs
-a Windows file lock on a running `uv tool` environment. So the contracts are
-pinned structurally instead -- the waiter script's text, the scheduling
-bookkeeping, and the one behaviour that *is* directly observable everywhere:
-that a slow installer is never killed.
+The original corruption is not reproducible here -- it needs a real `uv tool
+install` losing a race against a real Windows file lock on a live environment.
+So most contracts are pinned structurally: the waiter script's text, the
+scheduling bookkeeping, and the one behaviour observable everywhere, that a slow
+installer is never killed.
+
+``TestWaiterScriptOnWindows`` goes further and *executes* the generated
+PowerShell on the windows-latest CI runner, which is the only place it runs at
+all. That is not decoration -- it is what caught the helper writing its log as
+UTF-16LE.
 """
 
 import json
@@ -180,10 +185,21 @@ def test_gives_up_without_installing_when_kbagent_never_exits(self, script: str)
 
     def test_installs_the_exact_prepared_command(self, script: str) -> None:
         expected = " ".join(quote_for_powershell(part) for part in REQUEST.install_command)
-        assert f"& {expected} *>> $logFile" in script
+        assert f"$output = (& {expected} 2>&1 | Out-String -Width 4096)" in script
+
+    def test_writes_the_log_as_utf8_not_a_redirection(self, script: str) -> None:
+        """PowerShell 5.1 redirections are UTF-16LE; the log must be UTF-8.
+
+        Every other writer and reader of that file assumes UTF-8, so a `*>>`
+        redirection made it unreadable (caught by the Windows CI job).
+        """
+        assert "*>>" not in script
+        assert "New-Object System.Text.UTF8Encoding $false" in script
 
     def test_records_the_installer_exit_code(self, script: str) -> None:
-        assert "Set-Content -LiteralPath $exitFile -Value ([string]$LASTEXITCODE)" in script
+        # Captured immediately after the installer, before anything else runs.
+        assert "$code = $LASTEXITCODE" in script
+        assert "Set-Content -LiteralPath $exitFile -Value ([string]$code)" in script
 
     def test_a_powershell_level_error_is_recorded_as_a_failure(self, script: str) -> None:
         assert "Set-Content -LiteralPath $exitFile -Value 'failed'" in script
@@ -404,8 +420,11 @@ def test_installer_exit_code_is_recorded(self, tmp_path: Path) -> None:
             )
         )
 
-        assert exit_file.read_text().strip() == "0"
-        assert "installed" in install_log.read_text()
+        assert exit_file.read_text(encoding="utf-8").strip() == "0"
+        # The log must be plain UTF-8. PowerShell 5.1's `*>>` wrote UTF-16LE
+        # with a BOM, which `_tail` -- and the user -- read as mojibake.
+        assert not install_log.read_bytes().startswith(b"\xff\xfe")
+        assert "installed" in install_log.read_text(encoding="utf-8")
 
     def test_failing_installer_is_reported_not_swallowed(self, tmp_path: Path) -> None:
         exit_file = tmp_path / DEFERRED_UPDATE_EXIT_FILENAME
@@ -428,7 +447,7 @@ def test_failing_installer_is_reported_not_swallowed(self, tmp_path: Path) -> No
             )
         )
 
-        assert exit_file.read_text().strip() == "3"
+        assert exit_file.read_text(encoding="utf-8").strip() == "3"
 
     def test_gives_up_without_installing_while_a_process_is_still_running(
         self, tmp_path: Path
@@ -463,5 +482,5 @@ def test_gives_up_without_installing_while_a_process_is_still_running(
             )
         )
 
-        assert exit_file.read_text().strip() == DEFERRED_UPDATE_ABANDONED_MARKER
+        assert exit_file.read_text(encoding="utf-8").strip() == DEFERRED_UPDATE_ABANDONED_MARKER
         assert not sentinel.exists(), "the installer must not touch a live environment"

From 957b80139f199c9881af3e7bb777e09e96501ebb Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:45:16 +0200
Subject: [PATCH 5/7] refactor(update): classify a deferred result by whether
 the helper reported (#528)

_classify_exit took `marker_is_stale`, but the caller passed
`raw_exit is None` -- which is also true when the exit file exists and
merely could not be read. That case was labelled LOST ("the helper
vanished") when what actually happened is that the helper reported
something unusable, i.e. a FAILED install.

The predicate is now `helper_reported`, derived from whether an exit file
existed at all, so each status means what it says. Both already offered
recovery, so this changes wording rather than behaviour -- but the
parameter was lying about its own meaning.
---
 src/keboola_agent_cli/update_runner.py | 20 +++++++++++++++-----
 1 file changed, 15 insertions(+), 5 deletions(-)

diff --git a/src/keboola_agent_cli/update_runner.py b/src/keboola_agent_cli/update_runner.py
index e4335e7f..8b7fac14 100644
--- a/src/keboola_agent_cli/update_runner.py
+++ b/src/keboola_agent_cli/update_runner.py
@@ -468,18 +468,21 @@ def collect_finished_deferred_update() -> DeferredUpdateReport | None:
         return None
 
     exit_file = _exit_path()
+    reported = exit_file.is_file()
     raw_exit: str | None = None
-    if exit_file.is_file():
+    if reported:
         try:
             raw_exit = exit_file.read_text(encoding="utf-8").strip()
         except OSError:
-            raw_exit = None
+            # The helper reported, we just cannot read it. That is a failure to
+            # surface, not a helper that vanished.
+            logger.debug("Could not read the deferred-update exit file", exc_info=True)
     elif not _marker_is_stale(marker):
         return None  # helper is still waiting for kbagent to exit
 
     _clear_deferred_state()
 
-    status, exit_code = _classify_exit(raw_exit, marker_is_stale=raw_exit is None)
+    status, exit_code = _classify_exit(raw_exit, helper_reported=reported)
     return DeferredUpdateReport(
         status=status,
         from_version=str(marker.get("from_version") or "unknown"),
@@ -491,16 +494,23 @@ def collect_finished_deferred_update() -> DeferredUpdateReport | None:
 
 
 def _classify_exit(
-    raw_exit: str | None, *, marker_is_stale: bool
+    raw_exit: str | None, *, helper_reported: bool
 ) -> tuple[DeferredUpdateStatus, int | None]:
     """Map the helper's exit file to a status.
 
     Anything that is neither a clean exit code nor the explicit "gave up"
     marker counts as a failure -- an unparseable result is exactly the case
     where the user needs the recovery command, so it must not be optimistic.
+
+    Args:
+        raw_exit: Contents of the exit file, or None when there was nothing
+            readable there.
+        helper_reported: Whether an exit file existed at all. A helper that
+            wrote something unreadable FAILED; one that never wrote at all is
+            LOST (killed, or the machine rebooted mid-wait).
     """
     if raw_exit is None:
-        return (DeferredUpdateStatus.LOST if marker_is_stale else DeferredUpdateStatus.FAILED), None
+        return (DeferredUpdateStatus.FAILED if helper_reported else DeferredUpdateStatus.LOST), None
     if raw_exit == DEFERRED_UPDATE_ABANDONED_MARKER:
         return DeferredUpdateStatus.ABANDONED, None
     try:

From 7765031473ee589aca7077ec02bd410998e715c6 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 18:49:33 +0200
Subject: [PATCH 6/7] fix(update): stop killing the keboola-mcp-server upgrade
 too (#528)

The no-kill fix covered the two kbagent paths but left the MCP upgrade
two functions away still on `subprocess.run(timeout=...)`, which
terminates uv at 180s. The MCP environment is not the one kbagent runs
from, so no file lock is involved -- but a killed installer leaves it
half-recreated exactly the same way, and what stops working is
`kbagent tool call`.

`_perform_mcp_update` now goes through `run_install`, so the deadline
bounds only how long kbagent waits. A slow upgrade reports "still
running" instead of the untrue "timed out".

Read-only probes (`keboola_mcp_server --version`, `uv tool list`) keep
their ordinary timeouts -- killing a probe is harmless.
---
 src/keboola_agent_cli/changelog.py            |  7 ++-
 .../services/version_service.py               | 30 +++++-----
 tests/test_version_service.py                 | 58 ++++++++++++-------
 3 files changed, 57 insertions(+), 38 deletions(-)

diff --git a/src/keboola_agent_cli/changelog.py b/src/keboola_agent_cli/changelog.py
index df9b67d3..09925e98 100644
--- a/src/keboola_agent_cli/changelog.py
+++ b/src/keboola_agent_cli/changelog.py
@@ -37,13 +37,16 @@
         "only then installs; the outcome (including a copy-paste recovery command on failure) is "
         "reported on the next launch. POSIX keeps the proven inline install plus re-exec. "
         "Thanks to @papousek-radan for three rounds of precise Windows reports.",
-        "Fix (#528): a slow install is no longer killed mid-write. Both update paths used "
+        "Fix (#528): a slow install is no longer killed mid-write. Every update path used "
         "`subprocess.run(timeout=...)`, which terminates the child when the deadline passes -- on "
         "Windows a hard `TerminateProcess` of uv part-way through recreating a venv, producing "
         "exactly the same half-deleted environment a file lock does. The deadline now bounds only "
         "how long kbagent waits; the installer is left to finish the transaction it started, and "
         "the banner says so instead of offering a recovery command that would start a second "
-        "installer against the same environment.",
+        "installer against the same environment. This covers the keboola-mcp-server upgrade too: "
+        "that environment is not the one kbagent runs from, so no lock is involved, but a killed "
+        "installer leaves it just as broken and `kbagent tool call` is what stops working. "
+        "Read-only version probes still time out normally -- killing a probe is harmless.",
         "New (#528): `KBAGENT_DEFER_UPDATE` forces the out-of-process update path on (`1`) or off "
         "(`0`), overriding the platform default. Intended for reproducing the deferred flow on "
         "POSIX and as an escape hatch on Windows.",
diff --git a/src/keboola_agent_cli/services/version_service.py b/src/keboola_agent_cli/services/version_service.py
index 09cf967f..9a3212b2 100644
--- a/src/keboola_agent_cli/services/version_service.py
+++ b/src/keboola_agent_cli/services/version_service.py
@@ -513,10 +513,17 @@ def _perform_mcp_update(
 ) -> tuple[bool, str]:
     """Run the appropriate upgrade command for keboola-mcp-server.
 
+    Goes through :func:`run_install`, so a slow upgrade is never terminated
+    (issue #528). The MCP environment is not the one kbagent runs from, so the
+    Windows file-lock problem does not apply here -- but killing uv part-way
+    through recreating *any* tool environment leaves it half-written, and that
+    would break ``kbagent tool call`` until the user reinstalled MCP by hand.
+
     Args:
         method: Optional install method; if None, detect via
             :func:`_detect_mcp_install_method`.
-        timeout: Subprocess timeout in seconds.
+        timeout: How long to wait before giving up on the wait -- not on the
+            upgrade, which is left running.
         command: Prepared command. Supplying it guarantees this apply phase
             does not probe PATH or rebuild commands.
 
@@ -539,20 +546,15 @@ def _perform_mcp_update(
             return False, "pip not found on PATH"
         return False, f"could not build MCP upgrade command for {method!r}"
 
-    try:
-        result = subprocess.run(
-            cmd,
-            capture_output=True,
-            text=True,
-            timeout=timeout,
+    run = run_install(tuple(cmd), timeout=timeout)
+    if run.status is InstallStatus.SUCCEEDED:
+        return True, run.output
+    if run.status is InstallStatus.STILL_RUNNING:
+        return False, (
+            f"still running after {int(timeout)}s; it continues in the background "
+            f"and applies on the next launch (log: {run.log_path})"
         )
-        if result.returncode == 0:
-            return True, (result.stdout or "").strip()
-        return False, (result.stderr or "").strip() or "upgrade subprocess failed"
-    except subprocess.TimeoutExpired:
-        return False, f"upgrade timed out after {timeout}s"
-    except OSError as exc:
-        return False, f"subprocess error: {exc}"
+    return False, run.output or "upgrade subprocess failed"
 
 
 def build_mcp_upgrade_command(method: str) -> list[str] | None:
diff --git a/tests/test_version_service.py b/tests/test_version_service.py
index 8db32f35..9bf04659 100644
--- a/tests/test_version_service.py
+++ b/tests/test_version_service.py
@@ -581,40 +581,47 @@ def test_none_when_nothing_available(self, mock_which: MagicMock) -> None:
 # ---------------------------------------------------------------------------
 
 
+def _mcp_install_run(status: InstallStatus, output: str, exit_code: int | None = 0) -> InstallRun:
+    """An :class:`InstallRun` stand-in for a mocked MCP upgrade."""
+    return InstallRun(
+        status=status, exit_code=exit_code, output=output, log_path=Path("update.log")
+    )
+
+
 class TestPerformMcpUpdate:
     """Tests for ``_perform_mcp_update``."""
 
     @patch("keboola_agent_cli.services.version_service.shutil.which")
-    @patch("keboola_agent_cli.services.version_service.subprocess.run")
-    def test_uv_tool_success(self, mock_run: MagicMock, mock_which: MagicMock) -> None:
+    @patch("keboola_agent_cli.services.version_service.run_install")
+    def test_uv_tool_success(self, mock_install: MagicMock, mock_which: MagicMock) -> None:
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.return_value = MagicMock(returncode=0, stdout="upgraded", stderr="")
+        mock_install.return_value = _mcp_install_run(InstallStatus.SUCCEEDED, "upgraded")
         ok, info = _perform_mcp_update(method="uv_tool")
         assert ok is True
         assert "upgraded" in info
         # Verify the command shape we are about to run.
-        cmd = mock_run.call_args.args[0]
+        cmd = mock_install.call_args.args[0]
         assert "tool" in cmd and "upgrade" in cmd and MCP_PACKAGE_NAME in cmd
         # issue #324: the pre-release opt-in is mandatory -- without it uv
         # backtracks to a stale MCP (toon-format~=0.9.0b1 pin) and exits 0.
         assert "--prerelease=allow" in cmd
 
     @patch("keboola_agent_cli.services.version_service.shutil.which")
-    @patch("keboola_agent_cli.services.version_service.subprocess.run")
-    def test_pip_env_success(self, mock_run: MagicMock, mock_which: MagicMock) -> None:
+    @patch("keboola_agent_cli.services.version_service.run_install")
+    def test_pip_env_success(self, mock_install: MagicMock, mock_which: MagicMock) -> None:
         mock_which.return_value = "/usr/local/bin/pip"
-        mock_run.return_value = MagicMock(returncode=0, stdout="upgraded via pip", stderr="")
+        mock_install.return_value = _mcp_install_run(InstallStatus.SUCCEEDED, "upgraded via pip")
         ok, _info = _perform_mcp_update(method="pip_env")
         assert ok is True
-        cmd = mock_run.call_args.args[0]
+        cmd = mock_install.call_args.args[0]
         assert "install" in cmd and "--upgrade" in cmd
         # issue #324: pip's pre-release opt-in flag is --pre.
         assert "--pre" in cmd
 
     @patch("keboola_agent_cli.services.version_service.shutil.which")
-    @patch("keboola_agent_cli.services.version_service.subprocess.run")
+    @patch("keboola_agent_cli.services.version_service.run_install")
     def test_uvx_promotes_to_uv_tool_install(
-        self, mock_run: MagicMock, mock_which: MagicMock
+        self, mock_install: MagicMock, mock_which: MagicMock
     ) -> None:
         """Bug B fix from issue #263: uvx-cache install is promoted to a
         persistent ``uv tool install --upgrade``.
@@ -630,10 +637,10 @@ def test_uvx_promotes_to_uv_tool_install(
         runs use the faster ``uv_tool`` detection path.
         """
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.return_value = MagicMock(returncode=0, stdout="installed", stderr="")
+        mock_install.return_value = _mcp_install_run(InstallStatus.SUCCEEDED, "installed")
         ok, _info = _perform_mcp_update(method="uvx")
         assert ok is True
-        cmd = mock_run.call_args.args[0]
+        cmd = mock_install.call_args.args[0]
         assert "tool" in cmd and "install" in cmd and "--upgrade" in cmd
         assert MCP_PACKAGE_NAME in cmd
         # The broken --version arg must be GONE from the uvx upgrade path.
@@ -654,15 +661,22 @@ def test_none_returns_false(self) -> None:
         assert "not installed" in info
 
     @patch("keboola_agent_cli.services.version_service.shutil.which")
-    @patch(
-        "keboola_agent_cli.services.version_service.subprocess.run",
-        side_effect=subprocess.TimeoutExpired(cmd="x", timeout=MCP_UPGRADE_TIMEOUT),
-    )
-    def test_timeout(self, mock_run: MagicMock, mock_which: MagicMock) -> None:
+    @patch("keboola_agent_cli.services.version_service.run_install")
+    def test_slow_upgrade_is_left_running_not_killed(
+        self, mock_install: MagicMock, mock_which: MagicMock
+    ) -> None:
+        """Issue #528: terminating uv mid-write half-recreates the MCP env.
+
+        The MCP environment is not the one kbagent runs from, so no file lock
+        is involved -- but a killed installer leaves it just as broken, and
+        `kbagent tool call` is what stops working.
+        """
         mock_which.return_value = "/usr/local/bin/uv"
+        mock_install.return_value = _mcp_install_run(InstallStatus.STILL_RUNNING, "", None)
         ok, info = _perform_mcp_update(method="uv_tool", timeout=MCP_UPGRADE_TIMEOUT)
         assert ok is False
-        assert "timed out" in info
+        assert "still running" in info
+        assert "timed out" not in info
 
 
 # ---------------------------------------------------------------------------
@@ -1407,21 +1421,21 @@ class TestMcpPrereleaseOptIn:
         ],
     )
     @patch("keboola_agent_cli.services.version_service.shutil.which")
-    @patch("keboola_agent_cli.services.version_service.subprocess.run")
+    @patch("keboola_agent_cli.services.version_service.run_install")
     def test_internal_upgrade_command_opts_into_prereleases(
         self,
-        mock_run: MagicMock,
+        mock_install: MagicMock,
         mock_which: MagicMock,
         method: str,
         expected_flag: str,
     ) -> None:
         mock_which.return_value = "/usr/local/bin/uv"
-        mock_run.return_value = MagicMock(returncode=0, stdout="ok", stderr="")
+        mock_install.return_value = _mcp_install_run(InstallStatus.SUCCEEDED, "ok")
 
         ok, _info = _perform_mcp_update(method=method)
 
         assert ok is True
-        cmd = mock_run.call_args.args[0]
+        cmd = mock_install.call_args.args[0]
         assert expected_flag in cmd, f"{method} command missing {expected_flag}: {cmd}"
         assert MCP_PACKAGE_NAME in cmd
 

From d1f0c4d2d2fccc464b3c47cdf9822d2e82b55321 Mon Sep 17 00:00:00 2001
From: Petr <petr@keboola.com>
Date: Wed, 29 Jul 2026 19:06:07 +0200
Subject: [PATCH 7/7] fix(update): report each run's own output, and stop
 calling "not yet" a failure (#528)

Four review findings, all cases of a message not matching what happened.

1. `run_install` appended to one shared log and reported `_tail` of the
   whole file, so a run's `output` carried text it did not produce. This
   regressed the pre-change `capture_output=True` per-run capture, and
   routing the MCP upgrade through the same runner made it reachable
   within a single `kbagent update`: the MCP stage writes seconds before
   the kbagent stage reads. The offset the run starts at is now recorded
   before spawning, and only bytes past it are read. The log itself still
   keeps every run -- that is the diagnosis -- but is rolled once it
   passes a size cap, since every update appends to it forever.

2. A STILL_RUNNING install fell through to `_compose_update_summary`'s
   failure branch and rendered as "kbagent v0.77.0 update FAILED: Update
   still running ...", contradicting itself mid-sentence and the banner
   `auto_update` already got right. It now carries an explicit
   `still_running` flag and reads "(still installing)".

3. The extra human-mode stage message fired on the unschedulable branch
   too, whose message the summary already quotes verbatim -- the user was
   told the same thing twice. Now gated to the scheduled case, which is
   the only one the summary truncates to "(scheduled)".

4. `_classify_exit` returned a bare two-element tuple of semantically
   distinct values, which CONTRIBUTING.md forbids for new code. It
   returns a frozen `ClassifiedExit` instead.

Also strengthens the no-kill test to assert the log is readable while the
child still holds it open and the parent has closed its handle -- the
Windows file-sharing question raised in review, now answered by the
Windows CI job rather than by argument.
---
 src/keboola_agent_cli/commands/version.py     |  5 +-
 src/keboola_agent_cli/constants.py            |  7 ++
 .../services/version_service.py               | 16 +++-
 src/keboola_agent_cli/update_runner.py        | 77 +++++++++++++++----
 tests/test_update_runner.py                   | 46 ++++++++++-
 tests/test_version_service.py                 | 42 ++++++++++
 6 files changed, 172 insertions(+), 21 deletions(-)

diff --git a/src/keboola_agent_cli/commands/version.py b/src/keboola_agent_cli/commands/version.py
index 2c991a20..0fda2f49 100644
--- a/src/keboola_agent_cli/commands/version.py
+++ b/src/keboola_agent_cli/commands/version.py
@@ -181,8 +181,11 @@ def update_command(
         # The summary line only says "(scheduled)". What the user has to *do*
         # -- close other kbagent processes -- lives on the stage result, so
         # print that too rather than leave the instruction in JSON only.
+        # Only for the scheduled case: every other branch already has its
+        # message carried into the summary verbatim, so printing it here again
+        # would just repeat the same sentence back at the user.
         kbagent_stage = result.get("kbagent", {})
-        if kbagent_stage.get("deferred") is not None and not kbagent_stage.get("updated"):
+        if kbagent_stage.get("deferred") is True:
             formatter.console.print(kbagent_stage["message"])
 
 
diff --git a/src/keboola_agent_cli/constants.py b/src/keboola_agent_cli/constants.py
index 327ef517..8aecfd0d 100644
--- a/src/keboola_agent_cli/constants.py
+++ b/src/keboola_agent_cli/constants.py
@@ -337,6 +337,13 @@ def _resolve_app_name() -> str:
 DEFERRED_UPDATE_MARKER_FILENAME: str = "pending_update.json"
 DEFERRED_UPDATE_EXIT_FILENAME: str = "pending_update.exit"
 DEFERRED_UPDATE_LOG_FILENAME: str = "pending_update.log"
+# The install log is appended to by every update (kbagent and MCP, inline and
+# deferred), so it is rolled once it passes this size rather than growing for
+# the life of the install.
+DEFERRED_UPDATE_LOG_MAX_BYTES: int = 1_048_576
+# How much of a run's own output is carried back in the result. Only the bytes
+# this run appended are ever read, so this bounds one transcript, not the file.
+DEFERRED_UPDATE_OUTPUT_MAX_CHARS: int = 4000
 # Written by the helper into the exit file when kbagent never stopped running
 # within the wait window, so nothing was installed and nothing was mutated.
 DEFERRED_UPDATE_ABANDONED_MARKER: str = "abandoned"
diff --git a/src/keboola_agent_cli/services/version_service.py b/src/keboola_agent_cli/services/version_service.py
index 9a3212b2..023fb969 100644
--- a/src/keboola_agent_cli/services/version_service.py
+++ b/src/keboola_agent_cli/services/version_service.py
@@ -937,7 +937,11 @@ def self_update(self, *, include_prerelease: bool = False) -> dict[str, Any]:
                 {
                     "kbagent": {"updated": bool, "current_version": str,
                                 "latest_version": str|None, "message": str,
-                                "output": str|None},
+                                "output": str|None,
+                                # Both below distinguish "not updated YET" from
+                                # "failed" -- neither is an error:
+                                "deferred": bool,      # handed to the helper
+                                "still_running": bool},  # outran the wait
                     "mcp": {"updated": bool|None, "current_version": str|None,
                             "latest_version": str|None, "install_method": str,
                             "message": str, "output": str|None},
@@ -999,6 +1003,12 @@ def _compose_update_summary(
                 f"kbagent v{kbagent_result.get('current_version')}"
                 f" -> v{kbagent_result.get('latest_version')} (scheduled)"
             )
+        elif kbagent_result.get("still_running"):
+            # Outran our patience, not our expectations -- it was never killed.
+            parts.append(
+                f"kbagent v{kbagent_result.get('current_version')}"
+                f" -> v{kbagent_result.get('latest_version')} (still installing)"
+            )
         elif kbagent_result.get("up_to_date"):
             parts.append(f"kbagent v{kbagent_result.get('current_version')} (already up to date)")
         elif kbagent_result.get("current_version"):
@@ -1115,11 +1125,13 @@ def _update_kbagent(plan: KbagentUpdatePlan) -> dict[str, Any]:
             }
         if run.status is InstallStatus.STILL_RUNNING:
             # Not killed, still installing -- offering a recovery command here
-            # would invite a second installer into the same environment.
+            # would invite a second installer into the same environment. The
+            # explicit flag keeps the summary from calling this a failure.
             timeout_s = int(get_update_timeout())
             return {
                 "planned": True,
                 "updated": False,
+                "still_running": True,
                 "up_to_date": False,
                 "current_version": old_version,
                 "latest_version": kbagent_latest,
diff --git a/src/keboola_agent_cli/update_runner.py b/src/keboola_agent_cli/update_runner.py
index 8b7fac14..4c51879a 100644
--- a/src/keboola_agent_cli/update_runner.py
+++ b/src/keboola_agent_cli/update_runner.py
@@ -51,8 +51,10 @@
     DEFERRED_UPDATE_ABANDONED_MARKER,
     DEFERRED_UPDATE_EXIT_FILENAME,
     DEFERRED_UPDATE_LOG_FILENAME,
+    DEFERRED_UPDATE_LOG_MAX_BYTES,
     DEFERRED_UPDATE_MARKER_FILENAME,
     DEFERRED_UPDATE_MAX_WAIT_SECONDS,
+    DEFERRED_UPDATE_OUTPUT_MAX_CHARS,
     DEFERRED_UPDATE_POLL_SECONDS,
     DEFERRED_UPDATE_PROCESS_NAME,
     DEFERRED_UPDATE_STALE_SECONDS,
@@ -112,6 +114,14 @@ class DeferredUpdateStatus(Enum):
     LOST = "lost"
 
 
+@dataclass(frozen=True)
+class ClassifiedExit:
+    """What the helper's exit file meant, and the code behind it if any."""
+
+    status: DeferredUpdateStatus
+    exit_code: int | None
+
+
 @dataclass(frozen=True)
 class DeferredUpdateReport:
     """A finished deferred update, ready to be reported to the user once."""
@@ -192,6 +202,12 @@ def run_install(command: tuple[str, ...], *, timeout: float) -> InstallRun:
     except OSError:
         logger.debug("Could not create the update log directory", exc_info=True)
 
+    # Where this run's own output begins. The log is shared -- the MCP stage
+    # writes to it moments before the kbagent stage, and the Windows helper
+    # appends to it too -- so reporting the tail of the whole file would
+    # attribute someone else's transcript to this command.
+    start_offset = _roll_log_if_oversized(destination)
+
     try:
         with destination.open("a", encoding="utf-8", errors="replace") as sink:
             process = subprocess.Popen(
@@ -207,7 +223,7 @@ def run_install(command: tuple[str, ...], *, timeout: float) -> InstallRun:
                 return InstallRun(
                     status=InstallStatus.STILL_RUNNING,
                     exit_code=None,
-                    output=_tail(destination),
+                    output=_tail(destination, start=start_offset),
                     log_path=destination,
                 )
     except OSError as exc:
@@ -221,18 +237,45 @@ def run_install(command: tuple[str, ...], *, timeout: float) -> InstallRun:
     return InstallRun(
         status=InstallStatus.SUCCEEDED if exit_code == 0 else InstallStatus.FAILED,
         exit_code=exit_code,
-        output=_tail(destination),
+        output=_tail(destination, start=start_offset),
         log_path=destination,
     )
 
 
-def _tail(path: Path, *, max_chars: int = 4000) -> str:
-    """Return the end of the install log, or an empty string if unreadable."""
+def _roll_log_if_oversized(path: Path) -> int:
+    """Bound the shared log, and return the offset this run should read from.
+
+    Returns 0 when the file was rolled or does not exist yet, otherwise its
+    current size -- everything past that point is what this run writes.
+    """
     try:
-        text = path.read_text(encoding="utf-8", errors="replace")
+        size = path.stat().st_size
+    except OSError:
+        return 0
+    if size < DEFERRED_UPDATE_LOG_MAX_BYTES:
+        return size
+    try:
+        path.unlink()
+    except OSError:
+        logger.debug("Could not roll the oversized update log", exc_info=True)
+        return size
+    return 0
+
+
+def _tail(path: Path, *, start: int = 0, max_chars: int = DEFERRED_UPDATE_OUTPUT_MAX_CHARS) -> str:
+    """Return what was appended from ``start``, or "" if unreadable.
+
+    Read as bytes and decoded here rather than via ``read_text`` so the offset
+    is exact and a byte range split mid-character cannot raise -- the child may
+    still be writing while we read.
+    """
+    try:
+        with path.open("rb") as handle:
+            handle.seek(start)
+            payload = handle.read()
     except OSError:
         return ""
-    return text[-max_chars:].strip()
+    return payload.decode("utf-8", errors="replace")[-max_chars:].strip()
 
 
 def quote_for_powershell(value: str) -> str:
@@ -482,20 +525,18 @@ def collect_finished_deferred_update() -> DeferredUpdateReport | None:
 
     _clear_deferred_state()
 
-    status, exit_code = _classify_exit(raw_exit, helper_reported=reported)
+    classified = _classify_exit(raw_exit, helper_reported=reported)
     return DeferredUpdateReport(
-        status=status,
+        status=classified.status,
         from_version=str(marker.get("from_version") or "unknown"),
         target_version=str(marker.get("target_version") or "unknown"),
-        exit_code=exit_code,
+        exit_code=classified.exit_code,
         recovery_command=marker.get("recovery_command"),
         log_path=log_path(),
     )
 
 
-def _classify_exit(
-    raw_exit: str | None, *, helper_reported: bool
-) -> tuple[DeferredUpdateStatus, int | None]:
+def _classify_exit(raw_exit: str | None, *, helper_reported: bool) -> ClassifiedExit:
     """Map the helper's exit file to a status.
 
     Anything that is neither a clean exit code nor the explicit "gave up"
@@ -510,16 +551,18 @@ def _classify_exit(
             LOST (killed, or the machine rebooted mid-wait).
     """
     if raw_exit is None:
-        return (DeferredUpdateStatus.FAILED if helper_reported else DeferredUpdateStatus.LOST), None
+        return ClassifiedExit(
+            DeferredUpdateStatus.FAILED if helper_reported else DeferredUpdateStatus.LOST, None
+        )
     if raw_exit == DEFERRED_UPDATE_ABANDONED_MARKER:
-        return DeferredUpdateStatus.ABANDONED, None
+        return ClassifiedExit(DeferredUpdateStatus.ABANDONED, None)
     try:
         exit_code = int(raw_exit)
     except ValueError:
-        return DeferredUpdateStatus.FAILED, None
+        return ClassifiedExit(DeferredUpdateStatus.FAILED, None)
     if exit_code == 0:
-        return DeferredUpdateStatus.SUCCEEDED, 0
-    return DeferredUpdateStatus.FAILED, exit_code
+        return ClassifiedExit(DeferredUpdateStatus.SUCCEEDED, 0)
+    return ClassifiedExit(DeferredUpdateStatus.FAILED, exit_code)
 
 
 def _clear_deferred_state() -> None:
diff --git a/tests/test_update_runner.py b/tests/test_update_runner.py
index 21ca37a3..5e4f5ea0 100644
--- a/tests/test_update_runner.py
+++ b/tests/test_update_runner.py
@@ -123,15 +123,21 @@ def test_slow_installer_is_left_running(self, tmp_path: Path) -> None:
         sentinel = tmp_path / "finished.txt"
         program = (
             "import time, pathlib, sys;"
+            "print('early-output', flush=True);"
             "time.sleep(1.5);"
             f"pathlib.Path({str(sentinel)!r}).write_text('done')"
         )
 
-        run = run_install((sys.executable, "-c", program), timeout=0.2)
+        run = run_install((sys.executable, "-c", program), timeout=0.5)
 
         assert run.status is InstallStatus.STILL_RUNNING
         assert run.exit_code is None
         assert not sentinel.exists(), "precondition: the child cannot have finished yet"
+        # `run.output` was read while the child still holds the log open and the
+        # parent has already closed its own handle. On Windows that combination
+        # depends on file-sharing semantics, so this assertion is what proves it
+        # -- the Windows CI job runs this suite.
+        assert "early-output" in run.output
 
         deadline = time.monotonic() + 20
         while time.monotonic() < deadline and not sentinel.exists():
@@ -484,3 +490,41 @@ def test_gives_up_without_installing_while_a_process_is_still_running(
 
         assert exit_file.read_text(encoding="utf-8").strip() == DEFERRED_UPDATE_ABANDONED_MARKER
         assert not sentinel.exists(), "the installer must not touch a live environment"
+
+
+class TestInstallOutputBelongsToItsOwnRun:
+    """`output` must be this run's transcript, not the shared log's tail.
+
+    The log is appended to by every update -- the MCP stage writes to it moments
+    before the kbagent stage in the very same `kbagent update`, and the Windows
+    helper appends to it too. Reporting the tail of the whole file attributed
+    someone else's output to this command.
+    """
+
+    def test_second_run_output_excludes_the_first(self) -> None:
+        first = run_install((sys.executable, "-c", "print('FIRST-RUN-MARKER')"), timeout=30)
+        second = run_install((sys.executable, "-c", "print('SECOND-RUN-MARKER')"), timeout=30)
+
+        assert "FIRST-RUN-MARKER" in first.output
+        assert "SECOND-RUN-MARKER" in second.output
+        assert "FIRST-RUN-MARKER" not in second.output
+
+    def test_log_keeps_every_run_even_though_output_does_not(self, tmp_path: Path) -> None:
+        """Trimming the *report* must not trim the *log* -- it is the diagnosis."""
+        run_install((sys.executable, "-c", "print('FIRST-RUN-MARKER')"), timeout=30)
+        run_install((sys.executable, "-c", "print('SECOND-RUN-MARKER')"), timeout=30)
+
+        log = (tmp_path / "pending_update.log").read_text(encoding="utf-8")
+        assert "FIRST-RUN-MARKER" in log
+        assert "SECOND-RUN-MARKER" in log
+
+    def test_oversized_log_is_rolled(self, tmp_path: Path, monkeypatch: pytest.MonkeyPatch) -> None:
+        """Every update appends here, so the file cannot grow without bound."""
+        monkeypatch.setattr("keboola_agent_cli.update_runner.DEFERRED_UPDATE_LOG_MAX_BYTES", 64)
+        log = tmp_path / "pending_update.log"
+        log.write_text("x" * 500, encoding="utf-8")
+
+        run = run_install((sys.executable, "-c", "print('AFTER-ROLL')"), timeout=30)
+
+        assert "x" * 100 not in log.read_text(encoding="utf-8")
+        assert "AFTER-ROLL" in run.output
diff --git a/tests/test_version_service.py b/tests/test_version_service.py
index 9bf04659..3a70f15e 100644
--- a/tests/test_version_service.py
+++ b/tests/test_version_service.py
@@ -1528,3 +1528,45 @@ def test_failure_tail_is_last_nonempty_line(self) -> None:
         assert VersionService._summarize_failure_tail(msg) == "error: the real reason"
         assert VersionService._summarize_failure_tail("") == "update failed"
         assert VersionService._summarize_failure_tail(None) == "update failed"
+
+
+class TestSummaryDistinguishesNotYetFromFailed:
+    """ "Not updated" has three meanings; only one of them is a failure (#528)."""
+
+    @staticmethod
+    def _kbagent(**overrides: object) -> dict:
+        base = {
+            "planned": True,
+            "updated": False,
+            "up_to_date": False,
+            "current_version": "0.77.0",
+            "latest_version": "0.77.1",
+            "message": "...",
+        }
+        base.update(overrides)
+        return base
+
+    @staticmethod
+    def _mcp_up_to_date() -> dict:
+        return {"updated": False, "up_to_date": True, "current_version": "1.0.0"}
+
+    def test_scheduled_is_not_a_failure(self) -> None:
+        summary = VersionService._compose_update_summary(
+            self._kbagent(deferred=True), self._mcp_up_to_date()
+        )
+        assert "(scheduled)" in summary
+        assert "FAILED" not in summary
+
+    def test_still_running_is_not_a_failure(self) -> None:
+        """It was never killed -- calling it FAILED contradicts the banner."""
+        summary = VersionService._compose_update_summary(
+            self._kbagent(still_running=True), self._mcp_up_to_date()
+        )
+        assert "(still installing)" in summary
+        assert "FAILED" not in summary
+
+    def test_a_real_failure_is_still_reported_as_one(self) -> None:
+        summary = VersionService._compose_update_summary(
+            self._kbagent(message="Update failed: locked"), self._mcp_up_to_date()
+        )
+        assert "FAILED" in summary