Skip to content

Slim: include or exclude single services beside the categories #1644

Open
0 of 1 issue completed
Open

Description

@V3RON

Request: #1556, #1552

Problem

Slim turns off whole categories of simulator services (ios.slim.categories). Operators need finer control in both directions:

Who it is for

Operators of a shared iOS worker that runs many slim simulators for coding agents, where CPU and memory are tight.

Outcome

In the worker config, an operator names single launchd services that slim keeps running (ios.slim.include) or turns off (ios.slim.exclude), beside the categories. Every slim device that worker prepares from then on boots that way. Nothing changes for a lease, a gateway or a client.

How it works for the user

flowchart TD
  A["operator edits config.json:<br/>ios.slim.include / exclude"] --> B{daemon start}
  B -->|a name in both lists,<br/>or not a list of strings| C["start fails:<br/>Invalid config value for ios.slim"]
  B -->|ok| D[slim lease or warm boot]
  D --> E["services off = categories − lease --except<br/>+ exclude − include"]
  E --> F[boot once, read back]
  F -->|every service as written| G[device mode slim]
  F -->|a service not as written| H[device mode full]
  F -->|nothing is off| H
Loading

Before (config.json):

{ "ios": { "defaultMode": "slim", "slim": { "include": ["com.apple.apsd"] } } }

The daemon log says Unknown config key: "ios.slim.include" and the key is ignored: push stays off with the store category.

After:

{ "ios": { "defaultMode": "slim", "slim": {
    "include": ["com.apple.apsd"],
    "exclude": ["com.apple.diagnosticd"] } } }

The daemon logs no warning. A slim lease's simulator runs apsd and no diagnosticd; the rest of every category stays off.

A name in both lists fails the config load, so the daemon does not start; simlock daemon start prints the error line with the message Invalid config value for "ios.slim": expected no service in both include and exclude (com.apple.apsd).

Examples

What a slim device turns off (worker config → services off; "today" is the same config on main, where both keys are unknown and ignored):

categories include exclude Lease --except Today After
unset — — — every category, slim same
unset com.apple.apsd — — every category, apsd off every category but apsd
[] — com.apple.diagnosticd — nothing off, full only diagnosticd, slim
["widgets"] — com.apple.diagnosticd — widgets widgets + diagnosticd
["store"] every label of store — — store nothing off, full
["store","other"] — com.apple.diagnosticd store,other nothing off, full only diagnosticd, slim
["store"] — one label of store store store kept store kept, that label runs too
unset — com.apple.gamed — gamed runs (never disabled) gamed off
unset — com.apple.no-such-thing — — written off; nothing to stop; slim

What the config load says:

Value Today After
"include": ["com.apple.apsd"] logged as unknown, ignored accepted
"include": [] logged as unknown, ignored accepted (nothing changes)
"exclude": ["a", "a"] logged as unknown, ignored accepted (one name)
"include": ["x"], "exclude": ["x"] logged as unknown, ignored load fails
"exclude": "com.apple.diagnosticd" logged as unknown, ignored load fails: expected an array of strings
"exclude": [""] logged as unknown, ignored load fails: expected an array of strings
"exclude": ["store"] (a category name) logged as unknown, ignored accepted as a service name; matches no service

What could go wrong

  • An operator misspells a service name: nothing is turned off or kept, and Simlock says nothing. Likely now and then; the docs say so.
  • An operator excludes a service the simulator needs to boot: every slim boot on that worker fails or grants full. Rare; the config is theirs.
  • A name taken out of exclude stays off in copies of a baseline saved before this feature shipped. Rare; putting it in include fixes it.

Words used

  • service (launchd label): the name launchd gives a background program inside the simulator, e.g. com.apple.diagnosticd.
  • category: a named group of services slim turns off together, e.g. store.
  • managed label: a service whose on/off line Simlock writes into the simulator's disabled.plist on every slim boot; any other line in that file is left as it is.
  • readback: after the boot, Simlock asks launchd which services are disabled and compares with what it wrote.
  • --except: a lease's list of categories that run for that lease only.
  • record of named services: a small file Simlock keeps next to disabled.plist with the include and exclude names it last wrote, so a name taken out of both lists is turned back on, e.g. ["com.apple.diagnosticd"].

Non-goals

  • Service names on a lease: --except stays categories-only.
  • Advertising include or exclude in the catalog, or routing by them on a gateway.
  • Checking that a name is a real service of the runtime.
  • Turning a service back on in baselines saved before this feature shipped (they have no record).
  • Console editing of these keys.

Completion conditions

  • A worker with ios.slim.exclude: ["com.apple.diagnosticd"] and categories: [] grants a slim lease a slim device in which no diagnosticd runs (on a Mac, real simulator).
  • A worker with ios.slim.include: ["com.apple.apsd"] and categories unset grants a slim device whose launchctl print-disabled system shows apsd not disabled and every other category label disabled (on a Mac, real simulator).
  • A worker restarted with com.apple.diagnosticd taken out of exclude prepares its surviving idle simulators with diagnosticd on.
  • A config with one name in both lists fails the daemon start with the message of I1.
  • The configuration reference lists both keys and says that categories and exclude turn services off and include keeps them running.

Open questions

none

Decisions

  • ADR 0083 — A worker may turn single slim services on or off beside its categories: the two lists, how they combine with categories and --except, the readback rule, and when a device is slim.
  • ADR 0060 — iOS slim writes launchd overrides while the simulator is shut down: the file, the readback and its table stay; 0083 narrows §1 and §2.
  • ADR 0066 — A slim lease may keep named categories running: the strict rule stays for --except only.
  • Decided with the maintainer: an include or exclude service not read back as written follows today's slim rule (full; a readback that cannot run grants slim), not --except's failing boot, because a plain slim boot that fails is not retried and a slow readback would fail every boot on that worker.
  • Decided in the session: a device is slim when at least one service is written off, because categories: [] with an exclude is Slim: opt-in control for simulator diagnosticd #1552's setup.
  • Decided in the session: a lease's --except category wins over exclude for its own services, because the lease asked for them running and ADR 0066 already lets a kept category win.
  • Decided in the session: exclude wins over simslim's never-disable list (assistantd, gamed, sharingd), because the operator named the service.
  • Decided in the session: any non-empty string is a name, duplicates are one name, and a typo is not caught, because launchd reads back whatever the file says and the shape was agreed as "any service name".
  • Decided in the session: device.slimmed keeps its fields; labelCount counts excluded services too and categories stays the categories, because the event's consumers read counts, not lists.
  • Decided with the maintainer: Simlock keeps a record of the include and exclude names it wrote beside each simulator's disabled.plist (S2), and turns a recorded name it no longer manages back on at the next prepare, because otherwise an idle simulator that survives a restart, or a baseline's copy, keeps a reverted exclude off with no warning; the file also holds lines the runtime wrote, so Simlock cannot reset lines without knowing which are its own.
  • Decided in the session: the both-lists check runs on the merged config through a check on the driver's config entry, as modules already have, because config.json and the CLI overrides are validated one layer at a time.

Behaviours

Id Behaviour (invoker, action, what it sees) Seam Cases Task
B1 An operator starts a worker with ios.slim.include and ios.slim.exclude; the config loads with both, or fails with I1's message. configFromLayers (src/core/config.ts:125) both lists set; one empty list; a duplicate in one list; a name in both (fails, names it); include in config.json and the same name in exclude in the overrides layer (fails); a string instead of a list (fails); an empty string (fails); config get ios.slim shows both #1650
B2 A slim prepare boot writes each managed label as S1's rule says. IosSimctlDriver.makeReady (src/drivers/ios/index.ts:372), fake simctl and filesystem include label of a slimmed category → false; exclude label in no category → true; exclude of a never-disable label → true; --except category with one of its labels in exclude → false; a line the file had for an unmanaged label is kept; a name in S2's record and in neither list now → false, and the record is rewritten to the current names; no record → treated as empty, not logged; a record that cannot be read as a list of strings → treated as empty, logged; a failed record write counts as a failed overrides write (ADR 0060 §2); a record that would not change is not written; a provisioned copy gets its source's record with its plist #1650
B3 That boot's readback grants the mode of I2. IosSimctlDriver.makeReady every label as written → slim and device.slimmed with labelCount counting the exclude label; an exclude label read back enabled → full, slim skipped logged; an include label read back disabled on a lease with no --except → full, no throw; readback fails → slim, logged; categories: [] + exclude → slim; nothing written off (include covers the slim set, or --except covers it with no exclude) → full, no device.slimmed; categories: [], no exclude → full, slim skipped as today #1650
B4 A lease with --except on a worker with include/exclude still fails its boot only on its kept categories, as today. IosSimctlDriver.makeReady a kept label read back disabled → KeptCategoriesError; an exclude label read back enabled → full, no throw #1650
B5 An operator reads the configuration reference and the slim guide and finds both keys. src/core/config-reference.test.ts (walks the validator shape) the reference table lists ios.slim.include and ios.slim.exclude #1650
B6 On a Mac, a slim lease on a worker with categories: [] and exclude: ["com.apple.diagnosticd"] gets a slim simulator in which no diagnosticd process runs; on a worker with categories unset and include: ["com.apple.apsd"], the readback shows apsd not disabled and every other category label disabled. slow lane, real simulator the two leases, iOS 26.4 or newer #1650

Stored state

Id What and where Created, changed, deleted by Listed or swept by A restart mid-step leaves Schema step Task Used by
S1 The lines of a slim simulator's /private/var/tmp/com.apple.CoreSimulator.SimDevice.<udid>/disabled.plist (ADR 0060). Managed labels are every category label, the never-disable labels, every include and exclude name, and every name in S2's record. Each is written, in this order of precedence (last wins): false (so a recorded name in neither list goes back on); true for a label of a category in categories and not in the lease's --except, never-disable labels excepted; true for an exclude name; false for an include name; false for a label of a --except category. SlimBoot.writeOverrides on every prepare of a slim spec; copied from a source by copyOverrides; removed by destroy — (as today) the file as written, or the old one; the next prepare writes it again none #1650 —
S2 Record of named services: simlock-managed.json in the same folder as S1, a JSON array of the include and exclude names last written, sorted, mode 0644. SlimBoot.writeOverrides after the plist, atomically, on a prepare of a slim spec when its contents change (an empty list with no file is no change, so a worker without the keys writes none); copied with the plist by copyOverrides; removed with the folder by destroy — the plist written and the old record: the old record still lists every name the plist may hold off, so the next prepare handles it none #1650 —

Interfaces

Id What Shape and bounds Errors and limits Where Task Used by
I1 Worker config keys ios.slim.include, ios.slim.exclude each optional; an array of non-empty strings, any characters; unset is []; duplicates count once. Worker config only (driver keys). a value that is not an array of non-empty strings: Invalid config value for "ios.slim.<key>": expected an array of strings (today's stringArray). A name in both: Invalid config value for "ios.slim": expected no service in both include and exclude (<names, comma-separated>). Both fail the config load. src/drivers/ios/definition.ts #1650 —
I2 Device mode of a slim prepare boot slim when at least one managed label is written true, the write was ok and every managed label reads back as written; otherwise ADR 0060 §2's table. No label written true → full, no device.slimmed; with neither categories nor exclude known, slim skipped is logged as today. --except leases keep ADR 0066 §2 for their kept labels only. no new error src/drivers/ios/slim-boot.ts #1650 —
I4 DriverConfigEntry.check optional (section, config) => void, run on the merged config after both layers, as runModuleChecks runs a module's; throws ConfigError the both-lists message of I1 src/core/config-types.ts, src/core/config-role-checks.ts #1650 —
I3 device.slimmed fields unchanged; labelCount is the managed labels written true, exclude names included — EVENTS.md device.slimmed #1650 —

Existing code

Commit 1cd9315.

Searches: rg -n "slim" src --include=*.ts minus tests (43 files; read the iOS driver's slim-*, definition.ts, catalog.ts, seeds.ts, index.ts); rg -n "copyOverrides|writeOverrides|KeptCategoriesError" src (8 hits); rg -n "validatorShape" src (2 files); rg -ln "slim" website/src/content/docs (15 files; read reference/configuration.mdx, using-devices/choosing-a-device.mdx, reference/events.mdx, reference/errors.mdx); rg -ln slim ui/src (no config editor).

Id Code (path:line) Today With this feature Handled by
X1 src/drivers/ios/definition.ts:12-17, :49 slim is {categories, bootTimeoutMs}; objectValidator warns on any other key (src/core/validation.ts:41) adds include, exclude to the objectValidator shape (so validatorShape, src/core/validation.ts:23-51, still lists them for the reference test) and the both-lists check as the entry's I4 check B1, B5
X11 src/core/config-types.ts:266-275 DriverConfigEntry; src/core/config-role-checks.ts:133-136 runModuleChecks; src/core/config.ts:150-160 (layers validated one at a time) a driver entry has no check on the merged config; a module entry has check gains I4, run where module checks run B1
X2 src/drivers/ios/slim-labels.ts:349-364 overridesFor category labels and never-disable labels; kept categories win takes include and exclude in S1's order B2
X3 src/drivers/ios/slim-boot.ts:161-168 no known category → no-categories, no write, full, slim skipped no-categories only when no category and no exclude name B3
X4 src/drivers/ios/slim-boot.ts:245-246 an --except covering the slim set → full, no event no label written true → full, no event B3
X5 src/drivers/ios/slim-boot.ts:206, :217; slim-except.ts:33-43 strict failures when kept is not empty; kept = the lease's --except categories unchanged; include names never join kept B4
X6 src/drivers/ios/slim-boot.ts:232-240 a managed label not as written → full the same, now over include/exclude names too B3
X7 src/drivers/ios/seeds.ts:172, :249 copyOverrides a baseline or seed's file is copied into each copy before its first boot copies S2 beside the plist; a source saved before this feature has none, so a dropped name stays true in its copies (known gap, manual) B2
X8 src/drivers/ios/catalog.ts:82, :206 checkExcept and slimCategories from categories unchanged: no catalog or routing change —
X9 src/drivers/ios/slim-boot.ts:261 labelCount counts every label written true counts exclude names with no code change B3
X10 website/src/content/docs/docs/reference/configuration.mdx:206; using-devices/choosing-a-device.mdx:107-118; docs/internal/EVENTS.md:106; src/drivers/ios/AGENTS.md (slim rules, Known gaps) categories only both keys, the precedence, the record, the typo and old-baseline gaps B5

Tasks

  • Slim: worker include and exclude lists of single services #1650 Slim: worker include and exclude lists of single services — an operator keeps single services running or turns them off on slim simulators from the worker config. Risk: a service that should run stays off (push, StoreKit, log stream), or a slim worker grants full devices.

Completion conditions: all five by #1650 (the real-simulator ones through its slow-lane Done when line).

Open work in the same area:

Written by an agent.

Activity

  1. added
    feature:specSpec in progress, business and technical together.
    on Nov 17, 2026
  2. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Design posted: business sections, Decisions (ADR 0082), Behaviours B1–B6, S1, I1–I3, Existing code.

    Written by an agent.

  3. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Spec updated: task #1650 posted; Tasks section and Task cells filled.

    Written by an agent.

  4. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Spec updated: the ADR is renumbered 0083 (PR #1647 holds 0082); S2's record is written only when it changes; #1651 listed under open work; #1650 names the slim test helper and the write checks it touches.

    Written by an agent.

  5. added
    feature:plannedSplit into tasks. Never picked up itself.
    and removed
    feature:specSpec in progress, business and technical together.
    on Nov 17, 2026
  6. V3RON commented on Nov 17, 2026

    @V3RON
    ContributorAuthor

    Delivery run

    Merged: none
    Parked: #1650 — PR #1655 ready and needs-hardware: the slow lane refused this machine (10.2 GiB free disk, needs 15); the stack #1646 → #1655 waits on it
    Waiting: none
    Decided: none

    Written by an agent.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    feature:plannedSplit into tasks. Never picked up itself.

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions