openclaw-parallels-smoke skill

OpenClaw Parallels Smoke

Use this skill for Parallels guest workflows and smoke interpretation. Do not load it for normal repo work.

Global rules

for the bounded beta-publish phase. Run it against one exact published package version and record the Validation SHA + Tooling SHA run tuple that authorized that package. Validation SHA maps to its Code SHA or Release SHA; it is not a third release identity.

• Parallels is postpublish-confidence coverage by default, not a prerequisite

Classify it as product, harness/tooling/provenance, infrastructure/credential, or wrapper failure. Only a confirmed product defect enters the next beta.

• A failed postpublish Parallels lane does not retroactively unpublish a beta.

retry one failed family once, then reassess; do not restart the aggregate matrix automatically.

• Use one coordinator and one lane per independent guest family. Diagnose and

snapshot matches the requested baseline, switch to it and reuse its user, tools, and base setup. Do not create a new VM, reinstall macOS, or rebuild the guest baseline for a "fresh" run.

• Inventory existing VMs and snapshots before provisioning anything. When a preconfigured pristine

Do not create ad-hoc snapshots unless the user explicitly asks or no suitable baseline exists; restore the original snapshot and leave the guest stopped after an ad-hoc run.

• "Fresh" means restoring the closest existing pristine snapshot, not creating another snapshot.

preconfigured logged-in session; switch to it normally so Parallels resumes that session. Do not pass --skip-resume at test entry unless the run intentionally needs to discard the saved session and boot from the login window. --skip-resume is acceptable for final cleanup that must leave the restored source guest stopped.

• Inspect the snapshot state before restoring it. A pristine poweron snapshot can contain the

If a lane hits the cap, stop there, inspect the newest /tmp/openclaw-parallels-* run directory and phase log, then fix or rerun the smallest affected lane. Do not keep waiting on a capped lane.

• Gateway verification in smoke runs should use openclaw gateway status --deep --require-rpc unless the stable version being checked does not support it yet.
• Stable 2026.3.12 pre-upgrade diagnostics may require a plain gateway status --deep fallback.
• Treat precheck=latest-ref-fail on that stable pre-upgrade lane as baseline, not automatically a regression.
• Pass --json for machine-readable summaries.
• Per-phase logs land under .artifacts/parallels/openclaw-parallels- by default. Override with OPENCLAWPARALLELSARTIFACTROOT when a run needs another artifact volume.
• Do not run local and gateway agent turns in parallel on the same fresh workspace or session.
• Hard-cap every top-level Parallels lane with host timeout --foreground (or gtimeout --foreground if that is the available binary) so a stalled install, snapshot switch, or prlctl exec transport cannot consume the rest of the testing window. Defaults:
• macOS: 75m
• Linux: 75m
• Windows: 90m
• aggregate npm-update wrapper: 150m

Keep each lane in its own shell/session and track the run directory for each one. Before starting the matrix, run any required host build/package gate to completion. When current-main tgz packaging is needed, the smoke scripts hold a shared package lock through pnpm build, inventory/staging, and npm pack; if that lock is missing or broken, serialize the matrix instead of accepting concurrent dist mutation.

• Actual OpenClaw npm install/update phases are a stricter signal than whole-lane caps: install phases should normally finish within 7 minutes, and update phases should normally show meaningful progress within 5 minutes. If a phase named install-main, install-latest, install-baseline, or install-baseline-package exceeds 420s, or a phase named update-dev / same-guest openclaw update exceeds 300s without new markers, start diagnosis from that phase log and guest process state. Current Windows update phases can still pass after roughly 10-15 minutes because doctor --fix may install bundled plugin runtime deps; keep the script hard cap near 20 minutes unless the log is truly stale.
• For a full OS matrix, prefer running independent guest-family lanes in parallel when host capacity allows:
• timeout --foreground 75m pnpm test:parallels:macos -- --json
• timeout --foreground 90m pnpm test:parallels:windows -- --json
• timeout --foreground 75m pnpm test:parallels:linux -- --json

• Do not run multiple smoke lanes against the same guest family at once. Tahoe lanes share the host HTTP port, and Windows/Linux lanes can collide on snapshot restore/start state if two jobs touch the same VM concurrently.
• Do not run the aggregate pnpm test:parallels:npm-update wrapper in parallel with individual macOS/Windows/Linux smoke lanes; it touches the same guest families and snapshots.
• Do not start Parallels lanes while any unrelated host command may rebuild, clean, or restage dist (pnpm build, pnpm ui:build, pnpm release:check, pnpm test:install:smoke, npm pack/install smoke, or Docker lanes that run package/build prep). Run unrelated build/package gates first, let them finish, then start the VM matrix. Concurrent dist mutation can make host npm pack fail with missing files and wastes a full VM cycle.
• While running or optimizing the matrix, record wall-clock duration per lane and the slowest phase from /tmp/openclaw-parallels-* logs. Use that timing before changing smoke order, timeouts, or helper behavior.
• If a host build changes tracked generated files, stop before spending VM time. Commit the generated artifact separately or fix the generator drift, then rerun the smallest affected lane.
• If main is moving under active multi-agent work, prefer a detached worktree pinned to one commit for long Parallels suites. The smoke scripts now verify the packed tgz commit instead of live git rev-parse HEAD, but a pinned worktree still avoids noisy rebuild/version drift during reruns.
• For openclaw update --channel dev lanes, remember the guest clones GitHub main, not your local worktree. If a local fix exists but the rerun still fails inside the cloned dev checkout, do not treat that as disproof of the fix until the branch has been pushed.
• For prlctl exec, pass the VM name before --current-user (prlctl exec "$VM" --current-user ...), not the other way around.
• If the workflow installs OpenClaw from a repo checkout instead of the site installer/npm release, finish by installing a real guest CLI shim and verifying it in a fresh guest shell. pnpm openclaw ... inside the repo is not enough for handoff parity.
• On macOS guests, prefer a user-global install plus a stable PATH-visible shim:
• install with NPMCONFIGPREFIX="$HOME/.npm-global" npm install -g .
• make sure ~/.local/bin/openclaw exists or ~/.npm-global/bin is on PATH

npm install then update

This keeps the same-guest openclaw update --tag ... coverage and uses the shared macOS current-user/sudo fallback without starting Windows/Linux lanes.

• Preferred entrypoint: pnpm test:parallels:npm-update
• For a macOS-only published release update check, use:
• timeout --foreground 75m pnpm test:parallels:npm-update -- --platform macos --package-spec openclaw@ --update-target --json

This resolves beta3 to the latest *-beta.3 version, runs latest->that-version same-guest update coverage, and then runs fresh install smoke for that exact published target on the same selected OS matrix. Use --platform macos|windows|linux to narrow reruns.

• Required coverage: every release/update regression run must include both lanes:
• fresh snapshot -> install requested package/baseline -> smoke
• same guest baseline -> run the guest's installed openclaw update ... command -> smoke again
• The update lane must exercise OpenClaw's internal updater. Do not count a direct npm install -g or harness-side package swap as update-flow coverage; those are install smokes only.
• For published targets, install the old baseline package first (for example openclaw@2026.4.9), then run the installed guest CLI with the intended channel/tag (for example openclaw update --channel beta --yes --json) and verify openclaw --version, openclaw update status --json, gateway RPC, and an agent turn after the command.
• For unpublished targets, pack the candidate on the host, serve the .tgz over the harness HTTP server, and point the guest updater at that served package. Prefer openclaw update --tag http://:/openclaw-.tgz --yes --json; when channel persistence also matters, pass --channel and set OPENCLAWUPDATEPACKAGE_SPEC to the same served URL in the guest update environment. The command under test must still be openclaw update, not direct npm.
• For unpublished local-fix validation, remember the old baseline updater code still controls the first hop. A fix that lives only in the new updater code cannot change that already-running old process; the served candidate must either keep package/plugin metadata compatible with the baseline host or the baseline itself must include the updater fix.
• For beta/stable verification, resolve the tag immediately before the run (npm view openclaw@beta version dist.tarball or npm view openclaw@latest ...). Tags can move while a long VM matrix is already running; restart the matrix when the intended prerelease appears after an earlier registry 404/tag-lag check.
• Use the configured secret workflow to inject only the provider keys needed by OpenAI/Anthropic lanes. Do not print secrets or env dumps; pass provider secrets through the guest exec environment.
• Same-guest update verification should set the default model explicitly to openai/gpt-5.4 before the agent turn and use a fresh explicit --session-id so old session model state does not leak into the check.
• The aggregate npm-update wrapper must resolve the Linux VM with the same Ubuntu fallback policy as parallels-linux-smoke.sh before both fresh and update lanes. Treat any Ubuntu guest with major version >= 24 as acceptable when the exact default VM is missing, preferring the newest versioned Ubuntu guest with a fresh poweroff snapshot. On Peter's current host today, use Ubuntu 26.04.
• On macOS same-guest update checks, restart the gateway after the npm upgrade before gateway status / agent; launchd can otherwise report a loaded service while the old process has exited and the fresh process is not RPC-ready yet.

Prefer the explicit beta4 alias over openclaw@beta when validating a specific prerelease number; npm tags can move.

• For beta 4 npm validation with agent turns, the known-good shape is:
• gtimeout --foreground 150m pnpm test:parallels:npm-update -- --beta-validation beta4 --model openai/gpt-5.4 --json

• If the wrapper fails a lane, read the auto-dumped tail first, then the full nested lane log under .artifacts/parallels/openclaw-parallels-npm-update.*.
• Current known macOS update-lane transport signature when the fallback is missing or bypassed: Unable to authenticate the user. Make sure that the specified credentials are correct and try again. Treat that as Parallels current-user authentication before blaming npm or OpenClaw.
• A macOS packaged fresh install with global package directories or bundled files mode 0777 usually means the harness used the root prlctl exec fallback under a permissive umask. The POSIX guest transports should prepend umask 022; verify the phase preflight line before blaming npm.

CLI invocation footgun

• The Parallels smoke shell scripts should tolerate a literal bare -- arg so pnpm test:parallels:* -- --json and similar forwarded invocations work without needing to call bash scripts/e2e/... directly.

macOS and Windows guest-command transport

The macOS and Windows smoke and same-guest update lanes route guest commands through scripts/e2e/parallels/parallels-exec.py; macOS hosts need python3 with its standard library. On verified Parallels 27.0.0 (58628) and 27.0.2 (58673) Apple-silicon installations for macOS guests, and 27.1.0 (58756) for Windows guests, the client retains SDK login-job handles through result extraction, avoiding the host CLI's intermittent PrlJob_GetRetCode: Invalid argument failure. This error is not proof that the guest needs reinstallation or another Tools update.

Selection checks the actual prlctl on PATH and the installed CLI digest before execution. Other binaries retain ordinary prlctl; an SDK failure never retries through another transport. Root/current-user choice, raw shell-argument joining, stdin, stdout/stderr, and guest exit status are preserved. Windows calls pass --windows to keep the program separate from its raw arguments; POSIX calls retain shell joining. Callers still own shell quoting. Bare UUIDs use the CLI's braced lookup form; when that UUID is absent, the client checks the original literal VM name once before any guest execution. Other lookup failures are terminal. Snapshot/start/stop/input/capture and Linux execution are unchanged.

For an already-owned, running macOS guest, the same transport can be checked directly:

python3 -B scripts/e2e/parallels/parallels-exec.py --timeout-ms 30000 -- exec "<owned-macos-vm>" --current-user /bin/echo ready

Keep the outer host timeout for complete lanes; the SDK wait deadline is not proof of guest-process termination. This is a bounded workaround, not a supported public SDK integration. Revalidate ABI and live command/stdio/cleanup behavior before adding an installed-binary digest; remove the workaround after a vendor-fixed CLI is verified. Restore the original snapshot and stop the guest after ad-hoc proof.

macOS flow

• Preferred entrypoint: pnpm test:parallels:macos
• parallels-macos-smoke.sh --mode fresh --target-package-spec openclaw@ is an install smoke only. For published old-version -> new-version update coverage on macOS, prefer the npm-update wrapper with --platform macos; parallels-macos-smoke.sh --mode upgrade --target-package-spec ... installs the target package and does not exercise the baseline CLI's updater.
• Default upgrade coverage on macOS should now include: fresh snapshot -> site installer pinned to the latest stable tag -> openclaw update --channel dev on the guest. Treat this as part of the default Tahoe regression plan, not an optional side quest.
• parallels-macos-smoke.sh --mode upgrade should run that release-to-dev lane by default. Keep the older host-tgz upgrade path only when the caller explicitly passes --target-package-spec.
• Because the default upgrade lane no longer needs a host tgz, skip npm pack + host HTTP server startup for --mode upgrade unless --target-package-spec is set. Keep the pack/server path for fresh and both.
• If that release-to-dev lane fails with reason=preflight-no-good-commit and repeated sh: pnpm: command not found tails from preflight build, treat it as an updater regression first. The fix belongs in the git/dev updater bootstrap path, not in Parallels retry logic.
• Until the public stable train includes that updater bootstrap fix, the macOS release-to-dev lane may seed a temporary guest-local pnpm shim immediately before openclaw update --channel dev. Keep that workaround scoped to the smoke harness and remove it once the latest stable no longer needs it.
• In Tahoe prlctl exec --current-user runs, prefer explicit node .../openclaw.mjs ... invocations for the release->dev handoff itself and for post-update verification. The shebanged global openclaw wrapper can fail with env: node: No such file or directory, and self-updating through the wrapper is a weaker lane than invoking the entrypoint under a fixed node.
• Default to the snapshot closest to macOS 26.5 latest.
• On Peter's Tahoe VM, fresh-latest-march-2026 can hang in prlctl snapshot-switch; if restore times out there, rerun with --snapshot-hint 'macOS 26.5 latest' before blaming auth or the harness.
• parallels-macos-smoke.sh now retries snapshot-switch once after force-stopping a stuck running/suspended guest. If Tahoe still times out after that recovery path, then treat it as a real Parallels/host issue and rerun manually.
• The macOS smoke should include a dashboard load phase after gateway health: resolve the tokenized URL with openclaw dashboard --no-open, verify the served HTML contains the Control UI title/root shell, then open Safari and require an established localhost TCP connection from Safari to the gateway port.