cdx-manager 0.18.4 → 0.18.5

package/src/tray_install.py

@@ -251,32 +251,89 @@ def install(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, targe
     return state
 
 
-def align_companion(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target=None, env=None, probe=None):
+def align_companion(
+    base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target=None, env=None,
+    probe=None, spawn=None, stop=None, start=None,
+):
     """Bring an installed companion up to the CDX release that just landed.
 
     `item_081` AC2 asks for the two to stay aligned, and until now nothing did
     it: `cdx update` moved CDX and left the companion behind, so the user had to
     notice the drift and reinstall by hand.
 
+    A running companion is stopped first, replaced, and started again. Stopping
+    before touching anything on disk is not politeness: a running executable
+    cannot be replaced on Windows, and a directory holding one cannot reliably
+    be renamed either. It also means a companion that refuses to stop leaves the
+    files exactly as they were — the user keeps a working tray on the old
+    version, which is a far better outcome than a half-replaced one.
+
     Returns a dict describing what happened, and never raises. The CDX update
     has already succeeded by the time this runs — failing it because a companion
     could not be replaced would undo a good outcome for a worse reason. Every
     refusal is reported instead.
     """
+    from .tray_restart import start_companion, stop_running_companion
+
     state = read_state(base_dir)
     if not state:
         return {"aligned": False, "reason": "no companion is installed"}
     if state.get("cdx_version") == version:
         return {"aligned": False, "reason": "already aligned"}
+
+    halted = (stop or stop_running_companion)(env=env)
+    if halted.get("was_running") and not halted.get("stopped"):
+        return {
+            "aligned": False,
+            "reason": halted.get("reason", "the running tray could not be stopped"),
+            "previous": state.get("cdx_version"),
+        }
+
     try:
-        update(base_dir, version, download=download, ledger_path=ledger_path, target=target, probe=probe)
+        result = update(
+            base_dir, version,
+            download=download, ledger_path=ledger_path, target=target, probe=probe,
+        )
     except TrayInstallError as error:
-        return {
+        outcome = {
             "aligned": False,
             "reason": str(error),
             "previous": state.get("cdx_version"),
         }
-    return {"aligned": True, "previous": state.get("cdx_version"), "version": version}
+        # Nothing was replaced, so the companion we stopped is the one to bring
+        # back. Leaving the user with no tray because an update failed would be
+        # a worse outcome than the failure itself.
+        if halted.get("was_running"):
+            outcome["restarted"] = (start or start_companion)(
+                state["executable"], spawn=spawn, env=env,
+            ).get("started", False)
+        return outcome
+
+    aligned = {"aligned": True, "previous": state.get("cdx_version"), "version": version}
+    if not halted.get("was_running"):
+        # Files updated, and no tray to bring back. Starting one the user had
+        # not started themselves would be deciding for them.
+        aligned["restarted"] = False
+        aligned["restart_reason"] = "no tray was running"
+        return aligned
+
+    started = (start or start_companion)(result["state"]["executable"], spawn=spawn, env=env)
+    if started.get("started"):
+        aligned["restarted"] = True
+        return aligned
+
+    # The replacement passed its probe and still did not come up here. Put back
+    # the one that was proven to work, and start that — a rollback that leaves
+    # no running tray has only done half the job.
+    aligned["restarted"] = False
+    aligned["restart_reason"] = started.get("reason", "the replacement did not start")
+    aligned["rolled_back"] = restore_previous(base_dir, result.get("previous_state"))
+    if aligned["rolled_back"]:
+        aligned["aligned"] = False
+        aligned["restarted"] = (start or start_companion)(
+            state["executable"], spawn=spawn, env=env,
+        ).get("started", False)
+    return aligned
 
 
 def _extract(archive, destination):
@@ -385,22 +442,58 @@ def update(base_dir, version, download=None, ledger_path=CHECKSUM_LEDGER, target
         )
 
     live = os.path.join(state_dir(base_dir), "companion")
-    retired = os.path.join(state_dir(base_dir), "companion.previous")
+    retired = previous_dir(base_dir)
     shutil.rmtree(retired, ignore_errors=True)
     if os.path.isdir(live):
         os.rename(live, retired)
     os.rename(staged, live)
-    # Only now is the previous one retired.
-    shutil.rmtree(retired, ignore_errors=True)
+    # The retired copy stays. It used to be deleted here, which left nothing to
+    # go back to the moment the replacement turned out not to start — and that
+    # is precisely when it is needed. The next update clears it, so at most one
+    # extra copy is ever on disk.
 
     state = {
         **fresh,
         "executable": fresh["executable"].replace(staged, live, 1),
         "paths": [live],
     }
+    _record_state(base_dir, state)
+    return {"state": state, "replaced": previous.get("cdx_version"), "previous_state": previous}
+
+
+def previous_dir(base_dir):
+    """The last working companion, kept until the next update replaces it."""
+    return os.path.join(state_dir(base_dir), "companion.previous")
+
+
+def _record_state(base_dir, state):
     with open(state_path(base_dir), "w", encoding="utf-8") as handle:
         json.dump(state, handle, indent=2)
-    return {"state": state, "replaced": previous.get("cdx_version")}
+
+
+def restore_previous(base_dir, previous_state):
+    """Put back the companion that was proven to work.
+
+    Only called when the replacement failed to start, and it has to be able to
+    fail quietly itself: a rollback that raises would turn a bad update into an
+    unusable install, which is the one outcome worse than not updating.
+    """
+    live = os.path.join(state_dir(base_dir), "companion")
+    retired = previous_dir(base_dir)
+    if not os.path.isdir(retired):
+        return False
+    try:
+        broken = os.path.join(state_dir(base_dir), "companion.rejected")
+        shutil.rmtree(broken, ignore_errors=True)
+        if os.path.isdir(live):
+            os.rename(live, broken)
+        os.rename(retired, live)
+        shutil.rmtree(broken, ignore_errors=True)
+        if previous_state:
+            _record_state(base_dir, previous_state)
+        return True
+    except OSError:
+        return False
 
 
 def _probe(executable):

package/src/tray_logics.py

@@ -0,0 +1,141 @@
+"""The bundled Logics card: what is blocked, what is next, and nothing else.
+
+Built from `logics-manager status --format json` and from nothing else. Not for
+lack of richer sources — the repository is right there — but because a tray card
+that read documents would be a second implementation of Logics' own view, drifting
+from it at its own pace. One command, one contract, and when it changes the card
+breaks loudly in one place instead of quietly in several.
+
+Two rows at most, and the choice of which two is the whole design: the first
+blocked document, because it is what stops work, and the highest-priority active
+task, because it is what to do instead. A tray menu that listed everything would
+be a worse `logics-manager status`, run more often.
+"""
+import json
+import subprocess
+import time
+
+from .logics_view import resolve_logics_manager
+from .tray_plugins import ADAPTER_TIMEOUT_SECONDS, CARD_TTL_SECONDS
+
+_PRIORITY_ORDER = {"high": 0, "medium": 1, "low": 2}
+
+
+def logics_card(env=None, now=None, cache=None, runner=None, executable=None):
+    """One card, or None when there is nothing truthful to show.
+
+    None covers every unhappy case on purpose — not installed, not a Logics
+    repository, a command that failed or timed out, output that is not the JSON
+    we expect. A card saying "Logics is unhappy" would be noise in a menu the
+    user opened to look at quota.
+    """
+    now = time.time() if now is None else now
+    cached = _from_cache(cache, now)
+    if cached is not None:
+        return cached
+    status = _status(env=env, runner=runner, executable=executable)
+    card = _card_from_status(status)
+    _to_cache(cache, now, card)
+    return card
+
+
+def _from_cache(cache, now):
+    """A card is reused for its TTL, so a tray polling every 30 seconds does not
+    make Logics pay that rate. A manual refresh passes no cache and so bypasses
+    this entirely, which is what makes the refresh action mean something."""
+    if not isinstance(cache, dict):
+        return None
+    stamped = cache.get("logics")
+    if not isinstance(stamped, dict):
+        return None
+    if now - stamped.get("at", 0) > CARD_TTL_SECONDS:
+        return None
+    return stamped.get("card")
+
+
+def _to_cache(cache, now, card):
+    if isinstance(cache, dict):
+        cache["logics"] = {"at": now, "card": card}
+
+
+def _status(env=None, runner=None, executable=None):
+    """`logics-manager status --format json`, or None however it failed.
+
+    Resolved through CDX's own lookup rather than a path the tray knows: on a
+    Windows host serving CDX from WSL, the tray is not where `logics-manager`
+    lives, and the only process that can find it is this one.
+    """
+    executable = executable or resolve_logics_manager(env or {})
+    if not executable:
+        return None
+    try:
+        completed = (runner or subprocess.run)(
+            [executable, "status", "--format", "json"],
+            capture_output=True,
+            text=True,
+            timeout=ADAPTER_TIMEOUT_SECONDS,
+            check=False,
+        )
+    except (OSError, subprocess.SubprocessError):
+        return None
+    if getattr(completed, "returncode", 1) != 0:
+        return None
+    try:
+        payload = json.loads(completed.stdout)
+    except (TypeError, ValueError):
+        return None
+    return payload if isinstance(payload, dict) else None
+
+
+def _card_from_status(status):
+    if not isinstance(status, dict):
+        return None
+    blocked = [doc for doc in (status.get("blocked_docs") or []) if isinstance(doc, dict)]
+    active = [task for task in (status.get("active_tasks") or []) if isinstance(task, dict)]
+    if not blocked and not active:
+        # Nothing blocked and nothing in flight is not a state worth a row. The
+        # summary still says so, because "0 blocked" is the good news a user
+        # opening the menu wants to confirm.
+        return {
+            "title": "Logics",
+            "summary": "Nothing blocked, nothing in progress",
+            "rows": [],
+            "actions": ["logics.open", "logics.refresh"],
+        }
+    rows = []
+    if blocked:
+        rows.append(_row(blocked[0], "blocked"))
+    if active:
+        rows.append(_row(_most_urgent(active), "next"))
+    return {
+        "title": "Logics",
+        "summary": f"{len(blocked)} blocked · {len(active)} in progress",
+        "rows": [row for row in rows if row],
+        "actions": ["logics.open", "logics.refresh"],
+    }
+
+
+def _most_urgent(tasks):
+    """High before medium before low, and least finished first inside a priority.
+
+    Progress breaks the tie because a task at 90% needs a push and one at 0%
+    needs a decision, and the tray has room to point at one of them.
+    """
+    def rank(task):
+        priority = str(task.get("priority") or "").strip().lower()
+        return (_PRIORITY_ORDER.get(priority, len(_PRIORITY_ORDER)), _progress(task))
+
+    return sorted(tasks, key=rank)[0]
+
+
+def _progress(task):
+    value = task.get("progress")
+    return value if isinstance(value, (int, float)) else 0
+
+
+def _row(doc, kind):
+    ref = doc.get("ref")
+    title = doc.get("title") or ref
+    if not isinstance(ref, str) or not ref or not isinstance(title, str):
+        return None
+    return {"label": f"{kind}: {title}", "action": f"logics.focus:{ref}"}

package/src/tray_plugin_actions.py

@@ -0,0 +1,62 @@
+"""What a card action is allowed to do.
+
+The tray sends back an action id, never a command, and this is the only place
+that turns one into behaviour. Everything an integration can cause the machine
+to do is written here, in full, as a fixed vocabulary: refresh a card, open the
+Logics viewer, or open it focused on one document.
+
+The consequence worth stating: an adapter cannot extend this by producing a
+different id. An id CDX does not recognise is refused, and refusal is the
+default branch rather than the exception — so an integration gaining a new
+capability is a change to this file, reviewed like any other.
+"""
+from .errors import CdxError
+
+ACTION_UNKNOWN = "tray_plugin_action_unknown"
+
+
+def perform_action(action, ctx):
+    """Run one action id. Never raises for a bad id: it reports."""
+    if not isinstance(action, str) or "." not in action:
+        return _unknown(action)
+    plugin, rest = action.split(".", 1)
+    verb, _, reference = rest.partition(":")
+    if plugin != "logics":
+        return _unknown(action)
+    if verb == "refresh":
+        # The card is rebuilt by the next `cdx tray status --refresh`, which the
+        # tray issues itself. Nothing to do here beyond saying so, and saying so
+        # is what keeps the action id meaningful rather than silently ignored.
+        return {"ok": True, "code": None, "message": "The Logics card refreshes on the next tray refresh."}
+    if verb == "open":
+        return _open_viewer(ctx, None)
+    if verb == "focus" and reference:
+        return _open_viewer(ctx, reference)
+    return _unknown(action)
+
+
+def _open_viewer(ctx, reference):
+    from .logics_view import missing_logics_manager_failure, resolve_logics_manager, run_logics_viewer
+
+    executable = resolve_logics_manager(ctx.get("env") or {})
+    if not executable:
+        failure = missing_logics_manager_failure()
+        return {"ok": False, "code": failure["code"], "message": failure["message"]}
+    extra = ["--focus", reference] if reference else []
+    try:
+        run_logics_viewer(
+            executable, ctx.get("cwd"), env=ctx.get("env"),
+            extra_args=extra, runner=ctx.get("spawn_detached_runner"),
+        )
+    except (OSError, CdxError) as error:
+        return {"ok": False, "code": "logics_viewer_failed", "message": str(error)}
+    where = f" focused on {reference}" if reference else ""
+    return {"ok": True, "code": None, "message": f"Opened the Logics viewer{where}."}
+
+
+def _unknown(action):
+    return {
+        "ok": False,
+        "code": ACTION_UNKNOWN,
+        "message": f"CDX does not know the tray action {action!r}.",
+    }

package/src/tray_plugins.py

@@ -0,0 +1,163 @@
+"""Cards the tray shows for tools other than CDX itself.
+
+The shape of this is a deliberate refusal. A plugin system would mean discovery,
+trust, packaging, versioning and a lifecycle — and there is exactly one
+integration asking for it, which is not evidence that any of that is needed. So
+there is no marketplace, no installation from a URL, no plugin-defined command,
+and nothing runs inside the tray process. What exists is narrower and testable:
+
+  - **CDX owns the registry.** Adapters are functions in this repository, named
+    here. Nothing is discovered at runtime, so nothing unknown can run.
+  - **Adapters produce data, never behaviour.** A card is a summary, at most two
+    rows, and action ids drawn from a fixed vocabulary. An adapter cannot ask
+    the tray to run a command, because it cannot express one.
+  - **Failure is silence.** A slow, broken, absent or malformed adapter costs
+    its own card and nothing else. The session rows that are the reason the tray
+    exists are never at risk from an integration nobody depends on.
+  - **The tray executes nothing.** Cards ride the snapshot CDX already builds,
+    and every action goes back through CDX. `adr_005` put the transport there;
+    an integration is not a reason to open a second one.
+"""
+import json
+import os
+import re
+
+CARD_SCHEMA_MAJOR = 1
+# How long a card stays usable before CDX asks its adapter again. The tray polls
+# every 30 to 60 seconds and must not make an integration pay that rate, so a
+# card outlives a poll and a manual refresh bypasses it.
+CARD_TTL_SECONDS = 60
+# What an adapter is allowed to spend. It runs inside `cdx tray status`, which a
+# user is waiting on, so this is small on purpose.
+ADAPTER_TIMEOUT_SECONDS = 5
+
+_MAX_ROWS = 2
+_MAX_TEXT = 80
+# Action ids are `<plugin>.<verb>` or `<plugin>.<verb>:<ref>`, and the reference
+# is restricted to what a Logics ref can contain. This is the whole reason an
+# action cannot become a command: there is no character in here that a shell
+# would treat as one.
+_ACTION_PATTERN = re.compile(r"^[a-z][a-z0-9_]{0,15}\.[a-z][a-z0-9_]{0,15}(:[A-Za-z0-9_.-]{1,120})?$")
+
+STATE_VERSION = 1
+
+
+def state_path(base_dir):
+    return os.path.join(base_dir, "tray", "plugins.json")
+
+
+def enabled_plugins(base_dir):
+    """The plugins the user turned on. Nothing is on by default.
+
+    An unreadable or unknown-version state file reads as nothing enabled: an
+    integration is opt-in, and inheriting one from a file we cannot parse is
+    the opposite of opt-in.
+    """
+    try:
+        with open(state_path(base_dir), encoding="utf-8") as handle:
+            state = json.load(handle)
+    except (OSError, ValueError):
+        return []
+    if not isinstance(state, dict) or state.get("version") != STATE_VERSION:
+        return []
+    enabled = state.get("enabled")
+    return [name for name in enabled if name in ADAPTERS] if isinstance(enabled, list) else []
+
+
+def set_plugin_enabled(base_dir, name, enabled):
+    """Turn one plugin on or off, and report what is on afterwards."""
+    if name not in ADAPTERS:
+        raise KeyError(name)
+    current = set(enabled_plugins(base_dir))
+    current.add(name) if enabled else current.discard(name)
+    path = state_path(base_dir)
+    os.makedirs(os.path.dirname(path), exist_ok=True)
+    temp = f"{path}.{os.getpid()}.tmp"
+    with open(temp, "w", encoding="utf-8") as handle:
+        json.dump({"version": STATE_VERSION, "enabled": sorted(current)}, handle, indent=2)
+    os.replace(temp, path)
+    return sorted(current)
+
+
+def _text(value, limit=_MAX_TEXT):
+    """Printable, single-line and bounded. A card is a menu row, not a document."""
+    if not isinstance(value, str):
+        return ""
+    value = " ".join("".join(c if c.isprintable() else " " for c in value).split())
+    return value[: limit - 1] + "…" if len(value) > limit else value
+
+
+def bounded_card(raw, plugin):
+    """One adapter's output, or None if it cannot be trusted as a card.
+
+    Everything is checked rather than assumed, including from an adapter in this
+    repository: the check is what lets the tray render a card without knowing
+    which adapter produced it, and a first-party bug is not less of a bug.
+    """
+    if not isinstance(raw, dict):
+        return None
+    title = _text(raw.get("title"))
+    summary = _text(raw.get("summary"))
+    if not title or not summary:
+        return None
+    rows = []
+    for row in (raw.get("rows") or [])[:_MAX_ROWS]:
+        if not isinstance(row, dict):
+            continue
+        label = _text(row.get("label"))
+        action = row.get("action")
+        if not label or not _valid_action(action, plugin):
+            continue
+        rows.append({"label": label, "action": action})
+    actions = [a for a in (raw.get("actions") or []) if _valid_action(a, plugin)]
+    return {
+        "plugin": plugin,
+        "schema": CARD_SCHEMA_MAJOR,
+        "title": title,
+        "summary": summary,
+        "rows": rows,
+        "actions": actions[:_MAX_ROWS],
+    }
+
+
+def _valid_action(action, plugin):
+    return (
+        isinstance(action, str)
+        and bool(_ACTION_PATTERN.match(action))
+        and action.split(".", 1)[0] == plugin
+    )
+
+
+def collect_cards(base_dir, env=None, now=None, adapters=None, cache=None):
+    """Every enabled plugin's card, bounded, with failures dropped.
+
+    Never raises. An adapter that throws, hangs past its timeout, returns
+    nonsense or is simply not installed contributes nothing, and the caller
+    cannot tell the difference — which is the point: the tray's own data must
+    not depend on how an integration is having its day.
+    """
+    registry = ADAPTERS if adapters is None else adapters
+    cards = []
+    for name in enabled_plugins(base_dir):
+        adapter = registry.get(name)
+        if not adapter:
+            continue
+        try:
+            raw = adapter(env=env, now=now, cache=cache)
+        except Exception:  # noqa: BLE001 - an integration cannot break the tray
+            continue
+        card = bounded_card(raw, name)
+        if card:
+            cards.append(card)
+    return cards
+
+
+def _logics_adapter(env=None, now=None, cache=None):
+    from .tray_logics import logics_card
+
+    return logics_card(env=env, now=now, cache=cache)
+
+
+# The registry. A name here is the only way an adapter can run, and adding one
+# is a change to this repository — which is the trust model, stated as code.
+ADAPTERS = {"logics": _logics_adapter}

package/src/tray_restart.py

@@ -0,0 +1,152 @@
+"""Replacing a companion that is currently running.
+
+`cdx update` used to leave the running tray on its old binary and tell the user
+to quit it from its menu. That is a correct thing to say and a poor thing to
+have to do: the whole point of the companion is that nobody thinks about it.
+
+The order here is what makes it safe, and it is the reverse of what looks
+natural. The running companion is asked to stop *before* anything on disk moves,
+so the replacement never has to fight a live process for its own files — on
+Windows a running executable cannot be replaced at all, and a directory holding
+one cannot reliably be renamed either. Stop, replace, start, and if the start
+fails, put back the one that was proven to work and start that instead.
+
+Nothing here kills anything. A companion that does not stop within the bounded
+wait is left alone and reported, because a tray the user is reading a menu from
+is not a process to terminate over a version number.
+"""
+import os
+import time
+
+from .tray_instance import _is_alive, companion_instance, lock_path
+
+# How long to wait for a companion to notice the request and exit.
+#
+# It polls several times a second, so this is generous by two orders of
+# magnitude — deliberately. On Windows the menu is modal: while the user has it
+# open, the message pump is stopped and the companion notices nothing at all.
+# Ten seconds covers reading a menu and closing it; beyond that, the honest
+# answer is to leave it running and say so.
+STOP_TIMEOUT_SECONDS = 10.0
+_POLL_SECONDS = 0.1
+
+
+def stop_path(env=None):
+    """Where a stop request is written. Beside the lock, by the same rule."""
+    return os.path.join(os.path.dirname(lock_path(env=env)), "companion.stop")
+
+
+def request_stop(env=None):
+    """Ask the running companion to exit. False when it could not be asked."""
+    path = stop_path(env=env)
+    try:
+        os.makedirs(os.path.dirname(path), exist_ok=True)
+        with open(path, "w", encoding="utf-8") as handle:
+            handle.write("stop")
+        return True
+    except OSError:
+        return False
+
+
+def clear_stop(env=None):
+    """Remove a stop request nobody consumed.
+
+    A companion that had already died leaves the request on disk, and the next
+    one to start would read it and quit immediately — a tray that refuses to
+    stay open, with nothing on screen explaining why.
+    """
+    try:
+        os.remove(stop_path(env=env))
+    except OSError:
+        pass
+
+
+def wait_for_exit(pid, timeout=STOP_TIMEOUT_SECONDS, sleep=None, alive=None):
+    """Wait for one process to go, up to `timeout`. True if it did."""
+    sleep = time.sleep if sleep is None else sleep
+    alive = _is_alive if alive is None else alive
+    deadline = time.monotonic() + timeout
+    while True:
+        if not alive(pid):
+            return True
+        if time.monotonic() >= deadline:
+            return False
+        sleep(_POLL_SECONDS)
+
+
+def stop_running_companion(env=None, timeout=STOP_TIMEOUT_SECONDS, sleep=None, alive=None):
+    """Stop the companion if one is running, and say what happened.
+
+    `stopped` is True only when a live companion was asked and observed to go.
+    Everything else is a reason, and every reason is one the caller can act on
+    without guessing: nothing was running, the request could not be written, or
+    it did not exit in time.
+    """
+    instance = companion_instance(env=env)
+    pid = instance.get("pid")
+    if not pid:
+        # A stale lock is not a running tray, but it is worth clearing the stop
+        # request that may be sitting beside it from an earlier attempt.
+        clear_stop(env=env)
+        return {"stopped": False, "was_running": False, "reason": "no tray companion is running"}
+    if not request_stop(env=env):
+        return {
+            "stopped": False,
+            "was_running": True,
+            "pid": pid,
+            "reason": "the stop request could not be written",
+        }
+    if not wait_for_exit(pid, timeout=timeout, sleep=sleep, alive=alive):
+        # It is still running and it still owns its binary. Withdrawing the
+        # request matters: leaving it would stop the companion later, at a
+        # moment nobody connected to an update.
+        clear_stop(env=env)
+        return {
+            "stopped": False,
+            "was_running": True,
+            "pid": pid,
+            "reason": (
+                f"the running tray did not stop within {timeout:g}s. "
+                "An open tray menu blocks it on Windows; close the menu and run: cdx tray launch"
+            ),
+        }
+    clear_stop(env=env)
+    return {"stopped": True, "was_running": True, "pid": pid}
+
+
+def start_companion(executable, spawn=None, verify=None, env=None, settle=None):
+    """Start a companion and confirm it is actually running.
+
+    Spawning is not evidence. A binary that exits immediately — a missing
+    library, a quarantined bundle, a companion that reads a stale stop request —
+    leaves a successful spawn and no tray, which is exactly the "reported
+    success before the replacement is usable" this must not do.
+    """
+    from .tray_install import launch_command
+
+    spawn = spawn or _spawn_detached
+    settle = time.sleep if settle is None else settle
+    try:
+        spawn(launch_command(executable))
+    except Exception as error:  # noqa: BLE001 - any launch failure is a reason
+        return {"started": False, "reason": str(error)}
+    # It has to register its lock before it counts as running, and it does that
+    # a moment after exec.
+    for _ in range(20):
+        settle(_POLL_SECONDS)
+        instance = (verify or companion_instance)(env=env)
+        if instance.get("pid"):
+            return {"started": True, "pid": instance["pid"]}
+    return {"started": False, "reason": "it was launched but never registered as running"}
+
+
+def _spawn_detached(command):
+    import subprocess
+
+    subprocess.Popen(  # noqa: S603  (path comes from our own install state)
+        command,
+        stdout=subprocess.DEVNULL,
+        stderr=subprocess.DEVNULL,
+        stdin=subprocess.DEVNULL,
+        start_new_session=True,
+    )