PwrSnap: Skill for Codex

PwrSnap macOS VM E2E lab

PwrSnap does not own the Tart lab, runner VMs, or guest OS baseline — PwrSuiteLab does. Product tests and CI contracts belong here; lab inventory, configuration, transport, diagnosis, and recovery belong only there. Do not provision a product-local Tart lab, clone a base image, or register a runner from this repository, and never copy private lab details into PwrSnap (see AGENTS.md for what that covers).

Why this exists

Headed desktop E2E takes over the screen: it opens windows, steals focus, and drives the region selector and global hotkeys. Run on the operator's own desktop it interrupts whatever they are doing and can pull their real windows into a capture under test.

Prefer Control MCP

Discover the available PwrSuiteLab Control MCP tools and read their live input schemas and served skill://manage-pwrlab-e2e/SKILL.md before operating. Use that skill for the current job, ownership, transport, and recovery contract; do not assume this product guide replaces it. If a tool discovery client is available, search its live MCP connections even if no lab tools were initially registered. Discover skills with skills/list and skills/get (or resources/list for older clients), then read the served skill with resources/read.

An Operate grant authorizes the exposed MCP actions for the requested work without per-operation native confirmation. A Read only grant does not. Keep the requested target and test scope; a grant does not authorize unrelated work or bypass controller safety checks. Do not ask again for an already authorized run. Running on the operator's own desktop still requires explicit approval.

• Use lab_status and the exact dedicated E2E target it returns. Never use a GitHub Actions runner or the physical desktop for this workflow. Check status before preparing and again before submitting a run; idle shutdown can stop the VM between jobs, and lab_e2e_run starts it when needed.
• Both lab_e2e_run and lab_e2e_acquire require top-level agent_name, project_name, and thread_name, including when consuming a reservation. Use actual display attribution (PwrSnap for the project); use a descriptive task title if the thread title is unavailable. Include pr_number as a decimal string only when applicable and known; omit it otherwise. These labels are not authentication. Never include secrets or local paths in them.
• job.repository is the absolute path to this thread's exact clean, committed worktree. Check untracked files too; never discard changes to make it clean. Only committed HEAD and locally available submodule/LFS content travel. Obtain needed LFS objects before submission. No push or named-workload enrollment is required; the repository must be local to Control's host.
• job.setup is an ordered array of argv arrays; job.command is an argv array. Explicit ["bash", "-c", "..."] is allowed for shell setup. All commands run in the guest. Select runtime versions, dependency installation, native rebuild/build, and narrow tests from PwrSnap's current package scripts and CI. The concrete example lives in CONTRIBUTING.md. Never install tools on the host as a workaround or copy credentials.
• Bound the timeout and artifact paths to this task. Artifacts are relative checkout paths, with no traversal or symlinks; do not collect a whole home directory or dependency tree. The live schema sets the current limits.
• Save both the returned request ID and run_id. Poll lab_request_status with the request ID for operation status; a completed launch with job_state: running is not a passing test. Use lab_e2e_collect with the exact target and saved run_id for job progress and artifacts, polling its request ID if necessary. Inspect the returned artifact directory, e2e.log, exit code, and artifact completeness. Distinguish setup and test failures.
• On Invalid tool or arguments, inspect the current schema and missing or mistyped fields first, especially attribution and argv arrays. This is a schema/tool mismatch, not evidence that an Operate grant was lost. Correct the call; do not request reauthorization or switch to scripts/raw SSH to evade a validation or permission refusal. If launch or transport failed, inspect any returned run ID before retrying: the guest may already be running.