- `pnpm check:changed`: runs the smart changed check gate for the diff against `origin/main`. It runs typecheck, lint, and guard commands for the affected architectural lanes, but does not run Vitest tests. Use `pnpm test:changed` or explicit `pnpm test <target>` for test proof.

- `pnpm test`: routes explicit file/directory targets through scoped Vitest lanes. Untargeted runs use fixed shard groups and expand to leaf configs for local parallel execution; the extension group always expands to the per-extension shard configs instead of one giant root-project process.

- Test wrapper runs end with a short `[test] passed|failed|skipped ... in ...` summary. Vitest's own duration line stays the per-shard detail.

- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. Docker/Bash E2E lanes can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag.

- Shared OpenClaw test state: use `src/test-utils/openclaw-test-state.ts` from Vitest when a test needs an isolated `HOME`, `OPENCLAW_STATE_DIR`, `OPENCLAW_CONFIG_PATH`, config fixture, workspace, agent dir, or auth-profile store. Docker/Bash E2E lanes that source `scripts/lib/docker-e2e-image.sh` can pass `docker_e2e_test_state_shell_b64 <label> <scenario>` into the container and `eval` the decoded snippet there; multi-home scripts can pass `docker_e2e_test_state_function_b64` and call `openclaw_test_state_create <label> <scenario>` in each flow. Lower-level callers can use `scripts/lib/openclaw-test-state.mjs shell --label <name> --scenario <name>` for an in-container shell snippet, or `node scripts/lib/openclaw-test-state.mjs -- create --label <name> --scenario <name> --env-file <path> --json` for a sourceable host env file. The `--` before `create` keeps newer Node runtimes from treating `--env-file` as a Node flag.

- Full, extension, and include-pattern shard runs update local timing data in `.artifacts/vitest-shard-timings.json`; later whole-config runs use those timings to balance slow and fast shards. Include-pattern CI shards append the shard name to the timing key, which keeps filtered shard timings visible without replacing whole-config timing data. Set `OPENCLAW_TEST_PROJECTS_TIMINGS=0` to ignore the local timing artifact.

- Selected `plugin-sdk` and `commands` test files now route through dedicated light lanes that keep only `test/setup.ts`, leaving runtime-heavy cases on their existing lanes.

- Source files with sibling tests map to that sibling before falling back to wider directory globs. Helper edits under `src/channels/plugins/contracts/test-helpers`, `src/plugin-sdk/test-helpers`, and `src/plugins/contracts` use a local import graph to run importing tests instead of broad-running every shard when the dependency path is precise.

IMAGE_NAME="$(docker_e2e_resolve_image "openclaw-agents-delete-shared-workspace-e2e:local" OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_IMAGE)"

SKIP_BUILD="${OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_E2E_SKIP_BUILD:-0}"

DOCKER_COMMAND_TIMEOUT="${OPENCLAW_AGENTS_DELETE_SHARED_WORKSPACE_DOCKER_COMMAND_TIMEOUT:-300s}"

OPENCLAW_TEST_STATE_SCRIPT_B64="$(

node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \

--label agents-delete-shared-workspace \

--scenario empty \

| base64 \

| tr -d '\n'

)"

OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 agents-delete-shared-workspace empty)"

docker_cmd() {

if command -v timeout >/dev/null 2>&1; then

IMAGE_NAME="$(docker_e2e_resolve_image "openclaw-bundled-plugin-install-uninstall-e2e" OPENCLAW_BUNDLED_PLUGIN_INSTALL_UNINSTALL_E2E_IMAGE)"

docker_e2e_build_or_reuse "$IMAGE_NAME" bundled-plugin-install-uninstall

OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 bundled-plugin-install-uninstall empty)"

DOCKER_ENV_ARGS=(-e COREPACK_ENABLE_DOWNLOAD_PROMPT=0)

DOCKER_ENV_ARGS=(

-e COREPACK_ENABLE_DOWNLOAD_PROMPT=0

-e "OPENCLAW_TEST_STATE_SCRIPT_B64=$OPENCLAW_TEST_STATE_SCRIPT_B64"

)

for env_name in \

OPENCLAW_BUNDLED_PLUGIN_SWEEP_TOTAL \

OPENCLAW_BUNDLED_PLUGIN_SWEEP_INDEX \

fi

export OPENCLAW_ENTRY

home_dir=$(mktemp -d "/tmp/openclaw-bundled-plugin-sweep.XXXXXX")

export HOME="$home_dir"

eval "$(printf "%s" "${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}" | base64 -d)"

node - <<'NODE' > /tmp/bundled-plugin-sweep-ids

const fs = require("node:fs");

PACKAGE_TGZ="$(docker_e2e_prepare_package_tgz doctor-switch "${OPENCLAW_CURRENT_PACKAGE_TGZ:-}")"

# Bare lanes mount the package artifact instead of baking app sources into the image.

docker_e2e_package_mount_args "$PACKAGE_TGZ"

OPENCLAW_TEST_STATE_FUNCTION_B64="$(docker_e2e_test_state_function_b64)"

docker_e2e_build_or_reuse "$IMAGE_NAME" doctor-switch "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR" "bare"

echo "Running doctor install switch E2E..."

docker run --rm \

-e COREPACK_ENABLE_DOWNLOAD_PROMPT=0 \

-e "OPENCLAW_TEST_STATE_FUNCTION_B64=$OPENCLAW_TEST_STATE_FUNCTION_B64" \

"${DOCKER_E2E_PACKAGE_ARGS[@]}" \

"$IMAGE_NAME" \

bash -lc '

set -euo pipefail

eval "$(printf "%s" "${OPENCLAW_TEST_STATE_FUNCTION_B64:?missing OPENCLAW_TEST_STATE_FUNCTION_B64}" | base64 -d)"

# Keep logs focused; the npm global install step can emit noisy deprecation warnings.

export npm_config_loglevel=error

local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"

echo "== Flow: $name =="

home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")

export HOME="$home_dir"

openclaw_test_state_create "switch-${name}" empty

export USER="testuser"

if ! timeout "$command_timeout" bash -c "$install_cmd" >"$install_log" 2>&1; then

local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"

echo "== Flow: $name =="

home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")

export HOME="$home_dir"

openclaw_test_state_create "switch-${name}" empty

export USER="testuser"

unit_path="$HOME/.config/systemd/user/openclaw-gateway.service"

local command_timeout="${OPENCLAW_DOCKER_DOCTOR_SWITCH_COMMAND_TIMEOUT:-300s}"

echo "== Flow: $name =="

home_dir=$(mktemp -d "/tmp/openclaw-switch-${name}.XXXXXX")

export HOME="$home_dir"

openclaw_test_state_create "switch-${name}" empty

export USER="testuser"

mkdir -p "$HOME/.local/bin"

local wrapper="$HOME/.local/bin/openclaw-wrapper"

docker_e2e_package_mount_args "$PACKAGE_TGZ"

docker_e2e_harness_mount_args

run_log="$(docker_e2e_run_log npm-onboard-channel-agent)"

OPENCLAW_TEST_STATE_SCRIPT_B64="$(

node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \

--label npm-onboard-channel-agent \

--scenario empty \

| base64 \

| tr -d '\n'

)"

OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 npm-onboard-channel-agent empty)"

echo "Running npm tarball onboard/channel/agent Docker E2E ($CHANNEL)..."

if ! docker run --rm \

docker_e2e_build_or_reuse "$IMAGE_NAME" openai-image-auth "$ROOT_DIR/scripts/e2e/Dockerfile" "$ROOT_DIR" "" "$SKIP_BUILD"

docker_e2e_harness_mount_args

OPENCLAW_TEST_STATE_SCRIPT_B64="$(docker_e2e_test_state_shell_b64 openai-image-auth empty)"

echo "Running OpenAI image auth Docker E2E..."

# Harness files are mounted read-only; the app under test comes from /app/dist.

run_logged openai-image-auth docker run --rm \

-e "OPENAI_API_KEY=sk-openclaw-image-auth-e2e" \

-e "OPENCLAW_QA_ALLOW_LOCAL_IMAGE_PROVIDER=1" \

-e "OPENCLAW_TEST_STATE_SCRIPT_B64=$OPENCLAW_TEST_STATE_SCRIPT_B64" \

"${DOCKER_E2E_HARNESS_ARGS[@]}" \

-i "$IMAGE_NAME" bash -lc '

set -euo pipefail

export HOME="$(mktemp -d "/tmp/openclaw-openai-image-auth.XXXXXX")"

export OPENCLAW_STATE_DIR="$HOME/.openclaw"

eval "$(printf "%s" "${OPENCLAW_TEST_STATE_SCRIPT_B64:?missing OPENCLAW_TEST_STATE_SCRIPT_B64}" | base64 -d)"

export OPENCLAW_SKIP_CHANNELS=1

export OPENCLAW_SKIP_GMAIL_WATCHER=1

export OPENCLAW_SKIP_CRON=1

build_args+=(-t "$image_name" -f "$dockerfile" "$context")

docker_build_run "$label-build" "${build_args[@]}"

}

docker_e2e_test_state_shell_b64() {

local label="${1:?missing test-state label}"

local scenario="${2:-empty}"

node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell \

--label "$label" \

--scenario "$scenario" \

| base64 \

| tr -d '\n'

}

docker_e2e_test_state_function_b64() {

node "$ROOT_DIR/scripts/lib/openclaw-test-state.mjs" shell-function \

| base64 \

| tr -d '\n'

}

{

estimateSeconds: 280,

resources: ["npm"],

stateScenario: "empty",

weight: 1,

},

),

{ resources: ["npm"], weight: 3 },

),

npmLane("doctor-switch", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:doctor-switch", {

stateScenario: "empty",

weight: 3,

}),

npmLane(

npmLane("plugin-update", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:plugin-update"),

serviceLane("config-reload", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:config-reload"),

...bundledScenarioLanes,

lane("openai-image-auth", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:openai-image-auth"),

lane("openai-image-auth", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:openai-image-auth", {

stateScenario: "empty",

}),

lane(

"crestodian-first-run",

"OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:crestodian-first-run",

{ resources: ["service"], stateScenario: "empty", weight: 3 },

),

npmLane("doctor-switch", "OPENCLAW_SKIP_DOCKER_BUILD=1 pnpm test:docker:doctor-switch", {

stateScenario: "empty",

weight: 3,

}),

npmLane(

name: "npm-onboard-channel-agent",

stateScenario: "empty",

}),

expect.objectContaining({

name: "doctor-switch",

stateScenario: "empty",

}),

expect.objectContaining({

name: "update-channel-switch",

stateScenario: "update-stable",

it("surfaces Docker lane test-state scenarios in plan JSON", () => {

const plan = planFor({

selectedLaneNames: ["onboard", "agents-delete-shared-workspace", "update-channel-switch"],

selectedLaneNames: [

"onboard",

"agents-delete-shared-workspace",

"doctor-switch",

"openai-image-auth",

"bundled-plugin-install-uninstall-0",

"update-channel-switch",

],

});

expect(plan.lanes).toEqual([

name: "agents-delete-shared-workspace",

stateScenario: "empty",

}),

expect.objectContaining({

name: "doctor-switch",

stateScenario: "empty",

}),

expect.objectContaining({

name: "openai-image-auth",

stateScenario: "empty",

}),

expect.objectContaining({

name: "bundled-plugin-install-uninstall-0",

stateScenario: "empty",

}),

expect.objectContaining({

name: "update-channel-switch",

stateScenario: "update-stable",