@simon-says-build/harbormaster 0.6.0

package/harbormaster

@@ -0,0 +1,1024 @@
+#!/usr/bin/env python3
+"""harbormaster — caller-owned port leases: Firebase emulator sandboxes, Metro
+ports, private simulators. (Formerly firebase-ports.)
+
+A localhost daemon hands each CALLER its own emulator sandbox (a pool port block +
+fresh data) and reclaims it when the caller's process exits. No registry, no shared
+per-project instances — two callers that both want "an impulse emulator" get two
+independent suites, so they never collide on ports or data.
+
+  acquire [--cwd DIR] [--owner PID] [--only a,b] [--ttl N] [--metro] [--sim] [--json|--env]
+        Boot a private sandbox for the project in DIR (default: nearest firebase.json
+        above $PWD). Owned by --owner (default: the calling process's parent), reaped
+        when that process exits. Prints the ports (use --env to eval into your shell).
+        --metro also reserves a Metro/Expo port (METRO_PORT). --sim also creates+boots
+        a private iOS simulator (DETOX_UDID/DETOX_SIM_NAME) and implies --metro; the
+        sim is deleted when the lease is reaped. Tune with --sim-device / --sim-runtime
+        (or FBPORTS_SIM_DEVICE / FBPORTS_SIM_RUNTIME). This is the e2e dev-env: one
+        lease = emulators + metro port + simulator, all torn down when the owner exits.
+  up ...                 Alias for acquire (interactive dev; owner = your shell).
+  down [--cwd DIR]       Release this shell's sandbox for DIR (else it's reaped on exit).
+  release <leaseId>      Release a specific lease.
+  status                 Everything the daemon has out.
+  allocate [--owner PID|auto] [--ttl N] [--metro] [--sim] [--spawn CMD] [--cwd DIR]
+           [--detach] [--json|--env]
+        Reserve a block WITHOUT booting — for a caller that boots its own suite (the
+        agent-qa run driver). Also owner-reaped. --metro/--sim work as on acquire
+        (metro port in the block; private simulator, deleted on reap) for e2e Metro
+        sessions whose emulators are per-RUN acquires. NOTE: reserved leases also
+        reap on TTL even with a live owner — pass a long --ttl for long-lived
+        Metro sessions (owner death still reaps promptly).
+        --spawn CMD makes the DAEMON run CMD (via sh -c, in --cwd if given) as the
+        lease's process: daemon-owned, so it survives the calling shell/agent —
+        liveness is the spawned pid (+ TTL backstop), teardown kills its process
+        group, stdout goes to the lease log. CMD sees FBPORTS_BLOCK_BASE,
+        FBPORTS_LEASE_ID, and METRO_PORT / DETOX_UDID / DETOX_SIM_NAME when leased.
+        With --spawn (or --detach) the lease defaults to NO owner pid, since the
+        calling shell exits immediately and would reap it. Pass --owner auto to
+        record the nearest ancestor that DOES outlive the call (under an agent,
+        the agent process) so the lease dies with that session; or --owner PID
+        to name one yourself. Otherwise release it with
+        `harbormaster release <leaseId>` or let the TTL reap it.
+        Any lease is also reaped once its --cwd stops existing — a deleted
+        worktree can never need its Metro again.
+  exec [--cwd DIR] [--only a,b] '<script>'
+        Run `firebase emulators:exec` on a daemon-allocated block: boots the suite on
+        free ports, runs the script (which gets FIRESTORE_EMULATOR_HOST etc.), tears
+        down. Use this instead of a bare `firebase emulators:exec` so concurrent runs
+        don't collide.
+  verify <leaseId>       Exit 0 iff the lease is FULLY alive: known to the daemon,
+        its process running, its simulator still present, and (for booted suites)
+        its ports open. The reuse gate for long-lived sessions:
+            harbormaster verify "$FBPORTS_LEASE_ID" || <re-lease>
+  serve                  Run the daemon (auto-starts on first command).
+
+NOTE: firebase.json ports are optional — the daemon injects (and overrides) a
+per-lease pool block, so concurrent suites never collide. Ledger:
+~/.local/state/firebase-ports/ledger.json. See DESIGN.md.
+"""
+
+import http.client
+import http.server
+import json
+import os
+import signal
+import socket
+import subprocess
+import sys
+import threading
+import time
+import uuid
+from datetime import datetime, timezone
+from pathlib import Path
+
+VERSION = "0.6.0"
+
+# Overridable for tests / parallel installs; default is the shared user daemon.
+# The dir keeps the old "firebase-ports" name: pre-rename binaries still installed
+# in other projects must find the same ledger and daemon.
+STATE_DIR = Path(os.environ.get("FBPORTS_STATE_DIR",
+                                str(Path.home() / ".local" / "state" / "firebase-ports")))
+LEDGER = STATE_DIR / "ledger.json"
+BROKER_HOST, BROKER_PORT = "127.0.0.1", int(os.environ.get("FBPORTS_PORT", "4999"))
+POOL_BASE, BLOCK, POOL_BLOCKS = 11000, 20, 200          # blocks of 20 ports, 11000-14999
+BLOCK_OFFSETS = {"auth": 0, "firestore": 1, "functions": 2, "storage": 3, "ui": 4,
+                 "hub": 5, "logging": 6, "pubsub": 7, "eventarc": 8, "database": 9,
+                 # Firestore's UI websocket is a SECOND port it needs (CLI default 9150).
+                 # It must be pool-allocated too — otherwise every concurrent firestore
+                 # emulator defaults to 9150 and they fight over it, even though their
+                 # data ports are isolated. (Block is 20 wide, so +10 is in range.)
+                 "firestore_websocket": 10}
+METRO_OFFSET = 11        # Metro/Expo dev-server port in the block (offsets 0-10 are emulators)
+DEFAULT_SIM_DEVICE = os.environ.get("FBPORTS_SIM_DEVICE", "iPhone 16")
+DEFAULT_SIM_RUNTIME = os.environ.get("FBPORTS_SIM_RUNTIME",
+                                     "com.apple.CoreSimulator.SimRuntime.iOS-18-2")
+DEFAULT_TTL = 3600
+RECLAIM_GRACE = int(os.environ.get("FBPORTS_RECLAIM_GRACE", "45"))
+REAP_INTERVAL = int(os.environ.get("FBPORTS_REAP_INTERVAL", "10"))
+# How often the reaper cross-checks leased simulators against simctl. A lease
+# whose sim was deleted externally is broken for its caller even if its process
+# is healthy — sweep it whole rather than leave a half-alive session.
+SIM_CHECK_INTERVAL = int(os.environ.get("FBPORTS_SIM_CHECK_INTERVAL", "60"))
+BOOT_BACKSTOP = 600          # only for a genuinely wedged boot; readiness is liveness-driven
+
+
+def _now():
+    return datetime.now(timezone.utc).isoformat(timespec="seconds")
+
+
+def _port_open(port, host="127.0.0.1"):
+    with socket.socket(socket.AF_INET, socket.SOCK_STREAM) as s:
+        s.settimeout(0.5)
+        return s.connect_ex((host, int(port))) == 0
+
+
+def _all_open(ports):
+    return bool(ports) and all(_port_open(p) for p in ports.values())
+
+
+def _pid_alive(pid):
+    try:
+        os.kill(int(pid), 0)
+        return True
+    except PermissionError:
+        return True                       # EPERM: exists, just not ours to signal
+    except (OSError, ProcessLookupError, ValueError, TypeError):
+        return False
+
+
+def _child_alive(pid):
+    """Liveness for a process the DAEMON spawned. A zombie child passes kill-0
+    until someone waits on it, so reap it first (WNOHANG); if it exited, it's
+    dead. After a daemon restart the process is no longer our child
+    (ECHILD) — launchd reaps it instead, so plain kill-0 is then correct."""
+    try:
+        done, _ = os.waitpid(int(pid), os.WNOHANG)
+        if done == int(pid):
+            return False
+    except (ChildProcessError, OSError, ValueError, TypeError):
+        pass
+    return _pid_alive(pid)
+
+
+def _proc_start(pid):
+    """A process's start time — pairs with the PID to survive PID reuse. '' if gone."""
+    try:
+        r = subprocess.run(["ps", "-o", "lstart=", "-p", str(int(pid))],
+                           capture_output=True, text=True, timeout=2)
+        return r.stdout.strip()
+    except (subprocess.SubprocessError, ValueError, TypeError):
+        return ""
+
+
+# Ancestors that exit with (or just before) the script asking for a lease, so
+# owning a lease by one of them would reap it seconds later. `--owner auto`
+# walks past these looking for something that outlives the call.
+_TRANSIENT_COMMS = {"sh", "bash", "zsh", "dash", "fish", "ksh", "login", "env",
+                    "node", "npm", "npx", "yarn", "pnpm", "bun", "make", "xargs"}
+# Walking past *these* would hand ownership to something that outlives the work
+# by days (your editor, your login session), which reaps nothing in practice.
+# Better to record no owner and fall back to TTL + working-dir checks.
+_BOUNDARY_COMMS = {"launchd", "Code", "Code Helper", "Code Helper (Plugin)",
+                   "Code Helper (Renderer)", "Electron", "Terminal", "iTerm2",
+                   "WindowServer", "sshd", "init", "systemd"}
+
+
+def _proc_field(pid, fmt):
+    try:
+        r = subprocess.run(["ps", "-o", fmt, "-p", str(int(pid))],
+                           capture_output=True, text=True, timeout=2)
+        return r.stdout.strip()
+    except (subprocess.SubprocessError, ValueError, TypeError):
+        return ""
+
+
+def _durable_ancestor(pid, _max_hops=16):
+    """The nearest ancestor of `pid` that will outlive the calling script.
+
+    A daemon-spawned lease (`--spawn`) deliberately survives the shell that
+    asked for it, so that shell's pid is useless as an owner — it exits within
+    seconds and would take the lease with it. But "daemonised" only decides who
+    *reaps the child*; we can still record who is *interested*. Walking up past
+    the transient shell/node wrappers finds that process: under an agent it is
+    the agent itself, so its leases die with the session.
+
+    Returns None when the walk reaches a boundary (an editor, a login session)
+    rather than pretending a days-long process is a meaningful owner.
+    """
+    seen = pid
+    for _ in range(_max_hops):
+        ppid = _proc_field(seen, "ppid=")
+        if not ppid or not ppid.isdigit() or int(ppid) <= 1:
+            return None
+        seen = int(ppid)
+        comm = os.path.basename(_proc_field(seen, "comm="))
+        if not comm or comm in _BOUNDARY_COMMS:
+            return None
+        if comm not in _TRANSIENT_COMMS:
+            return seen
+    return None
+
+
+def _owner_alive(pid, start):
+    """A lease's owner is alive iff the same PID exists AND was started at the same time."""
+    if pid is None:
+        return True                       # no owner tracking → rely on TTL / liveness
+    if not _pid_alive(pid):
+        return False
+    if not start:
+        return True
+    observed = _proc_start(pid)
+    # `ps` can time out on a loaded machine (exactly when a lease is booting).
+    # An unreadable start time is NOT evidence of PID reuse — the pid exists
+    # (os.kill(0) just succeeded), so treat indeterminate as alive rather than
+    # reaping a healthy lease.
+    return not observed or observed == start
+
+
+def _tail(path, n=25):
+    try:
+        return "\n".join(Path(path).read_text().splitlines()[-n:])
+    except OSError:
+        return ""
+
+
+def _firebaserc_project(cwd):
+    try:
+        return json.loads((Path(cwd) / ".firebaserc").read_text()).get("projects", {}).get("default")
+    except (OSError, json.JSONDecodeError, AttributeError):
+        return None
+
+
+def _find_firebase_dir(start):
+    p = Path(start).resolve()
+    for d in [p, *p.parents]:
+        if (d / "firebase.json").exists():
+            return str(d)
+    return None
+
+
+def _block_ports(base):
+    return {svc: base + off for svc, off in BLOCK_OFFSETS.items()}
+
+
+def _service_ports(ports):
+    return {s: p for s, p in ports.items() if s not in ("ui", "hub", "logging")}
+
+
+def _write_injected_config(cwd, ports):
+    """Set ports on the emulators the portless firebase.json DECLARES (+ hub/logging).
+    Never adds emulators the project doesn't use. Returns the temp config basename."""
+    cfg = json.loads((Path(cwd) / "firebase.json").read_text())
+    emu = cfg.setdefault("emulators", {})
+    for svc in [k for k in emu if k != "singleProjectMode"]:
+        if svc in ports and isinstance(emu[svc], dict):
+            emu[svc]["port"] = ports[svc]
+            if svc == "ui":
+                emu[svc]["enabled"] = True
+            if svc == "firestore":
+                # Give firestore's UI websocket a private port too, else concurrent
+                # suites all default to 9150 and collide (isolated data port isn't enough).
+                emu[svc]["websocketPort"] = ports["firestore_websocket"]
+    for svc in ("hub", "logging"):
+        emu.setdefault(svc, {})["port"] = ports[svc]
+    emu["singleProjectMode"] = True
+    tmp = f".firebase.brokered-{ports['firestore']}.json"
+    (Path(cwd) / tmp).write_text(json.dumps(cfg, indent=2))
+    return tmp
+
+
+def _sim_create_boot(device, runtime, name):
+    """Create a fresh iOS simulator, boot it, and return its UDID. The device is
+    per-lease (unique name) so concurrent e2e runs never share one; reaped on
+    lease teardown. Boots on a PINNED runtime so we don't pay a second OS image."""
+    r = subprocess.run(["xcrun", "simctl", "create", name, device, runtime],
+                       capture_output=True, text=True, timeout=120)
+    if r.returncode != 0:
+        raise RuntimeError(f"simctl create failed ({device} / {runtime}): {r.stderr.strip()}")
+    udid = r.stdout.strip()
+    # boot is idempotent-ish (errors if already booted); bootstatus waits until ready.
+    subprocess.run(["xcrun", "simctl", "boot", udid], capture_output=True, text=True, timeout=120)
+    subprocess.run(["xcrun", "simctl", "bootstatus", udid, "-b"], capture_output=True, text=True, timeout=300)
+    return udid
+
+
+def _sim_udids():
+    """The set of simulator UDIDs simctl knows, or None when indeterminate.
+    simctl erroring/missing must never read as 'every sim is gone' — callers
+    treat None as 'no evidence', mirroring _owner_alive's philosophy."""
+    try:
+        r = subprocess.run(["xcrun", "simctl", "list", "devices", "-j"],
+                           capture_output=True, text=True, timeout=15)
+        if r.returncode != 0:
+            return None
+        devices = json.loads(r.stdout).get("devices", {})
+        return {d["udid"] for lst in devices.values() for d in lst if d.get("udid")}
+    except (subprocess.SubprocessError, OSError, json.JSONDecodeError,
+            AttributeError, TypeError):
+        return None
+
+
+def _sim_teardown(udid):
+    """Shut down + delete a leased simulator (best effort) so devices never leak."""
+    for args in (["shutdown", udid], ["delete", udid]):
+        try:
+            subprocess.run(["xcrun", "simctl", *args], capture_output=True, text=True, timeout=60)
+        except (subprocess.SubprocessError, OSError):
+            pass
+
+
+# ---- the daemon ----------------------------------------------------------
+
+class Broker:
+    def __init__(self):
+        self.lock = threading.RLock()
+        self.leases = {}                  # leaseId -> caller-owned lease
+        self._load()
+        self._reconcile()
+
+    def _load(self):
+        if LEDGER.exists():
+            try:
+                self.leases = json.loads(LEDGER.read_text()).get("leases", {})
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    def _save(self):
+        STATE_DIR.mkdir(parents=True, exist_ok=True)
+        LEDGER.write_text(json.dumps({"leases": self.leases}, indent=2))
+
+    def _reconcile(self):
+        for lid in list(self.leases):
+            reason = self._dead_reason(self.leases[lid], time.time())
+            if reason:
+                print(f"reaping {lid}: {reason}", flush=True)
+                self._cleanup(self.leases.pop(lid))
+        self._save()
+
+    def _dead(self, l, now):
+        return bool(self._dead_reason(l, now))
+
+    def _dead_reason(self, l, now):
+        if l.get("owner_pid") is not None and not _owner_alive(l["owner_pid"], l.get("owner_start")):
+            return f"owner pid {l['owner_pid']} gone"
+        # A lease for a directory that no longer exists can never be useful
+        # again: deleted worktrees were the main source of immortal Metro
+        # leases, since a daemon-spawned Metro has no owner to outlive and the
+        # TTL is measured in days. Only a *confirmed* absence counts — a parent
+        # that is itself missing means an unmounted volume or similar, which is
+        # not evidence the project is gone.
+        cwd = l.get("cwd")
+        if cwd and not os.path.isdir(cwd) and os.path.isdir(os.path.dirname(cwd)):
+            return f"working dir {cwd} no longer exists"
+        exp = l.get("expires")
+        if exp is not None and exp < now:
+            # TTL is a backstop for callers the daemon can't track (no owner)
+            # and for reserved blocks (documented: reserved leases reap on TTL
+            # even with a live owner). A BOOTED lease whose tracked owner is
+            # verifiably alive is not orphaned — let owner-death/liveness
+            # govern it instead of killing a healthy hour-old dev-env.
+            if l["kind"] == "reserved" or l.get("owner_pid") is None:
+                return "ttl expired"
+        if l["kind"] == "reserved":
+            # Daemon-spawned process (--spawn): its pid IS the lease's liveness —
+            # ports are irrelevant (Metro restarting/compiling must not reap it).
+            if l.get("pid"):
+                if not _child_alive(l["pid"]):
+                    return f"spawned pid {l['pid']} died"
+                return None
+            # Caller boots its own — liveness on the block.
+            base = l["block"]
+            if _port_open(base) or _port_open(base + 1):
+                l["seen_active"], l["down_since"] = True, None
+            elif l.get("seen_active"):
+                l["down_since"] = l.get("down_since") or now
+            if l.get("down_since") and now - l["down_since"] >= RECLAIM_GRACE:
+                return "reserved block down past grace"
+            return None
+        # Booted suite: the process is the strong liveness signal — reap a dead
+        # process immediately. Ports are a weak signal (a single 0.5s connect can
+        # fail on a loaded machine while the suite is fine), so closed ports only
+        # reap after RECLAIM_GRACE of CONTINUOUS downtime, mirroring the
+        # reserved-lease path above.
+        if not _child_alive(l.get("pid")):
+            return f"suite pid {l.get('pid')} died"
+        if _all_open(l.get("check_ports") or _service_ports(l["ports"])):
+            l["down_since"] = None
+            return None
+        l["down_since"] = l.get("down_since") or now
+        if now - l["down_since"] >= RECLAIM_GRACE:
+            return "ports down past grace"
+        return None
+
+    def _free_block(self):
+        used = {l["block"] for l in self.leases.values() if l.get("block")}
+        for i in range(POOL_BLOCKS):
+            base = POOL_BASE + i * BLOCK
+            if base not in used and all(not _port_open(base + off) for off in range(BLOCK)):
+                return base
+        raise RuntimeError("emulator port pool exhausted")
+
+    def _boot(self, cwd, block, only, project_id, label):
+        all_ports = _block_ports(block)
+        tmp = _write_injected_config(cwd, all_ports)
+        # Readiness/liveness track ONLY the data services actually started (respect
+        # --only, else the project's declared emulators; skip ui/hub/logging) — else
+        # we'd wait forever for ports (functions, pubsub, …) that never open.
+        declared = [k for k in json.loads((Path(cwd) / "firebase.json").read_text()).get("emulators", {}) if k != "singleProjectMode"]
+        run_ports = {s: all_ports[s] for s in (only or declared) if s in all_ports}
+        check = {s: p for s, p in run_ports.items() if s not in ("ui", "hub", "logging")}
+        log = STATE_DIR / f"{label}.log"
+        cmd = ["firebase", "emulators:start", "--config", tmp]
+        if only:
+            cmd += ["--only", ",".join(only)]
+        if project_id:
+            cmd += ["--project", project_id]
+        with open(log, "w") as lf:
+            proc = subprocess.Popen(cmd, cwd=cwd, stdout=lf, stderr=subprocess.STDOUT, start_new_session=True)
+        # Liveness-driven: keep waiting while the process is alive (a slow JVM is still
+        # booting, not stuck); succeed when the ports open; fail if it exits; the
+        # backstop only guards a genuinely wedged boot.
+        backstop = time.time() + BOOT_BACKSTOP
+        while True:
+            if _all_open(check):
+                return proc.pid, tmp, str(log), run_ports, check
+            if proc.poll() is not None:
+                raise RuntimeError(f"emulators exited early; see {log}\n{_tail(log)}")
+            if time.time() > backstop:
+                try:
+                    os.killpg(os.getpgid(proc.pid), signal.SIGKILL)   # killpg → reap JVM children
+                except (OSError, ProcessLookupError):
+                    pass
+                raise RuntimeError(f"boot backstop ({BOOT_BACKSTOP}s) hit, process still alive; see {log}")
+            time.sleep(1)
+
+    def _cleanup(self, rec):
+        """Coordinated teardown — killpg the whole group so JVM children die too. Never pkill."""
+        pid = rec.get("pid")
+        # _child_alive, not _pid_alive: a daemon-spawned process that already
+        # exited lingers as our zombie child, which passes kill-0 — treating it
+        # as alive would stall this loop through a futile TERM+KILL cycle.
+        if _child_alive(pid):
+            for sig in (signal.SIGTERM, signal.SIGKILL):
+                try:
+                    os.killpg(os.getpgid(int(pid)), sig)
+                except (OSError, ProcessLookupError):
+                    break
+                for _ in range(50):
+                    if not _child_alive(pid):
+                        break
+                    time.sleep(0.1)
+                if not _child_alive(pid):
+                    break
+        tmp = rec.get("tmp_config")
+        if tmp and rec.get("cwd") and (Path(rec["cwd"]) / tmp).exists():
+            (Path(rec["cwd"]) / tmp).unlink()
+        if rec.get("sim_udid"):
+            _sim_teardown(rec["sim_udid"])
+
+    def acquire(self, cwd, owner_pid, owner_start=None, only=None, ttl=DEFAULT_TTL,
+                metro=False, sim=False, sim_device=None, sim_runtime=None):
+        with self.lock:
+            base = self._free_block()
+            lid = f"run:{uuid.uuid4().hex[:12]}"
+            project_id = _firebaserc_project(cwd)
+            pid, tmp, log, ports, check = self._boot(cwd, base, only, project_id, lid.replace(":", "-"))
+            # A leased simulator implies a metro port (the e2e dev-env wants both).
+            # The metro port lives in the lease's own 20-port block, so it's
+            # collision-free by construction and needs no health check.
+            if metro or sim:
+                ports["metro"] = base + METRO_OFFSET
+            sim_udid = sim_name = None
+            if sim:
+                sim_name = lid.replace(":", "-")
+                try:
+                    sim_udid = _sim_create_boot(sim_device or DEFAULT_SIM_DEVICE,
+                                                sim_runtime or DEFAULT_SIM_RUNTIME, sim_name)
+                except Exception:
+                    # Don't leak the emulators we just booted if the sim fails.
+                    self._cleanup({"pid": pid, "cwd": cwd, "tmp_config": tmp})
+                    raise
+            self.leases[lid] = {"leaseId": lid, "kind": "acquired", "cwd": cwd, "block": base,
+                                "ports": ports, "check_ports": check, "pid": pid,
+                                "owner_pid": owner_pid, "owner_start": owner_start,
+                                "tmp_config": tmp, "log": log, "project_id": project_id,
+                                "sim_udid": sim_udid, "sim_name": sim_name,
+                                "started": _now(), "expires": time.time() + ttl}
+            self._save()
+            resp = {"leaseId": lid, "ports": ports, "projectId": project_id}
+            if sim_udid:
+                resp["sim"] = {"udid": sim_udid, "name": sim_name}
+            return resp
+
+    def allocate(self, owner_pid, owner_start=None, ttl=DEFAULT_TTL, label=None,
+                 metro=False, sim=False, sim_device=None, sim_runtime=None,
+                 spawn=None, spawn_cwd=None):
+        with self.lock:
+            base = self._free_block()
+            lid = f"alloc:{uuid.uuid4().hex[:12]}"
+            ports = {"base": base}
+            # A reserved block can also carry the dev-env extras for callers that
+            # boot their own emulators (or none at all): a Metro port and/or a
+            # private simulator. Used by e2e Metro sessions whose emulator suites
+            # are per-RUN acquires (walk2gether) — the long-lived Metro process
+            # owns just the port + sim.
+            if metro or sim:
+                ports["metro"] = base + METRO_OFFSET
+            sim_udid = sim_name = None
+            if sim:
+                sim_name = lid.replace(":", "-")
+                sim_udid = _sim_create_boot(sim_device or DEFAULT_SIM_DEVICE,
+                                            sim_runtime or DEFAULT_SIM_RUNTIME, sim_name)
+            # --spawn: the DAEMON runs the lease's process (Metro, a dev server…),
+            # so it survives the calling shell/agent/session. Its pid is the
+            # lease's liveness; teardown killpgs it like a booted suite.
+            pid = None
+            log = None
+            if spawn:
+                log = str(STATE_DIR / f"{lid.replace(':', '-')}.log")
+                env = {**os.environ,
+                       "FBPORTS_BLOCK_BASE": str(base),
+                       "FBPORTS_LEASE_ID": lid}
+                if ports.get("metro"):
+                    env["METRO_PORT"] = str(ports["metro"])
+                if sim_udid:
+                    env["DETOX_UDID"] = sim_udid
+                    env["DETOX_SIM_NAME"] = sim_name
+                try:
+                    with open(log, "w") as lf:
+                        proc = subprocess.Popen(["/bin/sh", "-c", spawn],
+                                                cwd=spawn_cwd or None, env=env,
+                                                stdout=lf, stderr=subprocess.STDOUT,
+                                                start_new_session=True)
+                    pid = proc.pid
+                except OSError:
+                    # Don't leak the simulator we just created if the spawn fails.
+                    if sim_udid:
+                        _sim_teardown(sim_udid)
+                    raise
+            print(f"leased {lid} ({label or 'no label'}): base {base}"
+                  f"{f' sim {sim_name}' if sim_udid else ''}"
+                  f"{f' spawned pid {pid}' if pid else ''}", flush=True)
+            self.leases[lid] = {"leaseId": lid, "kind": "reserved", "cwd": spawn_cwd,
+                                "block": base, "ports": ports, "pid": pid,
+                                "owner_pid": owner_pid,
+                                "owner_start": owner_start, "tmp_config": None,
+                                "log": log, "spawn": spawn,
+                                "label": label, "sim_udid": sim_udid, "sim_name": sim_name,
+                                "started": _now(), "expires": time.time() + ttl}
+            self._save()
+            resp = {"leaseId": lid, "base": base, "ports": ports}
+            if sim_udid:
+                resp["sim"] = {"udid": sim_udid, "name": sim_name}
+            if pid:
+                resp["spawnedPid"] = pid
+                resp["log"] = log
+            return resp
+
+    def release(self, lid):
+        with self.lock:
+            rec = self.leases.pop(lid, None)
+            if not rec:
+                return {"released": False, "reason": "unknown lease"}
+            print(f"released {lid} ({rec.get('label') or rec.get('cwd') or 'no label'})", flush=True)
+            self._cleanup(rec)
+            self._save()
+            return {"released": True}
+
+    def release_owned(self, owner_pid, cwd=None):
+        with self.lock:
+            n = 0
+            for lid in list(self.leases):
+                l = self.leases[lid]
+                if l.get("owner_pid") == owner_pid and (cwd is None or l.get("cwd") == cwd):
+                    self._cleanup(self.leases.pop(lid))
+                    n += 1
+            self._save()
+            return {"released": n}
+
+    def heartbeat(self, lid, ttl=DEFAULT_TTL):
+        with self.lock:
+            l = self.leases.get(lid)
+            if l and l.get("expires") is not None:
+                l["expires"] = time.time() + ttl
+                self._save()
+            return {"ok": bool(l)}
+
+    def status(self):
+        with self.lock:
+            return {"leases": [{"leaseId": l["leaseId"], "kind": l["kind"], "cwd": l.get("cwd"),
+                                "ownerPid": l.get("owner_pid"), "up": _pid_alive(l.get("pid")),
+                                "ports": l["ports"], "projectId": l.get("project_id"),
+                                "sim": l.get("sim_udid"), "expires": l.get("expires"),
+                                "label": l.get("label"), "log": l.get("log")}
+                               for l in self.leases.values()]}
+
+    def reap(self):
+        with self.lock:
+            now = time.time()
+            for lid in list(self.leases):
+                if self._dead(self.leases[lid], now):
+                    self._cleanup(self.leases.pop(lid))
+            self._reap_deleted_sims(now)
+            self._save()
+
+    def _reap_deleted_sims(self, now):
+        """Reap leases whose simulator was deleted externally (Xcode cleanup,
+        `simctl delete/erase`, a stray reset). The lease is broken for its
+        caller even though its process is healthy; reaping it WHOLE (killing
+        the spawn too) prevents the half-alive ghost: sim gone, Metro still
+        squatting its port, callers 'reusing' a session Detox can't drive.
+        Throttled — one simctl listing per SIM_CHECK_INTERVAL, not per lease."""
+        if now - getattr(self, "_sims_checked", 0) < SIM_CHECK_INTERVAL:
+            return
+        sim_leases = [lid for lid, l in self.leases.items() if l.get("sim_udid")]
+        if not sim_leases:
+            self._sims_checked = now
+            return
+        udids = _sim_udids()
+        if udids is None:
+            return                        # indeterminate — no evidence, retry next pass
+        self._sims_checked = now
+        for lid in sim_leases:
+            l = self.leases.get(lid)
+            if l and l["sim_udid"] not in udids:
+                print(f"reaping {lid}: sim {l['sim_udid']} deleted externally", flush=True)
+                self._cleanup(self.leases.pop(lid))
+
+    def verify(self, lid):
+        """Full-liveness check for one lease, for callers deciding whether to
+        REUSE a session rather than re-lease: known to the daemon + process
+        alive + simulator present + (booted suites) ports open. Read-only —
+        never tears anything down."""
+        with self.lock:
+            l = self.leases.get(lid)
+            if not l:
+                return {"ok": False, "reasons": ["unknown lease"]}
+            reasons = []
+            pid = l.get("pid")
+            if pid and not _child_alive(pid):
+                reasons.append(f"process {pid} dead")
+            if l.get("sim_udid"):
+                udids = _sim_udids()
+                if udids is not None and l["sim_udid"] not in udids:
+                    reasons.append(f"sim {l['sim_udid']} gone")
+            if l["kind"] == "acquired":
+                down = [s for s, p in (l.get("check_ports") or _service_ports(l["ports"])).items()
+                        if not _port_open(p)]
+                if down:
+                    reasons.append("ports down: " + ",".join(sorted(down)))
+            return {"ok": not reasons, "reasons": reasons}
+
+
+class _Handler(http.server.BaseHTTPRequestHandler):
+    broker = None
+
+    def log_message(self, *_):
+        pass
+
+    def _send(self, code, obj):
+        body = json.dumps(obj).encode()
+        self.send_response(code)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(body)))
+        self.end_headers()
+        self.wfile.write(body)
+
+    def _body(self):
+        n = int(self.headers.get("Content-Length") or 0)
+        try:
+            return json.loads(self.rfile.read(n) or b"{}") if n else {}
+        except json.JSONDecodeError:
+            return {}
+
+    def do_GET(self):
+        if self.path == "/health":
+            return self._send(200, {"ok": True, "version": VERSION})
+        if self.path == "/status":
+            return self._send(200, self.broker.status())
+        self._send(404, {"error": "not found"})
+
+    def do_POST(self):
+        b, d = self.broker, self._body()
+        try:
+            if self.path == "/acquire":
+                return self._send(200, b.acquire(d["cwd"], d.get("owner_pid"), d.get("owner_start"),
+                                                 d.get("only"), d.get("ttl", DEFAULT_TTL),
+                                                 d.get("metro", False), d.get("sim", False),
+                                                 d.get("sim_device"), d.get("sim_runtime")))
+            if self.path == "/allocate":
+                return self._send(200, b.allocate(d.get("owner_pid"), d.get("owner_start"),
+                                                  d.get("ttl", DEFAULT_TTL), d.get("label"),
+                                                  d.get("metro", False), d.get("sim", False),
+                                                  d.get("sim_device"), d.get("sim_runtime"),
+                                                  d.get("spawn"), d.get("spawn_cwd")))
+            if self.path == "/release":
+                return self._send(200, b.release(d.get("leaseId")))
+            if self.path == "/release-owned":
+                return self._send(200, b.release_owned(d.get("owner_pid"), d.get("cwd")))
+            if self.path == "/heartbeat":
+                return self._send(200, b.heartbeat(d.get("leaseId"), d.get("ttl", DEFAULT_TTL)))
+            if self.path == "/verify":
+                return self._send(200, b.verify(d.get("leaseId")))
+            if self.path == "/shutdown":
+                threading.Thread(target=self.server.shutdown, daemon=True).start()
+                return self._send(200, {"ok": True})
+            self._send(404, {"error": "not found"})
+        except Exception as e:
+            self._send(500, {"error": str(e)})
+
+
+def cmd_serve():
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    _Handler.broker = Broker()
+    srv = http.server.ThreadingHTTPServer((BROKER_HOST, BROKER_PORT), _Handler)
+
+    def reaper():
+        while True:
+            time.sleep(REAP_INTERVAL)
+            try:
+                _Handler.broker.reap()
+            except Exception:
+                pass
+
+    threading.Thread(target=reaper, daemon=True).start()
+    print(f"harbormaster {VERSION} daemon on http://{BROKER_HOST}:{BROKER_PORT} "
+          f"(pool {POOL_BASE}-{POOL_BASE + POOL_BLOCKS * BLOCK - 1})", flush=True)
+    srv.serve_forever()
+
+
+# ---- client --------------------------------------------------------------
+
+def _call(method, path, body=None, timeout=BOOT_BACKSTOP + 60):   # client must outlive server's boot
+    conn = http.client.HTTPConnection(BROKER_HOST, BROKER_PORT, timeout=timeout)
+    data = json.dumps(body).encode() if body is not None else None
+    conn.request(method, path, body=data, headers={"Content-Type": "application/json"} if data else {})
+    resp = conn.getresponse()
+    out = json.loads(resp.read() or b"{}")
+    conn.close()
+    return resp.status, out
+
+
+def _up():
+    try:
+        return _call("GET", "/health", timeout=1)[0] == 200
+    except OSError:
+        return False
+
+
+def _daemon_version():
+    """The running daemon's version, '0' for pre-0.3 daemons, None if not running."""
+    try:
+        st, out = _call("GET", "/health", timeout=1)
+        return (out.get("version") or "0") if st == 200 else None
+    except OSError:
+        return None
+
+
+def _ver_tuple(v):
+    try:
+        return tuple(int(x) for x in str(v).split("."))
+    except ValueError:
+        return (0,)
+
+
+def _spawn_daemon():
+    STATE_DIR.mkdir(parents=True, exist_ok=True)
+    log = open(STATE_DIR / "daemon.log", "a")
+    subprocess.Popen([sys.argv[0], "serve"], stdout=log, stderr=subprocess.STDOUT, start_new_session=True)
+
+
+def _ensure():
+    v = _daemon_version()
+    if v is not None:
+        if _ver_tuple(v) >= _ver_tuple(VERSION):
+            return
+        # A newer client found an older daemon (e.g. a stale node_modules copy
+        # started it). Replace it: leases persist in the ledger and every leased
+        # process (suites, spawns) runs in its own session, so the successor
+        # daemon reloads them and carries on — nothing is torn down.
+        try:
+            _call("POST", "/shutdown", timeout=5)
+        except OSError:
+            pass
+        for _ in range(50):
+            if not _up():
+                break
+            time.sleep(0.1)
+        if _up():
+            raise RuntimeError(
+                f"daemon {v} is older than this client ({VERSION}) and did not "
+                f"shut down — kill the 'harbormaster serve' process and retry")
+    _spawn_daemon()
+    for _ in range(50):
+        if _up():
+            return
+        time.sleep(0.1)
+    raise RuntimeError("daemon failed to start (see ~/.local/state/firebase-ports/daemon.log)")
+
+
+def _owner(opts):
+    """The owning process: --owner, else the CLI's parent (the calling shell/runner).
+
+    `--owner auto` resolves the nearest ancestor that outlives the calling
+    script — the useful answer for daemon-spawned leases, where the immediate
+    parent exits seconds later. Resolves to no owner when nothing suitable is
+    found, leaving TTL and working-dir checks to govern the lease.
+    """
+    if str(opts.get("owner")).lower() == "auto":
+        pid = _durable_ancestor(os.getpid())
+        return (pid, _proc_start(pid)) if pid else (None, None)
+    pid = int(opts["owner"]) if opts.get("owner") else os.getppid()
+    return pid, _proc_start(pid)
+
+
+def _resolve_cwd(opts):
+    cwd = opts.get("cwd") or _find_firebase_dir(os.getcwd())
+    if not cwd or not (Path(cwd) / "firebase.json").exists():
+        print("no firebase.json here — run inside a project or pass --cwd DIR", file=sys.stderr)
+        sys.exit(1)
+    return str(Path(cwd).resolve())
+
+
+def _print(out, fmt):
+    ports, pid = out.get("ports", {}), out.get("projectId")
+    sim = out.get("sim")
+    if fmt == "json":
+        print(json.dumps(out))
+    elif fmt == "env":
+        # Standard Firebase host vars (admin SDK + emulators:exec auto-read these) AND
+        # EMULATOR_<SVC>_PORT (what app.config / config.sh / scrub scripts read).
+        std = {"firestore": "FIRESTORE_EMULATOR_HOST", "auth": "FIREBASE_AUTH_EMULATOR_HOST",
+               "storage": "FIREBASE_STORAGE_EMULATOR_HOST", "database": "FIREBASE_DATABASE_EMULATOR_HOST",
+               "pubsub": "PUBSUB_EMULATOR_HOST"}
+        if pid:
+            print(f"export GCLOUD_PROJECT={pid}")
+            print(f"export GOOGLE_CLOUD_PROJECT={pid}")
+        for svc, port in ports.items():
+            if svc == "metro":
+                print(f"export METRO_PORT={port}")            # Expo/Metro dev server + Detox bundle URL
+                continue
+            if svc in std:
+                print(f"export {std[svc]}=127.0.0.1:{port}")
+            print(f"export EMULATOR_{svc.upper()}_PORT={port}")
+        if sim:
+            print(f"export DETOX_UDID={sim['udid']}")          # Detox targets this simulator by UDID
+            print(f"export DETOX_SIM_NAME={sim['name']}")
+    else:
+        print(f"{out.get('leaseId', '')}  ({pid})".strip())
+        for svc, port in ports.items():
+            print(f"    {svc:<10} 127.0.0.1:{port}")
+        if sim:
+            print(f"    {'sim':<10} {sim['name']}  {sim['udid']}")
+
+
+def _parse(args):
+    pos, flags, opts = [], set(), {}
+    i = 0
+    while i < len(args):
+        a = args[i]
+        if a.startswith("--"):
+            if "=" in a:
+                k, v = a[2:].split("=", 1)
+                opts[k] = v
+            elif a[2:] in ("cwd", "only", "ttl", "owner", "label", "sim-device", "sim-runtime", "spawn") and i + 1 < len(args):
+                opts[a[2:]] = args[i + 1]
+                i += 1
+            else:
+                flags.add(a[2:])
+        else:
+            pos.append(a)
+        i += 1
+    return pos, flags, opts
+
+
+def main():
+    if len(sys.argv) < 2 or sys.argv[1] in ("-h", "--help"):
+        print(__doc__.strip())
+        sys.exit(0)
+    cmd = sys.argv[1]
+    pos, flags, opts = _parse(sys.argv[2:])
+    fmt = "json" if "json" in flags else "env" if "env" in flags else "human"
+    only = opts["only"].split(",") if opts.get("only") else None
+
+    def ok(res, verb):
+        st, out = res
+        if st != 200:
+            print(f"{verb} failed: {out.get('error', out)}", file=sys.stderr)
+            sys.exit(1)
+        return out
+
+    if cmd == "version":
+        print(VERSION)
+    elif cmd == "serve":
+        cmd_serve()
+    elif cmd in ("acquire", "up"):
+        _ensure()
+        pid, start = _owner(opts)
+        _print(ok(_call("POST", "/acquire", {"cwd": _resolve_cwd(opts), "owner_pid": pid,
+                                             "owner_start": start, "only": only,
+                                             "ttl": int(opts.get("ttl", DEFAULT_TTL)),
+                                             "metro": "metro" in flags, "sim": "sim" in flags,
+                                             "sim_device": opts.get("sim-device"),
+                                             "sim_runtime": opts.get("sim-runtime")}), "acquire"), fmt)
+    elif cmd == "down":
+        if _up():
+            out = _call("POST", "/release-owned", {"owner_pid": os.getppid(), "cwd": _resolve_cwd(opts)})[1]
+            print(f"released {out.get('released', 0)} sandbox(es)")
+        else:
+            print("daemon not running")
+    elif cmd == "release":
+        if _up() and pos:
+            out = _call("POST", "/release", {"leaseId": pos[0]})[1]
+            print("released" if out.get("released") else f"not released: {out.get('reason')}")
+        else:
+            print("nothing to release")
+    elif cmd == "allocate":
+        _ensure()
+        spawn = opts.get("spawn")
+        # A daemon-spawned or explicitly-detached lease has no owner: it outlives
+        # the calling shell/agent by design and is governed by pid liveness + TTL.
+        if (spawn or "detach" in flags) and not opts.get("owner"):
+            pid, start = None, None
+        else:
+            pid, start = _owner(opts)
+        out = ok(_call("POST", "/allocate", {"owner_pid": pid, "owner_start": start,
+                                             "ttl": int(opts.get("ttl", DEFAULT_TTL)),
+                                             "label": opts.get("label"),
+                                             "metro": "metro" in flags, "sim": "sim" in flags,
+                                             "sim_device": opts.get("sim-device"),
+                                             "sim_runtime": opts.get("sim-runtime"),
+                                             "spawn": spawn,
+                                             "spawn_cwd": str(Path(opts["cwd"]).resolve()) if opts.get("cwd") else None}),
+                 "allocate")
+        if fmt == "env":
+            # Reserved block, nothing booted — emit only the dev-env extras (plus
+            # the base for callers that derive their own ports from it).
+            print(f"export FBPORTS_BLOCK_BASE={out['base']}")
+            print(f"export FBPORTS_LEASE_ID={out['leaseId']}")
+            if out.get("ports", {}).get("metro"):
+                print(f"export METRO_PORT={out['ports']['metro']}")
+            if out.get("sim"):
+                print(f"export DETOX_UDID={out['sim']['udid']}")
+                print(f"export DETOX_SIM_NAME={out['sim']['name']}")
+            if out.get("log"):
+                print(f"export FBPORTS_SPAWN_LOG={out['log']}")
+        elif fmt == "json":
+            print(json.dumps(out))
+        else:
+            extra = f"  metro {out['ports']['metro']}" if out.get("ports", {}).get("metro") else ""
+            extra += f"  sim {out['sim']['udid']}" if out.get("sim") else ""
+            extra += f"  spawned pid {out['spawnedPid']}" if out.get("spawnedPid") else ""
+            print(f"{out['leaseId']}  base {out['base']}{extra}")
+    elif cmd == "exec":
+        # harbormaster exec [--cwd DIR] [--only a,b] '<script>'
+        # Reserve a free block from the daemon, then run `firebase emulators:exec`
+        # on it (which boots the suite, sets FIRESTORE_EMULATOR_HOST etc. for the
+        # script, and tears down). This is how projects should invoke emulators:exec
+        # so concurrent runs never collide on ports.
+        _ensure()
+        cwd = _resolve_cwd(opts)
+        script = " ".join(pos)
+        if not script:
+            print("usage: harbormaster exec [--cwd DIR] [--only a,b] '<script>'", file=sys.stderr)
+            sys.exit(1)
+        me = os.getpid()                      # this process owns the reservation for the run
+        res = ok(_call("POST", "/allocate", {"owner_pid": me, "owner_start": _proc_start(me), "label": "exec"}), "exec")
+        base, lid = res["base"], res["leaseId"]
+        tmp = _write_injected_config(cwd, _block_ports(base))
+        try:
+            run = ["firebase", "emulators:exec", "--config", tmp]
+            if only:
+                run += ["--only", ",".join(only)]
+            run.append(script)
+            rc = subprocess.call(run, cwd=cwd)
+        finally:
+            try:
+                _call("POST", "/release", {"leaseId": lid})
+            except OSError:
+                pass
+            p = Path(cwd) / tmp
+            if p.exists():
+                p.unlink()
+        sys.exit(rc)
+    elif cmd == "verify":
+        # verify <leaseId> — exit 0 iff the lease is FULLY alive. The reuse
+        # gate for long-lived sessions (e2e Metro + sim): anything less than
+        # fully alive means tear down what's left and re-lease.
+        if not pos:
+            print("usage: harbormaster verify <leaseId>", file=sys.stderr)
+            sys.exit(2)
+        _ensure()                          # also upgrades an older daemon first
+        out = _call("POST", "/verify", {"leaseId": pos[0]})[1]
+        if out.get("ok"):
+            print("ok")
+        else:
+            print("; ".join(out.get("reasons") or [out.get("error", "not ok")]))
+            sys.exit(1)
+    elif cmd in ("status", "leases"):
+        if not _up():
+            print("daemon not running.")
+            return
+        leases = _call("GET", "/status")[1].get("leases", [])
+        if not leases:
+            print("nothing out.")
+            return
+        for l in leases:
+            exp = l.get("expires")
+            ttl = "" if exp is None else f"  ttl~{max(0, int(exp - time.time()))}s"
+            where = f"base:{l['ports']['base']}" if l["kind"] == "reserved" else f"firestore:{l['ports'].get('firestore')}"
+            if l["kind"] != "reserved" and l["ports"].get("metro"):
+                where += f" metro:{l['ports']['metro']}"
+            if l.get("sim"):
+                where += f" sim:{l['sim'][:8]}"
+            print(f"{l['leaseId']:<22} {l['kind']:<9} owner:{str(l.get('ownerPid') or '-'):<7} "
+                  f"{'up' if l['up'] else '-':<3} {where}{ttl}  "
+                  f"{l.get('label') or ''}  {l.get('cwd') or ''}".rstrip())
+    else:
+        print(f"Unknown command: {cmd}", file=sys.stderr)
+        print("Commands: acquire, up, down, release, allocate, verify, status, leases, serve", file=sys.stderr)
+        sys.exit(1)
+
+
+if __name__ == "__main__":
+    main()