Skip to content

Every simlock command runs against a remote farm with --url or SIMLOCK_URL and a token #1641

Open

Description

@V3RON

Part of #1635.

Scope

With --url or SIMLOCK_URL and a token, every simlock command whose work is the daemon's runs against a standalone worker or a gateway from a machine with no daemon, with the token's role, and never starts a local daemon or falls back to an agent session. simlock simctl and simlock adb run on the lease's worker through device.exec, picking the lease this CLI's requester took. events --since replays from the farm, and baseline list/remove follow the farm's mode. Commands that act on this machine (daemon *, config set, setup) exit 2 in remote mode. A remote simlock lease without SIMLOCK_AGENT_ID or an agent session prints one notice. A held lease still ends on a dropped connection as today; the next task makes it reconnect.

A user would notice: a command that reaches this machine's daemon while --url is set, or the farm while --local is set; a local daemon started in remote mode; simctl acting on another agent's device; or any command behaving differently with no URL set.

Technical spec

Commit 1cd9315.

Rows

Behaviours: B6, B7
Interfaces: I6, I7, I11
Existing code: X9, X10, X11, X12, X13, X14, X25, X26, X27, X19 (reference/cli.mdx, using-devices/remote-agents.mdx, using-devices/ci.mdx)

Facts

# Fact Source
F1 Global flags (--token, --gateway, --local) are taken out of the whole argv before routing src/cli/index.ts:69-101
F2 The CLI's credential order is --token, SIMLOCK_ADMIN_TOKEN, the admin.token file, with an agent fallback and a notice src/cli/connect.ts:39-79
F3 Gateway passthrough picks its lease with resolveRemoteLeaseId and sends device.exec, with requesterId only for an admin src/cli/commands/passthrough.ts:49-80, src/cli/remote-lease.ts:44-50
F4 The lease the CLI requests carries the CLI's requester id src/cli/commands/lease.ts:101, :213
F5 The CLI's requester id falls back to the process id when neither SIMLOCK_AGENT_ID nor a session variable is set src/cli/environment.ts:349, src/agent-identity/index.ts:30-37
F6 events without --follow connects with launch: false and reads history.db when no daemon answers src/cli/commands/events.ts:1, :29

Modules touched

src/cli/ (index.ts (global --url, the remote gate), tree.ts (CommandContext carries the URL and token), commands/rotate.ts (its default lease follows I11), environment.ts (remote connector, SIMLOCK_URL/SIMLOCK_TOKEN for all), connect.ts, types.ts, remote-lease.ts, commands/passthrough.ts, commands/events.ts, commands/baseline.ts, commands/tunnel.ts (URL from the context), commands/lease.ts (the notice), AGENTS.md), the new slow-lane test e2e/slow-remote-cli.test.ts, and the website pages reference/cli.mdx, using-devices/remote-agents.mdx, using-devices/ci.mdx. Searches: connectDaemonClient, connectAdmin, connectExistingAdmin, tunnelUrl, tunnelToken, daemon.mode === "gateway", daemonHome.role, GATEWAY_EXEMPT_PATHS, selectOnlyLease, resolveRemoteLeaseId.

Rules in play

  • ADR 0081 §3: remote by URL; local-machine commands refused; simctl/adb as device.exec.
  • ADR 0005 §19c: through a remote farm passthrough is device.exec, the refusal list stays with the driver.
  • src/cli/AGENTS.md: the router loads nothing (lazy-loading.test.ts): the remote gate and --url parsing live in the router's static imports only as values it already may import; no decision logic beyond the connect choice.
  • src/cli/AGENTS.md Output: errors as one JSON line; remote text through escapeControl.
  • Documentation rule 9: the three website pages; ci.mdx replaces curl steps with commands and sets SIMLOCK_AGENT_ID.

Tests

Seam: runCli with a fake environment whose WebSocket connector reaches a fake session (models: src/cli/index-exit-codes-passthrough.test.ts, src/cli/index-admin-auto-launch.test.ts, src/cli/passthrough.test.ts).

  • B6: remote mode selection: each row of both Examples tables; --token beats SIMLOCK_TOKEN; SIMLOCK_ADMIN_TOKEN not sent; a rejected token (no fallback, no notice); tunnel --url still reaches its URL; nothing launched
  • B7: each command in remote mode: status, lease, lease renew, release, list, catalog, doctor, token list (agent and operator); whoami; baseline list and remove on a gateway; each of I7's commands; events --since 1h; simctl listapps on a worker-mode farm; adb shell echo --stdin; each I11 case, rotate included; simlock lease with and without SIMLOCK_AGENT_ID

Done when

  • pnpm test:changed passes, with every Tests line above as a test, and every CLI test with no URL set passes unchanged.
  • pnpm check passes, lazy-loading.test.ts included.
  • On a Mac with an iOS runtime: scripts/slow-e2e.sh e2e/slow-remote-cli.test.ts passes. With SIMLOCK_URL set to a worker's HTTP address (withHttpDaemon, e2e/helpers), an agent token and SIMLOCK_AGENT_ID, a CLI run from a data folder with no daemon does lease --platform ios --detach, status, simctl listapps and release <id>, each exits 0, and no second daemon starts.
  • The website build passes: pnpm --dir website install && pnpm --dir website build && node website/scripts/check-openapi.mjs.

Out of scope

Depends on

Written by an agent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    task:readySpec checked. An agent may implement it once its Depends on allow.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions