@simon-says-build/harbormaster 0.9.0 → 0.10.0

package/README.md

@@ -102,3 +102,25 @@ 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`.

package/harbormaster

@@ -71,7 +71,9 @@ import http.server
 import json
 import os
 import signal
+import re
 import socket
+import shutil
 import subprocess
 import sys
 import threading
@@ -80,7 +82,7 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "0.9.0"
+VERSION = "0.10.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
@@ -88,6 +90,9 @@ VERSION = "0.9.0"
 STATE_DIR = Path(os.environ.get("FBPORTS_STATE_DIR",
                                 str(Path.home() / ".local" / "state" / "firebase-ports")))
 LEDGER = STATE_DIR / "ledger.json"
+# Per-suite TMPDIR for the emulator process (see EmulatorPool._boot).
+def _suite_tmpdir(label):
+    return STATE_DIR / "tmp" / str(label)
 BROKER_HOST, BROKER_PORT = "127.0.0.1", int(os.environ.get("FBPORTS_PORT", "4999"))
 # Blocks of 20 ports, 11000-14999 by default. Overridable so an isolated test
 # daemon (FBPORTS_PORT + FBPORTS_STATE_DIR) can also use a DISJOINT pool — its
@@ -181,6 +186,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())
 
@@ -623,9 +655,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")
 
@@ -639,6 +676,18 @@ class Broker:
         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"
+        # Each suite gets its OWN temp dir. firebase-tools keeps the Storage
+        # emulator's blobs at `${os.tmpdir()}/firebase/storage/blobs` — one
+        # fixed path for every instance on the box — and `stop()` rm -rf's it.
+        # So any suite shutting down wiped the blobs of every other suite still
+        # running, and their next upload died with ENOENT inside firebase-tools
+        # ("An unexpected error has occurred.", exit 2, all emulators gone).
+        # On a box that runs several suites at once that is not a corner case:
+        # 2026-08-28, three walk2gether e2e runs in a row on the studio, each
+        # killed by a daemon verify drive finishing. os.tmpdir() honours
+        # TMPDIR, so a per-suite one makes the path private.
+        suite_tmp = _suite_tmpdir(label)
+        suite_tmp.mkdir(parents=True, exist_ok=True)
         cmd = ["firebase", "emulators:start", "--config", tmp]
         if only:
             cmd += ["--only", ",".join(only)]
@@ -648,9 +697,9 @@ class Broker:
         # daemon's env — the functions emulator runtime inherits it, which is
         # the only way a CALLER can set per-suite env (e.g. LLM_CACHE_DIR)
         # when the daemon, not the caller, spawns the emulator.
-        spawn_env = None
+        spawn_env = {**os.environ, "TMPDIR": str(suite_tmp)}
         if extra_env:
-            spawn_env = {**os.environ, **{str(k): str(v) for k, v in dict(extra_env).items()}}
+            spawn_env.update({str(k): str(v) for k, v in dict(extra_env).items()})
         with open(log, "w") as lf:
             proc = subprocess.Popen(cmd, cwd=cwd, stdout=lf, stderr=subprocess.STDOUT, start_new_session=True, env=spawn_env)
         if on_spawn:
@@ -770,6 +819,11 @@ class Broker:
         tmp = rec.get("tmp_config")
         if tmp and rec.get("cwd") and (Path(rec["cwd"]) / tmp).exists():
             (Path(rec["cwd"]) / tmp).unlink()
+        # The suite's private TMPDIR (see _boot). Derived from the label the
+        # same way _boot derived it, so old ledger records need no new field.
+        label = rec.get("label") or (Path(rec["log"]).stem if rec.get("log") else None)
+        if label:
+            shutil.rmtree(_suite_tmpdir(label), ignore_errors=True)
         if rec.get("sim_udid"):
             gone = _sim_teardown(rec["sim_udid"])
             actions.append(f"sim {rec['sim_udid'][:8]} " +
@@ -1194,6 +1248,9 @@ class _Handler(http.server.BaseHTTPRequestHandler):
 
 def cmd_serve():
     STATE_DIR.mkdir(parents=True, exist_ok=True)
+    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)
 
@@ -1246,10 +1303,61 @@ 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():

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@simon-says-build/harbormaster",
-  "version": "0.9.0",
+  "version": "0.10.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",