local-operator-ui 0.25.10 → 0.25.11

package/out/main/index.js

@@ -1750,21 +1750,38 @@ function endpoint(request) {
       };
   }
 }
-async function requestDesktopMedia(input, bytes, backendUrl, token) {
+async function requestDesktopMediaOutcome(input, bytes, backendUrl, token) {
   const parsed = mediaRequestSchema.safeParse(input);
   if (!parsed.success) {
-    return { status: 422, kind: "error", detail: "Invalid media operation." };
+    return {
+      response: {
+        status: 422,
+        kind: "error",
+        detail: "Invalid media operation."
+      },
+      answered: false
+    };
   }
   if (!token) {
     return {
-      status: 503,
-      kind: "error",
-      detail: "Restart with a desktop-managed backend to use these controls."
+      response: {
+        status: 503,
+        kind: "error",
+        detail: "Restart with a desktop-managed backend to use these controls."
+      },
+      answered: false
     };
   }
   const request = parsed.data;
   if (bytes && bytes.byteLength > MAX_UPLOAD_BYTES) {
-    return { status: 413, kind: "error", detail: "This file is too large." };
+    return {
+      response: {
+        status: 413,
+        kind: "error",
+        detail: "This file is too large."
+      },
+      answered: false
+    };
   }
   const target2 = endpoint(request);
   let body;
@@ -1776,7 +1793,10 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
     contentType = "application/json";
   } else {
     if (!bytes) {
-      return { status: 422, kind: "error", detail: "A file is required." };
+      return {
+        response: { status: 422, kind: "error", detail: "A file is required." },
+        answered: false
+      };
     }
     const form = new FormData();
     const blob = new Blob([bytes], {
@@ -1790,6 +1810,7 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
     }
     body = form;
   }
+  let answered = false;
   try {
     const response = await fetch(new URL(target2.path, backendUrl), {
       method: target2.method,
@@ -1802,6 +1823,7 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
       redirect: "error",
       signal: AbortSignal.timeout(12e4)
     });
+    answered = true;
     const responseType = response.headers.get("content-type") ?? "";
     if (!response.ok) {
       let detail = "The media request failed.";
@@ -1813,34 +1835,57 @@ async function requestDesktopMedia(input, bytes, backendUrl, token) {
         } catch {
         }
       }
-      return { status: response.status, kind: "error", detail };
+      return {
+        response: { status: response.status, kind: "error", detail },
+        answered: true
+      };
     }
     if (responseType.includes("application/json")) {
       return {
-        status: response.status,
-        kind: "json",
-        body: await response.json()
+        response: {
+          status: response.status,
+          kind: "json",
+          body: await response.json()
+        },
+        answered: true
       };
     }
     const buffer = new Uint8Array(await response.arrayBuffer());
     if (buffer.byteLength > MAX_DOWNLOAD_BYTES) {
       return {
-        status: 502,
-        kind: "error",
-        detail: "The backend returned too much data."
+        response: {
+          status: 502,
+          kind: "error",
+          detail: "The backend returned too much data."
+        },
+        // The daemon answered; what it sent was over this relay's ceiling.
+        answered: true
       };
     }
     return {
-      status: response.status,
-      kind: "bytes",
-      mimeType: responseType || "application/octet-stream",
-      data: buffer
+      response: {
+        status: response.status,
+        kind: "bytes",
+        mimeType: responseType || "application/octet-stream",
+        data: buffer
+      },
+      answered: true
     };
   } catch {
     return {
-      status: 503,
-      kind: "error",
-      detail: "The backend could not complete this request. Check its connection and try again."
+      response: {
+        status: 503,
+        kind: "error",
+        detail: "The backend could not complete this request. Check its connection and try again."
+      },
+      /*
+       * Survives the catch for the same reason as its JSON twin, and with the same
+       * two cases: a body that failed to parse was already `answered: true`, and so
+       * is a failure during the body read. A timeout abort that never got a
+       * response throws out of `fetch` first and returns `false` (review round 2
+       * MINOR-1; review round 3 MINOR-1 found the second case).
+       */
+      answered
     };
   }
 }
@@ -2037,27 +2082,40 @@ class DesktopStreamRelay {
     this.streams.clear();
   }
 }
-async function requestDesktop(input, backendUrl, token) {
+async function requestDesktopOutcome(input, backendUrl, token) {
   const parsed = desktopRequestSchema.safeParse(input);
   if (!parsed.success) {
-    return { status: 422, body: { detail: "Invalid desktop operation." } };
+    return {
+      response: {
+        status: 422,
+        body: { detail: "Invalid desktop operation." }
+      },
+      answered: false
+    };
   }
   const request = parsed.data;
   if (request.op !== "capabilities" && !token) {
     return {
-      status: 503,
-      body: {
-        detail: "Restart with a desktop-managed backend to use these controls."
-      }
+      response: {
+        status: 503,
+        body: {
+          detail: "Restart with a desktop-managed backend to use these controls."
+        }
+      },
+      answered: false
     };
   }
   const target2 = desktopEndpoint(request);
+  let answered = false;
   try {
     const body = target2.body === void 0 ? void 0 : JSON.stringify(target2.body);
     if (body && Buffer.byteLength(body) > desktopRequestByteBudget(request.op)) {
       return {
-        status: 413,
-        body: { detail: desktopRequestTooLargeDetail(request.op) }
+        response: {
+          status: 413,
+          body: { detail: desktopRequestTooLargeDetail(request.op) }
+        },
+        answered: false
       };
     }
     const response = await fetch(new URL(target2.path, backendUrl), {
@@ -2071,20 +2129,42 @@ async function requestDesktop(input, backendUrl, token) {
       redirect: "error",
       signal: AbortSignal.timeout(2e4)
     });
+    answered = true;
     const result = response.status === 204 ? null : await response.json();
     if (request.op === "capabilities" && !token && result?.result) {
       result.result.desktop_available = false;
     }
-    return { status: response.status, body: result };
+    return {
+      response: { status: response.status, body: result },
+      answered: true
+    };
   } catch {
     return {
-      status: 503,
-      body: {
-        detail: "The backend could not complete this request. Check its connection and try again."
-      }
+      response: {
+        status: 503,
+        body: {
+          detail: "The backend could not complete this request. Check its connection and try again."
+        }
+      },
+      /*
+       * `answered` survives the catch, and it is true here in exactly TWO cases,
+       * both of them a listener that answered: a body this process could not
+       * parse (the flag was set when `fetch` resolved, and a malformed answer is
+       * still an answer), and a failure DURING the body read - an abort that
+       * fired while the bytes were being pulled in lands here with `answered`
+       * already set. A timeout abort that never got a response does NOT:
+       * it throws out of `fetch` before the assignment, so it returns
+       * `answered: false`, like a refused socket (review round 2 MINOR-1, and
+       * review round 3 MINOR-1 which found the second case - the wording said
+       * "the ONE case" and the invariant it named was narrower than the code).
+       */
+      answered
     };
   }
 }
+async function requestDesktop(input, backendUrl, token) {
+  return (await requestDesktopOutcome(input, backendUrl, token)).response;
+}
 function trustedDesktopFrame(actual, expected) {
   try {
     const current = new URL(actual);
@@ -3622,6 +3702,8 @@ const apiConfig = {
   baseUrl: backendConfig.VITE_LOCAL_OPERATOR_API_URL
 };
 const DEGRADED_AFTER_FAILURES = 3;
+const UNANSWERED_BEFORE_DETACHED = 9;
+const TRANSPORT_EVIDENCE_MS = 3e4;
 const PROBE_INTERVAL_MS = 1e4;
 const PROBE_TIMEOUT_MS$1 = 2e3;
 const DETACHED_AFTER_MS = 9e4;
@@ -3642,11 +3724,16 @@ class DaemonStateMachine {
   updatedAt;
   detachedSince = null;
   backoffMs = REATTACH_BACKOFF_MS;
+  /** Consecutive probes that ran out of budget with no answer at all. */
+  unanswered = 0;
+  /** When a desktop request was last answered, or null. */
+  lastTransportAt = null;
   /** Adopt a validated daemon (`owned` says whether this app spawned it). */
   attach(identity, options) {
     this.identity = identity;
     this.owned = options.owned;
     this.failures = 0;
+    this.unanswered = 0;
     this.detachedSince = null;
     this.backoffMs = REATTACH_BACKOFF_MS;
     this.state = "attached";
@@ -3676,6 +3763,7 @@ class DaemonStateMachine {
     switch (observation.kind) {
       case "identified":
         this.failures = 0;
+        this.unanswered = 0;
         this.capabilityStatus = null;
         this.detachedSince = null;
         this.backoffMs = REATTACH_BACKOFF_MS;
@@ -3701,11 +3789,20 @@ class DaemonStateMachine {
           this.enterDetached(observation.detail);
         } else {
           this.state = "degraded";
-          this.detail = `${observation.detail} (probe ${this.failures} of ${DEGRADED_AFTER_FAILURES})`;
+          this.detail = `${observation.detail} (probe ${this.failures} of ${DEGRADED_AFTER_FAILURES}).${this.transportEvidenceSuffix("so it is serving")}`;
+        }
+        break;
+      case "unanswered":
+        this.observeUnanswered(observation.detail);
+        break;
+      case "unattachable":
+        if (this.state !== "attached" && this.state !== "replaced") {
+          this.state = "wedged";
         }
+        this.detail = observation.detail;
         break;
       case "pid-dead":
-        this.enterDetached("The daemon's process is gone.");
+        this.enterDetached("The daemon's process is gone.", true);
         break;
       case "no-candidate":
         this.enterDetached(observation.detail);
@@ -3714,7 +3811,96 @@ class DaemonStateMachine {
     this.updatedAt = this.now();
     return this.state;
   }
-  enterDetached(detail) {
+  /**
+   * Fold a probe that ran out of budget with no answer.
+   *
+   * Three rules, in order, and each one exists because the alternative was
+   * measured on the operator's machine:
+   *
+   *   1. A successful desktop request inside the evidence window means the
+   *      connection is ALIVE and the probe is the thing that is wrong. The state
+   *      does not move at all - not to `degraded`, because the app is talking to
+   *      its daemon right now - and the detail records both facts. This is the
+   *      rule that makes "no surface may say offline while the app is still
+   *      reading from it" true by construction rather than by each surface
+   *      remembering to check a second flag.
+   *   2. Without that evidence, misses accumulate as `degraded` (usable), which
+   *      is all a 2 s budget on a busy box justifies.
+   *   3. Only `UNANSWERED_BEFORE_DETACHED` consecutive misses detach, and the
+   *      detail says how many were counted, so the log line names the evidence.
+   */
+  observeUnanswered(detail) {
+    this.unanswered += 1;
+    if (this.transportEvidenceFresh()) {
+      this.detail = `${detail}${this.transportEvidenceSuffix("so it is serving and the probe's budget is what expired")} (no answer to probe ${this.unanswered}).`;
+      return;
+    }
+    if (this.unanswered >= UNANSWERED_BEFORE_DETACHED) {
+      this.enterDetached(detail);
+      return;
+    }
+    this.state = "degraded";
+    this.detail = `${detail} (no answer to probe ${this.unanswered} of ${UNANSWERED_BEFORE_DETACHED})`;
+  }
+  /**
+   * Record that a real request against the attached daemon was answered.
+   *
+   * WHY this is the state machine's business and not a caller's: the probe and
+   * the transport disagree regularly on a box running long turns - the probe
+   * has a 2 s budget, a session list has a 30 s one - and the one carrying the
+   * user's data is the transport. Recording it here is what lets
+   * {@link observeUnanswered} prefer it without every surface re-deriving the
+   * same fact.
+   *
+   * It revives `degraded` (the daemon just answered, so the missed probes are
+   * explained) and never a `detached` connection: coming back from those is
+   * `recoverFromDetachment`'s job, because that path also has to re-prove the
+   * daemon's IDENTITY before anything may use it.
+   *
+   * @returns whether the state actually moved, so the caller only pushes a
+   * snapshot when there is something new to push.
+   */
+  recordTransportSuccess() {
+    const moved = this.state === "degraded";
+    this.lastTransportAt = this.now();
+    this.unanswered = 0;
+    if (moved) {
+      this.failures = 0;
+      this.state = this.identity ? "attached" : "connecting";
+      this.detail = this.identity ? `Connected to the daemon on ${this.identity.url} (pid ${this.identity.pid}, v${this.identity.version}).` : "Connected to the Local Operator daemon.";
+    }
+    this.updatedAt = this.now();
+    return moved;
+  }
+  /** Whether a successful request is recent enough to outrank a probe. */
+  transportEvidenceFresh() {
+    return this.lastTransportAt !== null && this.now() - this.lastTransportAt <= TRANSPORT_EVIDENCE_MS;
+  }
+  /**
+   * The clause a sentence owes when THIS app's own request is the evidence
+   * behind a connection the app has not detached from, or the empty string when
+   * there is no such evidence.
+   *
+   * Shared rather than copied: three arms carry it (a probe budget that expired,
+   * a refusal past the detach threshold, and a refusal short of it), and a third
+   * copy is how one of them came to say "refused the connection" while the app
+   * was still holding the connection open on the strength of its own answered
+   * request.
+   */
+  transportEvidenceSuffix(tail) {
+    if (!this.transportEvidenceFresh()) return "";
+    const silentFor = Math.round(
+      (this.now() - this.lastTransportAt) / 1e3
+    );
+    return ` The daemon answered a request ${silentFor}s ago, ${tail}.`;
+  }
+  enterDetached(detail, corroborated = false) {
+    if (!corroborated && this.transportEvidenceFresh()) {
+      this.failures = 0;
+      this.state = "degraded";
+      this.detail = `${detail}${this.transportEvidenceSuffix("so this app is not reporting it as gone")}`;
+      return;
+    }
     this.failures = DEGRADED_AFTER_FAILURES;
     this.state = "detached";
     if (this.detachedSince === null) this.detachedSince = this.now();
@@ -3770,6 +3956,13 @@ class DaemonStateMachine {
       desktopAvailable: this.desktopAvailable,
       failures: this.failures,
       capabilityStatus: this.capabilityStatus,
+      /**
+       * Carried so a surface can explain a `degraded` connection in the same
+       * terms main used, rather than inventing a second reason for it. Both are
+       * also what a reader needs to tell a busy daemon from a gone one.
+       */
+      unanswered: this.unanswered,
+      lastTransportAt: this.lastTransportAt,
       detail: this.detail,
       updatedAt: this.updatedAt
     };
@@ -3902,6 +4095,24 @@ function recordAddress(record) {
   const host = record.host.includes(":") ? `[${record.host}]` : record.host;
   return `http://${host}:${record.port}`;
 }
+function classifyUnreachable(error) {
+  const name = error?.name;
+  if (name === "TimeoutError" || name === "AbortError") return "timeout";
+  const code = error?.code ?? error?.cause?.code;
+  switch (code) {
+    case "ECONNREFUSED":
+    case "EHOSTUNREACH":
+    case "ENETUNREACH":
+    case "ENETDOWN":
+    case "EPIPE":
+      return "refused";
+    case "ENOTFOUND":
+    case "EAI_AGAIN":
+      return "unresolved";
+    default:
+      return "other";
+  }
+}
 function readIdentity(payload) {
   if (typeof payload !== "object" || payload === null) return null;
   const result = payload.result;
@@ -3958,6 +4169,7 @@ async function probeIdentity(address, expectedInstanceId, options = {}) {
   } catch (error) {
     return {
       outcome: "unreachable",
+      cause: classifyUnreachable(error),
       detail: error instanceof Error ? error.message : String(error)
     };
   }
@@ -4143,14 +4355,16 @@ async function probeUnidentified(address, options = {}) {
     });
     if (response.status !== 200) {
       return {
-        reason: "not-a-daemon",
+        reason: "unready-answer",
         detail: `${HEALTH_PATH$1} answered ${response.status} and no record describes this address`
       };
     }
     const payload = await response.json().catch(() => null);
-    if (readIdentity(payload)) {
+    const identity = readIdentity(payload);
+    if (identity) {
       return {
         reason: "identity-mismatch",
+        identity,
         detail: `a daemon answered but no serve record describes ${address}, so it cannot be proven to be the one this app found`
       };
     }
@@ -4161,6 +4375,7 @@ async function probeUnidentified(address, options = {}) {
   } catch (error) {
     return {
       reason: "unreachable",
+      cause: classifyUnreachable(error),
       detail: error instanceof Error ? error.message : String(error)
     };
   }
@@ -5189,9 +5404,15 @@ const SHUTDOWN_TIMEOUT_DEFAULTS = {
 };
 const OWNED_STOP_WORST_MS = SHUTDOWN_TIMEOUT_DEFAULTS.normal + SHUTDOWN_TIMEOUT_DEFAULTS.force;
 const READINESS_POLL_INTERVAL_MS = 1e3;
+const DESKTOP_TOKEN_FILENAME = "desktop-token";
 const execPromise = node_util.promisify(node_child_process.exec);
 const ENV_VAR_REGEX = /^([^=]+)=(.*)$/;
 const LINE_BREAK = /\r?\n/;
+function classifyDesktopAnswer(status2) {
+  if (status2 >= 200 && status2 < 300) return "accepted";
+  if (status2 === 401 || status2 === 403) return "refused";
+  return "unusable";
+}
 class BackendServiceManager {
   process = null;
   isRunning = false;
@@ -5215,6 +5436,19 @@ class BackendServiceManager {
   remoteConfigured = false;
   /** A failed probe or unreadable record is not evidence that spawning is safe. */
   discoveryBlocksSpawn = false;
+  /**
+   * The address of a daemon that ANSWERED this app's desktop read without
+   * refusing its credential, and the status it answered, from the last
+   * discovery sweep.
+   *
+   * Non-null means the address is OCCUPIED by a daemon this app may not attach
+   * to *yet*: `start()`'s no-spawn report has to publish that as a running
+   * daemon, because the alternative it would otherwise reach - `no-candidate` -
+   * renders as offline, which is the one sentence this whole change exists to
+   * stop saying about a server that answers (#1170: an unreadable session store
+   * answers 503 instead of an empty 200).
+   */
+  answeredButUnusable = null;
   /**
    * Records discovery found alive but unresponsive (pid alive, heartbeat
    * stopped). They are why no candidate exists AND why spawning is forbidden,
@@ -5226,6 +5460,14 @@ class BackendServiceManager {
   nextRecoveryAt = 0;
   appDataPath = electron.app.getPath("userData");
   venvPath;
+  /**
+   * Why the last `/health` read did not return 200, for the callers that must
+   * tell a refusal from an expired budget: `null` when it was not a transport
+   * failure at all (the address answered, with a status this path does not
+   * accept).
+   */
+  lastHealthFailure = null;
+  /** The one probe loop's interval handle. */
   healthCheckInterval = null;
   /** The only process this manager may terminate. Null means it owns nothing,
    * which is a reason to report "nothing to stop" - never to go looking. */
@@ -5255,6 +5497,29 @@ class BackendServiceManager {
   shellEnv = {};
   // External/dev backends may be explicitly paired through main's environment.
   // Managed starts always rotate this; it is never exposed by preload or logs.
+  /**
+   * The credential this app holds for its OWN daemon.
+   *
+   * Read from disk at construction, and REPLACED by a freshly minted, persisted
+   * one on every managed start. Those are two halves of one rule:
+   *
+   *   - the read is what makes a daemon the previous run left running
+   *     attachable. The app deliberately leaves its daemon serving when it
+   *     attached to an external backend, and a daemon it spawned is
+   *     env-governed from the spawn (its record publishes `claim_key: ""`), so
+   *     the ONLY credential that can ever open it is the token its spawner held.
+   *     A launch that starts with no token there declines the daemon it owns and
+   *     starts a second one onto its port - measured on the operator's machine as
+   *     the 07:47 -> 09:17 sequence, ending in `[Errno 48] Address already in
+   *     use`;
+   *   - the write is why the token still changes when the app REPLACES a daemon
+   *     in place: the relay's cache key is this value (see `getStreamRelay`), and
+   *     a token that survived a restart would leave a subscription pointed at a
+   *     daemon this app had already stopped.
+   *
+   * The environment still wins, because an explicitly paired app is a deliberate
+   * configuration and not a cache to be second-guessed.
+   */
   desktopToken = process.env.LOCAL_OPERATOR_DESKTOP_TOKEN || null;
   /** Authenticated SSE relay for canonical session events. Recreated when the
    * backend URL rotates (external-backend discovery) or the desktop token does
@@ -5447,15 +5712,51 @@ class BackendServiceManager {
     this.feedRelay?.watchState(stateObserver);
   }
   requestDesktop(input) {
-    return requestDesktop(input, this.backendUrl, this.desktopToken);
+    return requestDesktopOutcome(
+      input,
+      this.backendUrl,
+      this.desktopToken
+    ).then(({ response, answered }) => {
+      if (answered) this.noteTransportAnswer();
+      return response;
+    });
   }
   requestDesktopMedia(input, bytes) {
-    return requestDesktopMedia(
+    return requestDesktopMediaOutcome(
       input,
       bytes,
       this.backendUrl,
       this.desktopToken
-    );
+    ).then(({ response, answered }) => {
+      if (answered) this.noteTransportAnswer();
+      return response;
+    });
+  }
+  /**
+   * Tell the state machine that this app's own request reached the daemon.
+   *
+   * `answered` is the TRANSPORT's verdict, not the promise's: every failure the
+   * transport can produce resolves rather than throws, so `.then()` alone fires
+   * for a refused socket, for a request this app never sent (no token, oversize,
+   * an invalid op), and for one whose budget expired. Gating on it here is the
+   * fix for review round 1's F-1, where an unearned stamp held the state at
+   * `degraded` - which is not a state `checkBackendHealth` recovers from, so a
+   * genuinely gone daemon could never be reported as gone.
+   *
+   * WHY this still counts EVERY answer, including a gated route's `401`/`403`:
+   * the capability rules elsewhere in this file say a refusal is not a LIVENESS
+   * signal, and that is about not calling it "connected". Turned around, a
+   * refusal is the strongest liveness evidence this app has - a process read the
+   * request and wrote a status line - which is exactly what a probe that ran out
+   * of its 2 s budget failed to establish. Without this, one long agent turn was
+   * enough to detach the connection and disable every read the daemon was still
+   * answering.
+   *
+   * Only a state that actually moves pushes a snapshot: this runs on every
+   * desktop call, and one IPC wake-up per request would be worse than the bug.
+   */
+  noteTransportAnswer() {
+    if (this.daemonState.recordTransportSuccess()) this.notifyStatus();
   }
   isAppClosing = false;
   // Flag to track when the app is being closed
@@ -5494,6 +5795,7 @@ class BackendServiceManager {
       packaged: electron.app.isPackaged
     });
     this.loadShellEnvironment();
+    this.desktopToken = this.desktopToken || this.persistedDesktopToken();
     logger.info(
       `Backend Service Manager initialized. May spawn or kill: ${this.managerMaySpawn}`,
       LogFileType.BACKEND
@@ -5768,6 +6070,11 @@ class BackendServiceManager {
         kind: "heartbeat-stale",
         detail: `A Local Operator daemon is running (pid ${wedged.pid}), but it stopped publishing its heartbeat, so this app did not attach to it. Waiting without starting a second one.`
       });
+    } else if (this.answeredButUnusable) {
+      this.daemonState.observe({
+        kind: "unattachable",
+        detail: `A Local Operator daemon is running at ${this.answeredButUnusable.address} and answered this app's read with HTTP ${this.answeredButUnusable.status}, so this app is not attached to it. Nothing is being started over it; it keeps probing.`
+      });
     } else {
       this.daemonState.observe({
         kind: "no-candidate",
@@ -5914,6 +6221,7 @@ class BackendServiceManager {
   async adoptFirstUsableDaemon() {
     if (this.isAppClosing) return false;
     this.discoveryWedged = [];
+    this.answeredButUnusable = null;
     if (this.remoteConfigured) {
       this.discoveryBlocksSpawn = true;
       return await this.legacyFixedPortAdoption();
@@ -5996,19 +6304,40 @@ class BackendServiceManager {
           return false;
       }
     }
-    if (!await this.authenticatesAgainst(candidate.address, token)) {
+    const probe = await this.probeCandidate(candidate.address, token);
+    if (probe.verdict === "refused") {
       logger.info(
-        `Daemon ${candidate.address} refuses this app's bearer for its desktop plane; not attaching (it would refuse every session list and every stream).`,
+        `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.observe({
         kind: "capability",
-        status: 403,
-        detail: `A daemon is running at ${candidate.address}, but it refused this app's credential for its desktop plane.`
+        status: probe.status,
+        detail: `A daemon is running at ${candidate.address}, but it refused this app's credential for its desktop plane (HTTP ${probe.status}).`
+      });
+      this.notifyStatus();
+      return false;
+    }
+    if (probe.verdict === "unusable") {
+      logger.info(
+        `Daemon ${candidate.address} answered HTTP ${probe.status} to this app's desktop read without refusing its credential; not attaching this tick, and not starting a daemon over it.`,
+        LogFileType.BACKEND
+      );
+      this.discoveryBlocksSpawn = true;
+      this.answeredButUnusable = {
+        address: candidate.address,
+        status: probe.status
+      };
+      this.daemonState.observe({
+        kind: "unattachable",
+        detail: `A daemon is running at ${candidate.address} and answered this app's read with HTTP ${probe.status}, so this app is not attached to it. Nothing is being started over it.`
       });
       this.notifyStatus();
       return false;
     }
+    if (probe.verdict === "unreachable") {
+      return false;
+    }
     await this.attachTo(candidate, token);
     return true;
   }
@@ -6024,16 +6353,17 @@ class BackendServiceManager {
    * `this.desktopToken` because this runs BEFORE adoption: the candidate must
    * be proved usable without the manager having committed to it.
    */
-  async authenticatesAgainst(address, token) {
+  async probeCandidate(address, token) {
     try {
       const result = await requestDesktop(
         { op: "sessions.list", limit: 1 },
         address,
         token
       );
-      return result.status >= 200 && result.status < 300;
+      const verdict = classifyDesktopAnswer(result.status);
+      return verdict === "accepted" ? { verdict } : { verdict, status: result.status };
     } catch {
-      return false;
+      return { verdict: "unreachable" };
     }
   }
   /**
@@ -6139,7 +6469,7 @@ class BackendServiceManager {
       const payload = await response.json().catch(() => null);
       if (!await this.authenticatesAgainstBackend()) {
         logger.info(
-          "A backend answered health but refused this app's desktop token; not adopting it.",
+          "A backend answered health but did not accept this app's desktop credential; not adopting it.",
           LogFileType.BACKEND
         );
         return false;
@@ -6187,7 +6517,7 @@ class BackendServiceManager {
         op: "sessions.list",
         limit: 1
       });
-      return result.status >= 200 && result.status < 300;
+      return classifyDesktopAnswer(result.status) === "accepted";
     } catch {
       return false;
     }
@@ -6268,7 +6598,13 @@ class BackendServiceManager {
       this.startHealthCheck();
       return false;
     }
-    this.desktopToken = node_crypto.randomBytes(32).toString("hex");
+    const occupancy = await this.configuredOriginOccupancy();
+    if (occupancy) {
+      this.observeOriginOccupancy(occupancy);
+      this.startHealthCheck();
+      return false;
+    }
+    this.desktopToken = this.mintDesktopToken();
     let captured = null;
     try {
       this.venvPath = managedVenvPath({
@@ -6700,11 +7036,142 @@ class BackendServiceManager {
         `Backend health check response status: ${response.status}`,
         LogFileType.BACKEND
       );
+      this.lastHealthFailure = null;
       return response.ok;
-    } catch (_error) {
+    } catch (error) {
+      this.lastHealthFailure = classifyUnreachable(error);
       return false;
     }
   }
+  /**
+   * What is answering the address this app is configured to serve on, if
+   * anything that stops it starting a daemon there.
+   *
+   * `null` means "start it": either the socket was refused (the one answer that
+   * proves a port free), or something answered 200 without identifying as a Local
+   * Operator daemon. The second arm is deliberate and narrow - see the spawn gate
+   * in `startOwned()` - and the observation is logged either way. An answer whose
+   * STATUS is not 200 is not in that arm: it is an occupant (review round 1,
+   * F-2), and it returns a `silent` occupancy below rather than a licence to
+   * spawn.
+   */
+  async configuredOriginOccupancy() {
+    const probe = await probeUnidentified(this.backendUrl, {
+      timeoutMs: PROBE_TIMEOUT_MS$1
+    });
+    switch (probe.reason) {
+      case "identity-mismatch":
+        return {
+          kind: "daemon",
+          pid: probe.identity?.pid ?? null,
+          version: probe.identity?.version ?? "",
+          detail: probe.detail
+        };
+      /*
+       * A status that is not 200 is an OCCUPANT, not a licence to spawn, and it
+       * is handled here rather than by the `default` arm below so the decision is
+       * the one a reader finds rather than the one the switch happens to fall
+       * into (review round 1, F-2). It covers a Local Operator daemon starting up,
+       * unhealthy or shutting down, and a proxy that fronts one and answers 5xx:
+       * in every one of them the socket is bound, so a child spawned onto it dies
+       * on `[Errno 48]` - after `mintDesktopToken()` has already overwritten the
+       * credential for the daemon actually serving there. The answer does not
+       * prove a daemon this app may attach to, so the gate declines to start one
+       * and keeps probing; that is the safe direction, because the failure mode of
+       * the other one is unrecoverable loss of the pairing token.
+       */
+      case "unready-answer":
+        return {
+          kind: "silent",
+          cause: "other",
+          detail: probe.detail
+        };
+      case "not-a-daemon":
+        logger.info(
+          `${this.backendUrl}${HEALTH_PATH$1} answered and is not a Local Operator daemon (${probe.detail}); starting a daemon anyway, as this app always has.`,
+          LogFileType.BACKEND
+        );
+        return null;
+      case "unreachable":
+        return probe.cause === "refused" ? null : {
+          kind: "silent",
+          cause: probe.cause ?? "other",
+          detail: probe.detail
+        };
+      default:
+        return {
+          kind: "silent",
+          cause: "other",
+          detail: probe.detail
+        };
+    }
+  }
+  /**
+   * Publish what the spawn gate saw, in the vocabulary the copy already uses.
+   *
+   * Two outcomes reach here and each gets the state that names it: a Local
+   * Operator daemon this app may not drive is `unattachable` (state `wedged` - a
+   * server IS running and this app did not attach to it, no banner claiming it is
+   * offline), and an address that did not answer in time is `unanswered` -
+   * `degraded`, usable, no banner, and still counted, because a budget that
+   * expired is not evidence of absence either way.
+   */
+  observeOriginOccupancy(occupancy) {
+    const daemonLine = occupancy.kind === "daemon";
+    const what = daemonLine ? "This app was not given the key to that server, so it did not start a second one" : `${this.backendUrl} answered without proving it is a Local Operator daemon, so this app did not start one there`;
+    const detail = `${what}. It keeps probing for a server it can open.`;
+    this.daemonState.observe(
+      occupancy.kind === "silent" ? { kind: "unanswered", cause: occupancy.cause, detail } : { kind: "unattachable", detail }
+    );
+    logger.info(`Not spawning a daemon: ${detail}`, LogFileType.BACKEND);
+    this.notifyStatus();
+  }
+  /**
+   * The token governing the daemon this app spawned in a PREVIOUS run, read from
+   * the 0600 file beside the app's other per-user state, or null.
+   *
+   * Read-only on purpose: a launch that has not spawned anything yet must not
+   * create a credential, or "this app holds no token" (a first run, and the
+   * honest reason to decline a daemon it cannot open) would become unreachable.
+   */
+  persistedDesktopToken() {
+    try {
+      const stored = fs.readFileSync(this.desktopTokenFile(), "utf8").trim();
+      return stored || null;
+    } catch {
+      return null;
+    }
+  }
+  /**
+   * Mint the token for a daemon this app is about to spawn, and persist it so the
+   * next launch can re-attach to that daemon instead of starting a second one.
+   *
+   * A token that cannot be written still governs this run's child - failing to
+   * start over a cache file would be the worse trade - and the log line names
+   * the cost, which is the stranded daemon next launch.
+   */
+  mintDesktopToken() {
+    const token = node_crypto.randomBytes(32).toString("hex");
+    try {
+      const file = this.desktopTokenFile();
+      fs.mkdirSync(path$1.dirname(file), { recursive: true, mode: 448 });
+      fs.writeFileSync(file, token, { mode: 384 });
+    } catch (error) {
+      logger.warn(
+        "Could not persist the desktop token; a daemon spawned now will not be re-attachable after a restart.",
+        LogFileType.BACKEND,
+        error
+      );
+    }
+    return token;
+  }
+  desktopTokenPath = null;
+  desktopTokenFile() {
+    if (this.desktopTokenPath === null) {
+      this.desktopTokenPath = path$1.join(this.appDataPath, DESKTOP_TOKEN_FILENAME);
+    }
+    return this.desktopTokenPath;
+  }
   /**
    * One probe of the daemon this app is attached to.
    *
@@ -6722,9 +7189,12 @@ class BackendServiceManager {
     const expected = this.daemonState.expectedInstanceId();
     if (!expected) {
       const ok = await this.checkHealth();
-      return ok ? { kind: "identified" } : {
-        kind: "failed",
-        detail: `No answer from ${this.backendUrl}${HEALTH_PATH$1}`
+      if (ok) return { kind: "identified" };
+      const failure = this.lastHealthFailure;
+      return {
+        kind: failure === null || failure === "refused" ? "failed" : "unanswered",
+        cause: failure ?? "other",
+        detail: failure === null ? `${this.backendUrl}${HEALTH_PATH$1} answered a status this app does not accept` : `No answer from ${this.backendUrl}${HEALTH_PATH$1}`
       };
     }
     const probe = await probeIdentity(this.backendUrl, expected, {
@@ -6747,8 +7217,12 @@ class BackendServiceManager {
           detail: `${this.backendUrl} answered but is not a Local Operator daemon (${probe.detail})`
         };
       case "unreachable":
-        return {
+        return probe.cause === "refused" ? {
           kind: "failed",
+          detail: `${this.backendUrl} refused the connection (${probe.detail})`
+        } : {
+          kind: "unanswered",
+          cause: probe.cause,
           detail: `${this.backendUrl} did not answer (${probe.detail})`
         };
     }