local-operator-ui 0.17.1 → 0.17.2

package/out/main/index.js

@@ -4422,9 +4422,910 @@ class DesktopNotifier {
     notification.show();
   }
 }
+const PENDING_INSTALL_MARKER_FILE = "pending-update-install.json";
+const INSTALL_DISK_SLACK_BYTES = 256 * 1024 * 1024;
+const DOWNLOAD_PAGE_URL = "https://local-operator.com/download";
+const WATCHDOG_TIMEOUT_SECONDS = 600;
+const PLIST_READ_TIMEOUT_SECONDS = 5;
+const WATCHDOG_TOKEN = "local-operator-update-watchdog";
+const BAD_BUNDLE_MARKERS = [
+  "errSecCSBadBundleFormat",
+  "-67028",
+  "not a valid code object",
+  "code object is not signed at all",
+  "a sealed resource is missing or invalid",
+  "errSecCSUnsigned",
+  "-67062"
+];
+function appBundleFromExecutable(execPath) {
+  const marker = `${path.join("Contents", "MacOS")}/`;
+  const index = execPath.lastIndexOf(marker);
+  if (index <= 0) return null;
+  return execPath.slice(0, index - 1);
+}
+function evaluateBundleSeal(probe) {
+  const output = `${probe.stdout}
+${probe.stderr}`.trim();
+  if (probe.ran === false) {
+    return {
+      kind: "unavailable",
+      detail: `codesign --verify did not complete: ${output || "no output"}`
+    };
+  }
+  if (probe.exitCode === 0) return { kind: "sealed" };
+  const marker = BAD_BUNDLE_MARKERS.find(
+    (candidate) => output.includes(candidate)
+  );
+  return {
+    kind: "unsealed",
+    detail: marker ? `${marker}: ${output || "no output"}` : `codesign --verify exited ${probe.exitCode}: ${output || "no output"}`
+  };
+}
+function installedBundleSealBlock(appBundlePath, detail, version2) {
+  return {
+    code: "installed-bundle-not-sealed",
+    message: version2 ? `This install of Local Operator can't be updated in place, so the update to version ${version2} was stopped before the app quit.` : "This install of Local Operator can't be updated in place, so the update was stopped before the app quit.",
+    remedy: {
+      text: "Quit Local Operator, then download a fresh copy and replace the app in Applications.",
+      url: DOWNLOAD_PAGE_URL
+    },
+    detail: `${appBundlePath}: ${detail}`
+  };
+}
+function metadataBasenames(filePath, updatePath) {
+  const names = [path.basename(filePath)];
+  if (updatePath) names.push(path.basename(updatePath));
+  return names;
+}
+function matchArtifactMetadata(filePath, files, updatePath) {
+  const names = metadataBasenames(filePath, updatePath);
+  for (const name of names) {
+    for (const file of files) {
+      let url = file.url;
+      try {
+        url = decodeURIComponent(url);
+      } catch {
+      }
+      if (path.basename(url) === name) return file;
+    }
+  }
+  return null;
+}
+function requiredDiskBytes(input) {
+  return input.artifactSize + input.installedBundleSize * 2 + INSTALL_DISK_SLACK_BYTES;
+}
+function formatGiB(bytes) {
+  return `${(bytes / 1024 ** 3).toFixed(1)} GiB`;
+}
+function measureDirectoryBytes(root) {
+  try {
+    const stats = fs.lstatSync(root);
+    if (!stats.isDirectory()) return stats.size;
+    let total = 0;
+    for (const entry of fs.readdirSync(root)) {
+      const child = path.join(root, entry);
+      let childStats;
+      try {
+        childStats = fs.lstatSync(child);
+      } catch {
+        continue;
+      }
+      if (childStats.isDirectory()) {
+        const nested = measureDirectoryBytes(child);
+        if (nested != null) total += nested;
+      } else {
+        total += childStats.size;
+      }
+    }
+    return total;
+  } catch {
+    return null;
+  }
+}
+function versionClause(version2) {
+  return version2 ? ` to version ${version2}` : "";
+}
+function verifyStagedArtifact(input) {
+  const name = path.basename(input.filePath);
+  const version2 = input.version ?? null;
+  if (input.metadata == null) {
+    return {
+      ok: false,
+      block: {
+        code: "artifact-metadata-missing",
+        message: `The downloaded update${versionClause(version2)} isn't listed in the release metadata, so it wasn't installed.`,
+        remedy: {
+          text: "Check for updates again to re-download the release."
+        },
+        detail: `${name} has no matching entry in the update metadata.`
+      }
+    };
+  }
+  const expectedSize = input.metadata.size ?? null;
+  if (expectedSize != null && input.actualSize !== expectedSize) {
+    return {
+      ok: false,
+      block: {
+        code: "download-verification-failed",
+        message: `The downloaded update${versionClause(version2)} doesn't match the published release, so it wasn't installed.`,
+        remedy: {
+          text: "Check for updates again to re-download the release."
+        },
+        detail: `${name} is ${input.actualSize} bytes; the release lists ${expectedSize}.`
+      }
+    };
+  }
+  const expectedSha = input.metadata.sha512 ?? null;
+  if (expectedSha != null && input.actualSha512 !== expectedSha) {
+    return {
+      ok: false,
+      block: {
+        code: "download-verification-failed",
+        message: `The downloaded update${versionClause(version2)} doesn't match the published release, so it wasn't installed.`,
+        remedy: {
+          text: "Check for updates again to re-download the release."
+        },
+        detail: `${name} sha512 ${input.actualSha512} does not match the release's ${expectedSha}.`
+      }
+    };
+  }
+  const artifactSize = expectedSize ?? input.actualSize;
+  const installedBundleSize = input.installedBundleSize ?? 0;
+  const needed = requiredDiskBytes({ artifactSize, installedBundleSize });
+  if (input.freeBytes < needed) {
+    const footprint = installedBundleSize ? `${formatGiB(artifactSize)} artifact + two ${formatGiB(
+      installedBundleSize
+    )} app copies + ${formatGiB(INSTALL_DISK_SLACK_BYTES)} slack` : `${formatGiB(artifactSize)} artifact + ${formatGiB(INSTALL_DISK_SLACK_BYTES)} slack (the installed app could not be measured)`;
+    return {
+      ok: false,
+      block: {
+        code: "insufficient-disk-space",
+        message: `There isn't enough free disk space to install the update${versionClause(version2)}, so it wasn't installed.`,
+        remedy: {
+          text: `Free up about ${formatGiB(needed - input.freeBytes)}, then check for updates again.`
+        },
+        detail: `Install needs ${formatGiB(needed)} (${footprint}); ${formatGiB(input.freeBytes)} free.`
+      }
+    };
+  }
+  return { ok: true, sha512: input.actualSha512, size: input.actualSize };
+}
+function resolveStagedArtifactPath(input) {
+  if (input.downloadHelperFile && fs.existsSync(input.downloadHelperFile)) {
+    return input.downloadHelperFile;
+  }
+  if (input.candidateNames.length === 0 || !fs.existsSync(input.pendingDir)) {
+    return null;
+  }
+  const entries = input.listDir(input.pendingDir);
+  for (const name of input.candidateNames) {
+    const match = entries.find((entry) => entry === name);
+    if (match) return path.join(input.pendingDir, match);
+  }
+  return null;
+}
+function pendingInstallMarkerPath(dir) {
+  return path.join(dir, PENDING_INSTALL_MARKER_FILE);
+}
+function writePendingInstallMarker(dir, marker) {
+  fs.mkdirSync(dir, { recursive: true });
+  const target2 = pendingInstallMarkerPath(dir);
+  const temp = `${target2}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(marker, null, 2)}
+`, "utf8");
+  fs.renameSync(temp, target2);
+  return marker;
+}
+function parsePendingInstallMarker(raw) {
+  try {
+    const parsed = JSON.parse(raw);
+    if (typeof parsed?.targetVersion !== "string" || parsed.targetVersion.length === 0) {
+      return null;
+    }
+    return {
+      targetVersion: parsed.targetVersion,
+      artifactPath: typeof parsed.artifactPath === "string" ? parsed.artifactPath : "",
+      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : "",
+      watchdogPid: typeof parsed.watchdogPid === "number" ? parsed.watchdogPid : null
+    };
+  } catch {
+    return null;
+  }
+}
+function readPendingInstallMarker(dir) {
+  const path2 = pendingInstallMarkerPath(dir);
+  if (!fs.existsSync(path2)) return null;
+  try {
+    return parsePendingInstallMarker(fs.readFileSync(path2, "utf8"));
+  } catch {
+    return null;
+  }
+}
+function clearPendingInstallMarker(dir) {
+  const path2 = pendingInstallMarkerPath(dir);
+  if (!fs.existsSync(path2)) return false;
+  fs.rmSync(path2, { force: true });
+  return true;
+}
+const LAST_INSTALL_ATTEMPT_FILE = "last-update-install.json";
+function lastInstallAttemptPath(dir) {
+  return path.join(dir, LAST_INSTALL_ATTEMPT_FILE);
+}
+function readLastInstallAttempt(dir) {
+  const path2 = lastInstallAttemptPath(dir);
+  if (!fs.existsSync(path2)) return null;
+  try {
+    const parsed = JSON.parse(
+      fs.readFileSync(path2, "utf8")
+    );
+    if (typeof parsed?.targetVersion !== "string" || parsed.targetVersion.length === 0) {
+      return null;
+    }
+    return {
+      targetVersion: parsed.targetVersion,
+      runningVersion: typeof parsed.runningVersion === "string" ? parsed.runningVersion : "unknown",
+      startedAt: typeof parsed.startedAt === "string" ? parsed.startedAt : null,
+      detectedAt: typeof parsed.detectedAt === "string" ? parsed.detectedAt : "",
+      detail: typeof parsed.detail === "string" ? parsed.detail : "",
+      attempts: typeof parsed.attempts === "number" && parsed.attempts > 0 ? parsed.attempts : 1
+    };
+  } catch {
+    return null;
+  }
+}
+function recordInstallFailure(dir, input) {
+  const previous = readLastInstallAttempt(dir);
+  const record = {
+    targetVersion: input.payload.targetVersion,
+    runningVersion: previous?.runningVersion ?? "unknown",
+    startedAt: input.startedAt,
+    detectedAt: input.detectedAt,
+    detail: input.payload.detail,
+    attempts: previous && previous.targetVersion === input.payload.targetVersion ? previous.attempts + 1 : 1
+  };
+  fs.mkdirSync(dir, { recursive: true });
+  const target2 = lastInstallAttemptPath(dir);
+  const temp = `${target2}.tmp`;
+  fs.writeFileSync(temp, `${JSON.stringify(record, null, 2)}
+`, "utf8");
+  fs.renameSync(temp, target2);
+  return record;
+}
+const VERSION_TRIPLE_REGEX = /^v?(\d+)\.(\d+)\.(\d+)/;
+function compareVersions(a, b) {
+  const parse = (value) => {
+    const match = VERSION_TRIPLE_REGEX.exec(value.trim());
+    if (!match) return null;
+    return [Number(match[1]), Number(match[2]), Number(match[3])];
+  };
+  const left = parse(a);
+  const right = parse(b);
+  if (!left || !right) return null;
+  for (let index = 0; index < 3; index++) {
+    if (left[index] !== right[index])
+      return left[index] < right[index] ? -1 : 1;
+  }
+  return 0;
+}
+function evaluatePendingInstall(input) {
+  const { marker } = input;
+  if (marker == null) return { kind: "none" };
+  if (marker.targetVersion === input.runningVersion) {
+    return { kind: "succeeded", marker };
+  }
+  const order = compareVersions(marker.targetVersion, input.runningVersion);
+  if (order !== null && order < 0) return { kind: "stale", marker };
+  return { kind: "failed", marker };
+}
+function installFailurePayload(marker, runningVersion, options = {}) {
+  const started = marker.startedAt ? new Date(marker.startedAt) : null;
+  const startedText = started && !Number.isNaN(started.getTime()) ? started.toLocaleString() : "at an unknown time";
+  const logText = options.shipItLogPath ? ` Squirrel's own log is at ${options.shipItLogPath}.` : "";
+  return {
+    message: `The update to version ${marker.targetVersion} didn't finish, so version ${runningVersion} is still running.`,
+    remedy: {
+      text: "Quit Local Operator and replace it in Applications with a fresh copy, or update again from the app.",
+      url: DOWNLOAD_PAGE_URL
+    },
+    detail: `Install started ${startedText} from ${marker.artifactPath || "an unknown artifact"}.${logText}`,
+    targetVersion: marker.targetVersion,
+    attempts: options.attempts ?? 1
+  };
+}
+function shipItJobLabel(bundleId) {
+  return `${bundleId}.ShipIt`;
+}
+function shipItCacheDir(cacheRoot, bundleId) {
+  return path.join(cacheRoot, shipItJobLabel(bundleId));
+}
+function watchdogSwapTarget(input) {
+  if (!input.target) return null;
+  if (!input.running) return input.target;
+  const order = compareVersions(input.target, input.running);
+  if (order !== null && order <= 0) return null;
+  if (input.target === input.running) return null;
+  return input.target;
+}
+function buildWatchdogPlan(input) {
+  const timeoutSeconds = input.timeoutSeconds ?? WATCHDOG_TIMEOUT_SECONDS;
+  const intervalSeconds = input.intervalSeconds ?? 3;
+  const settleSeconds = input.settleSeconds ?? 5;
+  const appearSeconds = input.appearSeconds ?? 30;
+  const plistTimeoutSeconds = input.plistReadTimeoutSeconds ?? PLIST_READ_TIMEOUT_SECONDS;
+  const script = `#!/bin/sh
+# ${WATCHDOG_TOKEN}
+#
+# Why this exists: a failed Squirrel.Mac install quits the app and never brings
+# it back - ShipIt logs an installation error, leaves no exit status and does not
+# run the relaunch - so the user is left with no app and no message (operator
+# report, 2026-09-11, errSecCSBadBundleFormat -67028).
+#
+# How it decides, and why each signal is the one it is:
+#   - "the app has exited" is asked of the app's own pid (kill -0), captured by
+#     the app before it quit. A name probe cannot answer it on macOS: pgrep -f
+#     does not report its own ancestors, and this script is the app's child.
+#   - "the install is over" is asked of BOTH the ShipIt launchd job, by label,
+#     AND the state of the swap on disk. The job is submitted as part of the quit
+#     and unloaded when an install settles, so it is the signal that separates a
+#     hung install from an unrelated process that merely has the word in its
+#     command line - but it is not sufficient on its own: the 0.17.0 failure
+#     left its job loaded and respawning for hours (runs=3114), so waiting only
+#     on the job meant waiting for the bound with the user staring at nothing
+#     (review R11). The version in the target bundle's own Info.plist is what
+#     says the swap landed, whether or not the job ever goes away.
+#
+# It starts the app in exactly one situation - the app is not running - and it
+# reaches that point on three paths:
+#   (a) ShipIt's job is gone: the install is decided. The conservative case.
+#   (b) the bundle at the target path reports the version this update was for, or
+#       one beyond it: the new app is in place and ShipIt has nothing left to do.
+#       This is what makes an early exit safe rather than a guess, and it is the
+#       path a failed-but-swapped install takes.
+#   (c) the bound arrived with no decision. Trying is still better than leaving
+#       the user with nothing, and the bound is what makes the previous
+#       version's silent exit 0 impossible. It is ~2.4x the slowest ShipIt
+#       attempt measured on this machine (255s from request to verdict for a
+#       1 GiB app), and it is the ONE path that can start the app while a swap
+#       is still in flight - an accepted risk, not an oversight.
+#
+# With no job label to ask about, the job cannot be consulted at all, so the swap
+# state is the whole signal: the script waits for (b) rather than spending an
+# appear window on a job it cannot see and then relaunching on no evidence.
+set -u
+APP_PID="\${LO_UPDATE_WATCHDOG_APP_PID:-}"
+BUNDLE="\${LO_UPDATE_WATCHDOG_APP_BUNDLE:-}"
+NAME="\${LO_UPDATE_WATCHDOG_APP_NAME:-}"
+SHIPIT_JOB="\${LO_UPDATE_WATCHDOG_SHIPIT_JOB:-}"
+TARGET_VERSION="\${LO_UPDATE_WATCHDOG_TARGET_VERSION:-}"
+if [ -z "$APP_PID" ] || [ -z "$BUNDLE" ]; then
+	exit 1
+fi
+now() { date +%s; }
+app_running() { kill -0 "$APP_PID" 2>/dev/null; }
+# launchctl list <label> exits 113 when the job is not loaded, 0 when it is.
+shipit_loaded() { [ -n "$SHIPIT_JOB" ] && launchctl list "$SHIPIT_JOB" >/dev/null 2>&1; }
+# (b), the swap's own state: is the app at the target path AT OR BEYOND the
+# version this update was for? plutil rather than \`defaults read\`, which reads
+# through a preference domain and can answer from a stale cache; a half-written
+# plist and a missing one both read as "not landed yet", which is the safe
+# direction.
+#
+# At or beyond rather than an exact match, because this is the same question the
+# renderer's clear rule asks ("is the server no longer behind the version the
+# panel named?"): a release that moves on between the offer and the check must
+# not leave the app waiting out the whole bound for a bundle already past the
+# target (review Q6).
+version_at_least() {
+	# An absent version is not a version. This is the ONE input the two halves
+	# answer differently on, deliberately: the renderer pads a missing side with
+	# zero (\`left[index] ?? 0\`), so it reads an empty target as "at least 0",
+	# while a rule that can start a relaunch must not call a version nobody
+	# reported "landed". Both callers prove the operand non-empty first - the
+	# script's \`swap_landed\` declines an empty target outright and the read
+	# answers nothing rather than a version - so no path reaches this with one.
+	[ -n "$1" ] && [ -n "$2" ] || return 1
+	# Exact match first, as the renderer's rule does: a pre-release pair that
+	# matches exactly IS the version that was waited for, and the digit checks
+	# below cannot order a suffix at all. The caller strips a leading \`v\` before
+	# calling, which is the other half of what the renderer's rule does itself.
+	[ "$1" = "$2" ] && return 0
+	# Anything else carrying a suffix is not orderable here, and the renderer's
+	# rule refuses the same inputs for the same reason ("keeps the instruction on
+	# screen rather than clearing over a real gap"). Answered before the digit
+	# walk, because a suffix the unrelated leading numeric components never reach
+	# would otherwise be ignored - \`1.0.0\` against \`0.18.0-rc1\` compared as
+	# landed here and as not-beyond there. Not-landed is the safe direction in
+	# this script: the job and the bound still decide, and the app still comes
+	# back.
+	case "$1$2" in *-*) return 1 ;; esac
+	_va="$1"
+	_vb="$2"
+	while :; do
+		case "$_va" in
+			*.*) _ha="\${_va%%.*}"; _va="\${_va#*.}" ;;
+			*) _ha="$_va"; _va="" ;;
+		esac
+		case "$_vb" in
+			*.*) _hb="\${_vb%%.*}"; _vb="\${_vb#*.}" ;;
+			*) _hb="$_vb"; _vb="" ;;
+		esac
+		# A component with no digits in it is a pre-release suffix, which this
+		# cannot order: it reads as "not landed", so the job and the bound stay
+		# the deciders. Same shape as the renderer's rule.
+		case "$_ha" in *[!0-9]*) return 1 ;; esac
+		case "$_hb" in *[!0-9]*) return 1 ;; esac
+		# A side that has run out contributes zero, which is what the renderer's
+		# \`left[index] ?? 0\` does, so unequally wide dotted versions order the
+		# same way in both halves of "at or beyond". Without this, \`0.18.0.1\`
+		# against \`0.18.0\` read as not-landed here and as landed there (review
+		# round 4, M3): the safe direction is not a reason to leave two
+		# implementations of one rule disagreeing.
+		[ -n "$_ha" ] || _ha=0
+		[ -n "$_hb" ] || _hb=0
+		if [ "$_ha" -gt "$_hb" ]; then return 0; fi
+		if [ "$_ha" -lt "$_hb" ]; then return 1; fi
+		if [ -z "$_va" ] && [ -z "$_vb" ]; then return 0; fi
+	done
+}
+# Read the bundle's version under a hard time bound. This sits inside the poll
+# loop, and an unbounded read of a path on a mount that has stopped answering
+# would outlive the script's own deadline and leave the user with no app - the
+# very outcome this script exists to undo. macOS ships no \`timeout(1)\`, so the
+# bound is a background read the script can stop waiting on (review R17).
+bundle_version() {
+	_plist="$BUNDLE/Contents/Info.plist"
+	# A plist that is not readable yet - the ordinary state while a swap is in
+	# flight - answers without starting a read at all, so the bound below is only
+	# ever spent on a read that started and did not answer.
+	[ -r "$_plist" ] || return 1
+	_stamp="$$-$(now)"
+	_out="\${TMPDIR:-/tmp}/lo-update-watchdog-version-$_stamp.out"
+	# The pid the bound kills IS the reader: \`exec\` replaces the subshell rather
+	# than wrapping plutil, so nothing is reparented when the kill lands. The
+	# previous shape killed a subshell whose whole job was to drop a completion
+	# marker, and the read that subshell had forked was left blocked under pid 1 -
+	# one more per poll, for as long as the mount stayed dead (review round 4,
+	# Q7). Completion is read off the answer itself instead: plutil writes the
+	# version into this file and nothing else does, so bytes in it mean the read
+	# answered, and a read that fails writes none and is stopped by the same
+	# deadline.
+	( exec /usr/bin/plutil -extract CFBundleShortVersionString raw -o - "$_plist" ) >"$_out" 2>/dev/null &
+	_read_pid=$!
+	_waited=0
+	while [ ! -s "$_out" ]; do
+		if [ "$_waited" -ge ${plistTimeoutSeconds} ]; then
+			kill -9 "$_read_pid" 2>/dev/null
+			rm -f "$_out"
+			return 1
+		fi
+		sleep 1
+		_waited=$((_waited + 1))
+	done
+	_version="$(cat "$_out" 2>/dev/null)"
+	rm -f "$_out"
+	[ -n "$_version" ] || return 1
+	printf '%s
+' "$_version"
+}
+swap_landed() {
+	[ -n "$TARGET_VERSION" ] || return 1
+	installed=$(bundle_version) || return 1
+	installed=\${installed#v}
+	[ -n "$installed" ] || return 1
+	target=\${TARGET_VERSION#v}
+	[ "$installed" = "$target" ] && return 0
+	version_at_least "$installed" "$target"
+}
+job_known=0
+[ -n "$SHIPIT_JOB" ] && job_known=1
+decided() {
+	if [ "$job_known" -eq 1 ] && ! shipit_loaded; then return 0; fi
+	swap_landed && return 0
+	return 1
+}
+deadline=$(( $(now) + ${timeoutSeconds} ))
+# 1. The install only starts once the old app has exited.
+while app_running; do
+	if [ "$(now)" -ge "$deadline" ]; then break; fi
+	sleep ${intervalSeconds}
+done
+# 2. ShipIt's job is submitted as part of the quit, so it may not be loaded the
+#    instant the app is gone: give it a bounded window to appear before treating
+#    "no job" as "the install is over". Skipped when there is no label to ask
+#    about: an appear window for an unaskable job is 30s of pretending, and it
+#    used to end by relaunching with no evidence about the install at all.
+if [ "$job_known" -eq 1 ]; then
+	appear_deadline=$(( $(now) + ${appearSeconds} ))
+	while ! shipit_loaded; do
+		if [ "$(now)" -ge "$appear_deadline" ] || [ "$(now)" -ge "$deadline" ]; then break; fi
+		sleep ${intervalSeconds}
+	done
+fi
+# 3. Wait for the install to be decided - by the job going, or by the swap
+#    landing - and never past the bound.
+while :; do
+	if decided; then break; fi
+	if [ "$(now)" -ge "$deadline" ]; then break; fi
+	sleep ${intervalSeconds}
+done
+# Let Squirrel's own relaunch (which happens as the job finishes) land first.
+sleep ${settleSeconds}
+# 4. Nothing to do if Squirrel relaunched the app or the user started it. This is
+#    what makes the script a no-op when the install succeeded, by construction
+#    rather than by claim.
+if app_running; then exit 0; fi
+if [ -n "$NAME" ] && [ -x "$BUNDLE/Contents/MacOS/$NAME" ]; then
+	open -a "$BUNDLE" >/dev/null 2>&1 || "$BUNDLE/Contents/MacOS/$NAME" >/dev/null 2>&1 &
+fi
+exit 0
+`;
+  return {
+    script,
+    env: {
+      LO_UPDATE_WATCHDOG_APP_PID: String(input.appPid),
+      LO_UPDATE_WATCHDOG_APP_BUNDLE: input.appBundlePath,
+      LO_UPDATE_WATCHDOG_APP_NAME: input.executableName,
+      LO_UPDATE_WATCHDOG_SHIPIT_JOB: input.shipItJob ?? "",
+      LO_UPDATE_WATCHDOG_TARGET_VERSION: input.targetVersion ?? ""
+    },
+    timeoutSeconds
+  };
+}
+function reapFailedInstall(input) {
+  const result = {
+    jobLabel: null,
+    jobRemoved: false,
+    removedStaging: [],
+    errors: []
+  };
+  if (!input.bundleId) {
+    input.log(
+      "Skipped cleaning up the failed install: the app's bundle id could not be read."
+    );
+    return result;
+  }
+  const label = shipItJobLabel(input.bundleId);
+  result.jobLabel = label;
+  try {
+    const removal = input.removeJob(label);
+    result.jobRemoved = !removal.notFound;
+    input.log(
+      removal.notFound ? `Leftover install job ${label} was not loaded.` : `Removed the leftover install job ${label}.`
+    );
+  } catch (error) {
+    result.errors.push(`launchctl remove ${label}: ${String(error)}`);
+    input.log(
+      `Could not remove the leftover install job ${label}: ${String(error)}`
+    );
+  }
+  const cacheDir = input.cacheRoot ? shipItCacheDir(input.cacheRoot, input.bundleId) : null;
+  if (!cacheDir) return result;
+  try {
+    if (!input.exists(cacheDir)) return result;
+    for (const entry of input.listDir(cacheDir)) {
+      if (!entry.startsWith("update.")) continue;
+      const staging = path.join(cacheDir, entry);
+      try {
+        input.removeDir(staging);
+        result.removedStaging.push(staging);
+        input.log(`Removed the staged update left behind at ${staging}.`);
+      } catch (error) {
+        result.errors.push(`${staging}: ${String(error)}`);
+        input.log(`Could not remove ${staging}: ${String(error)}`);
+      }
+    }
+  } catch (error) {
+    result.errors.push(`${cacheDir}: ${String(error)}`);
+    input.log(`Could not inspect ${cacheDir}: ${String(error)}`);
+  }
+  return result;
+}
+function watchdogIsOurs(input) {
+  if (!input.alive || !input.installSucceeded) return false;
+  return (input.commandLine ?? "").includes(WATCHDOG_TOKEN);
+}
+const UV_TOOL_LIST_ENTRY_REGEX = /(^|\n)local-operator v\d/i;
+const PIPX_LIST_ENTRY_REGEX = /(^|\n)\s*package local-operator\b/i;
+function uvToolListNamesLocalOperator(output) {
+  return UV_TOOL_LIST_ENTRY_REGEX.test(output ?? "");
+}
+function pipxListNamesLocalOperator(output) {
+  return PIPX_LIST_ENTRY_REGEX.test(output ?? "");
+}
+const PYTHON_LIB_DIR = /^python\d/;
+const LOCAL_OPERATOR_DIST_INFO = /^local[-_]operator[-_]/;
+function resolveDistributionMarkers(prefix) {
+  const sitePackages = [];
+  try {
+    for (const entry of fs.readdirSync(path.join(prefix, "lib"))) {
+      if (!PYTHON_LIB_DIR.test(entry)) continue;
+      const candidate = path.join(prefix, "lib", entry, "site-packages");
+      if (fs.existsSync(candidate)) sitePackages.push(candidate);
+    }
+  } catch {
+  }
+  const windowsSitePackages = path.join(prefix, "Lib", "site-packages");
+  if (fs.existsSync(windowsSitePackages)) sitePackages.push(windowsSitePackages);
+  let installer = null;
+  let editable = false;
+  for (const dir of sitePackages) {
+    let entries;
+    try {
+      entries = fs.readdirSync(dir);
+    } catch {
+      continue;
+    }
+    for (const entry of entries) {
+      if (!LOCAL_OPERATOR_DIST_INFO.test(entry)) continue;
+      if (!entry.endsWith(".dist-info")) continue;
+      const distInfo = path.join(dir, entry);
+      try {
+        const installerText = fs.readFileSync(path.join(distInfo, "INSTALLER"), "utf8");
+        installer = installerText.trim().toLowerCase() || installer;
+      } catch {
+      }
+      try {
+        const payload = JSON.parse(
+          fs.readFileSync(path.join(distInfo, "direct_url.json"), "utf8")
+        );
+        if (payload.editable === true || payload.dir_info?.editable === true) {
+          editable = true;
+        }
+      } catch {
+      }
+    }
+  }
+  return { installer, editable };
+}
+const TRAILING_SLASHES = /\/+$/;
+function commandSearchDirs(env, home) {
+  const dirs = [];
+  const add = (dir) => {
+    if (!dir) return;
+    const trimmed = dir.replace(TRAILING_SLASHES, "");
+    if (trimmed.length === 0 || dirs.includes(trimmed)) return;
+    dirs.push(trimmed);
+  };
+  for (const dir of (env.PATH ?? "").split(path.delimiter)) add(dir);
+  add(env.UV_TOOL_BIN_DIR);
+  add(env.XDG_BIN_HOME);
+  if (env.XDG_DATA_HOME) add(path.join(env.XDG_DATA_HOME, "..", "bin"));
+  add(path.join(home, ".local", "bin"));
+  add("/opt/homebrew/bin");
+  add("/usr/local/bin");
+  add("/usr/bin");
+  add("/bin");
+  return dirs;
+}
+function uvToolBinDirs(env, home, listDir, platform) {
+  const root = env.UV_TOOL_DIR ?? (env.XDG_DATA_HOME ? path.join(env.XDG_DATA_HOME, "uv", "tools") : path.join(home, ".local", "share", "uv", "tools"));
+  const scriptDir = platform === "win32" ? "Scripts" : "bin";
+  const dirs = [];
+  try {
+    for (const entry of listDir(root)) {
+      dirs.push(path.join(root, entry, scriptDir));
+    }
+  } catch {
+  }
+  return dirs;
+}
+const WINDOWS_DEFAULT_PATHEXT = ".COM;.EXE;.BAT;.CMD";
+function windowsCommandExtensions(env) {
+  const raw = (env.PATHEXT ?? "").trim();
+  const parts = (raw.length > 0 ? raw : WINDOWS_DEFAULT_PATHEXT).split(";");
+  const extensions = [];
+  for (const part of parts) {
+    const extension = part.trim();
+    if (extension.length === 0 || extensions.includes(extension)) continue;
+    extensions.push(extension);
+  }
+  return extensions;
+}
+function commandCandidates(dir, name, env, platform) {
+  const candidates = [path.join(dir, name)];
+  if (platform !== "win32") return candidates;
+  for (const extension of windowsCommandExtensions(env)) {
+    candidates.push(path.join(dir, name + extension));
+  }
+  return candidates;
+}
+function resolveCommandPath(name, options = {}) {
+  const env = options.env ?? process.env;
+  const home = options.home ?? os.homedir();
+  const platform = options.platform ?? process.platform;
+  const exists = options.exists ?? fs.existsSync;
+  const listDir = options.listDir ?? ((dir) => {
+    try {
+      return fs.readdirSync(dir);
+    } catch {
+      return [];
+    }
+  });
+  const dirs = [
+    ...commandSearchDirs(env, home),
+    ...uvToolBinDirs(env, home, listDir, platform)
+  ];
+  for (const dir of dirs) {
+    for (const candidate of commandCandidates(dir, name, env, platform)) {
+      try {
+        if (exists(candidate)) return candidate;
+      } catch {
+      }
+    }
+  }
+  return null;
+}
+function readInstallIdentity(shimPath) {
+  if (!shimPath) return { path: null };
+  let realPath = null;
+  try {
+    realPath = fs.realpathSync(shimPath);
+  } catch {
+    realPath = null;
+  }
+  let shebang = null;
+  try {
+    const firstLine = fs.readFileSync(shimPath, "utf8").split("\n", 1)[0] ?? "";
+    shebang = firstLine.startsWith("#!") ? firstLine : null;
+  } catch {
+    shebang = null;
+  }
+  const executable = realPath ?? shimPath;
+  const prefix = path.dirname(path.dirname(executable));
+  const existing = (candidate) => fs.existsSync(candidate) ? candidate : null;
+  const markers = resolveDistributionMarkers(prefix);
+  return {
+    path: shimPath,
+    realPath,
+    shebang,
+    uvReceipt: existing(path.join(prefix, "uv-receipt.toml")),
+    venvPrefix: fs.existsSync(path.join(prefix, "pyvenv.cfg")) ? prefix : null,
+    installer: markers.installer,
+    editable: markers.editable
+  };
+}
+function classifyGlobalInstall(identity) {
+  if (!identity.path) return "global-unknown";
+  if (identity.editable) return "editable";
+  const haystack = [
+    identity.path,
+    identity.realPath ?? "",
+    identity.shebang ?? ""
+  ].join("\n").toLowerCase();
+  if (haystack.includes("/uv/tools/")) return "uv-tool";
+  if (identity.uvReceipt) return "uv-tool";
+  if (uvToolListNamesLocalOperator(identity.uvToolList)) return "uv-tool";
+  if (haystack.includes("/pipx/venvs/") || haystack.includes("/pipx/") && haystack.includes("venvs"))
+    return "pipx";
+  if (pipxListNamesLocalOperator(identity.pipxList)) return "pipx";
+  if (identity.venvPrefix) return "pip";
+  if (identity.installer === "pip") return "pip";
+  return "global-unknown";
+}
+function resolveGlobalInstallPlan(input) {
+  const kind = classifyGlobalInstall(input.identity);
+  const sourceBuild = kind === "editable" || kind === "uv-tool" && Boolean(input.lopUpdatePath);
+  const detail = input.identity.path ? `local-operator resolves to ${input.identity.path}${input.identity.realPath && input.identity.realPath !== input.identity.path ? ` (${input.identity.realPath})` : ""}, classified as ${kind}${sourceBuild ? ", built from source on this machine, so it follows the checkout rather than the published release" : ""}` : "local-operator was not found on PATH";
+  if (kind === "editable") {
+    return {
+      canManageUpdate: false,
+      updateCommand: "",
+      remedy: "The server is running from a source checkout on this machine rather than an installed copy, so update it with lop-update after your change is merged.",
+      detail,
+      sourceBuild: true
+    };
+  }
+  if (kind === "uv-tool") {
+    const useLopUpdate = Boolean(input.lopUpdatePath);
+    return {
+      canManageUpdate: false,
+      updateCommand: useLopUpdate ? "lop-update" : "uv tool upgrade local-operator",
+      remedy: useLopUpdate ? "The server is a uv tool install built from source on this machine, so update it from your terminal:" : "The server is a uv tool install, so update it from your terminal:",
+      detail,
+      sourceBuild
+    };
+  }
+  if (kind === "pipx") {
+    return {
+      canManageUpdate: false,
+      updateCommand: "pipx upgrade local-operator",
+      remedy: "The server is a pipx install, so update it from your terminal:",
+      detail,
+      sourceBuild: false
+    };
+  }
+  if (kind === "pip") {
+    return {
+      canManageUpdate: false,
+      updateCommand: "pip install --upgrade local-operator",
+      remedy: "The server is a pip install, so update it from your terminal:",
+      detail,
+      sourceBuild: false
+    };
+  }
+  return {
+    canManageUpdate: false,
+    updateCommand: "",
+    remedy: "The app could not tell how this server was installed, so update it with the tool you installed it with - uv, pipx or pip:",
+    detail,
+    sourceBuild: false
+  };
+}
+function buildPipUpgradeCommand(pythonPath) {
+  const args = [
+    "-m",
+    "pip",
+    "install",
+    "--upgrade",
+    "--no-input",
+    "--disable-pip-version-check",
+    "local-operator"
+  ];
+  return {
+    command: pythonPath,
+    args,
+    display: `"${pythonPath}" ${args.join(" ")}`
+  };
+}
+const PIP_SHOW_VERSION_REGEX = /^Version:\s*(.+)$/m;
+function parsePipShowVersion(stdout) {
+  const match = stdout.match(PIP_SHOW_VERSION_REGEX);
+  if (!match) return null;
+  const version2 = match[1].trim();
+  return version2.length > 0 ? version2 : null;
+}
+function didUpgradeLand(input) {
+  const { before, after, target: target2 } = input;
+  if (after == null) return false;
+  if (before == null) {
+    return target2 != null && after.trim() === target2.trim();
+  }
+  return before.trim() !== after.trim();
+}
 const VERSION_LINE_REGEX = /Version:\s*([^\n]+)/;
 const VERSION_CLEAN_REGEX = /^v/i;
 const BETA_VERSION_REGEX = /v\d+\.\d+\.\d+\.beta\.\d+/;
+const BUNDLE_ID_REGEX = /^[\w.-]+$/;
+const LAUNCHCTL_NOT_LOADED_REGEX = /could not find|no such process/i;
+const SEAL_PROBE_TIMEOUT_MS = 45e3;
+function versionSuffix(version2) {
+  return version2 ? ` to version ${version2}` : "";
+}
+function runCommand(command, args, options = {}) {
+  return new Promise((resolve) => {
+    node_child_process.execFile(
+      command,
+      args,
+      { timeout: options.timeoutMs ?? 2e4, maxBuffer: 4 * 1024 * 1024 },
+      (error, stdout, stderr) => {
+        const code = error?.code;
+        const killed = error?.killed === true;
+        const out = stdout?.toString() ?? "";
+        const err = stderr?.toString() ?? "";
+        resolve({
+          exitCode: error ? typeof code === "number" ? code : 1 : 0,
+          stdout: out,
+          stderr: err,
+          // A timeout (killed) or a process that failed to start (a string
+          // code such as ENOENT) produced no verdict about the bundle. A
+          // numeric exit with output did.
+          ran: !error || !killed && typeof code === "number" && `${out}${err}`.trim().length > 0
+        });
+      }
+    );
+  });
+}
+function readCommandOutput(command, args) {
+  try {
+    const output = node_child_process.execFileSync(command, args, {
+      encoding: "utf8",
+      timeout: 5e3
+    });
+    return output.trim();
+  } catch {
+    return null;
+  }
+}
 class UpdateService {
   mainWindow = null;
   isDevMode;
@@ -4432,6 +5333,47 @@ class UpdateService {
   backendUrl;
   updateCheckInterval = null;
   backendService = null;
+  /**
+   * What the updater is doing right now.
+   *
+   * Only used to decide whether an `error` event is a failure the user has to
+   * hear about: a download or an install that dies is not "no update
+   * available", which is how `shouldFilterUpdateError` would otherwise read it.
+   */
+  updateStage = "idle";
+  /** The last update the updater told us about, for its file metadata. */
+  lastUpdateInfo = null;
+  /**
+   * The version the published release last answered with, or null.
+   *
+   * The by-hand prompt is produced from a click, not from a check, so it has no
+   * version of its own to name - and the panel that tells the user to go and do
+   * work is the one that most needs to say what they are working towards. The
+   * periodic and start-up checks read this from the published release already,
+   * so it is kept rather than fetched again on the click (review U17).
+   */
+  lastPublishedBackendVersion = null;
+  /** Path of the artifact this run downloaded, when the updater reported one. */
+  downloadedArtifactPath = null;
+  /**
+   * Artifacts that failed their size/sha512/disk check, by version.
+   *
+   * The 5-minute periodic check runs regardless of what the user dismissed, so
+   * without this an update that cannot be verified is offered again every five
+   * minutes for as long as the app is open.
+   */
+  failedVerificationVersions = /* @__PURE__ */ new Set();
+  /** A failed install detected from the marker on this start, if any. */
+  pendingInstallFailure = null;
+  installFailureDelivered = false;
+  /**
+   * True while `quit-and-install` is running its pre-flight.
+   *
+   * The pre-flight can take seconds over a large bundle and artifact, and the
+   * whole point of it is that a second request must not run beside the first (see
+   * the handler).
+   */
+  installPreflightInFlight = false;
   /**
    * Initialize the update service
    * @param mainWindow - The main application window
@@ -4455,8 +5397,9 @@ class UpdateService {
       debug: (message) => logger.debug(message, LogFileType.UPDATE_SERVICE)
     };
     electronUpdater.autoUpdater.autoDownload = false;
-    electronUpdater.autoUpdater.autoInstallOnAppQuit = true;
+    electronUpdater.autoUpdater.autoInstallOnAppQuit = false;
     this.setupUpdateEvents();
+    this.recoverPendingInstall();
     this.startPeriodicUpdateChecks();
   }
   /**
@@ -4479,6 +5422,517 @@ class UpdateService {
       LogFileType.UPDATE_SERVICE
     );
   }
+  // -----------------------------------------------------------------------
+  // Install robustness
+  // -----------------------------------------------------------------------
+  /**
+   * Where the pending-update marker lives.
+   *
+   * userData, not the app bundle: the marker has to survive the bundle being
+   * replaced (that is exactly the case it describes) and it must not be inside
+   * the thing ShipIt is swapping.
+   */
+  markerDir() {
+    return electron.app.getPath("userData");
+  }
+  sendToRenderer(channel, payload) {
+    const webContents = this.mainWindow?.webContents;
+    if (!webContents || webContents.isDestroyed()) return false;
+    webContents.send(channel, payload);
+    return true;
+  }
+  /**
+   * Report a refusal to start an install, with the reason and the remedy.
+   *
+   * Sent rather than thrown: the caller is an IPC handler the renderer fires and
+   * forgets, and the whole point of these checks is that the user gets an
+   * explanation instead of an app that quits and never returns.
+   */
+  sendInstallBlock(block, version2) {
+    logger.error(
+      `Update refused (${block.code}): ${block.detail}`,
+      LogFileType.UPDATE_SERVICE
+    );
+    this.sendToRenderer("update-install-blocked", {
+      code: block.code,
+      version: version2 ?? null,
+      message: block.message,
+      remedy: block.remedy,
+      detail: block.detail
+    });
+  }
+  /**
+   * Read the marker a previous run may have left, and act on it.
+   *
+   * A failed Squirrel install leaves no exit status and never relaunches the
+   * app, so the marker plus the running version is the only record that the
+   * update did not happen. Everything the user learns afterwards starts here:
+   * the notice, the durable record it can be found in later, and the cleanup of
+   * what Squirrel left running.
+   */
+  recoverPendingInstall() {
+    const marker = readPendingInstallMarker(this.markerDir());
+    const outcome = evaluatePendingInstall({
+      marker,
+      runningVersion: electron.app.getVersion()
+    });
+    switch (outcome.kind) {
+      case "none":
+        return;
+      case "succeeded":
+        logger.info(
+          `Update marker: install of version ${outcome.marker.targetVersion} succeeded (running ${electron.app.getVersion()}).`,
+          LogFileType.UPDATE_SERVICE
+        );
+        this.reapWatchdog(outcome.marker, true);
+        clearPendingInstallMarker(this.markerDir());
+        return;
+      case "stale":
+        logger.info(
+          `Update marker: ignored a marker for version ${outcome.marker.targetVersion}; version ${electron.app.getVersion()} is running, so it was superseded.`,
+          LogFileType.UPDATE_SERVICE
+        );
+        this.reapWatchdog(outcome.marker, true);
+        clearPendingInstallMarker(this.markerDir());
+        return;
+      case "failed": {
+        const shipItLogPath = this.shipItLog();
+        const record = recordInstallFailure(this.markerDir(), {
+          payload: installFailurePayload(outcome.marker, electron.app.getVersion(), {
+            shipItLogPath
+          }),
+          startedAt: outcome.marker.startedAt || null,
+          detectedAt: (/* @__PURE__ */ new Date()).toISOString()
+        });
+        const payload = installFailurePayload(
+          outcome.marker,
+          electron.app.getVersion(),
+          { attempts: record.attempts, shipItLogPath }
+        );
+        logger.error(
+          `Update marker: install of version ${outcome.marker.targetVersion} did not complete (attempt ${record.attempts}). ${payload.detail}`,
+          LogFileType.UPDATE_SERVICE
+        );
+        this.pendingInstallFailure = payload;
+        this.reapWatchdog(outcome.marker, false);
+        clearPendingInstallMarker(this.markerDir());
+        this.reapFailedInstallLeftovers();
+        this.schedulePendingInstallFailureDelivery();
+      }
+    }
+  }
+  /**
+   * This app's bundle identifier, as macOS records it.
+   *
+   * Read from the running bundle rather than from `package.json`: the running
+   * app is the only thing whose ShipIt job and cache directory this process may
+   * touch, and a build whose `appId` drifted would otherwise have us cleaning up
+   * some other app's leftovers.
+   */
+  bundleIdentifier() {
+    const bundlePath = appBundleFromExecutable(process.execPath);
+    if (!bundlePath) return null;
+    const value = readCommandOutput("/usr/bin/defaults", [
+      "read",
+      path.join(bundlePath, "Contents", "Info.plist"),
+      "CFBundleIdentifier"
+    ]);
+    return value && BUNDLE_ID_REGEX.test(value) ? value : null;
+  }
+  /** The launchd job Squirrel's install runs under, by label. */
+  shipItJob() {
+    const bundleId = this.bundleIdentifier();
+    return bundleId ? shipItJobLabel(bundleId) : null;
+  }
+  /**
+   * Squirrel's own stderr log for this app, when it exists.
+   *
+   * It is the only record of why an install failed: the app is not running
+   * while ShipIt works, so the failure notice cannot quote a reason the way the
+   * pre-flight refusal can. The log is preserved by `reapFailedInstallLeftovers`
+   * for exactly this reason, so the details line points at the thing that is
+   * still there afterwards (review U14).
+   */
+  shipItLog() {
+    const bundleId = this.bundleIdentifier();
+    if (!bundleId) return null;
+    const candidate = path.join(
+      shipItCacheDir(path.join(os.homedir(), "Library", "Caches"), bundleId),
+      "ShipIt_stderr.log"
+    );
+    return fs.existsSync(candidate) ? candidate : null;
+  }
+  /**
+   * Remove the launchd job and the staged update a failed install left behind.
+   *
+   * Why: the 0.17.0 failure left `com.local-operator.ShipIt` loaded in the
+   * user's launchd domain, respawning every ~2.5 s (runs=3114,
+   * LastExitStatus=256) and writing 3.4 MB of "Could not read update request" to
+   * its stderr log, with the staged tree beside it. Squirrel only retires that
+   * job when an install finishes, so a failed one leaves it running forever - it
+   * was removed by hand during round 1 of the review, and the product must not
+   * need that.
+   */
+  reapFailedInstallLeftovers() {
+    if (process.platform !== "darwin") return;
+    const log = (message) => logger.info(message, LogFileType.UPDATE_SERVICE);
+    try {
+      const result = reapFailedInstall({
+        bundleId: this.bundleIdentifier(),
+        cacheRoot: path.join(os.homedir(), "Library", "Caches"),
+        removeJob: (label) => {
+          const result2 = node_child_process.spawnSync("/bin/launchctl", ["remove", label], {
+            encoding: "utf8",
+            timeout: 5e3
+          });
+          const output = `${result2.stdout ?? ""}${result2.stderr ?? ""}`.trim();
+          const notFound = LAUNCHCTL_NOT_LOADED_REGEX.test(output) || output === "" && result2.status !== 0;
+          if (result2.status !== 0 && !notFound) {
+            throw new Error(
+              output || `launchctl remove exited ${result2.status}`
+            );
+          }
+          return { notFound, output };
+        },
+        exists: (path2) => fs.existsSync(path2),
+        listDir: (dir) => fs.readdirSync(dir),
+        removeDir: (dir) => fs.rmSync(dir, { recursive: true, force: true }),
+        log
+      });
+      if (result.errors.length > 0) {
+        logger.warn(
+          `Failed to clean up the leftover install: ${result.errors.join("; ")}`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+    } catch (error) {
+      logger.warn(
+        `Could not clean up the leftover install: ${String(error)}`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+  }
+  /**
+   * Deliver the failed-install notice once the renderer can hear it.
+   *
+   * The marker is read while the window is still loading, so the push happens
+   * on `did-finish-load` with a delayed fallback: the component subscribes from
+   * a React effect, which may run after the load event.
+   */
+  schedulePendingInstallFailureDelivery() {
+    if (!this.pendingInstallFailure) return;
+    const deliver = () => this.deliverPendingInstallFailure();
+    const webContents = this.mainWindow?.webContents;
+    if (webContents && !webContents.isDestroyed()) {
+      webContents.once("did-finish-load", deliver);
+    }
+    setTimeout(deliver, 5e3);
+  }
+  deliverPendingInstallFailure() {
+    if (!this.pendingInstallFailure || this.installFailureDelivered) return;
+    if (!this.sendToRenderer("update-install-failed", this.pendingInstallFailure)) {
+      return;
+    }
+    this.installFailureDelivered = true;
+    logger.info(
+      "Reported a failed update install to the renderer",
+      LogFileType.UPDATE_SERVICE
+    );
+  }
+  /**
+   * Kill a watchdog still running from the recorded install attempt.
+   *
+   * Killing by pid alone would be unsafe after a pid reuse, so the process's
+   * command line has to still carry the script's sentinel.
+   */
+  reapWatchdog(marker, installSucceeded) {
+    const pid = marker.watchdogPid;
+    if (pid == null) return;
+    let commandLine = null;
+    let alive = false;
+    commandLine = readCommandOutput("/bin/ps", [
+      "-o",
+      "command=",
+      "-p",
+      String(pid)
+    ]);
+    alive = commandLine != null;
+    if (!watchdogIsOurs({ alive, commandLine, installSucceeded })) {
+      if (alive && !installSucceeded) {
+        logger.info(
+          `Relaunch watchdog ${pid} is still running; leaving it to finish or hit its deadline.`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+      return;
+    }
+    try {
+      process.kill(pid, "SIGTERM");
+      logger.info(
+        `Reaped relaunch watchdog ${pid} left over from the previous install.`,
+        LogFileType.UPDATE_SERVICE
+      );
+    } catch (error) {
+      logger.warn(
+        `Could not reap relaunch watchdog ${pid}: ${String(error)}`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+  }
+  /**
+   * Ask `codesign` whether the installed bundle is a sealed code object.
+   *
+   * This is the exact question ShipIt asks of the same bundle before it
+   * installs (`SecStaticCodeCreateWithPath` in SQRLInstaller): on 2026-09-11 it
+   * answered -67028 errSecCSBadBundleFormat because a Finder copy was replacing
+   * the app at that moment, ShipIt quit, and nothing relaunched the app.
+   * Refusing the install here keeps the user with a working app instead.
+   *
+   * Three deliberate properties, all of them from round 1's findings:
+   *
+   * - `--strict` is gone. It does not test the seal - `--verify` does that, and
+   *   it is what catches the mid-replacement -67028 - it additionally rejects
+   *   bundles carrying FinderInfo/detritus xattrs that ShipIt itself tolerates,
+   *   so it can only refuse installs Squirrel would have performed (R5).
+   * - The timeout is generous because the bundle is ~1 GiB; measured warm at
+   *   6.1 s, and a cold or slow volume is not a reason to refuse.
+   * - A probe that could not run is retried once and then *allowed to proceed*.
+   *   "We could not ask" is not "the bundle is bad", and treating it as one is
+   *   how a transient hiccup became a permanent reinstall message (R5).
+   */
+  async probeInstalledBundleSeal(version2) {
+    if (process.platform !== "darwin" || !electron.app.isPackaged) return null;
+    const bundlePath = appBundleFromExecutable(process.execPath);
+    if (!bundlePath) {
+      logger.warn(
+        `Could not derive an app bundle from ${process.execPath}; skipping the seal pre-flight.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    const probeBundle = () => runCommand(
+      "/usr/bin/codesign",
+      ["--verify", "--deep", "--verbose=2", bundlePath],
+      { timeoutMs: SEAL_PROBE_TIMEOUT_MS }
+    );
+    let seal = evaluateBundleSeal(await probeBundle());
+    if (seal.kind === "unavailable") {
+      logger.warn(
+        `Seal check did not complete, retrying once: ${seal.detail}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      seal = evaluateBundleSeal(await probeBundle());
+    }
+    if (seal.kind === "unavailable") {
+      logger.warn(
+        `Seal check could not run twice, continuing with the install: ${seal.detail}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    if (seal.kind === "sealed") {
+      logger.info(
+        `Installed bundle passed its seal check: ${bundlePath}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    logger.error(
+      `Installed bundle failed its seal check: ${seal.detail}`,
+      LogFileType.UPDATE_SERVICE
+    );
+    return installedBundleSealBlock(bundlePath, seal.detail, version2);
+  }
+  /** File names the updater's metadata knows this update by. */
+  stagedArtifactCandidates(info) {
+    const names = /* @__PURE__ */ new Set();
+    if (info?.path) names.add(path.basename(info.path));
+    for (const file of info?.files ?? []) {
+      if (file.url) names.add(path.basename(decodeURIComponent(file.url)));
+    }
+    if (this.downloadedArtifactPath) {
+      names.add(path.basename(this.downloadedArtifactPath));
+    }
+    return [...names];
+  }
+  /**
+   * electron-updater exposes no public path for the staged file; the private
+   * download helper is authoritative for a download this run performed, and a
+   * null simply falls back to the updater's pending cache directory.
+   */
+  downloadHelper() {
+    const updater = electronUpdater.autoUpdater;
+    return updater.downloadedUpdateHelper ?? null;
+  }
+  /** Free bytes on the volume holding `dir`, or null when it cannot be read. */
+  freeBytesAt(dir) {
+    try {
+      const stats = fs.statfsSync(dir);
+      return stats.bavail * stats.bsize;
+    } catch (error) {
+      logger.warn(
+        `Could not read free space for ${dir}: ${String(error)}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+  }
+  static async sha512Base64(filePath) {
+    const hash = node_crypto.createHash("sha512");
+    const stream = fs.createReadStream(filePath);
+    for await (const chunk of stream) {
+      hash.update(chunk);
+    }
+    return hash.digest("base64");
+  }
+  /**
+   * Verify the staged artifact against the metadata the updater parsed.
+   *
+   * electron-updater checks a file's sha512 while downloading it, but a staged
+   * file reused on a later start is only checked for existence (`"check here
+   * only existence, not checksum"` in its own DownloadedUpdateHelper), and the
+   * install's real footprint - a full copy of the app - is never checked
+   * against the free space available.
+   */
+  async ensureStagedArtifactVerified(info) {
+    const helper = this.downloadHelper();
+    const pendingDir = helper?.cacheDirForPendingUpdate ?? null;
+    const candidates = this.stagedArtifactCandidates(info);
+    const artifactPath = resolveStagedArtifactPath({
+      downloadHelperFile: this.downloadedArtifactPath ?? helper?.file ?? null,
+      pendingDir: pendingDir ?? "",
+      candidateNames: candidates,
+      listDir: (dir) => {
+        try {
+          return fs.readdirSync(dir);
+        } catch {
+          return [];
+        }
+      }
+    });
+    if (!artifactPath) {
+      return {
+        code: "download-verification-failed",
+        message: `The downloaded update${versionSuffix(info?.version)} could not be found on disk, so it wasn't installed.`,
+        remedy: {
+          text: "Check for updates again to re-download the release."
+        },
+        detail: `No staged artifact matching ${candidates.join(", ") || "the update metadata"}.`
+      };
+    }
+    const files = info?.files ?? [];
+    const metadata = matchArtifactMetadata(
+      artifactPath,
+      files,
+      info?.path ?? null
+    );
+    let actualSize;
+    let actualSha512;
+    try {
+      actualSize = fs.statSync(artifactPath).size;
+      actualSha512 = await UpdateService.sha512Base64(artifactPath);
+    } catch (error) {
+      return {
+        code: "download-verification-failed",
+        message: `The downloaded update${versionSuffix(info?.version)} could not be read, so it wasn't installed.`,
+        remedy: {
+          text: "Check for updates again to re-download the release."
+        },
+        detail: `${artifactPath}: ${String(error)}`
+      };
+    }
+    const bundlePath = appBundleFromExecutable(process.execPath);
+    const installedBundleSize = bundlePath ? measureDirectoryBytes(bundlePath) : null;
+    if (installedBundleSize == null) {
+      logger.warn(
+        `Could not measure the installed app at ${bundlePath ?? "(no bundle path)"}; the free-space guard falls back to the artifact's own size.`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+    const freeCandidates = [
+      bundlePath ? this.freeBytesAt(path__namespace.dirname(bundlePath)) : null,
+      this.freeBytesAt(path__namespace.dirname(artifactPath))
+    ].filter((value) => value != null);
+    const freeBytes = freeCandidates.length > 0 ? Math.min(...freeCandidates) : Number.MAX_SAFE_INTEGER;
+    const verdict = verifyStagedArtifact({
+      filePath: artifactPath,
+      actualSize,
+      actualSha512,
+      metadata,
+      freeBytes,
+      installedBundleSize,
+      version: info?.version ?? null
+    });
+    if (verdict.ok) {
+      const required = requiredDiskBytes({
+        artifactSize: verdict.size,
+        installedBundleSize: installedBundleSize ?? 0
+      });
+      logger.info(
+        `Staged artifact verified: ${artifactPath} (${verdict.size} bytes, sha512 matches, ${required} bytes required free, ${installedBundleSize ?? "unknown"} byte app).`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    return verdict.block;
+  }
+  /**
+   * Everything that has to hold before the app is allowed to quit.
+   *
+   * Returns the reason to refuse, or null to go ahead.
+   */
+  async runInstallPreflight(info) {
+    const sealBlock = await this.probeInstalledBundleSeal(
+      info?.version ?? null
+    );
+    if (sealBlock) return sealBlock;
+    return this.ensureStagedArtifactVerified(info);
+  }
+  /**
+   * Start the detached relaunch watchdog.
+   *
+   * Spawned detached so it survives this process exiting, with stdio ignored so
+   * it holds no pipe open and cannot keep the app alive.
+   */
+  launchWatchdog(targetVersion) {
+    if (process.platform !== "darwin" || !electron.app.isPackaged) return null;
+    const bundlePath = appBundleFromExecutable(process.execPath);
+    if (!bundlePath) return null;
+    const plan = buildWatchdogPlan({
+      appBundlePath: bundlePath,
+      executableName: path.basename(process.execPath),
+      // The app's own pid, captured here - before the quit - because the
+      // watchdog cannot ask a name about its own ancestor (review R1).
+      appPid: process.pid,
+      shipItJob: this.shipItJob(),
+      // What "the install is over" is measured against on disk (review R11):
+      // the updater's advertised version, and nothing that is already in place
+      // (review R15).
+      targetVersion: watchdogSwapTarget({
+        target: targetVersion,
+        running: electron.app.getVersion()
+      })
+    });
+    try {
+      const child = node_child_process.spawn("sh", ["-c", plan.script], {
+        detached: true,
+        stdio: "ignore",
+        env: { ...process.env, ...plan.env }
+      });
+      child.unref();
+      logger.info(
+        `Started the update relaunch watchdog (pid ${child.pid ?? "unknown"}): it starts the app again as soon as the install's job goes or version ${plan.env.LO_UPDATE_WATCHDOG_TARGET_VERSION || "unknown"} is in place, and at the ${plan.timeoutSeconds}s bound if neither happens.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return child.pid ?? null;
+    } catch (error) {
+      logger.error(
+        `Could not start the update relaunch watchdog: ${String(error)}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+  }
   /**
    * Clean up resources when the service is no longer needed
    */
@@ -4494,6 +5948,7 @@ class UpdateService {
     electron.ipcMain.removeHandler("check-for-updates");
     electron.ipcMain.removeHandler("check-for-backend-updates");
     electron.ipcMain.removeHandler("check-for-all-updates");
+    electron.ipcMain.removeHandler("get-last-install-attempt");
     electron.ipcMain.removeHandler("update-backend");
     electron.ipcMain.removeHandler("download-update");
     electron.ipcMain.removeHandler("quit-and-install");
@@ -4585,38 +6040,44 @@ class UpdateService {
   setupUpdateEvents() {
     electronUpdater.autoUpdater.on("update-available", (info) => {
       logger.info("Update available:", LogFileType.UPDATE_SERVICE, info);
-      if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-        this.mainWindow.webContents.send("update-available", info);
+      this.lastUpdateInfo = info;
+      if (this.failedVerificationVersions.has(info.version)) {
+        logger.warn(
+          `Not offering version ${info.version} again: its artifact already failed verification in this session.`,
+          LogFileType.UPDATE_SERVICE
+        );
+        return;
       }
+      this.sendToRenderer("update-available", info);
     });
     electronUpdater.autoUpdater.on("update-not-available", (info) => {
       logger.info("No update available:", LogFileType.UPDATE_SERVICE, info);
-      if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-        this.mainWindow.webContents.send("update-not-available", info);
-      }
+      this.sendToRenderer("update-not-available", info);
     });
-    electronUpdater.autoUpdater.on("update-downloaded", (info) => {
+    electronUpdater.autoUpdater.on("update-downloaded", async (info) => {
       logger.info("Update downloaded:", LogFileType.UPDATE_SERVICE, info);
-      if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-        this.mainWindow.webContents.send("update-downloaded", info);
+      this.lastUpdateInfo = info;
+      const block = await this.ensureStagedArtifactVerified(info);
+      if (block) {
+        this.failedVerificationVersions.add(info.version);
+        this.sendInstallBlock(block, info.version);
+        return;
       }
+      this.sendToRenderer("update-downloaded", info);
     });
     electronUpdater.autoUpdater.on("error", (err) => {
       logger.error("Update error:", LogFileType.UPDATE_SERVICE, err);
-      const shouldFilter = this.shouldFilterUpdateError(err);
+      const actionable = this.updateStage !== "idle";
+      const shouldFilter = !actionable && this.shouldFilterUpdateError(err);
       if (shouldFilter) {
         logger.info(
           "Error filtering result: Reporting as no updates available"
         );
-        if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-          this.mainWindow.webContents.send("update-not-available", {
-            version: electron.app.getVersion()
-          });
-        }
+        this.sendToRenderer("update-not-available", {
+          version: electron.app.getVersion()
+        });
       } else {
-        if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-          this.mainWindow.webContents.send("update-error", err.message);
-        }
+        this.sendToRenderer("update-error", err.message);
       }
     });
     electronUpdater.autoUpdater.on("download-progress", (progressObj) => {
@@ -4640,38 +6101,74 @@ class UpdateService {
     });
   }
   /**
-   * Set up IPC handlers for update-related actions
+   * Set up IPC handlers for update-related actions
+   */
+  /**
+   * The last install that did not complete, if any.
+   *
+   * Read from disk rather than from `this.pendingInstallFailure` so it survives
+   * a dismiss: the panel that reports a failure is not the only place the user
+   * can find out what happened, which is what made Dismiss an information loss
+   * (reviews U1, D3).
+   */
+  lastInstallAttempt() {
+    return readLastInstallAttempt(this.markerDir());
+  }
+  /**
+   * Note that a check was asked for, and let an explicit one re-offer a release
+   * whose artifact failed verification.
+   *
+   * Why the distinction exists: every refusal records its version in
+   * `failedVerificationVersions` so the 5-minute timer cannot re-offer an
+   * artifact that will fail again. That record used to apply to user-initiated
+   * checks too, which made two of the panels' own labelled remedies inert - the
+   * user freed disk space or cleared the bad download, pressed "Check for
+   * updates" as instructed, and got silence until the app restarted (reviews
+   * R3, U3). A user who asks again gets a fresh answer; the timer does not.
    */
+  onCheckRequested(options) {
+    if (!options?.manual) return;
+    if (this.failedVerificationVersions.size === 0) return;
+    logger.info(
+      `Explicit check requested; re-offering ${[...this.failedVerificationVersions].join(", ")} after a failed verification.`,
+      LogFileType.UPDATE_SERVICE
+    );
+    this.failedVerificationVersions.clear();
+  }
   setupIpcHandlers() {
-    electron.ipcMain.handle("check-for-updates", async () => {
-      logger.info("Checking for UI updates...", LogFileType.UPDATE_SERVICE);
-      try {
-        return await electronUpdater.autoUpdater.checkForUpdates();
-      } catch (error) {
-        logger.error(
-          "Error checking for UI updates:",
-          LogFileType.UPDATE_SERVICE,
-          error
-        );
-        const shouldFilter = this.shouldFilterUpdateError(error);
-        if (shouldFilter) {
-          logger.info(
-            "Error filtering result in IPC handler: Reporting as no updates available",
-            LogFileType.UPDATE_SERVICE
+    electron.ipcMain.handle(
+      "check-for-updates",
+      async (_event, options) => {
+        logger.info("Checking for UI updates...", LogFileType.UPDATE_SERVICE);
+        this.onCheckRequested(options);
+        try {
+          return await electronUpdater.autoUpdater.checkForUpdates();
+        } catch (error) {
+          logger.error(
+            "Error checking for UI updates:",
+            LogFileType.UPDATE_SERVICE,
+            error
           );
-          return {
-            updateInfo: {
-              version: electron.app.getVersion()
-            },
-            versionInfo: {
-              version: electron.app.getVersion()
-            },
-            cancellationToken: null
-          };
+          const shouldFilter = this.shouldFilterUpdateError(error);
+          if (shouldFilter) {
+            logger.info(
+              "Error filtering result in IPC handler: Reporting as no updates available",
+              LogFileType.UPDATE_SERVICE
+            );
+            return {
+              updateInfo: {
+                version: electron.app.getVersion()
+              },
+              versionInfo: {
+                version: electron.app.getVersion()
+              },
+              cancellationToken: null
+            };
+          }
+          throw error;
         }
-        throw error;
       }
-    });
+    );
     electron.ipcMain.handle("check-for-backend-updates", async () => {
       logger.info(
         "Checking for backend updates...",
@@ -4688,55 +6185,70 @@ class UpdateService {
         throw error;
       }
     });
-    electron.ipcMain.handle("check-for-all-updates", async () => {
-      logger.info(
-        "Checking for all updates (UI and backend)...",
-        LogFileType.UPDATE_SERVICE
-      );
-      try {
-        return await this.checkForAllUpdates();
-      } catch (error) {
-        logger.error(
-          "Error checking for all updates:",
-          LogFileType.UPDATE_SERVICE,
-          error
+    electron.ipcMain.handle(
+      "check-for-all-updates",
+      async (_event, options) => {
+        logger.info(
+          "Checking for all updates (UI and backend)...",
+          LogFileType.UPDATE_SERVICE
         );
-        const shouldFilter = this.shouldFilterUpdateError(error);
-        if (shouldFilter) {
-          logger.info(
-            "Error filtering result in check-for-all-updates: Reporting as no updates available",
-            LogFileType.UPDATE_SERVICE
+        this.onCheckRequested(options);
+        try {
+          return await this.checkForAllUpdates();
+        } catch (error) {
+          logger.error(
+            "Error checking for all updates:",
+            LogFileType.UPDATE_SERVICE,
+            error
           );
-          return {
-            updateInfo: {
-              version: electron.app.getVersion()
-            },
-            versionInfo: {
-              version: electron.app.getVersion()
-            },
-            cancellationToken: null
-          };
+          const shouldFilter = this.shouldFilterUpdateError(error);
+          if (shouldFilter) {
+            logger.info(
+              "Error filtering result in check-for-all-updates: Reporting as no updates available",
+              LogFileType.UPDATE_SERVICE
+            );
+            return {
+              updateInfo: {
+                version: electron.app.getVersion()
+              },
+              versionInfo: {
+                version: electron.app.getVersion()
+              },
+              cancellationToken: null
+            };
+          }
+          throw error;
         }
-        throw error;
       }
-    });
-    electron.ipcMain.handle("update-backend", async () => {
-      logger.info("Updating backend...", LogFileType.UPDATE_SERVICE);
-      try {
-        return await this.updateBackend();
-      } catch (error) {
-        logger.error(
-          "Error updating backend:",
-          LogFileType.UPDATE_SERVICE,
-          error
-        );
-        throw error;
+    );
+    electron.ipcMain.handle("get-last-install-attempt", () => this.lastInstallAttempt());
+    electron.ipcMain.handle(
+      "update-backend",
+      async (_event, targetVersion) => {
+        logger.info("Updating backend...", LogFileType.UPDATE_SERVICE);
+        try {
+          return await this.updateBackend(
+            typeof targetVersion === "string" ? targetVersion : void 0
+          );
+        } catch (error) {
+          logger.error(
+            "Error updating backend:",
+            LogFileType.UPDATE_SERVICE,
+            error
+          );
+          throw error;
+        }
       }
-    });
+    );
     electron.ipcMain.handle("download-update", async () => {
       logger.info("Downloading update...", LogFileType.UPDATE_SERVICE);
+      this.updateStage = "downloading";
       try {
-        return await electronUpdater.autoUpdater.downloadUpdate();
+        const downloadedPaths = await electronUpdater.autoUpdater.downloadUpdate();
+        if (Array.isArray(downloadedPaths) && downloadedPaths.length > 0) {
+          this.downloadedArtifactPath = downloadedPaths[0];
+        }
+        return downloadedPaths;
       } catch (error) {
         logger.error(
           "Error downloading update:",
@@ -4759,15 +6271,50 @@ class UpdateService {
           };
         }
         throw error;
+      } finally {
+        this.updateStage = "idle";
       }
     });
-    electron.ipcMain.handle("quit-and-install", () => {
+    electron.ipcMain.handle("quit-and-install", async () => {
+      if (this.installPreflightInFlight) {
+        logger.info(
+          "Ignoring a second install request while the pre-flight is still running.",
+          LogFileType.UPDATE_SERVICE
+        );
+        return false;
+      }
+      logger.info(
+        "Preparing to quit and install the update...",
+        LogFileType.UPDATE_SERVICE
+      );
+      this.installPreflightInFlight = true;
+      this.updateStage = "installing";
+      let block = null;
+      try {
+        block = await this.runInstallPreflight(this.lastUpdateInfo);
+      } finally {
+        this.installPreflightInFlight = false;
+      }
+      if (block) {
+        this.updateStage = "idle";
+        this.sendInstallBlock(block, this.lastUpdateInfo?.version ?? void 0);
+        return false;
+      }
+      const targetVersion = this.lastUpdateInfo?.version ?? electron.app.getVersion();
+      const watchdogPid = this.launchWatchdog(targetVersion);
+      const marker = writePendingInstallMarker(this.markerDir(), {
+        targetVersion,
+        artifactPath: this.downloadedArtifactPath ?? this.downloadHelper()?.file ?? "unknown",
+        startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+        watchdogPid
+      });
       logger.info(
-        "Quitting and installing update...",
+        `Pending install marker written for version ${marker.targetVersion} (watchdog pid ${watchdogPid ?? "none"}).`,
         LogFileType.UPDATE_SERVICE
       );
       this.backendService?.setAutoUpdating(true);
       electronUpdater.autoUpdater.quitAndInstall(false, true);
+      return true;
     });
   }
   /**
@@ -5075,6 +6622,103 @@ class UpdateService {
    * @param silent - Whether to suppress notifications on no update
    * @returns Promise resolving to update info or null if no update is available
    */
+  /**
+   * Decide what the backend update prompt may offer for a startup mode.
+   *
+   * GLOBAL_INSTALL is the mode that produced the operator's report: the app
+   * offered `pip install --upgrade local-operator` for a server that was a uv
+   * tool install (0.54.17, read from /health) with `canManageUpdate: true`. pip
+   * is the wrong installer for that environment - uv owns it, and the
+   * environment lives outside anything the app may write to.
+   *
+   * EXISTING_SERVER takes the same classification as GLOBAL_INSTALL, because it
+   * is the same question: a server the app attaches to but does not own was
+   * still being told to run pip, three lines below the code that had already
+   * learned better (reviews U4, D4).
+   */
+  async resolveBackendUpdatePlan(startupMode) {
+    if (startupMode === LocalOperatorStartupMode.EXISTING_SERVER || startupMode === LocalOperatorStartupMode.GLOBAL_INSTALL) {
+      const plan = resolveGlobalInstallPlan({
+        identity: this.resolveInstallIdentity(),
+        lopUpdatePath: this.resolveLopUpdatePath()
+      });
+      logger.info(
+        `External backend install (${startupMode}): ${plan.detail}; remedy is \`${plan.updateCommand || "nothing the app can name"}\``,
+        LogFileType.UPDATE_SERVICE
+      );
+      return {
+        canManageUpdate: plan.canManageUpdate,
+        updateCommand: plan.updateCommand,
+        remedy: plan.remedy,
+        detail: plan.detail,
+        sourceBuild: plan.sourceBuild
+      };
+    }
+    return {
+      canManageUpdate: true,
+      updateCommand: "pip install --upgrade local-operator",
+      remedy: "Updating the server will improve AI functionality.",
+      detail: `The app started this server itself (${startupMode}).`,
+      sourceBuild: false
+    };
+  }
+  /**
+   * Path the `local-operator` shim resolves to, or null when it is not installed.
+   *
+   * Sync on purpose: it runs once per backend check, and the answer decides
+   * which installer the prompt names, so the caller wants it before it builds
+   * the message rather than a promise to settle afterwards.
+   *
+   * It does NOT ask the shell's `which` on macOS: the app is normally started
+   * by Finder or `open`, whose PATH is the launchd default and does not contain
+   * `~/.local/bin` - so the uv tool install this whole classification exists to
+   * describe was invisible, and its remedy came out with no command in it.
+   * `resolveCommandPath` searches the standard install locations for the same
+   * markers (see `commandSearchDirs`). Windows keeps `where`, which already
+   * searches the machine's and the user's own install locations.
+   */
+  resolveLocalOperatorPath() {
+    if (process.platform === "win32") {
+      const first = readCommandOutput("where", ["local-operator"])?.split("\n")[0]?.trim();
+      return first && first.length > 0 ? first : null;
+    }
+    return resolveCommandPath("local-operator");
+  }
+  /**
+   * Path the `lop-update` shim resolves to, or null when this machine has none.
+   *
+   * The same problem as the shim above, for the remedy rather than the
+   * classification: `lop-update` is what the source-build wording tells the user
+   * to run, and it lives in `~/.local/bin`, which a Finder launch cannot see
+   * through PATH alone - so the plan fell back to the pip/pipx wording for an
+   * install that is neither. It is a shell script, so there is no Windows
+   * counterpart to look for.
+   */
+  resolveLopUpdatePath() {
+    if (process.platform === "win32") return null;
+    return resolveCommandPath("lop-update");
+  }
+  /**
+   * Everything `classifyGlobalInstall` needs to tell a uv tool install from a
+   * pipx one from an ordinary pip venv from the checkout a developer runs.
+   *
+   * The cheap signals are gathered first - `readInstallIdentity` reads the
+   * shim's path, its resolved target, its shebang and the dist-info's own
+   * markers - and the two CLI probes are skipped when a string test already
+   * answered: spawning `uv` and `pipx` on every backend check for a question
+   * three string tests settled is work nobody asked for.
+   */
+  resolveInstallIdentity() {
+    const identity = readInstallIdentity(this.resolveLocalOperatorPath());
+    if (identity.path && classifyGlobalInstall(identity) !== "global-unknown") {
+      return identity;
+    }
+    const uv = resolveCommandPath("uv");
+    const pipx = resolveCommandPath("pipx");
+    identity.uvToolList = uv ? readCommandOutput(uv, ["tool", "list"]) : null;
+    identity.pipxList = pipx ? readCommandOutput(pipx, ["list"]) : null;
+    return identity;
+  }
   async checkForBackendUpdates(silent = false) {
     logger.info(
       `Checking for backend updates... (silent mode: ${silent})`,
@@ -5104,20 +6748,34 @@ class UpdateService {
       }
       const installedVersion = await this.getInstalledBackendVersion();
       const latestVersion = await this.getLatestPypiVersion();
+      if (latestVersion) this.lastPublishedBackendVersion = latestVersion;
       if (!installedVersion || !latestVersion) {
         logger.error(
           "Unable to determine backend versions.",
           LogFileType.UPDATE_SERVICE
         );
-        if (!silent && this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-          this.mainWindow.webContents.send(
+        if (!silent) {
+          this.sendToRenderer(
             "backend-update-error",
             "Unable to determine backend version."
           );
         }
         return null;
       }
-      const shouldUpdate = installedVersion === "Unknown" || this.isNewerVersion(latestVersion, installedVersion);
+      if (installedVersion === "Unknown") {
+        logger.error(
+          "The installed backend version could not be determined from the health endpoint.",
+          LogFileType.UPDATE_SERVICE
+        );
+        if (!silent) {
+          this.sendToRenderer(
+            "backend-update-error",
+            "The installed server version could not be determined, so no update was offered. Restart the app to try again."
+          );
+        }
+        return null;
+      }
+      const shouldUpdate = this.isNewerVersion(latestVersion, installedVersion);
       logger.info(
         `Installed backend version: ${installedVersion}, Latest: ${latestVersion}, Update needed: ${shouldUpdate}, Startup mode: ${startupMode}`,
         LogFileType.UPDATE_SERVICE
@@ -5127,33 +6785,29 @@ class UpdateService {
           `New backend version available: ${latestVersion} (installed: ${installedVersion})`,
           LogFileType.UPDATE_SERVICE
         );
-        const canManageUpdate = startupMode !== LocalOperatorStartupMode.EXISTING_SERVER;
-        let updateCommand = "pip install --upgrade local-operator";
-        if (startupMode === LocalOperatorStartupMode.EXISTING_SERVER) {
-          updateCommand = "pip install --upgrade local-operator";
-        }
+        const { canManageUpdate, updateCommand, remedy, detail, sourceBuild } = await this.resolveBackendUpdatePlan(startupMode);
         const updateInfo = {
           currentVersion: installedVersion,
           latestVersion,
           updateCommand,
           canManageUpdate,
-          startupMode
+          startupMode,
+          remedy,
+          detail,
+          sourceBuild,
+          /* `silent` is the whole difference between the two callers: the periodic
+             and start-up checks pass `true`, the IPC handlers behind the buttons
+             pass `false`. The renderer needs to know which one it is answering,
+             because the by-hand panel's instruction deliberately outlives a
+             background check and is only ended by a check the user asked for
+             (review U12, round 3). */
+          manual: !silent
         };
-        if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-          logger.info(
-            `Sending backend-update-available event with info: ${JSON.stringify(updateInfo)}`,
-            LogFileType.UPDATE_SERVICE
-          );
-          this.mainWindow.webContents.send(
-            "backend-update-available",
-            updateInfo
-          );
-        } else {
-          logger.error(
-            "Cannot send backend-update-available event: mainWindow is not available or destroyed",
-            LogFileType.UPDATE_SERVICE
-          );
-        }
+        logger.info(
+          `Sending backend-update-available event with info: ${JSON.stringify(updateInfo)}`,
+          LogFileType.UPDATE_SERVICE
+        );
+        this.sendToRenderer("backend-update-available", updateInfo);
         return updateInfo;
       }
       logger.info(
@@ -5185,7 +6839,76 @@ class UpdateService {
    * Update the backend using pip and restart the backend service
    * @returns Promise resolving to true if update was successful, false otherwise
    */
-  async updateBackend() {
+  /** The version the bundled environment has installed, via `pip show`. */
+  async readBundledBackendVersion(pythonPath) {
+    const probe = await runCommand(
+      pythonPath,
+      ["-m", "pip", "show", "local-operator"],
+      { timeoutMs: 12e4 }
+    );
+    if (probe.exitCode !== 0) {
+      logger.warn(
+        `pip show local-operator exited ${probe.exitCode}: ${(probe.stderr || probe.stdout).trim()}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    return parsePipShowVersion(probe.stdout);
+  }
+  /**
+   * Bring the previous server back after a failed upgrade, and say whether it
+   * actually came back.
+   *
+   * A failure here must not leave the user with no backend at all: whatever pip
+   * did or did not do, the environment usually still holds a working install, so
+   * start it again and then ask /health rather than assuming. The answer is not
+   * cosmetic: `pip install --upgrade` uninstalls before it installs, so a
+   * mid-install failure can leave the package absent, and telling the user "the
+   * previous server is still running" when it is not is a claim we had no
+   * evidence for (review R6).
+   */
+  async restartBackendAfterFailedUpgrade() {
+    try {
+      await this.backendService?.start();
+      const healthy = await this.checkBackendHealth();
+      logger.info(
+        healthy ? "Restarted the previous backend after a failed update" : "The backend did not answer its health check after a failed update",
+        LogFileType.UPDATE_SERVICE
+      );
+      return healthy;
+    } catch (error) {
+      logger.error(
+        "Could not restart the backend after a failed update:",
+        LogFileType.UPDATE_SERVICE,
+        error
+      );
+      return false;
+    }
+  }
+  /**
+   * Poll /health until it reports `targetVersion`, bounded by a timeout.
+   *
+   * Returns null when the version never matched (or could not be read), which
+   * the caller reports as a failure rather than as a completed update.
+   */
+  async waitForBackendVersion(target2, timeoutMs = 6e4, intervalMs = 2e3) {
+    const deadline = Date.now() + timeoutMs;
+    let last = null;
+    while (Date.now() < deadline) {
+      const version2 = await this.getInstalledBackendVersion();
+      if (version2 && version2 !== "Unknown") {
+        last = version2;
+        if (target2 == null || version2 === target2) return version2;
+      }
+      await new Promise((resolve) => setTimeout(resolve, intervalMs));
+    }
+    logger.warn(
+      `Backend version poll timed out after ${timeoutMs}ms (target ${target2 ?? "any"}, last seen ${last ?? "none"})`,
+      LogFileType.UPDATE_SERVICE
+    );
+    return null;
+  }
+  async updateBackend(targetVersion) {
     logger.info("Updating backend...", LogFileType.UPDATE_SERVICE);
     try {
       if (!this.backendService) {
@@ -5216,18 +6939,28 @@ class UpdateService {
           }
           return false;
         case LocalOperatorStartupMode.EXISTING_SERVER:
+        case LocalOperatorStartupMode.GLOBAL_INSTALL: {
+          const plan = await this.resolveBackendUpdatePlan(startupMode);
           logger.info(
-            "Cannot manage update for existing server. User must update manually.",
+            `Cannot manage the update for ${startupMode}: ${plan.detail}`,
             LogFileType.UPDATE_SERVICE
           );
-          if (this.mainWindow && !this.mainWindow.isDestroyed() && this.mainWindow.webContents && !this.mainWindow.webContents.isDestroyed()) {
-            this.mainWindow.webContents.send("backend-update-manual-required", {
-              message: "Please update the local-operator package manually using pip.",
-              command: "pip install --upgrade local-operator"
-            });
-          }
+          const installed = await this.getInstalledBackendVersion();
+          this.sendToRenderer("backend-update-manual-required", {
+            message: plan.remedy,
+            command: plan.updateCommand,
+            detail: plan.detail,
+            // The caller's target when it named one (the "Update server"
+            // button does), otherwise the published release the last check
+            // read: the compatibility banner calls this with no target at
+            // all, and the panel's version sentence then had nothing to
+            // render on the path that actually produces it (review U17).
+            latestVersion: targetVersion ?? this.lastPublishedBackendVersion ?? null,
+            currentVersion: installed && installed !== "Unknown" ? installed : null,
+            sourceBuild: plan.sourceBuild
+          });
           return false;
-        case LocalOperatorStartupMode.GLOBAL_INSTALL:
+        }
         case LocalOperatorStartupMode.APP_BUNDLED_VENV:
           break;
         default:
@@ -5249,75 +6982,66 @@ class UpdateService {
           LogFileType.UPDATE_SERVICE
         );
       }
-      const execAsync = node_util.promisify(node_child_process.exec);
       let pythonPath = "";
-      let pipCommand = "";
-      if (startupMode === LocalOperatorStartupMode.APP_BUNDLED_VENV) {
-        try {
-          if (electron.app.isPackaged) {
-            if (process.platform === "darwin") {
-              pythonPath = path.join(
-                this.backendService?.getVenvPath(),
-                "bin",
-                "python3"
-              );
-            } else if (process.platform === "win32") {
-              pythonPath = path.join(
-                this.backendService?.getVenvPath(),
-                "Scripts",
-                "python.exe"
-              );
-            } else if (process.platform === "linux") {
-              pythonPath = path.join(
-                this.backendService?.getVenvPath(),
-                "bin",
-                "python3"
-              );
-            }
-            if (pythonPath) {
-              logger.info(
-                `Using bundled Python at: ${pythonPath}`,
-                LogFileType.UPDATE_SERVICE
-              );
-              pipCommand = `"${pythonPath}" -m pip install --upgrade local-operator`;
-            }
-          }
-        } catch (error) {
-          logger.warn(
-            "Error finding bundled Python path:",
-            LogFileType.UPDATE_SERVICE,
-            error
-          );
-          pythonPath = "";
-        }
-      } else if (startupMode === LocalOperatorStartupMode.GLOBAL_INSTALL) {
-        try {
-          const { stdout } = await execAsync("which python3 || which python");
-          pythonPath = stdout.trim();
-          logger.info(
-            `Using system Python at: ${pythonPath}`,
-            LogFileType.UPDATE_SERVICE
-          );
-          pipCommand = `"${pythonPath}" -m pip install --upgrade local-operator`;
-        } catch (error) {
-          logger.warn(
-            "Could not find system Python:",
-            LogFileType.UPDATE_SERVICE,
-            error
-          );
-        }
+      const venvPath = this.backendService?.getVenvPath();
+      if (venvPath && electron.app.isPackaged) {
+        const venvBinDir = process.platform === "win32" ? "Scripts" : "bin";
+        const pythonName = process.platform === "win32" ? "python.exe" : "python3";
+        pythonPath = path.join(venvPath, venvBinDir, pythonName);
       }
-      if (!pipCommand) {
-        logger.warn("Using fallback pip command", LogFileType.UPDATE_SERVICE);
-        pipCommand = "pip install --upgrade local-operator";
+      if (!pythonPath || !fs.existsSync(pythonPath)) {
+        logger.error(
+          `Cannot update the bundled backend: no Python at ${pythonPath || "an unknown path"}`,
+          LogFileType.UPDATE_SERVICE
+        );
+        await this.restartBackendAfterFailedUpgrade();
+        this.sendToRenderer(
+          "backend-update-error",
+          "The bundled server's Python environment could not be found, so the update did not run. Please reinstall the application."
+        );
+        return false;
       }
+      const pip = buildPipUpgradeCommand(pythonPath);
+      const versionBefore = await this.readBundledBackendVersion(pythonPath);
+      logger.info(
+        `Executing pip command: ${pip.display}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      const pipRun = await runCommand(pip.command, pip.args, {
+        timeoutMs: 15 * 60 * 1e3
+      });
       logger.info(
-        `Executing pip command: ${pipCommand}`,
+        `pip stdout:
+${pipRun.stdout.trim()}`,
         LogFileType.UPDATE_SERVICE
       );
-      await execAsync(pipCommand);
+      if (pipRun.stderr.trim().length > 0) {
+        logger.warn(
+          `pip stderr:
+${pipRun.stderr.trim()}`,
+          LogFileType.UPDATE_SERVICE
+        );
+      }
+      const versionAfter = await this.readBundledBackendVersion(pythonPath);
+      const upgradeLanded = pipRun.exitCode === 0 && didUpgradeLand({
+        before: versionBefore,
+        after: versionAfter,
+        target: targetVersion ?? null
+      });
+      if (!upgradeLanded) {
+        logger.error(
+          `Backend upgrade did not land: pip exited ${pipRun.exitCode}; version ${versionBefore ?? "unknown"} -> ${versionAfter ?? "unknown"}`,
+          LogFileType.UPDATE_SERVICE
+        );
+        const serverIsBack = await this.restartBackendAfterFailedUpgrade();
+        this.sendToRenderer(
+          "backend-update-error",
+          pipRun.exitCode !== 0 ? serverIsBack ? "The server update failed to install. The previously installed server is running again; see the update service log for pip's output." : "The server update failed to install and the server did not come back up. Restart Local Operator, and see the update service log for pip's output." : `The server update ran but the installed version did not change (still ${versionAfter ?? "unknown"}), so it is reported as failed.`
+        );
+        return false;
+      }
       logger.info(
-        "Backend package updated successfully via pip",
+        `Backend package upgraded: ${versionBefore ?? "unknown"} -> ${versionAfter}`,
         LogFileType.UPDATE_SERVICE
       );
       logger.info(
@@ -5382,6 +7106,24 @@ class UpdateService {
         }
         return false;
       }
+      const reportedVersion = await this.waitForBackendVersion(
+        targetVersion ?? null
+      );
+      if (reportedVersion == null) {
+        logger.error(
+          `Backend did not report version ${targetVersion ?? "the new one"} after the update`,
+          LogFileType.UPDATE_SERVICE
+        );
+        this.sendToRenderer(
+          "backend-update-error",
+          `The server restarted but did not report ${targetVersion ? `version ${targetVersion}` : "the updated version"}. Check the update service log, then try again.`
+        );
+        return false;
+      }
+      logger.info(
+        `Backend reports version ${reportedVersion} after the update`,
+        LogFileType.UPDATE_SERVICE
+      );
       logger.info(
         "Backend update and restart completed successfully",
         LogFileType.UPDATE_SERVICE
@@ -5461,6 +7203,14 @@ class UpdateService {
    * @param err The error object from autoUpdater
    * @returns True if the error should be filtered, false if it should be shown to the user
    */
+  /**
+   * Whether an error from the updater is a genuine availability problem.
+   *
+   * Only availability checks may be filtered. A download, verification or
+   * install failure means something the user asked for did not happen, and
+   * reporting it as "no update available" (the previous behaviour) is how the
+   * operator's failed install produced no message at all.
+   */
   shouldFilterUpdateError(err) {
     const errorMessage = err.message || "";
     logger.info(