[V3RON]

Summary

device.exec lets an agent token run host tools such as xcrun simctl spawn as the daemon's user. That is by design. Two things were not: the exec child got the daemon's whole environment, so any secret in it was readable by every lease holder, and the docs never said an agent token equals code execution on the worker.

Now the child starts from a short allowlist of the daemon's variables, plus the driver's env, minus its unsetEnv. The website says what an agent token can do.

Changes

• src/daemon/exec-env.ts (new): execBaseEnvironment(env) keeps PATH, HOME, TMPDIR, user and shell keys, LANG, LC_*, TERM, DEVELOPER_DIR, the ANDROID_* homes and JAVA_HOME. main.ts passes it as the dispatcher's execEnv.
• Website: remote-agents.mdx and gateway/access-control.mdx say an agent token is like shell access and list the variables a command gets.
• Manuals: src/daemon/AGENTS.md, docs/internal/flows/device-exec.md.

Tests

• src/daemon/exec-env.test.ts: kept and dropped keys, look-alikes included.
• src/daemon/main.test.ts: a planted AWS_SECRET_ACCESS_KEY does not reach a device.exec child; LC_CTYPE, PATH and the driver's env do.

Assumptions

• Assumption: where is the filter applied? — at the composition root (main.ts), so the proof goes through startDaemon, not the Dispatcher alone.
• Assumption: are keys beyond the brief's list needed? — no; drivers set ANDROID_ADB_SERVER_PORT themselves, and adb-server or emulator keys are read by processes the daemon starts with its own environment.

Review

Spec review: skipped. Code review: 0 blocking, 0 fixed, 0 notes. Claims review: skipped.
Rounds: 1. Tokens: n/a.

One combined review by the maintainer's agent on 2026-10-22 (comment below); no blocking findings.

Rebased onto main e1f2f43 on 2026-10-26 as one commit. Conflicts: flows/device-exec.md keeps main's device-filling line (ADR 0047) and this PR's env step. remote-agents.mdx keeps this PR's paragraph on what a command gets, and main's newer bullets (Simlock fills in the device), replacing this PR's older "name your device" bullets.

Written by an agent.

[V3RON]

Review (maintainer's agent, round 1)

No blocking findings.

• execBaseEnvironment is a pure allowlist read once at start; the driver's env/unsetEnv layering in the dispatcher is untouched, so the physical-adb ANDROID_SERIAL unset still works. The kept set covers what xcrun, adb (absolute path, HOME for its keys) and devicectl need; nothing in the drivers' passthrough env builders depends on a dropped key.
• The startDaemon test is the right seam given the filter lives in main.ts: it plants a secret and a locale in the real env, drives device.exec through the dispatcher, and checks the child's env. Env is restored in finally.
• Docs: the remote-agents paragraph says plainly that an agent token is shell access to the worker and names the kept variables; the access-control caution adds simctl spawn. The flow doc and the daemon manual's security model are updated and the manual stays under its line limit.

Notes, no change needed:

• The website lists the kept variables literally. Documentation rule 8 allows an end-user page to show a value, so this is fine, but a later change to KEPT_KEYS must update that sentence too.
• SIMCTL_CHILD_* variables in the daemon's env no longer reach a simulator process through simctl spawn; that is the intended effect, just worth knowing if an operator relied on it.