Skip to content

Commit 156d69e

Browse files
authored
docs(agents): stop local simulators and emulators on close (#4166)
* docs(agents): stop local simulators and emulators on close Agents finish with plain close, which never stops the device, while open boots a stopped one. Tell them to finish with close --shutdown on local simulators and emulators, in close help, workflow/manual-qa/validate help, the skills, and the repo agent docs. Refs #4162 * docs(agents): scope close --shutdown to a device the session booted Address review: one rule and one exception everywhere (the session booted the local simulator or emulator, unless the user asks to keep it running). Drop the AGENTS.md sentence; device-verification.md owns the rule. Remove two cleanup lines that duplicate CLI help and the line above them. * docs(help): keep the workflow card under its size budget The workflow card was 9092 of 9100 bytes on main. Leave it unchanged; the close command help and the manual-qa/validate topics carry the rule.
1 parent 7b3f63f commit 156d69e

8 files changed

Lines changed: 12 additions & 7 deletions

File tree

‎docs/agents/device-verification.md‎

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -31,18 +31,17 @@ A failed command can look like a fast success. Before you record the time of a c
3131

3232
Use one session for each purpose. For more isolation, use a separate `--state-dir` under `/private/tmp`.
3333
Close each session that you opened manually, including failed attempts, with its original session, platform, UDID, and state directory.
34+
If your session booted a local simulator or emulator, add `--shutdown`, unless the user asks to keep it running.
3435

3536
For `DEVICE_IN_USE`:
3637

3738
- "already in use by session X": follow the `close --session` hint of this daemon.
3839
- "owned by session X in workspace Y": examine `device status`. Use `device release --stale` only for provably dead owners.
3940
A live or uncertain owner blocks `open`, unless the device rebooted after the claim.
40-
With reboot evidence, `open` settles old resources, takes the claim, and reports the release in `warnings`.
4141
Do not search for PIDs. Do not steal the claim.
4242

4343
If cleanup is stuck, run `agent-device device status --stale`.
4444
To stop the owning daemon, run `agent-device daemon stop --state-dir <dir>`. For retained runners, add `--clean`.
45-
To release dead owners, run `agent-device device release --stale`.
4645
If you are blocked, report the session, state directory, and status output. Always report incomplete cleanup.
4746
The physical runner handoff checklist is in `docs/evidence/ios-physical-runner-handoff-2026-09-19.md`.
4847

‎packages/command-surface/src/management/app.ts‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -93,7 +93,7 @@ const openCommandMetadata = defineFieldCommandMetadata(
9393

9494
const closeCommandMetadata = defineFieldCommandMetadata(
9595
'close',
96-
'Close the named app, or close the active session app when app is omitted. Use shutdown only when the selected simulator or emulator should also stop. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running.',
96+
'Close the named app, or close the active session app when app is omitted. If the session booted a local simulator or emulator, add shutdown when you finish, unless the user asks to keep it running; close alone never stops the device. Android ADB close fails with android-app-close-timeout if the app stays foreground past 2s, a killed process does not exit within 10s, or a new process runs past 2s. It fails with android-process-probe-unavailable when adb pidof cannot list the app processes; if that happens before the force-stop, the app keeps running.',
9797
{
9898
app: stringField('Optional app to close.'),
9999
shutdown: booleanField('Shutdown the session/device where supported.'),

‎scripts/__tests__/simulator-skills-contract.test.ts‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -37,6 +37,7 @@ const SKILLS = [
3737
id: 'foreground platform open',
3838
requiredText: 'agent-device open <app-or-bundle-id> --platform ios --foreground',
3939
},
40+
{ id: 'device shutdown on finish', requiredText: 'agent-device close --shutdown' },
4041
] satisfies Contract[],
4142
prohibitions: [
4243
{ id: 'version startup probe', forbiddenText: 'agent-device --version' },
@@ -64,6 +65,7 @@ const SKILLS = [
6465
id: 'foreground platform open',
6566
requiredText: 'agent-device open <app-or-package-id> --platform android --foreground',
6667
},
68+
{ id: 'device shutdown on finish', requiredText: 'agent-device close --shutdown' },
6769
] satisfies Contract[],
6870
prohibitions: [
6971
{ id: 'version startup probe', forbiddenText: 'agent-device --version' },

‎skills/agent-device/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,7 @@ agent-device open <app> --foreground
1313

1414
That starts the session and returns the initial interactive snapshot with `@refs`.
1515

16-
Loop: act with `press|click|fill|longpress <target> ... --settle`, `scroll <direction> --settle`, or `back --settle`; continue from the printed diff, verify the named expectation (`wait text "..."`, `is`, `get`, or `find`), then run `agent-device close`.
16+
Loop: act with `press|click|fill|longpress <target> ... --settle`, `scroll <direction> --settle`, or `back --settle`; continue from the printed diff, verify the named expectation (`wait text "..."`, `is`, `get`, or `find`), then run `agent-device close`, or `agent-device close --shutdown` if your session booted a local simulator or emulator, unless the user asks to keep it running.
1717

1818
Reaching an off-screen target is one command, not a scroll-and-check loop: `scroll down --until <selector>` scrolls until that element is on screen, and `scroll bottom` runs to the end of the content. Repeated bare `scroll down` calls are the slow way to find something.
1919

‎skills/android-emulator/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ agent-device open <app-or-package-id> --platform android --foreground
2121

2222
Follow the initial interactive snapshot and corrective error hints. If the shell reports that `agent-device` is unavailable, stop and ask the user to install it or expose their existing installation on `PATH`.
2323

24+
When you finish, if your session booted the emulator, run `agent-device close --shutdown`, unless the user asks to keep it running.
25+
2426
Only when the task is specialized or a command shape is unclear, read the relevant version-matched help topic:
2527

2628
```bash

‎skills/dogfood/SKILL.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -22,6 +22,6 @@ Read current CLI guidance:
2222
agent-device help dogfood
2323
```
2424

25-
Loop: open app -> snapshot -i + screenshot -> explore flows -> capture evidence per issue -> close.
25+
Loop: open app -> snapshot -i + screenshot -> explore flows -> capture evidence per issue -> close (`close --shutdown` if your session booted a local simulator or emulator, unless the user asks to keep it running).
2626

2727
Target app is required; infer platform or ask. Findings must come from runtime behavior, not source reads. Let `help dogfood` provide exact report shape, evidence commands, and current workflow guidance.

‎skills/ios-simulator/SKILL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,8 @@ agent-device open <app-or-bundle-id> --platform ios --foreground
2121

2222
Follow the initial interactive snapshot and corrective error hints. If the shell reports that `agent-device` is unavailable, stop and ask the user to install it or expose their existing installation on `PATH`.
2323

24+
When you finish, if your session booted the simulator, run `agent-device close --shutdown`, unless the user asks to keep it running.
25+
2426
Only when the task is specialized or a command shape is unclear, read the relevant version-matched help topic:
2527

2628
```bash

‎src/commands/schema/cli-help-workflows.ts‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -29,7 +29,7 @@ Loop:
2929
4. Treat a settled:true diff as the next observation. Do not add wait stable or another snapshot when the diff already shows the next target or expected result.
3030
5. If --settle prints not settled, follow its hint before the next ref-based action.
3131
6. Verify named expectations with wait text/selector/absent, get, is, find, or the settled diff. A bare screenshot/snapshot is not verification for a named expectation.
32-
7. Close the session when the script ends.
32+
7. Close the session when the script ends. If your session booted a local simulator or emulator, use close --shutdown, unless the user asks to keep it running.
3333
3434
Command shapes:
3535
agent-device open com.example.app --relaunch
@@ -278,7 +278,7 @@ Loop:
278278
3. Use snapshot -i and press/fill/click/longpress --settle for UI-driving steps.
279279
4. Use the settled diff as evidence when it shows the changed behavior; otherwise verify with wait/get/is/find, screenshot, logs, network, perf, or trace based on the claim.
280280
5. Record timings, token/output size, screenshots/videos, logs, or perf artifacts only when they answer the validation question.
281-
6. Close sessions and release leases before finishing.
281+
6. Close sessions and release leases before finishing. If your session booted a local simulator or emulator, use close --shutdown, unless the user asks to keep it running.
282282
283283
Evidence:
284284
CLI/runtime freshness: pnpm build, pnpm clean:daemon, then agent-device --version or the command under test.

0 commit comments

Comments
 (0)