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/.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/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/.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 49e270d5..dd3057c6 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.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.
+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.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
+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/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/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/changelog.py b/src/keboola_agent_cli/changelog.py
index 479b4a8f..09925e98 100644
--- a/src/keboola_agent_cli/changelog.py
+++ b/src/keboola_agent_cli/changelog.py
@@ -24,6 +24,33 @@
 
 # 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. 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. 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.",
+    ],
     "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/src/keboola_agent_cli/commands/version.py b/src/keboola_agent_cli/commands/version.py
index 6a85ca36..0fda2f49 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,15 @@ 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.
+        # 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 True:
+            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..8aecfd0d 100644
--- a/src/keboola_agent_cli/constants.py
+++ b/src/keboola_agent_cli/constants.py
@@ -317,6 +317,47 @@ 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"
+# 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"
+# 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..023fb969 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__)
 
@@ -506,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.
 
@@ -532,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:
@@ -928,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},
@@ -984,6 +997,18 @@ 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("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"):
@@ -1007,7 +1032,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 +1069,88 @@ 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. 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,
-                "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..4c51879a
--- /dev/null
+++ b/src/keboola_agent_cli/update_runner.py
@@ -0,0 +1,574 @@
+"""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_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,
+    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 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."""
+
+    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)
+
+    # 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(
+                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, start=start_offset),
+                    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, start=start_offset),
+        log_path=destination,
+    )
+
+
+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:
+        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 payload.decode("utf-8", errors="replace")[-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.
+
+    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``.
+    """
+    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",
+            "  }",
+            # -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 {",
+            "  [System.IO.File]::AppendAllText("
+            "$logFile, ($_ | Out-String -Width 4096), (New-Object System.Text.UTF8Encoding $false))",
+            "  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()
+    reported = exit_file.is_file()
+    raw_exit: str | None = None
+    if reported:
+        try:
+            raw_exit = exit_file.read_text(encoding="utf-8").strip()
+        except OSError:
+            # 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()
+
+    classified = _classify_exit(raw_exit, helper_reported=reported)
+    return DeferredUpdateReport(
+        status=classified.status,
+        from_version=str(marker.get("from_version") or "unknown"),
+        target_version=str(marker.get("target_version") or "unknown"),
+        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) -> ClassifiedExit:
+    """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 ClassifiedExit(
+            DeferredUpdateStatus.FAILED if helper_reported else DeferredUpdateStatus.LOST, None
+        )
+    if raw_exit == DEFERRED_UPDATE_ABANDONED_MARKER:
+        return ClassifiedExit(DeferredUpdateStatus.ABANDONED, None)
+    try:
+        exit_code = int(raw_exit)
+    except ValueError:
+        return ClassifiedExit(DeferredUpdateStatus.FAILED, None)
+    if exit_code == 0:
+        return ClassifiedExit(DeferredUpdateStatus.SUCCEEDED, 0)
+    return ClassifiedExit(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..5e4f5ea0
--- /dev/null
+++ b/tests/test_update_runner.py
@@ -0,0 +1,530 @@
+"""Tests for the self-reinstall runner (issue #528).
+
+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
+import os
+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,
+    resolve_powershell,
+    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;"
+            "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.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():
+            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"$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:
+        # 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
+
+
+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
+
+
+@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(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
+        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(encoding="utf-8").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(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 0409ae1b..3a70f15e 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:
@@ -579,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``.
@@ -628,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.
@@ -652,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
 
 
 # ---------------------------------------------------------------------------
@@ -766,12 +782,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 +803,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 +815,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")
@@ -1312,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
 
@@ -1419,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
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" },