@simon-says-build/harbormaster 0.10.0 → 0.11.1

package/README.md

@@ -124,3 +124,16 @@ 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 2 minutes 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:
@@ -82,7 +84,7 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "0.10.0"
+VERSION = "0.11.1"
 
 # Overridable for tests / parallel installs; default is the shared user daemon.
 # The dir keeps the old "firebase-ports" name: pre-rename binaries still installed
@@ -1246,8 +1248,43 @@ 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)
@@ -1362,8 +1399,11 @@ def _spawn_daemon():
 
 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
@@ -1381,6 +1421,17 @@ 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. Two minutes: a
+        # busy box's startup sweep is not quick — the studio's first managed
+        # start reaped 75 leftovers and served after ~40 s (2026-10-09), and a
+        # client that gives up early starts a broker that fights the service.
+        for _ in range(1200):
+            if _up():
+                return
+            time.sleep(0.1)
+        print("harbormaster: the managed broker did not come back in 120s — starting one here", file=sys.stderr)
     _spawn_daemon()
     for _ in range(50):
         if _up():
@@ -1494,7 +1545,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.10.0",
+  "version": "0.11.1",
   "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",