@simon-says-build/harbormaster 0.9.1 → 0.11.0

package/README.md

@@ -102,3 +102,38 @@ See [DESIGN.md](./DESIGN.md) for the full architecture.
 ## License
 
 MIT — see [LICENSE](./LICENSE).
+
+## The daemon's environment is nobody's test environment
+
+The daemon is started by whichever client first needs it and would otherwise
+inherit that shell. Suites it boots inherit the daemon's environment (that is
+how `--fn-env` reaches the functions emulator runtime), so a variable exported
+by the first caller would reach every later caller's suite for the life of the
+daemon. Harbormaster therefore strips test-only and emulator-pointing variables
+(`TEST_NOW_MS`, `LLM_CACHE*`, `*_EMULATOR_HOST`, `*_EMULATOR_PORT`,
+`GCLOUD_PROJECT`, and the values a lease hands out) both when spawning the
+daemon and when it starts serving. A suite that needs one of these gets it
+explicitly: `acquire --fn-env TEST_NOW_MS=...`.
+
+## A block docker holds is not free (0.10.0)
+
+Free-block selection also asks `docker ps` which host ports are published. On
+Linux, dockerd publishes a container's ports through iptables and, without the
+userland proxy, nothing listens on them, so a connect finds the port quiet
+while a container holds it. Simon Says' local Supabase stacks are containers
+on harbormaster blocks. On simon-linux-1 (2026-10-09), four jobs were handed a
+block a stack still held. No docker means the empty set, never a failure.
+`python3 test/docker_ports.py`.
+
+## A managed broker (0.11.0)
+
+`harbormaster serve --managed` is for a broker that a service manager
+(systemd, launchd) runs and restarts. It keeps a marker in the state dir
+fresh, touched every minute. While the marker is fresh, clients never replace
+the broker, even an older one, and never spawn their own. If it is briefly
+down, they wait up to 45 s for the service manager to bring it back. Upgrades
+are the service manager's job: restart it after installing a new version. A
+stale marker means the service is gone, and clients spawn as before. Without
+this, the broker belonged to whichever client happened to start it: on
+simon-linux-1 that was a CI job, whose orphan cleanup killed the broker and
+every emulator it ran for other jobs mid-suite. `python3 test/managed.py`.

package/harbormaster

@@ -59,7 +59,9 @@ independent suites, so they never collide on ports or data.
         JVMs / functions workers re-parented to pid 1), stray run-*/alloc-* sims.
         --fix evicts them; exits 1 when findings remain unfixed. The daemon runs
         the same sweep itself at startup and every FBPORTS_SWEEP_INTERVAL (300s).
-  serve                  Run the daemon (auto-starts on first command).
+  serve [--managed]      Run the daemon (auto-starts on first command). --managed: a service
+                         manager (systemd/launchd) runs and restarts it; clients then never
+                         replace or spawn a broker while its marker is fresh.
 
 NOTE: firebase.json ports are optional — the daemon injects (and overrides) a
 per-lease pool block, so concurrent suites never collide. Ledger:
@@ -71,6 +73,7 @@ import http.server
 import json
 import os
 import signal
+import re
 import socket
 import shutil
 import subprocess
@@ -81,7 +84,7 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "0.9.1"
+VERSION = "0.11.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
@@ -185,6 +188,33 @@ def _port_open(port, host="127.0.0.1"):
         return s.connect_ex((host, int(port))) == 0
 
 
+# THE PORTS DOCKER PUBLISHES, asked of docker itself. A connect is not enough:
+# on Linux dockerd publishes a container's port through iptables and, with no
+# userland proxy, nothing LISTENS on it — `_port_open` finds the port quiet
+# while a container holds it. Simon Says' local Supabase stacks (20-port blocks,
+# one per job) are containers; on simon-linux-1 (2026-10-09) four jobs in a row
+# were handed a block a stack still held and died on "address already in use".
+# One `docker ps` per allocation; no docker, or one that will not answer, is the
+# empty set — never a failure.
+_PUBLISHED_RE = re.compile(r":(\d+)(?:-(\d+))?->")
+
+
+def _parse_published(text):
+    out = set()
+    for m in _PUBLISHED_RE.finditer(text or ""):
+        a = int(m.group(1)); b = int(m.group(2)) if m.group(2) else a
+        out.update(range(a, min(b, a + 999) + 1))
+    return out
+
+
+def _docker_published_ports():
+    try:
+        r = subprocess.run(["docker", "ps", "--format", "{{.Ports}}"], capture_output=True, text=True, timeout=10)
+        return _parse_published(r.stdout) if r.returncode == 0 else set()
+    except (OSError, subprocess.SubprocessError):
+        return set()
+
+
 def _all_open(ports):
     return bool(ports) and all(_port_open(p) for p in ports.values())
 
@@ -627,9 +657,14 @@ class Broker:
 
     def _free_block(self):
         used = {l["block"] for l in self.leases.values() if l.get("block")}
+        published = _docker_published_ports()
         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)):
+            if base in used:
+                continue
+            if any(base + off in published for off in range(BLOCK)):
+                continue
+            if all(not _port_open(base + off) for off in range(BLOCK)):
                 return base
         raise RuntimeError("emulator port pool exhausted")
 
@@ -1213,8 +1248,46 @@ class _Handler(http.server.BaseHTTPRequestHandler):
             self._send(500, {"error": str(e)})
 
 
-def cmd_serve():
+# A MANAGED broker (0.11.0): one a service manager runs and keeps alive —
+# `harbormaster serve --managed` under systemd or launchd. Its marker in the
+# state dir is touched every minute; while it is fresh, clients never replace
+# the broker and never spawn their own: the service manager owns its lifecycle
+# and its upgrades. Without this, the broker belonged to whichever client
+# happened to start it. On simon-linux-1 (2026-10-09) that was an SSB job's own
+# checkout inside the runner's systemd unit, and before it a CI job, whose
+# orphan cleanup killed the broker — and every emulator it ran for OTHER jobs —
+# mid-suite. A stale marker means the service is gone: clients spawn as before.
+MANAGED_MARK = STATE_DIR / "managed"
+MANAGED_FRESH_S = 300
+
+
+def _managed_recent():
+    try:
+        return time.time() - MANAGED_MARK.stat().st_mtime < MANAGED_FRESH_S
+    except OSError:
+        return False
+
+
+def _touch_managed():
+    try:
+        MANAGED_MARK.write_text(json.dumps({"pid": os.getpid(), "version": VERSION, "exe": str(Path(__file__).resolve())}))
+    except OSError:
+        pass
+
+
+def cmd_serve(managed=False):
     STATE_DIR.mkdir(parents=True, exist_ok=True)
+    if managed:
+        _touch_managed()
+
+        def keep_marked():
+            while True:
+                time.sleep(60)
+                _touch_managed()
+        threading.Thread(target=keep_marked, daemon=True).start()
+    dropped = _scrub_environ()
+    if dropped:
+        print(f"harbormaster: scrubbed inherited env before serving: {', '.join(dropped)}", flush=True)
     _Handler.broker = Broker()
     srv = http.server.ThreadingHTTPServer((BROKER_HOST, BROKER_PORT), _Handler)
 
@@ -1267,16 +1340,70 @@ def _ver_tuple(v):
         return (0,)
 
 
+# THE DAEMON'S ENVIRONMENT IS NOBODY'S TEST ENVIRONMENT.
+#
+# The daemon is started by whichever client first needs it, and inherits that
+# client's shell. Every suite it boots then inherits the daemon's environment
+# (`_boot`: {**os.environ, ...}), because that is how the functions emulator
+# runtime gets the env a caller passes with --fn-env. So a variable exported
+# by the FIRST caller reaches every LATER caller's suite, for the life of the
+# daemon — and nothing shows it.
+#
+# 2026-09-02: a session-test run (TEST_NOW_MS=1784000000000, LLM_CACHE=1
+# exported) started the daemon at 07:04. Every native e2e suite booted after
+# that ran its functions emulator on a clock frozen at 2026-07-13; the app
+# created its onboarding session with that date, decided the session was
+# seven weeks old and not editable, and hid the composer. The onboarding gate
+# spec failed on every PR for the rest of the day, and the diagnosis took
+# hours because the only trace was a date inside one Firestore document.
+#
+# So: anything test-only, anything that points at an emulator, and anything a
+# lease hands out is stripped from the daemon's own environment — when a
+# client spawns it AND when it starts serving (a daemon started by hand from a
+# test shell is the same hazard). A caller that wants a suite to see such a
+# variable passes it explicitly with --fn-env, which rides on top of this.
+SCRUB_EXACT = {
+    "TEST_NOW_MS",
+    "GCLOUD_PROJECT", "FIREBASE_CONFIG", "FUNCTIONS_EMULATOR",
+    "FBPORTS_LEASE_ID", "FBPORTS_BLOCK_BASE",
+    "METRO_PORT", "DETOX_UDID", "DETOX_SIM_NAME", "AGENT_SIM_UDID",
+}
+# LLM_ is the whole family, not LLM_CACHE: 2026-09-13 a session that built
+# replay-only mode started the daemon with LLM_REPLAY_ONLY=1, and for five days
+# every native e2e suite threw on its first OpenAI call instead of replying.
+SCRUB_PREFIXES = ("LLM_", "EMULATOR_")
+SCRUB_SUFFIXES = ("_EMULATOR_HOST", "_EMULATOR_PORT")
+
+
+def scrub_key(k):
+    return (k in SCRUB_EXACT or k.startswith(SCRUB_PREFIXES) or k.endswith(SCRUB_SUFFIXES))
+
+
+def scrubbed_env(env):
+    return {k: v for k, v in env.items() if not scrub_key(k)}
+
+
+def _scrub_environ():
+    dropped = sorted(k for k in os.environ if scrub_key(k))
+    for k in dropped:
+        del os.environ[k]
+    return dropped
+
+
 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)
+    subprocess.Popen([sys.argv[0], "serve"], stdout=log, stderr=subprocess.STDOUT,
+                     start_new_session=True, env=scrubbed_env(os.environ))
 
 
 def _ensure():
     v = _daemon_version()
+    managed = _managed_recent()
     if v is not None:
-        if _ver_tuple(v) >= _ver_tuple(VERSION):
+        # A managed broker is never replaced by a client: its service manager
+        # owns upgrades (restart it to pick up a new install).
+        if managed or _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
@@ -1294,6 +1421,14 @@ def _ensure():
             raise RuntimeError(
                 f"daemon {v} is older than this client ({VERSION}) and did not "
                 f"shut down — kill the 'harbormaster serve' process and retry")
+    if managed:
+        # Down, but a service runs it: it is restarting. Wait for it rather than
+        # start one of our own that would die with this client.
+        for _ in range(450):
+            if _up():
+                return
+            time.sleep(0.1)
+        print("harbormaster: the managed broker did not come back in 45s — starting one here", file=sys.stderr)
     _spawn_daemon()
     for _ in range(50):
         if _up():
@@ -1407,7 +1542,7 @@ def main():
     if cmd == "version":
         print(VERSION)
     elif cmd == "serve":
-        cmd_serve()
+        cmd_serve(managed="managed" in flags)
     elif cmd in ("acquire", "up"):
         _ensure()
         pid, start = _owner(opts)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simon-says-build/harbormaster",
-  "version": "0.9.1",
+  "version": "0.11.0",
   "description": "A localhost daemon that leases each caller its own port block — isolated Firebase emulator sandboxes, Metro/Expo ports, private iOS simulators — reaped when the caller exits. No port collisions, no shared instances, no pkill.",
   "bin": {
     "harbormaster": "harbormaster",