Bug type

Crash / fatal error on startup

Summary

After updating to 2026.4.9, the CLI crashes on any command that imports the QA scenario module (including the completion cache builder). The qa/scenarios/ directory and its required files are not included in the published npm package, but the code unconditionally loads them at module top-level.

Steps to reproduce

1. Install or update to OpenClaw 2026.4.9 via Homebrew or npm
2. Run openclaw qa --help

Expected behavior

Help output is displayed.

Actual behavior

Two sequential crashes:

Crash 1 — missing pack index:

[openclaw] Failed to start CLI: Error: qa scenario pack not found: qa/scenarios/index.md
    at readQaScenarioPack (suite-BW4kSK9C.js:754)

Crash 2 (after manually creating index.md) — missing required scenario:

[openclaw] Failed to start CLI: Error: unknown qa scenario: source-docs-discovery-report
    at readQaScenarioById (suite-BW4kSK9C.js:791)

Root cause

Three code paths in suite-BW4kSK9C.js create the failure chain:

1. readQaScenarioPack() (line 752) reads qa/scenarios/index.md and throws if the file is empty or absent.
2. readQaScenarioById("source-docs-discovery-report") (line 790) throws if that scenario ID is not found in the pack.
3. readRequiredDiscoveryRefs() (line 2833) calls readQaScenarioById and is invoked at module top-level (line 2840), so the error fires on every CLI invocation that imports the module — including the completion cache builder during openclaw update.

resolveRepoPath() (line 713) walks up from import.meta.dirname looking for these files relative to each parent directory. Since the npm/Homebrew package does not include a qa/ directory anywhere in the tree, the lookup always fails.

Impact

• openclaw qa and all subcommands are completely broken (exit code 1).
• Completion cache update fails on every openclaw update, leaving shell completions stale.
• Core non-QA commands are unaffected.

OpenClaw version

2026.4.9 (0512059)

Operating system

macOS (Homebrew)

Install method

Homebrew (/opt/homebrew/lib/node_modules/openclaw)

Workaround

Create two files in <install_root>/qa/scenarios/:

index.md:

# QA Scenario Pack

\`\`\`yaml qa-pack
version: 1
kickoffTask: "Run all registered QA scenarios"
\`\`\`

source-docs-discovery-report.md:

# Source Docs Discovery Report

\`\`\`yaml qa-scenario
id: source-docs-discovery-report
title: Source Docs Discovery Report
surface: cli
objective: Verify the agent can discover and read required source documentation files
successCriteria:
  - Agent reads all required source files
execution:
  kind: flow
  config:
    requiredFiles:
      - repo/qa/scenarios/index.md
      - repo/extensions/qa-lab/src/suite.ts
      - repo/docs/help/testing.md
\`\`\`

\`\`\`yaml qa-flow
steps:
  - name: discover source docs
    actions:
      - assert: "true"
\`\`\`

These files will be overwritten on the next update.

Suggested fix

Either:

1. Include qa/scenarios/ with its scaffold files in the published package, or
2. Guard the top-level readRequiredDiscoveryRefs() call (line 2840) with a try/catch so it degrades to the hardcoded defaults (line 2834) when the scaffold is absent — the fallback array already exists but is never reached because readQaScenarioById throws first.