Two Simlock instances on one machine keep their Android emulators apart #1189

Request: #264

Problem

In the reporter's words (#264): "The Android driver's startup sweep announces every console port in 5586–5682 to this instance's adb server, as ADR 0001's correction prescribes. It assumes the range belongs to one instance. With two Simlock instances on one machine, which docs/CLI.md and docs/CONFIGURATION.md document, each instance attaches the other's emulators to its own adb server."

One worker per user is already the rule (ADR 0034), but nothing enforces it once SIMLOCK_HOME points a second worker at another folder. The website still suggests it for "a separate install". Two workers with real drivers then share the emulator ports, the emulators and the iOS runtimes. An agent leased from the second worker sees, and can drive, emulators leased to agents of the first:

$ adb devices                      # agent-2, leased from the second worker (adb server 5039)
emulator-5586  device              # the first worker's emulator, leased to agent-1
emulator-5590  device              # agent-2's own

The slow e2e lane hits the same thing: it starts its own real-driver worker under a temporary SIMLOCK_HOME, next to the maintainer's own worker.

Who it is for

A user on one Mac who starts a second Simlock worker with another SIMLOCK_HOME, by mistake or by following the old docs. And the maintainer, who runs the slow e2e lane on a Mac where their own worker runs.

Outcome

A second worker with real drivers for the same user refuses to start, and says which worker holds the machine and how to stop it. It never touches the first worker's emulators. Test workers with fake drivers still run side by side, as many as the suite wants.

How it works for the user

flowchart TD
  A["simlock daemon start (SIMLOCK_HOME=~/.simlock-b)"] --> B{"another worker of this user with real drivers alive?"}
  B -- no --> C["starts as today"]
  B -- "yes, same folder" --> D["'already running', as today"]
  B -- "yes, other folder" --> E["refuses, naming pid and folder; exit 1"]
  F["scripts/slow-e2e.sh"] --> G{"a worker holds the lock?"}
  G -- yes --> H["exits 69 (not fit), naming it and how to stop it"]
  G -- no --> I["runs as today"]

Before:

$ SIMLOCK_HOME=~/.simlock-b simlock daemon start
Daemon running (pid 5150)

After:

$ SIMLOCK_HOME=~/.simlock-b simlock daemon start
The daemon could not start: another Simlock worker runs for this user (pid 4242, folder /Users/me/.simlock, since 2026-11-02T09:12:03.000Z); stop it first: SIMLOCK_HOME=/Users/me/.simlock simlock daemon stop
$ echo $?
1

Examples

What could go wrong

• A worker crashes and its pid is reused by another program: the next start refuses until that program ends. Unlikely; a reboot clears it.
• A worker that cannot create its lock folder in /tmp refuses to start; the message names the folder.
• Two OS users on one Mac can still each run a worker (known gap, unchanged).

Words used

• worker: the Simlock daemon that owns devices, e.g. the one simlock daemon start runs in ~/.simlock.
• real drivers: the iOS and Android drivers a worker finds on the machine; the opposite is a fake driver set from SIMLOCK_DRIVERS_MODULE, used by tests.
• worker lock: the folder holding owner.json (pid, folder, start time): /tmp/simlock-<uid>/worker.lock/ on macOS and Linux, e.g. /tmp/simlock-501/worker.lock/owner.json; <os.tmpdir()>\simlock\worker.lock\ on Windows.
• stale lock: a worker lock whose pid is no longer running.
• folder: a worker's data directory, ~/.simlock or $SIMLOCK_HOME.

Non-goals

• Two OS users on one Mac (ADR 0034 keeps it a known gap).
• Attaching only this worker's own emulators in the sweep: with one worker per user it is not needed.
• Removing SIMLOCK_HOME from every user page (ADR 0034's own work); only the "separate install" passage goes here.
• Checking a reused pid's command line.

Completion conditions

• A second real-driver worker of the same user with another folder refuses to start with the message above, exit 1, and starts no driver.
• The first worker's stop frees the lock; a crashed worker's lock is taken over at the next start.
• pnpm test:e2e still runs its files in parallel and passes.
• scripts/slow-e2e.sh exits 69 naming the holder while a worker outside the lane holds the lock.
• worker/running-the-daemon.mdx no longer offers a separate install with SIMLOCK_HOME.

Open questions

Decisions

• ADR 0059 — A worker with real drivers holds a per-user lock (PR docs(adr): 0059 a worker with real drivers holds a per-user lock (#1189) #1190): who takes the lock, where it lives, who wins, when it is released, and the slow lane's exit 69.

Shared values

none

Behaviours

Tasks

• A second real-driver worker of the same user refuses to start, naming the first #1191 A second real-driver worker of the same user refuses to start — a user's second worker refuses and names the first; the slow lane refuses to run and says to stop the worker. Risk: a worker refuses to start with no other worker running (a stale lock not taken over).

Every Completion condition is delivered by #1191.

Open work in the same area: bugs #1168 and #1169 change Simlock's adb server, not driver discovery or the daemon start; no Depends on. ADR 0034's issue #700 is closed.

Written by an agent.