local-operator-ui 0.29.6 → 0.29.8

package/out/main/index.js

@@ -38,8 +38,16 @@ const path__namespace = /* @__PURE__ */ _interopNamespaceDefault(path$1);
 const https__namespace = /* @__PURE__ */ _interopNamespaceDefault(https);
 const icon = path.join(__dirname, "../../resources/icon.png");
 const BACKEND_STATUS_CHANNEL = "backend-status";
+const DAEMON_PAIRED = { available: true, cause: null };
+const DAEMON_UNPAIRED = {
+  available: false,
+  cause: "unpaired"
+};
 const BACKEND_STATUS_EVENT = "backend-status-changed";
 const BACKEND_RECONNECT_CHANNEL = "backend-reconnect";
+function relayNeedsRebuild(current, next) {
+  return current.url !== next.url || current.token !== next.token;
+}
 const id$1 = zod.z.string().min(1).max(128).regex(/^[a-zA-Z0-9_-]+$/);
 const settingKey = zod.z.string().min(1).max(256).regex(/^[a-zA-Z0-9_][a-zA-Z0-9_.-]*$/);
 const secret = zod.z.string().min(1).max(32768);
@@ -1024,6 +1032,51 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
     value: secret
   }).strict()
 ]);
+const DESKTOP_REFUSAL_CODE = {
+  /**
+   * This app holds no token for the daemon it can see, so main refused to send
+   * the request at all. A PAIRING condition: the daemon never answered.
+   */
+  noCredential: "pairing.no-credential",
+  /**
+   * A 401/403 from a `/v1/desktop/` route: the daemon answered and refused this
+   * app's bearer. Re-claiming is the repair that exists, so it is a pairing
+   * condition and not a version one.
+   */
+  refused: "pairing.refused",
+  /**
+   * A 503 from a `/v1/desktop/` route that the app did NOT author: the daemon is
+   * running with its desktop plane shut (no claim accepted, no environment
+   * token), which is what a successor answers with until the app claims it.
+   */
+  planeClosed: "pairing.plane-closed",
+  /**
+   * Main could not complete the request at all (a refused socket, a reset). NOT a
+   * pairing condition - nothing was established about the daemon's plane - and it
+   * carries its own authored sentence.
+   */
+  transportFailed: "transport.failed"
+};
+const DESKTOP_MACHINE_DETAIL = {
+  /*
+   * NOTE for whoever greps for the ownership instruction this change removed:
+   * `noCredential` still READS like that sentence, and deliberately. The code is
+   * what `userFacingMessage` keys on, so this string is never rendered; it exists
+   * because the development proxy forwards a refusal body without declaring one,
+   * and `mcp-failure.ts` has to recognise main's own 503 by its text there. It is
+   * a machine vocabulary, not copy - which is why the sentence a user reads comes
+   * from `userFacingMessage` and this one is only ever compared (review round 1,
+   * NIT-5).
+   */
+  noCredential: "Restart with a desktop-managed backend to use these controls.",
+  transportFailed: "The backend could not complete this request. Check its connection and try again."
+};
+function desktopRefusalCodeForStatus(path2, status2) {
+  if (!path2.startsWith("/v1/desktop/")) return void 0;
+  if (status2 === 401 || status2 === 403) return DESKTOP_REFUSAL_CODE.refused;
+  if (status2 === 503) return DESKTOP_REFUSAL_CODE.planeClosed;
+  return void 0;
+}
 const DESKTOP_MESSAGE_BYTE_BUDGET = 88e4;
 const DESKTOP_CONTROL_BYTE_BUDGET = 262144;
 const DESKTOP_SYSTEM_PROMPT_BYTE_BUDGET = 11e5;
@@ -2335,6 +2388,8 @@ async function claimDesktopPlane(address, claimKey, options = {}) {
     if (response.status === 409)
       return { outcome: "already-claimed", status: 409 };
     if (response.status === 401) return { outcome: "wrong-key", status: 401 };
+    if (response.status === 404)
+      return { outcome: "no-handshake", status: 404 };
     return {
       outcome: "refused",
       status: response.status,
@@ -2387,6 +2442,14 @@ const BUNDLED_PYTHON_LAYOUT = {
   checkoutSeedNames,
   machOMagics
 };
+const embeddedProvisioningProfilePath = "Contents/embedded.provisionprofile";
+const unrestrictedEntitlementKeys = ["com.apple.security.app-sandbox", "com.apple.security.application-groups", "com.apple.security.get-task-allow", "com.apple.security.inherit", "com.apple.security.print", "com.apple.security.smartcard"];
+const unrestrictedEntitlementPrefixes = ["com.apple.security.cs.", "com.apple.security.network.", "com.apple.security.files.", "com.apple.security.device.", "com.apple.security.personal-information.", "com.apple.security.assets.", "com.apple.security.automation."];
+const MACOS_ENTITLEMENT_POLICY = {
+  embeddedProvisioningProfilePath,
+  unrestrictedEntitlementKeys,
+  unrestrictedEntitlementPrefixes
+};
 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";
@@ -2688,6 +2751,70 @@ function resolveStagedArtifactPath(input) {
   }
   return null;
 }
+const EMBEDDED_PROVISIONING_PROFILE_PATH = MACOS_ENTITLEMENT_POLICY.embeddedProvisioningProfilePath;
+function isProfileBackedEntitlement(key) {
+  if (MACOS_ENTITLEMENT_POLICY.unrestrictedEntitlementKeys.includes(key)) {
+    return false;
+  }
+  return !MACOS_ENTITLEMENT_POLICY.unrestrictedEntitlementPrefixes.some(
+    (prefix) => key.startsWith(prefix)
+  );
+}
+function profileBackedEntitlementKeys(plistText) {
+  const keys = [];
+  for (const match of String(plistText ?? "").matchAll(
+    /<key>([^<]+)<\/key>/g
+  )) {
+    const key = match[1];
+    if (isProfileBackedEntitlement(key) && !keys.includes(key)) keys.push(key);
+  }
+  return keys;
+}
+function zipListingHasEmbeddedProfile(listing) {
+  const suffix = `/${EMBEDDED_PROVISIONING_PROFILE_PATH}`;
+  return String(listing ?? "").split("\n").some((entry) => entry.trim().endsWith(suffix));
+}
+function zipMainExecutableEntry(listing) {
+  for (const raw of String(listing ?? "").split("\n")) {
+    const entry = raw.trim();
+    if (!entry || entry.endsWith("/")) continue;
+    if (/^[^/]+\.app\/Contents\/MacOS\/[^/]+$/.test(entry)) return entry;
+  }
+  return null;
+}
+function stagedSignatureBlock(facts) {
+  if (facts.entitlementsPlist == null) {
+    if (facts.embeddedProfile) return null;
+    return {
+      code: "artifact-cannot-launch",
+      heading: "The update couldn't be checked",
+      message: facts.version ? `The update to version ${facts.version} can't be checked for launch, so it wasn't installed.` : "The downloaded update can't be checked for launch, so it wasn't installed.",
+      remedy: {
+        text: "Check for updates again to re-download the release."
+      },
+      detail: `${facts.artifactName} carries no ${EMBEDDED_PROVISIONING_PROFILE_PATH} and its signature could not be read.`,
+      dismissLabel: "Not now"
+    };
+  }
+  const claimed = profileBackedEntitlementKeys(facts.entitlementsPlist);
+  if (claimed.length === 0) return null;
+  if (facts.embeddedProfile) return null;
+  return {
+    code: "artifact-cannot-launch",
+    message: facts.version ? `The update to version ${facts.version} can't be launched by macOS, so it wasn't installed.` : "The downloaded update can't be launched by macOS, so it wasn't installed.",
+    remedy: {
+      text: facts.version ? `Keep using this copy, and skip version ${facts.version} if you download one by hand — the next release will be offered here as usual.` : "Keep using this copy; the next release will be offered here as usual."
+    },
+    // The facts a reader can check, and nothing else: which archive, which
+    // claim, which file macOS found missing. TN3125's rule (a restricted
+    // entitlement needs a profile) is what makes the refusal TRUE, but a
+    // reader who wants the rule wants Apple's document, and 250 characters of
+    // it in a mono column made the details block 44% of the panel (design
+    // round 1, D4). It belongs in this comment, not in the card.
+    detail: `${facts.artifactName} claims ${claimed.join(", ")} and carries no ${EMBEDDED_PROVISIONING_PROFILE_PATH}.`,
+    dismissLabel: "Not now"
+  };
+}
 function pendingInstallMarkerPath(dir) {
   return path$1.join(dir, PENDING_INSTALL_MARKER_FILE);
 }
@@ -2854,6 +2981,20 @@ function recordInstallFailure(dir, input) {
   fs.renameSync(temp, target2);
   return record;
 }
+function installAttemptSupersededBy(record, runningVersion) {
+  const standing = targetStanding(record.targetVersion, runningVersion);
+  return standing === "reached" || standing === "passed";
+}
+function clearLastInstallAttempt(dir) {
+  const path2 = lastInstallAttemptPath(dir);
+  if (!fs.existsSync(path2)) return false;
+  try {
+    fs.rmSync(path2, { force: true });
+    return true;
+  } catch {
+    return false;
+  }
+}
 const VERSION_TRIPLE_REGEX = /^v?(\d+)\.(\d+)\.(\d+)/;
 function compareVersions(a, b) {
   const parse = (value) => {
@@ -2870,14 +3011,20 @@ function compareVersions(a, b) {
   }
   return 0;
 }
+function targetStanding(target2, runningVersion) {
+  if (target2 === runningVersion) return "reached";
+  const order = compareVersions(target2, runningVersion);
+  if (order === null) return "unorderable";
+  if (order < 0) return "passed";
+  if (order > 0) return "ahead";
+  return "same-triple";
+}
 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 };
+  const standing = targetStanding(marker.targetVersion, input.runningVersion);
+  if (standing === "reached") return { kind: "succeeded", marker };
+  if (standing === "passed") return { kind: "stale", marker };
   if (input.installInFlight === true) return { kind: "in-flight", marker };
   return { kind: "failed", marker };
 }
@@ -3700,6 +3847,23 @@ function generationInstallRoot(identity) {
     dir = parent;
   }
 }
+function installPointerPath(filePath) {
+  if (!filePath) return null;
+  const identity = readInstallIdentity(filePath);
+  const generation = generationInstallRoot(identity);
+  if (!generation) return filePath;
+  let resolved;
+  try {
+    resolved = fs.realpathSync(identity.realPath ?? filePath);
+  } catch {
+    return filePath;
+  }
+  const inside2 = path$1.relative(generation, resolved);
+  if (inside2 === "" || inside2.startsWith("..") || path$1.isAbsolute(inside2)) {
+    return filePath;
+  }
+  return path$1.join(path$1.dirname(path$1.dirname(generation)), "current", inside2);
+}
 function classifyGlobalInstall(identity) {
   if (!identity.path) return "global-unknown";
   if (identity.editable) return "editable";
@@ -4352,7 +4516,8 @@ async function requestDesktopMediaOutcome(input, bytes, backendUrl, token) {
       response: {
         status: 503,
         kind: "error",
-        detail: "Restart with a desktop-managed backend to use these controls."
+        detail: DESKTOP_MACHINE_DETAIL.noCredential,
+        code: DESKTOP_REFUSAL_CODE.noCredential
       },
       answered: false
     };
@@ -4421,7 +4586,15 @@ async function requestDesktopMediaOutcome(input, bytes, backendUrl, token) {
         }
       }
       return {
-        response: { status: response.status, kind: "error", detail },
+        response: {
+          status: response.status,
+          kind: "error",
+          detail,
+          // Only a path the plane has to ADMIT makes the status a pairing fact:
+          // `speech.create` and `agent.export` are outside `/v1/desktop/`, where a
+          // 503 is that route's own failure and not this app's pairing.
+          code: desktopRefusalCodeForStatus(target2.path, response.status)
+        },
         answered: true
       };
     }
@@ -4461,7 +4634,8 @@ async function requestDesktopMediaOutcome(input, bytes, backendUrl, token) {
       response: {
         status: 503,
         kind: "error",
-        detail: "The backend could not complete this request. Check its connection and try again."
+        detail: DESKTOP_MACHINE_DETAIL.transportFailed,
+        code: DESKTOP_REFUSAL_CODE.transportFailed
       },
       /*
        * Survives the catch for the same reason as its JSON twin, and with the same
@@ -4705,7 +4879,10 @@ async function requestDesktopOutcome(input, backendUrl, token) {
       response: {
         status: 503,
         body: {
-          detail: "Restart with a desktop-managed backend to use these controls."
+          detail: {
+            code: DESKTOP_REFUSAL_CODE.noCredential,
+            message: DESKTOP_MACHINE_DETAIL.noCredential
+          }
         }
       },
       answered: false
@@ -4767,7 +4944,10 @@ async function requestDesktopOutcome(input, backendUrl, token) {
       response: {
         status: 503,
         body: {
-          detail: "The backend could not complete this request. Check its connection and try again."
+          detail: {
+            code: DESKTOP_REFUSAL_CODE.transportFailed,
+            message: DESKTOP_MACHINE_DETAIL.transportFailed
+          }
         }
       },
       /*
@@ -5177,7 +5357,14 @@ class DaemonStateMachine {
   identity = null;
   failures = 0;
   capabilityStatus = null;
-  desktopAvailable = false;
+  /**
+   * Whether this app is paired with the daemon it can see, and why not when it
+   * is not. ONE field rather than the pair it used to be (`desktopAvailable`,
+   * written `true` at three sites and `false` at none): the value and its cause
+   * are one fact, and a producer that can only set half of it is how the app
+   * went on claiming a pairing a successor had already destroyed.
+   */
+  pairing = DAEMON_UNPAIRED;
   detail = "Looking for a Local Operator daemon.";
   updatedAt;
   detachedSince = null;
@@ -5196,6 +5383,7 @@ class DaemonStateMachine {
     this.backoffMs = REATTACH_BACKOFF_MS;
     this.state = "attached";
     this.detail = `Connected to the daemon on ${identity.url} (pid ${identity.pid}, v${identity.version}).`;
+    this.pairing = DAEMON_PAIRED;
     this.updatedAt = this.now();
   }
   /** This app started a successor for a daemon it owns. */
@@ -5205,9 +5393,15 @@ class DaemonStateMachine {
     this.detail = `Started a replacement daemon on ${identity.url} (pid ${identity.pid}).`;
     this.updatedAt = this.now();
   }
-  /** Record a capability answer - never a liveness answer. */
-  setDesktopAvailable(available) {
-    this.desktopAvailable = available;
+  /**
+   * Record this app's PAIRING with the daemon, cause and all.
+   *
+   * The replacement for `setDesktopAvailable(boolean)`, which could only ever be
+   * called with `true` in practice and therefore could not report the one thing
+   * the renderer needed: which fact made the app unusable (design § 1.4, § 5.2).
+   */
+  setPairing(pairing) {
+    this.pairing = pairing;
     this.updatedAt = this.now();
   }
   /**
@@ -5455,7 +5649,11 @@ class DaemonStateMachine {
       version: this.identity?.version ?? null,
       prefix: this.identity?.prefix ?? null,
       installKind: this.identity?.installKind ?? null,
-      desktopAvailable: this.desktopAvailable,
+      // DERIVED, never set independently: the pairing record is the value, and
+      // this field is its boolean projection for the callers that only need the
+      // bit. One assignment, so the two cannot disagree.
+      desktopAvailable: this.pairing.available,
+      pairing: this.pairing,
       failures: this.failures,
       capabilityStatus: this.capabilityStatus,
       /**
@@ -6566,6 +6764,20 @@ class BackendServiceManager {
    */
   feedRelay = null;
   feedRelayUrl = "";
+  /**
+   * The credential the current feed relay was built with.
+   *
+   * WHY IT IS TRACKED AT ALL, and the defect it stands for: the relay takes its
+   * bearer ONCE, at construction, and a re-pair leaves the address unchanged
+   * while replacing the credential - same port, new claim key. A rebuild keyed on
+   * the URL alone therefore keeps a relay that 401s on every attempt, for good:
+   * measured after the successor swap, the app was `attached` and paired with the
+   * new daemon while the sidebar still rendered "Not connected to the backend -
+   * showing the last known state." more than a minute later, and the same line
+   * never cleared (QA round 1 Q-2, design round 1 D3). The stream relay next door
+   * already compares the token; this one now does too.
+   */
+  feedRelayToken = null;
   /** Both survive relay recreation, so a URL rotation cannot silently detach
    * the banner path or leave the sidebar reading a stale connection state. */
   feedFrameObserver = null;
@@ -6679,7 +6891,10 @@ class BackendServiceManager {
    * backend-ready hook, which is the first moment the token exists.
    */
   getDesktopFeedRelay() {
-    if (!this.feedRelay || this.feedRelayUrl !== this.backendUrl) {
+    if (!this.feedRelay || relayNeedsRebuild(
+      { url: this.feedRelayUrl, token: this.feedRelayToken },
+      { url: this.backendUrl, token: this.desktopToken }
+    )) {
       this.feedRelay?.stop();
       this.feedRelay = new DesktopFeedRelay(
         this.backendUrl,
@@ -6703,6 +6918,7 @@ class BackendServiceManager {
       this.feedRelay.observe(this.feedFrameObserver);
       this.feedRelay.watchState(this.feedStateObserver);
       this.feedRelayUrl = this.backendUrl;
+      this.feedRelayToken = this.desktopToken;
     }
     return this.feedRelay;
   }
@@ -7299,14 +7515,19 @@ class BackendServiceManager {
   async attachIfUsable(candidate) {
     const key = candidate.record.claim_key;
     if (!key && !this.desktopToken) {
+      const governed = candidate.record.desktop;
       logger.info(
-        `Daemon ${candidate.address} publishes no claim key and this app holds no pairing token for it; not attaching (its controls would refuse every call).`,
+        `Daemon ${candidate.address} publishes no claim key and this app holds no pairing token for it; not attaching (its controls would refuse every call).${governed ? " Its record says the plane is already governed by another program." : " Its record does not describe a governed plane, so it predates the pairing handshake."}`,
         LogFileType.BACKEND
       );
+      this.daemonState.setPairing({
+        available: false,
+        cause: governed ? "governed-elsewhere" : "pre-handshake"
+      });
       this.daemonState.observe({
         kind: "capability",
         status: 401,
-        detail: `A daemon is running at ${candidate.address}, but this app holds no credential for its desktop plane.`
+        detail: governed ? `A daemon is running at ${candidate.address}, but its desktop plane is already managed by another program and this app holds no credential for it.` : `A daemon is running at ${candidate.address}, but it is older than the pairing handshake this app uses and this app holds no credential for it.`
       });
       this.notifyStatus();
       return false;
@@ -7330,11 +7551,40 @@ class BackendServiceManager {
           );
           break;
         case "wrong-key":
+          logger.info(
+            `Daemon ${candidate.address} did not accept the claim key its own record published (${outcome.outcome}); the record belongs to a process that is no longer answering. Not attaching.`,
+            LogFileType.BACKEND
+          );
+          this.daemonState.setPairing({
+            available: false,
+            cause: "successor"
+          });
+          return false;
+        case "no-handshake":
+          logger.info(
+            `Daemon ${candidate.address} has no claim route (HTTP ${outcome.status}); it predates the pairing handshake. Not attaching.`,
+            LogFileType.BACKEND
+          );
+          this.daemonState.setPairing({
+            available: false,
+            cause: "pre-handshake"
+          });
+          this.daemonState.observe({
+            kind: "capability",
+            status: outcome.status,
+            detail: `A daemon is running at ${candidate.address}, but it is older than the pairing handshake this app uses (its claim route answered HTTP ${outcome.status}).`
+          });
+          this.notifyStatus();
+          return false;
         case "refused":
           logger.info(
-            `Daemon ${candidate.address} did not accept this app's claim (${outcome.outcome}); not attaching.`,
+            `Daemon ${candidate.address} did not accept this app's claim (${outcome.outcome} ${outcome.status}); not attaching.`,
             LogFileType.BACKEND
           );
+          this.daemonState.setPairing({
+            available: false,
+            cause: outcome.status === 503 ? "pre-handshake" : "credential-refused"
+          });
           return false;
         case "unreachable":
           logger.info(
@@ -7350,6 +7600,10 @@ class BackendServiceManager {
         `Daemon ${candidate.address} refused this app's bearer for its desktop plane (HTTP ${probe.status}); not attaching (it would refuse every session list and every stream).`,
         LogFileType.BACKEND
       );
+      this.daemonState.setPairing({
+        available: false,
+        cause: "credential-refused"
+      });
       this.daemonState.observe({
         kind: "capability",
         status: probe.status,
@@ -7438,7 +7692,7 @@ class BackendServiceManager {
       },
       { owned: false }
     );
-    this.daemonState.setDesktopAvailable(true);
+    this.daemonState.setPairing(DAEMON_PAIRED);
     if (candidate.record.retiring_to) {
       this.daemonState.observe({
         kind: "build-announced",
@@ -7529,7 +7783,7 @@ class BackendServiceManager {
         },
         { owned: false }
       );
-      this.daemonState.setDesktopAvailable(true);
+      this.daemonState.setPairing(DAEMON_PAIRED);
       logger.info(
         `Adopted a pre-record daemon at ${this.backendUrl} (v${version || "unknown"}) through the deprecated fallback.`,
         LogFileType.BACKEND
@@ -7806,7 +8060,7 @@ class BackendServiceManager {
       return;
     }
     this.daemonState.attach(identity, { owned: true });
-    this.daemonState.setDesktopAvailable(true);
+    this.daemonState.setPairing(DAEMON_PAIRED);
     this.notifyStatus();
     logger.info(
       `Registered this app's own daemon: ${identity.url} (pid ${identity.pid}, v${identity.version || "unknown"}, ${identity.installKind || "kind unknown"}).`,
@@ -8259,6 +8513,16 @@ class BackendServiceManager {
     const probe = await probeIdentity(this.backendUrl, expected, {
       timeoutMs: PROBE_TIMEOUT_MS
     });
+    const answersThisApp = probe.outcome === "identified" && probe.identity.pid === this.daemonState.snapshot().pid;
+    const answeredAnotherProcess = probe.outcome === "identity-mismatch" || probe.outcome === "not-a-daemon" || probe.outcome === "identified";
+    if (answersThisApp) {
+      this.daemonState.setPairing(DAEMON_PAIRED);
+    } else if (answeredAnotherProcess) {
+      this.daemonState.setPairing({
+        available: false,
+        cause: "successor"
+      });
+    }
     switch (probe.outcome) {
       case "identified":
         return probe.identity.pid === this.daemonState.snapshot().pid ? { kind: "identified" } : {
@@ -17618,6 +17882,7 @@ const INSTALL_IN_FLIGHT_RECHECK_MS = 1e4;
 const LAUNCHCTL_NOT_LOADED_REGEX = /could not find|no such process/i;
 const APP_OWNED_PUBLISH_HEADROOM_BYTES = 450 * 1024 * 1024;
 const SEAL_PROBE_TIMEOUT_MS = 45e3;
+const STAGED_SIGNATURE_PROBE_TIMEOUT_MS = 2e4;
 const STARTUP_SEAL_PROBE_DELAY_MS = 15e3;
 const POST_WAKE_CHECK_DELAY_MS = 2e4;
 function versionSuffix(version) {
@@ -18310,6 +18575,7 @@ class UpdateService {
         );
         this.reapWatchdog(outcome.marker, true);
         clearPendingInstallMarker(this.markerDir());
+        this.retireSupersededInstallRecord();
         return;
       case "stale":
         logger.info(
@@ -18318,6 +18584,7 @@ class UpdateService {
         );
         this.reapWatchdog(outcome.marker, true);
         clearPendingInstallMarker(this.markerDir());
+        this.retireSupersededInstallRecord();
         return;
       case "in-flight": {
         this.installWasInFlight = true;
@@ -19094,10 +19361,123 @@ ${heal.removed.join("\n")}`,
         `Staged artifact verified: ${artifactPath} (${verdict.size} bytes, sha512 matches, ${required} bytes required free, ${installedBundleSize ?? "unknown"} byte app).`,
         LogFileType.UPDATE_SERVICE
       );
-      return null;
+      return this.stagedSignatureBlock(artifactPath, info);
     }
     return verdict.block;
   }
+  /**
+   * Refuse a staged artifact macOS would not launch, before the app quits.
+   *
+   * Why this is worth a probe of its own. On 2026-09-19 the operator's install
+   * updated itself to 0.29.6, which was Developer-ID signed, notarized, stapled,
+   * `codesign --verify --deep --strict`-clean and `spctl -t exec`-accepted - and
+   * completely unlaunchable: every executable in the bundle claimed the
+   * restricted `keychain-access-groups` entitlement while the bundle embedded no
+   * provisioning profile to authorize it, so amfid refused every Mach-O at exec
+   * (`AppleMobileFileIntegrityError Code=-413 "No matching profile found"`).
+   * `open` reported `RBSRequestErrorDomain Code=5 / NSPOSIXErrorDomain Code=163
+   * "Launchd job spawn failed"`. The ShipIt that should have relaunched the app
+   * was refused for the same reason, so the install completed and left the user
+   * with no app, no message and no automatic way back.
+   *
+   * The signature check is done on the STAGED artifact rather than on the
+   * installed bundle because by the time the installed bundle is the broken one,
+   * there is nothing left running to report it.
+   *
+   * A probe that could not read the artifact at all is not a refusal by itself -
+   * `stagedSignatureBlock` decides that - and neither is a non-zip artifact: the
+   * macOS in-app update is a `.zip`, and an artifact this cannot read is reported
+   * as such rather than treated as clean.
+   */
+  async stagedSignatureBlock(artifactPath, info) {
+    const facts = await this.inspectStagedSignature(artifactPath, info);
+    if (!facts) return null;
+    const block = stagedSignatureBlock(facts);
+    if (!block) {
+      logger.info(
+        `Staged artifact signature checked: ${facts.artifactName} claims no entitlement macOS needs a provisioning profile for.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    logger.warn(
+      `Refusing the update to ${info?.version ?? "an unknown version"}: ${block.detail}`,
+      LogFileType.UPDATE_SERVICE
+    );
+    return block;
+  }
+  /**
+   * The facts `stagedSignatureBlock` decides on, read out of the archive.
+   *
+   * Two members of the zip and one `codesign`, which is cheap because the file
+   * that carries the entitlements is the bundle's LAUNCHER rather than the app
+   * (`Contents/MacOS/Local Operator` is ~54 KB beside a ~376 MB bundle). The
+   * listing comes from the central directory, so neither the interpreter nor the
+   * frameworks are ever decompressed.
+   *
+   * Returns null when there is nothing this can ask about - not a zip, or a zip
+   * whose listing could not be read - and says so in the log. That is a
+   * deliberate "we could not tell", which is different from "we looked and it is
+   * clean"; the caller logs the clean case itself.
+   */
+  async inspectStagedSignature(artifactPath, info) {
+    const artifactName = path$1.basename(artifactPath);
+    if (!artifactPath.toLowerCase().endsWith(".zip")) {
+      logger.info(
+        `Staged artifact ${artifactName} is not a zip; its signature was not inspected before the install.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    const listing = await runCommand("/usr/bin/unzip", ["-Z1", artifactPath], {
+      timeoutMs: STAGED_SIGNATURE_PROBE_TIMEOUT_MS
+    });
+    if (!listing.ran || listing.exitCode !== 0) {
+      logger.warn(
+        `Could not list ${artifactName} to check its signature (exit ${listing.exitCode}): ${listing.stderr.trim() || "no output"}`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return null;
+    }
+    const embeddedProfile = zipListingHasEmbeddedProfile(listing.stdout);
+    const entry = zipMainExecutableEntry(listing.stdout);
+    const base = {
+      entitlementsPlist: null,
+      embeddedProfile,
+      artifactName,
+      version: info?.version ?? null
+    };
+    if (!entry) {
+      logger.warn(
+        `${artifactName} has no Contents/MacOS entry to read a signature from; its entitlements were not inspected before the install.`,
+        LogFileType.UPDATE_SERVICE
+      );
+      return base;
+    }
+    const scratch = fs.mkdtempSync(path$1.join(os.tmpdir(), "lo-staged-signature-"));
+    try {
+      const extracted = await runCommand(
+        "/usr/bin/unzip",
+        ["-o", "-q", artifactPath, entry, "-d", scratch],
+        { timeoutMs: STAGED_SIGNATURE_PROBE_TIMEOUT_MS }
+      );
+      if (!extracted.ran || extracted.exitCode !== 0) {
+        logger.warn(
+          `Could not extract ${entry} from ${artifactName} (exit ${extracted.exitCode}): ${extracted.stderr.trim() || "no output"}`,
+          LogFileType.UPDATE_SERVICE
+        );
+        return base;
+      }
+      const signature = await runCommand(
+        "/usr/bin/codesign",
+        ["-d", "--entitlements", "-", "--xml", path$1.join(scratch, entry)],
+        { timeoutMs: STAGED_SIGNATURE_PROBE_TIMEOUT_MS }
+      );
+      return signature.ran && signature.exitCode === 0 ? { ...base, entitlementsPlist: signature.stdout } : base;
+    } finally {
+      fs.rmSync(scratch, { recursive: true, force: true });
+    }
+  }
   /**
    * Everything that has to hold before the app is allowed to quit.
    *
@@ -19315,9 +19695,39 @@ ${heal.removed.join("\n")}`,
    * 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).
+   *
+   * AND IT RETIRES ONCE THE MACHINE HAS ARRIVED, which is the other half of that
+   * promise: a record that survives a dismiss must not survive the state it
+   * describes, or "Version 0.28.2 is running" is printed to a user on 0.29.1 for
+   * ever (the operator's report, 2026-09-18 - a 0.28.3 record against a running
+   * 0.29.1). The test is read-time because the fact becomes true without this
+   * process doing anything: the installer ran, the user relaunched, and the app
+   * that comes up is the one that answers every reader.
    */
   lastInstallAttempt() {
-    return readLastInstallAttempt(this.markerDir());
+    return this.retireSupersededInstallRecord();
+  }
+  /**
+   * The record, retired first when the version now running has reached its target.
+   *
+   * One function rather than the same test written at each site, because there are two
+   * moments the fact becomes true - the launch that reads the record, and a start-up
+   * that observes an install having succeeded or been superseded - and two spellings of
+   * one rule is how the arms drift apart. The predicate keeps a record whose versions
+   * cannot be ordered, so nothing is dropped on a guess (`installAttemptSupersededBy`).
+   */
+  retireSupersededInstallRecord() {
+    const record = readLastInstallAttempt(this.markerDir());
+    if (!record) return null;
+    const running = electron.app.getVersion();
+    if (!installAttemptSupersededBy(record, running)) return record;
+    if (clearLastInstallAttempt(this.markerDir())) {
+      logger.info(
+        `Retired the recorded install failure for ${record.targetVersion}: this app is running ${running}, so the target has been reached and the record describes a state the machine has left`,
+        LogFileType.UPDATE_SERVICE
+      );
+    }
+    return null;
   }
   /**
    * Note that a check was asked for, and let an explicit one re-offer a release
@@ -20155,9 +20565,15 @@ ${heal.removed.join("\n")}`,
    * 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.
+   *
+   * Read through the install's own pointer for the same reason the version is (see
+   * `readInstallVersionAt`): a rebuild keeps `pyproject.toml`'s version and moves the
+   * `.lop-source` ref, so the marker is the ONLY evidence of that move on this route -
+   * and a marker read from the frozen `generations/<id>` the daemon started from cannot
+   * show it any more than the version could.
    */
   readRebuildMarkerState(installPath) {
-    const identity = readInstallIdentity(installPath);
+    const identity = readInstallIdentity(installPointerPath(installPath));
     return readSourceMarkerState(identity.venvPrefix ?? null);
   }
   /**
@@ -20943,9 +21359,16 @@ ${heal.removed.join("\n")}`,
    * 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.
+   *
+   * AND THE INSTALL IS READ THROUGH ITS OWN POINTER, because on a generation layout the
+   * install it names cannot move under it: the tree `/health` reports as the install root
+   * is `generations/<id>`, an install lands BESIDE it, and only `<stable>/current` moves.
+   * Reading the concrete path here is what produced the false "did not take effect" verdict
+   * of 2026-09-18; `installPointerPath` is the same install named so the flip is visible,
+   * and it is a no-op on every other layout.
    */
   readInstallVersionAt(installPath) {
-    return readInstallIdentity(installPath)?.version ?? null;
+    return readInstallIdentity(installPointerPath(installPath))?.version ?? null;
   }
   /**
    * Run the install's own front end: `<resolved shim> update`.
@@ -21175,8 +21598,17 @@ ${heal.removed.join("\n")}`,
        * 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.
+       *
+       * RECORDED THROUGH ITS OWN POINTER where the layout has one, so the record outlives
+       * the tree it names: on a generation install the flip an install performs is visible
+       * only through `<stable>/current`, and the generation this attempt started from is
+       * unreferenced the moment it is superseded - which makes it prunable, and a record
+       * naming a pruned tree reads as "nothing moved" for an install that landed. A record
+       * an older build wrote carries the concrete generation path instead, which the reader
+       * resolves through the same pointer (`installPointerPath` is idempotent, so both
+       * spellings land in the same place).
        */
-      installPath
+      installPath: installPointerPath(installPath)
     };
     writePendingServerUpdateMarker(this.markerDir(), marker);
     const run = await this.runGlobalUpdate(
@@ -21198,7 +21630,7 @@ ${heal.removed.join("\n")}`,
           deadlineAt: marker.deadlineAt,
           groupPid: pid,
           groupStartedAt: readProcessStartStamp(pid),
-          installPath
+          installPath: installPointerPath(installPath)
         });
       }
     );