local-operator-ui 0.30.28 → 0.30.30

package/out/main/index.js

@@ -47,6 +47,9 @@ const DAEMON_UNPAIRED = {
 };
 const BACKEND_STATUS_EVENT = "backend-status-changed";
 const BACKEND_RECONNECT_CHANNEL = "backend-reconnect";
+function isServerReachable(state) {
+  return state !== "detached" && state !== "wedged";
+}
 function relayNeedsRebuild(current, next) {
   return current.url !== next.url || current.token !== next.token;
 }
@@ -223,6 +226,9 @@ const publicationDocument = zod.z.object({
   categories: zod.z.array(zod.z.string()),
   tags: zod.z.array(zod.z.string())
 }).partial().strict();
+const catalogueScopeKind = zod.z.enum(["team", "agent"]);
+const catalogueScopeName = zod.z.string().min(1).max(64);
+const catalogueCursor = zod.z.string().min(1).max(256);
 const desktopRequestSchema = zod.z.discriminatedUnion("op", [
   zod.z.object({ op: zod.z.literal("capabilities") }).strict(),
   zod.z.object({ op: zod.z.literal("profiles.list") }).strict(),
@@ -272,7 +278,31 @@ const desktopRequestSchema = zod.z.discriminatedUnion("op", [
      * questions a list that hides them cannot answer: the open conversation's own
      * archived state, and an unarchive control on a row found by search.
      */
-    include_archived: zod.z.boolean().optional()
+    include_archived: zod.z.boolean().optional(),
+    /*
+     * The four parameters that make the catalogue PAGEABLE, and the switch that
+     * makes the daemon count it.
+     *
+     * ALL FOUR ARE OPTIONAL AND DEFAULTED, which is the whole compatibility
+     * promise: a request that sends none of them is byte-identical to the one
+     * this app sent before they existed, and an older daemon is therefore fully
+     * supported. They are gated on the `session_catalogue_page` capability rather
+     * than on a `session_catalogue` version bump, for the reason that map's own
+     * register states (an EXISTING surface must keep working against a backend
+     * that lacks the new one): FastAPI silently ignores unknown query parameters,
+     * so an un-gated client asking for `scope_kind=team&scope_name=lopdev` would
+     * receive the UNSCOPED page and draw other teams' rows under that team, and an
+     * un-gated `cursor` would receive page one again and duplicate it. The client
+     * has to be able to ask whether the daemon understands these, and the
+     * capability map is how this codebase asks.
+     *
+     * They travel as ONE contract revision rather than three: counts without the
+     * scope could not be rendered consistently with that scope's paged rows.
+     */
+    scope_kind: catalogueScopeKind.optional(),
+    scope_name: catalogueScopeName.optional(),
+    cursor: catalogueCursor.optional(),
+    with_counts: zod.z.boolean().optional()
   }).strict(),
   zod.z.object({
     // Content search over the store: name, id, exact conversation body, and
@@ -1323,14 +1353,19 @@ function desktopEndpoint(request) {
         method: "PATCH",
         body: { request_id: request.requestId, ...request.fields }
       };
-    case "sessions.list":
+    case "sessions.list": {
+      const params = new URLSearchParams();
+      params.set("limit", String(request.limit ?? 100));
+      if (request.include_archived) params.set("include_archived", "true");
+      if (request.scope_kind) params.set("scope_kind", request.scope_kind);
+      if (request.scope_name) params.set("scope_name", request.scope_name);
+      if (request.cursor) params.set("cursor", request.cursor);
+      if (request.with_counts) params.set("with_counts", "true");
       return {
-        // Omitted when false, for the reason `sessions.search`'s own query
-        // states: the pre-flag request is what an older backend must keep
-        // seeing, and `false` is the route's default anyway.
-        path: `/v1/desktop/sessions?limit=${request.limit ?? 100}${request.include_archived ? "&include_archived=true" : ""}`,
+        path: `/v1/desktop/sessions?${params}`,
         method: "GET"
       };
+    }
     case "sessions.search": {
       const query = new URLSearchParams({
         q: request.q,
@@ -2056,6 +2091,65 @@ function readServeRecords(dir) {
   }
   return { files, problem: null };
 }
+function recordsHolding(files, address, now) {
+  if (!address) return [];
+  const wanted = normaliseAddress(address) ?? address;
+  const records = [];
+  for (const entry of files) {
+    if (!entry.record) continue;
+    if (recordAddress(entry.record) !== wanted) continue;
+    if (recordPidLiveness(entry.record, now) === "dead") continue;
+    records.push(entry.record);
+  }
+  return records;
+}
+function addressHoldsLiveRecord(address, options = {}) {
+  const { unreadable, records } = addressHolders(address, options);
+  return unreadable || records.length > 0;
+}
+function anyRecordHoldsSomething(files, now) {
+  return files.some(
+    (entry) => !entry.record || recordPidLiveness(entry.record, now) !== "dead"
+  );
+}
+function addressHolders(address, options = {}) {
+  if (!address) return { unreadable: false, records: [] };
+  const { files, problem } = readServeRecords(
+    serveRunDir(options.env ?? process.env)
+  );
+  return {
+    unreadable: problem === "unreadable",
+    records: recordsHolding(files, address, (options.now ?? Date.now)())
+  };
+}
+function listenerPidsOn(port) {
+  if (!Number.isInteger(port) || port <= 0 || port > 65535) return [];
+  try {
+    const out = node_child_process.execFileSync(
+      "lsof",
+      ["-nP", `-iTCP:${port}`, "-sTCP:LISTEN", "-t"],
+      { encoding: "utf8", timeout: 2e3 }
+    );
+    const pids = /* @__PURE__ */ new Set();
+    for (const line of out.split("\n")) {
+      const pid = Number.parseInt(line.trim(), 10);
+      if (Number.isInteger(pid) && pid > 0) pids.add(pid);
+    }
+    return [...pids];
+  } catch {
+    return [];
+  }
+}
+function readRecordForPid(pid, env = process.env) {
+  if (!Number.isInteger(pid) || pid <= 0) return null;
+  const file = path$1.join(serveRunDir(env), `${pid}.json`);
+  try {
+    const entry = parseRecord(JSON.parse(fs.readFileSync(file, "utf8")), file);
+    return entry.record && entry.record.pid === pid ? entry.record : null;
+  } catch {
+    return null;
+  }
+}
 function pidLiveness(pid, options = {}) {
   try {
     process.kill(pid, 0);
@@ -2096,8 +2190,18 @@ function classifyRecord(record, now, liveness = recordPidLiveness(record, now))
   return age > HEARTBEAT_TIMEOUT_MS ? "wedged" : "live";
 }
 function recordAddress(record) {
-  const host = record.host.includes(":") ? `[${record.host}]` : record.host;
-  return `http://${host}:${record.port}`;
+  return addressOf("http:", canonicalHost(record.host), record.port);
+}
+function canonicalHost(host) {
+  const bare = host.startsWith("[") && host.endsWith("]") ? host.slice(1, -1) : host;
+  const unqualified = bare.endsWith(".") ? bare.slice(0, -1) : bare;
+  const lower = unqualified.toLowerCase();
+  if (lower === "localhost") return "127.0.0.1";
+  if (lower === "::1" || lower === "0:0:0:0:0:0:0:1") return "::1";
+  return bare;
+}
+function addressOf(scheme, host, port) {
+  return `${scheme}//${host.includes(":") ? `[${host}]` : host}:${port}`;
 }
 function classifyUnreachable(error) {
   const name = error?.name;
@@ -2320,12 +2424,24 @@ async function discoverDaemons(options = {}) {
     wedged,
     noRecordsAtAll: files.length === 0,
     // A dead PID is positive evidence; timeout, malformed JSON or a stopped
-    // heartbeat is not. Do not spawn over a busy or temporarily unreadable daemon.
-    // The liveness question is asked the way `registry.py::scan` asks it, so a
+    // heartbeat is not. Do not spawn over an address a record says is held. The
+    // liveness question is asked the way `registry.py::scan` asks it, so a
     // zombie record is dead here too and cannot block spawning forever.
-    blocksSpawn: problem === "unreadable" || files.some(
-      (entry) => !entry.record || recordPidLiveness(entry.record, now()) !== "dead"
-    )
+    //
+    // SCOPED TO THE CONFIGURED ADDRESS (2026-09-23). It used to be scoped to the
+    // ROOT - any record anywhere in this config root with a non-dead pid - which
+    // forbade the spawn onto the address this app was actually configured for
+    // because something else in the root had a live record. `addressHoldsLiveRecord`
+    // is the same predicate for the addresses this app may also spawn on, so the
+    // per-address gate in `backend-service.ts` and this verdict cannot disagree.
+    // A caller that names NO address gets the old root-wide answer instead
+    // (`anyRecordHoldsSomething`): there is then no address this verdict can call
+    // free, and answering "free" on no evidence is the direction this module never
+    // takes. The unparseable record lives in that arm for the same reason - it
+    // cannot be attributed to an address at all - and what it used to stand for, a
+    // daemon holding a port and not answering, is now asked directly of the port by
+    // the spawn gate's own occupancy probe.
+    blocksSpawn: problem === "unreadable" || (configuredAddress === null ? anyRecordHoldsSomething(files, now()) : recordsHolding(files, configuredAddress, now()).length > 0)
   };
   for (const rejection of rejected) {
     log(
@@ -2341,9 +2457,13 @@ function normaliseAddress(url) {
   if (!url) return null;
   try {
     const parsed = new URL(url);
-    const host = parsed.hostname.includes(":") ? `[${parsed.hostname}]` : parsed.hostname;
+    if (!parsed.hostname) return null;
     const port = parsed.port || (parsed.protocol === "https:" ? "443" : "80");
-    return `${parsed.protocol}//${host}:${port}`;
+    return addressOf(
+      parsed.protocol,
+      canonicalHost(parsed.hostname),
+      Number(port)
+    );
   } catch {
     return null;
   }
@@ -6290,6 +6410,17 @@ class DaemonStateMachine {
   getUrl() {
     return this.identity?.url ?? null;
   }
+  /**
+   * The connection's own snapshot.
+   *
+   * IT RETURNS EVERY FIELD EXCEPT `addressSubstitution`, and the Omission is the
+   * point rather than a type trick (agent round 2, R2-1): that field is DERIVED
+   * from the address this app is actually on, so it is assembled by the manager
+   * (`BackendServiceManager.getStatusSnapshot`) which is the only object that holds
+   * both the configured address and the connection. A machine that could write it
+   * here would be a second producer, which is exactly how the field came to claim a
+   * fallback the app had already left.
+   */
   snapshot() {
     return {
       state: this.state,
@@ -7302,6 +7433,110 @@ function readinessPollDelayMs(elapsedMs) {
   return READINESS_POLL_INTERVAL_MS;
 }
 const DESKTOP_TOKEN_FILENAME = "desktop-token";
+function portOf(address) {
+  try {
+    const parsed = Number.parseInt(new URL(address).port, 10);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+function installName(prefix) {
+  return prefix ? path$1.basename(prefix) : "";
+}
+function describeStartedAt(startedAtMs) {
+  const started = new Date(startedAtMs);
+  if (started.toDateString() === (/* @__PURE__ */ new Date()).toDateString()) {
+    return `started ${started.toLocaleTimeString(void 0, {
+      hour: "numeric",
+      minute: "2-digit"
+    })}`;
+  }
+  return `started ${started.toLocaleDateString(void 0, {
+    year: "numeric",
+    month: "short",
+    day: "numeric"
+  })}`;
+}
+function describeOccupant(occupant) {
+  const facts = [];
+  if (occupant.pid !== null) {
+    facts.push(
+      occupant.pidSource === "listener" ? `pid ${occupant.pid} read off the listening socket` : `pid ${occupant.pid}`
+    );
+  }
+  const install = occupant.installKind || installName(occupant.prefix);
+  if (install) facts.push(install);
+  if (occupant.version) facts.push(`v${occupant.version}`);
+  if (occupant.startedAtMs !== null) {
+    facts.push(describeStartedAt(occupant.startedAtMs));
+  }
+  if (occupant.desktopReadStatus !== null) {
+    facts.push(
+      classifyDesktopAnswer(occupant.desktopReadStatus) === "refused" ? `refused this app's credential for its desktop plane (HTTP ${occupant.desktopReadStatus})` : `answered this app's desktop read with HTTP ${occupant.desktopReadStatus}`
+    );
+  }
+  return facts.length > 0 ? ` (${facts.join(", ")})` : "";
+}
+const HOLDER_CLASS = {
+  daemon: {
+    one: "is running a Local Operator daemon this app has no key for",
+    many: "are running Local Operator daemons this app has no key for"
+  },
+  record: {
+    one: "is listed as still running in this app's own records",
+    many: "are listed as still running in this app's own records"
+  }
+};
+function listAddresses(items) {
+  if (items.length === 0) return "";
+  if (items.length === 1) return items[0];
+  return `${items.slice(0, -1).join(", ")} and ${items[items.length - 1]}`;
+}
+function describeHolder(occupancy) {
+  return `${occupancy.occupant.address}${describeOccupant(occupancy.occupant)}`;
+}
+function describeHolders(refusals) {
+  const fragments = [];
+  for (const kind of ["daemon", "record"]) {
+    const group = refusals.filter((occupancy) => occupancy.kind === kind);
+    if (group.length === 0) continue;
+    fragments.push(
+      `${listAddresses(group.map(describeHolder))} ${HOLDER_CLASS[kind][group.length === 1 ? "one" : "many"]}`
+    );
+  }
+  for (const occupancy of refusals) {
+    if (occupancy.kind !== "silent") continue;
+    fragments.push(
+      `${describeHolder(occupancy)} did not answer this app's probe with anything it could use (${occupancy.detail})`
+    );
+  }
+  if (refusals.some((occupancy) => occupancy.kind === "unreadable")) {
+    fragments.push(
+      "this app's own records could not be read, so no address it may serve on could be called free"
+    );
+  }
+  return fragments.join("; ");
+}
+const holderCount = (refusals) => refusals.length;
+function reclaimClause(refusals) {
+  const pids = refusals.map((occupancy) => occupancy.occupant.pid).filter((pid) => pid !== null);
+  if (pids.length === 0) return "";
+  const single = holderCount(refusals) === 1 && pids.length === 1;
+  const command = single ? `lop services reclaim ${pids[0]}` : "lop services reclaim <pid>";
+  const direct = single ? "it from the install that owns it" : "them from the installs that own them";
+  return ` Stop ${direct} with ${command} (lop services status lists what is running).`;
+}
+function describeSpawnRefusal(refusals) {
+  const named = refusals.filter((occupancy) => occupancy.kind !== "unreadable");
+  const stopped = named.length === 0 ? "Nothing was started" : named.length === 1 ? "Nothing was started over it" : "Nothing was started over them";
+  return `${describeHolders(refusals)}. ${stopped}.${reclaimClause(refusals)} It keeps probing for a server it can open.`;
+}
+const FALLBACK_SPAWN_URL = "http://127.0.0.1:8080";
+const NO_SUBSTITUTION_REASON = Object.freeze({
+  holder: null,
+  reclaim: null
+});
 const execPromise = node_util.promisify(node_child_process.exec);
 const ENV_VAR_REGEX = /^([^=]+)=(.*)$/;
 function classifyDesktopAnswer(status2) {
@@ -7329,7 +7564,50 @@ class BackendServiceManager {
   startupMode = "NOT_STARTED";
   port;
   backendUrl;
+  /**
+   * The address this app is CONFIGURED to serve on, which never rotates.
+   *
+   * `backendUrl` is where the app is TALKING - a daemon discovery adopted, or the
+   * fallback address after a fallback spawn - so a spawn gate keyed on it would
+   * ask "may I start a daemon here" about whatever the app happens to be attached
+   * to, which is somebody else's daemon. The config address is a separate fact and
+   * it is the one the gate needs.
+   */
+  configuredUrl;
+  /**
+   * The addresses this app may spawn a managed daemon on after the configured one,
+   * best first (`FALLBACK_SPAWN_URL` by default).
+   *
+   * A field rather than a bare constant so a rig can exercise the fallback on a
+   * port the kernel picked, which is the same reason `DiscoverOptions.fetchImpl`
+   * is injectable: proving this path must not require binding a fixed port on a
+   * machine somebody else is using.
+   */
+  fallbackSpawnUrls;
+  /**
+   * What stopped the last spawn attempt, when what stopped it was an address this
+   * app may spawn on being held by something IT DOES NOT OWN. Null when nothing
+   * did.
+   *
+   * Read by `index.ts` through `isStartBlockedByOccupiedAddress()`: a false return
+   * from `start()` is the one place the app used to quit, and the whole point of
+   * this field is that this class of failure is not a reason to take the app down.
+   */
+  spawnRefusals = null;
   remoteConfigured = false;
+  /**
+   * The last address this app served on that was NOT the one it is configured for,
+   * and the reason the gate gave for moving there.
+   *
+   * NEITHER IS THE CLAIM - both are history. The claim itself is derived on every
+   * snapshot from the address the connection is on (`addressSubstitutionFor`), so a
+   * reason recorded here can only reach a surface while the app is genuinely on
+   * that other address (agent round 2, R2-1/R2-2). That is what makes it safe to
+   * write the reason at the moment the gate makes its decision, which is the only
+   * moment the holder is observable at all.
+   */
+  servedElsewhere = null;
+  substitutionReason = NO_SUBSTITUTION_REASON;
   /** A failed probe or unreadable record is not evidence that spawning is safe. */
   discoveryBlocksSpawn = false;
   /**
@@ -7540,7 +7818,98 @@ class BackendServiceManager {
    * "I am not allowed" into "it is down".
    */
   getStatusSnapshot() {
-    return this.daemonState.snapshot();
+    const snapshot2 = this.daemonState.snapshot();
+    return {
+      ...snapshot2,
+      addressSubstitution: this.addressSubstitutionFor(snapshot2)
+    };
+  }
+  /**
+   * Where this app is serving, relative to the address it is configured for.
+   *
+   * THE INVARIANT (agent round 2, R2-1): a snapshot's address claim is a FUNCTION
+   * OF THE ADDRESS THE APP IS ACTUALLY USING, never of the last decision a gate
+   * made. The first version of this field was written once by the spawn gate, and
+   * that produced two wrong answers in opposite directions:
+   *
+   *   - a launch that ATTACHES to a daemon discovered on another address (the
+   *     second launch of the incident - the fallback daemon is still there and the
+   *     persisted credential still opens it) records nothing, so the app was
+   *     silently on another address, which is the invisibility D1 exists to remove;
+   *   - a substitution recorded earlier was never retracted: once recovery attached
+   *     the app back to the configured address the record still said `serving:
+   *     <fallback>`, beside a snapshot whose own `url` was the configured address,
+   *     and its reclaim advice named a pid that may by then be the daemon the
+   *     operator is using.
+   *
+   * It also answers agent round 2's R2-2 for free: the claim is derived from
+   * `isRunning` and the attached URL, so a start that never landed - a readiness
+   * timeout, a throw, a stop - reports nothing at all, where a record written at
+   * intent time announced a return over a dead backend.
+   *
+   * `holder`/`reclaim` are the one fact the derivation cannot recover, because the
+   * gate is the only witness to what held the address; they are kept beside the
+   * landing (`substitutionReasonFor`, which the landing publishes) and reach a surface
+   * only through an arm
+   * that is true. Null holder/reclaim is the honest state for a launch that adopted
+   * somebody else's daemon: it never asked the configured address anything.
+   */
+  addressSubstitutionFor(snapshot2) {
+    const configured = normaliseAddress(this.configuredUrl);
+    if (!configured || !snapshot2.url || !isServerReachable(snapshot2.state)) {
+      return null;
+    }
+    const serving = normaliseAddress(snapshot2.url);
+    if (!serving) return null;
+    if (serving !== configured) {
+      return {
+        kind: "substituted",
+        configured,
+        serving,
+        ...this.substitutionReason
+      };
+    }
+    return this.servedElsewhere ? { kind: "returned", configured, serving: this.servedElsewhere } : null;
+  }
+  /**
+   * Adopt a validated daemon, and record WHERE the app landed and WHY it landed there.
+   *
+   * Every landing in this class goes through here - the spawn's registration and
+   * both attach paths - which is what makes the claim a property of the app's
+   * address rather than of one code path (agent round 2, R2-1). `servedElsewhere`
+   * survives a landing on the configured address on purpose: it is what a return
+   * has to name.
+   *
+   * THE REASON TRAVELS WITH THE LANDING rather than being written beside it (agent
+   * round 3, R3-1). It used to be cleared here and re-recorded by the caller AFTER
+   * this call returned, which meant the snapshot this landing pushed carried
+   * `holder: null` for a fallback spawn - the ADOPTED arm's sentence about a daemon
+   * the app had just started, and with the act withheld - until the next read. Now
+   * the spawn path hands the reason in and the landing publishes it, so there is one
+   * push per landing and it is the true one. The default is the empty pair, which is
+   * what an attach path means: this app observed no holder because it never asked.
+   */
+  attachDaemon(identity, options, reason = NO_SUBSTITUTION_REASON) {
+    this.daemonState.attach(identity, options);
+    const configured = normaliseAddress(this.configuredUrl);
+    const landed = normaliseAddress(identity.url);
+    if (landed && configured && landed !== configured) {
+      this.servedElsewhere = landed;
+    }
+    this.substitutionReason = reason;
+  }
+  /**
+   * The reason a fallback was taken, composed where the gate's refusals are still in
+   * hand - and HANDED to the landing rather than written beside it (agent round 2,
+   * R2-2 for the timing, agent round 3, R3-1 for the hand-off). A start that never
+   * lands never carries this anywhere, and the claim is not there to render it
+   * anyway.
+   */
+  substitutionReasonFor(refusals) {
+    return refusals.length > 0 ? {
+      holder: describeHolders(refusals),
+      reclaim: reclaimClause(refusals).trim() || null
+    } : NO_SUBSTITUTION_REASON;
   }
   getStreamRelay() {
     if (!this.streamRelay || this.streamRelayUrl !== this.backendUrl || this.streamRelayToken !== this.desktopToken) {
@@ -7720,6 +8089,7 @@ class BackendServiceManager {
    */
   constructor(options = {}) {
     this.userShellPath = options.userShellPath;
+    this.fallbackSpawnUrls = options.fallbackSpawnUrls ?? [FALLBACK_SPAWN_URL];
     try {
       const apiUrl = new URL(backendConfig.VITE_LOCAL_OPERATOR_API_URL);
       this.port = Number.parseInt(apiUrl.port, 10) || 1111;
@@ -7740,6 +8110,7 @@ class BackendServiceManager {
         error
       );
     }
+    this.configuredUrl = this.backendUrl;
     this.venvPath = managedVenvPath({
       platform: process.platform,
       home: electron.app.getPath("home"),
@@ -8420,7 +8791,7 @@ class BackendServiceManager {
       `Attached to daemon ${candidate.address} (pid ${candidate.record.pid}, v${candidate.identity.version}, ${candidate.record.install_kind || "kind unknown"}, record ${candidate.file})${previousUrl !== candidate.address ? ` - backend URL moved from ${previousUrl}` : ""}`,
       LogFileType.BACKEND
     );
-    this.daemonState.attach(
+    this.attachDaemon(
       {
         url: candidate.address,
         instanceId: candidate.identity.instanceId,
@@ -8511,7 +8882,7 @@ class BackendServiceManager {
       this.attachedRecord = null;
       this.isExternalBackend = true;
       this.startupMode = "EXISTING_SERVER";
-      this.daemonState.attach(
+      this.attachDaemon(
         {
           url: this.backendUrl,
           instanceId: "",
@@ -8639,8 +9010,8 @@ class BackendServiceManager {
       return true;
     }
     if (epoch !== this.startEpoch || this.isAppClosing) return false;
-    if (!this.managerMaySpawn || this.remoteConfigured || this.discoveryBlocksSpawn) {
-      const noSpawnReason = this.managerMaySpawn ? this.remoteConfigured ? `the configured target (${this.backendUrl}) is remote` : "a local daemon may still be running and could not be attached" : "VITE_DISABLE_BACKEND_MANAGER=true";
+    if (!this.managerMaySpawn || this.remoteConfigured) {
+      const noSpawnReason = this.managerMaySpawn ? `the configured target (${this.backendUrl}) is remote` : "VITE_DISABLE_BACKEND_MANAGER=true";
       logger.info(
         `No daemon discovered, and this app is configured not to spawn one (${noSpawnReason}).`,
         LogFileType.BACKEND
@@ -8649,12 +9020,21 @@ class BackendServiceManager {
       this.startHealthCheck();
       return false;
     }
-    const occupancy = await this.configuredOriginOccupancy();
-    if (occupancy) {
-      this.observeOriginOccupancy(occupancy);
+    const { target: target2, refusals } = await this.resolveSpawnTarget();
+    this.spawnRefusals = target2 ? null : refusals;
+    if (!target2) {
+      this.observeSpawnRefusal(refusals);
       this.startHealthCheck();
       return false;
     }
+    this.port = target2.port;
+    this.backendUrl = target2.address;
+    if (refusals.length > 0) {
+      logger.warn(
+        `Starting a managed daemon on ${target2.address} instead: ${describeHolders(refusals)}.`,
+        LogFileType.BACKEND
+      );
+    }
     this.desktopToken = this.mintDesktopToken();
     let captured = null;
     try {
@@ -8723,7 +9103,8 @@ class BackendServiceManager {
           break;
         if (healthy) {
           this.isRunning = true;
-          await this.registerOwnedDaemon(child);
+          const reason = this.substitutionReasonFor(refusals);
+          await this.registerOwnedDaemon(child, reason);
           this.startHealthCheck();
           this.notifyBackendReady();
           return true;
@@ -8788,7 +9169,7 @@ class BackendServiceManager {
    * second arm is the case of an install predating the record format, which is
    * reachable on a fixed port exactly as the deprecated adoption path allows.
    */
-  async registerOwnedDaemon(child) {
+  async registerOwnedDaemon(child, reason) {
     const identity = await this.ownedDaemonIdentity(child);
     if (!identity) {
       logger.warn(
@@ -8797,7 +9178,7 @@ class BackendServiceManager {
       );
       return;
     }
-    this.daemonState.attach(identity, { owned: true });
+    this.attachDaemon(identity, { owned: true }, reason);
     this.daemonState.setPairing(DAEMON_PAIRED);
     this.notifyStatus();
     logger.info(
@@ -9106,16 +9487,15 @@ class BackendServiceManager {
    * F-2), and it returns a `silent` occupancy below rather than a licence to
    * spawn.
    */
-  async configuredOriginOccupancy() {
-    const probe = await probeUnidentified(this.backendUrl, {
+  async configuredOriginOccupancy(address) {
+    const probe = await probeUnidentified(address, {
       timeoutMs: PROBE_TIMEOUT_MS
     });
     switch (probe.reason) {
       case "identity-mismatch":
         return {
           kind: "daemon",
-          pid: probe.identity?.pid ?? null,
-          version: probe.identity?.version ?? "",
+          occupant: this.occupantOf(address, probe.identity ?? null),
           detail: probe.detail
         };
       /*
@@ -9135,11 +9515,12 @@ class BackendServiceManager {
         return {
           kind: "silent",
           cause: "other",
+          occupant: this.occupantOf(address, null),
           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.`,
+          `${address}${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;
@@ -9147,32 +9528,203 @@ class BackendServiceManager {
         return probe.cause === "refused" ? null : {
           kind: "silent",
           cause: probe.cause ?? "other",
+          occupant: this.occupantOf(address, null),
           detail: probe.detail
         };
       default:
         return {
           kind: "silent",
           cause: "other",
+          occupant: this.occupantOf(address, null),
           detail: probe.detail
         };
     }
   }
+  /**
+   * One address's holder, from the facts already in hand.
+   *
+   * WHERE EACH FACT COMES FROM, because the copy has to be able to say it. The
+   * occupant's own `/health` is asked first and is the only source that proves who
+   * holds the address; when it did not answer with an identity - a timeout, a
+   * non-200, a body with no `instance_id` - the LISTENING SOCKET is asked instead
+   * (`listenerPidsOn`), and `pidSource` carries which of the two produced the pid
+   * so the sentence reports a kernel fact as a kernel fact.
+   *
+   * The record lookup goes the other way round: it is keyed by the pid, so it adds
+   * `started_at` and the published install to whichever source named the holder.
+   * A holder that ALSO has a record in this app's own root is usually one of this
+   * app's own daemons from an earlier run, and that is worth saying out loud.
+   */
+  occupantOf(address, identity) {
+    let pid = identity && Number.isInteger(identity.pid) && identity.pid > 0 ? identity.pid : null;
+    let pidSource = pid === null ? null : "answer";
+    if (pid === null) {
+      const port = portOf(address);
+      const [found] = port === null ? [] : listenerPidsOn(port);
+      if (found !== void 0) {
+        pid = found;
+        pidSource = "listener";
+      }
+    }
+    const record = pid === null ? null : readRecordForPid(pid);
+    return {
+      address,
+      pid,
+      pidSource,
+      version: identity?.version || record?.version || "",
+      prefix: identity?.prefix || record?.prefix || "",
+      installKind: identity?.installKind || record?.install_kind || "",
+      startedAtMs: record ? record.started_at * 1e3 : null,
+      // Probe-side occupancy never carries this: `configuredOriginOccupancy` is
+      // asked about an address the attach path did not just read, and inventing
+      // a status here would be the same class of guess the record arm avoids.
+      desktopReadStatus: null
+    };
+  }
+  /**
+   * The addresses this app may spawn a managed daemon on, best first.
+   *
+   * The configured address leads, so a fallback spawn does not make the app forget
+   * where it was told to serve: `backendUrl` rotates to wherever the app ended up,
+   * while this list is recomputed from the configuration on every attempt. The rest
+   * are the fallback budget, de-duplicated by `normaliseAddress` so a configuration
+   * that already names 8080 does not probe one address twice - and the de-dup reads
+   * through `canonicalHost`, so a configuration naming `localhost` is not probed a
+   * second time as `127.0.0.1` (review round 1, R1-6: this comment asserted that
+   * folding before `normaliseAddress` did it, which is how the assertion and the
+   * comparison could disagree without either looking wrong).
+   */
+  spawnAddresses() {
+    const addresses = [this.configuredUrl, ...this.fallbackSpawnUrls];
+    const seen = /* @__PURE__ */ new Set();
+    const allowed = [];
+    for (const address of addresses) {
+      const normalised = normaliseAddress(address);
+      if (!normalised || seen.has(normalised)) continue;
+      if (portOf(normalised) === null) continue;
+      seen.add(normalised);
+      allowed.push(normalised);
+    }
+    return allowed;
+  }
+  /**
+   * Record where this attempt's daemon is going, relative to the address this app
+   * is configured for (design round 1, D1).
+   *
+   * WHY THE SNAPSHOT AND NOT ONLY THE LOG LINE. Measured on this change: serving on
+   * the fallback address was pixel-for-pixel invisible - the "attached on 8080" and
+   * "attached on 1111" frames of the whole surface hashed identically - and the
+   * operator's own question in that state had no in-product answer while they
+   * worked. What is recorded here is what the band renders.
+   *
+  /**
+   * The first address this attempt may actually start a daemon on, and what the
+   * gate found on every address that refused.
+   *
+   * TWO GATES PER ADDRESS, and each answers a different question. The record gate
+   * (`addressHoldsLiveRecord`) is "does this app's own registry say a process holds
+   * this address": its subject is a pid, and it needs no network. The occupancy
+   * probe is "would a child of mine be able to bind this address", asked of the
+   * address itself - and it exists precisely because the two came apart on the
+   * operator's machine, where discovery had no record to work with, the app spawned
+   * onto a port a daemon was already serving, and the child died on `[Errno 48]`
+   * every ~10 s (see the comment at the call site).
+   *
+   * ORDER MATTERS and it is the record gate first: a live record for the address
+   * means the address is held by something whose pid we can already name, and
+   * probing it would only add an answer to a question already answered.
+   */
+  async resolveSpawnTarget() {
+    const refusals = [];
+    for (const address of this.spawnAddresses()) {
+      const port = portOf(address);
+      if (port === null) continue;
+      if (addressHoldsLiveRecord(address)) {
+        const { unreadable, records } = addressHolders(address);
+        if (unreadable) {
+          refusals.push({
+            kind: "unreadable",
+            occupant: {
+              address,
+              pid: null,
+              pidSource: null,
+              version: "",
+              prefix: "",
+              installKind: "",
+              startedAtMs: null,
+              desktopReadStatus: null
+            },
+            detail: "this app's own records could not be read, so no address it may serve on could be called free"
+          });
+          continue;
+        }
+        const record = records[0] ?? null;
+        const observed = this.answeredButUnusable?.address === address ? this.answeredButUnusable.status : null;
+        refusals.push({
+          kind: "record",
+          occupant: {
+            address,
+            pid: record?.pid ?? null,
+            // The record is this app's own file about its own child, so the pid
+            // is this app's own answer rather than a socket's.
+            pidSource: record ? "answer" : null,
+            version: record?.version ?? "",
+            prefix: record?.prefix ?? "",
+            installKind: record?.install_kind ?? "",
+            startedAtMs: record ? record.started_at * 1e3 : null,
+            desktopReadStatus: observed
+          },
+          /*
+           * Not user-facing: the record arm is rendered by `HOLDER_CLASS.record`, which
+           * words the fact for a reader. This is the diagnostic beside it, for a log or
+           * a debugger, so it keeps the module's own nouns.
+           */
+          detail: `a serve record names ${address} with a pid that is not proven dead`
+        });
+        continue;
+      }
+      const occupancy = await this.configuredOriginOccupancy(address);
+      if (!occupancy) return { target: { address, port }, refusals };
+      refusals.push(occupancy);
+      if (occupancy.kind === "silent") return { target: null, refusals };
+    }
+    return { target: null, refusals };
+  }
+  /**
+   * Whether the last spawn attempt declined because an address this app may serve
+   * on is held by something it does not own, so the app has nowhere of its own to
+   * start a daemon.
+   *
+   * THIS IS THE ONE THING `index.ts` NEEDS FROM THIS CLASS, and it is the whole of
+   * the incident it answers: a `false` from `start()` used to mean "quit", and this
+   * class of false means the opposite - the app is fine, its address is taken, and
+   * waiting is what recovers it.
+   */
+  isStartBlockedByOccupiedAddress() {
+    return this.spawnRefusals !== null;
+  }
   /**
    * 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
+   * Three 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` -
+   * offline), 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.`;
+   * expired is not evidence of absence either way - and a registry this app could
+   * not read is `no-candidate`, which claims only that this app has no daemon of its
+   * own (review round 1, R1-3).
+   */
+  observeSpawnRefusal(refusals) {
+    const detail = describeSpawnRefusal(refusals);
+    const holder = refusals.find(
+      (occupancy) => occupancy.kind === "daemon" || occupancy.kind === "record"
+    );
+    const silent = refusals.find(
+      (occupancy) => occupancy.kind === "silent"
+    );
     this.daemonState.observe(
-      occupancy.kind === "silent" ? { kind: "unanswered", cause: occupancy.cause, detail } : { kind: "unattachable", detail }
+      holder ? { kind: "unattachable", detail } : silent ? { kind: "unanswered", cause: silent.cause, detail } : { kind: "no-candidate", detail }
     );
     logger.info(`Not spawning a daemon: ${detail}`, LogFileType.BACKEND);
     this.notifyStatus();
@@ -9466,7 +10018,7 @@ class BackendServiceManager {
       if (this.process && this.process.exitCode === null && this.process.signalCode == null)
         return;
       if (await this.discoverAndAttach()) return;
-      if (!this.managerMaySpawn || this.remoteConfigured || this.isExternalBackend || this.discoveryBlocksSpawn)
+      if (!this.managerMaySpawn || this.remoteConfigured || this.isExternalBackend)
         return;
       await this.start({ quiet: true });
     } finally {
@@ -30703,32 +31255,46 @@ electron.app.whenReady().then(async () => {
         startAttempts++;
       }
       if (!backendStarted) {
-        logger.error(
-          "Failed to start backend after installation, quitting app",
-          LogFileType.INSTALLER
-        );
-        reportBackendFailure(
-          "Failed to start the Local Operator backend service after installation. Please restart the application.",
-          LogFileType.INSTALLER
-        );
-        electron.app.quit();
-        return;
+        if (backendService.isStartBlockedByOccupiedAddress()) {
+          logger.error(
+            "Failed to start backend after installation: every address this app may serve on is held by something it does not own. Continuing without quitting; the status surface names the holder and the app keeps probing.",
+            LogFileType.INSTALLER
+          );
+        } else {
+          logger.error(
+            "Failed to start backend after installation, quitting app",
+            LogFileType.INSTALLER
+          );
+          reportBackendFailure(
+            "Failed to start the Local Operator backend service after installation. Please restart the application.",
+            LogFileType.INSTALLER
+          );
+          electron.app.quit();
+          return;
+        }
       }
     } else {
       const backendStarted = await backendService.start({
         reuseDiscovery: true
       });
       if (!backendStarted) {
-        logger.error(
-          "Failed to start backend with existing installation, quitting app",
-          LogFileType.BACKEND
-        );
-        reportBackendFailure(
-          "Failed to start the Local Operator backend service. Please restart the application.",
-          LogFileType.BACKEND
-        );
-        electron.app.quit();
-        return;
+        if (backendService.isStartBlockedByOccupiedAddress()) {
+          logger.error(
+            "Failed to start backend with existing installation: every address this app may serve on is held by something it does not own. Continuing without quitting; the status surface names the holder and the app keeps probing.",
+            LogFileType.BACKEND
+          );
+        } else {
+          logger.error(
+            "Failed to start backend with existing installation, quitting app",
+            LogFileType.BACKEND
+          );
+          reportBackendFailure(
+            "Failed to start the Local Operator backend service. Please restart the application.",
+            LogFileType.BACKEND
+          );
+          electron.app.quit();
+          return;
+        }
       }
     }
   }