local-operator-ui 0.25.9 → 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);
@@ -2107,13 +2187,18 @@ function pythonBytecodeCacheDir(userDataDir) {
 }
 function withPythonBytecodeCache(env, userDataDir) {
   const existing = env.PYTHONPYCACHEPREFIX?.trim();
-  const prefix = existing && !insideAppBundle(existing) ? existing : pythonBytecodeCacheDir(userDataDir);
+  const prefix = isUsablePrefix(existing) ? existing : pythonBytecodeCacheDir(userDataDir);
   return {
     ...env,
     PYTHONPYCACHEPREFIX: prefix,
     PYTHONDONTWRITEBYTECODE: "1"
   };
 }
+function isUsablePrefix(value) {
+  if (!value) return false;
+  if (!path$1.isAbsolute(value)) return false;
+  return !insideAppBundle(value);
+}
 const VENV_BYTECODE_GUARD_FILE = "sitecustomize.py";
 const VENV_BYTECODE_GUARD_SENTINEL = "# Local Operator bytecode guard";
 function venvBytecodeGuardSource() {
@@ -2310,8 +2395,6 @@ function isPythonBytecodePath(bundlePath, candidate) {
   );
   const separator = "/";
   if (!path2.endsWith(".pyc")) return false;
-  const segments = path2.split(separator);
-  if (!segments.includes("__pycache__")) return false;
   return dirs.some((dir) => path2.startsWith(`${dir}${separator}`));
 }
 function planPythonBytecodeHeal(bundlePath, violations) {
@@ -3619,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;
@@ -3639,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";
@@ -3673,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;
@@ -3698,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);
@@ -3711,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();
@@ -3767,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
     };
@@ -3899,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;
@@ -3955,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)
     };
   }
@@ -4140,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`
       };
     }
@@ -4158,6 +4375,7 @@ async function probeUnidentified(address, options = {}) {
   } catch (error) {
     return {
       reason: "unreachable",
+      cause: classifyUnreachable(error),
       detail: error instanceof Error ? error.message : String(error)
     };
   }
@@ -5186,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;
@@ -5212,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,
@@ -5223,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. */
@@ -5252,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
@@ -5444,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
@@ -5491,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
@@ -5765,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",
@@ -5911,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();
@@ -5993,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;
   }
@@ -6021,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" };
     }
   }
   /**
@@ -6136,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;
@@ -6184,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;
     }
@@ -6265,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({
@@ -6697,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.
    *
@@ -6719,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, {
@@ -6744,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})`
         };
     }
@@ -8337,13 +8814,35 @@ class ApprovalStore {
   /**
    * Raise a request, or report that one already covers this caller.
    *
-   * The rules are `vendor/driver/access-flow.ts`'s, applied to the queue: a repeat
-   * request for the same origin by the same requester is idempotent with its
-   * original TTL, a request for a different origin REPLACES the live one (with
-   * a tombstone for the displaced requester), and a DURABLE denial answers
-   * "denied" without re-prompting, because that is what the button promises —
-   * "Don't allow" says the agent stops asking about this site until the denial is
-   * revoked.
+   * THE QUEUE IS A QUEUE, and this comment is the record of what changed. Until
+   * this round `requestAccess` called `displaceLive` on every new request, which
+   * cleared the WHOLE live queue and tombstoned it: one prompt slot,
+   * replace-don't-queue, so a second agent's request destroyed the first agent's
+   * (and the test said so plainly, `"one prompt slot, replace-don't-queue"`).
+   * The design authority says the opposite — "the queue is FIFO with a 10-minute
+   * async TTL" (design 9.1), which is why `access-queue.ts` ships a cap of 16 that
+   * this host could never reach — and the operator asked for it by name ("allow a
+   * queue"). So:
+   *
+   * 1. A repeat request for the same origin by the same requester is idempotent
+   *    with its ORIGINAL TTL. Resetting the TTL would let a polling agent extend
+   *    the window indefinitely.
+   * 2. A live receipt answers without re-prompting (see the deny arm below), so a
+   *    user does not learn to click Allow to make the prompt stop.
+   * 3. A request for a different origin, or from a different requester, is
+   *    APPENDED in `sequence` order and waits its turn.
+   * 4. At the cap the OLDEST live entry is displaced, with a `superseded`
+   *    tombstone so the agent that raised it learns what happened rather than
+   *    timing out into an anonymous `none`. The NEWEST requester is never refused:
+   *    refusing the agent that is behaving normally would turn a full queue into a
+   *    hard, unactionable failure for the one caller that did nothing wrong.
+   *
+   * WHAT THE CHANGE COSTS, stated because it is a real trade a reviewer should not
+   * have to find: a displaced request taught its agent immediately, where a queued
+   * one now waits for its own `await_access` budget and then re-requests
+   * (idempotent while its entry is live). In exchange, a user with four agents
+   * working sees four requests instead of one, and no agent's request is destroyed
+   * by another's arrival.
    */
   requestAccess(rawUrl, requester, kind = "async", commandId) {
     const url = safeHttpUrl(rawUrl);
@@ -8360,13 +8859,8 @@ class ApprovalStore {
     }
     this.sweep(now);
     if (liveQueue(this.queue, now).length >= ACCESS_QUEUE_CAP) {
-      throw new BridgeCommandError(
-        "access_queue_full",
-        `site approval queue is full with ${liveQueue(this.queue, now).length} pending requests`,
-        { pending_count: liveQueue(this.queue, now).length }
-      );
+      this.displaceOldest(now);
     }
-    this.displaceLive(now);
     const entry = newEntry(
       url.origin,
       displayAuthority(url),
@@ -8415,18 +8909,19 @@ class ApprovalStore {
         requestedAt: entry.requestedAt,
         expiresAt: entry.expiresAt
         /*
-         * NO `decision` TERM, and the removal is the point. The vendored
-         * `accessState()` takes an optional decision so that a LIVE record can read
-         * `allowed`/`denied` before the grant lands, and this host fed it from the
-         * decision receipts — but every arm that writes a receipt removes its entry
-         * from the queue FIRST (`respond` filters, `cancelAccess` splices), entry ids
-         * are minted per entry and nothing here is restored from disk, so a record
-         * with a decision can never be the record this reads. It was unreachable code
-         * carrying the residue of the defect this fix closes, and a reader would
-         * reasonably infer from it that a receipt can still answer. It cannot:
-         * `requestAccess` answers from `liveAuthority` and from a durable verdict, and
-         * the receipts are the store's record of what was decided (swept by TTL)
-         * rather than a reader's source.
+         * NO `decision` TERM, and the removal is the point (review round 1,
+         * finding 5). The vendored `accessState()` takes an optional decision so
+         * that a LIVE record can read `allowed`/`denied` before the grant lands,
+         * and this host fed it from the decision receipts — but every arm that
+         * writes a receipt removes its entry from the queue FIRST (`respond`
+         * filters, `cancelAccess` splices), entry ids are minted per entry and
+         * nothing here is restored from disk, so a record with a decision can
+         * never be the record this reads. It was unreachable code carrying the
+         * residue of the defect this PR fixes, and a reader would reasonably infer
+         * from it that a receipt can still answer. It cannot: `requestAccess`
+         * answers from `liveAuthority` and from a durable verdict, and the
+         * receipts are the store's record of what was decided (purged by
+         * `revokeOrigin` and swept by TTL) rather than a reader's source.
          */
       } : void 0,
       this.tombstones,
@@ -8484,6 +8979,16 @@ class ApprovalStore {
       );
     }
     const now = this.now();
+    if (now >= entry.expiresAt) {
+      this.queue = this.queue.filter(
+        (candidate) => candidate.entryId !== entryId
+      );
+      this.onChanged();
+      throw new BridgeCommandError(
+        "internal",
+        "that site approval request expired before it was answered; the agent has to ask again"
+      );
+    }
     this.queue = this.queue.filter(
       (candidate) => candidate.entryId !== entryId
     );
@@ -8644,6 +9149,9 @@ class ApprovalStore {
       delete this.store.origins[origin];
       removed += 1;
     }
+    for (const key of Object.keys(this.results)) {
+      if (this.results[key]?.origin === origin) delete this.results[key];
+    }
     if (this.sessionGrants.delete(origin)) removed += 1;
     const before = this.store.records.length;
     this.store.records = this.store.records.filter(
@@ -8701,13 +9209,17 @@ class ApprovalStore {
     this.onChanged();
   }
   // ---- internals -----------------------------------------------------------
-  /** Replace-don't-queue: the live entry for another origin (or another
-   * requester) is displaced, and its requester gets a tombstone so its next poll
+  /** At the cap: the OLDEST live entry (or entries, if a queue was restored over
+   * the cap) steps aside, and its requester gets a tombstone so its next poll
    * reads "superseded" rather than the neutral "none". */
-  displaceLive(now) {
+  displaceOldest(now) {
     const live = liveQueue(this.queue, now);
     if (!live.length) return;
-    for (const entry of live) {
+    const displaced = live.slice(
+      0,
+      Math.max(1, live.length - ACCESS_QUEUE_CAP + 1)
+    );
+    for (const entry of displaced) {
       this.tombstones[receiptKey(entry.origin, entry.requester)] = tombstoneFor(
         {
           origin: entry.origin,
@@ -8718,7 +9230,8 @@ class ApprovalStore {
         }
       );
     }
-    this.queue = [];
+    const displacedIds = new Set(displaced.map((entry) => entry.entryId));
+    this.queue = this.queue.filter((entry) => !displacedIds.has(entry.entryId));
     this.trimTombstones();
   }
   trimTombstones() {
@@ -9147,45 +9660,56 @@ class CdpPool {
   }
 }
 const CONSENT_TITLE = "Site approval needed";
-function consentBody(origin) {
-  return `An agent wants to open ${origin}. Approve or deny it in the browser tab.`;
+function consentBody(count, origin) {
+  return count === 1 ? `An agent wants to open ${origin}. Approve or deny it in the browser tab.` : `${count} site approvals are waiting. Approve or deny them in the browser tab.`;
 }
 class ConsentNotifier {
   constructor(options) {
     this.options = options;
   }
-  announced = /* @__PURE__ */ new Set();
+  announced = 0;
   /**
-   * Announce the pending entries that have not been announced yet.
+   * Announce a change in the size of the pending set — ONE banner per increase.
    *
-   * Called with the CURRENT pending list on every change rather than on an
-   * "added" event: the store's change hook is one callback for a mutable set,
-   * and a diff against what was already announced is both simpler and correct
-   * when an entry is superseded and replaced by a new one with a new id.
+   * WHY A COUNT WATERMARK RATHER THAN A SET OF ANNOUNCED IDS, which is what this
+   * was: with one prompt slot the set could hold at most one entry, and with a
+   * real queue (`approvals.ts` no longer displaces) the old rule raised one
+   * banner PER UNANNOUNCED ENTRY — up to 16 banners for one busy minute, against
+   * a rule that exists to avoid interrupting the operator (design 9.2, 11.4).
+   * The count of the live set is the thing the user can act on, so an increase is
+   * the event and a banner is the whole response to it.
+   *
+   * WHAT THIS GIVES UP, deliberately: a request that replaces another without
+   * changing the count (a displacement at the cap, a cancel plus an arrival in
+   * one refresh) raises no second banner. The alternative is a banner per entry,
+   * and the banner's job is to bring the user to the band — where the tray shows
+   * the whole live set, numbered. The click names the OLDEST live entry, which is
+   * the one the tray selects by default.
    */
   announce(pending) {
-    const live = new Set(pending.map((entry) => entry.entryId));
-    for (const entryId of [...this.announced]) {
-      if (!live.has(entryId)) this.announced.delete(entryId);
-    }
+    const count = pending.length;
+    const increased = count > this.announced;
+    this.announced = count;
+    if (!increased) return;
     if (this.options.show !== "focus") return;
-    if (!electron.Notification.isSupported()) return;
-    for (const entry of pending) {
-      if (this.announced.has(entry.entryId)) continue;
-      this.announced.add(entry.entryId);
-      try {
-        const notification = new electron.Notification({
+    const create = this.options.createNotification;
+    if (!create && !electron.Notification.isSupported()) return;
+    const oldest = pending[0];
+    if (!oldest) return;
+    try {
+      const notification = (create ?? ((options) => new electron.Notification(options)))(
+        {
           title: CONSENT_TITLE,
-          body: consentBody(entry.origin),
+          body: consentBody(count, oldest.origin),
           silent: false
-        });
-        notification.on("click", () => this.options.onAttention(entry.entryId));
-        notification.show();
-      } catch (error) {
-        this.options.log?.(
-          `[browser] could not raise a consent banner: ${String(error)}`
-        );
-      }
+        }
+      );
+      notification.on("click", () => this.options.onAttention(oldest.entryId));
+      notification.show();
+    } catch (error) {
+      this.options.log?.(
+        `[browser] could not raise a consent banner: ${String(error)}`
+      );
     }
   }
 }
@@ -10718,6 +11242,16 @@ class BrowserHost {
   titleForChrome(title) {
     return title === "about:blank" ? "" : title;
   }
+  /** Whether a tab is loading right now, false for a tab that is gone or whose
+   * webContents has already been destroyed. Guarded the same way `snapshot()`
+   * guards its reads: a read that lands between destruction and the
+   * `destroyed` handler would otherwise throw "Object has been destroyed" out of
+   * an IPC handler and blank the whole strip instead of dropping one tab. */
+  tabLoading(tabId) {
+    const record = this.registry.get(tabId);
+    if (!record || record.view.webContents.isDestroyed()) return false;
+    return record.view.webContents.isLoading();
+  }
   chromeState() {
     const activeRecord = this.registry.activeTab;
     const active = activeRecord && !activeRecord.view.webContents.isDestroyed() ? activeRecord : null;
@@ -10734,7 +11268,16 @@ class BrowserHost {
         // Per TAB, not only for the active one: a background tab whose load was
         // refused has no other way to say so - its page area is blank and the
         // band belongs to the active tab - so the strip carries the mark.
-        failed: this.loadFailures.has(entry.tabId)
+        failed: this.loadFailures.has(entry.tabId),
+        // PER TAB, and it is the one projection field this feature adds. The strip
+        // could only ever see the ACTIVE tab's loading state before (`loading`
+        // below), so a background agent tab that is loading a page showed nothing
+        // at all - and since an agent tab is created non-active and only the active
+        // tab occupies the content rect (`registry.ts:492-503`), "nothing at all"
+        // was the whole of what the user saw of an agent's work. Read from the
+        // record rather than the snapshot: `snapshot()` is the diagnostic
+        // projection shared with `status`/`tabs`, and this field is chrome.
+        loading: this.tabLoading(entry.tabId)
       })),
       activeTabId: activeRecord?.tabId ?? null,
       url: active ? active.view.webContents.getURL() : "",