Update to Autonom

{
  "description": "Build, run, and debug iOS apps on the Simulator for AI agents — resolve the scheme and destination, install and launch, then climb an evidence ladder through accessibility trees, screenshots, logs, and crash reports.",
  "included_files": [
    {
      "relative_path": "agents/openai.yaml",
      "size_in_bytes": 373
    }
  ],
  "name": "ios-debugger-agent",
  "skill_md_contents": "---\nname: ios-debugger-agent\ndescription: Build, run, and debug iOS apps on the Simulator for AI agents — resolve the scheme and destination, install and launch, then climb an evidence ladder through accessibility trees, screenshots, logs, and crash reports.\n---\n\n# iOS Debugger Agent (Simulator)\n\n## Purpose\n\nTurn \"the iOS app misbehaves\" into measured evidence. Build with the project's own\ntoolchain, drive the app through the Autonom CLI, and separate what was observed\nfrom what is inferred.\n\nPhysical devices are out of scope: they need Developer Mode, signing, and tunnels.\n\n## Prerequisites\n\n```bash\npython3 <autonom-root>/scripts/autonom.py doctor\n```\n\nEverything except `ui *` works with Xcode alone. The accessibility tree\nadditionally needs `idb` plus `idb_companion`; input (tap, swipe, type, key)\nneeds a companion that can load SimulatorKit, or AXe. `doctor` reports\n`capabilities.ios_tree` and `capabilities.ios_hid` separately and prints the\nexact fix for each gap.\n\n**Xcode 27 trap:** SimulatorKit moved to `Contents/SharedFrameworks`, and an\n`idb_companion` built before that looks in `Library/PrivateFrameworks`. The\ntree still works, but every input fails with `ios_hid_framework_missing`.\nFix it with `brew update && brew upgrade idb-companion`, or install AXe\n(`brew install cameroncooke/axe/axe`): the default `--ios-hid auto` then\nroutes input through AXe while the tree stays on idb, and each `ui` input\npayload reports `backend: axe`. Pin a route with `--ios-hid idb|axe` (or\n`AUTONOM_IOS_HID`) before the verb. Do not report a failed tap as an app\ndefect until `doctor` shows input ready. On Xcode 27 with AXe carrying input,\n`capabilities.ios_hid.ready` stays `false` (it describes idb's own HID) while\n`ios_hid.axe_ready` is `true`, `ios_hid.backend` is `axe`, and\n`capabilities.ios_ui.ready` is `true`: read `ios_ui` and `axe_ready`, and keep\ngoing — input works.\n\n## 1. Build\n\nUse whatever the repository already uses — never introduce a second build path.\n\n```bash\n# Flutter\nflutter build ios --simulator --debug\n# -> build/ios/iphonesimulator/Runner.app\n\n# Xcode project or workspace\nxcodebuild -scheme <Scheme> -destination 'platform=iOS Simulator,name=iPhone 17 Pro' \\\n  -derivedDataPath build/DerivedData build\n# -> build/DerivedData/Build/Products/Debug-iphonesimulator/<App>.app\n\n# SwiftPM executable targets\nswift build\n```\n\nResolve the scheme from `xcodebuild -list` rather than guessing. When FVM or a\npinned Flutter SDK is present, resolve it with `scripts/flutter_exec.py` instead of\nfalling back to a system SDK.\n\n## 2. Own a session\n\n```bash\npython3 <autonom-root>/scripts/autonom.py devices --platform ios\npython3 <autonom-root>/scripts/autonom.py session start \\\n  --platform ios --target <UDID> \\\n  --install <path>.app --launch --app-id <bundle-id> --log-stream\n```\n\n`--log-stream` starts a background `log stream` for the session, filtered to\nthe app and capped on disk (`AUTONOM_IOS_LOG_MAX_MB`, default 50, one\nrotation), which makes `logs tail` cheap afterwards. Without it, tailing\nfalls back to `log show`. A second `session start` while one is live is\nrefused with `session_already_active`; stop the old one first.\n\n## 3. Reproduce and capture\n\n```bash\npython3 <autonom-root>/scripts/autonom.py ui tree\npython3 <autonom-root>/scripts/autonom.py ui find --desc \"Log In\" --mode exact\npython3 <autonom-root>/scripts/autonom.py screenshot --out /tmp/before.png\npython3 <autonom-root>/scripts/autonom.py ui tap --desc \"Log In\" --mode exact\npython3 <autonom-root>/scripts/autonom.py screenshot --out /tmp/after.png\npython3 <autonom-root>/scripts/autonom.py logs tail --package <bundle-id> --since 60\npython3 <autonom-root>/scripts/autonom.py crash list --app-id <bundle-id>\n```\n\n**Compare the two screenshots.** A tap that exits 0 has not been proven to do\nanything; a changed screen (or a changed tree) is the proof. Pin the status\nbar first (`simulator status-bar pin`) so the battery and signal glyphs do not\nshow up as a difference, and pin the keyboard before typed text must be exact:\n\n```bash\npython3 <autonom-root>/scripts/autonom.py simulator status-bar pin\npython3 <autonom-root>/scripts/autonom.py simulator keyboard pin --value locale=en-US --value reboot=true\n```\n\nThe keyboard pin writes the simulator's preference store (autocorrect,\nprediction, auto-capitalisation off; locale set) and needs the device shut\ndown — `reboot=true` cycles it for you. Undo with `keyboard reset` and\n`status-bar clear`.\n\n## 4. Drive state the UI cannot reach\n\n```bash\npython3 <autonom-root>/scripts/autonom.py open \"myapp://order/42\"\npython3 <autonom-root>/scripts/autonom.py permissions grant photos <bundle-id>\npython3 <autonom-root>/scripts/autonom.py permissions reset all <bundle-id>\npython3 <autonom-root>/scripts/autonom.py location set 55.751244,37.618423\npython3 <autonom-root>/scripts/autonom.py media add fixtures/photo.png\npython3 <autonom-root>/scripts/autonom.py file ls Documents --app-id <bundle-id>\npython3 <autonom-root>/scripts/autonom.py file pull Documents/state.json --app-id <bundle-id>\npython3 <autonom-root>/scripts/autonom.py session launch <bundle-id> --setenv FLAVOR=staging\npython3 <autonom-root>/scripts/autonom.py simulator biometric enroll     # then match | nonmatch | unenroll\n```\n\n`simulator biometric match|nonmatch` posts the Face ID notification on a\nFace ID device and the Touch ID one otherwise (both when the device type\ndoes not say; `biometry` reports which), through the Simulator's Darwin\nnotifications. Nothing reports whether a prompt consumed it, so it answers\n`verified: false` with the reason in `verification`; prove the effect from\nthe app's screen. Unknown\nactions are `invalid_simulator_action` with the valid list.\n\nFile access is confined to the app container; a path that escapes it is refused.\nPulled files are written into session artifacts and their contents are not echoed,\nbecause app data can contain personal information.\n\n## 5. Evidence ladder\n\n1. code inspection;\n2. narrow unit / XCTest;\n3. explicit-simulator integration flow;\n4. screenshot + accessibility tree + logs + crash reports;\n5. recording of the exact repro (`record start` / `record stop`);\n6. equivalent before/after replay after the fix.\n\nReport measured facts, code-backed findings, hypotheses, and remaining uncertainty\nas four separate categories.\n\n## Boundaries and honesty rules\n\n- The tree is the **accessibility** hierarchy. A Flutter view without `Semantics`\n  can be nearly empty; that is reported as `sparse_accessibility_tree` and means\n  the app exposes little, not that the screen is blank.\n- Clear app state with `session clear` (uninstall + reinstall). `--strategy privacy`\n  resets permissions **only** and leaves data in place.\n- Load questions have CLI verbs: `autonom metrics snapshot` (host `ps` view of\n  the Simulator process + data-container size — never comparable to Android\n  PSS), `metrics series` for direction, `metrics memory warn` as a best-effort\n  pressure stimulus, and `metrics trace --preset allocations|time-profiler|\n  leaks|hitches` for real Instruments `.trace` bundles. `hitches` is\n  physical-device only: Instruments refuses Animation Hitches on the\n  Simulator (`list-presets` says `unsupported_on_simulator`), so on the\n  Simulator use `time-profiler` for main-thread stalls or\n  `metrics frames flutter-summary` on Flutter frame timings. Do not present a\n  screenshot or a log line as a performance measurement.\n- Simulator behavior differs from a physical device for camera, sensors, push,\n  background execution, and memory pressure. Say so when it matters to the finding.\n\n## Related\n\n- `mobile-session`, `mobile-screen`\n- `mobile-network` — inspect and mock the app's HTTP(S) traffic\n- `ios-project-setup` — scheme, simulator, and bundle-id conventions\n- `flutter-debugger-agent` — Dart-side debugging for Flutter apps\n"
}