Verify Bb

Verify BB

Run from the repository root. Start with the feature map and select the affected journeys. Read docs/debugging-and-qa.md for the source development workflow. The launch below targets the source web app and local host daemon. Desktop, native mobile, and hosted services have additional setup in their feature files. A pass on one platform does not verify another.

Coverage and selection

The feature map aims to inventory every feature discoverable in this checkout, including disabled plugins, compatibility paths, and developer surfaces. Group files contain individual capability recipes. Read only the relevant files for a focused verification request; for an exhaustive audit, track every recipe. Mark each selected recipe passed, failed, not run, or blocked with its specific prerequisite and evidence. Group-level source coverage never upgrades an unexecuted recipe to a pass.

Run the read-only inventory check before selecting coverage:

.bb/skills/verify-bb/scripts/inventory.py

Python 3 and Git are required. The check compares source declarations and fingerprints with INVENTORY.md and inventory.json, and requires all recipe owners to exist. On drift, inspect the changed source, add/update recipes and their prerequisites, then run scripts/inventory.py --write via its full path above and review the diff. Never accept a new baseline merely to silence the check. It watches CLI families, app routes/actions/settings, public contracts/SDK, plugin sources, platform clients and server/daemon implementation. The broad fingerprints deliberately flag implementation changes too: some require only a recorded review, others reveal behavior missing from the map. Literal extraction cannot resolve every dynamic registration, and source fingerprints cannot judge recipe completeness; reconcile menus, help, schemas and actual behavior during maintenance.

The latest maintenance audit assessed all 348 recipes: 166 passed, 177 partial/blocked and 5 failed. The per-recipe ledger records evidence and remaining subchecks. VALIDATION.md preserves the initial smoke history. An exhaustive map is the test inventory, not a whole-product pass.

After changing the inventory helper, run its standalone fixture tests:

.bb/skills/verify-bb/scripts/test_inventory.py

These use temporary Git repositories and verify drift, missing ownership, catalog consistency, and index coverage without starting BB.

Launch

Use Node 22.19 or newer in the Node 22 line; .nvmrc supplies the primary version. The initial run passed on Node 22.23.2. Node 24.18.0 crashed during native-module setup on that run. Keep the chosen Node on PATH for launch, source CLI calls, and cleanup. Do not bypass native-module repair or rebuild a shared binary manually.

node --version
npm install -g dev-browser@next
dev-browser --version
dev-browser --help

If Chrome is missing, run dev-browser install. The browser CLI accepts Puppeteer scripts on stdin and keeps named pages between calls.

Choose an unused checkout. pnpm dev assigns ports and a data directory from the checkout path. Resolve them before starting and confirm the ports are free. Use a fresh store, never an imported store or the user's production database.

For a new run, create a unique evidence directory and a nonempty fresh dev directory. The marker also prevents migrateLegacyDevData from adopting legacy data from the parent .bb-dev directory. If mkdir finds an existing dev directory, stop this setup and use another unused checkout; do not delete or adopt the existing data.

export BB_VERIFY_RUN="$(mktemp -d /tmp/bb-verification-XXXXXX)"
export BB_VERIFY_BROWSER="verify-bb-$(basename "$BB_VERIFY_RUN")"
node --conditions=source --import tsx --input-type=module > "$BB_VERIFY_RUN/before-launch.txt" <<'JS'
import { resolveCurrentDevInstanceConfig } from './packages/config/src/runtime.ts';
const config = resolveCurrentDevInstanceConfig(process.cwd());
console.log(`App: http://127.0.0.1:${config.ports.appPort}`);
console.log(`Server: ${config.serverUrl}`);
console.log(`Host daemon: http://127.0.0.1:${config.ports.hostDaemonPort}`);
console.log(`Data dir: ${config.dataDir}`);
JS
command -v lsof >/dev/null || exit 1
for BB_VERIFY_PORT in $(sed -nE 's/^(App|Server|Host daemon): http:\/\/[^:]+:([0-9]+)$/\2/p' "$BB_VERIFY_RUN/before-launch.txt"); do
  if lsof -nP -iTCP:"$BB_VERIFY_PORT" -sTCP:LISTEN; then
    exit 1
  fi
done
export BB_VERIFY_DATA_DIR="$(sed -n 's/^Data dir: //p' "$BB_VERIFY_RUN/before-launch.txt")"
export BB_VERIFY_APP_URL="$(sed -n 's/^App: //p' "$BB_VERIFY_RUN/before-launch.txt")"
test -n "$BB_VERIFY_DATA_DIR" && test -n "$BB_VERIFY_APP_URL" || exit 1
mkdir "$BB_VERIFY_DATA_DIR" || exit 1
printf '%s\n' "$BB_VERIFY_RUN" > "$BB_VERIFY_DATA_DIR/verify-bb-owner"
git rev-parse HEAD > "$BB_VERIFY_RUN/source-commit.txt"
pnpm dev > "$BB_VERIFY_RUN/launch.log" 2>&1

All three ports must be unoccupied before starting; checkout-derived ports can collide. Run under the same OS user that owns the dev processes so listener inspection is complete.

Run slow startup through the agent's background process facility, inspect the log, and provide progress while it builds. Keep the process session handle for cleanup and wait for server and daemon health before driving. If it fails, inspect the error and clean up that attempt. pnpm dev runs native-module checks and starts development tasks through Turbo. Install dependencies with pnpm install first if they are missing.

Record the variables above in your run notes so later shell calls retain the same targets. Never rely on variables surviving separate agent shell calls. When resuming this run, require its marker to contain the exact run directory and verify the processes still belong to this checkout.

For source startup checks, run pnpm start:worktree --dryrun first. It prepares through Turbo and prints the resolved paths/ports without starting services or migrating instance data. Repeat to verify cache hits, then run normally and check server/daemon health. Dry runs write build outputs and may repair native modules; use an isolated checkout and keep the serving checkout's data/ports stable.

Doctor

export BB_SERVER_URL="$(sed -n 's/^Server: //p' "$BB_VERIFY_RUN/before-launch.txt")"
export BB_HOST_DAEMON_PORT="$(sed -nE 's/^Host daemon: http:\/\/[^:]+:([0-9]+)$/\1/p' "$BB_VERIFY_RUN/before-launch.txt")"
unset BB_THREAD_ID BB_ENVIRONMENT_ID BB_THREAD_STORAGE BB_PROJECT_ID BB_CLI BB_CLI_REEXEC
pnpm exec turbo run build --filter=@bb/cli
curl -fsS "$BB_SERVER_URL/health"
curl -fsS "http://127.0.0.1:$BB_HOST_DAEMON_PORT/health"
curl -fsS "$BB_SERVER_URL/api/v1/hosts"
node apps/cli/dist/index.js project list --json

The server health returns {"ok":true} (possibly with launchId); daemon health returns ok. Require the intended host to be connected. Inspect lsof -nP -iTCP:<port> -sTCP:LISTEN for each port recorded in preflight, then check its PID's command and working directory with ps and lsof -p <pid>. A responding port alone does not establish instance ownership. Record the current source commit and whether the tree is dirty with the launch evidence.

The doctor shell clears inherited thread context and CLI overrides and sets explicit dev endpoints from preflight. Use node apps/cli/dist/index.js for CLI checks after the Turbo build above.

The source entry point otherwise reexecutes an inherited BB_CLI, silently using the installed client against the dev server. During maintenance, pnpm --silent bb:dev also changed literal newlines in arguments into backslash-plus-n bytes. Direct Node invocation with quoted arguments preserved the bytes. Check the returned content and revision, not only the exit code. Keep these environment changes inside the test shell or wrapper; use bare bb outside it for coordination with the parent BB thread.

Commands such as workflows require thread context. After configuring the dev environment, set BB_THREAD_ID, BB_PROJECT_ID, and BB_ENVIRONMENT_ID only from synthetic entities created in that instance. Never restore the parent's production context. A wrapper that changes directory must invoke the built CLI by its absolute checkout path; scaffold commands should run in an owned fixture directory.

Run doctor after any unexpected behavior. Also check the browser URL and the feature's prerequisite. Provider login is required only for actual agent turns; inspect it through the UI or source CLI, never by printing credentials.