Opt-in slim mode for Android emulators

[V3RON]

Request: #151

Problem

Slim mode exists only for iOS. An Android emulator boots with the guest RAM its device profile asks for and with every background package its system image ships. Most of that serves a phone owner, not a test run. The resource capacity strategy budgets 4 GiB per emulator, so heavy emulators mean fewer devices per machine.

#148 makes the window, GPU, audio, and boot animation configurable. Guest RAM and background packages are what it leaves out.

Who it is for

An operator sizing a Mac or CI host that runs several Android emulators at once, and the parallel coding agents leasing them. Also an agent whose test needs a stock device and must be able to ask for one.

Outcome

• Android slim follows the mode rules of Lease requests choose slim or full; config sets the default #172. The operator sets android.defaultMode to slim or full; the default is full. A request picks a mode with --mode, and a request with no mode gets the default.
• The settings under android.slim.* are set once, by the operator, never from a lease request, MCP, or HTTP.
• A slim emulator boots with the guest RAM size the operator configured, 1536 MB when no size is set.
• A slim emulator boots as a low-RAM device. A separate key under android.slim.* turns that off while keeping the RAM size and the package pass, for a test that must see a stock device profile.
• A slim emulator has a known set of background packages disabled. The set ships with Simlock, is grouped into named categories, and the operator can narrow it to some categories, as on iOS.
• The Play Store, Chrome, and the setup wizard are one category of their own that is not in the default set. The operator adds it by name.
• No category contains Google Play Services or a package the system cannot boot without. Push, sign-in, WebView, and networking keep working on a slim device, and a slim device always finishes booting.
• A lease on a slim device reports mode: "slim" on every surface. simlock lease --mode full gets a stock device and never receives a slim one. --mode slim gets a slim device on any worker, whatever its default.
• A slim setting that changes applies at the device's next boot. A running emulator keeps what it started with.
• A reclaimed slim device comes back slim, and reclaim costs no more than it does for a full device.
• A package the image does not carry is skipped and logged. A failed slim pass degrades to a device that is not slim, never to a failed lease.
• simlock doctor reports an installed system image that cannot honour the configured RAM size, the way it reports an iOS runtime that cannot be slimmed.
• Slim mode touches only devices Simlock created, needs nothing installed beyond the Android SDK Simlock already requires, and needs no root inside the guest.

Non-goals

• Headless, GPU, audio, and boot animation: Configure Android emulator launch options (headless, GPU, audio, boot animation) from the config file #148.
• Guest settings of any kind: animations, background process caps, sync, location. Slim never changes a guest setting.
• Camera and D-pad hardware toggles.
• Guest CPU count and VM heap size.
• A per-lease choice of RAM size or packages. The only per-lease control is --mode.
• Changing capacity.config.ramBudget.androidBytesPerDevice automatically. The operator lowers it to match, and the docs say so.
• Uninstalling packages or altering the system image on disk.
• Slim as the default mode out of the box.

Completion conditions

• With android.defaultMode unset, a request with no mode gets an emulator whose launch command and package state are exactly what they were before this feature.
• On a worker whose default mode is full, --mode slim grants a slim Android device.
• With no size set, a slim emulator reports roughly 1536 MB from inside the guest and identifies itself as a low-RAM device. With a size set, it reports roughly that size.
• With the low-RAM key off, the emulator boots with the configured size and does not identify itself as a low-RAM device.
• On a slim device, every package in the enabled categories shows as disabled. With no categories set, the Play Store, Chrome, and the setup wizard stay enabled; naming their category disables them. Google Play Services is enabled in every case.
• On every API level Simlock supports, a slim device reaches boot completion and answers package-manager queries.
• A slim device's animation scales, sync, and location settings are what a stock device has.
• The lease response carries mode: "slim". A --mode full lease on the same spec gets a device with no package disabled, the profile's own RAM, no low-RAM mode, and mode: "full".
• While slim devices sit idle in the pool, a --mode full request does not receive one.
• A slim device that is released and reclaimed with the standard clean level is granted again still slim, with no extra boot compared to a full device.
• Changing the RAM size, the low-RAM key, or the categories, then leasing the device again, yields a device with the new setting, and reclaim on that device is not permanently degraded to a full wipe.
• A configured package missing from the image is logged and the lease still grants.
• simlock doctor names an installed image that ignores the RAM size, and stays quiet when the default mode is full.
• simlock events shows a device.slimmed event for the Android device after the pass, and docs/EVENTS.md describes its Android payload.
• A lease request carrying any android field, or any slim setting other than mode, is rejected as BAD_REQUEST.
• simlock config renders android.defaultMode and the android.slim block. docs/CONFIGURATION.md documents every key, its default, what slim mode disables, what stops working, and the capacity budget and GPU setting to pair it with. docs/CLI.md and docs/HTTP-API.md no longer say slim is unavailable on Android.
• AVDs outside Simlock's device root are untouched.

Open questions

None.

Decisions

• ADR 0006 — Opt-in slim Android emulators: guest RAM and low-RAM mode as per-boot launch flags, packages disabled before the clean baseline is captured, and the baseline config hash as the one idempotence marker. Accepted — not yet implemented, on branch claude/inspiring-volta-g3soer until it lands on main. It predates Lease requests choose slim or full; config sets the default #172 and is amended with it.

Tasks

1. Boot Android emulators slim: guest RAM, low-RAM mode, and the feature profile #163 — Boot Android emulators slim: guest RAM, low-RAM mode, and the feature profile. Depends on Configure Android emulator launch options (headless, GPU, audio, boot animation) from the config file #148 and Lease requests choose slim or full; config sets the default #172.
2. Disable background packages on slim Android emulators #164 — Disable background packages on slim Android emulators. Depends on Boot Android emulators slim: guest RAM, low-RAM mode, and the feature profile #163.

Written by an agent.

[V3RON]

Spec updated: Outcome, Non-goals, and Completion conditions amended; Open questions sharpened and a fifth added.

Written by an agent.

---

Generated by Claude Code

[V3RON]

Spec updated: Open questions resolved into Outcome, Non-goals, and Completion conditions; Open questions now empty.

Written by an agent.

---

Generated by Claude Code

[V3RON]

Spec updated: Decisions and Tasks added; split into #163 and #164; stays feature:spec until ADR 0006 is accepted.

Written by an agent.

---

Generated by Claude Code

[V3RON]

Spec updated: ADR 0006 accepted, label moved to feature:planned.

Written by an agent.

---

Generated by Claude Code

[V3RON]

Spec updated: Outcome, Non-goals, Completion conditions, Decisions, and Tasks amended to follow the request mode in #172.

Written by an agent.