@simon-says-build/harbormaster 0.14.1 → 0.15.0

package/DESIGN.md

@@ -169,9 +169,20 @@ POST /doctor    {fix?}                                      -> {findings, fixed,
 ```
 
 CLI: `acquire` / `up` (alias) / `down` (release your lease) / `release <id>` / `status`
-/ `leases` / `allocate` / `serve`. Pool: blocks of 20 ports from 11000–14999, offsets
-`auth=+0 firestore=+1 functions=+2 storage=+3 ui=+4 hub=+5 logging=+6 pubsub=+7
-eventarc=+8 database=+9` (kept in sync with the run driver's derivation).
+/ `leases` / `allocate` / `serve`. Pool: blocks of 20 ports from 11000–14999. An
+`acquire`/`exec` suite's block (0.15.0: every port the CLI may bind, declared or not):
+
+| +0 auth | +5 hub | +10 firestore websocket | +15 hosting |
+|---|---|---|---|
+| +1 firestore | +6 logging | +11 Metro | +16 apphosting |
+| +2 functions | +7 pubsub | +12 caller | +17 dataconnect |
+| +3 storage | +8 eventarc | +13 caller | +18 dataconnect postgres |
+| +4 ui | +9 database | +14 caller | +19 tasks |
+
++12..+14 are never bound by a suite: they are the caller's (SimonSays' verify dev
+server, CDP, api, vite). A reserved (`allocate`) block is the caller's whole, bar
+Metro at +11. Android emulator console/adb pairs (`--android`) come from a second
+range, even consoles 5554–5584 (adb = console + 1), leased the same way.
 
 ## What changes from v1
 

package/README.md

@@ -92,8 +92,9 @@ its port) can never linger for callers to "reuse".
   children die too) when `owner_pid` dies. The caller's death *is* the release —
   nothing to remember, and never a reason to `pkill`. A TTL and emulator-liveness are
   backstops.
-- **Pool ports.** Blocks of 20 from 11000–14999; each firestore suite also gets a
-  private websocket port, so concurrent suites never collide on the default 9150.
+- **Pool ports.** Blocks of 20 from 11000–14999. Every port a suite binds is on its
+  block, including the ones firebase-tools starts unasked (see "Every port a suite
+  binds is on its block"); offsets 12–14 are left for the caller.
 - **No registry, no shared instances.** A "project" is just the `firebase.json` in
   `cwd`; the project id comes from `.firebaserc`.
 
@@ -155,6 +156,59 @@ env, under the caller's explicit `--fn-env`. `exec`: on top of the caller's
 ambient env, so a key exported in some shell can't leak into the suite.
 `python3 test/project_env.py`.
 
+## A function env value can name a leased port (0.14.2)
+
+`--fn-env KEY={port:firestore}`, or the same in `harbormaster.env`, becomes
+this lease's firestore port, inside a value too (`127.0.0.1:{port:auth}`). A
+caller can't know its ports before the lease, and an app whose functions read
+their own variable for the emulator (Tapuat's `EMULATOR_PORT_FIRESTORE ||
+"8080"`) otherwise talks to whatever holds the default. An unknown service is
+left as written. `python3 test/port_env.py`.
+
+## Every port a suite binds is on its block (0.15.0)
+
+firebase-tools starts more than `firebase.json` declares: the hub always; the
+UI whenever a UI-supported emulator runs (declared or not) and logging with
+it; eventarc and tasks whenever functions has a backend (an extension counts);
+firestore's websocket (9150) and dataconnect's postgres (5432). Any port it is
+not given it takes from the default and, if that is held, probes upward —
+check-then-bind, so two suites booting in the same seconds pick the same port
+and the second dies with "An unexpected error has occurred." (SimonSays' Mac
+Studio, 2026-10-21: logging 4501 and 4502 taken twice; a walk2gether-expo CI
+suite holding tasks 9501.) The injected config now sets all of them, plus
+hosting, apphosting and dataconnect wherever the project uses them:
+
+| +0 auth | +5 hub | +10 firestore websocket | +15 hosting |
+|---|---|---|---|
+| +1 firestore | +6 logging | +11 Metro | +16 apphosting |
+| +2 functions | +7 pubsub | +12 caller | +17 dataconnect |
+| +3 storage | +8 eventarc | +13 caller | +18 dataconnect postgres |
+| +4 ui | +9 database | +14 caller | +19 tasks |
+
++12..+14 are never bound by a suite. A declared emulator with no offset is
+refused by name instead of left to its default. Teardown and the world sweep
+already cover the whole block. `python3 test/injected_config.py`; `test/e2e.sh`
+checks a live suite's listeners.
+
+## An Android emulator's ports are a lease (0.15.0)
+
+`acquire --android` / `allocate --android` also lease an emulator console/adb
+pair: an even console port in 5554..5584 (the range adb discovers; adb =
+console + 1; `FBPORTS_ANDROID_CONSOLE_FIRST`/`_LAST` move it), unique among
+live leases and free when handed out. The caller (and a `--spawn` process)
+gets `ANDROID_CONSOLE_PORT`, `ANDROID_ADB_PORT`, `ANDROID_SERIAL=emulator-<console>`:
+
+```bash
+harbormaster allocate --android --owner auto \
+  --spawn 'exec emulator -avd Pixel -port "$ANDROID_CONSOLE_PORT" -read-only -no-window' --env
+```
+
+The pair is outside the pool, where a hand-booted emulator lands by default, so
+teardown kills only what the lease spawned (its group and recorded tree) and
+reports anything else still on the pair; the world sweep reports unleased
+listeners on the range and evicts only what it can attribute.
+`python3 test/android_ports.py`.
+
 ## A lease never reads the hosting config it doesn't start (0.14.1)
 
 A lease whose `--only` leaves hosting out boots from a config with no

package/harbormaster

@@ -8,7 +8,7 @@ per-project instances — two callers that both want "an impulse emulator" get t
 independent suites, so they never collide on ports or data.
 
   acquire [--cwd DIR] [--owner PID] [--only a,b] [--ttl N] [--metro] [--sim]
-          [--fn-env KEY=VAL ...] [--json|--env]
+          [--android] [--fn-env KEY=VAL ...] [--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).
@@ -20,15 +20,23 @@ independent suites, so they never collide on ports or data.
         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.
+        --android also leases an Android emulator console/adb port pair (an even
+        console port in 5554..5584, adb = console + 1; FBPORTS_ANDROID_CONSOLE_FIRST
+        / _LAST move the range): ANDROID_CONSOLE_PORT, ANDROID_ADB_PORT,
+        ANDROID_SERIAL=emulator-<console>. Boot with `emulator -port "$ANDROID_CONSOLE_PORT"`.
+        Every port the suite binds is on the block, including the ones firebase-tools
+        starts unasked (ui, logging, eventarc, tasks, firestore's websocket,
+        dataconnect's postgres); block offsets 12-14 are never bound — they're yours.
   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]
+  allocate [--owner PID|auto] [--ttl N] [--metro] [--sim] [--android] [--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
+        (metro port in the block; private simulator, deleted on reap), and so does
+        --android (the pair; CMD sees ANDROID_CONSOLE_PORT etc.), 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).
@@ -36,7 +44,8 @@ independent suites, so they never collide on ports or data.
         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.
+        FBPORTS_LEASE_ID, and METRO_PORT / DETOX_UDID / DETOX_SIM_NAME /
+        ANDROID_CONSOLE_PORT / ANDROID_ADB_PORT / ANDROID_SERIAL 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,
@@ -84,7 +93,7 @@ import uuid
 from datetime import datetime, timezone
 from pathlib import Path
 
-VERSION = "0.14.1"
+VERSION = "0.15.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
@@ -103,14 +112,62 @@ BROKER_HOST, BROKER_PORT = "127.0.0.1", int(os.environ.get("FBPORTS_PORT", "4999
 POOL_BASE = int(os.environ.get("FBPORTS_POOL_BASE", "11000"))
 POOL_BLOCKS = int(os.environ.get("FBPORTS_POOL_BLOCKS", "200"))
 BLOCK = 20
+# EVERY port an emulator suite can bind is on its block (0.15.0). firebase-tools
+# (15.28, controller.js) binds more than firebase.json declares, and for any
+# port it is not given it takes the default and, if that is held, probes upward
+# — check-then-bind, so two suites booting in the same seconds pick the same
+# port and the second dies with "An unexpected error has occurred." (SSB's Mac
+# Studio, 2026-10-21: three suites, logging 4501/4502 twice; a walk2gether-expo
+# CI suite holding tasks 9501). Started unasked: hub (always), ui (whenever a
+# UI-supported emulator runs, declared or not), logging (with the ui), eventarc
+# and tasks (whenever functions has a backend — an extension counts), firestore's
+# websocket (9150), dataconnect's postgres (5432).
+#
+#   +0 auth        +5 hub        +10 firestore websocket  +15 hosting
+#   +1 firestore   +6 logging    +11 Metro (METRO_OFFSET) +16 apphosting
+#   +2 functions   +7 pubsub     +12 ┐                    +17 dataconnect
+#   +3 storage     +8 eventarc   +13 ├ the caller's       +18 dataconnect postgres
+#   +4 ui          +9 database   +14 ┘                    +19 tasks
+#
+# 12-14 stay the caller's: SimonSays' acquire callers put their verify dev
+# server / CDP / api / vite there (simon-says bin/lease-offsets.test.mjs,
+# web/playwright.config.ts, bin/seeded-explore). Everything else in the block
+# is harbormaster's. A reserved (`allocate`) block is the caller's whole, bar
+# Metro: this table is only what an `acquire`/`exec` suite binds.
 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)
+                 "firestore_websocket": 10,
+                 "hosting": 15, "apphosting": 16, "dataconnect": 17,
+                 # dataconnect's second port: its PGlite postgres (CLI default 5432).
+                 "dataconnect_postgres": 18,
+                 "tasks": 19}
+METRO_OFFSET = 11        # Metro/Expo dev-server port in the block
+CALLER_OFFSETS = (12, 13, 14)   # never bound by a suite; the acquire caller's own
+# What firebase-tools starts for a product named at the top level of
+# firebase.json OR under `emulators` (its filterEmulatorTargets), and what it
+# starts whether or not the file names it. eventarc/tasks are service emulators
+# to the CLI too, but bound only for a functions backend — so they're implicit.
+SERVICE_EMULATORS = ("auth", "firestore", "functions", "storage", "pubsub",
+                     "database", "hosting", "apphosting", "dataconnect")
+IMPLICIT_EMULATORS = ("hub", "ui", "logging", "eventarc", "tasks")
+# The second port an emulator binds: (emulator, its config key) -> offset name.
+SECOND_PORTS = {("firestore", "websocketPort"): "firestore_websocket",
+                ("dataconnect", "postgresPort"): "dataconnect_postgres"}
+# Keys under `emulators` that are settings, not emulators with a port of their
+# own (`extensions` runs inside the functions emulator).
+NOT_EMULATORS = ("singleProjectMode", "extensions")
+# Android emulator console ports (2026-10-21). An emulator instance binds an
+# even console port and adb = console + 1; adb discovers emulators only on
+# 5554..5584 (sixteen instances) unless ADB_LOCAL_TRANSPORT_MAX_PORT is raised,
+# and the emulator accepts -port up to 5682. A lease taken with --android gets
+# one pair from this range, leased like a block: unique among live leases,
+# both ports free when handed out, released with the lease.
+ANDROID_CONSOLE_FIRST = int(os.environ.get("FBPORTS_ANDROID_CONSOLE_FIRST", "5554"))
+ANDROID_CONSOLE_LAST = int(os.environ.get("FBPORTS_ANDROID_CONSOLE_LAST", "5584"))
 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")
@@ -358,12 +415,48 @@ def _block_ports(base):
 
 
 def _service_ports(ports):
-    return {s: p for s, p in ports.items() if s not in ("ui", "hub", "logging")}
+    return {s: p for s, p in ports.items()
+            if s not in IMPLICIT_EMULATORS and s not in ("metro", "android_console", "android_adb")}
+
+
+# A value that names a LEASED port: `{port:firestore}` becomes this lease's
+# firestore port. The caller cannot know its ports before the lease, and an
+# app whose functions read their own variable for the emulator (Tapuat's
+# admin.ts: `127.0.0.1:${EMULATOR_PORT_FIRESTORE || "8080"}`, unconditionally)
+# otherwise talks to whatever holds the default — on simon-linux-1, nothing;
+# every callable 500'd (run 20261021-131438-exploration-everyday-user). An
+# unknown service is left as written, so a typo shows in the app's own error.
+_PORT_REF = re.compile(r"\{port:([a-z_]+)\}")
+
+def _android_env(ports):
+    """What a caller (and a --spawn'd process) is told about a leased Android
+    pair: boot with `emulator -port $ANDROID_CONSOLE_PORT`, talk to it as
+    $ANDROID_SERIAL (adb's name for the instance; adb itself honours it)."""
+    c = ports["android_console"]
+    return {"ANDROID_CONSOLE_PORT": str(c), "ANDROID_ADB_PORT": str(ports["android_adb"]),
+            "ANDROID_SERIAL": f"emulator-{c}"}
+
+
+def _with_ports(env, ports):
+    return {k: _PORT_REF.sub(lambda m: str(ports[m.group(1)]) if m.group(1) in ports else m.group(0), v)
+            for k, v in env.items()}
+
+
+def _emulator_targets(cfg):
+    """The service emulators firebase-tools would start for this config with no
+    --only: a product named at the top level or under `emulators`."""
+    emu = cfg.get("emulators") or {}
+    return [s for s in SERVICE_EMULATORS if s in cfg or s in emu]
 
 
 def _write_injected_config(cwd, ports, only=None):
-    """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.
+    """Put EVERY port the CLI may bind for this config on the block: each
+    emulator the config starts (a product at the top level or under
+    `emulators`), the ones the CLI starts unasked (IMPLICIT_EMULATORS), and the
+    second ports (SECOND_PORTS). Never adds a service emulator the project
+    doesn't use — an `emulators.<x>` entry makes the CLI start <x>. A declared
+    emulator with no offset is refused by name (ValueError): no lease, no port.
+    Returns the temp config basename.
 
     With an --only that leaves hosting out, the `hosting` block goes too: no
     emulator a lease starts serves it, and firebase-tools still READS it. A
@@ -376,17 +469,23 @@ def _write_injected_config(cwd, ports, only=None):
     if only and "hosting" not in only:
         cfg.pop("hosting", None)
         emu.pop("hosting", None)
-    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]
+    known = set(SERVICE_EMULATORS) | set(IMPLICIT_EMULATORS) | set(NOT_EMULATORS)
+    unknown = [k for k, v in emu.items() if k not in known and isinstance(v, dict)
+               and (not only or k in only)]
+    if unknown:
+        raise ValueError(f"firebase.json declares emulator(s) harbormaster has no port for: "
+                         f"{', '.join(unknown)} — add them to BLOCK_OFFSETS")
+    if "ui" in emu and isinstance(emu["ui"], dict):
+        emu["ui"]["enabled"] = True        # declared: wanted on (as before 0.15.0)
+    for svc in [*_emulator_targets(cfg), *IMPLICIT_EMULATORS]:
+        if not isinstance(emu.get(svc), dict):
+            emu[svc] = {}
+        emu[svc]["port"] = ports[svc]
+    for (svc, key), name in SECOND_PORTS.items():
+        # Only on an emulator that starts: a key under emulators.<svc> would
+        # otherwise make the CLI start <svc>.
+        if svc in emu:
+            emu[svc][key] = ports[name]
     emu["singleProjectMode"] = True
     tmp = f".firebase.brokered-{ports['firestore']}.json"
     (Path(cwd) / tmp).write_text(json.dumps(cfg, indent=2))
@@ -783,6 +882,26 @@ class Broker:
                 return base
         raise RuntimeError("emulator port pool exhausted")
 
+    def _free_android_console(self):
+        """An even console port in ANDROID_CONSOLE_FIRST..LAST whose pair
+        (console, console + 1 = adb) no live lease holds and nothing listens
+        on. Called under self.lock, so two callers never draw one pair; the
+        listen check keeps a hand-booted emulator's pair out of it."""
+        used = {l["ports"].get("android_console") for l in self.leases.values()
+                if isinstance(l.get("ports"), dict)}
+        first = ANDROID_CONSOLE_FIRST + (ANDROID_CONSOLE_FIRST % 2)   # consoles are even
+        for console in range(first, ANDROID_CONSOLE_LAST + 1, 2):
+            if console in used:
+                continue
+            if not _port_open(console) and not _port_open(console + 1):
+                return console
+        raise RuntimeError(f"android console pool exhausted ({first}-{ANDROID_CONSOLE_LAST}: "
+                           f"every pair is leased or listening)")
+
+    def _lease_android(self, ports):
+        console = self._free_android_console()
+        ports["android_console"], ports["android_adb"] = console, console + 1
+
     def _boot(self, cwd, block, only, project_id, label, on_spawn=None, extra_env=None):
         all_ports = _block_ports(block)
         tmp = _write_injected_config(cwd, all_ports, only)
@@ -791,7 +910,12 @@ class Broker:
         # 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")}
+        # Not waited on: the ones the CLI starts on its own terms (eventarc and
+        # tasks only for a functions backend), and hosting with no hosting
+        # config, which the CLI skips with a warning.
+        has_hosting = "hosting" in json.loads((Path(cwd) / tmp).read_text())
+        check = {s: p for s, p in run_ports.items()
+                 if s not in IMPLICIT_EMULATORS and (s != "hosting" or has_hosting)}
         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
@@ -814,9 +938,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 = {**os.environ, **project_env(cwd), "TMPDIR": str(suite_tmp)}
+        spawn_env = {**os.environ, **_with_ports(project_env(cwd), all_ports), "TMPDIR": str(suite_tmp)}
         if extra_env:
-            spawn_env.update({str(k): str(v) for k, v in dict(extra_env).items()})
+            spawn_env.update(_with_ports({str(k): str(v) for k, v in dict(extra_env).items()}, all_ports))
         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:
@@ -920,7 +1044,9 @@ class Broker:
                 actions.append(f"tree sweep killed {sorted(killed)}")
         # Port sweep: every port the lease covers. rec["ports"] catches legacy
         # records; the block range catches everything else (metro, websocket).
-        ports = {v for v in (rec.get("ports") or {}).values() if isinstance(v, int)}
+        android = {v for k, v in (rec.get("ports") or {}).items()
+                   if k in ("android_console", "android_adb") and isinstance(v, int)}
+        ports = {v for v in (rec.get("ports") or {}).values() if isinstance(v, int)} - android
         if rec.get("block"):
             ports |= {rec["block"] + off for off in range(BLOCK)}
         if ports:
@@ -933,6 +1059,16 @@ class Broker:
                            if port in ports and pids)
             if still:
                 actions.append(f"ports STILL HELD after sweep: {still}")
+        # The Android pair is OUTSIDE the pool, where a hand-booted emulator
+        # lands by default (5554). So it is not port-swept: what the lease
+        # spawned died with its group and recorded tree above; anything still
+        # on the pair is reported, never signalled (the world sweep evicts it
+        # only if it is provably ours).
+        if android:
+            held = {port: pids for port, pids in _listeners().items() if port in android and pids}
+            if held:
+                actions.append(f"android ports still held (not signalled): "
+                               + ", ".join(f"{p} by {sorted(v)}" for p, v in sorted(held.items())))
         tmp = rec.get("tmp_config")
         if tmp and rec.get("cwd") and (Path(rec["cwd"]) / tmp).exists():
             (Path(rec["cwd"]) / tmp).unlink()
@@ -949,11 +1085,15 @@ class Broker:
             print(f"teardown {lid}: " + "; ".join(actions), flush=True)
 
     def acquire(self, cwd, owner_pid, owner_start=None, only=None, ttl=DEFAULT_TTL,
-                metro=False, sim=False, sim_device=None, sim_runtime=None, env=None):
+                metro=False, sim=False, sim_device=None, sim_runtime=None, env=None,
+                android=False):
         with self.lock:
             base = self._free_block()
             lid = f"run:{uuid.uuid4().hex[:12]}"
             project_id = _firebaserc_project(cwd)
+            # Drawn before the boot, so an exhausted range costs no suite; the
+            # lock is held throughout, so nobody else can draw it meanwhile.
+            android_console = self._free_android_console() if android else None
 
             def on_spawn(spawn_pid, spawn_tmp, spawn_log):
                 # Provisional record, saved before the readiness wait: a daemon
@@ -984,6 +1124,8 @@ class Broker:
             # collision-free by construction and needs no health check.
             if metro or sim:
                 ports["metro"] = base + METRO_OFFSET
+            if android_console:
+                ports["android_console"], ports["android_adb"] = android_console, android_console + 1
             sim_udid = sim_name = None
             if sim:
                 sim_name = lid.replace(":", "-")
@@ -1011,7 +1153,7 @@ class Broker:
 
     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):
+                 spawn=None, spawn_cwd=None, android=False):
         with self.lock:
             base = self._free_block()
             lid = f"alloc:{uuid.uuid4().hex[:12]}"
@@ -1023,6 +1165,10 @@ class Broker:
             # owns just the port + sim.
             if metro or sim:
                 ports["metro"] = base + METRO_OFFSET
+            # --android: an emulator console/adb pair, outside the pool (adb
+            # only discovers 5554..5584) but leased the same way.
+            if android:
+                self._lease_android(ports)
             sim_udid = sim_name = None
             if sim:
                 sim_name = lid.replace(":", "-")
@@ -1040,6 +1186,8 @@ class Broker:
                        "FBPORTS_LEASE_ID": lid}
                 if ports.get("metro"):
                     env["METRO_PORT"] = str(ports["metro"])
+                if ports.get("android_console"):
+                    env.update(_android_env(ports))
                 if sim_udid:
                     env["DETOX_UDID"] = sim_udid
                     env["DETOX_SIM_NAME"] = sim_name
@@ -1055,8 +1203,9 @@ class Broker:
                     if sim_udid:
                         _sim_teardown(sim_udid)
                     raise
+            android_note = f" android {ports['android_console']}" if android else ""
             print(f"leased {lid} ({label or 'no label'}): base {base}"
-                  f"{f' sim {sim_name}' if sim_udid else ''}"
+                  f"{f' sim {sim_name}' if sim_udid else ''}{android_note}"
                   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,
@@ -1228,9 +1377,14 @@ class Broker:
         for l in self.leases.values():
             if l.get("block"):
                 leased_ports |= {l["block"] + off for off in range(BLOCK)}
+        for l in self.leases.values():
+            for k in ("android_console", "android_adb"):
+                if isinstance((l.get("ports") or {}).get(k), int):
+                    leased_ports.add(l["ports"][k])
         pool_end = POOL_BASE + POOL_BLOCKS * BLOCK
         for port, pids in _listeners().items():
-            if POOL_BASE <= port < pool_end and port not in leased_ports:
+            in_android = ANDROID_CONSOLE_FIRST <= port <= ANDROID_CONSOLE_LAST + 1
+            if (POOL_BASE <= port < pool_end or in_android) and port not in leased_ports:
                 for pid in pids:
                     if pid not in lease_pids:
                         cmd = _proc_field(pid, "command=")[:200]
@@ -1414,13 +1568,14 @@ class _Handler(http.server.BaseHTTPRequestHandler):
                                                  d.get("only"), d.get("ttl", DEFAULT_TTL),
                                                  d.get("metro", False), d.get("sim", False),
                                                  d.get("sim_device"), d.get("sim_runtime"),
-                                                 d.get("env")))
+                                                 d.get("env"), d.get("android", False)))
             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")))
+                                                  d.get("spawn"), d.get("spawn_cwd"),
+                                                  d.get("android", False)))
             if self.path == "/release":
                 return self._send(200, b.release(d.get("leaseId")))
             if self.path == "/release-owned":
@@ -1712,9 +1867,14 @@ def _print(out, fmt):
             if svc == "metro":
                 print(f"export METRO_PORT={port}")            # Expo/Metro dev server + Detox bundle URL
                 continue
+            if svc in ("android_console", "android_adb"):
+                continue                                      # below, as ANDROID_*
             if svc in std:
                 print(f"export {std[svc]}=127.0.0.1:{port}")
             print(f"export EMULATOR_{svc.upper()}_PORT={port}")
+        if ports.get("android_console"):
+            for k, v in _android_env(ports).items():
+                print(f"export {k}={v}")
         if sim:
             print(f"export DETOX_UDID={sim['udid']}")          # Detox targets this simulator by UDID
             print(f"export DETOX_SIM_NAME={sim['name']}")
@@ -1786,7 +1946,8 @@ def main():
                                              "metro": "metro" in flags, "sim": "sim" in flags,
                                              "sim_device": opts.get("sim-device"),
                                              "sim_runtime": opts.get("sim-runtime"),
-                                             "env": dict(kv.split("=", 1) for kv in opts.get("fn-env", []))}), "acquire"), fmt)
+                                             "env": dict(kv.split("=", 1) for kv in opts.get("fn-env", [])),
+                                             "android": "android" in flags}), "acquire"), fmt)
     elif cmd == "down":
         if _up():
             out = _call("POST", "/release-owned", {"owner_pid": os.getppid(), "cwd": _resolve_cwd(opts)})[1]
@@ -1815,7 +1976,8 @@ def main():
                                              "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}),
+                                             "spawn_cwd": str(Path(opts["cwd"]).resolve()) if opts.get("cwd") else None,
+                                             "android": "android" in flags}),
                  "allocate")
         if fmt == "env":
             # Reserved block, nothing booted — emit only the dev-env extras (plus
@@ -1824,6 +1986,9 @@ def main():
             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("ports", {}).get("android_console"):
+                for k, v in _android_env(out["ports"]).items():
+                    print(f"export {k}={v}")
             if out.get("sim"):
                 print(f"export DETOX_UDID={out['sim']['udid']}")
                 print(f"export DETOX_SIM_NAME={out['sim']['name']}")
@@ -1834,6 +1999,8 @@ def main():
         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"  android {out['ports']['android_console']}/{out['ports']['android_adb']}"
+                      if out.get("ports", {}).get("android_console") else "")
             extra += f"  spawned pid {out['spawnedPid']}" if out.get("spawnedPid") else ""
             print(f"{out['leaseId']}  base {out['base']}{extra}")
     elif cmd == "exec":
@@ -1851,7 +2018,12 @@ def main():
         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), only)
+        try:
+            tmp = _write_injected_config(cwd, _block_ports(base), only)
+        except ValueError as e:
+            _call("POST", "/release", {"leaseId": lid})
+            print(f"exec failed: {e}", file=sys.stderr)
+            sys.exit(1)
         try:
             run = ["firebase", "emulators:exec", "--config", tmp]
             if only:
@@ -1860,7 +2032,7 @@ def main():
             # The project's env beats the caller's AMBIENT env here: a key
             # exported in some shell for a one-off script is exactly what
             # harbormaster.env exists to keep out of the suite (project_env).
-            rc = subprocess.call(run, cwd=cwd, env={**os.environ, **project_env(cwd)})
+            rc = subprocess.call(run, cwd=cwd, env={**os.environ, **_with_ports(project_env(cwd), _block_ports(base))})
         finally:
             try:
                 _call("POST", "/release", {"leaseId": lid})
@@ -1941,6 +2113,8 @@ def main():
                 where += f" metro:{l['ports']['metro']}"
             if l.get("sim"):
                 where += f" sim:{l['sim'][:8]}"
+            if l["ports"].get("android_console"):
+                where += f" android:{l['ports']['android_console']}"
             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())

package/package.json

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