# iPhone / LixelGO capture lab

This is an isolated evidence tool for the XGRIDS K1 plugin. It is not a Mission
Core runtime dependency and must not be bundled without a separate GPL license
review.

## Install without Xcode

From the repository root:

```bash
uv sync --project plugins/xgrids-k1/lab/iphone-capture --frozen
```

The environment is created under the lab directory. It pins
`pymobiledevice3==9.36.0`; it does not modify the system Python, Homebrew, the
Mission Core `.venv`, or the root lockfile.

## USB preflight

Connect exactly one iPhone with a data-capable USB cable, unlock it, confirm the
Mac accessory prompt, and tap **Trust This Computer** on the iPhone. Then run:

```bash
uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
  python plugins/xgrids-k1/lab/iphone-capture/preflight.py
```

The preflight prints only a device count. It never prints or stores the iPhone
UDID or serial number.

## Bounded network capture

Run this only after the post-refactor exact-profile K1 regression in ADR 0004:

```bash
uv run --project plugins/xgrids-k1/lab/iphone-capture --frozen \
  python plugins/xgrids-k1/lab/iphone-capture/capture.py \
  --duration 120
```

The capture uses the iPhone `pcapd` service over USB, suppresses packet hex on
stdout, and writes private artifacts under ignored
`sessions/iphone-k1-observation/`. It is intentionally bounded to 5–600 seconds.
Each successful run retains the original metadata-bearing `PCAPNG` and creates a
classic Ethernet `PCAP` that the macOS bundled `tcpdump` can read. The redacted
manifest records the validated packet count and hashes both artifacts.
The default refuses a dirty repository; `--allow-dirty` records a source-tree
fingerprint when an explicitly approved lab run cannot wait for a commit.

Operator events may be recorded while the capture is active and can finish
after the bounded network process exits. Preserve the original capture manifest
and create a separate integrity inventory after the operator timeline is closed:

```bash
uv run python plugins/xgrids-k1/lab/iphone-capture/session_integrity.py \
  sessions/iphone-k1-observation/<session>
```

The sealer re-hashes every manifest artifact, adds the manifest and optional
`operator-events.private.jsonl`, and writes an ignored mode-`0600`
`integrity.private.json`. It never edits the original manifest or raw capture.

Do not add `--bluetooth` unless Apple's Bluetooth diagnostic logging profile is
already installed on the iPhone and the operator explicitly approved that
configuration change. The script never installs the profile.

Wireshark is optional and is not required to record PCAP/PCAPNG. Full Xcode is
also not required for this path.