local-operator-ui 0.28.1 → 0.28.3

package/out/main/index.js

@@ -393,6 +393,38 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     sessionId,
     completionToken: zod.z.string().uuid()
   }).strict(),
+  /*
+   * Bulk acknowledgement: mark many completions read in ONE user gesture
+   * (`POST /v1/desktop/attention/seen`).
+   *
+   * Its OWN op rather than a loop over `sessions.seen`, for two reasons that are
+   * both about what the receipt MEANS. The backend writes the whole batch in one
+   * `BEGIN IMMEDIATE`, so an observer sees the pre-batch or the post-batch receipt
+   * set and never a prefix; N round trips would expose a partial batch to every
+   * poller, and a failure half way would leave the user unable to tell which
+   * marks went. And the items are TOKEN-bound on purpose: the batch names exactly
+   * the completions the client has RENDERED, so a completion published between
+   * the render and the click is not in it and stays unread. A watermark sweep
+   * ("acknowledge everything now") would clear exactly that result instead, which
+   * is the hazard the per-session receipt exists to prevent — so this op never
+   * carries a time, a count or a "all" flag, only the pairs the client observed.
+   *
+   * `items` is 1..500: 500 is the catalogue's own maximum page, so every row the
+   * sidebar can hold is sendable in one call and `markAllRead` never has to
+   * chunk (chunking would break "one gesture, one request").
+   */
+  zod.z.object({
+    op: zod.z.literal("attention.seen"),
+    items: zod.z.array(
+      zod.z.object({
+        sessionId,
+        // A REAL uuid, like `sessions.seen`: a token that is not one cannot
+        // name a completion, so it is refused here rather than round-tripped
+        // to answer `unknown` for an item the client should not have sent.
+        completionToken: zod.z.string().uuid()
+      }).strict()
+    ).min(1).max(500)
+  }).strict(),
   // Cross-surface delivery claim, NOT a read receipt. `claim_delivery`
   // serialises the observers that can see one completion (a TUI, this app) so
   // exactly one of them toasts it. It deliberately never advances the read
@@ -992,6 +1024,7 @@ function desktopRequestDeadlineMs(op) {
   return LONG_READ_OPS.has(op) ? DESKTOP_LONG_READ_DEADLINE_MS : DESKTOP_CONTROL_DEADLINE_MS;
 }
 const DESKTOP_DEADLINE_EXCEEDED_CODE = "deadline_exceeded";
+const DESKTOP_FOREGROUND_REQUIRED_MESSAGE = "View these completions in the foreground before marking them read.";
 const READ_ONLY_OPS = /* @__PURE__ */ new Set([
   "capabilities",
   "accounts.list",
@@ -1234,6 +1267,25 @@ function desktopEndpoint(request) {
         method: "POST",
         body: { completion_token: request.completionToken }
       };
+    case "attention.seen":
+      return {
+        /*
+         * A path with no `{session_id}` in it, deliberately: the batch spans
+         * sessions, and `/v1/desktop/attention/seen` cannot be shadowed by the
+         * per-session route at any registration order. The body is snake_case
+         * like every other route in that module, and the conversation identity
+         * is NEVER taken from the client — the backend derives `session/<id>`
+         * from the validated session id, the rule `/seen` already follows.
+         */
+        path: "/v1/desktop/attention/seen",
+        method: "POST",
+        body: {
+          items: request.items.map((item) => ({
+            session_id: item.sessionId,
+            completion_token: item.completionToken
+          }))
+        }
+      };
     case "sessions.notified":
       return {
         path: `/v1/desktop/sessions/${request.sessionId}/notified`,
@@ -2657,7 +2709,20 @@ function parsePendingServerUpdateMarker(raw) {
     return {
       before: typeof parsed.before === "string" ? parsed.before : null,
       target: typeof parsed.target === "string" ? parsed.target : null,
-      startedAt: parsed.startedAt
+      startedAt: parsed.startedAt,
+      // The three identity fields are additive: a record written before they
+      // existed parses as "no evidence", which is exactly what the evaluator
+      // bounds by the deadline rather than by a pid.
+      deadlineAt: typeof parsed.deadlineAt === "string" ? parsed.deadlineAt : null,
+      groupPid: typeof parsed.groupPid === "number" ? parsed.groupPid : null,
+      groupStartedAt: typeof parsed.groupStartedAt === "string" ? parsed.groupStartedAt : null,
+      /*
+       * The install the attempt ran, and the reason it is parsed rather than dropped:
+       * the reader has no press in scope, so the record is the ONLY thing that can tell
+       * it which tree to ask about. A record without it is an older build's, and the
+       * reader says so and falls back rather than guessing silently.
+       */
+      installPath: typeof parsed.installPath === "string" ? parsed.installPath : null
     };
   } catch {
     return null;
@@ -2678,6 +2743,29 @@ function clearPendingServerUpdateMarker(dir) {
   fs.rmSync(path2, { force: true });
   return true;
 }
+const PENDING_SERVER_UPDATE_GRACE_MS = 10 * 6e4;
+function evaluatePendingServerUpdateMarker(input) {
+  const marker = input.marker;
+  if (!marker) return { kind: "none" };
+  if (marker.groupPid === null) {
+    return { kind: "expired", marker, reason: "unproven" };
+  }
+  if (!input.groupAlive) {
+    return { kind: "expired", marker, reason: "gone" };
+  }
+  const recorded = marker.groupStartedAt;
+  const live = input.liveGroupStamp ?? null;
+  if (recorded && live) {
+    return recorded === live ? { kind: "running", marker, reason: "owned" } : { kind: "expired", marker, reason: "foreign-pid" };
+  }
+  const deadline2 = Date.parse(marker.deadlineAt ?? "");
+  const now = input.now ?? Date.now();
+  const grace = input.graceMs ?? PENDING_SERVER_UPDATE_GRACE_MS;
+  if (Number.isFinite(deadline2) && now > deadline2 + grace) {
+    return { kind: "expired", marker, reason: "expired" };
+  }
+  return { kind: "running", marker, reason: "unproven" };
+}
 const LAST_INSTALL_ATTEMPT_FILE = "last-update-install.json";
 function lastInstallAttemptPath(dir) {
   return path$1.join(dir, LAST_INSTALL_ATTEMPT_FILE);
@@ -3277,6 +3365,45 @@ function readSourceRef(prefix) {
     return null;
   }
 }
+function readSourceMarkerState(prefix) {
+  if (!prefix) return { ref: null, mtimeMs: null };
+  const marker = path$1.join(prefix, ".lop-source");
+  try {
+    const stat = fs.statSync(marker);
+    return { ref: readSourceRef(prefix), mtimeMs: stat.mtimeMs };
+  } catch {
+    return { ref: null, mtimeMs: null };
+  }
+}
+function didSourceRebuildLand(input) {
+  const { before, after } = input;
+  const hadMarker = before.ref !== null || before.mtimeMs !== null;
+  const hasMarker = after.ref !== null || after.mtimeMs !== null;
+  if (!hasMarker) return false;
+  if (!hadMarker) return true;
+  if (before.ref !== null && after.ref !== null) {
+    return before.ref !== after.ref;
+  }
+  if (before.mtimeMs !== null && after.mtimeMs !== null) {
+    return after.mtimeMs > before.mtimeMs;
+  }
+  return false;
+}
+const GUARD_BYPASS_ADVICE = /--skip-[a-z-]+|--allow-downgrade|--force\b|--no-verify|--ignore-checks/i;
+const TERMINAL_INSTRUCTION = /^(?!\S+:\s)(?:git|lop-update|uv|pip|pipx|python\d?|sudo)\b/i;
+function installDiagnosisLines(text, maxLines = 6) {
+  const lines = text.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
+  if (lines.length === 0) return "";
+  const allowed = lines.filter((line) => !GUARD_BYPASS_ADVICE.test(line));
+  if (allowed.length === 0) return "";
+  const head = [];
+  for (const line of allowed) {
+    if (head.length >= maxLines) break;
+    if (head.length > 0 && TERMINAL_INSTRUCTION.test(line)) break;
+    head.push(line);
+  }
+  return head.join("\n").slice(0, 800);
+}
 const LOCAL_OPERATOR_DIST_INFO_VERSION = /^local[-_]operator[-_](.+)\.dist-info$/;
 function newerDistInfoVersion(candidate, current) {
   if (current === null) return true;
@@ -3501,8 +3628,14 @@ function classifyGlobalInstall(identity) {
   if (identity.installer === "pip") return "pip";
   return "global-unknown";
 }
+function installPrefixOf(identity) {
+  if (identity.venvPrefix) return identity.venvPrefix;
+  const script = identity.realPath ?? identity.path;
+  return script ? path$1.dirname(path$1.dirname(script)) : null;
+}
 function resolveGlobalInstallPlan(input) {
   const kind = classifyGlobalInstall(input.identity);
+  const installPrefix = installPrefixOf(input.identity);
   const sourceBuild = kind === "editable" || kind === "uv-tool" && isSourceBuildRef(input.identity.sourceRef);
   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}.${kind === "editable" ? " 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") {
@@ -3511,15 +3644,18 @@ function resolveGlobalInstallPlan(input) {
       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
+      sourceBuild: true,
+      managedRoute: null,
+      installPrefix
     };
   }
   if (kind === "uv-tool") {
     const managed = generationInstallRoot(input.identity) !== null;
-    const provenance = sourceBuild ? " Built from source on this machine, so `lop update` installs the published release over it - the harness prints the same notice." : "";
+    const sourceRebuildRoute = !managed && sourceBuild && (input.sourceRebuild ?? null) !== null;
+    const provenance = sourceBuild ? " source build of this machine's checkout; `lop update` would install the published release over it." : "";
     return {
-      canManageUpdate: managed,
-      updateCommand: "lop update",
+      canManageUpdate: managed || sourceRebuildRoute,
+      updateCommand: sourceRebuildRoute ? "lop-update" : "lop update",
       /*
        * The remedy is the sentence above the command well in the by-hand panel
        * and the consequence line in the managed offer, and each arm says the
@@ -3532,6 +3668,10 @@ function resolveGlobalInstallPlan(input) {
        * destructive thing this path does, so it is stated here rather than in
        * the in-flight panel the user reaches only after pressing.
        *
+       * Source build - the same disclosure with the one difference that matters:
+       * what is rebuilt is THEIR checkout, and the version they end up on is the
+       * checkout's rather than the release the app offered.
+       *
        * Legacy - WHY the app will not press the button, which is what the user
        * is choosing between (reviews U8, N1). It lived only in the mono Details
        * line, trailing a resolved path and a classification.
@@ -3540,9 +3680,11 @@ function resolveGlobalInstallPlan(input) {
        * panels, and in the by-hand panel the next line was the version sentence,
        * so the promise landed on the wrong line (review D5).
        */
-      remedy: managed ? "The app updates this install and then restarts the server it started, so a turn that is in flight is dropped while the server comes back. This can take a minute or two." : "This install predates the non-disruptive installer, so update it once from your terminal. This install's updater rewrites the shared environment in place, which can interrupt sessions mid-turn; the app manages updates after that.",
-      detail: `${detail}${provenance}`,
-      sourceBuild
+      remedy: managed ? "The app updates this install and then restarts the server it started, so a turn that is in flight is dropped while the server comes back. This can take a minute or two." : sourceRebuildRoute ? "Rebuilds this checkout with `lop-update`. The rebuild happens in place, so sessions on this machine can be interrupted while it runs, and it can take up to half an hour. This install keeps reporting the checkout's version, not the release the app offered." : "This install predates the non-disruptive installer, so update it once from your terminal. This install's updater rewrites the shared environment in place, which can interrupt sessions mid-turn; the app manages updates after that.",
+      detail: `${detail}${managed ? provenance : sourceRebuildRoute ? " source build of this machine's checkout; an in-place rebuild." : provenance}`,
+      sourceBuild,
+      managedRoute: managed ? "entry-point" : sourceRebuildRoute ? "source-build" : null,
+      installPrefix
     };
   }
   if (kind === "pipx") {
@@ -3551,7 +3693,9 @@ function resolveGlobalInstallPlan(input) {
       updateCommand: "pipx upgrade local-operator",
       remedy: "The server is a pipx install, so update it from your terminal",
       detail,
-      sourceBuild: false
+      sourceBuild: false,
+      managedRoute: null,
+      installPrefix
     };
   }
   if (kind === "pip") {
@@ -3560,7 +3704,9 @@ function resolveGlobalInstallPlan(input) {
       updateCommand: "pip install --upgrade local-operator",
       remedy: "The server is a pip install, so update it from your terminal",
       detail,
-      sourceBuild: false
+      sourceBuild: false,
+      managedRoute: null,
+      installPrefix
     };
   }
   return {
@@ -3568,7 +3714,9 @@ function resolveGlobalInstallPlan(input) {
     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
+    sourceBuild: false,
+    managedRoute: null,
+    installPrefix
   };
 }
 const PINNABLE_VERSION_REGEX = /^(?:\d+!)?\d+(?:\.\d+)*(?:(?:a|b|rc)\d+)?(?:\.post\d+)?(?:\.dev\d+)?(?:[-+][0-9A-Za-z.]+)?$/;
@@ -14982,16 +15130,16 @@ function createSessionCookieQuitHold(deps) {
   };
 }
 const OPERATION_ID = /^[a-zA-Z0-9_-]{1,128}$/;
+const FOREGROUND_RECEIPT_OPS = /* @__PURE__ */ new Set([
+  "sessions.seen",
+  "attention.seen"
+]);
 function guardForegroundReceipts(window, send2) {
   return (input) => {
-    if (input !== null && typeof input === "object" && "op" in input && input.op === "sessions.seen") {
+    if (input !== null && typeof input === "object" && "op" in input && typeof input.op === "string" && FOREGROUND_RECEIPT_OPS.has(input.op)) {
       const owner = window();
       if (!owner || owner.isDestroyed() || !owner.isVisible() || owner.isMinimized() || !owner.isFocused()) {
-        return Promise.reject(
-          new Error(
-            "View this completion in the foreground before marking it read."
-          )
-        );
+        return Promise.reject(new Error(DESKTOP_FOREGROUND_REQUIRED_MESSAGE));
       }
     }
     return send2(input);
@@ -16554,9 +16702,176 @@ function clauseTextOf(message, start, end) {
 function stripErrorPrefixes(message) {
   return message.replace(LEADING_ERROR_PREFIXES, "").replace(EMBEDDED_ERROR_PREFIX, ": ");
 }
+const GROUP_SIGNAL_GRACE_MS = 5e3;
+const GROUP_EXIT_WAIT_MS = 2e4;
+function isInstallGroupAlive(pid) {
+  try {
+    process.kill(-pid, 0);
+    return true;
+  } catch (error) {
+    return error.code === "EPERM";
+  }
+}
+function readProcessStartStamp(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  try {
+    const result = node_child_process.spawnSync("ps", ["-o", "lstart=", "-p", String(pid)], {
+      encoding: "utf8",
+      timeout: 2e3
+    });
+    if (result.status !== 0 || typeof result.stdout !== "string") return null;
+    const stamp = result.stdout.trim();
+    return stamp.length > 0 ? stamp : null;
+  } catch {
+    return null;
+  }
+}
+function signalInstallGroup(pid, signal) {
+  try {
+    process.kill(-pid, signal);
+    return true;
+  } catch {
+    return false;
+  }
+}
+async function waitForInstallGroupGone(pid, timeoutMs = GROUP_EXIT_WAIT_MS) {
+  const started = Date.now();
+  while (Date.now() - started < timeoutMs) {
+    if (!isInstallGroupAlive(pid)) return true;
+    await new Promise((resolve) => setTimeout(resolve, 100));
+  }
+  return !isInstallGroupAlive(pid);
+}
+function runInOwnProcessGroup(input) {
+  const graceMs = input.graceMs ?? GROUP_SIGNAL_GRACE_MS;
+  const log = input.log ?? (() => {
+  });
+  return new Promise((resolve) => {
+    let settled = false;
+    let timedOut = false;
+    let stdout = "";
+    let stderr = "";
+    let groupPid = null;
+    let timer = null;
+    let escalation = null;
+    const finish = (result) => {
+      if (settled) return;
+      settled = true;
+      if (timer) clearTimeout(timer);
+      dropStream(child?.stdout);
+      dropStream(child?.stderr);
+      resolve({ ...result, groupPid });
+    };
+    let child = null;
+    try {
+      child = node_child_process.spawn(input.command, input.args, {
+        detached: true,
+        cwd: input.cwd,
+        ...input.env ? { env: input.env } : {},
+        // No inherited stdin: the front end is non-interactive, and an
+        // inherited terminal on a GUI process is a handle to nothing.
+        stdio: ["ignore", "pipe", "pipe"]
+      });
+    } catch (error) {
+      log(
+        `Could not start ${input.command}: ${error.message}`,
+        "error"
+      );
+      finish({
+        exitCode: null,
+        stdout,
+        stderr: error.message,
+        ran: false,
+        timedOut: false,
+        groupStillRunning: false
+      });
+      return;
+    }
+    groupPid = child.pid ?? null;
+    if (groupPid !== null) input.onSpawn?.(groupPid);
+    const record = (chunk, stream) => {
+      const text = String(chunk);
+      if (stream === "stdout") {
+        stdout = (stdout + text).slice(-4194304);
+      } else {
+        stderr = (stderr + text).slice(-4194304);
+      }
+    };
+    child.stdout?.on("data", (chunk) => record(chunk, "stdout"));
+    child.stderr?.on("data", (chunk) => record(chunk, "stderr"));
+    child.on("error", (error) => {
+      log(`The updater could not be run: ${error.message}`, "error");
+      finish({
+        exitCode: null,
+        stdout,
+        stderr: stderr.length > 0 ? stderr : error.message,
+        ran: false,
+        timedOut: false,
+        groupStillRunning: false
+      });
+    });
+    child.on("close", (code) => {
+      finish({
+        exitCode: code,
+        stdout,
+        stderr,
+        ran: true,
+        timedOut,
+        groupStillRunning: false
+      });
+    });
+    timer = setTimeout(() => {
+      timedOut = true;
+      log(
+        `The updater did not finish within ${input.timeoutMs}ms; stopping the process group this run started. Its own children (uv, pipx, pip) run inside that group, so signalling only the front end would leave the installer running`,
+        "warn"
+      );
+      if (groupPid !== null) signalInstallGroup(groupPid, "SIGTERM");
+      escalation = setTimeout(() => {
+        if (groupPid === null || !isInstallGroupAlive(groupPid)) return;
+        log(
+          `The updater's process group was still alive ${graceMs}ms after the stop signal; killing it`,
+          "warn"
+        );
+        signalInstallGroup(groupPid, "SIGKILL");
+      }, graceMs);
+      escalation.unref?.();
+      finish({
+        exitCode: null,
+        stdout,
+        stderr,
+        ran: false,
+        timedOut: true,
+        groupStillRunning: groupPid !== null && isInstallGroupAlive(groupPid)
+      });
+    }, input.timeoutMs);
+  });
+}
+function dropStream(stream) {
+  const destroy = stream?.destroy;
+  if (typeof destroy === "function") destroy.call(stream);
+}
+function serverUpdateFailureRemedy(input) {
+  if (input.rebuildRoute && /REFUSING to release a stale ref/i.test(input.diagnosis)) {
+    return "This checkout is behind its remote, which is what `lop-update` refused to build from: bring the checkout up to date, and the next press here will build it.";
+  }
+  if (input.rebuildRoute) {
+    return "A rebuild changes this install only once it succeeds, so nothing was restarted.";
+  }
+  return "Nothing was restarted: the build that was serving is the build still serving.";
+}
+function serverUpdateFailureSentence(input) {
+  const headline = !input.ran ? "The server update did not finish: the installer could not be run to a verdict." : input.exitCode !== 0 ? `The server update did not install: \`${input.rebuildRoute ? "lop-update" : "lop update"}\` exited ${input.exitCode}.` : input.rebuildRoute ? "The rebuild finished but did not change this install: its `.lop-source` still names the same revision." : `The server update to ${input.target ?? "the new release"} did not take effect: the install still reports ${input.after ?? input.before ?? "its previous version"}.`;
+  const stopped = input.groupSurvived ? " The updater was stopped; something it started may still be replacing the install." : "";
+  const pointer = input.diagnosis ? " The installer's own output is below." : " The installer's own output is in the update service log.";
+  const escapeHatch = input.rebuildRoute ? ` You can also run \`${input.updateCommand || "lop-update"}\` yourself in a terminal.` : "";
+  return `${headline}${stopped} ${serverUpdateFailureRemedy(input)}${pointer}${escapeHatch}`;
+}
 const VERSION_LINE_REGEX = /Version:\s*([^\n]+)/;
 const VERSION_CLEAN_REGEX = /^v/i;
 const BETA_VERSION_REGEX = /v\d+\.\d+\.\d+\.beta\.\d+/;
+const GLOBAL_UPDATE_TIMEOUT_MS = 15 * 60 * 1e3;
+const SOURCE_REBUILD_TIMEOUT_MS = 30 * 60 * 1e3;
 const BUNDLE_ID_REGEX = /^[\w.-]+$/;
 const INSTALL_IN_FLIGHT_RECHECK_MS = 1e4;
 const LAUNCHCTL_NOT_LOADED_REGEX = /could not find|no such process/i;
@@ -16641,10 +16956,6 @@ const DRIFT_ABSENCE_REPORT = {
   "running-ahead": "the server is running a build NEWER than the install on disk (a downgrade on disk), so it is left alone",
   unorderable: "the two readings cannot be ordered against each other, so nothing is restarted on a guess"
 };
-function stderrTail(stderr, maxLines = 4) {
-  const lines = stderr.split("\n").map((line) => line.trim()).filter((line) => line.length > 0);
-  return lines.slice(-maxLines).join("\n").slice(-600);
-}
 function readingOfHealth(health) {
   const result = health.result;
   return {
@@ -18814,9 +19125,22 @@ ${heal.removed.join("\n")}`,
    * machines this check exists for. Null when the prefix carries no console
    * script, which is "we could not classify it" rather than a guess.
    */
-  servingInstallIdentity(prefix) {
+  /**
+   * The console script an install root exposes, or null when it has none.
+   *
+   * ONE PLACE, because two callers must agree: the identity the app CLASSIFIES an
+   * install by, and the command it RUNS for that install. They used to be derived
+   * separately - the check read `<prefix>/bin/local-operator` while the press ran
+   * whatever the shim resolved to - which is how the two halves came to describe
+   * different installs (review round 5, Q-1 = M2).
+   */
+  servingConsoleScript(prefix) {
     const script = process.platform === "win32" ? path$1.join(prefix, "Scripts", "local-operator.exe") : path$1.join(prefix, "bin", "local-operator");
-    return fs.existsSync(script) ? readInstallIdentity(script) : null;
+    return fs.existsSync(script) ? script : null;
+  }
+  servingInstallIdentity(prefix) {
+    const script = this.servingConsoleScript(prefix);
+    return script === null ? null : readInstallIdentity(script);
   }
   /**
    * Decide what the backend update prompt may offer for a startup mode.
@@ -18848,6 +19172,15 @@ ${heal.removed.join("\n")}`,
         return {
           canManageUpdate: false,
           updateCommand: "",
+          /*
+           * NO ROUTE AND NO PREFIX: this arm names no installer, which is the whole point
+           * of the sentence above - there is nothing here for the app to run, so the
+           * managed-route fields are empty rather than pointing at the managed tree.
+           * (This arm is upstream's, arrived in the fold; the fields are this branch's,
+           * and the type is what required them to be stated.)
+           */
+          managedRoute: null,
+          installPrefix: null,
           remedy: "This server is running from Local Operator's own managed environment, which no package manager owns - so there is no terminal command that can update it correctly. The app can only update a server it started itself: stop this one, then start Local Operator again and let it start its own.",
           detail,
           sourceBuild: false,
@@ -18858,7 +19191,10 @@ ${heal.removed.join("\n")}`,
       }
       const servingIdentity = serving.prefix !== null ? this.servingInstallIdentity(serving.prefix) : null;
       const identity = servingIdentity ?? await this.resolveInstallIdentity();
-      const plan = resolveGlobalInstallPlan({ identity });
+      const plan = resolveGlobalInstallPlan({
+        identity,
+        sourceRebuild: resolveCommandPath("lop-update")
+      });
       logger.info(
         `External backend install (${startupMode}): ${plan.detail}; remedy is \`${plan.updateCommand || "nothing the app can name"}\`; install version ${serving.version ?? identity.version ?? "unreadable"}`,
         LogFileType.UPDATE_SERVICE
@@ -18875,7 +19211,9 @@ ${heal.removed.join("\n")}`,
          * Either reading of the serving root proves the subject: its dist-info's
          * version, or the identity read from its own console script.
          */
-        installedInstallVersionDescribesServingInstall: serving.version !== null || servingIdentity !== null
+        installedInstallVersionDescribesServingInstall: serving.version !== null || servingIdentity !== null,
+        managedRoute: plan.managedRoute,
+        installPrefix: plan.installPrefix
       };
     }
     return {
@@ -18913,9 +19251,25 @@ ${heal.removed.join("\n")}`,
        * construction - it is read FROM the root the server named - so it describes the
        * subject whenever there is a reading at all.
        */
-      installedInstallVersionDescribesServingInstall: serving.version !== null
+      installedInstallVersionDescribesServingInstall: serving.version !== null,
+      managedRoute: "entry-point",
+      installPrefix: null
     };
   }
+  /**
+   * `.lop-source` for the install currently resolved, read from a fresh resolution.
+   *
+   * Re-resolved on every call rather than captured with the plan, for the reason
+   * this whole path re-reads its evidence: between a check and a click the install
+   * can move (a generations swap re-points `current`, and `lop-update` rewrites the
+   * uv tool root), so a prefix held from minutes ago can name a tree nothing is
+   * using any more. The reading is what `didSourceRebuildLand` compares, in both
+   * directions.
+   */
+  readRebuildMarkerState(installPath) {
+    const identity = readInstallIdentity(installPath);
+    return readSourceMarkerState(identity.venvPrefix ?? null);
+  }
   /**
    * Path the `local-operator` shim resolves to, or null when it is not installed.
    *
@@ -19684,15 +20038,24 @@ ${heal.removed.join("\n")}`,
   }
   /**
    * The version the resolved global install reports on disk, or null.
+   * The version an install reports on disk, or null.
+   *
+   * Shell-free, and deliberately a different read from the running backend's `/health`:
+   * the install is what an update moves, and immediately after one it is the only reading
+   * that has moved - the daemon lags until it is restarted.
    *
-   * Shell-free, and deliberately a different read from the running backend's
-   * `/health`: the install is what an update moves, and immediately after one it
-   * is the only reading that has moved - the daemon lags until it is restarted.
-   * Read through the same resolution the plan classified, because it is half of
-   * the evidence that the install changed at all.
+   * THE INSTALL IS A REQUIRED ARGUMENT, and that is a fix rather than a style. This read
+   * used to default to `resolveLocalOperatorPath()` - the shim - and that default is how
+   * the same seam kept arriving: a caller that forgot which install its attempt had run
+   * silently read the shim instead, and four review rounds found it one site at a time
+   * (the press against the check, the two evidence reads, then the unattended
+   * reconciliation). A required argument turns that mistake into a compile error rather
+   * than into a plausible number. The one caller with a record and no path - the
+   * reconciliation reading a marker an older build wrote - names its fallback explicitly
+   * and logs it.
    */
-  readGlobalInstallVersion() {
-    return readInstallIdentity(this.resolveLocalOperatorPath())?.version ?? null;
+  readInstallVersionAt(installPath) {
+    return readInstallIdentity(installPath)?.version ?? null;
   }
   /**
    * Run the install's own front end: `<resolved shim> update`.
@@ -19718,23 +20081,36 @@ ${heal.removed.join("\n")}`,
    * cannot land inside the sealed bundle. `shell: true` is never used - this is a
    * resolved shim path, not a command line.
    */
-  async runGlobalUpdate(consolePath) {
+  async runGlobalUpdate(command, timeoutMs, onSpawn) {
     const updatePath = installerSearchPath(process.env, os.homedir());
     logger.info(
-      `Executing the install's own updater: ${consolePath} update (PATH: ${updatePath})`,
+      `Executing the install's own updater: ${command.path} ${command.args.join(" ")} (PATH: ${updatePath})`,
       LogFileType.UPDATE_SERVICE
     );
-    const run = await runCommand(consolePath, ["update"], {
-      timeoutMs: 15 * 60 * 1e3,
-      env: { ...this.pythonSpawnEnv(), PATH: updatePath }
+    const run = await runInOwnProcessGroup({
+      command: command.path,
+      args: command.args,
+      timeoutMs,
+      // A neutral working directory, never the app's resources dir, so an updater
+      // that resolves a relative path from where it stands cannot land inside the
+      // sealed bundle.
+      cwd: os.homedir(),
+      env: { ...this.pythonSpawnEnv(), PATH: updatePath },
+      onSpawn,
+      log: (line, level) => {
+        if (level === "error") logger.error(line, LogFileType.UPDATE_SERVICE);
+        else if (level === "warn")
+          logger.warn(line, LogFileType.UPDATE_SERVICE);
+        else logger.info(line, LogFileType.UPDATE_SERVICE);
+      }
     });
     logger.info(
-      `lop update stdout: ${run.stdout.trim() || "(empty)"}`,
+      `${command.path} stdout: ${run.stdout.trim() || "(empty)"}`,
       LogFileType.UPDATE_SERVICE
     );
     if (run.stderr.trim().length > 0) {
       logger.warn(
-        `lop update stderr: ${run.stderr.trim()}`,
+        `${command.path} stderr: ${run.stderr.trim()}`,
         LogFileType.UPDATE_SERVICE
       );
     }
@@ -19770,6 +20146,36 @@ ${heal.removed.join("\n")}`,
    * exactly as the pip path does (`didUpgradeLand`).
    */
   async updateGlobalInstall(backend, plan, target2) {
+    const recorded = readPendingServerUpdateMarker(this.markerDir());
+    const recordedPid = recorded?.groupPid ?? null;
+    const recordedGroupAlive = recordedPid !== null && isInstallGroupAlive(recordedPid);
+    const outcome = evaluatePendingServerUpdateMarker({
+      marker: recorded,
+      groupAlive: recordedGroupAlive,
+      liveGroupStamp: recordedGroupAlive && recordedPid !== null ? readProcessStartStamp(recordedPid) : null
+    });
+    if (outcome.kind === "expired") {
+      logger.warn(
+        `A recorded server update (${outcome.marker.startedAt}) is not running any more (${outcome.reason}); clearing the record so this attempt can proceed`,
+        LogFileType.UPDATE_SERVICE
+      );
+      clearPendingServerUpdateMarker(this.markerDir());
+    }
+    if (outcome.kind === "running") {
+      logger.warn(
+        `A server update recorded by an earlier launch is still running (group ${outcome.marker.groupPid}, ${outcome.reason}, started ${outcome.marker.startedAt}); refusing to start a second beside it`,
+        LogFileType.UPDATE_SERVICE
+      );
+      const startedAtMs = Date.parse(outcome.marker.startedAt);
+      const ageMinutes = Number.isFinite(startedAtMs) ? Math.max(0, Math.round((Date.now() - startedAtMs) / 6e4)) : null;
+      const age = ageMinutes === null ? "at a time that could not be read" : ageMinutes < 1 ? "moments ago" : `${ageMinutes} minute${ageMinutes === 1 ? "" : "s"} ago`;
+      this.sendToRenderer("backend-update-error", {
+        message: `A server update this app started ${age} is still running (process group ${outcome.marker.groupPid}), so a second one will not be started beside it. If that update is no longer responding, the update service log says what it was doing.`,
+        phase: "update",
+        logPath: serverUpdateLogPath()
+      });
+      return false;
+    }
     if (this.serverUpdateInFlight) {
       logger.warn(
         "A global install update is already running; refusing to start a second beside it",
@@ -19783,16 +20189,75 @@ ${heal.removed.join("\n")}`,
       return false;
     }
     this.serverUpdateInFlight = true;
+    let handedOff = false;
     try {
-      return await this.runGlobalUpdateAttempt(backend, plan, target2);
+      const landed = await this.runGlobalUpdateAttempt(backend, plan, target2);
+      const stillRunning = this.recordedUpdateStillRunning();
+      if (stillRunning !== null) {
+        handedOff = true;
+        void this.holdGlobalInstallGuardUntilGroupGone(stillRunning);
+      }
+      return landed;
     } finally {
-      this.serverUpdateInFlight = false;
+      if (!handedOff) this.serverUpdateInFlight = false;
     }
   }
+  /**
+   * The group a record on disk still names, or null when nothing is running.
+   *
+   * Read rather than passed, because it is the SAME evidence the next launch reads:
+   * a guard that decided from an in-memory value would disagree with the launch
+   * that follows a crash, which is the whole class this pass is closing.
+   */
+  recordedUpdateStillRunning() {
+    const recorded = readPendingServerUpdateMarker(this.markerDir());
+    const pid = recorded?.groupPid ?? null;
+    if (pid === null) return null;
+    const alive = isInstallGroupAlive(pid);
+    const outcome = evaluatePendingServerUpdateMarker({
+      marker: recorded,
+      groupAlive: alive,
+      liveGroupStamp: alive ? readProcessStartStamp(pid) : null
+    });
+    return outcome.kind === "running" ? pid : null;
+  }
+  /**
+   * Hold the install guard until a signalled group is really gone.
+   *
+   * Fire-and-forget on purpose: the verdict has already been delivered to the user,
+   * and awaiting this would put a descendant that outlived its stop signal back in
+   * the panel's path. The record is cleared only once the group is gone, because
+   * until then it is the evidence that an updater is still writing into the install
+   * root - the thing another launch has to see.
+   */
+  async holdGlobalInstallGuardUntilGroupGone(groupPid) {
+    let gone = await waitForInstallGroupGone(groupPid, GROUP_EXIT_WAIT_MS);
+    while (!gone) {
+      logger.warn(
+        `The updater's process group ${groupPid} outlived the stop signal and the ${Math.round(GROUP_EXIT_WAIT_MS / 1e3)}s wait; another server update will not be started until it exits`,
+        LogFileType.UPDATE_SERVICE
+      );
+      await new Promise((resolve) => setTimeout(resolve, 5e3));
+      gone = !isInstallGroupAlive(groupPid);
+    }
+    clearPendingServerUpdateMarker(this.markerDir());
+    this.serverUpdateInFlight = false;
+  }
   /** The attempt itself, under the guard above. */
   async runGlobalUpdateAttempt(backend, plan, target2) {
     const consolePath = this.resolveLocalOperatorPath();
-    if (!consolePath) {
+    const rebuildPath = resolveCommandPath("lop-update");
+    const running = await this.readRunningBackend();
+    const serving = this.readServingInstall(running);
+    const servingScript = serving.prefix ? this.servingConsoleScript(serving.prefix) : null;
+    const servingIdentity = serving.prefix ? this.servingInstallIdentity(serving.prefix) : null;
+    const installPath = servingScript ?? consolePath;
+    const freshPlan = resolveGlobalInstallPlan({
+      identity: servingIdentity ?? readInstallIdentity(installPath),
+      sourceRebuild: rebuildPath
+    });
+    const rebuildRoute = freshPlan.managedRoute === "source-build" && rebuildPath !== null;
+    if (!consolePath && !rebuildRoute) {
       this.sendToRenderer("backend-update-error", {
         message: "The global install could not be found on this machine, so the update did not run. See the update service log.",
         phase: "update",
@@ -19800,28 +20265,83 @@ ${heal.removed.join("\n")}`,
       });
       return false;
     }
-    const before = this.readGlobalInstallVersion() ?? plan.installedInstallVersion;
-    this.sendToRenderer("backend-update-progress", { phase: "installing" });
-    writePendingServerUpdateMarker(this.markerDir(), {
+    const budgetMs = rebuildRoute ? SOURCE_REBUILD_TIMEOUT_MS : GLOBAL_UPDATE_TIMEOUT_MS;
+    const before = this.readInstallVersionAt(installPath) ?? plan.installedInstallVersion;
+    const markerBefore = rebuildRoute ? this.readRebuildMarkerState(installPath) : null;
+    this.sendToRenderer("backend-update-progress", {
+      phase: "installing",
+      sourceRebuild: rebuildRoute
+    });
+    const marker = {
       before,
       target: target2,
-      startedAt: (/* @__PURE__ */ new Date()).toISOString()
-    });
-    const run = await this.runGlobalUpdate(consolePath);
-    const after = this.readGlobalInstallVersion();
-    clearPendingServerUpdateMarker(this.markerDir());
-    const landed = run.exitCode === 0 && didUpgradeLand({ before, after, target: target2 });
+      startedAt: (/* @__PURE__ */ new Date()).toISOString(),
+      // The record's own budget, so a reader can tell a run that is going from a
+      // record that outlived it without consulting a clock the app chose later.
+      deadlineAt: new Date(Date.now() + budgetMs).toISOString(),
+      groupPid: null,
+      groupStartedAt: null,
+      /*
+       * The install this attempt runs, recorded so a later launch does not have to resolve
+       * one of its own: the reconciliation reads this, and a marker without it (an older
+       * build's) is the only case that falls back.
+       */
+      installPath
+    };
+    writePendingServerUpdateMarker(this.markerDir(), marker);
+    const run = await this.runGlobalUpdate(
+      rebuildRoute && rebuildPath !== null ? { path: rebuildPath, args: [] } : (
+        /*
+        * THE SERVING INSTALL'S OWN FRONT END when it has one, and the shim's
+        * resolution only as the fallback: the identity above is that script's, so
+        * running anything else would update one install and verify another - the
+        * seam this case classifies (review round 5, Q-1 = M2).
+        */
+        { path: installPath ?? "", args: ["update"] }
+      ),
+      budgetMs,
+      (pid) => {
+        writePendingServerUpdateMarker(this.markerDir(), {
+          before,
+          target: target2,
+          startedAt: marker.startedAt,
+          deadlineAt: marker.deadlineAt,
+          groupPid: pid,
+          groupStartedAt: readProcessStartStamp(pid),
+          installPath
+        });
+      }
+    );
+    const after = this.readInstallVersionAt(installPath);
+    const markerAfter = rebuildRoute ? this.readRebuildMarkerState(installPath) : null;
+    const groupSurvived = run.timedOut && run.groupStillRunning && run.groupPid !== null;
+    if (!groupSurvived) clearPendingServerUpdateMarker(this.markerDir());
+    const landed = run.exitCode === 0 && (rebuildRoute ? didSourceRebuildLand({
+      before: markerBefore ?? { ref: null, mtimeMs: null },
+      after: markerAfter ?? { ref: null, mtimeMs: null }
+    }) : didUpgradeLand({ before, after, target: target2 }));
     if (!landed) {
-      const running = await this.getInstalledBackendVersion();
-      const tail = stderrTail(run.stderr);
+      const running2 = await this.getInstalledBackendVersion();
+      const diagnosis = installDiagnosisLines(
+        run.stderr.length > 0 ? run.stderr : run.stdout
+      );
       logger.error(
-        `Global install update did not land (exited ${run.exitCode}, ran ${run.ran}): ${before ?? "unknown"} -> ${after ?? "unknown"}, running backend reports ${running ?? "no reading"}`,
+        `${rebuildRoute ? "Source rebuild" : "Global install update"} did not land (exited ${run.exitCode}, ran ${run.ran}${groupSurvived ? `, group ${run.groupPid} still alive` : ""}): ${before ?? "unknown"} -> ${after ?? "unknown"}${rebuildRoute ? `, marker ${markerBefore?.ref ?? "none"} -> ${markerAfter?.ref ?? "none"}` : ""}, running backend reports ${running2 ?? "no reading"}`,
         LogFileType.UPDATE_SERVICE
       );
       this.sendToRenderer("backend-update-error", {
-        message: `${!run.ran ? "The server update did not finish: the installer could not be run to a verdict or timed out." : run.exitCode !== 0 ? `The server update did not install: \`lop update\` exited ${run.exitCode}.` : `The server update to ${target2 ?? "the new release"} did not take effect: the install still reports ${after ?? before ?? "its previous version"}.`} The running backend is still serving${running ? ` version ${running}` : ""}; see the update service log for the installer's output.${tail ? `
-
-${tail}` : ""}`,
+        message: serverUpdateFailureSentence({
+          rebuildRoute,
+          ran: run.ran,
+          exitCode: run.exitCode,
+          groupSurvived,
+          diagnosis,
+          target: target2,
+          after,
+          before,
+          updateCommand: freshPlan.updateCommand ?? null
+        }),
+        installerOutput: diagnosis || void 0,
         phase: "update",
         logPath: serverUpdateLogPath()
       });
@@ -19833,14 +20353,14 @@ ${tail}` : ""}`,
     );
     if (backend.isUsingExternalBackend()) {
       const health = await this.getInstalledBackendVersion();
-      const running = this.eventRunningVersion(health);
+      const running2 = this.eventRunningVersion(health);
       logger.info(
-        `Install moved to ${after ?? "unknown"}; the attached backend still reports ${running ?? "no reading"}${running === health ? "" : ` (its own record; /health answers ${health ?? "no reading"})`}`,
+        `Install moved to ${after ?? "unknown"}; the attached backend still reports ${running2 ?? "no reading"}${running2 === health ? "" : ` (its own record; /health answers ${health ?? "no reading"})`}`,
         LogFileType.UPDATE_SERVICE
       );
       this.sendToRenderer("backend-update-completed", {
         installVersion: after,
-        runningVersion: running,
+        runningVersion: running2,
         restarted: false,
         restartable: this.backendIsAppOwned(),
         /*
@@ -19888,7 +20408,14 @@ ${tail}` : ""}`,
         return false;
       }
     }
-    const reported = await this.waitForBackendVersion(target2);
+    const reported = await this.waitForBackendVersion(
+      // The rebuild keeps the version, so there is no target to hold it to: the
+      // version the restarted daemon reports is the CHECKOUT's, and holding it to
+      // the release the app offered would fail a restart that landed (the same
+      // reasoning as `sourceBuild` in the prompt). What is held is that the daemon
+      // is back and answering at all.
+      rebuildRoute ? null : target2
+    );
     if (reported === null) {
       logger.error(
         `Backend restarted onto the updated install but did not report ${target2 ?? "the target version"}`,
@@ -19931,7 +20458,30 @@ ${tail}` : ""}`,
   async reportUnattendedServerUpdate() {
     const marker = readPendingServerUpdateMarker(this.markerDir());
     if (!marker) return;
-    const after = this.readGlobalInstallVersion();
+    const recordedPid = marker.groupPid ?? null;
+    const recordedAlive = recordedPid !== null && isInstallGroupAlive(recordedPid);
+    const outcome = evaluatePendingServerUpdateMarker({
+      marker,
+      groupAlive: recordedAlive,
+      liveGroupStamp: recordedAlive && recordedPid !== null ? readProcessStartStamp(recordedPid) : null
+    });
+    if (outcome.kind === "running") {
+      logger.warn(
+        `A server update recorded at ${marker.startedAt} is still running (group ${recordedPid}, ${outcome.reason}); leaving its record in place`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return;
+    }
+    const recordPath = marker.installPath ?? null;
+    const after = this.readInstallVersionAt(
+      recordPath ?? this.resolveLocalOperatorPath()
+    );
+    if (recordPath === null) {
+      logger.warn(
+        `The update record from ${marker.startedAt} names no install (written by an older build); reading the shim's resolution instead`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
     clearPendingServerUpdateMarker(this.markerDir());
     if (!after || after === marker.before) {
       logger.info(