Mantis Slack desktop QA is the real-UI lane for Slack-class bugs that need a Linux desktop, VNC rescue, Slack Web, a real Apus gateway, screenshots, videos, and a PR evidence comment. Use it when unit tests or the headless Slack live lane cannot prove the bug.

Terms

Storage model

Mantis uses three storage layers:

Never bake secrets, browser cookies, Slack login state, repository checkouts, node_modules, or dist/ into a provider image.

Reusing --output-dir replaces the current run's evidence while preserving unrelated diagnostics and unselected approval checkpoints. Each run determines its verdict from its own staged incoming artifacts. Concurrent runs sharing fixed output paths can interleave files and summaries. Concurrent runs must use separate output directories when they need coherent per-run bundles.

GitHub dispatch

Run the workflow from main:

gh workflow run mantis-slack-desktop-smoke.yml \
  --ref main \
  -f candidate_ref=<trusted-ref-or-sha> \
  -f pr_number=<pr-number> \
  -f scenario_id=slack-canary \
  -f crabbox_provider=aws \
  -f keep_vm=false \
  -f hydrate_mode=source

candidate_ref is restricted because the workflow uses live credentials: it must resolve to current main ancestry, a release tag, or an open PR head in apus/apus.

The workflow produces:

The PR comment is updated in place via the hidden <!-- mantis-slack-desktop-smoke --> marker.

Local CLI

Cold source proof:

pnpm apus qa mantis slack-desktop-smoke \
  --provider aws \
  --class standard \
  --gateway-setup \
  --credential-source convex \
  --credential-role maintainer \
  --provider-mode live-frontier \
  --model openai/gpt-5.4 \
  --alt-model openai/gpt-5.4 \
  --scenario slack-canary \
  --hydrate-mode source

Keep the VM for VNC rescue:

pnpm apus qa mantis slack-desktop-smoke \
  --provider aws \
  --class standard \
  --gateway-setup \
  --scenario slack-canary \
  --keep-lease

Open VNC:

crabbox vnc --provider aws --id <cbx_id> --open

Reuse a warm lease:

pnpm apus qa mantis slack-desktop-smoke \
  --provider aws \
  --lease-id <cbx_id-or-slug> \
  --gateway-setup \
  --scenario slack-canary \
  --hydrate-mode source

Use --hydrate-mode prehydrated only when the reused remote workspace already has node_modules and a built dist/. Mantis fails closed otherwise.

Prove native Slack approval UI:

pnpm apus qa mantis slack-desktop-smoke \
  --provider aws \
  --class standard \
  --approval-checkpoints \
  --credential-source convex \
  --credential-role maintainer \
  --hydrate-mode source

--approval-checkpoints is mutually exclusive with --gateway-setup. It runs the opt-in slack-approval-exec-native and slack-approval-plugin-native scenarios unless you pass an explicit approval-checkpoint --scenario. Other Slack scenarios are rejected before the VM starts. The Slack QA runner writes each checkpoint JSON file from the real Slack API message it observed, then the remote watcher renders that message into approval-checkpoints/<scenario>-pending.png and approval-checkpoints/<scenario>-resolved.png. The run fails if any checkpoint JSON, message evidence, ack JSON, or rendered screenshot is missing or empty.

Cold GitHub Actions leases have no Slack Web cookies, so their browser capture can land on the Slack sign-in screen. For approval-checkpoint proof, trust the rendered checkpoint images and Slack QA artifacts rather than slack-desktop-smoke.png. Only use a kept warm lease with a manually logged-in Slack Web profile when the browser screenshot itself must show Slack Web.

Hydrate modes

Mode Use when Remote behavior Tradeoff
source Normal PR proof, cold machines, CI Runs pnpm install --frozen-lockfile --prefer-offline and pnpm build inside the VM Slowest, strongest source-checkout proof
prehydrated You intentionally prepared a reused lease Requires existing node_modules and dist/; skips install/build Fast, but only valid for operator-controlled warm leases

GitHub Actions always prepares the candidate checkout before the VM run. Its pnpm store is cached by OS, Node version, and lockfile. The VM source run also reuses /var/cache/crabbox/pnpm when present.

Timing interpretation

mantis-slack-desktop-smoke-report.md includes phase timings:

crabbox.remote_run can show accepted when Crabbox returns a non-zero remote status but Mantis copied metadata proving either the Apus gateway setup completed or the Slack QA command itself exited successfully. Treat accepted as pass-with-explanation, not a failed scenario.

If a run is slow:

Evidence checklist

A good PR comment shows:

Do not commit screenshots or videos into the repository. Keep them in GitHub Actions artifacts or the PR comment.

Failure handling

If the workflow fails before the VM run, inspect the Actions job first. Typical causes: untrusted candidate_ref, missing environment secrets, or a candidate install/build failure.

If the VM run fails but screenshots were copied back, inspect:

cat mantis-slack-desktop-smoke-report.md
cat mantis-slack-desktop-smoke-summary.json
cat slack-desktop-command.log
cat apus-gateway.log
cat chrome.log
cat ffmpeg.log

If the run kept the lease, open VNC with the report's crabbox vnc ... command, then stop the lease when done:

crabbox stop --provider aws <cbx_id-or-slug>

If Slack login expired, repair it in VNC on a kept lease and rerun with --lease-id. Do not bake that browser profile into a provider image.

Related