One Simlock instance per host #700

Request: none

Problem

Today every SIMLOCK_HOME is a separate Simlock. A user can run several workers on one machine, each with its own registry, devices and adb server. None of them can see the others:

• component remove counts only its own devices, so it can remove a runtime another worker still uses.
• Two workers can enrol the same physical device, and each release uninstalls the apps the other installed.
• A console port one worker handed out but has not booted yet reads free to another.

iOS runtimes belong to the whole machine (CoreSimulator keeps one copy in /Library/Developer/CoreSimulator), so no per-folder setup can isolate them. The planned disk lifecycle feature (garbage collection of runtimes, system images and devices with a disk budget) needs one owner of what Simlock installs.

The gateway and the worker are told apart by a mode config key, and running both on one Mac needs two SIMLOCK_HOMEs.

Who it is for

A developer or CI operator who runs a Simlock worker for coding agents on a machine, and sometimes a gateway in front of several workers.

Outcome

• A user runs one worker, always in ~/.simlock. A second worker for the same user cannot start.
• A gateway always lives in ~/.simlock/gateway. The folder decides what a daemon is; there is no mode key.
• On a machine with one daemon, every command reaches it with no flag. On a machine with both, plain commands reach the worker and --gateway reaches the gateway. --local always reaches the worker, which is how a worker is added to a machine that got its gateway first.
• A worker's HTTP listens on 4701 by default and a gateway's on 4700, so both fit on one machine with defaults.

How it works for the user

flowchart TD
  A["simlock <command>"] --> B{--gateway or --local?}
  B -- "--gateway" --> G["gateway in ~/.simlock/gateway"]
  B -- "--local" --> W
  B -- no --> C{"a gateway is present<br/>and ~/.simlock/instance.json does not exist?"}
  C -- yes --> G
  C -- no --> W["worker in ~/.simlock<br/>(started if not running)"]
  W --> D{"worker refuses: only a gateway does this<br/>and a gateway is present?"}
  D -- yes --> E["same error, plus a hint to add --gateway"]

A gateway and a worker on one Mac, before and after:

# today
SIMLOCK_HOME=~/.simlock-gw simlock config set mode gateway
SIMLOCK_HOME=~/.simlock-gw simlock daemon start
SIMLOCK_HOME=~/.simlock-gw simlock token create --role worker

# after
simlock --gateway daemon start
simlock --gateway token create --role worker
simlock worker drain 3f2a…
{"error":{"code":"UNSUPPORTED_IN_WORKER_MODE","message":"worker.drain acts on a gateway's workers, and this daemon is not a gateway. A gateway also runs on this machine: run the command again with --gateway."}}

A machine that runs only a gateway:

simlock --gateway config set http.port 4800
simlock daemon start          # no flag: only a gateway lives here, so this starts it
Daemon running
Console: http://127.0.0.1:4800/
simlock status --json | jq .daemon.mode
"gateway"

The old key, after:

simlock config set mode gateway
{"error":{"code":"USAGE","message":"Invalid config after setting mode: \"mode\" is no longer a config key. A daemon started with --gateway is a gateway; any other is a worker. Remove \"mode\" from config.json."}}

Examples

Which daemon a command reaches, with no --gateway flag:

With --gateway:

What could go wrong

• A command reaches the wrong daemon: the user sees a worker's answer where they expected the gateway's. Unlikely; the flag always wins.
• On a gateway-only machine, a plain command starts an empty worker. Unlikely; the table above prevents it.
• A setup that relied on SIMLOCK_HOME or mode stops working. Certain, accepted: Simlock has no users yet.
• Two macOS users on one machine each run a worker and share iOS runtimes. Not prevented; written down as a known gap.

Words used

• worker: the daemon that owns devices, e.g. the one in ~/.simlock.
• gateway: the daemon that fronts several workers and owns no devices, e.g. the one in ~/.simlock/gateway.
• root: ~/.simlock, or $SIMLOCK_HOME in tests. The worker lives in the root, the gateway in <root>/gateway.
• worker marker: <root>/instance.json. A worker writes it on its first start; config set alone never does.
• present gateway: <root>/gateway/instance.json or <root>/gateway/config.json exists. The gateway writes the first on its first start; simlock --gateway config set writes the second. An empty gateway folder is not one.
• gateway-only command: one a worker refuses with UNSUPPORTED_IN_WORKER_MODE, e.g. simlock worker drain.

Non-goals

• Several OS users on one machine, each with a worker (known gap).
• One daemon that is both gateway and worker.
• Moving data from an old SIMLOCK_HOME or an old mode key. No migration.
• The disk lifecycle feature itself. It depends on this one.
• A new lock: the existing socket claim is what refuses a second worker.

Completion conditions

• A second worker for the same user cannot start: it finds the running one at ~/.simlock/daemon.sock and says so.
• simlock --gateway daemon start starts a gateway in ~/.simlock/gateway while the worker in ~/.simlock keeps running, and simlock status / simlock --gateway status report worker / gateway.
• A gateway becomes present only through simlock --gateway daemon start or simlock --gateway config set; with no gateway present, any other --gateway command exits 2 with GATEWAY_NOT_PRESENT, and a --gateway mcp tool call fails with the same code.
• On a machine that got its gateway first, simlock --local daemon start starts a worker, and plain commands reach it afterwards.
• With defaults, a worker's HTTP listens on 4701 and a gateway's on 4700.
• A config that sets mode is rejected at load and by config set, with a message that says what replaces it.
• On a gateway-only machine, plain simlock daemon start and simlock status reach the gateway; no worker starts.
• With both, a gateway-only command without --gateway fails with the worker's refusal plus the --gateway hint.
• simlock --gateway mcp serves the gateway; plain simlock mcp follows the same folder choice as the CLI.
• The user docs no longer mention SIMLOCK_HOME, the mode key, or several instances on one machine.

Open questions

Decisions

• ADR 0034 — One worker per user, and the folder says what a daemon is: fixes the folders, removes mode, adds --gateway, the folder choice and the hint; keeps SIMLOCK_HOME for tests only. Draft in docs(adr): 0034 one worker per user, and the folder says what a daemon is #702.

Shared values

Tasks

flowchart LR
  T1["#708 The folder sets the role"] --> T2["#709 Commands find the daemon by folder"]

• The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 The folder sets the role: gateway in <root>/gateway, --gateway, mode removed — after it, a user starts a gateway beside their worker with simlock --gateway daemon start, and every command takes --gateway. Risk: every gateway test and doc changes at once; a missed spot leaves a gateway reading the worker's folder.
• Commands find the daemon by folder, and a gateway-only command sent to the worker says to add --gateway #709 Commands find the daemon by folder, and the --gateway hint — after it, a gateway-only machine needs no flag, and a gateway-only command sent to a worker says to add --gateway. Risk: a command on a gateway-only machine starts an empty worker.

Completion conditions → tasks:

• Second worker cannot start: already true (src/daemon/connection-host.test.ts:57); The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708's docs state it.
• --gateway daemon start beside a worker; status reports roles: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708.
• mode rejected: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708.
• Only --gateway daemon start creates a gateway; GATEWAY_NOT_PRESENT in CLI and MCP: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708.
• HTTP defaults 4700 / 4701: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708.
• Gateway-only machine needs no flag; --local adds a worker there: Commands find the daemon by folder, and a gateway-only command sent to the worker says to add --gateway #709.
• Hint on a gateway-only command: Commands find the daemon by folder, and a gateway-only command sent to the worker says to add --gateway #709.
• --gateway mcp: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708; plain mcp follows the folder choice: Commands find the daemon by folder, and a gateway-only command sent to the worker says to add --gateway #709.
• Docs: The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 (flags, folders, mode, SIMLOCK_HOME, the new code, ports), Commands find the daemon by folder, and a gateway-only command sent to the worker says to add --gateway #709 (the folder choice, --local, the hint).

Open work in the same area:

• daemon start reports DAEMON_CONNECTION_LOST for a daemon that never came up #684 (bug:ready) daemon start reports DAEMON_CONNECTION_LOST for a daemon that never came up: its fix classifies failures in AutoLaunchIpcConnector.connect, the function The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 changes. The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 Depends on daemon start reports DAEMON_CONNECTION_LOST for a daemon that never came up #684.
• The event history is a SQLite file, history.db #629 / PR feat(history): the event history is a SQLite file, history.db #694 (history.db): adds a line directly above void startDaemon() in the daemon entry, which The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 rewrites; the history file is per data directory, so a gateway's lands in <root>/gateway with no extra work. The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 Depends on The event history is a SQLite file, history.db #629.
• Projections: request, minute and device fact rows #630 / PR feat(history): project requests, minutes and device facts into history.db #695 (metrics config): rewrites loadConfig's defaults call and its mode === "gateway" branch, which The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 rekeys on the role, and adds mode: "gateway" config tests The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 must convert. The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 Depends on Projections: request, minute and device fact rows #630.
• usage.get and simlock stats from the projections #631–Console Usage page #634 (task:ready, the rest of Operational metrics kept over hours and shown in the console #623's stack; PR feat(stats): usage.get and simlock stats from the projections #711 for usage.get and simlock stats from the projections #631): add gateway tests and console fixtures that set mode: "gateway", which The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 refuses. The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 Depends on usage.get and simlock stats from the projections #631, GET /v1/stats and the simlock stats --csv ledger #632, Overview and Waiting: a range picker, wait p95, leases granted and three charts #633 and Console Usage page #634, and converts them once.
• Auth checks live in one module, src/auth #712 (task:draft, feature Sign in through a sign-in proxy, and know who did what #701, auth module): rewrites startDaemon around the mode branch The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 rekeys. Auth checks live in one module, src/auth #712 should list The folder sets the role: a gateway lives in <root>/gateway, --gateway reaches it, and the mode key is gone #708 under Depends on; noted on Auth checks live in one module, src/auth #712 for its spec session.
• PR docs(adr): 0033 a sign-in proxy is a second way to sign in, and auth is one module #704 also proposes an ADR numbered 0033; this feature's ADR is renumbered 0034 in docs(adr): 0034 one worker per user, and the folder says what a daemon is #702.
• Leftover .tmp files and .staging directories from a crashed write are never cleaned up #699 (bug:triage) leftover .tmp/.staging files: a fix that sweeps the root must also sweep <root>/gateway. Noted on Leftover .tmp files and .staging directories from a crashed write are never cleaned up #699; no Depends on.
• The Android startup sweep attaches another Simlock instance's emulators to this instance's adb server #264, After a restart, Android shutdown and reclaim can send emu kill or a snapshot load to an emulator that is not the device's #284 (bug:new) Android cross-instance bugs: still possible for test roots and a second OS user. No Depends on.

Written by an agent.