{"owner":"openclaw","repo":"clawsweeper","hasSkills":true,"totalSkillsCount":4,"totalTokensCount":14129,"categories":["anthropic-skill","root-instruction"],"hasMcp":false,"mcpConfig":null,"found":[".agents/skills/crabbox/SKILL.md",".agents/skills/local-clawsweeper-review/SKILL.md",".agents/skills/local-clawsweeper-review/agents/openai.yaml","AGENTS.md"],"skills":{".agents/skills/crabbox/SKILL.md":"---\nname: crabbox\ndescription: Use the Crabbox wrapper for validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id.\n---\n\n# Crabbox\n\n## Provider Selection Contract\n\nProvider selection is configuration resolution, not testing policy. Run\n`crabbox config show` from the exact worktree being tested; a session may have\nstarted in another checkout whose repository config or skill text is stale. A\nrequest to \"use Crabbox\" does not authorize a provider override. When the user\ndoes not name a backend, omit `--provider` and preserve the resolved provider,\nincluding values supplied by user config or `CRABBOX_PROVIDER`.\n\nTest scope, expected duration, and hydration failures do not select a provider.\nOverride the resolved provider only when the user explicitly names a different\nbackend. If that provider cannot perform the requested test, report the blocker\ninstead of silently selecting another backend.\n\nUse the Crabbox wrapper for validation execution, environment lifecycle, sync,\nlogs/results, cache inspection, and lease cleanup.\n\nCrabbox is the transport/orchestration surface. The actual backend can be:\n\n- local Docker isolation: `provider=local-container`, lease ids like `cbx_...`\n- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like\n  `cbx_...`, `syncDelegated=false`\n- Blacksmith Testbox through Crabbox: delegated provider,\n  `provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`\n\nThe provider-specific sections below document capabilities and commands after\nconfiguration or an explicit user request has selected a backend. They are not\nprovider-selection policy. Their validation commands intentionally omit\n`--provider`; add it only to carry out an explicit user override of the resolved\nconfiguration.\n\nProvider identity must remain attached to a lease after creation. A lease\ncreated through the resolved configuration can keep using provider-neutral\ncommands while that configuration is unchanged. If the user explicitly\noverrode the provider, or the resolved configuration has changed since the\nlease was created, pass the provider reported by Crabbox to every later command\nthat targets that lease, including hydrate, rerun, desktop/WebVNC, status,\ninspect, SSH, and stop. This preserves resource identity; it does not select a\nprovider for unrelated work.\n\nWhen the resolved configuration selects Blacksmith Testbox, or the user\nexplicitly requests it, do not describe the run as \"AWS Crabbox\". Report it as\nTestbox-through-Crabbox with the `tbx_...` id and Actions run.\n\nDirect AWS supports persistent leases, `--fresh-pr`, `--full-resync`,\nenvironment forwarding, capture/download, and provider-comparison workflows.\nBlacksmith Testbox provides a prepared CI environment and delegated broad/heavy\n`pnpm` gates. These capabilities do not override the resolved configuration.\n\n## First Checks\n\n- Run from the repo root. Crabbox sync mirrors the current checkout.\n- Check the wrapper and providers before Crabbox work:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,120p'\n../crabbox/bin/crabbox desktop launch --help\n../crabbox/bin/crabbox webvnc --help\n```\n\n- OpenClaw scripts prefer `../crabbox/bin/crabbox` when present. The user PATH\n  shim can be stale.\n- Read `.crabbox.yaml`, then run `crabbox config show` from the repository root\n  before selecting a provider. The resolved provider can come from the user's\n  Crabbox config or environment as well as the repository file.\n- Omitting `--provider` means \"use the resolved configuration\". Pass it only\n  when the user explicitly requests a different backend, and report the\n  provider from Crabbox output rather than inferring it from bootstrap wording.\n- Treat `CRABBOX_PROVIDER` as part of that resolved provider configuration. The\n  provider reported by `crabbox config show` is authoritative; a hydration or\n  test failure is not permission to switch backends. Override it only when the\n  user explicitly names another provider.\n- Some package-manager wrappers insert a command delimiter before Crabbox\n  options. If the printed command looks like `crabbox run -- --provider ...`\n  or `crabbox run -- --no-hydrate ...`, call the trusted Crabbox binary\n  directly so lifecycle flags are parsed by Crabbox.\n- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo\n  config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.\n  If warmup drifts well past the minute-scale path, verify image promotion,\n  region/AZ placement, and FSR state before blaming OpenClaw.\n- Targeted and broad `pnpm` gates both use the resolved provider. Test size does\n  not authorize a provider override.\n- Always report the provider field and id. Both local-container and direct\n  providers can use `cbx_...`, so the id prefix alone does not prove AWS;\n  `tbx_...` identifies Blacksmith Testbox through Crabbox. If the output only\n  says `blacksmith testbox list`, use `blacksmith testbox list --all` before\n  concluding no box exists.\n- If a warm direct-provider lease smells stale, retry with `--full-resync`\n  (alias `--fresh-sync`) before replacing the lease. This resets the remote\n  workdir, skips the fingerprint fast path, reseeds Git when possible, and\n  uploads the checkout from scratch.\n- For live/provider bugs, use the configured secret workflow before downgrading\n  to mocks. Copy only the exact needed key into the remote process environment\n  for that one command. Do not print it, do not sync it as a repo file, and do\n  not leave it in remote shell history or logs. If no secret-safe injection path\n  is available, say true live provider auth is blocked instead of silently using\n  a fake key.\n- Targeted versus broad describes test scope only; it does not imply local,\n  remote, host, or container execution.\n- Do not treat unrelated inherited shell controls as operator intent. In\n  particular, `OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not\n  permission to move broad `pnpm check:changed`, `pnpm test:changed`, full\n  `pnpm test`, or lint/typecheck fan-out onto the laptop. This does not negate\n  provider-selection variables such as `CRABBOX_PROVIDER`, which are resolved\n  and reported by `crabbox config show`.\n- `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` controls direct host execution; it\n  is separate from Crabbox provider selection and must not override the provider\n  reported by `crabbox config show`.\n\n## macOS And Windows Targets\n\nUse these only when the task needs an existing non-Linux host. OpenClaw Linux\nvalidation uses the resolved Crabbox configuration unless the user explicitly\nrequests another provider or target.\n\nNative Windows is available when the resolved provider supports that target.\nFor providers other than AWS, keep placement and capacity in their resolved\nconfiguration:\n\n```sh\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --timing-json\n```\n\nAWS has a provider-specific placement requirement: the OpenClaw Windows\ndeveloper image and Docker cache are available in `us-west-2`, and native\nWindows leases must use on-demand capacity. After `crabbox config show` confirms\n`provider=aws` (or the user explicitly selects AWS), use:\n\n```sh\nCRABBOX_AWS_REGION=us-west-2 \\\nCRABBOX_CAPACITY_REGIONS=us-west-2 \\\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --market on-demand \\\n  --timing-json\n```\n\nThe region variables pin both the AWS image lookup and the capacity candidate\nset because `warmup` does not expose a generic `--region` flag. These placement\nand market settings are AWS availability constraints applied after provider\nselection; they are not a reason to select AWS for other runs. If the user\nexplicitly requests AWS while `crabbox config show` resolves another provider,\nadd `--provider aws` to this command to carry out that explicit override.\n\nThe hydrate workflow assumes Docker should already be baked into Linux images\nand only installs it as a fallback. Do not add per-run Docker installs to proof\ncommands unless the image probe shows Docker is actually missing.\n\nWhen the user explicitly asks for brokered macOS runners, use Crabbox AWS\nmacOS only after confirming the deployed coordinator supports EC2 Mac host\nlifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota\nand IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,\nor run the no-spend preflight first:\n\nThese administration commands specify AWS because they inspect or allocate an\nAWS EC2 Dedicated Host. The explicit provider is a billing and resource-scope\nsafety boundary, not a validation default.\n\n```sh\ncrabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json\ncrabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json\nCRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh\n```\n\nDo not silently substitute AWS macOS for normal OpenClaw Linux proof. Report\npaid-host blockers as quota, IAM, coordinator deployment, or host availability\ninstead of falling back to local macOS.\n\nCrabbox supports static SSH targets:\n\nThese commands specify `ssh` because the user-supplied static host selects that\ntransport explicitly; they do not establish an SSH preference for other runs.\n\n```sh\n../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command \"dotnet test\"\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test\n```\n\n- `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH,\n  bash, Git, rsync, and tar contract.\n- Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar\n  archive transfer into `static.workRoot`. Direct native Windows runs support\n  `--script*`, `--env-from-profile`, `--preflight`, and PowerShell `--shell`.\n- `crabbox actions hydrate/register` are Linux-only today; use plain\n  `crabbox run` loops for static macOS and Windows hosts.\n- Live proof needs a reachable, operator-managed SSH host. Without one, verify\n  with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox\n  Go test suite.\n\n## Direct Brokered AWS Backend\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects direct AWS Crabbox.\n\nChanged gate:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\"\n```\n\nFocused rerun:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>\"\n```\n\nRead the JSON summary. Useful fields:\n\n- `provider`: `aws`\n- `leaseId`: `cbx_...`\n- `syncDelegated`: `false`\n- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`\n- `commandMs` / `totalMs`\n- `exitCode`\n\nCrabbox should stop one-shot AWS leases automatically after the run. Verify\ncleanup when a run fails, is interrupted, or the command output is unclear:\n\n```sh\n../crabbox/bin/crabbox list --provider aws\n```\n\nThe explicit provider keeps cleanup attached to the AWS lease recorded by the\nrun, including when AWS was a user-requested override of another configured\ndefault.\n\n## Blacksmith Testbox Through Crabbox\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects Blacksmith Testbox:\n\nA fresh Testbox requires a repository-specific workflow. Crabbox resolves it\nfrom `blacksmith.workflow`, falling back to `actions.workflow`; job and ref use\nthe equivalent Blacksmith values with Actions fallbacks. The workflow must\ncontain a `useblacksmith/testbox`, `useblacksmith/begin-testbox`, or\n`useblacksmith/run-testbox` step. Confirm both the effective config and the\nactual workflow before using the provider-neutral command below; nonempty\nfields alone do not prove that an ordinary Actions workflow is Testbox-capable.\n\nFor a local workflow path, validate it with:\n\n```sh\nrg -n 'useblacksmith/(testbox|begin-testbox|run-testbox)' <workflow-path>\n```\n\nFor a workflow name or id, inspect its YAML through GitHub before dispatch. Do\nnot guess a Testbox workflow from another repository.\n\nIf the user explicitly supplies a Blacksmith override, carry those exact values\non the command instead:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --provider blacksmith-testbox \\\n  --blacksmith-workflow <repository-workflow> \\\n  --timing-json -- <test-command>\n```\n\nAdd `--blacksmith-org`, `--blacksmith-job`, and `--blacksmith-ref` only when the\nuser supplies those overrides. The explicit provider and workflow flags in this\nform implement the user's repository-specific selection; they are not defaults\nfor other runs.\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed\n```\n\nRead the JSON summary and the Testbox line. Useful fields:\n\n- `provider`: `blacksmith-testbox`\n- `leaseId`: `tbx_...`\n- `syncDelegated`: `true`\n- `syncPhases`: delegated/skipped because Blacksmith owns checkout/sync\n- Actions run URL/id from the Testbox output\n- `exitCode`\n\n`blacksmith testbox list` may hide hydrating or ready boxes. Use:\n\n```sh\nblacksmith testbox list --all\nblacksmith testbox status <tbx_id>\n```\n\n## Observability Flags\n\nUse these on debugging runs before inventing ad hoc logging:\n\n- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,\n  and target-specific tool probes. Defaults cover `git`, `tar`, `node`, `npm`,\n  `corepack`, `pnpm`, `yarn`, `bun`, `docker`, plus POSIX\n  `sudo`/`apt`/`bubblewrap` and native Windows\n  `powershell`/`execution_policy`/`longpaths`/`temp`/`pwsh`. Add\n  `--preflight-tools node,bun,docker`, `CRABBOX_PREFLIGHT_TOOLS`, or repo\n  `run.preflightTools` to replace the list. `default` expands built-ins; `none`\n  prints only the workspace summary. Preflight is diagnostic only; install\n  toolchains through Actions hydration, images, devcontainer/Nix/mise/asdf, or\n  the run script. On `blacksmith-testbox`, this prints a delegated-unsupported\n  note because the workflow owns setup.\n- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct\n  providers and prints `set len=N secret=true` style summaries. On\n  `blacksmith-testbox`, env forwarding is unsupported; put secrets in the\n  Testbox workflow instead.\n- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple\n  `export NAME=value` / `NAME=value` lines from a local profile without\n  executing it, then forwards only allowlisted names. `--allow-env` is\n  repeatable and comma-separated. Profile values override ambient allowlisted\n  env values for that run. Direct POSIX, WSL2, and native Windows runs are\n  supported; delegated providers are not. Crabbox probes the uploaded profile\n  remotely and prints redacted presence/length metadata before the command.\n- `--env-helper <name>`: with `--env-from-profile` on POSIX SSH targets,\n  persists `.crabbox/env/<name>` and `.crabbox/env/<name>.env` so follow-up\n  commands on the same lease can run through `./.crabbox/env/<name> <command>`.\n  Use only on leases you control; the profile stays until cleanup, lease reset,\n  or `--full-resync`.\n- `--script <file>` / `--script-stdin`: upload a local script into\n  `.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute\n  directly on POSIX; scripts without a shebang run through `bash`. Native\n  Windows uploads run through Windows PowerShell, and Crabbox appends `.ps1`\n  when needed. Arguments after `--` become script args.\n- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a\n  fresh remote checkout of the GitHub PR. Bare numbers use the current repo's\n  GitHub origin. Add `--apply-local-patch` only when the current local\n  `git diff --binary HEAD` should be applied on top of that PR checkout.\n- `--full-resync` / `--fresh-sync`: reset a stale direct-provider workdir\n  before syncing. Use after sync fingerprints look wrong, SSH times out before\n  sync, or rsync watchdog output suggests it. It is redundant with\n  `--fresh-pr`, incompatible with `--no-sync`, and unsupported by delegated\n  providers.\n- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to\n  local files and keep binary/noisy output out of retained logs. Parent\n  directories must already exist. These are direct-provider only.\n- `--capture-on-fail`: on non-zero direct-provider exits, downloads\n  `.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,\n  `coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.\n- `--keep-on-failure`: leave a failed one-shot lease alive for live debugging\n  until idle/TTL expiry. Useful on direct providers and delegated one-shots.\n- `--timing-json`: final machine-readable timing. Add\n  `echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell\n  commands; direct providers and Blacksmith Testbox both report them as\n  `commandPhases`.\n\nLive-provider debug template for the resolved direct-provider lease:\n\n```sh\nmkdir -p .crabbox/logs\n../crabbox/bin/crabbox run \\\n  --preflight \\\n  --allow-env OPENAI_API_KEY,OPENAI_BASE_URL \\\n  --timing-json \\\n  --capture-stdout .crabbox/logs/live-provider.stdout.log \\\n  --capture-stderr .crabbox/logs/live-provider.stderr.log \\\n  --capture-on-fail \\\n  --shell -- \\\n  \"echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live\"\n```\n\nDo not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or\n`--sync-only` to delegated providers. Also do not pass `--script*`,\n`--fresh-pr`, `--full-resync`, or `--env-helper` there. Crabbox rejects these\nbecause the provider owns sync or command transport. `--keep-on-failure` is OK\nfor delegated one-shots when you need to inspect a failed lease.\n\n## Efficient Bug E2E Verification\n\nUse the smallest Crabbox lane that proves the reported user path, not just the\ntouched code. Aim for one after-fix E2E proof before commenting, closing, or\nopening a PR for a user-visible bug.\n\nWhen the user says \"test in Crabbox\", do not simply copy tests to the remote\nbox and run them there. Crabbox is for remote real-scenario proof: copy or\ninstall OpenClaw as the user would, run the same setup/update/CLI/Gateway/API\ncall that failed, and capture behavior from that entrypoint. For regressions or\nbug reports, prove the broken state first when feasible, then run the same\nscenario after the fix.\n\nPick the lane by symptom:\n\n- Docker/setup/install bug: build a package tarball and run the matching\n  `scripts/e2e/*-docker.sh` or package script. This proves npm packaging,\n  install paths, runtime deps, config writes, and container behavior.\n- Provider/model/auth bug: prefer true live E2E. Use the configured secret\n  workflow, then inject the single needed key into Crabbox if needed. Scrub\n  unrelated provider env vars in the child command so interactive defaults do\n  not drift to another provider. If only a dummy key is used, label the proof\n  narrowly, e.g. \"UI/install path only; live provider auth not exercised.\"\n- Channel delivery bug: use the channel Docker/live lane when available; include\n  setup, config, gateway start, send/receive or agent-turn proof, and redacted\n  logs.\n- Gateway/session/tool bug: prefer an end-to-end CLI or Gateway RPC command that\n  creates real state and inspects the resulting files/API output.\n- Pure parser/config bug: targeted tests may be enough, but still run a\n  Crabbox command when OS, package, Docker, secrets, or service lifecycle could\n  change behavior.\n\nEfficient flow:\n\n1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint\n   when feasible. If the issue cannot be reproduced, capture the exact command\n   and observed behavior instead.\n2. Patch locally and run narrow local tests for edit speed.\n3. Run one Crabbox E2E command that starts from the user-facing entrypoint:\n   package install, Docker setup, onboarding, channel add, gateway start, or\n   agent turn as appropriate.\n4. Record proof as: Testbox id, command, environment shape, redacted secret\n   source, and copied success/failure output.\n5. If the issue says \"cannot reproduce\", ask for the missing config/log fields\n   that would distinguish the tested path from the reporter's path.\n\nKeep it efficient:\n\n- Reuse existing E2E scripts and helper assertions before writing ad hoc shell.\n- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead\n  of quote-heavy `--shell` strings on direct SSH providers.\n- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the\n  local dirty tree. Add `--apply-local-patch` only when testing a local fixup on\n  top of that PR.\n- Use `--full-resync` before replacing a warmed direct-provider lease when the\n  remote workdir or sync fingerprint appears stale.\n- Use one-shot Crabbox for a single proof; use a reusable Testbox only when\n  several commands must share built images, installed packages, or live state.\n- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a\n  candidate tarball; prefer the repo's package helper instead of direct source\n  execution when the bug might be packaging/install related.\n- Keep secrets redacted. It is fine to report key presence, source, and length;\n  never print secret values.\n- Include `--timing-json` on broad or flaky runs when command duration or sync\n  behavior matters.\n\nBefore/after PR proof on delegated Testbox:\n\n- For PRs that should prove \"broken before, fixed after\", compare base and PR\n  on the same Testbox when practical. Fetch both refs, create detached temp\n  worktrees under `/tmp`, install in each, then run the same harness twice.\n- Do not checkout base/PR refs in the synced repo root. Delegated Testbox sync\n  may leave the root dirty with local files; `git checkout` can abort or mix\n  proof state.\n- Temp harness files under `/tmp` do not resolve repo packages by default. Put\n  the harness inside the worktree, or in ESM use\n  `createRequire(path.join(process.cwd(), \"package.json\"))` before requiring\n  workspace deps such as `@lydell/node-pty`.\n- For full-screen TUI/CLI bugs, a PTY harness is stronger than helper-only\n  assertions. Use a real PTY, wait for visible lifecycle markers, send input,\n  then send control keys and assert process exit/stuck behavior.\n- When validating a rebased local branch before push, remember delegated sync\n  usually validates synced file content on a detached dirty checkout, not a\n  remote commit object. Record the local head SHA, changed files, Testbox id,\n  and final success markers; after pushing, ensure the pushed SHA has the same\n  file content.\n- If GitHub CI is still queued but the exact changed content passed Testbox\n  `pnpm check:changed`, `pnpm check:test-types`, and the real E2E proof, it is\n  reasonable to merge once required checks allow it. Note any still-running\n  unrelated shards in the proof comment instead of waiting forever.\n\nInteractive CLI/onboarding:\n\n- For full-screen or prompt-heavy CLI flows, run the target command inside tmux\n  on the Crabbox and drive it with `tmux send-keys`; capture proof with\n  `tmux capture-pane`, redacted through `sed`.\n- Prefer deterministic arrow navigation over search typing for Clack-style\n  searchable selects. Raw `send-keys -l openai` may not trigger filtering in a\n  tmux pane; inspect option order locally or on-box and send exact Down/Enter\n  sequences.\n- Isolate mutable state with `OPENCLAW_STATE_DIR=$(mktemp -d)`. Plugin npm\n  installs live under that state dir (`npm/node_modules/...`), not under\n  `OPENCLAW_CONFIG_DIR`. Verify downloads by checking the state dir, package\n  lock, and installed package metadata.\n- To test automatic setup installs against local package artifacts, use\n  `OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1` plus\n  `OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{\"plugin-id\":\"npm-pack:/tmp/plugin.tgz\"}'`.\n  Pack with `npm pack`, set an isolated `OPENCLAW_STATE_DIR`, and verify the\n  package under `npm/node_modules`. Overrides are test-only and must not be\n  treated as official/trusted-source installs.\n- For OpenAI/Codex onboarding proof, the useful markers are the UI line\n  `Installed Codex plugin`, `npm/node_modules/@openclaw/codex`, and the\n  package-lock entry showing the bundled `@openai/codex` dependency. A dummy\n  OpenAI-shaped key can prove only UI/install behavior; it is not live auth.\n\n## Reuse And Keepalive\n\nFor most Crabbox calls, one-shot is enough. Use reuse only when you need\nmultiple manual commands on the same hydrated box.\n\nThe examples below assume the lease came from the still-current resolved\nconfiguration. For a lease created through an explicit provider override, add\n`--provider <reported-provider>` to every reuse, inspection, and cleanup command\ninstead of relying on the id to recover its backend.\n\nIf Crabbox returns a reusable id or you intentionally keep a lease:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --no-sync --timing-json --shell -- \"pnpm test <path>\"\n```\n\nStop boxes you created before handoff:\n\n```sh\n../crabbox/bin/crabbox stop <id-or-slug>\nblacksmith testbox stop --id <tbx_id>\n```\n\n## Interactive Desktop And WebVNC\n\nBefore using WebVNC, confirm the resolved provider supports both desktop and a\ncoordinator-backed WebVNC lease, and that broker login is configured. Crabbox\n0.39 WebVNC supports coordinator-backed Hetzner, AWS, and Azure desktop leases;\nthis capability list does not establish a provider preference. If the resolved\nprovider lacks WebVNC, do not switch providers: use native `crabbox vnc` on the\nsame provider when it supports that path, or report the capability blocker.\n\nWhen those preconditions hold, prefer WebVNC for human inspection because the\nbrowser portal can preload the lease VNC password and avoids a native VNC\nclient's copy/paste/password dance. Use native `crabbox vnc` when the browser\nportal is unavailable or broken, or the user explicitly wants a local VNC\nclient.\n\nCommon desktop flow:\n\n```sh\n../crabbox/bin/crabbox warmup --desktop --browser --idle-timeout 60m --ttl 240m\n../crabbox/bin/crabbox desktop launch --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open --take-control\n```\n\nUseful WebVNC commands:\n\n```sh\n../crabbox/bin/crabbox webvnc --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon start --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc daemon stop --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc reset --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox desktop doctor --id <cbx_id-or-slug>\n../crabbox/bin/crabbox desktop click --id <cbx_id-or-slug> --x 640 --y 420\n../crabbox/bin/crabbox desktop paste --id <cbx_id-or-slug> --text \"user@example.com\"\n../crabbox/bin/crabbox desktop key --id <cbx_id-or-slug> ctrl+l\n../crabbox/bin/crabbox artifacts collect --id <cbx_id-or-slug> --all --output artifacts/<slug>\n../crabbox/bin/crabbox artifacts publish --dir artifacts/<slug> --pr <number>\n```\n\n`desktop launch --webvnc --open` is usually the nicest one-shot: it starts the\nbrowser/app inside the visible session, bridges the lease into the authenticated\nWebVNC portal, and opens the portal. Keep browsers windowed for human QA; use\n`--fullscreen` only for capture/video workflows.\nFor human handoff, include `--take-control` so the opened portal viewer gets\nkeyboard/mouse control automatically instead of landing as an observer.\n\nHuman handoff preflight:\n\n- Do not assume a visible desktop or launched browser means the repo CLI/app is\n  installed, built, or on the interactive terminal's `PATH`.\n- Before handing WebVNC to a human tester, prove the expected command from the\n  same kept lease and from a neutral directory such as `~`.\n- If the handoff needs repo-local code, sync/build/link it explicitly on that\n  lease. Source-tree CLIs often need build output before a symlink works.\n- Prefer a real `command -v <expected-command> && <expected-command> --version`\n  check over a repo-root-only `pnpm ...` command.\n\nGeneric handoff repair pattern:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --full-resync --shell -- \\\n  \"set -euo pipefail\n   pnpm install --frozen-lockfile\n   pnpm build\n   sudo ln -sf \\\"\\$PWD/<cli-entry>\\\" /usr/local/bin/<expected-command>\n   cd ~\n   command -v <expected-command>\n   <expected-command> --version\"\n```\n\n## If Crabbox Fails\n\nKeep the fallback narrow. First decide whether the failure is Crabbox itself,\nthe brokered AWS lease, Blacksmith/Testbox, repo hydration, sync, or the test\ncommand.\n\nFast checks:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,140p'\n../crabbox/bin/crabbox doctor\ncommand -v blacksmith\nblacksmith --version\nblacksmith testbox list\n```\n\nCommon Crabbox-only failures:\n\n- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling\n  repo, or update/install Crabbox before retrying.\n- Local-container hydration rejects a configured Actions `uses` step: stay on\n  `provider=local-container`, add `--no-hydrate`, and perform the required\n  dependency setup inside the container command. For example:\n\n  ```sh\n  ../crabbox/bin/crabbox run --no-hydrate --timing-json --shell -- \\\n    \"corepack enable && pnpm install --frozen-lockfile && <check-command>\"\n  ```\n\n  This is a hydration transport workaround, not permission to run the broad\n  check on the host or silently select a remote provider.\n- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and\n  `crabbox whoami`; preserve the resolved provider unless the user explicitly\n  requests another backend.\n- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot\n  without `--id`.\n- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the\n  printed Actions URL. Large sync warnings now include top source directories\n  by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect\n  those before reaching for `--force-sync-large`. Quiet rsync watchdogs and SSH\n  timeouts now print `next_action=` hints; follow them, usually `--full-resync`\n  first and a fresh lease second.\n- Cleanup uncertainty: run `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  only boxes you created.\n- Testbox queued/capacity pressure: do not retry repeatedly or switch providers.\n  Report the blocker and preserve the resolved provider.\n\nIf the resolved direct provider cannot dispatch, sync, attach, or stop, retry\nonce with `--debug` and `--timing-json` without changing providers:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\n```\n\nAuth fallback, only when `blacksmith` says auth is missing:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\nRaw Blacksmith footguns:\n\n- Run from repo root. The CLI syncs the current directory.\n- Save the returned `tbx_...` id in the session.\n- Reuse that id for focused reruns; stop it before handoff.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable\n  queue.\n\nIf the selected Blacksmith backend is down or quota-limited, do not keep probing\nit or switch providers. Report the delegated-provider outage.\n\n## Blacksmith Backend Notes\n\nCrabbox Blacksmith backend delegates setup to:\n\n- the organization reported by `crabbox config show`\n- a Testbox-capable `blacksmith.workflow` or `actions.workflow` in the target\n  repository\n- `blacksmith.job` / `blacksmith.ref`, with `actions.job` / `actions.ref`\n  fallbacks\n\nThe hydration workflow owns checkout, Node/pnpm setup, dependency install,\nsecrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command\nexecution, timing, logs/results, and cleanup.\n\nMinimal configured Blacksmith-backed Crabbox run, from repo root. Do not use\nthis fresh-run form until the effective workflow is present and verified as\nTestbox-capable; supply the explicit user-provided workflow above or reuse an\nexisting Testbox id instead.\n\n```sh\n../crabbox/bin/crabbox run --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed\n```\n\nUse direct Blacksmith only when Crabbox is the broken layer and you are\nisolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup\ndiagnostics, not as a reusable work queue.\n\nImportant Blacksmith footguns:\n\n- Always run from repo root. The CLI syncs the current directory.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- If auth is missing and browser auth is acceptable:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\n## Brokered AWS\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects AWS. Do not infer AWS from an omitted `--provider`.\n\nConfirm the selection first:\n\n```sh\ncrabbox config show\ncrabbox doctor\n```\n\nFor Linux, the repository configuration supplies the broker URL, developer\nimage, `eu-west-1` default region, capacity-region candidates, and\nspot-to-on-demand capacity policy. Do not repeat those values on every command;\nthe resolved configuration remains the source of truth. For native Windows,\nuse the `us-west-2` on-demand command in \"macOS And Windows Targets\" above. For\nbrokered macOS, complete the quota/IAM and no-spend Dedicated Host preflight in\nthat section before allocation. If the user explicitly selects AWS over a\ndifferent resolved provider, add `--provider aws` to the AWS commands below.\n\n```sh\n../crabbox/bin/crabbox warmup --idle-timeout 90m\n../crabbox/bin/crabbox actions hydrate --id <cbx_id-or-slug>\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --timing-json --shell -- \"env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n../crabbox/bin/crabbox stop <cbx_id-or-slug>\n```\n\nInstall/auth for owned Crabbox if needed. When configuration already resolves\nAWS and only broker auth is missing, omit `--provider` so login writes the token\nwithout changing provider selection:\n\n```sh\nbrew install openclaw/tap/crabbox\ncrabbox login --url https://crabbox.openclaw.ai\n```\n\nIf the user explicitly wants AWS as their persisted user-config default, use\n`crabbox login --url https://crabbox.openclaw.ai --provider aws`. The provider\nflag writes both broker auth and `provider=aws`; it is a configuration change,\nnot merely credential scoping. Repository config or `CRABBOX_PROVIDER` may\nstill take higher precedence, so confirm the effective result with\n`crabbox config show` in the target worktree.\n\nNew users should self-resolve broker auth before anyone asks for AWS keys:\n\n```sh\ncrabbox config show\ncrabbox doctor\ncrabbox whoami\n```\n\n- If broker auth is missing, run `crabbox login --url https://crabbox.openclaw.ai`.\n  Add `--provider aws` only when the user also wants to persist AWS as their\n  user-config default.\n- If the CLI asks for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS\n  profile setup during normal OpenClaw validation, assume the agent selected\n  the wrong path. Use brokered `crabbox login` or an existing brokered lease\n  before asking the user for cloud credentials.\n- Ask for AWS keys only for explicit direct-provider/account administration,\n  not for normal brokered OpenClaw proof.\n- Trusted automation that intentionally persists AWS as its default may use\n  `printf '%s' \"$CRABBOX_COORDINATOR_TOKEN\" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin`.\n\nmacOS config lives at:\n\n```text\n~/Library/Application Support/crabbox/config.yaml\n```\n\nIt should include `broker.url` and `broker.token` for AWS lanes. Let the resolved\nconfig select the backend; override it only when the user explicitly requests a\ndifferent provider.\n\n### Interactive Desktop / WebVNC\n\nFor human desktop demos, prefer `webvnc` over native `vnc` and keep the remote\ndesktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE\npanel/window chrome unless the explicit goal is video/capture output. After\nlaunch, verify a screenshot shows the desktop panel plus browser title bar. If\nChrome is fullscreen, toggle it back with:\n\n```sh\ncrabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11'\n```\n\n## Diagnostics\n\n```sh\ncrabbox status --id <id-or-slug> --wait\ncrabbox inspect --id <id-or-slug> --json\ncrabbox sync-plan\ncrabbox history --limit 20\ncrabbox history --lease <id-or-slug>\ncrabbox attach <run_id>\ncrabbox events <run_id> --json\ncrabbox logs <run_id>\ncrabbox results <run_id>\ncrabbox cache stats --id <id-or-slug>\ncrabbox ssh --id <id-or-slug>\nblacksmith testbox list\n```\n\nUse `--debug` on `run` when measuring sync timing.\nUse `--timing-json` on warmup, hydrate, and run when comparing backends.\nUse `--market spot|on-demand` only on AWS warmup/one-shot runs.\n\n## Failure Triage\n\n- Crabbox cannot find provider: verify `../crabbox/bin/crabbox --help` lists\n  the provider selected by `.crabbox.yaml`; update Crabbox before falling back.\n- Hydration stuck or failed: open the printed GitHub Actions run URL and inspect\n  the hydration step.\n- Sync failed: rerun with `--debug`; check changed-file count and whether the\n  checkout is dirty.\n- Command failed: rerun only the failing shard/file first. Do not rerun a full\n  suite until the focused failure is understood.\n- Cleanup uncertain: `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  owned `tbx_...` leases you created.\n- Selected provider broken: report the provider-specific blocker; do not switch\n  providers unless the user explicitly requests the fallback.\n\n## Boundary\n\nDo not add OpenClaw-specific setup to Crabbox itself. Put repo setup in the\nhydration workflow and keep Crabbox generic around lease, sync, command\nexecution, logs/results, timing, and cleanup.\n",".agents/skills/local-clawsweeper-review/SKILL.md":"---\nname: local-clawsweeper-review\ndescription: Run local ClawSweeper exact-item or committed-range reviews without GitHub mutation.\n---\n\n# Local ClawSweeper Review\n\nUse this skill when someone wants read-only local ClawSweeper output before\nsubmitting, updating, or re-reviewing an issue or PR.\n\n## Safety Boundary\n\n- Run only `pnpm run review -- --local-only` for an existing GitHub item, or\n  `pnpm run review -- --local-range` for a pre-submission committed range.\n- Do not run `apply-artifacts`, `apply-decisions`, GitHub comment posting, or\n  merge/autofix commands unless the user explicitly asks for that mutation.\n- Do not print `OPENAI_API_KEY`, `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN`, GitHub\n  tokens, or Codex auth material.\n- Treat generated review artifacts as local proof. Do not claim ClawSweeper\n  posted or synced anything unless a separate explicit mutation command did it.\n\n## Locate ClawSweeper\n\nPrefer the current repository when its `package.json` name is\n`@openclaw/clawsweeper`. Otherwise use a known clean local checkout:\n\n- Windows: `C:\\oc-work\\clawsweeper-source`\n- POSIX fallback: `~/Projects/clawsweeper`\n\nInspect `git status --short` before making changes. If another ClawSweeper clone\nis dirty or ambiguous, do not use it for the local review runner.\n\n## First-Time Setup\n\nFrom the ClawSweeper checkout:\n\n```sh\ncorepack enable\npnpm install\npnpm run build:all\npnpm run codex:local:check -- --diagnostics\n```\n\nThe diagnostics mode checks the selected Codex binary and login status without\na model request. It does not prove model access or review readiness. Omit\n`--diagnostics` for the existing model smoke test, which consumes model usage.\n\nIf the Codex check says the CLI is not logged in, have the operator authenticate\ntheir own Codex CLI. Device auth is the simplest shareable setup:\n\n```sh\ncodex login --device-auth -c 'service_tier=\"fast\"'\n```\n\nFor API-key setup, pass the key through the shell only for the login command and\nthen clear it from the environment. Do not put the key in docs, scripts, shell\nhistory, or committed files.\n\nPowerShell:\n\n```powershell\n$env:OPENAI_API_KEY = Read-Host \"OpenAI API key\"\n$env:OPENAI_API_KEY | codex login --with-api-key -c 'service_tier=\"fast\"'\nRemove-Item Env:OPENAI_API_KEY\n```\n\nPOSIX shell:\n\n```sh\nprintf '%s' \"$OPENAI_API_KEY\" | codex login --with-api-key -c 'service_tier=\"fast\"'\nunset OPENAI_API_KEY\n```\n\nIf the wrong Codex binary is used, set `CODEX_BIN` in the local shell for that\nrun. Otherwise, `--local-only` uses the first spawnable `codex` command on\n`PATH`, including on Windows. If no Windows PATH command is spawnable, it falls\nback to the installed Codex Desktop binary.\n\n## Target Checkout Modes\n\nBy default, an exact local PR review manages its own target checkout under\n`artifacts/local-review-<pr-number>/target`.\n\nBy default, `--local-range` reviews the clean checkout where the command was\ninvoked. It does not manage or switch that checkout. Pass `--target-dir` when\nthe branch to review is elsewhere.\n\nIn a built source checkout, `node dist/clawsweeper-local.js review` is the\nlocal-only entrypoint for the same full committed-range engine. Its `--help`\nand `--version` paths do not load the review engine or invoke Codex. It does not\nprovide diagnostics yet; `codex:local:check` remains the existing model smoke\ntest. This entrypoint does not publish hosted action-ledger or cache metadata.\n\nPass `--target-dir` when the operator wants to review an existing checkout or\nan issue.\n\nUse a clean target checkout of the repository being reviewed. Prefer a dedicated\nreview checkout if the normal worktree is dirty:\n\n- Windows: `C:\\oc-work\\clawsweeper-local-target-openclaw`\n- POSIX fallback: `../openclaw`\n\nBefore reviewing against `main`, update the target checkout only when it is\nclean:\n\n```sh\ngit -C <target-dir> status --short\ngit -C <target-dir> fetch origin main\ngit -C <target-dir> switch main\ngit -C <target-dir> pull --ff-only origin main\n```\n\nDo not switch branches, pull, or overwrite files in a dirty target checkout.\n\n## Run A Local Review\n\nUse the exact issue or PR number. If the number is not provided and the current\nbranch has an open PR, use `gh pr view --json number,url,headRefOid` to identify\nit.\n\nFrom the ClawSweeper checkout:\n\n```sh\npnpm run review -- --local-only --item-number <pr-number>\n```\n\nTo use a supplied checkout or review an issue:\n\n```sh\npnpm run review -- --local-only \\\n  --item-number <issue-or-pr-number> \\\n  --target-dir <target-dir>\n```\n\nTo review committed branch work before a PR exists:\n\n```sh\npnpm run review -- --local-range \\\n  --target-repo <owner/repo> \\\n  --base origin/main\n```\n\nThe range is `merge-base(<base>, HEAD)..HEAD`. It must be clean and contain at\nleast one commit beyond the base. This path withholds GitHub credentials,\nisolates cached `gh` auth, disables web search, and skips host-side URL/media\npreprocessing. It still calls the configured Codex model service; do not call it\nair-gapped or fully network-offline.\n\nThe exact local command prints a human-readable progress summary by default. Add\n`--verbose` only when debugging checkout, selection, or Codex process details.\n\nFor quick smoke tests, lower `--batch-size`, `--shard-count`, `--max-pages`, and\n`--codex-timeout-ms`, but label the result as a smoke run rather than a full\nlocal review.\n\n## Read The Artifact\n\nThe default OpenClaw report is written to:\n\n```text\n<artifact-dir>/<issue-or-pr-number>.md\n```\n\nRead the artifact and summarize:\n\n- `review_status`\n- `main_sha`\n- `pull_head_sha` for PRs\n- decision/confidence/action fields when present\n- findings or blockers\n- exact Codex/auth/runtime failure if the run failed\n\nIf the failure is Codex auth, stop after providing the local setup command. If\nthe failure is runner/runtime behavior, include the artifact path and a concise\nstderr or log summary.\n\n## Closeout\n\nBefore reporting success:\n\n- Confirm the command used `review --local-only` or `review --local-range`.\n- Confirm no GitHub comments, labels, merges, or apply commands were run.\n- Confirm the target checkout is still clean.\n- If findings exist, list the actionable items and the next local fix/test step.\n- If no blockers exist, say the local ClawSweeper artifact found no blockers\n  and include the reviewed `main_sha` and PR head SHA when available.\n",".agents/skills/local-clawsweeper-review/agents/openai.yaml":"interface:\n  display_name: \"Local ClawSweeper Review\"\n  short_description: \"Run local ClawSweeper before PRs\"\n  default_prompt: \"Use $local-clawsweeper-review to run a local ClawSweeper review before I submit a PR.\"\n","AGENTS.md":"# AGENTS.MD\n\nClawSweeper is the conservative maintenance bot for OpenClaw repositories.\nKeep changes narrow, evidence-backed, and automation-safe.\n\n`AGENTS.md` is the canonical repository-wide coding-agent policy. Task-specific\nworkflows under `.agents/skills/` are opt-in procedures and do not override this\nfile. This repository does not currently maintain `AGENT.md`, `CLAUDE.md`, or\nCursor aliases; agents that do not discover `AGENTS.md` automatically must be\ndirected here rather than given a duplicated policy copy.\n\n## Structure\n\n- Main code: `src/clawsweeper.ts`.\n- Repair lane code: `src/repair/`; canonical records live in the Cloudflare\n  Worker, ledger/assets blobs live in R2, and remaining operational state lives\n  in `openclaw/clawsweeper-state`.\n- Tests: `test/*.test.ts` and `test/repair/*.test.ts`; add new coverage to the\n  narrowest matching test file instead of growing `test/clawsweeper.test.ts`.\n- Workflow: `.github/workflows/sweep.yml`.\n- Vision and product boundaries: `VISION.md`.\n- Explainer: `README.md`; state/dashboard repo: `../clawsweeper-state`.\n- Changelog: one-bullet fragments in `changelog.d/`, stitched into\n  `CHANGELOG.md` at release time; see\n  [`changelog.d/README.md`](changelog.d/README.md).\n- Open/reviewed records in the canonical Worker store:\n  `records/<repo-slug>/items/<number>.md`.\n- Archived records in the canonical Worker store:\n  `records/<repo-slug>/closed/<number>.md`.\n- Scratch/generated output: `.artifacts/`, `artifacts/`, `apply-report.json`.\n\nPreserve one flat `items/` and `closed/` report layout per repository slug. Do\nnot split reports into issue/PR subtrees.\n\n## Operating Model\n\n- Review lane is proposal-only. It never closes GitHub items.\n- Ordinary PRs receive one automatic completed review after ten quiet minutes.\n  Later pushes, edits, reopen events, and scheduled passes require a new explicit\n  review request. Failed or stale-source attempts can finish the first review.\n  `clawsweeper:autofix` and `clawsweeper:automerge` no longer change review\n  admission; they only keep their close protection.\n- Maintainer-authored items and items labeled `maintainer` created from\n  2026-10-15 03:50 UTC are reviewed like everyone else's: a PR gets its one\n  automatic review. Older maintainer items need an explicit `@clawsweeper review`\n  request.\n  Finish the work and validation first; request review only when it is needed.\n  Agents must not request reviews automatically or repeat a queued/running request.\n  An explicit review request stays open while the queue requeues its own review\n  after source drift, in place or from the publisher still holding the request's\n  publication; that retry continues the request. A finished or replaced\n  request, later changes after the answer, and scheduled passes need a new\n  request.\n- Apply lane mutates GitHub by syncing the durable Codex review comment and then\n  closing only unchanged, high-confidence proposals.\n- Repository-specific rules live in `src/repository-profiles.ts`; ClawHub apply\n  may close only PRs that are certainly implemented on `main`.\n- Hosted review concurrency and batching belong to the shared exact-review\n  queue. Broad sweeps only admit candidates; they do not start per-run shards\n  or grant immediate-apply authority.\n- `openclaw/clawsweeper-state` is the live status surface and operational state\n  store; the Worker/R2 pair is authoritative for records, ledger, and assets.\n  Check current Actions and the canonical owner before trusting local generated\n  timestamps.\n- When asked about PRs outside `openclaw/clawsweeper`, treat the task as\n  monitoring/debugging how ClawSweeper workflows operate on that PR. Do not fix\n  foreign PR branches directly; ClawSweeper repair/automerge workflows own those\n  branch edits.\n- In `openclaw/openclaw`, `CHANGELOG.md` is release-owned. Do not ask contributor\n  PR authors, repair workers, or automerge/autofix lanes to edit it during normal\n  PR work. Preserve release-note context in PR bodies and commit messages instead.\n- In `openclaw/clawsweeper` itself, record a user-visible change as one new\n  `changelog.d/<pr-or-slug>.md` fragment holding a single bullet line. Do not\n  edit `CHANGELOG.md` or other PRs' fragments in normal PR work; the release\n  maintainer folds fragments in with `pnpm run changelog:stitch`, and\n  `pnpm run check:changelog` validates them.\n- When referencing GitHub issues or PRs in user-facing output, always include\n  the full GitHub URL, not only `#12345`.\n\n## Safety Rules\n\n- Never disable or pause the live ClawSweeper sweep workflow unless Peter\n  explicitly asks for that exact action.\n- Do not run live apply/close commands unless Peter explicitly asks.\n- For apply-path repros, copy one report into a temp `items/` dir and pass\n  `--skip-dashboard`, `--item-number`, and a temp `--closed-dir`.\n- Treat maintainer-authored and protected-label items as non-closeable, except\n  for `implemented_on_main` with its existing\n  source/history/release evidence and fresh apply guards (PRs additionally need\n  GitHub-verified merged same-repository fixing provenance and paired-issue\n  relationship checks; see `docs/implemented-on-main-close-policy.md`), and\n  the maintainer-approved metadata-only `oversized_pull_request` policy:\n  drafts, maintainer authorship, and the `maintainer` label do not exempt that\n  reason. Its explicit PR exemption labels, `size: accepted-large`, other\n  protected labels, live freshness checks, and apply gates still apply.\n- Leave canonical OpenClaw Mantis locale PRs open; their generated-PR publisher\n  owns freshness and auto-merge. See `docs/target-repositories.md` for identity scope.\n- Snapshot or `updated_at` drift blocks apply unless the only change is the\n  existing ClawSweeper review comment, or a ClawSweeper-recorded write for the\n  item (`docs/scheduler.md`) while the complete source/timeline/head/activity\n  receipt matches and no non-automation activity follows the review snapshot.\n- Open-but-locked issues can exist when stale automation locked a closed issue\n  and the author later reopened it. These must be skipped, not allowed to crash\n  the apply run.\n- Locked-comment 403s from GitHub are terminal apply skips, not retryable API\n  failures.\n\n## PR Validation and Landing\n\n- For code-bearing changes, run focused validation that exercises the changed\n  behavior, commit the final candidate, then obtain a fresh Codex review of the\n  entire committed branch against a pinned intended base. Require a clean index\n  and working tree; review the merge-base-to-HEAD range, not only the last commit.\n  Complete this review before publication, handoff, or landing, including direct\n  pushes where otherwise permitted. Early local review is optional feedback and\n  does not replace this final branch review. See `CONTRIBUTING.md` for the command.\n- Address every accepted or actionable finding and repeat the affected proof and\n  review after fixes. A changed head, parent or selected base/range, dirty source,\n  post-review hook edits, or changed review evidence, context, or applicable policy\n  invalidates the affected review. Verify the final source after hooks and before\n  publication or handoff. A failed or incomplete review never falls back to an\n  earlier clean result; repeat review when needed, not merely to obtain a nicer\n  verdict. An unchanged Git tree alone does not establish equivalent review inputs.\n  CI, an older ClawSweeper comment, prior review comments, or manual self-review\n  alone do not replace this loop or the separate gates below.\n- At task kickoff, define the `pr-behavior-proof` contract for every\n  code-bearing PR: claim, exercised surface, scenario or fixture, command and\n  environment, observable result, artifact or trace, and limits. Run its\n  controlled real-behavior proof before opening even a draft PR; only Martin\n  may expressly approve an evidence-in-progress exception.\n- Keep that proof current in the PR body. Tests, CI, mocks, snapshots, lint,\n  typechecks, and clean review support the claim but never replace proof of a\n  changed runtime, workflow, queue, API, UI, package, or integration path. On\n  this Windows host, proof for those surfaces uses Docker-backed Crabbox\n  `local-container` and records the current head, provider, image, lease,\n  artifact, and limits. Use the narrowest meaningful proof first and broaden\n  it for shared or higher-risk behavior. Docs-only changes normally need\n  `git diff --check` and relevant link or command sanity instead.\n- The public dashboard is observer-only: it may display status and provide\n  view-only navigation to verified-public GitHub repository, item, workflow-run,\n  and job pages. Those canonical GET links are references, not action controls.\n  It never calls GitHub from the browser and never triggers or offers queue,\n  workflow, GitHub, DLQ, recovery, deploy, rollback, or other mutation controls.\n- A ClawSweeper result that requires proof or identifies an accepted/actionable\n  finding remains PR-owner work, not a handoff. Before a manually requested\n  review or re-review, put current proof and the finding disposition or evidence\n  in the main PR body. A head or review-content body change after the durable review marker\n  makes that review and any affected proof stale: rerun the affected proof and\n  obtain a review for the current head and body. CI, labels, readiness, and\n  maintainer permissions are evidence only; the explicit-user-approval boundary\n  below still controls landing.\n- Before merge or automerge, the latest ClawSweeper review must apply to the\n  current PR head and review-content body. The canonical preflight reader excludes\n  one valid advisory annotation only; human text, proof, and all outside whitespace\n  remain review content. Raw event and concurrency guards can still invalidate\n  after a metadata edit. Resolve every accepted finding. Apply each\n  applicable `Rank-up moves:` item, or explicitly justify the exception in the\n  PR body; Rank-up moves remain optional and do not by themselves block merge.\n  Do not merge while proof is missing or while the review has an unresolved\n  contributor-facing blocker.\n- Land only after the current review and status evidence is ready for\n  maintainer look, including `proof: sufficient` or `proof: override` when the\n  proof label applies. This does not replace the user's explicit merge approval\n  in the current conversation; agents must not merge or enable/execute\n  automerge without it.\n\n## Commands\n\n```bash\ncorepack enable\npnpm install\npnpm run build\npnpm run test:unit\npnpm run format\npnpm run check\n```\n\nUse `pnpm run check` before handoff for code/test/workflow changes.\n\n`engines.node` is `>=24`. Node 22 will install (no `engine-strict`) but the\nnotifier tests' 5-second retry paths surface as `cancelledByParent` under the\nold `node:test` runner. Run on Node 24 or newer before reporting test\nfailures.\n\n## GitHub Checks\n\nUseful live probes:\n\n```bash\ngh run list --repo openclaw/clawsweeper --limit 20 --json databaseId,displayTitle,status,conclusion,createdAt,updatedAt\ngh api repos/openclaw/clawsweeper/readme --jq '.content' | base64 --decode\ngh api graphql -f query='query { repository(owner:\"openclaw\", name:\"openclaw\") { issues(states: OPEN) { totalCount } pullRequests(states: OPEN) { totalCount } } }'\n```\n\nFor throughput/default tuning, start with `config/automation-limits.json` and\n[`docs/limits.md`](docs/limits.md). `scripts/check-limits.ts` identifies the\nderived docs, Worker values, and the `workflow_dispatch` literals that must stay\naligned. Effective exact-review admission, publication, and batching overrides\nlive in `dashboard/wrangler.toml`; owning fallback behavior lives in\n`dashboard/exact-review-queue.ts`. Update `.github/workflows/sweep.yml` or\n`src/clawsweeper.ts` only when the changed contract is actually owned there.\n\nUse [`docs/README.md`](docs/README.md) for the documentation map, lifecycle\nstates, role ownership, and cross-surface update triggers.\n"},"files":{".agents/skills/crabbox/SKILL.md":"---\nname: crabbox\ndescription: Use the Crabbox wrapper for validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id.\n---\n\n# Crabbox\n\n## Provider Selection Contract\n\nProvider selection is configuration resolution, not testing policy. Run\n`crabbox config show` from the exact worktree being tested; a session may have\nstarted in another checkout whose repository config or skill text is stale. A\nrequest to \"use Crabbox\" does not authorize a provider override. When the user\ndoes not name a backend, omit `--provider` and preserve the resolved provider,\nincluding values supplied by user config or `CRABBOX_PROVIDER`.\n\nTest scope, expected duration, and hydration failures do not select a provider.\nOverride the resolved provider only when the user explicitly names a different\nbackend. If that provider cannot perform the requested test, report the blocker\ninstead of silently selecting another backend.\n\nUse the Crabbox wrapper for validation execution, environment lifecycle, sync,\nlogs/results, cache inspection, and lease cleanup.\n\nCrabbox is the transport/orchestration surface. The actual backend can be:\n\n- local Docker isolation: `provider=local-container`, lease ids like `cbx_...`\n- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like\n  `cbx_...`, `syncDelegated=false`\n- Blacksmith Testbox through Crabbox: delegated provider,\n  `provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`\n\nThe provider-specific sections below document capabilities and commands after\nconfiguration or an explicit user request has selected a backend. They are not\nprovider-selection policy. Their validation commands intentionally omit\n`--provider`; add it only to carry out an explicit user override of the resolved\nconfiguration.\n\nProvider identity must remain attached to a lease after creation. A lease\ncreated through the resolved configuration can keep using provider-neutral\ncommands while that configuration is unchanged. If the user explicitly\noverrode the provider, or the resolved configuration has changed since the\nlease was created, pass the provider reported by Crabbox to every later command\nthat targets that lease, including hydrate, rerun, desktop/WebVNC, status,\ninspect, SSH, and stop. This preserves resource identity; it does not select a\nprovider for unrelated work.\n\nWhen the resolved configuration selects Blacksmith Testbox, or the user\nexplicitly requests it, do not describe the run as \"AWS Crabbox\". Report it as\nTestbox-through-Crabbox with the `tbx_...` id and Actions run.\n\nDirect AWS supports persistent leases, `--fresh-pr`, `--full-resync`,\nenvironment forwarding, capture/download, and provider-comparison workflows.\nBlacksmith Testbox provides a prepared CI environment and delegated broad/heavy\n`pnpm` gates. These capabilities do not override the resolved configuration.\n\n## First Checks\n\n- Run from the repo root. Crabbox sync mirrors the current checkout.\n- Check the wrapper and providers before Crabbox work:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,120p'\n../crabbox/bin/crabbox desktop launch --help\n../crabbox/bin/crabbox webvnc --help\n```\n\n- OpenClaw scripts prefer `../crabbox/bin/crabbox` when present. The user PATH\n  shim can be stale.\n- Read `.crabbox.yaml`, then run `crabbox config show` from the repository root\n  before selecting a provider. The resolved provider can come from the user's\n  Crabbox config or environment as well as the repository file.\n- Omitting `--provider` means \"use the resolved configuration\". Pass it only\n  when the user explicitly requests a different backend, and report the\n  provider from Crabbox output rather than inferring it from bootstrap wording.\n- Treat `CRABBOX_PROVIDER` as part of that resolved provider configuration. The\n  provider reported by `crabbox config show` is authoritative; a hydration or\n  test failure is not permission to switch backends. Override it only when the\n  user explicitly names another provider.\n- Some package-manager wrappers insert a command delimiter before Crabbox\n  options. If the printed command looks like `crabbox run -- --provider ...`\n  or `crabbox run -- --no-hydrate ...`, call the trusted Crabbox binary\n  directly so lifecycle flags are parsed by Crabbox.\n- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo\n  config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.\n  If warmup drifts well past the minute-scale path, verify image promotion,\n  region/AZ placement, and FSR state before blaming OpenClaw.\n- Targeted and broad `pnpm` gates both use the resolved provider. Test size does\n  not authorize a provider override.\n- Always report the provider field and id. Both local-container and direct\n  providers can use `cbx_...`, so the id prefix alone does not prove AWS;\n  `tbx_...` identifies Blacksmith Testbox through Crabbox. If the output only\n  says `blacksmith testbox list`, use `blacksmith testbox list --all` before\n  concluding no box exists.\n- If a warm direct-provider lease smells stale, retry with `--full-resync`\n  (alias `--fresh-sync`) before replacing the lease. This resets the remote\n  workdir, skips the fingerprint fast path, reseeds Git when possible, and\n  uploads the checkout from scratch.\n- For live/provider bugs, use the configured secret workflow before downgrading\n  to mocks. Copy only the exact needed key into the remote process environment\n  for that one command. Do not print it, do not sync it as a repo file, and do\n  not leave it in remote shell history or logs. If no secret-safe injection path\n  is available, say true live provider auth is blocked instead of silently using\n  a fake key.\n- Targeted versus broad describes test scope only; it does not imply local,\n  remote, host, or container execution.\n- Do not treat unrelated inherited shell controls as operator intent. In\n  particular, `OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not\n  permission to move broad `pnpm check:changed`, `pnpm test:changed`, full\n  `pnpm test`, or lint/typecheck fan-out onto the laptop. This does not negate\n  provider-selection variables such as `CRABBOX_PROVIDER`, which are resolved\n  and reported by `crabbox config show`.\n- `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` controls direct host execution; it\n  is separate from Crabbox provider selection and must not override the provider\n  reported by `crabbox config show`.\n\n## macOS And Windows Targets\n\nUse these only when the task needs an existing non-Linux host. OpenClaw Linux\nvalidation uses the resolved Crabbox configuration unless the user explicitly\nrequests another provider or target.\n\nNative Windows is available when the resolved provider supports that target.\nFor providers other than AWS, keep placement and capacity in their resolved\nconfiguration:\n\n```sh\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --timing-json\n```\n\nAWS has a provider-specific placement requirement: the OpenClaw Windows\ndeveloper image and Docker cache are available in `us-west-2`, and native\nWindows leases must use on-demand capacity. After `crabbox config show` confirms\n`provider=aws` (or the user explicitly selects AWS), use:\n\n```sh\nCRABBOX_AWS_REGION=us-west-2 \\\nCRABBOX_CAPACITY_REGIONS=us-west-2 \\\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --market on-demand \\\n  --timing-json\n```\n\nThe region variables pin both the AWS image lookup and the capacity candidate\nset because `warmup` does not expose a generic `--region` flag. These placement\nand market settings are AWS availability constraints applied after provider\nselection; they are not a reason to select AWS for other runs. If the user\nexplicitly requests AWS while `crabbox config show` resolves another provider,\nadd `--provider aws` to this command to carry out that explicit override.\n\nThe hydrate workflow assumes Docker should already be baked into Linux images\nand only installs it as a fallback. Do not add per-run Docker installs to proof\ncommands unless the image probe shows Docker is actually missing.\n\nWhen the user explicitly asks for brokered macOS runners, use Crabbox AWS\nmacOS only after confirming the deployed coordinator supports EC2 Mac host\nlifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota\nand IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,\nor run the no-spend preflight first:\n\nThese administration commands specify AWS because they inspect or allocate an\nAWS EC2 Dedicated Host. The explicit provider is a billing and resource-scope\nsafety boundary, not a validation default.\n\n```sh\ncrabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json\ncrabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json\nCRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh\n```\n\nDo not silently substitute AWS macOS for normal OpenClaw Linux proof. Report\npaid-host blockers as quota, IAM, coordinator deployment, or host availability\ninstead of falling back to local macOS.\n\nCrabbox supports static SSH targets:\n\nThese commands specify `ssh` because the user-supplied static host selects that\ntransport explicitly; they do not establish an SSH preference for other runs.\n\n```sh\n../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command \"dotnet test\"\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test\n```\n\n- `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH,\n  bash, Git, rsync, and tar contract.\n- Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar\n  archive transfer into `static.workRoot`. Direct native Windows runs support\n  `--script*`, `--env-from-profile`, `--preflight`, and PowerShell `--shell`.\n- `crabbox actions hydrate/register` are Linux-only today; use plain\n  `crabbox run` loops for static macOS and Windows hosts.\n- Live proof needs a reachable, operator-managed SSH host. Without one, verify\n  with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox\n  Go test suite.\n\n## Direct Brokered AWS Backend\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects direct AWS Crabbox.\n\nChanged gate:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\"\n```\n\nFocused rerun:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>\"\n```\n\nRead the JSON summary. Useful fields:\n\n- `provider`: `aws`\n- `leaseId`: `cbx_...`\n- `syncDelegated`: `false`\n- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`\n- `commandMs` / `totalMs`\n- `exitCode`\n\nCrabbox should stop one-shot AWS leases automatically after the run. Verify\ncleanup when a run fails, is interrupted, or the command output is unclear:\n\n```sh\n../crabbox/bin/crabbox list --provider aws\n```\n\nThe explicit provider keeps cleanup attached to the AWS lease recorded by the\nrun, including when AWS was a user-requested override of another configured\ndefault.\n\n## Blacksmith Testbox Through Crabbox\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects Blacksmith Testbox:\n\nA fresh Testbox requires a repository-specific workflow. Crabbox resolves it\nfrom `blacksmith.workflow`, falling back to `actions.workflow`; job and ref use\nthe equivalent Blacksmith values with Actions fallbacks. The workflow must\ncontain a `useblacksmith/testbox`, `useblacksmith/begin-testbox`, or\n`useblacksmith/run-testbox` step. Confirm both the effective config and the\nactual workflow before using the provider-neutral command below; nonempty\nfields alone do not prove that an ordinary Actions workflow is Testbox-capable.\n\nFor a local workflow path, validate it with:\n\n```sh\nrg -n 'useblacksmith/(testbox|begin-testbox|run-testbox)' <workflow-path>\n```\n\nFor a workflow name or id, inspect its YAML through GitHub before dispatch. Do\nnot guess a Testbox workflow from another repository.\n\nIf the user explicitly supplies a Blacksmith override, carry those exact values\non the command instead:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --provider blacksmith-testbox \\\n  --blacksmith-workflow <repository-workflow> \\\n  --timing-json -- <test-command>\n```\n\nAdd `--blacksmith-org`, `--blacksmith-job`, and `--blacksmith-ref` only when the\nuser supplies those overrides. The explicit provider and workflow flags in this\nform implement the user's repository-specific selection; they are not defaults\nfor other runs.\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed\n```\n\nRead the JSON summary and the Testbox line. Useful fields:\n\n- `provider`: `blacksmith-testbox`\n- `leaseId`: `tbx_...`\n- `syncDelegated`: `true`\n- `syncPhases`: delegated/skipped because Blacksmith owns checkout/sync\n- Actions run URL/id from the Testbox output\n- `exitCode`\n\n`blacksmith testbox list` may hide hydrating or ready boxes. Use:\n\n```sh\nblacksmith testbox list --all\nblacksmith testbox status <tbx_id>\n```\n\n## Observability Flags\n\nUse these on debugging runs before inventing ad hoc logging:\n\n- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,\n  and target-specific tool probes. Defaults cover `git`, `tar`, `node`, `npm`,\n  `corepack`, `pnpm`, `yarn`, `bun`, `docker`, plus POSIX\n  `sudo`/`apt`/`bubblewrap` and native Windows\n  `powershell`/`execution_policy`/`longpaths`/`temp`/`pwsh`. Add\n  `--preflight-tools node,bun,docker`, `CRABBOX_PREFLIGHT_TOOLS`, or repo\n  `run.preflightTools` to replace the list. `default` expands built-ins; `none`\n  prints only the workspace summary. Preflight is diagnostic only; install\n  toolchains through Actions hydration, images, devcontainer/Nix/mise/asdf, or\n  the run script. On `blacksmith-testbox`, this prints a delegated-unsupported\n  note because the workflow owns setup.\n- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct\n  providers and prints `set len=N secret=true` style summaries. On\n  `blacksmith-testbox`, env forwarding is unsupported; put secrets in the\n  Testbox workflow instead.\n- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple\n  `export NAME=value` / `NAME=value` lines from a local profile without\n  executing it, then forwards only allowlisted names. `--allow-env` is\n  repeatable and comma-separated. Profile values override ambient allowlisted\n  env values for that run. Direct POSIX, WSL2, and native Windows runs are\n  supported; delegated providers are not. Crabbox probes the uploaded profile\n  remotely and prints redacted presence/length metadata before the command.\n- `--env-helper <name>`: with `--env-from-profile` on POSIX SSH targets,\n  persists `.crabbox/env/<name>` and `.crabbox/env/<name>.env` so follow-up\n  commands on the same lease can run through `./.crabbox/env/<name> <command>`.\n  Use only on leases you control; the profile stays until cleanup, lease reset,\n  or `--full-resync`.\n- `--script <file>` / `--script-stdin`: upload a local script into\n  `.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute\n  directly on POSIX; scripts without a shebang run through `bash`. Native\n  Windows uploads run through Windows PowerShell, and Crabbox appends `.ps1`\n  when needed. Arguments after `--` become script args.\n- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a\n  fresh remote checkout of the GitHub PR. Bare numbers use the current repo's\n  GitHub origin. Add `--apply-local-patch` only when the current local\n  `git diff --binary HEAD` should be applied on top of that PR checkout.\n- `--full-resync` / `--fresh-sync`: reset a stale direct-provider workdir\n  before syncing. Use after sync fingerprints look wrong, SSH times out before\n  sync, or rsync watchdog output suggests it. It is redundant with\n  `--fresh-pr`, incompatible with `--no-sync`, and unsupported by delegated\n  providers.\n- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to\n  local files and keep binary/noisy output out of retained logs. Parent\n  directories must already exist. These are direct-provider only.\n- `--capture-on-fail`: on non-zero direct-provider exits, downloads\n  `.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,\n  `coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.\n- `--keep-on-failure`: leave a failed one-shot lease alive for live debugging\n  until idle/TTL expiry. Useful on direct providers and delegated one-shots.\n- `--timing-json`: final machine-readable timing. Add\n  `echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell\n  commands; direct providers and Blacksmith Testbox both report them as\n  `commandPhases`.\n\nLive-provider debug template for the resolved direct-provider lease:\n\n```sh\nmkdir -p .crabbox/logs\n../crabbox/bin/crabbox run \\\n  --preflight \\\n  --allow-env OPENAI_API_KEY,OPENAI_BASE_URL \\\n  --timing-json \\\n  --capture-stdout .crabbox/logs/live-provider.stdout.log \\\n  --capture-stderr .crabbox/logs/live-provider.stderr.log \\\n  --capture-on-fail \\\n  --shell -- \\\n  \"echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live\"\n```\n\nDo not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or\n`--sync-only` to delegated providers. Also do not pass `--script*`,\n`--fresh-pr`, `--full-resync`, or `--env-helper` there. Crabbox rejects these\nbecause the provider owns sync or command transport. `--keep-on-failure` is OK\nfor delegated one-shots when you need to inspect a failed lease.\n\n## Efficient Bug E2E Verification\n\nUse the smallest Crabbox lane that proves the reported user path, not just the\ntouched code. Aim for one after-fix E2E proof before commenting, closing, or\nopening a PR for a user-visible bug.\n\nWhen the user says \"test in Crabbox\", do not simply copy tests to the remote\nbox and run them there. Crabbox is for remote real-scenario proof: copy or\ninstall OpenClaw as the user would, run the same setup/update/CLI/Gateway/API\ncall that failed, and capture behavior from that entrypoint. For regressions or\nbug reports, prove the broken state first when feasible, then run the same\nscenario after the fix.\n\nPick the lane by symptom:\n\n- Docker/setup/install bug: build a package tarball and run the matching\n  `scripts/e2e/*-docker.sh` or package script. This proves npm packaging,\n  install paths, runtime deps, config writes, and container behavior.\n- Provider/model/auth bug: prefer true live E2E. Use the configured secret\n  workflow, then inject the single needed key into Crabbox if needed. Scrub\n  unrelated provider env vars in the child command so interactive defaults do\n  not drift to another provider. If only a dummy key is used, label the proof\n  narrowly, e.g. \"UI/install path only; live provider auth not exercised.\"\n- Channel delivery bug: use the channel Docker/live lane when available; include\n  setup, config, gateway start, send/receive or agent-turn proof, and redacted\n  logs.\n- Gateway/session/tool bug: prefer an end-to-end CLI or Gateway RPC command that\n  creates real state and inspects the resulting files/API output.\n- Pure parser/config bug: targeted tests may be enough, but still run a\n  Crabbox command when OS, package, Docker, secrets, or service lifecycle could\n  change behavior.\n\nEfficient flow:\n\n1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint\n   when feasible. If the issue cannot be reproduced, capture the exact command\n   and observed behavior instead.\n2. Patch locally and run narrow local tests for edit speed.\n3. Run one Crabbox E2E command that starts from the user-facing entrypoint:\n   package install, Docker setup, onboarding, channel add, gateway start, or\n   agent turn as appropriate.\n4. Record proof as: Testbox id, command, environment shape, redacted secret\n   source, and copied success/failure output.\n5. If the issue says \"cannot reproduce\", ask for the missing config/log fields\n   that would distinguish the tested path from the reporter's path.\n\nKeep it efficient:\n\n- Reuse existing E2E scripts and helper assertions before writing ad hoc shell.\n- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead\n  of quote-heavy `--shell` strings on direct SSH providers.\n- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the\n  local dirty tree. Add `--apply-local-patch` only when testing a local fixup on\n  top of that PR.\n- Use `--full-resync` before replacing a warmed direct-provider lease when the\n  remote workdir or sync fingerprint appears stale.\n- Use one-shot Crabbox for a single proof; use a reusable Testbox only when\n  several commands must share built images, installed packages, or live state.\n- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a\n  candidate tarball; prefer the repo's package helper instead of direct source\n  execution when the bug might be packaging/install related.\n- Keep secrets redacted. It is fine to report key presence, source, and length;\n  never print secret values.\n- Include `--timing-json` on broad or flaky runs when command duration or sync\n  behavior matters.\n\nBefore/after PR proof on delegated Testbox:\n\n- For PRs that should prove \"broken before, fixed after\", compare base and PR\n  on the same Testbox when practical. Fetch both refs, create detached temp\n  worktrees under `/tmp`, install in each, then run the same harness twice.\n- Do not checkout base/PR refs in the synced repo root. Delegated Testbox sync\n  may leave the root dirty with local files; `git checkout` can abort or mix\n  proof state.\n- Temp harness files under `/tmp` do not resolve repo packages by default. Put\n  the harness inside the worktree, or in ESM use\n  `createRequire(path.join(process.cwd(), \"package.json\"))` before requiring\n  workspace deps such as `@lydell/node-pty`.\n- For full-screen TUI/CLI bugs, a PTY harness is stronger than helper-only\n  assertions. Use a real PTY, wait for visible lifecycle markers, send input,\n  then send control keys and assert process exit/stuck behavior.\n- When validating a rebased local branch before push, remember delegated sync\n  usually validates synced file content on a detached dirty checkout, not a\n  remote commit object. Record the local head SHA, changed files, Testbox id,\n  and final success markers; after pushing, ensure the pushed SHA has the same\n  file content.\n- If GitHub CI is still queued but the exact changed content passed Testbox\n  `pnpm check:changed`, `pnpm check:test-types`, and the real E2E proof, it is\n  reasonable to merge once required checks allow it. Note any still-running\n  unrelated shards in the proof comment instead of waiting forever.\n\nInteractive CLI/onboarding:\n\n- For full-screen or prompt-heavy CLI flows, run the target command inside tmux\n  on the Crabbox and drive it with `tmux send-keys`; capture proof with\n  `tmux capture-pane`, redacted through `sed`.\n- Prefer deterministic arrow navigation over search typing for Clack-style\n  searchable selects. Raw `send-keys -l openai` may not trigger filtering in a\n  tmux pane; inspect option order locally or on-box and send exact Down/Enter\n  sequences.\n- Isolate mutable state with `OPENCLAW_STATE_DIR=$(mktemp -d)`. Plugin npm\n  installs live under that state dir (`npm/node_modules/...`), not under\n  `OPENCLAW_CONFIG_DIR`. Verify downloads by checking the state dir, package\n  lock, and installed package metadata.\n- To test automatic setup installs against local package artifacts, use\n  `OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1` plus\n  `OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{\"plugin-id\":\"npm-pack:/tmp/plugin.tgz\"}'`.\n  Pack with `npm pack`, set an isolated `OPENCLAW_STATE_DIR`, and verify the\n  package under `npm/node_modules`. Overrides are test-only and must not be\n  treated as official/trusted-source installs.\n- For OpenAI/Codex onboarding proof, the useful markers are the UI line\n  `Installed Codex plugin`, `npm/node_modules/@openclaw/codex`, and the\n  package-lock entry showing the bundled `@openai/codex` dependency. A dummy\n  OpenAI-shaped key can prove only UI/install behavior; it is not live auth.\n\n## Reuse And Keepalive\n\nFor most Crabbox calls, one-shot is enough. Use reuse only when you need\nmultiple manual commands on the same hydrated box.\n\nThe examples below assume the lease came from the still-current resolved\nconfiguration. For a lease created through an explicit provider override, add\n`--provider <reported-provider>` to every reuse, inspection, and cleanup command\ninstead of relying on the id to recover its backend.\n\nIf Crabbox returns a reusable id or you intentionally keep a lease:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --no-sync --timing-json --shell -- \"pnpm test <path>\"\n```\n\nStop boxes you created before handoff:\n\n```sh\n../crabbox/bin/crabbox stop <id-or-slug>\nblacksmith testbox stop --id <tbx_id>\n```\n\n## Interactive Desktop And WebVNC\n\nBefore using WebVNC, confirm the resolved provider supports both desktop and a\ncoordinator-backed WebVNC lease, and that broker login is configured. Crabbox\n0.39 WebVNC supports coordinator-backed Hetzner, AWS, and Azure desktop leases;\nthis capability list does not establish a provider preference. If the resolved\nprovider lacks WebVNC, do not switch providers: use native `crabbox vnc` on the\nsame provider when it supports that path, or report the capability blocker.\n\nWhen those preconditions hold, prefer WebVNC for human inspection because the\nbrowser portal can preload the lease VNC password and avoids a native VNC\nclient's copy/paste/password dance. Use native `crabbox vnc` when the browser\nportal is unavailable or broken, or the user explicitly wants a local VNC\nclient.\n\nCommon desktop flow:\n\n```sh\n../crabbox/bin/crabbox warmup --desktop --browser --idle-timeout 60m --ttl 240m\n../crabbox/bin/crabbox desktop launch --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open --take-control\n```\n\nUseful WebVNC commands:\n\n```sh\n../crabbox/bin/crabbox webvnc --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon start --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc daemon stop --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc reset --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox desktop doctor --id <cbx_id-or-slug>\n../crabbox/bin/crabbox desktop click --id <cbx_id-or-slug> --x 640 --y 420\n../crabbox/bin/crabbox desktop paste --id <cbx_id-or-slug> --text \"user@example.com\"\n../crabbox/bin/crabbox desktop key --id <cbx_id-or-slug> ctrl+l\n../crabbox/bin/crabbox artifacts collect --id <cbx_id-or-slug> --all --output artifacts/<slug>\n../crabbox/bin/crabbox artifacts publish --dir artifacts/<slug> --pr <number>\n```\n\n`desktop launch --webvnc --open` is usually the nicest one-shot: it starts the\nbrowser/app inside the visible session, bridges the lease into the authenticated\nWebVNC portal, and opens the portal. Keep browsers windowed for human QA; use\n`--fullscreen` only for capture/video workflows.\nFor human handoff, include `--take-control` so the opened portal viewer gets\nkeyboard/mouse control automatically instead of landing as an observer.\n\nHuman handoff preflight:\n\n- Do not assume a visible desktop or launched browser means the repo CLI/app is\n  installed, built, or on the interactive terminal's `PATH`.\n- Before handing WebVNC to a human tester, prove the expected command from the\n  same kept lease and from a neutral directory such as `~`.\n- If the handoff needs repo-local code, sync/build/link it explicitly on that\n  lease. Source-tree CLIs often need build output before a symlink works.\n- Prefer a real `command -v <expected-command> && <expected-command> --version`\n  check over a repo-root-only `pnpm ...` command.\n\nGeneric handoff repair pattern:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --full-resync --shell -- \\\n  \"set -euo pipefail\n   pnpm install --frozen-lockfile\n   pnpm build\n   sudo ln -sf \\\"\\$PWD/<cli-entry>\\\" /usr/local/bin/<expected-command>\n   cd ~\n   command -v <expected-command>\n   <expected-command> --version\"\n```\n\n## If Crabbox Fails\n\nKeep the fallback narrow. First decide whether the failure is Crabbox itself,\nthe brokered AWS lease, Blacksmith/Testbox, repo hydration, sync, or the test\ncommand.\n\nFast checks:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,140p'\n../crabbox/bin/crabbox doctor\ncommand -v blacksmith\nblacksmith --version\nblacksmith testbox list\n```\n\nCommon Crabbox-only failures:\n\n- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling\n  repo, or update/install Crabbox before retrying.\n- Local-container hydration rejects a configured Actions `uses` step: stay on\n  `provider=local-container`, add `--no-hydrate`, and perform the required\n  dependency setup inside the container command. For example:\n\n  ```sh\n  ../crabbox/bin/crabbox run --no-hydrate --timing-json --shell -- \\\n    \"corepack enable && pnpm install --frozen-lockfile && <check-command>\"\n  ```\n\n  This is a hydration transport workaround, not permission to run the broad\n  check on the host or silently select a remote provider.\n- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and\n  `crabbox whoami`; preserve the resolved provider unless the user explicitly\n  requests another backend.\n- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot\n  without `--id`.\n- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the\n  printed Actions URL. Large sync warnings now include top source directories\n  by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect\n  those before reaching for `--force-sync-large`. Quiet rsync watchdogs and SSH\n  timeouts now print `next_action=` hints; follow them, usually `--full-resync`\n  first and a fresh lease second.\n- Cleanup uncertainty: run `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  only boxes you created.\n- Testbox queued/capacity pressure: do not retry repeatedly or switch providers.\n  Report the blocker and preserve the resolved provider.\n\nIf the resolved direct provider cannot dispatch, sync, attach, or stop, retry\nonce with `--debug` and `--timing-json` without changing providers:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\n```\n\nAuth fallback, only when `blacksmith` says auth is missing:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\nRaw Blacksmith footguns:\n\n- Run from repo root. The CLI syncs the current directory.\n- Save the returned `tbx_...` id in the session.\n- Reuse that id for focused reruns; stop it before handoff.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable\n  queue.\n\nIf the selected Blacksmith backend is down or quota-limited, do not keep probing\nit or switch providers. Report the delegated-provider outage.\n\n## Blacksmith Backend Notes\n\nCrabbox Blacksmith backend delegates setup to:\n\n- the organization reported by `crabbox config show`\n- a Testbox-capable `blacksmith.workflow` or `actions.workflow` in the target\n  repository\n- `blacksmith.job` / `blacksmith.ref`, with `actions.job` / `actions.ref`\n  fallbacks\n\nThe hydration workflow owns checkout, Node/pnpm setup, dependency install,\nsecrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command\nexecution, timing, logs/results, and cleanup.\n\nMinimal configured Blacksmith-backed Crabbox run, from repo root. Do not use\nthis fresh-run form until the effective workflow is present and verified as\nTestbox-capable; supply the explicit user-provided workflow above or reuse an\nexisting Testbox id instead.\n\n```sh\n../crabbox/bin/crabbox run --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed\n```\n\nUse direct Blacksmith only when Crabbox is the broken layer and you are\nisolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup\ndiagnostics, not as a reusable work queue.\n\nImportant Blacksmith footguns:\n\n- Always run from repo root. The CLI syncs the current directory.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- If auth is missing and browser auth is acceptable:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\n## Brokered AWS\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects AWS. Do not infer AWS from an omitted `--provider`.\n\nConfirm the selection first:\n\n```sh\ncrabbox config show\ncrabbox doctor\n```\n\nFor Linux, the repository configuration supplies the broker URL, developer\nimage, `eu-west-1` default region, capacity-region candidates, and\nspot-to-on-demand capacity policy. Do not repeat those values on every command;\nthe resolved configuration remains the source of truth. For native Windows,\nuse the `us-west-2` on-demand command in \"macOS And Windows Targets\" above. For\nbrokered macOS, complete the quota/IAM and no-spend Dedicated Host preflight in\nthat section before allocation. If the user explicitly selects AWS over a\ndifferent resolved provider, add `--provider aws` to the AWS commands below.\n\n```sh\n../crabbox/bin/crabbox warmup --idle-timeout 90m\n../crabbox/bin/crabbox actions hydrate --id <cbx_id-or-slug>\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --timing-json --shell -- \"env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n../crabbox/bin/crabbox stop <cbx_id-or-slug>\n```\n\nInstall/auth for owned Crabbox if needed. When configuration already resolves\nAWS and only broker auth is missing, omit `--provider` so login writes the token\nwithout changing provider selection:\n\n```sh\nbrew install openclaw/tap/crabbox\ncrabbox login --url https://crabbox.openclaw.ai\n```\n\nIf the user explicitly wants AWS as their persisted user-config default, use\n`crabbox login --url https://crabbox.openclaw.ai --provider aws`. The provider\nflag writes both broker auth and `provider=aws`; it is a configuration change,\nnot merely credential scoping. Repository config or `CRABBOX_PROVIDER` may\nstill take higher precedence, so confirm the effective result with\n`crabbox config show` in the target worktree.\n\nNew users should self-resolve broker auth before anyone asks for AWS keys:\n\n```sh\ncrabbox config show\ncrabbox doctor\ncrabbox whoami\n```\n\n- If broker auth is missing, run `crabbox login --url https://crabbox.openclaw.ai`.\n  Add `--provider aws` only when the user also wants to persist AWS as their\n  user-config default.\n- If the CLI asks for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS\n  profile setup during normal OpenClaw validation, assume the agent selected\n  the wrong path. Use brokered `crabbox login` or an existing brokered lease\n  before asking the user for cloud credentials.\n- Ask for AWS keys only for explicit direct-provider/account administration,\n  not for normal brokered OpenClaw proof.\n- Trusted automation that intentionally persists AWS as its default may use\n  `printf '%s' \"$CRABBOX_COORDINATOR_TOKEN\" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin`.\n\nmacOS config lives at:\n\n```text\n~/Library/Application Support/crabbox/config.yaml\n```\n\nIt should include `broker.url` and `broker.token` for AWS lanes. Let the resolved\nconfig select the backend; override it only when the user explicitly requests a\ndifferent provider.\n\n### Interactive Desktop / WebVNC\n\nFor human desktop demos, prefer `webvnc` over native `vnc` and keep the remote\ndesktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE\npanel/window chrome unless the explicit goal is video/capture output. After\nlaunch, verify a screenshot shows the desktop panel plus browser title bar. If\nChrome is fullscreen, toggle it back with:\n\n```sh\ncrabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11'\n```\n\n## Diagnostics\n\n```sh\ncrabbox status --id <id-or-slug> --wait\ncrabbox inspect --id <id-or-slug> --json\ncrabbox sync-plan\ncrabbox history --limit 20\ncrabbox history --lease <id-or-slug>\ncrabbox attach <run_id>\ncrabbox events <run_id> --json\ncrabbox logs <run_id>\ncrabbox results <run_id>\ncrabbox cache stats --id <id-or-slug>\ncrabbox ssh --id <id-or-slug>\nblacksmith testbox list\n```\n\nUse `--debug` on `run` when measuring sync timing.\nUse `--timing-json` on warmup, hydrate, and run when comparing backends.\nUse `--market spot|on-demand` only on AWS warmup/one-shot runs.\n\n## Failure Triage\n\n- Crabbox cannot find provider: verify `../crabbox/bin/crabbox --help` lists\n  the provider selected by `.crabbox.yaml`; update Crabbox before falling back.\n- Hydration stuck or failed: open the printed GitHub Actions run URL and inspect\n  the hydration step.\n- Sync failed: rerun with `--debug`; check changed-file count and whether the\n  checkout is dirty.\n- Command failed: rerun only the failing shard/file first. Do not rerun a full\n  suite until the focused failure is understood.\n- Cleanup uncertain: `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  owned `tbx_...` leases you created.\n- Selected provider broken: report the provider-specific blocker; do not switch\n  providers unless the user explicitly requests the fallback.\n\n## Boundary\n\nDo not add OpenClaw-specific setup to Crabbox itself. Put repo setup in the\nhydration workflow and keep Crabbox generic around lease, sync, command\nexecution, logs/results, timing, and cleanup.\n",".agents/skills/local-clawsweeper-review/SKILL.md":"---\nname: local-clawsweeper-review\ndescription: Run local ClawSweeper exact-item or committed-range reviews without GitHub mutation.\n---\n\n# Local ClawSweeper Review\n\nUse this skill when someone wants read-only local ClawSweeper output before\nsubmitting, updating, or re-reviewing an issue or PR.\n\n## Safety Boundary\n\n- Run only `pnpm run review -- --local-only` for an existing GitHub item, or\n  `pnpm run review -- --local-range` for a pre-submission committed range.\n- Do not run `apply-artifacts`, `apply-decisions`, GitHub comment posting, or\n  merge/autofix commands unless the user explicitly asks for that mutation.\n- Do not print `OPENAI_API_KEY`, `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN`, GitHub\n  tokens, or Codex auth material.\n- Treat generated review artifacts as local proof. Do not claim ClawSweeper\n  posted or synced anything unless a separate explicit mutation command did it.\n\n## Locate ClawSweeper\n\nPrefer the current repository when its `package.json` name is\n`@openclaw/clawsweeper`. Otherwise use a known clean local checkout:\n\n- Windows: `C:\\oc-work\\clawsweeper-source`\n- POSIX fallback: `~/Projects/clawsweeper`\n\nInspect `git status --short` before making changes. If another ClawSweeper clone\nis dirty or ambiguous, do not use it for the local review runner.\n\n## First-Time Setup\n\nFrom the ClawSweeper checkout:\n\n```sh\ncorepack enable\npnpm install\npnpm run build:all\npnpm run codex:local:check -- --diagnostics\n```\n\nThe diagnostics mode checks the selected Codex binary and login status without\na model request. It does not prove model access or review readiness. Omit\n`--diagnostics` for the existing model smoke test, which consumes model usage.\n\nIf the Codex check says the CLI is not logged in, have the operator authenticate\ntheir own Codex CLI. Device auth is the simplest shareable setup:\n\n```sh\ncodex login --device-auth -c 'service_tier=\"fast\"'\n```\n\nFor API-key setup, pass the key through the shell only for the login command and\nthen clear it from the environment. Do not put the key in docs, scripts, shell\nhistory, or committed files.\n\nPowerShell:\n\n```powershell\n$env:OPENAI_API_KEY = Read-Host \"OpenAI API key\"\n$env:OPENAI_API_KEY | codex login --with-api-key -c 'service_tier=\"fast\"'\nRemove-Item Env:OPENAI_API_KEY\n```\n\nPOSIX shell:\n\n```sh\nprintf '%s' \"$OPENAI_API_KEY\" | codex login --with-api-key -c 'service_tier=\"fast\"'\nunset OPENAI_API_KEY\n```\n\nIf the wrong Codex binary is used, set `CODEX_BIN` in the local shell for that\nrun. Otherwise, `--local-only` uses the first spawnable `codex` command on\n`PATH`, including on Windows. If no Windows PATH command is spawnable, it falls\nback to the installed Codex Desktop binary.\n\n## Target Checkout Modes\n\nBy default, an exact local PR review manages its own target checkout under\n`artifacts/local-review-<pr-number>/target`.\n\nBy default, `--local-range` reviews the clean checkout where the command was\ninvoked. It does not manage or switch that checkout. Pass `--target-dir` when\nthe branch to review is elsewhere.\n\nIn a built source checkout, `node dist/clawsweeper-local.js review` is the\nlocal-only entrypoint for the same full committed-range engine. Its `--help`\nand `--version` paths do not load the review engine or invoke Codex. It does not\nprovide diagnostics yet; `codex:local:check` remains the existing model smoke\ntest. This entrypoint does not publish hosted action-ledger or cache metadata.\n\nPass `--target-dir` when the operator wants to review an existing checkout or\nan issue.\n\nUse a clean target checkout of the repository being reviewed. Prefer a dedicated\nreview checkout if the normal worktree is dirty:\n\n- Windows: `C:\\oc-work\\clawsweeper-local-target-openclaw`\n- POSIX fallback: `../openclaw`\n\nBefore reviewing against `main`, update the target checkout only when it is\nclean:\n\n```sh\ngit -C <target-dir> status --short\ngit -C <target-dir> fetch origin main\ngit -C <target-dir> switch main\ngit -C <target-dir> pull --ff-only origin main\n```\n\nDo not switch branches, pull, or overwrite files in a dirty target checkout.\n\n## Run A Local Review\n\nUse the exact issue or PR number. If the number is not provided and the current\nbranch has an open PR, use `gh pr view --json number,url,headRefOid` to identify\nit.\n\nFrom the ClawSweeper checkout:\n\n```sh\npnpm run review -- --local-only --item-number <pr-number>\n```\n\nTo use a supplied checkout or review an issue:\n\n```sh\npnpm run review -- --local-only \\\n  --item-number <issue-or-pr-number> \\\n  --target-dir <target-dir>\n```\n\nTo review committed branch work before a PR exists:\n\n```sh\npnpm run review -- --local-range \\\n  --target-repo <owner/repo> \\\n  --base origin/main\n```\n\nThe range is `merge-base(<base>, HEAD)..HEAD`. It must be clean and contain at\nleast one commit beyond the base. This path withholds GitHub credentials,\nisolates cached `gh` auth, disables web search, and skips host-side URL/media\npreprocessing. It still calls the configured Codex model service; do not call it\nair-gapped or fully network-offline.\n\nThe exact local command prints a human-readable progress summary by default. Add\n`--verbose` only when debugging checkout, selection, or Codex process details.\n\nFor quick smoke tests, lower `--batch-size`, `--shard-count`, `--max-pages`, and\n`--codex-timeout-ms`, but label the result as a smoke run rather than a full\nlocal review.\n\n## Read The Artifact\n\nThe default OpenClaw report is written to:\n\n```text\n<artifact-dir>/<issue-or-pr-number>.md\n```\n\nRead the artifact and summarize:\n\n- `review_status`\n- `main_sha`\n- `pull_head_sha` for PRs\n- decision/confidence/action fields when present\n- findings or blockers\n- exact Codex/auth/runtime failure if the run failed\n\nIf the failure is Codex auth, stop after providing the local setup command. If\nthe failure is runner/runtime behavior, include the artifact path and a concise\nstderr or log summary.\n\n## Closeout\n\nBefore reporting success:\n\n- Confirm the command used `review --local-only` or `review --local-range`.\n- Confirm no GitHub comments, labels, merges, or apply commands were run.\n- Confirm the target checkout is still clean.\n- If findings exist, list the actionable items and the next local fix/test step.\n- If no blockers exist, say the local ClawSweeper artifact found no blockers\n  and include the reviewed `main_sha` and PR head SHA when available.\n",".agents/skills/local-clawsweeper-review/agents/openai.yaml":"interface:\n  display_name: \"Local ClawSweeper Review\"\n  short_description: \"Run local ClawSweeper before PRs\"\n  default_prompt: \"Use $local-clawsweeper-review to run a local ClawSweeper review before I submit a PR.\"\n","AGENTS.md":"# AGENTS.MD\n\nClawSweeper is the conservative maintenance bot for OpenClaw repositories.\nKeep changes narrow, evidence-backed, and automation-safe.\n\n`AGENTS.md` is the canonical repository-wide coding-agent policy. Task-specific\nworkflows under `.agents/skills/` are opt-in procedures and do not override this\nfile. This repository does not currently maintain `AGENT.md`, `CLAUDE.md`, or\nCursor aliases; agents that do not discover `AGENTS.md` automatically must be\ndirected here rather than given a duplicated policy copy.\n\n## Structure\n\n- Main code: `src/clawsweeper.ts`.\n- Repair lane code: `src/repair/`; canonical records live in the Cloudflare\n  Worker, ledger/assets blobs live in R2, and remaining operational state lives\n  in `openclaw/clawsweeper-state`.\n- Tests: `test/*.test.ts` and `test/repair/*.test.ts`; add new coverage to the\n  narrowest matching test file instead of growing `test/clawsweeper.test.ts`.\n- Workflow: `.github/workflows/sweep.yml`.\n- Vision and product boundaries: `VISION.md`.\n- Explainer: `README.md`; state/dashboard repo: `../clawsweeper-state`.\n- Changelog: one-bullet fragments in `changelog.d/`, stitched into\n  `CHANGELOG.md` at release time; see\n  [`changelog.d/README.md`](changelog.d/README.md).\n- Open/reviewed records in the canonical Worker store:\n  `records/<repo-slug>/items/<number>.md`.\n- Archived records in the canonical Worker store:\n  `records/<repo-slug>/closed/<number>.md`.\n- Scratch/generated output: `.artifacts/`, `artifacts/`, `apply-report.json`.\n\nPreserve one flat `items/` and `closed/` report layout per repository slug. Do\nnot split reports into issue/PR subtrees.\n\n## Operating Model\n\n- Review lane is proposal-only. It never closes GitHub items.\n- Ordinary PRs receive one automatic completed review after ten quiet minutes.\n  Later pushes, edits, reopen events, and scheduled passes require a new explicit\n  review request. Failed or stale-source attempts can finish the first review.\n  `clawsweeper:autofix` and `clawsweeper:automerge` no longer change review\n  admission; they only keep their close protection.\n- Maintainer-authored items and items labeled `maintainer` created from\n  2026-10-15 03:50 UTC are reviewed like everyone else's: a PR gets its one\n  automatic review. Older maintainer items need an explicit `@clawsweeper review`\n  request.\n  Finish the work and validation first; request review only when it is needed.\n  Agents must not request reviews automatically or repeat a queued/running request.\n  An explicit review request stays open while the queue requeues its own review\n  after source drift, in place or from the publisher still holding the request's\n  publication; that retry continues the request. A finished or replaced\n  request, later changes after the answer, and scheduled passes need a new\n  request.\n- Apply lane mutates GitHub by syncing the durable Codex review comment and then\n  closing only unchanged, high-confidence proposals.\n- Repository-specific rules live in `src/repository-profiles.ts`; ClawHub apply\n  may close only PRs that are certainly implemented on `main`.\n- Hosted review concurrency and batching belong to the shared exact-review\n  queue. Broad sweeps only admit candidates; they do not start per-run shards\n  or grant immediate-apply authority.\n- `openclaw/clawsweeper-state` is the live status surface and operational state\n  store; the Worker/R2 pair is authoritative for records, ledger, and assets.\n  Check current Actions and the canonical owner before trusting local generated\n  timestamps.\n- When asked about PRs outside `openclaw/clawsweeper`, treat the task as\n  monitoring/debugging how ClawSweeper workflows operate on that PR. Do not fix\n  foreign PR branches directly; ClawSweeper repair/automerge workflows own those\n  branch edits.\n- In `openclaw/openclaw`, `CHANGELOG.md` is release-owned. Do not ask contributor\n  PR authors, repair workers, or automerge/autofix lanes to edit it during normal\n  PR work. Preserve release-note context in PR bodies and commit messages instead.\n- In `openclaw/clawsweeper` itself, record a user-visible change as one new\n  `changelog.d/<pr-or-slug>.md` fragment holding a single bullet line. Do not\n  edit `CHANGELOG.md` or other PRs' fragments in normal PR work; the release\n  maintainer folds fragments in with `pnpm run changelog:stitch`, and\n  `pnpm run check:changelog` validates them.\n- When referencing GitHub issues or PRs in user-facing output, always include\n  the full GitHub URL, not only `#12345`.\n\n## Safety Rules\n\n- Never disable or pause the live ClawSweeper sweep workflow unless Peter\n  explicitly asks for that exact action.\n- Do not run live apply/close commands unless Peter explicitly asks.\n- For apply-path repros, copy one report into a temp `items/` dir and pass\n  `--skip-dashboard`, `--item-number`, and a temp `--closed-dir`.\n- Treat maintainer-authored and protected-label items as non-closeable, except\n  for `implemented_on_main` with its existing\n  source/history/release evidence and fresh apply guards (PRs additionally need\n  GitHub-verified merged same-repository fixing provenance and paired-issue\n  relationship checks; see `docs/implemented-on-main-close-policy.md`), and\n  the maintainer-approved metadata-only `oversized_pull_request` policy:\n  drafts, maintainer authorship, and the `maintainer` label do not exempt that\n  reason. Its explicit PR exemption labels, `size: accepted-large`, other\n  protected labels, live freshness checks, and apply gates still apply.\n- Leave canonical OpenClaw Mantis locale PRs open; their generated-PR publisher\n  owns freshness and auto-merge. See `docs/target-repositories.md` for identity scope.\n- Snapshot or `updated_at` drift blocks apply unless the only change is the\n  existing ClawSweeper review comment, or a ClawSweeper-recorded write for the\n  item (`docs/scheduler.md`) while the complete source/timeline/head/activity\n  receipt matches and no non-automation activity follows the review snapshot.\n- Open-but-locked issues can exist when stale automation locked a closed issue\n  and the author later reopened it. These must be skipped, not allowed to crash\n  the apply run.\n- Locked-comment 403s from GitHub are terminal apply skips, not retryable API\n  failures.\n\n## PR Validation and Landing\n\n- For code-bearing changes, run focused validation that exercises the changed\n  behavior, commit the final candidate, then obtain a fresh Codex review of the\n  entire committed branch against a pinned intended base. Require a clean index\n  and working tree; review the merge-base-to-HEAD range, not only the last commit.\n  Complete this review before publication, handoff, or landing, including direct\n  pushes where otherwise permitted. Early local review is optional feedback and\n  does not replace this final branch review. See `CONTRIBUTING.md` for the command.\n- Address every accepted or actionable finding and repeat the affected proof and\n  review after fixes. A changed head, parent or selected base/range, dirty source,\n  post-review hook edits, or changed review evidence, context, or applicable policy\n  invalidates the affected review. Verify the final source after hooks and before\n  publication or handoff. A failed or incomplete review never falls back to an\n  earlier clean result; repeat review when needed, not merely to obtain a nicer\n  verdict. An unchanged Git tree alone does not establish equivalent review inputs.\n  CI, an older ClawSweeper comment, prior review comments, or manual self-review\n  alone do not replace this loop or the separate gates below.\n- At task kickoff, define the `pr-behavior-proof` contract for every\n  code-bearing PR: claim, exercised surface, scenario or fixture, command and\n  environment, observable result, artifact or trace, and limits. Run its\n  controlled real-behavior proof before opening even a draft PR; only Martin\n  may expressly approve an evidence-in-progress exception.\n- Keep that proof current in the PR body. Tests, CI, mocks, snapshots, lint,\n  typechecks, and clean review support the claim but never replace proof of a\n  changed runtime, workflow, queue, API, UI, package, or integration path. On\n  this Windows host, proof for those surfaces uses Docker-backed Crabbox\n  `local-container` and records the current head, provider, image, lease,\n  artifact, and limits. Use the narrowest meaningful proof first and broaden\n  it for shared or higher-risk behavior. Docs-only changes normally need\n  `git diff --check` and relevant link or command sanity instead.\n- The public dashboard is observer-only: it may display status and provide\n  view-only navigation to verified-public GitHub repository, item, workflow-run,\n  and job pages. Those canonical GET links are references, not action controls.\n  It never calls GitHub from the browser and never triggers or offers queue,\n  workflow, GitHub, DLQ, recovery, deploy, rollback, or other mutation controls.\n- A ClawSweeper result that requires proof or identifies an accepted/actionable\n  finding remains PR-owner work, not a handoff. Before a manually requested\n  review or re-review, put current proof and the finding disposition or evidence\n  in the main PR body. A head or review-content body change after the durable review marker\n  makes that review and any affected proof stale: rerun the affected proof and\n  obtain a review for the current head and body. CI, labels, readiness, and\n  maintainer permissions are evidence only; the explicit-user-approval boundary\n  below still controls landing.\n- Before merge or automerge, the latest ClawSweeper review must apply to the\n  current PR head and review-content body. The canonical preflight reader excludes\n  one valid advisory annotation only; human text, proof, and all outside whitespace\n  remain review content. Raw event and concurrency guards can still invalidate\n  after a metadata edit. Resolve every accepted finding. Apply each\n  applicable `Rank-up moves:` item, or explicitly justify the exception in the\n  PR body; Rank-up moves remain optional and do not by themselves block merge.\n  Do not merge while proof is missing or while the review has an unresolved\n  contributor-facing blocker.\n- Land only after the current review and status evidence is ready for\n  maintainer look, including `proof: sufficient` or `proof: override` when the\n  proof label applies. This does not replace the user's explicit merge approval\n  in the current conversation; agents must not merge or enable/execute\n  automerge without it.\n\n## Commands\n\n```bash\ncorepack enable\npnpm install\npnpm run build\npnpm run test:unit\npnpm run format\npnpm run check\n```\n\nUse `pnpm run check` before handoff for code/test/workflow changes.\n\n`engines.node` is `>=24`. Node 22 will install (no `engine-strict`) but the\nnotifier tests' 5-second retry paths surface as `cancelledByParent` under the\nold `node:test` runner. Run on Node 24 or newer before reporting test\nfailures.\n\n## GitHub Checks\n\nUseful live probes:\n\n```bash\ngh run list --repo openclaw/clawsweeper --limit 20 --json databaseId,displayTitle,status,conclusion,createdAt,updatedAt\ngh api repos/openclaw/clawsweeper/readme --jq '.content' | base64 --decode\ngh api graphql -f query='query { repository(owner:\"openclaw\", name:\"openclaw\") { issues(states: OPEN) { totalCount } pullRequests(states: OPEN) { totalCount } } }'\n```\n\nFor throughput/default tuning, start with `config/automation-limits.json` and\n[`docs/limits.md`](docs/limits.md). `scripts/check-limits.ts` identifies the\nderived docs, Worker values, and the `workflow_dispatch` literals that must stay\naligned. Effective exact-review admission, publication, and batching overrides\nlive in `dashboard/wrangler.toml`; owning fallback behavior lives in\n`dashboard/exact-review-queue.ts`. Update `.github/workflows/sweep.yml` or\n`src/clawsweeper.ts` only when the changed contract is actually owned there.\n\nUse [`docs/README.md`](docs/README.md) for the documentation map, lifecycle\nstates, role ownership, and cross-surface update triggers.\n"},"items":[{"name":"AGENTS.md","path":"AGENTS.md","rawUrl":"https://raw.githubusercontent.com/openclaw/clawsweeper/HEAD/AGENTS.md","title":"AI Agent Protocol & Instructions","category":"root-instruction","format":"markdown","content":"# AGENTS.MD\n\nClawSweeper is the conservative maintenance bot for OpenClaw repositories.\nKeep changes narrow, evidence-backed, and automation-safe.\n\n`AGENTS.md` is the canonical repository-wide coding-agent policy. Task-specific\nworkflows under `.agents/skills/` are opt-in procedures and do not override this\nfile. This repository does not currently maintain `AGENT.md`, `CLAUDE.md`, or\nCursor aliases; agents that do not discover `AGENTS.md` automatically must be\ndirected here rather than given a duplicated policy copy.\n\n## Structure\n\n- Main code: `src/clawsweeper.ts`.\n- Repair lane code: `src/repair/`; canonical records live in the Cloudflare\n  Worker, ledger/assets blobs live in R2, and remaining operational state lives\n  in `openclaw/clawsweeper-state`.\n- Tests: `test/*.test.ts` and `test/repair/*.test.ts`; add new coverage to the\n  narrowest matching test file instead of growing `test/clawsweeper.test.ts`.\n- Workflow: `.github/workflows/sweep.yml`.\n- Vision and product boundaries: `VISION.md`.\n- Explainer: `README.md`; state/dashboard repo: `../clawsweeper-state`.\n- Changelog: one-bullet fragments in `changelog.d/`, stitched into\n  `CHANGELOG.md` at release time; see\n  [`changelog.d/README.md`](changelog.d/README.md).\n- Open/reviewed records in the canonical Worker store:\n  `records/<repo-slug>/items/<number>.md`.\n- Archived records in the canonical Worker store:\n  `records/<repo-slug>/closed/<number>.md`.\n- Scratch/generated output: `.artifacts/`, `artifacts/`, `apply-report.json`.\n\nPreserve one flat `items/` and `closed/` report layout per repository slug. Do\nnot split reports into issue/PR subtrees.\n\n## Operating Model\n\n- Review lane is proposal-only. It never closes GitHub items.\n- Ordinary PRs receive one automatic completed review after ten quiet minutes.\n  Later pushes, edits, reopen events, and scheduled passes require a new explicit\n  review request. Failed or stale-source attempts can finish the first review.\n  `clawsweeper:autofix` and `clawsweeper:automerge` no longer change review\n  admission; they only keep their close protection.\n- Maintainer-authored items and items labeled `maintainer` created from\n  2026-10-15 03:50 UTC are reviewed like everyone else's: a PR gets its one\n  automatic review. Older maintainer items need an explicit `@clawsweeper review`\n  request.\n  Finish the work and validation first; request review only when it is needed.\n  Agents must not request reviews automatically or repeat a queued/running request.\n  An explicit review request stays open while the queue requeues its own review\n  after source drift, in place or from the publisher still holding the request's\n  publication; that retry continues the request. A finished or replaced\n  request, later changes after the answer, and scheduled passes need a new\n  request.\n- Apply lane mutates GitHub by syncing the durable Codex review comment and then\n  closing only unchanged, high-confidence proposals.\n- Repository-specific rules live in `src/repository-profiles.ts`; ClawHub apply\n  may close only PRs that are certainly implemented on `main`.\n- Hosted review concurrency and batching belong to the shared exact-review\n  queue. Broad sweeps only admit candidates; they do not start per-run shards\n  or grant immediate-apply authority.\n- `openclaw/clawsweeper-state` is the live status surface and operational state\n  store; the Worker/R2 pair is authoritative for records, ledger, and assets.\n  Check current Actions and the canonical owner before trusting local generated\n  timestamps.\n- When asked about PRs outside `openclaw/clawsweeper`, treat the task as\n  monitoring/debugging how ClawSweeper workflows operate on that PR. Do not fix\n  foreign PR branches directly; ClawSweeper repair/automerge workflows own those\n  branch edits.\n- In `openclaw/openclaw`, `CHANGELOG.md` is release-owned. Do not ask contributor\n  PR authors, repair workers, or automerge/autofix lanes to edit it during normal\n  PR work. Preserve release-note context in PR bodies and commit messages instead.\n- In `openclaw/clawsweeper` itself, record a user-visible change as one new\n  `changelog.d/<pr-or-slug>.md` fragment holding a single bullet line. Do not\n  edit `CHANGELOG.md` or other PRs' fragments in normal PR work; the release\n  maintainer folds fragments in with `pnpm run changelog:stitch`, and\n  `pnpm run check:changelog` validates them.\n- When referencing GitHub issues or PRs in user-facing output, always include\n  the full GitHub URL, not only `#12345`.\n\n## Safety Rules\n\n- Never disable or pause the live ClawSweeper sweep workflow unless Peter\n  explicitly asks for that exact action.\n- Do not run live apply/close commands unless Peter explicitly asks.\n- For apply-path repros, copy one report into a temp `items/` dir and pass\n  `--skip-dashboard`, `--item-number`, and a temp `--closed-dir`.\n- Treat maintainer-authored and protected-label items as non-closeable, except\n  for `implemented_on_main` with its existing\n  source/history/release evidence and fresh apply guards (PRs additionally need\n  GitHub-verified merged same-repository fixing provenance and paired-issue\n  relationship checks; see `docs/implemented-on-main-close-policy.md`), and\n  the maintainer-approved metadata-only `oversized_pull_request` policy:\n  drafts, maintainer authorship, and the `maintainer` label do not exempt that\n  reason. Its explicit PR exemption labels, `size: accepted-large`, other\n  protected labels, live freshness checks, and apply gates still apply.\n- Leave canonical OpenClaw Mantis locale PRs open; their generated-PR publisher\n  owns freshness and auto-merge. See `docs/target-repositories.md` for identity scope.\n- Snapshot or `updated_at` drift blocks apply unless the only change is the\n  existing ClawSweeper review comment, or a ClawSweeper-recorded write for the\n  item (`docs/scheduler.md`) while the complete source/timeline/head/activity\n  receipt matches and no non-automation activity follows the review snapshot.\n- Open-but-locked issues can exist when stale automation locked a closed issue\n  and the author later reopened it. These must be skipped, not allowed to crash\n  the apply run.\n- Locked-comment 403s from GitHub are terminal apply skips, not retryable API\n  failures.\n\n## PR Validation and Landing\n\n- For code-bearing changes, run focused validation that exercises the changed\n  behavior, commit the final candidate, then obtain a fresh Codex review of the\n  entire committed branch against a pinned intended base. Require a clean index\n  and working tree; review the merge-base-to-HEAD range, not only the last commit.\n  Complete this review before publication, handoff, or landing, including direct\n  pushes where otherwise permitted. Early local review is optional feedback and\n  does not replace this final branch review. See `CONTRIBUTING.md` for the command.\n- Address every accepted or actionable finding and repeat the affected proof and\n  review after fixes. A changed head, parent or selected base/range, dirty source,\n  post-review hook edits, or changed review evidence, context, or applicable policy\n  invalidates the affected review. Verify the final source after hooks and before\n  publication or handoff. A failed or incomplete review never falls back to an\n  earlier clean result; repeat review when needed, not merely to obtain a nicer\n  verdict. An unchanged Git tree alone does not establish equivalent review inputs.\n  CI, an older ClawSweeper comment, prior review comments, or manual self-review\n  alone do not replace this loop or the separate gates below.\n- At task kickoff, define the `pr-behavior-proof` contract for every\n  code-bearing PR: claim, exercised surface, scenario or fixture, command and\n  environment, observable result, artifact or trace, and limits. Run its\n  controlled real-behavior proof before opening even a draft PR; only Martin\n  may expressly approve an evidence-in-progress exception.\n- Keep that proof current in the PR body. Tests, CI, mocks, snapshots, lint,\n  typechecks, and clean review support the claim but never replace proof of a\n  changed runtime, workflow, queue, API, UI, package, or integration path. On\n  this Windows host, proof for those surfaces uses Docker-backed Crabbox\n  `local-container` and records the current head, provider, image, lease,\n  artifact, and limits. Use the narrowest meaningful proof first and broaden\n  it for shared or higher-risk behavior. Docs-only changes normally need\n  `git diff --check` and relevant link or command sanity instead.\n- The public dashboard is observer-only: it may display status and provide\n  view-only navigation to verified-public GitHub repository, item, workflow-run,\n  and job pages. Those canonical GET links are references, not action controls.\n  It never calls GitHub from the browser and never triggers or offers queue,\n  workflow, GitHub, DLQ, recovery, deploy, rollback, or other mutation controls.\n- A ClawSweeper result that requires proof or identifies an accepted/actionable\n  finding remains PR-owner work, not a handoff. Before a manually requested\n  review or re-review, put current proof and the finding disposition or evidence\n  in the main PR body. A head or review-content body change after the durable review marker\n  makes that review and any affected proof stale: rerun the affected proof and\n  obtain a review for the current head and body. CI, labels, readiness, and\n  maintainer permissions are evidence only; the explicit-user-approval boundary\n  below still controls landing.\n- Before merge or automerge, the latest ClawSweeper review must apply to the\n  current PR head and review-content body. The canonical preflight reader excludes\n  one valid advisory annotation only; human text, proof, and all outside whitespace\n  remain review content. Raw event and concurrency guards can still invalidate\n  after a metadata edit. Resolve every accepted finding. Apply each\n  applicable `Rank-up moves:` item, or explicitly justify the exception in the\n  PR body; Rank-up moves remain optional and do not by themselves block merge.\n  Do not merge while proof is missing or while the review has an unresolved\n  contributor-facing blocker.\n- Land only after the current review and status evidence is ready for\n  maintainer look, including `proof: sufficient` or `proof: override` when the\n  proof label applies. This does not replace the user's explicit merge approval\n  in the current conversation; agents must not merge or enable/execute\n  automerge without it.\n\n## Commands\n\n```bash\ncorepack enable\npnpm install\npnpm run build\npnpm run test:unit\npnpm run format\npnpm run check\n```\n\nUse `pnpm run check` before handoff for code/test/workflow changes.\n\n`engines.node` is `>=24`. Node 22 will install (no `engine-strict`) but the\nnotifier tests' 5-second retry paths surface as `cancelledByParent` under the\nold `node:test` runner. Run on Node 24 or newer before reporting test\nfailures.\n\n## GitHub Checks\n\nUseful live probes:\n\n```bash\ngh run list --repo openclaw/clawsweeper --limit 20 --json databaseId,displayTitle,status,conclusion,createdAt,updatedAt\ngh api repos/openclaw/clawsweeper/readme --jq '.content' | base64 --decode\ngh api graphql -f query='query { repository(owner:\"openclaw\", name:\"openclaw\") { issues(states: OPEN) { totalCount } pullRequests(states: OPEN) { totalCount } } }'\n```\n\nFor throughput/default tuning, start with `config/automation-limits.json` and\n[`docs/limits.md`](docs/limits.md). `scripts/check-limits.ts` identifies the\nderived docs, Worker values, and the `workflow_dispatch` literals that must stay\naligned. Effective exact-review admission, publication, and batching overrides\nlive in `dashboard/wrangler.toml`; owning fallback behavior lives in\n`dashboard/exact-review-queue.ts`. Update `.github/workflows/sweep.yml` or\n`src/clawsweeper.ts` only when the changed contract is actually owned there.\n\nUse [`docs/README.md`](docs/README.md) for the documentation map, lifecycle\nstates, role ownership, and cross-surface update triggers.\n","isInternal":false,"tokens":2741,"sizeBytes":11972},{"name":"SKILL.md","path":".agents/skills/crabbox/SKILL.md","rawUrl":"https://raw.githubusercontent.com/openclaw/clawsweeper/HEAD/.agents/skills/crabbox/SKILL.md","title":"crabbox","category":"anthropic-skill","format":"markdown","content":"---\nname: crabbox\ndescription: Use the Crabbox wrapper for validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id.\n---\n\n# Crabbox\n\n## Provider Selection Contract\n\nProvider selection is configuration resolution, not testing policy. Run\n`crabbox config show` from the exact worktree being tested; a session may have\nstarted in another checkout whose repository config or skill text is stale. A\nrequest to \"use Crabbox\" does not authorize a provider override. When the user\ndoes not name a backend, omit `--provider` and preserve the resolved provider,\nincluding values supplied by user config or `CRABBOX_PROVIDER`.\n\nTest scope, expected duration, and hydration failures do not select a provider.\nOverride the resolved provider only when the user explicitly names a different\nbackend. If that provider cannot perform the requested test, report the blocker\ninstead of silently selecting another backend.\n\nUse the Crabbox wrapper for validation execution, environment lifecycle, sync,\nlogs/results, cache inspection, and lease cleanup.\n\nCrabbox is the transport/orchestration surface. The actual backend can be:\n\n- local Docker isolation: `provider=local-container`, lease ids like `cbx_...`\n- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like\n  `cbx_...`, `syncDelegated=false`\n- Blacksmith Testbox through Crabbox: delegated provider,\n  `provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`\n\nThe provider-specific sections below document capabilities and commands after\nconfiguration or an explicit user request has selected a backend. They are not\nprovider-selection policy. Their validation commands intentionally omit\n`--provider`; add it only to carry out an explicit user override of the resolved\nconfiguration.\n\nProvider identity must remain attached to a lease after creation. A lease\ncreated through the resolved configuration can keep using provider-neutral\ncommands while that configuration is unchanged. If the user explicitly\noverrode the provider, or the resolved configuration has changed since the\nlease was created, pass the provider reported by Crabbox to every later command\nthat targets that lease, including hydrate, rerun, desktop/WebVNC, status,\ninspect, SSH, and stop. This preserves resource identity; it does not select a\nprovider for unrelated work.\n\nWhen the resolved configuration selects Blacksmith Testbox, or the user\nexplicitly requests it, do not describe the run as \"AWS Crabbox\". Report it as\nTestbox-through-Crabbox with the `tbx_...` id and Actions run.\n\nDirect AWS supports persistent leases, `--fresh-pr`, `--full-resync`,\nenvironment forwarding, capture/download, and provider-comparison workflows.\nBlacksmith Testbox provides a prepared CI environment and delegated broad/heavy\n`pnpm` gates. These capabilities do not override the resolved configuration.\n\n## First Checks\n\n- Run from the repo root. Crabbox sync mirrors the current checkout.\n- Check the wrapper and providers before Crabbox work:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,120p'\n../crabbox/bin/crabbox desktop launch --help\n../crabbox/bin/crabbox webvnc --help\n```\n\n- OpenClaw scripts prefer `../crabbox/bin/crabbox` when present. The user PATH\n  shim can be stale.\n- Read `.crabbox.yaml`, then run `crabbox config show` from the repository root\n  before selecting a provider. The resolved provider can come from the user's\n  Crabbox config or environment as well as the repository file.\n- Omitting `--provider` means \"use the resolved configuration\". Pass it only\n  when the user explicitly requests a different backend, and report the\n  provider from Crabbox output rather than inferring it from bootstrap wording.\n- Treat `CRABBOX_PROVIDER` as part of that resolved provider configuration. The\n  provider reported by `crabbox config show` is authoritative; a hydration or\n  test failure is not permission to switch backends. Override it only when the\n  user explicitly names another provider.\n- Some package-manager wrappers insert a command delimiter before Crabbox\n  options. If the printed command looks like `crabbox run -- --provider ...`\n  or `crabbox run -- --no-hydrate ...`, call the trusted Crabbox binary\n  directly so lifecycle flags are parsed by Crabbox.\n- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo\n  config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.\n  If warmup drifts well past the minute-scale path, verify image promotion,\n  region/AZ placement, and FSR state before blaming OpenClaw.\n- Targeted and broad `pnpm` gates both use the resolved provider. Test size does\n  not authorize a provider override.\n- Always report the provider field and id. Both local-container and direct\n  providers can use `cbx_...`, so the id prefix alone does not prove AWS;\n  `tbx_...` identifies Blacksmith Testbox through Crabbox. If the output only\n  says `blacksmith testbox list`, use `blacksmith testbox list --all` before\n  concluding no box exists.\n- If a warm direct-provider lease smells stale, retry with `--full-resync`\n  (alias `--fresh-sync`) before replacing the lease. This resets the remote\n  workdir, skips the fingerprint fast path, reseeds Git when possible, and\n  uploads the checkout from scratch.\n- For live/provider bugs, use the configured secret workflow before downgrading\n  to mocks. Copy only the exact needed key into the remote process environment\n  for that one command. Do not print it, do not sync it as a repo file, and do\n  not leave it in remote shell history or logs. If no secret-safe injection path\n  is available, say true live provider auth is blocked instead of silently using\n  a fake key.\n- Targeted versus broad describes test scope only; it does not imply local,\n  remote, host, or container execution.\n- Do not treat unrelated inherited shell controls as operator intent. In\n  particular, `OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not\n  permission to move broad `pnpm check:changed`, `pnpm test:changed`, full\n  `pnpm test`, or lint/typecheck fan-out onto the laptop. This does not negate\n  provider-selection variables such as `CRABBOX_PROVIDER`, which are resolved\n  and reported by `crabbox config show`.\n- `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` controls direct host execution; it\n  is separate from Crabbox provider selection and must not override the provider\n  reported by `crabbox config show`.\n\n## macOS And Windows Targets\n\nUse these only when the task needs an existing non-Linux host. OpenClaw Linux\nvalidation uses the resolved Crabbox configuration unless the user explicitly\nrequests another provider or target.\n\nNative Windows is available when the resolved provider supports that target.\nFor providers other than AWS, keep placement and capacity in their resolved\nconfiguration:\n\n```sh\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --timing-json\n```\n\nAWS has a provider-specific placement requirement: the OpenClaw Windows\ndeveloper image and Docker cache are available in `us-west-2`, and native\nWindows leases must use on-demand capacity. After `crabbox config show` confirms\n`provider=aws` (or the user explicitly selects AWS), use:\n\n```sh\nCRABBOX_AWS_REGION=us-west-2 \\\nCRABBOX_CAPACITY_REGIONS=us-west-2 \\\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --market on-demand \\\n  --timing-json\n```\n\nThe region variables pin both the AWS image lookup and the capacity candidate\nset because `warmup` does not expose a generic `--region` flag. These placement\nand market settings are AWS availability constraints applied after provider\nselection; they are not a reason to select AWS for other runs. If the user\nexplicitly requests AWS while `crabbox config show` resolves another provider,\nadd `--provider aws` to this command to carry out that explicit override.\n\nThe hydrate workflow assumes Docker should already be baked into Linux images\nand only installs it as a fallback. Do not add per-run Docker installs to proof\ncommands unless the image probe shows Docker is actually missing.\n\nWhen the user explicitly asks for brokered macOS runners, use Crabbox AWS\nmacOS only after confirming the deployed coordinator supports EC2 Mac host\nlifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota\nand IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,\nor run the no-spend preflight first:\n\nThese administration commands specify AWS because they inspect or allocate an\nAWS EC2 Dedicated Host. The explicit provider is a billing and resource-scope\nsafety boundary, not a validation default.\n\n```sh\ncrabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json\ncrabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json\nCRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh\n```\n\nDo not silently substitute AWS macOS for normal OpenClaw Linux proof. Report\npaid-host blockers as quota, IAM, coordinator deployment, or host availability\ninstead of falling back to local macOS.\n\nCrabbox supports static SSH targets:\n\nThese commands specify `ssh` because the user-supplied static host selects that\ntransport explicitly; they do not establish an SSH preference for other runs.\n\n```sh\n../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command \"dotnet test\"\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test\n```\n\n- `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH,\n  bash, Git, rsync, and tar contract.\n- Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar\n  archive transfer into `static.workRoot`. Direct native Windows runs support\n  `--script*`, `--env-from-profile`, `--preflight`, and PowerShell `--shell`.\n- `crabbox actions hydrate/register` are Linux-only today; use plain\n  `crabbox run` loops for static macOS and Windows hosts.\n- Live proof needs a reachable, operator-managed SSH host. Without one, verify\n  with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox\n  Go test suite.\n\n## Direct Brokered AWS Backend\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects direct AWS Crabbox.\n\nChanged gate:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\"\n```\n\nFocused rerun:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>\"\n```\n\nRead the JSON summary. Useful fields:\n\n- `provider`: `aws`\n- `leaseId`: `cbx_...`\n- `syncDelegated`: `false`\n- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`\n- `commandMs` / `totalMs`\n- `exitCode`\n\nCrabbox should stop one-shot AWS leases automatically after the run. Verify\ncleanup when a run fails, is interrupted, or the command output is unclear:\n\n```sh\n../crabbox/bin/crabbox list --provider aws\n```\n\nThe explicit provider keeps cleanup attached to the AWS lease recorded by the\nrun, including when AWS was a user-requested override of another configured\ndefault.\n\n## Blacksmith Testbox Through Crabbox\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects Blacksmith Testbox:\n\nA fresh Testbox requires a repository-specific workflow. Crabbox resolves it\nfrom `blacksmith.workflow`, falling back to `actions.workflow`; job and ref use\nthe equivalent Blacksmith values with Actions fallbacks. The workflow must\ncontain a `useblacksmith/testbox`, `useblacksmith/begin-testbox`, or\n`useblacksmith/run-testbox` step. Confirm both the effective config and the\nactual workflow before using the provider-neutral command below; nonempty\nfields alone do not prove that an ordinary Actions workflow is Testbox-capable.\n\nFor a local workflow path, validate it with:\n\n```sh\nrg -n 'useblacksmith/(testbox|begin-testbox|run-testbox)' <workflow-path>\n```\n\nFor a workflow name or id, inspect its YAML through GitHub before dispatch. Do\nnot guess a Testbox workflow from another repository.\n\nIf the user explicitly supplies a Blacksmith override, carry those exact values\non the command instead:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --provider blacksmith-testbox \\\n  --blacksmith-workflow <repository-workflow> \\\n  --timing-json -- <test-command>\n```\n\nAdd `--blacksmith-org`, `--blacksmith-job`, and `--blacksmith-ref` only when the\nuser supplies those overrides. The explicit provider and workflow flags in this\nform implement the user's repository-specific selection; they are not defaults\nfor other runs.\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed\n```\n\nRead the JSON summary and the Testbox line. Useful fields:\n\n- `provider`: `blacksmith-testbox`\n- `leaseId`: `tbx_...`\n- `syncDelegated`: `true`\n- `syncPhases`: delegated/skipped because Blacksmith owns checkout/sync\n- Actions run URL/id from the Testbox output\n- `exitCode`\n\n`blacksmith testbox list` may hide hydrating or ready boxes. Use:\n\n```sh\nblacksmith testbox list --all\nblacksmith testbox status <tbx_id>\n```\n\n## Observability Flags\n\nUse these on debugging runs before inventing ad hoc logging:\n\n- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,\n  and target-specific tool probes. Defaults cover `git`, `tar`, `node`, `npm`,\n  `corepack`, `pnpm`, `yarn`, `bun`, `docker`, plus POSIX\n  `sudo`/`apt`/`bubblewrap` and native Windows\n  `powershell`/`execution_policy`/`longpaths`/`temp`/`pwsh`. Add\n  `--preflight-tools node,bun,docker`, `CRABBOX_PREFLIGHT_TOOLS`, or repo\n  `run.preflightTools` to replace the list. `default` expands built-ins; `none`\n  prints only the workspace summary. Preflight is diagnostic only; install\n  toolchains through Actions hydration, images, devcontainer/Nix/mise/asdf, or\n  the run script. On `blacksmith-testbox`, this prints a delegated-unsupported\n  note because the workflow owns setup.\n- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct\n  providers and prints `set len=N secret=true` style summaries. On\n  `blacksmith-testbox`, env forwarding is unsupported; put secrets in the\n  Testbox workflow instead.\n- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple\n  `export NAME=value` / `NAME=value` lines from a local profile without\n  executing it, then forwards only allowlisted names. `--allow-env` is\n  repeatable and comma-separated. Profile values override ambient allowlisted\n  env values for that run. Direct POSIX, WSL2, and native Windows runs are\n  supported; delegated providers are not. Crabbox probes the uploaded profile\n  remotely and prints redacted presence/length metadata before the command.\n- `--env-helper <name>`: with `--env-from-profile` on POSIX SSH targets,\n  persists `.crabbox/env/<name>` and `.crabbox/env/<name>.env` so follow-up\n  commands on the same lease can run through `./.crabbox/env/<name> <command>`.\n  Use only on leases you control; the profile stays until cleanup, lease reset,\n  or `--full-resync`.\n- `--script <file>` / `--script-stdin`: upload a local script into\n  `.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute\n  directly on POSIX; scripts without a shebang run through `bash`. Native\n  Windows uploads run through Windows PowerShell, and Crabbox appends `.ps1`\n  when needed. Arguments after `--` become script args.\n- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a\n  fresh remote checkout of the GitHub PR. Bare numbers use the current repo's\n  GitHub origin. Add `--apply-local-patch` only when the current local\n  `git diff --binary HEAD` should be applied on top of that PR checkout.\n- `--full-resync` / `--fresh-sync`: reset a stale direct-provider workdir\n  before syncing. Use after sync fingerprints look wrong, SSH times out before\n  sync, or rsync watchdog output suggests it. It is redundant with\n  `--fresh-pr`, incompatible with `--no-sync`, and unsupported by delegated\n  providers.\n- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to\n  local files and keep binary/noisy output out of retained logs. Parent\n  directories must already exist. These are direct-provider only.\n- `--capture-on-fail`: on non-zero direct-provider exits, downloads\n  `.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,\n  `coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.\n- `--keep-on-failure`: leave a failed one-shot lease alive for live debugging\n  until idle/TTL expiry. Useful on direct providers and delegated one-shots.\n- `--timing-json`: final machine-readable timing. Add\n  `echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell\n  commands; direct providers and Blacksmith Testbox both report them as\n  `commandPhases`.\n\nLive-provider debug template for the resolved direct-provider lease:\n\n```sh\nmkdir -p .crabbox/logs\n../crabbox/bin/crabbox run \\\n  --preflight \\\n  --allow-env OPENAI_API_KEY,OPENAI_BASE_URL \\\n  --timing-json \\\n  --capture-stdout .crabbox/logs/live-provider.stdout.log \\\n  --capture-stderr .crabbox/logs/live-provider.stderr.log \\\n  --capture-on-fail \\\n  --shell -- \\\n  \"echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live\"\n```\n\nDo not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or\n`--sync-only` to delegated providers. Also do not pass `--script*`,\n`--fresh-pr`, `--full-resync`, or `--env-helper` there. Crabbox rejects these\nbecause the provider owns sync or command transport. `--keep-on-failure` is OK\nfor delegated one-shots when you need to inspect a failed lease.\n\n## Efficient Bug E2E Verification\n\nUse the smallest Crabbox lane that proves the reported user path, not just the\ntouched code. Aim for one after-fix E2E proof before commenting, closing, or\nopening a PR for a user-visible bug.\n\nWhen the user says \"test in Crabbox\", do not simply copy tests to the remote\nbox and run them there. Crabbox is for remote real-scenario proof: copy or\ninstall OpenClaw as the user would, run the same setup/update/CLI/Gateway/API\ncall that failed, and capture behavior from that entrypoint. For regressions or\nbug reports, prove the broken state first when feasible, then run the same\nscenario after the fix.\n\nPick the lane by symptom:\n\n- Docker/setup/install bug: build a package tarball and run the matching\n  `scripts/e2e/*-docker.sh` or package script. This proves npm packaging,\n  install paths, runtime deps, config writes, and container behavior.\n- Provider/model/auth bug: prefer true live E2E. Use the configured secret\n  workflow, then inject the single needed key into Crabbox if needed. Scrub\n  unrelated provider env vars in the child command so interactive defaults do\n  not drift to another provider. If only a dummy key is used, label the proof\n  narrowly, e.g. \"UI/install path only; live provider auth not exercised.\"\n- Channel delivery bug: use the channel Docker/live lane when available; include\n  setup, config, gateway start, send/receive or agent-turn proof, and redacted\n  logs.\n- Gateway/session/tool bug: prefer an end-to-end CLI or Gateway RPC command that\n  creates real state and inspects the resulting files/API output.\n- Pure parser/config bug: targeted tests may be enough, but still run a\n  Crabbox command when OS, package, Docker, secrets, or service lifecycle could\n  change behavior.\n\nEfficient flow:\n\n1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint\n   when feasible. If the issue cannot be reproduced, capture the exact command\n   and observed behavior instead.\n2. Patch locally and run narrow local tests for edit speed.\n3. Run one Crabbox E2E command that starts from the user-facing entrypoint:\n   package install, Docker setup, onboarding, channel add, gateway start, or\n   agent turn as appropriate.\n4. Record proof as: Testbox id, command, environment shape, redacted secret\n   source, and copied success/failure output.\n5. If the issue says \"cannot reproduce\", ask for the missing config/log fields\n   that would distinguish the tested path from the reporter's path.\n\nKeep it efficient:\n\n- Reuse existing E2E scripts and helper assertions before writing ad hoc shell.\n- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead\n  of quote-heavy `--shell` strings on direct SSH providers.\n- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the\n  local dirty tree. Add `--apply-local-patch` only when testing a local fixup on\n  top of that PR.\n- Use `--full-resync` before replacing a warmed direct-provider lease when the\n  remote workdir or sync fingerprint appears stale.\n- Use one-shot Crabbox for a single proof; use a reusable Testbox only when\n  several commands must share built images, installed packages, or live state.\n- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a\n  candidate tarball; prefer the repo's package helper instead of direct source\n  execution when the bug might be packaging/install related.\n- Keep secrets redacted. It is fine to report key presence, source, and length;\n  never print secret values.\n- Include `--timing-json` on broad or flaky runs when command duration or sync\n  behavior matters.\n\nBefore/after PR proof on delegated Testbox:\n\n- For PRs that should prove \"broken before, fixed after\", compare base and PR\n  on the same Testbox when practical. Fetch both refs, create detached temp\n  worktrees under `/tmp`, install in each, then run the same harness twice.\n- Do not checkout base/PR refs in the synced repo root. Delegated Testbox sync\n  may leave the root dirty with local files; `git checkout` can abort or mix\n  proof state.\n- Temp harness files under `/tmp` do not resolve repo packages by default. Put\n  the harness inside the worktree, or in ESM use\n  `createRequire(path.join(process.cwd(), \"package.json\"))` before requiring\n  workspace deps such as `@lydell/node-pty`.\n- For full-screen TUI/CLI bugs, a PTY harness is stronger than helper-only\n  assertions. Use a real PTY, wait for visible lifecycle markers, send input,\n  then send control keys and assert process exit/stuck behavior.\n- When validating a rebased local branch before push, remember delegated sync\n  usually validates synced file content on a detached dirty checkout, not a\n  remote commit object. Record the local head SHA, changed files, Testbox id,\n  and final success markers; after pushing, ensure the pushed SHA has the same\n  file content.\n- If GitHub CI is still queued but the exact changed content passed Testbox\n  `pnpm check:changed`, `pnpm check:test-types`, and the real E2E proof, it is\n  reasonable to merge once required checks allow it. Note any still-running\n  unrelated shards in the proof comment instead of waiting forever.\n\nInteractive CLI/onboarding:\n\n- For full-screen or prompt-heavy CLI flows, run the target command inside tmux\n  on the Crabbox and drive it with `tmux send-keys`; capture proof with\n  `tmux capture-pane`, redacted through `sed`.\n- Prefer deterministic arrow navigation over search typing for Clack-style\n  searchable selects. Raw `send-keys -l openai` may not trigger filtering in a\n  tmux pane; inspect option order locally or on-box and send exact Down/Enter\n  sequences.\n- Isolate mutable state with `OPENCLAW_STATE_DIR=$(mktemp -d)`. Plugin npm\n  installs live under that state dir (`npm/node_modules/...`), not under\n  `OPENCLAW_CONFIG_DIR`. Verify downloads by checking the state dir, package\n  lock, and installed package metadata.\n- To test automatic setup installs against local package artifacts, use\n  `OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1` plus\n  `OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{\"plugin-id\":\"npm-pack:/tmp/plugin.tgz\"}'`.\n  Pack with `npm pack`, set an isolated `OPENCLAW_STATE_DIR`, and verify the\n  package under `npm/node_modules`. Overrides are test-only and must not be\n  treated as official/trusted-source installs.\n- For OpenAI/Codex onboarding proof, the useful markers are the UI line\n  `Installed Codex plugin`, `npm/node_modules/@openclaw/codex`, and the\n  package-lock entry showing the bundled `@openai/codex` dependency. A dummy\n  OpenAI-shaped key can prove only UI/install behavior; it is not live auth.\n\n## Reuse And Keepalive\n\nFor most Crabbox calls, one-shot is enough. Use reuse only when you need\nmultiple manual commands on the same hydrated box.\n\nThe examples below assume the lease came from the still-current resolved\nconfiguration. For a lease created through an explicit provider override, add\n`--provider <reported-provider>` to every reuse, inspection, and cleanup command\ninstead of relying on the id to recover its backend.\n\nIf Crabbox returns a reusable id or you intentionally keep a lease:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --no-sync --timing-json --shell -- \"pnpm test <path>\"\n```\n\nStop boxes you created before handoff:\n\n```sh\n../crabbox/bin/crabbox stop <id-or-slug>\nblacksmith testbox stop --id <tbx_id>\n```\n\n## Interactive Desktop And WebVNC\n\nBefore using WebVNC, confirm the resolved provider supports both desktop and a\ncoordinator-backed WebVNC lease, and that broker login is configured. Crabbox\n0.39 WebVNC supports coordinator-backed Hetzner, AWS, and Azure desktop leases;\nthis capability list does not establish a provider preference. If the resolved\nprovider lacks WebVNC, do not switch providers: use native `crabbox vnc` on the\nsame provider when it supports that path, or report the capability blocker.\n\nWhen those preconditions hold, prefer WebVNC for human inspection because the\nbrowser portal can preload the lease VNC password and avoids a native VNC\nclient's copy/paste/password dance. Use native `crabbox vnc` when the browser\nportal is unavailable or broken, or the user explicitly wants a local VNC\nclient.\n\nCommon desktop flow:\n\n```sh\n../crabbox/bin/crabbox warmup --desktop --browser --idle-timeout 60m --ttl 240m\n../crabbox/bin/crabbox desktop launch --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open --take-control\n```\n\nUseful WebVNC commands:\n\n```sh\n../crabbox/bin/crabbox webvnc --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon start --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc daemon stop --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc reset --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox desktop doctor --id <cbx_id-or-slug>\n../crabbox/bin/crabbox desktop click --id <cbx_id-or-slug> --x 640 --y 420\n../crabbox/bin/crabbox desktop paste --id <cbx_id-or-slug> --text \"user@example.com\"\n../crabbox/bin/crabbox desktop key --id <cbx_id-or-slug> ctrl+l\n../crabbox/bin/crabbox artifacts collect --id <cbx_id-or-slug> --all --output artifacts/<slug>\n../crabbox/bin/crabbox artifacts publish --dir artifacts/<slug> --pr <number>\n```\n\n`desktop launch --webvnc --open` is usually the nicest one-shot: it starts the\nbrowser/app inside the visible session, bridges the lease into the authenticated\nWebVNC portal, and opens the portal. Keep browsers windowed for human QA; use\n`--fullscreen` only for capture/video workflows.\nFor human handoff, include `--take-control` so the opened portal viewer gets\nkeyboard/mouse control automatically instead of landing as an observer.\n\nHuman handoff preflight:\n\n- Do not assume a visible desktop or launched browser means the repo CLI/app is\n  installed, built, or on the interactive terminal's `PATH`.\n- Before handing WebVNC to a human tester, prove the expected command from the\n  same kept lease and from a neutral directory such as `~`.\n- If the handoff needs repo-local code, sync/build/link it explicitly on that\n  lease. Source-tree CLIs often need build output before a symlink works.\n- Prefer a real `command -v <expected-command> && <expected-command> --version`\n  check over a repo-root-only `pnpm ...` command.\n\nGeneric handoff repair pattern:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --full-resync --shell -- \\\n  \"set -euo pipefail\n   pnpm install --frozen-lockfile\n   pnpm build\n   sudo ln -sf \\\"\\$PWD/<cli-entry>\\\" /usr/local/bin/<expected-command>\n   cd ~\n   command -v <expected-command>\n   <expected-command> --version\"\n```\n\n## If Crabbox Fails\n\nKeep the fallback narrow. First decide whether the failure is Crabbox itself,\nthe brokered AWS lease, Blacksmith/Testbox, repo hydration, sync, or the test\ncommand.\n\nFast checks:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,140p'\n../crabbox/bin/crabbox doctor\ncommand -v blacksmith\nblacksmith --version\nblacksmith testbox list\n```\n\nCommon Crabbox-only failures:\n\n- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling\n  repo, or update/install Crabbox before retrying.\n- Local-container hydration rejects a configured Actions `uses` step: stay on\n  `provider=local-container`, add `--no-hydrate`, and perform the required\n  dependency setup inside the container command. For example:\n\n  ```sh\n  ../crabbox/bin/crabbox run --no-hydrate --timing-json --shell -- \\\n    \"corepack enable && pnpm install --frozen-lockfile && <check-command>\"\n  ```\n\n  This is a hydration transport workaround, not permission to run the broad\n  check on the host or silently select a remote provider.\n- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and\n  `crabbox whoami`; preserve the resolved provider unless the user explicitly\n  requests another backend.\n- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot\n  without `--id`.\n- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the\n  printed Actions URL. Large sync warnings now include top source directories\n  by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect\n  those before reaching for `--force-sync-large`. Quiet rsync watchdogs and SSH\n  timeouts now print `next_action=` hints; follow them, usually `--full-resync`\n  first and a fresh lease second.\n- Cleanup uncertainty: run `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  only boxes you created.\n- Testbox queued/capacity pressure: do not retry repeatedly or switch providers.\n  Report the blocker and preserve the resolved provider.\n\nIf the resolved direct provider cannot dispatch, sync, attach, or stop, retry\nonce with `--debug` and `--timing-json` without changing providers:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\n```\n\nAuth fallback, only when `blacksmith` says auth is missing:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\nRaw Blacksmith footguns:\n\n- Run from repo root. The CLI syncs the current directory.\n- Save the returned `tbx_...` id in the session.\n- Reuse that id for focused reruns; stop it before handoff.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable\n  queue.\n\nIf the selected Blacksmith backend is down or quota-limited, do not keep probing\nit or switch providers. Report the delegated-provider outage.\n\n## Blacksmith Backend Notes\n\nCrabbox Blacksmith backend delegates setup to:\n\n- the organization reported by `crabbox config show`\n- a Testbox-capable `blacksmith.workflow` or `actions.workflow` in the target\n  repository\n- `blacksmith.job` / `blacksmith.ref`, with `actions.job` / `actions.ref`\n  fallbacks\n\nThe hydration workflow owns checkout, Node/pnpm setup, dependency install,\nsecrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command\nexecution, timing, logs/results, and cleanup.\n\nMinimal configured Blacksmith-backed Crabbox run, from repo root. Do not use\nthis fresh-run form until the effective workflow is present and verified as\nTestbox-capable; supply the explicit user-provided workflow above or reuse an\nexisting Testbox id instead.\n\n```sh\n../crabbox/bin/crabbox run --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed\n```\n\nUse direct Blacksmith only when Crabbox is the broken layer and you are\nisolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup\ndiagnostics, not as a reusable work queue.\n\nImportant Blacksmith footguns:\n\n- Always run from repo root. The CLI syncs the current directory.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- If auth is missing and browser auth is acceptable:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\n## Brokered AWS\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects AWS. Do not infer AWS from an omitted `--provider`.\n\nConfirm the selection first:\n\n```sh\ncrabbox config show\ncrabbox doctor\n```\n\nFor Linux, the repository configuration supplies the broker URL, developer\nimage, `eu-west-1` default region, capacity-region candidates, and\nspot-to-on-demand capacity policy. Do not repeat those values on every command;\nthe resolved configuration remains the source of truth. For native Windows,\nuse the `us-west-2` on-demand command in \"macOS And Windows Targets\" above. For\nbrokered macOS, complete the quota/IAM and no-spend Dedicated Host preflight in\nthat section before allocation. If the user explicitly selects AWS over a\ndifferent resolved provider, add `--provider aws` to the AWS commands below.\n\n```sh\n../crabbox/bin/crabbox warmup --idle-timeout 90m\n../crabbox/bin/crabbox actions hydrate --id <cbx_id-or-slug>\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --timing-json --shell -- \"env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n../crabbox/bin/crabbox stop <cbx_id-or-slug>\n```\n\nInstall/auth for owned Crabbox if needed. When configuration already resolves\nAWS and only broker auth is missing, omit `--provider` so login writes the token\nwithout changing provider selection:\n\n```sh\nbrew install openclaw/tap/crabbox\ncrabbox login --url https://crabbox.openclaw.ai\n```\n\nIf the user explicitly wants AWS as their persisted user-config default, use\n`crabbox login --url https://crabbox.openclaw.ai --provider aws`. The provider\nflag writes both broker auth and `provider=aws`; it is a configuration change,\nnot merely credential scoping. Repository config or `CRABBOX_PROVIDER` may\nstill take higher precedence, so confirm the effective result with\n`crabbox config show` in the target worktree.\n\nNew users should self-resolve broker auth before anyone asks for AWS keys:\n\n```sh\ncrabbox config show\ncrabbox doctor\ncrabbox whoami\n```\n\n- If broker auth is missing, run `crabbox login --url https://crabbox.openclaw.ai`.\n  Add `--provider aws` only when the user also wants to persist AWS as their\n  user-config default.\n- If the CLI asks for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS\n  profile setup during normal OpenClaw validation, assume the agent selected\n  the wrong path. Use brokered `crabbox login` or an existing brokered lease\n  before asking the user for cloud credentials.\n- Ask for AWS keys only for explicit direct-provider/account administration,\n  not for normal brokered OpenClaw proof.\n- Trusted automation that intentionally persists AWS as its default may use\n  `printf '%s' \"$CRABBOX_COORDINATOR_TOKEN\" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin`.\n\nmacOS config lives at:\n\n```text\n~/Library/Application Support/crabbox/config.yaml\n```\n\nIt should include `broker.url` and `broker.token` for AWS lanes. Let the resolved\nconfig select the backend; override it only when the user explicitly requests a\ndifferent provider.\n\n### Interactive Desktop / WebVNC\n\nFor human desktop demos, prefer `webvnc` over native `vnc` and keep the remote\ndesktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE\npanel/window chrome unless the explicit goal is video/capture output. After\nlaunch, verify a screenshot shows the desktop panel plus browser title bar. If\nChrome is fullscreen, toggle it back with:\n\n```sh\ncrabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11'\n```\n\n## Diagnostics\n\n```sh\ncrabbox status --id <id-or-slug> --wait\ncrabbox inspect --id <id-or-slug> --json\ncrabbox sync-plan\ncrabbox history --limit 20\ncrabbox history --lease <id-or-slug>\ncrabbox attach <run_id>\ncrabbox events <run_id> --json\ncrabbox logs <run_id>\ncrabbox results <run_id>\ncrabbox cache stats --id <id-or-slug>\ncrabbox ssh --id <id-or-slug>\nblacksmith testbox list\n```\n\nUse `--debug` on `run` when measuring sync timing.\nUse `--timing-json` on warmup, hydrate, and run when comparing backends.\nUse `--market spot|on-demand` only on AWS warmup/one-shot runs.\n\n## Failure Triage\n\n- Crabbox cannot find provider: verify `../crabbox/bin/crabbox --help` lists\n  the provider selected by `.crabbox.yaml`; update Crabbox before falling back.\n- Hydration stuck or failed: open the printed GitHub Actions run URL and inspect\n  the hydration step.\n- Sync failed: rerun with `--debug`; check changed-file count and whether the\n  checkout is dirty.\n- Command failed: rerun only the failing shard/file first. Do not rerun a full\n  suite until the focused failure is understood.\n- Cleanup uncertain: `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  owned `tbx_...` leases you created.\n- Selected provider broken: report the provider-specific blocker; do not switch\n  providers unless the user explicitly requests the fallback.\n\n## Boundary\n\nDo not add OpenClaw-specific setup to Crabbox itself. Put repo setup in the\nhydration workflow and keep Crabbox generic around lease, sync, command\nexecution, logs/results, timing, and cleanup.\n","frontmatter":{"name":"crabbox","description":"Use the Crabbox wrapper for validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id."},"isInternal":false,"tokens":9783,"sizeBytes":39672},{"name":"openai.yaml","path":".agents/skills/local-clawsweeper-review/agents/openai.yaml","rawUrl":"https://raw.githubusercontent.com/openclaw/clawsweeper/HEAD/.agents/skills/local-clawsweeper-review/agents/openai.yaml","title":"Agents Skill","category":"anthropic-skill","format":"yaml","content":"interface:\n  display_name: \"Local ClawSweeper Review\"\n  short_description: \"Run local ClawSweeper before PRs\"\n  default_prompt: \"Use $local-clawsweeper-review to run a local ClawSweeper review before I submit a PR.\"\n","isInternal":false,"tokens":57,"sizeBytes":216},{"name":"SKILL.md","path":".agents/skills/local-clawsweeper-review/SKILL.md","rawUrl":"https://raw.githubusercontent.com/openclaw/clawsweeper/HEAD/.agents/skills/local-clawsweeper-review/SKILL.md","title":"local-clawsweeper-review","category":"anthropic-skill","format":"markdown","content":"---\nname: local-clawsweeper-review\ndescription: Run local ClawSweeper exact-item or committed-range reviews without GitHub mutation.\n---\n\n# Local ClawSweeper Review\n\nUse this skill when someone wants read-only local ClawSweeper output before\nsubmitting, updating, or re-reviewing an issue or PR.\n\n## Safety Boundary\n\n- Run only `pnpm run review -- --local-only` for an existing GitHub item, or\n  `pnpm run review -- --local-range` for a pre-submission committed range.\n- Do not run `apply-artifacts`, `apply-decisions`, GitHub comment posting, or\n  merge/autofix commands unless the user explicitly asks for that mutation.\n- Do not print `OPENAI_API_KEY`, `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN`, GitHub\n  tokens, or Codex auth material.\n- Treat generated review artifacts as local proof. Do not claim ClawSweeper\n  posted or synced anything unless a separate explicit mutation command did it.\n\n## Locate ClawSweeper\n\nPrefer the current repository when its `package.json` name is\n`@openclaw/clawsweeper`. Otherwise use a known clean local checkout:\n\n- Windows: `C:\\oc-work\\clawsweeper-source`\n- POSIX fallback: `~/Projects/clawsweeper`\n\nInspect `git status --short` before making changes. If another ClawSweeper clone\nis dirty or ambiguous, do not use it for the local review runner.\n\n## First-Time Setup\n\nFrom the ClawSweeper checkout:\n\n```sh\ncorepack enable\npnpm install\npnpm run build:all\npnpm run codex:local:check -- --diagnostics\n```\n\nThe diagnostics mode checks the selected Codex binary and login status without\na model request. It does not prove model access or review readiness. Omit\n`--diagnostics` for the existing model smoke test, which consumes model usage.\n\nIf the Codex check says the CLI is not logged in, have the operator authenticate\ntheir own Codex CLI. Device auth is the simplest shareable setup:\n\n```sh\ncodex login --device-auth -c 'service_tier=\"fast\"'\n```\n\nFor API-key setup, pass the key through the shell only for the login command and\nthen clear it from the environment. Do not put the key in docs, scripts, shell\nhistory, or committed files.\n\nPowerShell:\n\n```powershell\n$env:OPENAI_API_KEY = Read-Host \"OpenAI API key\"\n$env:OPENAI_API_KEY | codex login --with-api-key -c 'service_tier=\"fast\"'\nRemove-Item Env:OPENAI_API_KEY\n```\n\nPOSIX shell:\n\n```sh\nprintf '%s' \"$OPENAI_API_KEY\" | codex login --with-api-key -c 'service_tier=\"fast\"'\nunset OPENAI_API_KEY\n```\n\nIf the wrong Codex binary is used, set `CODEX_BIN` in the local shell for that\nrun. Otherwise, `--local-only` uses the first spawnable `codex` command on\n`PATH`, including on Windows. If no Windows PATH command is spawnable, it falls\nback to the installed Codex Desktop binary.\n\n## Target Checkout Modes\n\nBy default, an exact local PR review manages its own target checkout under\n`artifacts/local-review-<pr-number>/target`.\n\nBy default, `--local-range` reviews the clean checkout where the command was\ninvoked. It does not manage or switch that checkout. Pass `--target-dir` when\nthe branch to review is elsewhere.\n\nIn a built source checkout, `node dist/clawsweeper-local.js review` is the\nlocal-only entrypoint for the same full committed-range engine. Its `--help`\nand `--version` paths do not load the review engine or invoke Codex. It does not\nprovide diagnostics yet; `codex:local:check` remains the existing model smoke\ntest. This entrypoint does not publish hosted action-ledger or cache metadata.\n\nPass `--target-dir` when the operator wants to review an existing checkout or\nan issue.\n\nUse a clean target checkout of the repository being reviewed. Prefer a dedicated\nreview checkout if the normal worktree is dirty:\n\n- Windows: `C:\\oc-work\\clawsweeper-local-target-openclaw`\n- POSIX fallback: `../openclaw`\n\nBefore reviewing against `main`, update the target checkout only when it is\nclean:\n\n```sh\ngit -C <target-dir> status --short\ngit -C <target-dir> fetch origin main\ngit -C <target-dir> switch main\ngit -C <target-dir> pull --ff-only origin main\n```\n\nDo not switch branches, pull, or overwrite files in a dirty target checkout.\n\n## Run A Local Review\n\nUse the exact issue or PR number. If the number is not provided and the current\nbranch has an open PR, use `gh pr view --json number,url,headRefOid` to identify\nit.\n\nFrom the ClawSweeper checkout:\n\n```sh\npnpm run review -- --local-only --item-number <pr-number>\n```\n\nTo use a supplied checkout or review an issue:\n\n```sh\npnpm run review -- --local-only \\\n  --item-number <issue-or-pr-number> \\\n  --target-dir <target-dir>\n```\n\nTo review committed branch work before a PR exists:\n\n```sh\npnpm run review -- --local-range \\\n  --target-repo <owner/repo> \\\n  --base origin/main\n```\n\nThe range is `merge-base(<base>, HEAD)..HEAD`. It must be clean and contain at\nleast one commit beyond the base. This path withholds GitHub credentials,\nisolates cached `gh` auth, disables web search, and skips host-side URL/media\npreprocessing. It still calls the configured Codex model service; do not call it\nair-gapped or fully network-offline.\n\nThe exact local command prints a human-readable progress summary by default. Add\n`--verbose` only when debugging checkout, selection, or Codex process details.\n\nFor quick smoke tests, lower `--batch-size`, `--shard-count`, `--max-pages`, and\n`--codex-timeout-ms`, but label the result as a smoke run rather than a full\nlocal review.\n\n## Read The Artifact\n\nThe default OpenClaw report is written to:\n\n```text\n<artifact-dir>/<issue-or-pr-number>.md\n```\n\nRead the artifact and summarize:\n\n- `review_status`\n- `main_sha`\n- `pull_head_sha` for PRs\n- decision/confidence/action fields when present\n- findings or blockers\n- exact Codex/auth/runtime failure if the run failed\n\nIf the failure is Codex auth, stop after providing the local setup command. If\nthe failure is runner/runtime behavior, include the artifact path and a concise\nstderr or log summary.\n\n## Closeout\n\nBefore reporting success:\n\n- Confirm the command used `review --local-only` or `review --local-range`.\n- Confirm no GitHub comments, labels, merges, or apply commands were run.\n- Confirm the target checkout is still clean.\n- If findings exist, list the actionable items and the next local fix/test step.\n- If no blockers exist, say the local ClawSweeper artifact found no blockers\n  and include the reviewed `main_sha` and PR head SHA when available.\n","frontmatter":{"name":"local-clawsweeper-review","description":"Run local ClawSweeper exact-item or committed-range reviews without GitHub mutation."},"isInternal":false,"tokens":1548,"sizeBytes":6299}],"systemPromptSnippet":"<yakaai_skills repo=\"openclaw/clawsweeper\">\n<!-- File: AGENTS.md (Tokens: ~2741 | Category: root-instruction) -->\n# AGENTS.MD\n\nClawSweeper is the conservative maintenance bot for OpenClaw repositories.\nKeep changes narrow, evidence-backed, and automation-safe.\n\n`AGENTS.md` is the canonical repository-wide coding-agent policy. Task-specific\nworkflows under `.agents/skills/` are opt-in procedures and do not override this\nfile. This repository does not currently maintain `AGENT.md`, `CLAUDE.md`, or\nCursor aliases; agents that do not discover `AGENTS.md` automatically must be\ndirected here rather than given a duplicated policy copy.\n\n## Structure\n\n- Main code: `src/clawsweeper.ts`.\n- Repair lane code: `src/repair/`; canonical records live in the Cloudflare\n  Worker, ledger/assets blobs live in R2, and remaining operational state lives\n  in `openclaw/clawsweeper-state`.\n- Tests: `test/*.test.ts` and `test/repair/*.test.ts`; add new coverage to the\n  narrowest matching test file instead of growing `test/clawsweeper.test.ts`.\n- Workflow: `.github/workflows/sweep.yml`.\n- Vision and product boundaries: `VISION.md`.\n- Explainer: `README.md`; state/dashboard repo: `../clawsweeper-state`.\n- Changelog: one-bullet fragments in `changelog.d/`, stitched into\n  `CHANGELOG.md` at release time; see\n  [`changelog.d/README.md`](changelog.d/README.md).\n- Open/reviewed records in the canonical Worker store:\n  `records/<repo-slug>/items/<number>.md`.\n- Archived records in the canonical Worker store:\n  `records/<repo-slug>/closed/<number>.md`.\n- Scratch/generated output: `.artifacts/`, `artifacts/`, `apply-report.json`.\n\nPreserve one flat `items/` and `closed/` report layout per repository slug. Do\nnot split reports into issue/PR subtrees.\n\n## Operating Model\n\n- Review lane is proposal-only. It never closes GitHub items.\n- Ordinary PRs receive one automatic completed review after ten quiet minutes.\n  Later pushes, edits, reopen events, and scheduled passes require a new explicit\n  review request. Failed or stale-source attempts can finish the first review.\n  `clawsweeper:autofix` and `clawsweeper:automerge` no longer change review\n  admission; they only keep their close protection.\n- Maintainer-authored items and items labeled `maintainer` created from\n  2026-10-15 03:50 UTC are reviewed like everyone else's: a PR gets its one\n  automatic review. Older maintainer items need an explicit `@clawsweeper review`\n  request.\n  Finish the work and validation first; request review only when it is needed.\n  Agents must not request reviews automatically or repeat a queued/running request.\n  An explicit review request stays open while the queue requeues its own review\n  after source drift, in place or from the publisher still holding the request's\n  publication; that retry continues the request. A finished or replaced\n  request, later changes after the answer, and scheduled passes need a new\n  request.\n- Apply lane mutates GitHub by syncing the durable Codex review comment and then\n  closing only unchanged, high-confidence proposals.\n- Repository-specific rules live in `src/repository-profiles.ts`; ClawHub apply\n  may close only PRs that are certainly implemented on `main`.\n- Hosted review concurrency and batching belong to the shared exact-review\n  queue. Broad sweeps only admit candidates; they do not start per-run shards\n  or grant immediate-apply authority.\n- `openclaw/clawsweeper-state` is the live status surface and operational state\n  store; the Worker/R2 pair is authoritative for records, ledger, and assets.\n  Check current Actions and the canonical owner before trusting local generated\n  timestamps.\n- When asked about PRs outside `openclaw/clawsweeper`, treat the task as\n  monitoring/debugging how ClawSweeper workflows operate on that PR. Do not fix\n  foreign PR branches directly; ClawSweeper repair/automerge workflows own those\n  branch edits.\n- In `openclaw/openclaw`, `CHANGELOG.md` is release-owned. Do not ask contributor\n  PR authors, repair workers, or automerge/autofix lanes to edit it during normal\n  PR work. Preserve release-note context in PR bodies and commit messages instead.\n- In `openclaw/clawsweeper` itself, record a user-visible change as one new\n  `changelog.d/<pr-or-slug>.md` fragment holding a single bullet line. Do not\n  edit `CHANGELOG.md` or other PRs' fragments in normal PR work; the release\n  maintainer folds fragments in with `pnpm run changelog:stitch`, and\n  `pnpm run check:changelog` validates them.\n- When referencing GitHub issues or PRs in user-facing output, always include\n  the full GitHub URL, not only `#12345`.\n\n## Safety Rules\n\n- Never disable or pause the live ClawSweeper sweep workflow unless Peter\n  explicitly asks for that exact action.\n- Do not run live apply/close commands unless Peter explicitly asks.\n- For apply-path repros, copy one report into a temp `items/` dir and pass\n  `--skip-dashboard`, `--item-number`, and a temp `--closed-dir`.\n- Treat maintainer-authored and protected-label items as non-closeable, except\n  for `implemented_on_main` with its existing\n  source/history/release evidence and fresh apply guards (PRs additionally need\n  GitHub-verified merged same-repository fixing provenance and paired-issue\n  relationship checks; see `docs/implemented-on-main-close-policy.md`), and\n  the maintainer-approved metadata-only `oversized_pull_request` policy:\n  drafts, maintainer authorship, and the `maintainer` label do not exempt that\n  reason. Its explicit PR exemption labels, `size: accepted-large`, other\n  protected labels, live freshness checks, and apply gates still apply.\n- Leave canonical OpenClaw Mantis locale PRs open; their generated-PR publisher\n  owns freshness and auto-merge. See `docs/target-repositories.md` for identity scope.\n- Snapshot or `updated_at` drift blocks apply unless the only change is the\n  existing ClawSweeper review comment, or a ClawSweeper-recorded write for the\n  item (`docs/scheduler.md`) while the complete source/timeline/head/activity\n  receipt matches and no non-automation activity follows the review snapshot.\n- Open-but-locked issues can exist when stale automation locked a closed issue\n  and the author later reopened it. These must be skipped, not allowed to crash\n  the apply run.\n- Locked-comment 403s from GitHub are terminal apply skips, not retryable API\n  failures.\n\n## PR Validation and Landing\n\n- For code-bearing changes, run focused validation that exercises the changed\n  behavior, commit the final candidate, then obtain a fresh Codex review of the\n  entire committed branch against a pinned intended base. Require a clean index\n  and working tree; review the merge-base-to-HEAD range, not only the last commit.\n  Complete this review before publication, handoff, or landing, including direct\n  pushes where otherwise permitted. Early local review is optional feedback and\n  does not replace this final branch review. See `CONTRIBUTING.md` for the command.\n- Address every accepted or actionable finding and repeat the affected proof and\n  review after fixes. A changed head, parent or selected base/range, dirty source,\n  post-review hook edits, or changed review evidence, context, or applicable policy\n  invalidates the affected review. Verify the final source after hooks and before\n  publication or handoff. A failed or incomplete review never falls back to an\n  earlier clean result; repeat review when needed, not merely to obtain a nicer\n  verdict. An unchanged Git tree alone does not establish equivalent review inputs.\n  CI, an older ClawSweeper comment, prior review comments, or manual self-review\n  alone do not replace this loop or the separate gates below.\n- At task kickoff, define the `pr-behavior-proof` contract for every\n  code-bearing PR: claim, exercised surface, scenario or fixture, command and\n  environment, observable result, artifact or trace, and limits. Run its\n  controlled real-behavior proof before opening even a draft PR; only Martin\n  may expressly approve an evidence-in-progress exception.\n- Keep that proof current in the PR body. Tests, CI, mocks, snapshots, lint,\n  typechecks, and clean review support the claim but never replace proof of a\n  changed runtime, workflow, queue, API, UI, package, or integration path. On\n  this Windows host, proof for those surfaces uses Docker-backed Crabbox\n  `local-container` and records the current head, provider, image, lease,\n  artifact, and limits. Use the narrowest meaningful proof first and broaden\n  it for shared or higher-risk behavior. Docs-only changes normally need\n  `git diff --check` and relevant link or command sanity instead.\n- The public dashboard is observer-only: it may display status and provide\n  view-only navigation to verified-public GitHub repository, item, workflow-run,\n  and job pages. Those canonical GET links are references, not action controls.\n  It never calls GitHub from the browser and never triggers or offers queue,\n  workflow, GitHub, DLQ, recovery, deploy, rollback, or other mutation controls.\n- A ClawSweeper result that requires proof or identifies an accepted/actionable\n  finding remains PR-owner work, not a handoff. Before a manually requested\n  review or re-review, put current proof and the finding disposition or evidence\n  in the main PR body. A head or review-content body change after the durable review marker\n  makes that review and any affected proof stale: rerun the affected proof and\n  obtain a review for the current head and body. CI, labels, readiness, and\n  maintainer permissions are evidence only; the explicit-user-approval boundary\n  below still controls landing.\n- Before merge or automerge, the latest ClawSweeper review must apply to the\n  current PR head and review-content body. The canonical preflight reader excludes\n  one valid advisory annotation only; human text, proof, and all outside whitespace\n  remain review content. Raw event and concurrency guards can still invalidate\n  after a metadata edit. Resolve every accepted finding. Apply each\n  applicable `Rank-up moves:` item, or explicitly justify the exception in the\n  PR body; Rank-up moves remain optional and do not by themselves block merge.\n  Do not merge while proof is missing or while the review has an unresolved\n  contributor-facing blocker.\n- Land only after the current review and status evidence is ready for\n  maintainer look, including `proof: sufficient` or `proof: override` when the\n  proof label applies. This does not replace the user's explicit merge approval\n  in the current conversation; agents must not merge or enable/execute\n  automerge without it.\n\n## Commands\n\n```bash\ncorepack enable\npnpm install\npnpm run build\npnpm run test:unit\npnpm run format\npnpm run check\n```\n\nUse `pnpm run check` before handoff for code/test/workflow changes.\n\n`engines.node` is `>=24`. Node 22 will install (no `engine-strict`) but the\nnotifier tests' 5-second retry paths surface as `cancelledByParent` under the\nold `node:test` runner. Run on Node 24 or newer before reporting test\nfailures.\n\n## GitHub Checks\n\nUseful live probes:\n\n```bash\ngh run list --repo openclaw/clawsweeper --limit 20 --json databaseId,displayTitle,status,conclusion,createdAt,updatedAt\ngh api repos/openclaw/clawsweeper/readme --jq '.content' | base64 --decode\ngh api graphql -f query='query { repository(owner:\"openclaw\", name:\"openclaw\") { issues(states: OPEN) { totalCount } pullRequests(states: OPEN) { totalCount } } }'\n```\n\nFor throughput/default tuning, start with `config/automation-limits.json` and\n[`docs/limits.md`](docs/limits.md). `scripts/check-limits.ts` identifies the\nderived docs, Worker values, and the `workflow_dispatch` literals that must stay\naligned. Effective exact-review admission, publication, and batching overrides\nlive in `dashboard/wrangler.toml`; owning fallback behavior lives in\n`dashboard/exact-review-queue.ts`. Update `.github/workflows/sweep.yml` or\n`src/clawsweeper.ts` only when the changed contract is actually owned there.\n\nUse [`docs/README.md`](docs/README.md) for the documentation map, lifecycle\nstates, role ownership, and cross-surface update triggers.\n\n<!-- File: .agents/skills/crabbox/SKILL.md (Tokens: ~9783 | Category: anthropic-skill) -->\n---\nname: crabbox\ndescription: Use the Crabbox wrapper for validation across Linux, macOS, Windows, and WSL2, including delegated Blacksmith Testbox proof. Report the actual provider and id.\n---\n\n# Crabbox\n\n## Provider Selection Contract\n\nProvider selection is configuration resolution, not testing policy. Run\n`crabbox config show` from the exact worktree being tested; a session may have\nstarted in another checkout whose repository config or skill text is stale. A\nrequest to \"use Crabbox\" does not authorize a provider override. When the user\ndoes not name a backend, omit `--provider` and preserve the resolved provider,\nincluding values supplied by user config or `CRABBOX_PROVIDER`.\n\nTest scope, expected duration, and hydration failures do not select a provider.\nOverride the resolved provider only when the user explicitly names a different\nbackend. If that provider cannot perform the requested test, report the blocker\ninstead of silently selecting another backend.\n\nUse the Crabbox wrapper for validation execution, environment lifecycle, sync,\nlogs/results, cache inspection, and lease cleanup.\n\nCrabbox is the transport/orchestration surface. The actual backend can be:\n\n- local Docker isolation: `provider=local-container`, lease ids like `cbx_...`\n- brokered AWS Crabbox: direct provider, `provider=aws`, lease ids like\n  `cbx_...`, `syncDelegated=false`\n- Blacksmith Testbox through Crabbox: delegated provider,\n  `provider=blacksmith-testbox`, ids like `tbx_...`, `syncDelegated=true`\n\nThe provider-specific sections below document capabilities and commands after\nconfiguration or an explicit user request has selected a backend. They are not\nprovider-selection policy. Their validation commands intentionally omit\n`--provider`; add it only to carry out an explicit user override of the resolved\nconfiguration.\n\nProvider identity must remain attached to a lease after creation. A lease\ncreated through the resolved configuration can keep using provider-neutral\ncommands while that configuration is unchanged. If the user explicitly\noverrode the provider, or the resolved configuration has changed since the\nlease was created, pass the provider reported by Crabbox to every later command\nthat targets that lease, including hydrate, rerun, desktop/WebVNC, status,\ninspect, SSH, and stop. This preserves resource identity; it does not select a\nprovider for unrelated work.\n\nWhen the resolved configuration selects Blacksmith Testbox, or the user\nexplicitly requests it, do not describe the run as \"AWS Crabbox\". Report it as\nTestbox-through-Crabbox with the `tbx_...` id and Actions run.\n\nDirect AWS supports persistent leases, `--fresh-pr`, `--full-resync`,\nenvironment forwarding, capture/download, and provider-comparison workflows.\nBlacksmith Testbox provides a prepared CI environment and delegated broad/heavy\n`pnpm` gates. These capabilities do not override the resolved configuration.\n\n## First Checks\n\n- Run from the repo root. Crabbox sync mirrors the current checkout.\n- Check the wrapper and providers before Crabbox work:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,120p'\n../crabbox/bin/crabbox desktop launch --help\n../crabbox/bin/crabbox webvnc --help\n```\n\n- OpenClaw scripts prefer `../crabbox/bin/crabbox` when present. The user PATH\n  shim can be stale.\n- Read `.crabbox.yaml`, then run `crabbox config show` from the repository root\n  before selecting a provider. The resolved provider can come from the user's\n  Crabbox config or environment as well as the repository file.\n- Omitting `--provider` means \"use the resolved configuration\". Pass it only\n  when the user explicitly requests a different backend, and report the\n  provider from Crabbox output rather than inferring it from bootstrap wording.\n- Treat `CRABBOX_PROVIDER` as part of that resolved provider configuration. The\n  provider reported by `crabbox config show` is authoritative; a hydration or\n  test failure is not permission to switch backends. Override it only when the\n  user explicitly names another provider.\n- Some package-manager wrappers insert a command delimiter before Crabbox\n  options. If the printed command looks like `crabbox run -- --provider ...`\n  or `crabbox run -- --no-hydrate ...`, call the trusted Crabbox binary\n  directly so lifecycle flags are parsed by Crabbox.\n- The brokered AWS default is a Linux developer image in `eu-west-1`; the repo\n  config pins hot `eu-west-1a/b/c` placement so Fast Snapshot Restore can apply.\n  If warmup drifts well past the minute-scale path, verify image promotion,\n  region/AZ placement, and FSR state before blaming OpenClaw.\n- Targeted and broad `pnpm` gates both use the resolved provider. Test size does\n  not authorize a provider override.\n- Always report the provider field and id. Both local-container and direct\n  providers can use `cbx_...`, so the id prefix alone does not prove AWS;\n  `tbx_...` identifies Blacksmith Testbox through Crabbox. If the output only\n  says `blacksmith testbox list`, use `blacksmith testbox list --all` before\n  concluding no box exists.\n- If a warm direct-provider lease smells stale, retry with `--full-resync`\n  (alias `--fresh-sync`) before replacing the lease. This resets the remote\n  workdir, skips the fingerprint fast path, reseeds Git when possible, and\n  uploads the checkout from scratch.\n- For live/provider bugs, use the configured secret workflow before downgrading\n  to mocks. Copy only the exact needed key into the remote process environment\n  for that one command. Do not print it, do not sync it as a repo file, and do\n  not leave it in remote shell history or logs. If no secret-safe injection path\n  is available, say true live provider auth is blocked instead of silently using\n  a fake key.\n- Targeted versus broad describes test scope only; it does not imply local,\n  remote, host, or container execution.\n- Do not treat unrelated inherited shell controls as operator intent. In\n  particular, `OPENCLAW_LOCAL_CHECK_MODE=throttled` from the local shell is not\n  permission to move broad `pnpm check:changed`, `pnpm test:changed`, full\n  `pnpm test`, or lint/typecheck fan-out onto the laptop. This does not negate\n  provider-selection variables such as `CRABBOX_PROVIDER`, which are resolved\n  and reported by `crabbox config show`.\n- `OPENCLAW_LOCAL_CHECK_MODE=throttled|full` controls direct host execution; it\n  is separate from Crabbox provider selection and must not override the provider\n  reported by `crabbox config show`.\n\n## macOS And Windows Targets\n\nUse these only when the task needs an existing non-Linux host. OpenClaw Linux\nvalidation uses the resolved Crabbox configuration unless the user explicitly\nrequests another provider or target.\n\nNative Windows is available when the resolved provider supports that target.\nFor providers other than AWS, keep placement and capacity in their resolved\nconfiguration:\n\n```sh\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --timing-json\n```\n\nAWS has a provider-specific placement requirement: the OpenClaw Windows\ndeveloper image and Docker cache are available in `us-west-2`, and native\nWindows leases must use on-demand capacity. After `crabbox config show` confirms\n`provider=aws` (or the user explicitly selects AWS), use:\n\n```sh\nCRABBOX_AWS_REGION=us-west-2 \\\nCRABBOX_CAPACITY_REGIONS=us-west-2 \\\n../crabbox/bin/crabbox warmup \\\n  --target windows \\\n  --windows-mode normal \\\n  --market on-demand \\\n  --timing-json\n```\n\nThe region variables pin both the AWS image lookup and the capacity candidate\nset because `warmup` does not expose a generic `--region` flag. These placement\nand market settings are AWS availability constraints applied after provider\nselection; they are not a reason to select AWS for other runs. If the user\nexplicitly requests AWS while `crabbox config show` resolves another provider,\nadd `--provider aws` to this command to carry out that explicit override.\n\nThe hydrate workflow assumes Docker should already be baked into Linux images\nand only installs it as a fallback. Do not add per-run Docker installs to proof\ncommands unless the image probe shows Docker is actually missing.\n\nWhen the user explicitly asks for brokered macOS runners, use Crabbox AWS\nmacOS only after confirming the deployed coordinator supports EC2 Mac host\nlifecycle/image routes and the operator has AWS EC2 Mac Dedicated Host quota\nand IAM. Prefer `CRABBOX_HOST_ID` for a known Crabbox-managed Dedicated Host,\nor run the no-spend preflight first:\n\nThese administration commands specify AWS because they inspect or allocate an\nAWS EC2 Dedicated Host. The explicit provider is a billing and resource-scope\nsafety boundary, not a validation default.\n\n```sh\ncrabbox admin hosts quota --provider aws --target macos --region eu-west-1 --type mac2.metal --json\ncrabbox admin hosts allocate --provider aws --target macos --region eu-west-1 --type mac2.metal --dry-run --json\nCRABBOX_MACOS_TYPES=all scripts/macos-host-region-preflight.sh\n```\n\nDo not silently substitute AWS macOS for normal OpenClaw Linux proof. Report\npaid-host blockers as quota, IAM, coordinator deployment, or host availability\ninstead of falling back to local macOS.\n\nCrabbox supports static SSH targets:\n\nThese commands specify `ssh` because the user-supplied static host selects that\ntransport explicitly; they do not establish an SSH preference for other runs.\n\n```sh\n../crabbox/bin/crabbox run --provider ssh --target macos --static-host mac-studio.local -- xcodebuild test\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode normal --static-host win-dev.local -- pwsh -NoProfile -Command \"dotnet test\"\n../crabbox/bin/crabbox run --provider ssh --target windows --windows-mode wsl2 --static-host win-dev.local -- pnpm test\n```\n\n- `target=macos` and `target=windows --windows-mode wsl2` use the POSIX SSH,\n  bash, Git, rsync, and tar contract.\n- Native Windows uses OpenSSH, PowerShell, Git, and tar; sync is manifest tar\n  archive transfer into `static.workRoot`. Direct native Windows runs support\n  `--script*`, `--env-from-profile`, `--preflight`, and PowerShell `--shell`.\n- `crabbox actions hydrate/register` are Linux-only today; use plain\n  `crabbox run` loops for static macOS and Windows hosts.\n- Live proof needs a reachable, operator-managed SSH host. Without one, verify\n  with `../crabbox/bin/crabbox run --help`, config/flag tests, and the Crabbox\n  Go test suite.\n\n## Direct Brokered AWS Backend\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects direct AWS Crabbox.\n\nChanged gate:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\"\n```\n\nFocused rerun:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  --shell -- \\\n  \"env CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test <path-or-filter>\"\n```\n\nRead the JSON summary. Useful fields:\n\n- `provider`: `aws`\n- `leaseId`: `cbx_...`\n- `syncDelegated`: `false`\n- `commandPhases`: populated when the command prints `CRABBOX_PHASE:<name>`\n- `commandMs` / `totalMs`\n- `exitCode`\n\nCrabbox should stop one-shot AWS leases automatically after the run. Verify\ncleanup when a run fails, is interrupted, or the command output is unclear:\n\n```sh\n../crabbox/bin/crabbox list --provider aws\n```\n\nThe explicit provider keeps cleanup attached to the AWS lease recorded by the\nrun, including when AWS was a user-requested override of another configured\ndefault.\n\n## Blacksmith Testbox Through Crabbox\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects Blacksmith Testbox:\n\nA fresh Testbox requires a repository-specific workflow. Crabbox resolves it\nfrom `blacksmith.workflow`, falling back to `actions.workflow`; job and ref use\nthe equivalent Blacksmith values with Actions fallbacks. The workflow must\ncontain a `useblacksmith/testbox`, `useblacksmith/begin-testbox`, or\n`useblacksmith/run-testbox` step. Confirm both the effective config and the\nactual workflow before using the provider-neutral command below; nonempty\nfields alone do not prove that an ordinary Actions workflow is Testbox-capable.\n\nFor a local workflow path, validate it with:\n\n```sh\nrg -n 'useblacksmith/(testbox|begin-testbox|run-testbox)' <workflow-path>\n```\n\nFor a workflow name or id, inspect its YAML through GitHub before dispatch. Do\nnot guess a Testbox workflow from another repository.\n\nIf the user explicitly supplies a Blacksmith override, carry those exact values\non the command instead:\n\n```sh\n../crabbox/bin/crabbox run \\\n  --provider blacksmith-testbox \\\n  --blacksmith-workflow <repository-workflow> \\\n  --timing-json -- <test-command>\n```\n\nAdd `--blacksmith-org`, `--blacksmith-job`, and `--blacksmith-ref` only when the\nuser supplies those overrides. The explicit provider and workflow flags in this\nform implement the user's repository-specific selection; they are not defaults\nfor other runs.\n\n```sh\n../crabbox/bin/crabbox run \\\n  --idle-timeout 90m \\\n  --ttl 240m \\\n  --timing-json \\\n  -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 OPENCLAW_TESTBOX=1 OPENCLAW_TESTBOX_REMOTE_RUN=1 pnpm check:changed\n```\n\nRead the JSON summary and the Testbox line. Useful fields:\n\n- `provider`: `blacksmith-testbox`\n- `leaseId`: `tbx_...`\n- `syncDelegated`: `true`\n- `syncPhases`: delegated/skipped because Blacksmith owns checkout/sync\n- Actions run URL/id from the Testbox output\n- `exitCode`\n\n`blacksmith testbox list` may hide hydrating or ready boxes. Use:\n\n```sh\nblacksmith testbox list --all\nblacksmith testbox status <tbx_id>\n```\n\n## Observability Flags\n\nUse these on debugging runs before inventing ad hoc logging:\n\n- `--preflight`: prints run context, workspace mode, SSH target, remote user/cwd,\n  and target-specific tool probes. Defaults cover `git`, `tar`, `node`, `npm`,\n  `corepack`, `pnpm`, `yarn`, `bun`, `docker`, plus POSIX\n  `sudo`/`apt`/`bubblewrap` and native Windows\n  `powershell`/`execution_policy`/`longpaths`/`temp`/`pwsh`. Add\n  `--preflight-tools node,bun,docker`, `CRABBOX_PREFLIGHT_TOOLS`, or repo\n  `run.preflightTools` to replace the list. `default` expands built-ins; `none`\n  prints only the workspace summary. Preflight is diagnostic only; install\n  toolchains through Actions hydration, images, devcontainer/Nix/mise/asdf, or\n  the run script. On `blacksmith-testbox`, this prints a delegated-unsupported\n  note because the workflow owns setup.\n- `CRABBOX_ENV_ALLOW=NAME,...`: forwards only listed local env vars for direct\n  providers and prints `set len=N secret=true` style summaries. On\n  `blacksmith-testbox`, env forwarding is unsupported; put secrets in the\n  Testbox workflow instead.\n- `--env-from-profile <file>` plus `--allow-env NAME`: loads simple\n  `export NAME=value` / `NAME=value` lines from a local profile without\n  executing it, then forwards only allowlisted names. `--allow-env` is\n  repeatable and comma-separated. Profile values override ambient allowlisted\n  env values for that run. Direct POSIX, WSL2, and native Windows runs are\n  supported; delegated providers are not. Crabbox probes the uploaded profile\n  remotely and prints redacted presence/length metadata before the command.\n- `--env-helper <name>`: with `--env-from-profile` on POSIX SSH targets,\n  persists `.crabbox/env/<name>` and `.crabbox/env/<name>.env` so follow-up\n  commands on the same lease can run through `./.crabbox/env/<name> <command>`.\n  Use only on leases you control; the profile stays until cleanup, lease reset,\n  or `--full-resync`.\n- `--script <file>` / `--script-stdin`: upload a local script into\n  `.crabbox/scripts/` and execute it on the remote box. Shebang scripts execute\n  directly on POSIX; scripts without a shebang run through `bash`. Native\n  Windows uploads run through Windows PowerShell, and Crabbox appends `.ps1`\n  when needed. Arguments after `--` become script args.\n- `--fresh-pr owner/repo#123|URL|number`: skip dirty local sync and create a\n  fresh remote checkout of the GitHub PR. Bare numbers use the current repo's\n  GitHub origin. Add `--apply-local-patch` only when the current local\n  `git diff --binary HEAD` should be applied on top of that PR checkout.\n- `--full-resync` / `--fresh-sync`: reset a stale direct-provider workdir\n  before syncing. Use after sync fingerprints look wrong, SSH times out before\n  sync, or rsync watchdog output suggests it. It is redundant with\n  `--fresh-pr`, incompatible with `--no-sync`, and unsupported by delegated\n  providers.\n- `--capture-stdout <path>` / `--capture-stderr <path>`: write remote streams to\n  local files and keep binary/noisy output out of retained logs. Parent\n  directories must already exist. These are direct-provider only.\n- `--capture-on-fail`: on non-zero direct-provider exits, downloads\n  `.crabbox/captures/*.tar.gz` with `test-results`, `playwright-report`,\n  `coverage`, JUnit XML, and nearby logs. Treat as secret-bearing until reviewed.\n- `--keep-on-failure`: leave a failed one-shot lease alive for live debugging\n  until idle/TTL expiry. Useful on direct providers and delegated one-shots.\n- `--timing-json`: final machine-readable timing. Add\n  `echo CRABBOX_PHASE:install`, `CRABBOX_PHASE:test`, etc. in long shell\n  commands; direct providers and Blacksmith Testbox both report them as\n  `commandPhases`.\n\nLive-provider debug template for the resolved direct-provider lease:\n\n```sh\nmkdir -p .crabbox/logs\n../crabbox/bin/crabbox run \\\n  --preflight \\\n  --allow-env OPENAI_API_KEY,OPENAI_BASE_URL \\\n  --timing-json \\\n  --capture-stdout .crabbox/logs/live-provider.stdout.log \\\n  --capture-stderr .crabbox/logs/live-provider.stderr.log \\\n  --capture-on-fail \\\n  --shell -- \\\n  \"echo CRABBOX_PHASE:install; pnpm install --frozen-lockfile; echo CRABBOX_PHASE:test; pnpm test:live\"\n```\n\nDo not pass `--capture-*`, `--download`, `--checksum`, `--force-sync-large`, or\n`--sync-only` to delegated providers. Also do not pass `--script*`,\n`--fresh-pr`, `--full-resync`, or `--env-helper` there. Crabbox rejects these\nbecause the provider owns sync or command transport. `--keep-on-failure` is OK\nfor delegated one-shots when you need to inspect a failed lease.\n\n## Efficient Bug E2E Verification\n\nUse the smallest Crabbox lane that proves the reported user path, not just the\ntouched code. Aim for one after-fix E2E proof before commenting, closing, or\nopening a PR for a user-visible bug.\n\nWhen the user says \"test in Crabbox\", do not simply copy tests to the remote\nbox and run them there. Crabbox is for remote real-scenario proof: copy or\ninstall OpenClaw as the user would, run the same setup/update/CLI/Gateway/API\ncall that failed, and capture behavior from that entrypoint. For regressions or\nbug reports, prove the broken state first when feasible, then run the same\nscenario after the fix.\n\nPick the lane by symptom:\n\n- Docker/setup/install bug: build a package tarball and run the matching\n  `scripts/e2e/*-docker.sh` or package script. This proves npm packaging,\n  install paths, runtime deps, config writes, and container behavior.\n- Provider/model/auth bug: prefer true live E2E. Use the configured secret\n  workflow, then inject the single needed key into Crabbox if needed. Scrub\n  unrelated provider env vars in the child command so interactive defaults do\n  not drift to another provider. If only a dummy key is used, label the proof\n  narrowly, e.g. \"UI/install path only; live provider auth not exercised.\"\n- Channel delivery bug: use the channel Docker/live lane when available; include\n  setup, config, gateway start, send/receive or agent-turn proof, and redacted\n  logs.\n- Gateway/session/tool bug: prefer an end-to-end CLI or Gateway RPC command that\n  creates real state and inspects the resulting files/API output.\n- Pure parser/config bug: targeted tests may be enough, but still run a\n  Crabbox command when OS, package, Docker, secrets, or service lifecycle could\n  change behavior.\n\nEfficient flow:\n\n1. Reproduce or prove the pre-fix symptom from the real user-facing entrypoint\n   when feasible. If the issue cannot be reproduced, capture the exact command\n   and observed behavior instead.\n2. Patch locally and run narrow local tests for edit speed.\n3. Run one Crabbox E2E command that starts from the user-facing entrypoint:\n   package install, Docker setup, onboarding, channel add, gateway start, or\n   agent turn as appropriate.\n4. Record proof as: Testbox id, command, environment shape, redacted secret\n   source, and copied success/failure output.\n5. If the issue says \"cannot reproduce\", ask for the missing config/log fields\n   that would distinguish the tested path from the reporter's path.\n\nKeep it efficient:\n\n- Reuse existing E2E scripts and helper assertions before writing ad hoc shell.\n- Use `--script <file>` or `--script-stdin` for multi-line E2E commands instead\n  of quote-heavy `--shell` strings on direct SSH providers.\n- Use `--fresh-pr <pr>` when validating an upstream PR in isolation from the\n  local dirty tree. Add `--apply-local-patch` only when testing a local fixup on\n  top of that PR.\n- Use `--full-resync` before replacing a warmed direct-provider lease when the\n  remote workdir or sync fingerprint appears stale.\n- Use one-shot Crabbox for a single proof; use a reusable Testbox only when\n  several commands must share built images, installed packages, or live state.\n- Prefer `OPENCLAW_CURRENT_PACKAGE_TGZ` with Docker/package lanes when testing a\n  candidate tarball; prefer the repo's package helper instead of direct source\n  execution when the bug might be packaging/install related.\n- Keep secrets redacted. It is fine to report key presence, source, and length;\n  never print secret values.\n- Include `--timing-json` on broad or flaky runs when command duration or sync\n  behavior matters.\n\nBefore/after PR proof on delegated Testbox:\n\n- For PRs that should prove \"broken before, fixed after\", compare base and PR\n  on the same Testbox when practical. Fetch both refs, create detached temp\n  worktrees under `/tmp`, install in each, then run the same harness twice.\n- Do not checkout base/PR refs in the synced repo root. Delegated Testbox sync\n  may leave the root dirty with local files; `git checkout` can abort or mix\n  proof state.\n- Temp harness files under `/tmp` do not resolve repo packages by default. Put\n  the harness inside the worktree, or in ESM use\n  `createRequire(path.join(process.cwd(), \"package.json\"))` before requiring\n  workspace deps such as `@lydell/node-pty`.\n- For full-screen TUI/CLI bugs, a PTY harness is stronger than helper-only\n  assertions. Use a real PTY, wait for visible lifecycle markers, send input,\n  then send control keys and assert process exit/stuck behavior.\n- When validating a rebased local branch before push, remember delegated sync\n  usually validates synced file content on a detached dirty checkout, not a\n  remote commit object. Record the local head SHA, changed files, Testbox id,\n  and final success markers; after pushing, ensure the pushed SHA has the same\n  file content.\n- If GitHub CI is still queued but the exact changed content passed Testbox\n  `pnpm check:changed`, `pnpm check:test-types`, and the real E2E proof, it is\n  reasonable to merge once required checks allow it. Note any still-running\n  unrelated shards in the proof comment instead of waiting forever.\n\nInteractive CLI/onboarding:\n\n- For full-screen or prompt-heavy CLI flows, run the target command inside tmux\n  on the Crabbox and drive it with `tmux send-keys`; capture proof with\n  `tmux capture-pane`, redacted through `sed`.\n- Prefer deterministic arrow navigation over search typing for Clack-style\n  searchable selects. Raw `send-keys -l openai` may not trigger filtering in a\n  tmux pane; inspect option order locally or on-box and send exact Down/Enter\n  sequences.\n- Isolate mutable state with `OPENCLAW_STATE_DIR=$(mktemp -d)`. Plugin npm\n  installs live under that state dir (`npm/node_modules/...`), not under\n  `OPENCLAW_CONFIG_DIR`. Verify downloads by checking the state dir, package\n  lock, and installed package metadata.\n- To test automatic setup installs against local package artifacts, use\n  `OPENCLAW_ALLOW_PLUGIN_INSTALL_OVERRIDES=1` plus\n  `OPENCLAW_PLUGIN_INSTALL_OVERRIDES='{\"plugin-id\":\"npm-pack:/tmp/plugin.tgz\"}'`.\n  Pack with `npm pack`, set an isolated `OPENCLAW_STATE_DIR`, and verify the\n  package under `npm/node_modules`. Overrides are test-only and must not be\n  treated as official/trusted-source installs.\n- For OpenAI/Codex onboarding proof, the useful markers are the UI line\n  `Installed Codex plugin`, `npm/node_modules/@openclaw/codex`, and the\n  package-lock entry showing the bundled `@openai/codex` dependency. A dummy\n  OpenAI-shaped key can prove only UI/install behavior; it is not live auth.\n\n## Reuse And Keepalive\n\nFor most Crabbox calls, one-shot is enough. Use reuse only when you need\nmultiple manual commands on the same hydrated box.\n\nThe examples below assume the lease came from the still-current resolved\nconfiguration. For a lease created through an explicit provider override, add\n`--provider <reported-provider>` to every reuse, inspection, and cleanup command\ninstead of relying on the id to recover its backend.\n\nIf Crabbox returns a reusable id or you intentionally keep a lease:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --no-sync --timing-json --shell -- \"pnpm test <path>\"\n```\n\nStop boxes you created before handoff:\n\n```sh\n../crabbox/bin/crabbox stop <id-or-slug>\nblacksmith testbox stop --id <tbx_id>\n```\n\n## Interactive Desktop And WebVNC\n\nBefore using WebVNC, confirm the resolved provider supports both desktop and a\ncoordinator-backed WebVNC lease, and that broker login is configured. Crabbox\n0.39 WebVNC supports coordinator-backed Hetzner, AWS, and Azure desktop leases;\nthis capability list does not establish a provider preference. If the resolved\nprovider lacks WebVNC, do not switch providers: use native `crabbox vnc` on the\nsame provider when it supports that path, or report the capability blocker.\n\nWhen those preconditions hold, prefer WebVNC for human inspection because the\nbrowser portal can preload the lease VNC password and avoids a native VNC\nclient's copy/paste/password dance. Use native `crabbox vnc` when the browser\nportal is unavailable or broken, or the user explicitly wants a local VNC\nclient.\n\nCommon desktop flow:\n\n```sh\n../crabbox/bin/crabbox warmup --desktop --browser --idle-timeout 60m --ttl 240m\n../crabbox/bin/crabbox desktop launch --id <cbx_id-or-slug> --browser --url https://example.com --webvnc --open --take-control\n```\n\nUseful WebVNC commands:\n\n```sh\n../crabbox/bin/crabbox webvnc --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon start --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox webvnc daemon status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc daemon stop --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc status --id <cbx_id-or-slug>\n../crabbox/bin/crabbox webvnc reset --id <cbx_id-or-slug> --open --take-control\n../crabbox/bin/crabbox desktop doctor --id <cbx_id-or-slug>\n../crabbox/bin/crabbox desktop click --id <cbx_id-or-slug> --x 640 --y 420\n../crabbox/bin/crabbox desktop paste --id <cbx_id-or-slug> --text \"user@example.com\"\n../crabbox/bin/crabbox desktop key --id <cbx_id-or-slug> ctrl+l\n../crabbox/bin/crabbox artifacts collect --id <cbx_id-or-slug> --all --output artifacts/<slug>\n../crabbox/bin/crabbox artifacts publish --dir artifacts/<slug> --pr <number>\n```\n\n`desktop launch --webvnc --open` is usually the nicest one-shot: it starts the\nbrowser/app inside the visible session, bridges the lease into the authenticated\nWebVNC portal, and opens the portal. Keep browsers windowed for human QA; use\n`--fullscreen` only for capture/video workflows.\nFor human handoff, include `--take-control` so the opened portal viewer gets\nkeyboard/mouse control automatically instead of landing as an observer.\n\nHuman handoff preflight:\n\n- Do not assume a visible desktop or launched browser means the repo CLI/app is\n  installed, built, or on the interactive terminal's `PATH`.\n- Before handing WebVNC to a human tester, prove the expected command from the\n  same kept lease and from a neutral directory such as `~`.\n- If the handoff needs repo-local code, sync/build/link it explicitly on that\n  lease. Source-tree CLIs often need build output before a symlink works.\n- Prefer a real `command -v <expected-command> && <expected-command> --version`\n  check over a repo-root-only `pnpm ...` command.\n\nGeneric handoff repair pattern:\n\n```sh\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --full-resync --shell -- \\\n  \"set -euo pipefail\n   pnpm install --frozen-lockfile\n   pnpm build\n   sudo ln -sf \\\"\\$PWD/<cli-entry>\\\" /usr/local/bin/<expected-command>\n   cd ~\n   command -v <expected-command>\n   <expected-command> --version\"\n```\n\n## If Crabbox Fails\n\nKeep the fallback narrow. First decide whether the failure is Crabbox itself,\nthe brokered AWS lease, Blacksmith/Testbox, repo hydration, sync, or the test\ncommand.\n\nFast checks:\n\n```sh\ncommand -v crabbox\n../crabbox/bin/crabbox --version\n../crabbox/bin/crabbox run --help | sed -n '1,140p'\n../crabbox/bin/crabbox doctor\ncommand -v blacksmith\nblacksmith --version\nblacksmith testbox list\n```\n\nCommon Crabbox-only failures:\n\n- Provider missing or old CLI: use `../crabbox/bin/crabbox` from the sibling\n  repo, or update/install Crabbox before retrying.\n- Local-container hydration rejects a configured Actions `uses` step: stay on\n  `provider=local-container`, add `--no-hydrate`, and perform the required\n  dependency setup inside the container command. For example:\n\n  ```sh\n  ../crabbox/bin/crabbox run --no-hydrate --timing-json --shell -- \\\n    \"corepack enable && pnpm install --frozen-lockfile && <check-command>\"\n  ```\n\n  This is a hydration transport workaround, not permission to run the broad\n  check on the host or silently select a remote provider.\n- Bad local config: inspect `.crabbox.yaml`, `crabbox config show`, and\n  `crabbox whoami`; preserve the resolved provider unless the user explicitly\n  requests another backend.\n- Slug/claim confusion: use the raw `cbx_...` / `tbx_...` id, or run one-shot\n  without `--id`.\n- Sync/timing bug: add `--debug --timing-json`; capture the final JSON and the\n  printed Actions URL. Large sync warnings now include top source directories\n  by file count and a hint to update `.crabboxignore` / `sync.exclude`; inspect\n  those before reaching for `--force-sync-large`. Quiet rsync watchdogs and SSH\n  timeouts now print `next_action=` hints; follow them, usually `--full-resync`\n  first and a fresh lease second.\n- Cleanup uncertainty: run `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  only boxes you created.\n- Testbox queued/capacity pressure: do not retry repeatedly or switch providers.\n  Report the blocker and preserve the resolved provider.\n\nIf the resolved direct provider cannot dispatch, sync, attach, or stop, retry\nonce with `--debug` and `--timing-json` without changing providers:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\n```\n\nFull suite:\n\n```sh\n../crabbox/bin/crabbox run --debug --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test\n```\n\nAuth fallback, only when `blacksmith` says auth is missing:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\nRaw Blacksmith footguns:\n\n- Run from repo root. The CLI syncs the current directory.\n- Save the returned `tbx_...` id in the session.\n- Reuse that id for focused reruns; stop it before handoff.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- Treat `blacksmith testbox list` as cleanup diagnostics, not a shared reusable\n  queue.\n\nIf the selected Blacksmith backend is down or quota-limited, do not keep probing\nit or switch providers. Report the delegated-provider outage.\n\n## Blacksmith Backend Notes\n\nCrabbox Blacksmith backend delegates setup to:\n\n- the organization reported by `crabbox config show`\n- a Testbox-capable `blacksmith.workflow` or `actions.workflow` in the target\n  repository\n- `blacksmith.job` / `blacksmith.ref`, with `actions.job` / `actions.ref`\n  fallbacks\n\nThe hydration workflow owns checkout, Node/pnpm setup, dependency install,\nsecrets, ready marker, and keepalive. Crabbox owns dispatch, sync, SSH command\nexecution, timing, logs/results, and cleanup.\n\nMinimal configured Blacksmith-backed Crabbox run, from repo root. Do not use\nthis fresh-run form until the effective workflow is present and verified as\nTestbox-capable; supply the explicit user-provided workflow above or reuse an\nexisting Testbox id instead.\n\n```sh\n../crabbox/bin/crabbox run --timing-json -- \\\n  CI=1 NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 pnpm test:changed\n```\n\nUse direct Blacksmith only when Crabbox is the broken layer and you are\nisolating a Crabbox bug. Prefer direct `blacksmith testbox list` for cleanup\ndiagnostics, not as a reusable work queue.\n\nImportant Blacksmith footguns:\n\n- Always run from repo root. The CLI syncs the current directory.\n- Raw commit SHAs are not reliable `warmup --ref` refs; use a branch or tag.\n- If auth is missing and browser auth is acceptable:\n\n```sh\nblacksmith auth login --non-interactive --organization openclaw\n```\n\n## Brokered AWS\n\nThis section applies only after the resolved configuration or an explicit user\nrequest selects AWS. Do not infer AWS from an omitted `--provider`.\n\nConfirm the selection first:\n\n```sh\ncrabbox config show\ncrabbox doctor\n```\n\nFor Linux, the repository configuration supplies the broker URL, developer\nimage, `eu-west-1` default region, capacity-region candidates, and\nspot-to-on-demand capacity policy. Do not repeat those values on every command;\nthe resolved configuration remains the source of truth. For native Windows,\nuse the `us-west-2` on-demand command in \"macOS And Windows Targets\" above. For\nbrokered macOS, complete the quota/IAM and no-spend Dedicated Host preflight in\nthat section before allocation. If the user explicitly selects AWS over a\ndifferent resolved provider, add `--provider aws` to the AWS commands below.\n\n```sh\n../crabbox/bin/crabbox warmup --idle-timeout 90m\n../crabbox/bin/crabbox actions hydrate --id <cbx_id-or-slug>\n../crabbox/bin/crabbox run --id <cbx_id-or-slug> --timing-json --shell -- \"env NODE_OPTIONS=--max-old-space-size=4096 OPENCLAW_TEST_PROJECTS_PARALLEL=6 OPENCLAW_VITEST_MAX_WORKERS=1 OPENCLAW_VITEST_NO_OUTPUT_TIMEOUT_MS=900000 pnpm test:changed\"\n../crabbox/bin/crabbox stop <cbx_id-or-slug>\n```\n\nInstall/auth for owned Crabbox if needed. When configuration already resolves\nAWS and only broker auth is missing, omit `--provider` so login writes the token\nwithout changing provider selection:\n\n```sh\nbrew install openclaw/tap/crabbox\ncrabbox login --url https://crabbox.openclaw.ai\n```\n\nIf the user explicitly wants AWS as their persisted user-config default, use\n`crabbox login --url https://crabbox.openclaw.ai --provider aws`. The provider\nflag writes both broker auth and `provider=aws`; it is a configuration change,\nnot merely credential scoping. Repository config or `CRABBOX_PROVIDER` may\nstill take higher precedence, so confirm the effective result with\n`crabbox config show` in the target worktree.\n\nNew users should self-resolve broker auth before anyone asks for AWS keys:\n\n```sh\ncrabbox config show\ncrabbox doctor\ncrabbox whoami\n```\n\n- If broker auth is missing, run `crabbox login --url https://crabbox.openclaw.ai`.\n  Add `--provider aws` only when the user also wants to persist AWS as their\n  user-config default.\n- If the CLI asks for `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, or AWS\n  profile setup during normal OpenClaw validation, assume the agent selected\n  the wrong path. Use brokered `crabbox login` or an existing brokered lease\n  before asking the user for cloud credentials.\n- Ask for AWS keys only for explicit direct-provider/account administration,\n  not for normal brokered OpenClaw proof.\n- Trusted automation that intentionally persists AWS as its default may use\n  `printf '%s' \"$CRABBOX_COORDINATOR_TOKEN\" | crabbox login --url https://crabbox.openclaw.ai --provider aws --token-stdin`.\n\nmacOS config lives at:\n\n```text\n~/Library/Application Support/crabbox/config.yaml\n```\n\nIt should include `broker.url` and `broker.token` for AWS lanes. Let the resolved\nconfig select the backend; override it only when the user explicitly requests a\ndifferent provider.\n\n### Interactive Desktop / WebVNC\n\nFor human desktop demos, prefer `webvnc` over native `vnc` and keep the remote\ndesktop visible/windowed. Do not fullscreen the remote browser or hide the XFCE\npanel/window chrome unless the explicit goal is video/capture output. After\nlaunch, verify a screenshot shows the desktop panel plus browser title bar. If\nChrome is fullscreen, toggle it back with:\n\n```sh\ncrabbox run --id <lease> --shell -- 'DISPLAY=:99 xdotool search --onlyvisible --class google-chrome windowactivate key F11'\n```\n\n## Diagnostics\n\n```sh\ncrabbox status --id <id-or-slug> --wait\ncrabbox inspect --id <id-or-slug> --json\ncrabbox sync-plan\ncrabbox history --limit 20\ncrabbox history --lease <id-or-slug>\ncrabbox attach <run_id>\ncrabbox events <run_id> --json\ncrabbox logs <run_id>\ncrabbox results <run_id>\ncrabbox cache stats --id <id-or-slug>\ncrabbox ssh --id <id-or-slug>\nblacksmith testbox list\n```\n\nUse `--debug` on `run` when measuring sync timing.\nUse `--timing-json` on warmup, hydrate, and run when comparing backends.\nUse `--market spot|on-demand` only on AWS warmup/one-shot runs.\n\n## Failure Triage\n\n- Crabbox cannot find provider: verify `../crabbox/bin/crabbox --help` lists\n  the provider selected by `.crabbox.yaml`; update Crabbox before falling back.\n- Hydration stuck or failed: open the printed GitHub Actions run URL and inspect\n  the hydration step.\n- Sync failed: rerun with `--debug`; check changed-file count and whether the\n  checkout is dirty.\n- Command failed: rerun only the failing shard/file first. Do not rerun a full\n  suite until the focused failure is understood.\n- Cleanup uncertain: `crabbox list` with the resolved configuration; for\n  explicitly selected Blacksmith runs, use `blacksmith testbox list` and stop\n  owned `tbx_...` leases you created.\n- Selected provider broken: report the provider-specific blocker; do not switch\n  providers unless the user explicitly requests the fallback.\n\n## Boundary\n\nDo not add OpenClaw-specific setup to Crabbox itself. Put repo setup in the\nhydration workflow and keep Crabbox generic around lease, sync, command\nexecution, logs/results, timing, and cleanup.\n\n<!-- File: .agents/skills/local-clawsweeper-review/agents/openai.yaml (Tokens: ~57 | Category: anthropic-skill) -->\ninterface:\n  display_name: \"Local ClawSweeper Review\"\n  short_description: \"Run local ClawSweeper before PRs\"\n  default_prompt: \"Use $local-clawsweeper-review to run a local ClawSweeper review before I submit a PR.\"\n\n<!-- File: .agents/skills/local-clawsweeper-review/SKILL.md (Tokens: ~1548 | Category: anthropic-skill) -->\n---\nname: local-clawsweeper-review\ndescription: Run local ClawSweeper exact-item or committed-range reviews without GitHub mutation.\n---\n\n# Local ClawSweeper Review\n\nUse this skill when someone wants read-only local ClawSweeper output before\nsubmitting, updating, or re-reviewing an issue or PR.\n\n## Safety Boundary\n\n- Run only `pnpm run review -- --local-only` for an existing GitHub item, or\n  `pnpm run review -- --local-range` for a pre-submission committed range.\n- Do not run `apply-artifacts`, `apply-decisions`, GitHub comment posting, or\n  merge/autofix commands unless the user explicitly asks for that mutation.\n- Do not print `OPENAI_API_KEY`, `CODEX_API_KEY`, `CODEX_ACCESS_TOKEN`, GitHub\n  tokens, or Codex auth material.\n- Treat generated review artifacts as local proof. Do not claim ClawSweeper\n  posted or synced anything unless a separate explicit mutation command did it.\n\n## Locate ClawSweeper\n\nPrefer the current repository when its `package.json` name is\n`@openclaw/clawsweeper`. Otherwise use a known clean local checkout:\n\n- Windows: `C:\\oc-work\\clawsweeper-source`\n- POSIX fallback: `~/Projects/clawsweeper`\n\nInspect `git status --short` before making changes. If another ClawSweeper clone\nis dirty or ambiguous, do not use it for the local review runner.\n\n## First-Time Setup\n\nFrom the ClawSweeper checkout:\n\n```sh\ncorepack enable\npnpm install\npnpm run build:all\npnpm run codex:local:check -- --diagnostics\n```\n\nThe diagnostics mode checks the selected Codex binary and login status without\na model request. It does not prove model access or review readiness. Omit\n`--diagnostics` for the existing model smoke test, which consumes model usage.\n\nIf the Codex check says the CLI is not logged in, have the operator authenticate\ntheir own Codex CLI. Device auth is the simplest shareable setup:\n\n```sh\ncodex login --device-auth -c 'service_tier=\"fast\"'\n```\n\nFor API-key setup, pass the key through the shell only for the login command and\nthen clear it from the environment. Do not put the key in docs, scripts, shell\nhistory, or committed files.\n\nPowerShell:\n\n```powershell\n$env:OPENAI_API_KEY = Read-Host \"OpenAI API key\"\n$env:OPENAI_API_KEY | codex login --with-api-key -c 'service_tier=\"fast\"'\nRemove-Item Env:OPENAI_API_KEY\n```\n\nPOSIX shell:\n\n```sh\nprintf '%s' \"$OPENAI_API_KEY\" | codex login --with-api-key -c 'service_tier=\"fast\"'\nunset OPENAI_API_KEY\n```\n\nIf the wrong Codex binary is used, set `CODEX_BIN` in the local shell for that\nrun. Otherwise, `--local-only` uses the first spawnable `codex` command on\n`PATH`, including on Windows. If no Windows PATH command is spawnable, it falls\nback to the installed Codex Desktop binary.\n\n## Target Checkout Modes\n\nBy default, an exact local PR review manages its own target checkout under\n`artifacts/local-review-<pr-number>/target`.\n\nBy default, `--local-range` reviews the clean checkout where the command was\ninvoked. It does not manage or switch that checkout. Pass `--target-dir` when\nthe branch to review is elsewhere.\n\nIn a built source checkout, `node dist/clawsweeper-local.js review` is the\nlocal-only entrypoint for the same full committed-range engine. Its `--help`\nand `--version` paths do not load the review engine or invoke Codex. It does not\nprovide diagnostics yet; `codex:local:check` remains the existing model smoke\ntest. This entrypoint does not publish hosted action-ledger or cache metadata.\n\nPass `--target-dir` when the operator wants to review an existing checkout or\nan issue.\n\nUse a clean target checkout of the repository being reviewed. Prefer a dedicated\nreview checkout if the normal worktree is dirty:\n\n- Windows: `C:\\oc-work\\clawsweeper-local-target-openclaw`\n- POSIX fallback: `../openclaw`\n\nBefore reviewing against `main`, update the target checkout only when it is\nclean:\n\n```sh\ngit -C <target-dir> status --short\ngit -C <target-dir> fetch origin main\ngit -C <target-dir> switch main\ngit -C <target-dir> pull --ff-only origin main\n```\n\nDo not switch branches, pull, or overwrite files in a dirty target checkout.\n\n## Run A Local Review\n\nUse the exact issue or PR number. If the number is not provided and the current\nbranch has an open PR, use `gh pr view --json number,url,headRefOid` to identify\nit.\n\nFrom the ClawSweeper checkout:\n\n```sh\npnpm run review -- --local-only --item-number <pr-number>\n```\n\nTo use a supplied checkout or review an issue:\n\n```sh\npnpm run review -- --local-only \\\n  --item-number <issue-or-pr-number> \\\n  --target-dir <target-dir>\n```\n\nTo review committed branch work before a PR exists:\n\n```sh\npnpm run review -- --local-range \\\n  --target-repo <owner/repo> \\\n  --base origin/main\n```\n\nThe range is `merge-base(<base>, HEAD)..HEAD`. It must be clean and contain at\nleast one commit beyond the base. This path withholds GitHub credentials,\nisolates cached `gh` auth, disables web search, and skips host-side URL/media\npreprocessing. It still calls the configured Codex model service; do not call it\nair-gapped or fully network-offline.\n\nThe exact local command prints a human-readable progress summary by default. Add\n`--verbose` only when debugging checkout, selection, or Codex process details.\n\nFor quick smoke tests, lower `--batch-size`, `--shard-count`, `--max-pages`, and\n`--codex-timeout-ms`, but label the result as a smoke run rather than a full\nlocal review.\n\n## Read The Artifact\n\nThe default OpenClaw report is written to:\n\n```text\n<artifact-dir>/<issue-or-pr-number>.md\n```\n\nRead the artifact and summarize:\n\n- `review_status`\n- `main_sha`\n- `pull_head_sha` for PRs\n- decision/confidence/action fields when present\n- findings or blockers\n- exact Codex/auth/runtime failure if the run failed\n\nIf the failure is Codex auth, stop after providing the local setup command. If\nthe failure is runner/runtime behavior, include the artifact path and a concise\nstderr or log summary.\n\n## Closeout\n\nBefore reporting success:\n\n- Confirm the command used `review --local-only` or `review --local-range`.\n- Confirm no GitHub comments, labels, merges, or apply commands were run.\n- Confirm the target checkout is still clean.\n- If findings exist, list the actionable items and the next local fix/test step.\n- If no blockers exist, say the local ClawSweeper artifact found no blockers\n  and include the reviewed `main_sha` and PR head SHA when available.\n</yakaai_skills>"}