Skip to content

Commit 9f2271c

Browse files
committed
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
1 parent a42bc35 commit 9f2271c

10 files changed

Lines changed: 26 additions & 8 deletions

File tree

‎AGENTS.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -48,7 +48,7 @@ The versioned CLI help owns command semantics. To drive an app, start with the s
4848
- In a new worktree, run `pnpm install --frozen-lockfile && pnpm build` before you test.
4949
- Do not change other worktrees, devices, sessions, dirty files, or experiments. Do not use `git stash`; all worktrees share it.
5050
- Do not copy `.env` into a worktree. For host credentials, source the main checkout's file by its absolute path.
51-
- Give each parallel worker different files and a different device. `pnpm check:affected --run`, `pnpm check`, and heavy `pnpm gate` ids share one lock.
51+
- Give each parallel worker different files and a different device. When a worker is done, it must stop its device with `close --shutdown`. `pnpm check:affected --run`, `pnpm check`, and heavy `pnpm gate` ids share one lock.
5252
- The layering scan reads only tracked files. Stage new modules before you trust its result.
5353
- When you rename a file, move its Fallow baseline entry. Do not regenerate unrelated baselines.
5454

‎docs/agents/device-verification.md‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -31,6 +31,10 @@ 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+
When you finish with a local simulator or emulator, close its session with `close --shutdown`.
35+
`close` alone does not stop the device. `open` boots a stopped device and does not stop it later.
36+
Use `close` without `--shutdown` only when the user tells you to keep the device running.
37+
If you are a parallel worker, always stop the device that you used.
3438

3539
For `DEVICE_IN_USE`:
3640

‎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. When you finish with a local simulator or emulator, add shutdown so the device does not keep running; omit it only when the device must stay up for more work. 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`. On a local simulator or emulator, run `agent-device close --shutdown` when you finish, unless the device must stay up for more work.
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: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@ 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, end the session and stop the emulator so it does not keep running. Use plain `agent-device close` only when the emulator must stay up for more work:
25+
26+
```bash
27+
agent-device close --shutdown
28+
```
29+
2430
Only when the task is specialized or a command shape is unclear, read the relevant version-matched help topic:
2531

2632
```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` on a local simulator or emulator).
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: 6 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -21,6 +21,12 @@ 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, end the session and stop the simulator so it does not keep running. Use plain `agent-device close` only when the simulator must stay up for more work:
25+
26+
```bash
27+
agent-device close --shutdown
28+
```
29+
2430
Only when the task is specialized or a command shape is unclear, read the relevant version-matched help topic:
2531

2632
```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. On a local simulator or emulator, use close --shutdown unless the device must stay up for more work.
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. Add --shutdown to close for each local simulator or emulator you no longer need, so it does not keep running.
282282
283283
Evidence:
284284
CLI/runtime freshness: pnpm build, pnpm clean:daemon, then agent-device --version or the command under test.

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

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -78,7 +78,7 @@ Command shape:
7878
Command lines only -- no prose, numbering, fences, pipes, or grep/head/tail/jq; raw output carries refs/hints for the next step. Order: subcommand, positionals, flags: agent-device open com.example.app --session checkout --platform android --relaunch
7979
Chain confident consecutive steps with &&: press 'label="Search"' --settle && fill 'label="Search"' "query" --settle. Fall back to one command at a time when a step is uncertain (ambiguous match, network-backed result, unseen screen).
8080
Refs look like @e12; use the exact ref from the latest snapshot -i, never a placeholder (@ref, @eN, @Label_Name). Pin with ~s<n> (press @e12~s4); every platform rejects a stale pinned ref -- refresh with snapshot -i or use a selector.
81-
close = agent-device close. App back is back; system back is back --system. Single taps are press/click; gesture tap touches 2 to 5 points at once. type never takes --settle: run type, then diff snapshot to verify. Known flow: batch --steps-file ./steps.json (help batch).
81+
close = agent-device close; when you finish with a local simulator or emulator, run close --shutdown unless the device must stay up for more work. App back is back; system back is back --system. Single taps are press/click; gesture tap touches 2 to 5 points at once. type never takes --settle: run type, then diff snapshot to verify. Known flow: batch --steps-file ./steps.json (help batch).
8282
Gestures: scroll/swipe for lists/flicks; gesture pan|fling|pinch|rotate|transform|tap|drag for multi-touch. Shapes and platform quirks: help gestures.
8383
8484
Bootstrap:
@@ -126,7 +126,7 @@ Validation and evidence:
126126
127127
React Native: help react-native for Metro/Re.Pack reload, DevTools, RN overlays. JS-only change: metro reload, find "Home"; open --relaunch for native reset.
128128
129-
Lifecycle facts (trust these instead of probing): open without --relaunch is idempotent-foreground except native macOS app opens (background); --relaunch restarts it. close keeps a healthy iOS runner warm by default; runners/daemons self-idle after 5 minutes; stale leases self-reclaim. open device claims reclaim other worktrees' warm runners; "already owned by another agent-device daemon" = owner outside claim arbitration. Env vars: help physical-device.
129+
Lifecycle facts (trust these instead of probing): open without --relaunch is idempotent-foreground except native macOS app opens (background); --relaunch restarts it. close keeps a healthy iOS runner warm by default and never stops the device; close --shutdown also stops a local simulator or emulator; runners/daemons self-idle after 5 minutes; stale leases self-reclaim. open device claims reclaim other worktrees' warm runners; "already owned by another agent-device daemon" = owner outside claim arbitration. Env vars: help physical-device.
130130
131131
Escalate:
132132
help manual-qa scripted manual QA

0 commit comments

Comments
 (0)