Update to Autonom

{
  "description": "Own an explicit Android device or iOS simulator session for AI agents — list targets, start Autonom session artifacts, install/launch/force-stop/clear apps, and stop cleanly with evidence directories.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 308
    }
  ],
  "name": "mobile-session",
  "skill_md_contents": "---\nname: mobile-session\ndescription: Own an explicit Android device or iOS simulator session for AI agents — list targets, start Autonom session artifacts, install/launch/force-stop/clear apps, and stop cleanly with evidence directories.\n---\n\n# Mobile Session (Android + iOS Simulator)\n\n## Purpose\n\nGive the agent a **single explicit target** and an artifact directory before UI,\nlog, or network work. Prefer this skill over ad-hoc `adb` or `simctl` when testing\nor debugging.\n\nOne verb set covers both platforms. `--serial` remains a permanent Android alias\nof `--target`, so existing Android workflows are unchanged.\n\n## CLI entrypoint\n\n```bash\npython3 <autonom-root>/scripts/autonom.py devices          # Android + iOS in one list\npython3 <autonom-root>/scripts/autonom.py doctor           # what this machine can actually do\n```\n\nEach device carries `running` (true when Booted / `device`), so you can tell a\nlive target from a cold one without knowing each platform's wording. The\nAndroid listing also reports `avds` (bootable emulator images not yet started)\nand `avd_profiles` — each AVD's hardware profile, screen size and density, and\nAPI level read from its `config.ini` — so \"the phone-sized emulator\" is a\nlookup, not a guess from the name. A running emulator names the `avd` it\nbooted from.\n\n`doctor` lists every active `AUTONOM_*` override under `overrides` and warns\nwith `override_path_missing` when one points at a binary that does not exist —\nthe usual reason a tool reads as missing while `which` finds it.\n\n### Boot and shut down a target\n\n```bash\npython3 <autonom-root>/scripts/autonom.py devices boot --avd Pixel_9      # start an Android emulator, wait for boot\npython3 <autonom-root>/scripts/autonom.py devices boot --udid <UDID>      # boot an iOS simulator\npython3 <autonom-root>/scripts/autonom.py devices shutdown --serial emulator-5554\npython3 <autonom-root>/scripts/autonom.py devices shutdown --udid <UDID>\n```\n\n`boot --avd` waits for `sys.boot_completed` and returns the serial it came up\nas (`--no-wait` to skip the wait). `session start` still boots a shutdown\nsimulator on its own, so `devices boot` is only needed to start an Android\nemulator up front or to pre-warm a target. `shutdown` refuses any serial that\nis not `emulator-<port>` — it never powers off physical hardware.\n\nAn emulator started by `devices boot` is registered as **harness-owned**:\n`doctor` does not list it as an orphan while it runs, and `devices shutdown`\nreleases its registry entry, so no stale process warning follows.\n\n### Android\n\n```bash\npython3 <autonom-root>/scripts/autonom.py session start --serial emulator-5554 --app-id com.example.app\npython3 <autonom-root>/scripts/autonom.py session launch com.example.app            # resume where it was\npython3 <autonom-root>/scripts/autonom.py session launch com.example.app --fresh    # launcher activity on a cleared task\npython3 <autonom-root>/scripts/autonom.py session launch com.example.app --fresh --activity .MainActivity\npython3 <autonom-root>/scripts/autonom.py session force-stop com.example.app\npython3 <autonom-root>/scripts/autonom.py session clear com.example.app\npython3 <autonom-root>/scripts/autonom.py session stop\n```\n\n### iOS Simulator\n\n```bash\npython3 <autonom-root>/scripts/autonom.py session start \\\n  --platform ios --target <UDID> \\\n  --install build/ios/iphonesimulator/Runner.app \\\n  --launch --app-id com.example.app --log-stream\n\npython3 <autonom-root>/scripts/autonom.py session launch com.example.app --setenv FLAVOR=staging\npython3 <autonom-root>/scripts/autonom.py session force-stop com.example.app\npython3 <autonom-root>/scripts/autonom.py session stop\n```\n\nTarget flags work before or after the subcommand. A shutdown simulator is booted\nautomatically and the response reports `\"booted\": true` when this call did it.\nThe response also says what `--install` and `--launch` did: `installed`\n(true/false) and `launched` (`null`, or the app id with the iOS `pid` / the\nAndroid `am start -W` report: `mode`, `component`, `launch`). An Android\n`session launch` (resume) is the launcher icon's own `am start -W` intent,\nnot `monkey`, so it no longer resets a pinned orientation.\n\n`session start` refuses with `session_already_active` (naming the live\nsession's id and target) while a session is current — run `session stop`\nfirst; it never replaces a session silently. If `--install` or `--launch`\nfails, the new session is rolled back (`session_rolled_back` names it) so no\nhalf-built session is left current. A flag that does nothing on the\nplatform (`--log-stream` or `--setenv` on Android, `--activity` on iOS) is\nreported in a `flag_ignored_on_platform` warning, and `session uninstall`\nreports a failed uninstall as `ok: false`.\n\nIntent extras that start with `--` must be attached to the flag, or argparse\nreads them as options: `session launch com.example.app --arg=--es --arg=key=value`.\nArgument mistakes come back as `error_code: usage_error` with the usage line.\n\nAll commands print JSON. `session start` writes, **machine-globally** under\n`~/.autonom/sessions/` (honouring `AUTONOM_HOME`) — not in the project, so the\nactive session is found from any directory, like mocks and per-app knowledge:\n\n```text\n~/.autonom/sessions/<session_id>/{shots,trees,logs,network,recordings,crashes,files,journal.ndjson,session.json}\n~/.autonom/sessions/<session_id>/flows/<run_id>/events.ndjson   # per-step flow run evidence (mobile-flow)\n~/.autonom/sessions/current.json\n```\n\n### Session journal — the full record of a run\n\nEverything a session does is appended to `<session>/journal.ndjson`: every verb\n(what ran, its scrubbed arguments, success, the artifact produced) and any note\nthe agent writes. Read it back for analytics or a handoff:\n\n```bash\npython3 <autonom-root>/scripts/autonom.py journal                     # whole timeline\npython3 <autonom-root>/scripts/autonom.py journal --kind note         # only notes\npython3 <autonom-root>/scripts/autonom.py journal --verb 'ui tap'     # only taps\npython3 <autonom-root>/scripts/autonom.py note add \"login screen renders; password field visible\" --task login\npython3 <autonom-root>/scripts/autonom.py note list --task login\npython3 <autonom-root>/scripts/autonom.py journal --session-id <id>   # a finished session's timeline\n```\n\nThe journal is secret-safe (typed text, secret-bearing flag values in any\nspelling or abbreviation, and every `KEY=VALUE` option value are masked) and\nbest-effort (a journal error never fails your command). `ui tree` keeps a\nsequenced file per capture under `trees/`, so the whole run's screens are kept,\nnot just the last.\n\n## Clearing app data\n\n| Platform | Behavior |\n| --- | --- |\n| Android | `pm clear` — full data reset |\n| iOS default | uninstall + reinstall; needs the `.app` path, so start the session with `--install` |\n| iOS `--strategy privacy` | `simctl privacy reset all` — **permissions only, app data survives** |\n\nWithout a recorded install path the verb fails with\n`ios_clear_requires_install_path` rather than silently doing something weaker.\n\n## Remote iOS targets\n\n`idb` splits into a macOS companion and a client that can run elsewhere, so a\nLinux orchestrator can drive a Mac:\n\n```bash\nexport AUTONOM_IDB_COMPANION=mac-farm-01:10882\n# or: --idb-host mac-farm-01 --idb-port 10882\n```\n\n## Rules\n\n1. If more than one target is ready, **always** pass `--target` (or `--serial` / `--udid`).\n   Ambiguity is an error listing the candidates, never a silent guess.\n2. Do not print signing secrets, tokens, or `.env` values while installing/launching.\n3. One session per investigation; stop when done so artifacts stay coherent.\n   `autonom session outputs` lists every followable file in the session dir\n   (device log stream, process output, network flows) with a `tail -f` hint\n   for a human's second terminal, plus the `metrics/` and `recordings/`\n   artifacts (`followable: false` for a binary, `directory: true` for an\n   Instruments `.trace`, with an `open` hint where the host has one).\n4. `session stop` tears down the log stream, recorder, and proxy best-effort,\n   then every process the session registered (the iOS log-stream writer, a\n   `canvas serve` pair, an idb companion its own idb calls started), and\n   reports each action under `teardown` — it never fails because teardown\n   failed. Every pid is signalled only once its registry row or its command\n   line shows it is still that process (a pid in a session file can be days\n   old); one `ps` cannot vouch for is skipped with `unverified_skipped`. A\n   companion it did not start is named in a `companion_left_running`\n   warning, never killed.\n5. If a session died without stopping, `autonom doctor` lists orphaned processes,\n   any device left pointing at a dead proxy, and any emulator still routed\n   through another session's *live* proxy (`device_attached_to_foreign_proxy`).\n\n## Failure codes worth knowing\n\n| Code | Meaning |\n| --- | --- |\n| `ambiguous_target` | more than one ready target; pass `--target` |\n| `session_already_active` | a session is current; `session stop` it before starting another |\n| `idb_required` | iOS `ui` verbs need idb; `screenshot`/`logs`/`open` still work |\n| `ios_boot_failed` | simulator never reached `Booted`; try `xcrun simctl erase <udid>` |\n| `no_active_session` | start one with `session start` |\n| `usage_error` | argparse rejected the argv; `hint` carries the usage line |\n| `app_not_debuggable` | `file ls`/`pull` need a debuggable build; release and system apps refuse run-as |\n| `simulator_must_be_shutdown` | `simulator keyboard pin` needs a shut-down simulator; pass `--value reboot=true` or shut it down first |\n| `simulator_data_not_found` | the simulator has no data directory yet — boot it once, or set `AUTONOM_CORESIMULATOR_DEVICES` |\n\n## Related skills\n\n- `mobile-screen` — UI tree, find, tap, screenshot\n- `mobile-network` — HTTP(S) capture and mocking\n- `ios-debugger-agent` / `android-debugger-agent` — build-and-run workflows\n- `project-router` — when to load runtime skills at all\n"
}