Boot Android emulators slim: guest RAM, low-RAM mode, and the feature profile #163

Part of #159.

Scope

After this PR a slim Android device runs with the configured guest RAM and, unless turned off, as a low-RAM device. The mode rules are those of #172: android.defaultMode sets the default, --mode slim gets a slim device on any worker, and the lease reports mode: "slim". A --mode full lease gets a stock emulator on its own pool key, as on iOS. simlock doctor names an installed image that ignores the RAM size. No package is disabled yet; that is the next task.

{
  "android": {
    "defaultMode": "full",   // default
    "slim": {
      "ramMb": 1536,      // guest RAM in MiB for a slim device
      "lowRam": true      // boot the guest as a low-RAM device
    }
  }
}

A changed key applies at a device's next boot and rebuilds that device's clean baseline once. Nothing under android.slim is settable from a lease request, MCP, or HTTP.

Technical spec

Written before #172. #172 has shipped (#204): featureProfile is now device.mode ("slim" or "full", always present), slim.enabled gave way to android.defaultMode, and --full is now --mode full. Revise this section against that before approval.

Modules touched

• src/core/config.ts: android.slim block beside android.emulator (Configure Android emulator launch options (headless, GPU, audio, boot animation) from the config file #148) with the defaults above. Validators reject a non-boolean enabled or lowRam and a ramMb that is not a positive integer, naming the key. A gateway already warns about and ignores the android key; only the docs list changes.
• src/contract/schemas.ts: the config block so simlock config and config.get render it.
• src/daemon/main.ts: thread config.android.slim into discoverAndroidDriver as slim, the way config.ios.slim reaches the iOS driver.
• src/drivers/android/data.ts: AndroidDriverData.full?: true; isAndroidDriverData accepts data with or without it.
• src/drivers/android/index.ts:
  • AndroidDriverOptions.slim (AndroidSlimOptions, optional; omitted equals disabled). reducesFeatures is slim?.enabled === true.
  • provision stamps full: true into driver data when spec.full is true, and nothing otherwise, so a normal spec's driver data stays byte-identical.
  • One function decides whether slim applies to a device: enabled and not full. Every other site calls it (architecture rule 10).
  • #startEmulator appends -memory <ramMb> and, when lowRam, -lowram after the android.emulator flags, on every boot of a device slim applies to, recovery included (ADR 0006 §2).
  • #currentConfigHash gains the device's slim inputs (ramMb, lowRam) only when slim applies, and appends nothing otherwise, so a baseline captured before this change keeps its hash for slim off and for a full device (ADR 0006 §3). #configHash and #captureBaseline pass the device through.
  • makeReady returns featureProfile on every path, including the already-running path and a recover boot: undefined while slim is off, "full" for a full device, "reduced" otherwise (ADR 0006 §5).
  • advisories() returns one slim-image-ram-floor advisory naming each installed image whose tag ends in _ps16k while slim is on and ramMb is below 4096 (ADR 0006 §9). Read-only, same contract as listCatalog.
• docs/CONFIGURATION.md: the three keys in the table, their validation, the next-boot and baseline-rebuild rules, the gateway-ignored list, a slim section that no longer says iOS-only and says what to pair: capacity.config.ramBudget.androidBytesPerDevice and android.emulator.gpu.
• docs/CLI.md: --full, featureProfile, and the doctor advisory text no longer say Android is ignored or absent.
• docs/HTTP-API.md: the same for full and slim.
• docs/internal/KNOWN-PITFALLS.md: an Android slim section: a config change wipes each device once, low-RAM mode is app-visible, 16 KiB images gain nothing.
• e2e/slow-android-slim.test.ts: the real-emulator lane, gated like slow-android-smoke.test.ts.

Contract and event changes

None beyond the config schema. No new operation, event, or lease-request field. lease.request must not gain slim.

Rules in play

• docs/internal/adr/0006-opt-in-slim-android-emulators.md §1 to §5 and §9: the design this task builds.
• docs/internal/adr/0002-opt-in-slim-ios-simulators.md §6: full and pool identity, reused unchanged.
• docs/internal/agent-rules/architecture.md: rule 2 (the core forwards the block unread), rule 10 (one "does slim apply" decision), rule 13 (the iOS-only claims in the docs become false).
• docs/internal/agent-rules/safety.md: rule 2 (a recovery boot keeps the flags and changes nothing else), rule 9 (config fails closed).
• docs/internal/agent-rules/testing.md.

Tests

• With android.slim absent, the emulator launch command is byte-for-byte what it was before this change and makeReady reports no featureProfile.
• With slim enabled, a device's launch adds -memory 1536 -lowram after the android.emulator flags and makeReady reports featureProfile: "reduced".
• With lowRam: false the launch adds -memory 1536 and not -lowram.
• A full spec is stamped full: true into driver data, its launch carries neither flag, and makeReady reports featureProfile: "full".
• A recover boot of a slim device carries the same launch flags as a prepare boot and runs no baseline logic.
• The already-running path of makeReady reports the same featureProfile as a fresh boot.
• reducesFeatures is true exactly when android.slim.enabled is true.
• Enabling slim, or changing ramMb or lowRam, changes the baseline hash of a non-full device and does not change it for a full device or with slim off.
• advisories() names each installed *_ps16k image while slim is on and ramMb is below 4096, and returns nothing while slim is off or ramMb is 4096 or more.
• A non-boolean android.slim.enabled, a non-boolean android.slim.lowRam, or an android.slim.ramMb that is not a positive integer is rejected at config load, naming the key.
• isAndroidDriverData accepts driver data with and without full.
• simlock config renders the android.slim block with its defaults (e2e, fast lane).
• lease.request carrying a slim field is BAD_REQUEST.
• Slow lane, real emulator: a slim lease's guest reports ro.config.low_ram as true and a MemTotal near 1536 MiB, its grant carries featureProfile: "reduced", and a --full lease of the same spec reports neither and carries featureProfile: "full".

Done when

• Every test above passes and pnpm check is green.
• With default config the emulator launch command is byte-for-byte what it was before.
• simlock config shows the block. docs/CONFIGURATION.md, docs/CLI.md, and docs/HTTP-API.md say what the Modules section lists, and no end-user doc says slim is iOS-only or that --full is ignored on Android.
• The slow lane passes on a machine with an Android SDK.

Out of scope

• Disabling packages, android.slim.categories, the device.slimmed event: the next task.
• Guest settings of any kind.
• Any change to the capacity RAM budget.
• Headless, GPU, audio, boot animation: Configure Android emulator launch options (headless, GPU, audio, boot animation) from the config file #148.

Depends on

• Configure Android emulator launch options (headless, GPU, audio, boot animation) from the config file #148
• Lease requests choose slim or full; config sets the default #172
• Gateway: remote agents lease and reach physical devices on workers #442
• Heartbeats keep the simlock lease alive #473
• simlock ending a simlock lease ends the agent-device session first #474

Approval

• Approved for delivery

Written by an agent.