A standalone worker serves agent-device on localhost by default #957

Part of #952.

Scope

A standalone worker serves agent-device on 127.0.0.1:4701 with no config set. On a worker with no gateway.url, http.enabled defaults to on, and agent-device is on unless capabilities.agent-device.enabled is set. With the profile from #956, an agent on the Mac connects and works with no operator step. A Mac without agent-device is not flagged as a problem. Joined workers and gateways keep today's defaults. The test harnesses keep HTTP and agent-device off unless a test asks for them. The docs drop the enable steps.

In short

After an upgrade, a standalone worker listens on 127.0.0.1:4701. The API and the console both still ask for a token. The worker also starts agent-device when the agent-device command is on PATH, and writes the profile from #956. A value the operator set wins. If agent-device was never set and is not installed, its capability is off: simlock doctor stays clean and the console shows no warning. Any other agent-device trouble stays loud, as today.

flowchart LR
  L[config load] --> J{gateway.url set?}
  J -->|no: standalone| D1["http.enabled default true; agent-device on unless set (changed)"]
  J -->|yes: joined| D2[both off, as today]
  D1 --> S{agent-device command found?}
  S -->|yes| R[daemons start; profile written]
  S -->|no, never set| O["capability off, no finding (changed)"]
  S -->|no, set true| U[unavailable + finding, as today]

Defaults:

User session, a fresh standalone worker with agent-device on PATH and no config.json:

$ simlock daemon start
$ agent-device connect --remote-config ~/.simlock/agent-device-profile.json --session "$CLAUDE_CODE_SESSION_ID"
$ agent-device open --platform ios --session "$CLAUDE_CODE_SESSION_ID"

Today the connect fails, because there is no profile file and nothing listens on 4701. After this task the open leases and opens a simulator.

If this goes wrong, a user notices one of three things: the worker still needs config set first; a joined worker refuses to start with the http.enabled error; or doctor and the console complain on a Mac without agent-device.

Technical spec

Commit for every source: cac23e033f94ad87aee0b92e130190094df6d93a.

Facts

Modules touched

Searches: http.enabled readers, enabled: false in defaultConfig, OptionalModuleDefinition, agentDeviceFindings, module-unavailable, startDaemon( (F15), seedConfig, http: in e2e/.

flowchart LR
  C["core/config.ts (changed: http default by gateway.url)"] --> H["modules host/types (changed: on-by-default for standalone, set-or-default bit)"]
  DEF["agent-device/definition.ts (changed: declares on-by-default)"] --> H
  H --> AD["agent-device worker + availability (changed: not-found by default → off)"]
  AD --> DR[core/doctor.ts]
  HR["e2e/helpers/env.ts, e2e/console/fixtures.ts, in-process test helpers (changed: pin off)"] --> C

Files: src/modules/types.ts (an optional definition may declare enabledByDefault: "standalone-worker", plain data), src/core/config.ts (after the merge: the http.enabled default follows gateway.url; for every module entry that declares enabledByDefault and whose enabled no layer sets, a worker with no gateway.url gets enabled: true; loadConfig's callers also get the set of module names whose enabled came from a default, outside Config; core never names agent-device), src/daemon/main.ts and src/modules/host.ts (pass that set to the module, e.g. enabledByDefault: boolean on WorkerContext), src/agent-device/definition.ts, src/agent-device/worker.ts and host/availability-findings.ts or agentDeviceCapabilitySource (not-found while on by default → off), e2e/helpers/env.ts, e2e/console/fixtures.ts, the F15 test helpers, e2e/slow-agent-device.test.ts and e2e/helpers/agent-device.ts, and the F16 tests. Manuals: src/http/AGENTS.md (State table), src/agent-device/AGENTS.md ("Off unless … (false)"), src/modules/AGENTS.md, the config.ts:937-940 comment. Website: the F19 pages.

Contract and event changes

None. config.get returns Config unchanged (src/daemon/dispatcher.ts:879), so it shows the resolved enabled (true on a standalone worker that never set it). The set of defaulted module names is not part of Config. No event.

Other code on the same state

Searches: readers of http.enabled (src/daemon/main.ts, requireJoinedWorkerHttpOff, requireGatewayHttp) and of capabilities.agent-device (module host, supervisor, doctor, status.get).

• requireJoinedWorkerHttpOff (F3): the default is false when gateway.url is set, so a joined worker never trips it; an explicit true still does.
• simlock config set writes only the key it is given, so the next start re-derives a default.
• A worker that later joins (gateway.url set) has both off at its next start, and A standalone worker writes a private agent-device profile for local agents #956 withdraws the profile.
• A standalone worker writes a private agent-device profile for local agents #956 writes the profile when HTTP is on and agent-device is turned on. After this task that includes a standalone Mac where agent-device is on by default but not installed: the profile and its token are written there too (ADR 0046 Consequences), and do nothing until agent-device is installed and the worker restarts.

Failure modes

This task writes no state. Two daemons on one machine with default HTTP clash as in the taken row, which is why the harnesses pin HTTP off.

Rules in play

• ADR 0046 §1: the defaults, the set-or-default bit outside the contract, and quiet only for not-found, exactly as written. It narrows ADR 0023 §1 and ADR 0030 §2 for this module only.
• ADR 0039 "invalid … gateway.url set and http.enabled: true": kept; a default never produces it.
• ADR 0011 §3 "the console is served whenever HTTP is": the console now opens on a standalone worker by default and still asks for a token.
• Architecture: core names no agent-device; the on-by-default flag is a neutral member of the module definition.
• Documentation rule 9: the F19 pages change in this PR.
• Slow lane only where the fast lane cannot prove it: one case, the real CLI with the profile.

Tests

Seams: loadConfig (model src/core/config.test.ts); a whole worker daemon (src/daemon/main.test.ts describe("doctor.run") for findings, src/agent-device/edge.test.ts "a worker's capabilities in status.get" for the capability); slow lane e2e/slow-agent-device.test.ts.

• A worker with no config file loads with http.enabled true. Cases: standalone → true; joined (gateway.url and gateway.token set) → false; gateway → true; standalone with http.enabled: false in the file → false; joined with http.enabled: true in the file → refused with ADR 0039's message. Extends config.test.ts:123, :1663 and :1835.
• A standalone worker with no capabilities.agent-device section runs agent-device; a joined worker and a gateway do not. Cases: no section, standalone → available; enabled: false → off; no section, joined → off. Extends edge.test.ts:4271 and definition.test.ts:35.
• agent-device trouble while on by default (doctor.run, extends the main.test.ts:3366 cases): not found, never set → no agent-device finding, capability off; not found, set true → today's finding, unavailable; wrong version, never set → today's finding, unavailable.
• A standalone worker on its defaults serves agent-device end to end (in-process startDaemon with the fake agent-device, model edge.test.ts): config sets only http.port (a free port) and capabilities.agent-device.command (the fake), no enabled keys → HTTP listens, config.get shows both enabled true, the A standalone worker writes a private agent-device profile for local agents #956 profile is written, and GET /v1/agent-device/health with the profile's token answers 200. The same with gateway.url and gateway.token set → no HTTP, no profile, capability off.
• The harnesses give HTTP and agent-device to no test that does not ask: the fake and real seedConfig bases and the console lane config set http.enabled: false and capabilities.agent-device.enabled: false, which a test's own values override; every F15 helper does the same. A fast e2e test that sets http.port and uses HTTP sets enabled: true. The fast e2e files the change touches, and the F15 files, pass.
• Slow lane, e2e/slow-agent-device.test.ts: a new case starts the pinned agent-device CLI with no AGENT_DEVICE_DAEMON_AUTH_TOKEN and runs connect --remote-config <data dir>/agent-device-profile.json --session <name>, open --platform ios, install of the fixture app (an upload) and close, each with --session. The lease's owner is the profile token. The existing token cases keep passing on the same daemon.

Done when

• pnpm exec vitest run --project unit <file> passes for src/core/config.test.ts, src/agent-device/definition.test.ts, src/agent-device/edge.test.ts and src/daemon/main.test.ts with the lines above. The doctor.run cases wait for the capability to leave starting before reading it.
• pnpm test:e2e passes for the e2e files the harness change touches. CI is green.
• Slow lane: scripts/slow-e2e.sh e2e/slow-agent-device.test.ts passes, including the profile case. It needs the "agent-device through simlock" machine.
• The website build passes. using-devices/agent-device.mdx says a standalone worker serves agent-device by default, drops the config set steps, and says to restart the worker after installing agent-device. The other F19 pages state the new defaults.

Out of scope

• The profile file: A standalone worker writes a private agent-device profile for local agents #956.
• Running without HTTP when 4701 is taken (ADR 0046 Alternatives).
• The shipped agent instructions (Add simlock instructions: the rules an agent must follow, printable and served over MCP #147).

Depends on

• A standalone worker writes a private agent-device profile for local agents #956

Written by an agent.