m-19 VM Testing restructure (CI sanity)

.changeset/cli-error-shape-unified.md

@@ -67,7 +67,7 @@ Update parsers to:
 
 ## New ergonomics
 
-`packages/podkit-cli/src/test-utils/cli-error.ts` and `packages/e2e-tests/src/helpers/cli-error.ts` export `expectCliError` for asserting on the canonical shape in one call.
+`packages/podkit-cli/src/test-utils/cli-error.ts` and `test-packages/e2e-host-tests/src/helpers/cli-error.ts` export `expectCliError` for asserting on the canonical shape in one call.
 
 `OutputContext` now takes an optional `ExitCodeSink` (default: writes `process.exitCode`; tests use `BufferExitCodeSink` to avoid process-global mutation).
 

.changeset/config.json

@@ -7,6 +7,6 @@
   "access": "public",
   "baseBranch": "main",
   "updateInternalDependencies": "patch",
-  "ignore": ["@podkit/gpod-testing", "@podkit/e2e-tests"],
+  "ignore": ["@podkit/gpod-testing", "@podkit/e2e-host-tests"],
   "privatePackages": { "version": true, "tag": false }
 }

.changeset/consolidate-unsupported-reason.md

@@ -0,0 +1,8 @@
+---
+"podkit": minor
+"@podkit/core": minor
+"@podkit/devices-ipod": minor
+"@podkit/device-types": minor
+---
+
+Consolidate the two ways podkit expressed "this device is unsupported" into one canonical shape. `ReadinessUnsupportedReason` moves to `@podkit/device-types` (its natural home), and `resolveIpodModel(bag)` now returns it directly on `IpodModel.unsupportedReason` instead of the bare-string `notSupportedReason`. The bridge functions in `@podkit/core` (`makeUnsupportedReasonFromModel`, `makeUnsupportedReasonFromAssessment`) are removed — consumers read `model.unsupportedReason` directly. Internal refactor; user-facing CLI behaviour is unchanged.

.changeset/device-add-volume-uuid-required.md

@@ -0,0 +1,5 @@
+---
+"podkit": patch
+---
+
+`podkit device add` now refuses cleanly when an iPod's volume UUID can't be read, with a clear message + structured error code (`VOLUME_UUID_REQUIRED`). Previously a synthetic `manual-...` UUID could be persisted in config, which then broke replug detection and `podkit doctor -d <name>` lookups. Most-common cause (HFS+ on Linux) was already addressed in TASK-317.12; this is the defensive catch-all for any remaining edge cases (corrupt partition tables, unusual layouts).

.changeset/device-config-unsupported-rich-shape.md

@@ -0,0 +1,5 @@
+---
+"podkit": minor
+---
+
+`DeviceConfig.unsupported` (the marker for devices the user added via the warn-allow flow in TASK-317.03) is now a structured object (`{ kind, confirmedAt }`) instead of a bare boolean. The `kind` captures which unsupported-reason class triggered the prompt (iOS device, hashAB nano, mass-storage with no preset, etc.) so a future reader can tell why the device was confirmed. The `confirmedAt` ISO timestamp records when. Legacy `unsupported = true` config entries are silently coerced to the new shape on load.

.changeset/device-scan-unsupported-reason.md

@@ -0,0 +1,29 @@
+---
+"podkit": minor
+---
+
+`podkit device scan --format json`: rename `notSupportedReason: string` to `unsupportedReason: ReadinessUnsupportedReason` on USB-only device entries
+
+The JSON envelope for `device scan` previously carried unsupported-device
+diagnostics as a bare `notSupportedReason` string. It now matches the structured
+`ReadinessUnsupportedReason` shape already used by the readiness pipeline and
+`IpodModel.unsupportedReason`:
+
+```json
+{
+  "unsupportedReason": {
+    "kind": "ios-device",
+    "headline": "iPod Touch is not supported by podkit.",
+    "docsUrl": "https://jvgomg.github.io/podkit/devices/supported-devices/"
+  }
+}
+```
+
+Consumers reading `device.notSupportedReason` should read
+`device.unsupportedReason.headline` instead — the same string, just nested
+under the typed payload. The change applies to both USB-only iPod entries
+(touch, iPhone, iPad, nano 6G/7G, shuffle 3G/4G) and to vendor-recognised
+mass-storage devices with no matching preset.
+
+The same rename also lands on the internal `IpodIdentity` and
+`IpodClassification` shapes, but those are not part of the public CLI surface.

.changeset/diagnostic-scope-three-way.md

@@ -0,0 +1,6 @@
+---
+"podkit": minor
+"@podkit/core": minor
+---
+
+Refactor the diagnostic-check scope model from a 2-field shape (`scope: 'system' | 'device'` + `category?: 'readiness' | 'database'`) to a single required 3-way union (`scope: 'system' | 'device-readiness' | 'database-health'`). Compile-time enforcement that every check declares which section it renders into; no more silent fallback when `category` is missing. The user-facing CLI `--scope` flag values are unchanged.

.changeset/doctor-consistent-sections.md

@@ -0,0 +1,6 @@
+---
+"podkit": minor
+"@podkit/core": minor
+---
+
+`podkit doctor` now renders a consistent `System` / `Device Readiness` / `Database Health` section structure across all device types. Previously, mass-storage devices (Echo Mini) collapsed everything into a single `Device Health` bucket and mis-categorised three system-scope checks. The fix audits every check's `scope` tag, adds a `category?: 'readiness' | 'database'` discriminator so device-scope checks can be routed to the right subsection, and skips `iPod Firmware Inquiry Methods` on non-iPod devices.

.changeset/doctor-repair-correctness.md

@@ -0,0 +1,11 @@
+---
+"podkit": patch
+"@podkit/core": patch
+"@podkit/ipod-firmware": patch
+---
+
+Fix three `podkit doctor` repair correctness bugs:
+
+- `--repair sysinfo-consistency` now overwrites a stale on-disk SysInfoExtended (previously short-circuited on file existence, reporting success without rewriting).
+- `--repair sysinfo-extended` no longer requires an existing iTunesDB — repairs without a `database` requirement skip the DB open so identity-populating repairs work on freshly formatted iPods. New `'database'` value on `RepairRequirement`.
+- The readiness `SysInfoExtended:` status line distinguishes a missing file from a present-but-unparseable one.

.changeset/doctor-scope-system.md

@@ -0,0 +1,9 @@
+---
+"podkit": minor
+---
+
+Add `podkit doctor --scope <system|device|all>` for running host-environment checks without a registered device.
+
+`--scope system` skips device resolution entirely and runs only the system-scope checks (FFmpeg, codec encoders, video encoder, libgpod runtime, SCSI inquiry, udev rule on Linux). Useful before plugging an iPod in for the first time, and required by the m-19 Tier-3 test harness to assert host-state against a captured `SystemState` fixture.
+
+`--scope device` requires `-d/--device` and runs only device-scope checks. `--scope all` (default) preserves the existing combined output byte-for-byte; the legacy `--no-system` flag still applies in that mode. JSON output under `--scope system` uses a discriminator field (`scope: "system"`) so consumers can distinguish the two envelopes.

.changeset/inquiry-orchestrator-error-detail.md

@@ -0,0 +1,6 @@
+---
+"podkit": patch
+"@podkit/ipod-firmware": patch
+---
+
+Improve the firmware-inquiry orchestrator's failure message so users can see what went wrong without `-vv`. The default error now names every transport attempted (USB, SCSI) with each one's failure reason on its own line and includes a remediation hint (e.g. `podkit doctor --repair udev-rule` for EACCES on `/dev/sg*` or `/dev/bus/usb/...`). The orchestrator also no longer short-circuits a planned SCSI fallback when USB hits a permission wall — both transports run if the plan calls for it.

.changeset/reconcile-discovery.md

@@ -0,0 +1,6 @@
+---
+"podkit": minor
+"@podkit/core": minor
+---
+
+Reconcile USB-inquiry and block-device discovery so each connected iPod renders once in `podkit device scan`. Previously, `device scan` could surface the same physical iPod twice on Linux when both pipelines independently identified it. The orphan entry also surfaced a destructive remediation (`Needs partitioning — see: podkit device init`) on a healthy device. Both issues fixed: a new reconciliation primitive matches USB and block-device records by serial number (or disk identifier as fallback), and the readiness-failure copy now points at docs instead of suggesting an inappropriate command.

.changeset/refuse-hfsplus-on-linux.md

@@ -0,0 +1,12 @@
+---
+"podkit": minor
+"@podkit/core": minor
+---
+
+Refuse HFS+ iPods on Linux at `device add`; warn at `device scan`
+
+iPods formatted as HFS+ are now refused on Linux at `podkit device add` time, with a clear message pointing at docs explaining how to reformat to FAT32. `podkit device scan` surfaces the same iPods with a `Filesystem not supported on Linux` warning instead of running readiness stages or suggesting destructive remediation. macOS HFS+ behaviour is unchanged.
+
+Why: the Linux kernel hfsplus driver refuses RW on journaled HFS+ (the iPod default), udev/blkid don't surface a filesystem UUID for HFS+ on Linux (breaking podkit's identity model), and udisksctl mount paths fall back to a generic name with no label. Each friction point has a partial fix; together they mean Linux + HFS+ is a second-class experience no matter how much we patch. Refusing cleanly with a docs link sharpens podkit's Linux story to "FAT32 iPods, supported well."
+
+Structured `--json` output preserves a stable error code (`UNSUPPORTED_FILESYSTEM_ON_LINUX`) so scripted callers can handle the refusal.

.changeset/sysinfo-modelnum-mismatch-check.md

@@ -0,0 +1,6 @@
+---
+"podkit": patch
+"@podkit/core": patch
+---
+
+New `podkit doctor` check `sysinfo-modelnum-mismatch` detects when the on-disk classic SysInfo file's `ModelNumStr` disagrees with the firmware-derived identity (e.g. SysInfo manually edited, or files copied from another iPod). Offers `--repair sysinfo-modelnum-mismatch` to overwrite the on-disk file with firmware-derived data. Identified during the TERAPOD (iPod 5G with iFlash mod) inventory pass — the SysInfo claimed `MA147` (5G) while the serial said `V9M`/`A446` (5.5G).

.changeset/udev-rule-usb-subsystem.md

@@ -0,0 +1,6 @@
+---
+"podkit": patch
+"@podkit/core": patch
+---
+
+Extend the podkit udev rule to grant Apple-vendor USB device access (`/dev/bus/usb/<bus>/<dev>`) in addition to the existing SCSI generic (`/dev/sg*`) coverage. Linux libusb-based firmware inquiry now works without sudo from SSH sessions, headless boxes, Docker containers, and CI — the SSH-session permission gap previously closed only the SCSI half. `podkit doctor --repair udev-rule` installs the extended rule and cleans up any legacy filename from previous installs.

.changeset/unsupported-device-cascade.md

@@ -0,0 +1,17 @@
+---
+"podkit": minor
+"@podkit/core": minor
+---
+
+Unify the unsupported-device UX across `podkit device add`, `device scan`, `device info`, `sync`, and `doctor`. Every command now composes identity via the same cascade primitive (`resolveIpodModel(bag)`) — no command re-implements the check, no command leaks `libgpod` into user-facing copy.
+
+Key behaviour changes:
+- `device add` on an unsupported device (hashAB nano, etc.) now asks "Add anyway? [y/N]" rather than hard-refusing. Confirmed devices are recorded with `unsupported: true` in config; `--yes` flips the default to accept.
+- `device add` against an iOS device (iPod touch) now surfaces the canonical unsupported message instead of the generic "No iPod devices found".
+- `device scan` headers show the resolved model name (e.g. "iPod touch 5th generation") instead of "Unknown iPod (USB only)".
+- `sync --dry-run` refuses cleanly on unsupported devices with the canonical message — no track plan generated.
+- `sync` on a supported device with SysInfoExtended present resolves identity via the cascade; the legacy "Could not identify iPod model" warning is gone for that case.
+- `device info` renders the cascade `displayName` instead of the libgpod-derived `info.device.modelName`.
+- `doctor` on an unsupported device suppresses repair suggestions that would mutate device state and surfaces the canonical unsupported message instead.
+
+Wording is centralised in `@podkit/core` (`makeUnsupportedReasonFromAssessment` / `makeUnsupportedReasonFromModel`) — every consumer imports.

.gitignore

@@ -50,4 +50,10 @@ test/manual-collection/
 SCRATCH.md
 
 .claude/worktrees
-branding/
+branding/
+
+# Bun --compile temp files (occasionally orphaned with 000 perms after kill -9)
+*.bun-build
+
+# Locally-built native bindings (published via prebuild.yml CI, never committed)
+packages/libgpod-node/prebuilds/

AGENTS.md

@@ -10,24 +10,33 @@ Instructions for AI agents (Claude Code, Cursor, etc.) working in this repositor
 
 **Monorepo structure:**
 ```
-packages/
+packages/            # Published / published-adjacent packages
+├── compatibility/   # Cross-version compatibility helpers
 ├── demo/            # Animated GIF demo (VHS + mocked CLI build)
 ├── device-types/    # Shared TypeScript types for device capabilities, identity, firmware
 ├── devices-ipod/    # Pure TypeScript iPod generation tables + capability synthesis (no libgpod)
 ├── devices-mass-storage/ # User-extensible mass-storage preset framework (Echo Mini, Rockbox, generic)
-├── e2e-tests/       # End-to-end CLI tests (dummy + real iPod)
-├── gpod-testing/    # Test utilities for iPod environments (no hardware needed)
+├── docs-site/       # Documentation site (Starlight/Astro)
+├── ipod-avatar/     # iPod avatar image assets
 ├── ipod-db/         # Pure TypeScript iTunesDB/ArtworkDB parser (browser-compatible)
 ├── ipod-firmware/   # iPod firmware inquiry — SCSI via koffi (SG_IO/IOKit), USB via the `usb` npm package
 ├── ipod-web/        # Virtual iPod UI — React + Jotai web component
 ├── libgpod-node/    # Native Node.js bindings for libgpod (database operations only; no USB/libusb)
 ├── podkit-core/     # Core sync logic, adapters, transcoding
 ├── podkit-cli/      # Command-line interface
 ├── podkit-docker/   # Docker image (Dockerfile, entrypoint, compose files)
-├── test-fixtures/   # Test fixture generator (FLAC files with controllable metadata/artwork)
+├── podkit-daemon/   # Background sync daemon
 ├── virtual-ipod-app/    # Tauri macOS app — frameless iPod-shaped window
 └── virtual-ipod-server/ # Lima VM backend — USB gadget + REST/WebSocket API
 
+test-packages/             # Testing infrastructure (private, not published)
+├── device-testing/        # VM test harness — DevicePersona + SystemState registries, TestRuntime, Lima yamls, apply-state.sh
+├── device-testing-daemon/ # FunctionFS userspace daemon — synthesises iPod USB gadget on dummy_hcd
+├── e2e-host-tests/        # End-to-end CLI tests on the host (dummy + real iPod)
+├── e2e-vm-tests/          # End-to-end podkit feature tests inside the Lima VM
+├── gpod-testing/          # Test utilities for iPod environments (no hardware needed)
+└── test-fixtures/         # Test fixture generator (FLAC files with controllable metadata/artwork)
+
 tools/
 ├── demo/            # Live demo documentation for the virtual iPod system
 ├── gpod-tool/       # C CLI for iPod database operations
@@ -199,7 +208,7 @@ The virtual iPod system creates a synthetic iPod for demonstrating podkit. It co
 - `@podkit/virtual-ipod-server` — Runs inside a Lima VM. Manages USB gadget via configfs + dummy_hcd (Apple vendor/product IDs). Serves iPod filesystem over REST + WebSocket. podkit sees the virtual device as a real iPod with zero code changes.
 - `@podkit/virtual-ipod-app` — Tauri v2 macOS app. Frameless transparent window shaped like an iPod. Manages Lima VM lifecycle.
 
-**Lima VM (`tools/lima/virtual-ipod.yaml`):**
+**Lima VM (`tools/lima/podkit-virtual-ipod.yaml`):**
 - Debian 12 with dummy_hcd + configfs USB gadget support
 - `mise run vipod:install` rsyncs source to `/opt/podkit/` (VM-local, won't touch macOS node_modules), builds, and installs podkit binary to `/usr/local/bin`
 - `mise run vipod:shell` drops into an isolated `james@lima-virtual-ipod:~$` with podkit in PATH and tab completion
@@ -241,12 +250,17 @@ Key files to understand:
 | CLI entry | `packages/podkit-cli/src/main.ts` |
 | Core library | `packages/podkit-core/src/index.ts` |
 | libgpod bindings | `packages/libgpod-node/src/index.ts` |
-| Test utilities | `packages/gpod-testing/src/index.ts` |
-| E2E test helpers | `packages/e2e-tests/src/helpers/index.ts` |
+| Test utilities | `test-packages/gpod-testing/src/index.ts` |
+| E2E test helpers | `test-packages/e2e-host-tests/src/helpers/index.ts` |
+| VM test harness | `test-packages/device-testing/src/index.ts` |
+| VM test entry | `test-packages/e2e-vm-tests/src/` |
+| FunctionFS daemon | `test-packages/device-testing-daemon/src/main.ts` |
+| VM test Lima configs | `test-packages/device-testing/lima/` |
+| apply-state.sh | `test-packages/device-testing/scripts/apply-state.sh` |
 | gpod-tool CLI | `tools/gpod-tool/gpod-tool.c` |
 | Demo build | `packages/demo/build.ts` |
 | Demo tape | `packages/demo/demo.tape` |
-| Test fixture generator | `packages/test-fixtures/src/index.ts` |
+| Test fixture generator | `test-packages/test-fixtures/src/index.ts` |
 | Docker entrypoint | `packages/podkit-docker/entrypoint.sh` |
 | Dockerfile | `packages/podkit-docker/Dockerfile` |
 | Linux device manager | `packages/podkit-core/src/device/platforms/linux.ts` |
@@ -261,7 +275,7 @@ Key files to understand:
 | Virtual iPod server | `packages/virtual-ipod-server/src/main.ts` |
 | Virtual iPod USB gadget | `packages/virtual-ipod-server/src/gadget.ts` |
 | Virtual iPod Tauri app | `packages/virtual-ipod-app/src/App.tsx` |
-| Virtual iPod Lima config | `tools/lima/virtual-ipod.yaml` |
+| Virtual iPod Lima config | `tools/lima/podkit-virtual-ipod.yaml` |
 | Live demo guide | `tools/demo/README.md` |
 | Device-types entry | `packages/device-types/src/index.ts` |
 | iPod identity | `packages/devices-ipod/src/identity.ts` |