[ymichael]

What this fixes

Test-determinism and QA/runbook maintenance only, extracted from #1385.

Issue	Simple explanation	Fix
Docs watcher test was timing-dependent	The test wrote a real file and then raced native FSEvents plus a 250ms debounce, so it failed whenever the watch-vaults service had not attached yet or the host was busy.	Give the Docs plugin a watcher injection seam that defaults to native fs.watch, and have the test drive a fake watcher directly. It now asserts the watched root, the published vault-changed signal, and watcher cleanup on abort — with no filesystem-event timing.
Database-maintenance test depended on file order	The @bb/server vitest project runs with isolate: false, so files share the module-level lastDatabaseMaintenanceCheckAt. periodic-sweeps.test.ts parks it at wall time, while this file swept from a hardcoded 1_000_000_000_000 (2001) — every sweep then looked "too soon".	Start the synthetic clock a day ahead of wall time so it always leads any real timestamp another file records.
Daemon restart helper only worked once	buildDaemonRestartCommand baked in the PID captured at build time, so a second run left the first replacement daemon alive and raced a second one onto the same port and data dir.	Resolve the PID from the daemon PID file at run time (build-time PID as first-run fallback), and refuse to run when the resolved value is not a positive integer so a corrupt PID file cannot become a stray kill.
Archive runbook expected immediate destruction	A last-live archived managed worktree stays revivable for the five-minute undo grace period (MANAGED_ENVIRONMENT_RETIRE_GRACE_MS), so the old expectation was wrong.	Assert retiring plus a preserved worktree first, then permanently delete the archived thread and wait for destruction.
Runbook tracked the wrong restarted daemon	DAEMON_PID=$! after eval "$RESTART_DAEMON_COMMAND" captures the shell's job, not the detached daemon.	Read the authoritative PID file (.paths.daemonRestartPidPath) exported by the standalone harness after each restart.
Permission QA used non-public modes and unreliable probes	readonly and workspace-write are not accepted by the CLI (public modes are accept-edits, auto, full), and Codex sandboxes commonly permit the OS temp dir, so /tmp probes were not reliably outside the workspace.	Cover only the public modes and place the approval/denial probes under $HOME. A new contract test rejects stale mode names and pins the probe targets.
Provisioning runbook promised restart recovery	The old "Server restart during environment provisioning" scenario killed the server mid-RPC and implied lost-result recovery and persisted attempt identity.	Removed entirely. Replaced with the supported contract: a .bb-env-setup.sh hook fails exactly once, the thread and environment settle in error with thread_provisioning_failed, and one explicit bb thread tell ... --mode auto starts a fresh provisioning attempt that reaches ready before the turn runs. A contract test keeps the restart scenario from returning.

Scope

No product behavior, database schema, migration, Drizzle snapshot, provisioning implementation, host-daemon wire contract, or protocol-version change.

The full diff is 8 files. Only two are non-test sources:

• plugins/docs/server.ts — adds the watcher injection seam; the default parameter is the existing native fs.watch implementation, so production behavior is unchanged.
• tests/qa/src/shared.ts — QA-harness helper in the tests/qa package.

Deliberately omitted: the provider-interaction integration commit from #1385 (0fc13d45e). It deletes roughly 750 lines of live-provider scenarios covering auto permission mode plus the auto-ask/auto-deny harness presets. Its premise does hold on current main — auto pairs with approvalReviewer: "automatic", which the Codex adapter maps to auto_review rather than routing to onInteractiveRequest — so it is not strictly coupled to the excluded Codex runtime commits. It is omitted because it is a coverage deletion rather than a flaky-test or QA fix, and it cannot be validated here: src/integration*.test.ts is excluded from the default test task and only runs via test:integration against real providers. Removing unverifiable integration coverage does not belong in a no-product-change PR; it is left as a follow-up.

Validation

Run on this branch rebased onto current main:

• turbo run typecheck test --filter=bb-plugin-simple-notes --filter=@bb/qa --force — 5/5 tasks; Docs 59 tests, QA 25 tests.
• turbo run typecheck test --filter=@bb/server --force — 161 files, 1450 tests passed.
• Database-maintenance flake reproduced before the fix with --no-file-parallelism --sequence.shuffle.files --sequence.seed=3 (4 failures), and passing on that same ordering after.
• The standalone-restart regression assertions were confirmed to fail against the previous buildDaemonRestartCommand.
• turbo run lint on the touched packages — no lint tasks are defined for them.
• Prettier clean; final diff audited for schema/migration/contract/provisioning paths (none).

Runbook claims were checked against main rather than assumed: thread_provisioning_failed, error in threadStatusValues, bb thread wait --status, bb thread delete --yes, bb thread tell --mode auto, PROJECT_ROOT exported by the QA harness, and MANAGED_ENVIRONMENT_RETIRE_GRACE_MS = 5 * 60_000.

Pre-existing macOS-only failure, not from this PR

packages/agent-runtime/src/runtime.process-lifecycle.test.ts > bounds provider stderr while data arrives without a newline fails on clean origin/main on macOS. Its fake child writes 100KB to stderr and immediately calls process.exit(42). Pipe writes are asynchronous on macOS, so the child exits without flushing bytes that never reach the parent; this is distinct from the real parent-side exit-before-close drain bug. CI's Tests (packages) shard runs on Ubuntu, where the fixture passes.

#1402 fixes both issues separately: the fixture uses process.exitCode = 42 so Node flushes naturally, while the runtime waits for stream close before finalizing provider exit. Those provider-runtime changes are explicitly out of scope here, and this branch touches no agent-runtime files.

AGENT GENERATED: by Claude Opus 5 (1M context)