diff --git a/.github/workflows/install-checks.yml b/.github/workflows/install-checks.yml
index 6fdeb68a..7db2b9e8 100644
--- a/.github/workflows/install-checks.yml
+++ b/.github/workflows/install-checks.yml
@@ -1,8 +1,9 @@
 name: Install checks
 
-# Installs the backend on clean Linux and Windows hosts, checks the running
-# service, then uninstalls. Tray companions need a desktop session that hosted
-# runners do not reliably provide, so they are not covered here.
+# Installs the backend on clean macOS, Linux, and Windows hosts, checks the
+# running service, then uninstalls; on Linux it also runs a real update. Tray
+# companions need a desktop session that hosted runners do not reliably
+# provide, so they are not covered here.
 on:
   push:
     branches: [main]
@@ -95,6 +96,200 @@ jobs:
         if: failure()
         run: journalctl --user -u token-meter-server.service -n 200 --no-pager || true
 
+  # Installs from a local clone whose origin is a local bare remote, publishes a
+  # newer commit there, then drives Install through the dashboard API. The
+  # installer restarts the server mid-update, so this proves the helper
+  # outlives that restart and the server comes back on the new revision.
+  linux-update:
+    name: Linux update
+    runs-on: ubuntu-latest
+    timeout-minutes: 25
+    env:
+      TOKEN_METER_READINESS_TIMEOUT_SECONDS: "600"
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Start a systemd user session
+        run: |
+          sudo loginctl enable-linger "$USER"
+          runtime_dir="/run/user/$(id -u)"
+          export XDG_RUNTIME_DIR="$runtime_dir"
+          export DBUS_SESSION_BUS_ADDRESS="unix:path=$runtime_dir/bus"
+          for _ in $(seq 1 30); do
+            systemctl --user show-environment >/dev/null 2>&1 && break
+            sleep 1
+          done
+          systemctl --user show-environment >/dev/null
+          echo "XDG_RUNTIME_DIR=$XDG_RUNTIME_DIR" >> "$GITHUB_ENV"
+          echo "DBUS_SESSION_BUS_ADDRESS=$DBUS_SESSION_BUS_ADDRESS" >> "$GITHUB_ENV"
+
+      - name: Publish this revision to a local remote
+        run: |
+          remote="$RUNNER_TEMP/update-remote.git"
+          source="$RUNNER_TEMP/update-source"
+          git init --quiet --bare --initial-branch=main "$remote"
+          git push --quiet "$remote" HEAD:refs/heads/main
+          git clone --quiet "$remote" "$source"
+          echo "UPDATE_SOURCE=$source" >> "$GITHUB_ENV"
+
+      - name: Add a sample session and turn off automatic installs
+        run: |
+          python3 .github/scripts/write_sample_trace.py
+          mkdir -p "$HOME/.token-meter"
+          printf '%s\n' '{"updates": {"enabled": true, "auto_install": false}}' \
+            > "$HOME/.token-meter/settings.json"
+
+      - name: Install
+        run: |
+          cd "$UPDATE_SOURCE"
+          ./scripts/install --backend-only
+          systemctl --user show -p MainPID --value token-meter-server.service \
+            > "$RUNNER_TEMP/server-pid-before"
+
+      - name: Publish a newer revision
+        run: |
+          cd "$UPDATE_SOURCE"
+          git -c user.name="Token Meter CI" -c user.email="ci@token-meter.invalid" \
+            commit --quiet --allow-empty -m "ci: update bump"
+          git push --quiet origin main
+          echo "UPDATE_TARGET=$(git rev-parse HEAD)" >> "$GITHUB_ENV"
+
+      - name: Check for and install the update
+        run: |
+          python3 - <<'PY'
+          import json, os, time, urllib.request
+          base = "http://127.0.0.1:8722"
+          target = os.environ["UPDATE_TARGET"]
+
+          def get(path):
+              with urllib.request.urlopen(base + path, timeout=10) as response:
+                  return json.load(response)
+
+          def post(path, token):
+              request = urllib.request.Request(
+                  base + path, data=b"{}", method="POST",
+                  headers={"Content-Type": "application/json", "X-Token-Meter-Action": token},
+              )
+              with urllib.request.urlopen(request, timeout=10) as response:
+                  return response.status, json.load(response)
+
+          token = get("/updates/status")["actions"]["token"]
+          deadline = time.monotonic() + 180
+          # A check already running from server startup ignores a new request,
+          # so keep asking until one sees the published revision.
+          while True:
+              status = get("/updates/status")
+              if status.get("can_update") and target.startswith(status.get("latest_revision") or "-"):
+                  break
+              assert time.monotonic() < deadline, status
+              if not status.get("checking"):
+                  post("/updates/check", token)
+              time.sleep(2)
+          code, result = post("/updates/install", token)
+          assert code == 202 and result.get("ok"), (code, result)
+          print("update started for", target[:12])
+          PY
+
+      - name: Wait for the update to finish
+        run: |
+          status_file="$HOME/.token-meter/update-status.json"
+          deadline=$((SECONDS + 720))
+          while (( SECONDS < deadline )); do
+            phase="$(python3 -c 'import json,sys; print(json.load(open(sys.argv[1])).get("phase",""))' "$status_file" 2>/dev/null || true)"
+            case "$phase" in
+              complete) echo "update complete"; break ;;
+              failed) cat "$status_file"; exit 1 ;;
+            esac
+            sleep 2
+          done
+          test "$phase" = complete || { echo "update stuck in phase: $phase" >&2; cat "$status_file"; exit 1; }
+
+      - name: Check the updated installation
+        run: |
+          runtime="${XDG_DATA_HOME:-$HOME/.local/share}/token-meter/runtime"
+          installed="$(cat "$runtime/INSTALLED_REVISION")"
+          case "$UPDATE_TARGET" in
+            "$installed"*) echo "installed revision ok: $installed" ;;
+            *) echo "installed $installed, expected $UPDATE_TARGET" >&2; exit 1 ;;
+          esac
+          systemctl --user is-active --quiet token-meter-server.service
+          before="$(cat "$RUNNER_TEMP/server-pid-before")"
+          after="$(systemctl --user show -p MainPID --value token-meter-server.service)"
+          test "$before" != "$after" || { echo "the server was not restarted" >&2; exit 1; }
+          curl -fsS --max-time 10 http://127.0.0.1:8722/health | python3 -c 'import json, sys; h = json.load(sys.stdin); assert h.get("ok"), h; print("health ok")'
+
+      - name: Show update and server logs
+        if: failure()
+        run: |
+          cat "$HOME/.token-meter/update-status.json" || true
+          journalctl --user -u token-meter-update.service -n 200 --no-pager || true
+          journalctl --user -u token-meter-server.service -n 200 --no-pager || true
+
+  macos:
+    name: macOS install
+    runs-on: macos-latest
+    timeout-minutes: 20
+    env:
+      TOKEN_METER_READINESS_TIMEOUT_SECONDS: "600"
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - name: Add a sample session
+        run: python3 .github/scripts/write_sample_trace.py
+
+      - name: Install
+        run: ./scripts/install --backend-only
+
+      - name: Check the installation
+        run: |
+          runtime="$HOME/Library/Application Support/Token Meter/runtime"
+          launchctl print "gui/$UID/com.token-meter.server" >/dev/null
+          test "$(cat "$runtime/INSTALL_MODE")" = "backend-only"
+          python3 - <<'PY'
+          import json, time, urllib.request
+          deadline = time.monotonic() + 60
+          while True:
+              with urllib.request.urlopen("http://127.0.0.1:8722/health", timeout=10) as response:
+                  health = json.load(response)
+              if health.get("inventory_ready") or time.monotonic() > deadline:
+                  break
+              time.sleep(1)
+          assert health.get("ok") and health.get("state_ready"), health
+          assert health.get("inventory_ready"), health
+          assert (health.get("sources") or 0) >= 1, health
+          assert not health.get("runtime_adapter_failures"), health
+          print("health ok:", health["sources"], "session(s) indexed")
+          PY
+          curl -fsS --max-time 10 http://127.0.0.1:8722/menubar | python3 -c 'import json, sys; json.load(sys.stdin); print("menubar ok")'
+
+      - name: Uninstall
+        run: |
+          runtime="$HOME/Library/Application Support/Token Meter/runtime"
+          "$runtime/scripts/uninstall-launch-agent"
+          if launchctl print "gui/$UID/com.token-meter.server" >/dev/null 2>&1; then
+            echo "com.token-meter.server is still loaded" >&2
+            exit 1
+          fi
+          for _ in $(seq 1 10); do
+            curl -fsS --max-time 3 http://127.0.0.1:8722/health >/dev/null 2>&1 || { echo "uninstall ok"; exit 0; }
+            sleep 1
+          done
+          echo "the server still answers after uninstall" >&2
+          exit 1
+
+      - name: Show server logs
+        if: failure()
+        run: |
+          runtime="$HOME/Library/Application Support/Token Meter/runtime"
+          for name in meter.err.log meter.log; do
+            [[ -f "$runtime/$name" ]] && { echo "== $name"; tail -n 200 "$runtime/$name"; }
+          done
+          true
+
   windows:
     name: Windows install
     runs-on: windows-latest
diff --git a/.github/workflows/tests.yml b/.github/workflows/tests.yml
new file mode 100644
index 00000000..7696eacb
--- /dev/null
+++ b/.github/workflows/tests.yml
@@ -0,0 +1,129 @@
+name: Tests
+
+# Runs the unit and contract suites on every supported host, so a change made
+# for one platform is checked on the others, plus the static gates from
+# specs/AGENTS.md and the native companion build.
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+concurrency:
+  group: tests-${{ github.event_name == 'pull_request' && github.ref || github.sha }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
+
+jobs:
+  unit:
+    name: Unit tests (${{ matrix.os }})
+    runs-on: ${{ matrix.os }}
+    timeout-minutes: 30
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+    env:
+      PYTHONUTF8: "1"
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+        with:
+          fetch-depth: 0
+
+      - uses: actions/setup-python@a26af69be951a213d495a4c3e4e4022e16d87065 # v5
+        with:
+          python-version: "3.12"
+
+      # Pull-request checkouts are detached; installer tests clone this
+      # repository and expect a local main branch, as a developer clone has.
+      - name: Name the checked-out commit main
+        run: git switch --quiet -C main
+
+      - name: Run the test suite
+        if: runner.os != 'Windows'
+        run: python -m unittest discover -s tests
+
+      # The full suite is not yet Windows-clean (SQLite handles held across
+      # temp-dir cleanup, mktime range limits). Run every module that is, so
+      # a regression in them still fails here.
+      - name: Run the Windows-clean test modules
+        if: runner.os == 'Windows'
+        run: >-
+          python -m unittest
+          tests.contracts.test_agent_workflow tests.contracts.test_architecture_guards
+          tests.contracts.test_compat tests.contracts.test_contracts tests.contracts.test_design_system
+          tests.contracts.test_kiro_extension_budget tests.contracts.test_model_pricing
+          tests.contracts.test_path_cache tests.contracts.test_platform_services
+          tests.contracts.test_public_projections tests.contracts.test_quota_privacy
+          tests.contracts.test_quota_registry tests.contracts.test_runtime_catalog
+          tests.contracts.test_runtime_manifest tests.contracts.test_runtime_registry
+          tests.contracts.test_telemetry_mapping tests.contracts.test_windows_packaging
+          tests.domain.test_aggregates tests.domain.test_compare tests.domain.test_matched_pace_parity
+          tests.domain.test_timing_tools_insights tests.domain.test_usage
+          tests.integration.test_application_composition tests.integration.test_discovery_performance
+          tests.integration.test_model_pricing_compat
+          tests.integration.test_runtime_dispatch_characterization
+          tests.integration.test_session_selection
+          tests.runtimes.test_claude_adapter tests.runtimes.test_codex_adapter
+          tests.runtimes.test_kiro_adapter tests.runtimes.test_pi_adapter
+          tests.test_claude_cost_correctness tests.test_codex_model_identity
+          tests.test_current_model_catalog tests.test_goals tests.test_installer_modes tests.test_linux_update
+          tests.test_mcp_queries tests.test_mcp_server tests.test_menubar_settings
+
+  static:
+    name: Static checks
+    runs-on: ubuntu-latest
+    timeout-minutes: 10
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Compile Python
+        run: |
+          PYTHONPYCACHEPREFIX="$RUNNER_TEMP/pycache" python3 -m py_compile \
+            meter.py token_meter_mcp.py $(find token_meter -type f -name '*.py' -print)
+
+      - name: Parse the dashboard JavaScript
+        run: |
+          node -e "const fs=require('fs');const h=fs.readFileSync('page.html','utf8');const m=h.match(/<script>([\s\S]*)<\/script>/);new Function(m[1]);console.log('js ok')"
+
+      - name: Check shell syntax
+        run: |
+          for script in scripts/*; do
+            if head -n 1 "$script" | grep -q bash; then
+              bash -n "$script"
+            fi
+          done
+
+      - name: Reject whitespace errors
+        if: github.event_name == 'pull_request'
+        run: |
+          git fetch --no-tags --depth=1 origin "${{ github.base_ref }}"
+          git diff --check FETCH_HEAD HEAD
+
+  native:
+    name: macOS companion build
+    runs-on: macos-latest
+    timeout-minutes: 15
+    steps:
+      - uses: actions/checkout@11d5960a326750d5838078e36cf38b85af677262 # v4
+
+      - name: Compile the menu-bar companion
+        run: swiftc menubar/TokenMeterMenuBar.swift -o "$RUNNER_TEMP/token-meter-menubar"
+
+      # The smoke check reads the live /menubar payload, as it does after install.
+      - name: Start the local server
+        run: |
+          python3 .github/scripts/write_sample_trace.py
+          nohup python3 meter.py > "$RUNNER_TEMP/meter.log" 2>&1 &
+          for _ in $(seq 1 120); do
+            curl -fsS --max-time 3 http://127.0.0.1:8722/menubar >/dev/null 2>&1 && exit 0
+            sleep 1
+          done
+          cat "$RUNNER_TEMP/meter.log"
+          exit 1
+
+      - name: Run the smoke check
+        run: TOKEN_METER_MENUBAR_SMOKE=1 "$RUNNER_TEMP/token-meter-menubar"
diff --git a/tests/contracts/test_platform_services.py b/tests/contracts/test_platform_services.py
index d1614b09..975302b7 100644
--- a/tests/contracts/test_platform_services.py
+++ b/tests/contracts/test_platform_services.py
@@ -142,23 +142,75 @@ def test_windows_process_trash_and_update_launch_are_owned_platform_decisions(se
         )
 
     def test_posix_update_plan_preserves_existing_helper_contract(self):
-        platform = platform_services("linux", environment={}, home="/home/example")
+        platform = platform_services("darwin", environment={}, home="/Users/example")
 
         update = platform.update_plan(
-            "/opt/token-meter", "/home/example/source", "/home/example/status.json"
+            "/opt/token-meter", "/Users/example/source", "/Users/example/status.json"
         )
 
         self.assertEqual(update.script_path, "/opt/token-meter/scripts/update")
         self.assertEqual(update.command, (
             "/opt/token-meter/scripts/update",
-            "/home/example/source",
-            "/home/example/status.json",
+            "/Users/example/source",
+            "/Users/example/status.json",
         ))
         self.assertEqual(
             platform.agent_launcher("/opt/token-meter"),
             "/opt/token-meter/scripts/run-token-meter-mcp",
         )
 
+    def test_linux_update_plan_runs_the_helper_outside_the_server_cgroup(self):
+        platform = platform_services(
+            "linux", environment={"INVOCATION_ID": "a" * 32}, home="/home/example",
+        )
+
+        update = platform.update_plan(
+            "/opt/token-meter", "/home/example/source", "/home/example/status.json",
+            systemd_run="/usr/bin/systemd-run",
+        )
+        retry = platform.update_plan(
+            "/opt/token-meter", "/home/example/source", "/home/example/status.json",
+            retry_revision="b" * 40, systemd_run="/usr/bin/systemd-run",
+        )
+
+        self.assertTrue(update.supported)
+        self.assertEqual(update.script_path, "/opt/token-meter/scripts/update")
+        self.assertEqual(update.command, (
+            "/usr/bin/systemd-run", "--user", "--quiet", "--collect",
+            "--unit=token-meter-update", "--description=Token Meter update", "--",
+            "/opt/token-meter/scripts/update",
+            "/home/example/source",
+            "/home/example/status.json",
+        ))
+        self.assertIn(
+            "--setenv=TOKEN_METER_UPDATE_RETRY_REVISION=" + "b" * 40, retry.command,
+        )
+        self.assertLess(
+            retry.command.index("--setenv=TOKEN_METER_UPDATE_RETRY_REVISION=" + "b" * 40),
+            retry.command.index("--"),
+        )
+
+    def test_linux_update_plan_falls_back_to_the_helper_without_systemd_run(self):
+        under_systemd = platform_services(
+            "linux", environment={"INVOCATION_ID": "a" * 32}, home="/home/example",
+        )
+        started_by_hand = platform_services("linux", environment={}, home="/home/example")
+        helper = (
+            "/opt/token-meter/scripts/update",
+            "/home/example/source",
+            "/home/example/status.json",
+        )
+
+        for platform, systemd_run in (
+            (under_systemd, ""),
+            (started_by_hand, "/usr/bin/systemd-run"),
+        ):
+            update = platform.update_plan(
+                "/opt/token-meter", "/home/example/source", "/home/example/status.json",
+                systemd_run=systemd_run,
+            )
+            self.assertEqual(update.command, helper)
+
     def test_linux_prefers_gio_and_macos_uses_owned_trash_directory(self):
         linux = platform_services("linux", environment={}, home="/home/example")
         macos = platform_services("darwin", environment={}, home="/Users/example")
diff --git a/tests/test_meter.py b/tests/test_meter.py
index 180ee1db..c01f5b09 100644
--- a/tests/test_meter.py
+++ b/tests/test_meter.py
@@ -15992,7 +15992,9 @@ def test_explicit_install_starts_only_the_bounded_detached_helper(self):
                 "dirty": False,
             }, str(status_path))
             popen = mock.Mock()
+            macos = meter.platform_services("darwin", environment={}, home=tmp)
             with (mock.patch.object(meter, "source_checkout_path", return_value=tmp),
+                  mock.patch.object(meter, "_PLATFORM_SERVICES", macos),
                   mock.patch.object(meter.os.path, "isfile", return_value=True),
                   mock.patch.object(meter.os, "access", return_value=True)):
                 result = meter.start_software_update(
@@ -16009,6 +16011,148 @@ def test_explicit_install_starts_only_the_bounded_detached_helper(self):
         self.assertTrue(kwargs["close_fds"])
         self.assertNotIn(tmp, json.dumps(result))
 
+    def test_linux_install_launches_the_helper_as_a_transient_user_unit(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            settings_path = self.enabled_settings(tmp)
+            status_path = Path(tmp) / "update-status.json"
+            target = "b" * 40
+            meter._persist_update_status({
+                "phase": "failed",
+                "error_code": "update_interrupted",
+                "current_revision": "a" * 40,
+                "latest_revision": target,
+                "failed_revision": target,
+                "checked_at": 1234,
+                "available": True,
+                "can_update": False,
+            }, str(status_path))
+            popen = mock.Mock()
+            linux = meter.platform_services(
+                "linux", environment={"INVOCATION_ID": "a" * 32}, home=tmp,
+            )
+            with (mock.patch.object(meter, "source_checkout_path", return_value=tmp),
+                  mock.patch.object(meter, "_PLATFORM_SERVICES", linux),
+                  mock.patch("token_meter.platforms.linux.shutil.which",
+                             return_value="/usr/bin/systemd-run"),
+                  mock.patch.object(meter.os.path, "isfile", return_value=True),
+                  mock.patch.object(meter.os, "access", return_value=True)):
+                result = meter.start_software_update(
+                    popen=popen,
+                    settings_path=str(settings_path),
+                    status_path=str(status_path),
+                )
+            command = popen.call_args.args[0]
+        self.assertTrue(result["ok"])
+        self.assertEqual(command[:2], ["/usr/bin/systemd-run", "--user"])
+        self.assertIn("--setenv=TOKEN_METER_UPDATE_RETRY_REVISION=" + target, command)
+        separator = command.index("--")
+        self.assertTrue(command[separator + 1].endswith("/scripts/update"))
+        self.assertEqual(command[separator + 2:], [tmp, str(status_path)])
+
+    def test_stale_in_progress_update_becomes_a_retryable_interruption(self):
+        with tempfile.TemporaryDirectory() as tmp:
+            settings_path = self.enabled_settings(tmp)
+            status_path = Path(tmp) / "update-status.json"
+            target = "b" * 40
+            record = {
+                "phase": "installing",
+                "current_revision": target,
+                "latest_revision": target,
+                "previous_revision": "a" * 40,
+                "checked_at": 1000,
+                "started_at": 1001,
+                "available": True,
+                "can_update": False,
+            }
+            meter._persist_update_status(record, str(status_path))
+            fresh = meter._recover_stale_update(
+                record, now=1001 + meter.UPDATE_STALE_AFTER_S - 1,
+                status_path=str(status_path),
+            )
+            still_installing = json.loads(status_path.read_text())["phase"]
+            recovered = meter._recover_stale_update(
+                record, now=1001 + meter.UPDATE_STALE_AFTER_S,
+                status_path=str(status_path),
+            )
+            stored = json.loads(status_path.read_text())
+            status = meter.software_update_status(
+                settings_path=str(settings_path), status_path=str(status_path),
+            )
+        self.assertFalse(fresh)
+        self.assertEqual(still_installing, "installing")
+        self.assertTrue(recovered)
+        self.assertEqual(stored["phase"], "failed")
+        self.assertEqual(stored["error_code"], "update_interrupted")
+        self.assertEqual(stored["failed_revision"], target)
+        self.assertEqual(stored["previous_revision"], "a" * 40)
+        self.assertEqual(status["state"], "attention")
+        self.assertIn("stopped before it finished", status["message"])
+
+    def test_stale_check_falls_back_to_checked_at_and_needs_a_timestamp(self):
+        """The Windows helper writes in-progress records without started_at."""
+        with tempfile.TemporaryDirectory() as tmp:
+            status_path = str(Path(tmp) / "update-status.json")
+            windows_record = {
+                "phase": "installing", "checked_at": 1000, "latest_revision": "b" * 40,
+            }
+            meter._persist_update_status(windows_record, status_path)
+            fresh = meter._recover_stale_update(
+                windows_record, now=1005, status_path=status_path,
+            )
+            undated = meter._recover_stale_update(
+                {"phase": "fetching"}, now=10 ** 9, status_path=status_path,
+            )
+            still_installing = json.loads(Path(status_path).read_text())["phase"]
+            stale = meter._recover_stale_update(
+                windows_record, now=1000 + meter.UPDATE_STALE_AFTER_S,
+                status_path=status_path,
+            )
+            stored = json.loads(Path(status_path).read_text())
+        self.assertFalse(fresh)
+        self.assertFalse(undated)
+        self.assertEqual(still_installing, "installing")
+        self.assertTrue(stale)
+        self.assertEqual(stored["error_code"], "update_interrupted")
+
+    def test_update_watcher_waits_on_a_fresh_in_progress_update(self):
+        wake = mock.Mock()
+        wake.wait.side_effect = [None, RuntimeError("stop watcher")]
+        fresh = {"phase": "installing", "started_at": int(time.time())}
+        with (mock.patch.object(meter, "_update_wake", wake),
+              mock.patch.object(
+                  meter, "update_settings",
+                  return_value={"enabled": True, "auto_install": False},
+              ),
+              mock.patch.object(meter, "_update_status_record", return_value=fresh),
+              mock.patch.object(meter, "_persist_update_status") as persist,
+              mock.patch.object(meter, "check_for_software_update") as check):
+            with self.assertRaisesRegex(RuntimeError, "stop watcher"):
+                meter.software_update_watcher()
+        persist.assert_not_called()
+        self.assertEqual(wake.wait.call_args_list, [mock.call(5), mock.call(5)])
+        check.assert_not_called()
+
+    def test_update_watcher_recovers_a_stale_in_progress_update(self):
+        wake = mock.Mock()
+        wake.wait.side_effect = [RuntimeError("stop watcher")]
+        stale = {"phase": "installing", "started_at": 1}
+        with (mock.patch.object(meter, "_update_wake", wake),
+              mock.patch.object(
+                  meter, "update_settings",
+                  return_value={"enabled": True, "auto_install": False},
+              ),
+              mock.patch.object(
+                  meter, "_update_status_record",
+                  side_effect=[stale, {"phase": "failed"}],
+              ),
+              mock.patch.object(meter, "_persist_update_status", return_value=True) as persist,
+              mock.patch.object(meter, "check_for_software_update") as check):
+            with self.assertRaisesRegex(RuntimeError, "stop watcher"):
+                meter.software_update_watcher()
+        self.assertEqual(persist.call_args.args[0]["error_code"], "update_interrupted")
+        self.assertEqual(wake.wait.call_args_list, [mock.call(meter.UPDATE_CHECK_INTERVAL_S)])
+        check.assert_not_called()
+
     def test_explicit_install_retries_a_failed_current_revision(self):
         with tempfile.TemporaryDirectory() as tmp:
             settings_path = self.enabled_settings(tmp)
diff --git a/token_meter/app.py b/token_meter/app.py
index 7977c84e..30cfe9c6 100644
--- a/token_meter/app.py
+++ b/token_meter/app.py
@@ -365,6 +365,8 @@ def hermes_state_db_path(environ=None):
 UPDATE_CHECK_INTERVAL_S = 10 * 60
 GIT_DELIVERY_INTERVAL_S = 5 * 60
 UPDATE_FETCH_TIMEOUT_S = 45
+# Comfortably past the installer's default 600-second readiness wait.
+UPDATE_STALE_AFTER_S = 30 * 60
 UPDATE_REF_RE = re.compile(r"^[A-Za-z0-9][A-Za-z0-9._/-]{1,199}$")
 
 # Compatibility re-exports retain the existing runtime-oriented names while
@@ -2243,6 +2245,7 @@ def _update_message(state, error_code="", latest_revision=""):
             "Reinstall Token Meter to repair automatic updates."
         ),
         "install_failed": "The update did not install. The existing checkout needs attention.",
+        "update_interrupted": "The last update stopped before it finished. Try installing it again.",
     }
     return messages.get(error_code, "Update status is unavailable.")
 
@@ -2462,7 +2465,8 @@ def start_software_update(popen=None, settings_path=None, status_path=None):
     failed_target = _safe_update_revision(raw.get("failed_revision"))
     retry_failed = bool(
         str(raw.get("phase") or "") == "failed"
-        and str(raw.get("error_code") or "") in {"install_failed", "launch_failed"}
+        and str(raw.get("error_code") or "") in {
+            "install_failed", "launch_failed", "update_interrupted"}
         and failed_target
         and failed_target == _safe_update_revision(raw.get("latest_revision"))
     )
@@ -2472,6 +2476,7 @@ def start_software_update(popen=None, settings_path=None, status_path=None):
     target_status_path = status_path or TOKEN_METER_UPDATE_STATUS
     update_plan = _PLATFORM_SERVICES.update_plan(
         _SOURCE_ROOT, checkout or "", target_status_path,
+        retry_revision=failed_target if retry_failed else "",
     )
     helper_ready = bool(
         update_plan.supported
@@ -2536,6 +2541,29 @@ def start_software_update(popen=None, settings_path=None, status_path=None):
     return {"ok": True, "status": software_update_status(settings_path, status_path)}
 
 
+def _recover_stale_update(previous, now=None, status_path=None):
+    """Fail an in-progress update whose helper stopped without a final status."""
+    started_at = _safe_update_int(previous.get("started_at"))
+    # The Windows helper rewrites the record without started_at but stamps
+    # checked_at on every phase.
+    progressed_at = started_at or _safe_update_int(previous.get("checked_at"))
+    now = int(now or time.time())
+    if not progressed_at or now - progressed_at < UPDATE_STALE_AFTER_S:
+        return False
+    latest_revision = previous.get("latest_revision", "")
+    return _persist_update_status({
+        "phase": "failed",
+        "error_code": "update_interrupted",
+        "checked_at": _safe_update_int(previous.get("checked_at")),
+        "started_at": started_at,
+        "current_revision": previous.get("current_revision", ""),
+        "latest_revision": latest_revision,
+        "failed_revision": latest_revision,
+        "available": True,
+        "can_update": False,
+    }, status_path)
+
+
 def software_update_watcher():
     """Run checks every 10 minutes and install safe results when enabled."""
     while True:
@@ -2547,7 +2575,8 @@ def software_update_watcher():
         previous = _update_status_record()
         phase = str(previous.get("phase") or "")
         if phase in {"starting", "fetching", "installing"}:
-            _update_wake.wait(5)
+            if not _recover_stale_update(previous):
+                _update_wake.wait(5)
             continue
         if phase in {"complete", "failed"}:
             if _update_wake.wait(UPDATE_CHECK_INTERVAL_S):
diff --git a/token_meter/platforms/base.py b/token_meter/platforms/base.py
index 34e865a2..3c3c398b 100644
--- a/token_meter/platforms/base.py
+++ b/token_meter/platforms/base.py
@@ -89,6 +89,7 @@ def trash_plan(
 
     def update_plan(
         self, source_root: str, checkout: str, status_path: str,
+        retry_revision: str = "",
     ) -> UpdatePlan:
         ...
 
diff --git a/token_meter/platforms/common.py b/token_meter/platforms/common.py
index eb488e55..cb4408a9 100644
--- a/token_meter/platforms/common.py
+++ b/token_meter/platforms/common.py
@@ -1,6 +1,7 @@
 """Shared POSIX platform behavior."""
 
 import os
+import posixpath
 
 from .base import PlatformCapabilities, ProcessOptions, ProcessPurpose, UpdatePlan
 
@@ -13,7 +14,7 @@ def expand_home(path, home):
     if value == "~":
         return home
     if value.startswith("~/"):
-        return os.path.join(home, value[2:])
+        return posixpath.join(home, value[2:])
     return value
 
 
@@ -41,8 +42,8 @@ def process_options(self, purpose):
     def capabilities(self):
         return PlatformCapabilities(paths=True, detached_process=True, trash=True)
 
-    def update_plan(self, source_root, checkout, status_path):
-        script = os.path.join(str(source_root), "scripts", "update")
+    def update_plan(self, source_root, checkout, status_path, retry_revision=""):
+        script = posixpath.join(str(source_root), "scripts", "update")
         return UpdatePlan(
             supported=True,
             script_path=script,
@@ -50,7 +51,7 @@ def update_plan(self, source_root, checkout, status_path):
         )
 
     def agent_launcher(self, source_root):
-        return os.path.join(str(source_root), "scripts", "run-token-meter-mcp")
+        return posixpath.join(str(source_root), "scripts", "run-token-meter-mcp")
 
     def lower_background_priority(self):
         try:
diff --git a/token_meter/platforms/linux.py b/token_meter/platforms/linux.py
index 3f158b7a..3465bab2 100644
--- a/token_meter/platforms/linux.py
+++ b/token_meter/platforms/linux.py
@@ -1,14 +1,17 @@
 """Linux/XDG path and lifecycle policy."""
 
 import os
+import posixpath
+import shutil
 
-from .base import CpuActivity, PlatformPaths, TrashPlan
+from .base import CpuActivity, PlatformPaths, TrashPlan, UpdatePlan
 from .common import PosixPlatformServices, expand_home
 
 
 POWER_SUPPLY_ROOT = "/sys/class/power_supply"
 POWER_SUPPLY_MAX_ENTRIES = 32
 PROC_STAT_PATH = "/proc/stat"
+UPDATE_UNIT_NAME = "token-meter-update"
 
 
 def parse_proc_stat(text):
@@ -34,7 +37,7 @@ def parse_proc_stat(text):
 
 def _read_supply_value(root, name, field):
     try:
-        with open(os.path.join(root, name, field), encoding="utf-8") as handle:
+        with open(posixpath.join(root, name, field), encoding="utf-8") as handle:
             return handle.read(64).strip()
     except (OSError, UnicodeDecodeError):
         return ""
@@ -52,16 +55,16 @@ def resolve_paths(self):
             data_home=data_home,
             cache_home=cache_home,
             claude_desktop_data_roots=(
-                os.path.join(config_home, "Claude"),
-                os.path.join(config_home, "Claude-3p"),
+                posixpath.join(config_home, "Claude"),
+                posixpath.join(config_home, "Claude-3p"),
             ),
-            cursor_state_db=os.path.join(
+            cursor_state_db=posixpath.join(
                 config_home, "Cursor", "User", "globalStorage", "state.vscdb"
             ),
-            cursor_request_logs=os.path.join(config_home, "Cursor", "logs"),
-            opencode_data_root=os.path.join(data_home, "opencode"),
-            opencode_cache_root=os.path.join(cache_home, "opencode"),
-            default_trash_dir=os.path.join(data_home, "Trash", "files"),
+            cursor_request_logs=posixpath.join(config_home, "Cursor", "logs"),
+            opencode_data_root=posixpath.join(data_home, "opencode"),
+            opencode_cache_root=posixpath.join(cache_home, "opencode"),
+            default_trash_dir=posixpath.join(data_home, "Trash", "files"),
         )
 
     def trash_plan(self, path, override=None, command_available=False):
@@ -84,6 +87,34 @@ def trash_plan(self, path, override=None, command_available=False):
             destination_label="Trash",
         )
 
+    def update_plan(self, source_root, checkout, status_path, retry_revision="",
+                    systemd_run=None):
+        plan = super().update_plan(source_root, checkout, status_path, retry_revision)
+        # Only a server started by systemd shares a cgroup with its children;
+        # elsewhere a user manager may be absent and systemd-run would fail.
+        if not self.environment.get("INVOCATION_ID"):
+            return plan
+        if systemd_run is None:
+            systemd_run = shutil.which("systemd-run", path=self.environment.get("PATH"))
+        if not systemd_run:
+            return plan
+        # systemd tracks the server's cgroup, not its session: a setsid child is
+        # still stopped with the server when the installer restarts it. A
+        # transient user unit survives that restart, but starts from the user
+        # manager's environment rather than this process's.
+        command = [
+            systemd_run, "--user", "--quiet", "--collect",
+            f"--unit={UPDATE_UNIT_NAME}",
+            "--description=Token Meter update",
+        ]
+        if retry_revision:
+            command.append(f"--setenv=TOKEN_METER_UPDATE_RETRY_REVISION={retry_revision}")
+        command.append("--")
+        command.extend(plan.command)
+        return UpdatePlan(
+            supported=True, script_path=plan.script_path, command=tuple(command),
+        )
+
     def cpu_activity(self, path=PROC_STAT_PATH):
         try:
             with open(path, encoding="utf-8") as handle:
diff --git a/token_meter/platforms/macos.py b/token_meter/platforms/macos.py
index 8edcde5c..de212ae1 100644
--- a/token_meter/platforms/macos.py
+++ b/token_meter/platforms/macos.py
@@ -1,6 +1,7 @@
 """macOS path and lifecycle policy."""
 
 import os
+import posixpath
 import re
 import subprocess
 
@@ -101,22 +102,22 @@ def resolve_paths(self):
         config_home = self._environment_path("XDG_CONFIG_HOME", "~/.config")
         data_home = self._environment_path("XDG_DATA_HOME", "~/.local/share")
         cache_home = self._environment_path("XDG_CACHE_HOME", "~/.cache")
-        application_support = os.path.join(self.home, "Library", "Application Support")
+        application_support = posixpath.join(self.home, "Library", "Application Support")
         return PlatformPaths(
             config_home=config_home,
             data_home=data_home,
             cache_home=cache_home,
             claude_desktop_data_roots=(
-                os.path.join(application_support, "Claude"),
-                os.path.join(application_support, "Claude-3p"),
+                posixpath.join(application_support, "Claude"),
+                posixpath.join(application_support, "Claude-3p"),
             ),
-            cursor_state_db=os.path.join(
+            cursor_state_db=posixpath.join(
                 application_support, "Cursor", "User", "globalStorage", "state.vscdb"
             ),
-            cursor_request_logs=os.path.join(application_support, "Cursor", "logs"),
-            opencode_data_root=os.path.join(data_home, "opencode"),
-            opencode_cache_root=os.path.join(cache_home, "opencode"),
-            default_trash_dir=os.path.join(self.home, ".Trash"),
+            cursor_request_logs=posixpath.join(application_support, "Cursor", "logs"),
+            opencode_data_root=posixpath.join(data_home, "opencode"),
+            opencode_cache_root=posixpath.join(cache_home, "opencode"),
+            default_trash_dir=posixpath.join(self.home, ".Trash"),
         )
 
     def trash_plan(self, path, override=None, command_available=False):
diff --git a/token_meter/platforms/unsupported.py b/token_meter/platforms/unsupported.py
index 88f887a3..f9cb294c 100644
--- a/token_meter/platforms/unsupported.py
+++ b/token_meter/platforms/unsupported.py
@@ -24,7 +24,7 @@ def trash_plan(self, path, override=None, command_available=False):
             message="Moving session logs to Trash is unavailable on this platform.",
         )
 
-    def update_plan(self, source_root, checkout, status_path):
+    def update_plan(self, source_root, checkout, status_path, retry_revision=""):
         return UpdatePlan(
             supported=False,
             error_code="unsupported_platform",
diff --git a/token_meter/platforms/windows.py b/token_meter/platforms/windows.py
index 929a56f4..acf0f368 100644
--- a/token_meter/platforms/windows.py
+++ b/token_meter/platforms/windows.py
@@ -93,7 +93,7 @@ def trash_plan(self, path, override=None, command_available=False):
             destination_label="Trash",
         )
 
-    def update_plan(self, source_root, checkout, status_path):
+    def update_plan(self, source_root, checkout, status_path, retry_revision=""):
         script = ntpath.join(str(source_root), "scripts", "update-windows.ps1")
         return UpdatePlan(
             supported=True,