Skip to content

State-tagged probe template

Status: verified — 2026-05-02 (D40 distillation)

Distilled from the D40 state-aware retrospective (originally notes/d40-state-retrospective.md §F, since deleted per feedback_notes_are_temporary_buffer). The retrospective surfaced the meta-observation that probes D20..D39 ran in different apparatus states without recording it, producing apparent inconsistencies (D31 Run #2 SUCCESS vs D29 0/N) that may have been state-conditional rather than race-jitter. D40 P1 retest later falsified that specific hypothesis (apparatus state does not influence AUA outcome — see ../research/coredevice-internals/aua-history-d38-d40.md §"D40 update" + the D40 P1 entry in ../plans/d66-history-q15-d34-d40.md), but the discipline of capturing state at trigger remains project-wide policy per memory rule feedback_state_tagged_testing.md. This runbook is the forward-looking template that operationalises that policy.

When this runbook applies

Every probe agent dispatched after 2026-05-02 that involves an AUA trigger (or any trigger that fans out through com.apple.coredevice.action.acquireusageassertion) populates the §0 block below in its notes file BEFORE the trigger fires. Any cross-probe comparison cites both probes' Dimensions 1-8 alongside the result; differences in any dimension invalidate the comparison unless explicitly justified.

This is procedural. The data captured here does not by itself explain anything — it lets a future investigator decide whether two probes' results are even comparable.

Notes file template

# <task-id> <descriptive title>

Status: in progress

## §0 — Apparatus state at trigger (REQUIRED — populate FIRST)

### State capture timestamp

2026-05-NN HH:MM:SS UTC (also record host wall-clock in MSK/PT/etc).

### Dimension 1 — Xcode UI state

- Xcode running: yes/no (PID if yes)
- Xcode launched-via-wrapper: yes/no
- Devices window: closed / open-no-row / open-iPhone-row-visible /
  open-iPhone-row-selected
- Pair button last clicked: timestamp / never-this-session / unknown
- Last `_shadowUseAssertion.fulfilled` transition: timestamp /
  never-this-session / unknown

### Dimension 2 — CDS state

- CoreDeviceService PID: <pid>
- CoreDeviceService etime: <hh:mm:ss> (since last spawn)
- AUAs handled this CDS lifetime: count from `pgrep`-correlated log
  scan
- Multiple CDS PIDs concurrent: yes/no (list all if yes)

### Dimension 3 — devicectl state

- Trigger path: naked-cli / wrapper-cli / Xcode-spawned /
  lldb-launched / dtrace-launched
- DYLD_INSERT_LIBRARIES env: empty /
  `iosmux_devicectl_inject.dylib` + sha
- Xcode-side inject env active (if Xcode-launched-via-wrapper):
  yes/no + dylib sha

### Dimension 4 — Apparatus age

- VM uptime: <hh:mm:ss>
- Last reboot: timestamp
- Last `iosmux-restore.sh` invocation: timestamp
- AUA invocations since last restore: count

### Dimension 5 — Trigger type

- Command: full argv preserved verbatim
- Initiator: human-cli / agent-script / Xcode-auto-poll / Xcode-UI

### Dimension 6 — Inject configuration

- CDS-side inject: D23 v2 / D30 / D37-G / D38 / other (sha)
- devicectl-side inject: none / D38 G-x / D41 G-2 / other (sha)
- Xcode-side inject: none / D39 H#2 / other (sha) — and
  ACTIVATED yes/no

### Dimension 7 — Probe instrumentation

- log-only / lldb-attached / dtrace-attached / JSONL-counter /
  static-only

### Dimension 8 — Ambient log baseline

- Pre-trigger line count of `Successfully acquired usage assertion`
  in unified-log lookback window: <N>
- Pre-trigger line count of `Failed to acquire usage assertion`:
  <N>
- Lookback window: `--last <duration>` value

## §A onwards — task-specific sections

(Original probe-specific structure resumes here.)

## §Z — Post-trigger state delta (REQUIRED)

For each Dimension 1-8, capture what changed during/after the
probe. Specifically:

- New process IDs spawned.
- Inject dylib sha post-probe (must equal pre-probe sha — any
  delta = STOP CONDITION).
- Apple binary sha post-probe (must equal expected — any delta
  = STOP CONDITION + apparatus damage).
- Diagnostic reports generated (must be empty — any new entry
  = STOP CONDITION).
- Path-A success line count delta: <N>.
- Path-B failure line count delta: <N>.
- Sample latencies (success-reply → outcome-line): <ms>.

Comparison rules

When citing a result from a prior probe for comparison, the citing probe MUST also cite the prior probe's Dimensions 1-8. If they differ from the current probe's, cite as "different state" and DO NOT use the prior result as a baseline.

Concrete:

  1. Probes from different Xcode states → no comparison.
  2. Probes with different inject configurations → no comparison unless the inject is on a code path the test doesn't exercise.
  3. Probes with different instrumentation → comparison only at the architectural-mechanism level, not at the timing or path-A/path-B-rate level.
  4. Path-A vs Path-B counts only valid within the same cell.
  5. Latency comparisons valid only with same Dimension 4 (apparatus age bucket: cold-boot / warm <1h / aged 1-24h / continuous >24h).

Empirically-corrected state taxonomy (2026-05-02)

D40 originally enumerated 8 dimensions with sub-states each. After running D40 P1 retest across the matrix the user collapsed the Xcode UI state axis (Dimension 1) to three operational cells that empirical history split on:

Cell Description
S1 (cold) post-VM-reboot + iosmux-restore.sh, Xcode NOT launched.
S2 (warm Xcode + Devices&Sims) Xcode running from Dock, Devices and Simulators window open, iPhone (iosmux) row visible, Pair NOT clicked.
S3 (post-Pair) as S2 + iPhone row clicked, Xcode auto-fires AUA, "Failed to acquire assertion" appears in ERRORS AND WARNINGS UI section.

The fuller 6-cell S1-S6 taxonomy in D40 brief was state-overengineering; empirical history split only on Pair-clicked-yes-no axis, not on Devices-window-open vs not. Dimensions 2-8 stay multi-valued; only Dimension 1 collapses to S1/S2/S3 in practice.

D40 P1 retest empirically falsified the "state determines AUA outcome" hypothesis (cumulative 66/66 Path-B deterministic across S1, S2, S3, S1+G2 wrap, S3+G2 wrap, plus the historical D29 0/30 baseline). State capture is still required for cross-probe discipline but not for outcome prediction within the AUA-failure class — every state cell currently produces deterministic Path-B in the D23 v2 + GAMBIT configuration.

See also